@heyramzi/ui 2.24.0 → 3.1.0

package/src/agents/agent-avatar.svelte

@@ -568,6 +568,17 @@
 
 	/* No box: the slot carries no border, background or padding. Without an
      explicit size it stays square, and the avatar fills three quarters of it. */
+	const label = $derived(
+		ariaLabel ??
+			(name
+				? `${name}${role ? `, ${role}` : ""}`
+				: `${preset.label} agent, ${stateLabels[stateKey]}`),
+	);
+	// A hidden avatar sits inside a parent control that names it, so only a visible one becomes the button.
+	const asButton = $derived(userClick !== undefined && !ariaHidden);
+	const BUTTON_RESET =
+		"appearance:none;background:none;border:0;padding:0;margin:0;color:inherit;font:inherit;cursor:pointer;";
+
 	const hostStyle = $derived.by(() => {
 		const base =
 			size === undefined
@@ -592,10 +603,16 @@
 	}
 </script>
 
-<span
+<!-- WHY the host turns button: onclick is the caller's action, so it needs focus and Enter. The jump alone is decoration. -->
+<!-- svelte-ignore a11y_no_static_element_interactions (the handler is set only when it's a button) -->
+<svelte:element
+	this={asButton ? "button" : "span"}
 	bind:this={hostEl}
+	type={asButton ? "button" : undefined}
+	aria-label={asButton ? label : undefined}
 	class={className ? `agent-avatar ${className}` : "agent-avatar"}
-	style={hostStyle}
+	style={asButton ? `${hostStyle}${BUTTON_RESET}` : hostStyle}
+	onclick={asButton ? handleClick : undefined}
 	data-agent-shape={type}
 >
 	{#if drawnSize > 0}
@@ -604,17 +621,12 @@
 			data-bot-avatar={type}
 			data-face={faceKind}
 			data-state={stateKey}
-			role={ariaHidden ? undefined : "img"}
-			aria-hidden={ariaHidden ? "true" : undefined}
-			aria-label={ariaHidden
-				? undefined
-				: (ariaLabel ??
-					(name
-						? `${name}${role ? `, ${role}` : ""}`
-						: `${preset.label} agent, ${stateLabels[stateKey]}`))}
+			role={ariaHidden || asButton ? undefined : "img"}
+			aria-hidden={ariaHidden || asButton ? "true" : undefined}
+			aria-label={ariaHidden || asButton ? undefined : label}
 			style={canvasStyle}
-			onclick={handleClick}
+			onclick={asButton ? undefined : handleClick}
 			{...rest}
 		></canvas>
 	{/if}
-</span>
+</svelte:element>

package/src/agents/agent-avatar.svelte.d.ts

@@ -0,0 +1,6 @@
+import type { AgentAvatarProps } from "./types.js";
+declare const $$Component: import("svelte").Component<AgentAvatarProps, {
+    getCanvas: () => HTMLCanvasElement | null;
+}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/agents/agent-avatar.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it } from "vite-plus/test";
+import { flushSync, mount, unmount } from "svelte";
+import AgentAvatar from "./agent-avatar.svelte";
+
+// jsdom has no canvas paths; the avatar builds its body shape with one while it mounts.
+globalThis.Path2D ??= class {} as unknown as typeof Path2D;
+
+let app: ReturnType<typeof mount> | null = null;
+
+afterEach(() => {
+  if (app) unmount(app);
+  app = null;
+  document.body.innerHTML = "";
+});
+
+function render(props: Record<string, unknown>) {
+  app = mount(AgentAvatar, { target: document.body, props: { size: 48, ...props } as never });
+  flushSync();
+  return document.querySelector<HTMLElement>(".agent-avatar");
+}
+
+describe("AgentAvatar's host", () => {
+  it("is a named button when the caller attaches an action", () => {
+    let clicks = 0;
+    const host = render({ name: "Ada", role: "Researcher", onclick: () => clicks++ });
+    expect(host?.tagName).toBe("BUTTON");
+    expect(host?.getAttribute("type")).toBe("button");
+    expect(host?.getAttribute("aria-label")).toBe("Ada, Researcher");
+    host?.click();
+    expect(clicks).toBe(1);
+  });
+
+  it("stays a plain span when the jump is the only thing a click does", () => {
+    expect(render({ name: "Ada" })?.tagName).toBe("SPAN");
+  });
+
+  it("stays a span inside a parent control that hides it", () => {
+    expect(render({ name: "Ada", onclick: () => {}, "aria-hidden": true })?.tagName).toBe("SPAN");
+  });
+});

package/src/agents/agent-cast.svelte

@@ -106,88 +106,93 @@
 </div>
 
 <style>
-	.agent-cast {
-		width: 100%;
-		color: var(--color-foreground, #18181b);
-	}
-	.agent-cast__section + .agent-cast__section {
-		margin-top: 2rem;
-	}
-	.agent-cast__heading {
-		margin: 0 0 0.75rem;
-		font-size: 0.9375rem;
-		font-weight: 600;
-		letter-spacing: -0.015em;
-	}
-	.agent-cast__grid {
-		display: grid;
-		gap: 0.75rem;
-		grid-template-columns: repeat(auto-fill, minmax(var(--agent-cast-min, 8.5rem), 1fr));
-		margin: 0;
-		padding: 0;
-		list-style: none;
-	}
-	.agent-cast__card {
-		display: flex;
-		flex-direction: column;
-		width: 100%;
-		height: 100%;
-		overflow: hidden;
-		padding: 0;
-		text-align: left;
-		background: var(--color-card, #fff);
-		border: 1px solid var(--color-border, #e4e4e7);
-		border-radius: 0.75rem;
-		cursor: pointer;
-		transition:
-			border-color var(--duration-quick, 150ms)
-				var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1)),
-			transform var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
-	}
-	@media (prefers-reduced-motion: reduce) {
+	@layer theme, base, components, utilities;
+
+	@layer components {
+		.agent-cast {
+			width: 100%;
+			color: var(--color-foreground, #18181b);
+		}
+		.agent-cast__section + .agent-cast__section {
+			margin-top: 2rem;
+		}
+		.agent-cast__heading {
+			margin: 0 0 0.75rem;
+			font-size: 0.9375rem;
+			font-weight: 600;
+			letter-spacing: -0.015em;
+		}
+		.agent-cast__grid {
+			display: grid;
+			gap: 0.75rem;
+			grid-template-columns: repeat(auto-fill, minmax(var(--agent-cast-min, 8.5rem), 1fr));
+			margin: 0;
+			padding: 0;
+			list-style: none;
+		}
 		.agent-cast__card {
-			transition: border-color var(--duration-quick, 150ms) linear;
+			display: flex;
+			flex-direction: column;
+			width: 100%;
+			height: 100%;
+			overflow: hidden;
+			padding: 0;
+			text-align: left;
+			background: var(--color-card, #fff);
+			border: 1px solid var(--color-border, #e4e4e7);
+			border-radius: 0.75rem;
+			cursor: pointer;
+			transition:
+				border-color var(--duration-quick, 150ms)
+					var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1)),
+				transform var(--duration-quick, 150ms)
+					var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+		}
+		@media (prefers-reduced-motion: reduce) {
+			.agent-cast__card {
+				transition: border-color var(--duration-quick, 150ms) linear;
+			}
+			.agent-cast__card:active {
+				transform: none;
+			}
+		}
+		@media (hover: hover) and (pointer: fine) {
+			.agent-cast__card:hover {
+				border-color: color-mix(in oklab, var(--color-foreground, #18181b) 25%, transparent);
+			}
 		}
 		.agent-cast__card:active {
-			transform: none;
+			transform: scale(0.985);
 		}
-	}
-	@media (hover: hover) and (pointer: fine) {
-		.agent-cast__card:hover {
-			border-color: color-mix(in oklab, var(--color-foreground, #18181b) 25%, transparent);
+		.agent-cast__card:focus-visible {
+			outline: 2px solid var(--color-ring, #6366f1);
+			outline-offset: 2px;
+		}
+		.agent-cast__card[aria-pressed="true"] {
+			border-color: var(--color-accent, #6366f1);
+			box-shadow: 0 0 0 1px var(--color-accent, #6366f1);
+		}
+		/* Room above the head, so a hop or a hat never meets the card's edge. */
+		.agent-cast__slot {
+			display: block;
+			width: 100%;
+			padding: 0.5rem 0.5rem 0;
+		}
+		.agent-cast__meta {
+			display: flex;
+			flex-direction: column;
+			gap: 0.125rem;
+			padding: 0.625rem;
+		}
+		.agent-cast__name {
+			font-size: 0.8125rem;
+			font-weight: 500;
+			line-height: 1.2;
+		}
+		.agent-cast__role {
+			font-size: 0.75rem;
+			line-height: 1.3;
+			color: var(--color-muted-foreground, #71717a);
 		}
-	}
-	.agent-cast__card:active {
-		transform: scale(0.985);
-	}
-	.agent-cast__card:focus-visible {
-		outline: 2px solid var(--color-ring, #6366f1);
-		outline-offset: 2px;
-	}
-	.agent-cast__card[aria-pressed="true"] {
-		border-color: var(--color-accent, #6366f1);
-		box-shadow: 0 0 0 1px var(--color-accent, #6366f1);
-	}
-	/* Room above the head, so a hop or a hat never meets the card's edge. */
-	.agent-cast__slot {
-		display: block;
-		width: 100%;
-		padding: 0.5rem 0.5rem 0;
-	}
-	.agent-cast__meta {
-		display: flex;
-		flex-direction: column;
-		gap: 0.125rem;
-		padding: 0.625rem;
-	}
-	.agent-cast__name {
-		font-size: 0.8125rem;
-		font-weight: 500;
-		line-height: 1.2;
-	}
-	.agent-cast__role {
-		font-size: 0.75rem;
-		line-height: 1.3;
-		color: var(--color-muted-foreground, #71717a);
 	}
 </style>

package/src/agents/agent-cast.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Agent } from "./types.js";
+interface Props {
+    /** The cast to lay out. */
+    agents: Agent[];
+    /** Selected agent id, when the cast is a picker. */
+    selectedId?: string | null;
+    /** Called with the agent that was picked. */
+    onSelect?: (agent: Agent) => void;
+    /** Hide the role line under each name. */
+    showRole?: boolean;
+    /** Extra props forwarded to every `<AgentAvatar>`. */
+    avatarProps?: Record<string, unknown>;
+    /** Minimum card width, any CSS length. Controls the column count. */
+    minColumn?: string;
+    class?: string;
+    style?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/agents/types.ts

@@ -67,6 +67,7 @@ export type AgentAvatarProps = Omit<
   size?: number;
   class?: string;
   style?: string;
+  /** Set, the avatar is a button named like the image, so the action takes focus and Enter. */
   onclick?: (event: MouseEvent) => void;
   "aria-label"?: string;
   /** Hide the canvas from assistive tech when a parent already names the agent. */

package/src/ai/ai-button/AiButton.svelte

@@ -39,6 +39,14 @@
 		class: className,
 		iconOnly = false,
 	}: AiButtonProps = $props();
+
+	// A disabled button drops focus to the page, so while it works it's aria-disabled and ignores presses instead.
+	const busy = $derived(status === "processing");
+
+	function handleClick(e: MouseEvent) {
+		if (busy) return;
+		onclick?.(e);
+	}
 </script>
 
 <!-- ===========================
@@ -49,29 +57,32 @@
 		{variant}
 		size="sm"
 		icon
-		disabled={disabled || status === "processing"}
-		{onclick}
-		class={cn("relative", status === "processing" && "pointer-events-none", className)}
+		{disabled}
+		aria-disabled={busy || undefined}
+		aria-label={busy ? processingLabel : label}
+		onclick={handleClick}
+		class={cn("relative", busy && "pointer-events-none opacity-50", className)}
 	>
-		{#if status === "processing"}
+		{#if busy}
 			<Spinner class="size-4" />
 		{:else}
-			<Sparkle class="size-4" weight="fill" />
+			<Sparkle class="size-4" weight="fill" aria-hidden="true" />
 		{/if}
 	</Button>
 {:else}
 	<Button
 		{variant}
 		{size}
-		disabled={disabled || status === "processing"}
-		{onclick}
-		class={cn("gap-1.5", status === "processing" && "pointer-events-none", className)}
+		{disabled}
+		aria-disabled={busy || undefined}
+		onclick={handleClick}
+		class={cn("gap-1.5", busy && "pointer-events-none opacity-50", className)}
 	>
-		{#if status === "processing"}
+		{#if busy}
 			<Spinner class="size-3.5" />
 			<span>{processingLabel}</span>
 		{:else}
-			<Sparkle class="size-3.5" weight="fill" />
+			<Sparkle class="size-3.5" weight="fill" aria-hidden="true" />
 			<span>{label}</span>
 		{/if}
 	</Button>

package/src/ai/ai-button/AiButton.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { ButtonProps } from "../../shadcn/button/index.js";
+export type AiStatus = "idle" | "processing" | "done";
+export interface AiButtonProps {
+    status?: AiStatus;
+    label?: string;
+    processingLabel?: string;
+    variant?: ButtonProps["variant"];
+    size?: ButtonProps["size"];
+    disabled?: boolean;
+    onclick?: (e: MouseEvent) => void;
+    class?: string;
+    iconOnly?: boolean;
+}
+declare const $$Component: import("svelte").Component<AiButtonProps, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/ai/ai-button/ai-button.svelte.test.ts

@@ -0,0 +1,27 @@
+import { flushSync, mount, unmount } from "svelte";
+import { describe, expect, it, vi } from "vite-plus/test";
+import AiButton, { type AiStatus } from "./AiButton.svelte";
+
+// 10 Nov 2026: the button turned disabled while it worked, and focus dropped to the page.
+describe("AiButton while processing", () => {
+  for (const iconOnly of [false, true]) {
+    it(`keeps focus and ignores presses${iconOnly ? " (icon only)" : ""}`, () => {
+      const target = document.createElement("div");
+      document.body.appendChild(target);
+      const onclick = vi.fn();
+      const props = $state({ status: "idle" as AiStatus, onclick, iconOnly });
+      const app = mount(AiButton, { target, props });
+      flushSync();
+      const button = target.querySelector("button");
+      button?.focus();
+      props.status = "processing";
+      flushSync();
+      expect(document.activeElement).toBe(button);
+      expect(button?.getAttribute("aria-disabled")).toBe("true");
+      button?.click();
+      expect(onclick).not.toHaveBeenCalled();
+      void unmount(app);
+      target.remove();
+    });
+  }
+});

package/src/ai/confirmation/Confirmation.svelte

@@ -32,20 +32,36 @@
 			return executing;
 		},
 	});
+
+	let section = $state<HTMLElement | null>(null);
+	let hadFocus = false;
+
+	// The actions unmount once it resolves. If one held focus, the box takes it so focus doesn't drop to the page.
+	$effect.pre(() => {
+		void kind;
+		hadFocus = !!section?.contains(document.activeElement);
+	});
+
+	$effect(() => {
+		void kind;
+		if (hadFocus && section && !section.contains(document.activeElement)) section.focus();
+		hadFocus = false;
+	});
 </script>
 
 {#if kind !== "idle"}
-	{@const isResolved = kind === "accepted" || kind === "rejected" || kind === "failed"}
+	<!-- Live from the moment it shows, so the change to the result is read out. -->
 	<section
+		bind:this={section}
+		tabindex="-1"
 		class={cn(
-			"flex flex-col gap-2 rounded-lg border p-3",
+			"flex flex-col gap-2 rounded-lg border p-3 outline-none",
 			"border-[color:var(--border,rgba(0,0,0,0.1))] bg-[color:var(--card,white)] shadow-sm",
 			className,
 		)}
 		aria-label="Confirmation"
 		aria-busy={executing ? "true" : undefined}
-		role={isResolved ? "status" : undefined}
-		aria-live={isResolved ? "polite" : undefined}
+		aria-live="polite"
 		data-state={kind}
 		{...rest}
 	>

package/src/ai/confirmation/Confirmation.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import type { ConfirmationKind } from "./confirmation-context.svelte.js";
+export interface ConfirmationProps extends HTMLAttributes<HTMLElement> {
+    kind: ConfirmationKind;
+    executing?: boolean;
+    class?: string;
+    children?: Snippet;
+}
+declare const $$Component: import("svelte").Component<ConfirmationProps, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/ai/confirmation/ConfirmationAction.svelte

@@ -34,7 +34,12 @@
 				? false
 				: ctx.executing && variant === "default",
 	);
-	const isDisabled = $derived(Boolean(disabled) || ctx.executing);
+	// A disabled button drops focus to the page, so while the action runs it's aria-disabled and stops presses here.
+	function blockWhileRunning(event: MouseEvent) {
+		if (!ctx.executing) return;
+		event.preventDefault();
+		event.stopImmediatePropagation();
+	}
 </script>
 
 <Button
@@ -42,8 +47,10 @@
 	{variant}
 	{size}
 	type="button"
-	disabled={isDisabled}
-	class={cn("h-8 px-3 text-sm", className)}
+	{disabled}
+	aria-disabled={ctx.executing || undefined}
+	onclickcapture={blockWhileRunning}
+	class={cn("h-8 px-3 text-sm", ctx.executing && "pointer-events-none opacity-50", className)}
 >
 	{#if showBusy && busyLabel}
 		{busyLabel}

package/src/ai/confirmation/ConfirmationAction.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { ButtonProps } from "../../shadcn/button/index.js";
+export interface ConfirmationActionProps extends ButtonProps {
+    busyLabel?: string;
+    busyWhen?: "always" | "default" | "never";
+}
+declare const $$Component: import("svelte").Component<ConfirmationActionProps, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/ai/confirmation/ConfirmationActions.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+export interface ConfirmationActionsProps extends HTMLAttributes<HTMLDivElement> {
+    class?: string;
+    children?: Snippet;
+}
+declare const $$Component: import("svelte").Component<ConfirmationActionsProps, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/ai/confirmation/ConfirmationState.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from "svelte";
+import type { ConfirmationKind } from "./confirmation-context.svelte.js";
+export interface ConfirmationStateProps {
+    /** The state whose content this shows. */
+    when: Exclude<ConfirmationKind, "idle">;
+    children?: Snippet;
+}
+declare const $$Component: import("svelte").Component<ConfirmationStateProps, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/ai/confirmation/ConfirmationTitle.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+export interface ConfirmationTitleProps extends HTMLAttributes<HTMLParagraphElement> {
+    class?: string;
+    children?: Snippet;
+}
+declare const $$Component: import("svelte").Component<ConfirmationTitleProps, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/ai/confirmation/confirmation-focus.test.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+	// A request whose Delete runs, then resolves, for the focus and live region test.
+	import {
+		Confirmation,
+		ConfirmationAction,
+		ConfirmationActions,
+		ConfirmationState,
+		type ConfirmationKind,
+	} from "./index.js";
+
+	let { onDelete }: { onDelete: () => void } = $props();
+	let kind = $state<ConfirmationKind>("requested");
+	let executing = $state(false);
+
+	export function resolve() {
+		executing = false;
+		kind = "accepted";
+	}
+</script>
+
+<Confirmation {kind} {executing}>
+	<ConfirmationState when="requested">
+		<ConfirmationActions>
+			<ConfirmationAction
+				onclick={() => {
+					executing = true;
+					onDelete();
+				}}>Delete</ConfirmationAction
+			>
+		</ConfirmationActions>
+	</ConfirmationState>
+	<ConfirmationState when="accepted">Deleted.</ConfirmationState>
+</Confirmation>

package/src/ai/confirmation/confirmation-focus.test.svelte.d.ts

@@ -0,0 +1,8 @@
+type $$ComponentProps = {
+    onDelete: () => void;
+};
+declare const $$Component: import("svelte").Component<$$ComponentProps, {
+    resolve: () => void;
+}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/ai/confirmation/confirmation-focus.test.ts

@@ -0,0 +1,34 @@
+import { flushSync, mount, unmount } from "svelte";
+import { describe, expect, it, vi } from "vite-plus/test";
+import Flow from "./confirmation-focus.test.svelte";
+
+// 10 Nov 2026: focus dropped to the page after Delete, and the box turned live in the same update as its result.
+describe("Confirmation after an action", () => {
+  it("keeps focus through the run and moves it to the live box once resolved", () => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+    const onDelete = vi.fn();
+    const app = mount(Flow, { target, props: { onDelete } });
+    flushSync();
+    const section = target.querySelector("section");
+    const button = target.querySelector("button");
+    expect(section?.getAttribute("aria-live")).toBe("polite");
+
+    button?.focus();
+    button?.click();
+    flushSync();
+    expect(onDelete).toHaveBeenCalledTimes(1);
+    expect(document.activeElement).toBe(button);
+    expect(button?.disabled).toBe(false);
+    button?.click();
+    expect(onDelete).toHaveBeenCalledTimes(1);
+
+    app.resolve();
+    flushSync();
+    expect(section?.textContent?.trim()).toBe("Deleted.");
+    expect(document.activeElement).toBe(section);
+
+    void unmount(app);
+    target.remove();
+  });
+});

package/src/ai/confirmation/confirmation-parts.test.svelte.d.ts

@@ -0,0 +1,7 @@
+import { type ConfirmationKind } from "./index.js";
+type $$ComponentProps = {
+    kind: ConfirmationKind;
+};
+declare const $$Component: import("svelte").Component<$$ComponentProps, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;