@primitiv-ui/react 0.1.0

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

@@ -0,0 +1,54 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { MillerColumns } from "../MillerColumns";
+import { useMillerColumnsSelection } from "../useMillerColumnsSelection";
+
+function SelectionProbe() {
+  const { path, selectedValue } = useMillerColumnsSelection();
+
+  return (
+    <div data-testid="probe" data-selected={selectedValue}>
+      {path.join("/")}
+    </div>
+  );
+}
+
+describe("MillerColumns — useMillerColumnsSelection", () => {
+  it("exposes the active path and the deepest selected value", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MillerColumns.Root>
+        <MillerColumns.Column>
+          <MillerColumns.Item value="fruit">
+            Fruit
+            <MillerColumns.Column>
+              <MillerColumns.Item value="apple">Apple</MillerColumns.Item>
+            </MillerColumns.Column>
+          </MillerColumns.Item>
+        </MillerColumns.Column>
+        <SelectionProbe />
+      </MillerColumns.Root>,
+    );
+
+    const probe = screen.getByTestId("probe");
+
+    expect(probe).toHaveTextContent("");
+    expect(probe).not.toHaveAttribute("data-selected");
+
+    await user.click(screen.getByRole("treeitem", { name: "Fruit" }));
+
+    expect(probe).toHaveTextContent("fruit");
+    expect(probe).toHaveAttribute("data-selected", "fruit");
+
+    await user.click(screen.getByRole("treeitem", { name: "Apple" }));
+
+    expect(probe).toHaveTextContent("fruit/apple");
+    expect(probe).toHaveAttribute("data-selected", "apple");
+  });
+
+  it("throws when used outside Root", () => {
+    expect(() => render(<SelectionProbe />)).toThrow("<MillerColumns.Root>");
+  });
+});

package/src/MillerColumns/__tests__/MillerColumns.uncontrolled-state.test.tsx

