@box-kite/react 0.0.1 → 2.0.0

package/docs/a11y.md

@@ -0,0 +1,199 @@
+# The behaviour primitives (`@box-kite/react/a11y`)
+
+Five hooks and one component: the mechanics every accessible widget needs and none of them can be
+seen in the markup. They are what the library's own components are built from, and they are
+published so a consumer building a pattern this library does not ship — a tree view, a split
+button, a command palette — does not have to write them again.
+
+```tsx
+import { useControllableState, useDismiss, useFocusReturn, useIdentifier, useRovingFocus } from '@box-kite/react/a11y';
+import VisuallyHidden from '@box-kite/react/components/visuallyHidden';
+```
+
+2.2 KB gzipped for the whole entry, and it pulls in no styling engine: the hooks reach React, two
+leaf modules of DOM helpers, and each other. They are client hooks — the entry carries a `'use client'` banner, so importing it from a
+Server Component opens a client boundary. `VisuallyHidden` is a component and ships separately,
+where it can still render on a server.
+
+What they deliberately do **not** do is supply roles or ARIA. A listbox and a menu navigate
+identically and are named completely differently; a hook that decided both would be wrong for one
+of them. Movement, state and focus are here — the semantics belong to whoever is building the
+pattern.
+
+`Tooltip` is the first component assembled from them, and a small enough one to read as a worked
+example: `src/components/tooltip.tsx` is `useControllableState` for the open state (so a consumer
+can control it and be told _why_ it changed), `useIdentifier` for the id `aria-describedby` points
+at, and `useDismiss` with `outsidePointer: false` for Escape. Everything left over — the delays,
+the hover grace period, `role="tooltip"` — is the pattern, and that is the split this file is
+about. It uses no `useFocusReturn`: focus never enters a tooltip, so there is nothing to return.
+
+---
+
+## `useControllableState`
+
+One value that behaves the same whether the consumer controls it or not, and every change carrying
+a **reason**.
+
+```tsx
+const [open, setOpen] = useControllableState<boolean, 'trigger' | 'select' | 'escape'>({
+  value: props.open, // present = the consumer owns it
+  defaultValue: false,
+  onChange: props.onOpenChange,
+});
+
+setOpen(false, { reason: 'escape', event });
+```
+
+`onChange(value, { reason, event })` is the point of the hook. A component that only reports
+`onOpenChange(false)` makes its consumer guess whether the popup closed because something was
+picked, because Escape was pressed, because the user clicked away, or because the component decided
+on its own — and each of those wants different behaviour from the surrounding app. This is the
+Base UI shape, and it is the answer to the long-standing complaints about controlled state in
+Radix.
+
+Details worth knowing:
+
+- The setter's identity is **stable**, so it can sit in a dependency array.
+- It takes an updater (`setOpen((value) => !value, details)`), resolved against the current value.
+- A change to the value it already holds is dropped: two dismissal layers closing the same popup is
+  normal, and the consumer should hear about it once.
+- "Controlled" means `value !== undefined`, decided per render.
+
+## `useDismiss`
+
+Light dismiss: Escape, and a pointer press outside — composable across nested layers.
+
+```tsx
+useDismiss({
+  enabled: open,
+  inside: [triggerRef, popupRef],
+  onDismiss: (reason, event) => setOpen(false, { reason, event }),
+});
+```
+
+- `inside` is what counts as inside. Pass the **trigger** as well as the popup, or a press on the
+  trigger of an open popup reads as a press outside it — dismissing and reopening in one gesture.
+- Escape goes to the innermost layer only, worked out from DOM containment rather than registration
+  order (React runs a child's effects before its parent's, so registration order gets nesting
+  backwards). An outside press is judged by each layer for itself, so a press in the page closes a
+  menu and its submenu together, while a press in the menu closes only the submenu.
+- An Escape a consumer already handled (`event.preventDefault()`) is left alone — that is how a
+  search box inside the popup clears itself without also closing the popup.
+- It listens on `pointerdown`, not `click`: dismissal belongs at the start of the gesture, and a
+  press that starts inside the popup and ends outside it (a drag, a text selection) is not a
+  dismissal at all.
+- `escapeKey: false` / `outsidePointer: false` turn off either half.
+
+## `useFocusReturn`
+
+Put focus back where it came from when a layer closes.
+
+```tsx
+useFocusReturn({ enabled: open, returnTo: triggerRef });
+```
+
+Losing focus to `<body>` is the most common keyboard bug in a popup: the trigger is gone as far as
+the tab order is concerned, so the next Tab starts again at the top of the page.
+
+- The invoker is captured **during the render that opens the layer**, before the layer's own
+  `autoFocus` can take focus away — an effect would remember the popup's first control instead.
+- The restore is skipped when something else already holds focus (a menu item that opened a dialog,
+  a user who tabbed away first), because taking it back would be the same bug pointing the other
+  way.
+- `returnTo` overrides the invoker; `preventScroll` is passed to `focus()`.
+- It also returns `{ returnFocus }` for the cases where the component wants to say when.
+
+## `useRovingFocus`
+
+Arrow-key navigation over a list — the movement half of every APG list pattern (listbox, menu,
+tabs, radio group) — with both of the focus strategies those patterns use.
+
+```tsx
+const roving = useRovingFocus({
+  count: items.length,
+  orientation: 'vertical', // 'horizontal' | 'both'
+  loop: true,
+  isDisabled: (index) => items[index].disabled,
+  textOf: (index) => items[index].label, // supplying this turns on typeahead
+  onSelect: (index, event) => choose(index),
+});
+
+<ul onKeyDown={roving.onKeyDown}>
+  {items.map((item, index) => (
+    <li key={item.id} role="option" aria-selected={index === roving.activeIndex} {...roving.itemProps(index)}>
+      {item.label}
+    </li>
+  ))}
+</ul>;
+```
+
+**A sideways arrow follows the reading order.** APG asks for it and a right-to-left list reverses it, so
+`ArrowLeft` is the _next_ item there and `ArrowRight` the previous one. Nothing configures it: the hook
+asks the element for its _resolved_ direction (`getComputedStyle`, so a `dir="auto"` or a `<bdi>` above it
+counts) the moment one of those two keys arrives, which is why a vertical list pays nothing for it. The
+vertical axis, Tab, Home and End never flip — Home is the first item in the reading order either way.
+
+Keys: arrows per `orientation`, Home/End (skipping disabled items), Enter and Space to select,
+printable characters for typeahead. A single character — or the same character repeated — moves to
+the next item starting with it; a longer buffer narrows instead of hopping. Space belongs to an
+open typeahead buffer rather than to selection, because "New York" contains one.
+
+**Two focus modes.** The default (`focusItems: true`) is roving tabindex: real DOM focus follows
+the active item and `itemProps` puts exactly one item in the tab order, so Tab enters and leaves the
+list in one press. `focusItems: false` is the other half — focus stays where it is (a combobox
+trigger) and the caller names the active item with `aria-activedescendant`, for which
+`roving.activeItem()` hands back the element.
+
+`activeIndex` is clamped to `count`, so a list filtered down by a search box cannot leave it
+pointing past the end. It is controllable through `activeIndex`/`onActiveIndexChange`, and
+`setActiveIndex(index, details)` sets it outright — opening a list on the selected item.
+
+## `useIdentifier`
+
+A stable, unique id for wiring one element to another.
+
+```tsx
+const id = useIdentifier('select');
+// `${id}-trigger`, `${id}-listbox`, `${id}-option-3`
+```
+
+React's `useId` with the punctuation removed: `:r1:` (React 18) and `«r1»` (React 19) are both
+rejected by `querySelector('#…')`, and the part that varies is the word characters. Derive related
+ids from one call rather than calling the hook once per element. On React 16/17, which have no
+`useId`, the fallback is a module counter — pass ids in explicitly there if the tree is hydrated.
+
+## `VisuallyHidden`
+
+Content for screen readers that is not drawn on screen — the name of an icon-only button, the
+heading a region is labelled by, a live region's announcement.
+
+```tsx
+import VisuallyHidden from '@box-kite/react/components/visuallyHidden';
+
+<Button>
+  <VisuallyHidden tag="span">Delete the invoice</VisuallyHidden>
+  <TrashIcon aria-hidden />
+</Button>;
+```
+
+`display: none` and `hidden` take content out of the accessibility tree along with the layout,
+which is the opposite of what is wanted. This clips the element instead: absolutely positioned, one
+pixel (not zero — some screen readers skip a zero-sized element), `overflow: hidden`,
+`clip-path: inset(50%)` and `white-space: nowrap`, so a long string is not wrapped into a
+one-pixel-wide column and read out one word per line. It is a Box, so props override the defaults
+and `tag` picks the element.
+
+---
+
+## Testing them
+
+Each hook has its own unit tests next to it in `src/react/a11y/`. What those cannot prove is that
+they compose, so `src/react/a11y/primitives.a11y.test.tsx` assembles all five into a select-only
+combobox, drives it entirely from the keyboard, and runs axe over it — the pattern A5 has to reach,
+built the way a consumer would build it. The bugs it is there to catch are the ones that only
+appear in combination: a dismissal firing while the list is still taking focus, focus returning to
+a trigger a roving index has moved away from, an id regenerated per render so
+`aria-activedescendant` points at nothing.
+
+See [a11y-testing.md](a11y-testing.md) for the test infrastructure itself and what automated checks
+can and cannot see.

