@box-kite/react 0.0.1 → 2.0.0

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/anchor/useAnchorPosition.d.ts

@@ -0,0 +1,79 @@
+import { CSSProperties } from 'react';
+import { BoxStyleProps } from '@box-kite/core/types';
+import { AnchorAlign, AnchorSide } from '../../utils/anchor/anchorUtils';
+import { ElementLike } from '../../utils/dom/domUtils';
+export interface AnchorPositionOptions {
+    /** Which side of the anchor to sit on. `top`/`bottom` are the block axis, `start`/`end` the inline one. Default `'bottom'`. */
+    side?: AnchorSide;
+    /** Which of the anchor's edges to line up with along the other axis. Default `'center'`. */
+    align?: AnchorAlign;
+    /** The gap between anchor and layer, on the ÷4 spacing scale — `offset: 2` is 8px. Default `0`. */
+    offset?: number;
+    /**
+     * Whether the browser may move the layer where it does not fit: the side swapped for its opposite, the
+     * alignment mirrored, or both — three candidates, since a candidate has to fit on both axes. Default `true`.
+     */
+    flip?: boolean;
+    /** Whether the layer is at least as wide as its anchor, the way a select popup is. Default `false`. */
+    matchWidth?: boolean;
+    /** The anchor's name. Generated per instance when omitted, which is what keeps two layers apart. */
+    name?: string;
+    /**
+     * The anchor as an element rather than props to spread — for a caller handed a trigger it does not
+     * render itself. The name is written onto it in a layout effect, so a ref is read when the layer mounts.
+     */
+    anchor?: ElementLike;
+    /**
+     * Whether `side` reports where the layer ended up rather than where it was asked to go. Off by default,
+     * because on the CSS path it costs the one thing that path otherwise never does: a read after layout.
+     */
+    trackSide?: boolean;
+}
+/** The two anchor-positioning properties, which csstype does not know yet. An inline style, deliberately — see the hook. */
+type AnchorStyle = CSSProperties & {
+    anchorName?: string;
+    positionAnchor?: string;
+};
+/** What goes on the anchor: its name, and — where the browser cannot place the layer — a ref to measure it by. */
+export interface AnchorElementProps {
+    ref?: (element: HTMLElement | null) => void;
+    style: AnchorStyle;
+}
+/** What goes on the floating layer. The geometry is shared props; only the identity and the fallback's coordinates are inline. */
+export interface AnchorLayerProps extends Pick<BoxStyleProps, 'position' | 'positionArea' | 'positionTryFallbacks' | 'minWidth' | 'mt' | 'mb' | 'ms' | 'me'> {
+    ref?: (element: HTMLElement | null) => void;
+    style: AnchorStyle;
+}
+export interface AnchorPosition {
+    /** Whether the browser is placing the layer. `false` means this hook measured it instead. */
+    css: boolean;
+    /** The side the layer is on: the requested one, unless `trackSide` is on and a flip moved it. */
+    side: AnchorSide;
+    anchorProps: AnchorElementProps;
+    layerProps: AnchorLayerProps;
+}
+/**
+ * A floating layer placed against an anchor — in CSS where the browser has anchor positioning, and by
+ * measurement where it does not. Spread `anchorProps` on the trigger and `layerProps` on the layer;
+ * nothing else is needed, and on the CSS path nothing runs at all: no scroll listener, no state, no
+ * measurement, because `position-area` and `position-try-fallbacks` are the flip a positioning library
+ * ships JS for.
+ *
+ * ```tsx
+ * const { anchorProps, layerProps } = useAnchorPosition({ side: 'bottom', offset: 2, matchWidth: true });
+ *
+ * <Button {...anchorProps} onClick={toggle}>Options</Button>
+ * {open && <Box {...layerProps} component="menu">…</Box>}
+ * ```
+ *
+ * Two things worth knowing. The layer is `position: fixed`, so it escapes every `overflow: hidden`
+ * ancestor without a portal — but not a *transformed* one, which is a fixed element's containing block in
+ * either path, and not the stacking order, which is still the page's. And the anchor's **name is an inline
+ * style rather than a prop**: an identity is per-instance, so a class for it would be a rule per instance
+ * that is never freed — the same rule that makes a sparkline's `d` an attribute and its stroke a class.
+ *
+ * @a11y None of it. A layer is not a pattern: the role, the dismissal and the focus belong to whatever
+ * renders one — `useDismiss` and `useFocusReturn` from `@box-kite/react/a11y` are the other half.
+ */
+export default function useAnchorPosition(options?: AnchorPositionOptions): AnchorPosition;
+export {};

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/dialog/useScrollLock.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+/**
+ * Stop the page behind a layer from scrolling, with a class rather than an inline style — so it is one
+ * shared rule like every other value this library writes, and a consumer can see what did it. Returns
+ * the style elements to render, which is element mode's way of getting a rule onto the page at all.
+ *
+ * `overflow: hidden` on `<html>` is the whole mechanism, which means two things worth knowing: the
+ * scrollbar's width leaves the page as it is applied, so a document that wants no shift should carry
+ * `scrollbarGutter="stable"`; and iOS Safari scrolls anyway, where nothing short of `position: fixed`
+ * on the body holds it.
+ */
+export default function useScrollLock(enabled: boolean): React.ReactElement[] | undefined;

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,6 @@
+/**
+ * The container every portalled layer shares, created on first use. Pass `false` on the top-layer path,
+ * where nothing is portalled: the container is a DOM node plus a theme-class subscription, and a layer
+ * that stays where it was declared inherits the theme instead of needing one copied onto it.
+ */
+export default function usePortalContainer(enabled?: boolean): HTMLElement | null;

