@heyramzi/ui 2.1.0 → 2.2.0

package/src/thread/thread.test.ts

@@ -6,57 +6,68 @@ const ada = { kind: "user", name: "Ada" } as const;
 const bot = { kind: "agent", name: "Scribe" } as const;
 
 function comment(id: string, at: string, extra: Partial<ThreadComment> = {}): ThreadComment {
-	return { id, author: ada, body: id, createdAt: at, ...extra };
+  return { id, author: ada, body: id, createdAt: at, ...extra };
 }
 
 describe("buildThread", () => {
-	it("puts replies under their root in time order", () => {
-		const nodes = buildThread([
-			comment("r2", "2026-10-22T10:05:00Z", { parentId: "a" }),
-			comment("a", "2026-10-22T10:00:00Z"),
-			comment("b", "2026-10-22T10:02:00Z", { author: bot }),
-			comment("r1", "2026-10-22T10:03:00Z", { parentId: "a" }),
-		]);
-		expect(nodes.map((n) => n.comment.id)).toEqual(["a", "b"]);
-		expect(nodes[0].replies.map((r) => r.id)).toEqual(["r1", "r2"]);
-	});
-
-	it("keeps a reply to a reply under the root", () => {
-		const nodes = buildThread([
-			comment("a", "2026-10-22T10:00:00Z"),
-			comment("r1", "2026-10-22T10:01:00Z", { parentId: "a" }),
-			comment("r2", "2026-10-22T10:02:00Z", { parentId: "r1" }),
-		]);
-		expect(nodes).toHaveLength(1);
-		expect(nodes[0].replies.map((r) => r.id)).toEqual(["r1", "r2"]);
-	});
-
-	it("turns an orphan reply into a root and survives a parent loop", () => {
-		const nodes = buildThread([
-			comment("x", "2026-10-22T10:00:00Z", { parentId: "gone" }),
-			comment("p", "2026-10-22T10:01:00Z", { parentId: "q" }),
-			comment("q", "2026-10-22T10:02:00Z", { parentId: "p" }),
-		]);
-		expect(nodes.map((n) => n.comment.id)).toContain("x");
-		expect(nodes.flatMap((n) => [n.comment.id, ...n.replies.map((r) => r.id)]).sort()).toEqual(["p", "q", "x"]);
-	});
-
-	it("sorts a malformed timestamp last", () => {
-		const nodes = buildThread([comment("bad", "soon"), comment("ok", "2026-10-22T10:00:00Z")]);
-		expect(nodes.map((n) => n.comment.id)).toEqual(["ok", "bad"]);
-	});
-
-	it("counts resolved roots", () => {
-		const nodes = buildThread([comment("a", "2026-10-22T10:00:00Z", { resolved: true }), comment("b", "2026-10-22T10:01:00Z")]);
-		expect(resolvedCount(nodes)).toBe(1);
-	});
+  it("puts replies under their root in time order", () => {
+    const nodes = buildThread([
+      comment("r2", "2026-10-22T10:05:00Z", { parentId: "a" }),
+      comment("a", "2026-10-22T10:00:00Z"),
+      comment("b", "2026-10-22T10:02:00Z", { author: bot }),
+      comment("r1", "2026-10-22T10:03:00Z", { parentId: "a" }),
+    ]);
+    expect(nodes.map((n) => n.comment.id)).toEqual(["a", "b"]);
+    expect(nodes[0].replies.map((r) => r.id)).toEqual(["r1", "r2"]);
+  });
+
+  it("keeps a reply to a reply under the root", () => {
+    const nodes = buildThread([
+      comment("a", "2026-10-22T10:00:00Z"),
+      comment("r1", "2026-10-22T10:01:00Z", { parentId: "a" }),
+      comment("r2", "2026-10-22T10:02:00Z", { parentId: "r1" }),
+    ]);
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].replies.map((r) => r.id)).toEqual(["r1", "r2"]);
+  });
+
+  it("turns an orphan reply into a root and survives a parent loop", () => {
+    const nodes = buildThread([
+      comment("x", "2026-10-22T10:00:00Z", { parentId: "gone" }),
+      comment("p", "2026-10-22T10:01:00Z", { parentId: "q" }),
+      comment("q", "2026-10-22T10:02:00Z", { parentId: "p" }),
+    ]);
+    expect(nodes.map((n) => n.comment.id)).toContain("x");
+    expect(nodes.flatMap((n) => [n.comment.id, ...n.replies.map((r) => r.id)]).sort()).toEqual([
+      "p",
+      "q",
+      "x",
+    ]);
+  });
+
+  it("sorts a malformed timestamp last", () => {
+    const nodes = buildThread([comment("bad", "soon"), comment("ok", "2026-10-22T10:00:00Z")]);
+    expect(nodes.map((n) => n.comment.id)).toEqual(["ok", "bad"]);
+  });
+
+  it("counts resolved roots", () => {
+    const nodes = buildThread([
+      comment("a", "2026-10-22T10:00:00Z", { resolved: true }),
+      comment("b", "2026-10-22T10:01:00Z"),
+    ]);
+    expect(resolvedCount(nodes)).toBe(1);
+  });
 });
 
 describe("labels", () => {
-	it("lets a host write French over the English defaults", () => {
-		const fr = resolveThreadLabels({ title: "Activité", send: "Commenter", showResolved: "Afficher {count} résolus" });
-		expect(fr.title).toBe("Activité");
-		expect(fr.cancel).toBe(DEFAULT_THREAD_LABELS.cancel);
-		expect(fillCount(fr.showResolved, 3)).toBe("Afficher 3 résolus");
-	});
+  it("lets a host write French over the English defaults", () => {
+    const fr = resolveThreadLabels({
+      title: "Activité",
+      send: "Commenter",
+      showResolved: "Afficher {count} résolus",
+    });
+    expect(fr.title).toBe("Activité");
+    expect(fr.cancel).toBe(DEFAULT_THREAD_LABELS.cancel);
+    expect(fillCount(fr.showResolved, 3)).toBe("Afficher 3 résolus");
+  });
 });

