@primitiv-ui/react 0.1.0

package/src/MillerColumns/MillerColumns.tsx

@@ -0,0 +1,329 @@
+import { Ref } from "react";
+import { createPortal } from "react-dom";
+
+import { Slot } from "../Slot";
+
+import {
+  MillerColumnsContext,
+  MillerColumnsColumnContext,
+  MillerColumnsItemContext,
+} from "./MillerColumnsContext";
+import {
+  useMillerColumnsColumn,
+  useMillerColumnsContext,
+  useMillerColumnsItem,
+  useMillerColumnsItemContext,
+  useMillerColumnsResizeHandle,
+  useMillerColumnsRoot,
+} from "./hooks";
+
+import { partitionItemChildren } from "./utils";
+
+import type {
+  MillerColumnsRootProps,
+  MillerColumnsColumnProps,
+  MillerColumnsItemProps,
+  MillerColumnsItemIndicatorProps,
+  MillerColumnsResizeHandleProps,
+  MillerColumnsPreviewPanelProps,
+} from "./types";
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Root>
+ *   <MillerColumns.Column>
+ *     <MillerColumns.Item value="docs">Docs</MillerColumns.Item>
+ *   </MillerColumns.Column>
+ * </MillerColumns.Root>
+ * ```
+ */
+export function MillerColumnsRoot({
+  children,
+  defaultValue,
+  value,
+  onValueChange,
+  ...rest
+}: MillerColumnsRootProps) {
+  const { contextValue, columnCount, registerSlotRef, stripRef } =
+    useMillerColumnsRoot(value, defaultValue, onValueChange);
+
+  return (
+    <MillerColumnsContext.Provider value={contextValue}>
+      <div
+        ref={stripRef}
+        role="tree"
+        data-miller-columns-strip=""
+        data-orientation="horizontal"
+        {...rest}
+      >
+        {Array.from({ length: columnCount }, (_, depth) => (
+          <div
+            key={depth}
+            data-miller-columns-slot=""
+            style={{ display: "contents" }}
+            ref={registerSlotRef(depth)}
+          />
+        ))}
+        {children}
+      </div>
+    </MillerColumnsContext.Provider>
+  );
+}
+
+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.
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Column>
+ *   <MillerColumns.Item value="a">A</MillerColumns.Item>
+ * </MillerColumns.Column>
+ * ```
+ */
+export function MillerColumnsColumn({
+  children,
+  style,
+  ...rest
+}: MillerColumnsColumnProps) {
+  const { slot, depth, width, columnContextValue } = useMillerColumnsColumn();
+
+  if (!slot) {
+    return null;
+  }
+
+  return createPortal(
+    <MillerColumnsColumnContext.Provider value={columnContextValue}>
+      <div
+        role="group"
+        data-miller-columns-column=""
+        data-depth={depth}
+        style={{ ...style, ...(width !== undefined ? { width } : {}) }}
+        {...rest}
+      >
+        {children}
+      </div>
+    </MillerColumnsColumnContext.Provider>,
+    slot,
+  );
+}
+
+MillerColumnsColumn.displayName = "MillerColumnsColumn";
+
+/**
+ * A single selectable node within a `Column`. Renders a
+ * `<div role="treeitem">` for its cell content.
+ *
+ * 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.
+ *
+ * **`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 forwarding.** A `ref` prop (React 19 ref-as-prop style) is
+ * forwarded to the rendered element and composed with the library's
+ * internal ref.
+ *
+ * @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<T extends HTMLElement = HTMLDivElement>({
+  children,
+  ref,
+  asChild = false,
+  ...props
+}: MillerColumnsItemProps<T>) {
+  const { cell, column } = partitionItemChildren(children);
+  const { itemProps, selected, itemContextValue } = useMillerColumnsItem(
+    { ref: ref as Ref<HTMLDivElement>, ...props },
+    column !== null,
+  );
+
+  return (
+    <MillerColumnsItemContext.Provider value={itemContextValue}>
+      {asChild ? (
+        <Slot {...itemProps}>{cell[0]}</Slot>
+      ) : (
+        <div {...itemProps}>{cell}</div>
+      )}
+      {selected ? column : null}
+    </MillerColumnsItemContext.Provider>
+  );
+}
+
+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).
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Item value="docs">
+ *   Docs
+ *   <MillerColumns.ItemIndicator>▸</MillerColumns.ItemIndicator>
+ *   <MillerColumns.Column>…</MillerColumns.Column>
+ * </MillerColumns.Item>
+ * ```
+ */
+export function MillerColumnsItemIndicator({
+  children,
+  ...rest
+}: MillerColumnsItemIndicatorProps) {
+  const { selected, hasChildren } = useMillerColumnsItemContext();
+
+  if (!hasChildren) {
+    return null;
+  }
+
+  return (
+    <span
+      aria-hidden="true"
+      data-state={selected ? "selected" : "unselected"}
+      data-has-children=""
+      {...rest}
+    >
+      {children}
+    </span>
+  );
+}
+
+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`.
+ *
+ * Must be rendered among a `MillerColumns.Column`'s children — it reads
+ * the column's depth from context. Position it with CSS (typically
+ * absolutely, against the column's trailing edge).
+ *
+ * @example
+ * ```tsx
+ * <MillerColumns.Column>
+ *   <MillerColumns.ResizeHandle />
+ *   <MillerColumns.Item value="a">A</MillerColumns.Item>
+ * </MillerColumns.Column>
+ * ```
+ */
+export function MillerColumnsResizeHandle(
+  props: MillerColumnsResizeHandleProps,
+) {
+  const { handleProps } = useMillerColumnsResizeHandle(props);
+
+  return <div {...handleProps} />;
+}
+
+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, 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.
+ *
+ * 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`.
+ *
+ * @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,
+  ...rest
+}: MillerColumnsPreviewPanelProps) {
+  useMillerColumnsContext();
+
+  return (
+    <div data-miller-columns-preview="" {...rest}>
+      {children}
+    </div>
+  );
+}
+
+MillerColumnsPreviewPanel.displayName = "MillerColumnsPreviewPanel";
+
+type MillerColumnsCompound = typeof MillerColumnsRoot & {
+  Root: typeof MillerColumnsRoot;
+  Column: typeof MillerColumnsColumn;
+  Item: typeof MillerColumnsItem;
+  ItemIndicator: typeof MillerColumnsItemIndicator;
+  ResizeHandle: typeof MillerColumnsResizeHandle;
+  PreviewPanel: typeof MillerColumnsPreviewPanel;
+};
+
+const MillerColumnsCompound: MillerColumnsCompound = Object.assign(
+  MillerColumnsRoot,
+  {
+    Root: MillerColumnsRoot,
+    Column: MillerColumnsColumn,
+    Item: MillerColumnsItem,
+    ItemIndicator: MillerColumnsItemIndicator,
+    ResizeHandle: MillerColumnsResizeHandle,
+    PreviewPanel: MillerColumnsPreviewPanel,
+  },
+);
+
+MillerColumnsCompound.displayName = "MillerColumns";
+
+export { MillerColumnsCompound as MillerColumns };

