@kbach/ui 0.1.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,328 @@
+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-6xH1WxpZ.js';
+
+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/ui'; // or '@kbach/native' — either works, native re-exports react's types
+ * declare module '@kbach/ui' {
+ *   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'>()`.
+ */
+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>;
+
+/**
+ * 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:
+ *
+ * ```ts
+ * import '@kbach/ui'; // or '@kbach/native'
+ * declare module '@kbach/ui' {
+ *   interface KbachCustomSpacing {
+ *     18: true; // value doesn't matter — only the key is read (see SpacingAPI)
+ *   }
+ * }
+ * ```
+ */
+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/ui/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/ui/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;
+
+/**
+ * Renders Kbach's base browser-default reset (borderless button/input,
+ * visible checkbox/radio, no arrow-less <select>, etc.) as a plain <style>
+ * 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
+ * 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.
+ */
+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" />
+ * ```
+ */
+declare function styled<T extends ComponentType<any>>(Component: T, baseClasses?: string): ForwardRefExoticComponent<Omit<React__default.ComponentPropsWithRef<T>, OmittedKeys> & StyledProps>;
+
+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.
+ */
+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;
+}
+/**
+ * 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.
+ */
+declare const InteractiveWrapper: React__default.ForwardRefExoticComponent<InteractiveWrapperProps & React__default.RefAttributes<unknown>>;
+
+/**
+ * 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'
+ * ```
+ */
+declare function cx(...classes: Array<string | false | null | undefined>): string;
+
+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 };