@box-kite/react 0.0.1 → 1.0.0

package/platform.cjs

@@ -0,0 +1 @@
+function e(e){return e?`current`in e?e.current:e:null}function t(t){let n=e(t);return n instanceof HTMLElement?n:null}function n(t,n){let r=typeof t.composedPath==`function`?t.composedPath():[];return n.some(n=>{let i=e(n);return i?r.includes(i)||t.target instanceof Node&&i.contains(t.target):!1})}function r(t){let n=e(t),r=n?.ownerDocument?.defaultView;return!!n&&!!r&&r.getComputedStyle(n).direction===`rtl`}function i(){return typeof window<`u`&&window.document!==void 0}function a(){return typeof document<`u`}function o(){return a()?document:null}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return n}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return e}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return o}});

package/platform.mjs

@@ -0,0 +1,32 @@
+//#region src/utils/dom/domUtils.ts
+function e(e) {
+	return e ? "current" in e ? e.current : e : null;
+}
+function t(t) {
+	let n = e(t);
+	return n instanceof HTMLElement ? n : null;
+}
+function n(t, n) {
+	let r = typeof t.composedPath == "function" ? t.composedPath() : [];
+	return n.some((n) => {
+		let i = e(n);
+		return i ? r.includes(i) || t.target instanceof Node && i.contains(t.target) : !1;
+	});
+}
+function r(t) {
+	let n = e(t), r = n?.ownerDocument?.defaultView;
+	return !!n && !!r && r.getComputedStyle(n).direction === "rtl";
+}
+//#endregion
+//#region src/utils/environment/environmentUtils.ts
+function i() {
+	return typeof window < "u" && window.document !== void 0;
+}
+function a() {
+	return typeof document < "u";
+}
+function o() {
+	return a() ? document : null;
+}
+//#endregion
+export { n as a, t as i, i as n, r as o, e as r, o as t };

package/react/a11y/callbacks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Handler identity, which every hook here has the same problem with: a document listener must not
+ * be torn down and re-registered on every render, but it must still call the consumer's *current*
+ * handler — and consumers write handlers inline, so a new one arrives with every render.
+ */
+/**
+ * The latest value, readable from an event handler that must not be re-registered when it changes. Written
+ * from an effect rather than during render, which costs nothing here: it is only read from an event.
+ */
+export declare function useLatest<T>(value: T): React.RefObject<T>;
+/** A callback with a stable identity that always calls the *latest* function it was given. */
+export declare function useEventCallback<TArgs extends unknown[], TResult>(fn: ((...args: TArgs) => TResult) | undefined): (...args: TArgs) => TResult | undefined;

package/react/a11y/useControllableState.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Why a change happened, and the event that caused it — the reason being the point. A component that only
+ * says `onOpenChange(false)` makes its consumer guess whether the popup closed because the user picked
+ * something, pressed Escape or clicked away, and each of those wants different behaviour from the app.
+ */
+export interface ChangeDetails<TReason extends string = string> {
+    reason: TReason;
+    /** The DOM or React event behind the change, when there was one. */
+    event?: Event | React.SyntheticEvent;
+}
+export type ChangeHandler<T, TReason extends string = string> = (value: T, details: ChangeDetails<TReason>) => void;
+export interface ControllableStateOptions<T, TReason extends string = string> {
+    /** Present (not `undefined`) means the consumer owns the value: state here is ignored. */
+    value?: T;
+    /** The starting value when the consumer does not own it. A function is called once, lazily. */
+    defaultValue: T | (() => T);
+    onChange?: ChangeHandler<T, TReason>;
+}
+export type SetControllableState<T, TReason extends string = string> = (next: T | ((current: T) => T), details: ChangeDetails<TReason>) => void;
+/**
+ * One state value that works the same whether the consumer controls it or not. The setter is stable, and
+ * every call names a reason, which is what reaches `onChange`. A call resolving to the value already held
+ * is dropped: two dismissal layers closing the same popup is the normal case, not an error.
+ */
+export default function useControllableState<T, TReason extends string = string>(options: ControllableStateOptions<T, TReason>): [T, SetControllableState<T, TReason>];

