ngx-theme-stack 0.0.1

package/README.md

@@ -0,0 +1,61 @@
+# ngx-theme-stack
+
+A robust, SSR-safe, and signal-based theme management library for Angular applications.
+
+## Features
+
+- 🌓 **SSR Safe**: Works perfectly with Angular Universal/SSR.
+- 🚦 **Signal-based**: Built with modern Angular Signals for reactive theme management.
+- 🛠️ **Schematics Support**: Easy installation and configuration via `ng add`.
+- 🧬 **Flexible**: Support for custom themes and system theme detection.
+
+## Quick Start
+
+### Installation
+
+```bash
+ng add ngx-theme-stack
+```
+
+### Usage
+
+Inject the `ThemeService` into your component or use the provided directives.
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { ThemeService } from 'ngx-theme-stack';
+
+@Component({
+  selector: 'app-root',
+  template: `
+    <button (click)="theme.toggleTheme()">Toggle Theme</button>
+    <p>Current theme: {{ theme.currentTheme() }}</p>
+  `,
+  imports: []
+})
+export class AppComponent {
+  theme = inject(ThemeService);
+}
+```
+
+## Developing
+
+### Building
+
+To build the library, run:
+
+```bash
+ng build ngx-theme-stack
+```
+
+The build artifacts will be placed in the `dist/ngx-theme-stack` directory.
+
+### Running unit tests
+
+```bash
+ng test ngx-theme-stack
+```
+
+## License
+
+MIT

package/fesm2022/ngx-theme-stack.mjs

@@ -0,0 +1,281 @@
+import { isPlatformBrowser } from '@angular/common';
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, DestroyRef, DOCUMENT, RendererFactory2, PLATFORM_ID, signal, computed, effect, Injectable } from '@angular/core';
+
+/** Built-in themes. All other values are considered custom themes. */
+const DEFAULT_THEMES = ['light', 'dark', 'system'];
+
+const DEFAULT_NG_CONFIG = {
+    theme: 'system',
+    storageKey: 'ngx-theme-stack-theme',
+    mode: 'class',
+    themes: [...DEFAULT_THEMES],
+};
+const NGX_THEME_STACK_CONFIG = new InjectionToken('NGX_THEME_STACK_CONFIG', {
+    factory: () => DEFAULT_NG_CONFIG,
+});
+/**
+ * Helper function to provide Theme Stack configuration.
+ */
+function provideThemeStack(config = {}) {
+    return {
+        provide: NGX_THEME_STACK_CONFIG,
+        useValue: {
+            ...DEFAULT_NG_CONFIG,
+            ...config,
+        },
+    };
+}
+
+/**
+ * Core service for managing the application's color theme.
+ *
+ * Handles theme persistence, system preference detection, and DOM updates.
+ * Supports built-in themes ('dark', 'light', 'system') and custom extensions.
+ */
+class CoreThemeService {
+    // ── Dependencies ──────────────────────────────────────────────────────────
+    #config = inject(NGX_THEME_STACK_CONFIG);
+    #destroyRef = inject(DestroyRef);
+    #document = inject(DOCUMENT);
+    #renderer = inject(RendererFactory2).createRenderer(null, null);
+    #isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
+    // ── Theme configuration ───────────────────────────────────────────────────
+    /** List of available themes for Select/Cycle services. Defaults to ['light', 'dark', 'system']. */
+    availableThemes = this.#config.themes;
+    /** Internal Set for O(1) existence checks. */
+    #validThemes = new Set(this.availableThemes);
+    // ── System preference ─────────────────────────────────────────────────────
+    /** MediaQueryList for OS color scheme, created once and reused. Null in SSR. */
+    #mediaQuery = this.#isBrowser
+        ? (this.#document.defaultView?.matchMedia('(prefers-color-scheme: dark)') ?? null)
+        : null;
+    #systemPreference = signal(this.resolveSystemPreference(), ...(ngDevMode ? [{ debugName: "#systemPreference" }] : /* istanbul ignore next */ []));
+    // ── Theme state ───────────────────────────────────────────────────────────
+    #selectedTheme = signal(this.resolveInitialTheme(), ...(ngDevMode ? [{ debugName: "#selectedTheme" }] : /* istanbul ignore next */ []));
+    /** The theme explicitly selected by the user. May be `'system'`. */
+    selectedTheme = this.#selectedTheme.asReadonly();
+    /** Resolved theme applied to the DOM. Always `'dark'` or `'light'` (or custom) — never `'system'`. */
+    userTheme = computed(() => {
+        const theme = this.#selectedTheme();
+        return theme === 'system' ? this.#systemPreference() : theme;
+    }, ...(ngDevMode ? [{ debugName: "userTheme" }] : /* istanbul ignore next */ []));
+    /** Whether the currently applied theme is dark. */
+    isDark = computed(() => this.userTheme() === 'dark', ...(ngDevMode ? [{ debugName: "isDark" }] : /* istanbul ignore next */ []));
+    /** Whether the currently applied theme is light. */
+    isLight = computed(() => this.userTheme() === 'light', ...(ngDevMode ? [{ debugName: "isLight" }] : /* istanbul ignore next */ []));
+    // ── Event handler ─────────────────────────────────────────────────────────
+    #onSystemPreferenceChange = () => this.#systemPreference.set(this.resolveSystemPreference());
+    // ── Lifecycle ─────────────────────────────────────────────────────────────
+    constructor() {
+        if (this.#isBrowser && this.#selectedTheme() === 'system') {
+            this.startSystemThemeListener();
+        }
+        effect(() => this.applyThemeToDOM(this.userTheme()));
+        this.#destroyRef.onDestroy(() => this.stopSystemThemeListener());
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * Changes the active theme.
+     *
+     * Persists the choice explicitly so that switching e.g. from `'system'` to
+     * `'light'` is saved even when the resolved `userTheme` did not change
+     * (system preference was already `'light'`).
+     *
+     * @param theme - The theme to apply: `'dark'`, `'light'`, `'system'`, or a custom theme name.
+     * @throws If `theme` is not a valid theme according to library configuration.
+     */
+    setTheme(theme) {
+        if (!this.#isBrowser)
+            return;
+        if (!this.#validThemes.has(theme)) {
+            throw new Error(`[ngx-theme-stack] Invalid theme: "${theme}". Valid values are: ${[...this.#validThemes].join(', ')}.`);
+        }
+        if (theme === 'system') {
+            this.startSystemThemeListener();
+        }
+        else {
+            this.stopSystemThemeListener();
+        }
+        this.#selectedTheme.set(theme);
+        this.saveTheme(theme);
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    resolveSystemPreference() {
+        return this.#mediaQuery?.matches ? 'dark' : 'light';
+    }
+    resolveInitialTheme() {
+        if (!this.#isBrowser)
+            return this.#config.theme;
+        const saved = this.readStoredTheme();
+        return saved && this.#validThemes.has(saved) ? saved : this.#config.theme;
+    }
+    startSystemThemeListener() {
+        if (!this.#mediaQuery)
+            return;
+        this.stopSystemThemeListener();
+        this.#mediaQuery.addEventListener('change', this.#onSystemPreferenceChange);
+    }
+    stopSystemThemeListener() {
+        this.#mediaQuery?.removeEventListener('change', this.#onSystemPreferenceChange);
+    }
+    applyThemeToDOM(userTheme) {
+        if (!this.#isBrowser)
+            return;
+        const host = this.#document.documentElement;
+        const { mode } = this.#config;
+        if (mode === 'attribute' || mode === 'both') {
+            this.#renderer.setAttribute(host, 'data-theme', userTheme);
+        }
+        if (mode === 'class' || mode === 'both') {
+            for (const theme of this.availableThemes) {
+                this.#renderer.removeClass(host, theme);
+            }
+            this.#renderer.addClass(host, userTheme);
+        }
+        if (userTheme === 'dark' || userTheme === 'light') {
+            this.#renderer.setStyle(host, 'color-scheme', userTheme);
+            return;
+        }
+        this.#renderer.removeStyle(host, 'color-scheme');
+    }
+    readStoredTheme() {
+        try {
+            return localStorage.getItem(this.#config.storageKey);
+        }
+        catch (e) {
+            console.warn('[ngx-theme-stack] Could not read theme from localStorage.', e);
+            return null;
+        }
+    }
+    saveTheme(theme) {
+        try {
+            localStorage.setItem(this.#config.storageKey, theme);
+        }
+        catch (e) {
+            console.warn('[ngx-theme-stack] Could not save theme to localStorage.', e);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: CoreThemeService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: CoreThemeService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: CoreThemeService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Convenience service for cycling through themes in a fixed order.
+ *
+ * Default cycle: `'light'` → `'dark'` → `'system'` → `'light'` → ...
+ *
+ * Use this when you want to offer users a single button that rotates
+ * through all available theme options.
+ */
+class ThemeCycleService {
+    #core = inject(CoreThemeService);
+    /** List of all configured themes for cycling. Defaults to ['light', 'dark', 'system']. */
+    #cycle = this.#core.availableThemes;
+    /** The theme explicitly selected by the user. May be `'system'`. */
+    selectedTheme = this.#core.selectedTheme;
+    /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */
+    userTheme = this.#core.userTheme;
+    /** Whether the currently applied theme is dark. */
+    isDark = this.#core.isDark;
+    /** Whether the currently applied theme is light. */
+    isLight = this.#core.isLight;
+    /**
+     * Advances to the next theme in the cycle.
+     *
+     * Cycle order is determined by the configured `themes` property in `NgConfig`.
+     *
+     * If the current theme is not found in the cycle (e.g. set externally),
+     * the cycle restarts from the first theme.
+     */
+    cycle() {
+        const current = this.#core.selectedTheme();
+        const index = this.#cycle.indexOf(current);
+        const next = this.#cycle[(index + 1) % this.#cycle.length];
+        this.#core.setTheme(next);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeCycleService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeCycleService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeCycleService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Convenience service for selecting a theme from a list.
+ *
+ * Use this when you want to bind a `<select>` or a group of radio/tab
+ * buttons to the full set of available themes.
+ */
+class ThemeSelectService {
+    #core = inject(CoreThemeService);
+    /** List of all configured themes. Defaults to ['light', 'dark', 'system']. */
+    availableThemes = this.#core.availableThemes;
+    /** The theme explicitly selected by the user. May be `'system'`. */
+    selectedTheme = this.#core.selectedTheme;
+    /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */
+    userTheme = this.#core.userTheme;
+    /** Whether the currently applied theme is dark. */
+    isDark = this.#core.isDark;
+    /** Whether the currently applied theme is light. */
+    isLight = this.#core.isLight;
+    /**
+     * Applies the given theme.
+     *
+     * @param theme - The theme to apply: `'dark'`, `'light'`, `'system'`, or custom.
+     * @throws If `theme` is not a valid theme according to library configuration.
+     */
+    select(theme) {
+        this.#core.setTheme(theme);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeSelectService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeSelectService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeSelectService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Convenience service for toggling between `'dark'` and `'light'`.
+ *
+ * Use this when you only need a simple on/off switch and do not
+ * need to manage `'system'` or cycle through themes.
+ */
+class ThemeToggleService {
+    #core = inject(CoreThemeService);
+    /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */
+    userTheme = this.#core.userTheme;
+    /** Whether the currently applied theme is dark. */
+    isDark = this.#core.isDark;
+    /** Whether the currently applied theme is light. */
+    isLight = this.#core.isLight;
+    /**
+     * Toggles between `'dark'` and `'light'`.
+     *
+     * If the selected theme is explicitly `'dark'`, switches to `'light'`.
+     * Otherwise (including `'system'`), switches to `'dark'`.
+     */
+    toggle() {
+        const next = this.#core.selectedTheme() === 'dark' ? 'light' : 'dark';
+        this.#core.setTheme(next);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeToggleService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeToggleService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.6", ngImport: i0, type: ThemeToggleService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { CoreThemeService, DEFAULT_NG_CONFIG, DEFAULT_THEMES, NGX_THEME_STACK_CONFIG, ThemeCycleService, ThemeSelectService, ThemeToggleService, provideThemeStack };
+//# sourceMappingURL=ngx-theme-stack.mjs.map

package/fesm2022/ngx-theme-stack.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ngx-theme-stack.mjs","sources":["../../../projects/ngx-theme-stack/src/lib/types.ts","../../../projects/ngx-theme-stack/src/lib/theme-stack.config.ts","../../../projects/ngx-theme-stack/src/lib/core-theme.service.ts","../../../projects/ngx-theme-stack/src/lib/theme-cycle.service.ts","../../../projects/ngx-theme-stack/src/lib/theme-select.service.ts","../../../projects/ngx-theme-stack/src/lib/theme-toggle.service.ts","../../../projects/ngx-theme-stack/src/ngx-theme-stack.ts"],"sourcesContent":["/** Built-in themes. All other values are considered custom themes. */\nexport const DEFAULT_THEMES = ['light', 'dark', 'system'] as const;\n\n/** String union with autocompletion for defaults + any string support for customization. */\nexport type NgTheme = (typeof DEFAULT_THEMES)[number] | (string & {});\n\nexport type NgSystemTheme = Exclude<NgTheme, 'system'>;\nexport type NgMode = 'attribute' | 'class' | 'both';\n\nexport interface NgConfig {\n  theme: NgTheme;\n  storageKey: string;\n  mode: NgMode;\n  themes: NgTheme[];\n}\n","import { InjectionToken } from '@angular/core';\nimport { DEFAULT_THEMES, NgConfig } from './types';\n\nexport const DEFAULT_NG_CONFIG = {\n  theme: 'system',\n  storageKey: 'ngx-theme-stack-theme',\n  mode: 'class',\n  themes: [...DEFAULT_THEMES],\n} satisfies NgConfig;\n\nexport const NGX_THEME_STACK_CONFIG = new InjectionToken<NgConfig>('NGX_THEME_STACK_CONFIG', {\n  factory: () => DEFAULT_NG_CONFIG,\n});\n\n/**\n * Helper function to provide Theme Stack configuration.\n */\nexport function provideThemeStack(config: Partial<NgConfig> = {}) {\n  return {\n    provide: NGX_THEME_STACK_CONFIG,\n    useValue: {\n      ...DEFAULT_NG_CONFIG,\n      ...config,\n    } satisfies NgConfig,\n  };\n}\n","import { isPlatformBrowser } from '@angular/common';\nimport {\n  computed,\n  DestroyRef,\n  DOCUMENT,\n  effect,\n  inject,\n  Injectable,\n  PLATFORM_ID,\n  RendererFactory2,\n  signal,\n} from '@angular/core';\nimport { NGX_THEME_STACK_CONFIG } from './theme-stack.config';\nimport { NgSystemTheme, NgTheme } from './types';\n\n/**\n * Core service for managing the application's color theme.\n *\n * Handles theme persistence, system preference detection, and DOM updates.\n * Supports built-in themes ('dark', 'light', 'system') and custom extensions.\n */\n@Injectable({ providedIn: 'root' })\nexport class CoreThemeService {\n  // ── Dependencies ──────────────────────────────────────────────────────────\n\n  readonly #config = inject(NGX_THEME_STACK_CONFIG);\n  readonly #destroyRef = inject(DestroyRef);\n  readonly #document = inject(DOCUMENT);\n  readonly #renderer = inject(RendererFactory2).createRenderer(null, null);\n  readonly #isBrowser = isPlatformBrowser(inject(PLATFORM_ID));\n\n  // ── Theme configuration ───────────────────────────────────────────────────\n\n  /** List of available themes for Select/Cycle services. Defaults to ['light', 'dark', 'system']. */\n  readonly availableThemes = this.#config.themes;\n\n  /** Internal Set for O(1) existence checks. */\n  readonly #validThemes = new Set<NgTheme>(this.availableThemes);\n\n  // ── System preference ─────────────────────────────────────────────────────\n\n  /** MediaQueryList for OS color scheme, created once and reused. Null in SSR. */\n  readonly #mediaQuery: MediaQueryList | null = this.#isBrowser\n    ? (this.#document.defaultView?.matchMedia('(prefers-color-scheme: dark)') ?? null)\n    : null;\n\n  readonly #systemPreference = signal<NgSystemTheme>(this.resolveSystemPreference());\n\n  // ── Theme state ───────────────────────────────────────────────────────────\n\n  readonly #selectedTheme = signal<NgTheme>(this.resolveInitialTheme());\n\n  /** The theme explicitly selected by the user. May be `'system'`. */\n  readonly selectedTheme = this.#selectedTheme.asReadonly();\n\n  /** Resolved theme applied to the DOM. Always `'dark'` or `'light'` (or custom) — never `'system'`. */\n  readonly userTheme = computed(() => {\n    const theme = this.#selectedTheme();\n    return theme === 'system' ? this.#systemPreference() : theme;\n  });\n\n  /** Whether the currently applied theme is dark. */\n  readonly isDark = computed(() => this.userTheme() === 'dark');\n\n  /** Whether the currently applied theme is light. */\n  readonly isLight = computed(() => this.userTheme() === 'light');\n\n  // ── Event handler ─────────────────────────────────────────────────────────\n\n  readonly #onSystemPreferenceChange = () =>\n    this.#systemPreference.set(this.resolveSystemPreference());\n\n  // ── Lifecycle ─────────────────────────────────────────────────────────────\n\n  constructor() {\n    if (this.#isBrowser && this.#selectedTheme() === 'system') {\n      this.startSystemThemeListener();\n    }\n\n    effect(() => this.applyThemeToDOM(this.userTheme()));\n\n    this.#destroyRef.onDestroy(() => this.stopSystemThemeListener());\n  }\n\n  // ── Public API ────────────────────────────────────────────────────────────\n\n  /**\n   * Changes the active theme.\n   *\n   * Persists the choice explicitly so that switching e.g. from `'system'` to\n   * `'light'` is saved even when the resolved `userTheme` did not change\n   * (system preference was already `'light'`).\n   *\n   * @param theme - The theme to apply: `'dark'`, `'light'`, `'system'`, or a custom theme name.\n   * @throws If `theme` is not a valid theme according to library configuration.\n   */\n  public setTheme(theme: NgTheme): void {\n    if (!this.#isBrowser) return;\n\n    if (!this.#validThemes.has(theme)) {\n      throw new Error(\n        `[ngx-theme-stack] Invalid theme: \"${theme}\". Valid values are: ${[...this.#validThemes].join(', ')}.`,\n      );\n    }\n\n    if (theme === 'system') {\n      this.startSystemThemeListener();\n    } else {\n      this.stopSystemThemeListener();\n    }\n\n    this.#selectedTheme.set(theme);\n    this.saveTheme(theme);\n  }\n\n  // ── Private ───────────────────────────────────────────────────────────────\n\n  private resolveSystemPreference(): NgSystemTheme {\n    return this.#mediaQuery?.matches ? 'dark' : 'light';\n  }\n\n  private resolveInitialTheme(): NgTheme {\n    if (!this.#isBrowser) return this.#config.theme;\n    const saved = this.readStoredTheme();\n    return saved && this.#validThemes.has(saved) ? saved : this.#config.theme;\n  }\n\n  private startSystemThemeListener(): void {\n    if (!this.#mediaQuery) return;\n    this.stopSystemThemeListener();\n    this.#mediaQuery.addEventListener('change', this.#onSystemPreferenceChange);\n  }\n\n  private stopSystemThemeListener(): void {\n    this.#mediaQuery?.removeEventListener('change', this.#onSystemPreferenceChange);\n  }\n\n  private applyThemeToDOM(userTheme: NgTheme): void {\n    if (!this.#isBrowser) return;\n\n    const host = this.#document.documentElement;\n    const { mode } = this.#config;\n\n    if (mode === 'attribute' || mode === 'both') {\n      this.#renderer.setAttribute(host, 'data-theme', userTheme);\n    }\n\n    if (mode === 'class' || mode === 'both') {\n      for (const theme of this.availableThemes) {\n        this.#renderer.removeClass(host, theme);\n      }\n      this.#renderer.addClass(host, userTheme);\n    }\n\n    if (userTheme === 'dark' || userTheme === 'light') {\n      this.#renderer.setStyle(host, 'color-scheme', userTheme);\n      return;\n    }\n\n    this.#renderer.removeStyle(host, 'color-scheme');\n  }\n\n  private readStoredTheme(): NgTheme | null {\n    try {\n      return localStorage.getItem(this.#config.storageKey) as NgTheme;\n    } catch (e) {\n      console.warn('[ngx-theme-stack] Could not read theme from localStorage.', e);\n      return null;\n    }\n  }\n\n  private saveTheme(theme: NgTheme): void {\n    try {\n      localStorage.setItem(this.#config.storageKey, theme);\n    } catch (e) {\n      console.warn('[ngx-theme-stack] Could not save theme to localStorage.', e);\n    }\n  }\n}\n","import { inject, Injectable } from '@angular/core';\nimport { CoreThemeService } from './core-theme.service';\n\n/**\n * Convenience service for cycling through themes in a fixed order.\n *\n * Default cycle: `'light'` → `'dark'` → `'system'` → `'light'` → ...\n *\n * Use this when you want to offer users a single button that rotates\n * through all available theme options.\n */\n@Injectable({ providedIn: 'root' })\nexport class ThemeCycleService {\n\n  readonly #core = inject(CoreThemeService);\n\n  /** List of all configured themes for cycling. Defaults to ['light', 'dark', 'system']. */\n  readonly #cycle = this.#core.availableThemes;\n\n  /** The theme explicitly selected by the user. May be `'system'`. */\n  readonly selectedTheme = this.#core.selectedTheme;\n\n  /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */\n  readonly userTheme = this.#core.userTheme;\n\n  /** Whether the currently applied theme is dark. */\n  readonly isDark = this.#core.isDark;\n\n  /** Whether the currently applied theme is light. */\n  readonly isLight = this.#core.isLight;\n\n  /**\n   * Advances to the next theme in the cycle.\n   *\n   * Cycle order is determined by the configured `themes` property in `NgConfig`.\n   *\n   * If the current theme is not found in the cycle (e.g. set externally),\n   * the cycle restarts from the first theme.\n   */\n  cycle(): void {\n    const current = this.#core.selectedTheme();\n    const index = this.#cycle.indexOf(current);\n    const next = this.#cycle[(index + 1) % this.#cycle.length];\n    this.#core.setTheme(next);\n  }\n}\n","import { inject, Injectable } from '@angular/core';\nimport { CoreThemeService } from './core-theme.service';\nimport { NgTheme } from './types';\n\n/**\n * Convenience service for selecting a theme from a list.\n *\n * Use this when you want to bind a `<select>` or a group of radio/tab\n * buttons to the full set of available themes.\n */\n@Injectable({ providedIn: 'root' })\nexport class ThemeSelectService {\n\n  readonly #core = inject(CoreThemeService);\n\n  /** List of all configured themes. Defaults to ['light', 'dark', 'system']. */\n  readonly availableThemes = this.#core.availableThemes;\n\n  /** The theme explicitly selected by the user. May be `'system'`. */\n  readonly selectedTheme = this.#core.selectedTheme;\n\n  /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */\n  readonly userTheme = this.#core.userTheme;\n\n  /** Whether the currently applied theme is dark. */\n  readonly isDark = this.#core.isDark;\n\n  /** Whether the currently applied theme is light. */\n  readonly isLight = this.#core.isLight;\n\n  /**\n   * Applies the given theme.\n   *\n   * @param theme - The theme to apply: `'dark'`, `'light'`, `'system'`, or custom.\n   * @throws If `theme` is not a valid theme according to library configuration.\n   */\n  select(theme: NgTheme): void {\n    this.#core.setTheme(theme);\n  }\n}\n","import { inject, Injectable } from '@angular/core';\nimport { CoreThemeService } from './core-theme.service';\n\n/**\n * Convenience service for toggling between `'dark'` and `'light'`.\n *\n * Use this when you only need a simple on/off switch and do not\n * need to manage `'system'` or cycle through themes.\n */\n@Injectable({ providedIn: 'root' })\nexport class ThemeToggleService {\n\n  readonly #core = inject(CoreThemeService);\n\n  /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */\n  readonly userTheme = this.#core.userTheme;\n\n  /** Whether the currently applied theme is dark. */\n  readonly isDark = this.#core.isDark;\n\n  /** Whether the currently applied theme is light. */\n  readonly isLight = this.#core.isLight;\n\n  /**\n   * Toggles between `'dark'` and `'light'`.\n   *\n   * If the selected theme is explicitly `'dark'`, switches to `'light'`.\n   * Otherwise (including `'system'`), switches to `'dark'`.\n   */\n  toggle(): void {\n    const next = this.#core.selectedTheme() === 'dark' ? 'light' : 'dark';\n    this.#core.setTheme(next);\n  }\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "ngx-theme-stack",
+  "version": "0.0.1",
+  "peerDependencies": {
+    "@angular/common": "^21.2.0",
+    "@angular/core": "^21.2.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "schematics": "./schematics/collection.json",
+  "module": "fesm2022/ngx-theme-stack.mjs",
+  "typings": "types/ngx-theme-stack.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/ngx-theme-stack.d.ts",
+      "default": "./fesm2022/ngx-theme-stack.mjs"
+    }
+  },
+  "type": "module"
+}

package/types/ngx-theme-stack.d.ts

@@ -0,0 +1,165 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken } from '@angular/core';
+import * as ngx_theme_stack from 'ngx-theme-stack';
+
+/** Built-in themes. All other values are considered custom themes. */
+declare const DEFAULT_THEMES: readonly ["light", "dark", "system"];
+/** String union with autocompletion for defaults + any string support for customization. */
+type NgTheme = (typeof DEFAULT_THEMES)[number] | (string & {});
+type NgSystemTheme = Exclude<NgTheme, 'system'>;
+type NgMode = 'attribute' | 'class' | 'both';
+interface NgConfig {
+    theme: NgTheme;
+    storageKey: string;
+    mode: NgMode;
+    themes: NgTheme[];
+}
+
+/**
+ * Core service for managing the application's color theme.
+ *
+ * Handles theme persistence, system preference detection, and DOM updates.
+ * Supports built-in themes ('dark', 'light', 'system') and custom extensions.
+ */
+declare class CoreThemeService {
+    #private;
+    /** List of available themes for Select/Cycle services. Defaults to ['light', 'dark', 'system']. */
+    readonly availableThemes: NgTheme[];
+    /** The theme explicitly selected by the user. May be `'system'`. */
+    readonly selectedTheme: _angular_core.Signal<NgTheme>;
+    /** Resolved theme applied to the DOM. Always `'dark'` or `'light'` (or custom) — never `'system'`. */
+    readonly userTheme: _angular_core.Signal<NgSystemTheme>;
+    /** Whether the currently applied theme is dark. */
+    readonly isDark: _angular_core.Signal<boolean>;
+    /** Whether the currently applied theme is light. */
+    readonly isLight: _angular_core.Signal<boolean>;
+    constructor();
+    /**
+     * Changes the active theme.
+     *
+     * Persists the choice explicitly so that switching e.g. from `'system'` to
+     * `'light'` is saved even when the resolved `userTheme` did not change
+     * (system preference was already `'light'`).
+     *
+     * @param theme - The theme to apply: `'dark'`, `'light'`, `'system'`, or a custom theme name.
+     * @throws If `theme` is not a valid theme according to library configuration.
+     */
+    setTheme(theme: NgTheme): void;
+    private resolveSystemPreference;
+    private resolveInitialTheme;
+    private startSystemThemeListener;
+    private stopSystemThemeListener;
+    private applyThemeToDOM;
+    private readStoredTheme;
+    private saveTheme;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CoreThemeService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<CoreThemeService>;
+}
+
+declare const DEFAULT_NG_CONFIG: {
+    theme: "system";
+    storageKey: string;
+    mode: "class";
+    themes: ("light" | "dark" | "system")[];
+};
+declare const NGX_THEME_STACK_CONFIG: InjectionToken<NgConfig>;
+/**
+ * Helper function to provide Theme Stack configuration.
+ */
+declare function provideThemeStack(config?: Partial<NgConfig>): {
+    provide: InjectionToken<NgConfig>;
+    useValue: {
+        theme: ngx_theme_stack.NgTheme;
+        storageKey: string;
+        mode: ngx_theme_stack.NgMode;
+        themes: ngx_theme_stack.NgTheme[];
+    };
+};
+
+/**
+ * Convenience service for cycling through themes in a fixed order.
+ *
+ * Default cycle: `'light'` → `'dark'` → `'system'` → `'light'` → ...
+ *
+ * Use this when you want to offer users a single button that rotates
+ * through all available theme options.
+ */
+declare class ThemeCycleService {
+    #private;
+    /** The theme explicitly selected by the user. May be `'system'`. */
+    readonly selectedTheme: _angular_core.Signal<ngx_theme_stack.NgTheme>;
+    /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */
+    readonly userTheme: _angular_core.Signal<ngx_theme_stack.NgSystemTheme>;
+    /** Whether the currently applied theme is dark. */
+    readonly isDark: _angular_core.Signal<boolean>;
+    /** Whether the currently applied theme is light. */
+    readonly isLight: _angular_core.Signal<boolean>;
+    /**
+     * Advances to the next theme in the cycle.
+     *
+     * Cycle order is determined by the configured `themes` property in `NgConfig`.
+     *
+     * If the current theme is not found in the cycle (e.g. set externally),
+     * the cycle restarts from the first theme.
+     */
+    cycle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThemeCycleService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ThemeCycleService>;
+}
+
+/**
+ * Convenience service for selecting a theme from a list.
+ *
+ * Use this when you want to bind a `<select>` or a group of radio/tab
+ * buttons to the full set of available themes.
+ */
+declare class ThemeSelectService {
+    #private;
+    /** List of all configured themes. Defaults to ['light', 'dark', 'system']. */
+    readonly availableThemes: NgTheme[];
+    /** The theme explicitly selected by the user. May be `'system'`. */
+    readonly selectedTheme: _angular_core.Signal<NgTheme>;
+    /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */
+    readonly userTheme: _angular_core.Signal<ngx_theme_stack.NgSystemTheme>;
+    /** Whether the currently applied theme is dark. */
+    readonly isDark: _angular_core.Signal<boolean>;
+    /** Whether the currently applied theme is light. */
+    readonly isLight: _angular_core.Signal<boolean>;
+    /**
+     * Applies the given theme.
+     *
+     * @param theme - The theme to apply: `'dark'`, `'light'`, `'system'`, or custom.
+     * @throws If `theme` is not a valid theme according to library configuration.
+     */
+    select(theme: NgTheme): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThemeSelectService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ThemeSelectService>;
+}
+
+/**
+ * Convenience service for toggling between `'dark'` and `'light'`.
+ *
+ * Use this when you only need a simple on/off switch and do not
+ * need to manage `'system'` or cycle through themes.
+ */
+declare class ThemeToggleService {
+    #private;
+    /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */
+    readonly userTheme: _angular_core.Signal<ngx_theme_stack.NgSystemTheme>;
+    /** Whether the currently applied theme is dark. */
+    readonly isDark: _angular_core.Signal<boolean>;
+    /** Whether the currently applied theme is light. */
+    readonly isLight: _angular_core.Signal<boolean>;
+    /**
+     * Toggles between `'dark'` and `'light'`.
+     *
+     * If the selected theme is explicitly `'dark'`, switches to `'light'`.
+     * Otherwise (including `'system'`), switches to `'dark'`.
+     */
+    toggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ThemeToggleService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ThemeToggleService>;
+}
+
+export { CoreThemeService, DEFAULT_NG_CONFIG, DEFAULT_THEMES, NGX_THEME_STACK_CONFIG, ThemeCycleService, ThemeSelectService, ThemeToggleService, provideThemeStack };
+export type { NgConfig, NgMode, NgSystemTheme, NgTheme };