@primitiv-ui/react 0.1.0

package/src/Tree/hooks/useTreePath.ts

@@ -0,0 +1,68 @@
+import { useTreeContext } from "../TreeContext";
+
+import type { TreePathSegment } from "../types";
+
+/**
+ * Returns the root-to-leaf ancestor chain of a tree value as an array
+ * of {@link TreePathSegment}s, or an empty array if the value has
+ * never been registered in the tree.
+ *
+ * Must be called from a component rendered inside `Tree.Root`.
+ *
+ * The segments are ordered **root → leaf** so the last entry is the
+ * queried value itself. Each segment exposes its `label` (the `label`
+ * prop passed to `Tree.Item` / `Tree.Branch`, or `null` when omitted),
+ * `isBranch`, `disabled` and `depth` — enough to render breadcrumbs,
+ * outline trails, or location indicators without a parallel data
+ * lookup.
+ *
+ * Paths survive a branch collapsing without `forceMount`: the tree
+ * keeps a durable copy of every node's metadata so ancestry remains
+ * resolvable even after descendants unmount. A value never mounted
+ * (e.g. a pre-selected item whose branch has not yet opened) returns
+ * an empty array.
+ *
+ * @example
+ * ```tsx
+ * function CurrentPath({ value }: { value: string }) {
+ *   const path = useTreePath(value);
+ *   return <>{path.map((s) => s.label ?? s.value).join(" / ")}</>;
+ * }
+ * ```
+ */
+export function useTreePath(value: string): TreePathSegment[] {
+  const { getPath } = useTreeContext();
+  return getPath(value);
+}
+
+/**
+ * Returns one path per currently-selected value, in selection order.
+ * In single-selection mode the array has zero or one entry; in
+ * multiple-selection mode it has one entry per selected value.
+ *
+ * Each inner array is the same shape as the return of
+ * {@link useTreePath} — root → leaf segments with labels carried from
+ * the `label` prop.
+ *
+ * Used by `Tree.SelectionPath` for its default rendering, and
+ * available directly for fully-custom breadcrumb UIs.
+ *
+ * @example
+ * ```tsx
+ * function Crumbs() {
+ *   const paths = useTreeSelectionPaths();
+ *   if (paths.length === 0) return <span>Nothing selected</span>;
+ *   return (
+ *     <ul>
+ *       {paths.map((path, i) => (
+ *         <li key={i}>{path.map((s) => s.label ?? s.value).join(" / ")}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useTreeSelectionPaths(): TreePathSegment[][] {
+  const { selectedOrder, getPath } = useTreeContext();
+  return selectedOrder.map((value) => getPath(value));
+}

package/src/Tree/hooks/useTreeRoot.ts

@@ -0,0 +1,279 @@
+import { useCallback, useId, useRef, useState } from "react";
+
+import { useCollection, useControllableState } from "../../hooks";
+
+import type {
+  SelectionMode,
+  TreeContextValue,
+  TreeNodeMeta,
+  TreePathSegment,
+  TreeSelectModifiers,
+} from "../types";
+
+/** Defensive cap to short-circuit a cycle in `parentValue` pointers. */
+const MAX_PATH_DEPTH = 64;
+
+export type UseTreeRootOptions = {
+  expandedValues: string[] | undefined;
+  defaultExpandedValues: string[] | undefined;
+  onExpandedChange: ((values: string[]) => void) | undefined;
+  selectionMode: SelectionMode;
+  selectedValue: string | null | undefined;
+  defaultSelectedValue: string | null | undefined;
+  onSelectedValueChange: ((value: string | null) => void) | undefined;
+  selectedValues: string[] | undefined;
+  defaultSelectedValues: string[] | undefined;
+  onSelectedValuesChange: ((values: string[]) => void) | undefined;
+};
+
+function singleToArray(value: string | null | undefined): string[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return value === null ? [] : [value];
+}
+
+/**
+ * Owns the Tree's expansion and selection state, the item collection
+ * used to compute the visible DFS order, and the anchor that pins
+ * Shift+click range selection.
+ */
+export function useTreeRoot(options: UseTreeRootOptions): TreeContextValue {
+  const rootId = useId();
+
+  const [expandedValues, setExpandedValues] = useControllableState<string[]>(
+    options.expandedValues,
+    options.defaultExpandedValues ?? [],
+    options.onExpandedChange,
+  );
+
+  const normalisedSelectedValues =
+    options.selectionMode === "multiple"
+      ? options.selectedValues
+      : singleToArray(options.selectedValue);
+
+  const normalisedDefaultSelectedValues =
+    options.selectionMode === "multiple"
+      ? (options.defaultSelectedValues ?? [])
+      : (singleToArray(options.defaultSelectedValue) ?? []);
+
+  const handleSelectedValuesChange = useCallback(
+    (next: string[]) => {
+      if (options.selectionMode === "multiple") {
+        options.onSelectedValuesChange?.(next);
+      } else {
+        options.onSelectedValueChange?.(next[0]!);
+      }
+    },
+    [
+      options.selectionMode,
+      options.onSelectedValueChange,
+      options.onSelectedValuesChange,
+    ],
+  );
+
+  const [selectedValues, setSelectedValues] = useControllableState<string[]>(
+    normalisedSelectedValues,
+    normalisedDefaultSelectedValues,
+    handleSelectedValuesChange,
+  );
+
+  const {
+    register: registerCollectionNode,
+    itemsRef,
+    keys,
+  } = useCollection<string, TreeNodeMeta>();
+
+  // Durable copy of every node meta ever registered. Unlike the
+  // collection above (which deletes on unmount so visible-order /
+  // focus reflect mounted state) this map keeps the last-seen entry
+  // for each value so `getPath` resolves ancestry even when an
+  // ancestor branch has collapsed without `forceMount` and its
+  // descendants have unmounted.
+  const pathMetaRef = useRef<Map<string, TreeNodeMeta>>(new Map());
+  const [pathMetaVersion, setPathMetaVersion] = useState(0);
+
+  const registerNode = useCallback(
+    (value: string, meta: TreeNodeMeta | null) => {
+      if (meta !== null) {
+        pathMetaRef.current.set(value, meta);
+        setPathMetaVersion((current) => current + 1);
+      }
+      registerCollectionNode(value, meta);
+    },
+    [registerCollectionNode],
+  );
+
+  const getPath = useCallback(
+    (value: string): TreePathSegment[] => {
+      const segments: TreePathSegment[] = [];
+      let cursor: string | null = value;
+      let hops = 0;
+      while (cursor !== null && hops < MAX_PATH_DEPTH) {
+        const meta = pathMetaRef.current.get(cursor);
+        if (meta === undefined) {
+          return [];
+        }
+        segments.unshift({
+          value: meta.value,
+          label: meta.label,
+          isBranch: meta.isBranch,
+          disabled: meta.disabled,
+          depth: meta.depth,
+        });
+        cursor = meta.parentValue;
+        hops += 1;
+      }
+      return segments;
+    },
+    // `pathMetaVersion` bumps whenever the persistent map mutates,
+    // forcing context-value identity to change so consumers re-render
+    // and re-evaluate `getPath`.
+    [pathMetaVersion],
+  );
+
+  const anchorRef = useRef<string | null>(null);
+  const [activeValue, setActiveValue] = useState<string | null>(null);
+
+  const focusItem = useCallback(
+    (value: string) => {
+      itemsRef.current.get(value)?.element.focus();
+    },
+    [itemsRef],
+  );
+
+  const isNodeDisabled = useCallback(
+    (value: string) => itemsRef.current.get(value)?.disabled === true,
+    [itemsRef],
+  );
+
+  const isExpanded = useCallback(
+    (value: string) => expandedValues.includes(value),
+    [expandedValues],
+  );
+
+  const toggleExpanded = useCallback(
+    (value: string) => {
+      const open = expandedValues.includes(value);
+      setExpandedValues(
+        open
+          ? expandedValues.filter((current) => current !== value)
+          : [...expandedValues, value],
+      );
+    },
+    [expandedValues, setExpandedValues],
+  );
+
+  const isSelected = useCallback(
+    (value: string) => selectedValues.includes(value),
+    [selectedValues],
+  );
+
+  const getVisibleOrder = useCallback((): string[] => {
+    const childrenByParent = new Map<string | null, string[]>();
+    for (const key of keys) {
+      const meta = itemsRef.current.get(key)!;
+      const bucket = childrenByParent.get(meta.parentValue) ?? [];
+      bucket.push(meta.value);
+      childrenByParent.set(meta.parentValue, bucket);
+    }
+
+    const result: string[] = [];
+    const visit = (parent: string | null): void => {
+      for (const value of childrenByParent.get(parent) ?? []) {
+        result.push(value);
+        const meta = itemsRef.current.get(value);
+        if (meta?.isBranch && expandedValues.includes(value)) {
+          visit(value);
+        }
+      }
+    };
+    visit(null);
+    return result;
+  }, [keys, itemsRef, expandedValues]);
+
+  const select = useCallback(
+    (value: string, modifiers?: TreeSelectModifiers) => {
+      if (options.selectionMode === "single") {
+        if (selectedValues[0] === value) {
+          return;
+        }
+        setSelectedValues([value]);
+        anchorRef.current = value;
+        return;
+      }
+
+      const shift = modifiers?.shift === true;
+      const additive = modifiers?.meta === true || modifiers?.ctrl === true;
+      const alreadySelected = selectedValues.includes(value);
+
+      if (shift) {
+        const anchor = anchorRef.current ?? value;
+        const order = getVisibleOrder();
+        const anchorIndex = order.indexOf(anchor);
+        const valueIndex = order.indexOf(value);
+        if (anchorIndex === -1 || valueIndex === -1) {
+          setSelectedValues([value]);
+          return;
+        }
+        const [start, end] =
+          anchorIndex <= valueIndex
+            ? [anchorIndex, valueIndex]
+            : [valueIndex, anchorIndex];
+        const range = order
+          .slice(start, end + 1)
+          .filter((candidate) => !isNodeDisabled(candidate));
+        setSelectedValues(range);
+        return;
+      }
+
+      if (additive) {
+        setSelectedValues(
+          alreadySelected
+            ? selectedValues.filter((current) => current !== value)
+            : [...selectedValues, value],
+        );
+        anchorRef.current = value;
+        return;
+      }
+
+      if (selectedValues.length === 1 && alreadySelected) {
+        return;
+      }
+      setSelectedValues([value]);
+      anchorRef.current = value;
+    },
+    [
+      options.selectionMode,
+      selectedValues,
+      setSelectedValues,
+      getVisibleOrder,
+      isNodeDisabled,
+    ],
+  );
+
+  const visibleOrder = getVisibleOrder();
+  const defaultTabStop =
+    visibleOrder.find((candidate) => !isNodeDisabled(candidate)) ?? null;
+  const tabStop =
+    activeValue !== null && visibleOrder.includes(activeValue)
+      ? activeValue
+      : defaultTabStop;
+
+  return {
+    rootId,
+    selectionMode: options.selectionMode,
+    isExpanded,
+    toggleExpanded,
+    isSelected,
+    select,
+    registerNode,
+    getVisibleOrder,
+    isNodeDisabled,
+    tabStop,
+    setActiveValue,
+    focusItem,
+    getPath,
+    selectedOrder: selectedValues,
+  };
+}

