@kbach/react 0.6.51 → 1.0.0-beta.1

package/dist/index.d.ts

@@ -1,165 +1,26 @@
-import * as React from 'react';
-import React__default, { Context, 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, generateKbachTypesDts, getConfig, initConfig, normalizeClassString, parseClass, parseClasses, resolve, setResolveTarget, splitClassTokens, updateConfig } from './core';
-export { r as registerWebElement } from './web-substitute-CfpYFnE7.js';
+export { T as ThemeConfig, d as defaultTheme, g as getTheme, s as setTheme } from './theme-BKAb78KP.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
 
-interface ThemeContextValue {
-    /** The user-selected mode ('light' | 'dark' | 'system') */
-    mode: ThemeMode;
-    /** The effective resolved mode (never 'system') */
-    resolvedMode: 'light' | 'dark';
-    /** Convenience boolean */
-    isDark: boolean;
-    /** Change the theme mode programmatically */
-    setMode: (mode: ThemeMode) => void;
-    /** Toggle between light and dark (ignores system) */
-    toggle: () => void;
-    /** The fully resolved framework config (theme values, darkMode strategy, etc.) */
-    config: ResolvedConfig;
-}
-declare global {
-    var __kbachThemeContext: Context<ThemeContextValue | null> | undefined;
-}
-declare const ThemeContext: Context<ThemeContextValue | null>;
-declare function useTheme(): ThemeContextValue;
-declare function useIsDark(): boolean;
-
-interface ColorScale {
-    /** `colors.blue[6]` → raw hex string */
-    readonly [shade: number]: string;
-    /** `colors.blue['6/50']` → shade 6 at 50% opacity */
-    readonly [key: string]: string;
-}
 /**
- * Empty on purpose — augment it via declaration merging so `useColors()` (and
- * `useSpacing()`'s equivalent, `KbachCustomSpacing`) know about a project's
- * `kbach.config.js` colors without repeating a type parameter at every call
- * site. `kbach.config.js` is a plain runtime-loaded .js file, so TypeScript
- * can't see into it on its own — this is the same declaration-merging pattern
- * styled-components' `DefaultTheme` and i18next's resource typing use for the
- * identical problem. Put this in any .d.ts your tsconfig includes:
- *
- * ```ts
- * import '@kbach/react'; // or '@kbach/native' — either works, native re-exports react's types
- * declare module '@kbach/react' {
- *   interface KbachCustomColors {
- *     primary: string;    // a flat color, like the built-in `white`/`black`
- *     brand: ColorScale;  // a 1–12 shade scale, like the built-in `blue`/`red`
- *   }
- * }
- * ```
- *
- * A mode-aware `{ light, dark }` config color (see ColorValue) still resolves
- * to a flat `string` at read time — declare those as `string` here too, not
- * as the config shape.
- */
-interface KbachCustomColors {
-}
-type ColorValueFor<K extends string> = K extends keyof typeof defaultColors ? (typeof defaultColors)[K] extends string ? string : ColorScale : K extends keyof KbachCustomColors ? KbachCustomColors[K] : ColorScale | string;
-/** Every color name TypeScript knows about without an explicit type parameter: the built-in theme plus whatever's been added via the KbachCustomColors augmentation above. */
-type KnownColorName = DefaultColorName | Extract<keyof KbachCustomColors, string>;
-/**
- * `ColorName` defaults to `KnownColorName` (the built-in theme's color names
- * plus anything augmented onto `KbachCustomColors` above), so `useColors()`
- * gets full autocomplete and typo-catching out of the box — including custom
- * `kbach.config.js` colors, once augmented once project-wide. Without that
- * augmentation, a project with extra colors can still widen per call instead:
- * `useColors<DefaultColorName | 'brand'>()`.
+ * Loads and instantiates the Rust/WASM core engine. Call once at startup
+ * (e.g. before `ReactDOM.createRoot(...).render(...)`) and await it — every
+ * subsequent call returns the same memoized promise, so it's safe to call
+ * again from multiple entry points.
  */
