@primitiv-ui/react 0.1.38 → 0.1.39

package/dist/MillerColumns/MillerColumns.d.ts

@@ -0,0 +1,309 @@
+import type { ReactElement, ReactPortal } from "react";
+import type { MillerColumnsRootProps, MillerColumnsColumnProps, MillerColumnsItemProps, MillerColumnsItemIndicatorProps, MillerColumnsResizeHandleProps, MillerColumnsPreviewPanelProps } from "./types.js";
+/**
+ * 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 **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
+ * rendering one `display: contents` slot per visible depth and portalling
+ * each column into its slot. This fixes left-to-right DOM order by slot
+ * order rather than by portal commit order.
+ *
+ * **Controlled vs uncontrolled.** State is the *selection path* — an array
+ * of item ids, root column first (`["docs", "guides"]`). The two modes are
+ * statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link MillerColumnsRootUncontrolledProps.defaultValue | `defaultValue`}
+ *   (or omit it to start empty). The component owns the path.
+ * - **Controlled** — pass {@link MillerColumnsRootControlledProps.value | `value`}
+ *   and {@link MillerColumnsRootControlledProps.onValueChange | `onValueChange`}
+ *   together; every selection defers back through the callback.
+ *
+ * **Roving tabindex.** The whole tree has exactly **one** Tab stop
+ * (`tabIndex={0}`), not one per column. It follows the last-focused item;
+ * 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. 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);
+ * each Column provides {@link MillerColumnsColumnContext} (its depth) and
+ * each Item {@link MillerColumnsItemContext} (`selected` / `hasChildren`).
+ * Read the current selection from consumer content with
+ * {@link useMillerColumnsSelection}.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Root>
+ *   <MillerColumns.Column>
+ *     <MillerColumns.Item value="docs">Docs</MillerColumns.Item>
+ *   </MillerColumns.Column>
+ * </MillerColumns.Root>
+ * ```
+ */
+export declare function MillerColumnsRoot({ children, defaultValue, value, onValueChange, dir, ...rest }: MillerColumnsRootProps): ReactElement;
+export declare namespace MillerColumnsRoot {
+    var displayName: string;
+}
+/**
+ * A single vertical list of items within the strip. Renders a
+ * `<div role="group">` (carrying `data-depth`) that is **portal-projected**
+ * into the {@link MillerColumnsRoot | `Root`} strip's depth slot, so a
+ * `Column` nested inside an `Item` still appears side-by-side with its
+ * 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
+ * {@link MillerColumnsResizeHandle | `ResizeHandle`} in this column is
+ * applied here as an inline `width` style (consumer `style` still wins for
+ * every other property).
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Column>
+ *   <MillerColumns.Item value="a">A</MillerColumns.Item>
+ * </MillerColumns.Column>
+ * ```
+ */
+export declare function MillerColumnsColumn({ children, style, ...rest }: MillerColumnsColumnProps): ReactPortal | null;
+export declare namespace MillerColumnsColumn {
+    var displayName: string;
+}
+/**
+ * A single selectable node within a {@link MillerColumnsColumn | `Column`}.
+ * Renders a `<div role="treeitem">` for its cell content, with
+ * `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.
+ *
+ * **Branch vs leaf.** An `Item` becomes a *branch* by nesting a
+ * `<MillerColumns.Column>` among its children — `partitionItemChildren`
+ * splits the children into the cell content and that single optional
+ * nested column (matched however deeply it is wrapped in fragments; a
+ * second nested column throws). A branch carries `aria-expanded` and
+ * mounts its child column (projecting it into the strip) only while the
+ * item is selected; an item with no nested column is a *leaf*.
+ *
+ * **Keyboard & selection.** Clicking or activating (Enter/Space) selects
+ * the item, truncating the path to this depth. ArrowRight on a branch opens
+ * and steps into the child column; ArrowLeft returns focus to the parent
+ * item. The item participates in the tree-wide single roving Tab stop.
+ *
+ * **Disabled.** Pass `disabled` to render `aria-disabled="true"` /
+ * `data-disabled`; the item is skipped by roving navigation and cannot be
+ * selected, focused, or activated.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the cell as a
+ * consumer-supplied element (e.g. an `<a>`) instead of the default
+ * `<div>`. All treeitem ARIA attributes, event handlers, and the internal
+ * ref are merged onto that child via the {@link Slot} pattern. A nested
+ * `<MillerColumns.Column>` is still declared as a sibling of the cell
+ * element.
+ *
+ * **Ref forwarding.** A `ref` prop (React 19 ref-as-prop style) is
+ * forwarded to the rendered element and composed with the library's
+ * internal ref.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Leaf
+ * ```tsx
+ * <MillerColumns.Item value="guides">Guides</MillerColumns.Item>
+ * ```
+ *
+ * @example Branch
+ * ```tsx
+ * <MillerColumns.Item value="docs">
+ *   Docs
+ *   <MillerColumns.Column>
+ *     <MillerColumns.Item value="guides">Guides</MillerColumns.Item>
+ *   </MillerColumns.Column>
+ * </MillerColumns.Item>
+ * ```
+ */
+export declare function MillerColumnsItem<T extends HTMLElement = HTMLDivElement>({ children, ref, asChild, ...props }: MillerColumnsItemProps<T>): ReactElement;
+export declare namespace MillerColumnsItem {
+    var displayName: string;
+}
+/**
+ * An optional, decorative affordance for a branch item — typically a
+ * chevron or arrow signalling "this item reveals a child column".
+ *
+ * Renders a `<span aria-hidden="true">` (so the glyph is ignored by
+ * assistive technology) **only for branch items**; for a leaf item it
+ * renders nothing. Place it among an `Item`'s cell content.
+ *
+ * **Styling hooks.**
+ * - `data-state="selected" | "unselected"` — mirrors the parent item.
+ * - `data-has-children` — always present (the indicator only renders
+ *   for branch items).
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Item value="docs">
+ *   Docs
+ *   <MillerColumns.ItemIndicator>▸</MillerColumns.ItemIndicator>
+ *   <MillerColumns.Column>...</MillerColumns.Column>
+ * </MillerColumns.Item>
+ * ```
+ */
+export declare function MillerColumnsItemIndicator({ children, ...rest }: MillerColumnsItemIndicatorProps): ReactElement | null;
+export declare namespace MillerColumnsItemIndicator {
+    var displayName: string;
+}
+/**
+ * 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
+ * {@link MillerColumnsColumnContext}. Position it with CSS (typically
+ * absolutely, against the column's trailing edge).
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Column>
+ *   <MillerColumns.ResizeHandle
+ *     aria-label="Resize column"
+ *     minWidth={120}
+ *     maxWidth={400}
+ *   />
+ *   <MillerColumns.Item value="a">A</MillerColumns.Item>
+ * </MillerColumns.Column>
+ * ```
+ */
+export declare function MillerColumnsResizeHandle(props: MillerColumnsResizeHandleProps): ReactElement;
+export declare namespace MillerColumnsResizeHandle {
+    var displayName: string;
+}
+/**
+ * A trailing panel for previewing the current selection — the
+ * macOS-Finder-style preview pane.
+ *
+ * Renders a plain `<div data-miller-columns-preview>` as the last child
+ * 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
+ * sibling of the root `Column`. It subscribes to
+ * {@link MillerColumnsContext} (so it must live inside a `Root`) but does
+ * not portal — it stays in document flow after the projected columns.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * function FilePreview() {
+ *   const { selectedValue } = useMillerColumnsSelection();
+ *   return selectedValue ? <Preview id={selectedValue} /> : null;
+ * }
+ *
+ * <MillerColumns.Root>
+ *   <MillerColumns.Column>{items}</MillerColumns.Column>
+ *   <MillerColumns.PreviewPanel>
+ *     <FilePreview />
+ *   </MillerColumns.PreviewPanel>
+ * </MillerColumns.Root>;
+ * ```
+ */
+export declare function MillerColumnsPreviewPanel({ children, forceMount, ...rest }: MillerColumnsPreviewPanelProps): ReactElement | null;
+export declare namespace MillerColumnsPreviewPanel {
+    var displayName: string;
+}
+/** Type of the {@link MillerColumns} compound — the Root callable plus its sub-components. */
+type MillerColumnsCompound = typeof MillerColumnsRoot & {
+    /** The root strip, owning selection state and portal slots. */
+    Root: typeof MillerColumnsRoot;
+    /** A single vertical list within the strip. */
+    Column: typeof MillerColumnsColumn;
+    /** A selectable node within a column. */
+    Item: typeof MillerColumnsItem;
+    /** The branch-item chevron affordance. */
+    ItemIndicator: typeof MillerColumnsItemIndicator;
+    /** The drag-to-resize separator. */
+    ResizeHandle: typeof MillerColumnsResizeHandle;
+    /** The trailing preview pane. */
+    PreviewPanel: typeof MillerColumnsPreviewPanel;
+};
+/**
+ * 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`, ...);
+ * the default export is also callable as the Root.
+ */
+declare const MillerColumnsCompound: MillerColumnsCompound;
+export { MillerColumnsCompound as MillerColumns };

