@primitiv-ui/react 0.1.29 → 0.1.31

package/src/MillerColumns/__tests__/MillerColumns.styled-parts.test.tsx

@@ -0,0 +1,143 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Children, type ComponentProps, type ReactNode } from "react";
+
+import { MillerColumns } from "../MillerColumns";
+import { MILLER_COLUMNS_PART } from "../utils";
+
+/**
+ * A stand-in for a styling layer's wrapper — exactly what the registry
+ * `miller-columns` surface renders. `Item` inspects its children *before*
+ * rendering them, so it sees this component, not the `MillerColumns.Column`
+ * it returns.
+ */
+function StyledColumn(props: ComponentProps<typeof MillerColumns.Column>) {
+  return <MillerColumns.Column {...props} />;
+}
+StyledColumn[MILLER_COLUMNS_PART] = "column" as const;
+
+function Tree() {
+  return (
+    <MillerColumns.Root>
+      <MillerColumns.Column>
+        <MillerColumns.Item value="fruit">
+          Fruit
+          <StyledColumn>
+            <MillerColumns.Item value="apple">Apple</MillerColumns.Item>
+          </StyledColumn>
+        </MillerColumns.Item>
+        <MillerColumns.Item value="veg">
+          Veg
+          <StyledColumn>
+            <MillerColumns.Item value="carrot">Carrot</MillerColumns.Item>
+          </StyledColumn>
+        </MillerColumns.Item>
+      </MillerColumns.Column>
+    </MillerColumns.Root>
+  );
+}
+
+describe("MillerColumns — styled wrappers standing in for parts", () => {
+  it("keeps a wrapped child column closed until its branch is selected", async () => {
+    const user = userEvent.setup();
+
+    render(<Tree />);
+
+    // Nothing is selected, so the child column must not be mounted at all.
+    expect(
+      screen.queryByRole("treeitem", { name: "Apple" }),
+    ).not.toBeInTheDocument();
+
+    await user.click(screen.getByRole("treeitem", { name: "Fruit" }));
+
+    expect(screen.getByRole("treeitem", { name: "Apple" })).toBeInTheDocument();
+  });
+
+  it("opens only the selected branch's column, not every sibling's at once", async () => {
+    const user = userEvent.setup();
+
+    render(<Tree />);
+
+    await user.click(screen.getByRole("treeitem", { name: "Fruit" }));
+
+    // Selecting Fruit opens a slot at depth 1. Every unrecognised wrapped
+    // column projects into that slot on sight, so Veg's children ride along.
+    expect(screen.getByRole("treeitem", { name: "Apple" })).toBeInTheDocument();
+    expect(
+      screen.queryByRole("treeitem", { name: "Carrot" }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("treats a wrapped child column as the branch's column, not cell content", () => {
+    render(<Tree />);
+
+    // A branch is a branch because it nests a column — even a wrapped one.
+    expect(screen.getByRole("treeitem", { name: "Fruit" })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+    expect(screen.getByRole("treeitem", { name: "Fruit" })).toHaveAttribute(
+      "data-has-children",
+    );
+  });
+});
+
+/**
+ * The registry surface wraps BOTH parts, and its Item maps over `children` to
+ * wrap bare text in a label span before handing them to the headless. That map
+ * sits between the consumer's JSX and `partitionItemChildren`, so it is the
+ * thing most likely to lose a nested column.
+ */
+function wrapRowTextNodes(children: ReactNode): ReactNode {
+  const mapped = Children.map(children, (child) =>
+    typeof child === "string" || typeof child === "number" ? (
+      <span className="label">{child}</span>
+    ) : (
+      child
+    ),
+  );
+  return Array.isArray(mapped) && mapped.length === 1 ? mapped[0] : mapped;
+}
+
+function StyledItem({
+  children,
+  ...props
+}: ComponentProps<typeof MillerColumns.Item>) {
+  return (
+    <MillerColumns.Item {...props}>
+      {wrapRowTextNodes(children)}
+    </MillerColumns.Item>
+  );
+}
+
+describe("MillerColumns — the registry's own composition", () => {
+  it("opens only the selected branch when Item and Column are both wrapped", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MillerColumns.Root>
+        <MillerColumns.Column>
+          <StyledItem value="fruit">
+            Fruit
+            <StyledColumn>
+              <StyledItem value="apple">Apple</StyledItem>
+            </StyledColumn>
+          </StyledItem>
+          <StyledItem value="veg">
+            Veg
+            <StyledColumn>
+              <StyledItem value="carrot">Carrot</StyledItem>
+            </StyledColumn>
+          </StyledItem>
+        </MillerColumns.Column>
+      </MillerColumns.Root>,
+    );
+
+    await user.click(screen.getByRole("treeitem", { name: "Fruit" }));
+
+    expect(screen.getByRole("treeitem", { name: "Apple" })).toBeInTheDocument();
+    expect(
+      screen.queryByRole("treeitem", { name: "Carrot" }),
+    ).not.toBeInTheDocument();
+  });
+});

package/src/MillerColumns/__tests__/MillerColumns.typeahead.test.tsx

@@ -0,0 +1,104 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { TYPEAHEAD_RESET_MS } from "../constants";
+import { MillerColumns } from "../MillerColumns";
+
+function Tree() {
+  return (
+    <MillerColumns.Root>
+      <MillerColumns.Column>
+        <MillerColumns.Item value="apricot">Apricot</MillerColumns.Item>
+        <MillerColumns.Item value="banana">Banana</MillerColumns.Item>
+        <MillerColumns.Item value="blueberry">Blueberry</MillerColumns.Item>
+        <MillerColumns.Item value="cherry">
+          Cherry
+          <MillerColumns.Column>
+            <MillerColumns.Item value="morello">Morello</MillerColumns.Item>
+            <MillerColumns.Item value="maraschino">
+              Maraschino
+            </MillerColumns.Item>
+          </MillerColumns.Column>
+        </MillerColumns.Item>
+      </MillerColumns.Column>
+    </MillerColumns.Root>
+  );
+}
+
+describe("MillerColumns — typeahead", () => {
+  it("focuses the first item whose label starts with the typed character", async () => {
+    const user = userEvent.setup();
+
+    render(<Tree />);
+    screen.getByRole("treeitem", { name: "Apricot" }).focus();
+
+    await user.keyboard("c");
+
+    expect(screen.getByRole("treeitem", { name: "Cherry" })).toHaveFocus();
+  });
+
+  it("accumulates characters into a prefix query", async () => {
+    const user = userEvent.setup();
+
+    render(<Tree />);
+    screen.getByRole("treeitem", { name: "Apricot" }).focus();
+
+    await user.keyboard("bl");
+
+    expect(screen.getByRole("treeitem", { name: "Blueberry" })).toHaveFocus();
+  });
+
+  it("cycles through matches when the same character repeats", async () => {
+    const user = userEvent.setup();
+
+    render(<Tree />);
+    screen.getByRole("treeitem", { name: "Apricot" }).focus();
+
+    await user.keyboard("b");
+    expect(screen.getByRole("treeitem", { name: "Banana" })).toHaveFocus();
+
+    await user.keyboard("b");
+    expect(screen.getByRole("treeitem", { name: "Blueberry" })).toHaveFocus();
+  });
+
+  it("searches only within the focused column", async () => {
+    const user = userEvent.setup();
+
+    render(<Tree />);
+    await user.click(screen.getByRole("treeitem", { name: "Cherry" }));
+    screen.getByRole("treeitem", { name: "Morello" }).focus();
+
+    // "B" matches Banana and Blueberry, but both are in the parent column.
+    await user.keyboard("b");
+    expect(screen.getByRole("treeitem", { name: "Morello" })).toHaveFocus();
+
+    // Let the query lapse — otherwise the next keys extend it to "bma".
+    await new Promise((resolve) =>
+      setTimeout(resolve, TYPEAHEAD_RESET_MS + 100),
+    );
+
+    await user.keyboard("ma");
+    expect(screen.getByRole("treeitem", { name: "Maraschino" })).toHaveFocus();
+  });
+
+  it("skips disabled items", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MillerColumns.Root>
+        <MillerColumns.Column>
+          <MillerColumns.Item value="a">Apricot</MillerColumns.Item>
+          <MillerColumns.Item value="b1" disabled>
+            Banana
+          </MillerColumns.Item>
+          <MillerColumns.Item value="b2">Blueberry</MillerColumns.Item>
+        </MillerColumns.Column>
+      </MillerColumns.Root>,
+    );
+    screen.getByRole("treeitem", { name: "Apricot" }).focus();
+
+    await user.keyboard("b");
+
+    expect(screen.getByRole("treeitem", { name: "Blueberry" })).toHaveFocus();
+  });
+});

package/src/MillerColumns/constants.ts

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

package/src/MillerColumns/hooks/useMillerColumnsColumn.ts

@@ -7,17 +7,20 @@ import type { MillerColumnsColumnContextValue } from "../types";
 import { useMillerColumnsContext } from "./useMillerColumnsContext";
 
 export function useMillerColumnsColumn() {
-  const { slots, columnWidths } = useMillerColumnsContext();
+  const { slots, columnWidths, getColumnItems } = useMillerColumnsContext();
   const parentColumn = useContext(MillerColumnsColumnContext);
   const depth = parentColumn ? parentColumn.depth + 1 : 0;
 
   const slot = slots.get(depth) ?? null;
   const width = columnWidths.get(depth);
+  // Selecting a childless branch opens a column with nothing in it; the
+  // styling layer needs to know so it can say so rather than show a void.
+  const empty = getColumnItems(depth).length === 0;
 
   const columnContextValue = useMemo<MillerColumnsColumnContextValue>(
     () => ({ depth }),
     [depth],
   );
 
-  return { slot, depth, width, columnContextValue };
+  return { slot, depth, width, empty, columnContextValue };
 }

package/src/MillerColumns/hooks/useMillerColumnsItem.ts

@@ -2,7 +2,7 @@ import {
   FocusEvent,
   KeyboardEvent,
   MouseEvent,
-  useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
 } from "react";
@@ -31,6 +31,7 @@ export function useMillerColumnsItem(
   hasChildren: boolean,
 ) {
   const {
+    dir,
     activePath,
     select,
     registerItem,
@@ -40,18 +41,26 @@ export function useMillerColumnsItem(
     requestColumnFocus,
     activeItem,
     setActiveItem,
+    handleTypeahead,
   } = useMillerColumnsContext();
   const { depth } = useMillerColumnsColumnContext();
 
   const selected = activePath[depth] === value;
+  // The deepest selected item — the one the user actually landed on, as
+  // opposed to the ancestors its path passes through. Nothing else in the
+  // DOM distinguishes the two, and styling them alike loses the depth cue.
+  const terminal = selected && depth === activePath.length - 1;
 
   const itemRef = useRef<HTMLDivElement>(null);
   const composedRef = ref ? composeRefs(itemRef, ref) : itemRef;
 
-  useEffect(() => {
-    registerItem(depth, value, itemRef.current, disabled);
-    return () => registerItem(depth, value, null, disabled);
-  }, [depth, value, disabled, registerItem]);
+  // Registration is a *layout* effect so the resulting state update lands
+  // before paint. As a passive effect, a populated column would paint one
+  // frame with `data-empty` before its items registered.
+  useLayoutEffect(() => {
+    registerItem(depth, value, itemRef.current, disabled, hasChildren);
+    return () => registerItem(depth, value, null, disabled, hasChildren);
+  }, [depth, value, disabled, hasChildren, registerItem]);
 
   const enabledValues = getColumnItems(depth)
     .filter((item) => !item.disabled)
@@ -100,10 +109,15 @@ export function useMillerColumnsItem(
     : depth === 0 &&
       getColumnItems(0).find((item) => !item.disabled)?.value === value;
 
+  // Columns run left-to-right under ltr and right-to-left under rtl, so
+  // the key that steps *into* a child column mirrors with the direction.
+  const stepInKey = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+  const stepOutKey = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+
   function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
     onKeyDown?.(event);
 
-    if (event.key === "ArrowRight") {
+    if (event.key === stepInKey) {
       if (!hasChildren || disabled) {
         return;
       }
@@ -117,7 +131,7 @@ export function useMillerColumnsItem(
       return;
     }
 
-    if (event.key === "ArrowLeft") {
+    if (event.key === stepOutKey) {
       if (depth === 0) {
         return;
       }
@@ -129,6 +143,13 @@ export function useMillerColumnsItem(
     }
 
     rovingKeyDown(event);
+
+    // The keymap gets first refusal — it calls preventDefault on every key
+    // it consumes, so only a still-unhandled printable character reaches
+    // typeahead (Space activates, and never falls through).
+    if (!event.defaultPrevented) {
+      handleTypeahead(event);
+    }
   }
 
   const itemProps = {
@@ -139,6 +160,7 @@ export function useMillerColumnsItem(
     "aria-level": depth + 1,
     ...(hasChildren ? { "aria-expanded": selected } : {}),
     "data-state": selected ? "selected" : "unselected",
+    ...(terminal ? { "data-terminal": "" } : {}),
     "data-depth": depth,
     ...(hasChildren ? { "data-has-children": "" } : {}),
     ...(disabled ? { "aria-disabled": true, "data-disabled": "" } : {}),

package/src/MillerColumns/hooks/useMillerColumnsResizeHandle.ts

@@ -1,4 +1,11 @@
-import { PointerEvent, useEffect, useState } from "react";
+import {
+  KeyboardEvent,
+  PointerEvent,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
 
 import type { MillerColumnsResizeHandleProps } from "../types";
 
@@ -9,12 +16,43 @@ type DragState = { startX: number; startWidth: number };
 
 export function useMillerColumnsResizeHandle({
   onPointerDown,
+  onKeyDown,
+  minWidth = 0,
+  maxWidth = Number.POSITIVE_INFINITY,
+  step = 10,
   ...rest
 }: MillerColumnsResizeHandleProps) {
-  const { columnWidths, setColumnWidth } = useMillerColumnsContext();
+  const { columnWidths, setColumnWidth, dir } = useMillerColumnsContext();
   const { depth } = useMillerColumnsColumnContext();
 
+  const handleRef = useRef<HTMLDivElement>(null);
   const [drag, setDrag] = useState<DragState | null>(null);
+  // The column's rendered width before anything resizes it. Tracked so
+  // `aria-valuenow` is truthful from the first render — a splitter whose
+  // value only appears after the first drag announces nothing until then.
+  const [measured, setMeasured] = useState(0);
+
+  const clamp = (width: number) =>
+    Math.min(maxWidth, Math.max(minWidth, width));
+
+  // The resized width wins; otherwise the column is still sized by CSS.
+  const width = columnWidths.get(depth) ?? measured;
+
+  useLayoutEffect(() => {
+    const column = handleRef.current?.closest<HTMLElement>(
+      "[data-miller-columns-column]",
+    );
+    /* c8 ignore next 3 -- the handle only renders inside a Column, which
+       context already enforces, so the ancestor is always present. */
+    if (!column) {
+      return;
+    }
+    const measure = () => setMeasured(column.getBoundingClientRect().width);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(column);
+    return () => observer.disconnect();
+  }, []);
 
   // A drag is tracked on `window`, not the handle, so the pointer can
   // travel anywhere once it is down; the listeners live only for the
@@ -27,13 +65,8 @@ export function useMillerColumnsResizeHandle({
     const activeDrag = drag;
 
     function handleMove(event: globalThis.PointerEvent) {
-      setColumnWidth(
-        depth,
-        Math.max(
-          0,
-          activeDrag.startWidth + event.clientX - activeDrag.startX,
-        ),
-      );
+      const next = activeDrag.startWidth + event.clientX - activeDrag.startX;
+      setColumnWidth(depth, Math.min(maxWidth, Math.max(minWidth, next)));
     }
 
     function endDrag() {
@@ -48,7 +81,7 @@ export function useMillerColumnsResizeHandle({
       window.removeEventListener("pointerup", endDrag);
       window.removeEventListener("pointercancel", endDrag);
     };
-  }, [drag, depth, setColumnWidth]);
+  }, [drag, depth, setColumnWidth, minWidth, maxWidth]);
 
   function handlePointerDown(event: PointerEvent<HTMLDivElement>) {
     onPointerDown?.(event);
@@ -63,13 +96,50 @@ export function useMillerColumnsResizeHandle({
     setDrag({ startX: event.clientX, startWidth });
   }
 
+  // The column extends towards the inline-end edge, which is leftwards
+  // under rtl — so the key that widens it mirrors with the direction.
+  const growKey = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+  const shrinkKey = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    onKeyDown?.(event);
+
+    const next = (() => {
+      switch (event.key) {
+        case growKey:
+          return width + step;
+        case shrinkKey:
+          return width - step;
+        case "Home":
+          return minWidth;
+        case "End":
+          return maxWidth;
+        default:
+          return null;
+      }
+    })();
+
+    if (next === null || !Number.isFinite(next)) {
+      return;
+    }
+
+    event.preventDefault();
+    setColumnWidth(depth, clamp(next));
+  }
+
   return {
     handleProps: {
+      ref: handleRef,
       role: "separator" as const,
       "aria-orientation": "vertical" as const,
+      tabIndex: 0,
+      "aria-valuenow": Math.round(width),
+      "aria-valuemin": minWidth,
+      ...(Number.isFinite(maxWidth) ? { "aria-valuemax": maxWidth } : {}),
       "data-miller-columns-resize-handle": "",
       ...(drag ? { "data-dragging": "" } : {}),
       onPointerDown: handlePointerDown,
+      onKeyDown: handleKeyDown,
       ...rest,
     },
   };

package/src/MillerColumns/index.ts

@@ -1,3 +1,7 @@
 export * from "./MillerColumns";
+export {
+  MILLER_COLUMNS_PART,
+  type MillerColumnsPartName,
+} from "./utils";
 export { useMillerColumnsSelection } from "./useMillerColumnsSelection";
 export * from "./types";

package/src/MillerColumns/types.ts

@@ -1,13 +1,24 @@
-import { ComponentProps, ReactNode, Ref } from "react";
+import { ComponentProps, KeyboardEvent, ReactNode, Ref } from "react";
+
+import type { Direction } from "../DirectionProvider/types";
 
 /**
  * Shared base for both {@link MillerColumnsRootProps} variants — the native
- * `<div>` attributes (minus `ref`, which the strip owns internally).
+ * `<div>` attributes (minus `ref`, which the strip owns internally, and
+ * `dir`, narrowed below to the {@link Direction} union).
  */
 export type MillerColumnsRootBaseProps = Omit<
   ComponentProps<"div">,
-  "ref" | "defaultValue"
+  "ref" | "defaultValue" | "dir"
 > & {
+  /**
+   * Reading direction. Under `"rtl"` the horizontal arrow pair is
+   * mirrored — ArrowLeft steps *into* a branch's child column and
+   * ArrowRight walks back out — so navigation follows the visual order.
+   * Inherited from a `DirectionProvider` ancestor when omitted.
+   * @default "ltr"
+   */
+  dir?: Direction;
   /**
    * The strip's tree, authored recursively: root
    * {@link MillerColumnsColumnProps | Column(s)} whose branch
@@ -65,8 +76,10 @@ export type MillerColumnsRootProps =
  */
 export type MillerColumnsColumnProps = ComponentProps<"div"> & {
   /** The column's {@link MillerColumnsItemProps | Items} and, optionally, a
-   * {@link MillerColumnsResizeHandleProps | ResizeHandle}. */
-  children: ReactNode;
+   * {@link MillerColumnsResizeHandleProps | ResizeHandle}. Optional: a
+   * childless branch legitimately opens an empty column, which carries
+   * `data-empty` for the styling layer. */
+  children?: ReactNode;
 };
 
 /**
@@ -118,7 +131,26 @@ export type MillerColumnsItemIndicatorProps = ComponentProps<"span"> & {
  * Props for {@link MillerColumnsResizeHandle | `MillerColumns.ResizeHandle`},
  * the drag-to-resize separator for its containing column.
  */
-export type MillerColumnsResizeHandleProps = ComponentProps<"div">;
+export type MillerColumnsResizeHandleProps = ComponentProps<"div"> & {
+  /**
+   * Smallest width the column can be dragged or stepped to, in pixels.
+   * Also published as `aria-valuemin`.
+   * @default 0
+   */
+  minWidth?: number;
+  /**
+   * Largest width the column can be dragged or stepped to, in pixels.
+   * Published as `aria-valuemax` when finite; left unbounded by default,
+   * in which case the attribute is omitted.
+   * @default Infinity
+   */
+  maxWidth?: number;
+  /**
+   * Pixels moved per arrow-key press.
+   * @default 10
+   */
+  step?: number;
+};
 
 /**
  * Props for {@link MillerColumnsPreviewPanel | `MillerColumns.PreviewPanel`},
@@ -128,6 +160,14 @@ export type MillerColumnsPreviewPanelProps = ComponentProps<"div"> & {
   /** The preview content for the current selection (typically driven by
    * {@link useMillerColumnsSelection}). */
   children?: ReactNode;
+  /**
+   * Keep the panel mounted regardless of the selection, instead of following
+   * Finder's rule (a preview only where a selected *leaf* would open a child
+   * column). Use it for a persistent inspector, or to animate the panel in
+   * and out.
+   * @default false
+   */
+  forceMount?: boolean;
 };
 
 /** The current selection, as returned by `useMillerColumnsSelection`. */
@@ -156,6 +196,8 @@ export type MillerColumnsItemAddress = {
 
 /** Value shared through the root MillerColumns context. */
 export type MillerColumnsContextValue = {
+  /** The resolved reading direction — the `dir` prop, else the inherited one. */
+  dir: Direction;
   /** Portal slots keyed by column depth. */
   slots: Map<number, HTMLElement>;
   /** Per-depth column widths set via the resize handle. */
@@ -172,9 +214,15 @@ export type MillerColumnsContextValue = {
     value: string,
     element: HTMLElement | null,
     disabled: boolean,
+    hasChildren: boolean,
   ) => void;
+  /** Whether the deepest selected item is a leaf — Finder's rule for whether a
+   * preview occupies the slot after it. `false` when nothing is selected. */
+  terminalIsLeaf: boolean;
   /** Get the registered items for a column. */
   getColumnItems: (depth: number) => MillerColumnsItemMeta[];
+  /** Read a registered item's rendered cell text, for typeahead matching. */
+  getItemLabel: (depth: number, value: string) => string;
   /** Move focus to the given item. */
   focusItem: (depth: number, value: string) => void;
   /** Focus the first item in a column; returns whether one was focused. */
@@ -185,6 +233,8 @@ export type MillerColumnsContextValue = {
   activeItem: MillerColumnsItemAddress | null;
   /** Set the active (focused) item. */
   setActiveItem: (item: MillerColumnsItemAddress) => void;
+  /** Printable-character typeahead, scoped to the focused item's column. */
+  handleTypeahead: (event: KeyboardEvent<HTMLElement>) => void;
 };
 
 /** Value shared through a column's context. */