@primitiv-ui/react 0.1.37 → 0.1.39

package/src/Tree/__tests__/Tree.uncontrolled-expansion.test.tsx

@@ -1,69 +0,0 @@
-import { render, screen } from "@testing-library/react";
-import userEvent from "@testing-library/user-event";
-
-import { Tree } from "../Tree";
-
-function renderTree(props?: { defaultExpandedValues?: string[] }) {
-  return render(
-    <Tree.Root {...props}>
-      <Tree.Branch value="src">
-        <Tree.BranchControl>src</Tree.BranchControl>
-        <Tree.BranchContent>
-          <Tree.Item value="index">index.ts</Tree.Item>
-        </Tree.BranchContent>
-      </Tree.Branch>
-    </Tree.Root>,
-  );
-}
-
-describe("Tree uncontrolled expansion tests", () => {
-  it("should collapse branches by default", () => {
-    // Arrange
-    renderTree();
-
-    // Assert
-    expect(screen.queryByText("index.ts")).not.toBeInTheDocument();
-    expect(screen.getByRole("treeitem")).toHaveAttribute(
-      "aria-expanded",
-      "false",
-    );
-  });
-
-  it("should expand a branch listed in defaultExpandedValues", () => {
-    // Arrange
-    renderTree({ defaultExpandedValues: ["src"] });
-
-    // Assert
-    expect(screen.getByText("index.ts")).toBeInTheDocument();
-    expect(screen.getByRole("treeitem", { expanded: true })).toBeInTheDocument();
-  });
-
-  it("should expand a collapsed branch when its control row is clicked", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    renderTree();
-
-    // Act
-    await user.click(screen.getByText("src"));
-
-    // Assert
-    expect(screen.getByText("index.ts")).toBeInTheDocument();
-    expect(screen.getByRole("treeitem", { expanded: true })).toBeInTheDocument();
-  });
-
-  it("should collapse an expanded branch when its control row is clicked", async () => {
-    // Arrange
-    const user = userEvent.setup();
-    renderTree({ defaultExpandedValues: ["src"] });
-
-    // Act
-    await user.click(screen.getByText("src"));
-
-    // Assert
-    expect(screen.queryByText("index.ts")).not.toBeInTheDocument();
-    expect(screen.getByRole("treeitem")).toHaveAttribute(
-      "aria-expanded",
-      "false",
-    );
-  });
-});

package/src/Tree/hooks/index.ts

@@ -1,3 +0,0 @@
-export * from "./useTreeRoot";
-export * from "./useTreeItemKeyboard";
-export * from "./useTreePath";

package/src/Tree/hooks/useTreeItemKeyboard.ts

@@ -1,86 +0,0 @@
-import type { KeyboardEvent } from "react";
-
-import { useRovingTabindex } from "../../hooks/index.ts";
-import { useTreeContext } from "../TreeContext";
-
-type TreeItemKeyboardOptions = {
-  isBranch: boolean;
-  parentValue: string | null;
-  disabled: boolean;
-};
-
-/**
- * Combined keyboard handler for every Tree treeitem. Layers the tree's
- * own ArrowRight / ArrowLeft semantics — expand, collapse, focus first
- * child, focus parent — on top of the vertical roving-tabindex
- * navigation, with Enter/Space activation routed through Item-vs-Branch
- * behaviour. Disabled items short-circuit branch keys and activation
- * but pass through Home/End so a user can escape them.
- */
-export function useTreeItemKeyboard(
-  value: string,
-  { isBranch, parentValue, disabled }: TreeItemKeyboardOptions,
-) {
-  const ctx = useTreeContext();
-  const navigable = ctx
-    .getVisibleOrder()
-    .filter((candidate) => !ctx.isNodeDisabled(candidate));
-
-  const { handleKeyDown: rovingHandleKeyDown } = useRovingTabindex<string>({
-    orientation: "vertical",
-    navigable,
-    currentKey: value,
-    includeHomeEnd: true,
-    includeActivate: true,
-    onNavigate: (target, action) => {
-      if (action === "activate") {
-        if (disabled) {
-          return;
-        }
-        if (isBranch) {
-          ctx.toggleExpanded(value);
-        }
-        ctx.select(value);
-        return;
-      }
-      ctx.focusItem(target);
-    },
-  });
-
-  return function handleKeyDown(event: KeyboardEvent<HTMLElement>) {
-    if (event.key === "ArrowRight") {
-      if (!isBranch || disabled) {
-        return;
-      }
-      event.preventDefault();
-      if (!ctx.isExpanded(value)) {
-        ctx.toggleExpanded(value);
-        return;
-      }
-      const order = ctx.getVisibleOrder();
-      const next = order[order.indexOf(value) + 1];
-      if (next !== undefined) {
-        ctx.focusItem(next);
-      }
-      return;
-    }
-
-    if (event.key === "ArrowLeft") {
-      if (disabled) {
-        return;
-      }
-      if (isBranch && ctx.isExpanded(value)) {
-        event.preventDefault();
-        ctx.toggleExpanded(value);
-        return;
-      }
-      if (parentValue !== null) {
-        event.preventDefault();
-        ctx.focusItem(parentValue);
-      }
-      return;
-    }
-
-    rovingHandleKeyDown(event);
-  };
-}

package/src/Tree/hooks/useTreePath.ts

@@ -1,100 +0,0 @@
-import { useTreeContext, useTreeLevelContext } 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));
-}
-
-/**
- * Read the current nesting depth inside a `Tree` — `0` for a node directly
- * under {@link TreeRoot | `Tree.Root`}, one deeper per enclosing
- * {@link TreeBranchContent | `Tree.BranchContent`}.
- *
- * A styling layer needs the depth as a *number* to compute a row's indent, and
- * so to make the row span the tree's full width (a hover or selected band that
- * runs edge to edge, as VS Code and most file trees do). Reading it back off
- * the `data-depth` attribute in CSS requires `attr(data-depth type(<integer>))`,
- * which Firefox does not support — hence this hook.
- *
- * @throws If called outside a `Tree.Root`.
- *
- * @example Indenting a row so its background still spans the full width
- * ```tsx
- * function StyledItem(props: TreeItemProps) {
- *   const { depth } = useTreeLevel();
- *   return (
- *     <Tree.Item
- *       {...props}
- *       style={{ "--depth": depth } as CSSProperties}
- *       className="row"
- *     />
- *   );
- * }
- * ```
- */
-export function useTreeLevel(): { depth: number } {
-  const { depth } = useTreeLevelContext();
-  return { depth };
-}

package/src/Tree/hooks/useTreeRoot.ts

@@ -1,279 +0,0 @@
-import { useCallback, useId, useRef, useState } from "react";
-
-import { useCollection, useControllableState } from "../../hooks/index.ts";
-
-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

@@ -1,8 +0,0 @@
-export * from "./Tree";
-export * from "./types";
-export { TREE_PART, type TreePartName } from "./utils";
-export {
-  useTreeLevel,
-  useTreePath,
-  useTreeSelectionPaths,
-} from "./hooks/useTreePath";