@@ -0,0 +1,70 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { MillerColumns } from "../MillerColumns";
+
+describe("MillerColumns — uncontrolled state", () => {
+  it("selects an item when it is clicked", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MillerColumns.Root>
+        <MillerColumns.Column>
+          <MillerColumns.Item value="a">A</MillerColumns.Item>
+          <MillerColumns.Item value="b">B</MillerColumns.Item>
+        </MillerColumns.Column>
+      </MillerColumns.Root>,
+    );
+
+    const itemA = screen.getByRole("treeitem", { name: "A" });
+    expect(itemA).toHaveAttribute("aria-selected", "false");
+
+    await user.click(itemA);
+
+    expect(itemA).toHaveAttribute("aria-selected", "true");
+  });
+
+  it("starts with the item named by defaultValue selected", () => {
+    render(
+      <MillerColumns.Root defaultValue={["b"]}>
+        <MillerColumns.Column>
+          <MillerColumns.Item value="a">A</MillerColumns.Item>
+          <MillerColumns.Item value="b">B</MillerColumns.Item>
+        </MillerColumns.Column>
+      </MillerColumns.Root>,
+    );
+
+    expect(screen.getByRole("treeitem", { name: "B" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    expect(screen.getByRole("treeitem", { name: "A" })).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+  });
+
+  it("moving the selection within a column deselects the previous item", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MillerColumns.Root defaultValue={["a"]}>
+        <MillerColumns.Column>
+          <MillerColumns.Item value="a">A</MillerColumns.Item>
+          <MillerColumns.Item value="b">B</MillerColumns.Item>
+        </MillerColumns.Column>
+      </MillerColumns.Root>,
+    );
+
+    await user.click(screen.getByRole("treeitem", { name: "B" }));
+
+    expect(screen.getByRole("treeitem", { name: "A" })).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+    expect(screen.getByRole("treeitem", { name: "B" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+});

package/src/MillerColumns/hooks/index.ts

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

package/src/MillerColumns/hooks/useMillerColumnsColumn.ts

@@ -0,0 +1,23 @@
+import { useContext, useMemo } from "react";
+
+import { MillerColumnsColumnContext } from "../MillerColumnsContext";
+
+import type { MillerColumnsColumnContextValue } from "../types";
+
+import { useMillerColumnsContext } from "./useMillerColumnsContext";
+
+export function useMillerColumnsColumn() {
+  const { slots, columnWidths } = useMillerColumnsContext();
+  const parentColumn = useContext(MillerColumnsColumnContext);
+  const depth = parentColumn ? parentColumn.depth + 1 : 0;
+
+  const slot = slots.get(depth) ?? null;
+  const width = columnWidths.get(depth);
+
+  const columnContextValue = useMemo<MillerColumnsColumnContextValue>(
+    () => ({ depth }),
+    [depth],
+  );
+
+  return { slot, depth, width, columnContextValue };
+}

package/src/MillerColumns/hooks/useMillerColumnsColumnContext.ts

@@ -0,0 +1 @@
+export { useMillerColumnsColumnContext } from "../MillerColumnsContext";

package/src/MillerColumns/hooks/useMillerColumnsContext.ts

@@ -0,0 +1 @@
+export { useMillerColumnsContext } from "../MillerColumnsContext";

package/src/MillerColumns/hooks/useMillerColumnsItem.ts

@@ -0,0 +1,157 @@
+import {
+  FocusEvent,
+  KeyboardEvent,
+  MouseEvent,
+  useEffect,
+  useMemo,
+  useRef,
+} from "react";
+
+import { useRovingTabindex } from "../../hooks";
+import { composeRefs } from "../../Slot";
+
+import type {
+  MillerColumnsItemContextValue,
+  MillerColumnsItemProps,
+} from "../types";
+
+import { useMillerColumnsContext } from "./useMillerColumnsContext";
+import { useMillerColumnsColumnContext } from "./useMillerColumnsColumnContext";
+
+export function useMillerColumnsItem(
+  {
+    value,
+    ref,
+    onClick,
+    onKeyDown,
+    onFocus,
+    disabled = false,
+    ...rest
+  }: Omit<MillerColumnsItemProps, "children">,
+  hasChildren: boolean,
+) {
+  const {
+    activePath,
+    select,
+    registerItem,
+    getColumnItems,
+    focusItem,
+    focusFirstInColumn,
+    requestColumnFocus,
+    activeItem,
+    setActiveItem,
+  } = useMillerColumnsContext();
+  const { depth } = useMillerColumnsColumnContext();
+
+  const selected = activePath[depth] === value;
+
+  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]);
+
+  const enabledValues = getColumnItems(depth)
+    .filter((item) => !item.disabled)
+    .map((item) => item.value);
+
+  const { handleKeyDown: rovingKeyDown } = useRovingTabindex<string>({
+    orientation: "vertical",
+    navigable: enabledValues,
+    currentKey: value,
+    includeHomeEnd: true,
+    includeActivate: true,
+    onNavigate: (target, action) => {
+      if (action === "activate") {
+        if (!disabled) {
+          select(depth, value);
+        }
+        return;
+      }
+      focusItem(depth, target);
+    },
+  });
+
+  function handleClick(event: MouseEvent<HTMLDivElement>) {
+    if (disabled) {
+      return;
+    }
+    onClick?.(event);
+    select(depth, value);
+  }
+
+  function handleFocus(event: FocusEvent<HTMLDivElement>) {
+    onFocus?.(event);
+    setActiveItem({ depth, value });
+  }
+
+  // Exactly one item in the whole tree is the Tab stop. It follows the
+  // last-focused item; before any focus it defaults to the deepest
+  // selected item, falling back to the first enabled root item.
+  const tabStop =
+    activeItem ??
+    (activePath.length > 0
+      ? { depth: activePath.length - 1, value: activePath[activePath.length - 1] }
+      : null);
+  const isTabStop = tabStop
+    ? tabStop.depth === depth && tabStop.value === value
+    : depth === 0 &&
+      getColumnItems(0).find((item) => !item.disabled)?.value === value;
+
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    onKeyDown?.(event);
+
+    if (event.key === "ArrowRight") {
+      if (!hasChildren || disabled) {
+        return;
+      }
+      event.preventDefault();
+      if (selected) {
+        focusFirstInColumn(depth + 1);
+      } else {
+        requestColumnFocus(depth + 1);
+        select(depth, value);
+      }
+      return;
+    }
+
+    if (event.key === "ArrowLeft") {
+      if (depth === 0) {
+        return;
+      }
+      event.preventDefault();
+      // A column at depth > 0 exists only because its parent item is
+      // selected, so activePath[depth - 1] is always defined here.
+      focusItem(depth - 1, activePath[depth - 1]);
+      return;
+    }
+
+    rovingKeyDown(event);
+  }
+
+  const itemProps = {
+    ref: composedRef,
+    role: "treeitem",
+    tabIndex: isTabStop ? 0 : -1,
+    "aria-selected": selected,
+    "aria-level": depth + 1,
+    ...(hasChildren ? { "aria-expanded": selected } : {}),
+    "data-state": selected ? "selected" : "unselected",
+    "data-depth": depth,
+    ...(hasChildren ? { "data-has-children": "" } : {}),
+    ...(disabled ? { "aria-disabled": true, "data-disabled": "" } : {}),
+    onClick: handleClick,
+    onKeyDown: handleKeyDown,
+    onFocus: handleFocus,
+    ...rest,
+  };
+
+  const itemContextValue = useMemo<MillerColumnsItemContextValue>(
+    () => ({ selected, hasChildren }),
+    [selected, hasChildren],
+  );
+
+  return { itemProps, selected, itemContextValue };
+}

package/src/MillerColumns/hooks/useMillerColumnsItemContext.ts

@@ -0,0 +1 @@
+export { useMillerColumnsItemContext } from "../MillerColumnsContext";

package/src/MillerColumns/hooks/useMillerColumnsResizeHandle.ts

@@ -0,0 +1,76 @@
+import { PointerEvent, useEffect, useState } from "react";
+
+import type { MillerColumnsResizeHandleProps } from "../types";
+
+import { useMillerColumnsContext } from "./useMillerColumnsContext";
+import { useMillerColumnsColumnContext } from "./useMillerColumnsColumnContext";
+
+type DragState = { startX: number; startWidth: number };
+
+export function useMillerColumnsResizeHandle({
+  onPointerDown,
+  ...rest
+}: MillerColumnsResizeHandleProps) {
+  const { columnWidths, setColumnWidth } = useMillerColumnsContext();
+  const { depth } = useMillerColumnsColumnContext();
+
+  const [drag, setDrag] = useState<DragState | null>(null);
+
+  // 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
+  // lifetime of the drag.
+  useEffect(() => {
+    if (!drag) {
+      return;
+    }
+
+    const activeDrag = drag;
+
+    function handleMove(event: globalThis.PointerEvent) {
+      setColumnWidth(
+        depth,
+        Math.max(
+          0,
+          activeDrag.startWidth + event.clientX - activeDrag.startX,
+        ),
+      );
+    }
+
+    function endDrag() {
+      setDrag(null);
+    }
+
+    window.addEventListener("pointermove", handleMove);
+    window.addEventListener("pointerup", endDrag);
+    window.addEventListener("pointercancel", endDrag);
+    return () => {
+      window.removeEventListener("pointermove", handleMove);
+      window.removeEventListener("pointerup", endDrag);
+      window.removeEventListener("pointercancel", endDrag);
+    };
+  }, [drag, depth, setColumnWidth]);
+
+  function handlePointerDown(event: PointerEvent<HTMLDivElement>) {
+    onPointerDown?.(event);
+    // The handle only renders inside a Column (enforced by context), so
+    // its column ancestor is always present in the DOM. Once a column
+    // has been resized its width is known; before that, measure it.
+    const column = event.currentTarget.closest<HTMLElement>(
+      "[data-miller-columns-column]",
+    )!;
+    const startWidth =
+      columnWidths.get(depth) ?? column.getBoundingClientRect().width;
+    setDrag({ startX: event.clientX, startWidth });
+  }
+
+  return {
+    handleProps: {
+      role: "separator" as const,
+      "aria-orientation": "vertical" as const,
+      "data-miller-columns-resize-handle": "",
+      ...(drag ? { "data-dragging": "" } : {}),
+      onPointerDown: handlePointerDown,
+      ...rest,
+    },
+  };
+}

package/src/MillerColumns/index.ts

@@ -0,0 +1,3 @@
+export * from "./MillerColumns";
+export { useMillerColumnsSelection } from "./useMillerColumnsSelection";
+export type { MillerColumnsSelection } from "./types";

package/src/MillerColumns/types.ts

@@ -0,0 +1,93 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+type MillerColumnsRootBaseProps = Omit<ComponentProps<"div">, "ref"> & {
+  children: ReactNode;
+};
+
+type MillerColumnsRootUncontrolledProps = MillerColumnsRootBaseProps & {
+  defaultValue?: string[];
+  value?: never;
+  onValueChange?: never;
+};
+
+type MillerColumnsRootControlledProps = MillerColumnsRootBaseProps & {
+  defaultValue?: never;
+  value: string[];
+  onValueChange: (path: string[]) => void;
+};
+
+export type MillerColumnsRootProps =
+  | MillerColumnsRootUncontrolledProps
+  | MillerColumnsRootControlledProps;
+
+export type MillerColumnsColumnProps = ComponentProps<"div"> & {
+  children: ReactNode;
+};
+
+export type MillerColumnsItemProps<
+  T extends HTMLElement = HTMLDivElement,
+> = Omit<ComponentProps<"div">, "ref"> & {
+  value: string;
+  disabled?: boolean;
+  asChild?: boolean;
+  children: ReactNode;
+  /** Ref to the rendered element. Defaults to `HTMLDivElement`; when using
+   * `asChild`, specify the child's element type. */
+  ref?: Ref<T>;
+};
+
+export type MillerColumnsItemIndicatorProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+};
+
+export type MillerColumnsResizeHandleProps = ComponentProps<"div">;
+
+export type MillerColumnsPreviewPanelProps = ComponentProps<"div"> & {
+  children?: ReactNode;
+};
+
+export type MillerColumnsSelection = {
+  /** The full active path — selected item ids, root column first. */
+  path: string[];
+  /** The deepest selected item id, or `undefined` when nothing is selected. */
+  selectedValue: string | undefined;
+};
+
+export type MillerColumnsItemMeta = {
+  value: string;
+  disabled: boolean;
+};
+
+export type MillerColumnsItemAddress = {
+  depth: number;
+  value: string;
+};
+
+export type MillerColumnsContextValue = {
+  slots: Map<number, HTMLElement>;
+  columnWidths: Map<number, number>;
+  setColumnWidth: (depth: number, width: number) => void;
+  activePath: string[];
+  select: (depth: number, value: string) => void;
+  registerItem: (
+    depth: number,
+    value: string,
+    element: HTMLElement | null,
+    disabled: boolean,
+  ) => void;
+  getColumnItems: (depth: number) => MillerColumnsItemMeta[];
+  focusItem: (depth: number, value: string) => void;
+  focusFirstInColumn: (depth: number) => boolean;
+  requestColumnFocus: (depth: number) => void;
+  activeItem: MillerColumnsItemAddress | null;
+  setActiveItem: (item: MillerColumnsItemAddress) => void;
+};
+
+export type MillerColumnsColumnContextValue = {
+  depth: number;
+};
+
+export type MillerColumnsItemContextValue = {
+  selected: boolean;
+  hasChildren: boolean;
+};

