ngx-theme-stack 1.0.0 → 2.0.0

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

@@ -2,17 +2,53 @@ 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. */
+/**
+ * Runtime list of built-in themes.
+ *
+ * Lives here (and not in config/index.ts) because it defines a type:
+ * config/index.ts already imports from types.ts, so placing DEFAULT_THEMES
+ * here avoids any circular dependency.
+ *
+ * ⚠ KEEP IN SYNC with the duplicate in:
+ * projects/ngx-theme-stack/schematics/ng-add/constants.ts → DEFAULT_THEMES
+ *
+ * Schematics compile to CommonJS and cannot import from this ESM file,
+ * so the values are intentionally duplicated. Change both at the same time.
+ */
 declare const DEFAULT_THEMES: readonly ["system", "light", "dark"];
-/** String union with autocompletion for defaults + any string support for customization. */
-type NgTheme = (typeof DEFAULT_THEMES)[number] | (string & {});
-type NgSystemTheme = Exclude<NgTheme, 'system'>;
+/** Literal union of built-in themes: `'system' | 'light' | 'dark'`. */
+type DefaultNgTheme = (typeof DEFAULT_THEMES)[number];
+/**
+ * Theme type.
+ *
+ * - **Without** `T`: open union — accepts any `string` with IDE autocomplete
+ *   hints for the built-in themes (`'system' | 'light' | 'dark'`).
+ * - **With** `T`: closed union — exactly `DefaultNgTheme | T`, enabling
+ *   full type-safety for custom theme sets.
+ *
+ * @example
+ * NgTheme            // 'system' | 'light' | 'dark' | (string & {})
+ * NgTheme<'sepia'>   // 'system' | 'light' | 'dark' | 'sepia'
+ */
+type NgTheme<T extends string = string & {}> = DefaultNgTheme | T;
+/**
+ * Resolved theme — always `'light'` or `'dark'`, never `'system'`.
+ * Represents the value that comes from `matchMedia`, not user selection.
+ */
+type NgSystemTheme = Exclude<DefaultNgTheme, 'system'>;
 type NgMode = 'attribute' | 'class' | 'both';
