@aurora-ds/theme 1.0.3

package/dist/index.d.ts

@@ -0,0 +1,685 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, CSSProperties } from 'react';
+export { CSSProperties } from 'react';
+
+/**
+ * Base color tokens following modern design system semantics
+ */
+type BaseColors = {
+    primary: string;
+    onPrimary: string;
+    primaryHover: string;
+    primaryActive: string;
+    primarySubtle: string;
+    secondary: string;
+    onSecondary: string;
+    secondaryHover: string;
+    secondaryActive: string;
+    secondarySubtle: string;
+    accent: string;
+    onAccent: string;
+    accentHover: string;
+    accentSubtle: string;
+    background: string;
+    surface: string;
+    surfaceHover: string;
+    surfaceActive: string;
+    elevated: string;
+    overlay: string;
+    text: string;
+    textSecondary: string;
+    textTertiary: string;
+    textInverse: string;
+    border: string;
+    borderHover: string;
+    borderFocus: string;
+    borderSubtle: string;
+    success: string;
+    onSuccess: string;
+    successHover: string;
+    successSubtle: string;
+    warning: string;
+    onWarning: string;
+    warningHover: string;
+    warningSubtle: string;
+    error: string;
+    onError: string;
+    errorHover: string;
+    errorSubtle: string;
+    info: string;
+    onInfo: string;
+    infoHover: string;
+    infoSubtle: string;
+    link: string;
+    linkHover: string;
+    linkVisited: string;
+    focus: string;
+    disabled: string;
+    disabledText: string;
+};
+
+/**
+ * Spacing scale with semantic naming
+ * Based on 4px unit system
+ */
+type BaseSpacing = {
+    none: string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+};
+
+/**
+ * Border radius scale
+ */
+type BaseRadius = {
+    none: string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    full: string;
+};
+
+/**
+ * Shadow scale for elevation
+ */
+type BaseShadows = {
+    none: string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+};
+
+/**
+ * Font size scale
+ */
+type BaseFontSize = {
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+};
+
+/**
+ * Font weight scale
+ */
+type BaseFontWeight = {
+    light: number;
+    regular: number;
+    medium: number;
+    semibold: number;
+    bold: number;
+};
+
+/**
+ * Line height scale
+ */
+type BaseLineHeight = {
+    none: number;
+    tight: number;
+    normal: number;
+    relaxed: number;
+};
+
+/**
+ * Z-index scale for layering
+ */
+type BaseZIndex = {
+    behind: number;
+    base: number;
+    dropdown: number;
+    overlay: number;
+    modal: number;
+    tooltip: number;
+};
+
+/**
+ * Transition timing scale
+ */
+type BaseTransition = {
+    fast: string;
+    normal: string;
+    slow: string;
+};
+
+/**
+ * Standard theme type with all required tokens
+ */
+type Theme = {
+    colors: BaseColors;
+    spacing: BaseSpacing;
+    radius: BaseRadius;
+    shadows: BaseShadows;
+    fontSize: BaseFontSize;
+    fontWeight: BaseFontWeight;
+    lineHeight: BaseLineHeight;
+    zIndex: BaseZIndex;
+    transition: BaseTransition;
+};
+
+/**
+ * Generic theme type that allows extending base tokens
+ */
+type ExtendedTheme<TColors extends BaseColors = BaseColors, TSpacing extends BaseSpacing = BaseSpacing, TRadius extends BaseRadius = BaseRadius, TShadows extends BaseShadows = BaseShadows, TFontSize extends BaseFontSize = BaseFontSize, TFontWeight extends BaseFontWeight = BaseFontWeight, TLineHeight extends BaseLineHeight = BaseLineHeight, TZIndex extends BaseZIndex = BaseZIndex, TTransition extends BaseTransition = BaseTransition, TExtensions extends Record<string, unknown> = Record<string, never>> = {
+    colors: TColors;
+    spacing: TSpacing;
+    radius: TRadius;
+    shadows: TShadows;
+    fontSize: TFontSize;
+    fontWeight: TFontWeight;
+    lineHeight: TLineHeight;
+    zIndex: TZIndex;
+    transition: TTransition;
+} & TExtensions;
+/**
+ * Helper type to create a custom theme with extensions
+ */
+type ExtendTheme<T extends Partial<Theme> & Record<string, unknown>> = Theme & T;
+/**
+ * Utility type to deeply make all properties optional
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Type for theme overrides
+ */
+type ThemeOverride<T extends Theme = Theme> = DeepPartial<T>;
+
+/**
+ * Color scale type - 12 shades from 25 to 950
+ */
+type ColorScale = {
+    25: string;
+    50: string;
+    100: string;
+    200: string;
+    300: string;
+    400: string;
+    500: string;
+    600: string;
+    700: string;
+    800: string;
+    900: string;
+    950: string;
+};
+
+/**
+ * Available color scale names
+ */
+type ColorName = 'gray' | 'slate' | 'stone' | 'red' | 'orange' | 'amber' | 'yellow' | 'lime' | 'green' | 'emerald' | 'teal' | 'cyan' | 'sky' | 'blue' | 'indigo' | 'violet' | 'purple' | 'fuchsia' | 'pink' | 'rose';
+
+/**
+ * Available shade values (keys of ColorScale)
+ */
+type ColorShade = keyof ColorScale;
+
+/**
+ * Available palette preset names
+ */
+type PaletteName = 'indigo' | 'rose' | 'emerald' | 'violet' | 'amber' | 'cyan' | 'slate' | 'gray';
+
+type ThemeProviderProps<T extends Theme = Theme> = {
+    theme: T;
+    children?: ReactNode;
+};
+/**
+ * Theme provider component
+ * Provides theme context to all child components
+ *
+ * @example
+ * ```tsx
+ * // With default theme
+ * <ThemeProvider theme={defaultTheme}>
+ *     <App />
+ * </ThemeProvider>
+ *
+ * // With custom extended theme
+ * <ThemeProvider theme={myCustomTheme}>
+ *     <App />
+ * </ThemeProvider>
+ * ```
+ */
+declare const ThemeProvider: <T extends Theme>({ theme, children }: ThemeProviderProps<T>) => react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the current theme
+ * Use the generic parameter to get proper typing for extended themes
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const theme = useTheme()
+ *
+ * // With custom theme type
+ * const theme = useTheme<MyCustomTheme>()
+ * ```
+ *
+ * @throws {Error} If used outside a ThemeProvider
+ */
+declare const useTheme: <T extends Theme = Theme>() => T;
+
+/**
+ * Create a theme by merging a base theme with overrides
+ *
+ * @example
+ * ```ts
+ * const myTheme = createTheme(defaultTheme, {
+ *     colors: {
+ *         primary: '#ff0000',
+ *         // Only override what you need
+ *     },
+ *     spacing: {
+ *         md: '1.5rem',
+ *     },
+ * })
+ * ```
+ */
+declare const createTheme: <T extends Theme>(baseTheme: T, overrides: DeepPartial<T>) => T;
+/**
+ * Merge multiple theme overrides into one
+ * Later overrides take precedence
+ *
+ * @example
+ * ```ts
+ * const theme = mergeThemes(
+ *     baseTheme,
+ *     brandOverrides,
+ *     darkModeOverrides,
+ *     userPreferences
+ * )
+ * ```
+ */
+declare const mergeThemes: <T extends Theme>(baseTheme: T, ...overrides: DeepPartial<T>[]) => T;
+/**
+ * Create a theme extension factory
+ * Useful for creating theme variants (dark mode, high contrast, etc.)
+ *
+ * @example
+ * ```ts
+ * const createDarkVariant = createThemeVariant({
+ *     colors: {
+ *         background: '#1a1a1a',
+ *         text: '#ffffff',
+ *     },
+ * })
+ *
+ * const darkTheme = createDarkVariant(lightTheme)
+ * ```
+ */
+declare const createThemeVariant: <T extends Theme>(variantOverrides: DeepPartial<T>) => (baseTheme: T) => T;
+
+/**
+ * Default spacing scale
+ */
+declare const defaultSpacing: Theme['spacing'];
+/**
+ * Default border radius scale
+ */
+declare const defaultRadius: Theme['radius'];
+/**
+ * Default shadow scale
+ */
+declare const defaultShadows: Theme['shadows'];
+/**
+ * Default font size scale
+ */
+declare const defaultFontSize: Theme['fontSize'];
+/**
+ * Default font weight scale
+ */
+declare const defaultFontWeight: Theme['fontWeight'];
+/**
+ * Default line height scale
+ */
+declare const defaultLineHeight: Theme['lineHeight'];
+/**
+ * Default z-index scale
+ */
+declare const defaultZIndex: Theme['zIndex'];
+/**
+ * Default transition scale
+ */
+declare const defaultTransition: Theme['transition'];
+/**
+ * Default colors (using indigo palette)
+ */
+declare const defaultColors: BaseColors;
+/**
+ * Default dark colors (using indigo palette)
+ */
+declare const defaultDarkColors: BaseColors;
+/**
+ * Complete default light theme
+ */
+declare const defaultTheme: Theme;
+/**
+ * Complete default dark theme
+ */
+declare const defaultDarkTheme: Theme;
+
+declare const gray: ColorScale;
+
+declare const slate: ColorScale;
+
+declare const stone: ColorScale;
+
+declare const red: ColorScale;
+
+declare const orange: ColorScale;
+
+declare const amber: ColorScale;
+
+declare const yellow: ColorScale;
+
+declare const lime: ColorScale;
+
+declare const green: ColorScale;
+
+declare const emerald: ColorScale;
+
+declare const teal: ColorScale;
+
+declare const cyan: ColorScale;
+
+declare const sky: ColorScale;
+
+declare const blue: ColorScale;
+
+declare const indigo: ColorScale;
+
+declare const violet: ColorScale;
+
+declare const purple: ColorScale;
+
+declare const fuchsia: ColorScale;
+
+declare const pink: ColorScale;
+
+declare const rose: ColorScale;
+
+declare const white = "#ffffff";
+declare const black = "#000000";
+declare const transparent = "transparent";
+declare const current = "currentColor";
+/**
+ * All color scales organized by name
+ */
+declare const colors: {
+    readonly gray: ColorScale;
+    readonly slate: ColorScale;
+    readonly stone: ColorScale;
+    readonly red: ColorScale;
+    readonly orange: ColorScale;
+    readonly amber: ColorScale;
+    readonly yellow: ColorScale;
+    readonly lime: ColorScale;
+    readonly green: ColorScale;
+    readonly emerald: ColorScale;
+    readonly teal: ColorScale;
+    readonly cyan: ColorScale;
+    readonly sky: ColorScale;
+    readonly blue: ColorScale;
+    readonly indigo: ColorScale;
+    readonly violet: ColorScale;
+    readonly purple: ColorScale;
+    readonly fuchsia: ColorScale;
+    readonly pink: ColorScale;
+    readonly rose: ColorScale;
+    readonly white: "#ffffff";
+    readonly black: "#000000";
+    readonly transparent: "transparent";
+    readonly current: "currentColor";
+};
+
+type ColorPalette$7 = Theme['colors'];
+declare const indigoLight: ColorPalette$7;
+declare const indigoDark: ColorPalette$7;
+
+type ColorPalette$6 = Theme['colors'];
+declare const roseLight: ColorPalette$6;
+declare const roseDark: ColorPalette$6;
+
+type ColorPalette$5 = Theme['colors'];
+declare const emeraldLight: ColorPalette$5;
+declare const emeraldDark: ColorPalette$5;
+
+type ColorPalette$4 = Theme['colors'];
+declare const violetLight: ColorPalette$4;
+declare const violetDark: ColorPalette$4;
+
+type ColorPalette$3 = Theme['colors'];
+declare const amberLight: ColorPalette$3;
+declare const amberDark: ColorPalette$3;
+
+type ColorPalette$2 = Theme['colors'];
+declare const cyanLight: ColorPalette$2;
+declare const cyanDark: ColorPalette$2;
+
+type ColorPalette$1 = Theme['colors'];
+declare const slateLight: ColorPalette$1;
+declare const slateDark: ColorPalette$1;
+
+type ColorPalette = Theme['colors'];
+declare const grayLight: ColorPalette;
+declare const grayDark: ColorPalette;
+
+/**
+ * All available color palettes organized by name
+ */
+declare const palettes: {
+    readonly indigo: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+    readonly rose: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+    readonly emerald: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+    readonly violet: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+    readonly amber: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+    readonly cyan: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+    readonly slate: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+    readonly gray: {
+        readonly light: BaseColors;
+        readonly dark: BaseColors;
+    };
+};
+
+/**
+ * Extended type to support pseudo-classes, media queries, container queries, supports and complex selectors
+ */
+type StyleWithPseudos = CSSProperties & {
+    [key: `:${string}`]: CSSProperties;
+    [key: `@media ${string}`]: CSSProperties;
+    [key: `@container ${string}`]: CSSProperties;
+    [key: `@supports ${string}`]: CSSProperties;
+    [key: `& ${string}` | `&>${string}` | `&:${string}` | `&[${string}`]: CSSProperties;
+};
+/**
+ * Type for a function that returns StyleWithPseudos with any parameters
+ */
+type StyleFunction = (...args: never[]) => StyleWithPseudos;
+/**
+ * Type for @font-face options
+ */
+type FontFaceOptions = {
+    /** Font family name */
+    fontFamily: string;
+    /** Font source(s) - URL or local() */
+    src: string;
+    /** Font style */
+    fontStyle?: 'normal' | 'italic' | 'oblique';
+    /** Font weight */
+    fontWeight?: number | string;
+    /** Display behavior */
+    fontDisplay?: 'auto' | 'block' | 'swap' | 'fallback' | 'optional';
+    /** Unicode character range */
+    unicodeRange?: string;
+};
+
+/**
+ * Create typed styles with support for pseudo-classes, media queries, container queries, feature queries and complex selectors
+ *
+ * Supports custom extended themes via generic parameter.
+ *
+ * @example
+ * ```ts
+ * // Basic usage with default theme
+ * const STYLES = createStyles((theme) => ({
+ *     root: {
+ *         display: 'flex',
+ *         padding: theme.spacing.md,
+ *         ':hover': { backgroundColor: theme.colors.backgroundHover },
+ *     }
+ * }))
+ *
+ * // With custom extended theme
+ * type MyTheme = Theme & { colors: BaseColors & { accent: string } }
+ *
+ * const STYLES = createStyles<MyTheme>((theme) => ({
+ *     root: {
+ *         backgroundColor: theme.colors.accent, // TypeScript knows about accent!
+ *     }
+ * }))
+ * ```
+ */
+declare const createStyles: <TTheme extends Theme = Theme, T extends Record<string, StyleWithPseudos | StyleFunction> = Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: TTheme) => T)) => { [K in keyof T]: T[K] extends (...args: infer TArgs) => StyleWithPseudos ? (...args: TArgs) => string : string; };
+
+/**
+ * Create and inject keyframes
+ *
+ * @example
+ * ```ts
+ * const fadeIn = keyframes({
+ *     from: { opacity: 0 },
+ *     to: { opacity: 1 }
+ * })
+ *
+ * const STYLES = createStyles({
+ *     animated: { animation: `${fadeIn} 0.3s ease-in-out` }
+ * })
+ * ```
+ */
+declare const keyframes: (frames: Record<string, CSSProperties>) => string;
+
+/**
+ * Inject a @font-face rule
+ *
+ * @example
+ * ```ts
+ * fontFace({
+ *     fontFamily: 'MyFont',
+ *     src: "url('/fonts/myfont.woff2') format('woff2')",
+ *     fontWeight: 400,
+ *     fontStyle: 'normal',
+ *     fontDisplay: 'swap'
+ * })
+ * ```
+ */
+declare const fontFace: (options: FontFaceOptions) => string;
+
+/**
+ * Create CSS variables from the theme
+ * Injects variables into :root
+ *
+ * @example
+ * ```ts
+ * // In ThemeProvider
+ * injectCssVariables(theme, 'aurora')
+ * // Generates: :root { --aurora-colors-primary: #2563EB; ... }
+ * ```
+ */
+declare const injectCssVariables: (theme: Theme, prefix?: string) => void;
+/**
+ * Helper to use a CSS variable from the theme
+ *
+ * @example
+ * ```ts
+ * const STYLES = createStyles({
+ *     root: { color: cssVar('colors-primary') }
+ * })
+ * // Generates: color: var(--theme-colors-primary)
+ * ```
+ */
+declare const cssVar: (path: string, fallback?: string) => string;
+/**
+ * Create CSS variable references from a typed object
+ * Returns an object with the same structure where values are var() references
+ *
+ * @example
+ * ```ts
+ * const vars = cssVariables({
+ *     primaryColor: '#007bff',
+ *     spacing: '1rem',
+ * })
+ * // vars.primaryColor === 'var(--primary-color)'
+ * ```
+ */
+declare const cssVariables: <T extends Record<string, string | number>>(variables: T, options?: {
+    prefix?: string;
+    inject?: boolean;
+}) => { [K in keyof T]: string; };
+
+/**
+ * SSR: Get all collected CSS rules as a single string
+ * @returns The CSS content to inject into HTML
+ */
+declare const getSSRStyles: () => string;
+/**
+ * SSR: Get styles as a <style> tag ready to inject
+ * @returns The complete style tag to inject into <head>
+ */
+declare const getSSRStyleTag: () => string;
+/**
+ * SSR: Clear the collected rules buffer
+ * Call at the beginning of each SSR request to ensure clean state
+ */
+declare const clearSSRRules: () => void;
+/**
+ * SSR: Get raw CSS rules as an array
+ * @returns Array of CSS rules
+ */
+declare const getSSRRulesArray: () => string[];
+
+/**
+ * Set the theme getter
+ */
+declare const setThemeContextGetter: (getter: (() => Theme | undefined) | null) => (() => Theme | undefined) | null;
+/**
+ * Get the current theme
+ */
+declare const getTheme: () => Theme | undefined;
+/**
+ * Insert a CSS rule
+ */
+declare const insertRule: (rule: string) => void;
+/**
+ * Sanitize a CSS value to prevent injection attacks
+ * Returns the sanitized value or 'unset' if the value is dangerous
+ */
+declare const sanitizeCssValue: (value: string) => string;
+
+export { type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorName, type ColorScale, type ColorShade, type DeepPartial, type ExtendTheme, type ExtendedTheme, type FontFaceOptions, type PaletteName, type StyleFunction, type StyleWithPseudos, type Theme, type ThemeOverride, ThemeProvider, type ThemeProviderProps, amber, amberDark, amberLight, black, blue, clearSSRRules, colors, createStyles, createTheme, createThemeVariant, cssVar, cssVariables, current, cyan, cyanDark, cyanLight, defaultColors, defaultDarkColors, defaultDarkTheme, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultRadius, defaultShadows, defaultSpacing, defaultTheme, defaultTransition, defaultZIndex, emerald, emeraldDark, emeraldLight, fontFace, fuchsia, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, gray, grayDark, grayLight, green, indigo, indigoDark, indigoLight, injectCssVariables, insertRule, keyframes, lime, mergeThemes, orange, palettes, pink, purple, red, rose, roseDark, roseLight, sanitizeCssValue, setThemeContextGetter, sky, slate, slateDark, slateLight, stone, teal, transparent, useTheme, violet, violetDark, violetLight, white, yellow };