@fakhrirafiki/theme-engine 0.4.20 → 0.4.22

package/README.md

@@ -19,6 +19,9 @@ Dark mode + theme presets (semantic tokens via CSS variables).
 - 🎨 **Theme presets**: built-in presets + your own presets
 - 🧩 **Tailwind v4 friendly**: `@theme inline` tokens included (works with shadcn-style semantic tokens)
 
+> [!TIP]
+> If you’re using **shadcn/ui** with **Next.js App Router**, you should use this package — it provides a complete, production-ready theme layer (mode + presets) that plugs straight into shadcn’s semantic tokens.
+
 ## 📚 Table of contents
 
 - [Install](#-install)

package/dist/index.d.mts

@@ -234,15 +234,37 @@ interface ThemePresetButtonsProps {
     showSectionHeaders?: boolean;
 }
 
+/**
+ * Appearance mode.
+ *
+ * - `"system"` follows `prefers-color-scheme`
+ * - `resolvedMode` (from hooks/provider) is always `"light"` or `"dark"`
+ *
+ * @public
+ */
 type Mode = "light" | "dark" | "system";
+/**
+ * Screen coordinates used for the optional view-transition ripple when toggling modes.
+ *
+ * @public
+ */
 interface Coordinates {
     x: number;
     y: number;
 }
+/**
+ * Props for `ThemeToggle`.
+ *
+ * @public
+ */
 interface ThemeToggleProps {
+    /** Additional class name(s) applied to the button element */
     className?: string;
+    /** Styling hook exposed via `data-size` */
     size?: "sm" | "md" | "lg";
+    /** Styling hook exposed via `data-variant` */
     variant?: "default" | "outline" | "ghost";
+    /** Optional custom icon/content (overrides the default icon) */
     children?: ReactNode;
 }
 
@@ -366,13 +388,33 @@ type PresetId<TCustomPresets> = BuiltInPresetId | CustomPresetId$2<TCustomPreset
 interface UnifiedThemeProviderProps<TCustomPresets extends CustomPresetsRecord$2 | undefined = undefined> {
     /** React children to wrap with theming context */
     children: react__default.ReactNode;
-    /** Default appearance mode when no stored preference exists */
+    /**
+     * Default appearance mode when no stored preference exists.
+     *
+     * Notes for SSR/App Router:
+     * - The initial render must be deterministic between server and client to avoid hydration mismatches.
+     * - Persisted mode is restored after hydration (and also pre-hydration via the injected `ThemeScript`).
+     */
     defaultMode?: Mode;
-    /** Default preset ID to use when no stored preset exists or when resetting */
+    /**
+     * Default preset ID to use when no stored preset exists or when resetting.
+     *
+     * If provided, the preset will be applied when:
+     * - there is no persisted preset in `localStorage`, or
+     * - `clearPreset()` is called.
+     */
     defaultPreset?: PresetId<TCustomPresets>;
-    /** localStorage key for appearance mode persistence */
+    /**
+     * `localStorage` key for appearance mode persistence.
+     *
+     * Stored value is one of: `"light" | "dark" | "system"`.
+     */
     modeStorageKey?: string;
-    /** localStorage key for color preset persistence */
+    /**
+     * `localStorage` key for color preset persistence.
+     *
+     * Stored value is a JSON blob written by this provider and restored on subsequent loads.
+     */
     presetStorageKey?: string;
     /** Custom presets to add to the available collection */
     customPresets?: TCustomPresets;
@@ -391,6 +433,14 @@ interface UnifiedThemeProviderProps<TCustomPresets extends CustomPresetsRecord$2
  * - 🎨 **CSS `!important`** ensures presets override mode defaults
  * - 👀 **MutationObserver** automatically reapplies presets on mode changes
  *
+ * ## SSR / hydration behavior
+ * This provider is designed for Next.js App Router where Client Components are still SSR-ed.
+ * To avoid hydration mismatches:
+ * - The initial render does not read `localStorage`.
+ * - A pre-hydration `ThemeScript` is injected to apply the correct `html` mode class (`light`/`dark`)
+ *   and restore preset CSS variables as early as possible.
+ * - Persisted mode and preset are then reconciled after hydration.
+ *
  * @example
  * ```tsx
  * <ThemeProvider
@@ -411,6 +461,8 @@ declare function ThemeProvider<const TCustomPresets extends CustomPresetsRecord$
  * Provides access to both appearance mode controls and preset management
  * in a single, coordinated interface.
  *
+ * Prefer `useThemeEngine()` for a DX-first API with aliases and typed preset IDs.
+ *
  * @example
  * ```tsx
  * // Mode controls
@@ -476,17 +528,79 @@ interface ThemeScriptProps {
     defaultPreset?: string;
 }
 /**
- * Pre-hydration theme script.
- * - Restores appearance mode (light/dark/system) to avoid hydration mismatch + FOUC.
- * - Restores preset CSS variables early so Tailwind/shadcn tokens render correctly on first paint.
+ * Pre-hydration theme script injected by `ThemeProvider`.
+ *
+ * This runs before React hydration and is intentionally implemented as an inline script so it can:
+ * - restore the `html` mode class (`light`/`dark`) and `color-scheme` as early as possible
+ * - restore preset CSS variables early to prevent FOUC (unstyled/incorrect tokens on first paint)
+ *
+ * It reads:
+ * - `localStorage[modeStorageKey]` (mode persistence)
+ * - `localStorage[presetStorageKey]` (preset persistence)
+ *
+ * It writes:
+ * - `document.documentElement.classList` (`light`/`dark`)
+ * - `document.documentElement.style.colorScheme`
+ * - `document.documentElement.dataset.themeEngineMode` and `dataset.themeEngineResolvedMode` (best-effort)
+ *
+ * You typically do not render this manually — `ThemeProvider` includes it automatically.
  */
 declare function ThemeScript({ presetStorageKey, modeStorageKey, defaultMode, defaultPreset, }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Button that toggles the current appearance mode (light ↔ dark) using Theme Engine.
+ *
+ * - Reads `mode` / `resolvedMode` from `ThemeProvider` via `useTheme()`
+ * - On click, calls `toggleMode({ x, y })` to enable the optional view-transition ripple
+ * - Renders an icon that reflects the current mode (`light`/`dark`/`system`) unless you pass `children`
+ *
+ * Data attributes:
+ * - `data-size`: `"sm" | "md" | "lg"` (for styling hooks)
+ * - `data-variant`: `"default" | "outline" | "ghost"`
+ * - `data-mode`: resolved mode (`"light" | "dark"`) for CSS hooks
+ * - `data-theme`: alias of `data-mode`
+ *
+ * @example
+ * ```tsx
+ * import { ThemeToggle } from "@fakhrirafiki/theme-engine";
+ *
+ * export function Header() {
+ *   return <ThemeToggle className="ml-auto" />;
+ * }
+ * ```
+ */
 declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & react.RefAttributes<HTMLButtonElement>>;
 
 /**
  * Main ThemePresetButtons component
  */
+/**
+ * Preset picker UI for Theme Engine.
+ *
+ * Renders a horizontally scrolling set of preset buttons (optionally in multiple rows) and applies
+ * the selected preset via `ThemeProvider` context.
+ *
+ * Requirements:
+ * - Must be used under `ThemeProvider` (it reads `availablePresets`/`currentPreset` from context).
+ *
+ * Behavior:
+ * - Built-in + custom presets are merged from context and displayed (custom presets are shown first).
+ * - Selecting a preset calls `applyPreset()` from the provider, which also persists it to `localStorage`.
+ * - Supports infinite marquee animation; disable via `animation={{ enabled: false }}`.
+ *
+ * Customization:
+ * - Use `renderPreset` to fully control the button UI (selection handling is still managed internally).
+ * - Use `renderColorBox` to customize the color dots while keeping the default layout.
+ *
+ * @example
+ * ```tsx
+ * import { ThemePresetButtons } from "@fakhrirafiki/theme-engine";
+ *
+ * export function PresetsSection() {
+ *   return <ThemePresetButtons className="mt-6" maxPresets={24} />;
+ * }
+ * ```
+ */
 declare const ThemePresetButtons: ({ animation: animationOverrides, layout: layoutOverrides, renderPreset, renderColorBox, className, categories, maxPresets, showBuiltIn, showCustom, }: ThemePresetButtonsProps) => react_jsx_runtime.JSX.Element;
 
 type CustomPresetsRecord$1 = Record<string, TweakCNThemePreset>;
@@ -500,6 +614,28 @@ type LooseString$1 = string & {};
  * - Custom IDs are inferred from the keys of the `customPresets` argument
  *
  * The resulting `setThemePresetById()` still accepts any string, but VS Code will suggest known IDs first.
+ *
+ * Notes:
+ * - `customPresets` is only used for TypeScript inference (no runtime effect).
+ * - Prefer `useThemeEngine()` if you want a higher-level DX API with aliases.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ *
+ * import { useTypedTheme } from "@fakhrirafiki/theme-engine";
+ * import { customPresets } from "./custom-presets";
+ *
+ * export function PresetPicker() {
+ *   const { currentPreset, setThemePresetById } = useTypedTheme(customPresets);
+ *
+ *   return (
+ *     <button onClick={() => setThemePresetById("my-brand")}>
+ *       Active: {currentPreset?.presetName ?? "default"}
+ *     </button>
+ *   );
+ * }
+ * ```
  */
 declare function useTypedTheme<const TCustomPresets extends CustomPresetsRecord$1 | undefined = undefined>(customPresets?: TCustomPresets): {
     setThemePresetById: (presetId: LooseString$1 | ThemePresetId$1<TCustomPresets>) => void;
@@ -528,11 +664,26 @@ type LooseString = string & {};
 /**
  * Type helper to "register" your presets for autocomplete.
  *
- * Usage:
- * `useThemeEngine<ThemePresets<typeof customPresets>>()`
+ * @example
+ * ```ts
+ * import { type ThemePresets, useThemeEngine } from "@fakhrirafiki/theme-engine";
+ * import { customPresets } from "./custom-presets";
+ *
+ * type PresetRegistry = ThemePresets<typeof customPresets>;
+ *
+ * const theme = useThemeEngine<PresetRegistry>();
+ * // theme.applyThemeById("my-custom-id") // ✅ autocomplete for keys in customPresets + built-ins
+ * ```
  */
 type ThemePresets<T> = T extends CustomPresetsRecord ? T : never;
 type ThemeEnginePresetId<TCustomPresets extends CustomPresetsRecord | undefined = undefined> = ThemePresetId<TCustomPresets>;
+/**
+ * Accepts either:
+ * - a typed preset ID (built-in + inferred custom preset IDs), or
+ * - any string (runtime safety / forwards compatibility)
+ *
+ * This is useful when you receive preset IDs dynamically (e.g. from a URL param).
+ */
 type ThemeId<TCustomPresets extends CustomPresetsRecord | undefined = undefined> = ThemeEnginePresetId<TCustomPresets> | LooseString;
 /**
  * DX-first hook for Theme Engine.
@@ -543,6 +694,45 @@ type ThemeId<TCustomPresets extends CustomPresetsRecord | undefined = undefined>
  *
  * For typed preset ID autocomplete (built-in + your custom IDs):
  * `useThemeEngine<ThemePresets<typeof customPresets>>()`
+ *
+ * Naming:
+ * - `applyThemeById` and `applyPresetById` are aliases
+ * - `clearTheme` and `clearPreset` are aliases
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ *
+ * import { ThemeProvider, useThemeEngine, type ThemePresets } from "@fakhrirafiki/theme-engine";
+ * import { customPresets } from "./custom-presets";
+ *
+ * type Presets = ThemePresets<typeof customPresets>;
+ *
+ * function Controls() {
+ *   const { mode, resolvedMode, setDarkMode, applyThemeById, clearTheme } = useThemeEngine<Presets>();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setDarkMode("system")}>System</button>
+ *       <button onClick={() => setDarkMode("light")}>Light</button>
+ *       <button onClick={() => setDarkMode("dark")}>Dark</button>
+ *
+ *       <button onClick={() => applyThemeById("modern-minimal")}>Modern Minimal</button>
+ *       <button onClick={() => clearTheme()}>Reset</button>
+ *
+ *       <div>mode: {mode} · resolved: {resolvedMode}</div>
+ *     </div>
+ *   );
+ * }
+ *
+ * export default function Page() {
+ *   return (
+ *     <ThemeProvider customPresets={customPresets} defaultPreset="modern-minimal">
+ *       <Controls />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
  */
 declare function useThemeEngine<const TCustomPresets extends CustomPresetsRecord | undefined = undefined>(): {
     darkMode: boolean;
@@ -585,7 +775,14 @@ type ColorFormat = 'hsl' | 'rgb' | 'hex';
  */
 declare function formatColor(colorInput: string, outputFormat?: ColorFormat, includeFunctionWrapper?: boolean): string;
 /**
- * Create color with alpha transparency
+ * Create a color with alpha transparency.
+ *
+ * Notes:
+ * - This helper only supports HSL-like inputs that `parseHSL()` can parse
+ *   (e.g. `"hsl(210 40% 98%)"` or `"210 40% 98%"`).
+ * - For hex/rgb inputs, convert first with `formatColor(color, "hsl")`.
+ *
+ * @public
  */
 declare function withAlpha(colorInput: string, alpha: number): string;
 
@@ -595,7 +792,12 @@ declare function withAlpha(colorInput: string, alpha: number): string;
  */
 
 /**
- * Validation result type
+ * Validation result type.
+ *
+ * - `errors` should be treated as invalid input (preset should be rejected)
+ * - `warnings` indicate potentially incomplete presets but may still be usable
+ *
+ * @public
  */
 interface ValidationResult {
     isValid: boolean;
@@ -603,15 +805,30 @@ interface ValidationResult {
     warnings: string[];
 }
 /**
- * Validate a single TweakCN preset
+ * Validate a single preset in the TweakCN-compatible shape.
+ *
+ * Intended usage:
+ * - validating user-provided presets before passing them to `ThemeProvider`
+ * - debugging preset issues in development
+ *
+ * Notes:
+ * - This is a lightweight validator (it does not fully parse/compute CSS colors)
+ *
+ * @public
  */
 declare function validateTweakCNPreset(preset: any, presetId?: string): ValidationResult;
 /**
- * Validate a collection of custom presets
+ * Validate a collection of custom presets (record keyed by preset ID).
+ *
+ * @public
  */
 declare function validateCustomPresets(customPresets: Record<string, TweakCNThemePreset>): ValidationResult;
 /**
- * Helper function to log validation results
+ * Convenience logger for `ValidationResult`.
+ *
+ * This is primarily intended for local development diagnostics.
+ *
+ * @public
  */
 declare function logValidationResult(result: ValidationResult, context?: string): void;
 

package/dist/index.d.ts

@@ -234,15 +234,37 @@ interface ThemePresetButtonsProps {
     showSectionHeaders?: boolean;
 }
 
+/**
+ * Appearance mode.
+ *
+ * - `"system"` follows `prefers-color-scheme`
+ * - `resolvedMode` (from hooks/provider) is always `"light"` or `"dark"`
+ *
+ * @public
+ */
 type Mode = "light" | "dark" | "system";
+/**
+ * Screen coordinates used for the optional view-transition ripple when toggling modes.
+ *
+ * @public
+ */
 interface Coordinates {
     x: number;
     y: number;
 }
+/**
+ * Props for `ThemeToggle`.
+ *
+ * @public
+ */
 interface ThemeToggleProps {
+    /** Additional class name(s) applied to the button element */
     className?: string;
+    /** Styling hook exposed via `data-size` */
     size?: "sm" | "md" | "lg";
+    /** Styling hook exposed via `data-variant` */
     variant?: "default" | "outline" | "ghost";
+    /** Optional custom icon/content (overrides the default icon) */
     children?: ReactNode;
 }
 
@@ -366,13 +388,33 @@ type PresetId<TCustomPresets> = BuiltInPresetId | CustomPresetId$2<TCustomPreset
 interface UnifiedThemeProviderProps<TCustomPresets extends CustomPresetsRecord$2 | undefined = undefined> {
     /** React children to wrap with theming context */
     children: react__default.ReactNode;
-    /** Default appearance mode when no stored preference exists */
+    /**
+     * Default appearance mode when no stored preference exists.
+     *
+     * Notes for SSR/App Router:
+     * - The initial render must be deterministic between server and client to avoid hydration mismatches.
+     * - Persisted mode is restored after hydration (and also pre-hydration via the injected `ThemeScript`).
+     */
     defaultMode?: Mode;
-    /** Default preset ID to use when no stored preset exists or when resetting */
+    /**
+     * Default preset ID to use when no stored preset exists or when resetting.
+     *
+     * If provided, the preset will be applied when:
+     * - there is no persisted preset in `localStorage`, or
+     * - `clearPreset()` is called.
+     */
     defaultPreset?: PresetId<TCustomPresets>;
-    /** localStorage key for appearance mode persistence */
+    /**
+     * `localStorage` key for appearance mode persistence.
+     *
+     * Stored value is one of: `"light" | "dark" | "system"`.
+     */
     modeStorageKey?: string;
-    /** localStorage key for color preset persistence */
+    /**
+     * `localStorage` key for color preset persistence.
+     *
+     * Stored value is a JSON blob written by this provider and restored on subsequent loads.
+     */
     presetStorageKey?: string;
     /** Custom presets to add to the available collection */
     customPresets?: TCustomPresets;
@@ -391,6 +433,14 @@ interface UnifiedThemeProviderProps<TCustomPresets extends CustomPresetsRecord$2
  * - 🎨 **CSS `!important`** ensures presets override mode defaults
  * - 👀 **MutationObserver** automatically reapplies presets on mode changes
  *
+ * ## SSR / hydration behavior
+ * This provider is designed for Next.js App Router where Client Components are still SSR-ed.
+ * To avoid hydration mismatches:
+ * - The initial render does not read `localStorage`.
+ * - A pre-hydration `ThemeScript` is injected to apply the correct `html` mode class (`light`/`dark`)
+ *   and restore preset CSS variables as early as possible.
+ * - Persisted mode and preset are then reconciled after hydration.
+ *
  * @example
  * ```tsx
  * <ThemeProvider
@@ -411,6 +461,8 @@ declare function ThemeProvider<const TCustomPresets extends CustomPresetsRecord$
  * Provides access to both appearance mode controls and preset management
  * in a single, coordinated interface.
  *
+ * Prefer `useThemeEngine()` for a DX-first API with aliases and typed preset IDs.
+ *
  * @example
  * ```tsx
  * // Mode controls
@@ -476,17 +528,79 @@ interface ThemeScriptProps {
     defaultPreset?: string;
 }
 /**
- * Pre-hydration theme script.
- * - Restores appearance mode (light/dark/system) to avoid hydration mismatch + FOUC.
- * - Restores preset CSS variables early so Tailwind/shadcn tokens render correctly on first paint.
+ * Pre-hydration theme script injected by `ThemeProvider`.
+ *
+ * This runs before React hydration and is intentionally implemented as an inline script so it can:
+ * - restore the `html` mode class (`light`/`dark`) and `color-scheme` as early as possible
+ * - restore preset CSS variables early to prevent FOUC (unstyled/incorrect tokens on first paint)
+ *
+ * It reads:
+ * - `localStorage[modeStorageKey]` (mode persistence)
+ * - `localStorage[presetStorageKey]` (preset persistence)
+ *
+ * It writes:
+ * - `document.documentElement.classList` (`light`/`dark`)
+ * - `document.documentElement.style.colorScheme`
+ * - `document.documentElement.dataset.themeEngineMode` and `dataset.themeEngineResolvedMode` (best-effort)
+ *
+ * You typically do not render this manually — `ThemeProvider` includes it automatically.
  */
 declare function ThemeScript({ presetStorageKey, modeStorageKey, defaultMode, defaultPreset, }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * Button that toggles the current appearance mode (light ↔ dark) using Theme Engine.
+ *
+ * - Reads `mode` / `resolvedMode` from `ThemeProvider` via `useTheme()`
+ * - On click, calls `toggleMode({ x, y })` to enable the optional view-transition ripple
+ * - Renders an icon that reflects the current mode (`light`/`dark`/`system`) unless you pass `children`
+ *
+ * Data attributes:
+ * - `data-size`: `"sm" | "md" | "lg"` (for styling hooks)
+ * - `data-variant`: `"default" | "outline" | "ghost"`
+ * - `data-mode`: resolved mode (`"light" | "dark"`) for CSS hooks
+ * - `data-theme`: alias of `data-mode`
+ *
+ * @example
+ * ```tsx
+ * import { ThemeToggle } from "@fakhrirafiki/theme-engine";
+ *
+ * export function Header() {
+ *   return <ThemeToggle className="ml-auto" />;
+ * }
+ * ```
+ */
 declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & react.RefAttributes<HTMLButtonElement>>;
 
 /**
  * Main ThemePresetButtons component
  */
+/**
+ * Preset picker UI for Theme Engine.
+ *
+ * Renders a horizontally scrolling set of preset buttons (optionally in multiple rows) and applies
+ * the selected preset via `ThemeProvider` context.
+ *
+ * Requirements:
+ * - Must be used under `ThemeProvider` (it reads `availablePresets`/`currentPreset` from context).
+ *
+ * Behavior:
+ * - Built-in + custom presets are merged from context and displayed (custom presets are shown first).
+ * - Selecting a preset calls `applyPreset()` from the provider, which also persists it to `localStorage`.
+ * - Supports infinite marquee animation; disable via `animation={{ enabled: false }}`.
+ *
+ * Customization:
+ * - Use `renderPreset` to fully control the button UI (selection handling is still managed internally).
+ * - Use `renderColorBox` to customize the color dots while keeping the default layout.
+ *
+ * @example
+ * ```tsx
+ * import { ThemePresetButtons } from "@fakhrirafiki/theme-engine";
+ *
+ * export function PresetsSection() {
+ *   return <ThemePresetButtons className="mt-6" maxPresets={24} />;
+ * }
+ * ```
+ */
 declare const ThemePresetButtons: ({ animation: animationOverrides, layout: layoutOverrides, renderPreset, renderColorBox, className, categories, maxPresets, showBuiltIn, showCustom, }: ThemePresetButtonsProps) => react_jsx_runtime.JSX.Element;
 
 type CustomPresetsRecord$1 = Record<string, TweakCNThemePreset>;
@@ -500,6 +614,28 @@ type LooseString$1 = string & {};
  * - Custom IDs are inferred from the keys of the `customPresets` argument
  *
  * The resulting `setThemePresetById()` still accepts any string, but VS Code will suggest known IDs first.
+ *
+ * Notes:
+ * - `customPresets` is only used for TypeScript inference (no runtime effect).
+ * - Prefer `useThemeEngine()` if you want a higher-level DX API with aliases.
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ *
+ * import { useTypedTheme } from "@fakhrirafiki/theme-engine";
+ * import { customPresets } from "./custom-presets";
+ *
+ * export function PresetPicker() {
+ *   const { currentPreset, setThemePresetById } = useTypedTheme(customPresets);
+ *
+ *   return (
+ *     <button onClick={() => setThemePresetById("my-brand")}>
+ *       Active: {currentPreset?.presetName ?? "default"}
+ *     </button>
+ *   );
+ * }
+ * ```
  */
 declare function useTypedTheme<const TCustomPresets extends CustomPresetsRecord$1 | undefined = undefined>(customPresets?: TCustomPresets): {
     setThemePresetById: (presetId: LooseString$1 | ThemePresetId$1<TCustomPresets>) => void;
@@ -528,11 +664,26 @@ type LooseString = string & {};
 /**
  * Type helper to "register" your presets for autocomplete.
  *
- * Usage:
- * `useThemeEngine<ThemePresets<typeof customPresets>>()`
+ * @example
+ * ```ts
+ * import { type ThemePresets, useThemeEngine } from "@fakhrirafiki/theme-engine";
+ * import { customPresets } from "./custom-presets";
+ *
+ * type PresetRegistry = ThemePresets<typeof customPresets>;
+ *
+ * const theme = useThemeEngine<PresetRegistry>();
+ * // theme.applyThemeById("my-custom-id") // ✅ autocomplete for keys in customPresets + built-ins
+ * ```
  */
 type ThemePresets<T> = T extends CustomPresetsRecord ? T : never;
 type ThemeEnginePresetId<TCustomPresets extends CustomPresetsRecord | undefined = undefined> = ThemePresetId<TCustomPresets>;
+/**
+ * Accepts either:
+ * - a typed preset ID (built-in + inferred custom preset IDs), or
+ * - any string (runtime safety / forwards compatibility)
+ *
+ * This is useful when you receive preset IDs dynamically (e.g. from a URL param).
+ */
 type ThemeId<TCustomPresets extends CustomPresetsRecord | undefined = undefined> = ThemeEnginePresetId<TCustomPresets> | LooseString;
 /**
  * DX-first hook for Theme Engine.
@@ -543,6 +694,45 @@ type ThemeId<TCustomPresets extends CustomPresetsRecord | undefined = undefined>
  *
  * For typed preset ID autocomplete (built-in + your custom IDs):
  * `useThemeEngine<ThemePresets<typeof customPresets>>()`
+ *
+ * Naming:
+ * - `applyThemeById` and `applyPresetById` are aliases
+ * - `clearTheme` and `clearPreset` are aliases
+ *
+ * @example
+ * ```tsx
+ * "use client";
+ *
+ * import { ThemeProvider, useThemeEngine, type ThemePresets } from "@fakhrirafiki/theme-engine";
+ * import { customPresets } from "./custom-presets";
+ *
+ * type Presets = ThemePresets<typeof customPresets>;
+ *
+ * function Controls() {
+ *   const { mode, resolvedMode, setDarkMode, applyThemeById, clearTheme } = useThemeEngine<Presets>();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setDarkMode("system")}>System</button>
+ *       <button onClick={() => setDarkMode("light")}>Light</button>
+ *       <button onClick={() => setDarkMode("dark")}>Dark</button>
+ *
+ *       <button onClick={() => applyThemeById("modern-minimal")}>Modern Minimal</button>
+ *       <button onClick={() => clearTheme()}>Reset</button>
+ *
+ *       <div>mode: {mode} · resolved: {resolvedMode}</div>
+ *     </div>
+ *   );
+ * }
+ *
+ * export default function Page() {
+ *   return (
+ *     <ThemeProvider customPresets={customPresets} defaultPreset="modern-minimal">
+ *       <Controls />
+ *     </ThemeProvider>
+ *   );
+ * }
+ * ```
  */
 declare function useThemeEngine<const TCustomPresets extends CustomPresetsRecord | undefined = undefined>(): {
     darkMode: boolean;
@@ -585,7 +775,14 @@ type ColorFormat = 'hsl' | 'rgb' | 'hex';
  */
 declare function formatColor(colorInput: string, outputFormat?: ColorFormat, includeFunctionWrapper?: boolean): string;
 /**
- * Create color with alpha transparency
+ * Create a color with alpha transparency.
+ *
+ * Notes:
+ * - This helper only supports HSL-like inputs that `parseHSL()` can parse
+ *   (e.g. `"hsl(210 40% 98%)"` or `"210 40% 98%"`).
+ * - For hex/rgb inputs, convert first with `formatColor(color, "hsl")`.
+ *
+ * @public
  */
 declare function withAlpha(colorInput: string, alpha: number): string;
 
@@ -595,7 +792,12 @@ declare function withAlpha(colorInput: string, alpha: number): string;
  */
 
 /**
- * Validation result type
+ * Validation result type.
+ *
+ * - `errors` should be treated as invalid input (preset should be rejected)
+ * - `warnings` indicate potentially incomplete presets but may still be usable
+ *
+ * @public
  */
 interface ValidationResult {
     isValid: boolean;
@@ -603,15 +805,30 @@ interface ValidationResult {
     warnings: string[];
 }
 /**
- * Validate a single TweakCN preset
+ * Validate a single preset in the TweakCN-compatible shape.
+ *
+ * Intended usage:
+ * - validating user-provided presets before passing them to `ThemeProvider`
+ * - debugging preset issues in development
+ *
+ * Notes:
+ * - This is a lightweight validator (it does not fully parse/compute CSS colors)
+ *
+ * @public
  */
 declare function validateTweakCNPreset(preset: any, presetId?: string): ValidationResult;
 /**
- * Validate a collection of custom presets
+ * Validate a collection of custom presets (record keyed by preset ID).
+ *
+ * @public
  */
 declare function validateCustomPresets(customPresets: Record<string, TweakCNThemePreset>): ValidationResult;
 /**
- * Helper function to log validation results
+ * Convenience logger for `ValidationResult`.
+ *
+ * This is primarily intended for local development diagnostics.
+ *
+ * @public
  */
 declare function logValidationResult(result: ValidationResult, context?: string): void;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fakhrirafiki/theme-engine",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "Elegant theming system with smooth transitions, custom presets, semantic accent colors, and complete shadcn/ui support for modern React applications",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",