package/react/a11y/useDismiss.d.ts

@@ -0,0 +1,25 @@
+import { ElementLike } from '../../utils/dom/domUtils';
+export type DismissReason = 'escape' | 'outside-pointer';
+export type { ElementLike };
+export interface DismissOptions {
+    /** Usually the open state: listeners exist only while this is true. */
+    enabled?: boolean;
+    onDismiss: (reason: DismissReason, event: Event) => void;
+    /**
+     * What counts as *inside*: the popup, and the trigger too — a press on the trigger of an open popup must
+     * reach its own toggle rather than being dismissed and reopened in one gesture.
+     */
+    inside?: ReadonlyArray<ElementLike>;
+    /** Default true. */
+    escapeKey?: boolean;
+    /** Default true. */
+    outsidePointer?: boolean;
+}
+/**
+ * Close on Escape and on a pointer press outside — the two halves of light dismiss, composable across
+ * nested layers: Escape reaches the innermost only, while an outside press is judged per layer, so a
+ * press in the page closes a menu and its submenu and a press in the menu closes just the submenu.
+ * `pointerdown` rather than `click`, because a press that starts inside and ends outside (a drag across a
+ * scrollbar, a text selection) is not a dismissal.
+ */
+export default function useDismiss(options: DismissOptions): void;

package/react/a11y/useFocusReturn.d.ts

@@ -0,0 +1,18 @@
+import { ElementLike } from '../../utils/dom/domUtils';
+export interface FocusReturnOptions {
+    /** Usually the open state. The invoker is remembered the moment this becomes true. */
+    enabled?: boolean;
+    /** Where focus should land instead of whatever had it when the layer opened. */
+    returnTo?: ElementLike;
+    /** Passed to `focus()` — keeps a long page from jumping when the invoker is off screen. */
+    preventScroll?: boolean;
+}
+/**
+ * Put focus back where it came from when a layer closes. Losing it to `<body>` is the commonest keyboard
+ * bug in a popup: the next Tab starts again at the top of the page. Skipped when something else already
+ * holds focus — a dialog the layer opened, or a user who tabbed away — since taking it back is the same
+ * bug pointing the other way.
+ */
+export default function useFocusReturn(options?: FocusReturnOptions): {
+    returnFocus: () => void;
+};

package/react/a11y/useIdentifier.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A stable, unique id for wiring one element to another — `aria-labelledby`, `aria-controls`,
+ * `aria-activedescendant`, `<label for>`.
+ *
+ * Stable means: the same across renders, the same on the server and on the client (so hydration
+ * does not throw the markup away), and different for every instance of a component. Derive related
+ * ids from one call rather than calling the hook per element:
+ *
+ * ```ts
+ * const id = useIdentifier('select');
+ * // `${id}-trigger`, `${id}-listbox`
+ * ```
+ *
+ * On React 16/17 the fallback is a module counter, which cannot match between a server render and
+ * the client one — pass ids in explicitly there if the tree is hydrated.
+ */
+export default function useIdentifier(prefix?: string): string;

package/react/a11y/useRovingFocus.d.ts

