@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/components/tree/tree.test.tsx

@@ -0,0 +1,306 @@
+import {
+  hotkeysCoreFeature,
+  selectionFeature,
+  syncDataLoaderFeature,
+} from "@headless-tree/core";
+import { useTree } from "@headless-tree/react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { ReactNode } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { TreeDragLine, TreeItem, TreeItemLabel, TreeRoot } from "./tree";
+
+interface Item {
+  name: string;
+  children?: string[];
+}
+
+const items: Record<string, Item> = {
+  root: { name: "Root", children: ["folder", "leaf"] },
+  folder: { name: "Folder", children: ["nested"] },
+  nested: { name: "Nested" },
+  leaf: { name: "Leaf" },
+};
+
+interface HarnessProps {
+  initialExpanded?: string[];
+  leafIcon?: ReactNode;
+  parentIcon?: ReactNode | ((isExpanded: boolean) => ReactNode);
+  withChildren?: boolean;
+  indent?: number;
+  rootClassName?: string;
+  itemClassName?: string;
+  labelClassName?: string;
+}
+
+function Harness({
+  initialExpanded = [],
+  leafIcon,
+  parentIcon,
+  withChildren = false,
+  indent,
+  rootClassName,
+  itemClassName,
+  labelClassName,
+}: HarnessProps) {
+  const tree = useTree<Item>({
+    rootItemId: "root",
+    getItemName: (item) => item.getItemData().name,
+    isItemFolder: (item) => (item.getItemData().children?.length ?? 0) > 0,
+    dataLoader: {
+      getItem: (itemId) => items[itemId],
+      getChildren: (itemId) => items[itemId]?.children ?? [],
+    },
+    initialState: { expandedItems: initialExpanded },
+    features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+  });
+
+  return (
+    <TreeRoot tree={tree} indent={indent} className={rootClassName}>
+      {tree.getItems().map((item) =>
+        withChildren || labelClassName ? (
+          <TreeItem
+            key={item.getId()}
+            item={item}
+            data-testid={`item-${item.getId()}`}
+            leafIcon={leafIcon}
+            parentIcon={parentIcon}
+            className={itemClassName}
+          >
+            <TreeItemLabel className={labelClassName}>
+              {labelClassName
+                ? item.getItemName()
+                : `Custom: ${item.getItemName()}`}
+            </TreeItemLabel>
+          </TreeItem>
+        ) : (
+          <TreeItem
+            key={item.getId()}
+            item={item}
+            data-testid={`item-${item.getId()}`}
+            leafIcon={leafIcon}
+            parentIcon={parentIcon}
+            className={itemClassName}
+          />
+        ),
+      )}
+    </TreeRoot>
+  );
+}
+
+describe("Tree component", () => {
+  it("renders the item name by default", () => {
+    render(<Harness />);
+    expect(screen.getByText("Folder")).toBeInTheDocument();
+    expect(screen.getByText("Leaf")).toBeInTheDocument();
+  });
+
+  it("renders a default chevron parentIcon on folders only", () => {
+    render(<Harness />);
+    expect(
+      screen.getByTestId("item-folder").querySelector("svg"),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByTestId("item-leaf").querySelector("svg"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("opts out of the default chevron when parentIcon is null", () => {
+    render(<Harness parentIcon={null} />);
+    expect(
+      screen.getByTestId("item-folder").querySelector("svg"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders leafIcon only on non-folder items", () => {
+    render(
+      <Harness
+        leafIcon={<span data-testid="leaf-icon">L</span>}
+        parentIcon={<span data-testid="parent-icon">P</span>}
+      />,
+    );
+
+    const leafIcons = screen.getAllByTestId("leaf-icon");
+    const parentIcons = screen.getAllByTestId("parent-icon");
+
+    expect(leafIcons).toHaveLength(1);
+    expect(parentIcons).toHaveLength(1);
+    expect(screen.getByTestId("item-leaf")).toContainElement(leafIcons[0]!);
+    expect(screen.getByTestId("item-folder")).toContainElement(parentIcons[0]!);
+  });
+
+  it("calls the parentIcon function with the expanded state", () => {
+    render(
+      <Harness
+        initialExpanded={["folder"]}
+        parentIcon={(isExpanded) => (
+          <span data-testid="parent-icon">
+            {isExpanded ? "open" : "closed"}
+          </span>
+        )}
+      />,
+    );
+
+    expect(screen.getByTestId("item-folder")).toHaveTextContent("open");
+  });
+
+  it("ignores leafIcon / parentIcon when children are provided", () => {
+    render(
+      <Harness
+        withChildren
+        leafIcon={<span data-testid="leaf-icon">L</span>}
+        parentIcon={<span data-testid="parent-icon">P</span>}
+      />,
+    );
+
+    expect(screen.queryByTestId("leaf-icon")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("parent-icon")).not.toBeInTheDocument();
+    expect(screen.getByText("Custom: Folder")).toBeInTheDocument();
+  });
+
+  it("sets data-folder on folder items and aria-expanded based on state", () => {
+    render(<Harness initialExpanded={["folder"]} />);
+
+    const folder = screen.getByTestId("item-folder");
+    expect(folder).toHaveAttribute("data-folder", "true");
+    expect(folder).toHaveAttribute("aria-expanded", "true");
+
+    const leaf = screen.getByTestId("item-leaf");
+    expect(leaf).not.toHaveAttribute("data-folder");
+  });
+
+  it("exposes the --tree-indent CSS variable on the root", () => {
+    render(<Harness />);
+    const root = document.querySelector('[data-slot="tree"]');
+    expect(root).toHaveStyle({ "--tree-indent": "20px" });
+  });
+});
+
+describe("Tree data-slots", () => {
+  it("sets data-slot='tree-item' on each item", () => {
+    render(<Harness />);
+    const treeItems = document.querySelectorAll('[data-slot="tree-item"]');
+    expect(treeItems.length).toBeGreaterThan(0);
+  });
+
+  it("sets data-slot='tree-item-label' on item labels", () => {
+    render(<Harness />);
+    const labels = document.querySelectorAll('[data-slot="tree-item-label"]');
+    expect(labels.length).toBeGreaterThan(0);
+  });
+});
+
+describe("Tree classNames", () => {
+  it("applies className to TreeRoot", () => {
+    render(<Harness rootClassName="custom-root" />);
+    expect(document.querySelector('[data-slot="tree"]')).toHaveClass(
+      "custom-root",
+    );
+  });
+
+  it("applies className to TreeItem", () => {
+    render(<Harness itemClassName="custom-item" />);
+    const treeItems = document.querySelectorAll('[data-slot="tree-item"]');
+    for (const item of treeItems) {
+      expect(item).toHaveClass("custom-item");
+    }
+  });
+
+  it("applies className to TreeItemLabel", () => {
+    render(<Harness labelClassName="custom-label" />);
+    const labels = document.querySelectorAll('[data-slot="tree-item-label"]');
+    for (const label of labels) {
+      expect(label).toHaveClass("custom-label");
+    }
+  });
+});
+
+describe("Tree custom indent", () => {
+  it("uses custom indent value in CSS variable", () => {
+    render(<Harness indent={32} />);
+    expect(document.querySelector('[data-slot="tree"]')).toHaveStyle({
+      "--tree-indent": "32px",
+    });
+  });
+});
+
+describe("Tree selected state", () => {
+  it("sets data-selected on clicked item", async () => {
+    render(<Harness />);
+    const leaf = screen.getByTestId("item-leaf");
+    await userEvent.click(leaf);
+    expect(leaf).toHaveAttribute("data-selected", "true");
+  });
+});
+
+// ─── Context error paths ──────────────────────────────────────────────────────
+
+describe("Tree context errors", () => {
+  it("TreeDragLine throws when used outside a TreeRoot", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    expect(() => render(<TreeDragLine />)).toThrow(
+      "Tree components must be used within a TreeRoot",
+    );
+    spy.mockRestore();
+  });
+
+  it("TreeItemLabel throws when used outside a TreeItem", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    function BadUsage() {
+      const tree = useTree<Item>({
+        rootItemId: "root",
+        getItemName: (item) => item.getItemData().name,
+        isItemFolder: () => false,
+        dataLoader: {
+          getItem: (id) => items[id],
+          getChildren: () => [],
+        },
+        features: [syncDataLoaderFeature],
+      });
+      return (
+        <TreeRoot tree={tree}>
+          <TreeItemLabel>Orphan</TreeItemLabel>
+        </TreeRoot>
+      );
+    }
+
+    expect(() => render(<BadUsage />)).toThrow(
+      "TreeItemLabel must be used within a TreeItem",
+    );
+    spy.mockRestore();
+  });
+});
+
+// ─── TreeDragLine ─────────────────────────────────────────────────────────────
+
+describe("TreeDragLine", () => {
+  it("renders null when the tree has no active drag line style", () => {
+    function HarnessWithDragLine() {
+      const tree = useTree<Item>({
+        rootItemId: "root",
+        getItemName: (item) => item.getItemData().name,
+        isItemFolder: (item) => (item.getItemData().children?.length ?? 0) > 0,
+        dataLoader: {
+          getItem: (id) => items[id],
+          getChildren: (id) => items[id]?.children ?? [],
+        },
+        features: [syncDataLoaderFeature, selectionFeature, hotkeysCoreFeature],
+      });
+
+      return (
+        <TreeRoot tree={tree}>
+          <TreeDragLine />
+          {tree.getItems().map((item) => (
+            <TreeItem key={item.getId()} item={item} />
+          ))}
+        </TreeRoot>
+      );
+    }
+
+    render(<HarnessWithDragLine />);
+    // Without an active drag, getDragLineStyle returns undefined → renders null
+    expect(document.querySelector('[data-slot="tree-drag-line"]')).toBeNull();
+  });
+});

package/src/components/tree/tree.tsx

@@ -0,0 +1,218 @@
+"use client";
+
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import type { ItemInstance, TreeInstance } from "@headless-tree/core";
+import { ChevronRightIcon } from "lucide-react";
+import {
+  type CSSProperties,
+  createContext,
+  type ReactNode,
+  useContext,
+} from "react";
+
+import { cn } from "../../lib";
+
+const DEFAULT_PARENT_ICON = (
+  <ChevronRightIcon
+    aria-hidden
+    className="size-4 shrink-0 text-muted-foreground transition-transform duration-200 in-data-[expanded=true]:rotate-90"
+  />
+);
+
+interface TreeContextValue {
+  tree: TreeInstance<unknown>;
+}
+
+const TreeContext = createContext<TreeContextValue | undefined>(undefined);
+
+function useTreeContext() {
+  const context = useContext(TreeContext);
+  if (!context) {
+    throw new Error("Tree components must be used within a TreeRoot");
+  }
+  return context;
+}
+
+interface TreeItemContextValue {
+  item: ItemInstance<unknown>;
+}
+
+const TreeItemContext = createContext<TreeItemContextValue | undefined>(
+  undefined,
+);
+
+function useTreeItemContext() {
+  const context = useContext(TreeItemContext);
+  if (!context) {
+    throw new Error("TreeItemLabel must be used within a TreeItem");
+  }
+  return context;
+}
+
+interface TreeRootProps<T> extends useRender.ComponentProps<"div"> {
+  tree: TreeInstance<T>;
+  indent?: number;
+}
+
+export function TreeRoot<T>({
+  tree,
+  indent = 20,
+  className,
+  render,
+  style,
+  ...props
+}: TreeRootProps<T>) {
+  const { style: containerStyle, ...containerProps } = tree.getContainerProps();
+
+  const defaultProps = {
+    "data-slot": "tree",
+    ...containerProps,
+    className: cn("flex flex-col outline-none", className),
+    style: {
+      ...containerStyle,
+      ...style,
+      "--tree-indent": `${indent}px`,
+    } as CSSProperties,
+  };
+
+  return (
+    <TreeContext.Provider value={{ tree: tree as TreeInstance<unknown> }}>
+      {useRender({
+        defaultTagName: "div",
+        render,
+        props: mergeProps<"div">(defaultProps, props),
+      })}
+    </TreeContext.Provider>
+  );
+}
+
+type ParentIcon = ReactNode | ((isExpanded: boolean) => ReactNode);
+
+interface TreeItemProps<T> extends useRender.ComponentProps<"button"> {
+  item: ItemInstance<T>;
+  leafIcon?: ReactNode;
+  parentIcon?: ParentIcon;
+}
+
+export function TreeItem<T>({
+  item,
+  leafIcon,
+  parentIcon = DEFAULT_PARENT_ICON,
+  className,
+  render,
+  children,
+  style,
+  ...props
+}: TreeItemProps<T>) {
+  const { style: itemStyle, ...itemProps } = item.getProps();
+  const level = item.getItemMeta().level;
+  const isFolder = item.isFolder();
+  const isExpanded = item.isExpanded();
+
+  const icon = isFolder
+    ? typeof parentIcon === "function"
+      ? parentIcon(isExpanded)
+      : parentIcon
+    : leafIcon;
+
+  const autoLabel = (
+    <TreeItemLabel>
+      {icon}
+      {item.getItemName()}
+    </TreeItemLabel>
+  );
+
+  const defaultProps = {
+    "data-slot": "tree-item",
+    "data-focused": item.isFocused() || undefined,
+    "data-folder": isFolder || undefined,
+    "data-selected": item.isSelected?.() || undefined,
+    "data-drag-target": item.isDragTarget?.() || undefined,
+    "data-search-match": item.isMatchingSearch?.() || undefined,
+    "data-expanded": isExpanded || undefined,
+    "aria-expanded": isFolder ? isExpanded : undefined,
+    ...itemProps,
+    style: {
+      ...itemStyle,
+      ...style,
+      paddingInlineStart: `calc(var(--tree-indent) * ${level})`,
+    } as CSSProperties,
+    className: cn(
+      "z-10 not-last:pb-0.5 outline-hidden select-none focus:z-20",
+      "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      className,
+    ),
+    children: children ?? autoLabel,
+  };
+
+  return (
+    <TreeItemContext.Provider value={{ item: item as ItemInstance<unknown> }}>
+      {useRender({
+        defaultTagName: "button",
+        render,
+        props: mergeProps<"button">(defaultProps, props),
+      })}
+    </TreeItemContext.Provider>
+  );
+}
+
+export function TreeItemLabel({
+  className,
+  render,
+  children,
+  ...props
+}: useRender.ComponentProps<"span">) {
+  const { item } = useTreeItemContext();
+
+  const defaultProps = {
+    "data-slot": "tree-item-label",
+    className: cn(
+      "flex items-center gap-2 rounded-sm px-2 py-1.5 text-sm transition-colors",
+      "bg-background hover:bg-accent",
+      "in-data-[selected=true]:bg-accent in-data-[selected=true]:text-accent-foreground",
+      "in-data-[drag-target=true]:bg-accent",
+      "in-data-[search-match=true]:bg-blue-50",
+      "in-focus-visible:ring-3 in-focus-visible:ring-ring/50",
+      "[&_svg]:pointer-events-none [&_svg]:shrink-0",
+      className,
+    ),
+    children: children ?? item.getItemName(),
+  };
+
+  return useRender({
+    defaultTagName: "span",
+    render,
+    props: mergeProps<"span">(defaultProps, props),
+  });
+}
+
+export function TreeDragLine({
+  className,
+  render,
+  style,
+  ...props
+}: useRender.ComponentProps<"div">) {
+  const { tree } = useTreeContext();
+  const dragLineStyle = tree.getDragLineStyle?.();
+  if (!dragLineStyle) return null;
+
+  const defaultProps = {
+    "data-slot": "tree-drag-line",
+    style: { ...dragLineStyle, ...style },
+    className: cn(
+      "absolute z-30 -mt-px h-0.5 w-[unset] bg-primary",
+      "before:absolute before:-top-[3px] before:left-0 before:size-2 before:rounded-full",
+      "before:border-2 before:border-primary before:bg-background",
+      className,
+    ),
+  };
+
+  return useRender({
+    defaultTagName: "div",
+    render,
+    props: mergeProps<"div">(defaultProps, props),
+  });
+}
+
+export type { TreeRootProps, TreeItemProps };

package/src/hooks/index.ts

@@ -0,0 +1,27 @@
+export { useControllableState } from "@radix-ui/react-use-controllable-state";
+export * from "./use-array";
+export * from "./use-async";
+export * from "./use-boolean";
+export * from "./use-click-outside";
+export * from "./use-clipboard";
+export * from "./use-debounce-callback";
+export * from "./use-debounce-value";
+export * from "./use-disclosure";
+export * from "./use-document-title";
+export * from "./use-event-listener";
+export * from "./use-focus-trap";
+export * from "./use-hotkey";
+export * from "./use-hover";
+export * from "./use-is-visible";
+export * from "./use-local-storage";
+export * from "./use-media-query";
+export * from "./use-memoized-fn";
+export * from "./use-mutation";
+export * from "./use-object";
+export * from "./use-on-mount";
+export * from "./use-pagination";
+export * from "./use-portal";
+export * from "./use-prevent-page-close";
+export * from "./use-range-pagination";
+export * from "./use-selection";
+export * from "./use-step";

package/src/hooks/internal/index.ts

@@ -0,0 +1,4 @@
+export { isAppleDevice } from "./is-apple-device";
+export { isBrowser } from "./is-browser";
+export { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect";
+export { useLatestRef } from "./use-latest-ref";

package/src/hooks/internal/is-apple-device.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { isAppleDevice } from "./is-apple-device";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe("isAppleDevice", () => {
+  it("returns true when navigator.userAgentData.platform reports macOS", () => {
+    vi.stubGlobal("navigator", { userAgentData: { platform: "macOS" } });
+    expect(isAppleDevice()).toBe(true);
+  });
+
+  it("returns true for iPhone via legacy navigator.platform", () => {
+    vi.stubGlobal("navigator", { platform: "iPhone" });
+    expect(isAppleDevice()).toBe(true);
+  });
+
+  it("returns true for iPad via legacy navigator.platform", () => {
+    vi.stubGlobal("navigator", { platform: "iPad" });
+    expect(isAppleDevice()).toBe(true);
+  });
+
+  it("returns false on a non-Apple platform (Windows)", () => {
+    vi.stubGlobal("navigator", { platform: "Win32" });
+    expect(isAppleDevice()).toBe(false);
+  });
+
+  it("prefers userAgentData.platform over legacy navigator.platform", () => {
+    vi.stubGlobal("navigator", {
+      userAgentData: { platform: "Windows" },
+      platform: "MacIntel",
+    });
+    expect(isAppleDevice()).toBe(false);
+  });
+
+  it("returns false when navigator is missing (SSR)", () => {
+    vi.stubGlobal("navigator", undefined);
+    expect(isAppleDevice()).toBe(false);
+  });
+});

package/src/hooks/internal/is-apple-device.ts

@@ -0,0 +1,33 @@
+import { isBrowser } from "./is-browser";
+
+/**
+ * Structural shape of the modern `navigator.userAgentData` API, which is not
+ * yet part of the standard TypeScript DOM lib. Only the `platform` field is
+ * read here.
+ */
+type NavigatorWithUAData = Navigator & {
+  userAgentData?: { platform?: string };
+};
+
+const APPLE_PLATFORM_PATTERN = /mac|iphone|ipad|ipod/i;
+
+/**
+ * Lazily detects whether the current device is an Apple platform (macOS, iOS,
+ * iPadOS). Reads `navigator.userAgentData?.platform` when available, falling
+ * back to the legacy `navigator.platform`.
+ *
+ * SSR-safe: returns `false` when there is no `navigator` (e.g. on the server),
+ * so the `mod` hotkey modifier deterministically resolves to `ctrl` there.
+ *
+ * The check runs on every call (not memoized at module-eval) so it can be
+ * stubbed per-test and stays correct if the environment changes.
+ */
+export const isAppleDevice = (): boolean => {
+  if (!isBrowser || typeof navigator === "undefined") return false;
+
+  const nav = navigator as NavigatorWithUAData;
+  const platform = nav.userAgentData?.platform ?? nav.platform;
+  if (!platform) return false;
+
+  return APPLE_PLATFORM_PATTERN.test(platform);
+};

package/src/hooks/internal/is-browser.ts

@@ -0,0 +1 @@
+export const isBrowser = typeof window !== "undefined";

package/src/hooks/internal/use-isomorphic-layout-effect.ts

@@ -0,0 +1,6 @@
+import { useEffect, useLayoutEffect } from "react";
+import { isBrowser } from "./is-browser";
+
+export const useIsomorphicLayoutEffect = isBrowser
+  ? useLayoutEffect
+  : useEffect;

package/src/hooks/internal/use-latest-ref.ts

@@ -0,0 +1,21 @@
+import { useRef } from "react";
+import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect";
+
+/**
+ * Returns a ref whose `.current` always holds the latest value passed in.
+ *
+ * Internal building block for the handler-stable pattern: hooks that accept
+ * user callbacks should read them through a ref so listeners attached to
+ * `window`/`document`/elements never need to be re-attached when the consumer
+ * passes an inline function.
+ *
+ * Updates happen in a layout effect so the ref is current before any user
+ * effect or commit-phase work runs in the same render.
+ */
+export const useLatestRef = <T>(value: T) => {
+  const ref = useRef<T>(value);
+  useIsomorphicLayoutEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+};

package/src/hooks/use-array/index.ts

@@ -0,0 +1 @@
+export * from "./use-array";