asheeui 0.6.2 → 0.6.3

package/dist/shared/variant.js

@@ -1,51 +1,138 @@
 "use client";
 import { cn as r } from "../utils/cn.js";
-const t = {
-  none: "bg-background text-foreground",
-  primary: "bg-primary text-secondary",
-  secondary: "bg-secondary text-foreground",
-  danger: "bg-danger text-secondary",
-  warning: "bg-warning text-secondary",
-  success: "bg-success text-secondary"
-}, e = {
-  none: "bg-transparent text-foreground hover:bg-foreground/10",
-  primary: "bg-transparent text-primary hover:bg-primary/10",
-  secondary: "bg-transparent text-foreground hover:bg-secondary/10",
-  danger: "bg-transparent text-danger hover:bg-danger/10",
-  warning: "bg-transparent text-warning hover:bg-warning/10",
-  success: "bg-transparent text-success hover:bg-success/10"
-}, g = {
-  none: r(e.primary, "border-2 border-background"),
-  primary: r(e.primary, "border-2 border-primary"),
-  secondary: r(e.secondary, "border-2 border-border"),
-  danger: r(e.danger, "border-2 border-danger"),
-  warning: r(e.warning, "border-2 border-warning"),
-  success: r(e.success, "border-2 border-success")
-}, b = {
-  none: "bg-secondary/40 text-foreground border-2 border-transparent",
-  primary: "bg-primary/10 text-primary border-2 border-primary/20",
-  secondary: "bg-secondary/15 text-foreground border-2 border-secondary/30",
-  danger: "bg-danger/10 text-danger border-2 border-danger/20",
-  warning: "bg-warning/10 text-warning border-2 border-warning/20",
-  success: "bg-success/10 text-success border-2 border-success/20"
-}, n = "border-b-2 border-t-0 border-x-0 rounded-none bg-transparent shadow-none", c = {
-  none: r(n, "border-background text-foreground"),
-  primary: r(n, "border-primary text-primary"),
-  secondary: r(n, "border-secondary text-secondary"),
-  danger: r(n, "border-danger text-danger"),
-  warning: r(n, "border-warning text-warning"),
-  success: r(n, "border-success text-success")
-}, d = {
-  solid: t,
-  ghost: e,
-  bordered: g,
-  faded: b,
-  underlined: c
+const e = "transition-all duration-200 ease-in-out", b = {
+  none: r(e, "bg-background text-foreground hover:bg-background/80"),
+  primary: r(e, "bg-primary text-foreground hover:bg-primary/80"),
+  secondary: r(
+    e,
+    "bg-secondary text-foreground hover:bg-secondary/80"
+  ),
+  danger: r(e, "bg-danger text-foreground hover:bg-danger/80"),
+  warning: r(e, "bg-warning text-foreground hover:bg-warning/80"),
+  success: r(e, "bg-success text-foreground hover:bg-success/80")
+}, o = {
+  none: r(
+    e,
+    "bg-transparent text-foreground hover:bg-foreground/20 hover:text-foreground"
+  ),
+  primary: r(
+    e,
+    "bg-transparent text-primary hover:bg-primary/20 hover:text-primary"
+  ),
+  secondary: r(
+    e,
+    "bg-transparent text-foreground hover:bg-secondary/20 hover:text-foreground"
+  ),
+  danger: r(
+    e,
+    "bg-transparent text-danger hover:bg-danger/20 hover:text-danger"
+  ),
+  warning: r(
+    e,
+    "bg-transparent text-warning hover:bg-warning/20 hover:text-warning"
+  ),
+  success: r(
+    e,
+    "bg-transparent text-success hover:bg-success/20 hover:text-success"
+  )
+}, t = {
+  none: r(
+    e,
+    o.primary,
+    "border-2 border-background hover:border-background/60"
+  ),
+  primary: r(
+    e,
+    o.primary,
+    "border-2 border-primary hover:border-primary/60"
+  ),
+  secondary: r(
+    e,
+    o.secondary,
+    "border-2 border-border hover:border-border/60"
+  ),
+  danger: r(
+    e,
+    o.danger,
+    "border-2 border-danger hover:border-danger/60"
+  ),
+  warning: r(
+    e,
+    o.warning,
+    "border-2 border-warning hover:border-warning/60"
+  ),
+  success: r(
+    e,
+    o.success,
+    "border-2 border-success hover:border-success/60"
+  )
+}, c = {
+  none: r(
+    e,
+    "bg-secondary/40 text-foreground border-2 border-transparent hover:bg-secondary/60 hover:border-secondary/40"
+  ),
+  primary: r(
+    e,
+    "bg-primary/10 text-primary border-2 border-primary/20 hover:bg-primary/20 hover:border-primary/40"
+  ),
+  secondary: r(
+    e,
+    "bg-secondary/15 text-foreground border-2 border-secondary/30 hover:bg-secondary/25 hover:border-secondary/50"
+  ),
+  danger: r(
+    e,
+    "bg-danger/10 text-danger border-2 border-danger/20 hover:bg-danger/20 hover:border-danger/40"
+  ),
+  warning: r(
+    e,
+    "bg-warning/10 text-warning border-2 border-warning/20 hover:bg-warning/20 hover:border-warning/40"
+  ),
+  success: r(
+    e,
+    "bg-success/10 text-success border-2 border-success/20 hover:bg-success/20 hover:border-success/40"
+  )
+}, n = "border-b-2 border-t-0 border-x-0 rounded-none bg-transparent shadow-none", i = {
+  none: r(
+    e,
+    n,
+    "border-background text-foreground hover:border-background/80"
+  ),
+  primary: r(
+    e,
+    n,
+    "border-primary text-primary hover:border-primary/80"
+  ),
+  secondary: r(
+    e,
+    n,
+    "border-secondary text-secondary hover:border-secondary/80"
+  ),
+  danger: r(
+    e,
+    n,
+    "border-danger text-danger hover:border-danger/80"
+  ),
+  warning: r(
+    e,
+    n,
+    "border-warning text-warning hover:border-warning/80"
+  ),
+  success: r(
+    e,
+    n,
+    "border-success text-success hover:border-success/80"
+  )
+}, a = {
+  solid: b,
+  ghost: o,
+  bordered: t,
+  faded: c,
+  underlined: i
 };
-function y(a, s) {
-  var o;
-  return ((o = d[a]) == null ? void 0 : o[s]) ?? d.bordered.secondary;
+function h(s, g) {
+  var d;
+  return ((d = a[s]) == null ? void 0 : d[g]) ?? a.bordered.secondary;
 }
 export {
-  y as resolveVariantClass
+  h as resolveVariantClass
 };

package/dist/theme/color.d.ts

@@ -1,22 +1,91 @@
+/**
+ * Color configuration types for AsheeUI's theming system.
+ * This file defines the structure of theme color palettes, including
+ * the required built-in themes (light and dark) and optional custom
+ * theme extensions. It provides the type foundation for the color
+ * configuration that powers the component library's visual system.
+ */
+/**
+ * The built-in theme names that are always available in AsheeUI.
+ * "light" and "dark" are the core themes that every installation provides.
+ */
 export type KnownThemeName = "light" | "dark";
+/**
+ * Registry of available color themes in AsheeUI.
+ * Currently supports the built-in "light" and "dark" themes.
+ * This interface serves as the constraint for theme name resolution.
+ */
 export interface AsheeColorRegistry {
     light: true;
     dark: true;
 }
+/**
+ * All available theme names in AsheeUI.
+ * This is derived from the AsheeColorRegistry and includes both
+ * built-in themes and any custom themes defined by the user.
+ */
 export type ThemeName = keyof AsheeColorRegistry;
+/**
+ * The complete set of color variables required for a single theme.
+ * These colors are used throughout the component library for
+ * backgrounds, text, borders, interactive elements, and status indicators.
+ */
 export interface ColorVariant {
+    /**
+     * The main background color of the application.
+     * Used for page backgrounds and container surfaces.
+     */
     background: string;
+    /**
+     * The primary text color.
+     * Used for body text and other foreground content.
+     */
     foreground: string;
+    /**
+     * The primary brand or interactive color.
+     * Used for buttons, links, and other interactive elements.
+     */
     primary: string;
+    /**
+     * The secondary surface color.
+     * Used for cards, panels, and other elevated surfaces.
+     */
     secondary: string;
+    /**
+     * The border color.
+     * Used for separators, input borders, and dividing lines.
+     */
     border: string;
+    /**
+     * The danger or error color.
+     * Used for destructive actions and error states.
+     */
     danger: string;
+    /**
+     * The warning color.
+     * Used for cautionary states and warnings.
+     */
     warning: string;
+    /**
+     * The success color.
+     * Used for success states and positive feedback.
+     */
     success: string;
+    /**
+     * The scrollbar thumb color.
+     * Used for the draggable handle of scrollbars.
+     */
     scrollbarThumb: string;
+    /**
+     * The scrollbar track color.
+     * Used for the background track of scrollbars.
+     */
     scrollbarTrack: string;
 }
-/** Built-in colors map required by the core library */
+/**
+ * Built-in colors map required by the core library.
+ * Both "light" and "dark" themes must be fully defined.
+ */
 export type DefaultColorConfig = Record<KnownThemeName, ColorVariant>;
 /**
  * Full color configuration.
@@ -24,11 +93,30 @@ export type DefaultColorConfig = Record<KnownThemeName, ColorVariant>;
  * on default/unmerged configs, but enforced via ExternalColorConfig.
  */
 export type ColorConfig = Record<KnownThemeName, ColorVariant> & Partial<Record<Exclude<ThemeName, KnownThemeName>, ColorVariant>>;
+/**
+ * A color variant that can be partially defined.
+ * Custom themes can extend a known theme to inherit its colors.
+ */
 export type ExternalColorVariant = Partial<ColorVariant> & {
+    /**
+     * Optional theme to extend.
+     * When provided, the custom theme will inherit colors from the specified
+     * built-in theme, with any explicitly defined colors overriding the inherited values.
+     */
     extends?: KnownThemeName;
 };
 type CustomThemeName = Exclude<ThemeName, KnownThemeName>;
+/**
+ * External color configuration format.
+ * Built-in themes can be partially overridden, while custom themes
+ * must provide at least a partial color variant (with optional extension).
+ */
 export type ExternalColorConfig = Partial<Record<KnownThemeName, Partial<ColorVariant>>> & Record<CustomThemeName, ExternalColorVariant>;
+/**
+ * The default color configuration for AsheeUI.
+ * Provides complete color variants for both light and dark themes
+ * with carefully chosen default values that work out of the box.
+ */
 export declare const defaultColorConfig: DefaultColorConfig;
 export {};
 //# sourceMappingURL=color.d.ts.map

package/dist/theme/color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/theme/color.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,IAAI,CAAC;IACZ,IAAI,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC;AAEjD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,uDAAuD;AACvD,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC,GAC5D,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;AAEpE,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG;IACzD,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,KAAK,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAC1D,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAC9C,GACC,MAAM,CAAC,eAAe,EAAE,oBAAoB,CAAC,CAAC;AAEhD,eAAO,MAAM,kBAAkB,EAAE,kBAyBhC,CAAC"}
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../src/theme/color.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,IAAI,CAAC;IACZ,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,kBAAkB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,cAAc,EAAE,YAAY,CAAC,GAC5D,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;AAEpE;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,YAAY,CAAC,GAAG;IACzD;;;;OAIG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B,CAAC;AAEF,KAAK,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,OAAO,CACvC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC,CAC9C,GACC,MAAM,CAAC,eAAe,EAAE,oBAAoB,CAAC,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,kBAyBhC,CAAC"}

package/dist/theme/controller.d.ts

@@ -1,17 +1,72 @@
 import { ThemeName } from './color';
+/**
+ * A theme selection that can be either a specific theme name or the special
+ * "system" value, which resolves to either light or dark based on the user's
+ * system preference.
+ */
 export type ThemeSelection = ThemeName | "system";
+/**
+ * Local storage key used to persist the user's theme preference.
+ */
 export declare const THEME_STORAGE_KEY = "ashee-theme";
+/**
+ * Function type for theme change listeners.
+ */
 type Listener = () => void;
+/**
+ * Input configuration required to initialize the theme controller.
+ * Provides the default theme and the list of available themes.
+ */
 export interface ThemeConfigInput {
+    /**
+     * The default theme to use when no user preference is stored or when
+     * the stored preference is invalid. This can be a specific theme name
+     * or "system" to follow the system preference.
+     */
     defaultTheme: ThemeSelection;
+    /**
+     * The list of theme names that are available in the application.
+     * This is used to validate stored preferences and to determine
+     * which themes can be toggled through the toggleTheme method.
+     */
     themes: readonly string[];
 }
+/**
+ * Manages theme state, persistence, and system preference detection.
+ * This class handles the core logic of selecting, resolving, and applying
+ * themes, including storing preferences in localStorage and responding to
+ * system dark mode changes. It follows the observer pattern to notify
+ * subscribers when the theme changes.
+ */
 declare class ThemeController {
+    /**
+     * The user's selected theme preference, which may be "system"
+     * or a specific theme name.
+     */
     private selection;
+    /**
+     * The final resolved theme name after applying the selection
+     * and resolving "system" to either "light" or "dark".
+     */
     private resolved;
+    /**
+     * The default theme configured when the controller was initialized.
+     * Used as a fallback when the stored preference is invalid.
+     */
     private defaultTheme;
+    /**
+     * The list of available themes in the application.
+     * Used for validation and cycling through themes.
+     */
     private availableThemes;
+    /**
+     * Set of listener functions that are called when the theme changes.
+     */
     private listeners;
+    /**
+     * MediaQueryList for detecting system dark mode preference.
+     * Null when running in a non-browser environment.
+     */
     private mediaQuery;
     constructor();
     /**
@@ -27,24 +82,90 @@ declare class ThemeController {
      * Seeds the default theme. Kept for backward compatibility - prefer
      * `configure()`, which also validates the stored selection against the
      * available theme map.
+     *
+     * @deprecated Use `configure()` instead for complete initialization.
      */
     setDefault: (theme: ThemeSelection) => void;
+    /**
+     * Returns the current theme selection.
+     * @returns The current selected theme, which may be "system" or a specific theme name.
+     */
     getSelection: () => ThemeSelection;
+    /**
+     * Returns the resolved theme name after applying the selection.
+     * If the selection is "system", this will resolve to either "light" or "dark"
+     * based on the system preference.
+     * @returns The resolved theme name.
+     */
     getResolvedTheme: () => ThemeName;
+    /**
+     * Sets the theme selection and persists it to localStorage.
+     * The provided selection is validated and sanitized before applying.
+     * @param selection - The theme to select, either "system" or a theme name.
+     */
     setTheme: (selection: ThemeSelection) => void;
+    /**
+     * Subscribes a listener to theme changes.
+     * The listener will be called whenever the theme selection or resolved theme changes.
+     * @param listener - The function to call when the theme changes.
+     * @returns An unsubscribe function that removes the listener.
+     */
     subscribe: (listener: Listener) => (() => void);
+    /**
+     * Returns the list of available theme names.
+     * @returns The list of available themes configured in the controller.
+     */
     getAvailableThemes: () => readonly string[];
     /**
      * Cycles to the next theme in sequence (including "system" mode by default).
      * Loops back to the start when reaching the end of the available themes list.
+     * The "system" option is not included in the toggle sequence; only specific
+     * theme names are cycled through.
      */
     toggleTheme: () => void;
+    /**
+     * Handles system dark mode preference changes.
+     * Only re-applies the theme if the current selection is "system",
+     * ensuring the resolved theme stays in sync with system changes.
+     */
     private handleSystemChange;
+    /**
+     * Validates a theme selection and returns a valid fallback if necessary.
+     * @param selection - The theme selection to sanitize.
+     * @returns A valid theme selection, falling back to the default theme
+     *          if the provided selection is invalid.
+     */
     private sanitize;
+    /**
+     * Checks whether a theme selection is valid.
+     * "system" is always valid. Other theme names are valid if they exist
+     * in the available themes list. If no available themes are configured,
+     * any selection is considered valid.
+     * @param selection - The theme selection to validate.
+     * @returns True if the selection is valid, false otherwise.
+     */
     private isValid;
+    /**
+     * Resolves a theme selection to an actual theme name.
+     * If the selection is "system", resolves based on the system preference.
+     * @param selection - The theme selection to resolve.
+     * @returns The resolved theme name.
+     */
     private resolve;
+    /**
+     * Applies the current theme selection by updating the DOM.
+     * This method sanitizes the selection, resolves it to a theme name,
+     * and applies the appropriate CSS class to the document root.
+     * It ensures that only valid theme classes are applied and removes
+     * any previously applied theme classes.
+     */
     private applySelection;
 }
+/**
+ * Singleton instance of the theme controller.
+ * This instance manages the global theme state and should be used
+ * throughout the application for theme operations.
+ */
 export declare const themeController: ThemeController;
 export {};
 //# sourceMappingURL=controller.d.ts.map

package/dist/theme/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/theme/controller.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElD,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAI/C,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAE3B,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,cAAc,CAAC;IAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,cAAM,eAAe;IACnB,OAAO,CAAC,SAAS,CAA2B;IAC5C,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,YAAY,CAA2B;IAC/C,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,UAAU,CAA+B;;IASjD;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAwC3D;;;;OAIG;IACH,UAAU,UAAW,cAAc,KAAG,IAAI,CAExC;IAEF,YAAY,QAAO,cAAc,CAAmB;IACpD,gBAAgB,QAAO,SAAS,CAAkB;IAElD,QAAQ,cAAe,cAAc,KAAG,IAAI,CAS1C;IAEF,SAAS,aAAc,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAG5C;IAEF,kBAAkB,QAAO,SAAS,MAAM,EAAE,CAAyB;IAEnE;;;OAGG;IACH,WAAW,QAAO,IAAI,CAWpB;IAEF,OAAO,CAAC,kBAAkB,CAMxB;IAEF,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,cAAc;CA+BvB;AAED,eAAO,MAAM,eAAe,iBAAwB,CAAC"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/theme/controller.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,iBAAiB,gBAAgB,CAAC;AAa/C;;GAEG;AACH,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AAE3B;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,YAAY,EAAE,cAAc,CAAC;IAE7B;;;;OAIG;IACH,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,cAAM,eAAe;IACnB;;;OAGG;IACH,OAAO,CAAC,SAAS,CAA2B;IAE5C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAsB;IAEtC;;;OAGG;IACH,OAAO,CAAC,YAAY,CAA2B;IAE/C;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAyB;IAEhD;;OAEG;IACH,OAAO,CAAC,SAAS,CAAuB;IAExC;;;OAGG;IACH,OAAO,CAAC,UAAU,CAA+B;;IASjD;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,EAAE,gBAAgB,GAAG,IAAI;IAwC3D;;;;;;OAMG;IACH,UAAU,UAAW,cAAc,KAAG,IAAI,CAExC;IAEF;;;OAGG;IACH,YAAY,QAAO,cAAc,CAAmB;IAEpD;;;;;OAKG;IACH,gBAAgB,QAAO,SAAS,CAAkB;IAElD;;;;OAIG;IACH,QAAQ,cAAe,cAAc,KAAG,IAAI,CAS1C;IAEF;;;;;OAKG;IACH,SAAS,aAAc,QAAQ,KAAG,CAAC,MAAM,IAAI,CAAC,CAG5C;IAEF;;;OAGG;IACH,kBAAkB,QAAO,SAAS,MAAM,EAAE,CAAyB;IAEnE;;;;;OAKG;IACH,WAAW,QAAO,IAAI,CAWpB;IAEF;;;;OAIG;IACH,OAAO,CAAC,kBAAkB,CAMxB;IAEF;;;;;OAKG;IACH,OAAO,CAAC,QAAQ;IAKhB;;;;;;;OAOG;IACH,OAAO,CAAC,OAAO;IAOf;;;;;OAKG;IACH,OAAO,CAAC,OAAO;IAKf;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;CA+BvB;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,iBAAwB,CAAC"}

package/dist/theme/controller.js

@@ -5,33 +5,85 @@ var s = (n, e, t) => c(n, typeof e != "symbol" ? e + "" : e, t);
 const a = "ashee-theme", d = "(prefers-color-scheme: dark)", h = "theme-";
 class m {
   constructor() {
+    /**
+     * The user's selected theme preference, which may be "system"
+     * or a specific theme name.
+     */
     s(this, "selection", "light");
+    /**
+     * The final resolved theme name after applying the selection
+     * and resolving "system" to either "light" or "dark".
+     */
     s(this, "resolved", "light");
+    /**
+     * The default theme configured when the controller was initialized.
+     * Used as a fallback when the stored preference is invalid.
+     */
     s(this, "defaultTheme", "light");
+    /**
+     * The list of available themes in the application.
+     * Used for validation and cycling through themes.
+     */
     s(this, "availableThemes", []);
+    /**
+     * Set of listener functions that are called when the theme changes.
+     */
     s(this, "listeners", /* @__PURE__ */ new Set());
+    /**
+     * MediaQueryList for detecting system dark mode preference.
+     * Null when running in a non-browser environment.
+     */
     s(this, "mediaQuery", null);
     /**
      * Seeds the default theme. Kept for backward compatibility - prefer
      * `configure()`, which also validates the stored selection against the
      * available theme map.
+     *
+     * @deprecated Use `configure()` instead for complete initialization.
      */
     s(this, "setDefault", (e) => {
       this.configure({ defaultTheme: e, themes: this.availableThemes });
     });
+    /**
+     * Returns the current theme selection.
+     * @returns The current selected theme, which may be "system" or a specific theme name.
+     */
     s(this, "getSelection", () => this.selection);
+    /**
+     * Returns the resolved theme name after applying the selection.
+     * If the selection is "system", this will resolve to either "light" or "dark"
+     * based on the system preference.
+     * @returns The resolved theme name.
+     */
     s(this, "getResolvedTheme", () => this.resolved);
+    /**
+     * Sets the theme selection and persists it to localStorage.
+     * The provided selection is validated and sanitized before applying.
+     * @param selection - The theme to select, either "system" or a theme name.
+     */
     s(this, "setTheme", (e) => {
       const t = this.sanitize(e);
       this.selection = t, typeof window < "u" && window.localStorage.setItem(a, t), this.applySelection(), this.listeners.forEach((i) => {
         i();
       });
     });
+    /**
+     * Subscribes a listener to theme changes.
+     * The listener will be called whenever the theme selection or resolved theme changes.
+     * @param listener - The function to call when the theme changes.
+     * @returns An unsubscribe function that removes the listener.
+     */
     s(this, "subscribe", (e) => (this.listeners.add(e), () => this.listeners.delete(e)));
+    /**
+     * Returns the list of available theme names.
+     * @returns The list of available themes configured in the controller.
+     */
     s(this, "getAvailableThemes", () => this.availableThemes);
     /**
      * Cycles to the next theme in sequence (including "system" mode by default).
      * Loops back to the start when reaching the end of the available themes list.
+     * The "system" option is not included in the toggle sequence; only specific
+     * theme names are cycled through.
      */
     s(this, "toggleTheme", () => {
       const e = Array.from(new Set(this.availableThemes)).filter(
@@ -39,6 +91,11 @@ class m {
       ), t = e.indexOf(this.selection), i = t === -1 ? 0 : (t + 1) % e.length;
       this.setTheme(e[i]);
     });
+    /**
+     * Handles system dark mode preference changes.
+     * Only re-applies the theme if the current selection is "system",
+     * ensuring the resolved theme stays in sync with system changes.
+     */
     s(this, "handleSystemChange", () => {
       this.selection === "system" && (this.applySelection(), this.listeners.forEach((e) => {
         e();
@@ -70,16 +127,43 @@ class m {
       o();
     }), console.log("[Theme] Notified all listeners.");
   }
+  /**
+   * Validates a theme selection and returns a valid fallback if necessary.
+   * @param selection - The theme selection to sanitize.
+   * @returns A valid theme selection, falling back to the default theme
+   *          if the provided selection is invalid.
+   */
   sanitize(e) {
     return this.isValid(e) ? e : this.defaultTheme;
   }
+  /**
+   * Checks whether a theme selection is valid.
+   * "system" is always valid. Other theme names are valid if they exist
+   * in the available themes list. If no available themes are configured,
+   * any selection is considered valid.
+   * @param selection - The theme selection to validate.
+   * @returns True if the selection is valid, false otherwise.
+   */
   isValid(e) {
     return e === "system" ? !0 : this.availableThemes.length > 0 ? this.availableThemes.includes(e) : !0;
   }
+  /**
+   * Resolves a theme selection to an actual theme name.
+   * If the selection is "system", resolves based on the system preference.
+   * @param selection - The theme selection to resolve.
+   * @returns The resolved theme name.
+   */
   resolve(e) {
     var t;
     return e !== "system" ? e : (t = this.mediaQuery) != null && t.matches ? "dark" : "light";
   }
+  /**
+   * Applies the current theme selection by updating the DOM.
+   * This method sanitizes the selection, resolves it to a theme name,
+   * and applies the appropriate CSS class to the document root.
+   * It ensures that only valid theme classes are applied and removes
+   * any previously applied theme classes.
+   */
   applySelection() {
     const e = this.sanitize(this.selection);
     let t = this.resolve(e);