@@ -0,0 +1,84 @@
+import { ChangeDetails, ChangeHandler } from './useControllableState';
+export type RovingFocusReason = 'keyboard' | 'typeahead' | 'focus' | 'programmatic';
+export type RovingOrientation = 'vertical' | 'horizontal' | 'both';
+/** A position in grid mode. Both are `-1` when nothing is active. */
+export interface RovingCell {
+    row: number;
+    column: number;
+}
+export interface RovingFocusOptions {
+    /** How many items there are right now — rows, in grid mode. A filtered list may change this. */
+    count: number;
+    /**
+     * Turns the list into a grid and `count` into a count of rows: how many cells the row at `row` holds, a
+     * function when rows differ. Grid mode moves in two axes and never wraps (APG), Home/End go to the
+     * row's ends, Ctrl+Home/End to the grid's corners, PageUp/PageDown by `pageSize` rows.
+     */
+    columns?: number | ((row: number) => number);
+    /**
+     * Where a cell starts in column-index space, for rows whose cells do not line up one-to-one with the
+     * grid's columns (a grouped header, a spanning group row). Vertical movement is measured in this space,
+     * so a move down out of a cell covering columns 4–6 lands under the column it started in. Identity by default.
+     */
+    columnIndexOf?: (row: number, cell: number) => number;
+    /** Rows a PageUp/PageDown moves. Default 10. Grid mode only. */
+    pageSize?: number;
+    /** The starting column *index*, when the caller wants one other than the first. Grid mode only. */
+    defaultActiveColumn?: number;
+    /** The active cell moved. Grid mode only — `onActiveIndexChange` still reports the row. */
+    onActiveCellChange?: ChangeHandler<RovingCell, RovingFocusReason>;
+    /** Which arrow keys navigate. Default `vertical`. Ignored in grid mode, which uses both axes. */
+    orientation?: RovingOrientation;
+    /** Wrap around at the ends. Default true. */
+    loop?: boolean;
+    activeIndex?: number;
+    defaultActiveIndex?: number;
+    onActiveIndexChange?: ChangeHandler<number, RovingFocusReason>;
+    /** Disabled items are skipped by every movement, as APG requires. */
+    isDisabled?: (index: number) => boolean;
+    /** An item's text. Supplying it turns on typeahead. */
+    textOf?: (index: number) => string;
+    /**
+     * Move real DOM focus onto the active item — the roving-tabindex pattern. `false` is the other half of
+     * the APG list patterns: focus stays put (a combobox's trigger) and `aria-activedescendant` names the
+     * active item instead. The hook still tracks the index; it just does not take focus.
+     */
+    focusItems?: boolean;
+    /** Enter, and Space when no typeahead buffer is open. */
+    onSelect?: (index: number, event: React.KeyboardEvent) => void;
+}
+export interface RovingFocusItemProps {
+    ref: (element: HTMLElement | null) => void;
+    tabIndex?: number;
+    onFocus?: () => void;
+}
+export interface RovingFocus {
+    /** Clamped to the current `count`; `-1` when nothing is active. The row, in grid mode. */
+    activeIndex: number;
+    /**
+     * The active cell's ordinal in its row — its column index only while no cell spans more than one column.
+     * `-1` outside grid mode.
+     */
+    activeColumn: number;
+    setActiveIndex: (index: number, details: ChangeDetails<RovingFocusReason>) => void;
+    /** Grid mode: move both axes at once, `column` being a cell ordinal. Out-of-range values are clamped. */
+    setActiveCell: (row: number, column: number, details: ChangeDetails<RovingFocusReason>) => void;
+    /** Put this on the element that has focus: the list in roving-tabindex, the trigger otherwise. */
+    onKeyDown: (event: React.KeyboardEvent) => void;
+    itemProps: (index: number) => RovingFocusItemProps;
+    /** Grid mode's `itemProps`: the roving tabindex and the ref for one cell. */
+    cellProps: (row: number, column: number) => RovingFocusItemProps;
+    /**
+     * The active item's element, for `aria-activedescendant` or to scroll it into view. `null` in grid mode
+     * whenever the active cell is not rendered, which a virtualized grid is full of: bring the row into view
+     * first, then read this on the render that follows.
+     */
+    activeItem: () => HTMLElement | null;
+}
+/**
+ * Arrow-key navigation over a list: the movement half of every APG list pattern (listbox, menu, tabs,
+ * radio group), with both focus strategies. It owns which item is active and how the keys move it; the
+ * caller owns the roles and the ARIA, because a listbox and a menu navigate alike and are named quite
+ * differently. `columns` turns the same movement into APG's grid pattern, and may be a function of the row.
+ */
+export default function useRovingFocus(options: RovingFocusOptions): RovingFocus;

package/react/animation/usePresence.d.ts

