@elabs-ai/components-ui 4.0.0

package/src/components/virtual-select/use-virtual-listbox.ts

@@ -0,0 +1,132 @@
+// a2ui.exposed: yes
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type { Virtualizer } from "@tanstack/react-virtual";
+
+export interface VirtualSelectOption {
+  label: string;
+  value: string;
+  disabled?: boolean;
+}
+
+interface UseVirtualListboxOptions {
+  count: number;
+  filtered: VirtualSelectOption[];
+  /** Reserved for future use (e.g. multi-select keyboard shortcuts). */
+  multiple?: boolean;
+  isOpen: boolean;
+  onSelect: (value: string) => void;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  virtualizer: Virtualizer<any, any> | null;
+}
+
+interface UseVirtualListboxReturn {
+  activeIndex: number;
+  setActiveIndex: (index: number) => void;
+  onInputKeyDown: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+}
+
+/** First non-disabled option index at or after `from`; -1 if none exists. */
+function findNext(filtered: VirtualSelectOption[], from: number): number {
+  for (let i = Math.max(0, from); i < filtered.length; i++) {
+    if (!filtered[i]?.disabled) return i;
+  }
+  return -1;
+}
+
+/** Last non-disabled option index at or before `from`; -1 if none exists. */
+function findPrev(filtered: VirtualSelectOption[], from: number): number {
+  for (let i = Math.min(from, filtered.length - 1); i >= 0; i--) {
+    if (!filtered[i]?.disabled) return i;
+  }
+  return -1;
+}
+
+/**
+ * Keyboard navigation logic for the VirtualSelect listbox.
+ * Encapsulates ArrowDown/Up/Home/End/Enter/Escape handling.
+ * Focus stays on the search input; `aria-activedescendant` tracks the active row.
+ */
+export function useVirtualListbox({
+  count,
+  filtered,
+  isOpen,
+  onSelect,
+  virtualizer,
+}: UseVirtualListboxOptions): UseVirtualListboxReturn {
+  const [activeIndex, setActiveIndexRaw] = useState(0);
+
+  // When the filtered list changes, reset to the first enabled option.
+  useEffect(() => {
+    const first = findNext(filtered, 0);
+    setActiveIndexRaw(first >= 0 ? first : 0);
+  }, [filtered]);
+
+  // When the popover closes, reset to 0.
+  useEffect(() => {
+    if (!isOpen) setActiveIndexRaw(0);
+  }, [isOpen]);
+
+  const setActiveIndex = useCallback(
+    (index: number) => {
+      const clamped = Math.max(0, Math.min(index, count - 1));
+      setActiveIndexRaw(clamped);
+      virtualizer?.scrollToIndex(clamped, { align: "auto" });
+    },
+    [count, virtualizer],
+  );
+
+  const onInputKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLInputElement>) => {
+      if (!isOpen) return;
+
+      switch (e.key) {
+        case "ArrowDown": {
+          e.preventDefault();
+          if (count === 0) return;
+          const next = findNext(filtered, activeIndex + 1);
+          if (next >= 0) setActiveIndex(next);
+          break;
+        }
+        case "ArrowUp": {
+          e.preventDefault();
+          if (count === 0) return;
+          const prev = findPrev(filtered, activeIndex - 1);
+          if (prev >= 0) setActiveIndex(prev);
+          break;
+        }
+        case "Home": {
+          e.preventDefault();
+          if (count === 0) return;
+          const first = findNext(filtered, 0);
+          setActiveIndex(first >= 0 ? first : 0);
+          break;
+        }
+        case "End": {
+          e.preventDefault();
+          if (count === 0) return;
+          const last = findPrev(filtered, filtered.length - 1);
+          setActiveIndex(last >= 0 ? last : 0);
+          break;
+        }
+        case "Enter": {
+          e.preventDefault();
+          if (count === 0) return;
+          const opt = filtered[activeIndex];
+          if (opt && !opt.disabled) {
+            onSelect(opt.value);
+          }
+          break;
+        }
+        // Escape is handled by Radix Popover (it closes the portal and
+        // returns focus to the trigger). No additional handling required here.
+        default:
+          break;
+      }
+    },
+    [isOpen, count, filtered, activeIndex, setActiveIndex, onSelect],
+  );
+
+  return { activeIndex, setActiveIndex, onInputKeyDown };
+}

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

