@primitiv-ui/react 0.1.28 → 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,11 +33,60 @@ 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"`) into which every
- * `MillerColumns.Column` projects itself via a portal. Authoring the tree
- * is recursive: an `Item` declares its child column as a *nested*
- * `<MillerColumns.Column>`, and the strip flattens those nested columns
- * into a single left-to-right row.
+ * 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
@@ -53,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>
@@ -86,9 +139,24 @@ MillerColumnsRoot.displayName = "MillerColumnsRoot";
 
 /**
  * A single vertical list of items within the strip. Renders a
- * `<div role="group">` that is portal-projected into the `Root` strip, so
- * a `Column` nested inside an `Item` still appears side-by-side with its
- * ancestors rather than in document flow.
+ * `<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
@@ -102,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;
@@ -114,6 +183,7 @@ export function MillerColumnsColumn({
         role="group"
         data-miller-columns-column=""
         data-depth={depth}
+        {...(empty ? { "data-empty": "" } : {})}
         style={{ ...style, ...(width !== undefined ? { width } : {}) }}
         {...rest}
       >
@@ -128,27 +198,51 @@ export function MillerColumnsColumn({
 MillerColumnsColumn.displayName = "MillerColumnsColumn";
 
 /**
- * A single selectable node within a `Column`. Renders a
- * `<div role="treeitem">` for its cell content.
+ * 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.
  *
- * An `Item` becomes a branch by nesting a `<MillerColumns.Column>` among
- * its children. That child column is mounted (and projected into the
- * strip) only while the item is selected; an item with no nested column
- * is a leaf.
+ * **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. A nested `<MillerColumns.Column>` is
- * still declared as a sibling of the cell element.
+ * 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>
@@ -204,12 +298,14 @@ MillerColumnsItem.displayName = "MillerColumnsItem";
  * - `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.Column>...</MillerColumns.Column>
  * </MillerColumns.Item>
  * ```
  */
@@ -239,18 +335,43 @@ 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.
  *
- * Must be rendered among a `MillerColumns.Column`'s children — it reads
- * the column's depth from context. Position it with CSS (typically
+ * **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 />
+ *   <MillerColumns.ResizeHandle
+ *     aria-label="Resize column"
+ *     minWidth={120}
+ *     maxWidth={400}
+ *   />
  *   <MillerColumns.Item value="a">A</MillerColumns.Item>
  * </MillerColumns.Column>
  * ```
@@ -271,13 +392,22 @@ 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
- * sibling of the root `Column`.
+ * 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
@@ -296,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>
   );
@@ -329,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(