@@ -0,0 +1,32 @@
+import { RefCallback } from 'react';
+/** The Radix / Base UI attribute value, so a `[data-state]` selector written for either works here too. */
+export type PresenceState = 'open' | 'closed';
+export interface PresenceOptions {
+    /** Whether the subtree should be there. The exit starts the moment this goes false. */
+    present: boolean;
+}
+export interface Presence {
+    /** Whether to render anything at all: true for the whole exit, false once it has finished. */
+    mounted: boolean;
+    /** False from the first frame of the exit — the flag the leaving styles hang off. */
+    present: boolean;
+    state: PresenceState;
+    /** Goes on the element that carries the transition: its computed style is what the wait is measured from. */
+    ref: RefCallback<HTMLElement>;
+    /** `{ 'data-state': … }`, ready to spread into a Box's `props`. */
+    props: {
+        'data-state': PresenceState;
+    };
+}
+/**
+ * Holds a subtree long enough for its exit to run, then lets it go. React removes a node the instant it
+ * stops rendering it, which is why `startingStyle` can animate an entrance with no JavaScript and nothing
+ * can animate an exit: by the time the styles would change, the element is already gone.
+ *
+ * **The wait is the duration the element's own CSS declares**, read off the node the moment the exit
+ * starts. `transitionend` would be more precise but fires once per property with no way to know how many
+ * are coming, so the first one cuts a two-property exit short — and a transition that never starts fires
+ * nothing at all, so an event-driven wait needs this timer as a backstop anyway. One mechanism, sized from
+ * the real CSS: a zero duration (nothing declared, or `prefers-reduced-motion`) unmounts in the same commit.
+ */
+export default function usePresence(options: PresenceOptions): Presence;

package/react/boxClassNames.d.ts

@@ -0,0 +1,25 @@
+import { ClassNameType } from '@box-kite/core';
+import { ResolvedBoxStyles } from './resolveStyles';
+/**
+ * What `useClassNames` hands back: the class attribute for an element this library does not render
+ * itself, and — in element mode only — the `<style>` elements those classes need.
+ */
+export interface BoxClassNames {
+    /** The whole `class` attribute, the engine's classes and the caller's own, already joined. */
+    className: string;
+    /**
+     * Element mode only: the hoistable `<style>` elements the classes need. Render them beside the
+     * element (React 19 lifts them into `<head>`). Undefined in every other mode, where the CSS has
+     * already gone to a stylesheet and there is nothing left to render.
+     */
+    styles?: ResolvedBoxStyles['styleElements'];
+}
+/**
+ * The resolved styles as a class attribute. Hook-free, so the client entry and the Server-Component
+ * one give `useClassNames` the same shape — the only difference between them is whether resolving
+ * the styles scheduled a flush effect.
+ */
+export default function boxClassNames({ classNames: styleClasses, styleElements }: ResolvedBoxStyles, userClassName?: ClassNameType): {
+    className: string;
+    styles: import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>[] | undefined;
+};

package/react/boxProps.d.ts

@@ -0,0 +1,49 @@
+import { default as React } from 'react';
+import { ClassNameType } from '@box-kite/core';
+import { BoxStyleProps, ComponentsAndVariants } from '@box-kite/core/types';
+/**
+ * The prop shape of Box, shared by the client component and the Server-Component one so the public
+ * surface cannot drift between them.
+ */
+type AllProps<TTag extends keyof React.JSX.IntrinsicElements> = React.ComponentProps<TTag>;
+/** `data-*`, which React's own attribute types allow only in JSX position and never in a props bag. */
+type DataAttributes = {
+    [attribute: `data-${string}`]: string | number | boolean | undefined;
+};
+type TagProps<TTag extends keyof React.JSX.IntrinsicElements> = Omit<AllProps<TTag>, 'className' | 'style' | 'ref' | 'disabled' | 'required' | 'checked' | 'id'>;
+/**
+ * Every attribute the tag takes, plus `data-*` (bug #99: `props={{ 'data-state': 'open' }}` did not
+ * typecheck, and `<Box data-state>` did but was dropped, since Box forwards nothing but `props`). A union
+ * rather than an intersection: an index signature in the target makes every *interface* passed as a bag
+ * unassignable, and `TooltipTrigger.props` is one. Anything else unknown still fails.
+ */
+export type TagPropsType<TTag extends keyof React.JSX.IntrinsicElements> = TagProps<TTag> | (TagProps<TTag> & DataAttributes);
+/**
+ * `Omit` one union member at a time, for a component claiming attributes of its own. A plain `Omit` over
+ * a union keeps only the keys every member shares, so it collapsed the two above into one and dropped
+ * `data-*` again — bug #99 one layer up, on every pre-built component.
+ */
+export type OmitTagProps<TProps, TKeys extends PropertyKey> = TProps extends unknown ? Omit<TProps, TKeys> : never;
+/**
+ * The style props plus the `className` the engine's classes are merged with — everything the
+ * resolution needs and nothing about a tag. `useClassNames` takes this, which is why it can style
+ * an element this library does not render.
+ */
+export interface BoxClassNameProps<TKey extends keyof ComponentsAndVariants = never> extends BoxStyleProps<TKey> {
+    /** classNames. supports conditional classNames. */
+    className?: ClassNameType;
+}
+export interface BoxCoreProps<TTag extends keyof React.JSX.IntrinsicElements, TKey extends keyof ComponentsAndVariants> extends BoxClassNameProps<TKey> {
+    children?: React.ReactNode | ((props: {
+        isHover: boolean;
+    }) => React.ReactNode);
+    /** html tag element */
+    tag?: TTag;
+    /** props (attributes) related to html tag */
+    props?: TagPropsType<TTag>;
+    /** CSSProperties */
+    style?: React.ComponentProps<TTag>['style'];
+    /** The HTML id attribute is used to specify a unique id for an HTML element. */
+    id?: string;
+}
+export {};

