@elabs-ai/components-ui 4.0.0

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

@@ -0,0 +1,361 @@
+// a2ui.exposed: yes
+"use client";
+
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type KeyboardEvent,
+} from "react";
+import { Check, ChevronsUpDown } from "lucide-react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { cn } from "../../lib/cn";
+import { Badge } from "../badge";
+import { Button } from "../button";
+import { Input } from "../input";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+import { type VirtualSelectOption, useVirtualListbox } from "./use-virtual-listbox";
+
+export type { VirtualSelectOption };
+
+export interface VirtualSelectProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "value" | "onChange" | "defaultValue"
+> {
+  /** The full option list. Only visible items are rendered in the DOM. */
+  options: VirtualSelectOption[];
+  /** Allow selecting multiple values. Default `false`. */
+  multiple?: boolean;
+  /** Controlled value — `string` in single mode, `string[]` in multiple mode. */
+  value?: string | string[];
+  /** Uncontrolled initial value. */
+  defaultValue?: string | string[];
+  /** Called when the selection changes. Emits `string` (single) or `string[]` (multiple). */
+  onValueChange?: (value: string | string[]) => void;
+  /** Trigger placeholder when nothing is selected. Default "Select…" */
+  placeholder?: string;
+  /** Search-input placeholder. Default "Search…" */
+  searchPlaceholder?: string;
+  /** Empty-state message when no options match the query. Default "No results." */
+  emptyText?: string;
+  /**
+   * Estimated row height used by the virtualizer (px).
+   * Increase for taller rows (e.g. with descriptions). Default 32.
+   */
+  estimateOptionHeight?: number;
+  /**
+   * CSS max-height for the scrollable listbox. Default "18rem".
+   */
+  maxListHeight?: string;
+  className?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function toArray(v: string | string[] | undefined): string[] {
+  if (v === undefined) return [];
+  if (Array.isArray(v)) return v;
+  return v === "" ? [] : [v];
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+/**
+ * VirtualSelect — a combobox that renders only the visible window of options
+ * in the DOM, making it suitable for option lists of 10,000+ items.
+ *
+ * Uses `@tanstack/react-virtual` for windowed rendering and a purpose-built
+ * `aria-activedescendant` keyboard model so focus stays on the search input
+ * while navigating the listbox.
+ */
+export const VirtualSelect = forwardRef<HTMLButtonElement, VirtualSelectProps>(
+  function VirtualSelect(
+    {
+      options,
+      multiple = false,
+      value,
+      defaultValue,
+      onValueChange,
+      placeholder = "Select…",
+      searchPlaceholder = "Search…",
+      emptyText = "No results.",
+      estimateOptionHeight = 32,
+      maxListHeight = "18rem",
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    // ------------------------------------------------------------------
+    // Controlled / uncontrolled
+    // ------------------------------------------------------------------
+    const isControlled = value !== undefined;
+    const [internal, setInternal] = useState<string[]>(() => toArray(defaultValue));
+    const selected: string[] = isControlled ? toArray(value) : internal;
+
+    const emit = useCallback(
+      (next: string[]) => {
+        if (!isControlled) setInternal(next);
+        if (multiple) {
+          onValueChange?.(next);
+        } else {
+          onValueChange?.(next[0] ?? "");
+        }
+      },
+      [isControlled, multiple, onValueChange],
+    );
+
+    // ------------------------------------------------------------------
+    // Popover state
+    // ------------------------------------------------------------------
+    const [open, setOpen] = useState(false);
+
+    // ------------------------------------------------------------------
+    // Search / filter
+    // ------------------------------------------------------------------
+    const [query, setQuery] = useState("");
+    const searchRef = useRef<HTMLInputElement>(null);
+
+    // Reset query when popover toggles
+    useEffect(() => {
+      setQuery("");
+    }, [open]);
+
+    const filtered = useMemo(
+      () => options.filter((o) => o.label.toLowerCase().includes(query.toLowerCase())),
+      [options, query],
+    );
+
+    // ------------------------------------------------------------------
+    // Virtualizer
+    // ------------------------------------------------------------------
+    // State-backed scroll element (NOT a ref): the listbox mounts only when the
+    // Popover opens, so a plain ref would leave the virtualizer with a null
+    // scroll element and render zero options. A state callback ref forces the
+    // re-render that lets the virtualizer measure once the element appears.
+    const [scrollEl, setScrollEl] = useState<HTMLDivElement | null>(null);
+    const virtualizer = useVirtualizer({
+      count: filtered.length,
+      getScrollElement: () => scrollEl,
+      estimateSize: () => estimateOptionHeight,
+      overscan: 5,
+    });
+
+    // ------------------------------------------------------------------
+    // Keyboard navigation
+    // ------------------------------------------------------------------
+    const handleSelect = useCallback(
+      (optValue: string) => {
+        if (multiple) {
+          const next = selected.includes(optValue)
+            ? selected.filter((v) => v !== optValue)
+            : [...selected, optValue];
+          emit(next);
+          // Keep open in multi mode
+        } else {
+          emit(selected[0] === optValue ? [] : [optValue]);
+          setOpen(false);
+        }
+      },
+      [multiple, selected, emit],
+    );
+
+    const { activeIndex, setActiveIndex, onInputKeyDown } = useVirtualListbox({
+      count: filtered.length,
+      filtered,
+      isOpen: open,
+      onSelect: handleSelect,
+      virtualizer,
+    });
+
+    // ------------------------------------------------------------------
+    // IDs for ARIA wiring
+    // ------------------------------------------------------------------
+    const uid = useId();
+    const listboxId = `${uid}-listbox`;
+    const optionId = (index: number) => `${uid}-option-${index}`;
+
+    // Focus the search input when the popover opens
+    const handleOpenChange = useCallback((next: boolean) => {
+      setOpen(next);
+      if (next) {
+        // Defer one frame so Radix has mounted the portal
+        setTimeout(() => searchRef.current?.focus(), 0);
+      }
+    }, []);
+
+    // ------------------------------------------------------------------
+    // Trigger label
+    // ------------------------------------------------------------------
+    const selectedLabels = selected.map((v) => {
+      const opt = options.find((o) => o.value === v);
+      return { value: v, label: opt?.label ?? v };
+    });
+
+    const triggerContent =
+      selectedLabels.length === 0 ? (
+        <span className="text-muted-foreground">{placeholder}</span>
+      ) : multiple ? (
+        <>
+          {selectedLabels.slice(0, 2).map((l) => (
+            <Badge
+              key={l.value}
+              variant="secondary"
+              className="max-w-[8rem] truncate border-border"
+            >
+              {l.label}
+            </Badge>
+          ))}
+          {selectedLabels.length > 2 ? (
+            <Badge
+              variant="secondary"
+              aria-label={`and ${selectedLabels.length - 2} more selected`}
+            >
+              +{selectedLabels.length - 2}
+            </Badge>
+          ) : null}
+        </>
+      ) : (
+        <span className="truncate">{selectedLabels[0]?.label}</span>
+      );
+
+    // ------------------------------------------------------------------
+    // Render
+    // ------------------------------------------------------------------
+    const virtualItems = virtualizer.getVirtualItems();
+    // Only reference the active option from aria-activedescendant when it is
+    // actually mounted in the virtual window (else the id would dangle).
+    const activeMounted = virtualItems.some((v) => v.index === activeIndex);
+
+    return (
+      <Popover open={open} onOpenChange={handleOpenChange}>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            type="button"
+            variant="outline"
+            role="combobox"
+            aria-expanded={open}
+            aria-haspopup="listbox"
+            aria-controls={listboxId}
+            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">
+              {triggerContent}
+            </span>
+            <ChevronsUpDown className="ms-2 size-4 shrink-0 opacity-50" aria-hidden="true" />
+          </Button>
+        </PopoverTrigger>
+
+        <PopoverContent
+          className="w-64 p-0"
+          align="start"
+          // Prevent Radix from stealing focus so it can go to the input
+          onOpenAutoFocus={(e) => e.preventDefault()}
+        >
+          {/* Search input */}
+          <div className="border-b p-1.5">
+            <Input
+              ref={searchRef}
+              type="text"
+              autoComplete="off"
+              spellCheck={false}
+              placeholder={searchPlaceholder}
+              value={query}
+              onChange={(e) => setQuery(e.target.value)}
+              onKeyDown={(e: KeyboardEvent<HTMLInputElement>) => onInputKeyDown(e)}
+              aria-label={searchPlaceholder}
+              aria-autocomplete="list"
+              aria-controls={listboxId}
+              aria-activedescendant={
+                activeIndex >= 0 && activeMounted ? optionId(activeIndex) : undefined
+              }
+              className="h-8 border-0 shadow-none focus-visible:ring-0 focus-visible:ring-offset-0"
+            />
+          </div>
+
+          {/* Listbox — always mounted so aria-controls never dangles (even when empty) */}
+          <div
+            ref={setScrollEl}
+            id={listboxId}
+            role="listbox"
+            aria-multiselectable={multiple || undefined}
+            style={{ maxHeight: maxListHeight }}
+            className="overflow-auto p-1"
+          >
+            {filtered.length > 0 ? (
+              // Spacer gives the virtualizer its full scroll height
+              <div style={{ height: virtualizer.getTotalSize() }} className="relative">
+                {virtualItems.map((virtualRow) => {
+                  const opt = filtered[virtualRow.index];
+                  if (!opt) return null;
+                  const isSelected = selected.includes(opt.value);
+                  const isActive = activeIndex === virtualRow.index;
+
+                  return (
+                    <div
+                      key={virtualRow.key}
+                      id={optionId(virtualRow.index)}
+                      role="option"
+                      aria-selected={isSelected}
+                      aria-disabled={opt.disabled || undefined}
+                      style={{
+                        position: "absolute",
+                        top: 0,
+                        left: 0,
+                        width: "100%",
+                        height: `${virtualRow.size}px`,
+                        transform: `translateY(${virtualRow.start}px)`,
+                      }}
+                      className={cn(
+                        "flex cursor-pointer select-none items-center rounded-sm px-2 text-sm outline-none",
+                        "transition-colors duration-fast motion-reduce:transition-none",
+                        isActive && "bg-accent text-accent-foreground",
+                        !isActive && "hover:bg-accent hover:text-accent-foreground",
+                        opt.disabled && "pointer-events-none cursor-not-allowed opacity-50",
+                      )}
+                      onClick={() => {
+                        if (!opt.disabled) handleSelect(opt.value);
+                      }}
+                      onMouseEnter={() => {
+                        if (!opt.disabled) setActiveIndex(virtualRow.index);
+                      }}
+                    >
+                      <Check
+                        className={cn(
+                          "me-2 size-4 shrink-0",
+                          isSelected ? "opacity-100" : "opacity-0",
+                        )}
+                        aria-hidden="true"
+                      />
+                      <span className="truncate">{opt.label}</span>
+                    </div>
+                  );
+                })}
+              </div>
+            ) : null}
+          </div>
+          {filtered.length === 0 ? (
+            <div
+              role="status"
+              aria-live="polite"
+              className="px-2 py-6 text-center text-sm text-muted-foreground"
+            >
+              {emptyText}
+            </div>
+          ) : null}
+        </PopoverContent>
+      </Popover>
+    );
+  },
+);

package/src/components/wizard/index.ts

@@ -0,0 +1,12 @@
+export {
+  Wizard,
+  WizardSteps,
+  WizardStep,
+  WizardNav,
+  type WizardProps,
+  type WizardStepsProps,
+  type WizardStepProps,
+  type WizardNavProps,
+  type WizardStepMeta,
+  type WizardValidator,
+} from "./wizard";

package/src/components/wizard/wizard.stories.tsx

@@ -0,0 +1,148 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, waitFor, within } from "storybook/test";
+import { useState } from "react";
+import { Wizard, WizardSteps, WizardStep, WizardNav, type WizardStepMeta } from "./wizard";
+
+const meta = {
+  title: "Navigation/Wizard",
+  component: Wizard,
+  tags: ["autodocs"],
+  argTypes: {
+    steps: {
+      description: "Ordered step metadata (id, title, description) shown in the step indicator.",
+      control: false,
+      table: { category: "Data" },
+    },
+    step: {
+      description: "Controlled active step index (0-based).",
+      control: "number",
+      table: { category: "State" },
+    },
+    defaultStep: {
+      description: "Uncontrolled initial step index. Default 0.",
+      control: "number",
+      table: { category: "State" },
+    },
+    onStepChange: {
+      description: "Callback fired when the active step changes.",
+      control: false,
+      table: { category: "Events" },
+    },
+    orientation: {
+      description: "Layout direction for the step indicator and content.",
+      control: { type: "radio" },
+      options: ["horizontal", "vertical"],
+      table: { category: "Layout" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the wizard root.",
+      control: "text",
+      table: { category: "Styling" },
+    },
+    children: {
+      description: "WizardSteps, WizardStep panels, and WizardNav composed inside.",
+      control: false,
+      table: { category: "Content" },
+    },
+  },
+} satisfies Meta<typeof Wizard>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const steps: WizardStepMeta[] = [
+  { id: "account", title: "Account", description: "Login details" },
+  { id: "profile", title: "Profile", description: "About you" },
+  { id: "review", title: "Review", description: "Confirm" },
+];
+
+const Panel = ({ children }: { children: React.ReactNode }) => (
+  <div className="rounded-md border border-border bg-card p-4 text-card-foreground">{children}</div>
+);
+
+export const Default: Story = {
+  render: () => (
+    <Wizard steps={steps} className="max-w-xl">
+      <WizardSteps />
+      <WizardStep step={0}>
+        <Panel>Step 1 — account details.</Panel>
+      </WizardStep>
+      <WizardStep step={1}>
+        <Panel>Step 2 — profile details.</Panel>
+      </WizardStep>
+      <WizardStep step={2}>
+        <Panel>Step 3 — review and confirm.</Panel>
+      </WizardStep>
+      <WizardNav onFinish={() => alert("Finished!")} />
+    </Wizard>
+  ),
+  // Advances through all three steps via Next, then asserts the Finish button
+  // appears on the last step and Back brings us back one step.
+  play: async ({ canvasElement, userEvent }) => {
+    const canvas = within(canvasElement);
+    // Step 1 is visible
+    await waitFor(() => expect(canvas.getByText("Step 1 — account details.")).toBeVisible());
+    // Advance to step 2
+    await userEvent.click(canvas.getByRole("button", { name: /next/i }));
+    await waitFor(() => expect(canvas.getByText("Step 2 — profile details.")).toBeVisible());
+    // Advance to step 3
+    await userEvent.click(canvas.getByRole("button", { name: /next/i }));
+    await waitFor(() => expect(canvas.getByText("Step 3 — review and confirm.")).toBeVisible());
+    // On the last step, "Finish" replaces "Next"
+    await waitFor(() => expect(canvas.getByRole("button", { name: /finish/i })).toBeVisible());
+    // Back returns to step 2
+    await userEvent.click(canvas.getByRole("button", { name: /back/i }));
+    await waitFor(() => expect(canvas.getByText("Step 2 — profile details.")).toBeVisible());
+  },
+};
+
+export const Vertical: Story = {
+  render: () => (
+    <Wizard steps={steps} orientation="vertical" className="max-w-2xl">
+      <WizardSteps />
+      <div className="flex flex-1 flex-col gap-4">
+        <WizardStep step={0}>
+          <Panel>Account details.</Panel>
+        </WizardStep>
+        <WizardStep step={1}>
+          <Panel>Profile details.</Panel>
+        </WizardStep>
+        <WizardStep step={2}>
+          <Panel>Review.</Panel>
+        </WizardStep>
+        <WizardNav />
+      </div>
+    </Wizard>
+  ),
+};
+
+export const WithValidationGating: Story = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const [agreed, setAgreed] = useState(false);
+    return (
+      <Wizard steps={steps} className="max-w-xl">
+        <WizardSteps />
+        <WizardStep step={0} validate={() => agreed}>
+          <Panel>
+            <label className="flex items-center gap-2">
+              <input
+                type="checkbox"
+                checked={agreed}
+                onChange={(e) => setAgreed(e.target.checked)}
+              />
+              I agree to continue (Next is blocked until checked).
+            </label>
+          </Panel>
+        </WizardStep>
+        <WizardStep step={1}>
+          <Panel>Profile details.</Panel>
+        </WizardStep>
+        <WizardStep step={2}>
+          <Panel>Review.</Panel>
+        </WizardStep>
+        <WizardNav />
+      </Wizard>
+    );
+  },
+};

package/src/components/wizard/wizard.test.tsx

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { Wizard, WizardSteps, WizardStep, WizardNav, type WizardStepMeta } from "./wizard";
+
+const steps: WizardStepMeta[] = [
+  { id: "a", title: "Account" },
+  { id: "b", title: "Profile" },
+  { id: "c", title: "Review" },
+];
+
+function renderWizard(extra?: { validate?: () => boolean | Promise<boolean> }) {
+  return render(
+    <Wizard steps={steps}>
+      <WizardSteps />
+      <WizardStep step={0} validate={extra?.validate}>
+        <p>Account content</p>
+      </WizardStep>
+      <WizardStep step={1}>
+        <p>Profile content</p>
+      </WizardStep>
+      <WizardStep step={2}>
+        <p>Review content</p>
+      </WizardStep>
+      <WizardNav />
+    </Wizard>,
+  );
+}
+
+describe("Wizard", () => {
+  it("shows only the active step's content and marks the indicator", () => {
+    renderWizard();
+    expect(screen.getByText("Account content")).toBeInTheDocument();
+    expect(screen.queryByText("Profile content")).not.toBeInTheDocument();
+    expect(screen.getByRole("listitem", { current: "step" })).toHaveTextContent("Account");
+  });
+
+  it("advances and goes back", async () => {
+    const user = userEvent.setup();
+    renderWizard();
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    expect(screen.getByText("Profile content")).toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "Back" }));
+    expect(screen.getByText("Account content")).toBeInTheDocument();
+  });
+
+  it("disables Back on the first step", () => {
+    renderWizard();
+    expect(screen.getByRole("button", { name: "Back" })).toBeDisabled();
+  });
+
+  it("blocks advance when validate returns false", async () => {
+    const user = userEvent.setup();
+    renderWizard({ validate: () => false });
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    expect(screen.getByText("Account content")).toBeInTheDocument();
+    expect(screen.queryByText("Profile content")).not.toBeInTheDocument();
+  });
+
+  it("shows Finish on the last step", async () => {
+    const user = userEvent.setup();
+    renderWizard();
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    await waitFor(() => expect(screen.getByRole("button", { name: "Finish" })).toBeInTheDocument());
+  });
+});