@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/decoration.stories.tsx

@@ -2,7 +2,15 @@ import type { Meta, StoryObj } from "@storybook/react-vite";
 import { expect } from "storybook/test";
 import { DecorationProvider, type DecorationLevel } from "@elabs-ai/components-tokens";
 import { Button } from "./components/button";
-import { Card, CardContent, CardHeader, CardTitle } from "./components/card";
+import { FileText, PenLine, Plug, ShieldCheck, Workflow } from "lucide-react";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardMedia,
+  CardTitle,
+} from "./components/card";
 import { Badge } from "./components/badge";
 import { Input } from "./components/input";
 
@@ -94,7 +102,7 @@ const FADES = ["top", "bottom", "edges", "center"] as const;
  * Budget: it spends the region's one focal drafting gesture. For a one-off fade on
  * a single element, use Tailwind's own `mask-t-from-*` / `mask-radial-*` utilities.
  *
- * Shipped in anger on `Patterns/Templates/Marketing`, whose hero band carries
+ * Shipped in anger on `Patterns/Templates/Starters/Marketing`, whose hero band carries
  * `data-decoration-fade="top"` so the sheet fades in behind the headline instead of
  * starting on a hard ruled edge — that template, not this matrix, is the surface to
  * judge the gesture on.
@@ -234,3 +242,206 @@ export const ControlsAreUntouched: Story = {
     await expect(getComputedStyle(button).backgroundColor).not.toBe("transparent");
   },
 };
