@elabs-ai/components-ui 4.0.0

package/src/lib/use-copy-to-clipboard.ts

@@ -0,0 +1,75 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** How long the transient "copied" state stays true before it resets. */
+export const COPY_FEEDBACK_MS = 1500;
+
+export interface UseCopyToClipboardOptions {
+  /** ms the `copied` flag stays true. Default: {@link COPY_FEEDBACK_MS}. */
+  resetAfterMs?: number;
+}
+
+export interface CopyToClipboard {
+  /** True for `resetAfterMs` after a successful copy. */
+  copied: boolean;
+  /** Writes `text` to the clipboard. Resolves `false` when it could not. */
+  copy: (text: string) => Promise<boolean>;
+}
+
+/**
+ * Copy-to-clipboard with a transient confirmation flag.
+ *
+ * One implementation for the whole library — the copy button in
+ * `@elabs-ai/components-editor` and `CopyableValue` share it, so the
+ * timing, the unmount cleanup and the "no clipboard here" answer are defined
+ * once instead of re-derived per component.
+ *
+ * `navigator.clipboard` is absent under SSR, in jsdom, and in any insecure
+ * (non-`https`, non-`localhost`) context. That is reported as `false` rather
+ * than thrown: a copy affordance failing is a papercut, not a crash, and the
+ * caller decides whether to say anything about it. The deprecated
+ * `document.execCommand("copy")` fallback is deliberately not used.
+ */
+export function useCopyToClipboard(options?: UseCopyToClipboardOptions): CopyToClipboard {
+  const resetAfterMs = options?.resetAfterMs ?? COPY_FEEDBACK_MS;
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // A component that unmounts inside the feedback window must not have its
+  // state set afterwards, and a second copy must restart the window, not race
+  // the first one's reset.
+  useEffect(
+    () => () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+      }
+    },
+    [],
+  );
+
+  const copy = useCallback(
+    async (text: string): Promise<boolean> => {
+      if (typeof navigator === "undefined" || !navigator.clipboard) {
+        return false;
+      }
+      try {
+        await navigator.clipboard.writeText(text);
+      } catch {
+        return false;
+      }
+      setCopied(true);
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+      }
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        setCopied(false);
+      }, resetAfterMs);
+      return true;
+    },
+    [resetAfterMs],
+  );
+
+  return { copied, copy };
+}

package/src/lib/use-mobile.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from "react";
+
+const MOBILE_BREAKPOINT = 768;
+
+/** Returns true when the viewport is below the mobile breakpoint (768px). */
+export function useIsMobile(): boolean {
+  const [isMobile, setIsMobile] = useState<boolean | undefined>(undefined);
+  useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    mql.addEventListener("change", onChange);
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    return () => mql.removeEventListener("change", onChange);
+  }, []);
+  return !!isMobile;
+}

package/src/motion.stories.tsx

