@structyl/themes 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import * as React from 'react';
+
+type ThemeMode = 'light' | 'dark' | 'system';
+type ResolvedMode = 'light' | 'dark';
+type Theme = string;
+interface ThemeTokens {
+    bg: string;
+    fg: string;
+    card: string;
+    'card-fg': string;
+    popover: string;
+    'popover-fg': string;
+    primary: string;
+    'primary-fg': string;
+    'primary-hover': string;
+    'primary-active': string;
+    secondary: string;
+    'secondary-fg': string;
+    muted: string;
+    'muted-fg': string;
+    accent: string;
+    'accent-fg': string;
+    destructive: string;
+    'destructive-fg': string;
+    success: string;
+    'success-fg': string;
+    warning: string;
+    'warning-fg': string;
+    info: string;
+    'info-fg': string;
+    border: string;
+    'border-strong': string;
+    input: string;
+    ring: string;
+    overlay: string;
+    shadow: string;
+    'primary-light': string;
+    'primary-dark': string;
+    'primary-contrast': string;
+    'primary-dark-bg': string;
+    'secondary-light': string;
+    'secondary-dark': string;
+    'secondary-contrast': string;
+    'secondary-dark-bg': string;
+    'error-light': string;
+    'error-dark': string;
+    'error-contrast': string;
+    'error-dark-bg': string;
+    'warning-light': string;
+    'warning-dark': string;
+    'warning-contrast': string;
+    'warning-dark-bg': string;
+    'info-light': string;
+    'info-dark': string;
+    'info-contrast': string;
+    'info-dark-bg': string;
+    'success-light': string;
+    'success-dark': string;
+    'success-contrast': string;
+    'success-dark-bg': string;
+    'primary-state-contained': string;
+    'primary-state-outlined': string;
+    'primary-state-resting': string;
+    'primary-shade-12': string;
+    'primary-shade-16': string;
+    'secondary-state-contained': string;
+    'secondary-state-outlined': string;
+    'secondary-state-resting': string;
+    'secondary-shade-12': string;
+    'secondary-shade-16': string;
+    'error-state-contained': string;
+    'error-state-outlined': string;
+    'error-state-resting': string;
+    'error-alert-bg': string;
+    'error-alert-content': string;
+    'error-shade-12': string;
+    'error-shade-16': string;
+    'warning-state-contained': string;
+    'warning-state-outlined': string;
+    'warning-state-resting': string;
+    'warning-alert-bg': string;
+    'warning-alert-content': string;
+    'warning-shade-12': string;
+    'warning-shade-16': string;
+    'info-state-contained': string;
+    'info-state-outlined': string;
+    'info-state-resting': string;
+    'info-alert-bg': string;
+    'info-alert-content': string;
+    'info-shade-12': string;
+    'info-shade-16': string;
+    'success-state-contained': string;
+    'success-state-outlined': string;
+    'success-state-resting': string;
+    'success-alert-bg': string;
+    'success-alert-content': string;
+    'success-shade-12': string;
+    'success-shade-16': string;
+    text: string;
+    'text-secondary': string;
+    'text-disabled': string;
+    'text-info': string;
+    'text-fill': string;
+    'text-shade-12': string;
+    'text-shade-16': string;
+    surface: string;
+    'surface-paper': string;
+    divider: string;
+    'outlined-border': string;
+    'input-line': string;
+    'action-active': string;
+    'action-hover': string;
+    'action-selected': string;
+    'action-disabled': string;
+    'action-disabled-bg': string;
+    'action-focus': string;
+    backdrop: string;
+    'rating-active': string;
+    'snackbar-bg': string;
+    'map-grid': string;
+    'table-top-header': string;
+    'table-header': string;
+    'table-row': string;
+    'table-col-border': string;
+    'table-border': string;
+    [key: string]: string;
+}
+interface ThemeConfig {
+    light: Partial<ThemeTokens> & Record<string, string>;
+    dark: Partial<ThemeTokens> & Record<string, string>;
+}
+
+interface ThemeContextValue {
+    theme: Theme;
+    setTheme: (theme: Theme) => void;
+    mode: ThemeMode;
+    setMode: (mode: ThemeMode) => void;
+    resolvedMode: ResolvedMode;
+    themes: string[];
+}
+interface ThemeProviderProps {
+    children: React.ReactNode;
+    defaultTheme?: Theme;
+    defaultMode?: ThemeMode;
+    storageKey?: string | false;
+    enableTransitions?: boolean;
+    themes?: Record<string, ThemeConfig>;
+    attribute?: string;
+}
+declare function ThemeProvider(props: ThemeProviderProps): React.JSX.Element;
+
+declare function useTheme(): ThemeContextValue;
+
+interface ThemeScriptProps {
+    defaultTheme?: string;
+    defaultMode?: ThemeMode;
+    storageKey?: string;
+    attribute?: string;
+}
+/**
+ * Renders a <style> block with the default theme's CSS variables plus an inline
+ * script that updates them from localStorage before first paint. Place inside
+ * <head> of your root layout to prevent flash of unstyled content.
+ */
+declare function ThemeScript({ defaultTheme, defaultMode, storageKey, attribute, }: ThemeScriptProps): React.JSX.Element;
+
+interface PaletteColor {
+    main: string;
+    light: string;
+    dark: string;
+    contrastText: string;
+    darkBackground?: string;
+    state: {
+        containedHover: string;
+        outlinedHover: string;
+        outlinedResting: string;
+    };
+    shade: {
+        12: string;
+        16: string;
+    };
+}
+interface AlertPaletteColor extends PaletteColor {
+    alert: {
+        background: string;
+        content: string;
+    };
+}
+interface StructylScale {
+    '50': string;
+    '100': string;
+    '200': string;
+    '300': string;
+    '400': string;
+    '500': string;
+    '600': string;
+    '700': string;
+    '800': string;
+    '900': string;
+    A100: string;
+    A200: string;
+    A400: string;
+    A700: string;
+}
+interface StaticPalette {
+    yellow: StructylScale;
+    amber: StructylScale;
+    blue: StructylScale;
+    blueGrey: StructylScale;
+    brown: StructylScale;
+    teal: StructylScale;
+    red: StructylScale;
+    purple: StructylScale;
+    pink: StructylScale;
+    orange: StructylScale;
+    lime: StructylScale;
+    lightGreen: StructylScale;
+    cyan: StructylScale;
+    deepOrange: StructylScale;
+    deepPurple: StructylScale;
+    green: StructylScale;
+    grey: StructylScale;
+    indigo: StructylScale;
+    lightBlue: StructylScale;
+}
+
+declare const defaultThemes: Record<string, ThemeConfig>;
+
+declare const sharedSemanticLight: Partial<ThemeTokens>;
+declare const sharedSemanticDark: Partial<ThemeTokens>;
+declare const staticPalette: StaticPalette;
+declare const generalColors: {
+    readonly 'yellow-golden': "rgba(255, 215, 0, 0.6)";
+    readonly 'yellow-pale': "rgba(255, 255, 153, 0.4)";
+    readonly 'yellow-amber': "rgba(255, 191, 0, 0.7)";
+    readonly 'yellow-sunshine': "rgba(255, 239, 0, 0.5)";
+    readonly 'yellow-light': "rgba(255, 255, 0, 0.5)";
+    readonly 'yellow-warm': "rgba(255, 204, 0, 0.8)";
+    readonly 'yellow-soft': "rgba(255, 229, 153, 0.7)";
+    readonly 'red-rose': "rgba(255, 51, 51, 0.5)";
+    readonly 'red-crimson': "rgba(220, 20, 60, 0.6)";
+    readonly 'red-light-coral': "rgba(240, 128, 128, 0.5)";
+    readonly 'red-fire-brick': "rgba(178, 34, 34, 0.8)";
+    readonly 'red-bright': "rgba(255, 0, 0, 0.7)";
+    readonly 'red-soft-coral': "rgba(255, 102, 102, 0.6)";
+    readonly 'red-dark': "rgba(204, 0, 0, 0.8)";
+    readonly 'blue-turquoise': "rgba(64, 224, 208, 0.6)";
+    readonly 'blue-dodger': "rgba(30, 144, 255, 0.5)";
+    readonly 'blue-navy': "rgba(0, 0, 128, 0.8)";
+    readonly 'blue-steel': "rgba(70, 130, 180, 0.7)";
+    readonly 'blue-sky': "rgba(0, 153, 255, 0.5)";
+    readonly 'blue-light': "rgba(51, 204, 255, 0.7)";
+    readonly 'blue-deep': "rgba(0, 51, 204, 0.8)";
+    readonly 'green-lime': "rgba(50, 205, 50, 0.5)";
+    readonly 'green-pale': "rgba(152, 251, 152, 0.4)";
+    readonly 'green-forest': "rgba(34, 139, 34, 0.7)";
+    readonly 'green-olive': "rgba(128, 128, 0, 0.6)";
+    readonly 'green-fresh': "rgba(0, 204, 0, 0.6)";
+    readonly 'green-soft-mint': "rgba(102, 255, 153, 0.7)";
+    readonly 'green-dark': "rgba(0, 153, 76, 0.8)";
+    readonly 'orange-tangerine': "rgba(255, 140, 0, 0.6)";
+    readonly 'orange-apricot': "rgba(251, 206, 177, 0.5)";
+    readonly 'orange-burnt': "rgba(204, 85, 0, 0.7)";
+    readonly 'orange-carrot': "rgba(237, 145, 33, 0.6)";
+    readonly 'orange-bright': "rgba(255, 102, 0, 0.7)";
+    readonly 'orange-soft-peach': "rgba(255, 178, 102, 0.6)";
+    readonly 'orange-deep': "rgba(204, 85, 0, 0.8)";
+};
+
+/**
+ * Color accent presets for @structyl/themes.
+ *
+ * Built-in presets cover 10 common accent colors. Users can extend the list
+ * by creating additional `ColorPreset` objects and passing them to
+ * `useColorPreset({ extraPresets: [...] })` or calling `applyColorPreset`
+ * with any arbitrary hex color.
+ */
+/** A single accent-color preset. */
+interface ColorPreset {
+    /** Unique machine-readable identifier. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Primary hex color value (e.g. `'#6366f1'`). */
+    hex: string;
+}
+/**
+ * The 10 built-in accent presets shipped with @structyl/themes.
+ * Typed `as const` so that `ColorPresetId` is a precise union of literal IDs.
+ */
+declare const COLOR_PRESETS: readonly [{
+    readonly id: "structyl";
+    readonly name: "Structyl";
+    readonly hex: "#5754a3";
+}, {
+    readonly id: "indigo";
+    readonly name: "Indigo";
+    readonly hex: "#6366f1";
+}, {
+    readonly id: "ocean";
+    readonly name: "Ocean";
+    readonly hex: "#0284c7";
+}, {
+    readonly id: "rose";
+    readonly name: "Rose";
+    readonly hex: "#e11d48";
+}, {
+    readonly id: "forest";
+    readonly name: "Forest";
+    readonly hex: "#16a34a";
+}, {
+    readonly id: "sunset";
+    readonly name: "Sunset";
+    readonly hex: "#f97316";
+}, {
+    readonly id: "violet";
+    readonly name: "Violet";
+    readonly hex: "#7c3aed";
+}, {
+    readonly id: "slate";
+    readonly name: "Slate";
+    readonly hex: "#475569";
+}, {
+    readonly id: "ember";
+    readonly name: "Ember";
+    readonly hex: "#be123c";
+}, {
+    readonly id: "zinc";
+    readonly name: "Zinc";
+    readonly hex: "#71717a";
+}];
+/** Union of all built-in preset IDs (e.g. `'structyl' | 'indigo' | 'ocean' | ...`). */
+type ColorPresetId = (typeof COLOR_PRESETS)[number]['id'];
+/**
+ * Create a custom preset object. Useful for building typed preset lists
+ * that will be passed to `useColorPreset({ extraPresets: [...] })`.
+ *
+ * @example
+ * const myPreset = createColorPreset('brand', 'My Brand', '#ff5500');
+ */
+declare function createColorPreset(id: string, name: string, hex: string): ColorPreset;
+/**
+ * Apply an accent preset to the document root by overriding the five
+ * primary-color CSS custom properties.  Safe to call on every theme/mode
+ * change — the ThemeProvider will reset base vars first, then this re-applies.
+ *
+ * No-op in SSR environments.
+ *
+ * @param hex - The hex color string (e.g. `'#6366f1'`).
+ */
+declare function applyColorPreset(hex: string): void;
+/**
+ * Remove all CSS custom properties applied by `applyColorPreset`,
+ * restoring whatever values the active ThemeProvider theme supplies.
+ *
+ * No-op in SSR environments.
+ */
+declare function clearColorPreset(): void;
+
+interface UseColorPresetOptions {
+    /**
+     * Custom presets to add on top of the 10 built-ins.
+     * Built-ins always come first in `presets`.
+     *
+     * @example
+     * const brandPreset = createColorPreset('brand', 'Brand Blue', '#1a6cf0');
+     * const { setPreset } = useColorPreset({ extraPresets: [brandPreset] });
+     */
+    extraPresets?: ColorPreset[];
+    /**
+     * localStorage key used to persist the active preset across page loads.
+     * Override if you need multiple independent pickers on the same origin.
+     *
+     * @default 'structyl-color-preset'
+     */
+    storageKey?: string;
+}
+interface UseColorPresetReturn {
+    /** All available presets: built-ins first, then any `extraPresets`. */
+    presets: ColorPreset[];
+    /** ID of the currently active preset, or `null` when using the default theme. */
+    activeId: string | null;
+    /** Full preset object for the active ID, or `null`. */
+    activePreset: ColorPreset | null;
+    /**
+     * Activate a preset by its `id` and `hex` color.
+     * Applies CSS variables immediately and persists to localStorage.
+     */
+    setPreset: (id: string, hex: string) => void;
+    /**
+     * Clear the active preset, restoring the ThemeProvider's base theme colors.
+     * Also removes the stored value from localStorage.
+     */
+    clearPreset: () => void;
+}
+/**
+ * Manages an accent-color preset on top of the active structyl theme.
+ *
+ * Must be used inside a `<ThemeProvider>`. Persists the selection to
+ * localStorage and re-applies it whenever the base theme or color-mode
+ * changes (because ThemeProvider resets `--color-primary` on change).
+ *
+ * @example
+ * function AccentPicker() {
+ *   const { presets, activeId, setPreset, clearPreset } = useColorPreset();
+ *   return (
+ *     <>
+ *       {presets.map(p => (
+ *         <button key={p.id} onClick={() => setPreset(p.id, p.hex)}
+ *           style={{ background: p.hex }}>
+ *           {p.name}
+ *         </button>
+ *       ))}
+ *       {activeId && <button onClick={clearPreset}>Reset</button>}
+ *     </>
+ *   );
+ * }
+ *
+ * @example Adding custom presets
+ * const brandPreset = createColorPreset('brand', 'Company Blue', '#1a6cf0');
+ * const { presets } = useColorPreset({ extraPresets: [brandPreset] });
+ */
+declare function useColorPreset(options?: UseColorPresetOptions): UseColorPresetReturn;
+
+export { type AlertPaletteColor, COLOR_PRESETS, type ColorPreset, type ColorPresetId, type PaletteColor, type StaticPalette, type StructylScale, type Theme, type ThemeConfig, type ThemeMode, ThemeProvider, ThemeScript, type ThemeTokens, type UseColorPresetOptions, type UseColorPresetReturn, applyColorPreset, clearColorPreset, createColorPreset, defaultThemes, generalColors, sharedSemanticDark, sharedSemanticLight, staticPalette, useColorPreset, useTheme };