@heyramzi/ui 2.24.0 → 3.0.0

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.

package/src/triage/triage-plan.svelte

@@ -2,6 +2,7 @@
 	import { Button } from "../shadcn/button/index.js";
 	import { Input } from "../shadcn/input/index.js";
 	import { cn } from "../lib/utils.js";
+	import { focusAfterRender } from "../lib/focus.js";
 	import { DEFAULT_TRIAGE_PLAN_LABELS, type TriagePlanLabels } from "./types.js";
 
 	interface Props {
@@ -21,7 +22,7 @@
 		/** A failed attempt, shown on the card. */
 		error?: string | null;
 		labels?: Partial<TriagePlanLabels>;
-		/** Run the plan. The buttons stay disabled until it settles. */
+		/** Run the plan. The buttons stay unavailable until it settles. */
 		onApprove: () => void | Promise<void>;
 		/** Run a task the person typed instead of the plan. */
 		onPick: (task: string) => void | Promise<void>;
@@ -50,8 +51,13 @@
 	let picking = $state(false);
 	let busy = $state(false);
 	let task = $state("");
+	let card: HTMLElement | undefined = $state();
+
+	// aria-disabled, not disabled, while busy: a disabled button drops focus to the page.
+	const busyLook = "aria-disabled:pointer-events-none aria-disabled:opacity-50";
 
 	async function run(job: () => void | Promise<void>) {
+		if (busy) return;
 		busy = true;
 		try {
 			await job();
@@ -59,11 +65,27 @@
 			busy = false;
 		}
 	}
+
+	async function setPicking(on: boolean) {
+		picking = on;
+		await focusAfterRender(card, on ? `[id="${id}-task"]` : "[data-triage-pick]");
+	}
 </script>
 
-<article class={cn("bg-card border-border rounded-xl border p-5", className)}>
+<article
+	bind:this={card}
+	tabindex="-1"
+	aria-labelledby="{id}-heading"
+	class={cn(
+		"bg-card border-border rounded-xl border p-5 outline-none focus-visible:shadow-(--ring-focus)",
+		className,
+	)}
+>
 	<div class="flex items-start justify-between gap-3">
-		<h2 class="text-foreground min-w-0 text-sm font-semibold [overflow-wrap:anywhere]">
+		<h2
+			id="{id}-heading"
+			class="text-foreground min-w-0 text-sm font-semibold [overflow-wrap:anywhere]"
+		>
 			{sender}: “{subject}”
 		</h2>
 		{#if received}
@@ -92,7 +114,7 @@
 
 	{#if error}
 		<p
-			class="bg-destructive/10 text-destructive mt-3 rounded-lg px-3 py-2 text-sm [overflow-wrap:anywhere]"
+			class="bg-destructive/10 text-destructive-ink mt-3 rounded-lg px-3 py-2 text-sm [overflow-wrap:anywhere]"
 			role="alert"
 		>
 			{error}
@@ -100,20 +122,27 @@
 	{/if}
 
 	{#if picking}
+		<!-- WHY: Esc from any control in the form cancels, so one listener sits on the form. -->
+		<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
 		<form
 			class="mt-4 space-y-2"
 			onsubmit={(event) => {
 				event.preventDefault();
 				run(() => onPick(task.trim()));
 			}}
+			onkeydown={(event) => {
+				if (event.key !== "Escape") return;
+				event.preventDefault();
+				void setPicking(false);
+			}}
 		>
 			<label for="{id}-task" class="text-foreground block text-sm font-medium">
 				{words.taskLabel}
 			</label>
 			<Input id="{id}-task" bind:value={task} required autocomplete="off" />
 			<div class="flex flex-wrap gap-2">
-				<Button type="submit" disabled={busy}>{words.useTask}</Button>
-				<Button type="button" variant="outline" onclick={() => (picking = false)}>
+				<Button type="submit" aria-disabled={busy} class={busyLook}>{words.useTask}</Button>
+				<Button type="button" variant="outline" onclick={() => setPicking(false)}>
 					{words.cancel}
 				</Button>
 			</div>
@@ -121,10 +150,14 @@
 	{:else}
 		<div class="mt-4 flex flex-wrap gap-2">
 			{#if plan}
-				<Button disabled={busy} onclick={() => run(onApprove)}>{words.approve}</Button>
-				<Button variant="outline" onclick={() => (picking = true)}>{words.pick}</Button>
+				<Button aria-disabled={busy} class={busyLook} onclick={() => run(onApprove)}>
+					{words.approve}
+				</Button>
+				<Button variant="outline" data-triage-pick onclick={() => setPicking(true)}>
+					{words.pick}
+				</Button>
 			{/if}
-			<Button variant="ghost" disabled={busy} onclick={() => run(onDismiss)}>
+			<Button variant="ghost" aria-disabled={busy} class={busyLook} onclick={() => run(onDismiss)}>
 				{words.dismiss}
 			</Button>
 		</div>

package/src/triage/triage-plan.svelte.d.ts

@@ -0,0 +1,28 @@
+import { type TriagePlanLabels } from "./types.js";
+interface Props {
+    /** Who sent the email. */
+    sender: string;
+    subject: string;
+    /** The first lines of the body. */
+    snippet?: string;
+    /** When it arrived, as text the host already formatted. */
+    received?: string | null;
+    /** The ISO time behind `received`, for the `time` element. */
+    receivedAt?: string | null;
+    /** What the plan will do, as one sentence. Without it the card only offers to dismiss. */
+    plan?: string | null;
+    /** Why the model wasn't sure. */
+    reason?: string | null;
+    /** A failed attempt, shown on the card. */
+    error?: string | null;
+    labels?: Partial<TriagePlanLabels>;
+    /** Run the plan. The buttons stay unavailable until it settles. */
+    onApprove: () => void | Promise<void>;
+    /** Run a task the person typed instead of the plan. */
+    onPick: (task: string) => void | Promise<void>;
+    onDismiss: () => void | Promise<void>;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/triage/triage-queue.svelte

@@ -1,6 +1,7 @@
 <script lang="ts" generics="T">
 	import type { Snippet } from "svelte";
 	import { cn } from "../lib/utils.js";
+	import { focusAfterRender } from "../lib/focus.js";
 
 	interface Props {
 		items: readonly T[];
@@ -21,28 +22,65 @@
 	}
 
 	let { items, key, kind = "plans", row, empty, icon, class: className }: Props = $props();
+
+	let root: HTMLDivElement | undefined = $state();
+	// The key of the row that last held focus, and the keys in the order they were drawn.
+	let focusedKey: string | null = null;
+	let drawn: string[] = [];
+
+	function onfocusin(event: FocusEvent) {
+		const rows = root?.querySelector("[data-triage-rows]")?.children;
+		const at = rows ? [...rows].findIndex((r) => r.contains(event.target as Node)) : -1;
+		focusedKey = drawn[at] ?? null;
+	}
+
+	function onfocusout(event: FocusEvent) {
+		const next = event.relatedTarget;
+		if (next instanceof Node && !root?.contains(next)) focusedKey = null;
+	}
+
+	// A row that leaves takes focus with it, so focus goes to the row now in its place, or the empty state.
+	$effect(() => {
+		const keys = items.map(key);
+		const held = focusedKey;
+		const at = held !== null && !keys.includes(held) ? drawn.indexOf(held) : -1;
+		drawn = keys;
+		if (at === -1) return;
+		focusedKey = null;
+		const active = document.activeElement;
+		if (active && active !== document.body) return;
+		const next = Math.min(at, keys.length - 1) + 1;
+		void focusAfterRender(root, `[data-triage-rows] > :nth-child(${next})`, "[data-triage-empty]");
+	});
 </script>
 
-{#if items.length === 0}
-	<div
-		class={cn(
-			"border-border flex flex-col items-center gap-3 rounded-xl border border-dashed px-6 py-14 text-center",
-			className,
-		)}
-	>
-		<span class="text-muted-foreground" aria-hidden="true">{@render icon?.()}</span>
-		<p class="text-muted-foreground text-sm">{empty}</p>
-	</div>
-{:else if kind === "plans"}
-	<div class={cn("space-y-4", className)}>
-		{#each items as item (key(item))}
-			{@render row(item)}
-		{/each}
-	</div>
-{:else}
-	<ul class={cn("bg-card border-border divide-border divide-y rounded-xl border", className)}>
-		{#each items as item (key(item))}
-			{@render row(item)}
-		{/each}
-	</ul>
-{/if}
+<div bind:this={root} class="contents" {onfocusin} {onfocusout}>
+	{#if items.length === 0}
+		<div
+			tabindex="-1"
+			data-triage-empty
+			class={cn(
+				"border-border flex flex-col items-center gap-3 rounded-xl border border-dashed px-6 py-14 text-center outline-none focus-visible:shadow-(--ring-focus)",
+				className,
+			)}
+		>
+			<span class="text-muted-foreground" aria-hidden="true">{@render icon?.()}</span>
+			<p class="text-muted-foreground text-sm">{empty}</p>
+		</div>
+	{:else if kind === "plans"}
+		<div data-triage-rows class={cn("space-y-4", className)}>
+			{#each items as item (key(item))}
+				{@render row(item)}
+			{/each}
+		</div>
+	{:else}
+		<ul
+			data-triage-rows
+			class={cn("bg-card border-border divide-border divide-y rounded-xl border", className)}
+		>
+			{#each items as item (key(item))}
+				{@render row(item)}
+			{/each}
+		</ul>
+	{/if}
+</div>

package/src/triage/triage-queue.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { Snippet } from "svelte";
+declare function $$render<T>(): {
+    props: {
+        items: readonly T[];
+        /** The key a row is tracked by. */
+        key: (item: T) => string;
+        /**
+         * `plans` stacks cards that need a decision. `tasks` is one divided list of what was
+         * decided.
+         */
+        kind?: "plans" | "tasks";
+        /** One row: a `TriagePlan` for `plans`, a `TriageTask` for `tasks`. */
+        row: Snippet<[T]>;
+        /** What the person reads when nothing is waiting. */
+        empty: string;
+        /** The glyph above the empty text. */
+        icon?: Snippet;
+        class?: string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const $$Component: $$IsomorphicComponent;
+type $$Component<T> = InstanceType<typeof $$Component<T>>;
+export default $$Component;

package/src/triage/triage-task.svelte

@@ -45,7 +45,9 @@
 	let words = $derived({ ...DEFAULT_TRIAGE_TASK_LABELS, ...labels });
 	let busy = $state(false);
 
+	// aria-disabled, not disabled, while busy: a disabled button drops focus to the page.
 	async function undo() {
+		if (busy) return;
 		busy = true;
 		try {
 			await onUndo?.();
@@ -56,8 +58,9 @@
 </script>
 
 <li
+	tabindex="-1"
 	class={cn(
-		"flex flex-col gap-3 px-5 py-4 sm:flex-row sm:items-center sm:justify-between",
+		"flex flex-col gap-3 px-5 py-4 outline-none focus-visible:shadow-(--ring-focus) sm:flex-row sm:items-center sm:justify-between",
 		className,
 	)}
 >
@@ -83,12 +86,17 @@
 			<p class="text-muted-foreground text-xs [overflow-wrap:anywhere]">{detail}</p>
 		{/if}
 		{#if error}
-			<p class="text-destructive text-xs [overflow-wrap:anywhere]" role="alert">{error}</p>
+			<p class="text-destructive-ink text-xs [overflow-wrap:anywhere]" role="alert">{error}</p>
 		{/if}
 	</div>
 
 	{#if onUndo}
-		<Button variant="outline" class="shrink-0" disabled={busy} onclick={undo}>
+		<Button
+			variant="outline"
+			class="shrink-0 aria-disabled:pointer-events-none aria-disabled:opacity-50"
+			aria-disabled={busy}
+			onclick={undo}
+		>
 			{words.undo}
 		</Button>
 	{/if}

package/src/triage/triage-task.svelte.d.ts

@@ -0,0 +1,22 @@
+import { type TriageOutcome, type TriageTaskLabels, type TriageTaskLink } from "./types.js";
+interface Props {
+    sender: string;
+    subject: string;
+    /** What happened to the email. */
+    outcome: TriageOutcome;
+    /** The task it became. */
+    task?: TriageTaskLink | null;
+    /** When it settled, as text the host already formatted. */
+    when: string;
+    whenAt?: string | null;
+    /** Why it failed. */
+    detail?: string | null;
+    error?: string | null;
+    labels?: Partial<TriageTaskLabels>;
+    /** Takes the change back. The button shows only when this is passed. */
+    onUndo?: () => void | Promise<void>;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/triage/triage.svelte.test.ts

@@ -0,0 +1,130 @@
+import { createRawSnippet, flushSync, mount, tick, unmount } from "svelte";
+import { describe, expect, it } from "vite-plus/test";
+import TriagePlan from "./triage-plan.svelte";
+import TriageQueue from "./triage-queue.svelte";
+
+type Mail = { id: string; subject: string };
+
+const row = createRawSnippet((mail: () => Mail) => ({
+  render: () =>
+    `<article tabindex="-1" data-mail="${mail().id}"><button>Approve</button></article>`,
+}));
+
+function mountIn<P extends Record<string, unknown>>(component: never, props: P) {
+  const target = document.createElement("div");
+  document.body.appendChild(target);
+  const app = mount(component, { target, props });
+  flushSync();
+  return {
+    target,
+    done: () => {
+      void unmount(app);
+      target.remove();
+    },
+  };
+}
+
+async function settle() {
+  for (let i = 0; i < 4; i++) await tick();
+  flushSync();
+}
+
+describe("TriageQueue focus", () => {
+  function renderQueue() {
+    const props = $state({
+      items: [
+        { id: "m1", subject: "One" },
+        { id: "m2", subject: "Two" },
+      ] as Mail[],
+      key: (m: Mail) => m.id,
+      row,
+      empty: "Nothing waiting.",
+    });
+    return { props, ...mountIn(TriageQueue as never, props) };
+  }
+
+  it("moves focus to the card now in the place of one that left", async () => {
+    const { props, target, done } = renderQueue();
+    target.querySelector<HTMLElement>('[data-mail="m1"] button')?.focus();
+    props.items = props.items.slice(1);
+    await settle();
+    expect(document.activeElement).toBe(target.querySelector('[data-mail="m2"]'));
+    done();
+  });
+
+  it("moves focus to the empty state when the last card leaves", async () => {
+    const { props, target, done } = renderQueue();
+    target.querySelector<HTMLElement>('[data-mail="m2"] button')?.focus();
+    props.items = props.items.slice(0, 1);
+    await settle();
+    expect(document.activeElement).toBe(target.querySelector('[data-mail="m1"]'));
+    target.querySelector<HTMLElement>('[data-mail="m1"]')?.focus();
+    props.items = [];
+    await settle();
+    expect(document.activeElement?.textContent).toContain("Nothing waiting.");
+    done();
+  });
+});
+
+describe("TriagePlan focus", () => {
+  function renderPlan() {
+    return mountIn(TriagePlan as never, {
+      sender: "Ada",
+      subject: "Invoice",
+      plan: "File it",
+      onApprove: () => {},
+      onPick: () => {},
+      onDismiss: () => {},
+    });
+  }
+
+  const button = (target: HTMLElement, text: string) =>
+    [...target.querySelectorAll("button")].find((b) => b.textContent?.trim() === text);
+
+  it("keeps a busy button focusable and runs it once", async () => {
+    let calls = 0;
+    let finish = () => {};
+    const { target, done } = mountIn(TriagePlan as never, {
+      sender: "Ada",
+      subject: "Invoice",
+      plan: "File it",
+      onApprove: () => {
+        calls++;
+        return new Promise<void>((resolve) => (finish = resolve));
+      },
+      onPick: () => {},
+      onDismiss: () => {},
+    });
+    const approve = button(target, "Approve");
+    approve?.focus();
+    approve?.click();
+    await settle();
+    approve?.click();
+    expect(calls).toBe(1);
+    expect(approve?.disabled).toBe(false);
+    expect(approve?.getAttribute("aria-disabled")).toBe("true");
+    expect(document.activeElement).toBe(approve);
+    finish();
+    done();
+  });
+
+  it("puts focus in the task field on Pick, and back on Pick after Cancel or Esc", async () => {
+    const { target, done } = renderPlan();
+    button(target, "Pick another task")?.click();
+    await settle();
+    expect(document.activeElement?.tagName).toBe("INPUT");
+
+    button(target, "Cancel")?.click();
+    await settle();
+    expect(document.activeElement).toBe(button(target, "Pick another task"));
+
+    button(target, "Pick another task")?.click();
+    await settle();
+    document.activeElement?.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true }),
+    );
+    await settle();
+    expect(document.activeElement).toBe(button(target, "Pick another task"));
+    done();
+  });
+});

package/src/work/README.md

@@ -156,7 +156,7 @@ matches no group is drawn at the top level.
 inclusive ISO dates (`"2026-10-16"`). Drag a bar to move it, drag an edge to
 resize it, and the bar glides from day to day while a tip shows the new range.
 A focused bar moves a day with the arrow keys, and Shift plus an arrow moves
-its end. Leave out `onChange` and the chart is read only.
+its end. Leave out `onDatesChange` and the chart is read only.
 
 ```svelte
 <TaskGantt
@@ -168,7 +168,7 @@ its end. Leave out `onChange` and the chart is read only.
   getDependsOn={(task) => task.blockedBy}
   groups={columns}
   getGroup={(task) => task.column}
-  onChange={(id, { start, end }) => save(id, start, end)}
+  onDatesChange={(id, { start, end }) => save(id, start, end)}
 />
 ```
 
@@ -176,7 +176,7 @@ its end. Leave out `onChange` and the chart is read only.
 | -------------- | ----------------------------------------- | ----------------------------------------------------------- |
 | `items`, `getId`, `getTitle` |                             | Required.                                                   |
 | `getStart`, `getEnd` | `(item: T) => string \| null \| undefined` | ISO dates, inclusive. A one-day task has the same start and end. One date alone is a one-day task, none is undated. A parent with no dates draws the span of its children as an outline bar. |
-| `onChange`     | `(id, { start, end }) => void \| Promise<void>` | Called after a drag, a resize or a key nudge.        |
+| `onDatesChange` | `(id, { start, end }) => void \| Promise<void>` | Called after a drag, a resize or a key nudge.        |
 | `onSelect`     | `(id) => void`                            | A click or Enter that didn't move the bar.                  |
 | `getHue`       | `(item: T) => string \| undefined`         | Bar color. Falls back to the group hue, then `--color-primary`. |
 | `getProgress`  | `(item: T) => number \| undefined`         | 0 to 1, filled from the left.                               |
@@ -207,7 +207,7 @@ icon, so `ChartBarHorizontal` stands in.
 `SidePanel` is a sheet for one record: a title, a description, status chips, doors
 out to other tools (`openIn`), a copy-a-prompt `handoff`, a strip of `stats`, then
 the body and an optional pinned `footer`. You pass the tools; the panel knows none.
-Import it from `@heyramzi/ui/panel`, or from `@heyramzi/ui/work` for now.
+Import it from `@heyramzi/ui/panel`.
 
 ```svelte
 <SidePanel
@@ -266,7 +266,7 @@ and fetches nothing. You pass entries in and persist what it hands back.
 | `locale`, `labels`, `class` | | `labels` overrides any string in `DEFAULT_TIME_LABELS`. |
 
 Alt+S starts and stops the timer. A screen reader hears the start, one update a
-minute and the stop. Import it alone from `@heyramzi/ui/work/time`.
+minute and the stop. Import it from `@heyramzi/ui/work`.
 
 For boards and lists: `TimeChip` (`minutes`, `estimate?`, `running?`) shows the
 logged total, with a pulsing dot while a timer runs and a small ring against an
@@ -303,8 +303,9 @@ same values when they aren't. Everything goes still under
 
 ## Demo
 
-`src/demo.svelte` puts one task list behind a Board, List and Gantt filter, with
-sorting, a Days and Weeks scale and a status badge strip.
+The docs site's `/work` page (`site/src/lib/demos/pages/work.svelte`) puts one
+task list behind a Board, List and Gantt filter, with sorting, a Days and Weeks
+scale and a status badge strip.
 
 The fractional ordering in `board-order.ts` is the CC0 algorithm from
 [Implementing Fractional Indexing](https://observablehq.com/@dgreensp/implementing-fractional-indexing).

package/src/work/detail/task-chip.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from "svelte";
+import type { HTMLButtonAttributes } from "svelte/elements";
+interface Props extends Omit<HTMLButtonAttributes, "children"> {
+    /** No value yet: the label is a prompt and recedes until hovered. */
+    empty?: boolean;
+    children: Snippet;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/work/detail/task-detail.svelte.d.ts

@@ -0,0 +1,36 @@
+import type { Snippet } from "svelte";
+import type { ThreadComment, ThreadLabels, ThreadPost } from "../../thread/types.js";
+import { type TaskDetailLabels } from "./detail-types.js";
+interface Props {
+    title: string;
+    /** Without it the title is read-only. */
+    onTitleChange?: (next: string) => void | Promise<void>;
+    done?: boolean;
+    /** Closed covers done and dropped: the title mutes, never strikes through. */
+    closed?: boolean;
+    onToggleDone?: () => void;
+    /** One 12px line under the title: origin, dates. */
+    meta?: Snippet;
+    /** The rail. A `PropertyRow layout="responsive"` with a `TaskChip` or any picker trigger in each. */
+    properties?: Snippet;
+    /** Under the rail's rows: ids, shortcuts, anything quiet. */
+    railFooter?: Snippet;
+    description?: string | null;
+    onDescriptionChange?: (next: string | null) => void | Promise<void>;
+    comments?: ThreadComment[];
+    loadingComments?: boolean;
+    /** Replaces the default avatar for a person or an agent, drawn in a 24px slot. */
+    avatar?: Snippet<[ThreadComment]>;
+    when?: (comment: ThreadComment) => string;
+    /** Returns false to keep the draft. Without it no composer shows. */
+    onPostComment?: (post: ThreadPost) => void | boolean | Promise<void | boolean>;
+    onEditComment?: (comment: ThreadComment, body: string) => void | Promise<void>;
+    onDeleteComment?: (comment: ThreadComment) => void | Promise<void>;
+    canEditComment?: (comment: ThreadComment) => boolean;
+    labels?: Partial<TaskDetailLabels>;
+    threadLabels?: Partial<ThreadLabels>;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;