package/docs/anchor.md

@@ -0,0 +1,139 @@
+# Anchor positioning (`@box-kite/react/anchor`)
+
+Where a floating layer goes. One hook and two value families, over the six props the engine already
+ships (`anchorName`, `positionAnchor`, `positionArea`, `positionTryFallbacks`, `positionTryOrder`,
+`positionVisibility`).
+
+```tsx
+import { useAnchorPosition } from '@box-kite/react/anchor';
+```
+
+About 2 KB gzipped for the entry, and it pulls in no styling engine. It is a client hook — the entry
+carries a `'use client'` banner — but the thing it produces is ordinary props, so a layer that needs
+no JavaScript at all can be written by hand with the props below and rendered on a server.
+
+What it deliberately does **not** do is supply a role, a dismissal or focus handling. A layer is not
+a pattern: a tooltip, a menu and a select popup are placed identically and named completely
+differently. Placement is here; the semantics belong to whoever is building the pattern, and the
+mechanics are in `@box-kite/react/a11y`.
+
+---
+
+## `useAnchorPosition(options)`
+
+```tsx
+const { css, anchorProps, layerProps } = useAnchorPosition({ side: 'bottom', align: 'start', offset: 2, matchWidth: true });
+
+<Button {...anchorProps} onClick={toggle}>
+  Options
+</Button>;
+{
+  isOpen && <Box {...layerProps} component="menu">…</Box>;
+}
+```
+
+Spread `anchorProps` on the trigger and `layerProps` on the layer. On a browser with CSS anchor
+positioning that is the whole of it: nothing runs. No measuring, no scroll listener, no state,
+nothing to keep in sync when the page moves — `position-area` and `position-try-fallbacks` are the
+placement and the flip a positioning library ships JavaScript for.
+
+| Option       | Default   | What it means                                                                                                      |
+| ------------ | --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `side`       | `'bottom'` | `'top'`/`'bottom'` are the block axis, `'start'`/`'end'` the inline one — so a side mirrors in a right-to-left page |
+| `align`      | `'center'` | which of the anchor's edges to line the layer up with on the other axis                                             |
+| `offset`     | `0`        | the gap, on the ÷4 spacing scale, emitted as the margin on the side facing the anchor                               |
+| `flip`       | `true`     | `positionTryFallbacks`: the side's own axis, then the alignment's, then both                                         |
+| `matchWidth` | `false`    | `minWidth="anchor-size(width)"` — the anchor's width, with nothing measured                                         |
+| `name`       | generated  | the anchor's name; one per instance unless you pass one                                                             |
+| `anchor`     | —          | an anchor handed to the hook rather than one it spreads props onto (a ref or an element)                            |
+| `trackSide`  | `false`    | whether `side` in the result says where the layer ended up — one read after layout, so it is opt-in                 |
+
+`css` says which path ran: `true` is the browser placing the layer, `false` is the measured
+fallback. `side` is where the layer actually is: the requested side, unless `trackSide` is on and a
+flip moved it. There is no `strategy` option — the layer is always `position: fixed`, because that is
+what makes both paths agree about what the coordinates mean.
+
+A caller that was handed its trigger rather than rendering it passes `anchor` instead of spreading
+`anchorProps`: the name is written onto the element in a layout effect, which is the one thing an
+element somebody else rendered can be reached by. That is what `Overlay` does, and a ref is read when
+the layer mounts — so an element in state is the robust form when the layer is open from the start.
+
+### The fallback
+
+CSS anchor positioning is Chrome 125+, Firefox 147+ and Safari 26+. Everywhere else the hook
+measures: it flips to the opposite side when the requested one has no room and the opposite has,
+then shifts along the other axis to keep the layer in the viewport, and hands the layer its
+coordinates as an inline style. Both paths come out of one model, so the fallback is the CSS
+placement worked out by hand rather than a second set of rules.
+
+The first render always assumes the CSS path, so a server-rendered anchor and the first client
+render agree; a browser without anchor positioning says so in a layout effect, before it paints.
+
+---
+
+## `anchor-size()` and `anchor()`
+
+Every sizing prop (`width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`) takes an
+`anchor-size()` value, and every single-side inset prop (`top`, `right`, `bottom`, `left`,
+`insetStart`, `insetEnd`) takes an `anchor()` one:
+
+```tsx
+<Box position="fixed" positionAnchor="menu-trigger" minWidth="anchor-size(width)" maxHeight="anchor-size(height, 20rem)" />
+<Box position="fixed" top="anchor(bottom)" insetStart="anchor(left)" />
+```
+
+- `anchor-size()` takes an axis: `width`, `height`, `block`, `inline`, `self-block`, `self-inline`.
+- `anchor()` takes an edge: `top`, `right`, `bottom`, `left`, `start`, `end`, `self-start`,
+  `self-end`, `center`, `inside`, `outside` — or a percentage along one (`anchor(50%)`).
+- Both take an optional anchor name first, with the same optional `--` the props take
+  (`anchor-size(trigger width)`), and an optional fallback after a comma for when there is no anchor
+  to measure (`anchor-size(width, 10rem)`).
+- A bare `anchor()` is rejected — CSS needs the edge. A bare `anchor-size()` is not: it means the
+  layer's own axis.
+- A value the grammar rejects emits no rule and no class name, the way every validated value does.
+
+Together they are what places and sizes a layer against its anchor with no hook at all, which is
+what makes a floating layer possible in a Server Component.
+
+---
+
+## Five things worth knowing
+
+All five were measured in Chrome 152 rather than read off the spec.
+
+**The layer is `position: fixed`, so it escapes `overflow: hidden` without a portal.** Every clipped
+ancestor, no portal, no `z-index` juggling to get out of one — but *not* a transformed ancestor,
+which is a fixed element's containing block in either path, and not the page's stacking order, which
+is still the page's. `Overlay` (`@box-kite/react/components/overlay`) is this hook plus a portal, and
+is still the answer when the layer has to come out on top of everything.
+
+**A flip needs three candidates, not one.** A candidate position has to fit on *both* axes to be
+taken, so a lone `flip-block` does nothing at all for a layer that overflows the *cross* axis — the
+browser leaves it pressed against the edge of the viewport. `flip` therefore offers the side's own
+axis, the alignment's, and both, in that order, and the both-axes rule is what makes the order work:
+a menu with no room on the side its alignment reaches mirrors to the other end instead of running off
+the page.
+
+**Knowing which side the browser chose costs the entrance.** `trackSide` reads the *used*
+`position-area`, and that read is the style resolution `@starting-style` computes its before-change
+style from — so a class that depends on the answer arrives after the entrance has been decided, every
+time. An exit runs long afterwards and can use it, which is why `dropdown.items` has a `closedUp`
+variant and no `up` one. A used value is also not the value that went in: a `span-all` half is
+dropped, and a value naming both axes comes back in the `start`/`end` shorthand, where position names
+the axis (`block-end span-inline-end` reads back `end span-end`, and `start span-end` once flipped).
+
+**A flip is sticky.** Once the browser takes a `position-try` fallback it keeps it until the layer is
+laid out afresh, which is what stops the layer oscillating as the page scrolls. Hiding the layer and
+showing it again re-evaluates, so a popup that mounts when it opens always picks the side that fits,
+while one that stays mounted keeps the side it first chose.
+
+**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. Everything shared — the area, the flip, the margin, the width —
+is an ordinary prop, and an ordinary class.
+
+One more, from the props themselves: **a candidate position has to fit on both axes to be taken**, so
+an overflow the flips cannot fix disqualifies every one of them and the layer silently stays put.
+The hook cannot hit this — `align: 'center'` emits `span-all` rather than the centre cell for exactly
+that reason — but hand-written props can: `positionArea="block-end center"` with a layer wider than
+its anchor never flips.