@@ -0,0 +1,266 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect } from "storybook/test";
+import { useEffect, useRef, useState } from "react";
+import { Button } from "./components/button";
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "./components/card";
+import { RevealGroup } from "./components/reveal";
+
+/**
+ * Foundation/Motion — demonstrates and VERIFIES the token-driven motion gate.
+ *
+ * The gate is a single CSS multiplier (`--motion-factor`) that scales every
+ * duration token (`--t-fast`/`--t-base`/...). It is set by, in precedence order,
+ * the user's `data-motion-pref` (toolbar "Motion" global), the OS
+ * `prefers-reduced-motion` setting, and the per-theme default. Flip the **Motion**
+ * toolbar control (System / Reduce / Full) and the **theme** control to sweep all
+ * combinations. The play functions below assert the gate mechanically.
+ */
+
+/** Live readout of the resolved gate values (updates when data-motion-pref changes). */
+function GateReadout() {
+  const probeRef = useRef<HTMLSpanElement>(null);
+  const [factor, setFactor] = useState("—");
+  const [effective, setEffective] = useState("—");
+
+  useEffect(() => {
+    const read = () => {
+      const root = document.documentElement;
+      setFactor(getComputedStyle(root).getPropertyValue("--motion-factor").trim() || "1");
+      if (probeRef.current) {
+        setEffective(getComputedStyle(probeRef.current).transitionDuration);
+      }
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-motion-pref"],
+    });
+    const mql = window.matchMedia("(prefers-reduced-motion: reduce)");
+    mql.addEventListener("change", read);
+    return () => {
+      observer.disconnect();
+      mql.removeEventListener("change", read);
+    };
+  }, []);
+
+  return (
+    <div className="text-muted-foreground flex flex-col gap-1 text-body">
+      {/* Probe: drives a real property off the gated token so its computed value
+          reflects the effective duration the gate produces. */}
+      <span
+        ref={probeRef}
+        data-testid="motion-probe"
+        style={{ transitionProperty: "opacity", transitionDuration: "var(--t-base)" }}
+        aria-hidden
+        className="sr-only"
+      />
+      <span>
+        <span className="text-foreground font-medium">--motion-factor:</span> {factor}
+      </span>
+      <span>
+        <span className="text-foreground font-medium">effective --t-base:</span> {effective}
+      </span>
+    </div>
+  );
+}
+
+function MotionDemo() {
+  const [open, setOpen] = useState(false);
+  const [runId, setRunId] = useState(0);
+  return (
+    <div className="flex w-[28rem] max-w-full flex-col gap-6">
+      <Card>
+        <CardHeader>
+          <CardTitle>Micro-interactions</CardTitle>
+          <CardDescription>
+            Flip the <strong>Motion</strong> toolbar (System / Reduce / Full) and the theme — every
+            transition below is gated by <code>--motion-factor</code>.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="flex flex-col gap-5">
+          {/* Hover-lift: Card's `interactive` variant glides up + shadow on hover. */}
+          <div className="grid grid-cols-3 gap-3">
+            {["Hover", "these", "cards"].map((label) => (
+              <Card
+                key={label}
+                interactive
+                className="flex h-16 items-center justify-center text-body shadow-none"
+              >
+                {label}
+              </Card>
+            ))}
+          </div>
+
+          {/* Press: scale feedback (gated --t-fast, from the Button base recipe). */}
+          <div className="flex flex-wrap gap-3">
+            <Button>Press me</Button>
+            <Button variant="secondary">Secondary</Button>
+            <Button variant="outline" onClick={() => setOpen((o) => !o)} aria-expanded={open}>
+              {open ? "Collapse" : "Expand"}
+            </Button>
+          </div>
+
+          {/* Expand/collapse: grid-rows trick, animated over the gated --t-base. */}
+          <div
+            className="grid transition-[grid-template-rows] duration-base ease-standard"
+            style={{ gridTemplateRows: open ? "1fr" : "0fr" }}
+          >
+            <div className="overflow-hidden">
+              <p className="text-muted-foreground text-body">
+                Expands over <code>--t-base</code>; snaps near-instantly when motion is reduced (but
+                never a literal 0s, so transitionend still fires).
+              </p>
+            </div>
+          </div>
+
+          {/* Staggered entrance — the clearest on/off tell. Replay remounts the list. */}
+          <div className="flex items-center justify-between">
+            <span className="text-muted-foreground text-body">Staggered entrance</span>
+            <Button size="sm" variant="ghost" onClick={() => setRunId((n) => n + 1)}>
+              Replay
+            </Button>
+          </div>
+          <RevealGroup key={runId} className="flex flex-col gap-2" appear="up" staggerMs={60}>
+            {["First row", "Second row", "Third row", "Fourth row"].map((row) => (
+              <div key={row} className="bg-surface-muted rounded-md border px-3 py-2 text-body">
+                {row}
+              </div>
+            ))}
+          </RevealGroup>
+        </CardContent>
+      </Card>
+      <GateReadout />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Foundations/Motion",
+  tags: ["autodocs"],
+  parameters: { layout: "centered" },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Visual demo — drive the toolbar "Motion" + theme controls to sweep states. */
+export const Playground: Story = {
+  render: () => <MotionDemo />,
+};
+
+/**
+ * Reads the EFFECTIVE transition duration of a probe element under explicit
+ * `data-motion-pref="full"`. Explicit "full" overrides any OS reduce request, so
+ * this is environment-independent: it must resolve to the full ~0.18s base.
+ */
+export const GateFullMotion: Story = {
+  render: () => <MotionDemo />,
+  play: async ({ canvasElement }) => {
+    const root = document.documentElement;
+    const previous = root.getAttribute("data-motion-pref");
+    try {
+      root.setAttribute("data-motion-pref", "full");
+      const probe = canvasElement.querySelector<HTMLElement>('[data-testid="motion-probe"]')!;
+      // getComputedStyle forces a synchronous style flush, so the new gate value
+      // is reflected immediately.
+      const seconds = parseFloat(getComputedStyle(probe).transitionDuration);
+      await expect(seconds).toBeGreaterThanOrEqual(0.15);
+    } finally {
+      if (previous) root.setAttribute("data-motion-pref", previous);
+      else root.removeAttribute("data-motion-pref");
+    }
+  },
+};
+
+/**
+ * Verifies the gate actually GATES: under `data-motion-pref="reduced"` the same
+ * probe collapses to a tiny fraction of the full duration (≥100× smaller) while
+ * staying strictly > 0 (the --motion-min floor — a literal 0s would never fire
+ * transitionend and would strand Radix's unmount-suspension).
+ */
+export const GateReducedMotion: Story = {
+  render: () => <MotionDemo />,
+  play: async ({ canvasElement }) => {
+    const root = document.documentElement;
+    const previous = root.getAttribute("data-motion-pref");
+    const probe = canvasElement.querySelector<HTMLElement>('[data-testid="motion-probe"]')!;
+    try {
+      root.setAttribute("data-motion-pref", "full");
+      const full = parseFloat(getComputedStyle(probe).transitionDuration);
+      root.setAttribute("data-motion-pref", "reduced");
+      const reduced = parseFloat(getComputedStyle(probe).transitionDuration);
+
+      await expect(full).toBeGreaterThanOrEqual(0.15); // full motion intact
+      await expect(reduced).toBeLessThan(full * 0.5); // gate clearly engaged
+      await expect(reduced).toBeLessThan(0.05); // effectively off
+      await expect(reduced).toBeGreaterThanOrEqual(0); // never negative / NaN
+    } finally {
+      if (previous) root.setAttribute("data-motion-pref", previous);
+      else root.removeAttribute("data-motion-pref");
+    }
+  },
+};
+
+/**
+ * Guardrail for the load-bearing `--motion-min` floor: even at the worst case
+ * (`--motion-factor` = 0) the effective duration must stay strictly > 0s. A
+ * literal 0s never fires `transitionend`, which would strand Radix's CSS
+ * unmount-suspension (overlays would never unmount). Locks the `max(…, --motion-min)`
+ * in themes.css against a future "simplify" that drops the floor.
+ */
+export const GateFloorNeverZero: Story = {
+  render: () => (
+    <span
+      data-testid="floor-probe"
+      aria-hidden
+      style={{
+        transitionProperty: "opacity",
+        transitionDuration: "max(calc(var(--duration-base) * 0), var(--motion-min))",
+      }}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const probe = canvasElement.querySelector<HTMLElement>('[data-testid="floor-probe"]')!;
+    const seconds = parseFloat(getComputedStyle(probe).transitionDuration);
+    await expect(seconds).toBeGreaterThan(0);
+  },
+};
+
+/**
+ * Proves the Tailwind UTILITIES (not just the raw CSS vars) are generated and
+ * resolve to the tuned, gated scale (fast ≈0.16s, base ≈0.26s, slow ≈0.38s), and
+ * that `ease-standard` is the standard cubic-bezier — these are what components
+ * actually use. If a long-running dev server hasn't picked up the @theme
+ * additions, these resolve to defaults/none and this fails.
+ */
+export const UtilitiesGenerated: Story = {
+  render: () => (
+    <div>
+      <span data-testid="util-fast" className="transition-opacity duration-fast ease-standard" />
+      <span data-testid="util-base" className="transition-opacity duration-base ease-standard" />
+      <span data-testid="util-slow" className="transition-opacity duration-slow ease-standard" />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const dur = (id: string) =>
+      parseFloat(
+        getComputedStyle(canvasElement.querySelector<HTMLElement>(`[data-testid="${id}"]`)!)
+          .transitionDuration,
+      );
+    const fast = dur("util-fast");
+    const base = dur("util-base");
+    const slow = dur("util-slow");
+    // Tuned scale (full motion): fast 0.16s < base 0.26s < slow 0.38s — and clearly
+    // in the "smooth" range, not the original snappy 0.12/0.18/0.28.
+    await expect(fast).toBeGreaterThanOrEqual(0.14);
+    await expect(base).toBeGreaterThan(fast);
+    await expect(base).toBeGreaterThanOrEqual(0.24);
+    await expect(slow).toBeGreaterThan(base);
+    await expect(slow).toBeGreaterThanOrEqual(0.34);
+    const tf = getComputedStyle(
+      canvasElement.querySelector<HTMLElement>('[data-testid="util-fast"]')!,
+    ).transitionTimingFunction;
+    await expect(tf).toContain("cubic-bezier"); // ease-standard applied
+  },
+};

package/src/taste-profile.test.tsx

@@ -0,0 +1,252 @@
+/**
+ * taste-profile.test.tsx — the RENDERED half of the taste profile (#108).
+ *
+ * The type/default surface is locked in `packages/tokens/src/taste-profile.test.ts`;
+ * this file exercises the real `<ThemeProvider>` in a DOM, which `@…-tokens`
+ * cannot do (its vitest environment is `node` by design — no React, no jsdom).
+ * `@…-ui` already ships the jsdom + Testing Library setup and legitimately
+ * depends on tokens (one-way dep graph), so the provider's live behaviour is
+ * proven here rather than mocked anywhere.
+ */
+import { useState } from "react";
+import { describe, expect, it, beforeEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import {
+  DEFAULT_TASTE_PROFILE,
+  DEFAULT_THEME,
+  BUILT_IN_THEME_META,
+  ThemeProvider,
+  useDecoration,
+  useDensity,
+  useMotionPreference,
+  useTasteProfile,
+  type DecorationLevel,
+} from "@elabs-ai/components-tokens";
+
+/** A probe that prints the live profile and drives every axis from context. */
+function Probe() {
+  const { profile, setRegister } = useTasteProfile();
+  const { setDensity } = useDensity();
+  const { setDecoration } = useDecoration();
+  const { setMotionPreference } = useMotionPreference();
+  const [level, setLevel] = useState<DecorationLevel>(0);
+  return (
+    <div>
+      <output data-testid="profile">{JSON.stringify(profile)}</output>
+      <button onClick={() => setRegister("brand")}>brand</button>
+      <button onClick={() => setDensity("compact")}>compact</button>
+      {/* stands in for a real app's motion control (Settings → Motion) */}
+      <button onClick={() => setMotionPreference("full")}>full motion</button>
+      <button
+        onClick={() => {
+          const next = ((level + 6) % 12) as DecorationLevel;
+          setLevel(next);
+          setDecoration(next);
+        }}
+      >
+        decorate
+      </button>
+    </div>
+  );
+}
+
+const profile = () => JSON.parse(screen.getByTestId("profile").textContent ?? "{}");
+
+describe("useTasteProfile", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    for (const attr of ["data-register", "data-density", "data-decoration"]) {
+      document.documentElement.removeAttribute(attr);
+    }
+  });
+
+  it("returns the restrained defaults inside a bare ThemeProvider", async () => {
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(profile()).toEqual(DEFAULT_TASTE_PROFILE);
+    // The register is an inspectable seam on the root — no CSS keys off it.
+    expect(document.documentElement.getAttribute("data-register")).toBe("product");
+  });
+
+  it("setRegister writes data-register and persists it", async () => {
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "brand" }));
+    expect(profile().register).toBe("brand");
+    expect(document.documentElement.getAttribute("data-register")).toBe("brand");
+    expect(window.localStorage.getItem("brand-ui-taste-register")).toBe("brand");
+  });
+
+  it("rehydrates the persisted register on mount", () => {
+    window.localStorage.setItem("brand-ui-taste-register", "brand");
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(profile().register).toBe("brand");
+  });
+
+  it("ignores a junk persisted register and falls back to the default", () => {
+    window.localStorage.setItem("brand-ui-taste-register", "marketing");
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(profile().register).toBe("product");
+  });
+
+  it("tracks live changes on the density axis", async () => {
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    await userEvent.click(screen.getByRole("button", { name: "compact" }));
+    expect(profile().density).toBe("compact");
+    expect(document.documentElement.getAttribute("data-density")).toBe("compact");
+  });
+
+  it("expressiveness IS the effective decoration level (one dial, two names)", async () => {
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(profile().expressiveness).toBe(0);
+    await userEvent.click(screen.getByRole("button", { name: "decorate" }));
+    expect(profile().expressiveness).toBe(6);
+    expect(document.documentElement.getAttribute("data-decoration")).toBe("6");
+  });
+
+  it("expressiveness follows the THEME's own decoration default when unset", () => {
+    render(
+      <ThemeProvider defaultTheme={DEFAULT_THEME}>
+        <Probe />
+      </ThemeProvider>,
+    );
+    // With no override the profile must report the theme's EFFECTIVE level (its
+    // registry default), never the (null) override. Read from the registry so a
+    // retuned theme can't silently make this vacuous.
+    expect(profile().expressiveness).toBe(
+      BUILT_IN_THEME_META[DEFAULT_THEME as "light" | "dark"].decorationLevel ?? 0,
+    );
+  });
+
+  it("honours an explicit defaultRegister", () => {
+    render(
+      <ThemeProvider defaultRegister="brand">
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(profile().register).toBe("brand");
+  });
+});
+
+/**
+ * The scaffold contract (#109): an app-spec's `taste` block becomes ThemeProvider
+ * props, and NOTHING else — no hardcoded density/expressiveness in component
+ * source. These lock that a spec-driven provider actually writes the dials, for
+ * both shipped presets.
+ */
+describe("a spec-driven ThemeProvider writes the profile onto the root", () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    for (const attr of ["data-register", "data-density", "data-decoration", "data-motion-pref"]) {
+      document.documentElement.removeAttribute(attr);
+    }
+  });
+
+  it("product / calm — the restrained default omits the identity dials", () => {
+    render(
+      <ThemeProvider
+        defaultRegister="product"
+        defaultDensity="comfortable"
+        defaultMotionPreference="system"
+        defaultDecoration={0}
+      >
+        <Probe />
+      </ThemeProvider>,
+    );
+    const root = document.documentElement;
+    expect(root.getAttribute("data-register")).toBe("product");
+    // comfortable + "system" are identity values: no attribute, so the first
+    // paint is pixel-identical to a provider-less build (zero-flash).
+    expect(root.getAttribute("data-density")).toBeNull();
+    expect(root.getAttribute("data-motion-pref")).toBeNull();
+    expect(root.getAttribute("data-decoration")).toBe("0");
+    expect(profile()).toEqual({
+      register: "product",
+      density: "comfortable",
+      motion: "system",
+      expressiveness: 0,
+    });
+  });
+
+  it("brand / expressive — every non-identity dial lands on the root", () => {
+    render(
+      <ThemeProvider
+        defaultRegister="brand"
+        defaultDensity="spacious"
+        defaultMotionPreference="reduced"
+        defaultDecoration={4}
+      >
+        <Probe />
+      </ThemeProvider>,
+    );
+    const root = document.documentElement;
+    expect(root.getAttribute("data-register")).toBe("brand");
+    expect(root.getAttribute("data-density")).toBe("spacious");
+    expect(root.getAttribute("data-motion-pref")).toBe("reduced");
+    // expressiveness IS decoration — one dial, one attribute.
+    expect(root.getAttribute("data-decoration")).toBe("4");
+    expect(profile()).toEqual({
+      register: "brand",
+      density: "spacious",
+      motion: "reduced",
+      expressiveness: 4,
+    });
+  });
+
+  /**
+   * The a11y half of #108 AC3. `[data-motion-pref="full"]` is the ONE state that
+   * keeps `--motion-factor: 1` under an OS `prefers-reduced-motion: reduce` and
+   * opts out of the third-party animation cap (packages/tokens/src/themes.css) —
+   * informed consent, given by a PERSON for themselves. So:
+   *   · no scaffold preset ships it (stages.md), and the app-spec schema rejects a
+   *     spec that defaults to it (scripts/check-app-spec.test.mjs);
+   *   · `system` — what the presets DO ship — writes no attribute at all, which is
+   *     precisely what lets the OS rule win.
+   */
+  it('the scaffold defaults ("system") write NO motion attribute, so the OS rule wins', () => {
+    render(
+      <ThemeProvider defaultRegister="brand" defaultMotionPreference="system" defaultDecoration={4}>
+        <Probe />
+      </ThemeProvider>,
+    );
+    expect(document.documentElement.getAttribute("data-motion-pref")).toBeNull();
+    expect(profile().motion).toBe("system");
+  });
+
+  it('"full" is reachable only as the person\'s own explicit choice', async () => {
+    render(
+      <ThemeProvider>
+        <Probe />
+      </ThemeProvider>,
+    );
+    // Nothing an app is scaffolded with puts the override on the root…
+    expect(document.documentElement.getAttribute("data-motion-pref")).toBeNull();
+    // …only a motion control the person operates does.
+    await userEvent.click(screen.getByRole("button", { name: "full motion" }));
+    expect(document.documentElement.getAttribute("data-motion-pref")).toBe("full");
+    expect(profile().motion).toBe("full");
+  });
+});