asheeui 0.6.2 → 0.6.5

package/dist/theme/useTheme.d.ts

@@ -1,9 +1,77 @@
 import { ThemeSelection } from './controller';
+/**
+ * React hook that provides access to the current theme state and controls.
+ *
+ * This hook subscribes to the theme controller and returns the current
+ * theme selection, resolved theme name, and functions for changing the theme.
+ * Components using this hook will re-render automatically when the theme changes.
+ *
+ * The hook uses useSyncExternalStore to safely subscribe to the theme
+ * controller's state, making it compatible with React's concurrent rendering.
+ *
+ * @returns An object containing the current theme state and control functions.
+ *
+ * @example
+ * ```tsx
+ * function ThemeToggle() {
+ *   const { theme, setTheme, availableThemes } = useTheme();
+ *
+ *   return (
+ *     <select value={theme} onChange={(e) => setTheme(e.target.value as ThemeSelection)}>
+ *       {availableThemes.map(t => (
+ *         <option key={t} value={t}>{t}</option>
+ *       ))}
+ *       <option value="system">System</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ThemedComponent() {
+ *   const { resolvedTheme } = useTheme();
+ *
+ *   return (
+ *     <div className={resolvedTheme === 'dark' ? 'dark-styles' : 'light-styles'}>
+ *       Current theme: {resolvedTheme}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see ThemeController - The underlying class that manages theme state.
+ * @see ThemeSelection - The type for theme selections including "system".
+ * @see ThemeName - The type for resolved theme names.
+ */
 export declare function useTheme(): {
+    /**
+     * The user's current theme selection.
+     * This can be either a specific theme name or "system".
+     */
     theme: ThemeSelection;
+    /**
+     * The resolved theme name after applying the selection.
+     * If the selection is "system", this resolves to either "light" or "dark"
+     * based on the system preference.
+     */
     resolvedTheme: keyof import('./color').AsheeColorRegistry;
+    /**
+     * Function to set the theme selection.
+     * This persists the selection to localStorage and applies the theme.
+     * @param selection - The theme to select, either "system" or a theme name.
+     */
     setTheme: (selection: ThemeSelection) => void;
+    /**
+     * Function to cycle to the next available theme.
+     * This cycles through all available theme names, excluding "system".
+     * Loops back to the start when reaching the end of the list.
+     */
     toggleTheme: () => void;
+    /**
+     * The list of available theme names in the application.
+     * This does not include "system" as it is not a theme name.
+     */
     availableThemes: readonly string[];
 };
 //# sourceMappingURL=useTheme.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../src/theme/useTheme.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,cAAc,CAAC;AAEpE,wBAAgB,QAAQ;;;;;;EAoBvB"}
+{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../src/theme/useTheme.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,KAAK,cAAc,EAAmB,MAAM,cAAc,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,QAAQ;IAcpB;;;OAGG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;OAGG;;EAGN"}

package/dist/theme/useTheme.js

@@ -12,10 +12,33 @@ function r() {
     () => "light"
   );
   return {
+    /**
+     * The user's current theme selection.
+     * This can be either a specific theme name or "system".
+     */
     theme: o,
+    /**
+     * The resolved theme name after applying the selection.
+     * If the selection is "system", this resolves to either "light" or "dark"
+     * based on the system preference.
+     */
     resolvedTheme: l,
+    /**
+     * Function to set the theme selection.
+     * This persists the selection to localStorage and applies the theme.
+     * @param selection - The theme to select, either "system" or a theme name.
+     */
     setTheme: e.setTheme,
+    /**
+     * Function to cycle to the next available theme.
+     * This cycles through all available theme names, excluding "system".
+     * Loops back to the start when reaching the end of the list.
+     */
     toggleTheme: e.toggleTheme,
+    /**
+     * The list of available theme names in the application.
+     * This does not include "system" as it is not a theme name.
+     */
     availableThemes: e.getAvailableThemes()
   };
 }

package/dist/utils/index.d.ts

@@ -1,10 +1,3 @@
-/**
- * AsheeUI shared utilities.
- *
- * Client-safe helpers (`cn`, `mergeObject`) plus the `DeepPartial` type,
- * migrated from the former `@asheeui/utils` package. Node-only helpers
- * (config discovery) live under `./node`.
- */
 export { cn } from './cn';
 export { mergeObject } from './merge-object';
 export type { DeepPartial } from './types';

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC"}

