@primitiv-ui/react 0.1.29 → 0.1.30

package/src/Listbox/types.ts

@@ -0,0 +1,238 @@
+import type { HTMLAttributes, ReactNode, Ref } from "react";
+
+/**
+ * Mode-independent props shared by every `Listbox.Root` variant — orientation,
+ * direction, selection-follows-focus, `asChild`, children, and the ref.
+ * Combined with a mode-specific arm to form {@link ListboxRootProps}.
+ */
+export type ListboxRootBaseProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "defaultValue" | "dir"
+> & {
+  /** Layout axis for cursor navigation. `"vertical"` binds ArrowUp/ArrowDown;
+   * `"horizontal"` binds ArrowLeft/ArrowRight and additionally emits
+   * `aria-orientation="horizontal"` (vertical is the ARIA default, so it is
+   * left implicit). Surfaces as `data-orientation` for styling; it does not
+   * itself apply any layout.
+   * @default "vertical" */
+  orientation?: "horizontal" | "vertical";
+  /** Reading direction. In `"rtl"` the horizontal arrow pair is mirrored so
+   * the cursor follows visual order — meaningful only when
+   * {@link ListboxRootBaseProps.orientation} is `"horizontal"`. Inherited from
+   * the nearest {@link DirectionProvider} when omitted, falling back to
+   * `"ltr"`. */
+  dir?: "ltr" | "rtl";
+  /** When `true`, moving the cursor with the arrow / Home / End keys or via
+   * typeahead also selects the option it lands on — the behaviour of APG's
+   * single-select listbox example. Left `false`, arrowing only moves the
+   * highlight and the user commits with Enter or Space, which is what a
+   * command palette or search-suggestion list needs.
+   * @default false */
+  selectionFollowsFocus?: boolean;
+  /** Render a single consumer-supplied element in place of the native `<div>`,
+   * with the listbox's `role`, `tabIndex`, ARIA state, `data-orientation`, ref
+   * and keyboard handlers merged onto it via the {@link Slot} pattern.
+   * @default false */
+  asChild?: boolean;
+  /** The {@link ListboxOptionProps | `Listbox.Option`} and
+   * {@link ListboxGroupProps | `Listbox.Group`} elements that make up the
+   * list. */
+  children?: ReactNode;
+  /** Forwarded to the underlying `HTMLDivElement`. */
+  ref?: Ref<HTMLDivElement>;
+};
+
+/**
+ * Single-selection mode, uncontrolled — at most one option selected, with the
+ * initial choice supplied via `defaultValue`.
+ */
+export type ListboxSingleUncontrolledProps = {
+  /** Selects single-selection semantics: at most one option selected at a
+   * time, and re-selecting the current option is a no-op rather than a
+   * deselect. */
+  type: "single";
+  /** Value of the option selected on first render. Omit to start with nothing
+   * selected. */
+  defaultValue?: string;
+  /** Forbidden in uncontrolled mode — use
+   * {@link ListboxSingleUncontrolledProps.defaultValue}. */
+  value?: never;
+  /** Called with the newly selected option's value whenever the user commits a
+   * choice. */
+  onValueChange?: (value: string) => void;
+};
+
+/**
+ * Single-selection mode, controlled — the selected value is owned by the
+ * caller via `value` / `onValueChange`.
+ */
+export type ListboxSingleControlledProps = {
+  /** Selects single-selection semantics: at most one option selected at a
+   * time, and re-selecting the current option is a no-op rather than a
+   * deselect. */
+  type: "single";
+  /** The currently selected option's value. Must be kept in sync by the caller
+   * via {@link ListboxSingleControlledProps.onValueChange}. */
+  value: string;
+  /** Called with the value the user is asking to select. */
+  onValueChange?: (value: string) => void;
+  /** Forbidden in controlled mode — use
+   * {@link ListboxSingleControlledProps.value}. */
+  defaultValue?: never;
+};
+
+/**
+ * Multiple-selection mode, uncontrolled — options toggle independently, with
+ * the initial set supplied via `defaultValue`.
+ */
+export type ListboxMultipleUncontrolledProps = {
+  /** Selects multiple-selection semantics: any number of options can be
+   * selected and each toggles independently. Sets `aria-multiselectable` on
+   * the root. */
+  type: "multiple";
+  /** Values of the options selected on first render. Omit to start with
+   * nothing selected. */
+  defaultValue?: string[];
+  /** Forbidden in uncontrolled mode — use
+   * {@link ListboxMultipleUncontrolledProps.defaultValue}. */
+  value?: never;
+  /** Called with the complete next set of selected values whenever the user
+   * toggles any option. */
+  onValueChange?: (value: string[]) => void;
+};
+
+/**
+ * Multiple-selection mode, controlled — the set of selected values is owned by
+ * the caller via `value` / `onValueChange`.
+ */
+export type ListboxMultipleControlledProps = {
+  /** Selects multiple-selection semantics: any number of options can be
+   * selected and each toggles independently. Sets `aria-multiselectable` on
+   * the root. */
+  type: "multiple";
+  /** The full set of currently selected values. Must be kept in sync by the
+   * caller via {@link ListboxMultipleControlledProps.onValueChange}. */
+  value: string[];
+  /** Called with the complete next set of selected values whenever the user
+   * toggles any option. */
+  onValueChange?: (value: string[]) => void;
+  /** Forbidden in controlled mode — use
+   * {@link ListboxMultipleControlledProps.value}. */
+  defaultValue?: never;
+};
+
+/**
+ * Props for {@link ListboxRoot | `Listbox.Root`}. Combines the shared
+ * {@link ListboxRootBaseProps} with one mode-specific arm — single or
+ * multiple, controlled or uncontrolled — so the `value` / `defaultValue` /
+ * `onValueChange` shape is enforced per `type`.
+ */
+export type ListboxRootProps = ListboxRootBaseProps &
+  (
+    | ListboxSingleUncontrolledProps
+    | ListboxSingleControlledProps
+    | ListboxMultipleUncontrolledProps
+    | ListboxMultipleControlledProps
+  );
+
+/**
+ * Props for {@link ListboxOption | `Listbox.Option`} — one selectable choice.
+ * `value` identifies it within the listbox; `children` supplies the label that
+ * typeahead matches against.
+ */
+export type ListboxOptionProps = HTMLAttributes<HTMLDivElement> & {
+  /** Identifies this option within the listbox. It is this string — not the
+   * visible label — that is compared against the root's selected `value` /
+   * `defaultValue`; use `children` for the label. */
+  value: string;
+  /** Removes the option from cursor navigation, focus seeding and typeahead,
+   * and makes it unselectable by click or key. The option stays in the DOM and
+   * in the accessibility tree, marked `aria-disabled`. Also sets
+   * `data-disabled=""` for CSS targeting.
+   * @default false */
+  disabled?: boolean;
+  /** Render a single consumer-supplied element in place of the native `<div>`,
+   * with the option's `role`, `id`, `aria-selected`, `data-highlighted` and
+   * click handler merged onto it via the {@link Slot} pattern. The child must
+   * accept a `ref`.
+   * @default false */
+  asChild?: boolean;
+  /** Forwarded to the underlying `HTMLDivElement`. */
+  ref?: Ref<HTMLDivElement>;
+};
+
+/**
+ * Props for {@link ListboxGroup | `Listbox.Group`} — a named cluster of
+ * options. Grouping is presentational; it does not partition navigation.
+ */
+export type ListboxGroupProps = HTMLAttributes<HTMLDivElement> & {
+  /** Accessible name for the group, applied as `aria-label`. APG requires
+   * every option group to carry a name — supply it either with this prop (an
+   * invisible name) or by rendering a
+   * {@link ListboxGroupLabelProps | `Listbox.GroupLabel`} heading inside the
+   * group, which names it via `aria-labelledby` instead. A rendered
+   * `GroupLabel` takes precedence. */
+  label?: string;
+  /** Render a single consumer-supplied element in place of the native `<div>`,
+   * with the group's `role` and `aria-label` merged onto it via the
+   * {@link Slot} pattern.
+   * @default false */
+  asChild?: boolean;
+  /** Forwarded to the underlying `HTMLDivElement`. */
+  ref?: Ref<HTMLDivElement>;
+};
+
+/**
+ * Props for {@link ListboxGroupLabel | `Listbox.GroupLabel`} — the visible
+ * heading that names its enclosing {@link ListboxGroup | `Listbox.Group`}.
+ */
+export type ListboxGroupLabelProps = HTMLAttributes<HTMLDivElement> & {
+  /** Render a single consumer-supplied element in place of the native
+   * `<div>`, with the heading's `id` and `role="presentation"` merged onto it
+   * via the {@link Slot} pattern.
+   * @default false */
+  asChild?: boolean;
+  /** Forwarded to the underlying `HTMLDivElement`. */
+  ref?: Ref<HTMLDivElement>;
+};
+
+/**
+ * Context shared from {@link ListboxGroup | `Listbox.Group`} to its label —
+ * the id the heading must adopt so the group can point `aria-labelledby` at
+ * it, and the registrar telling the group a heading is present.
+ */
+export type ListboxGroupContextValue = {
+  /** The DOM id the {@link ListboxGroupLabel} must render with. */
+  labelId: string;
+  /** Called by the label on mount/unmount so the group knows whether to emit
+   * `aria-labelledby`. */
+  registerLabel: (present: boolean) => void;
+};
+
+/**
+ * Context shared from {@link ListboxRoot | `Listbox.Root`} to its options —
+ * the selected set, the select action, the virtual-focus cursor, option
+ * registration, and the id derivation that wires `aria-activedescendant` to
+ * each option's `id`.
+ */
+export type ListboxContextValue = {
+  /** Every currently selected option value. Single mode holds at most one. */
+  selectedValues: string[];
+  /** Selects (single) or toggles (multiple) the given option. */
+  select: (optionValue: string) => void;
+  /** The option the cursor is on, or `undefined` before the root is focused. */
+  activeValue: string | undefined;
+  /** Moves the cursor onto the given option and scrolls it into view. Used by
+   * `Listbox.Option` so a click leaves the cursor where the user clicked. */
+  moveCursor: (optionValue: string) => void;
+  /** Registers a mounted option's element and disabled state; pass `null` as
+   * the element to unregister. */
+  registerOption: (
+    optionValue: string,
+    element: HTMLElement | null,
+    disabled?: boolean,
+  ) => void;
+  /** Derives the stable DOM `id` for an option, shared by the option itself
+   * and the root's `aria-activedescendant`. */
+  getOptionId: (optionValue: string) => string;
+};

