@aurora-ds/theme 3.0.0 → 3.1.1

package/dist/index.d.cts

@@ -1,286 +1,21 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode, CSSProperties } from 'react';
-export { CSSProperties } from 'react';
 
-/**
- * Default token values for theme creation - V3
- * TypeScript infers the types automatically from the values using `as const`
- * Note: No default colors/palette - colors must be defined by the user
- */
-/**
- * Default spacing scale
- */
-declare const defaultSpacing: {
-    readonly none: "0";
-    readonly '2xs': "0.125rem";
-    readonly xs: "0.25rem";
-    readonly sm: "0.5rem";
-    readonly md: "1rem";
-    readonly lg: "1.5rem";
-    readonly xl: "2rem";
-    readonly '2xl': "3rem";
-    readonly '3xl': "4rem";
-    readonly '4xl': "6rem";
-    readonly '5xl': "8rem";
-};
-/**
- * Default border radius scale
- */
-declare const defaultRadius: {
-    readonly none: "0";
-    readonly xs: "0.125rem";
-    readonly sm: "0.25rem";
-    readonly md: "0.375rem";
-    readonly lg: "0.5rem";
-    readonly xl: "0.75rem";
-    readonly '2xl': "1rem";
-    readonly full: "9999px";
-};
-/**
- * Default shadow scale
- */
-declare const defaultShadows: {
-    readonly none: "none";
-    readonly xs: "0 1px 2px 0 rgb(0 0 0 / 0.05)";
-    readonly sm: "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)";
-    readonly md: "0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)";
-    readonly lg: "0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)";
-    readonly xl: "0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)";
-    readonly '2xl': "0 25px 50px -12px rgb(0 0 0 / 0.25)";
-    readonly inner: "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)";
-    readonly focus: "0 0 0 3px rgb(99 102 241 / 0.4)";
-};
-/**
- * Default font size scale
- */
-declare const defaultFontSize: {
-    readonly '2xs': "0.625rem";
-    readonly xs: "0.75rem";
-    readonly sm: "0.875rem";
-    readonly md: "1rem";
-    readonly lg: "1.25rem";
-    readonly xl: "1.5rem";
-    readonly '2xl': "2rem";
-    readonly '3xl': "2.5rem";
-    readonly '4xl': "3rem";
-    readonly '5xl': "4rem";
-};
-/**
- * Default font weight scale
- */
-declare const defaultFontWeight: {
-    readonly light: 300;
-    readonly regular: 400;
-    readonly medium: 500;
-    readonly semibold: 600;
-    readonly bold: 700;
-};
-/**
- * Default line height scale
- */
-declare const defaultLineHeight: {
-    readonly none: 1;
-    readonly tight: 1.25;
-    readonly normal: 1.5;
-    readonly relaxed: 1.75;
-    readonly loose: 2;
-};
-/**
- * Default z-index scale
- */
-declare const defaultZIndex: {
-    readonly behind: -1;
-    readonly base: 0;
-    readonly dropdown: 1000;
-    readonly sticky: 1100;
-    readonly overlay: 1300;
-    readonly modal: 1400;
-    readonly popover: 1500;
-    readonly tooltip: 1600;
-    readonly toast: 1700;
-};
-/**
- * Default transition scale
- */
-declare const defaultTransition: {
-    readonly fast: "150ms ease-out";
-    readonly normal: "250ms ease-out";
-    readonly slow: "350ms ease-out";
-};
-/**
- * Default opacity scale
- */
-declare const defaultOpacity: {
-    readonly none: 0;
-    readonly lowest: 0.05;
-    readonly low: 0.1;
-    readonly medium: 0.25;
-    readonly high: 0.5;
-    readonly higher: 0.75;
-    readonly full: 1;
-};
-/**
- * Default responsive breakpoints
- */
-declare const defaultBreakpoints: {
-    readonly xs: "480px";
-    readonly sm: "640px";
-    readonly md: "768px";
-    readonly lg: "1024px";
-    readonly xl: "1280px";
-    readonly '2xl': "1536px";
-};
-
-/**
- * Responsive breakpoints for mobile-first design
- * Type inferred automatically from defaultBreakpoints values
- *
- * - xs: Extra small devices (phones in portrait)
- * - sm: Small devices (phones in landscape, small tablets)
- * - md: Medium devices (tablets)
- * - lg: Large devices (desktops)
- * - xl: Extra large devices (large desktops)
- * - 2xl: Extra extra large devices (wide screens)
- */
-type BaseBreakpoints = typeof defaultBreakpoints;
-
-/**
- * Base color tokens following modern design system semantics - V2
- */
-type BaseColors = {
-    background: string;
-    surface: string;
-    surfaceHover: string;
-    surfaceActive: string;
-    text: string;
-    textSecondary: string;
-    textTertiary: string;
-    primary: string;
-    primaryHover: string;
-    primaryActive: string;
-    primarySubtle: string;
-    primaryDisabled: string;
-    onPrimary: string;
-    secondary: string;
-    secondaryHover: string;
-    secondaryActive: string;
-    secondarySubtle: string;
-    secondaryDisabled: string;
-    onSecondary: string;
-    border: string;
-    disabled: string;
-    disabledText: string;
-    success: string;
-    successSubtle: string;
-    warning: string;
-    warningSubtle: string;
-    error: string;
-    errorHover: string;
-    errorSubtle: string;
-    onError: string;
-    info: string;
-    infoSubtle: string;
-    link: string;
-    linkHover: string;
-    linkActive: string;
-    linkDisabled: string;
-};
+/** Registry for theme type via module augmentation */
+interface ThemeRegistry {
+}
+/** @internal */
+type InferredTheme = ThemeRegistry extends {
+    theme: infer T;
+} ? T : Record<string, any>;
+/** Theme type, inferred from ThemeRegistry */
+type Theme<T = InferredTheme> = T extends Record<string, any> ? T : Record<string, any>;
 
 /**
- * Spacing scale with semantic naming
- * Type inferred automatically from defaultSpacing values
+ * Creates a typed theme. Type is validated against ThemeRegistry.
+ * The theme must match the structure defined in your module augmentation.
  */