@@ -0,0 +1,203 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { expect, userEvent, within } from "storybook/test";
+import { VirtualSelect } from "./virtual-select";
+import type { VirtualSelectOption } from "./virtual-select";
+
+// ---------------------------------------------------------------------------
+// Shared option sets
+// ---------------------------------------------------------------------------
+
+const SMALL_OPTIONS: VirtualSelectOption[] = [
+  { label: "Design", value: "design" },
+  { label: "Engineering", value: "engineering" },
+  { label: "Product", value: "product" },
+  { label: "Marketing", value: "marketing" },
+  { label: "Sales", value: "sales" },
+  { label: "Finance", value: "finance" },
+  { label: "Legal", value: "legal" },
+  { label: "HR", value: "hr" },
+  { label: "Operations", value: "operations" },
+  { label: "Support", value: "support" },
+  { label: "Analytics", value: "analytics" },
+  { label: "Infrastructure", value: "infrastructure" },
+  { label: "Security", value: "security" },
+  { label: "Data Science", value: "data-science" },
+  { label: "Research", value: "research" },
+  { label: "QA", value: "qa" },
+  { label: "DevRel", value: "devrel" },
+  { label: "Growth", value: "growth" },
+  { label: "Platform", value: "platform" },
+  { label: "Core Services", value: "core-services" },
+];
+
+/** Generate 10,000 options — the perf acceptance story. */
+const LARGE_OPTIONS: VirtualSelectOption[] = Array.from({ length: 10_000 }, (_, i) => ({
+  label: `Option ${i + 1} — ${["Alpha", "Beta", "Gamma", "Delta", "Epsilon"][i % 5]} Group`,
+  value: `opt-${i + 1}`,
+}));
+
+const OPTIONS_WITH_DISABLED: VirtualSelectOption[] = SMALL_OPTIONS.map((o, i) => ({
+  ...o,
+  disabled: i === 2 || i === 7, // "Product" and "HR" are disabled
+}));
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: "Forms/VirtualSelect",
+  component: VirtualSelect,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A combobox backed by `@tanstack/react-virtual` that renders only the visible window of options. Handles 10,000+ items without DOM bloat. Single or multiple selection; keyboard-navigable via `aria-activedescendant` while focus stays on the search input.",
+      },
+    },
+  },
+  argTypes: {
+    options: {
+      description:
+        "Full option list `{ label, value, disabled? }[]`. Only visible rows are in the DOM.",
+      control: false,
+      table: { category: "Content" },
+    },
+    multiple: {
+      description: "Allow selecting multiple values.",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    value: {
+      description: "Controlled value — `string` (single) or `string[]` (multiple).",
+      control: false,
+      table: { category: "State" },
+    },
+    defaultValue: {
+      description: "Uncontrolled initial value.",
+      control: false,
+      table: { category: "State" },
+    },
+    placeholder: {
+      description: "Trigger placeholder when nothing is selected.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    searchPlaceholder: {
+      description: "Search-input placeholder.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    emptyText: {
+      description: "Message shown when no options match the query.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    estimateOptionHeight: {
+      description: "Estimated row height in px used by the virtualizer (default 32).",
+      control: "number",
+      table: { category: "Behavior" },
+    },
+    maxListHeight: {
+      description: "CSS max-height for the scrollable listbox (default `18rem`).",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+    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 VirtualSelect>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Basic single-select with ~20 options. */
+export const Default: Story = {
+  args: {
+    options: SMALL_OPTIONS,
+    placeholder: "Select a department…",
+  },
+  // Regression lock: the virtualizer must measure once the Popover mounts the
+  // listbox, so opening the trigger renders options (not an empty listbox).
+  // Guards the state-backed-scroll-element fix; jsdom unit tests can't open the
+  // Radix portal, so this runs in the browser via test-storybook.
+  play: async ({ canvasElement }) => {
+    await userEvent.click(within(canvasElement).getByRole("combobox"));
+    const options = await within(document.body).findAllByRole("option");
+    await expect(options.length).toBeGreaterThan(0);
+  },
+};
+
+/**
+ * 10,000 generated options — the performance acceptance story.
+ * Acceptance criterion: the list opens instantly, scrolling is smooth (no jank),
+ * and the trigger + search filter still respond in < 16 ms.
+ * (Smooth scroll is not measurable in jsdom; verify visually in the browser.)
+ */
+export const LargeDataset: Story = {
+  args: {
+    options: LARGE_OPTIONS,
+    placeholder: "Select from 10,000 options…",
+    searchPlaceholder: "Filter 10,000 options…",
+  },
+};
+
+/** Multiple selection — controlled with chips and overflow badge. */
+export const Multiple: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [value, setValue] = useState<string[]>(["design", "engineering"]);
+    return (
+      <VirtualSelect
+        options={SMALL_OPTIONS}
+        multiple
+        value={value}
+        onValueChange={(v) => setValue(v as string[])}
+        placeholder="Select departments…"
+      />
+    );
+  },
+};
+
+/** Single-select with a pre-selected value via `defaultValue`. */
+export const Preselected: Story = {
+  args: {
+    options: SMALL_OPTIONS,
+    defaultValue: "product",
+    placeholder: "Select a department…",
+  },
+};
+
+/** Two options are disabled; they can be seen but not selected or focused. */
+export const DisabledOptions: Story = {
+  args: {
+    options: OPTIONS_WITH_DISABLED,
+    placeholder: "Select a department…",
+  },
+};
+
+/**
+ * Filtering to an empty result — the empty state renders `emptyText`.
+ * Type something like "zzz" in the search box to trigger it.
+ */
+export const Empty: Story = {
+  args: {
+    options: SMALL_OPTIONS,
+    placeholder: "Select a department…",
+    emptyText: "No departments match your search.",
+  },
+};

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

@@ -0,0 +1,106 @@
+/**
+ * VirtualSelect — unit tests.
+ *
+ * Scope: things reachable WITHOUT opening the Radix Popover portal in jsdom
+ * (Radix portals render outside the test container and are unreliable in jsdom).
+ *
+ * What is NOT tested here (covered by Storybook interaction tests + orchestrator
+ * a11y / visual review on the real rendered surface):
+ *   - Opening / closing the popover
+ *   - Search filtering while open
+ *   - Keyboard navigation (ArrowDown/Up/Enter/Escape) driving aria-activedescendant
+ *   - Virtualizer scroll behavior with 10,000 options
+ *   - Six-theme visual correctness
+ */
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { VirtualSelect } from "./virtual-select";
+import type { VirtualSelectOption } from "./virtual-select";
+
+const OPTIONS: VirtualSelectOption[] = [
+  { label: "Alpha", value: "alpha" },
+  { label: "Beta", value: "beta" },
+  { label: "Gamma", value: "gamma" },
+  { label: "Delta", value: "delta" },
+];
+
+// ---------------------------------------------------------------------------
+// Trigger ARIA
+// ---------------------------------------------------------------------------
+
+describe("VirtualSelect trigger", () => {
+  it("renders with role=combobox and aria-expanded=false when closed", () => {
+    render(<VirtualSelect options={OPTIONS} />);
+    const trigger = screen.getByRole("combobox");
+    expect(trigger).toBeInTheDocument();
+    expect(trigger).toHaveAttribute("aria-expanded", "false");
+    expect(trigger).toHaveAttribute("aria-haspopup", "listbox");
+  });
+
+  it("shows placeholder when no value is selected", () => {
+    render(<VirtualSelect options={OPTIONS} placeholder="Pick one" />);
+    expect(screen.getByText("Pick one")).toBeInTheDocument();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Single — controlled value
+// ---------------------------------------------------------------------------
+
+describe("VirtualSelect single mode", () => {
+  it("shows the selected option label on the trigger for a controlled value", () => {
+    render(<VirtualSelect options={OPTIONS} value="beta" />);
+    expect(screen.getByText("Beta")).toBeInTheDocument();
+  });
+
+  it("falls back to placeholder when controlled value is empty string", () => {
+    render(<VirtualSelect options={OPTIONS} value="" placeholder="Choose…" />);
+    expect(screen.getByText("Choose…")).toBeInTheDocument();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Multiple — chips + overflow
+// ---------------------------------------------------------------------------
+
+describe("VirtualSelect multiple mode", () => {
+  it("renders a Badge chip for each selected value (up to 2)", () => {
+    render(<VirtualSelect options={OPTIONS} multiple value={["alpha", "beta"]} />);
+    // Both values fit within the 2-chip window
+    expect(screen.getByText("Alpha")).toBeInTheDocument();
+    expect(screen.getByText("Beta")).toBeInTheDocument();
+  });
+
+  it("collapses overflow into a +N badge when more than 2 values are selected", () => {
+    render(<VirtualSelect options={OPTIONS} multiple value={["alpha", "beta", "gamma"]} />);
+    // First two chips visible
+    expect(screen.getByText("Alpha")).toBeInTheDocument();
+    expect(screen.getByText("Beta")).toBeInTheDocument();
+    // Third is collapsed
+    expect(screen.queryByText("Gamma")).not.toBeInTheDocument();
+    expect(screen.getByText("+1")).toBeInTheDocument();
+  });
+
+  it("shows +N = 2 when 4 values are selected", () => {
+    render(
+      <VirtualSelect options={OPTIONS} multiple value={["alpha", "beta", "gamma", "delta"]} />,
+    );
+    expect(screen.getByText("+2")).toBeInTheDocument();
+  });
+
+  it("shows placeholder when multiple=true and value=[]", () => {
+    render(<VirtualSelect options={OPTIONS} multiple value={[]} placeholder="Select items…" />);
+    expect(screen.getByText("Select items…")).toBeInTheDocument();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Uncontrolled defaultValue
+// ---------------------------------------------------------------------------
+
+describe("VirtualSelect defaultValue (uncontrolled)", () => {
+  it("shows the pre-selected label on mount", () => {
+    render(<VirtualSelect options={OPTIONS} defaultValue="gamma" />);
+    expect(screen.getByText("Gamma")).toBeInTheDocument();
+  });
+});