package/src/thread/types.ts

@@ -1,93 +1,93 @@
 export type ThreadAuthorKind = "user" | "agent";
 
 export type ThreadAuthor = {
-	kind: ThreadAuthorKind;
-	name: string;
-	/** Image URL for a person. The host's own portrait goes through the `avatar` snippet. */
-	avatar?: string;
+  kind: ThreadAuthorKind;
+  name: string;
+  /** Image URL for a person. The host's own portrait goes through the `avatar` snippet. */
+  avatar?: string;
 };
 
 /** Where on a canvas a comment is pinned: a node and an offset from it, or a point. */
 export type ThreadAnchor = {
-	nodeId?: string;
-	dx?: number;
-	dy?: number;
-	x?: number;
-	y?: number;
+  nodeId?: string;
+  dx?: number;
+  dy?: number;
+  x?: number;
+  y?: number;
 };
 
 /** One comment on any subject. The host resolves the author's name. */
 export type ThreadComment = {
-	id: string;
-	author: ThreadAuthor;
-	/** Plain text, shown as written. Also the fallback when `content` is missing. */
-	body: string;
-	/** Tiptap JSON. When set, the thread draws it through the editor's renderer instead of `body`. */
-	content?: Record<string, unknown>;
-	/** ISO timestamp. */
-	createdAt: string;
-	/** Set when the body changed after posting. */
-	edited?: boolean;
-	/** The comment this one answers. A reply to a reply sits under the same root. */
-	parentId?: string | null;
-	/** Only a root carries it: the whole conversation is resolved. */
-	resolved?: boolean;
-	anchor?: ThreadAnchor | null;
+  id: string;
+  author: ThreadAuthor;
+  /** Plain text, shown as written. Also the fallback when `content` is missing. */
+  body: string;
+  /** Tiptap JSON. When set, the thread draws it through the editor's renderer instead of `body`. */
+  content?: Record<string, unknown>;
+  /** ISO timestamp. */
+  createdAt: string;
+  /** Set when the body changed after posting. */
+  edited?: boolean;
+  /** The comment this one answers. A reply to a reply sits under the same root. */
+  parentId?: string | null;
+  /** Only a root carries it: the whole conversation is resolved. */
+  resolved?: boolean;
+  anchor?: ThreadAnchor | null;
 };
 
 export type ThreadPost = {
-	body: string;
-	parentId: string | null;
-	anchor?: ThreadAnchor | null;
+  body: string;
+  parentId: string | null;
+  anchor?: ThreadAnchor | null;
 };
 
 /** A root comment with its replies in time order. */
 export type ThreadNode = {
-	comment: ThreadComment;
-	replies: ThreadComment[];
+  comment: ThreadComment;
+  replies: ThreadComment[];
 };
 
 export type ThreadLabels = {
-	title: string;
-	empty: string;
-	placeholder: string;
-	replyPlaceholder: string;
-	send: string;
-	sending: string;
-	reply: string;
-	edit: string;
-	delete: string;
-	edited: string;
-	save: string;
-	cancel: string;
-	resolve: string;
-	unresolve: string;
-	resolved: string;
-	/** Shows `{count}` resolved conversations. */
-	showResolved: string;
-	hideResolved: string;
-	agent: string;
-	pinned: string;
+  title: string;
+  empty: string;
+  placeholder: string;
+  replyPlaceholder: string;
+  send: string;
+  sending: string;
+  reply: string;
+  edit: string;
+  delete: string;
+  edited: string;
+  save: string;
+  cancel: string;
+  resolve: string;
+  unresolve: string;
+  resolved: string;
+  /** Shows `{count}` resolved conversations. */
+  showResolved: string;
+  hideResolved: string;
+  agent: string;
+  pinned: string;
 };
 
 export const DEFAULT_THREAD_LABELS: ThreadLabels = {
-	title: "Activity",
-	empty: "No comments yet",
-	placeholder: "Leave a comment",
-	replyPlaceholder: "Reply",
-	send: "Comment",
-	sending: "Sending",
-	reply: "Reply",
-	edit: "Edit comment",
-	delete: "Delete comment",
-	edited: "edited",
-	save: "Save",
-	cancel: "Cancel",
-	resolve: "Resolve",
-	unresolve: "Reopen",
-	resolved: "Resolved",
-	showResolved: "Show {count} resolved",
-	hideResolved: "Hide resolved",
-	agent: "AI",
-	pinned: "Pinned",
+  title: "Activity",
+  empty: "No comments yet",
+  placeholder: "Leave a comment",
+  replyPlaceholder: "Reply",
+  send: "Comment",
+  sending: "Sending",
+  reply: "Reply",
+  edit: "Edit comment",
+  delete: "Delete comment",
+  edited: "edited",
+  save: "Save",
+  cancel: "Cancel",
+  resolve: "Resolve",
+  unresolve: "Reopen",
+  resolved: "Resolved",
+  showResolved: "Show {count} resolved",
+  hideResolved: "Hide resolved",
+  agent: "AI",
+  pinned: "Pinned",
 };