package/src/MillerColumns/MillerColumns.tsx

@@ -18,7 +18,7 @@ import {
   useMillerColumnsRoot,
 } from "./hooks/index.ts";
 
-import { partitionItemChildren } from "./utils";
+import { partitionAriaProps, partitionItemChildren } from "./utils";
 
 import type {
   MillerColumnsRootProps,
@@ -33,9 +33,20 @@ import type {
  * The root of a Miller Columns widget — a horizontal strip of vertical
  * lists where selecting a node reveals its children in the next column.
  *
- * Renders the strip container (`role="tree"`, `data-orientation="horizontal"`)
- * into which every {@link MillerColumnsColumn | `MillerColumns.Column`}
- * projects itself via a portal. Authoring the tree is **recursive** and
+ * Renders **two** elements: an outer strip container
+ * (`data-miller-columns-strip`, `data-orientation="horizontal"`) that the
+ * consumer lays out and scrolls, and an inner `role="tree"` widget
+ * (`data-miller-columns-tree`) holding only the columns. The split exists
+ * because a tree may own nothing but `treeitem` and `group` — keeping the
+ * {@link MillerColumnsPreviewPanel | `PreviewPanel`} outside it means the
+ * panel is not an illegal child of the tree.
+ *
+ * Consequently **`aria-*` props land on the tree widget** (an `aria-label`
+ * must name the tree, not its scroll container) while every other prop —
+ * `className`, `id`, `style`, `data-*` — lands on the strip container.
+ *
+ * Every {@link MillerColumnsColumn | `MillerColumns.Column`}
+ * projects itself into the tree via a portal. Authoring the tree is **recursive** and
  * data-less: there is no `items` prop — an {@link MillerColumnsItem | `Item`}
  * declares its child column as a *nested* `<MillerColumns.Column>`, and the
  * strip flattens those nested columns into a single left-to-right row by
@@ -58,7 +69,15 @@ import type {
  * before any focus it defaults to the deepest selected item, falling back
  * to the first enabled root item. Within a column, Up/Down/Home/End move
  * focus; ArrowRight opens (and steps into) a branch item's child column,
- * ArrowLeft returns to the parent item.
+ * ArrowLeft returns to the parent item. Under
+ * {@link MillerColumnsRootBaseProps.dir | `dir="rtl"`} that horizontal pair
+ * is mirrored, so the step-in key always points at the child column.
+ *
+ * **Typeahead.** Printable characters move focus to the first item whose
+ * label starts with the accumulated query, wrapping, and cycling through
+ * matches when the same character repeats. The query is owned by `Root` —
+ * so it survives the focus move a match causes — but resolves against the
+ * **focused item's own column**, each column being an independent list.
  *
  * **Context.** Root establishes {@link MillerColumnsContext} (selection
  * path, portal slots, item registry, column widths, and focus commands);
@@ -83,28 +102,32 @@ export function MillerColumnsRoot({
   defaultValue,
   value,
   onValueChange,
+  dir,
   ...rest
 }: MillerColumnsRootProps): ReactElement {
-  const { contextValue, columnCount, registerSlotRef, stripRef } =
-    useMillerColumnsRoot(value, defaultValue, onValueChange);
+  const { contextValue, columnCount, registerSlotRef, stripRef, resolvedDir } =
+    useMillerColumnsRoot(value, defaultValue, onValueChange, dir);
+  const { aria, rest: containerProps } = partitionAriaProps(rest);
 
   return (
     <MillerColumnsContext.Provider value={contextValue}>
       <div
         ref={stripRef}
-        role="tree"
+        dir={resolvedDir}
         data-miller-columns-strip=""
         data-orientation="horizontal"
-        {...rest}
+        {...containerProps}
       >
-        {Array.from({ length: columnCount }, (_, depth) => (
-          <div
-            key={depth}
-            data-miller-columns-slot=""
-            style={{ display: "contents" }}
-            ref={registerSlotRef(depth)}
-          />
-        ))}
+        <div role="tree" data-miller-columns-tree="" {...aria}>
+          {Array.from({ length: columnCount }, (_, depth) => (
+            <div
+              key={depth}
+              data-miller-columns-slot=""
+              style={{ display: "contents" }}
+              ref={registerSlotRef(depth)}
+            />
+          ))}
+        </div>
         {children}
       </div>
     </MillerColumnsContext.Provider>
@@ -122,6 +145,10 @@ MillerColumnsRoot.displayName = "MillerColumnsRoot";
  * ancestors rather than in document flow. Until its slot has mounted the
  * component renders `null`.
  *
+ * A column holding no registered items carries **`data-empty`** — selecting
+ * a childless branch legitimately opens an empty column, and the styling
+ * layer needs to be able to say so rather than show a void.
+ *
  * It reads its depth from {@link MillerColumnsContext} and re-provides it to
  * descendant {@link MillerColumnsItem | Items} via
  * {@link MillerColumnsColumnContext}. A width set by a
@@ -143,7 +170,8 @@ export function MillerColumnsColumn({
   style,
   ...rest
 }: MillerColumnsColumnProps): ReactPortal | null {
-  const { slot, depth, width, columnContextValue } = useMillerColumnsColumn();
+  const { slot, depth, width, empty, columnContextValue } =
+    useMillerColumnsColumn();
 
   if (!slot) {
     return null;
@@ -155,6 +183,7 @@ export function MillerColumnsColumn({
         role="group"
         data-miller-columns-column=""
         data-depth={depth}
+        {...(empty ? { "data-empty": "" } : {})}
         style={{ ...style, ...(width !== undefined ? { width } : {}) }}
         {...rest}
       >
@@ -174,6 +203,13 @@ MillerColumnsColumn.displayName = "MillerColumnsColumn";
  * `aria-selected`, `aria-level` (1-based depth), and `data-state` /
  * `data-depth` styling hooks.
  *
+ * **Terminal vs ancestor.** Every item on the active path is
+ * `data-state="selected"`, including the ancestors the path merely passes
+ * through. The deepest one — the item the user actually landed on — also
+ * carries **`data-terminal`**. Style the two differently or the strip loses
+ * its depth cue: with a uniform selected state there is no way to tell
+ * which of four highlighted rows was clicked.
+ *
  * The {@link MillerColumnsItemProps.value | `value`} prop is the stable
  * identifier used to match this item against the active selection path.
  *
@@ -269,7 +305,7 @@ MillerColumnsItem.displayName = "MillerColumnsItem";
  * <MillerColumns.Item value="docs">
  *   Docs
  *   <MillerColumns.ItemIndicator>▸</MillerColumns.ItemIndicator>
- *   <MillerColumns.Column>…</MillerColumns.Column>
+ *   <MillerColumns.Column>...</MillerColumns.Column>
  * </MillerColumns.Item>
  * ```
  */
@@ -299,9 +335,27 @@ export function MillerColumnsItemIndicator({
 MillerColumnsItemIndicator.displayName = "MillerColumnsItemIndicator";
 
 /**
- * A drag-to-resize affordance for the column it is rendered in. Renders a
- * `<div role="separator" aria-orientation="vertical">` that, while
- * pointer-dragged, drives that column's width as state on the `Root`.
+ * A resize affordance for the column it is rendered in — the WAI-ARIA
+ * window-splitter pattern. Renders a focusable
+ * `<div role="separator" aria-orientation="vertical" tabIndex={0}>` that
+ * drives its column's width as state on the `Root`.
+ *
+ * **Pointer and keyboard.** Drag it, or focus it and use the arrow keys:
+ * the inline-end arrow widens by
+ * {@link MillerColumnsResizeHandleProps.step | `step`} and the inline-start
+ * arrow narrows (mirrored under `dir="rtl"`), with Home and End jumping to
+ * {@link MillerColumnsResizeHandleProps.minWidth | `minWidth`} /
+ * {@link MillerColumnsResizeHandleProps.maxWidth | `maxWidth`}. Both paths
+ * clamp to the same bounds. End is a no-op while `maxWidth` is unbounded.
+ *
+ * **Value semantics.** `aria-valuenow` tracks the column's real rendered
+ * width — measured with a `ResizeObserver`, so it is truthful before the
+ * first resize and follows CSS- or container-driven changes too.
+ * `aria-valuemin` always renders; `aria-valuemax` renders only when
+ * `maxWidth` is finite.
+ *
+ * **Give it an accessible name.** A splitter announces as an unnamed
+ * separator otherwise — pass `aria-label` (e.g. `"Resize column"`).
  *
  * Must be rendered among a {@link MillerColumnsColumn | `MillerColumns.Column`}'s
  * children — it reads the column's depth from
@@ -313,7 +367,11 @@ MillerColumnsItemIndicator.displayName = "MillerColumnsItemIndicator";
  * @example
  * ```tsx
  * <MillerColumns.Column>
- *   <MillerColumns.ResizeHandle />
+ *   <MillerColumns.ResizeHandle
+ *     aria-label="Resize column"
+ *     minWidth={120}
+ *     maxWidth={400}
+ *   />
  *   <MillerColumns.Item value="a">A</MillerColumns.Item>
  * </MillerColumns.Column>
  * ```
@@ -334,9 +392,14 @@ MillerColumnsResizeHandle.displayName = "MillerColumnsResizeHandle";
  * macOS-Finder-style preview pane.
  *
  * Renders a plain `<div data-miller-columns-preview>` as the last child
- * of the strip, sitting to the right of the columns. The component is
- * deliberately content-agnostic: it does not know how to preview an
- * item, so the consumer supplies whatever the panel should show.
+ * of the strip — *outside* the inner `role="tree"` widget, since a tree may
+ * own only `treeitem` and `group`. The component is deliberately
+ * content-agnostic: it does not know how to preview an item, so the
+ * consumer supplies whatever the panel should show.
+ *
+ * While nothing is selected the panel carries **`data-empty`**, so the
+ * styling layer can render a resting state without the consumer having to
+ * re-derive the selection.
  *
  * Pair it with {@link useMillerColumnsSelection} to render content for
  * the current selection. Author it as the **last child** of `Root`, a
@@ -363,12 +426,23 @@ MillerColumnsResizeHandle.displayName = "MillerColumnsResizeHandle";
  */
 export function MillerColumnsPreviewPanel({
   children,
+  forceMount = false,
   ...rest
-}: MillerColumnsPreviewPanelProps): ReactElement {
-  useMillerColumnsContext();
+}: MillerColumnsPreviewPanelProps): ReactElement | null {
+  const { activePath, terminalIsLeaf } = useMillerColumnsContext();
+
+  // Finder's rule: the preview occupies the slot *after* the selected item, so
+  // it exists only where that item has no children to open there instead.
+  if (!forceMount && !terminalIsLeaf) {
+    return null;
+  }
 
   return (
-    <div data-miller-columns-preview="" {...rest}>
+    <div
+      data-miller-columns-preview=""
+      {...(activePath.length === 0 ? { "data-empty": "" } : {})}
+      {...rest}
+    >
       {children}
     </div>
   );
@@ -396,7 +470,7 @@ type MillerColumnsCompound = typeof MillerColumnsRoot & {
 /**
  * MillerColumns — a horizontal strip of vertical lists where selecting a
  * node reveals its children in the next column. Use as a namespace
- * (`MillerColumns.Root`, `MillerColumns.Column`, `MillerColumns.Item`, …);
+ * (`MillerColumns.Root`, `MillerColumns.Column`, `MillerColumns.Item`, ...);
  * the default export is also callable as the Root.
  */
 const MillerColumnsCompound: MillerColumnsCompound = Object.assign(

package/src/MillerColumns/README.md

@@ -61,7 +61,7 @@ are ever rendered.
 | `MillerColumns.Column`        | List          | A vertical list of items, projected into the strip as `role="group"`                           |
 | `MillerColumns.Item`          | Tree node     | A `role="treeitem"`; branch when it nests a `Column`. Supports `disabled`, `asChild`, `ref`     |
 | `MillerColumns.ItemIndicator` | Icon wrapper  | Decorative `aria-hidden` icon, rendered only for branch items                                  |
-| `MillerColumns.ResizeHandle`  | Resize grip   | A `role="separator"` drag handle that sets its column's width                                   |
+| `MillerColumns.ResizeHandle`  | Resize grip   | A focusable `role="separator"` window splitter — drag or arrow-key it to set its column's width |
 | `MillerColumns.PreviewPanel`  | Preview pane  | A content-agnostic trailing panel; pair with `useMillerColumnsSelection`                        |
 
 ## Selection model
@@ -80,7 +80,20 @@ column deeper than _d_ closes.
 The two shapes are discriminated at the type level: passing
 `defaultValue` alongside `value` is a type error.
 
-There is no multi-select — only one path is active at a time.
+**Single path only, by decision.** There is no multi-select and there is
+not going to be one — this is settled, not a v1 shortfall awaiting a
+follow-up. A Miller strip's whole premise is that the selection *is* the
+path: column N+1 exists because exactly one item in column N is chosen.
+Two selections in a column have no defined answer for what the next
+column should show. A consumer needing to mark many nodes should keep
+that set themselves and render it as content inside each `Item` (a
+checkbox, a badge), leaving the path to mean navigation.
+
+Every item on the path renders `data-state="selected"`, including the
+ancestors the path merely passes through. The **deepest** one also gets
+`data-terminal`. Style the two apart — with a uniform selected state
+there is no way to tell which of several highlighted rows was actually
+clicked.
 
 ## Keyboard interaction
 
@@ -92,6 +105,18 @@ There is no multi-select — only one path is active at a time.
 | `ArrowRight`        | Branch: select it and move focus to its child column's first item; leaf: no-op |
 | `ArrowLeft`         | Move focus to the selected item of the parent column                   |
 | `Tab`               | Move into / out of the whole tree (single tabstop)                     |
+| Printable character | Typeahead — focus the first item in the column whose label matches     |
+
+Under `dir="rtl"` the horizontal pair is mirrored: `ArrowLeft` steps
+*into* a branch's child column and `ArrowRight` walks back out, so the
+step-in key always points at the column it opens. `dir` is inherited
+from a `DirectionProvider` ancestor when omitted.
+
+Typeahead accumulates keystrokes into a prefix query that resets after
+500 ms of inactivity; repeating one character cycles through the items
+starting with it. The query is scoped to the **focused item's own
+column** — each column is an independent list, so typing never jumps the
+cursor sideways.
 
 The strip is a single roving-tabindex widget: exactly one item is
 tabbable at a time. The tabstop follows the last-focused item and
@@ -109,7 +134,20 @@ effect when the strip is itself an overflow container; give
 
 ## ARIA
 
-- The strip is `role="tree"`.
+`Root` renders **two** elements: an outer strip container you lay out and
+scroll, and an inner `role="tree"` widget holding only the columns. A
+tree may own nothing but `treeitem` and `group`, so the `PreviewPanel`
+sits outside it.
+
+Because of that split, **`aria-*` props go to the tree widget** and every
+other prop (`className`, `id`, `style`, `data-*`) goes to the strip
+container:
+
+```tsx
+<MillerColumns.Root aria-label="Files" className="strip">
+```
+
+- The tree widget is `role="tree"`.
 - Each `Column` is `role="group"`.
 - Each `Item` is `role="treeitem"` with `aria-level` (1-based column
   depth), `aria-selected`, and — on branch items — `aria-expanded`.
@@ -156,10 +194,42 @@ it to the column's trailing edge yourself:
 ```
 
 The first drag measures the column's current rendered width and
-resizes from there; later drags resume from the last resized width. A
-width is clamped so it can never be dragged below zero — use CSS
-`min-width` for any larger floor. Resize is pointer-only; the handle
-is not keyboard-operable.
+resizes from there; later drags resume from the last resized width.
+
+The handle is a full WAI-ARIA **window splitter**: it is focusable, and
+arrow keys resize it. Pass `minWidth` / `maxWidth` / `step` to bound and
+pace that (they clamp pointer drags too, so CSS `min-width` is no longer
+the only floor).
+
+| Prop       | Default    | Effect                                             |
+| ---------- | ---------- | -------------------------------------------------- |
+| `minWidth` | `0`        | Floor for drag and keys; published as `aria-valuemin` |
+| `maxWidth` | `Infinity` | Ceiling; published as `aria-valuemax` only when finite |
+| `step`     | `10`       | Pixels moved per arrow-key press                    |
+
+| Key                       | Behaviour                          |
+| ------------------------- | ---------------------------------- |
+| Inline-end arrow          | Widen the column by `step`         |
+| Inline-start arrow        | Narrow the column by `step`        |
+| `Home` / `End`            | Jump to `minWidth` / `maxWidth`    |
+
+The arrow pair mirrors under `dir="rtl"`. `End` does nothing while
+`maxWidth` is unbounded — there is no largest width to jump to.
+
+`aria-valuenow` tracks the column's real rendered width via a
+`ResizeObserver`, so it is correct before the first resize and follows
+CSS- or container-driven changes as well.
+
+**Give the handle an accessible name** — without one it announces as an
+unnamed separator:
+
+```tsx
+<MillerColumns.ResizeHandle
+  aria-label="Resize column"
+  minWidth={120}
+  maxWidth={400}
+/>
+```
 
 ## Preview panel
 
@@ -199,10 +269,11 @@ function FilePreview() {
 both controlled and uncontrolled roots, and throws if called outside
 `MillerColumns.Root`.
 
-The panel ships with no ARIA role. The strip is a `role="tree"`, whose
-conforming children are `treeitem`s and `group`s — so give the panel
-content its own labelled landmark (`role`, `aria-label`, …) through
-props if the preview warrants being announced.
+The panel ships with no ARIA role, and renders *outside* the inner
+`role="tree"` widget — a tree may own only `treeitem`s and `group`s, so
+the panel could not legally sit inside it. Give the panel content its
+own labelled landmark (`role`, `aria-label`, ...) through props if the
+preview warrants being announced.
 
 ## `asChild` composition
 
@@ -216,7 +287,7 @@ element:
 ```tsx
 <MillerColumns.Item<HTMLAnchorElement> asChild value="docs">
   <a href="#docs">Docs</a>
-  <MillerColumns.Column>…</MillerColumns.Column>
+  <MillerColumns.Column>...</MillerColumns.Column>
 </MillerColumns.Item>
 ```
 
@@ -229,10 +300,11 @@ Zero styles ship with the component. Style it through `data-*` hooks;
 typically the strip is `display: flex` and each column scrolls
 vertically.
 
-Inside the strip, each column is wrapped in a transparent
+Inside the tree element, each column is wrapped in a transparent
 (`display: contents`) slot element that fixes left-to-right order — so
 target columns with `[data-miller-columns-column]`, not a direct-child
-selector like `[data-miller-columns-strip] > *`.
+selector like `[data-miller-columns-tree] > *`. Note the strip's direct
+children are the tree element and the `PreviewPanel`, not the columns.
 
 ```css
 [data-miller-columns-strip] {
@@ -258,11 +330,12 @@ selector like `[data-miller-columns-strip] > *`.
 | Element         | Attributes                                                                  |
 | --------------- | --------------------------------------------------------------------------- |
 | Strip (`Root`)  | `data-miller-columns-strip`, `data-orientation="horizontal"`                |
-| `Column`        | `data-miller-columns-column`, `data-depth`                                  |
-| `Item`          | `data-state="selected" \| "unselected"`, `data-depth`, `data-has-children`, `data-disabled` |
+| Tree (`Root`)   | `data-miller-columns-tree`, `role="tree"` — the inner widget element        |
+| `Column`        | `data-miller-columns-column`, `data-depth`, `data-empty` (no items)         |
+| `Item`          | `data-state="selected" \| "unselected"`, `data-terminal` (deepest selected), `data-depth`, `data-has-children`, `data-disabled` |
 | `ItemIndicator` | `data-state`, `data-has-children`                                           |
 | `ResizeHandle`  | `data-miller-columns-resize-handle`, `data-dragging` (present mid-drag)     |
-| `PreviewPanel`  | `data-miller-columns-preview`                                               |
+| `PreviewPanel`  | `data-miller-columns-preview`, `data-empty` (nothing selected)              |
 
 ## Deferred / follow-up work
 
@@ -273,6 +346,3 @@ good candidates for later, independent cycles:
    exists, a leaf image `Item` could open a context menu on
    right-click whose first entry ("Preview", with an eye icon) opens
    the `Modal` to show the image larger.
-2. **Keyboard-operable resize.** `MillerColumns.ResizeHandle` is
-   pointer-only; an arrow-key resize on the focused handle would round
-   out the WAI-ARIA window-splitter pattern.