package/src/Tree/index.ts

@@ -0,0 +1,3 @@
+export * from "./Tree";
+export { useTreePath, useTreeSelectionPaths } from "./hooks/useTreePath";
+export type { TreePathSegment } from "./types";

package/src/Tree/types.ts

@@ -0,0 +1,224 @@
+import type { ComponentProps, ReactNode } from "react";
+
+type TreeRootBaseProps = ComponentProps<"div"> & {
+  children: ReactNode;
+};
+
+type TreeRootUncontrolledExpansionProps = {
+  /** Branch values expanded on first render when uncontrolled. */
+  defaultExpandedValues?: string[];
+  expandedValues?: never;
+  onExpandedChange?: (values: string[]) => void;
+};
+
+type TreeRootControlledExpansionProps = {
+  defaultExpandedValues?: never;
+  /** The set of expanded branch values, owned by the consumer. */
+  expandedValues: string[];
+  onExpandedChange: (values: string[]) => void;
+};
+
+type TreeRootSingleUncontrolledSelectionProps = {
+  selectionMode?: "single";
+  /** The value selected on first render when uncontrolled. */
+  defaultSelectedValue?: string | null;
+  selectedValue?: never;
+  onSelectedValueChange?: (value: string | null) => void;
+  defaultSelectedValues?: never;
+  selectedValues?: never;
+  onSelectedValuesChange?: never;
+};
+
+type TreeRootSingleControlledSelectionProps = {
+  selectionMode?: "single";
+  defaultSelectedValue?: never;
+  /** The selected value, owned by the consumer. */
+  selectedValue: string | null;
+  onSelectedValueChange: (value: string | null) => void;
+  defaultSelectedValues?: never;
+  selectedValues?: never;
+  onSelectedValuesChange?: never;
+};
+
+type TreeRootMultipleUncontrolledSelectionProps = {
+  selectionMode: "multiple";
+  /** The values selected on first render when uncontrolled. */
+  defaultSelectedValues?: string[];
+  selectedValues?: never;
+  onSelectedValuesChange?: (values: string[]) => void;
+  defaultSelectedValue?: never;
+  selectedValue?: never;
+  onSelectedValueChange?: never;
+};
+
+type TreeRootMultipleControlledSelectionProps = {
+  selectionMode: "multiple";
+  defaultSelectedValues?: never;
+  /** The selected values, owned by the consumer. */
+  selectedValues: string[];
+  onSelectedValuesChange: (values: string[]) => void;
+  defaultSelectedValue?: never;
+  selectedValue?: never;
+  onSelectedValueChange?: never;
+};
+
+export type TreeRootProps = TreeRootBaseProps &
+  (TreeRootUncontrolledExpansionProps | TreeRootControlledExpansionProps) &
+  (
+    | TreeRootSingleUncontrolledSelectionProps
+    | TreeRootSingleControlledSelectionProps
+    | TreeRootMultipleUncontrolledSelectionProps
+    | TreeRootMultipleControlledSelectionProps
+  );
+
+export type TreeItemProps = ComponentProps<"div"> & {
+  /** Stable identifier for this item, unique within the tree. */
+  value: string;
+  /**
+   * Optional display label for this item. Stored alongside the value
+   * in the tree's node registry so {@link useTreePath} and
+   * `Tree.SelectionPath` can surface it without an external lookup.
+   * Has no effect on what `Tree.Item` renders.
+   */
+  label?: string;
+  /** Disable selection and remove the item from roving navigation. */
+  disabled?: boolean;
+  /** Render the item as the supplied child element instead of `<div>`. */
+  asChild?: boolean;
+  children: ReactNode;
+};
+
+export type TreeBranchProps = Omit<ComponentProps<"div">, "ref"> & {
+  /** Stable identifier for this branch, unique within the tree. */
+  value: string;
+  /**
+   * Optional display label for this branch. Stored alongside the value
+   * in the tree's node registry so {@link useTreePath} and
+   * `Tree.SelectionPath` can surface it without an external lookup.
+   * Has no effect on what `Tree.Branch` renders.
+   */
+  label?: string;
+  /**
+   * Disable selection, expansion-toggling, and roving navigation for
+   * this branch. The branch and its current content remain rendered.
+   */
+  disabled?: boolean;
+  children: ReactNode;
+};
+
+export type TreeBranchControlProps = ComponentProps<"div"> & {
+  /** Render the control as the supplied child element instead of `<div>`. */
+  asChild?: boolean;
+  children: ReactNode;
+};
+
+export type TreeBranchContentProps = ComponentProps<"div"> & {
+  children: ReactNode;
+  /**
+   * Keep the content mounted while the branch is collapsed so CSS can
+   * animate it in and out. When collapsed it is hidden from assistive
+   * technology with `aria-hidden`.
+   */
+  forceMount?: boolean;
+};
+
+export type TreeBranchIndicatorProps = ComponentProps<"span"> & {
+  /** Render as the supplied child element instead of `<span>`. */
+  asChild?: boolean;
+};
+
+/** Arguments passed to the `Tree.SelectionPath` render-prop form. */
+export type TreeSelectionPathRenderProps = {
+  /** One root-to-leaf chain per currently-selected value, in selection order. */
+  paths: TreePathSegment[][];
+};
+
+export type TreeSelectionPathProps = Omit<ComponentProps<"div">, "children"> & {
+  /**
+   * Either standard React children (ignored — the subcomponent does its
+   * own rendering) or a render-prop receiving the resolved selection
+   * paths so consumers can lay out custom markup.
+   */
+  children?: ReactNode | ((args: TreeSelectionPathRenderProps) => ReactNode);
+  /**
+   * Node passed to each `Breadcrumb.Separator` in the default rendering.
+   * Defaults to Breadcrumb's built-in `"/"` glyph.
+   */
+  separator?: ReactNode;
+};
+
+export type TreeLevelContextValue = {
+  /** Zero-based nesting depth — `0` for items directly inside `Tree.Root`. */
+  depth: number;
+  /** The value of the enclosing branch, or `null` at the tree root. */
+  parentValue: string | null;
+};
+
+export type TreeNodeMeta = {
+  value: string;
+  element: HTMLElement;
+  isBranch: boolean;
+  disabled: boolean;
+  depth: number;
+  parentValue: string | null;
+  label: string | null;
+};
+
+/**
+ * One segment of an ancestor chain returned by {@link useTreePath} or
+ * `TreeContextValue.getPath`. The array is ordered **root → leaf**, so
+ * the last segment is the queried item itself.
+ */
+export type TreePathSegment = {
+  value: string;
+  label: string | null;
+  isBranch: boolean;
+  disabled: boolean;
+  depth: number;
+};
+
+export type SelectionMode = "single" | "multiple";
+
+export type TreeSelectModifiers = {
+  meta: boolean;
+  ctrl: boolean;
+  shift: boolean;
+};
+
+export type TreeContextValue = {
+  /** Stable id shared across the tree, used to derive ARIA wiring ids. */
+  rootId: string;
+  selectionMode: SelectionMode;
+  isExpanded: (value: string) => boolean;
+  toggleExpanded: (value: string) => void;
+  isSelected: (value: string) => boolean;
+  select: (value: string, modifiers?: TreeSelectModifiers) => void;
+  registerNode: (value: string, meta: TreeNodeMeta | null) => void;
+  getVisibleOrder: () => string[];
+  isNodeDisabled: (value: string) => boolean;
+  /** Value of the treeitem currently holding the single roving tabstop. */
+  tabStop: string | null;
+  setActiveValue: (value: string) => void;
+  focusItem: (value: string) => void;
+  /**
+   * Returns the root-to-leaf chain of segments for the given value, or
+   * an empty array if the value has never been registered. Walks the
+   * persistent node registry so paths remain resolvable even when an
+   * ancestor branch has collapsed and its descendants unmounted.
+   */
+  getPath: (value: string) => TreePathSegment[];
+  /**
+   * The currently-selected values in selection order. Mirrors
+   * `selectedValues` in multiple mode and `[selectedValue]` (or `[]`)
+   * in single mode.
+   */
+  selectedOrder: readonly string[];
+};
+
+export type TreeItemContextValue = {
+  value: string;
+  expanded: boolean;
+  disabled: boolean;
+  /** DOM `id` of the branch's `BranchControl`, for `aria-labelledby`. */
+  controlId: string;
+};