package/src/MillerColumns/useMillerColumnsSelection.ts

@@ -0,0 +1,31 @@
+import { useMillerColumnsContext } from "./hooks";
+
+import type { MillerColumnsSelection } from "./types";
+
+/**
+ * Reads the current MillerColumns selection — the active path and the
+ * deepest selected item id.
+ *
+ * Intended for consumer content rendered inside a `MillerColumns.Root`
+ * (typically within a `MillerColumns.PreviewPanel`) that needs to know
+ * what is selected without owning the selection state itself. Works for
+ * both controlled and uncontrolled roots.
+ *
+ * Throws when called outside a `MillerColumns.Root`.
+ *
+ * @example
+ * ```tsx
+ * function FilePreview() {
+ *   const { selectedValue } = useMillerColumnsSelection();
+ *   return selectedValue ? <Preview id={selectedValue} /> : null;
+ * }
+ * ```
+ */
+export function useMillerColumnsSelection(): MillerColumnsSelection {
+  const { activePath } = useMillerColumnsContext();
+
+  return {
+    path: activePath,
+    selectedValue: activePath.at(-1),
+  };
+}

package/src/MillerColumns/utils.ts

@@ -0,0 +1,75 @@
+import {
+  Children,
+  cloneElement,
+  Fragment,
+  isValidElement,
+  ReactElement,
+  ReactNode,
+} from "react";
+
+import { MillerColumnsColumn } from "./MillerColumns";
+
+/**
+ * Produces the next active path when an item at `depth` with id `value`
+ * is selected: keeps the columns shallower than `depth` untouched,
+ * appends `value`, and drops everything deeper (those columns close).
+ */
+export function selectAtDepth(
+  path: string[],
+  depth: number,
+  value: string,
+): string[] {
+  return [...path.slice(0, depth), value];
+}
+
+/**
+ * Whether `node` is a `MillerColumns.Column` element — the identity
+ * check used to separate an Item's cell content from its child column.
+ */
+export function isColumnElement(node: ReactNode): node is ReactElement {
+  return isValidElement(node) && node.type === MillerColumnsColumn;
+}
+
+/**
+ * Splits an `Item`'s children into its cell content and its single
+ * optional nested `<MillerColumns.Column>`.
+ *
+ * The child column is matched however deeply it is wrapped in
+ * fragments, since `Children.toArray` does not descend into fragments —
+ * so `{cond ? <><Indicator/><Column/></> : null}` is partitioned the
+ * same as a bare `<Column/>`. Cell entries are re-keyed because
+ * unwrapping fragments can collide the keys `Children.toArray` assigns.
+ */
+export function partitionItemChildren(children: ReactNode): {
+  cell: ReactNode[];
+  column: ReactElement | null;
+} {
+  const cell: ReactNode[] = [];
+  let column: ReactElement | null = null;
+
+  const visit = (nodes: ReactNode): void => {
+    for (const child of Children.toArray(nodes)) {
+      if (isColumnElement(child)) {
+        if (column !== null) {
+          throw new Error(
+            "A MillerColumns.Item may contain at most one nested <MillerColumns.Column>.",
+          );
+        }
+        column = child;
+      } else if (isValidElement(child) && child.type === Fragment) {
+        visit((child.props as { children?: ReactNode }).children);
+      } else {
+        cell.push(child);
+      }
+    }
+  };
+
+  visit(children);
+
+  return {
+    cell: cell.map((node, index) =>
+      isValidElement(node) ? cloneElement(node, { key: `mc-${index}` }) : node,
+    ),
+    column,
+  };
+}