package/dist/utils/resolve-token.d.ts

@@ -1,5 +1,106 @@
+/**
+ * Utility functions for resolving cascade values in AsheeUI.
+ * This file provides helper functions that implement the configuration
+ * precedence hierarchy: instance prop > component config > theme default > hard fallback.
+ * These utilities are used throughout the component library to resolve
+ * values like variant, color, size, and radius.
+ */
+/**
+ * Resolves a value using the standard cascade precedence order.
+ * Follows the hierarchy: instance prop > component config > global default > hard fallback.
+ * This is the primary resolver for most component props.
+ *
+ * @param instance - The prop value passed directly to the component instance.
+ * @param section - The value from the component's configuration section.
+ * @param globalDefault - The global default value from the theme configuration.
+ * @param hardFallback - The final fallback value if all others are undefined.
+ * @returns The resolved value.
+ *
+ * @example
+ * ```tsx
+ * const variant = resolveCascade(
+ *   props.variant,          // 'ghost'
+ *   config.Button.variant,  // 'solid'
+ *   theme.defaultVariant,   // 'faded'
+ *   'solid'                 // hard fallback
+ * );
+ * // Returns 'ghost' because instance prop takes precedence
+ * ```
+ */
 export declare function resolveCascade<T>(instance: T | undefined, section: T | undefined, globalDefault: T | undefined, hardFallback: T): T;
+/**
+ * Resolves a value for animation or transition contexts.
+ * Similar to resolveCascade but without the global default tier.
+ * This is useful for values that should not inherit from theme defaults.
+ *
+ * @param instance - The prop value passed directly to the component instance.
+ * @param section - The value from the component's configuration section.
+ * @param hardFallback - The final fallback value if all others are undefined.
+ * @returns The resolved value.
+ *
+ * @example
+ * ```tsx
+ * const animate = resolveAnimate(
+ *   props.animate,           // false
+ *   config.Button.animate,   // true
+ *   true                     // hard fallback
+ * );
+ * // Returns false because instance prop takes precedence
+ * ```
+ */
 export declare function resolveAnimate<T>(instance: T | undefined, section: T | undefined, hardFallback: T): T;
+/**
+ * Resolves a radius value using the standard cascade precedence order.
+ * This is a specialized version of resolveCascade that provides a default
+ * hard fallback of "md" for radius values.
+ *
+ * @param instanceProp - The radius prop passed directly to the component instance.
+ * @param sectionConfig - The radius from the component's configuration section.
+ * @param globalDefaultRadius - The global default radius from the theme.
+ * @param hardFallback - Optional custom fallback, defaults to "md".
+ * @returns The resolved radius key.
+ *
+ * @example
+ * ```tsx
+ * const radius = resolveRadiusKey(
+ *   props.radius,          // 'lg'
+ *   config.Button.radius,  // 'md'
+ *   theme.defaultRadius,   // 'sm'
+ * );
+ * // Returns 'lg' because instance prop takes precedence
+ * ```
+ */
 export declare function resolveRadiusKey<TKey>(instanceProp: TKey | undefined, sectionConfig: TKey | undefined, globalDefaultRadius: TKey | undefined, hardFallback?: TKey): TKey;
+/**
+ * Resolves a CSS class from a class map based on a key.
+ * Returns the class string for the given key, falling back to the
+ * fallback key's class if the key is not found. Returns an empty
+ * string if neither the key nor the fallback key exist in the map.
+ *
+ * @param key - The key to look up in the class map.
+ * @param classMap - The record mapping keys to CSS class strings.
+ * @param fallbackKey - The fallback key to use if the primary key is not found.
+ * @returns The CSS class string.
+ *
+ * @example
+ * ```tsx
+ * const classes = resolveClassKey(
+ *   'lg',                          // key
+ *   { sm: 'text-sm', lg: 'text-lg' }, // classMap
+ *   'sm'                           // fallbackKey
+ * );
+ * // Returns 'text-lg'
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const classes = resolveClassKey(
+ *   'xl',                          // key not in map
+ *   { sm: 'text-sm', lg: 'text-lg' }, // classMap
+ *   'sm'                           // fallbackKey
+ * );
+ * // Returns 'text-sm' from fallback key
+ * ```
+ */
 export declare function resolveClassKey<TKey extends PropertyKey>(key: TKey, classMap: Record<TKey, string>, fallbackKey: TKey): string;
 //# sourceMappingURL=resolve-token.d.ts.map

