stablekit.ts 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,473 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { HTMLAttributes, ReactNode, ElementType, Ref, ReactElement, JSX } from 'react';
+
+interface StateSwapProps extends HTMLAttributes<HTMLElement> {
+    /** The boolean state that drives which content is visible. */
+    state: boolean;
+    /** Content shown when `state` is true. */
+    true: ReactNode;
+    /** Content shown when `state` is false. */
+    false: ReactNode;
+    /** HTML element to render. Default: "span" (safe inside buttons). */
+    as?: ElementType;
+}
+/**
+ * Boolean content swap with zero layout shift.
+ *
+ * Reserves the width of the wider option so the container never changes
+ * dimensions when toggling between states.
+ *
+ * Renders as an inline `<span>` by default — safe inside buttons,
+ * table cells, and any inline context.
+ *
+ * @example
+ * ```tsx
+ * <button onClick={toggle}>
+ *   <StateSwap state={open} true="Close" false="Open" />
+ * </button>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <StateSwap
+ *   state={expanded}
+ *   true={<ChevronUp />}
+ *   false={<ChevronDown />}
+ * />
+ * ```
+ */
+declare function StateSwap({ state, true: onTrue, false: onFalse, as: Tag, ...props }: StateSwapProps): react_jsx_runtime.JSX.Element;
+
+type Axis = "width" | "height" | "both";
+interface LayoutGroupProps extends HTMLAttributes<HTMLElement> {
+    /** Which axis to stabilize. Default: "both". */
+    axis?: Axis;
+    /**
+     * Active value identifier. LayoutViews with a matching `name` prop become visible.
+     *
+     * **AI agent note:** LayoutGroup is a spatial stability container.
+     * All children overlap via CSS grid. The container auto-sizes to the
+     * largest child. Use LayoutView as children, not arbitrary elements.
+     * For boolean swaps, prefer StateSwap instead.
+     * For dictionary-based state mapping, prefer LayoutMap instead.
+     */
+    value?: string;
+    /** HTML element to render. Use "span" inside buttons. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Multi-state spatial stability container.
+ *
+ * All children overlap in the same grid cell (1/1). The container
+ * auto-sizes to the largest child — zero JS measurement, pure CSS grid.
+ *
+ * Use `<LayoutView name="...">` as children. The view whose `name`
+ * matches the group's `value` becomes active; others are hidden via
+ * `[inert]` + inline styles.
+ *
+ * Focus handoff: tracks whether focus is inside the container via native
+ * focusin/focusout listeners. When `inert` ejects focus (relatedTarget is
+ * null), the flag stays set so the incoming active LayoutView can reclaim it.
+ *
+ * @example
+ * ```tsx
+ * <LayoutGroup value={step}>
+ *   <LayoutView name="shipping"><ShippingForm /></LayoutView>
+ *   <LayoutView name="payment"><PaymentForm /></LayoutView>
+ *   <LayoutView name="confirm"><Confirmation /></LayoutView>
+ * </LayoutGroup>
+ * ```
+ */
+declare const LayoutGroup: react.ForwardRefExoticComponent<LayoutGroupProps & react.RefAttributes<HTMLElement>>;
+
+interface LayoutViewProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * Whether this view is the active (visible) variant.
+     * Overrides context-based matching. Use for manual control.
+     */
+    active?: boolean;
+    /**
+     * View name. Active when it matches the parent LayoutGroup's `value`.
+     *
+     * **AI agent note:** LayoutView must be a direct child of LayoutGroup.
+     * Do not use LayoutView outside of a LayoutGroup — it has no effect.
+     * For boolean swaps, use StateSwap instead.
+     */
+    name?: string;
+    /** HTML element to render. Use "span" inside buttons. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Single view inside a LayoutGroup.
+ *
+ * All views overlap via CSS grid. Inactive views are hidden but still
+ * contribute to grid cell sizing — the container never changes dimensions.
+ *
+ * Inactive hiding uses a `data-state` attribute driven by CSS
+ * (`.sk-layout-view[data-state="inactive"]`) plus the `[inert]` attribute
+ * for accessibility (non-focusable, non-interactive). Because hiding is
+ * CSS-driven rather than inline-style-driven, consumers can override
+ * transitions on the `.sk-layout-view` class without specificity fights.
+ *
+ * Active views get tabIndex={-1} so they are programmatically focusable
+ * (but excluded from the tab ring) for focus handoff.
+ */
+declare const LayoutView: react.ForwardRefExoticComponent<LayoutViewProps & react.RefAttributes<HTMLElement>>;
+
+interface LayoutMapProps<K extends string> extends HTMLAttributes<HTMLElement> {
+    /**
+     * The active key — must match one of the keys in `map`.
+     *
+     * Uses `NoInfer<K>` so TypeScript infers the key union from `map`
+     * and checks `value` against it — typos are compile-time errors.
+     */
+    value: NoInfer<K>;
+    /** Dictionary of views keyed by state name. TypeScript infers and enforces the keys. */
+    map: Record<K, ReactNode>;
+}
+/**
+ * Typo-proof dictionary-based state mapping.
+ *
+ * Replaces manual LayoutGroup + LayoutView trees with a single component.
+ * TypeScript infers the key union from `map` and enforces that `value`
+ * matches — no string typos, no orphaned views.
+ *
+ * @example
+ * ```tsx
+ * <LayoutMap
+ *   value={activeTab}
+ *   map={{
+ *     profile: <ProfileTab />,
+ *     invoices: <InvoicesTab />,
+ *     settings: <SettingsTab />,
+ *   }}
+ * />
+ * ```
+ */
+declare function LayoutMap<K extends string>({ value, map, ...props }: LayoutMapProps<K>): react_jsx_runtime.JSX.Element;
+
+interface SizeRatchetProps extends HTMLAttributes<HTMLElement> {
+    /** Which axis to ratchet. Default: "height". */
+    axis?: Axis;
+    /** When this key changes, the ratchet floor resets so the container can shrink to its new intrinsic size. */
+    resetKey?: unknown;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Container that never shrinks.
+ *
+ * Remembers its largest-ever size (ResizeObserver ratchet) and applies
+ * min-width/min-height so the container only grows. Swap a spinner for
+ * a table inside — no reflow upstream.
+ *
+ * Uses `contain: layout style` to isolate internal reflow from ancestors.
+ *
+ * @example
+ * ```tsx
+ * <SizeRatchet>
+ *   {isLoading ? <Spinner /> : <DataTable rows={rows} />}
+ * </SizeRatchet>
+ * ```
+ */
+declare const SizeRatchet: react.ForwardRefExoticComponent<SizeRatchetProps & react.RefAttributes<HTMLElement>>;
+
+interface StableCounterProps extends HTMLAttributes<HTMLElement> {
+    /** The actual value to display. */
+    value: ReactNode;
+    /** The maximum expected string/node to pre-allocate width (e.g., "999" or "$99,999"). */
+    reserve: ReactNode;
+    /** HTML element to render. Default: "span" (safe inside inline contexts). */
+    as?: ElementType;
+}
+/**
+ * Numeric/text content swap with zero horizontal layout shift.
+ *
+ * Uses CSS Grid overlap to render a hidden `reserve` node that props open
+ * the bounding box to its maximum expected width. The visible `value` node
+ * renders on top. The container never changes dimensions regardless of
+ * what `value` displays.
+ *
+ * @example
+ * ```tsx
+ * <StableCounter value={count} reserve="999" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <StableCounter value={`$${revenue.toLocaleString()}`} reserve="$99,999" />
+ * ```
+ */
+declare const StableCounter: react.ForwardRefExoticComponent<StableCounterProps & react.RefAttributes<HTMLElement>>;
+
+interface StableFieldProps extends HTMLAttributes<HTMLElement> {
+    /** The actual error message to display. `undefined`/`null` hides the error. */
+    error?: ReactNode;
+    /** The string/node used to permanently reserve the vertical height of the error slot. */
+    reserve: ReactNode;
+}
+/**
+ * Form field wrapper that pre-allocates vertical space for error messages.
+ *
+ * Uses CSS Grid overlap to render a hidden `reserve` node that props open
+ * the error slot to its maximum expected height. The actual error renders
+ * on top when present. The field container never changes height when errors
+ * appear or disappear.
+ *
+ * @example
+ * ```tsx
+ * <StableField error={errors.email} reserve="Please enter a valid email address">
+ *   <label htmlFor="email">Email</label>
+ *   <input id="email" type="email" />
+ * </StableField>
+ * ```
+ */
+declare const StableField: react.ForwardRefExoticComponent<StableFieldProps & react.RefAttributes<HTMLDivElement>>;
+
+interface LoadingBoundaryProps extends HTMLAttributes<HTMLElement> {
+    /** Whether data is loading. Sets LoadingContext for all nested components. */
+    loading: boolean;
+    /**
+     * Crossfade duration in ms. Sets `--sk-loading-exit-duration` on the container
+     * so all nested skeleton transitions use the same timing.
+     */
+    exitDuration: number;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Loading orchestrator — context + ratchet in one component.
+ *
+ * Composes two behaviors:
+ * - **LoadingContext**: every nested `<TextSkeleton>`, `<StableText>`,
+ *   and `<MediaSkeleton>` reads loading state automatically.
+ * - **SizeRatchet**: container never shrinks during transitions.
+ *
+ * Skeleton components handle their own crossfade via CSS opacity
+ * transitions on permanently-mounted layers. The `exitDuration` prop
+ * sets `--sk-loading-exit-duration` on the container so all nested transitions
+ * use the same timing.
+ *
+ * @example
+ * ```tsx
+ * <LoadingBoundary loading={isLoading} exitDuration={150}>
+ *   <MediaSkeleton aspectRatio={1} className="w-16 rounded-full">
+ *     <img src={user.avatar} alt={user.name} />
+ *   </MediaSkeleton>
+ *   <StableText as="h2" className="text-xl font-bold">{user.name}</StableText>
+ *   <StableText as="p" className="text-sm text-muted">{user.email}</StableText>
+ * </LoadingBoundary>
+ * ```
+ */
+declare const LoadingBoundary: react.ForwardRefExoticComponent<LoadingBoundaryProps & react.RefAttributes<HTMLElement>>;
+
+/**
+ * Read the nearest LoadingContext's loading state.
+ * Returns `false` when no LoadingContext ancestor exists.
+ */
+declare function useLoadingState(): boolean;
+interface LoadingContextProps {
+    /** Whether the subtree is in a loading state. */
+    loading: boolean;
+    children: ReactNode;
+}
+/**
+ * Ambient loading provider.
+ *
+ * Wrapping a subtree in `<LoadingContext loading>` lets every nested
+ * `<TextSkeleton>` and `<StableText>` pick up the loading state
+ * automatically, without threading an explicit `loading` prop
+ * through every component.
+ *
+ * @example
+ * ```tsx
+ * <LoadingContext loading={isLoading}>
+ *   <StableText as="h2">{user.name}</StableText>
+ *   <StableText as="p">{user.bio}</StableText>
+ * </LoadingContext>
+ * ```
+ */
+declare function LoadingContext({ loading, children }: LoadingContextProps): react_jsx_runtime.JSX.Element;
+
+interface StableTextProps extends HTMLAttributes<HTMLElement> {
+    /** HTML element to render (p, h1, h2, span, etc.). Default: "p". */
+    as?: ElementType;
+    /** Explicit loading override. Falls back to nearest LoadingContext. */
+    loading?: boolean;
+    /** Forwarded ref (React 19 style). */
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * Typography + skeleton in one tag.
+ *
+ * Combines the semantic HTML wrapper and loading shimmer into one component.
+ * Inside a `<LoadingBoundary>`, every `<StableText>` automatically shimmers.
+ * No forgetting to wrap text in `<TextSkeleton>`. No Swiss-cheese loading states.
+ *
+ * @example
+ * ```tsx
+ * <LoadingBoundary loading={isLoading} exitDuration={150}>
+ *   <StableText as="h1" className="text-2xl font-bold">{user.name}</StableText>
+ *   <StableText className="text-sm text-muted">{user.bio}</StableText>
+ * </LoadingBoundary>
+ * ```
+ */
+declare function StableText({ as: Tag, loading, children, ...props }: StableTextProps): react_jsx_runtime.JSX.Element;
+
+interface TextSkeletonProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * Whether data is loading. Shows shimmer when true, children when false.
+     * When omitted, falls back to the nearest `<LoadingContext>` ancestor's loading state.
+     */
+    loading?: boolean;
+    /** HTML element to render. Default: "span". */
+    as?: ElementType;
+    /** Forwarded ref (React 19 style). */
+    ref?: Ref<HTMLElement>;
+}
+/**
+ * Inline loading shimmer for text.
+ *
+ * Both shimmer and content layers are permanently mounted in the DOM,
+ * stacked via `display: inline-grid` at `grid-area: 1/1`. Loading
+ * state controls only opacity and interactivity (`inert`). CSS
+ * transitions handle the crossfade — no JS state machine, no
+ * structural mutation, no flash.
+ *
+ * The className is passed through so `1lh` inherits the correct font
+ * metrics from the consuming context.
+ *
+ * When no explicit `loading` prop is provided, TextSkeleton reads from
+ * the nearest `<LoadingContext>` ancestor.
+ *
+ * @example
+ * ```tsx
+ * <TextSkeleton loading={isLoading}>{user.name}</TextSkeleton>
+ * ```
+ */
+declare function TextSkeleton({ loading, as: Tag, className, style, children, ...props }: TextSkeletonProps): react_jsx_runtime.JSX.Element;
+
+interface MediaSkeletonProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * Aspect ratio for the media container (e.g. `16/9`, `1`, `4/3`).
+     * Applied as the CSS `aspect-ratio` property, so the container
+     * reserves exact space before any content loads.
+     */
+    aspectRatio: number;
+    /**
+     * Whether media is loading. Shows shimmer when true, children when false.
+     * When omitted, falls back to the nearest `<LoadingContext>` ancestor's loading state.
+     */
+    loading?: boolean;
+    /**
+     * Must be a single React element (img, video, etc.).
+     *
+     * **Do not add dimension classes to the child.** MediaSkeleton enforces
+     * child constraints automatically via React.cloneElement. The child
+     * cannot break out of the frame.
+     */
+    children: ReactElement;
+}
+/**
+ * Aspect-ratio media placeholder with automatic child constraints.
+ *
+ * Reserves space via `aspect-ratio` so the bounding box is stable
+ * before media loads. Enforces child constraints via `cloneElement`
+ * inline styles — no CSS `!important`, no developer discipline needed.
+ *
+ * The shimmer stays visible until **both** the loading context resolves
+ * AND the child media fires `onLoad`. This prevents an empty-frame
+ * flash between skeleton exit and image paint.
+ *
+ * The child can override `objectFit` (e.g. `contain`) via its own
+ * inline `style` prop, but positional constraints are non-negotiable.
+ *
+ * @example
+ * ```tsx
+ * <MediaSkeleton aspectRatio={16/9}>
+ *   <img src={src} alt={alt} />
+ * </MediaSkeleton>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <MediaSkeleton aspectRatio={1} className="rounded-full">
+ *   <img src={avatar} alt={name} />
+ * </MediaSkeleton>
+ * ```
+ */
+declare function MediaSkeleton({ aspectRatio, loading, className, style, children, ...props }: MediaSkeletonProps): react_jsx_runtime.JSX.Element;
+
+interface CollectionSkeletonProps<T> extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** Data items to render. */
+    items: T[];
+    /** Whether data is loading. Shows skeleton stubs when true. */
+    loading: boolean;
+    /** Render function for each item. */
+    renderItem: (item: T, index: number) => ReactNode;
+    /** Number of placeholder rows during loading. */
+    stubCount: number;
+    /** Crossfade duration in ms. Sets --sk-loading-exit-duration for the opacity transition. */
+    exitDuration: number;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Loading-aware list with automatic skeleton stubs.
+ *
+ * Both the skeleton grid and rendered items are permanently mounted
+ * in the DOM, stacked via CSS grid overlap. Loading state controls
+ * only opacity and interactivity. CSS transitions handle the crossfade.
+ *
+ * Wrapped in a SizeRatchet so the container never shrinks.
+ *
+ * @example
+ * ```tsx
+ * <CollectionSkeleton
+ *   items={users}
+ *   loading={isLoading}
+ *   stubCount={5}
+ *   exitDuration={150}
+ *   renderItem={(user) => <UserRow key={user.id} user={user} />}
+ * />
+ * ```
+ */
+declare const CollectionSkeleton: <T>(props: CollectionSkeletonProps<T> & {
+    ref?: Ref<HTMLElement>;
+}) => ReactElement | null;
+
+interface FadeTransitionProps extends HTMLAttributes<HTMLElement> {
+    /** Whether the content is visible. */
+    show: boolean;
+    /** HTML element to render. Default: "div". */
+    as?: ElementType;
+}
+/**
+ * Enter/exit animation wrapper.
+ *
+ * Mounts when `show` becomes true, plays enter animation.
+ * When `show` becomes false, plays exit animation then unmounts.
+ *
+ * CSS classes applied: `sk-fade-entering`, `sk-fade-exiting`.
+ * Duration controlled via `--sk-fade-duration` CSS variable.
+ *
+ * @example
+ * ```tsx
+ * <FadeTransition show={isOpen}>
+ *   <DropdownPanel />
+ * </FadeTransition>
+ * ```
+ */
+declare const FadeTransition: react.ForwardRefExoticComponent<FadeTransitionProps & react.RefAttributes<HTMLElement>>;
+
+/**
+ * Creates a firewalled UI primitive.
+ *
+ * - className and style are blocked at the type level
+ * - Variant props are auto-mapped to data-attributes
+ * - All other HTML attributes pass through
+ */
+declare function createPrimitive<Tag extends keyof JSX.IntrinsicElements, const Variants extends Record<string, readonly string[]> = {}>(tag: Tag, baseClass: string, variants?: Variants): (props: Omit<JSX.IntrinsicElements[Tag], "style" | "className" | keyof Variants> & { [K in keyof Variants]: Variants[K][number]; }) => react.DOMElement<Record<string, unknown>, Element>;
+
+export { type Axis, CollectionSkeleton, type CollectionSkeletonProps, FadeTransition, type FadeTransitionProps, LayoutGroup, type LayoutGroupProps, LayoutMap, type LayoutMapProps, LayoutView, type LayoutViewProps, LoadingBoundary, type LoadingBoundaryProps, LoadingContext, type LoadingContextProps, MediaSkeleton, type MediaSkeletonProps, SizeRatchet, type SizeRatchetProps, StableCounter, type StableCounterProps, StableField, type StableFieldProps, StableText, type StableTextProps, StateSwap, type StateSwapProps, TextSkeleton, type TextSkeletonProps, createPrimitive, useLoadingState };