package/dist/MillerColumns/MillerColumns.js

@@ -0,0 +1,332 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createPortal } from "react-dom";
+import { Slot } from "../Slot/index.js";
+import { MillerColumnsContext, MillerColumnsColumnContext, MillerColumnsItemContext, } from "./MillerColumnsContext.js";
+import { useMillerColumnsColumn, useMillerColumnsContext, useMillerColumnsItem, useMillerColumnsItemContext, useMillerColumnsResizeHandle, useMillerColumnsRoot, } from "./hooks/index.js";
+import { partitionAriaProps, partitionItemChildren } from "./utils.js";
+/**
+ * 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 **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
+ * rendering one `display: contents` slot per visible depth and portalling
+ * each column into its slot. This fixes left-to-right DOM order by slot
+ * order rather than by portal commit order.
+ *
+ * **Controlled vs uncontrolled.** State is the *selection path* — an array
+ * of item ids, root column first (`["docs", "guides"]`). The two modes are
+ * statically discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass {@link MillerColumnsRootUncontrolledProps.defaultValue | `defaultValue`}
+ *   (or omit it to start empty). The component owns the path.
+ * - **Controlled** — pass {@link MillerColumnsRootControlledProps.value | `value`}
+ *   and {@link MillerColumnsRootControlledProps.onValueChange | `onValueChange`}
+ *   together; every selection defers back through the callback.
+ *
+ * **Roving tabindex.** The whole tree has exactly **one** Tab stop
+ * (`tabIndex={0}`), not one per column. It follows the last-focused item;
+ * 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. 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);
+ * each Column provides {@link MillerColumnsColumnContext} (its depth) and
+ * each Item {@link MillerColumnsItemContext} (`selected` / `hasChildren`).
+ * Read the current selection from consumer content with
+ * {@link useMillerColumnsSelection}.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Root>
+ *   <MillerColumns.Column>
+ *     <MillerColumns.Item value="docs">Docs</MillerColumns.Item>
+ *   </MillerColumns.Column>
+ * </MillerColumns.Root>
+ * ```
+ */
+export function MillerColumnsRoot({ children, defaultValue, value, onValueChange, dir, ...rest }) {
+    const { contextValue, columnCount, registerSlotRef, stripRef, resolvedDir } = useMillerColumnsRoot(value, defaultValue, onValueChange, dir);
+    const { aria, rest: containerProps } = partitionAriaProps(rest);
+    return (_jsx(MillerColumnsContext.Provider, { value: contextValue, children: _jsxs("div", { ref: stripRef, dir: resolvedDir, "data-miller-columns-strip": "", "data-orientation": "horizontal", ...containerProps, children: [_jsx("div", { role: "tree", "data-miller-columns-tree": "", ...aria, children: Array.from({ length: columnCount }, (_, depth) => (_jsx("div", { "data-miller-columns-slot": "", style: { display: "contents" }, ref: registerSlotRef(depth) }, depth))) }), children] }) }));
+}
+/** @internal */
+MillerColumnsRoot.displayName = "MillerColumnsRoot";
+/**
+ * A single vertical list of items within the strip. Renders a
+ * `<div role="group">` (carrying `data-depth`) that is **portal-projected**
+ * into the {@link MillerColumnsRoot | `Root`} strip's depth slot, so a
+ * `Column` nested inside an `Item` still appears side-by-side with its
+ * 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
+ * {@link MillerColumnsResizeHandle | `ResizeHandle`} in this column is
+ * applied here as an inline `width` style (consumer `style` still wins for
+ * every other property).
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Column>
+ *   <MillerColumns.Item value="a">A</MillerColumns.Item>
+ * </MillerColumns.Column>
+ * ```
+ */
+export function MillerColumnsColumn({ children, style, ...rest }) {
+    const { slot, depth, width, empty, columnContextValue } = useMillerColumnsColumn();
+    if (!slot) {
+        return null;
+    }
+    return createPortal(_jsx(MillerColumnsColumnContext.Provider, { value: columnContextValue, children: _jsx("div", { role: "group", "data-miller-columns-column": "", "data-depth": depth, ...(empty ? { "data-empty": "" } : {}), style: { ...style, ...(width !== undefined ? { width } : {}) }, ...rest, children: children }) }), slot);
+}
+/** @internal */
+MillerColumnsColumn.displayName = "MillerColumnsColumn";
+/**
+ * A single selectable node within a {@link MillerColumnsColumn | `Column`}.
+ * Renders a `<div role="treeitem">` for its cell content, with
+ * `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.
+ *
+ * **Branch vs leaf.** An `Item` becomes a *branch* by nesting a
+ * `<MillerColumns.Column>` among its children — `partitionItemChildren`
+ * splits the children into the cell content and that single optional
+ * nested column (matched however deeply it is wrapped in fragments; a
+ * second nested column throws). A branch carries `aria-expanded` and
+ * mounts its child column (projecting it into the strip) only while the
+ * item is selected; an item with no nested column is a *leaf*.
+ *
+ * **Keyboard & selection.** Clicking or activating (Enter/Space) selects
+ * the item, truncating the path to this depth. ArrowRight on a branch opens
+ * and steps into the child column; ArrowLeft returns focus to the parent
+ * item. The item participates in the tree-wide single roving Tab stop.
+ *
+ * **Disabled.** Pass `disabled` to render `aria-disabled="true"` /
+ * `data-disabled`; the item is skipped by roving navigation and cannot be
+ * selected, focused, or activated.
+ *
+ * **`asChild` prop.** Pass `asChild` to render the cell as a
+ * consumer-supplied element (e.g. an `<a>`) instead of the default
+ * `<div>`. All treeitem ARIA attributes, event handlers, and the internal
+ * ref are merged onto that child via the {@link Slot} pattern. A nested
+ * `<MillerColumns.Column>` is still declared as a sibling of the cell
+ * element.
+ *
+ * **Ref forwarding.** A `ref` prop (React 19 ref-as-prop style) is
+ * forwarded to the rendered element and composed with the library's
+ * internal ref.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example Leaf
+ * ```tsx
+ * <MillerColumns.Item value="guides">Guides</MillerColumns.Item>
+ * ```
+ *
+ * @example Branch
+ * ```tsx
+ * <MillerColumns.Item value="docs">
+ *   Docs
+ *   <MillerColumns.Column>
+ *     <MillerColumns.Item value="guides">Guides</MillerColumns.Item>
+ *   </MillerColumns.Column>
+ * </MillerColumns.Item>
+ * ```
+ */
+export function MillerColumnsItem({ children, ref, asChild = false, ...props }) {
+    const { cell, column } = partitionItemChildren(children);
+    const { itemProps, selected, itemContextValue } = useMillerColumnsItem({ ref: ref, ...props }, column !== null);
+    return (_jsxs(MillerColumnsItemContext.Provider, { value: itemContextValue, children: [asChild ? (_jsx(Slot, { ...itemProps, children: cell[0] })) : (_jsx("div", { ...itemProps, children: cell })), selected ? column : null] }));
+}
+/** @internal */
+MillerColumnsItem.displayName = "MillerColumnsItem";
+/**
+ * An optional, decorative affordance for a branch item — typically a
+ * chevron or arrow signalling "this item reveals a child column".
+ *
+ * Renders a `<span aria-hidden="true">` (so the glyph is ignored by
+ * assistive technology) **only for branch items**; for a leaf item it
+ * renders nothing. Place it among an `Item`'s cell content.
+ *
+ * **Styling hooks.**
+ * - `data-state="selected" | "unselected"` — mirrors the parent item.
+ * - `data-has-children` — always present (the indicator only renders
+ *   for branch items).
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Item value="docs">
+ *   Docs
+ *   <MillerColumns.ItemIndicator>▸</MillerColumns.ItemIndicator>
+ *   <MillerColumns.Column>...</MillerColumns.Column>
+ * </MillerColumns.Item>
+ * ```
+ */
+export function MillerColumnsItemIndicator({ children, ...rest }) {
+    const { selected, hasChildren } = useMillerColumnsItemContext();
+    if (!hasChildren) {
+        return null;
+    }
+    return (_jsx("span", { "aria-hidden": "true", "data-state": selected ? "selected" : "unselected", "data-has-children": "", ...rest, children: children }));
+}
+/** @internal */
+MillerColumnsItemIndicator.displayName = "MillerColumnsItemIndicator";
+/**
+ * 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
+ * {@link MillerColumnsColumnContext}. Position it with CSS (typically
+ * absolutely, against the column's trailing edge).
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Column>
+ *   <MillerColumns.ResizeHandle
+ *     aria-label="Resize column"
+ *     minWidth={120}
+ *     maxWidth={400}
+ *   />
+ *   <MillerColumns.Item value="a">A</MillerColumns.Item>
+ * </MillerColumns.Column>
+ * ```
+ */
+export function MillerColumnsResizeHandle(props) {
+    const { handleProps } = useMillerColumnsResizeHandle(props);
+    return _jsx("div", { ...handleProps });
+}
+/** @internal */
+MillerColumnsResizeHandle.displayName = "MillerColumnsResizeHandle";
+/**
+ * A trailing panel for previewing the current selection — the
+ * macOS-Finder-style preview pane.
+ *
+ * Renders a plain `<div data-miller-columns-preview>` as the last child
+ * 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
+ * sibling of the root `Column`. It subscribes to
+ * {@link MillerColumnsContext} (so it must live inside a `Root`) but does
+ * not portal — it stays in document flow after the projected columns.
+ *
+ * @extends HTMLDivElement
+ *
+ * @example
+ * ```tsx
+ * function FilePreview() {
+ *   const { selectedValue } = useMillerColumnsSelection();
+ *   return selectedValue ? <Preview id={selectedValue} /> : null;
+ * }
+ *
+ * <MillerColumns.Root>
+ *   <MillerColumns.Column>{items}</MillerColumns.Column>
+ *   <MillerColumns.PreviewPanel>
+ *     <FilePreview />
+ *   </MillerColumns.PreviewPanel>
+ * </MillerColumns.Root>;
+ * ```
+ */
+export function MillerColumnsPreviewPanel({ children, forceMount = false, ...rest }) {
+    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 (_jsx("div", { "data-miller-columns-preview": "", ...(activePath.length === 0 ? { "data-empty": "" } : {}), ...rest, children: children }));
+}
+/** @internal */
+MillerColumnsPreviewPanel.displayName = "MillerColumnsPreviewPanel";
+/**
+ * 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`, ...);
+ * the default export is also callable as the Root.
+ */
+const MillerColumnsCompound = Object.assign(MillerColumnsRoot, {
+    Root: MillerColumnsRoot,
+    Column: MillerColumnsColumn,
+    Item: MillerColumnsItem,
+    ItemIndicator: MillerColumnsItemIndicator,
+    ResizeHandle: MillerColumnsResizeHandle,
+    PreviewPanel: MillerColumnsPreviewPanel,
+});
+MillerColumnsCompound.displayName = "MillerColumns";
+export { MillerColumnsCompound as MillerColumns };