package/src/Tree/utils.ts

@@ -0,0 +1,59 @@
+import { Children, Fragment, isValidElement } from "react";
+import type { ReactElement, ReactNode } from "react";
+
+import { TreeBranchControl, TreeBranchContent } from "./Tree";
+
+/** Whether `node` is a `Tree.BranchControl` element. */
+export function isBranchControlElement(node: ReactNode): node is ReactElement {
+  return isValidElement(node) && node.type === TreeBranchControl;
+}
+
+/** Whether `node` is a `Tree.BranchContent` element. */
+export function isBranchContentElement(node: ReactNode): node is ReactElement {
+  return isValidElement(node) && node.type === TreeBranchContent;
+}
+
+/**
+ * Splits a `Tree.Branch`'s children into its single `<Tree.BranchControl>`
+ * (the clickable row) and its optional `<Tree.BranchContent>` (the nested
+ * group). Both are matched however deeply they are wrapped in fragments,
+ * since `Children.toArray` does not descend into fragments — so
+ * `{open && <BranchContent/>}` is partitioned the same as a bare element.
+ */
+export function partitionBranchChildren(children: ReactNode): {
+  control: ReactElement;
+  content: ReactElement | null;
+} {
+  let control: ReactElement | null = null;
+  let content: ReactElement | null = null;
+
+  const visit = (nodes: ReactNode): void => {
+    for (const child of Children.toArray(nodes)) {
+      if (isBranchControlElement(child)) {
+        if (control !== null) {
+          throw new Error(
+            "A Tree.Branch may contain at most one <Tree.BranchControl>.",
+          );
+        }
+        control = child;
+      } else if (isBranchContentElement(child)) {
+        if (content !== null) {
+          throw new Error(
+            "A Tree.Branch may contain at most one <Tree.BranchContent>.",
+          );
+        }
+        content = child;
+      } else if (isValidElement(child) && child.type === Fragment) {
+        visit((child.props as { children?: ReactNode }).children);
+      }
+    }
+  };
+
+  visit(children);
+
+  if (control === null) {
+    throw new Error("A Tree.Branch must contain a <Tree.BranchControl>.");
+  }
+
+  return { control, content };
+}

