@zendir/ui 0.1.0

package/dist/react/theme/ThemeProvider.d.ts

@@ -0,0 +1,385 @@
+import { default as React, ReactNode } from 'react';
+
+export type ThemeVariant = 'astro' | 'purple-hue' | 'hybrid' | 'transparent' | 'transparent-bold' | 'transparent-minimal';
+export type ThemeMode = 'light' | 'dark';
+export interface ThemeColors {
+    background: {
+        base: string;
+        surface: string;
+        elevated: string;
+        overlay: string;
+    };
+    border: {
+        default: string;
+        muted: string;
+        focus: string;
+        /** Transparent theme: thin faded top-to-bottom border (box-shadow, use with border: 'none') */
+        fadedBoxShadow?: string;
+        /** Card border style (computed from theme – solid or transparent faded). Use ...tokens.colors.border.cardStyle */
+        cardStyle?: React.CSSProperties;
+        /** Card border for dashed/empty state. Use ...tokens.colors.border.cardStyleDashed */
+        cardStyleDashed?: React.CSSProperties;
+        /** Card border using default color (e.g. NavBall, EclipseTimer). Use ...tokens.colors.border.cardStyleDefault */
+        cardStyleDefault?: React.CSSProperties;
+    };
+    text: {
+        primary: string;
+        secondary: string;
+        tertiary: string;
+        /** Muted/placeholder text (alias for tertiary when not set) */
+        muted?: string;
+        inverse: string;
+    };
+    status: {
+        normal: string;
+        standby: string;
+        caution: string;
+        serious: string;
+        critical: string;
+        off: string;
+    };
+    semantic: {
+        success: string;
+        warning: string;
+        error: string;
+        info: string;
+    };
+    accent: {
+        primary: string;
+        secondary: string;
+        tertiary: string;
+    };
+    interactive: {
+        default: string;
+        hover: string;
+        active: string;
+        disabled: string;
+        /** Transparent theme: button/control bg (low opacity purple) when not hovered */
+        transparentDefault?: string;
+        /** Transparent theme: button/control bg on hover (higher opacity purple) */
+        transparentHover?: string;
+        /** Transparent theme: input field bg (semi-transparent purple tint) */
+        transparentInputBg?: string;
+    };
+}
+export interface ThemeAnimation {
+    /** Fast transitions (hover states) - 150ms */
+    fast: string;
+    /** Normal transitions (most interactions) - 250ms */
+    normal: string;
+    /** Slow transitions (page/mode changes) - 400ms */
+    slow: string;
+    /** Spring animation for playful interactions */
+    spring: string;
+    /** Easing function */
+    easing: {
+        default: string;
+        in: string;
+        out: string;
+        inOut: string;
+    };
+    /** Duration values in milliseconds */
+    duration: {
+        instant: number;
+        fast: number;
+        normal: number;
+        slow: number;
+    };
+}
+export interface ThemeFocus {
+    /** Focus ring color */
+    color: string;
+    /** Focus ring width */
+    width: string;
+    /** Focus ring offset */
+    offset: string;
+    /** Full focus ring CSS */
+    ring: string;
+    /** Focus ring style object */
+    style: React.CSSProperties;
+}
+/**
+ * Astro UX Typography Style Token
+ * Based on https://www.astrouxds.com/foundations/typography/
+ */
+export interface TypographyStyle {
+    fontSize: string;
+    fontWeight: number;
+    letterSpacing: string;
+    lineHeight: string;
+}
+export interface ThemeTokens {
+    colors: ThemeColors;
+    spacing: {
+        /** 2px — micro adjustments, decorative offsets */
+        xxs: string;
+        /** 4px — tight gaps, icon padding */
+        xs: string;
+        /** 8px — compact spacing, small gaps */
+        sm: string;
+        /** 12px — form fields, compact cards (between sm and md) */
+        smd: string;
+        /** 16px — default card padding, section gaps */
+        md: string;
+        /** 20px — slightly generous spacing */
+        mdl: string;
+        /** 24px — generous spacing, content area padding */
+        lg: string;
+        /** 32px — large section gaps */
+        xl: string;
+        /** 48px — extra large spacing */
+        xxl: string;
+    };
+    borderRadius: {
+        none: string;
+        /** 1px — very subtle rounding */
+        xs: string;
+        /** 2px — small elements, badges, tooltips */
+        sm: string;
+        /** 4px — inputs, selects, standard controls */
+        md: string;
+        /** 8px — cards, containers */
+        lg: string;
+        /** 12px — prominent surfaces, modals */
+        xl: string;
+        /** 9999px — pills, fully rounded */
+        full: string;
+    };
+    /** Standardised element heights for interactive controls */
+    elementSize: {
+        /** 28px — compact controls */
+        sm: string;
+        /** 36px — default controls */
+        md: string;
+        /** 44px — prominent controls, touch targets */
+        lg: string;
+    };
+    typography: {
+        fontFamily: {
+            primary: string;
+            mono: string;
+        };
+        display: {
+            1: TypographyStyle;
+            2: TypographyStyle;
+        };
+        heading: {
+            1: TypographyStyle;
+            '1Bold': TypographyStyle;
+            2: TypographyStyle;
+            3: TypographyStyle;
+            4: TypographyStyle;
+            5: TypographyStyle;
+            6: TypographyStyle;
+        };
+        body: {
+            1: TypographyStyle;
+            '1Bold': TypographyStyle;
+            2: TypographyStyle;
+            '2Bold': TypographyStyle;
+            3: TypographyStyle;
+            '3Bold': TypographyStyle;
+        };
+        control: {
+            1: TypographyStyle;
+            '1Bold': TypographyStyle;
+        };
+        fontSize: {
+            micro: string;
+            xxs: string;
+            xs: string;
+            sm: string;
+            base: string;
+            md: string;
+            lg: string;
+            xl: string;
+            xxl: string;
+            xxxl: string;
+        };
+        fontWeight: {
+            light: number;
+            normal: number;
+            medium: number;
+            semibold: number;
+            bold: number;
+        };
+        lineHeight: {
+            tight: string;
+            normal: string;
+            relaxed: string;
+        };
+        letterSpacing: {
+            tight: string;
+            normal: string;
+            wide: string;
+        };
+    };
+    shadows: {
+        none: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        glow: (color: string) => string;
+    };
+    animation: ThemeAnimation;
+    focus: ThemeFocus;
+    /** Semantic layout tokens for consistent spacing across cards, forms, and sections */
+    layout: LayoutTokens;
+    /** Semantic border tokens for consistent element styling (derived from theme colors) */
+    borders: BorderTokens;
+}
+export interface LayoutTokens {
+    /** Card / panel container spacing */
+    card: {
+        /** Internal padding of card containers */
+        padding: string;
+        /** Gap between cards in grid layouts (desktop) */
+        gap: string;
+        /** Gap between cards in grid layouts (mobile / compact) */
+        gapCompact: string;
+        /** Card heading: icon size, title typography, gap — single system for all cards/charts */
+        heading: {
+            iconSize: number;
+            iconSizeCompact: number;
+            titleFontSize: string;
+            /** Smaller title for chart headers (e.g. Power Trends) so they match card visual weight */
+            titleFontSizeChart: string;
+            titleFontWeight: number;
+            gap: number;
+        };
+    };
+    /** Section heading spacing (heading + divider + content) */
+    section: {
+        /** Padding below heading text, above the divider border */
+        headerPaddingBottom: string;
+        /** Margin below the divider border, before content */
+        headerMarginBottom: string;
+        /** Padding above the first content element after heading */
+        contentPaddingTop: string;
+    };
+    /** Form and input field spacing */
+    form: {
+        /** Vertical gap between stacked form fields */
+        fieldGap: string;
+        /** Horizontal gap between side-by-side inline fields */
+        inlineGap: string;
+        /** Padding inside grouped / nested field containers */
+        groupPadding: string;
+        /** Gap between items within a field group */
+        groupGap: string;
+        /** Gap between label text and helper icons (e.g. tooltip) */
+        labelGap: string;
+    };
+    /** Nested surface / panel spacing (e.g. grouped fields within a card) */
+    surface: {
+        /** Internal padding of nested surfaces */
+        padding: string;
+        /** Border radius of nested surfaces */
+        borderRadius: string;
+        /** Gap between items in compact nested surfaces */
+        gap: string;
+    };
+}
+export interface BorderTokens {
+    /** Border widths — standardised across all interactive elements */
+    width: {
+        /** Thin (1px) — inputs, cards, dividers, dropdowns */
+        thin: string;
+        /** Medium (1.5px) — secondary buttons, emphasised inputs */
+        medium: string;
+        /** Thick (2px) — checkboxes, accent borders, active tabs */
+        thick: string;
+    };
+    /** Pre-computed input / control borders (width + style + color) */
+    input: {
+        /** Default resting state */
+        default: string;
+        /** Hover state (accent at 50% opacity) */
+        hover: string;
+        /** Focused state (full accent) */
+        focus: string;
+        /** Error / critical state */
+        error: string;
+    };
+    /** Focus ring box-shadow values for interactive elements */
+    focusRing: {
+        /** Standard ring for inputs and selects */
+        default: string;
+        /** Ring for buttons (double-ring pattern) */
+        button: string;
+        /** Subtle ring for checkboxes, tabs, toggles */
+        subtle: string;
+    };
+    /** Section divider border (headings, dialog headers/footers, tab bars) */
+    divider: string;
+    /** Dropdown / popover container border */
+    dropdown: string;
+    /** Separator line inside elements (unit separators, table rows) */
+    separator: string;
+}
+export interface ThemeContextValue {
+    theme: ThemeVariant;
+    mode: ThemeMode;
+    tokens: ThemeTokens;
+    prefersReducedMotion: boolean;
+    /** Custom accent color override (null = use theme default) */
+    accentColor: string | null;
+    setTheme: (theme: ThemeVariant) => void;
+    setMode: (mode: ThemeMode) => void;
+    toggleMode: () => void;
+    /** Override the accent color for the current theme */
+    setAccentColor: (color: string | null) => void;
+}
+export interface ThemeProviderProps {
+    children: ReactNode;
+    /** Default theme variant */
+    theme?: ThemeVariant;
+    /** Default color mode */
+    mode?: ThemeMode;
+    /** Persist preferences to localStorage */
+    persist?: boolean;
+}
+/**
+ * useScrollbarStyles — returns inline React.CSSProperties for a
+ * scrollable container that matches the current Zendir theme.
+ *
+ * Use when you need programmatic control rather than the
+ * `zendir-scroll` CSS class.
+ *
+ * @example
+ * ```tsx
+ * const scrollStyle = useScrollbarStyles();
+ * <div style={{ maxHeight: 400, ...scrollStyle }}>…</div>
+ * ```
+ */
+export declare function useScrollbarStyles(): React.CSSProperties;
+/**
+ * ThemeProvider - Enterprise theme context provider
+ *
+ * Provides theme tokens, mode switching, and accessibility features
+ * to all child components.
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider theme="hybrid" mode="dark">  // Zen (Hybrid) is the default
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export declare function ThemeProvider({ children, theme: defaultTheme, mode: defaultMode, persist, }: ThemeProviderProps): React.ReactElement;
+/**
+ * useTheme - Access theme context
+ *
+ * @throws Error if used outside ThemeProvider
+ *
+ * @example
+ * ```tsx
+ * const { tokens, mode, toggleMode } = useTheme();
+ * ```
+ */
+export declare function useTheme(): ThemeContextValue;
+/**
+ * useThemeTokens - Access only theme tokens (for memoization)
+ */
+export declare function useThemeTokens(): ThemeTokens;