-type ColorsAPI<ColorName extends string = KnownColorName> = {
-    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)'`
-     * - `colors.alpha('rgb(0,0,0)', 10)` → `'rgba(0,0,0,0.1)'`
-     * - `colors.alpha('rgba(0,0,0,0.5)')` → `'rgba(0,0,0,0.5)'` (passthrough)
-     */
-    readonly alpha: (color: string, opacity?: number) => string;
-};
-declare function wrapColors<ColorName extends string = KnownColorName>(rawColors: ThemeColors, isDark?: boolean): ColorsAPI<ColorName>;
-declare function useColors<ColorName extends string = KnownColorName>(): ColorsAPI<ColorName>;
+declare function initKbach(): Promise<void>;
+declare function isKbachReady(): boolean;
 
+declare function disableRuntimeCSS(): void;
+declare function isRuntimeCSSDisabled(): boolean;
 /**
- * Empty on purpose — augment it via declaration merging so `useSpacing()`
- * (like `useColors()`'s `KbachCustomColors`) knows about a project's
- * `kbach.config.js` spacing keys without repeating a type parameter at every
- * call site:
+ * Resolves a Kbach class string via the Rust/WASM engine, cascade-order-safe
+ * injects the resulting CSS rules into a single `<style data-kbach>` tag,
+ * and returns the class string unchanged for use as `className`.
  *
- * ```ts
- * import '@kbach/react'; // or '@kbach/native'
- * declare module '@kbach/react' {
- *   interface KbachCustomSpacing {
- *     18: true; // value doesn't matter — only the key is read (see SpacingAPI)
- *   }
- * }
- * ```
+ * Must be called after `await initKbach()` resolves — see wasmLoader.ts.
  */