package/src/VisuallyHidden/README.md

@@ -0,0 +1,58 @@
+# VisuallyHidden
+
+Visually hides its children while keeping them in the accessibility tree,
+implementing the standard
+[screen-reader-only pattern](https://www.w3.org/WAI/WCAG21/Techniques/css/C7).
+
+```tsx
+import { VisuallyHidden } from "@primitiv-ui/react";
+
+<button>
+  <SearchIcon aria-hidden="true" />
+  <VisuallyHidden>Search</VisuallyHidden>
+</button>;
+```
+
+## Props
+
+| Prop        | Type                     | Default | Notes                                              |
+| ----------- | ------------------------ | ------- | -------------------------------------------------- |
+| `asChild`   | `boolean`                | `false` | Render the consumer's element instead of a `<span>` |
+| `style`     | `CSSProperties`          | —       | Merged on top of the clip styles                  |
+| `className` | `string`                 | —       | Applied directly to the rendered element          |
+| `...rest`   | `ComponentProps<"span">` | —       | All other `<span>` props, including `aria-*`       |
+
+## Functional styles
+
+Unlike other `@primitiv-ui/react` components, `VisuallyHidden` ships inline
+styles — the clip rectangle that removes content from the visual layout
+*is* the component's behaviour, not decoration:
+
+```css
+position: absolute;
+width: 1px;
+height: 1px;
+padding: 0;
+margin: -1px;
+overflow: hidden;
+clip: rect(0 0 0 0);
+clip-path: inset(50%);
+white-space: nowrap;
+border-width: 0;
+```
+
+A consumer `style` is merged on top, so any individual property can still
+be overridden.
+
+## asChild
+
+Pass `asChild` to hide the consumer's own element instead of a `<span>` —
+useful when the hidden content needs specific semantics:
+
+```tsx
+<VisuallyHidden asChild>
+  <h2>Section heading</h2>
+</VisuallyHidden>
+```
+
+The clip styles are merged onto the child element via the `Slot` utility.