package/src/tokens/craft.css

@@ -1,8 +1,6 @@
 /* ── Radius, by role not by size ─────────────────────────────
-   A chip inside a control inside a card has to read as nested, which needs
-   three radii that step, not one radius reused. The Tailwind names are the
-   home so `rounded-lg` on a button already resolves to the control radius and
-   no component has to learn a new class. */
+   These override Tailwind's own names, so `rounded-lg` on a button already
+   resolves to the control radius. */
 @theme {
   --radius-xs: 4px; /* tag, dot, inline code */
   --radius-sm: 6px; /* chip, badge, small pill */
@@ -14,30 +12,9 @@
 }
 
 /* ── Elevation ───────────────────────────────────────────────
-   Four steps of lift, plus the two edges that are not lift.
-
-   WHY the steps are shadow-only and the hairline is its own token: most boxes
-   in a kit already draw a border, and an elevation that bakes a `0 0 0 1px`
-   ring into every step gives those boxes two edges a pixel apart. Compose them
-   where a component drops its border:
-
-     box-shadow: var(--elev-hairline), var(--elev-card);
-
-   WHY each step is stacked rather than one blurred drop: a single shadow reads
-   as a sticker. Depth is several offsets falling off together, which is what
-   the eye reads as distance. They cost nothing extra because every stop is the
-   same colour at a different alpha.
-
-   WHY the blur radii are large and the alphas small: a 4px blur at 20% draws a
-   visible grey edge, which the eye reads as a second border. A 28px blur at 7%
-   is barely a colour anywhere and reads as height. Reach for more blur before
-   more alpha, every time.
-
-   `--elev-tint` is the one knob an app turns. Pure black greys a warm palette
-   out; the hue of the app's own darkest surface keeps the shadow in the
-   family. */
+   The steps carry no ring, since a bordered box would get two edges a pixel
+   apart; a borderless one adds `var(--elev-hairline)` in front. */
 :root {
-
   /* Resting on the page. A button, a chip, a row. */
   --elev-btn:
     0 1px 1px -0.5px color-mix(in oklab, var(--elev-tint) 7%, transparent),
@@ -61,9 +38,8 @@
     0 12px 26px -8px color-mix(in oklab, var(--elev-tint) 12%, transparent),
     0 40px 72px -20px color-mix(in oklab, var(--elev-tint) 20%, transparent);
 
-  /* The two edges. A hairline separates a surface from what is behind it; a rim
-     is the light catching its top edge, which is what makes a filled control
-     read as a physical key rather than a coloured rectangle. */
+  /* A hairline separates a surface from what's behind it; a rim is light on the
+     top edge, which makes a filled control read as a key. */
   --elev-hairline: 0 0 0 1px var(--color-border, var(--border));
   --elev-rim: inset 0 1px 0 color-mix(in oklab, white 16%, transparent);
 
@@ -71,10 +47,8 @@
   --elev-field: inset 0 1px 2px color-mix(in oklab, var(--elev-tint) 7%, transparent);
 }
 
