mirror of
https://github.com/BetterSEQTA/BetterSEQTA-Plus.git
synced 2026-06-06 19:54:39 +00:00
SethBurkart123
123 lines
4.4 KiB
Markdown
123 lines
4.4 KiB
Markdown
# BetterSEQTA+ Theme System Documentation
|
|
|
|
## Overview
|
|
The BetterSEQTA+ theme system allows users to customize their SEQTA interface with custom CSS, colors, and images. Themes are stored locally using `localforage` and can be shared, downloaded, and modified.
|
|
|
|
## Theme Storage
|
|
Themes are stored using `localforage` in two main ways:
|
|
1. A list of theme IDs is stored under the key 'customThemes'
|
|
2. Individual themes are stored using their unique ID as the key
|
|
|
|
## Theme Structure
|
|
A theme consists of the following components:
|
|
|
|
```typescript
|
|
type CustomTheme = {
|
|
id: string; // Unique identifier for the theme
|
|
name: string; // Display name
|
|
description: string; // Theme description
|
|
defaultColour: string; // Default accent color
|
|
CanChangeColour: boolean; // Whether users can change the accent color
|
|
allowBackgrounds: boolean; // Whether background customization is allowed
|
|
CustomCSS: string; // Custom CSS styles
|
|
CustomImages: CustomImage[]; // Array of custom images used in the theme
|
|
coverImage: Blob | null; // Theme preview image
|
|
isEditable: boolean; // Whether the theme can be edited
|
|
hideThemeName: boolean; // Whether to hide the theme name in UI
|
|
webURL?: string; // Optional URL for web-downloaded themes
|
|
selectedColor?: string; // Currently selected accent color
|
|
forceDark?: boolean; // Force dark mode when theme is active
|
|
}
|
|
```
|
|
|
|
## Theme Management Functions
|
|
|
|
### Core Functions
|
|
1. `setTheme(themeId)`: Activates a theme
|
|
- Removes currently active theme
|
|
- Applies new theme's CSS and images
|
|
- Updates color settings
|
|
|
|
2. `applyTheme(theme)`: Applies theme components
|
|
- Applies custom CSS
|
|
- Sets up custom images
|
|
- Handles dark mode settings
|
|
|
|
3. `removeTheme(theme)`: Cleans up theme components
|
|
- Removes custom CSS
|
|
- Cleans up image URLs
|
|
- Restores original settings
|
|
|
|
### Theme Storage Operations
|
|
1. `saveTheme(theme)`: Saves/updates a theme
|
|
- Stores theme data in localforage
|
|
- Updates theme list if new
|
|
- Triggers theme update notifications
|
|
|
|
2. `deleteTheme(themeId)`: Removes a theme
|
|
- Removes theme data
|
|
- Updates theme list
|
|
- Cleans up theme components
|
|
|
|
### Theme Sharing
|
|
1. `shareTheme(themeId)`: Exports theme for sharing
|
|
- Converts blobs to base64
|
|
- Packages theme data
|
|
- Creates downloadable JSON file
|
|
|
|
2. `downloadTheme(theme)`: Installs shared theme
|
|
- Converts base64 to blobs
|
|
- Stores theme data
|
|
- Updates theme list
|
|
|
|
## State Management
|
|
The theme system uses a `settingsState` object to track:
|
|
- Currently selected theme (`selectedTheme`)
|
|
- Original and current color settings (`originalSelectedColor`, `selectedColor`)
|
|
- Dark mode state (`DarkMode`, `originalDarkMode`)
|
|
|
|
## Known Issues and Considerations
|
|
|
|
### Image Handling
|
|
1. Images are stored as Blobs and converted to URLs for display
|
|
2. Need to properly revoke object URLs to prevent memory leaks
|
|
3. Image variable names must be unique across themes
|
|
|
|
### Color Management
|
|
1. Theme colors can override user preferences
|
|
2. Need to properly restore original colors when disabling themes
|
|
3. Color change permissions (`CanChangeColour`) may need better enforcement
|
|
|
|
### CSS Application
|
|
1. CSS is applied through a single `<style>` element with id 'custom-theme'
|
|
2. Multiple themes attempting to apply CSS simultaneously could cause conflicts
|
|
3. CSS specificity issues might affect theme application
|
|
|
|
### State Persistence
|
|
1. Theme state needs to be properly restored on page reload
|
|
2. Dark mode preferences need better synchronization with theme settings
|
|
3. Original settings should be properly preserved and restored
|
|
|
|
## Best Practices
|
|
|
|
### Theme Development
|
|
1. Use unique, descriptive variable names for custom images
|
|
2. Include proper fallbacks in custom CSS
|
|
3. Test themes in both light and dark modes
|
|
4. Provide clear documentation for custom variables and features
|
|
|
|
### Theme Management
|
|
1. Always clean up resources when disabling/removing themes
|
|
2. Implement proper error handling for theme operations
|
|
3. Validate theme data before saving/applying
|
|
4. Maintain backward compatibility for theme formats
|
|
|
|
## Future Improvements
|
|
1. Theme versioning system
|
|
2. Better conflict resolution between themes
|
|
3. Theme dependencies management
|
|
4. Theme update mechanism
|
|
5. Theme preview system
|
|
6. Better error handling and user feedback
|
|
7. Theme categories and tags
|
|
8. Theme export/import validation |