@elabs-ai/components-ui 4.0.0

package/src/components/tree/use-tree-keyboard.ts

@@ -0,0 +1,314 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { TreeNode } from "./tree";
+
+/**
+ * Flattens the visible (expanded) tree into an ordered list of node ids.
+ * Nodes whose ancestors are collapsed are excluded.
+ */
+export function flattenVisible<T>(nodes: TreeNode<T>[], expandedIds: Set<string>): string[] {
+  const result: string[] = [];
+  function walk(list: TreeNode<T>[]) {
+    for (const node of list) {
+      result.push(node.id);
+      if ((node.children?.length || node.hasChildren) && expandedIds.has(node.id)) {
+        if (node.children?.length) walk(node.children);
+      }
+    }
+  }
+  walk(nodes);
+  return result;
+}
+
+/**
+ * Builds a lookup map: node id → parent id (or null for roots).
+ */
+function buildParentMap<T>(
+  nodes: TreeNode<T>[],
+  parentId: string | null = null,
+  map: Map<string, string | null> = new Map(),
+): Map<string, string | null> {
+  for (const node of nodes) {
+    map.set(node.id, parentId);
+    if (node.children?.length) {
+      buildParentMap(node.children, node.id, map);
+    }
+  }
+  return map;
+}
+
+/**
+ * Finds a node by id in the tree (depth-first).
+ */
+export function findNode<T>(nodes: TreeNode<T>[], id: string): TreeNode<T> | undefined {
+  for (const node of nodes) {
+    if (node.id === id) return node;
+    if (node.children?.length) {
+      const found = findNode(node.children, id);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+export interface UseTreeKeyboardOptions<T> {
+  nodes: TreeNode<T>[];
+  expandedIds: Set<string>;
+  onExpandedChange: (ids: Set<string>) => void;
+  selectionMode: "single" | "multiple" | "none";
+  selectedIds: Set<string>;
+  onSelectionChange: (ids: Set<string>) => void;
+  /**
+   * When `true`, the tree uses windowed rendering. Focus navigation must
+   * scroll the virtualizer before focusing an unmounted row.
+   */
+  virtualize?: boolean;
+  /**
+   * Ordered list of visible node ids in the virtual flat list. Provided by
+   * the Tree when `virtualize` is true so the keyboard hook can map an id to
+   * a virtual index without re-flattening.
+   */
+  flatNodeIds?: string[];
+  /**
+   * Ref that the keyboard hook writes a node id into when it needs to focus a
+   * row that is currently scrolled out of view. The Tree's `registerAndFlush`
+   * callback reads this ref on every ref registration and focuses the element
+   * once it mounts.
+   */
+  pendingFocusIdRef?: React.MutableRefObject<string | null>;
+  /**
+   * Called when the keyboard hook wants to bring an index into view before
+   * focusing it. Only called in virtual mode.
+   */
+  scrollToVirtualIndex?: (index: number) => void;
+}
+
+export interface UseTreeKeyboardResult {
+  activeId: string | null;
+  setActiveId: (id: string | null) => void;
+  /** ref callback — register each tree item element keyed by node id */
+  registerNodeRef: (id: string, el: HTMLElement | null) => void;
+  /** onKeyDown handler to attach to the root tree div */
+  onKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+}
+
+export function useTreeKeyboard<T>(options: UseTreeKeyboardOptions<T>): UseTreeKeyboardResult {
+  const {
+    nodes,
+    expandedIds,
+    onExpandedChange,
+    selectionMode,
+    selectedIds,
+    onSelectionChange,
+    virtualize = false,
+    flatNodeIds,
+    pendingFocusIdRef,
+    scrollToVirtualIndex,
+  } = options;
+
+  // The currently "roving" active item id
+  const [activeId, setActiveIdState] = useState<string | null>(() => {
+    // default to first visible node
+    const visible = flattenVisible(nodes, expandedIds);
+    return visible[0] ?? null;
+  });
+
+  // Map from node id → DOM element reference
+  const nodeRefs = useRef<Map<string, HTMLElement>>(new Map());
+
+  const registerNodeRef = useCallback((id: string, el: HTMLElement | null) => {
+    if (el) {
+      nodeRefs.current.set(id, el);
+    } else {
+      nodeRefs.current.delete(id);
+    }
+  }, []);
+
+  // Typeahead buffer
+  const typeaheadBuffer = useRef<string>("");
+  const typeaheadTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Clear any pending typeahead timer on unmount.
+  useEffect(
+    () => () => {
+      if (typeaheadTimer.current) clearTimeout(typeaheadTimer.current);
+    },
+    [],
+  );
+
+  /**
+   * Focus the element for `id`. In virtual mode, if the element isn't
+   * mounted yet, record it as pending and scroll the virtualizer so the row
+   * enters the render window; the Tree's `registerAndFlush` will focus it
+   * once the ref fires.
+   */
+  const setActiveId = useCallback(
+    (id: string | null) => {
+      setActiveIdState(id);
+      if (!id) return;
+
+      const el = nodeRefs.current.get(id);
+      if (el) {
+        el.focus();
+        return;
+      }
+
+      // Element not mounted — happens when it's scrolled out of the virtual window.
+      if (virtualize && scrollToVirtualIndex && pendingFocusIdRef) {
+        const ids = flatNodeIds ?? [];
+        const index = ids.indexOf(id);
+        if (index >= 0) {
+          pendingFocusIdRef.current = id;
+          scrollToVirtualIndex(index);
+          // The Tree's registerAndFlush will call el.focus() once the row mounts.
+        }
+      }
+    },
+    [virtualize, flatNodeIds, pendingFocusIdRef, scrollToVirtualIndex],
+  );
+
+  const onKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLElement>) => {
+      if (!activeId) return;
+
+      // In virtual mode use the pre-computed flat list so we don't re-flatten
+      const visible = virtualize && flatNodeIds ? flatNodeIds : flattenVisible(nodes, expandedIds);
+      const currentIndex = visible.indexOf(activeId);
+      const currentNode = findNode(nodes, activeId);
+      const parentMap = buildParentMap(nodes);
+
+      const moveTo = (id: string) => {
+        e.preventDefault();
+        setActiveId(id);
+      };
+
+      const selectNode = (id: string) => {
+        if (selectionMode === "none") return;
+        const node = findNode(nodes, id);
+        if (node?.disabled) return;
+        if (selectionMode === "single") {
+          onSelectionChange(new Set([id]));
+        } else {
+          const next = new Set(selectedIds);
+          if (next.has(id)) {
+            next.delete(id);
+          } else {
+            next.add(id);
+          }
+          onSelectionChange(next);
+        }
+      };
+
+      switch (e.key) {
+        case "ArrowDown": {
+          e.preventDefault();
+          const next = visible[currentIndex + 1];
+          if (next) moveTo(next);
+          break;
+        }
+        case "ArrowUp": {
+          e.preventDefault();
+          const prev = visible[currentIndex - 1];
+          if (prev) moveTo(prev);
+          break;
+        }
+        case "ArrowRight": {
+          e.preventDefault();
+          if (!currentNode) break;
+          const expandable = !!(currentNode.children?.length || currentNode.hasChildren);
+          if (expandable && !expandedIds.has(activeId)) {
+            // expand
+            const next = new Set(expandedIds);
+            next.add(activeId);
+            onExpandedChange(next);
+          } else if (expandable && expandedIds.has(activeId)) {
+            // move to first child (only if loaded)
+            const firstChild = currentNode.children?.[0];
+            if (firstChild) moveTo(firstChild.id);
+          }
+          // leaf: do nothing
+          break;
+        }
+        case "ArrowLeft": {
+          e.preventDefault();
+          if (!currentNode) break;
+          const expandable = !!(currentNode.children?.length || currentNode.hasChildren);
+          if (expandable && expandedIds.has(activeId)) {
+            // collapse
+            const next = new Set(expandedIds);
+            next.delete(activeId);
+            onExpandedChange(next);
+          } else {
+            // move to parent
+            const parentId = parentMap.get(activeId) ?? null;
+            if (parentId) moveTo(parentId);
+          }
+          break;
+        }
+        case "Home": {
+          e.preventDefault();
+          const first = visible[0];
+          if (first) moveTo(first);
+          break;
+        }
+        case "End": {
+          e.preventDefault();
+          const last = visible[visible.length - 1];
+          if (last) moveTo(last);
+          break;
+        }
+        case "Enter":
+        case " ": {
+          e.preventDefault();
+          selectNode(activeId);
+          break;
+        }
+        default: {
+          // typeahead — single printable characters
+          if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+            const char = e.key.toLowerCase();
+            typeaheadBuffer.current += char;
+
+            if (typeaheadTimer.current) clearTimeout(typeaheadTimer.current);
+            typeaheadTimer.current = setTimeout(() => {
+              typeaheadBuffer.current = "";
+            }, 500);
+
+            const prefix = typeaheadBuffer.current;
+            // find the next visible node (after current) whose label starts with prefix
+            const searchList = [
+              ...visible.slice(currentIndex + 1),
+              ...visible.slice(0, currentIndex + 1),
+            ];
+            for (const id of searchList) {
+              const node = findNode(nodes, id);
+              if (!node) continue;
+              // only string labels are searchable
+              if (typeof node.label !== "string") continue;
+              if (node.label.toLowerCase().startsWith(prefix)) {
+                moveTo(id);
+                break;
+              }
+            }
+          }
+          break;
+        }
+      }
+    },
+    [
+      activeId,
+      nodes,
+      expandedIds,
+      onExpandedChange,
+      selectionMode,
+      selectedIds,
+      onSelectionChange,
+      setActiveId,
+      virtualize,
+      flatNodeIds,
+    ],
+  );
+
+  return { activeId, setActiveId, registerNodeRef, onKeyDown };
+}