-/* A dark surface cannot cast a darker shadow than the page it sits on, so the
-   hairline does the separating and the shadow only sinks what is behind it. On
-   dark the hairline is white at a low alpha, which is what reads as a lit edge
-   rather than as a drawn border. */
+/* A shadow can't get darker than a dark page, so on dark the low-alpha white
+   hairline does the separating. */
 .dark {
   --elev-btn: 0 1px 2px color-mix(in oklab, black 30%, transparent);
   --elev-card:
@@ -93,25 +67,19 @@
 }
 
 /* ── Focus ───────────────────────────────────────────────────
-   One ring, two parts: a solid edge that redraws the control's own outline in
-   the accent, and a soft halo that carries it off the surface. Written as a
-   variable so a component spends one line on it and every control focuses the
-   same way. */
+   One variable, so every control focuses the same way: a solid accent edge,
+   then a soft halo. */
 :root {
   --ring-color: var(--color-ring, var(--ring));
   --ring-halo: color-mix(in oklab, var(--ring-color) 16%, transparent);
-  /* A solid pixel redrawing the control's own edge, then a wide soft band. At a
-     higher alpha the band reads as a second border rather than as a glow, which
-     is why it is 16% over 4px and not 30% over 2px. */
+  /* The halo is 16% over 4px, not 30% over 2px, because a stronger band reads
+     as a second border instead of a glow. */
   --ring-focus: 0 0 0 1px var(--ring-color), 0 0 0 5px var(--ring-halo);
 }
 
 /* ── Motion ──────────────────────────────────────────────────
-   The transitions-dev scale, verbatim, so a snippet pasted from that skill and
-   a component written here read from the same names.
-
-   The doctrine in one line: an open is an invitation and a close should get out
-   of the way, so every close is shorter than its open and no close bounces. */
+   The transitions-dev scale, verbatim, so a pasted snippet reads the same
+   names. Every close is shorter than its open, and no close bounces. */
 :root {
   --duration-stagger: 40ms;
   --duration-micro: 80ms;
@@ -163,13 +131,9 @@
 
   --ease-smooth-out: var(--ease-smooth-out);
 
-  /* WHY the durations are re-declared under a second name: Tailwind's
-     `duration-*` utility reads `--transition-duration-*`, not `--duration-*`, so
-     the six names above generated no class at all. `duration-fast` therefore
-     compiled to nothing and the element ended up at `transition-duration: 0s`:
-     no error, no warning, and a component that simply does not animate. The
-     comment at the top of this block had claimed `duration-fast` was a class
-     since the block was written. Found 31 Aug 2026 by probing a live page. */
+  /* Tailwind's `duration-*` reads `--transition-duration-*`, so without these
+     `duration-fast` silently compiles to nothing and the element doesn't animate
+     (31 Aug 2026). */
   --transition-duration-micro: var(--duration-micro);
   --transition-duration-quick: var(--duration-quick);
   --transition-duration-fast: var(--duration-fast);

package/src/tokens/index.css

@@ -1,16 +1,6 @@
-/* tokens.css
- *
- * The shared style layer for @heyramzi/ui, imported once after Tailwind:
- *
- *   @import "tailwindcss";
- *   @import "@heyramzi/ui/tokens.css";
- *   @import "@heyramzi/ui/animations";
- *   @import "@heyramzi/ui/shadcn/utilities.css"; // only if you use Attachment or Message
- *
- * It carries three things: the color palette and semantic tokens, the craft
- * layer (radius, elevation, focus and motion), and the small set of motion
- * primitives the components share. Override any variable on :root to retheme.
- * The parts load in this order because later blocks read earlier variables.
+/* tokens.css: import once, right after `@import "tailwindcss"`. Override any
+ * variable on :root to retheme; the parts load in this order because later ones
+ * read earlier variables.
  */
 
 @import "./palette.css";

package/src/tokens/palette.css

@@ -22,9 +22,8 @@
   --gray-900: oklch(0.15 0 0); /* Near-black — headings, primary text */
 
   /* === Brand roles ===
-     The look of a product, named by what each colour does. These defaults are neutral, and a
-     brand replaces them through `@heyramzi/ui/brand` (typed colours, no build step). Every
-     other token below reads from these, so nothing else in the package names a hue. */
+     Neutral defaults a brand replaces through `@heyramzi/ui/brand`; every token below reads
+     from these, so nothing else in the package names a hue. */
   --brand: oklch(0.28 0 0); /* The signature colour: focus ring, links, active states, the mark */
   --brand-on-dark: oklch(0.92 0 0); /* The same colour lifted for a dark page */
   --brand-highlight: oklch(0.78 0 0); /* Warmth: badges, highlights, soft accents */
@@ -39,9 +38,9 @@
   --brand-surface-light: oklch(0.99 0 0); /* Cards on a light page */
   --brand-line-light: oklch(0.91 0 0); /* Borders on a light page */
 
-  /* === Tint scales, derived from the three hues so a brand types one colour each ===
-     WHY mixes and not typed steps: a brand that sets `--brand` gets a matching 100 to 800
-     with nothing else to maintain. 400 is the colour lifted for dark, 600 the colour itself. */
+  /* === Tint scales ===
+     Mixed from the three hues so `--brand` alone yields 100 to 800; 400 is the colour lifted
+     for dark, 600 the colour itself. */
   --brand-100: color-mix(in oklab, var(--brand) 12%, white);
   --brand-200: color-mix(in oklab, var(--brand) 28%, white);
   --brand-400: var(--brand-on-dark);
@@ -117,8 +116,7 @@
   --sidebar-ring: var(--brand);
 
   /* === Shadow tint ===
-     The one knob the design layer exposes. Pure black greys out warm surfaces,
-     so the shadow takes the darkest surface's hue. Radius, focus and motion live there. */
+     Pure black greys out warm surfaces, so the shadow takes the darkest surface's hue. */
   --elev-tint: var(--brand-ink);
 }
 
