@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/utils/color.js

@@ -1,21 +1,76 @@
 /**
- * Utilidades de color para generar esquemas compatibles con Material Design 3.
- * Basado en @material/material-color-utilities.
+ * @file utils/color.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+/**
+ * @module color
+ *
+ * Color utilities for generating and applying Material Design 3–compliant
+ * dynamic color schemes.
+ *
+ * This module wraps `@material/material-color-utilities` to expose a
+ * simplified, opinionated API that covers the full Moni theming pipeline:
+ *
+ *  1. Convert a user-supplied "seed" hex color to the HCT color space.
+ *  2. Generate a complete 27-role `ColorScheme` via `SchemeTonalSpot`.
+ *  3. Apply the scheme to the document root as CSS custom properties under
+ *     three namespaces (`--md-sys-color-*`, `--moni-*`, and bare `--*`)
+ *     so any component or stylesheet can consume the tokens.
+ *
+ * **Contrast levels** map to the MD3 contrast spec:
+ *  - `standard` → 0.0 (WCAG AA baseline)
+ *  - `medium`   → 0.5 (enhanced readability)
+ *  - `high`     → 1.0 (WCAG AAA, maximum legibility)
+ *
+ * @see https://m3.material.io/styles/color/dynamic-color/overview
+ * @see https://github.com/material-foundation/material-color-utilities
  */
 import { SchemeTonalSpot, Hct, argbFromHex, hexFromArgb } from '@material/material-color-utilities';
