@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/surface-tour/surface-tour.tsx

@@ -0,0 +1,456 @@
+"use client";
+
+import {
+  forwardRef,
+  Suspense,
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from "react";
+import { Check, Copy } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { useCopyToClipboard } from "../../lib/use-copy-to-clipboard";
+import { isMotionAtFloor, readMotionFactor } from "../../lib/use-scroll-progress";
+import { Button } from "../button";
+import { Card } from "../card";
+import { CommandChip } from "../command-chip";
+import { RevealOnEnter } from "../reveal-on-enter";
+import { Skeleton } from "../skeleton";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "../tabs";
+
+// ─────────────────────────────── AffordanceHint ───────────────────────────────
+
+const HINT_DELAY_MS = 800;
+
+function hintSeen(key: string): boolean {
+  try {
+    return window.sessionStorage.getItem(key) === "1";
+  } catch {
+    return false;
+  }
+}
+
+function markHintSeen(key: string) {
+  try {
+    window.sessionStorage.setItem(key, "1");
+  } catch {
+    // Storage blocked (private mode, sandboxed iframe): the hint may show again. Harmless.
+  }
+}
+
+export interface AffordanceHintProps extends HTMLAttributes<HTMLSpanElement> {
+  /** `sessionStorage` key: once the hint has shown (or the visitor interacted), it never returns this session. */
+  storageKey: string;
+  /** ms after mount before the hint appears; skipped entirely when the motion gate is closed. Default 800. */
+  delay?: number;
+}
+
+/**
+ * A one-time visual nudge ("Drag a tile") pinned in the corner of its positioned parent. It
+ * appears `delay` ms after mounting (at once when motion is reduced), leaves on the first
+ * `pointerdown`/`keydown` inside that parent, and shows once per `storageKey` per session. It is
+ * `aria-hidden` — the surface it points at is accessible on its own; this is a visual cue only.
+ */
+export const AffordanceHint = forwardRef<HTMLSpanElement, AffordanceHintProps>(
+  function AffordanceHint(
+    { storageKey, delay = HINT_DELAY_MS, className, children, ...props },
+    ref,
+  ) {
+    const innerRef = useRef<HTMLSpanElement>(null);
+    useImperativeHandle(ref, () => innerRef.current as HTMLSpanElement, []);
+    const [visible, setVisible] = useState(false);
+
+    useEffect(() => {
+      const el = innerRef.current;
+      const host = el?.parentElement;
+      if (!el || !host || hintSeen(storageKey)) return;
+      const wait = isMotionAtFloor(readMotionFactor(el)) ? 0 : delay;
+      const timer = window.setTimeout(() => {
+        markHintSeen(storageKey);
+        setVisible(true);
+      }, wait);
+      const dismiss = () => {
+        window.clearTimeout(timer);
+        markHintSeen(storageKey);
+        setVisible(false);
+        host.removeEventListener("pointerdown", dismiss, true);
+        host.removeEventListener("keydown", dismiss, true);
+      };
+      host.addEventListener("pointerdown", dismiss, true);
+      host.addEventListener("keydown", dismiss, true);
+      return () => {
+        window.clearTimeout(timer);
+        host.removeEventListener("pointerdown", dismiss, true);
+        host.removeEventListener("keydown", dismiss, true);
+      };
+    }, [storageKey, delay]);
+
+    return (
+      <span
+        ref={innerRef}
+        aria-hidden="true"
+        data-slot="affordance-hint"
+        data-visible={visible ? "" : undefined}
+        className={cn(
+          "pointer-events-none absolute end-3 top-3 z-10 rounded-full bg-primary px-2.5 py-1 text-meta text-primary-foreground shadow-ring-sm transition-opacity duration-base ease-standard",
+          visible ? "opacity-100" : "opacity-0",
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </span>
+    );
+  },
+);
+
+// ───────────────────────────── SurfaceTourActions ─────────────────────────────
+
+/** Every string the actions row renders — pass your own to localize it. */
+export interface SurfaceTourActionsLabels {
+  openInStorybook: string;
+  copyPrompt: string;
+  promptCopied: string;
+  promptCopyFailed: string;
+  scaffold: string;
+  copyCommand: string;
+}
+
+export const DEFAULT_SURFACE_TOUR_ACTIONS_LABELS: SurfaceTourActionsLabels = {
+  openInStorybook: "Open in Storybook",
+  copyPrompt: "Copy prompt",
+  promptCopied: "Prompt copied",
+  promptCopyFailed: "Could not copy the prompt",
+  scaffold: "Scaffold",
+  copyCommand: "Copy scaffold command",
+};
+
+export interface SurfaceTourActionsProps extends HTMLAttributes<HTMLDivElement> {
+  /** Where "Open in Storybook" goes. Omit to hide the link. */
+  storybookHref?: string;
+  /** The (multi-line) prompt "Copy prompt" writes to the clipboard. Omit to hide the button. */
+  prompt?: string;
+  /** The scaffold command shown in a copyable chip. Omit to hide the chip. */
+  command?: string;
+  /** Override any rendered string. */
+  labels?: Partial<SurfaceTourActionsLabels>;
+}
+
+/** The per-surface actions row: open the story, copy an agent prompt, copy the scaffold command. */
+export const SurfaceTourActions = forwardRef<HTMLDivElement, SurfaceTourActionsProps>(
+  function SurfaceTourActions(
+    { storybookHref, prompt, command, labels: labelsProp, className, ...props },
+    ref,
+  ) {
+    const labels = { ...DEFAULT_SURFACE_TOUR_ACTIONS_LABELS, ...labelsProp };
+    const { copied, copy } = useCopyToClipboard();
+    const [failed, setFailed] = useState(false);
+
+    return (
+      <div
+        ref={ref}
+        data-slot="surface-tour-actions"
+        className={cn("flex min-w-0 flex-wrap items-center gap-2", className)}
+        {...props}
+      >
+        {storybookHref ? (
+          <Button asChild variant="outline" size="sm">
+            <a href={storybookHref} data-slot="surface-tour-actions-storybook">
+              {labels.openInStorybook}
+            </a>
+          </Button>
+        ) : null}
+        {prompt ? (
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            data-slot="surface-tour-actions-prompt"
+            data-copied={copied ? "" : undefined}
+            onClick={() => {
+              void copy(prompt).then((ok) => setFailed(!ok));
+            }}
+          >
+            {copied ? <Check aria-hidden="true" /> : <Copy aria-hidden="true" />}
+            {labels.copyPrompt}
+          </Button>
+        ) : null}
+        {command ? (
+          <span className="flex min-w-0 max-w-full items-center gap-2">
+            <span className="shrink-0 text-meta text-muted-foreground">{labels.scaffold}</span>
+            <CommandChip
+              className="min-w-0"
+              hosts={[{ id: "scaffold", label: labels.scaffold, command }]}
+              labels={{ copy: labels.copyCommand }}
+            />
+          </span>
+        ) : null}
+        <span role="status" aria-live="polite" className="sr-only">
+          {copied ? labels.promptCopied : failed ? labels.promptCopyFailed : ""}
+        </span>
+      </div>
+    );
+  },
+);
+
+// ───────────────────────────────── SurfaceTour ────────────────────────────────
+
+/** One surface in the tour. */
+export interface SurfaceTourTab {
+  /** Stable id — the tab value, the `#<hashKey>=<id>` deep link and the hint's session key. */
+  id: string;
+  /** Tab label. */
+  label: ReactNode;
+  /** One sentence under the frame saying what this surface is for. */
+  useCase?: ReactNode;
+  /** The actions row under the frame (typically a `SurfaceTourActions`). */
+  actions?: ReactNode;
+  /** Corner hint shown once per session when the surface first mounts. */
+  hint?: ReactNode;
+  /** Renders the surface. May suspend (a `React.lazy` or `next/dynamic` component). */
+  render: () => ReactNode;
+  /** Starts loading the surface's code; called on tab hover/focus, never on scroll. */
+  prefetch?: () => void;
+  /** Shown while the surface suspends. Default: a frame-filling `Skeleton`. */
+  fallback?: ReactNode;
+}
+
+export interface SurfaceTourProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  tabs: SurfaceTourTab[];
+  /** The tab shown first. Default: the first tab. */
+  defaultTab?: string;
+  /** Fires when the visitor picks another tab. */
+  onTabChange?: (id: string) => void;
+  /** Section heading. */
+  title?: ReactNode;
+  /** One sentence under the heading. */
+  description?: ReactNode;
+  /** When set, the active tab is read from and written to `#<hashKey>=<id>` (no history entries). */
+  hashKey?: string;
+  /** Classes for the frame — give it a height so every surface fills the same box. */
+  frameClassName?: string;
+}
+
+interface Layer {
+  id: string;
+  leaving: boolean;
+  entering: boolean;
+}
+
+/** Resolved `transition-duration` of `el` in ms (0 when motion is off or unmeasurable). */
+function transitionMs(el: Element | null): number {
+  if (!el || typeof window === "undefined") return 0;
+  const raw = window.getComputedStyle(el).transitionDuration.split(",")[0]?.trim() ?? "";
+  const value = parseFloat(raw);
+  if (!Number.isFinite(value)) return 0;
+  return raw.endsWith("ms") ? value : value * 1000;
+}
+
+function readHash(hashKey: string): string | null {
+  const match = new RegExp(`^#${hashKey}=([^&]+)$`).exec(window.location.hash);
+  return match?.[1] ? decodeURIComponent(match[1]) : null;
+}
+
+/**
+ * A tour of full-size surfaces behind a sticky tab strip. The frame stays put while the
+ * surfaces crossfade (`--t-base`, instant under reduced motion); the frame's min-height only
+ * ever grows, so switching never jumps the page. Surfaces mount on first selection and may
+ * suspend (lazy code) behind a `Skeleton`; `prefetch` runs on hover/focus of a tab. The sticky
+ * offset is the `--surface-tour-sticky-top` custom property (set it to your nav height).
+ */
+export const SurfaceTour = forwardRef<HTMLElement, SurfaceTourProps>(function SurfaceTour(
+  {
+    tabs,
+    defaultTab,
+    onTabChange,
+    title,
+    description,
+    hashKey,
+    frameClassName,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const rootRef = useRef<HTMLElement>(null);
+  useImperativeHandle(ref, () => rootRef.current as HTMLElement, []);
+  const titleId = useId();
+  const initial = tabs.find((t) => t.id === defaultTab)?.id ?? tabs[0]?.id ?? "";
+  const [active, setActive] = useState(initial);
+  const [layers, setLayers] = useState<Layer[]>([{ id: initial, leaving: false, entering: false }]);
+  const frameRef = useRef<HTMLDivElement>(null);
+  const prefetched = useRef(new Set<string>());
+
+  const prefetch = useCallback((tab: SurfaceTourTab) => {
+    if (!tab.prefetch || prefetched.current.has(tab.id)) return;
+    prefetched.current.add(tab.id);
+    tab.prefetch();
+  }, []);
+
+  const select = useCallback(
+    (id: string, { fromHash = false } = {}) => {
+      if (id === active || !tabs.some((t) => t.id === id)) return;
+      setLayers([
+        { id: active, leaving: true, entering: false },
+        { id, leaving: false, entering: !fromHash },
+      ]);
+      setActive(id);
+      if (hashKey && !fromHash && typeof window !== "undefined") {
+        const { pathname, search } = window.location;
+        window.history.replaceState(
+          window.history.state,
+          "",
+          `${pathname}${search}#${hashKey}=${encodeURIComponent(id)}`,
+        );
+      }
+      onTabChange?.(id);
+    },
+    [active, tabs, hashKey, onTabChange],
+  );
+
+  // Deep link: `#<hashKey>=<id>` opens that tab on load (a browser-only read, once).
+  useEffect(() => {
+    if (!hashKey) return;
+    const id = readHash(hashKey);
+    if (id && tabs.some((t) => t.id === id)) {
+      select(id, { fromHash: true });
+      rootRef.current?.scrollIntoView({ block: "start" });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only read of the URL
+  }, []);
+
+  // The outgoing surface unmounts once the fade (the frame's resolved `--t-base`) is over.
+  useEffect(() => {
+    if (!layers.some((l) => l.leaving)) return;
+    const ms = transitionMs(frameRef.current?.querySelector("[data-leaving]") ?? null);
+    const done = () => setLayers((current) => current.filter((l) => !l.leaving));
+    if (ms <= 1) {
+      done();
+      return;
+    }
+    const timer = window.setTimeout(done, ms);
+    return () => window.clearTimeout(timer);
+  }, [layers]);
+
+  // Height lock: the frame's min-height ratchets up to the tallest surface seen.
+  useEffect(() => {
+    const frame = frameRef.current;
+    if (!frame || typeof ResizeObserver !== "function") return;
+    let tallest = 0;
+    const observer = new ResizeObserver(() => {
+      const height = frame.getBoundingClientRect().height;
+      if (height > tallest) {
+        tallest = height;
+        frame.style.minHeight = `${Math.ceil(height)}px`;
+      }
+    });
+    observer.observe(frame);
+    return () => observer.disconnect();
+  }, []);
+
+  const activeTab = tabs.find((t) => t.id === active);
+
+  return (
+    <section
+      ref={rootRef}
+      data-slot="surface-tour"
+      aria-labelledby={title ? titleId : undefined}
+      className={cn("flex w-full min-w-0 flex-col gap-6", className)}
+      {...props}
+    >
+      {title || description ? (
+        <RevealOnEnter as="header" data-slot="surface-tour-header" className="flex flex-col gap-2">
+          {title ? (
+            <h2 id={titleId} className="text-display text-foreground">
+              {title}
+            </h2>
+          ) : null}
+          {description ? <p className="text-body text-muted-foreground">{description}</p> : null}
+        </RevealOnEnter>
+      ) : null}
+      <Tabs
+        value={active}
+        onValueChange={(id) => select(id)}
+        className="flex min-w-0 flex-col gap-4"
+      >
+        <div
+          data-slot="surface-tour-tabs"
+          className={cn(
+            "sticky z-20 bg-background py-2",
+            // Overflow affordance on narrow screens: the strip scrolls, the end edge fades.
+            "max-md:after:pointer-events-none max-md:after:absolute max-md:after:inset-y-0 max-md:after:end-0 max-md:after:w-10 max-md:after:from-background ltr:max-md:after:bg-linear-to-l rtl:max-md:after:bg-linear-to-r",
+          )}
+          style={{ top: "var(--surface-tour-sticky-top, 0px)" }}
+        >
+          <TabsList className="w-full justify-start md:w-auto">
+            {tabs.map((tab) => (
+              <TabsTrigger
+                key={tab.id}
+                value={tab.id}
+                onPointerEnter={() => prefetch(tab)}
+                onFocus={() => prefetch(tab)}
+              >
+                {tab.label}
+              </TabsTrigger>
+            ))}
+          </TabsList>
+        </div>
+        <Card
+          ref={frameRef}
+          data-slot="surface-tour-frame"
+          className={cn("relative grid min-h-96 overflow-hidden p-0 shadow-md", frameClassName)}
+        >
+          {tabs.map((tab) => {
+            const layer = layers.find((l) => l.id === tab.id);
+            return (
+              <TabsContent
+                key={tab.id}
+                value={tab.id}
+                forceMount
+                hidden={!layer}
+                inert={layer?.leaving || undefined}
+                aria-hidden={layer?.leaving || undefined}
+                data-leaving={layer?.leaving ? "" : undefined}
+                className={cn(
+                  "relative col-start-1 row-start-1 mt-0 min-h-0 min-w-0 transition-opacity duration-base ease-standard",
+                  layer?.leaving && "pointer-events-none opacity-0",
+                  layer?.entering && "starting:opacity-0",
+                )}
+              >
+                {layer ? (
+                  <>
+                    <Suspense
+                      fallback={tab.fallback ?? <Skeleton className="size-full min-h-96" />}
+                    >
+                      {tab.render()}
+                    </Suspense>
+                    {tab.hint && !layer.leaving ? (
+                      <AffordanceHint
+                        storageKey={`surface-tour-hint:${hashKey ?? "tour"}:${tab.id}`}
+                      >
+                        {tab.hint}
+                      </AffordanceHint>
+                    ) : null}
+                  </>
+                ) : null}
+              </TabsContent>
+            );
+          })}
+        </Card>
+        {activeTab?.useCase || activeTab?.actions ? (
+          <div data-slot="surface-tour-footer" className="flex min-w-0 flex-col gap-3">
+            {activeTab.useCase ? (
+              <p className="text-body text-muted-foreground">{activeTab.useCase}</p>
+            ) : null}
+            {activeTab.actions}
+          </div>
+        ) : null}
+      </Tabs>
+    </section>
+  );
+});

package/src/components/switch/switch.tsx

@@ -9,6 +9,7 @@ export const Switch = forwardRef<
   return (
     <SwitchPrimitive.Root
       ref={ref}
+      data-slot="switch"
       className={cn(
         "peer inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent shadow-sm transition-colors duration-fast ease-standard",
         "focus-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
@@ -19,6 +20,7 @@ export const Switch = forwardRef<
       {...props}
     >
       <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
         className={cn(
           "pointer-events-none block size-4 rounded-full bg-background shadow-xs ring-0 transition-transform duration-fast ease-standard",
           "data-[state=checked]:translate-x-4 data-[state=unchecked]:translate-x-0",

package/src/components/table/table.stories.tsx

@@ -104,7 +104,9 @@ export const Scrolling: Story = {
     });
     await expect(scrollRegion).toHaveAttribute("tabindex", "0");
     await expect(scrollRegion).toHaveAccessibleName("Table contents, scrollable");
-    await expect(scrollRegion).not.toHaveAttribute("role");
+    // A named, non-landmark stop: `group`, never `region` (a landmark per
+    // overflowing table collides under axe `landmark-unique`).
+    await expect(scrollRegion).toHaveAttribute("role", "group");
 
     // The region is the only focusable element the story renders, so a
     // single Tab from nothing focused reaches it — the real WCAG 2.1.1

package/src/components/table/table.test.tsx

@@ -136,7 +136,7 @@ describe("Table — #366 the scroll wrapper's tab stop exists only while it meas
     expect(scrollRegion).not.toHaveAttribute("tabindex");
   });
 
-  it('never adds a redundant role="region" landmark', () => {
+  it('adds role="group" once it overflows — a named, non-landmark stop', () => {
     const { container } = render(
       <Table>
         <TableBody>
@@ -147,12 +147,19 @@ describe("Table — #366 the scroll wrapper's tab stop exists only while it meas
       </Table>,
     );
     const scrollRegion = scrollRegionOf(container);
+    // `aria-label` on a plain `<div>` (role `generic`) is not guaranteed to
+    // produce an accessible name at all, so the overflowing stop needs a
+    // naming-capable role — `group`, never the `region` landmark, which would
+    // collide (axe `landmark-unique`) as soon as two tables overflow on a page.
+    expect(scrollRegion).not.toHaveAttribute("role");
     setScrollMetrics(scrollRegion, {
       scrollWidth: 300,
       clientWidth: 300,
       scrollHeight: 800,
       clientHeight: 200,
     });
-    expect(scrollRegion).not.toHaveAttribute("role");
+    expect(scrollRegion).toHaveAttribute("role", "group");
+    expect(screen.queryByRole("region")).toBeNull();
+    expect(screen.getByRole("group", { name: "Table contents, scrollable" })).toBe(scrollRegion);
   });
 });

package/src/components/table/table.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import {
   forwardRef,
   useCallback,
@@ -23,13 +25,20 @@ import { useLocale } from "../locale-provider";
  * affordance itself.
  *
  * A table that FITS must stay a byte-identical no-op: no `tabIndex`, no
- * `aria-label`, no ring — an unconditional stop would announce "scrollable"
- * on content that never scrolls. Only a table that measurably overflows
- * gets the tab stop, its accessible name (WCAG 4.1.2) and the compound focus
- * ring (`focus-ring-inset` — the wrapper's own edge is the scroll clip, so an
- * outside ring would be cut, `.claude/rules/theming.md`). No `role="region"`:
- * both existing precedents (`DataTable`, `SheetTable`) decided against a
- * redundant landmark over a real `<table>`, and this wrapper adds none either.
+ * `aria-label`, no `role`, no ring — an unconditional stop would announce
+ * "scrollable" on content that never scrolls. Only a table that measurably
+ * overflows gets the tab stop, its accessible name (WCAG 4.1.2) and the
+ * compound focus ring (`focus-ring-inset` — the wrapper's own edge is the
+ * scroll clip, so an outside ring would be cut, `.claude/rules/theming.md`).
+ *
+ * A naming-capable role is REQUIRED alongside that `aria-label`: `aria-label`
+ * on a plain `<div>` (role `generic`) is prohibited by ARIA 1.2 and not
+ * guaranteed to compute into a name, so `tabIndex={0}` alone would make an
+ * UNNAMED stop. That role is `group`, NOT `region`: `region` is a landmark,
+ * and every overflowing table on a page would add one more landmark with the
+ * same name (axe `landmark-unique`) over a real `<table>` that already has
+ * its own semantics. `group` names the stop without joining landmark
+ * navigation — the no-redundant-landmark call `DataTable` made first (#330).
  */
 export const Table = forwardRef<HTMLTableElement, HTMLAttributes<HTMLTableElement>>(function Table(
   { className, ...props },
@@ -67,6 +76,7 @@ export const Table = forwardRef<HTMLTableElement, HTMLAttributes<HTMLTableElemen
       ref={scrollRef}
       data-slot="table-scroll-region"
       tabIndex={scrollOverflows ? 0 : undefined}
+      role={scrollOverflows ? "group" : undefined}
       aria-label={scrollOverflows ? t("ui.table.scrollRegion") : undefined}
       onScroll={updateScrollAffordance}
       className="relative w-full overflow-auto focus-ring-inset"
@@ -124,7 +134,7 @@ export const TableRow = forwardRef<HTMLTableRowElement, HTMLAttributes<HTMLTable
           // alternation on the plain Table primitive). Decision test: "If
           // deleted, could a sighted user still tell the two rows apart?" No
           // (no fill change) → load-bearing → border-strong.
-          "border-b border-border-strong transition-colors duration-fast ease-standard hover:bg-surface-muted/50 data-[state=selected]:bg-accent",
+          "border-b border-border-strong transition-colors duration-fast ease-standard hover:bg-surface-muted/50 data-[state=selected]:bg-selection",
           className,
         )}
         {...props}
@@ -138,7 +148,10 @@ export const TableHead = forwardRef<HTMLTableCellElement, ThHTMLAttributes<HTMLT
       <th
         ref={ref}
         className={cn(
-          "h-10 px-3 text-start align-middle font-medium text-muted-foreground",
+          // Table-header seams (fidelity review #4): every default equals
+          // today's byte-identical rendering — see the matching comment on
+          // `DataTable`'s `<th>` (packages/data/src/data-table/data-table.tsx).
+          "h-10 px-3 text-start align-middle font-table-header bg-table-header-background text-table-header-foreground text-table-header tracking-(--table-header-tracking) [text-transform:var(--table-header-transform)]",
           className,
         )}
         {...props}

package/src/components/tabs/index.ts

@@ -1 +1,10 @@
-export { Tabs, TabsList, TabsTrigger, TabsContent } from "./tabs";
+export {
+  Tabs,
+  TabsList,
+  TabsTrigger,
+  TabsContent,
+  tabsListVariants,
+  tabsTriggerVariants,
+  type TabsListProps,
+  type TabsVariant,
+} from "./tabs";