@heyramzi/ui 2.23.0 → 3.0.0

package/src/status/status-icon.svelte

@@ -10,21 +10,34 @@
 		status: string;
 		size?: number;
 		animate?: boolean;
+		/** Names the icon for a screen reader, like the status word. Leave it out when the word is printed beside it. */
+		label?: string;
 		class?: string;
 	}
 
-	let { statuses, status, size = 14, animate = true, class: className }: Props = $props();
+	let { statuses, status, size = 14, animate = true, label, class: className }: Props = $props();
 
 	// An icon in the map wins; otherwise the status falls back to its dot.
 	let icon = $derived(
-		statuses.icon(status) as Component<{ size?: number; class?: string }> | undefined,
+		statuses.icon(status) as
+			| Component<{ size?: number; class?: string; "aria-hidden"?: boolean | "true" | "false" }>
+			| undefined,
 	);
 	let tone = $derived(statuses.tone(status));
 </script>
 
-{#if icon}
-	{@const Icon = icon}
-	<Icon {size} class={cn("shrink-0", TONE_ICON[tone], className)} />
+{#snippet mark()}
+	{#if icon}
+		{@const Icon = icon}
+		<Icon aria-hidden="true" {size} class={cn("shrink-0", TONE_ICON[tone], className)} />
+	{:else}
+		<StatusDot {statuses} {status} {size} {animate} class={className} />
+	{/if}
+{/snippet}
+
+<!-- Decorative by default: the status word usually sits beside it. Alone, `label` names it. -->
+{#if label}
+	<span role="img" aria-label={label} class="inline-flex shrink-0">{@render mark()}</span>
 {:else}
-	<StatusDot {statuses} {status} {size} {animate} class={className} />
+	{@render mark()}
 {/if}

package/src/status/status-icon.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Component } from "svelte";
+import type { Statuses } from "./status-types.js";
+interface Props {
+    statuses: Statuses;
+    status: string;
+    size?: number;
+    animate?: boolean;
+    /** Names the icon for a screen reader, like the status word. Leave it out when the word is printed beside it. */
+    label?: string;
+    class?: string;
+}
+declare const $$Component: Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/status/status-pill.svelte

@@ -1,13 +1,7 @@
-<script lang="ts" module>
-	import type { Tone } from "../lib/tone.js";
-	import { PILL_TINT } from "./pill-tint.js";
-
-	export { PILL_TINT };
-</script>
-
 <script lang="ts">
 	import type { Snippet } from "svelte";
 	import type { HTMLAttributes } from "svelte/elements";
+	import { TONE_TINT, type Tone } from "../lib/tone.js";
 	import { cn } from "../lib/utils.js";
 
 	interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "class" | "children"> {
@@ -30,7 +24,7 @@
 		"transition-[background-color,color] duration-quick ease-smooth-out motion-reduce:transition-none",
 		"[&>svg]:size-3 [&>svg]:shrink-0",
 		icon && "pl-1.5",
-		PILL_TINT[tone],
+		TONE_TINT[tone],
 		className,
 	)}
 	{...restProps}

package/src/status/status-pill.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import { type Tone } from "../lib/tone.js";
+interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "class" | "children"> {
+    tone?: Tone;
+    /** What sits before the label: a Phosphor icon, a `StatusIcon`, a dot or a spinner. */
+    icon?: Snippet;
+    children?: Snippet;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/test-setup.test.ts

@@ -0,0 +1,5 @@
+import { MediaQuery } from "svelte/reactivity";
+import { expect, it } from "vite-plus/test";
+it("has matchMedia before any import runs", () => {
+  expect(new MediaQuery("(min-width: 1px)").current).toBe(false);
+});

package/src/thread/thread-body.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    text: string;
+    more: string;
+    less: string;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/thread/thread-events.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { ThreadEvent } from "./types.js";
+interface Props {
+    events: ThreadEvent[];
+    when: (event: ThreadEvent) => string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/thread/thread-focus.svelte.test.ts

@@ -0,0 +1,90 @@
+import { flushSync, mount, tick, unmount } from "svelte";
+import { describe, expect, it } from "vite-plus/test";
+import Thread from "./thread.svelte";
+import { DEFAULT_THREAD_LABELS, type ThreadComment } from "./types.js";
+
+const ada = { kind: "user", name: "Ada" } as const;
+
+function comment(id: string, minute: number): ThreadComment {
+  return { id, author: ada, body: `Body ${id}`, createdAt: `2026-10-22T10:0${minute}:00Z` };
+}
+
+function render() {
+  const props = $state({
+    comments: [comment("a", 0), comment("b", 1), comment("c", 2)],
+    canEdit: () => true,
+    onPost: () => {},
+    onEdit: () => {},
+    onDelete: (gone: ThreadComment) => {
+      props.comments = props.comments.filter((c) => c.id !== gone.id);
+    },
+  });
+  const target = document.createElement("div");
+  document.body.appendChild(target);
+  const app = mount(Thread, { target, props });
+  flushSync();
+  const q = <E extends Element = HTMLElement>(selector: string) =>
+    target.querySelector(selector) as E | null;
+  return {
+    q,
+    press: (key: string) =>
+      document.activeElement?.dispatchEvent(new KeyboardEvent("keydown", { key, bubbles: true })),
+    done: () => {
+      void unmount(app);
+      target.remove();
+    },
+  };
+}
+
+async function settle() {
+  for (let i = 0; i < 4; i++) await tick();
+  flushSync();
+}
+
+const { edit, cancel, save, reply } = DEFAULT_THREAD_LABELS;
+
+describe("Thread focus", () => {
+  it("moves focus into the edit box, and back to Edit on Esc, Cancel and Save", async () => {
+    const { q, press, done } = render();
+    const editOf = () => q(`[data-comment="b"] [aria-label="${edit}"]`);
+    for (const close of ["Escape", cancel, save]) {
+      editOf()?.click();
+      await settle();
+      expect(document.activeElement).toBe(q('[data-thread-edit-box="b"]'));
+      if (close === "Escape") press("Escape");
+      else
+        [...document.querySelectorAll("button")]
+          .find((b) => b.textContent?.trim() === close)
+          ?.click();
+      await settle();
+      expect(q('[data-thread-edit-box="b"]')).toBeNull();
+      expect(document.activeElement).toBe(editOf());
+    }
+    done();
+  });
+
+  it("closes a reply on Esc and puts focus back on its Reply button", async () => {
+    const { q, press, done } = render();
+    q('[data-thread-reply="a"]')?.click();
+    await settle();
+    expect(document.activeElement?.getAttribute("aria-label")).toBe(
+      DEFAULT_THREAD_LABELS.replyPlaceholder,
+    );
+    press("Escape");
+    await settle();
+    expect(document.activeElement).toBe(q('[data-thread-reply="a"]'));
+    expect(document.activeElement?.textContent?.trim()).toBe(reply);
+    done();
+  });
+
+  it("moves focus to the next comment after a delete, then the one before", async () => {
+    const { q, done } = render();
+    q(`[data-comment="b"] [aria-label="${DEFAULT_THREAD_LABELS.delete}"]`)?.click();
+    await settle();
+    expect(document.activeElement).toBe(q('[data-comment="c"]'));
+    q(`[data-comment="c"] [aria-label="${DEFAULT_THREAD_LABELS.delete}"]`)?.click();
+    await settle();
+    expect(document.activeElement).toBe(q('[data-comment="a"]'));
+    done();
+  });
+});

package/src/thread/thread.svelte

@@ -2,6 +2,8 @@
 	import type { Snippet } from "svelte";
 	import { ArrowBendDownRight, Check, MapPin, PencilSimple, Trash } from "phosphor-svelte";
 	import { cn } from "../lib/utils.js";
+	import { focusAfterRender } from "../lib/focus.js";
+	import { shortDate } from "../lib/dates.js";
 	import { initial } from "../lib/initials.js";
 	import { AgentAvatar } from "../agents/index.js";
 	import RichRenderer from "../editor/renderer.svelte";
@@ -64,8 +66,8 @@
 		avatar,
 		attachments,
 		anchorChip,
-		when = (comment) => shortDate(comment.createdAt),
-		whenEvent = (event) => shortDate(event.at),
+		when = (comment) => shortDate(comment.createdAt, { locale }),
+		whenEvent = (event) => shortDate(event.at, { locale }),
 		onPost,
 		onEdit,
 		onDelete,
@@ -84,16 +86,13 @@
 	let shown = $derived(showResolved ? nodes : nodes.filter((node) => !node.comment.resolved));
 	let items = $derived(interleave(shown, events));
 
-	function shortDate(at: string): string {
-		return new Intl.DateTimeFormat(locale, { month: "short", day: "numeric" }).format(new Date(at));
-	}
-
 	let draft = $state("");
 	let replyTo = $state<string | null>(null);
 	let replyDraft = $state("");
 	let sending = $state(false);
 	let editingId = $state<string | null>(null);
 	let editDraft = $state("");
+	let threadEl: HTMLElement | undefined = $state();
 
 	async function post(body: string, parentId: string | null): Promise<boolean> {
 		const text = body.trim();
@@ -108,28 +107,66 @@
 
 	async function sendRoot(): Promise<void> {
 		if (await post(draft, null)) draft = "";
+		// The emptied draft disables Send, which drops focus to the page.
+		if (document.activeElement === document.body) {
+			await focusAfterRender(threadEl, "[data-thread-composer]");
+		}
 	}
 
 	async function sendReply(): Promise<void> {
-		if (await post(replyDraft, replyTo)) {
-			replyDraft = "";
-			replyTo = null;
-		}
+		if (await post(replyDraft, replyTo)) closeReply();
+	}
+
+	function closeReply(): void {
+		const parentId = replyTo;
+		replyDraft = "";
+		replyTo = null;
+		void focusAfterRender(threadEl, `[data-thread-reply="${CSS.escape(parentId ?? "")}"]`);
 	}
 
-	function submitOnModEnter(event: KeyboardEvent, send: () => Promise<void>): void {
+	function onComposerKey(event: KeyboardEvent, send: () => Promise<void>, isReply: boolean): void {
 		if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
 			event.preventDefault();
 			void send();
+		} else if (event.key === "Escape" && isReply) {
+			event.preventDefault();
+			closeReply();
 		}
 	}
 
+	function openEdit(comment: ThreadComment): void {
+		editingId = comment.id;
+		editDraft = comment.body;
+		void focusAfterRender(threadEl, `[data-thread-edit-box="${CSS.escape(comment.id)}"]`);
+	}
+
+	function closeEdit(id: string): void {
+		editingId = null;
+		void focusAfterRender(threadEl, `[data-thread-edit="${CSS.escape(id)}"]`);
+	}
+
 	async function saveEdit(comment: ThreadComment): Promise<void> {
 		const body = editDraft.trim();
-		editingId = null;
+		closeEdit(comment.id);
 		if (!body || body === comment.body) return;
 		await onEdit?.(comment, body);
 	}
+
+	// Focus lands on the next comment still shown, then the one before, the composer, the thread.
+	async function remove(comment: ThreadComment): Promise<void> {
+		const ids = [...(threadEl?.querySelectorAll<HTMLElement>("[data-comment]") ?? [])].map(
+			(el) => el.dataset.comment ?? "",
+		);
+		const at = ids.indexOf(comment.id);
+		const around = [...ids.slice(at + 1), ...ids.slice(0, at).reverse()];
+		await onDelete?.(comment);
+		await focusAfterRender(
+			threadEl,
+			...around.map((id) => `[data-comment="${CSS.escape(id)}"]`),
+			"[data-thread-composer]",
+			threadEl,
+		);
+	}
 </script>
 
 {#snippet composer(
@@ -146,11 +183,12 @@
 		<textarea
 			{value}
 			oninput={(event) => set(event.currentTarget.value)}
-			onkeydown={(event) => submitOnModEnter(event, onSend)}
+			onkeydown={(event) => onComposerKey(event, onSend, isReply)}
 			rows={2}
 			{placeholder}
 			aria-label={placeholder}
 			autofocus={isReply}
+			data-thread-composer={isReply ? undefined : ""}
 			class="block max-h-60 min-h-16 w-full resize-none border-0 bg-transparent px-3 py-2 text-sm leading-relaxed outline-none [field-sizing:content] placeholder:text-muted-foreground"
 		></textarea>
 		<div class="flex justify-end px-2 pb-2">
@@ -162,7 +200,11 @@
 {/snippet}
 
 {#snippet row(comment: ThreadComment, isRoot: boolean)}
-	<div class="group/row hover-row relative flex gap-3">
+	<div
+		data-comment={comment.id}
+		tabindex="-1"
+		class="group/row hover-row relative flex gap-3 rounded-md outline-none focus-visible:shadow-(--ring-focus)"
+	>
 		<span class="relative size-6 shrink-0">
 			{#if avatar}
 				{@render avatar(comment)}
@@ -229,10 +271,8 @@
 									size="sm"
 									icon
 									aria-label={labels.edit}
-									onclick={() => {
-										editingId = comment.id;
-										editDraft = comment.body;
-									}}
+									data-thread-edit={comment.id}
+									onclick={() => openEdit(comment)}
 								>
 									<PencilSimple class="size-3.5" aria-hidden="true" />
 								</Button>
@@ -243,7 +283,7 @@
 									size="sm"
 									icon
 									aria-label={labels.delete}
-									onclick={() => onDelete?.(comment)}
+									onclick={() => remove(comment)}
 								>
 									<Trash class="size-3.5" aria-hidden="true" />
 								</Button>
@@ -258,10 +298,16 @@
 					bind:value={editDraft}
 					rows={3}
 					aria-label={labels.edit}
+					data-thread-edit-box={comment.id}
+					onkeydown={(event) => {
+						if (event.key !== "Escape") return;
+						event.preventDefault();
+						closeEdit(comment.id);
+					}}
 					class="mt-1 w-full resize-y rounded-md border border-input bg-transparent px-2.5 py-2 text-sm leading-relaxed outline-none focus-visible:border-ring focus-visible:shadow-(--ring-focus)"
 				></textarea>
 				<div class="mt-2 flex justify-end gap-1.5">
-					<Button variant="ghost" size="sm" onclick={() => (editingId = null)}
+					<Button variant="ghost" size="sm" onclick={() => closeEdit(comment.id)}
 						>{labels.cancel}</Button
 					>
 					<Button size="sm" onclick={() => saveEdit(comment)}>{labels.save}</Button>
@@ -281,7 +327,12 @@
 	</div>
 {/snippet}
 
-<section aria-label={labels.title} class={cn("flex flex-col gap-3", className)}>
+<section
+	bind:this={threadEl}
+	tabindex="-1"
+	aria-label={labels.title}
+	class={cn("flex flex-col gap-3 outline-none", className)}
+>
 	<div class={cn("flex h-7 items-center justify-between", !heading && resolved === 0 && "sr-only")}>
 		<h2 class={cn("text-xs font-medium text-muted-foreground", !heading && "sr-only")}>
 			{labels.title}
@@ -348,6 +399,7 @@
 									variant="ghost"
 									size="sm"
 									class="ms-9 w-fit"
+									data-thread-reply={node.comment.id}
 									onclick={() => {
 										replyTo = node.comment.id;
 										replyDraft = "";

package/src/thread/thread.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { Snippet } from "svelte";
+import type { ThreadComment, ThreadEvent, ThreadLabels, ThreadPost } from "./types.js";
+interface Props {
+    comments: ThreadComment[];
+    /** Status moves, assignments and the like, one quiet line each between the comments. */
+    events?: ThreadEvent[];
+    /** Rows still on their way. Draws skeleton rows in place of the thread. */
+    loading?: boolean;
+    labels?: Partial<ThreadLabels>;
+    /** Replaces the default avatar for a person or an agent, drawn in a 24px slot. */
+    avatar?: Snippet<[ThreadComment]>;
+    /** Content under a comment's body, such as files. */
+    attachments?: Snippet<[ThreadComment]>;
+    /** Replaces the default "Pinned" chip on a comment that has an anchor. */
+    anchorChip?: Snippet<[ThreadComment]>;
+    /** How a timestamp reads. Defaults to a short date. */
+    when?: (comment: ThreadComment) => string;
+    /** How an event's time reads. Defaults to a short date. */
+    whenEvent?: (event: ThreadEvent) => string;
+    /** The locale the default times read in. */
+    locale?: string;
+    /** Returns false to keep the draft. Without it no composer shows. */
+    onPost?: (post: ThreadPost) => void | boolean | Promise<void | boolean>;
+    onEdit?: (comment: ThreadComment, body: string) => void | Promise<void>;
+    onDelete?: (comment: ThreadComment) => void | Promise<void>;
+    /** Without it a root has no resolve button. */
+    onResolve?: (comment: ThreadComment, resolved: boolean) => void | Promise<void>;
+    /** A click on a pinned comment's chip, to move a canvas to its node. */
+    onAnchor?: (comment: ThreadComment) => void;
+    /** Whose comments carry the edit and delete buttons. A rich comment can't be edited here. */
+    canEdit?: (comment: ThreadComment) => boolean;
+    /** False hides the visible title, for a thread already named by its tab. Screen readers still get it. */
+    heading?: boolean;
+    /** Drawn above the composer, such as a question waiting on an answer. */
+    footer?: Snippet;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/tokens/base.css

@@ -1,29 +1,29 @@
-/* The shadow family, now valued by @heyramzi/ui/design. Names stay because
+@layer theme, base, components, utilities;
+
+/* The shadow family, valued by craft.css. Names stay because
    170-odd call sites use them. Shadow only, since these elements draw their own border. */
 
-/* New work: use `shadow-btn`, `shadow-card`, `shadow-raised` and `shadow-overlay`. */
-@layer utilities {
-  .shadow-soft-sm {
-    box-shadow: var(--elev-btn);
-  }
+/* New work: use `shadow-btn`, `shadow-card`, `shadow-raised` and `shadow-overlay`.
+   `@utility`, so `hover:shadow-soft-md` and the other variants work. */
+@utility shadow-soft-sm {
+  box-shadow: var(--elev-btn);
+}
 
-  .shadow-soft {
-    box-shadow: var(--elev-card);
-  }
+@utility shadow-soft {
+  box-shadow: var(--elev-card);
+}
 
-  .shadow-soft-md {
-    box-shadow: var(--elev-raised);
-  }
+@utility shadow-soft-md {
+  box-shadow: var(--elev-raised);
+}
 
-  /* The one step that answers a pointer rather than describing a resting
-     height, so it borrows the step above whatever it was at rest. */
-  .shadow-soft-hover {
-    box-shadow: var(--elev-raised);
-  }
+/* The one step that answers a pointer rather than describing a resting
+   height, so it borrows the step above whatever it was at rest. */
+@utility shadow-soft-hover {
+  box-shadow: var(--elev-raised);
 }
 
-/* The nine bits-ui state variants moved into `@heyramzi/ui/design` on 14 Sep
-   2026. app.css imports that before this file. */
+/* The nine bits-ui state variants live in primitives.css. */
 
 @utility no-scrollbar {
   -ms-overflow-style: none;
@@ -54,35 +54,37 @@
   }
 }
 
-/* WHY: below sm the dialog docks as a bottom sheet. The .t-modal scale would lift
-   it off the edge. A sheet enters from the edge it rests on. */
-@media (max-width: 639px) {
-  [data-slot="dialog-content"]:not([data-command-dialog]).t-modal {
-    transform: translateY(100%);
-    transition:
-      transform var(--modal-open-dur) var(--modal-ease),
-      opacity var(--modal-open-dur) var(--modal-ease);
-  }
-  [data-slot="dialog-content"]:not([data-command-dialog]).t-modal[data-state="open"] {
-    transform: translateY(0);
-  }
-  [data-slot="dialog-content"]:not([data-command-dialog]).t-modal[data-state="closed"] {
-    transform: translateY(100%);
-    transition:
-      transform var(--modal-close-dur) var(--modal-ease),
-      opacity var(--modal-close-dur) var(--modal-ease);
+@layer components {
+  /* WHY: below sm the dialog docks as a bottom sheet. The .t-modal scale would lift
+     it off the edge. A sheet enters from the edge it rests on. */
+  @media (max-width: 639px) {
+    [data-slot="dialog-content"]:not([data-command-dialog]).t-modal {
+      transform: translateY(100%);
+      transition:
+        transform var(--modal-open-dur) var(--modal-ease),
+        opacity var(--modal-open-dur) var(--modal-ease);
+    }
+    [data-slot="dialog-content"]:not([data-command-dialog]).t-modal[data-state="open"] {
+      transform: translateY(0);
+    }
+    [data-slot="dialog-content"]:not([data-command-dialog]).t-modal[data-state="closed"] {
+      transform: translateY(100%);
+      transition:
+        transform var(--modal-close-dur) var(--modal-ease),
+        opacity var(--modal-close-dur) var(--modal-ease);
+    }
   }
-}
 
-/* ── The palette does not animate ──────────────────────
-   WHY: it's opened by shortcut dozens of times a day, so an entrance feels like
-   lag. Raycast and Spotlight don't animate either. */
+  /* ── The palette does not animate ──────────────────────
+     WHY: it's opened by shortcut dozens of times a day, so an entrance feels like
+     lag. Raycast and Spotlight don't animate either. */
 
-/* The backdrop is a sibling in the portal, so it's named via `overlayClass`.
-   Reaching across the portal would also hit a dialog open underneath. */
-[data-slot="dialog-content"][data-command-dialog].t-modal,
-[data-slot="dialog-overlay"].t-modal-backdrop.t-instant {
-  transition: none;
+  /* The backdrop is a sibling in the portal, so it's named via `overlayClass`.
+     Reaching across the portal would also hit a dialog open underneath. */
+  [data-slot="dialog-content"][data-command-dialog].t-modal,
+  [data-slot="dialog-overlay"].t-modal-backdrop.t-instant {
+    transition: none;
+  }
 }
 
 @layer base {

package/src/tokens/design.css

@@ -0,0 +1,8 @@
+@layer theme, base, components, utilities;
+
+/* `./design`: the craft layer and the bits-ui variants without the palette, for an app that
+ * brings its own colours. tokens.css already loads both, so import one or the other.
+ */
+
+@import "./craft.css";
+@import "./primitives.css";

package/src/tokens/index.css

@@ -1,3 +1,6 @@
+/* Tailwind's own order, written down: kit CSS sits in `components`, so a utility on a kit part wins. */
+@layer theme, base, components, utilities;
+
 /* 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.