-type BaseSpacing = typeof defaultSpacing;
-
-/**
- * Border radius scale
- * Type inferred automatically from defaultRadius values
- */
-type BaseRadius = typeof defaultRadius;
-
-/**
- * Shadow scale for elevation
- * Type inferred automatically from defaultShadows values
- */
-type BaseShadows = typeof defaultShadows;
-
-/**
- * Font size scale
- * Type inferred automatically from defaultFontSize values
- */
-type BaseFontSize = typeof defaultFontSize;
-
-/**
- * Font weight scale
- * Type inferred automatically from defaultFontWeight values
- */
-type BaseFontWeight = typeof defaultFontWeight;
-
-/**
- * Line height scale
- * Type inferred automatically from defaultLineHeight values
- */
-type BaseLineHeight = typeof defaultLineHeight;
-
-/**
- * Z-index scale for layering
- * Type inferred automatically from defaultZIndex values
- */
-type BaseZIndex = typeof defaultZIndex;
-
-/**
- * Transition timing scale
- * Type inferred automatically from defaultTransition values
- */
-type BaseTransition = typeof defaultTransition;
-
-/**
- * Base opacity scale for consistent transparency
- * Type inferred automatically from defaultOpacity values
- */
-type BaseOpacity = typeof defaultOpacity;
-
-/**
- * @deprecated Don't use Theme directly. Use `typeof yourTheme` instead.
- *
- * The Theme type has been removed in favor of type inference.
- * This forces better type safety and prevents issues with custom themes.
- *
- * @example
- * ```ts
- * // ✅ DO THIS - Infer type from your theme
- * const myTheme = createTheme({
- *   colors: { brand: '#000', accent: '#fff' }
- * })
- * type MyTheme = typeof myTheme
- *
- * type Props = {
- *   color: keyof MyTheme['colors']  // Type-safe!
- * }
- *
- * // ❌ DON'T DO THIS
- * import type { Theme } from '@aurora-ds/theme'  // Theme no longer exists!
- * ```
- */
-type Theme = never;
-
-/**
- * Minimum structure for a theme
- * Allows any extensions while preserving type safety
- */
-type ThemeStructure = {
-    colors: Record<string, string>;
-    spacing: Record<string, string>;
-    radius: Record<string, string>;
-    shadows: Record<string, string>;
-    fontSize: Record<string, string>;
-    fontWeight: Record<string, number>;
-    lineHeight: Record<string, number>;
-    zIndex: Record<string, number>;
-    transition: Record<string, string>;
-    opacity: Record<string, number>;
-    breakpoints: Record<string, string>;
-};
+declare const createTheme: <T extends Theme>(values: T) => T;
 
 /**
  * Color scale type - 12 shades from 25 to 950
@@ -300,151 +35,7 @@ type ColorScale = {
     950: string;
 };
 
-/**
- * Available shade values (keys of ColorScale)
- */
-type ColorShade = keyof ColorScale;
-
-type ThemeProviderProps<TTheme extends ThemeStructure = ThemeStructure> = {
-    theme: TTheme;
-    children?: ReactNode;
-};
-/**
- * Theme provider component
- * Provides theme context to all child components
- * Accepts any theme structure created with createTheme()
- *
- * @example
- * ```tsx
- * const myTheme = createTheme({
- *     colors: { primary: '#007bff', background: '#fff' }
- * })
- *
- * <ThemeProvider theme={myTheme}>
- *     <App />
- * </ThemeProvider>
- * ```
- */
-declare const ThemeProvider: <TTheme extends ThemeStructure>({ theme, children }: ThemeProviderProps<TTheme>) => react_jsx_runtime.JSX.Element;
-/**
- * Hook to access the current theme
- * Returns the theme provided by ThemeProvider with exact inferred types
- *
- * @example
- * ```tsx
- * const myTheme = createTheme({ colors: { brand: '#000' } })
- *
- * function MyComponent() {
- *   const theme = useTheme()  // theme.colors.brand is accessible!
- * }
- * ```
- *
- * @throws {Error} If used outside a ThemeProvider
- */
-declare const useTheme: <TTheme extends ThemeStructure = ThemeStructure>() => TTheme;
-
-/**
- * Default palette - V3
- * A clean, modern palette using Indigo as primary and Slate as neutral
- *
- * This palette is optional and serves as a reference/starting point.
- * You can use it directly, customize it, or create your own from scratch.
- *
- * @example
- * ```ts
- * // Use as-is
- * const theme = createTheme({ colors: defaultPalette })
- *
- * // Customize specific colors
- * const theme = createTheme({
- *   colors: {
- *     ...defaultPalette,
- *     primary: '#custom-color',
- *   }
- * })
- *
- * // Or create your own from scratch
- * const theme = createTheme({
- *   colors: { primary: '#...', background: '#...' }
- * })
- * ```
- */
-declare const defaultPalette: BaseColors;
-
-/**
- * Create a theme with custom color tokens - V3
- * Colors are optional - if not provided, defaultPalette is used
- * All other tokens use defaults and can be optionally overridden
- *
- * @param config - Theme configuration (all optional)
- *
- * @example
- * ```ts
- * // Use defaultPalette (quickest way to start)
- * const theme = createTheme()
- *
- * // Customize defaultPalette
- * const theme = createTheme({
- *     colors: {
- *         ...defaultPalette,
- *         primary: '#custom'
- *     }
- * })
- *
- * // Or create your own colors from scratch
- * const theme = createTheme({
- *     colors: {
- *         brand: '#007bff',
- *         surface: '#ffffff',
- *         text: '#212529',
- *     }
- * })
- * ```
- */
-declare const createTheme: <const TConfig extends {
-    colors?: Record<string, string>;
-    spacing?: Record<string, string>;
-    radius?: Record<string, string>;
-    shadows?: Record<string, string>;
-    fontSize?: Record<string, string>;
-    fontWeight?: Record<string, number>;
-    lineHeight?: Record<string, number>;
-    zIndex?: Record<string, number>;
-    transition?: Record<string, string>;
-    opacity?: Record<string, number>;
-    breakpoints?: Record<string, string>;
-} = object>(config?: TConfig) => {
-    readonly colors: TConfig["colors"] extends Record<string, string> ? TConfig["colors"] : typeof defaultPalette;
-    readonly spacing: TConfig["spacing"] extends Record<string, string> ? TConfig["spacing"] : typeof defaultSpacing;
-    readonly radius: TConfig["radius"] extends Record<string, string> ? TConfig["radius"] : typeof defaultRadius;
-    readonly shadows: TConfig["shadows"] extends Record<string, string> ? TConfig["shadows"] : typeof defaultShadows;
-    readonly fontSize: TConfig["fontSize"] extends Record<string, string> ? TConfig["fontSize"] : typeof defaultFontSize;
-    readonly fontWeight: TConfig["fontWeight"] extends Record<string, number> ? TConfig["fontWeight"] : typeof defaultFontWeight;
-    readonly lineHeight: TConfig["lineHeight"] extends Record<string, number> ? TConfig["lineHeight"] : typeof defaultLineHeight;
-    readonly zIndex: TConfig["zIndex"] extends Record<string, number> ? TConfig["zIndex"] : typeof defaultZIndex;
-    readonly transition: TConfig["transition"] extends Record<string, string> ? TConfig["transition"] : typeof defaultTransition;
-    readonly opacity: TConfig["opacity"] extends Record<string, number> ? TConfig["opacity"] : typeof defaultOpacity;
-    readonly breakpoints: TConfig["breakpoints"] extends Record<string, string> ? TConfig["breakpoints"] : typeof defaultBreakpoints;
-};
-
-/**
- * Color Scales - Modern color palettes with shades from 25 to 950
- *
- * Scales are only accessible via the colors object to maintain consistency
- *
- * @example
- * ```ts
- * import { colors } from '@aurora-ui/theme'
- *
- * colors.indigo[500]  // '#6366f1'
- * colors.emerald[400] // '#34d399'
- * colors.gray[900]    // '#18181b'
- * ```
- */
-/**
- * All color scales organized by name
- * All scales and special values are only accessible via this object
- */
+/** All color scales (19 scales with 12 shades each) */
 declare const colors: {
     readonly gray: ColorScale;
     readonly slate: ColorScale;
@@ -471,9 +62,39 @@ declare const colors: {
     readonly current: "currentColor";
 };
 
+type ThemeProviderProps = {
+    theme: Theme;
+    children?: ReactNode;
+};
 /**
- * Extended type to support pseudo-classes, media queries, container queries, supports and complex selectors
+ * Provides the theme to all child components.
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider theme={lightTheme}>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+declare const ThemeProvider: ({ theme, children }: ThemeProviderProps) => react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the current theme.
+ *
+ * Type is automatically inferred from ThemeRegistry (module augmentation).
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const theme = useTheme()
+ *   return <div style={{ color: theme.colors.primary }} />
+ * }
+ * ```
+ *
+ * @throws {Error} If used outside a ThemeProvider
  */
+declare const useTheme: () => Theme;
+
+/** CSS properties with support for pseudo-classes, media/container queries, and complex selectors */
 type StyleWithPseudos = CSSProperties & {
     [key: `:${string}`]: CSSProperties;
     [key: `@media ${string}`]: CSSProperties;
@@ -481,194 +102,47 @@ type StyleWithPseudos = CSSProperties & {
     [key: `@supports ${string}`]: CSSProperties;
     [key: `& ${string}` | `&>${string}` | `&:${string}` | `&[${string}`]: CSSProperties;
 };
-/**
- * Type for a function that returns StyleWithPseudos with any parameters
- */
+/** Function that returns StyleWithPseudos */
 type StyleFunction = (...args: never[]) => StyleWithPseudos;
-/**
- * Type for @font-face options
- */
+/** Options for @font-face */
 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 themes via generic parameter.
- *
- * @example
- * ```ts
- * // Basic usage
- * const STYLES = createStyles((theme) => ({
- *     root: {
- *         display: 'flex',
- *         padding: theme.spacing.md,
- *         ':hover': { backgroundColor: theme.colors.primary },
- *     }
- * }))
- *
- * // With explicit theme type
- * const myTheme = createTheme({ colors: { brand: '#007bff' } })
- *
- * const STYLES = createStyles((theme) => ({
- *     root: {
- *         backgroundColor: theme.colors.primary, // TypeScript knows the structure!
- *     }
- * }))
- * ```
+ * Creates styles with theme support. Type is inferred from ThemeRegistry.
+ * Supports pseudo-classes, media queries, and complex selectors.
  */
-declare const createStyles: <T extends Record<string, StyleWithPseudos | StyleFunction> = Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: ThemeStructure) => T)) => { [K in keyof T]: T[K] extends (...args: infer TArgs) => StyleWithPseudos ? (...args: TArgs) => string : string; };
-/**
- * Create a typed createStyles function pre-configured with your custom theme type.
- * This eliminates the need to specify the theme type on every createStyles call.
- *
- * @example
- * ```ts
- * // 1. Define your theme
- * const myTheme = createTheme({
- *     colors: {
- *         brand: '#007bff',
- *         surface: '#ffffff',
- *     }
- * })
- *
- * // 2. Create a pre-typed createStyles function (do this once)
- * export const createStyles = createTypedStyles<typeof myTheme>()
- *
- * // 3. Use it everywhere without specifying the type!
- * const STYLES = createStyles((theme) => ({
- *     button: {
- *         backgroundColor: theme.colors.primary,    // ✅ TypeScript knows!
- *     },
- * }))
- * ```
- */
-declare const createTypedStyles: <TTheme extends ThemeStructure = ThemeStructure>() => <T extends Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: TTheme) => T)) => { [K in keyof T]: T[K] extends (...args: infer TArgs) => StyleWithPseudos ? (...args: TArgs) => string : string; };
+declare const createStyles: <T extends Record<string, StyleWithPseudos | StyleFunction> = Record<string, StyleWithPseudos | StyleFunction>>(stylesOrCreator: T | ((theme: Theme) => 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` }
- * })
- * ```
- */
+/** Creates and injects a @keyframes rule, returns the animation name */
 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'
- * })
- * ```
- */
+/** Injects a @font-face rule and returns the font family name */
 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: ThemeStructure, 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)
- * ```
- */
+/** Injects CSS variables from theme into :root */
+declare const injectCssVariables: (theme: Theme, prefix?: string) => void;
+/** Returns a CSS var() reference for a theme path */
 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)'