+
+/**
+ * THE HAIRLINE FAMILY — the quiet line-work of a calm product page, as opt-in
+ * utilities (`packages/tokens`, the `--hairline-*` block). Like the paper
+ * grounds it is NOT on the dial: you ask for one gesture on one element and get
+ * it at any decoration level, in any theme. Lines take the theme's own rule ink
+ * (`--rule` / `--rule-strong`); the hatch is a translucent tint of
+ * `--foreground`, so a brand re-tints all of it by doing nothing.
+ *
+ * | utility | the gesture |
+ * | --- | --- |
+ * | `bg-hairline-hatch` | a faded diagonal hatch — the recessed WELL behind media (`CardMedia` default) |
+ * | `hairline-stack` | two sheet edges stacked under a card (`<Card stacked>`) |
+ * | `hairline-slot` | a dashed placeholder outline |
+ * | `hairline-frame` | dashed rails that run past a box's corners and fade |
+ * | `hairline-rails` | the same for a full-bleed section: rails down the content column |
+ * | `hairline-corners` | crop marks on the focal item |
+ * | `hairline-ticks-y` / `-x` | a tick ruler along an edge |
+ * | `hairline-rule` / `-y` | a dashed separator |
+ *
+ * Surfaces and the space between them only — never a control. One focal gesture
+ * per region; each utility owns its host's pseudo-elements, so nest a wrapper
+ * to combine two.
+ */
+export const Hairlines: Story = {
+  parameters: { layout: "fullscreen" },
+  render: () => (
+    <div className="bg-background px-6 py-12 text-foreground">
+      <div className="mx-auto grid max-w-5xl gap-4 md:grid-cols-3">
+        <Card>
+          <CardMedia data-testid="hairline-well">
+            <div className="flex w-full max-w-56 items-center gap-3 rounded-lg border border-card-border bg-card p-3 shadow-card">
+              <span className="flex size-9 items-center justify-center rounded-md bg-surface-muted text-muted-foreground">
+                <FileText aria-hidden="true" className="size-4" />
+              </span>
+              <span className="min-w-0 flex-1 space-y-1.5">
+                <span className="block truncate text-caption font-medium">q3-board-pack.pdf</span>
+                <span className="block h-1 rounded-full bg-surface-muted">
+                  <span className="block h-1 w-1/3 rounded-full bg-primary" />
+                </span>
+              </span>
+            </div>
+          </CardMedia>
+          <CardHeader>
+            <CardTitle>Hatch well</CardTitle>
+            <CardDescription>
+              <code>CardMedia</code> — a faded hairline hatch behind whatever the card shows.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+
+        <Card>
+          <CardMedia ground="none" className="items-end pb-0">
+            <Card
+              stacked
+              data-testid="hairline-stack"
+              className="w-full max-w-56 rounded-b-none border-b-0"
+            >
+              <CardContent className="space-y-2 p-4">
+                <p className="text-caption font-medium">Spending limit</p>
+                <span className="block h-2 rounded-sm bg-surface-muted">
+                  <span className="block h-2 w-2/5 rounded-sm bg-primary" />
+                </span>
+                <p className="text-meta text-muted-foreground">40% used · 60% free</p>
+              </CardContent>
+            </Card>
+          </CardMedia>
+          <CardHeader>
+            <CardTitle>Stacked sheets</CardTitle>
+            <CardDescription>
+              <code>{"<Card stacked>"}</code> — two sheet edges rise behind the top edge.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+
+        <Card>
+          <CardMedia ground="dots">
+            <div
+              data-testid="hairline-corners"
+              className="hairline-corners flex items-center gap-2 rounded-md border border-card-border bg-card px-3 py-2 shadow-card [--hairline-ink-strong:var(--primary-text)]"
+            >
+              <ShieldCheck aria-hidden="true" className="size-4 text-success-text" />
+              <span className="text-caption font-medium">Verified signer</span>
+              <PenLine aria-hidden="true" className="size-4 text-muted-foreground" />
+            </div>
+          </CardMedia>
+          <CardHeader>
+            <CardTitle>Crop corners on a dot field</CardTitle>
+            <CardDescription>
+              <code>hairline-corners</code> marks the focal item; re-inked here with one variable.
+            </CardDescription>
+          </CardHeader>
+        </Card>
+
+        <Card className="md:col-span-2">
+          <CardHeader>
+            <CardTitle>Dashed slots</CardTitle>
+            <CardDescription>
+              <code>hairline-slot</code> — the empty seats next to the filled ones.
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className="grid grid-cols-6 gap-3">
+              {[
+                Plug,
+                null,
+                Workflow,
+                null,
+                null,
+                ShieldCheck,
+                null,
+                FileText,
+                null,
+                PenLine,
+                null,
+                null,
+              ].map((Icon, i) =>
+                Icon ? (
+                  <span
+                    key={i}
+                    className="flex aspect-square items-center justify-center rounded-lg border border-card-border bg-card text-muted-foreground shadow-card"
+                  >
+                    <Icon aria-hidden="true" className="size-5" />
+                  </span>
+                ) : (
+                  <span
+                    key={i}
+                    data-slot-empty
+                    className="hairline-slot aspect-square rounded-lg"
+                  />
+                ),
+              )}
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Ruler and rule</CardTitle>
+            <CardDescription>
+              <code>hairline-ticks-y</code> and <code>hairline-rule</code>.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <div data-testid="hairline-ticks" className="hairline-ticks-y space-y-2 ps-5">
+              <span className="block h-4 w-11/12 rounded-sm bg-primary" />
+              <span className="block h-4 w-7/12 rounded-sm bg-surface-muted" />
+              <span className="block h-4 w-4/12 rounded-sm bg-surface-muted" />
+            </div>
+            <hr className="hairline-rule" />
+            <p className="text-caption text-muted-foreground">Below the dashed rule.</p>
+          </CardContent>
+        </Card>
+      </div>
+
+      <div className="mx-auto mt-16 max-w-3xl">
+        <div data-testid="hairline-frame" className="hairline-frame p-8">
+          <p className="text-subtitle font-medium">Frame rails</p>
+          <p className="mt-1 text-caption text-muted-foreground">
+            <code>hairline-frame</code> — construction lines, not a border: each rail runs past the
+            corner and fades out, so the panel reads as placed on a drawing rather than boxed in.
+          </p>
+        </div>
+      </div>
+    </div>
+  ),
+  /**
+   * The contract a reading of the CSS cannot prove: every gesture is an INERT
+   * pseudo-element layer, the hosts are never masked (their children stay
+   * opaque), the one texture is never flat — and the hairlines are there at
+   * decoration 0, because this family does not ride the dial.
+   */
+  play: async ({ canvas }) => {
+    const well = canvas.getByTestId("hairline-well");
+    const wellLayer = getComputedStyle(well, "::before");
+    await expect(wellLayer.backgroundImage).toContain("gradient");
+    await expect(wellLayer.maskImage).not.toBe("none");
+    await expect(wellLayer.pointerEvents).toBe("none");
+    await expect(getComputedStyle(well).maskImage).toBe("none");
+
+    const stack = canvas.getByTestId("hairline-stack");
+    for (const pseudo of ["::before", "::after"] as const) {
+      const sheet = getComputedStyle(stack, pseudo);
+      await expect(sheet.content).not.toBe("none");
+      await expect(sheet.pointerEvents).toBe("none");
+      await expect(sheet.borderTopStyle).toBe("solid");
+      await expect(sheet.borderBottomWidth).toBe("0px");
+    }
+
+    for (const id of ["hairline-frame", "hairline-corners", "hairline-ticks"]) {
+      const host = canvas.getByTestId(id);
+      const layer = getComputedStyle(host, "::before");
+      await expect(layer.content).not.toBe("none");
+      await expect(layer.pointerEvents).toBe("none");
+      await expect(getComputedStyle(host).maskImage).toBe("none");
+    }
+
+    // The frame's rails overshoot the box and fade — never a hard stop.
+    const frame = getComputedStyle(canvas.getByTestId("hairline-frame"), "::before");
+    await expect(frame.maskImage).toContain("gradient");
+    await expect(Number.parseFloat(frame.left)).toBeLessThan(0);
+  },
+};