package/src/components/tree-select/index.ts

@@ -0,0 +1 @@
+export { TreeSelect, type TreeSelectProps } from "./tree-select";

package/src/components/tree-select/tree-select.stories.tsx

@@ -0,0 +1,127 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { useState } from "react";
+import { Folder, FileText } from "lucide-react";
+import { TreeSelect } from "./tree-select";
+import type { TreeNode } from "../tree";
+
+const tree: TreeNode[] = [
+  {
+    id: "engineering",
+    label: "Engineering",
+    icon: <Folder className="size-4 text-muted-foreground" />,
+    children: [
+      {
+        id: "frontend",
+        label: "Frontend",
+        icon: <FileText className="size-4 text-muted-foreground" />,
+      },
+      {
+        id: "backend",
+        label: "Backend",
+        icon: <FileText className="size-4 text-muted-foreground" />,
+      },
+      {
+        id: "platform",
+        label: "Platform",
+        icon: <FileText className="size-4 text-muted-foreground" />,
+      },
+    ],
+  },
+  {
+    id: "design",
+    label: "Design",
+    icon: <Folder className="size-4 text-muted-foreground" />,
+    children: [
+      {
+        id: "product-design",
+        label: "Product Design",
+        icon: <FileText className="size-4 text-muted-foreground" />,
+      },
+      {
+        id: "research",
+        label: "Research",
+        icon: <FileText className="size-4 text-muted-foreground" />,
+      },
+    ],
+  },
+];
+
+const meta = {
+  title: "Forms/TreeSelect",
+  component: TreeSelect,
+  tags: ["autodocs"],
+  argTypes: {
+    nodes: {
+      description: "Hierarchical tree data (`TreeNode[]`).",
+      control: false,
+      table: { category: "Content" },
+    },
+    value: {
+      description: "Controlled selection — `string` (single) or `string[]` (multiple).",
+      control: false,
+      table: { category: "State" },
+    },
+    defaultValue: {
+      description: "Uncontrolled initial selection.",
+      control: false,
+      table: { category: "State" },
+    },
+    multiple: {
+      description: "Enable multi-select (checkbox tree).",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    placeholder: {
+      description: "Trigger text when nothing is selected.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    onValueChange: {
+      description: "Called when the selection changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the trigger button.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof TreeSelect>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { nodes: tree, placeholder: "Select a team" },
+  // Opens the tree popover and confirms root nodes are visible.
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("combobox");
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    const engineeringNode = await body.findByRole("treeitem", { name: /engineering/i });
+    await expect(engineeringNode).toBeInTheDocument();
+  },
+};
+
+export const Preselected: Story = {
+  args: { nodes: tree, defaultValue: "frontend" },
+};
+
+function MultipleExample() {
+  const [value, setValue] = useState<string[]>(["frontend", "research"]);
+  return (
+    <TreeSelect
+      nodes={tree}
+      multiple
+      value={value}
+      onValueChange={(v) => setValue(v as string[])}
+      placeholder="Select teams"
+    />
+  );
+}
+
+export const Multiple: Story = {
+  render: () => <MultipleExample />,
+};

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

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { TreeSelect } from "./tree-select";
+import type { TreeNode } from "../tree";
+
+const nodes: TreeNode[] = [
+  {
+    id: "fruits",
+    label: "Fruits",
+    children: [
+      { id: "apple", label: "Apple" },
+      { id: "banana", label: "Banana" },
+    ],
+  },
+  { id: "veggies", label: "Vegetables", children: [{ id: "carrot", label: "Carrot" }] },
+];
+
+describe("TreeSelect", () => {
+  it("renders the placeholder on the trigger when nothing is selected", () => {
+    render(<TreeSelect nodes={nodes} placeholder="Pick a node" />);
+    expect(screen.getByText("Pick a node")).toBeInTheDocument();
+    expect(screen.getByRole("combobox")).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("shows the selected label for a controlled single value", () => {
+    render(<TreeSelect nodes={nodes} value="apple" />);
+    expect(screen.getByText("Apple")).toBeInTheDocument();
+  });
+
+  it("renders a badge per selected node in multiple mode", () => {
+    render(<TreeSelect nodes={nodes} multiple value={["apple", "carrot"]} />);
+    expect(screen.getByText("Apple")).toBeInTheDocument();
+    expect(screen.getByText("Carrot")).toBeInTheDocument();
+  });
+
+  it("collapses overflow badges into a +N counter", () => {
+    render(<TreeSelect nodes={nodes} multiple value={["apple", "banana", "carrot"]} />);
+    expect(screen.getByText("+1")).toBeInTheDocument();
+  });
+});

package/src/components/tree-select/tree-select.tsx

@@ -0,0 +1,137 @@
+// a2ui.exposed: yes
+"use client";
+
+import { forwardRef, useId, useState, type ButtonHTMLAttributes, type ReactNode } from "react";
+import { ChevronsUpDown } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Badge } from "../badge";
+import { Button } from "../button";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { Tree, type TreeNode } from "../tree";
+
+export interface TreeSelectProps<T = unknown> extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "value" | "onChange"
+> {
+  nodes: TreeNode<T>[];
+  /** Controlled value — `string` in single mode, `string[]` in multiple mode. */
+  value?: string | string[];
+  /** Uncontrolled initial value. */
+  defaultValue?: string | string[];
+  onValueChange?: (value: string | string[]) => void;
+  /** Allow selecting multiple nodes (checkbox tree). Default false. */
+  multiple?: boolean;
+  placeholder?: string;
+  className?: string;
+}
+
+function toArray(v: string | string[] | undefined): string[] {
+  if (v === undefined) return [];
+  if (Array.isArray(v)) return v;
+  return v === "" ? [] : [v];
+}
+
+function findLabel<T>(nodes: TreeNode<T>[], id: string): ReactNode | undefined {
+  for (const node of nodes) {
+    if (node.id === id) return node.label;
+    if (node.children?.length) {
+      const found = findLabel(node.children, id);
+      if (found !== undefined) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * A select whose options are a hierarchical {@link Tree}. Single or multiple
+ * selection; composes `Tree` for all keyboard/SR behaviour.
+ */
+export const TreeSelect = forwardRef<HTMLButtonElement, TreeSelectProps>(function TreeSelect(
+  {
+    nodes,
+    value,
+    defaultValue,
+    onValueChange,
+    multiple = false,
+    placeholder = "Select…",
+    className,
+    ...props
+  },
+  ref,
+) {
+  const [open, setOpen] = useState(false);
+  const treeId = useId();
+  const isControlled = value !== undefined;
+  const [internal, setInternal] = useState<string[]>(() => toArray(defaultValue));
+  const selected = isControlled ? toArray(value) : internal;
+
+  const emit = (next: string[]) => {
+    if (!isControlled) setInternal(next);
+    onValueChange?.(multiple ? next : (next[0] ?? ""));
+  };
+
+  const handleSelectionChange = (ids: string[]) => {
+    emit(ids);
+    if (!multiple) setOpen(false);
+  };
+
+  const labels = selected.map((id) => ({ id, label: findLabel(nodes, id) ?? id }));
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button
+          ref={ref}
+          type="button"
+          variant="outline"
+          role="combobox"
+          aria-haspopup="tree"
+          aria-expanded={open}
+          aria-controls={treeId}
+          className={cn("h-auto min-h-9 w-64 justify-between font-normal", className)}
+          {...props}
+        >
+          <span className="flex min-w-0 flex-1 flex-wrap items-center gap-1 text-start">
+            {labels.length === 0 ? (
+              <span className="text-muted-foreground">{placeholder}</span>
+            ) : multiple ? (
+              <>
+                {labels.slice(0, 2).map((l) => (
+                  <Badge
+                    key={l.id}
+                    variant="secondary"
+                    className="max-w-[10rem] truncate border-border"
+                  >
+                    {l.label}
+                  </Badge>
+                ))}
+                {labels.length > 2 ? (
+                  <Badge variant="secondary" aria-label={`and ${labels.length - 2} more selected`}>
+                    +{labels.length - 2}
+                  </Badge>
+                ) : null}
+              </>
+            ) : (
+              <span className="truncate">{labels[0]?.label}</span>
+            )}
+          </span>
+          <ChevronsUpDown className="ms-2 size-4 shrink-0 opacity-50" aria-hidden="true" />
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-64 p-1" align="start">
+        <Tree
+          id={treeId}
+          nodes={nodes}
+          selectionMode={multiple ? "multiple" : "single"}
+          checkboxes={multiple}
+          selectedIds={selected}
+          onSelectionChange={handleSelectionChange}
+          defaultExpandedIds={nodes.map((n) => n.id)}
+          className="max-h-72 overflow-auto"
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}) as <T = unknown>(
+  props: TreeSelectProps<T> & { ref?: React.Ref<HTMLButtonElement> },
+) => React.ReactElement | null;

package/src/components/typography/index.ts

@@ -0,0 +1,31 @@
+export {
+  Heading,
+  Text,
+  headingVariants,
+  textVariants,
+  TEXT_ROLE_REM,
+  type HeadingProps,
+  type HeadingLevel,
+  type HeadingSize,
+  type TextProps,
+  type TextVariant,
+  type TextTone,
+  type TextRole,
+} from "./typography";
+export {
+  ProseHeading,
+  ProseText,
+  ProseLink,
+  ProseList,
+  ProseListItem,
+  ProseBlockquote,
+  ProseInlineCode,
+  PROSE_HEADING_REM,
+  PROSE_HEADING_WEIGHT,
+  PROSE_HEADING_TRACKING,
+  type ProseHeadingProps,
+  type ProseHeadingLevel,
+  type ProseTextProps,
+  type ProseLinkProps,
+  type ProseListProps,
+} from "./prose";

package/src/components/typography/prose.test.tsx

@@ -0,0 +1,48 @@
+/**
+ * prose.test.tsx — #399 class-name lock on the on-surface brand-accent rung.
+ *
+ * These are CLASS-NAME locks, NOT contrast proofs. The ratio itself is asserted
+ * on the tokens in `packages/tokens/src/themes-contrast.test.ts`
+ * (`primary-text ≥ 4.5:1 on …`, every theme × five content surfaces); what this
+ * file pins is that the components that render the brand accent AS TEXT keep
+ * reaching for that rung instead of sliding back onto the `--primary` FILL,
+ * whose gated contract is only the WCAG 1.4.11 mark bar (3:1). The two halves
+ * together are what makes #399 non-regressable: a token that clears AA nobody
+ * uses fixes nothing, and a call site pointing at a token nobody gates is how
+ * this shipped sub-AA in the first place.
+ */
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { Text } from "./typography";
+import { ProseLink } from "./prose";
+
+afterEach(cleanup);
+
+describe("ProseLink — #399 on-surface brand-accent rung", () => {
+  it("renders text-primary-text, never the text-primary fill rung", () => {
+    render(<ProseLink href="https://example.com">docs</ProseLink>);
+
+    const link = screen.getByRole("link", { name: "docs" });
+    const classes = link.className.split(/\s+/);
+    expect(classes).toContain("text-primary-text");
+    expect(classes).not.toContain("text-primary");
+  });
+
+  it("keeps its resting underline (the non-colour cue is independent of the rung)", () => {
+    render(<ProseLink href="https://example.com">docs</ProseLink>);
+
+    const classes = screen.getByRole("link", { name: "docs" }).className.split(/\s+/);
+    expect(classes).toContain("underline");
+  });
+});
+
+describe("Text tone=primary — #399 on-surface brand-accent rung", () => {
+  it("maps the primary tone to text-primary-text, never the fill rung", () => {
+    render(<Text tone="primary">accent</Text>);
+
+    const classes = screen.getByText("accent").className.split(/\s+/);
+    expect(classes).toContain("text-primary-text");
+    expect(classes).not.toContain("text-primary");
+  });
+});