package/dist/MillerColumns/MillerColumnsContext.d.ts

@@ -0,0 +1,4 @@
+import type { MillerColumnsContextValue, MillerColumnsColumnContextValue, MillerColumnsItemContextValue } from "./types.js";
+export declare const MillerColumnsContext: import("react").Context<MillerColumnsContextValue | null>, useMillerColumnsContext: () => MillerColumnsContextValue;
+export declare const MillerColumnsColumnContext: import("react").Context<MillerColumnsColumnContextValue | null>, useMillerColumnsColumnContext: () => MillerColumnsColumnContextValue;
+export declare const MillerColumnsItemContext: import("react").Context<MillerColumnsItemContextValue | null>, useMillerColumnsItemContext: () => MillerColumnsItemContextValue;

package/dist/MillerColumns/MillerColumnsContext.js

@@ -0,0 +1,5 @@
+"use client";
+import { createStrictContext } from "../utils/index.js";
+export const [MillerColumnsContext, useMillerColumnsContext] = createStrictContext("MillerColumns sub-components must be rendered inside <MillerColumns.Root>.", "MillerColumnsContext");
+export const [MillerColumnsColumnContext, useMillerColumnsColumnContext] = createStrictContext("MillerColumns.Item must be rendered inside <MillerColumns.Column>.", "MillerColumnsColumnContext");
+export const [MillerColumnsItemContext, useMillerColumnsItemContext] = createStrictContext("MillerColumns.ItemIndicator must be rendered inside <MillerColumns.Item>.", "MillerColumnsItemContext");

package/dist/MillerColumns/constants.d.ts

@@ -0,0 +1,2 @@
+/** Milliseconds of typing inactivity after which the typeahead query resets. */
+export declare const TYPEAHEAD_RESET_MS = 500;

package/dist/MillerColumns/constants.js

@@ -0,0 +1,3 @@
+"use client";
+/** Milliseconds of typing inactivity after which the typeahead query resets. */
+export const TYPEAHEAD_RESET_MS = 500;

package/dist/MillerColumns/hooks/index.d.ts

@@ -0,0 +1,7 @@
+export { useMillerColumnsContext } from "./useMillerColumnsContext.js";
+export { useMillerColumnsColumnContext } from "./useMillerColumnsColumnContext.js";
+export { useMillerColumnsItemContext } from "./useMillerColumnsItemContext.js";
+export { useMillerColumnsRoot } from "./useMillerColumnsRoot.js";
+export { useMillerColumnsColumn } from "./useMillerColumnsColumn.js";
+export { useMillerColumnsItem } from "./useMillerColumnsItem.js";
+export { useMillerColumnsResizeHandle } from "./useMillerColumnsResizeHandle.js";