@elabs-ai/components-ui 5.0.0 → 5.2.0

package/src/components/tree/tree.tsx

@@ -83,6 +83,13 @@ export interface TreeProps<T = unknown> extends Omit<HTMLAttributes<HTMLDivEleme
    *   the same multi-cue approach the Sidebar uses.)
    */
   surface?: "default" | "sidebar";
+  /**
+   * What a click on a row does to an expandable node. `"row"` (default): the click both
+   * selects the node and toggles its children. `"chevron"`: the click only selects; only
+   * the chevron (and ArrowLeft/ArrowRight) expands or collapses — the filter-pane
+   * convention, where clicking a parent value must select it without reflowing the list.
+   */
+  expandOn?: "row" | "chevron";
   /**
    * Enable windowed rendering for large trees (>50 visible rows).
    * When `true`, only the visible slice of the flattened tree is mounted in
@@ -242,6 +249,7 @@ interface VirtualFlatRowProps<T> {
   selectionMode: "single" | "multiple" | "none";
   checkboxes: boolean;
   surface: "default" | "sidebar";
+  expandOn: "row" | "chevron";
   onToggleExpand: (id: string) => void;
   onSelect: (id: string) => void;
   onRetry: (id: string) => void;
@@ -259,6 +267,7 @@ function VirtualFlatRow<T>({
   selectionMode,
   checkboxes,
   surface,
+  expandOn,
   onToggleExpand,
   onSelect,
   onRetry,
@@ -281,7 +290,7 @@ function VirtualFlatRow<T>({
     if (node.disabled) return;
     setActiveId(node.id);
     onSelect(node.id);
-    if (expandable) onToggleExpand(node.id);
+    if (expandable && expandOn === "row") onToggleExpand(node.id);
   };
 
   return (
@@ -488,6 +497,7 @@ interface TreeItemProps<T> {
   onSelectionChange: (ids: Set<string>) => void;
   checkboxes: boolean;
   surface: "default" | "sidebar";
+  expandOn: "row" | "chevron";
   activeId: string | null;
   setActiveId: (id: string | null) => void;
   registerNodeRef: (id: string, el: HTMLElement | null) => void;
@@ -507,6 +517,7 @@ function TreeItem<T>({
   onSelectionChange,
   checkboxes,
   surface,
+  expandOn,
   activeId,
   setActiveId,
   registerNodeRef,
@@ -560,7 +571,7 @@ function TreeItem<T>({
   const handleRowClick = () => {
     setActiveId(node.id);
     handleSelect();
-    if (expandable) toggleExpanded();
+    if (expandable && expandOn === "row") toggleExpanded();
   };
 
   const indentStyle = { paddingLeft: `${(level - 1) * 1}rem` };
@@ -695,6 +706,7 @@ function TreeItem<T>({
                 onSelectionChange={onSelectionChange}
                 checkboxes={checkboxes}
                 surface={surface}
+                expandOn={expandOn}
                 activeId={activeId}
                 setActiveId={setActiveId}
                 registerNodeRef={registerNodeRef}
@@ -806,6 +818,7 @@ export const Tree = forwardRef<HTMLDivElement, TreeProps>(function Tree(
     scrollSelectionIntoView = false,
     loadChildren,
     surface = "default",
+    expandOn = "row",
     className,
     ...props
   },
@@ -1113,6 +1126,7 @@ export const Tree = forwardRef<HTMLDivElement, TreeProps>(function Tree(
               onSelectionChange={setSelectedIds}
               checkboxes={checkboxes}
               surface={surface}
+              expandOn={expandOn}
               activeId={activeId}
               setActiveId={setActiveId}
               // registerAndFlush (not raw registerNodeRef) so nodeRefsForFlush is
@@ -1191,6 +1205,7 @@ export const Tree = forwardRef<HTMLDivElement, TreeProps>(function Tree(
                   selectionMode={selectionMode}
                   checkboxes={checkboxes}
                   surface={surface}
+                  expandOn={expandOn}
                   onToggleExpand={handleToggleExpand}
                   onSelect={handleSelectVirtual}
                   onRetry={() => handleExpandLazy(node)}

package/src/decoration.stories.tsx

@@ -254,10 +254,11 @@ export const ControlsAreUntouched: Story = {
  * | utility | the gesture |
  * | --- | --- |
  * | `bg-hairline-hatch` | a faded diagonal hatch — the recessed WELL behind media (`CardMedia` default) |
+ * | `bg-hairline-stripes` | stripes streaming out of one corner, thinning as they fade — a hero / header ground |
  * | `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-rails` | the same for a full-bleed section: rails down the content column, inked only near the corners (`hairline-rails-full` for whole lines) |
  * | `hairline-corners` | crop marks on the focal item |
  * | `hairline-ticks-y` / `-x` | a tick ruler along an edge |
  * | `hairline-rule` / `-y` | a dashed separator |
@@ -269,135 +270,150 @@ export const ControlsAreUntouched: Story = {
 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" />
+    <div className="bg-background text-foreground">
+      <header
+        data-testid="hairline-stripes"
+        className="bg-surface-muted bg-hairline-stripes px-6 py-14 text-center"
+      >
+        <p className="text-title font-semibold">Corner stripes</p>
+        <p className="mx-auto mt-1 max-w-prose text-caption text-muted-foreground">
+          <code>bg-hairline-stripes</code> on an offset fill — heavy at the corner, a hairline by
+          the middle, then gone, so the headline sits on clean ground.
+        </p>
+      </header>
+      <div
+        data-testid="hairline-rails"
+        className="hairline-rails px-6 py-12 [--hairline-rail-width:66rem]"
+      >
+        <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>
-            </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 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>
-                <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>
+              </div>
+            </CardMedia>
+            <CardHeader>
+              <CardTitle>Hatch well</CardTitle>
+              <CardDescription>
+                <code>CardMedia</code> — a faded hairline hatch behind whatever the card shows.
+              </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" />
+          <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>
-                ) : (
-                  <span
-                    key={i}
-                    data-slot-empty
-                    className="hairline-slot aspect-square rounded-lg"
-                  />
-                ),
-              )}
-            </div>
-          </CardContent>
-        </Card>
+                  <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>
-          <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>
+          <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>
 
-      <div className="mx-auto mt-16 max-w-3xl">
+      <div className="mx-auto max-w-3xl px-6 py-16">
         <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">
@@ -439,6 +455,20 @@ export const Hairlines: Story = {
       await expect(getComputedStyle(host).maskImage).toBe("none");
     }
 
+    // The corner stripes are ONE inert layer: a flat ink fill whose mask draws the stripes.
+    const stripes = getComputedStyle(canvas.getByTestId("hairline-stripes"), "::before");
+    await expect(stripes.pointerEvents).toBe("none");
+    await expect(stripes.backgroundImage).toBe("none");
+    await expect(stripes.maskImage).toContain("repeating-linear-gradient");
+    await expect(stripes.maskComposite).toContain("intersect");
+
+    // The section rails are corner marks: both pseudo layers are masked, so the middle of
+    // every run is air.
+    const rails = canvas.getByTestId("hairline-rails");
+    await expect(getComputedStyle(rails, "::before").maskImage).toContain("gradient");
+    await expect(getComputedStyle(rails, "::after").maskImage).toContain("gradient");
+    await expect(getComputedStyle(rails).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");

package/src/index.ts

@@ -15,6 +15,9 @@
 
 // Utilities
 export { cn } from "./lib/cn";
+// Forwarded ref + a locally owned ref on one node (a measured root that is also
+// the consumer's handle) — exported so siblings don't fork a callback-ref merger.
+export { mergeRefs } from "./lib/merge-refs";
 // 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";
@@ -177,6 +180,7 @@ export * from "./components/date-range-picker";
 export * from "./components/descriptions";
 export * from "./components/dialog";
 export * from "./components/drawer";
+export * from "./components/drafting-marks";
 export * from "./components/dropdown-menu";
 export * from "./components/empty-state";
 export * from "./components/error-state";

package/src/lib/cn.test.ts

@@ -1,6 +1,19 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { describe, expect, it } from "vitest";
 import { cn } from "./cn";
 
+/** Every `--text-<role>` companion-key root declared by the token engine. */
+function typeRolesFromThemesCss(): string[] {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const css = readFileSync(join(here, "../../../tokens/src/themes.css"), "utf8");
+  const roles = new Set<string>();
+  for (const m of css.matchAll(/^\s*--text-([a-z][a-z0-9-]*?)(?:--[a-z-]+)?:/gm))
+    if (m[1]) roles.add(m[1]);
+  return [...roles].sort();
+}
+
 describe("cn", () => {
   it("later utilities win for a genuine conflict (e.g. padding)", () => {
     expect(cn("p-2", "p-4")).toBe("p-4");
@@ -46,6 +59,22 @@ describe("cn", () => {
     }
   });
 
+  // 2026-09-21 new-user test: the chart roles from RM-019 were never registered,
+  // so `cn("text-chart-source", "text-chart-foreground-muted")` returned only the
+  // colour and every ChartCard source row rendered at body size. The expected
+  // list is read from themes.css so the next `--text-<role>` cannot drift either.
+  it("registers every --text-<role> the token engine declares (chart roles included)", () => {
+    const roles = typeRolesFromThemesCss();
+    expect(roles).toContain("chart-source");
+    expect(roles).toContain("chart-value");
+    for (const role of roles) {
+      expect(cn(`text-${role}`, "text-chart-foreground-muted"), role).toBe(
+        `text-${role} text-chart-foreground-muted`,
+      );
+      expect(cn(`text-${role}`, "text-caption"), role).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");

package/src/lib/cn.ts

@@ -22,6 +22,13 @@ const TEXT_ROLES = [
   "kpi",
   "kpi-sm",
   "code",
+  // Chart type roles (RM-019, themes.css § chart type roles). They were missing
+  // here from RM-019 until the 2026-09-21 new-user test: `cn("text-chart-source",
+  // "text-chart-foreground-muted")` dropped the role and every ChartCard source
+  // row rendered at body size. `cn.test.ts` now derives the expected list from
+  // themes.css, so a new `--text-<role>` token cannot drift from this list again.
+  "chart-value",
+  "chart-source",
 ];
 
 /**