package/react/boxTagProps.d.ts

@@ -0,0 +1,7 @@
+import { BoxStyleProps } from '@box-kite/core/types';
+/**
+ * The props that reach the HTML tag: whatever the caller put in `props`, the resolved class list,
+ * and the handful of attributes Box lifts to its own top level. Hook-free, so the client Box and
+ * the Server-Component Box assemble their markup through the same code.
+ */
+export default function buildTagProps(source: BoxStyleProps<any>, styleClasses: string[]): Record<string, any>;

package/react/clientRuntime.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The client half of the library needs React APIs the server build does not have. Under the `react-server`
+ * condition they are absent, so the first one touched at import time throws `createContext is not a
+ * function` — no file, no component, nothing to act on (bug #43). The published build prevents that; this
+ * is for the ways around it: a deep import, a bundler with no condition, a framework mixing the graphs.
+ */
+export declare const CLIENT_RUNTIME_MESSAGE: string;
+/** Throws with something readable if `react` is the server build. Called where the first one is needed. */
+export default function assertClientRuntime(react: {
+    createContext?: unknown;
+}): void;

package/react/effects.d.ts

@@ -0,0 +1,10 @@
+import { default as React, useLayoutEffect } from 'react';
+/** A layout effect on the browser, a passive one everywhere else. */
+export declare const useIsomorphicLayoutEffect: typeof React.useEffect;
+/**
+ * An insertion effect on the browser, falling back to a layout effect on React 16/17 — React's own
+ * recommendation for injecting CSS-in-JS. Insertion effects run during the commit ahead of *every* layout
+ * effect, so a component measuring its DOM already sees the styles. Off the browser nothing paints and
+ * `getStyles()` flushes for itself, so `useEffect` keeps React quiet.
+ */
+export declare const useIsomorphicInsertionEffect: typeof useLayoutEffect;

package/react/forms/labelledControl.d.ts

@@ -0,0 +1,17 @@
+import { BoxProps } from '../../box';
+export interface LabelledControlProps {
+    /** The text beside the control. Nothing is wrapped while this is absent. */
+    label?: React.ReactNode;
+    /** Styles for the `<label>` that wraps the pair — layout, not the control's own appearance. */
+    labelProps?: BoxProps<'label'>;
+    /** The control itself: an `<input>` that must end up *inside* the label element. */
+    children: React.ReactNode;
+}
+/**
+ * A form control and its text inside the one `<label>` that ties them together, implicitly: nothing has to
+ * be unique (an explicit `for`/`id` pair needs `useId`, a hook, so `RadioButton` would stop rendering on a
+ * server) and there is one element to click, so the whole row is a hit target. The text is a bare child
+ * rather than a `<Span>`, because a module several chunks share must not import a component chunk — that
+ * cycle left `StringUtils` undefined as soon as `semantics.mjs` loaded.
+ */
+export default function LabelledControl({ label, labelProps, children }: LabelledControlProps): React.ReactNode;

package/react/forms/placeholderProp.d.ts

@@ -0,0 +1,13 @@
+import { BoxPseudoElementStyles } from '@box-kite/core/types';
+/**
+ * `placeholder` is an attribute on an `<input>` and a pseudo-element on a Box, and both readings are
+ * right — the same collision `Rect`'s `width` and `Path`'s `d` have, settled per element. A string is the
+ * text, an object is the `::placeholder` styles, and both at once means the text goes in `props`, where
+ * every other attribute already goes.
+ */
+export type PlaceholderProp = string | BoxPseudoElementStyles;
+/** The prop split into the two things it can be: `text` for the attribute, `styles` for the Box prop. */
+export default function splitPlaceholder(placeholder: PlaceholderProp | undefined): {
+    text?: string;
+    styles?: BoxPseudoElementStyles;
+};

package/react/hooks/usePortalContainer.d.ts

@@ -0,0 +1 @@
+export default function usePortalContainer(): HTMLElement | null;

package/react/hooks/useVirtualization.d.ts

@@ -0,0 +1,43 @@
+export interface UseVirtualizationOptions {
+    /** Total number of items */
+    itemCount: number;
+    /** Height of each item in pixels */
+    itemHeight: number;
+    /** Height of the visible container in pixels */
+    containerHeight: number;
+    /** Number of items to render outside visible area (default: 3) */
+    overscan?: number;
+    /** Whether virtualization is enabled (default: true when itemCount > threshold) */
+    enabled?: boolean;
+    /** Threshold for enabling virtualization (default: 50) */
+    threshold?: number;
+}
+export interface UseVirtualizationResult {
+    /** First item index to render */
+    startIndex: number;
+    /** Last item index to render (inclusive) */
+    endIndex: number;
+    /** Total height of all items (for scroll container) */
+    totalHeight: number;
+    /** Y offset for positioning visible items */
+    offsetY: number;
+    /** Number of visible items */
+    visibleCount: number;
+    /** Whether virtualization is active */
+    isVirtualized: boolean;
+    /** Scroll event handler - attach to container's onScroll */
+    handleScroll: (e: React.UIEvent<HTMLElement>) => void;
+    /** Current scroll position */
+    scrollTop: number;
+    /** Container style for the scroll area */
+    containerStyle: React.CSSProperties;
+    /** Inner wrapper style (total height) */
+    innerStyle: React.CSSProperties;
+    /** Content style (transform offset) */
+    contentStyle: React.CSSProperties;
+}
+/**
+ * Hook for virtualizing large lists.
+ * Only renders items that are visible in the viewport plus overscan buffer.
+ */
+export default function useVirtualization(options: UseVirtualizationOptions): UseVirtualizationResult;

package/react/hooks/useVisibility.d.ts

@@ -0,0 +1,9 @@
+interface Props<T extends HTMLElement = HTMLDivElement> {
+    node?: T | null;
+    event?: 'mousedown' | 'click';
+    hideOnScroll?: boolean;
+    hideOnResize?: boolean;
+    hideOnEscape?: boolean;
+}
+export default function useVisibility<T extends HTMLElement = HTMLDivElement>(props?: Props<T>): [boolean, React.Dispatch<React.SetStateAction<boolean>>, React.RefObject<T | null>];
+export {};

package/react/reactTypes.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+/**
+ * React-only type helpers. These live in the adapter rather than in `src/core/coreTypes.ts`
+ * because they are expressed in React's own JSX types — the style definitions themselves stay
+ * framework-free so every adapter can share them.
+ */
+/** The DOM element type behind a set of React props (`HTMLAttributes<E>` / `SVGProps<E>` → `E`). */
+export type ExtractElementType<T> = T extends React.DetailedHTMLProps<React.HTMLAttributes<infer E>, infer E> ? E : T extends React.SVGProps<infer E> ? E : never;
+/** The DOM element type behind an intrinsic tag name (`'input'` → `HTMLInputElement`). */
+export type ExtractElementFromTag<T extends keyof React.JSX.IntrinsicElements> = ExtractElementType<React.JSX.IntrinsicElements[T]>;

package/react/resolveStyles.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+import { BoxStyleProps } from '@box-kite/core/types';
+export interface ResolvedBoxStyles {
+    classNames: string[];
+    /**
+     * Element mode only: the hoistable `<style>` elements this Box's classes need, the engine's base
+     * element first. Undefined in every other mode, where the CSS has already gone to a stylesheet.
+     */
+    styleElements?: React.ReactElement[];
+}
+/**
+ * Resolve a Box's classes with no hook at all — the render path a Server Component takes. In element mode
+ * what those classes need comes back as elements to render, so there is nothing to flush. Its own module
+ * for that reason: the RSC entry must reach this without pulling in `useStyles` and its flush effect.
+ */
+export default function resolveStyles(props: BoxStyleProps<any>, isSvg: boolean): ResolvedBoxStyles & {
+    signature: string | null;
+};

package/react/styleElements.d.ts

@@ -0,0 +1,3 @@
+import { default as React } from 'react';
+import { StyleElementDescriptor } from '@box-kite/core';
+export default function styleElementsOf(descriptors: readonly StyleElementDescriptor[] | undefined): React.ReactElement[] | undefined;

package/react/svg/attributesInProps.d.ts

@@ -0,0 +1,4 @@
+/** Marks a component of this library's own: its DOM attributes belong in `props`, not on top. */
+export declare function withAttributesInProps<TComponent>(component: TComponent): TComponent;
+/** Whether an element's `type` is one of those components. Anything else takes attributes on top. */
+export declare function hasAttributesInProps(type: unknown): boolean;

package/react/svg/svgNaming.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A drawing nobody named is decoration, which `aria-hidden` says and silence leaves ambiguous; `label` is
+ * the opt-in that makes it `role="img"`. The same rule for every `<svg>` this library puts on a page,
+ * whether it renders the element (`Svg`) or hands the attributes to one somebody else renders (`Icon`).
+ * `given` is naming the caller wrote by hand — if there is any, the decision was theirs.
+ */
+export default function svgNaming(label: string | undefined, given: object | undefined): {
+    role: string;
+    'aria-label': string;
+    'aria-hidden'?: undefined;
+} | {
+    'aria-hidden': boolean;
+    role?: undefined;
+    'aria-label'?: undefined;
+} | undefined;

package/react/theme/theme.d.ts

@@ -0,0 +1,26 @@
+import { default as React } from 'react';
+import { BoxStyleProps } from '@box-kite/core/types';
+interface ThemeProps {
+    children: React.ReactNode;
+    theme?: string;
+    use?: 'global' | 'local';
+    /** When provided, persists the user-selected theme to localStorage under this key. */
+    storageKey?: string;
+    /**
+     * App-wide Box style props applied to the document root (`<html>`). Only takes effect when `use="global"`.
+     * Supports the same shape as Box props, including theme-keyed values:
+     * `globalStyles={{ scrollbarColor: ['violet-500', 'transparent'], theme: { dark: { scrollbarColor: [...] } } }}`.
+     */
+    globalStyles?: BoxStyleProps;
+}
+/**
+ * The React binding for the theme system. Everything that actually touches the platform — reading
+ * and watching `prefers-color-scheme`, persisting the choice, writing the theme onto an element —
+ * lives in the framework-free `core/theme/themeRuntime`; this component only holds the React state
+ * and context around it.
+ */
+declare function Theme(props: ThemeProps): React.JSX.Element;
+declare namespace Theme {
+    function useTheme(): [string, (theme: string | null) => void];
+}
+export default Theme;

package/react/theme/themeContext.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+interface ThemeContextProps {
+    theme: string;
+    setTheme(theme: string | null): void;
+}
+declare const ThemeContext: React.Context<ThemeContextProps>;
+export default ThemeContext;

package/react/useStyles.d.ts

@@ -0,0 +1,22 @@
+import { StylesConfiguration } from '@box-kite/core';
+import { BoxStyleProps } from '@box-kite/core/types';
+import { ResolvedBoxStyles } from './resolveStyles';
+export type { StylesConfiguration };
+export default function useStyles(props: BoxStyleProps<any>, isSvg: boolean): ResolvedBoxStyles;
+/**
+ * Rules that target a root selector (`html`) instead of a class. Returns their style elements in
+ * element mode — global styles belong to no Box, so the caller has to render them itself.
+ */
+export declare function useGlobalStyles(props: BoxStyleProps<any> | undefined, selector: string): React.ReactElement[] | undefined;
+/** Engine controls for the default instance. For an isolated engine use `createStyleEngine()`. */
+export declare namespace StylesContext {
+    /** Write every pending rule now. The React binding calls this from an insertion effect. */
+    function flushSync(): void;
+    function clear(): void;
+    /** The CSS emitted so far, as text. Flushes first — see `StyleEngine.getStyles`. */
+    function getStyles(): string;
+    /** The id of the `<style>` element the default engine writes to. */
+    function styleElementId(): string;
+    /** Apply explicit engine configuration. Call before the first render — cached class names are dropped when the configuration changes. */
+    function configure(config: StylesConfiguration): void;
+}

package/react-shared.cjs

@@ -0,0 +1 @@
+const e=require("./rolldown-runtime.cjs");let t=require("react");t=e.t(t,1);let n=require("@box-kite/core");function r({classNames:e,styleElements:t},r){return{className:(0,n.classNames)(e,r).join(` `),styles:t}}var i={selected:`aria-selected`},a;(function(e){function t(e,t,n){e!==void 0&&e!=null&&(n[i[t]??t]=Array.isArray(e)?e[0]:e)}e.assignBooleanProp=t})(a||={});var o=a;function s(e,t){let r=e,{props:i,className:a,disabled:s,required:c,checked:l,selected:u}=r,d={...i,className:(0,n.classNames)(t,a).join(` `)};return o.assignBooleanProp(s,`disabled`,d),o.assignBooleanProp(c,`required`,d),o.assignBooleanProp(l,`checked`,d),o.assignBooleanProp(u,`selected`,d),`style`in r&&(d.style=r.style),`id`in r&&(d.id=r.id),d}var c=parseInt(t.default.version,10)>=19,l=!1;function u(e){if(e?.length)return!c&&!l&&(l=!0,console.warn(`[box-kite] Box.configure({ sink: 'element' }) needs React 19 to hoist and dedupe its <style> elements; React ${t.default.version} will render them inline. Use the default sink instead.`)),e.map(({href:e,css:n,precedence:r})=>t.default.createElement(`style`,{key:e,href:e,precedence:r,dangerouslySetInnerHTML:{__html:n}}))}function d(e,t){let{classNames:r,signature:i,styleElements:a}=(0,n.getDefaultEngine)().resolveClassNames(e,t);return{classNames:r,signature:i,styleElements:u(a)}}var f=`__boxAttributesInProps`;function p(e){return e[f]=!0,e}function m(e){return typeof e==`function`||typeof e==`object`&&e?e[f]===!0:!1}var h=[`role`,`aria-label`,`aria-labelledby`,`aria-hidden`];function g(e,t){if(e!==void 0)return{role:`img`,"aria-label":e};if(!(t&&h.some(e=>e in t)))return{"aria-hidden":!0}}var _;(function(e){function t(e){return e.charAt(0).toUpperCase()+e.slice(1)}e.capitalize=t})(_||={});var v=_,y;(function(e){function t(e,t,n){let r={...e},i=r.props||{};return t.forEach(e=>{e in r&&(i[e]=r[e],delete r[e])}),n&&Object.entries(n).forEach(([e,t])=>{i[e]=t}),r.props=i,r}e.buildProps=t;function n(e){return!!e&&typeof e==`object`}e.isObject=n;function r(e,t){return e in t}e.isKeyOf=r})(y||={});var b=y;Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return p}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return m}}),Object.defineProperty(exports,"l",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return v}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return d}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return g}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return b}});