+// ─────────────────────────────────────────────────────────────────────────────
+// Color conversion utilities
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Converts a 6-digit hex color string to the HSL color model.
+ *
+ * Normalizes the input (strips optional `#`), parses each 8-bit RGB channel
+ * into a [0, 1] float, then applies the standard RGB→HSL algorithm:
+ *
+ *  - Lightness  = (max + min) / 2
+ *  - Saturation = delta / (2 − max − min)  if L > 0.5
+ *               = delta / (max + min)       otherwise
+ *  - Hue        = derived from which channel is the maximum
+ *
+ * When the color is achromatic (r = g = b), hue and saturation are both 0.
+ *
+ * @param hex - A 6-digit hex color, with or without the `#` prefix.
+ *              Examples: `'#4f46e5'`, `'4f46e5'`.
+ * @returns An {@link HSL} object where `h` ∈ [0, 360), `s` ∈ [0, 100], `l` ∈ [0, 100].
+ *
+ * @example
+ * hexToHsl('#ff0000') // { h: 0,   s: 100, l: 50 }
+ * hexToHsl('#ffffff') // { h: 0,   s: 0,   l: 100 }
+ * hexToHsl('#4f46e5') // { h: 243, s: 73,  l: 59 }  (approx)
+ */
 export function hexToHsl(hex) {
     const normalized = hex.replace('#', '');
+    // Parse each 8-bit channel and normalize to [0, 1].
     const r = parseInt(normalized.substring(0, 2), 16) / 255;
     const g = parseInt(normalized.substring(2, 4), 16) / 255;
     const b = parseInt(normalized.substring(4, 6), 16) / 255;
     const max = Math.max(r, g, b);
     const min = Math.min(r, g, b);
+    // Initialize hue and saturation; they stay 0 for achromatic colors.
     let h = 0;
     let s = 0;
+    // Lightness is always the midpoint between brightest and darkest channel.
     const l = (max + min) / 2;
     if (max !== min) {
         const d = max - min;
+        // Saturation formula differs above and below the 50% lightness threshold.
         s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+        // Hue is determined by which channel dominates.
         switch (max) {
             case r:
                 h = (g - b) / d + (g < b ? 6 : 0);
@@ -27,15 +82,40 @@ export function hexToHsl(hex) {
                 h = (r - g) / d + 4;
                 break;
         }
+        // Normalize hue from a 0–6 sector index to degrees [0, 360).
         h /= 6;
     }
     return { h: h * 360, s: s * 100, l: l * 100 };
 }
+/**
+ * Converts an HSL color to a 6-digit hex string.
+ *
+ * Uses the CSS Color Level 4 reference algorithm. Internally computes R, G,
+ * and B via a piecewise function `f(n)` that maps chroma sector offsets to
+ * individual channel values.
+ *
+ * @param hsl - An {@link HSL} object where `h` ∈ [0, 360), `s` ∈ [0, 100], `l` ∈ [0, 100].
+ * @returns A lowercase 7-character hex string including the `#` prefix (e.g. `'#4f46e5'`).
+ *
+ * @example
+ * hslToHex({ h: 0, s: 100, l: 50 })   // '#ff0000'
+ * hslToHex({ h: 0, s: 0,   l: 100 }) // '#ffffff'
+ */
 export function hslToHex({ h, s, l }) {
+    // Normalize percentages to [0, 1] for the algorithm.
     s /= 100;
     l /= 100;
+    /**
+     * Sector index helper. Maps the offset `n` (0, 4, 8) to a position within
+     * the 12-sector hue wheel (each sector = 30°).
+     */
     const k = (n) => (n + h / 30) % 12;
+    /** Chroma magnitude: 0 at lightness extremes, max at L=0.5. */
     const a = s * Math.min(l, 1 - l);
+    /**
+     * Per-channel computation. Returns a 2-character hex string for the
+     * channel corresponding to sector offset `n` (0=R, 8=G, 4=B).
+     */
     const f = (n) => {
         const color = l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
         return Math.round(color * 255)
@@ -44,10 +124,52 @@ export function hslToHex({ h, s, l }) {
     };
     return `#${f(0)}${f(8)}${f(4)}`;
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Scheme generation
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Generates a complete Material Design 3 color scheme from a seed hex color.
+ *
+ * Uses `SchemeTonalSpot` — the standard M3 dynamic color algorithm — which
+ * derives all 27 color roles from a single source hue while respecting the
+ * target lightness/contrast requirements for each role.
+ *
+ * **Algorithm pipeline:**
+ * 1. Parse `seedHex` → ARGB integer via `argbFromHex`.
+ * 2. Convert ARGB → HCT (Hue–Chroma–Tone) color space.
+ * 3. Construct a `SchemeTonalSpot` with the requested mode and contrast level.
+ * 4. Extract each scheme role via `hexFromArgb` and build the {@link ColorScheme}.
+ *
+ * @param seedHex   - The source/brand color as a hex string. The `#` prefix
+ *                    is optional (e.g. `'#4f46e5'` or `'4f46e5'`).
+ * @param mode      - Color scheme polarity. `'light'` produces light backgrounds
+ *                    with dark text; `'dark'` inverts the tone mapping.
+ *                    Defaults to `'light'`.
+ * @param contrast  - WCAG contrast enhancement level. Defaults to `'standard'`.
+ *
+ * @returns A fully populated {@link ColorScheme} where every value is a
+ *          lowercase 7-character hex string (e.g. `'#6750a4'`).
+ *
+ * @example
+ * // Generate a standard light scheme from an indigo seed.
+ * const scheme = generateScheme('#4f46e5');
+ * console.log(scheme.primary);           // e.g. '#5046e4'
+ * console.log(scheme.primaryContainer);  // e.g. '#e9e7ff'
+ *
+ * @example
+ * // High-contrast dark scheme.
+ * const darkHC = generateScheme('#4f46e5', 'dark', 'high');
+ */
 export function generateScheme(seedHex, mode = 'light', contrast = 'standard') {
+    // Ensure the seed always has a leading '#' for argbFromHex.
     const seed = seedHex.startsWith('#') ? seedHex : `#${seedHex}`;
+    // Step 1: Convert hex → ARGB integer.
     const argb = argbFromHex(seed);
+    // Step 2: Convert ARGB → HCT. HCT is the perceptual color space used
+    // internally by the MD3 algorithm; it preserves human color perception
+    // better than RGB or HSL for palette generation.
     const hct = Hct.fromInt(argb);
+    // Step 3: Map the ContrastLevel union to a numeric value expected by the SDK.
     let contrastLevel = 0.0;
     if (contrast === 'medium') {
         contrastLevel = 0.5;
@@ -55,7 +177,10 @@ export function generateScheme(seedHex, mode = 'light', contrast = 'standard') {
     else if (contrast === 'high') {
         contrastLevel = 1.0;
     }
+    // Step 4: Build the tonal-spot scheme. isDark=true shifts every tone value
+    // to keep roles readable on dark backgrounds.
     const scheme = new SchemeTonalSpot(hct, mode === 'dark', contrastLevel);
+    // Step 5: Extract every color role from the scheme and convert back to hex.
     return {
         primary: hexFromArgb(scheme.primary),
         onPrimary: hexFromArgb(scheme.onPrimary),
@@ -92,16 +217,69 @@ export function generateScheme(seedHex, mode = 'light', contrast = 'standard') {
         shadow: hexFromArgb(scheme.shadow)
     };
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// DOM integration
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Writes a {@link ColorScheme} to the document root as CSS custom properties.
+ *
+ * For each color role in the scheme, **three aliases** are set on
+ * `document.documentElement` so every context can consume the tokens:
+ *
+ * | Namespace prefix     | Example                          | Consumer              |
+ * |----------------------|----------------------------------|-----------------------|
+ * | `--md-sys-color-`    | `--md-sys-color-primary`         | MD3 spec / third-party|
+ * | `--moni-`            | `--moni-primary`                 | Moni components       |
+ * | `--` (bare)          | `--primary`                      | BeerCSS / legacy      |
+ *
+ * camelCase role names are converted to kebab-case automatically
+ * (e.g. `primaryContainer` → `primary-container`).
+ *
+ * Additionally sets `data-theme="light|dark"` on `<html>` so CSS can use
+ * `:root[data-theme='dark']` selectors for any additional overrides.
+ *
+ * **Side effects:** Mutates `doc.documentElement.style` and attributes.
+ * This function should only be called in browser environments.
+ *
+ * @param scheme - The color scheme to apply, as produced by {@link generateScheme}.
+ * @param mode   - The resolved mode (`'light'` or `'dark'`); written to `data-theme`.
+ * @param doc    - The `Document` to target. Pass `document` in normal usage;
+ *                 accepts a custom document for iframe or SSR scenarios.
+ *
+ * @example
+ * const scheme = generateScheme('#4f46e5', 'dark');
+ * applySchemeToDocument(scheme, 'dark', document);
+ * // <html data-theme="dark" style="--md-sys-color-primary: #...; --moni-primary: #...; --primary: #...">
+ */
 export function applySchemeToDocument(scheme, mode, doc) {
     const root = doc.documentElement;
+    // MD3 canonical namespace prefix.
     const prefix = '--md-sys-color-';
     for (const [key, value] of Object.entries(scheme)) {
+        // Convert camelCase → kebab-case (e.g. 'onPrimary' → 'on-primary').
         const kebab = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
-        root.style.setProperty(`${prefix}${kebab}`, value);
-        root.style.setProperty(`--${kebab}`, value);
+        // Set all three namespace aliases simultaneously.
+        root.style.setProperty(`${prefix}${kebab}`, value); // MD3 spec namespace
+        root.style.setProperty(`--moni-${kebab}`, value); // Moni namespace
+        root.style.setProperty(`--${kebab}`, value); // Bare/BeerCSS namespace
     }
+    // Mark the document with the resolved mode for CSS `[data-theme]` selectors.
     root.setAttribute('data-theme', mode);
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Defaults
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Returns the default seed color used by the Moni design system.
+ *
+ * The default seed is a deep indigo (`#4f46e5`) that maps to a material-spec
+ * primary hue of roughly 243°. It was chosen because it:
+ *  - Generates accessible contrast ratios in both light and dark modes.
+ *  - Feels brand-neutral enough to serve as a placeholder before users
+ *    customize their color.
+ *
+ * @returns The default seed hex string `'#4f46e5'`.
+ */
 export function getDefaultSeed() {
     return '#4f46e5';
 }

package/dist/utils/theme.svelte.d.ts

@@ -1,45 +1,348 @@
 /**
- * ThemeEngine — gestión reactiva del tema visual de Moni.
- * Soporta: modo claro/oscuro, color semilla, densidad, radio, fuente y grain.
+ * @file utils/theme.svelte.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+/**
+ * @module theme
+ *
+ * Reactive theme engine for the Moni design system.
+ *
+ * `ThemeEngine` is the single source of truth for all visual customization
+ * options exposed to users: color seed, light/dark mode, contrast, density,
+ * border radius, typography, and motion reduction.
+ *
+ * **Architecture:**
+ * - The engine is a **singleton** accessed via {@link getThemeEngine}. This
+ *   ensures that all app-level components share the same reactive state.
+ * - Settings are persisted to `localStorage` under {@link STORAGE_KEY} so
+ *   they survive page reloads.
+ * - The class uses Svelte 5 `$state` runes for reactivity. Consumers in
+ *   Svelte components can read `engine.resolvedMode` or `engine.scheme`
+ *   reactively without any additional subscription setup.
+ * - In SSR or non-browser environments, all DOM-side effects are skipped
+ *   gracefully via `typeof window === 'undefined'` / `typeof document === 'undefined'` guards.
+ *
+ * **CSS custom properties set by {@link ThemeEngine.apply}:**
+ * - `--moni-spacing-density` — numeric multiplier (e.g. 0.75, 1.0, 1.25, 1.6)
+ * - `--moni-radius-base`     — border-radius base value (e.g. `'0px'`, `'12px'`, `'20px'`)
+ * - `--moni-font-sans`       — font-family stack for body text
+ * - `--moni-font-title`      — font-family stack for headings
+ * - `--moni-grain-opacity`   — CSS opacity for the texture overlay (0–1)
+ * - `moni-reduce-motion`     — class toggled on `<html>` when reduce-motion is active
+ *
+ * @example
+ * ```ts
+ * // In a Svelte component or framework-agnostic module:
+ * import { getThemeEngine } from '@moni-labs/moni-ui';
+ *
+ * const theme = getThemeEngine();
+ * theme.setSeedColor('#4f46e5');
+ * theme.setMode('dark');
+ * ```
  */
 import { type ColorScheme, type ContrastLevel } from './color.js';
+/**
+ * Color scheme polarity / light-dark preference.
+ *
+ * - `'light'`  — Always apply the light palette regardless of OS setting.
+ * - `'dark'`   — Always apply the dark palette regardless of OS setting.
+ * - `'system'` — Follow `prefers-color-scheme` media query. Updates
+ *                automatically when the user changes their OS preference.
+ */
 export type ThemeMode = 'light' | 'dark' | 'system';
+/**
+ * Spacing density scale.
+ *
+ * Controls the `--moni-spacing-density` custom property, which scales padding,
+ * gap, and height values throughout the component library.
+ *
+ * | Value         | Multiplier | Use case                               |
+ * |---------------|------------|----------------------------------------|
+ * | `'compact'`   | 0.75       | Dense data tables, admin dashboards    |
+ * | `'default'`   | 1.0        | Standard consumer UIs                  |
+ * | `'comfortable'`| 1.25      | Touch-friendly interfaces              |
+ * | `'spacious'`  | 1.6        | Large-display / presentation screens   |
+ */
 export type ThemeDensity = 'compact' | 'default' | 'comfortable' | 'spacious';
+/**
+ * Global border-radius style.
+ *
+ * Sets the `--moni-radius-base` custom property used as the base radius for
+ * cards, dialogs, sheets, and other container elements.
+ *
+ * - `'sharp'`   → `0px`  — No rounding; geometric aesthetic.
+ * - `'default'` → `12px` — Moderate rounding per M3 spec (medium shape).
+ * - `'rounded'` → `20px` — Expressive full-curve shapes; default for Moni brand.
+ */
 export type ThemeRadius = 'sharp' | 'default' | 'rounded';
+/**
+ * Available typeface families for body and title text.
+ *
+ * Each value maps to a specific font-family stack in {@link fontFamily}.
+ *
+ * - `'geist'`      — Geist (Vercel), system-ui fallback. Default body font.
+ * - `'inter'`      — Inter, system-ui fallback. Classic UI sans-serif.
+ * - `'roboto'`     — Roboto, system-ui fallback. Material Design reference font.
+ * - `'instrument'` — Instrument Serif, Georgia fallback. Editorial serif for titles.
+ */
 export type ThemeFont = 'geist' | 'inter' | 'roboto' | 'instrument';
+/**
+ * Complete snapshot of all user-configurable theme preferences.
+ *
+ * This interface is serialized to JSON and stored in `localStorage`. Adding
+ * new optional fields is backward-compatible; the {@link parseSettings}
+ * function merges with {@link defaults} to fill any missing keys.
+ */
 export interface ThemeSettings {
+    /** Light/dark/system color scheme preference. */
     mode: ThemeMode;
+    /** Seed hex color used to generate the full color scheme. */
     seedColor: string;
+    /** WCAG contrast enhancement level for generated colors. */
     contrast: ContrastLevel;
+    /** Component spacing density multiplier. */
     density: ThemeDensity;
+    /** Global border-radius style for containers. */
     radius: ThemeRadius;
+    /** Typeface for body and UI text. */
     font: ThemeFont;
+    /** Typeface for display, headline, and title text. */
     titleFont: ThemeFont;
+    /** Opacity of the film-grain texture overlay (0–1). `0` disables the grain. */
     grainOpacity: number;
+    /** When `true`, disables non-essential CSS transitions and animations. */
     reduceMotion: boolean;
 }
+/**
+ * Reactive singleton that orchestrates the full Moni visual theme.
+ *
+ * `ThemeEngine` is responsible for:
+ *  1. Loading persisted settings from `localStorage` on construction.
+ *  2. Listening to OS `prefers-color-scheme` changes when mode is `'system'`.
+ *  3. Generating the full 27-role `ColorScheme` from the current seed color.
+ *  4. Writing all CSS custom properties to the document root.
+ *  5. Persisting settings to `localStorage` on every user-initiated change.
+ *
+ * **Reactivity:** Public fields `settings`, `resolvedMode`, and `scheme` are
+ * Svelte 5 `$state` runes. Any Svelte template reading these fields will
+ * automatically re-render when they change.
+ *
+ * **Singleton pattern:** Do not instantiate this class directly. Always use
+ * {@link getThemeEngine}, which returns a module-level singleton and ensures
+ * exactly one engine exists per page lifecycle.
+ *
+ * **SSR compatibility:** The constructor is safe to call in a server context —
+ * all DOM/window access is guarded and skipped when unavailable.
+ *
+ * @example
+ * ```ts
+ * import { getThemeEngine } from '@moni-labs/moni-ui';
+ *
+ * const theme = getThemeEngine();
+ *
+ * // Change the seed color — triggers scheme regeneration and DOM update.
+ * theme.setSeedColor('#e91e63');
+ *
+ * // Read the current resolved scheme in a framework-agnostic way.
+ * console.log(theme.scheme.primary);
+ *
+ * // Reset to factory defaults.
+ * theme.reset();
+ * ```
+ */
 export declare class ThemeEngine {
+    /**
+     * The complete set of current user preferences.
+     *
+     * Mutate via the setter methods (e.g. `setMode`, `setSeedColor`) rather
+     * than directly, to ensure DOM updates and persistence are triggered.
+     */
     settings: ThemeSettings;
+    /**
+     * The resolved light/dark mode after applying the `'system'` logic.
+     *
+     * Always either `'light'` or `'dark'` — never `'system'`. Use this value
+     * for icon toggling, conditional rendering, and `aria-*` attributes.
+     */
     resolvedMode: "light" | "dark";
+    /**
+     * The currently active 27-role color scheme, derived from `settings.seedColor`,
+     * `resolvedMode`, and `settings.contrast`.
+     *
+     * Reactive: re-assigned every time {@link apply} runs.
+     */
     scheme: ColorScheme;
+    /**
+     * The OS `prefers-color-scheme` media query list.
+     * Used to listen for system-level dark mode changes when mode is `'system'`.
+     * `null` in SSR or when `window` is unavailable.
+     */
     private mediaQuery;
+    /**
+     * Guard flag to prevent attaching duplicate `'change'` listeners to
+     * {@link mediaQuery} if `bindSystem` is called more than once.
+     */
     private bound;
+    /**
+     * Initializes the engine.
+     *
+     * In browser environments:
+     *  1. Loads and merges stored settings from `localStorage`.
+     *  2. Captures the `prefers-color-scheme` media query.
+     *  3. Attaches a `'change'` listener to react to OS preference updates.
+     *  4. Runs the first {@link apply} pass to paint the document immediately.
+     *
+     * In SSR environments, the constructor is a no-op.
+     */
     constructor();
+    /**
+     * Attaches a listener to the OS color-scheme media query.
+     *
+     * Calls {@link apply} whenever the OS switches between light and dark mode,
+     * but only when `settings.mode === 'system'` — the effective mode check
+     * inside `apply` handles the conditional logic.
+     *
+     * Idempotent: calling this method multiple times is safe; the `bound` flag
+     * ensures only one listener is ever attached.
+     */
     private bindSystem;
+    /**
+     * Resolves the effective polarity (`'light'` or `'dark'`) from `settings.mode`.
+     *
+     * When mode is `'system'`, defers to {@link getSystemMode} which reads the
+     * OS media query. Otherwise returns the explicit mode directly.
+     *
+     * @returns `'light'` or `'dark'`.
+     */
     private getEffectiveMode;
+    /**
+     * Regenerates the color scheme and applies all theme tokens to the document.
+     *
+     * This is the central "render" method of the engine. It:
+     *  1. Resolves the effective mode (`'light'` | `'dark'`).
+     *  2. Generates a fresh {@link ColorScheme} from the current seed and contrast.
+     *  3. Writes all 81 CSS custom properties (3 namespaces × 27 roles) to `<html>`.
+     *  4. Sets `--moni-spacing-density`, `--moni-radius-base`, `--moni-font-sans`,
+     *     `--moni-font-title`, and `--moni-grain-opacity`.
+     *  5. Toggles the `moni-reduce-motion` class on `<html>`.
+     *
+     * **Side effects:** Mutates `document.documentElement.style` and `classList`.
+     * No-op in SSR (`typeof document === 'undefined'`).
+     */
     apply(): void;
+    /**
+     * Persists the current {@link settings} to `localStorage` and re-applies the theme.
+     *
+     * Called internally by all setter methods after mutating `settings`.
+     * No-op when `localStorage` is unavailable (SSR, private browsing, quota exceeded).
+     */
     persist(): void;
+    /**
+     * Updates the color scheme polarity.
+     *
+     * @param mode - `'light'`, `'dark'`, or `'system'` (follows OS preference).
+     */
     setMode(mode: ThemeMode): void;
+    /**
+     * Updates the seed color used to generate the full color scheme.
+     *
+     * Automatically prepends `#` if the value doesn't already have one,
+     * ensuring the stored value is always a valid 7-character hex string.
+     *
+     * @param color - A hex color string, with or without the `#` prefix
+     *                (e.g. `'#4f46e5'` or `'4f46e5'`).
+     */
     setSeedColor(color: string): void;
+    /**
+     * Updates the WCAG contrast enhancement level for the generated palette.
+     *
+     * @param contrast - `'standard'` (AA), `'medium'` (enhanced), or `'high'` (AAA).
+     */
     setContrast(contrast: ContrastLevel): void;
+    /**
+     * Updates the spacing density multiplier.
+     *
+     * @param density - `'compact'`, `'default'`, `'comfortable'`, or `'spacious'`.
+     */
     setDensity(density: ThemeDensity): void;
+    /**
+     * Updates the global border-radius style.
+     *
+     * @param radius - `'sharp'` (0px), `'default'` (12px), or `'rounded'` (20px).
+     */
     setRadius(radius: ThemeRadius): void;
+    /**
+     * Updates the body/UI typeface.
+     *
+     * @param font - One of `'geist'` | `'inter'` | `'roboto'` | `'instrument'`.
+     */
     setFont(font: ThemeFont): void;
+    /**
+     * Updates the display/title typeface.
+     *
+     * @param font - One of `'geist'` | `'inter'` | `'roboto'` | `'instrument'`.
+     */
     setTitleFont(font: ThemeFont): void;
+    /**
+     * Updates the grain texture opacity.
+     *
+     * The value is clamped to [0, 1] before storing. Setting to `0` effectively
+     * disables the grain overlay without removing the element from the DOM.
+     *
+     * @param opacity - A number in the range [0, 1].
+     */
     setGrainOpacity(opacity: number): void;
+    /**
+     * Enables or disables user-initiated motion reduction.
+     *
+     * When `true`, the `moni-reduce-motion` class is added to `<html>`, which
+     * CSS components use to disable non-essential transitions and animations.
+     * This is separate from `prefers-reduced-motion` (OS-level) and allows
+     * users to opt in without changing their OS settings.
+     *
+     * @param reduce - `true` to disable motion, `false` to restore it.
+     */
     setReduceMotion(reduce: boolean): void;
+    /**
+     * Resets all settings to factory defaults and re-applies the theme.
+     *
+     * The reset is also persisted to `localStorage` so subsequent page loads
+     * start from defaults rather than the old stored values.
+     */
     reset(): void;
 }
+/**
+ * Returns the module-level {@link ThemeEngine} singleton, creating it on first call.
+ *
+ * This is the **recommended** entry point for all consumers. Calling this
+ * function multiple times always returns the same instance.
+ *
+ * @returns The shared `ThemeEngine` instance.
+ *
+ * @example
+ * ```ts
+ * import { getThemeEngine } from '@moni-labs/moni-ui';
+ *
+ * const theme = getThemeEngine();
+ * theme.setMode('dark');
+ * ```
+ */
 export declare function getThemeEngine(): ThemeEngine;
+/**
+ * Destroys the module-level singleton, forcing the next call to
+ * {@link getThemeEngine} to create a fresh instance.
+ *
+ * **Intended for test isolation only.** Do not call this in application code,
+ * as it will cause components sharing the singleton to lose their reference.
+ *
+ * @example
+ * ```ts
+ * afterEach(() => {
+ *   resetThemeEngine(); // Start each test with a clean engine.
+ * });
+ * ```
+ */
 export declare function resetThemeEngine(): void;
 //# sourceMappingURL=theme.svelte.d.ts.map

package/dist/utils/theme.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme.svelte.d.ts","sourceRoot":"","sources":["../../src/utils/theme.svelte.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAyD,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAEzH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AACpD,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAC9E,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAC1D,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;CACtB;AAoED,qBAAa,WAAW;IACvB,QAAQ,gBAA0C;IAClD,YAAY,mBAAqC;IACjD,MAAM,cAAuF;IAC7F,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,KAAK,CAAS;;IAWtB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,gBAAgB;IAKxB,KAAK;IAqBL,OAAO;IAOP,OAAO,CAAC,IAAI,EAAE,SAAS;IAKvB,YAAY,CAAC,KAAK,EAAE,MAAM;IAK1B,WAAW,CAAC,QAAQ,EAAE,aAAa;IAKnC,UAAU,CAAC,OAAO,EAAE,YAAY;IAKhC,SAAS,CAAC,MAAM,EAAE,WAAW;IAK7B,OAAO,CAAC,IAAI,EAAE,SAAS;IAKvB,YAAY,CAAC,IAAI,EAAE,SAAS;IAK5B,eAAe,CAAC,OAAO,EAAE,MAAM;IAK/B,eAAe,CAAC,MAAM,EAAE,OAAO;IAK/B,KAAK;CAIL;AAID,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAED,wBAAgB,gBAAgB,SAE/B"}
+{"version":3,"file":"theme.svelte.d.ts","sourceRoot":"","sources":["../../src/utils/theme.svelte.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAyD,KAAK,WAAW,EAAE,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAMzH;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAE9E;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC;AAMpE;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC7B,iDAAiD;IACjD,IAAI,EAAE,SAAS,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,aAAa,CAAC;IACxB,4CAA4C;IAC5C,OAAO,EAAE,YAAY,CAAC;IACtB,iDAAiD;IACjD,MAAM,EAAE,WAAW,CAAC;IACpB,qCAAqC;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB,sDAAsD;IACtD,SAAS,EAAE,SAAS,CAAC;IACrB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,YAAY,EAAE,OAAO,CAAC;CACtB;AA4ID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,WAAW;IACvB;;;;;OAKG;IACH,QAAQ,gBAA0C;IAElD;;;;;OAKG;IACH,YAAY,mBAAqC;IAEjD;;;;;OAKG;IACH,MAAM,cAAuF;IAE7F;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAA+B;IAEjD;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAS;IAEtB;;;;;;;;;;OAUG;;IAUH;;;;;;;;;OASG;IACH,OAAO,CAAC,UAAU;IAMlB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;;;;;;;;;OAaG;IACH,KAAK;IA0BL;;;;;OAKG;IACH,OAAO;IASP;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS;IAKvB;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM;IAK1B;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,aAAa;IAKnC;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,YAAY;IAKhC;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,WAAW;IAK7B;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS;IAKvB;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,SAAS;IAK5B;;;;;;;OAOG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM;IAK/B;;;;;;;;;OASG;IACH,eAAe,CAAC,MAAM,EAAE,OAAO;IAK/B;;;;;OAKG;IACH,KAAK;CAIL;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,SAE/B"}