@tenerife.music/ui 1.0.8 → 1.0.13

package/dist/theme/index.d.cts

@@ -0,0 +1,453 @@
+import { M as Mode, C as ColorScale, B as BaseColorTokens, S as SurfaceColors, a as SemanticColors, T as TextColors } from '../colors-CVA7_16U.cjs';
+export { b as ChartColors, c as ColorTokens, d as cssVariableColorTokens, t as tailwindThemeColors } from '../colors-CVA7_16U.cjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default from 'react';
+
+/**
+ * Theme Override Types
+ *
+ * Defines types for theme overrides that can be applied to the token system.
+ */
+
+/**
+ * Theme name type
+ */
+type ThemeName = "default" | "dark" | "brand";
+
+/**
+ * Get initial mode from various sources
+ * Checks in order: DOM attribute, localStorage, system preference, default
+ */
+declare function getInitialMode(defaultMode?: Mode, storageKey?: string, enableSystem?: boolean): Mode;
+/**
+ * Get initial theme from various sources
+ */
+declare function getInitialTheme(defaultTheme?: "default" | "dark" | "brand", storageKey?: string): "default" | "dark" | "brand";
+/**
+ * Persist mode to localStorage
+ */
+declare function persistMode(mode: Mode, storageKey?: string): void;
+/**
+ * Persist theme to localStorage
+ */
+declare function persistTheme(theme: "default" | "dark" | "brand", storageKey?: string): void;
+/**
+ * Get initial brand from various sources
+ */
+declare function getInitialBrand(defaultBrand?: string | null, storageKey?: string): string | null;
+/**
+ * Persist brand to localStorage
+ */
+declare function persistBrand(brandId: string | null, storageKey?: string): void;
+
+/**
+ * Theme Schema
+ *
+ * Strict TypeScript schema for theme objects with validation.
+ * Ensures all themes conform to the token system and are type-safe.
+ */
+
+/**
+ * Theme metadata
+ */
+interface ThemeMetadata {
+    /**
+     * Unique theme identifier (kebab-case)
+     * Example: "ocean-blue", "sunset-orange"
+     */
+    id: string;
+    /**
+     * Human-readable theme name
+     * Example: "Ocean Blue", "Sunset Orange"
+     */
+    name: string;
+    /**
+     * Theme description
+     */
+    description?: string;
+    /**
+     * Theme category
+     * - "default": Standard themes
+     * - "brand": Brand-specific themes
+     * - "seasonal": Seasonal/holiday themes
+     * - "custom": User-created themes
+     */
+    category?: "default" | "brand" | "seasonal" | "custom";
+    /**
+     * Theme author (optional)
+     */
+    author?: string;
+    /**
+     * Theme version (semver)
+     */
+    version?: string;
+    /**
+     * Preview image URL (optional)
+     */
+    previewImage?: string;
+}
+/**
+ * Complete theme schema
+ * Extends ThemeOverride with metadata and validation
+ */
+interface ThemeSchema extends ThemeMetadata {
+    /**
+     * Override primary color scale
+     * Partial override - only specified values override base tokens
+     */
+    primaryColors?: Partial<ColorScale>;
+    /**
+     * Override accent color scale
+     */
+    accentColors?: Partial<ColorScale>;
+    /**
+     * Override secondary color scale
+     */
+    secondaryColors?: Partial<ColorScale>;
+    /**
+     * Override base colors (for day mode)
+     */
+    baseColorsDay?: Partial<BaseColorTokens>;
+    /**
+     * Override base colors (for night mode)
+     */
+    baseColorsNight?: Partial<BaseColorTokens>;
+    /**
+     * Override surface colors (for day mode)
+     */
+    surfaceColorsDay?: Partial<SurfaceColors>;
+    /**
+     * Override surface colors (for night mode)
+     */
+    surfaceColorsNight?: Partial<SurfaceColors>;
+    /**
+     * Override semantic colors (for day mode)
+     */
+    semanticColorsDay?: Partial<SemanticColors>;
+    /**
+     * Override semantic colors (for night mode)
+     */
+    semanticColorsNight?: Partial<SemanticColors>;
+    /**
+     * Override text colors (for day mode)
+     */
+    textColorsDay?: Partial<TextColors>;
+    /**
+     * Override text colors (for night mode)
+     */
+    textColorsNight?: Partial<TextColors>;
+}
+/**
+ * Theme validation result
+ */
+interface ThemeValidationResult {
+    /**
+     * Whether theme is valid
+     */
+    valid: boolean;
+    /**
+     * Validation errors
+     */
+    errors: string[];
+    /**
+     * Validation warnings
+     */
+    warnings: string[];
+}
+/**
+ * Validate theme schema
+ *
+ * @param theme - Theme to validate
+ * @returns Validation result
+ */
+declare function validateThemeSchema(theme: unknown): ThemeValidationResult;
+/**
+ * Type guard to check if object is ThemeSchema
+ */
+declare function isThemeSchema(obj: unknown): obj is ThemeSchema;
+/**
+ * Create a minimal valid theme schema
+ * Useful for CLI scaffolding
+ */
+declare function createMinimalThemeSchema(id: string, name: string): ThemeSchema;
+
+/**
+ * Theme Loader
+ *
+ * Loads themes from registry with error handling and fallback logic.
+ * Provides async loading support for dynamic themes.
+ */
+
+/**
+ * Theme loader options
+ */
+interface ThemeLoaderOptions {
+    /**
+     * Fallback theme ID if loading fails
+     */
+    fallbackThemeId?: string;
+    /**
+     * Whether to validate theme schema
+     */
+    validate?: boolean;
+    /**
+     * Whether to throw errors or return fallback
+     */
+    throwOnError?: boolean;
+}
+/**
+ * Theme loader result
+ */
+interface ThemeLoaderResult {
+    /**
+     * Loaded theme
+     */
+    theme: ThemeSchema;
+    /**
+     * Whether fallback was used
+     */
+    usedFallback: boolean;
+    /**
+     * Validation warnings (if validation enabled)
+     */
+    warnings: string[];
+}
+/**
+ * Load theme with error handling
+ *
+ * @param themeId - Theme ID to load
+ * @param options - Loader options
+ * @returns Theme loader result
+ */
+declare function loadThemeSafe(themeId: string, options?: ThemeLoaderOptions): Promise<ThemeLoaderResult>;
+/**
+ * Preload multiple themes
+ * Useful for prefetching themes that might be needed
+ *
+ * @param themeIds - Array of theme IDs to preload
+ */
+declare function preloadThemes(themeIds: string[]): Promise<void>;
+/**
+ * Get all available theme IDs
+ *
+ * @returns Array of theme IDs
+ */
+declare function getAvailableThemeIds(): string[];
+/**
+ * Check if theme can be loaded
+ *
+ * @param themeId - Theme ID to check
+ * @returns Whether theme can be loaded
+ */
+declare function canLoadTheme(themeId: string): Promise<boolean>;
+
+/**
+ * Theme Registry
+ *
+ * Central registry for all available themes.
+ * Provides metadata, dynamic imports, and theme discovery.
+ */
+
+/**
+ * Theme registry entry
+ */
+interface ThemeRegistryEntry {
+    /**
+     * Theme metadata
+     */
+    metadata: ThemeMetadata;
+    /**
+     * Dynamic import function for theme
+     */
+    loader: () => Promise<{
+        default: ThemeSchema;
+    }>;
+    /**
+     * Whether theme is enabled
+     */
+    enabled?: boolean;
+}
+/**
+ * Theme registry
+ * Maps theme IDs to their registry entries
+ */
+declare const themeRegistry: Map<string, ThemeRegistryEntry>;
+/**
+ * Register a theme in the registry
+ *
+ * @param entry - Theme registry entry
+ */
+declare function registerTheme(entry: ThemeRegistryEntry): void;
+/**
+ * Get theme metadata by ID
+ *
+ * @param id - Theme ID
+ * @returns Theme metadata or undefined
+ */
+declare function getThemeMetadata(id: string): ThemeMetadata | undefined;
+/**
+ * Get all registered themes
+ *
+ * @returns Array of theme metadata
+ */
+declare function getAllThemes(): ThemeMetadata[];
+/**
+ * Get themes by category
+ *
+ * @param category - Theme category
+ * @returns Array of theme metadata
+ */
+declare function getThemesByCategory(category: "default" | "brand" | "seasonal" | "custom"): ThemeMetadata[];
+/**
+ * Check if theme exists
+ *
+ * @param id - Theme ID
+ * @returns Whether theme exists
+ */
+declare function themeExists(id: string): boolean;
+/**
+ * Load theme by ID
+ *
+ * @param id - Theme ID
+ * @returns Theme schema
+ */
+declare function loadTheme(id: string): Promise<ThemeSchema>;
+/**
+ * Initialize default themes
+ * Registers built-in themes (default, dark, brand)
+ */
+declare function initializeDefaultThemes(): void;
+
+type SpacingScale = {
+    none: string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+    "4xl": string;
+    "5xl": string;
+};
+declare const spacing: SpacingScale;
+declare const borderRadius: {
+    none: string;
+    sm: string;
+    base: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+    full: string;
+};
+declare const shadows: {
+    none: string;
+    sm: string;
+    base: string;
+    md: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    inner: string;
+};
+
+/**
+ * Theme Context
+ */
+interface ThemeContextValue {
+    mode: Mode;
+    theme: ThemeName;
+    brand: string | null;
+    reduceMotion: boolean;
+    enableAnimations: boolean;
+    setMode: (mode: Mode) => void;
+    setTheme: (theme: ThemeName) => void;
+    setBrand: (brandId: string | null) => Promise<void>;
+    toggleMode: () => void;
+    setReduceMotion: (reduce: boolean) => void;
+    setEnableAnimations: (enable: boolean) => void;
+}
+/**
+ * Theme Provider Props
+ */
+interface ThemeProviderProps {
+    children: React__default.ReactNode;
+    defaultMode?: Mode;
+    defaultTheme?: ThemeName;
+    defaultBrand?: string | null;
+    storageKey?: string;
+    themeStorageKey?: string;
+    brandStorageKey?: string;
+    attribute?: string;
+    enableSystem?: boolean;
+    /**
+     * Override reduced motion preference
+     */
+    reduceMotion?: boolean;
+    /**
+     * Global animation toggle
+     */
+    enableAnimations?: boolean;
+}
+declare function ThemeProvider({ children, defaultMode, defaultTheme, defaultBrand, storageKey, themeStorageKey, brandStorageKey, attribute, enableSystem, reduceMotion: reduceMotionOverride, enableAnimations: enableAnimationsOverride, }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * useTheme Hook
+ *
+ * Provides access to theme context and theme control functions.
+ *
+ * @example
+ * ```tsx
+ * const { mode, theme, brand, setMode, setTheme, setBrand, toggleMode } = useTheme();
+ * ```
+ */
+declare function useTheme(): ThemeContextValue;
+
+type FontScale = {
+    xs: string;
+    sm: string;
+    base: string;
+    lg: string;
+    xl: string;
+    "2xl": string;
+    "3xl": string;
+    "4xl": string;
+    "5xl": string;
+    "6xl": string;
+};
+declare const fontFamilies: {
+    sans: string;
+    serif: string;
+    mono: string;
+};
+declare const fontSizes: FontScale;
+declare const fontWeights: {
+    thin: string;
+    extralight: string;
+    light: string;
+    normal: string;
+    medium: string;
+    semibold: string;
+    bold: string;
+    extrabold: string;
+    black: string;
+};
+declare const lineHeights: {
+    none: string;
+    tight: string;
+    snug: string;
+    normal: string;
+    relaxed: string;
+    loose: string;
+};
+declare const letterSpacings: {
+    tighter: string;
+    tight: string;
+    normal: string;
+    wide: string;
+    wider: string;
+    widest: string;
+};
+
+export { type FontScale, Mode, type SpacingScale, type ThemeLoaderOptions, type ThemeLoaderResult, type ThemeMetadata, ThemeProvider, type ThemeProviderProps, type ThemeRegistryEntry, type ThemeSchema, type ThemeValidationResult, borderRadius, canLoadTheme, createMinimalThemeSchema, fontFamilies, fontSizes, fontWeights, getAllThemes, getAvailableThemeIds, getInitialBrand, getInitialMode, getInitialTheme, getThemeMetadata, getThemesByCategory, initializeDefaultThemes, isThemeSchema, letterSpacings, lineHeights, loadTheme, loadThemeSafe, persistBrand, persistMode, persistTheme, preloadThemes, registerTheme, shadows, spacing, themeExists, themeRegistry, useTheme, validateThemeSchema };