package/docs/components.md

@@ -0,0 +1,48 @@
+# Components
+
+`Box` is the default export of `@box-kite/react` and takes every prop in `props.md`. Everything below is `Box` with the right element and its own defaults, one entry point each — **use one of these rather than `<Box tag="…">`**. Read from the built chunks, so the names cannot drift from what the package exports.
+
+## Rendered on a server
+
+No hook, no effect, no DOM: a React Server Component can render these directly.
+
+| Import | Components | Notes |
+| --- | --- | --- |
+| `@box-kite/react/components/baseSvg` | `BaseSvg` (default) | **deprecated** |
+| `@box-kite/react/components/button` | `Button` (default) |  |
+| `@box-kite/react/components/chart` | `ChartContainer`, `Gauge`, `MiniDonut`, `ProgressRing`, `Sparkline` |  |
+| `@box-kite/react/components/flex` | `Flex` (default) |  |
+| `@box-kite/react/components/grid` | `Grid` (default) |  |
+| `@box-kite/react/components/icon` | `Icon` (default) |  |
+| `@box-kite/react/components/progress` | `Progress` (default) |  |
+| `@box-kite/react/components/radioButton` | `RadioButton` (default) |  |
+| `@box-kite/react/components/semantics` | `Article`, `Aside`, `Details`, `Figcaption`, `Figure`, `Footer`, `H1`, `H2`, `H3`, `H4`, `H5`, `H6`, `Header`, `Img`, `Label`, `Li`, `Link`, `Main`, `Mark`, `Menu`, `MenuList`, `Nav`, `Ol`, `P`, `Section`, `Span`, `Summary`, `Time`, `Ul` | **deprecated** |
+| `@box-kite/react/components/svg` | `Circle`, `ClipPath`, `Defs`, `Ellipse`, `G`, `Line`, `LinearGradient`, `Marker`, `Mask`, `Path`, `Polygon`, `Polyline`, `RadialGradient`, `Rect`, `Stop`, `Svg`, `SvgSymbol`, `SvgText`, `TSpan`, `Use` |  |
+| `@box-kite/react/components/textarea` | `Textarea` (default) |  |
+| `@box-kite/react/components/textbox` | `Textbox` (default) |  |
+| `@box-kite/react/components/visuallyHidden` | `VisuallyHidden` (default) |  |
+
+## Client-only (`'use client'`)
+
+These hold state, measure the DOM or portal into it. A Server Component may import one — the chunk carries the banner, so the boundary opens — but the component itself renders on the client.
+
+| Import | Components | Notes |
+| --- | --- | --- |
+| `@box-kite/react/components/accordion` | `Accordion` (default), `Collapsible` |  |
+| `@box-kite/react/components/checkbox` | `Checkbox` (default) |  |
+| `@box-kite/react/components/combobox` | `Combobox` (default), `ComboboxUtils` |  |
+| `@box-kite/react/components/dataGrid` | `dataGrid` (default) |  |
+| `@box-kite/react/components/dialog` | `Dialog` (default), `AlertDialog` |  |
+| `@box-kite/react/components/dropdown` | `Dropdown` (default) | **deprecated** |
+| `@box-kite/react/components/form` | `Form` (default) |  |
+| `@box-kite/react/components/menu` | `Menu` (default) |  |
+| `@box-kite/react/components/overlay` | `Overlay` (default) |  |
+| `@box-kite/react/components/popover` | `Popover` (default) |  |
+| `@box-kite/react/components/presence` | `Presence` (default) |  |
+| `@box-kite/react/components/radioGroup` | `RadioGroup` (default) | **deprecated** |
+| `@box-kite/react/components/select` | `Select` (default) | **deprecated** |
+| `@box-kite/react/components/slider` | `Slider` (default) |  |
+| `@box-kite/react/components/switch` | `Switch` (default) |  |
+| `@box-kite/react/components/tabs` | `Tabs` (default) |  |
+| `@box-kite/react/components/toaster` | `Toaster` (default), `createToastStore`, `defaultToastStore`, `toast` |  |
+| `@box-kite/react/components/tooltip` | `Tooltip` (default) |  |

package/docs/index.md

@@ -0,0 +1,11 @@
+# Documentation for agents
+
+The markdown `@box-kite/react` ships for whatever is reading its source tree. No formal discovery standard exists for a package that carries its own docs — these files are here to be found.
+
+- [`../AGENTS.md`](../AGENTS.md) — the rules, and the fight-the-prior block. Start here
+- [`props.md`](props.md) — every prop, the CSS it writes and one measured example
+- [`components.md`](components.md) — every component, its import specifier and whether it renders on a server
+- [`a11y.md`](a11y.md) — the behaviour hooks (`@box-kite/react/a11y`) for a pattern this library does not ship
+- [`anchor.md`](anchor.md) — where a floating layer goes (`@box-kite/react/anchor`), in CSS and in the measured fallback
+
+The rest sits at the package root: `BOX_KITE_AI_CONTEXT.md`, the long-form reference (prop tables, the DataGrid API, debugging); `.claude/skills/box-kite/`, the same rules as an installable skill with four references beside it; and `.cursor/rules/box-kite.mdc`, which is that skill as a Cursor rule — copy either into the project rather than reading it from here, so it is loaded without anyone asking.