@kbach/react 0.6.24 → 0.6.26

package/dist/index.d.ts

@@ -1,224 +1,10 @@
 import * as React from 'react';
 import React__default, { ReactNode, ComponentType, ForwardRefExoticComponent } from 'react';
+import * as __core from './core';
+import { ThemeMode, ResolvedConfig, DefaultColorName, defaultColors, ThemeColors, DefaultSpacingKey, ThemeSpacing, FrameworkConfig, StyleValue, ResolvedStyle } from './core';
+export { DefaultColorName, DefaultSpacingKey, FrameworkConfig, ParsedClass, PluginAPI, ResolvedConfig, ResolvedStyle, StyleValue, ThemeConfig, ThemeMode, buildConfig, clearCache, defaultColors, defaultTheme, disableRuntimeCSS, flatten, getConfig, initConfig, normalizeClassString, parseClass, parseClasses, resolve, setResolveTarget, splitClassTokens, updateConfig } from './core';
 export { r as registerWebElement } from './web-substitute-CfpYFnE7.js';
 
-/**
- * Unified modifier registry — single source of truth for ALL modifier behavior.
- *
- * Adding a new modifier requires editing ONLY this file:
- *   1. Add an entry to BUILTIN_MODIFIERS with its CSS and JS behavior.
- *   2. Done — parser, resolver, CSS generator, and JSX runtime all derive
- *      their behavior from this data automatically.
- *
- * Plugin authors can register custom modifiers via registerModifier().
- */
-interface ModifierDef {
-    /** CSS pseudo-class or pseudo-element appended to the selector (e.g. ':hover', '::before') */
-    pseudo?: string;
-    /** Ancestor selector prefix INCLUDING trailing space (e.g. '.group:hover ', '.peer:focus ~ ') */
-    ancestorSelector?: string;
-    /** Directionality attribute selector prefix INCLUDING trailing space (e.g. '[dir="rtl"] ') */
-    dirSelector?: string;
-    /** @media query body WITHOUT the '@media ' prefix (e.g. 'print', '(orientation: landscape)') */
-    mediaQuery?: string;
-    /** Dark/light mode scheme — triggers the configured darkMode strategy in CSS output */
-    darkScheme?: 'dark' | 'light';
-    /** True for responsive modifiers — wraps in @media (min-width: theme.screens[name]) */
-    isResponsive?: boolean;
-    /**
-     * Forces !important on all declarations in the generated CSS rule.
-     * Applied automatically for structural / ancestor / media modifiers that must
-     * win over base inline styles.
-     */
-    forcesImportant?: boolean;
-    /**
-     * How the JSX runtime routes this modifier:
-     *   'interactive'  — managed by InteractiveWrapper (hover, focus, pressed, …)
-     *   'mode'         — managed by DarkWrapper (dark, light, not-dark, …)
-     *   'responsive'   — managed by DarkWrapper (sm, md, lg, xl, 2xl)
-     *   'css-only'     — CSS injection only; matchModifier always returns false
-     */
-    jsBehavior: 'interactive' | 'mode' | 'responsive' | 'css-only';
-    /**
-     * Evaluates whether this modifier's condition is met at runtime.
-     * Omit for 'css-only' modifiers — they never apply as inline styles.
-     */
-    jsMatch?: (isDark: boolean, state: Record<string, boolean | undefined>, breakpoints: Set<string>) => boolean;
-}
-
-type ThemeMode = 'light' | 'dark' | 'system';
-interface StyleValue {
-    [key: string]: string | number | undefined | null | StyleValue | StyleValue[];
-}
-interface ParsedClass {
-    /** The original class string, e.g. "dark:hover:bg-[#fff]" */
-    original: string;
-    /** Up to 3 modifier prefixes, e.g. ['dark', 'hover'] */
-    modifiers: string[];
-    /** Whether a leading `-` was present for negative values */
-    negative: boolean;
-    /** Whether a leading `!` was present — applies !important to all CSS declarations */
-    important: boolean;
-    /** The utility name, e.g. 'bg', 'p', 'text' */
-    utility: string;
-    /** The resolved value, e.g. 'white', '#fff', '4' */
-    value: string;
-    /** Whether the value was specified with bracket notation [value] */
-    isArbitrary: boolean;
-}
-interface ResolvedStyle {
-    /** Base styles applied unconditionally */
-    base?: StyleValue;
-    /** Styles keyed by modifier or modifier combo, e.g. 'dark', 'hover', 'dark:hover' */
-    [modifierKey: string]: StyleValue | undefined;
-}
-type ColorShades = Record<string, string>;
-type ThemeColors = Record<string, string | ColorShades>;
-type ThemeSpacing = Record<string, number | string>;
-interface ThemeConfig {
-    colors: ThemeColors;
-    spacing: ThemeSpacing;
-    fontSize: Record<string, number | string>;
-    fontFamily: Record<string, string | string[]>;
-    fontWeight: Record<string, string | number>;
-    borderRadius: Record<string, number | string>;
-    borderWidth: Record<string, number>;
-    opacity: Record<string, number>;
-    lineHeight: Record<string, number | string>;
-    letterSpacing: Record<string, number | string>;
-    zIndex: Record<string, number | string>;
-    flex: Record<string, number | string>;
-    shadow: Record<string, StyleValue>;
-    screens: Record<string, string | number>;
-    /**
-     * Custom @keyframes, web only. Each key is a keyframe name, its value maps
-     * percentage/from/to selectors to a plain CSS declaration object (camelCase
-     * properties, same shape as an inline style object):
-     *   keyframes: { wiggle: { '0%, 100%': { transform: 'rotate(-3deg)' }, '50%': { transform: 'rotate(3deg)' } } }
-     * Referenced from `animation` below, or directly via animate-[wiggle_1s_ease-in-out].
-     */
-    keyframes: Record<string, Record<string, StyleValue>>;
-    /**
-     * Named animation shorthands built on `keyframes` above, referenced via
-     * animate-{name} (e.g. animate-wiggle):
-     *   animation: { wiggle: 'wiggle 1s ease-in-out infinite' }
-     * The first word must match a `keyframes` key so its @keyframes rule can be
-     * injected alongside the animation — a name with no matching keyframes entry
-     * still sets the `animation` CSS property, it just won't animate anything.
-     */
-    animation: Record<string, string>;
-    [key: string]: unknown;
-}
-/**
- * 'class'     — toggles .dark class on <html>
- * 'media'     — uses prefers-color-scheme media query
- * 'attribute' — uses data-theme="dark" attribute on <html>
- */
-type DarkMode = 'attribute' | 'class' | 'media';
-interface PluginAPI {
-    addUtility(name: string, styles: StyleValue): void;
-    /**
-     * Register a custom variant.
-     *
-     * Pass a CSS selector string for simple cases — it is automatically
-     * converted into a ModifierDef that generates correct CSS rules:
-     *   addVariant('hocus', ':hover, :focus')  // pseudo
-     *   addVariant('supports-grid', '@media (display: grid)')  // media
-     *   addVariant('dark-green', '.dark-green')  // ancestor selector
-     *
-     * Pass a full ModifierDef object for advanced control (e.g. JS-trackable
-     * interactive variants with custom jsMatch logic).
-     */
-    addVariant(name: string, selectorOrDef: string | ModifierDef): void;
-    theme(path: string, defaultValue?: unknown): unknown;
-    e(className: string): string;
-}
-interface FrameworkConfig {
-    darkMode?: DarkMode;
-    theme?: Partial<ThemeConfig>;
-    /** Additive theme extension — accepts either `extend.theme.X` or `extend.X` directly. */
-    extend?: {
-        theme?: Partial<ThemeConfig>;
-    } & Partial<ThemeConfig>;
-    plugins?: Array<(api: PluginAPI) => void>;
-    content?: string[];
-}
-interface ResolvedConfig {
-    darkMode: DarkMode;
-    theme: ThemeConfig;
-    plugins: Array<(api: PluginAPI) => void>;
-}
-
-declare const defaultColors: ThemeColors;
-declare const defaultTheme: ThemeConfig;
-
-declare function setResolveTarget(target: 'web' | 'native' | null): void;
-
-declare function parseClass(className: string): ParsedClass | null;
-/**
- * Split a class string into tokens. Whitespace at bracket depth > 0 is STRIPPED
- * (not just skipped) so that arbitrary values like rgb(41, 172, 15) become valid
- * CSS class name tokens: bg-[rgb(41,172,15)].
- */
-declare function splitClassTokens(classString: string): string[];
-/**
- * Normalize a full class string so it is safe to use as an HTML className value.
- * Strips spaces inside brackets: "bg-[rgb(41, 172, 15)] p-4" → "bg-[rgb(41,172,15)] p-4"
- */
-declare function normalizeClassString(classString: string): string;
-/** Parse a space-separated class string into individual ParsedClass objects. */
-declare function parseClasses(classString: string): ParsedClass[];
-
-declare function disableRuntimeCSS(): void;
-/**
- * Resolve a class string to a ResolvedStyle object.
- *
- * Results are cached per (theme, classString, darkMode) — repeated calls with
- * the same arguments are O(1).  Different theme objects each get their own
- * cache so concurrent ThemeProviders with different configs are always correct.
- */
-declare function resolve(classString: string, theme: ThemeConfig, darkMode?: 'attribute' | 'class' | 'media'): ResolvedStyle;
-/**
- * Flatten a ResolvedStyle into a single StyleValue for the current runtime state.
- * Used by useStyles() and styled().
- *
- * The sort step is memoized per resolved object reference (#6) — when resolve()
- * returns a cached object, getSortedEntries() is O(1) on all subsequent calls.
- */
-declare function flatten(resolved: ResolvedStyle, isDark: boolean, state?: {
-    hover?: boolean;
-    focus?: boolean;
-    pressed?: boolean;
-    active?: boolean;
-    disabled?: boolean;
-    checked?: boolean;
-    visited?: boolean;
-    placeholder?: boolean;
-}, breakpoints?: Set<string>): StyleValue;
-/**
- * Clear CSS injection state so stale rules are re-injected when the theme changes.
- *
- * The per-theme style cache (WeakMap) does not need to be cleared manually:
- * updateConfig() creates a new theme object, making the old cache entry
- * automatically unreachable for GC.
- */
-declare function clearCache(): void;
-
-/**
- * Load, merge, and cache the resolved config.
- * Call resetConfig() to force a reload (e.g. in tests or after live update).
- */
-declare function getConfig(): ResolvedConfig;
-declare function buildConfig(userConfig: FrameworkConfig): ResolvedConfig;
-declare function updateConfig(userConfig: FrameworkConfig): void;
-/**
- * Like updateConfig, but only calls it when the config object reference has
- * actually changed. Used by the Babel-injected IIFE so that:
- *  - multiple files with kbach classes don't re-run the update on every load
- *  - Fast Refresh DOES re-run when kbach.config.js changes (new module → new object)
- */
-declare function initConfig(userConfig: FrameworkConfig): void;
-
 interface ThemeContextValue {
     /** The user-selected mode ('light' | 'dark' | 'system') */
     mode: ThemeMode;
@@ -243,7 +29,19 @@ interface ColorScale {
     /** `colors.blue['6/50']` → shade 6 at 50% opacity */
     readonly [key: string]: string;
 }
-interface ColorsAPI {
+type ColorValueFor<K extends string> = K extends keyof typeof defaultColors ? (typeof defaultColors)[K] extends string ? string : ColorScale : ColorScale | string;
+/**
+ * `ColorName` defaults to the built-in theme's color names (`DefaultColorName`,
+ * derived from `defaultColors` in core/theme.ts), so `useColors()` gets full
+ * autocomplete and typo-catching out of the box for any project on the default
+ * theme. A customized `kbach.config.js` isn't visible to TypeScript (it's a
+ * plain .js file loaded at runtime, not a statically-analyzed module), so a
+ * project with extra colors needs to widen the type parameter explicitly:
+ * `useColors<DefaultColorName | 'brand'>()`.
+ */
+type ColorsAPI<ColorName extends string = DefaultColorName> = {
+    readonly [K in ColorName]: ColorValueFor<K>;
+} & {
     /**
      * Pass any CSS color through, optionally applying an opacity (0–100).
      * - `colors.alpha('#3b82f6', 50)` → `'rgba(59,130,246,0.5)'`
@@ -251,10 +49,38 @@ interface ColorsAPI {
      * - `colors.alpha('rgba(0,0,0,0.5)')` → `'rgba(0,0,0,0.5)'` (passthrough)
      */
     readonly alpha: (color: string, opacity?: number) => string;
-    [color: string]: any;
-}
-declare function wrapColors(rawColors: ThemeColors): ColorsAPI;
-declare function useColors(): ColorsAPI;
+};
+declare function wrapColors<ColorName extends string = DefaultColorName>(rawColors: ThemeColors): ColorsAPI<ColorName>;
+declare function useColors<ColorName extends string = DefaultColorName>(): ColorsAPI<ColorName>;
+
+/**
+ * `SpacingKey` defaults to the built-in theme's spacing keys (`DefaultSpacingKey`,
+ * derived from `defaultTheme.spacing` in core/theme.ts), so `useSpacing()` gets
+ * full autocomplete and typo-catching out of the box for any project on the
+ * default scale. A customized `kbach.config.js` isn't visible to TypeScript
+ * (it's a plain .js file loaded at runtime, not a statically-analyzed module),
+ * so a project with extra spacing keys needs to widen the type parameter
+ * explicitly: `useSpacing<DefaultSpacingKey | '18'>()`.
+ */
+type SpacingAPI<SpacingKey extends string = DefaultSpacingKey> = {
+    readonly [K in SpacingKey]: number | string;
+};
+declare function wrapSpacing<SpacingKey extends string = DefaultSpacingKey>(rawSpacing: ThemeSpacing): SpacingAPI<SpacingKey>;
+/**
+ * Returns the active theme's spacing scale as a typed, autocomplete-friendly
+ * object — useful anywhere a raw JS number/string is needed instead of a
+ * className (Animated API distances, chart dimensions, FlatList separator
+ * heights, etc.). Values match exactly what `p-`/`m-`/`w-`/`h-`/`gap-` and
+ * other spacing-scale utilities resolve to.
+ *
+ * ```ts
+ * const spacing = useSpacing();
+ * spacing[4]      // 16
+ * spacing.full    // '100%'
+ * spacing['1/2']  // '50%'
+ * ```
+ */
+declare function useSpacing<SpacingKey extends string = DefaultSpacingKey>(): SpacingAPI<SpacingKey>;
 
 interface ThemeProviderProps {
     children: ReactNode;
@@ -358,7 +184,7 @@ declare function useStyles(classString: string | string[], state?: InteractionSt
  * Returns the full ResolvedStyle bucket map (base, dark, hover, …).
  * Useful when you need to apply styles selectively or pass them to Animated.
  */
-declare function useResolvedStyle(classString: string | string[]): ResolvedStyle;
+declare function useResolvedStyle(classString: string | string[]): __core.ResolvedStyle;
 
 /**
  * Subscribe to the global dark-mode store with React's concurrent-safe
@@ -452,4 +278,4 @@ declare function kb(classString: string, isDark?: boolean): StyleValue | string;
  */
 declare function cx(...classes: Array<string | false | null | undefined>): string;
 
-export { type ColorScale, type ColorsAPI, type FrameworkConfig, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, KbachReset, type ParsedClass, type PluginAPI, type ResolvedConfig, type ResolvedStyle, type StyleValue, type StyledProps, type ThemeConfig, ThemeContext, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, buildConfig, clearCache, cx, defaultColors, defaultTheme, disableRuntimeCSS, flatten, getConfig, initConfig, kb, normalizeClassString, parseClass, parseClasses, resolve, setResolveTarget, splitClassTokens, styled, updateConfig, useBreakpoint, useColors, useGlobalDarkMode, useIsDark, useResolvedStyle, useResponsive, useStyles, useTheme, wrapColors };
+export { type ColorScale, type ColorsAPI, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, KbachReset, type SpacingAPI, type StyledProps, ThemeContext, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, cx, kb, styled, useBreakpoint, useColors, useGlobalDarkMode, useIsDark, useResolvedStyle, useResponsive, useSpacing, useStyles, useTheme, wrapColors, wrapSpacing };