@@ -198,14 +196,18 @@
   --color-cat-indigo: var(--cat-indigo);
   --color-cat-purple: var(--cat-purple);
 
-  /* A hue as text or icon on its own tint: 40% toward the foreground clears AA in both themes.
-     A tone's 10% tint under plain destructive text is 3.6:1; the ink mix is not. */
+  /* A hue as text on its own tint mixes 40% toward the foreground to clear AA in both themes,
+     where plain destructive text on that tint is 3.6:1. */
   --color-cat-cyan-ink: color-mix(in oklab, var(--color-cat-cyan) 60%, var(--color-foreground));
   --color-cat-teal-ink: color-mix(in oklab, var(--color-cat-teal) 60%, var(--color-foreground));
   --color-cat-purple-ink: color-mix(in oklab, var(--color-cat-purple) 60%, var(--color-foreground));
   --color-cat-amber-ink: color-mix(in oklab, var(--color-cat-amber) 60%, var(--color-foreground));
   --color-success-ink: color-mix(in oklab, var(--color-success) 60%, var(--color-foreground));
-  --color-destructive-ink: color-mix(in oklab, var(--color-destructive) 60%, var(--color-foreground));
+  --color-destructive-ink: color-mix(
+    in oklab,
+    var(--color-destructive) 60%,
+    var(--color-foreground)
+  );
 
   /* Light theme color system: the light surfaces and lines of the brand roles */
   --color-background: var(--gray-50);