package/react/hooks/useVirtualization.d.ts

@@ -0,0 +1,32 @@
+import { VirtualWindow } from '../../utils/virtual/virtualUtils';
+export interface UseVirtualizationOptions {
+    /** How many rows there are in total — not how many are rendered. */
+    count: number;
+    /** The scrolling element: what it shows at once is the viewport, and its own rows are the pitch. */
+    scrollerRef: React.RefObject<HTMLElement | null>;
+    /** The pitch of a row, when it should be declared rather than measured. */
+    itemHeight?: number;
+    /** What the scroller shows, when it should be declared rather than measured. */
+    viewHeight?: number;
+    overscan?: number;
+    threshold?: number;
+    /** Forces windowing on or off. Left off, it follows the row count against `threshold`. */
+    enabled?: boolean;
+    /** The row the keyboard is on. Always rendered, whatever the scroll position says. */
+    activeIndex?: number;
+}
+export interface UseVirtualizationResult extends VirtualWindow {
+    /** Whether the list is being windowed at all. `false` means render every row and ignore the rest. */
+    virtualized: boolean;
+    /** Goes on the element that holds the rendered rows — the one the pitch is measured from. */
+    contentRef: (element: HTMLElement | null) => void;
+    /** Goes on the scrolling element. */
+    onScroll: (event: React.UIEvent<HTMLElement>) => void;
+}
+/**
+ * Renders a window of a long list instead of all of it, over the framework-free arithmetic in
+ * `VirtualUtils`. The two measurements it needs are taken from the DOM rather than declared, so a row
+ * restyled by the caller still windows correctly; until something has been laid out (a first render, or
+ * a test environment that computes none) the defaults in the model stand in.
+ */
+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/identity/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/popover/usePopoverLayer.d.ts