package/src/MillerColumns/MillerColumnsContext.ts

@@ -0,0 +1,25 @@
+import { createStrictContext } from "../utils";
+
+import type {
+  MillerColumnsContextValue,
+  MillerColumnsColumnContextValue,
+  MillerColumnsItemContextValue,
+} from "./types";
+
+export const [MillerColumnsContext, useMillerColumnsContext] =
+  createStrictContext<MillerColumnsContextValue>(
+    "MillerColumns sub-components must be rendered inside <MillerColumns.Root>.",
+    "MillerColumnsContext",
+  );
+
+export const [MillerColumnsColumnContext, useMillerColumnsColumnContext] =
+  createStrictContext<MillerColumnsColumnContextValue>(
+    "MillerColumns.Item must be rendered inside <MillerColumns.Column>.",
+    "MillerColumnsColumnContext",
+  );
+
+export const [MillerColumnsItemContext, useMillerColumnsItemContext] =
+  createStrictContext<MillerColumnsItemContextValue>(
+    "MillerColumns.ItemIndicator must be rendered inside <MillerColumns.Item>.",
+    "MillerColumnsItemContext",
+  );

package/src/MillerColumns/README.md

@@ -0,0 +1,278 @@
+# MillerColumns
+
+A compound component for the **Miller columns** pattern (also called
+cascading lists or the macOS Finder "column view"): a horizontal strip
+of vertical lists where selecting a node reveals its children in the
+next column to the right.
+
+```tsx
+import { MillerColumns } from "@primitiv-ui/react";
+
+function Node({ node }) {
+  return (
+    <MillerColumns.Item value={node.id}>
+      {node.label}
+      {node.children?.length ? (
+        <>
+          <MillerColumns.ItemIndicator>▸</MillerColumns.ItemIndicator>
+          <MillerColumns.Column>
+            {node.children.map((child) => (
+              <Node key={child.id} node={child} />
+            ))}
+          </MillerColumns.Column>
+        </>
+      ) : null}
+    </MillerColumns.Item>
+  );
+}
+
+<MillerColumns.Root defaultValue={["docs", "guides"]}>
+  <MillerColumns.Column>
+    {tree.map((node) => (
+      <Node key={node.id} node={node} />
+    ))}
+  </MillerColumns.Column>
+</MillerColumns.Root>;
+```
+
+## Authoring model
+
+The tree is authored by **recursive composition** — there is no `data`
+prop. An `Item` becomes a *branch* by nesting a
+`<MillerColumns.Column>` among its children; that nested column lists
+the item's children, each of which is another `Item`. An `Item` with no
+nested column is a *leaf*.
+
+Although child columns are authored nested, every `Column` is
+**portal-projected** into the `Root` strip, so the active columns sit
+side-by-side in a single left-to-right row regardless of how deeply
+they were declared.
+
+A branch's nested column is only **mounted while that branch is
+selected**, so a consumer's recursive `Node` component naturally stops
+recursing at inactive branches — only the columns along the active path
+are ever rendered.
+
+## Sub-components
+
+| Export                       | Role          | Notes                                                                                          |
+| ----------------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
+| `MillerColumns.Root`          | State owner   | Uncontrolled (`defaultValue`) or controlled (`value` + `onValueChange`); renders the strip     |
+| `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.PreviewPanel`  | Preview pane  | A content-agnostic trailing panel; pair with `useMillerColumnsSelection`                        |
+
+## Selection model
+
+The selection is a single **active path** — an array of item ids from
+the root column down to the deepest selected item. Selecting an item at
+depth _d_ truncates the path to _d_ and appends the new id, so every
+column deeper than _d_ closes.
+
+- **Uncontrolled** — pass `defaultValue` (or omit it to start with
+  nothing selected).
+- **Controlled** — pass `value` and `onValueChange` together. The
+  parent owns the path; the component defers every change back through
+  the callback.
+
+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.
+
+## Keyboard interaction
+
+| Key                 | Behaviour                                                              |
+| ------------------- | ---------------------------------------------------------------------- |
+| `ArrowUp` / `ArrowDown` | Move focus within the focused column (wraps, skips disabled items) |
+| `Home` / `End`      | Focus the first / last item of the focused column                      |
+| `Enter` / `Space`   | Select the focused item                                                |
+| `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)                     |
+
+The strip is a single roving-tabindex widget: exactly one item is
+tabbable at a time. The tabstop follows the last-focused item and
+defaults to the deepest selected item, falling back to the first item
+of the root column.
+
+## Auto-scroll
+
+When selecting a branch reveals a new column, the strip scrolls to its
+trailing edge so the newly opened column is brought into view. This
+fires only when a column is *added* — neither the initial render nor
+closing a column scrolls the strip. Scrolling only has a visible
+effect when the strip is itself an overflow container; give
+`[data-miller-columns-strip]` an `overflow-x` for it to take hold.
+
+## ARIA
+
+- The strip 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`.
+
+## Disabled items
+
+Pass `disabled` on an `Item` to render `aria-disabled="true"` and
+`data-disabled`, ignore clicks and activation keys, and skip the item
+during arrow-key navigation. Disabled items remain in the DOM and
+focusable for discovery.
+
+## Resizable columns
+
+Drop a `MillerColumns.ResizeHandle` among a `Column`'s children to make
+that column drag-resizable. The handle renders a
+`<div role="separator" aria-orientation="vertical">`; while it is
+pointer-dragged it drives that column's width as state on the `Root`,
+applied as the column's inline `width`.
+
+```tsx
+<MillerColumns.Column className="column">
+  <MillerColumns.ResizeHandle className="resize-handle" />
+  {items}
+</MillerColumns.Column>
+```
+
+The handle ships with no styles or position — give it a width and pin
+it to the column's trailing edge yourself:
+
+```css
+.column {
+  position: relative;
+}
+.resize-handle {
+  position: absolute;
+  inset-block: 0;
+  inset-inline-end: 0;
+  width: 6px;
+  cursor: col-resize;
+}
+.resize-handle[data-dragging] {
+  /* feedback while a drag is in progress */
+}
+```
+
+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.
+
+## Preview panel
+
+`MillerColumns.PreviewPanel` is a trailing pane — the macOS-Finder
+"preview" column — rendered as the last child of the strip, to the
+right of the columns. It is deliberately **content-agnostic**: the
+component cannot know how to preview an item, so the consumer decides
+what the panel shows. Author it as the last child of `Root`, a sibling
+of the root `Column`:
+
+```tsx
+<MillerColumns.Root>
+  <MillerColumns.Column>{items}</MillerColumns.Column>
+  <MillerColumns.PreviewPanel>
+    <FilePreview />
+  </MillerColumns.PreviewPanel>
+</MillerColumns.Root>
+```
+
+To render content for whatever is selected, read the selection with
+the `useMillerColumnsSelection` hook from any component inside `Root`:
+
+```tsx
+import { useMillerColumnsSelection } from "@primitiv-ui/react";
+
+function FilePreview() {
+  const { path, selectedValue } = useMillerColumnsSelection();
+  if (!selectedValue) {
+    return <p>Nothing selected</p>;
+  }
+  return <Preview id={selectedValue} />;
+}
+```
+
+`useMillerColumnsSelection` returns the active `path` and the deepest
+`selectedValue` (`undefined` when nothing is selected). It works for
+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.
+
+## `asChild` composition
+
+`MillerColumns.Item` accepts `asChild` to render the cell as a
+consumer-supplied element instead of the default `<div>`. All treeitem
+ARIA attributes, event handlers, and the internal ref are merged onto
+the child (child handler runs first, then the component's). A nested
+`<MillerColumns.Column>` is still declared as a sibling of the cell
+element:
+
+```tsx
+<MillerColumns.Item<HTMLAnchorElement> asChild value="docs">
+  <a href="#docs">Docs</a>
+  <MillerColumns.Column>…</MillerColumns.Column>
+</MillerColumns.Item>
+```
+
+A `ref` prop (React 19 ref-as-prop style) is forwarded to the rendered
+element and composed with the library's internal ref.
+
+## Styling hooks
+
+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
+(`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] > *`.
+
+```css
+[data-miller-columns-strip] {
+  display: flex;
+}
+[data-miller-columns-column] {
+  overflow-y: auto;
+}
+[data-miller-columns-column][data-depth="0"] {
+  /* the root column */
+}
+[role="treeitem"][data-state="selected"] {
+  /* the selected item in each column */
+}
+[role="treeitem"][data-has-children] {
+  /* branch items */
+}
+[role="treeitem"][data-disabled] {
+  opacity: 0.5;
+}
+```
+
+| 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` |
+| `ItemIndicator` | `data-state`, `data-has-children`                                           |
+| `ResizeHandle`  | `data-miller-columns-resize-handle`, `data-dragging` (present mid-drag)     |
+| `PreviewPanel`  | `data-miller-columns-preview`                                               |
+
+## Deferred / follow-up work
+
+The following were intentionally left out of the first version and are
+good candidates for later, independent cycles:
+
+1. **Context-menu image preview.** Once a Context Menu component
+   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.