package/src/index.ts

@@ -18,9 +18,26 @@ export { cn } from "./lib/cn";
 // The canonical mobile-breakpoint check (Sidebar / ContextPanel Sheet fallback
 // pattern, research 09 §B.4) — exported so siblings don't fork a matchMedia hook.
 export { useIsMobile } from "./lib/use-mobile";
+// Scroll progress for site motion (ParallaxPlane): a native scroll timeline, a lazy
+// `motion` fallback (optional peer, dynamic import only), or static under reduced motion.
+export {
+  MOTION_FACTOR_FLOOR,
+  isMotionAtFloor,
+  readMotionFactor,
+  supportsScrollTimeline,
+  useScrollProgress,
+  type ScrollProgress,
+  type ScrollProgressMode,
+  type ScrollProgressOptions,
+} from "./lib/use-scroll-progress";
 // Browser file-download mechanics — one home for the Blob/URL → <a download> dance
 // (shared by ConversationDownload, downloadCsv, and Gallery). SSR-guarded.
 export { downloadBlob, downloadUrl } from "./lib/download";
+// Shared CSV (RFC 4180) value stringification + injection-guarded field
+// quoting — one home for logic `@elabs-ai/components-data`'s `toCsv` and
+// `@elabs-ai/components-charts`'s ChartFrame serializer both need (charts may
+// not depend on data, so both build on this instead).
+export { csvStringifyValue, csvQuoteField } from "./lib/csv";
 // Clipboard write + transient "copied" flag — one implementation for the
 // editor's copy button and `CopyableValue`, so the timing and the
 // "no clipboard in this context" answer are defined once.
@@ -129,6 +146,7 @@ export * from "./components/advanced-group";
 export * from "./components/app-sidebar";
 export * from "./components/alert";
 export * from "./components/alert-dialog";
+export * from "./components/ambient-field";
 export * from "./components/app-shell";
 export * from "./components/aspect-ratio";
 export * from "./components/attribution-panel";
@@ -199,12 +217,15 @@ export * from "./components/navigation-menu";
 export * from "./components/number-input";
 export * from "./components/page-shell";
 export * from "./components/pagination";
+export * from "./components/parallax-plane";
 export * from "./components/popover";
+export * from "./components/meter";
 export * from "./components/progress";
 export * from "./components/radio-group";
 export * from "./components/rating";
 export * from "./components/resizable";
 export * from "./components/reveal";
+export * from "./components/reveal-on-enter";
 export * from "./components/schema-form";
 export * from "./components/scroll-area";
 export * from "./components/section-header";
@@ -230,6 +251,7 @@ export * from "./components/tag-input";
 export * from "./components/team-switcher";
 export * from "./components/textarea";
 export * from "./components/theme-switcher";
+export * from "./components/theme-family-switch";
 export * from "./components/revision-timeline";
 export * from "./components/timeline";
 export * from "./components/toggle";
@@ -245,3 +267,32 @@ export * from "./components/view-toolbar";
 export * from "./components/virtual-select";
 export * from "./components/workspace-picker";
 export * from "./components/wizard";
+export * from "./components/command-chip";
+// SurfaceTour — RM-096
+export * from "./components/surface-tour";
+// SpecPlayground — RM-101
+export * from "./components/spec-playground";
+// IntegrationMatrix, InstallTabs — RM-102
+export * from "./components/integration-matrix";
+export * from "./components/install-tabs";
+// TokenSpotlight — RM-103
+export * from "./components/token-spotlight";
+// colorScaleFor — RM-124: the one value → colour-token scale (continuous / stepped,
+// quantile, Jenks, …) shared by `charts`, `data` and `maps`, which may not import each other.
+export {
+  colorScaleFor,
+  type ColorScale,
+  type ColorScaleCategory,
+  type ColorScaleDomain,
+  type ColorScaleMethod,
+  type ColorScalePalette,
+  type ColorScaleSpec,
+  type ColorScaleStep,
+  type ColorScaleStop,
+  type ColorScaleType,
+  type ColorScaleValue,
+  type ContinuousColorScaleMethod,
+  type ContinuousColorScaleSpec,
+  type SteppedColorScaleMethod,
+  type SteppedColorScaleSpec,
+} from "./lib/color-scale";