-interface KbachCustomSpacing {
-}
-/** Every spacing key TypeScript knows about without an explicit type parameter. */
-type KnownSpacingKey = DefaultSpacingKey | Extract<keyof KbachCustomSpacing, string>;
-/**
- * `SpacingKey` defaults to `KnownSpacingKey` (the built-in theme's spacing keys
- * plus anything augmented onto `KbachCustomSpacing` above), so `useSpacing()`
- * gets full autocomplete and typo-catching out of the box — including custom
- * `kbach.config.js` keys, once augmented once project-wide. Without that
- * augmentation, a project with extra keys can still widen per call instead:
- * `useSpacing<DefaultSpacingKey | '18'>()`.
- */
-type SpacingAPI<SpacingKey extends string = KnownSpacingKey> = {
-    readonly [K in SpacingKey]: number | string;
-};
-declare function wrapSpacing<SpacingKey extends string = KnownSpacingKey>(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 = KnownSpacingKey>(): SpacingAPI<SpacingKey>;
-
-interface ThemeProviderProps {
-    children: ReactNode;
-    /** Initial mode. Falls back to persisted value, then 'system'. */
-    defaultMode?: ThemeMode;
-    /**
-     * System color scheme for native `defaultMode="system"`.
-     *
-     * Pass the value of `useColorScheme()` from `react-native`. When importing
-     * `ThemeProvider` from `@kbach/react/native` this is handled automatically.
-     *
-     * @example
-     * ```tsx
-     * import { useColorScheme } from 'react-native';
-     * const colorScheme = useColorScheme();
-     * <ThemeProvider defaultMode="system" colorScheme={colorScheme}>…</ThemeProvider>
-     * ```
-     */
-    colorScheme?: 'light' | 'dark' | null;
-    /**
-     * Current window/screen width in pixels for responsive breakpoints.
-     * On web this is read from `window.innerWidth` automatically.
-     * When importing `ThemeProvider` from `@kbach/react/native` this is provided
-     * automatically from `useWindowDimensions()`.
-     */
-    windowWidth?: number;
-    /** Override the config (useful for per-tree config). Defaults to global getConfig(). */
-    config?: FrameworkConfig;
-    /** Disable persistence to localStorage */
-    disablePersistence?: boolean;
-}
-declare function ThemeProvider({ children, defaultMode, colorScheme, windowWidth: windowWidthProp, config: configOverride, disablePersistence, }: ThemeProviderProps): React__default.JSX.Element;
+declare function kb(classString: string): string;
 
 /**
  * Renders Kbach's base browser-default reset (borderless button/input,
@@ -167,162 +28,90 @@ declare function ThemeProvider({ children, defaultMode, colorScheme, windowWidth
  * tag so it's part of the page's initial HTML.
  *
  * Runtime-only setups (no Vite plugin / static kbach.css) otherwise only get
- * this reset once ThemeProvider's client-side effect runs — fine for a plain
- * CSR app, but under SSR the server has no JS to run it, so the first paint
- * ships with raw browser defaults (e.g. the native button border) until
+ * this reset once kb()'s first call injects it — fine for a plain CSR app,
+ * but under SSR the server has no JS to run it, so the first paint ships
+ * with raw browser defaults (e.g. the native button border) until
  * hydration catches up. Render this once, as high in <head> as your
  * framework allows, to close that gap.
  *
- * Not needed if you're on the static-CSS setup — kbach.css already includes
- * the same reset, and the runtime injector detects this tag and skips adding
- * it a second time either way.
+ * Skips rendering entirely once disableRuntimeCSS() has fired — the Vite
+ * plugin calls it automatically wherever kbach.css gets imported (see
+ * vite-plugin/format.ts's own BASE_RESET inlining), and that static file
+ * already has this exact reset. No isNative check (unlike old-kbach's
+ * version of this component): @kbach/react is a web-only package now, so
+ * there's no cross-platform import path for this component to guard against.
  */
-declare function KbachReset(): React.JSX.Element | null;
+declare function KbachReset(): react.JSX.Element | null;
 
-interface StyledProps {
-    /** Additional utility classes applied on top of the base classes */
-    kb?: string;
-    /** Merged with resolved kb styles; applied last */
-    style?: StyleValue | StyleValue[];
-}
-type OmittedKeys = 'style';
 /**
- * Create a styled component from any React / React Native component.
- *
- * ```tsx
- * const Card = styled(View, 'bg-white dark:bg-gray-800 rounded-xl p-4 shadow-md');
- * const Button = styled(TouchableOpacity, 'bg-blue-500 pressed:bg-blue-700 dark:bg-blue-600 rounded-lg p-3');
- *
- * // Use it:
- * <Card kb="mt-4">...</Card>
- * <Button onPress={handlePress} kb="w-full" />
- * ```
+ * Port of old-kbach's dark-mode architecture (`packages/ui/src/core/
+ * darkModeStore.ts` + `ThemeProvider.tsx`), simplified for this package's
+ * web-only scope: a single module-level store is the actual source of
+ * truth, and `<ThemeProvider>`/`useTheme()` (see `ThemeProvider.tsx`) are a
+ * thin, OPTIONAL React wrapper around it — every function here works
+ * standalone, with no provider mounted anywhere, which is the whole point:
+ * a plain script, an event handler, or a component that never wants
+ * Context can call `toggleGlobalDarkMode()` directly.
  */
-declare function styled<T extends ComponentType<any>>(Component: T, baseClasses?: string): ForwardRefExoticComponent<Omit<React__default.ComponentPropsWithRef<T>, OmittedKeys> & StyledProps>;
+type ThemeMode = 'light' | 'dark' | 'system';
+declare function getGlobalDarkMode(): boolean;
+declare function getGlobalThemeMode(): ThemeMode;
+/** Explicit user choice — persisted, and takes priority over any later `<ThemeProvider defaultMode>` seed (see `seedDefaultMode` below). */
+declare function setGlobalThemeMode(nextMode: ThemeMode): void;
+declare function toggleGlobalDarkMode(): void;
+declare function subscribeGlobalDarkMode(listener: () => void): () => void;
 
-interface InteractionState {
-    hover?: boolean;
-    focus?: boolean;
-    /** Maps to 'pressed' and 'active' modifiers */
-    pressed?: boolean;
-    active?: boolean;
-    disabled?: boolean;
-    checked?: boolean;
-    visited?: boolean;
-    placeholder?: boolean;
-}
 /**
- * Resolve a utility class string to a style object for the current theme + state.
- *
- * ```tsx
- * // Basic usage
- * const styles = useStyles('bg-white dark:bg-gray-900 p-4');
- *
- * // With interaction state
- * const [pressed, setPressed] = useState(false);
- * const styles = useStyles('bg-blue-500 pressed:bg-blue-700', { pressed });
- *
- * // Multiple class strings (merged left-to-right)
- * const styles = useStyles(['bg-white p-4', 'dark:bg-gray-900 rounded-xl']);
- * ```
- */
-declare function useStyles(classString: string | string[], state?: InteractionState): StyleValue;
-/**
- * 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[]): __core.ResolvedStyle;
-
-/**
- * Subscribe to the global dark-mode store with React's concurrent-safe
- * useSyncExternalStore so that any component using className/kb re-renders
- * immediately when the theme changes — without needing ThemeContext.
+ * Reactive read of the global dark-mode store — works with or without a
+ * `<ThemeProvider>` mounted anywhere in the tree, since it subscribes to
+ * `darkModeStore.ts` directly. `useSyncExternalStore`'s SSR snapshot always
+ * returns `false` (light), matching `applyToDom`'s own server no-op — the
+ * server and the client's very first render agree, so there's no
+ * hydration-mismatch warning; the real value (if different) applies on the
+ * client immediately after.
  */
 declare function useGlobalDarkMode(): boolean;
 
-/**
- * Returns the name of the currently active breakpoint — the largest breakpoint
- * whose min-width the window satisfies, or `'xs'` when below all breakpoints.
- *
- * ```ts
- * const bp = useBreakpoint(); // 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
- * ```
- */
-declare function useBreakpoint(): string;
-/**
- * Returns a record of boolean flags for each breakpoint — `true` when the
- * window width satisfies that breakpoint's min-width threshold.
- *
- * ```ts
- * const { sm, md, lg } = useResponsive();
- * const padding = lg ? 32 : sm ? 16 : 8;
- * ```
- */
-declare function useResponsive(): Record<string, boolean>;
-
-interface InteractiveWrapperProps {
-    /** The real component to render (View, TouchableOpacity, div, a third-party button…) */
-    Component: React__default.ComponentType<any> | string;
-    /** Pre-resolved style buckets from resolve() */
-    resolvedStyle: ResolvedStyle;
-    /** On web: original class string so CSS pseudo-rules still fire */
-    className?: string;
-    /** Extra style prop passed by the user */
-    style?: StyleValue | StyleValue[];
-    children?: React__default.ReactNode;
-    onPressIn?: (...args: any[]) => void;
-    onPressOut?: (...args: any[]) => void;
-    onPointerDown?: (...args: any[]) => void;
-    onPointerUp?: (...args: any[]) => void;
-    onPointerLeave?: (...args: any[]) => void;
-    onPointerCancel?: (...args: any[]) => void;
-    onMouseEnter?: (...args: any[]) => void;
-    onMouseLeave?: (...args: any[]) => void;
-    onFocus?: (...args: any[]) => void;
-    onBlur?: (...args: any[]) => void;
+interface ThemeProviderProps {
+    children: ReactNode;
+    /**
+     * Applied once, on this provider's first mount, but ONLY if the user has
+     * no persisted preference already (see `darkModeStore.ts::seedDefaultMode`)
+     * — an explicit prior choice always wins over a component's own default.
+     */
+    defaultMode?: ThemeMode;
 }
 /**
- * Thin wrapper rendered automatically by the JSX runtime whenever a className/kb
- * string contains interactive modifiers (hover:, pressed:, focus:, active:, …).
- *
- * Manages interaction state locally and flattens the correct style bucket on
- * every render. The wrapped component sees a plain `style` prop — it never
- * knows it was wrapped.
- *
- * Refs are forwarded so the host component's imperative API still works.
+ * Optional React Context wrapper around `darkModeStore.ts`'s single global
+ * store — port of old-kbach's `ThemeProvider` (`packages/ui/src/
+ * ThemeProvider.tsx`), same "provider is a thin wrapper around a global
+ * store, not the source of truth itself" shape, simplified to this
+ * package's web-only scope (no native `useColorScheme()`/`windowWidth`
+ * branch, no `disablePersistence` prop — persistence is always on, since
+ * `darkModeStore.ts` already guards every `localStorage` access for
+ * environments where it's unavailable).
+ *
+ * Because the store is global, MULTIPLE mounted providers share the exact
+ * same `mode`/`isDark` state rather than each getting their own scoped
+ * value — mounting more than one is very likely a mistake (each fighting
+ * over the same state via a different `defaultMode`), so this warns once
+ * in dev, matching old-kbach's identical guard.
  */
-declare const InteractiveWrapper: React__default.ForwardRefExoticComponent<InteractiveWrapperProps & React__default.RefAttributes<unknown>>;
+declare function ThemeProvider({ children, defaultMode }: ThemeProviderProps): react.JSX.Element;
 
+interface ThemeContextValue {
+    mode: ThemeMode;
+    isDark: boolean;
+    setMode: (mode: ThemeMode) => void;
+    toggle: () => void;
+}
 /**
- * Resolve a utility class string outside of a React component.
- *
- * On **native** — returns a StyleValue (style object) for the given mode.
- * On **web** — injects CSS and returns the original class string (use as className).
- *
- * ```ts
- * // Inside a component use useStyles() instead.
- * // kb() is useful for StyleSheet.create() calls and static values.
- *
- * const styles = StyleSheet.create({
- *   container: kb('flex-1 bg-white p-4') as any,
- * });
- *
- * // Web: use as className
- * <div className={kb('bg-white dark:bg-gray-900 p-4') as string} />
- * ```
- *
- * @param classString   Space-separated utility classes
- * @param isDark        Whether dark mode is active (default: false)
- */
-declare function kb(classString: string, isDark?: boolean): StyleValue | string;
-/**
- * Conditionally join class names. Falsy values are ignored.
- *
- * ```ts
- * cx('bg-white p-4', isActive && 'border-2 border-blue-500', undefined)
- * // → 'bg-white p-4 border-2 border-blue-500'
- * ```
+ * Requires a `<ThemeProvider>` ancestor — throws otherwise, since a
+ * component that destructures `{ mode, setMode }` genuinely needs Context
+ * (unlike a component that just wants the dark/light boolean, which should
+ * reach for `useGlobalDarkMode()` instead and never needs a provider at
+ * all).
  */
-declare function cx(...classes: Array<string | false | null | undefined>): string;
+declare function useTheme(): ThemeContextValue;
 
-export { type ColorScale, type ColorsAPI, type InteractionState, InteractiveWrapper, type InteractiveWrapperProps, type KbachCustomColors, type KbachCustomSpacing, 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 };
+export { KbachReset, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, disableRuntimeCSS, getGlobalDarkMode, getGlobalThemeMode, initKbach, isKbachReady, isRuntimeCSSDisabled, kb, setGlobalThemeMode, subscribeGlobalDarkMode, toggleGlobalDarkMode, useGlobalDarkMode, useTheme };