-interface NgConfig {
-    theme: NgTheme;
+/**
+ * Library configuration.
+ *
+ * @typeParam T - Custom theme literals. Defaults to open `string`, preserving
+ * backwards compatibility. Pass specific literals (e.g. `'sepia' | 'ocean'`)
+ * via {@link provideThemeStack} to get a closed, type-safe theme union.
+ */
+interface NgConfig<T extends string = string & {}> {
+    defaultTheme: NgTheme<T>;
     storageKey: string;
     mode: NgMode;
-    themes: NgTheme[];
+    themes: NgTheme<T>[];
 }
 
 /**
@@ -23,22 +59,42 @@ interface NgConfig {
  */
 declare class CoreThemeService {
     #private;
-    /** List of available themes for Select/Cycle services. Defaults to ['light', 'dark', 'system']. */
-    readonly availableThemes: NgTheme[];
+    /** List of available themes for Select/Cycle services. Defaults to ['system', 'light', 'dark']. */
+    readonly availableThemes: string[];
     /** 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>;
+    readonly resolvedTheme: _angular_core.Signal<(string & {}) | 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>;
+    /** Whether the currently applied theme is system. */
+    readonly isSystem: _angular_core.Signal<boolean>;
+    /**
+     * Whether the service has completed client-side initialization.
+     *
+     * `false` during SSR and on the very first render pass. Becomes `true`
+     * immediately after the first browser render, once the real persisted theme
+     * has been read from `localStorage`.
+     *
+     * Use this to guard any template logic that depends on `selectedTheme` or
+     * `resolvedTheme` to avoid an SSR hydration-mismatch flash: the server
+     * renders the default (`'system'`) while the browser may have a different
+     * value stored.
+     *
+     * @example
+     * ```html
+     * {{ themeService.isHydrated() ? selectedTheme() : '—' }}
+     * ```
+     */
+    readonly isHydrated: _angular_core.WritableSignal<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
+     * `'light'` is saved even when the resolved theme did not change
      * (system preference was already `'light'`).
      *
      * @param theme - The theme to apply: `'dark'`, `'light'`, `'system'`, or a custom theme name.
@@ -53,6 +109,7 @@ declare class CoreThemeService {
     private applyThemeAttribute;
     private applyThemeClasses;
     private applyColorSchemeHint;
+    private captureAntiFlashClass;
     private readStoredTheme;
     private saveTheme;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<CoreThemeService, never>;
@@ -62,36 +119,69 @@ declare class CoreThemeService {
 /**
  * ⚠ ATTENTION: SHARED CONFIGURATION VALUES
  *
- * These values MUST match the schematic defaults in:
- * projects/ngx-theme-stack/schematics/ng-add/index.ts
+ * These defaults MUST match the schematic defaults in:
+ * projects/ngx-theme-stack/schematics/ng-add/constants.ts → DEFAULTS
  *
- * If you change any of these, you MUST also update the schematic's DEFAULTS
- * constant so 'ng add' continues to provide correct hints and clean code.
+ * Schematics compile to CommonJS and cannot import from this ESM file,
+ * so the values are intentionally duplicated. Change both at the same time.
+ *
+ * If you change defaults here, also update:
+ * schematics/ng-add/constants.ts → DEFAULTS + DEFAULT_THEMES
  */
 declare const DEFAULT_NG_CONFIG: {
-    theme: "system";
+    defaultTheme: "system";
     storageKey: string;
     mode: "class";
     themes: ("system" | "light" | "dark")[];
 };
-declare const NGX_THEME_STACK_CONFIG: InjectionToken<NgConfig>;
+declare const NGX_THEME_STACK_CONFIG: InjectionToken<NgConfig<string>>;
 /**
- * Helper function to provide Theme Stack configuration.
+ * Provides Theme Stack configuration to Angular's DI system.
+ *
+ * Custom `themes` are **merged** with the built-in defaults
+ * (`'light'`, `'dark'`, `'system'`), so you never lose the base themes.
+ *
+ * The type parameter `T` is **inferred automatically** from the `themes` array
+ * when passed as a `const` — no need to specify it manually.
+ *
+ * @typeParam T - Custom theme string literals, inferred from the `themes` option.
+ *
+ * @param config - Optional partial configuration. Omitted fields fall back to
+ *   {@link DEFAULT_NG_CONFIG}.
+ *
+ * @throws {@link NgxThemeStackError}
+ *   - If any entry in `themes` is an empty or whitespace-only string.
+ *   - If `defaultTheme` is not present in the resolved (merged) themes array.
+ *   - If `storageKey` is an empty or whitespace-only string.
+ *
+ * @example
+ * // Default — uses built-in themes and sensible defaults
+ * provideThemeStack()
+ *
+ * @example
+ * // Closed union: TypeScript infers 'sepia' | 'ocean' from the array
+ * provideThemeStack({
+ *   themes: ['sepia', 'ocean'] as const,
+ *   defaultTheme: 'sepia',   // ✅ in resolved themes
+ *   // defaultTheme: 'nope', // ❌ throws NgxThemeStackError at runtime
+ * })
+ *
+ * @example
+ * // Custom storage key and mode
+ * provideThemeStack({
+ *   storageKey: 'my-app-theme',
+ *   mode: 'class',
+ * })
  */
-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[];
-    };
+declare function provideThemeStack<const T extends string = DefaultNgTheme>(config?: Partial<NgConfig<T>>): {
+    provide: InjectionToken<NgConfig<string>>;
+    useValue: NgConfig<string>;
 };
 
 /**
  * Convenience service for cycling through themes in a fixed order.
  *
- * Default cycle: `'light'` → `'dark'` → `'system'` → `'light'` → ...
+ * Default cycle: `'system'` → `'light'` → `'dark'` → `'system'` → ...
  *
  * Use this when you want to offer users a single button that rotates
  * through all available theme options.
@@ -101,11 +191,18 @@ declare class ThemeCycleService {
     /** 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>;
+    readonly resolvedTheme: _angular_core.Signal<(string & {}) | 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>;
+    /** Whether the currently applied theme is system. */
+    readonly isSystem: _angular_core.Signal<boolean>;
+    /**
+     * Whether the service has completed client-side initialization.
+     * `false` during SSR. Becomes `true` after the first browser render.
+     */
+    readonly isHydrated: _angular_core.Signal<boolean>;
     /**
      * Advances to the next theme in the cycle.
      *
@@ -128,15 +225,22 @@ declare class ThemeCycleService {
 declare class ThemeSelectService {
     #private;
     /** List of all configured themes. Defaults to ['light', 'dark', 'system']. */
-    readonly availableThemes: NgTheme[];
+    readonly availableThemes: string[];
     /** 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>;
+    readonly resolvedTheme: _angular_core.Signal<(string & {}) | 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>;
+    /** Whether the currently applied theme is system. */
+    readonly isSystem: _angular_core.Signal<boolean>;
+    /**
+     * Whether the service has completed client-side initialization.
+     * `false` during SSR. Becomes `true` after the first browser render.
+     */
+    readonly isHydrated: _angular_core.Signal<boolean>;
     /**
      * Applies the given theme.
      *
@@ -157,11 +261,21 @@ declare class ThemeSelectService {
 declare class ThemeToggleService {
     #private;
     /** Resolved theme applied to the DOM. Always concrete — never `'system'`. */
-    readonly userTheme: _angular_core.Signal<ngx_theme_stack.NgSystemTheme>;
+    readonly resolvedTheme: _angular_core.Signal<(string & {}) | ngx_theme_stack.NgSystemTheme>;
+    readonly selectedTheme: _angular_core.Signal<ngx_theme_stack.NgTheme>;
     /** 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>;
+    /** Whether the currently applied theme is system. */
+    readonly isSystem: _angular_core.Signal<boolean>;
+    /**
+     * Whether the service has completed client-side initialization.
+     * `false` during SSR. Becomes `true` after the first browser render.
+     * Guard any template logic that shows `selectedTheme` or `resolvedTheme`
+     * behind this signal to avoid a hydration-mismatch flash.
+     */
+    readonly isHydrated: _angular_core.Signal<boolean>;
     /**
      * Toggles between `'dark'` and `'light'`.
      *
@@ -173,5 +287,26 @@ declare class ThemeToggleService {
     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 };
+/**
+ * Base error class for `ngx-theme-stack`.
+ *
+ * Thrown when the library configuration is invalid.
+ * Consumers can use `instanceof NgxThemeStackError` to catch only
+ * errors originating from this library.
+ *
+ * @example
+ * try {
+ *   bootstrapApplication(AppComponent, appConfig);
+ * } catch (e) {
+ *   if (e instanceof NgxThemeStackError) {
+ *     console.error('Bad ngx-theme-stack config:', e.message);
+ *   }
+ * }
+ */
+declare class NgxThemeStackError extends Error {
+    readonly name = "NgxThemeStackError";
+    constructor(message: string);
+}
+
+export { CoreThemeService, DEFAULT_NG_CONFIG, DEFAULT_THEMES, NGX_THEME_STACK_CONFIG, NgxThemeStackError, ThemeCycleService, ThemeSelectService, ThemeToggleService, provideThemeStack };
+export type { DefaultNgTheme, NgConfig, NgMode, NgSystemTheme, NgTheme };