package/src/lib/cn.test.ts

@@ -36,4 +36,24 @@ describe("cn", () => {
   it("still dedupes conflicting text-<color> utilities against each other", () => {
     expect(cn("text-red-500", "text-blue-500")).toBe("text-blue-500");
   });
+
+  it("keeps every type role beside a text colour, and lets a later role replace it", () => {
+    for (const role of ["eyebrow", "kpi-sm", "display-lg", "heading-xs", "table-header"]) {
+      expect(cn(`text-${role}`, "text-muted-foreground")).toBe(
+        `text-${role} text-muted-foreground`,
+      );
+      expect(cn(`text-${role}`, "text-caption")).toBe("text-caption");
+    }
+  });
+
+  it("lets a caller's utility replace a component-seam token default", () => {
+    expect(cn("shadow-card", "shadow-none")).toBe("shadow-none");
+    expect(cn("shadow-popover", "shadow-lg")).toBe("shadow-lg");
+    expect(cn("shadow-dialog", "shadow-none")).toBe("shadow-none");
+    expect(cn("rounded-badge", "rounded-md")).toBe("rounded-md");
+    expect(cn("font-tabs-active", "font-bold")).toBe("font-bold");
+    expect(cn("leading-(--card-title-leading)", "leading-tight")).toBe("leading-tight");
+    expect(cn("tracking-(--table-header-tracking)", "tracking-wide")).toBe("tracking-wide");
+    expect(cn("text-table-header-foreground", "text-foreground")).toBe("text-foreground");
+  });
 });

package/src/lib/cn.ts

@@ -9,14 +9,48 @@ import { extendTailwindMerge } from "tailwind-merge";
  * group makes role-vs-role and role-vs-raw-size conflicts resolve correctly while
  * keeping role + color independent.
  */
-const TEXT_ROLES = ["display", "title", "subtitle", "body", "caption", "meta", "kpi", "code"];
+const TEXT_ROLES = [
+  "display-lg",
+  "display",
+  "title",
+  "subtitle",
+  "body",
+  "caption",
+  "meta",
+  "eyebrow",
+  "heading-xs",
+  "kpi",
+  "kpi-sm",
+  "code",
+];
+
+/**
+ * Tailwind v4's CSS-variable shorthand (`leading-(--card-title-leading)`).
+ * tailwind-merge 2.x predates it and leaves such a class beside a caller's
+ * `leading-tight`, letting stylesheet order pick the winner. A typed hint
+ * (`text-(length:--x)`) is read as a variant prefix by 2.x and cannot be
+ * registered — give that seam a named `@theme` utility instead
+ * (`text-table-header`).
+ */
+const isVarShorthand = (value: string) => /^\(--[\w-]+\)$/.test(value);
 
 const twMerge = extendTailwindMerge({
   extend: {
     classGroups: {
-      "font-size": [{ text: TEXT_ROLES }],
+      "font-size": [{ text: [...TEXT_ROLES, "table-header"] }],
+      leading: [{ leading: [isVarShorthand] }],
+      tracking: [{ tracking: [isVarShorthand] }],
       // `font-display` is the display-face seam (sibling of font-mono, #187).
       "font-family": [{ font: ["display"] }],
+      // Theme-driven control/table/surface knobs (themes.css § CONTROL UTILITIES
+      // and the `@theme inline` bridge) — so a caller's `h-8` / `rounded-none` /
+      // `font-bold` / `shadow-none` still replaces the token default.
+      "font-weight": [{ font: ["control", "table-header", "tabs-active"] }],
+      rounded: [{ rounded: ["control", "badge"] }],
+      shadow: [{ shadow: ["input", "card", "popover", "dialog"] }],
+      h: [{ h: ["control", "control-sm", "control-lg", "header"] }],
+      size: [{ size: ["control", "control-sm", "control-lg"] }],
+      "min-w": [{ "min-w": ["control", "control-sm", "control-lg"] }],
     },
   },
 });