@su-labs/theme 22.0.0 → 22.2.0
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 +18 -0
- package/README.md +14 -8
- package/fesm2022/su-labs-theme.mjs +9 -78
- package/fesm2022/su-labs-theme.mjs.map +1 -1
- package/package.json +3 -2
- package/types/su-labs-theme.d.ts +18 -67
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,24 @@ 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
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [22.2.0] - 2026-11-07
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- `target` option: the element the theme is applied to (default: `<html>`), to theme one component instead of the whole page
|
|
14
|
+
- `storage` option: where the selected theme is saved (default: `localStorage`); pass `createSuCookieStorage({ domain })` from `@su-labs/core` to share it across subdomains
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
- Requires `@su-labs/core` 1.1.0 or later
|
|
18
|
+
- Package homepage now points to the website with a live demo
|
|
19
|
+
|
|
20
|
+
## [22.1.0] - 2026-11-05
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
- Theme logic moved to the framework-agnostic `@su-labs/core/theme`; `SuThemeService` is now an Angular wrapper around `SuThemeController` with the same public API
|
|
24
|
+
- Added `@su-labs/core` as a dependency
|
|
25
|
+
|
|
8
26
|
## [22.0.0] - 2026-11-04
|
|
9
27
|
|
|
10
28
|
### Changed
|
package/README.md
CHANGED
|
@@ -13,20 +13,22 @@
|
|
|
13
13
|
|
|
14
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.
|
|
15
15
|
|
|
16
|
+
> **Not using Angular?** The same theme logic is available for React, Svelte, vanilla JavaScript and Node in [`@su-labs/core`](https://www.npmjs.com/package/@su-labs/core). See the [installation guides](https://github.com/Greezaaa/settings-utils-lib/blob/main/docs/README.md).
|
|
17
|
+
|
|
16
18
|
## Table of Contents
|
|
17
19
|
|
|
18
|
-
- [Why Use This Library?](
|
|
20
|
+
- [Why Use This Library?](#why-use-this-library)
|
|
19
21
|
- [Features](#features)
|
|
20
22
|
- [Available Themes](#available-themes)
|
|
21
23
|
- [Installation](#installation)
|
|
22
|
-
- [Quick Start](
|
|
24
|
+
- [Quick Start](#quick-start)
|
|
23
25
|
- [Usage](#usage)
|
|
24
|
-
- [API Reference](
|
|
26
|
+
- [API Reference](#api-reference)
|
|
25
27
|
- [Configuration Options](#configuration-options)
|
|
26
|
-
- [Browser Compatibility](
|
|
27
|
-
- [Related Libraries](
|
|
28
|
-
- [Troubleshooting](
|
|
29
|
-
- [Support](
|
|
28
|
+
- [Browser Compatibility](#browser-compatibility)
|
|
29
|
+
- [Related Libraries](#related-libraries)
|
|
30
|
+
- [Troubleshooting](#troubleshooting)
|
|
31
|
+
- [Support](#support)
|
|
30
32
|
- [Contributing](#contributing)
|
|
31
33
|
- [License](#license)
|
|
32
34
|
|
|
@@ -219,6 +221,8 @@ type SuThemeName = 'light' | 'dark' | 'contrast' | 'custom' | 'system';
|
|
|
219
221
|
|
|
220
222
|
interface SuThemeConfig {
|
|
221
223
|
storageKey?: string; // Default: 'su:theme'
|
|
224
|
+
storage?: SuStorage; // Default: localStorage
|
|
225
|
+
target?: HTMLElement; // Default: <html>
|
|
222
226
|
cssVarPrefix?: string; // Default: '--su-theme-'
|
|
223
227
|
defaultTheme?: SuThemeName; // Default: 'system'
|
|
224
228
|
themes?: {
|
|
@@ -233,7 +237,9 @@ The service can be configured to fit your application's needs.
|
|
|
233
237
|
|
|
234
238
|
| Option | Description | Default Value |
|
|
235
239
|
|--------------------|---------------------------------------------------------------|------------------|
|
|
236
|
-
| `storageKey` | The key used to persist the selected theme
|
|
240
|
+
| `storageKey` | The key used to persist the selected theme. | `'su:theme'` |
|
|
241
|
+
| `storage` | Where the theme is saved. Use `createSuCookieStorage({ domain })` from `@su-labs/core` to share it across subdomains. | `localStorage` |
|
|
242
|
+
| `target` | Element the theme is applied to. Pass a component's element to theme only that part of the page. | `<html>` |
|
|
237
243
|
| `cssVarPrefix` | The prefix for all CSS variables managed by the service. | `'--su-theme-'` |
|
|
238
244
|
| `defaultTheme` | The theme to use if no preference is saved in `localStorage`. | `'system'` |
|
|
239
245
|
| `themes` | An object with custom CSS variable overrides for each theme. | `undefined` |
|
|
@@ -1,95 +1,26 @@
|
|
|
1
1
|
import * as i0 from "@angular/core";
|
|
2
2
|
import { Injectable, signal } from "@angular/core";
|
|
3
|
+
import { SuThemeController } from "@su-labs/core/theme";
|
|
3
4
|
var SuThemeService = class SuThemeService {
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
storageKey = "su:theme";
|
|
7
|
-
userPreference = "light";
|
|
8
|
-
currentThemeSignal = signal("light", ...ngDevMode ? [{ debugName: "currentThemeSignal" }] : /* istanbul ignore next */ []);
|
|
5
|
+
controller = new SuThemeController();
|
|
6
|
+
currentThemeSignal = signal(this.controller.getTheme(), ...ngDevMode ? [{ debugName: "currentThemeSignal" }] : /* istanbul ignore next */ []);
|
|
9
7
|
theme = this.currentThemeSignal.asReadonly();
|
|
10
|
-
|
|
11
|
-
mediaQuery;
|
|
8
|
+
unsubscribe = this.controller.theme.subscribe((theme) => this.currentThemeSignal.set(theme));
|
|
12
9
|
init(config) {
|
|
13
|
-
this.
|
|
14
|
-
...this.suThemeConfig,
|
|
15
|
-
...config
|
|
16
|
-
};
|
|
17
|
-
this.cssVarPrefix = this.suThemeConfig.cssVarPrefix ?? this.cssVarPrefix;
|
|
18
|
-
this.storageKey = this.suThemeConfig.storageKey ?? this.storageKey;
|
|
19
|
-
this.userPreference = localStorage.getItem(this.storageKey) ?? this.suThemeConfig.defaultTheme ?? "system";
|
|
20
|
-
this.setTheme(this.userPreference, false);
|
|
10
|
+
this.controller.init(config);
|
|
21
11
|
}
|
|
22
12
|
getTheme() {
|
|
23
13
|
return this.currentThemeSignal();
|
|
24
14
|
}
|
|
25
15
|
getUserPreference() {
|
|
26
|
-
return this.
|
|
16
|
+
return this.controller.getUserPreference();
|
|
27
17
|
}
|
|
28
18
|
setTheme(theme, persist = true) {
|
|
29
|
-
|
|
30
|
-
const resolvedTheme = theme === "system" ? this.resolveSystemTheme() : theme;
|
|
31
|
-
this.userPreference = theme;
|
|
32
|
-
this.currentThemeSignal.set(resolvedTheme);
|
|
33
|
-
document.documentElement.setAttribute("data-theme", resolvedTheme);
|
|
34
|
-
this.applyThemeVariables(resolvedTheme);
|
|
35
|
-
if (persist) localStorage.setItem(this.storageKey, theme);
|
|
36
|
-
if (theme === "system") this.listenToSystemChanges();
|
|
37
|
-
}
|
|
38
|
-
resolveSystemTheme() {
|
|
39
|
-
if (typeof window !== "undefined" && window.matchMedia("(prefers-color-scheme: dark)").matches) return "dark";
|
|
40
|
-
return "light";
|
|
41
|
-
}
|
|
42
|
-
listenToSystemChanges() {
|
|
43
|
-
if (!this.mediaQuery) {
|
|
44
|
-
this.mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
|
|
45
|
-
this.systemChangeHandler = (event) => {
|
|
46
|
-
if (this.userPreference === "system") {
|
|
47
|
-
this.currentThemeSignal.set(event.matches ? "dark" : "light");
|
|
48
|
-
document.documentElement.setAttribute("data-theme", this.currentThemeSignal());
|
|
49
|
-
this.applyThemeVariables(this.currentThemeSignal());
|
|
50
|
-
}
|
|
51
|
-
};
|
|
52
|
-
this.mediaQuery.addEventListener("change", this.systemChangeHandler);
|
|
53
|
-
}
|
|
54
|
-
}
|
|
55
|
-
stopListeningToSystemChanges() {
|
|
56
|
-
if (this.mediaQuery && this.systemChangeHandler) {
|
|
57
|
-
this.mediaQuery.removeEventListener("change", this.systemChangeHandler);
|
|
58
|
-
this.systemChangeHandler = null;
|
|
59
|
-
this.mediaQuery = void 0;
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
applyThemeVariables(theme) {
|
|
63
|
-
const variablesToApply = {
|
|
64
|
-
...{
|
|
65
|
-
light: {
|
|
66
|
-
color: "#333",
|
|
67
|
-
background: "#fff",
|
|
68
|
-
"main-accent": "#007bff",
|
|
69
|
-
"second-accent": "#6c757d",
|
|
70
|
-
"third-accent": "#28a745"
|
|
71
|
-
},
|
|
72
|
-
dark: {
|
|
73
|
-
color: "#f0f0f0",
|
|
74
|
-
background: "#1a1a1a",
|
|
75
|
-
"main-accent": "#38a8e1",
|
|
76
|
-
"second-accent": "#a8b0b5",
|
|
77
|
-
"third-accent": "#2ee057"
|
|
78
|
-
},
|
|
79
|
-
contrast: {
|
|
80
|
-
color: "#000",
|
|
81
|
-
background: "#fff",
|
|
82
|
-
"main-accent": "#ff0000"
|
|
83
|
-
},
|
|
84
|
-
custom: {},
|
|
85
|
-
system: {}
|
|
86
|
-
}[theme],
|
|
87
|
-
...this.suThemeConfig.themes?.[theme] ?? {}
|
|
88
|
-
};
|
|
89
|
-
for (const [key, value] of Object.entries(variablesToApply)) if (value) document.documentElement.style.setProperty(`${this.cssVarPrefix}${key}`, value);
|
|
19
|
+
this.controller.setTheme(theme, persist);
|
|
90
20
|
}
|
|
91
21
|
ngOnDestroy() {
|
|
92
|
-
this.
|
|
22
|
+
this.unsubscribe();
|
|
23
|
+
this.controller.destroy();
|
|
93
24
|
}
|
|
94
25
|
static ɵfac = i0.ɵɵngDeclareFactory({
|
|
95
26
|
minVersion: "12.0.0",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"su-labs-theme.mjs","names":[],"sources":["../../../../projects/su-labs/theme/src/lib/theme.service.ts"],"sourcesContent":["import { Injectable,
|
|
1
|
+
{"version":3,"file":"su-labs-theme.mjs","names":[],"sources":["../../../../projects/su-labs/theme/src/lib/theme.service.ts"],"sourcesContent":["import { Injectable, OnDestroy, signal } from '@angular/core';\nimport { SuThemeConfig, SuThemeController, SuThemeName } from '@su-labs/core/theme';\n\n/**\n * Angular service for managing application themes.\n *\n * Thin wrapper around the framework-agnostic `SuThemeController` from `@su-labs/core/theme`\n * that exposes the resolved theme as an Angular signal.\n */\n@Injectable({\n providedIn: 'root',\n})\nexport class SuThemeService implements OnDestroy {\n /** Framework-agnostic theme logic */\n private readonly controller = new SuThemeController();\n\n /** Current resolved theme signal, kept in sync with the controller */\n private readonly currentThemeSignal = signal<SuThemeName>(this.controller.getTheme());\n\n /** Read-only access to the resolved theme signal */\n readonly theme = this.currentThemeSignal.asReadonly();\n\n /** Stops syncing the controller's theme into the signal */\n private readonly unsubscribe = this.controller.theme.subscribe((theme) => this.currentThemeSignal.set(theme));\n\n /**\n * Initialize the service with optional configuration.\n * Should be called from an app initializer for default setup.\n * @param config Optional configuration object.\n */\n public init(config?: SuThemeConfig): void {\n this.controller.init(config);\n }\n\n /**\n * Get the currently active, resolved theme.\n * @returns The resolved theme name ('light', 'dark', 'contrast', 'custom').\n */\n public getTheme(): SuThemeName {\n return this.currentThemeSignal();\n }\n\n /**\n * Get the user's theme preference (may be 'system').\n * @returns The user preference ('light', 'dark', 'contrast', 'custom', 'system').\n */\n public getUserPreference(): SuThemeName {\n return this.controller.getUserPreference();\n }\n\n /**\n * Set a new theme.\n * @param theme The theme to set ('light', 'dark', 'contrast', 'custom', 'system').\n * @param persist Whether to store the preference in localStorage (default: true).\n */\n public setTheme(theme: SuThemeName, persist: boolean = true): void {\n this.controller.setTheme(theme, persist);\n }\n\n /** Angular lifecycle hook for service destruction */\n ngOnDestroy(): void {\n this.unsubscribe();\n this.controller.destroy();\n }\n}\n"],"mappings":";;;AAYA,IAAa,iBAAb,MAAa,eAAc;CAER,aAAa,IAAI,kBAAiB;CAGlC,qBAAqB,OAAoB,KAAK,WAAW,SAAQ,GAAG,GAAA,YAAA,CAAA,EAAA,WAAA,qBAAA,CAAA,+BAAA,CAAA,CAAA;CAG5E,QAAQ,KAAK,mBAAmB,WAAU;CAGlC,cAAc,KAAK,WAAW,MAAM,WAAW,UAAU,KAAK,mBAAmB,IAAI,KAAK,CAAC;CAOrG,KAAK,QAAsB;EAChC,KAAK,WAAW,KAAK,MAAM;CAC7B;CAMO,WAAQ;EACb,OAAO,KAAK,mBAAkB;CAChC;CAMO,oBAAiB;EACtB,OAAO,KAAK,WAAW,kBAAiB;CAC1C;CAOO,SAAS,OAAoB,UAAmB,MAAI;EACzD,KAAK,WAAW,SAAS,OAAO,OAAO;CACzC;CAGA,cAAW;EACT,KAAK,YAAW;EAChB,KAAK,WAAW,QAAO;CACzB;CAnDW,OAAA,OAAA,GAAA,mBAAA;EAAA,YAAA;EAAA,SAAA;EAAA,UAAA;EAAA,MAAA;EAAc,MAAA,CAAA;EAAA,QAAA,GAAA,gBAAA;CAAA,CAAA;CAAd,OAAA,QAAA,GAAA,sBAAA;EAAA,YAAA;EAAA,SAAA;EAAA,UAAA;EAAA,MAAA;EAAc,YAFb;CAAM,CAAA;;AAEP,GAAA,yBAAA;CAAA,YAAA;CAAA,SAAA;CAAA,UAAA;CAAA,MAAA;CAAc,YAAA,CAAA;EAH1B,MAAA;EAAW,MAAA,CAAA,EACV,YAAY,OACb,CAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@su-labs/theme",
|
|
3
|
-
"version": "22.
|
|
3
|
+
"version": "22.2.0",
|
|
4
4
|
"keywords": [
|
|
5
5
|
"angular",
|
|
6
6
|
"theme",
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"system-theme",
|
|
19
19
|
"prefers-color-scheme"
|
|
20
20
|
],
|
|
21
|
-
"homepage": "https://
|
|
21
|
+
"homepage": "https://su-labs.dev/theme/",
|
|
22
22
|
"author": {
|
|
23
23
|
"name": "Yevheniy Alekseyev",
|
|
24
24
|
"email": "yev.alekseyev@gmail.com",
|
|
@@ -37,6 +37,7 @@
|
|
|
37
37
|
"@angular/core": "^22.0.0"
|
|
38
38
|
},
|
|
39
39
|
"dependencies": {
|
|
40
|
+
"@su-labs/core": "^1.1.0",
|
|
40
41
|
"tslib": "^2.3.0"
|
|
41
42
|
},
|
|
42
43
|
"sideEffects": false,
|
package/types/su-labs-theme.d.ts
CHANGED
|
@@ -1,95 +1,46 @@
|
|
|
1
1
|
import * as i0 from "@angular/core";
|
|
2
2
|
import { OnDestroy } from "@angular/core";
|
|
3
|
-
|
|
4
|
-
export type SuThemeName = 'light' | 'dark' | 'contrast' | 'custom' | 'system';
|
|
5
|
-
/** Theme configuration */
|
|
6
|
-
export interface SuThemeConfig {
|
|
7
|
-
/** localStorage key for storing selected theme */
|
|
8
|
-
storageKey?: string;
|
|
9
|
-
/** CSS variable prefix, applied to all theme variables */
|
|
10
|
-
cssVarPrefix?: string;
|
|
11
|
-
/** Default theme if nothing saved in localStorage */
|
|
12
|
-
defaultTheme?: SuThemeName;
|
|
13
|
-
/** Optional CSS variable overrides for specific themes */
|
|
14
|
-
themes?: Partial<Record<SuThemeName, ThemeCssVariables>>;
|
|
15
|
-
}
|
|
16
|
-
/** Available CSS variables for theming */
|
|
17
|
-
export interface ThemeCssVariables {
|
|
18
|
-
color?: string;
|
|
19
|
-
background?: string;
|
|
20
|
-
'main-accent'?: string;
|
|
21
|
-
'second-accent'?: string;
|
|
22
|
-
'third-accent'?: string;
|
|
23
|
-
[key: string]: string | undefined;
|
|
24
|
-
}
|
|
3
|
+
import { SuThemeConfig, SuThemeConfig as SuThemeConfig$1, SuThemeName, SuThemeName as SuThemeName$1, ThemeCssVariables } from "@su-labs/core/theme";
|
|
25
4
|
/**
|
|
26
|
-
*
|
|
5
|
+
* Angular service for managing application themes.
|
|
27
6
|
*
|
|
28
|
-
*
|
|
29
|
-
*
|
|
7
|
+
* Thin wrapper around the framework-agnostic `SuThemeController` from `@su-labs/core/theme`
|
|
8
|
+
* that exposes the resolved theme as an Angular signal.
|
|
30
9
|
*/
|
|
31
10
|
export declare class SuThemeService implements OnDestroy {
|
|
32
|
-
/**
|
|
33
|
-
private
|
|
34
|
-
/**
|
|
35
|
-
private
|
|
36
|
-
/** localStorage key for storing user preference, can be customized */
|
|
37
|
-
private storageKey;
|
|
38
|
-
/** User selected theme (can be 'system') */
|
|
39
|
-
private userPreference;
|
|
40
|
-
/** Current resolved theme signal ('light' | 'dark' | 'contrast' | 'custom') */
|
|
41
|
-
private currentThemeSignal;
|
|
11
|
+
/** Framework-agnostic theme logic */
|
|
12
|
+
private readonly controller;
|
|
13
|
+
/** Current resolved theme signal, kept in sync with the controller */
|
|
14
|
+
private readonly currentThemeSignal;
|
|
42
15
|
/** Read-only access to the resolved theme signal */
|
|
43
|
-
readonly theme: import("@angular/core").Signal<SuThemeName>;
|
|
44
|
-
/**
|
|
45
|
-
private
|
|
46
|
-
/** MediaQueryList instance for system theme changes */
|
|
47
|
-
private mediaQuery?;
|
|
16
|
+
readonly theme: import("@angular/core").Signal<SuThemeName$1>;
|
|
17
|
+
/** Stops syncing the controller's theme into the signal */
|
|
18
|
+
private readonly unsubscribe;
|
|
48
19
|
/**
|
|
49
20
|
* Initialize the service with optional configuration.
|
|
50
|
-
* Should be called from
|
|
21
|
+
* Should be called from an app initializer for default setup.
|
|
51
22
|
* @param config Optional configuration object.
|
|
52
23
|
*/
|
|
53
|
-
init(config?: SuThemeConfig): void;
|
|
24
|
+
init(config?: SuThemeConfig$1): void;
|
|
54
25
|
/**
|
|
55
26
|
* Get the currently active, resolved theme.
|
|
56
27
|
* @returns The resolved theme name ('light', 'dark', 'contrast', 'custom').
|
|
57
28
|
*/
|
|
58
|
-
getTheme(): SuThemeName;
|
|
29
|
+
getTheme(): SuThemeName$1;
|
|
59
30
|
/**
|
|
60
31
|
* Get the user's theme preference (may be 'system').
|
|
61
32
|
* @returns The user preference ('light', 'dark', 'contrast', 'custom', 'system').
|
|
62
33
|
*/
|
|
63
|
-
getUserPreference(): SuThemeName;
|
|
34
|
+
getUserPreference(): SuThemeName$1;
|
|
64
35
|
/**
|
|
65
36
|
* Set a new theme.
|
|
66
37
|
* @param theme The theme to set ('light', 'dark', 'contrast', 'custom', 'system').
|
|
67
38
|
* @param persist Whether to store the preference in localStorage (default: true).
|
|
68
39
|
*/
|
|
69
|
-
setTheme(theme: SuThemeName, persist?: boolean): void;
|
|
70
|
-
/**
|
|
71
|
-
* Resolve the current system theme using prefers-color-scheme.
|
|
72
|
-
* @returns 'dark' if system prefers dark mode, otherwise 'light'.
|
|
73
|
-
*/
|
|
74
|
-
private resolveSystemTheme;
|
|
75
|
-
/**
|
|
76
|
-
* Listen to system theme changes and automatically update the theme.
|
|
77
|
-
* Only active when user preference is 'system'.
|
|
78
|
-
*/
|
|
79
|
-
private listenToSystemChanges;
|
|
80
|
-
/**
|
|
81
|
-
* Stop listening to system theme changes.
|
|
82
|
-
* Should be called when the service is destroyed or theme is no longer 'system'.
|
|
83
|
-
*/
|
|
84
|
-
private stopListeningToSystemChanges;
|
|
85
|
-
/**
|
|
86
|
-
* Apply CSS variables for the given theme.
|
|
87
|
-
* This method applies default variables if they are not overridden in the config.
|
|
88
|
-
* @param theme The theme whose variables should be applied.
|
|
89
|
-
*/
|
|
90
|
-
private applyThemeVariables;
|
|
40
|
+
setTheme(theme: SuThemeName$1, persist?: boolean): void;
|
|
91
41
|
/** Angular lifecycle hook for service destruction */
|
|
92
42
|
ngOnDestroy(): void;
|
|
93
43
|
static ɵfac: i0.ɵɵFactoryDeclaration<SuThemeService, never>;
|
|
94
44
|
static ɵprov: i0.ɵɵInjectableDeclaration<any>;
|
|
95
|
-
}
|
|
45
|
+
}
|
|
46
|
+
export type { SuThemeConfig, SuThemeName, ThemeCssVariables };
|