@su-labs/theme 21.0.4 โ 21.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +5 -0
- package/README.md +187 -22
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [21.0.5] - 2026-02-04
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- Update README.md
|
|
12
|
+
|
|
8
13
|
## [21.0.4] - 2026-02-03
|
|
9
14
|
|
|
10
15
|
### Changed
|
package/README.md
CHANGED
|
@@ -1,27 +1,115 @@
|
|
|
1
1
|
# SuThemeService
|
|
2
2
|
|
|
3
|
+
`@su-labs/theme`
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+

|
|
7
|
+

|
|
8
|
+

|
|
9
|
+

|
|
10
|
+

|
|
11
|
+

|
|
12
|
+

|
|
13
|
+
|
|
3
14
|
A robust and reactive Angular service for managing application themes. It provides a full-featured solution that supports dynamic switching, user preference persistence, and automatic system theme detection.
|
|
4
15
|
|
|
16
|
+
## ๐ Table of Contents
|
|
17
|
+
|
|
18
|
+
- [Why Use This Library?](#-why-use-this-library)
|
|
19
|
+
- [Features](#features)
|
|
20
|
+
- [Available Themes](#available-themes)
|
|
21
|
+
- [Installation](#installation)
|
|
22
|
+
- [Quick Start](#-quick-start)
|
|
23
|
+
- [Usage](#usage)
|
|
24
|
+
- [API Reference](#-api-reference)
|
|
25
|
+
- [Configuration Options](#configuration-options)
|
|
26
|
+
- [Browser Compatibility](#-browser-compatibility)
|
|
27
|
+
- [Related Libraries](#-related-libraries)
|
|
28
|
+
- [Troubleshooting](#-troubleshooting)
|
|
29
|
+
- [Support](#-support)
|
|
30
|
+
- [Contributing](#contributing)
|
|
31
|
+
- [License](#license)
|
|
32
|
+
|
|
33
|
+
## ๐ก Why Use This Library?
|
|
34
|
+
|
|
35
|
+
- ๐ฏ **Lightweight** - Minimal bundle size
|
|
36
|
+
- โก **Reactive** - Built with Angular Signals
|
|
37
|
+
- ๐จ **CSS Variables** - Modern CSS custom properties
|
|
38
|
+
- ๐ **System Theme** - Auto-detects OS preference
|
|
39
|
+
- ๐พ **Persistent** - Remembers user choice
|
|
40
|
+
- ๐ **Type-Safe** - Full TypeScript support
|
|
41
|
+
- ๐ฆ **Zero Dependencies** - No bloat
|
|
42
|
+
- ๐งช **Well Tested** - Comprehensive test coverage
|
|
43
|
+
|
|
5
44
|
## Features
|
|
6
45
|
|
|
7
|
-
* Reactive State
|
|
8
|
-
* System Theme Integration
|
|
9
|
-
* Persistence
|
|
10
|
-
* Configurable
|
|
11
|
-
* Programmatic Control
|
|
46
|
+
* **Reactive State**: Uses Angular signals for efficient, reactive theme management.
|
|
47
|
+
* **System Theme Integration**: Automatically follows the user's system theme preference (`prefers-color-scheme`).
|
|
48
|
+
* **Persistence**: Remembers the user's last-selected theme using `localStorage`.
|
|
49
|
+
* **Configurable**: Customizable with a configuration object for storage keys, CSS variable prefixes, and default themes.
|
|
50
|
+
* **Programmatic Control**: Simple public API to set, get, and track the active theme.
|
|
12
51
|
|
|
13
52
|
## Available Themes
|
|
14
53
|
|
|
15
54
|
The service currently supports the following theme names by default:
|
|
16
55
|
|
|
17
|
-
* `light`
|
|
18
|
-
* `dark`
|
|
19
|
-
* `contrast`
|
|
20
|
-
* `custom`
|
|
21
|
-
* `system`
|
|
56
|
+
* `light` - Light theme
|
|
57
|
+
* `dark` - Dark theme
|
|
58
|
+
* `contrast` - High contrast theme
|
|
59
|
+
* `custom` - Custom theme with your own variables
|
|
60
|
+
* `system` - Automatically follows OS preference
|
|
22
61
|
|
|
23
62
|
You can provide custom variables for any of these themes via the `themes` property in `SuThemeConfig`.
|
|
24
63
|
|
|
64
|
+
## Installation
|
|
65
|
+
|
|
66
|
+
You can install this library via npm:
|
|
67
|
+
|
|
68
|
+
```sh
|
|
69
|
+
npm install @su-labs/theme
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Peer Dependencies
|
|
73
|
+
|
|
74
|
+
This library requires the following peer dependencies:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
npm install @angular/common@^21 @angular/core@^21
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## ๐ Quick Start
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
// 1. Install
|
|
84
|
+
npm install @su-labs/theme
|
|
85
|
+
|
|
86
|
+
// 2. Initialize in app.config.ts
|
|
87
|
+
import { provideAppInitializer, inject } from '@angular/core';
|
|
88
|
+
import { SuThemeService } from '@su-labs/theme';
|
|
89
|
+
|
|
90
|
+
export const appConfig = {
|
|
91
|
+
providers: [
|
|
92
|
+
provideAppInitializer(() => {
|
|
93
|
+
inject(SuThemeService).init();
|
|
94
|
+
}),
|
|
95
|
+
],
|
|
96
|
+
};
|
|
97
|
+
|
|
98
|
+
// 3. Use in component
|
|
99
|
+
import { Component, inject } from '@angular/core';
|
|
100
|
+
import { SuThemeService } from '@su-labs/theme';
|
|
101
|
+
|
|
102
|
+
@Component({
|
|
103
|
+
template: `
|
|
104
|
+
<button (click)="themeService.setTheme('dark')">Dark Mode</button>
|
|
105
|
+
<p>Current: {{ themeService.theme() }}</p>
|
|
106
|
+
`
|
|
107
|
+
})
|
|
108
|
+
export class AppComponent {
|
|
109
|
+
themeService = inject(SuThemeService);
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
25
113
|
## Usage
|
|
26
114
|
|
|
27
115
|
The `SuThemeService` must be initialized at application startup to load its configuration and initial theme.
|
|
@@ -58,11 +146,11 @@ export const appConfig = {
|
|
|
58
146
|
|
|
59
147
|
โ
This ensures the theme is loaded and applied before the application renders. The `SuThemeService` handles all the logic internally, including loading from `localStorage` and applying the initial theme.
|
|
60
148
|
|
|
61
|
-
###
|
|
149
|
+
### Example 2: Using the Theme in Your Styles
|
|
150
|
+
|
|
62
151
|
Your service automatically applies CSS variables to the `:root` element. Your application stylesheets can use these variables, and the service will handle updating their values when the theme changes.
|
|
63
152
|
|
|
64
153
|
```CSS
|
|
65
|
-
|
|
66
154
|
/* styles.css */
|
|
67
155
|
/* Use the CSS variables in your stylesheet */
|
|
68
156
|
body {
|
|
@@ -77,11 +165,11 @@ h1 {
|
|
|
77
165
|
|
|
78
166
|
The service dynamically updates these variables based on the active theme, applying a combination of its internal defaults and any custom overrides you provide in the configuration.
|
|
79
167
|
|
|
80
|
-
###
|
|
168
|
+
### Example 3: Dynamic Theme Switching
|
|
169
|
+
|
|
81
170
|
Use the setTheme() method to switch themes and the theme signal to read the current state.
|
|
82
171
|
|
|
83
172
|
```TypeScript
|
|
84
|
-
|
|
85
173
|
import { Component, inject } from '@angular/core';
|
|
86
174
|
import { SuThemeService, SuThemeName } from '@su-labs/theme';
|
|
87
175
|
|
|
@@ -98,7 +186,6 @@ import { SuThemeService, SuThemeName } from '@su-labs/theme';
|
|
|
98
186
|
`,
|
|
99
187
|
})
|
|
100
188
|
export class ThemeSwitcherComponent {
|
|
101
|
-
// Use the service directly in the template
|
|
102
189
|
public readonly themeService = inject(SuThemeService);
|
|
103
190
|
|
|
104
191
|
setTheme(themeName: SuThemeName) {
|
|
@@ -106,9 +193,40 @@ export class ThemeSwitcherComponent {
|
|
|
106
193
|
}
|
|
107
194
|
}
|
|
108
195
|
```
|
|
109
|
-
|
|
196
|
+
|
|
110
197
|
โ
This correctly shows how to use your service's public API to switch between themes. The service handles the underlying logic, including persistence and CSS variable application.
|
|
111
198
|
|
|
199
|
+
## ๐ API Reference
|
|
200
|
+
|
|
201
|
+
### Signals
|
|
202
|
+
|
|
203
|
+
| Signal | Type | Description |
|
|
204
|
+
|--------|------|-------------|
|
|
205
|
+
| `theme()` | `SuThemeName` | Current active theme name |
|
|
206
|
+
|
|
207
|
+
### Methods
|
|
208
|
+
|
|
209
|
+
| Method | Parameters | Description |
|
|
210
|
+
|--------|------------|-------------|
|
|
211
|
+
| `init(config?)` | `SuThemeConfig` | Initialize with custom configuration |
|
|
212
|
+
| `setTheme(theme, persist?)` | `SuThemeName, boolean` | Change theme (persist defaults to true) |
|
|
213
|
+
| `getTheme()` | - | Returns current theme name |
|
|
214
|
+
|
|
215
|
+
### Types
|
|
216
|
+
|
|
217
|
+
```typescript
|
|
218
|
+
type SuThemeName = 'light' | 'dark' | 'contrast' | 'custom' | 'system';
|
|
219
|
+
|
|
220
|
+
interface SuThemeConfig {
|
|
221
|
+
storageKey?: string; // Default: 'su:theme'
|
|
222
|
+
cssVarPrefix?: string; // Default: '--su-theme-'
|
|
223
|
+
defaultTheme?: SuThemeName; // Default: 'system'
|
|
224
|
+
themes?: {
|
|
225
|
+
[key in SuThemeName]?: Record<string, string>;
|
|
226
|
+
};
|
|
227
|
+
}
|
|
228
|
+
```
|
|
229
|
+
|
|
112
230
|
## Configuration Options
|
|
113
231
|
|
|
114
232
|
The service can be configured to fit your application's needs.
|
|
@@ -120,12 +238,60 @@ The service can be configured to fit your application's needs.
|
|
|
120
238
|
| `defaultTheme` | The theme to use if no preference is saved in `localStorage`. | `'system'` |
|
|
121
239
|
| `themes` | An object with custom CSS variable overrides for each theme. | `undefined` |
|
|
122
240
|
|
|
123
|
-
##
|
|
124
|
-
|
|
241
|
+
## ๐ Browser Compatibility
|
|
242
|
+
|
|
243
|
+
Works in all modern browsers that support:
|
|
244
|
+
- โ
CSS Custom Properties
|
|
245
|
+
- โ
localStorage API
|
|
246
|
+
- โ
matchMedia (for system theme)
|
|
247
|
+
- โ
Angular 21+
|
|
248
|
+
- โ
ES2022+
|
|
249
|
+
|
|
250
|
+
| Browser | Version |
|
|
251
|
+
|---------|---------|
|
|
252
|
+
| Chrome | โฅ 90 |
|
|
253
|
+
| Firefox | โฅ 88 |
|
|
254
|
+
| Safari | โฅ 14 |
|
|
255
|
+
| Edge | โฅ 90 |
|
|
125
256
|
|
|
126
|
-
|
|
257
|
+
## ๐ Related Libraries
|
|
127
258
|
|
|
128
|
-
|
|
259
|
+
Part of the **@su-labs** suite:
|
|
260
|
+
|
|
261
|
+
- ๐ [@su-labs/visit-tracker](https://www.npmjs.com/package/@su-labs/visit-tracker) - User visit tracking
|
|
262
|
+
- ๐ [@su-labs/notifications](https://www.npmjs.com/package/@su-labs/notifications) - Toast notification system
|
|
263
|
+
- ๐ [@su-labs/scroll-spy](https://www.npmjs.com/package/@su-labs/scroll-spy) - Scroll position tracking
|
|
264
|
+
- ๐ [@su-labs/font-size](https://www.npmjs.com/package/@su-labs/font-size) - Accessible font size controls
|
|
265
|
+
|
|
266
|
+
## ๐ง Troubleshooting
|
|
267
|
+
|
|
268
|
+
### Theme not persisting?
|
|
269
|
+
|
|
270
|
+
Make sure localStorage is enabled in your browser and not blocked by privacy settings.
|
|
271
|
+
|
|
272
|
+
### CSS variables not updating?
|
|
273
|
+
|
|
274
|
+
Ensure you're using the correct prefix in your CSS (`--su-theme-` by default) and that you've initialized the service.
|
|
275
|
+
|
|
276
|
+
### System theme not working?
|
|
277
|
+
|
|
278
|
+
Check that your OS has a theme preference set and your browser supports `prefers-color-scheme` media query.
|
|
279
|
+
|
|
280
|
+
### TypeScript errors?
|
|
281
|
+
|
|
282
|
+
Ensure you have Angular 21+ and TypeScript 5.7+ installed.
|
|
283
|
+
|
|
284
|
+
## ๐ฌ Support
|
|
285
|
+
|
|
286
|
+
- ๐ Found a bug? [Open an issue](https://github.com/Greezaaa/settings-utils-lib/issues)
|
|
287
|
+
- ๐ก Have a feature request? [Start a discussion](https://github.com/Greezaaa/settings-utils-lib/discussions)
|
|
288
|
+
- โญ Like this library? [Give it a star!](https://github.com/Greezaaa/settings-utils-lib)
|
|
289
|
+
|
|
290
|
+
## Notes
|
|
291
|
+
|
|
292
|
+
- The service safely handles properties and ignores null or undefined values, preventing issues like prototype pollution.
|
|
293
|
+
- Works seamlessly with standalone components and reactive setups thanks to its signal-based API.
|
|
294
|
+
- Persistence is handled automatically: The service saves the user's preference to `localStorage` when you call `setTheme(..., true)`. On initialization, it automatically restores this saved preference. You do not need to add this logic in your components.
|
|
129
295
|
|
|
130
296
|
## Contributing
|
|
131
297
|
|
|
@@ -135,5 +301,4 @@ To contribute code, please ensure your changes include unit tests to maintain co
|
|
|
135
301
|
|
|
136
302
|
## License
|
|
137
303
|
|
|
138
|
-
This project is licensed under the MIT License. See the [**LICENSE**](https://github.com/Greezaaa/settings-utils-lib/blob/main/projects/su-labs/theme/LICENSE) file for details.
|
|
139
|
-
|
|
304
|
+
This project is licensed under the MIT License. See the [**LICENSE**](https://github.com/Greezaaa/settings-utils-lib/blob/main/projects/su-labs/theme/LICENSE) file for details.
|