package/src/tokens/primitives.css

@@ -1,11 +1,5 @@
-/* The bits-ui state variants every primitive in `./shadcn` is written against.
- *
- * bits-ui v2 writes `data-checked` / `data-open` and v1 wrote
- * `data-state="checked"`, so each variant matches both and a component does not
- * have to know which it is talking to. They live here rather than in a
- * consumer's stylesheet because the classes that need them ship in this
- * package: an app that defines only the palette would render a switch that
- * never moves. */
+/* Each variant matches both bits-ui v2's `data-checked` and v1's `data-state="checked"`, and
+ * ships here because an app that defines only the palette gets a switch that never moves. */
 @custom-variant data-open {
   &:where([data-state="open"]),
   &:where([data-open]:not([data-open="false"])) {
@@ -80,9 +74,8 @@
     background: color-mix(in oklab, var(--ring-color) 24%, transparent);
   }
 
-  /* A default macOS overlay scrollbar paints a black bar on a dark panel. Track
-     transparent, thumb on the line token, so it belongs to whatever surface it
-     is over. The border is what insets the thumb without a second element. */
+  /* A default macOS overlay scrollbar paints a black bar on a dark panel, so the track stays
+     transparent and the thumb takes the line token. */
   :where(html) {
     scrollbar-color: var(--color-border, var(--border)) transparent;
   }
@@ -111,16 +104,11 @@
 }
 
 @layer components {
-  /* Three moves the kit repeats. They are classes rather than tokens because a
-     component wants one name, not four declarations, and because the reduced
-     motion guard then lives in one place instead of in every component.
+  /* Classes, not tokens, so a component takes one name and the reduced-motion guard lives in
+     one place; the `t-` prefix matches the transitions-dev snippets. */
 
-     Namespaced `t-` to match the transitions-dev snippets, which these sit
-     beside rather than duplicate. */
-
-  /* A control that reads as a key: it travels down a pixel under the finger.
-     The travel is what sells it, because a colour change alone reads as a hover
-     state, not as a press. */
+  /* A key-like control travels down a pixel under the finger, because a colour change alone
+     reads as a hover, not a press. */
   .t-press {
     transition:
       background-color var(--duration-quick) var(--ease-smooth-out),
@@ -134,9 +122,8 @@
     transform: translateY(1px);
   }
 
-  /* A card that answers the pointer. It rises by a pixel and gains the next
-     step of elevation, so the hover reads as the card coming forward rather
-     than as its border changing colour. */
+  /* A hover card rises a pixel and gains the next elevation step, so it reads as coming
+     forward, not as its border changing colour. */
   .t-lift {
     transition:
       box-shadow var(--duration-fast) var(--ease-smooth-out),