@fakhrirafiki/theme-engine 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,501 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import react__default, { ReactNode } from 'react';
+
+/**
+ * Complete shadcn/ui color system - all semantic color tokens
+ *
+ * @public
+ */
+interface ShadcnColorSystem {
+    /** Base colors */
+    background: string;
+    foreground: string;
+    /** Card colors */
+    card: string;
+    'card-foreground': string;
+    popover: string;
+    'popover-foreground': string;
+    /** Brand colors */
+    primary: string;
+    'primary-foreground': string;
+    secondary: string;
+    'secondary-foreground': string;
+    /** Supporting colors */
+    muted: string;
+    'muted-foreground': string;
+    accent: string;
+    'accent-foreground': string;
+    /** System colors */
+    destructive: string;
+    'destructive-foreground': string;
+    border: string;
+    input: string;
+    ring: string;
+    /** Chart colors */
+    'chart-1': string;
+    'chart-2': string;
+    'chart-3': string;
+    'chart-4': string;
+    'chart-5': string;
+    /** Sidebar colors */
+    sidebar: string;
+    'sidebar-foreground': string;
+    'sidebar-primary': string;
+    'sidebar-primary-foreground': string;
+    'sidebar-accent': string;
+    'sidebar-accent-foreground': string;
+    'sidebar-border': string;
+    'sidebar-ring': string;
+}
+/**
+ * Typography system - font family definitions
+ *
+ * @public
+ */
+interface TypographySystem {
+    'font-sans': string;
+    'font-serif': string;
+    'font-mono': string;
+}
+/**
+ * Layout system - spacing and sizing
+ *
+ * @public
+ */
+interface LayoutSystem {
+    /** Border radius for components */
+    radius: string;
+}
+/**
+ * Shadow system - complete shadow definition
+ *
+ * @public
+ */
+interface ShadowSystem {
+    'shadow-color': string;
+    'shadow-opacity': string;
+    'shadow-blur': string;
+    'shadow-spread': string;
+    'shadow-offset-x': string;
+    'shadow-offset-y': string;
+}
+/**
+ * Spacing system - text and layout spacing
+ *
+ * @public
+ */
+interface SpacingSystem {
+    'letter-spacing': string;
+    spacing: string;
+}
+/**
+ * Complete shadcn/ui theme schema - all CSS custom properties
+ * Supports the full shadcn/ui theming system with 36+ properties
+ *
+ * @public
+ */
+interface CompleteThemeSchema extends ShadcnColorSystem, TypographySystem, LayoutSystem, ShadowSystem, SpacingSystem {
+    /** Allow additional custom properties */
+    [key: string]: string;
+}
+/**
+ * Theme preset interface with complete shadcn/ui support
+ *
+ * @public
+ */
+interface ThemePreset {
+    /** Unique preset identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Color scheme for light and dark modes */
+    colors: {
+        light: CompleteThemeSchema;
+        dark: CompleteThemeSchema;
+    };
+    /** Optional metadata for preset categorization */
+    metadata?: {
+        category?: string;
+        tags?: string[];
+        description?: string;
+        author?: string;
+        createdAt?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * Preset provider interface for data source abstraction
+ *
+ * @public
+ */
+interface PresetProvider {
+    /** Get all available presets */
+    getPresets(): ThemePreset[] | Promise<ThemePreset[]>;
+    /** Get specific preset by ID */
+    getPreset(id: string): ThemePreset | null | Promise<ThemePreset | null>;
+    /** Optional: Subscribe to preset changes */
+    onPresetChange?: (callback: (presets: ThemePreset[]) => void) => () => void;
+    /** Optional: Search/filter presets */
+    searchPresets?: (query: string) => ThemePreset[] | Promise<ThemePreset[]>;
+}
+/**
+ * Animation configuration for preset buttons
+ *
+ * @public
+ */
+interface AnimationConfig {
+    /** Enable/disable animations */
+    enabled: boolean;
+    /** Animation duration in seconds */
+    duration: number;
+    /** CSS easing function */
+    easing: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | string;
+    /** Number of preset rows */
+    rowCount: number;
+    /** Scroll speed multiplier */
+    scrollSpeed: number;
+    /** Pause animation on hover */
+    hoverPause: boolean;
+    /** Duplication factor for infinite scroll */
+    duplicationFactor: number;
+}
+/**
+ * Layout configuration for preset buttons
+ *
+ * @public
+ */
+interface LayoutConfig {
+    /** Button width in pixels */
+    buttonWidth: number;
+    /** Gap between buttons in pixels */
+    buttonGap: number;
+    /** Gap between rows in pixels */
+    rowGap: number;
+    /** Show color preview boxes */
+    showColorBoxes: boolean;
+    /** Number of color boxes to show */
+    colorBoxCount: number;
+    /** Gradient mask for edge fading */
+    enableMask: boolean;
+}
+/**
+ * Theme preset buttons component props - Zero-config design
+ *
+ * State management (preset provider, selection, and mode) is handled internally
+ * via ThemeProvider context. Just configure appearance and behavior!
+ *
+ * @public
+ */
+interface ThemePresetButtonsProps {
+    /** Animation configuration */
+    animation?: Partial<AnimationConfig>;
+    /** Layout configuration */
+    layout?: Partial<LayoutConfig>;
+    /** Custom preset renderer */
+    renderPreset?: (preset: ThemePreset, isSelected: boolean) => ReactNode;
+    /** Custom color box renderer */
+    renderColorBox?: (color: string, index: number) => ReactNode;
+    /** Additional CSS class */
+    className?: string;
+    /** Filter presets by categories */
+    categories?: string[];
+    /** Maximum number of presets to show */
+    maxPresets?: number;
+    /** Show built-in presets (default: true) */
+    showBuiltIn?: boolean;
+    /** Show custom presets (default: true) */
+    showCustom?: boolean;
+    /** Group presets by category or provider (default: 'none') */
+    groupBy?: 'none' | 'category' | 'provider';
+    /** Custom section labels */
+    labels?: {
+        /** Label for built-in presets section (default: "Built-in Themes") */
+        builtIn?: string;
+        /** Label for custom presets section (default: "Custom Themes") */
+        custom?: string;
+    };
+    /** Show section headers when grouping is enabled (default: true) */
+    showSectionHeaders?: boolean;
+}
+
+type Mode = "light" | "dark" | "system";
+interface Coordinates {
+    x: number;
+    y: number;
+}
+interface ThemeToggleProps {
+    className?: string;
+    size?: "sm" | "md" | "lg";
+    variant?: "default" | "outline" | "ghost";
+    children?: ReactNode;
+}
+
+/**
+ * TweakCN Compatible Preset Collection
+ *
+ * This file matches TweakCN's exact structure to make it easy to copy-paste
+ * the complete defaultPresets from TweakCN's theme-presets.ts file.
+ *
+ * Structure: Record<string, TweakCNThemePreset>
+ *
+ * Usage:
+ * 1. Copy the entire defaultPresets object from TweakCN's theme-presets.ts
+ * 2. Paste it into the tweakcnPresets constant below
+ * 3. The conversion utilities will handle the rest
+ */
+/**
+ * TweakCN's ThemePreset interface structure (exact match with TweakCN)
+ */
+interface TweakCNThemePreset {
+    /** Display name for the preset */
+    label: string;
+    /** Theme styles for light and dark modes */
+    styles: {
+        light: Record<string, string>;
+        dark: Record<string, string>;
+    };
+    /** Optional creation date (present in some TweakCN presets) */
+    createdAt?: string;
+}
+/**
+ * TweakCN Compatible Preset Collection
+ *
+ * 🚀 COPY-PASTE READY:
+ * Replace this object with the complete defaultPresets from TweakCN
+ */
+declare const tweakcnPresets: Record<string, TweakCNThemePreset>;
+/**
+ * Get all preset IDs
+ */
+declare function getPresetIds(): string[];
+/**
+ * Get preset by ID
+ */
+declare function getPresetById(id: string): TweakCNThemePreset | null;
+/**
+ * Get all preset labels
+ */
+declare function getPresetLabels(): string[];
+/**
+ * Search presets by name (case-insensitive)
+ */
+declare function searchPresets(query: string): Array<{
+    id: string;
+    preset: TweakCNThemePreset;
+}>;
+/**
+ * Get presets count
+ */
+declare function getPresetsCount(): number;
+/**
+ * Get preset entries (id + preset pairs)
+ */
+declare function getPresetEntries(): Array<[string, TweakCNThemePreset]>;
+
+/**
+ * Context value for the unified theming system.
+ * Provides access to both appearance mode (light/dark) and color presets.
+ *
+ * @public
+ */
+interface UnifiedThemeContextValue {
+    /** Current appearance mode setting */
+    mode: Mode;
+    /** Resolved appearance mode (never 'system') */
+    resolvedMode: 'light' | 'dark';
+    /** Change the appearance mode */
+    setMode: (mode: Mode) => void;
+    /** Toggle between light and dark modes with optional animation */
+    toggleMode: (coordinates?: Coordinates) => void;
+    /** Currently applied preset (null if using default colors) */
+    currentPreset: {
+        /** Unique identifier for the preset */
+        presetId: string;
+        /** Human-readable preset name */
+        presetName: string;
+        /** Color values for light and dark modes */
+        colors: ThemePreset['colors'];
+        /** Timestamp when preset was applied */
+        appliedAt: number;
+    } | null;
+    /** Apply a new color preset */
+    applyPreset: (preset: ThemePreset) => void;
+    /** Clear the current preset and revert to default colors */
+    clearPreset: () => void;
+    /** Available presets (merged built-in + custom) */
+    availablePresets: Record<string, TweakCNThemePreset>;
+    /** Built-in presets only */
+    builtInPresets: Record<string, TweakCNThemePreset>;
+    /** Custom presets only */
+    customPresets: Record<string, TweakCNThemePreset>;
+}
+/**
+ * Props for the UnifiedThemeProvider component.
+ *
+ * @public
+ */
+interface UnifiedThemeProviderProps {
+    /** React children to wrap with theming context */
+    children: react__default.ReactNode;
+    /** Default appearance mode when no stored preference exists */
+    defaultMode?: Mode;
+    /** Default preset ID to use when no stored preset exists or when resetting */
+    defaultPreset?: string;
+    /** Enable smooth transitions between modes */
+    enableTransitions?: boolean;
+    /** localStorage key for appearance mode persistence */
+    modeStorageKey?: string;
+    /** localStorage key for color preset persistence */
+    presetStorageKey?: string;
+    /** Enable custom color preset functionality */
+    enablePresets?: boolean;
+    /** Custom presets to add to the available collection */
+    customPresets?: Record<string, TweakCNThemePreset>;
+    /** Whether to include built-in TweakCN presets (default: true) */
+    includeBuiltInPresets?: boolean;
+}
+/**
+ * Theme Provider - The heart of the elegant theming system.
+ *
+ * Coordinates two theming concerns seamlessly:
+ * 1. **Appearance Mode** (light/dark/system) - Controls the base color scheme
+ * 2. **Color Presets** - Customizes the actual colors within that scheme
+ *
+ * ## Key Features
+ * - 🤝 **Perfect coordination** between appearance modes and presets
+ * - 💾 **Reliable persistence** with separate localStorage keys
+ * - ⚡ **SSR-safe** with pre-hydration script support
+ * - 🎨 **CSS `!important`** ensures presets override mode defaults
+ * - 👀 **MutationObserver** automatically reapplies presets on mode changes
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider
+ *   defaultMode="system"
+ *   modeStorageKey="app-mode"
+ *   presetStorageKey="app-preset"
+ *   enablePresets={true}
+ * >
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ *
+ * @public
+ */
+declare function ThemeProvider({ children, defaultMode, defaultPreset, enableTransitions, modeStorageKey, presetStorageKey, enablePresets, customPresets, includeBuiltInPresets, }: UnifiedThemeProviderProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * Hook for accessing the unified theming system.
+ *
+ * Provides access to both appearance mode controls and preset management
+ * in a single, coordinated interface.
+ *
+ * @example
+ * ```tsx
+ * // Mode controls
+ * function ModeControls() {
+ *   const { mode, setMode } = useTheme()
+ *
+ *   return (
+ *     <button onClick={() => setMode(mode === 'light' ? 'dark' : 'light')}>
+ *       Toggle Mode
+ *     </button>
+ *   )
+ * }
+ *
+ * // Preset management
+ * function PresetSelector() {
+ *   const {
+ *     currentPreset,  // Active color preset
+ *     applyPreset,    // Apply new preset
+ *     clearPreset     // Reset to defaults
+ *   } = useTheme()
+ *
+ *   return (
+ *     <div>
+ *       <p>Active: {currentPreset?.presetName || 'Default'}</p>
+ *       <ThemePresetButtons
+ *         selectedPresetId={currentPreset?.presetId || null}
+ *         onPresetSelect={applyPreset}
+ *       />
+ *       {currentPreset && (
+ *         <button onClick={clearPreset}>Reset</button>
+ *       )}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @throws Error if used outside of ThemeProvider
+ * @returns The theme context value
+ *
+ * @public
+ */
+declare function useTheme(): UnifiedThemeContextValue;
+
+interface ThemeScriptProps {
+    /**
+     * Storage key for theme preset persistence
+     * @default 'theme-preset'
+     */
+    presetStorageKey?: string;
+    /**
+     * Default preset ID to apply when no stored preset exists
+     */
+    defaultPreset?: string;
+}
+/**
+ * Simplified theme script that only handles preset restoration
+ * Works in harmony with ThemeProvider for dark/light mode
+ */
+declare function ThemeScript({ presetStorageKey, defaultPreset }: ThemeScriptProps): react_jsx_runtime.JSX.Element;
+
+declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & react.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Main ThemePresetButtons component
+ */
+declare const ThemePresetButtons: ({ animation: animationOverrides, layout: layoutOverrides, renderPreset, renderColorBox, className, categories, maxPresets, showBuiltIn, showCustom, groupBy, labels, showSectionHeaders, }: ThemePresetButtonsProps) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Lightweight color utilities for theme-engine
+ * Provides basic color manipulation without heavy dependencies
+ */
+type ColorFormat = 'hsl' | 'rgb' | 'hex';
+/**
+ * Universal color formatter
+ * Attempts to parse any color format and output in specified format
+ */
+declare function formatColor(colorInput: string, outputFormat?: ColorFormat, includeFunctionWrapper?: boolean): string;
+/**
+ * Create color with alpha transparency
+ */
+declare function withAlpha(colorInput: string, alpha: number): string;
+
+/**
+ * Preset validation utilities for theme-engine
+ * Provides validation and error handling for custom presets
+ */
+
+/**
+ * Validation result type
+ */
+interface ValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Validate a single TweakCN preset
+ */
+declare function validateTweakCNPreset(preset: any, presetId?: string): ValidationResult;
+/**
+ * Validate a collection of custom presets
+ */
+declare function validateCustomPresets(customPresets: Record<string, TweakCNThemePreset>): ValidationResult;
+/**
+ * Helper function to log validation results
+ */
+declare function logValidationResult(result: ValidationResult, context?: string): void;
+
+export { type CompleteThemeSchema, type Coordinates, type Mode, type PresetProvider, type ThemePreset, ThemePresetButtons, type ThemePresetButtonsProps, ThemeProvider, ThemeScript, ThemeToggle, type ThemeToggleProps, type TweakCNThemePreset, type ValidationResult, formatColor, getPresetById, getPresetEntries, getPresetIds, getPresetLabels, getPresetsCount, logValidationResult, searchPresets, tweakcnPresets, useTheme, validateCustomPresets, validateTweakCNPreset, withAlpha };