package/dist/utils/resolve-token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-token.d.ts","sourceRoot":"","sources":["../../src/utils/resolve-token.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,CAAC,EAC9B,QAAQ,EAAE,CAAC,GAAG,SAAS,EACvB,OAAO,EAAE,CAAC,GAAG,SAAS,EACtB,aAAa,EAAE,CAAC,GAAG,SAAS,EAC5B,YAAY,EAAE,CAAC,GACd,CAAC,CAEH;AAED,wBAAgB,cAAc,CAAC,CAAC,EAC9B,QAAQ,EAAE,CAAC,GAAG,SAAS,EACvB,OAAO,EAAE,CAAC,GAAG,SAAS,EACtB,YAAY,EAAE,CAAC,GACd,CAAC,CAEH;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EACnC,YAAY,EAAE,IAAI,GAAG,SAAS,EAC9B,aAAa,EAAE,IAAI,GAAG,SAAS,EAC/B,mBAAmB,EAAE,IAAI,GAAG,SAAS,EACrC,YAAY,GAAE,IAAmB,GAChC,IAAI,CAEN;AAED,wBAAgB,eAAe,CAAC,IAAI,SAAS,WAAW,EACtD,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAC9B,WAAW,EAAE,IAAI,GAChB,MAAM,CAER"}
+{"version":3,"file":"resolve-token.d.ts","sourceRoot":"","sources":["../../src/utils/resolve-token.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,QAAQ,EAAE,CAAC,GAAG,SAAS,EACvB,OAAO,EAAE,CAAC,GAAG,SAAS,EACtB,aAAa,EAAE,CAAC,GAAG,SAAS,EAC5B,YAAY,EAAE,CAAC,GACd,CAAC,CAEH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,QAAQ,EAAE,CAAC,GAAG,SAAS,EACvB,OAAO,EAAE,CAAC,GAAG,SAAS,EACtB,YAAY,EAAE,CAAC,GACd,CAAC,CAEH;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EACnC,YAAY,EAAE,IAAI,GAAG,SAAS,EAC9B,aAAa,EAAE,IAAI,GAAG,SAAS,EAC/B,mBAAmB,EAAE,IAAI,GAAG,SAAS,EACrC,YAAY,GAAE,IAAmB,GAChC,IAAI,CAEN;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAAS,WAAW,EACtD,GAAG,EAAE,IAAI,EACT,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAC9B,WAAW,EAAE,IAAI,GAChB,MAAM,CAER"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asheeui",
-  "version": "0.6.2",
+  "version": "0.6.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/dist/components/keyboard/default-keyboard-config.d.ts

@@ -1,10 +0,0 @@
-import { KeyboardConfig, KeyboardLayouts, KeyDisplayMap } from './keyboard-config';
-export declare const defaultKeyboardLayouts: KeyboardLayouts;
-export declare const defaultKeyDisplay: KeyDisplayMap;
-export declare const defaultKeyboardConfig: KeyboardConfig;
-declare module "../../libs/registry" {
-    interface ComponentTypeConfigRegistry {
-        keyboard: KeyboardConfig;
-    }
-}
-//# sourceMappingURL=default-keyboard-config.d.ts.map

package/dist/components/keyboard/default-keyboard-config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"default-keyboard-config.d.ts","sourceRoot":"","sources":["../../../src/components/keyboard/default-keyboard-config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,aAAa,EACd,MAAM,mBAAmB,CAAC;AAE3B,eAAO,MAAM,sBAAsB,EAAE,eAuBpC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,aAQ/B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,cAMnC,CAAC;AAEF,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,2BAA2B;QACnC,QAAQ,EAAE,cAAc,CAAC;KAC1B;CACF"}

package/dist/shared/size.d.ts

@@ -1,2 +0,0 @@
-export type Size = "sm" | "md" | "lg";
-//# sourceMappingURL=size.d.ts.map

package/dist/shared/size.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"size.d.ts","sourceRoot":"","sources":["../../src/shared/size.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC"}