- * ```
- */
+/** Creates CSS variable references from an object */
 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
- */
+/** SSR: Returns all collected CSS rules as a single string */
 declare const getSSRStyles: () => string;
-/**
- * SSR: Get styles as a <style> tag ready to inject
- * @returns The complete style tag to inject into <head>
- */
+/** SSR: Returns styles wrapped in a style tag */
 declare const getSSRStyleTag: () => string;
-/**
- * SSR: Clear the collected rules buffer
- * Call at the beginning of each SSR request to ensure clean state
- */
+/** SSR: Clears the collected rules buffer */
 declare const clearSSRRules: () => void;
-/**
- * SSR: Get raw CSS rules as an array
- * @returns Array of CSS rules
- */
+/** SSR: Returns raw CSS rules as an array */
 declare const getSSRRulesArray: () => string[];
 
-/**
- * Set the theme getter
- */
-declare const setThemeContextGetter: (getter: (() => ThemeStructure | undefined) | null) => (() => ThemeStructure | undefined) | null;
-/**
- * Get the current theme
- */
-declare const getTheme: () => ThemeStructure | 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 BaseBreakpoints, type BaseColors, type BaseFontSize, type BaseFontWeight, type BaseLineHeight, type BaseOpacity, type BaseRadius, type BaseShadows, type BaseSpacing, type BaseTransition, type BaseZIndex, type ColorScale, type ColorShade, type FontFaceOptions, type StyleFunction, type StyleWithPseudos, type Theme, ThemeProvider, type ThemeProviderProps, clearSSRRules, colors, createStyles, createTheme, createTypedStyles, cssVar, cssVariables, defaultBreakpoints, defaultFontSize, defaultFontWeight, defaultLineHeight, defaultOpacity, defaultPalette, defaultRadius, defaultShadows, defaultSpacing, defaultTransition, defaultZIndex, fontFace, getSSRRulesArray, getSSRStyleTag, getSSRStyles, getTheme, injectCssVariables, insertRule, keyframes, sanitizeCssValue, setThemeContextGetter, useTheme };
+export { type FontFaceOptions, type StyleWithPseudos, ThemeProvider, type ThemeRegistry, clearSSRRules, colors, createStyles, createTheme, cssVar, cssVariables, fontFace, getSSRRulesArray, getSSRStyleTag, getSSRStyles, injectCssVariables, keyframes, useTheme };