@@ -0,0 +1,87 @@
+import { ElementLike } from '../../utils/dom/domUtils';
+import { ChangeHandler, SetControllableState } from '../a11y/useControllableState';
+/** Why a layer opened or closed — every component built on this reports the same four. */
+export type PopoverReason = 'trigger' | 'escape' | 'outside-pointer' | 'imperative';
+/** What a trigger says it opens, which is the one thing the layers built on this disagree about. */
+export type PopoverHasPopup = 'dialog' | 'menu';
+/** The DOM attributes a trigger has to carry, whatever it opens. */
+export interface PopoverTriggerAttributes<THasPopup extends PopoverHasPopup = PopoverHasPopup> {
+    'aria-expanded': boolean;
+    'aria-haspopup': THasPopup;
+    'aria-controls'?: string;
+    /** Only where the browser has no Popover API. On the platform path `popovertarget` does the toggling. */
+    onClick?(event: React.MouseEvent): void;
+}
+/**
+ * What the trigger has to carry: spread it onto the control itself, not a wrapper. The `ref` is what the
+ * layer is anchored to, so it is not optional decoration.
+ *
+ * It must be a **button**: `popovertarget` is what the browser toggles on, and it only reads it off one.
+ */
+export interface PopoverTrigger<THasPopup extends PopoverHasPopup = PopoverHasPopup> {
+    ref: React.RefCallback<HTMLElement>;
+    props: PopoverTriggerAttributes<THasPopup>;
+}
+export interface PopoverLayerOptions<THasPopup extends PopoverHasPopup = PopoverHasPopup, TReason extends string = never> {
+    /** What the trigger says it opens. */
+    haspopup: THasPopup;
+    /** A consumer id wins over the generated one, and everything that names the layer follows it. */
+    id?: string;
+    /** What the generated id is prefixed with, so a debugger says which component it belongs to. */
+    idPrefix: string;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: ChangeHandler<boolean, PopoverReason | TReason>;
+    /**
+     * The layer is open *and* laid out — the only moment focus can be moved into it. On the platform path
+     * this is the `toggle` event rather than an effect on the open state, and the difference is not
+     * academic: `beforetoggle` fires before the panel opens and a discrete event is flushed synchronously,
+     * so an effect would run while `:popover-open` still does not match, which is `display: none` — and
+     * focusing a hidden element does nothing at all (measured).
+     */
+    onOpened?(panel: HTMLElement): void;
+    /**
+     * It is about to close, and `heldFocus` says whether it has focus. Fired from `beforetoggle`, while the
+     * panel is still shown, because that is the last moment focus can be moved without a flash: the platform
+     * returns focus to whatever had it before the **outermost** layer opened, and for a nested one it does
+     * nothing at all — focus drops to `<body>` (both measured in Chrome 152). A submenu puts focus back on
+     * its own item from here.
+     */
+    onClosing?(heldFocus: boolean, trigger: HTMLElement | null): void;
+    /**
+     * More elements a press inside counts as inside, for the portal path only: a nested layer is portalled
+     * out of the DOM it was declared in, so nothing about the tree says a press in it is a press in this
+     * one. The platform answers that question itself, by the popover nesting rules.
+     */
+    inside?: readonly ElementLike[];
+}
+export interface PopoverLayer<THasPopup extends PopoverHasPopup = PopoverHasPopup, TReason extends string = never> {
+    /** Whether the browser's Popover API is placing the layer in the top layer. `false` is the portal path. */
+    platform: boolean;
+    isOpen: boolean;
+    setOpen: SetControllableState<boolean, PopoverReason | TReason>;
+    id: string;
+    /** What the trigger render prop is handed. */
+    trigger: PopoverTrigger<THasPopup>;
+    triggerElement: HTMLElement | null;
+    /**
+     * The trigger's id — what names a layer after the control that opened it, which is what APG asks of a
+     * menu. One is written onto the trigger when it has none of its own.
+     */
+    triggerId?: string;
+    /** Goes on the panel, on both paths. */
+    setPanel: React.RefCallback<HTMLElement>;
+    panelElement: HTMLElement | null;
+}
+/**
+ * One conversation with the Popover API, for every component that opens a layer on it: the open state,
+ * the platform mirror, the dismissal reasons, and the two primitives that stand in where the browser has
+ * no popover at all. `Popover` is this plus a `role="dialog"` panel; `Menu` is this three times over —
+ * once for the menu and once per open submenu.
+ *
+ * What the platform owns, measured in Chrome 152: the top layer, light dismiss (Escape and an outside
+ * press), the toggle from a `popovertarget` trigger — including the press that closes an open layer from
+ * its own trigger, with no reopen — and focus return for the outermost layer. What it does not own is
+ * focus *into* the layer, focus return for a nested one, and any of the ARIA.
+ */
+export default function usePopoverLayer<THasPopup extends PopoverHasPopup, TReason extends string = never>(options: PopoverLayerOptions<THasPopup, TReason>): PopoverLayer<THasPopup, TReason>;

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;
+}