@heyramzi/ui 2.23.0 → 3.0.0

package/src/components/hold-to-confirm/hold-to-confirm.svelte

@@ -19,8 +19,13 @@
 		class?: string;
 		idle: Snippet;
 		holding: Snippet;
+		/** Read out when a screen reader's activate arms the button. Translate at the call site. */
+		confirmPrompt?: string;
 	}
 
+	// A screen reader's activate can't hold, so its first click arms and a second one inside this window confirms.
+	const ARM_MS = 5000;
+
 	// ========================= PROPS
 	let {
 		duration = 800,
@@ -32,6 +37,7 @@
 		class: className = "",
 		idle,
 		holding,
+		confirmPrompt = "Press again to confirm",
 		...restProps
 	}: Props = $props();
 
@@ -40,17 +46,24 @@
 	let isHolding = $state(false);
 	let rafId: number | null = $state(null);
 	let startTime: number | null = $state(null);
+	let armed = $state(false);
+	let armTimer: ReturnType<typeof setTimeout> | null = null;
+
+	$effect(() => () => {
+		if (armTimer !== null) clearTimeout(armTimer);
+	});
 
 	// ========================= FUNCTIONS
 	function startHold() {
-		if (disabled) return;
+		// A held key repeats keydown, and restarting the clock on each one stalled the fill at 6%.
+		if (disabled || isHolding) return;
 		isHolding = true;
 		startTime = performance.now();
 		tick();
 	}
 
 	function tick() {
-		if (!isHolding || !startTime) return;
+		if (!isHolding || startTime === null) return;
 
 		const elapsed = performance.now() - startTime;
 		progress = Math.min(elapsed / duration, 1);
@@ -96,9 +109,30 @@
 
 	function handleKeyup(e: KeyboardEvent) {
 		if (e.key === " " || e.key === "Enter") {
+			// Space clicks on keyup, and that click would arm the button behind a real hold.
+			e.preventDefault();
 			cancelHold();
 		}
 	}
+
+	function disarm() {
+		armed = false;
+		if (armTimer !== null) clearTimeout(armTimer);
+		armTimer = null;
+	}
+
+	// A pointer or a held key sends detail 1 or more. Assistive tech's activate sends a bare click, detail 0.
+	function handleClick(e: MouseEvent & { currentTarget: EventTarget & HTMLButtonElement }) {
+		restProps.onclick?.(e);
+		if (disabled || e.detail !== 0) return;
+		if (armed) {
+			disarm();
+			onConfirm();
+			return;
+		}
+		armed = true;
+		armTimer = setTimeout(disarm, ARM_MS);
+	}
 </script>
 
 <!-- ========================= MARKUP -->
@@ -116,12 +150,19 @@
 	)}
 	style="--progress: {progress}"
 	data-holding={isHolding}
+	data-armed={armed}
+	onclick={handleClick}
 	onpointerdown={startHold}
 	onpointerup={cancelHold}
 	onpointerleave={cancelHold}
 	onpointercancel={cancelHold}
 	onkeydown={handleKeydown}
 	onkeyup={handleKeyup}
+	onblur={(e) => {
+		cancelHold();
+		disarm();
+		restProps.onblur?.(e);
+	}}
 	{disabled}
 >
 	<!-- Fill sweep: scales from the left across the whole control -->
@@ -149,88 +190,94 @@
 		{/if}
 	</span>
 </button>
+<!-- Outside the button so it isn't part of its name, and mounted empty so the prompt is read when it lands. -->
+<span role="status" class="sr-only">{armed ? confirmPrompt : ""}</span>
 
 <!-- ========================= STYLE -->
 <style>
-	.hold-to-confirm {
-		touch-action: none;
-	}
+	@layer theme, base, components, utilities;
 
-	.hold-to-confirm:active:not(:disabled) {
-		transform: scale(0.97);
-	}
-
-	/* Fill: GPU-friendly scaleX. A vertical sheen survives the horizontal
-	   scale because it runs top-to-bottom, so the wipe keeps a crisp surface. */
-	.hold-to-confirm-fill {
-		transform: scaleX(var(--progress, 0));
-		background-image: linear-gradient(
-			to bottom,
-			color-mix(in oklch, var(--color-destructive-foreground) 14%, transparent),
-			transparent 55%
-		);
-		transition: transform var(--duration-quick) var(--ease-smooth-out);
-	}
-
-	.hold-to-confirm-fill.is-holding {
-		transition: none;
-	}
+	@layer components {
+		.hold-to-confirm {
+			touch-action: none;
+		}
 
-	/* Leading edge: positioned (not scaled) so its glow stays crisp at any
-	   width. Sits exactly at the head of the fill and fades in while held. */
-	.hold-to-confirm-edge {
-		left: calc(var(--progress, 0) * 100%);
-		width: 2px;
-		margin-left: -2px;
-		opacity: 0;
-		background: color-mix(
-			in oklch,
-			var(--color-destructive-foreground) 65%,
-			var(--color-destructive)
-		);
-		box-shadow: 0 0 4px 0 color-mix(in oklch, var(--color-destructive) 92%, transparent);
-		transition:
-			left var(--duration-quick) var(--ease-smooth-out),
-			opacity var(--duration-quick) var(--ease-out);
-	}
+		.hold-to-confirm:active:not(:disabled) {
+			transform: scale(0.97);
+		}
 
-	.hold-to-confirm-edge.is-holding {
-		opacity: 1;
-		transition: opacity var(--duration-quick) var(--ease-out);
-	}
+		/* Fill: GPU-friendly scaleX. A vertical sheen survives the horizontal
+		   scale because it runs top-to-bottom, so the wipe keeps a crisp surface. */
+		.hold-to-confirm-fill {
+			transform: scaleX(var(--progress, 0));
+			background-image: linear-gradient(
+				to bottom,
+				color-mix(in oklch, var(--color-destructive-foreground) 14%, transparent),
+				transparent 55%
+			);
+			transition: transform var(--duration-quick) var(--ease-smooth-out);
+		}
 
-	.hold-to-confirm-text {
-		animation: holdTextFadeIn var(--duration-quick) var(--ease-out);
-	}
+		.hold-to-confirm-fill.is-holding {
+			transition: none;
+		}
 
-	@keyframes holdTextFadeIn {
-		from {
+		/* Leading edge: positioned (not scaled) so its glow stays crisp at any
+		   width. Sits exactly at the head of the fill and fades in while held. */
+		.hold-to-confirm-edge {
+			left: calc(var(--progress, 0) * 100%);
+			width: 2px;
+			margin-left: -2px;
 			opacity: 0;
+			background: color-mix(
+				in oklch,
+				var(--color-destructive-foreground) 65%,
+				var(--color-destructive)
+			);
+			box-shadow: 0 0 4px 0 color-mix(in oklch, var(--color-destructive) 92%, transparent);
+			transition:
+				left var(--duration-quick) var(--ease-smooth-out),
+				opacity var(--duration-quick) var(--ease-out);
 		}
-		to {
+
+		.hold-to-confirm-edge.is-holding {
 			opacity: 1;
+			transition: opacity var(--duration-quick) var(--ease-out);
 		}
-	}
 
-	@media (prefers-reduced-motion: reduce) {
-		.hold-to-confirm:active:not(:disabled) {
-			transform: none;
+		.hold-to-confirm-text {
+			animation: holdTextFadeIn var(--duration-quick) var(--ease-out);
 		}
 
-		.hold-to-confirm-fill {
-			transition: none;
-			transform: scaleX(var(--progress, 0));
-			background-image: none;
-			opacity: 0.5;
-		}
+		@media (prefers-reduced-motion: reduce) {
+			.hold-to-confirm:active:not(:disabled) {
+				transform: none;
+			}
 
-		.hold-to-confirm-edge {
-			transition: none;
-			box-shadow: none;
+			.hold-to-confirm-fill {
+				transition: none;
+				transform: scaleX(var(--progress, 0));
+				background-image: none;
+				opacity: 0.5;
+			}
+
+			.hold-to-confirm-edge {
+				transition: none;
+				box-shadow: none;
+			}
+
+			.hold-to-confirm-text {
+				animation: none;
+			}
 		}
+	}
 
-		.hold-to-confirm-text {
-			animation: none;
+	@keyframes holdTextFadeIn {
+		from {
+			opacity: 0;
+		}
+		to {
+			opacity: 1;
 		}
 	}
 </style>

package/src/components/hold-to-confirm/hold-to-confirm.svelte.d.ts

@@ -0,0 +1,22 @@
+import { type ButtonSize, type ButtonVariant } from "../../shadcn/button/index.js";
+import type { Snippet } from "svelte";
+import type { HTMLButtonAttributes } from "svelte/elements";
+interface Props extends Omit<HTMLButtonAttributes, "class"> {
+    duration?: number;
+    onConfirm: () => void;
+    disabled?: boolean;
+    /** Uses the button recipe so call sites stop drawing their own.
+     *  `variant: null` opts out, for a caller that really is a menu row. */
+    variant?: ButtonVariant | null;
+    size?: ButtonSize;
+    /** Square, for a glyph with no label. Mirrors `Button`. */
+    icon?: boolean;
+    class?: string;
+    idle: Snippet;
+    holding: Snippet;
+    /** Read out when a screen reader's activate arms the button. Translate at the call site. */
+    confirmPrompt?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/hold-to-confirm/hold-to-confirm.test.ts

@@ -0,0 +1,105 @@
+import { createRawSnippet, flushSync, mount, unmount } from "svelte";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
+import HoldToConfirm from "./hold-to-confirm.svelte";
+
+const text = (label: string) => createRawSnippet(() => ({ render: () => `<span>${label}</span>` }));
+
+function render(duration = 800) {
+  const onConfirm = vi.fn();
+  const target = document.createElement("div");
+  document.body.appendChild(target);
+  const app = mount(HoldToConfirm, {
+    target,
+    props: { duration, onConfirm, idle: text("Hold to delete"), holding: text("Deleting") },
+  });
+  flushSync();
+  const button = target.querySelector("button");
+  if (!button) throw new Error("HoldToConfirm rendered no button");
+  const key = (type: "keydown" | "keyup", k: string, repeat = false) => {
+    button.dispatchEvent(new KeyboardEvent(type, { key: k, repeat, bubbles: true }));
+    flushSync();
+  };
+  return {
+    button,
+    onConfirm,
+    key,
+    done: () => {
+      void unmount(app);
+      target.remove();
+    },
+  };
+}
+
+// The OS repeats keydown about every 33ms while a key is held. The 10 Nov audit saw Space stall at 6%.
+async function holdWithRepeat(key: ReturnType<typeof render>["key"], k: string, ms: number) {
+  key("keydown", k);
+  for (let t = 33; t <= ms; t += 33) {
+    await vi.advanceTimersByTimeAsync(33);
+    key("keydown", k, true);
+  }
+}
+
+describe("HoldToConfirm keyboard", () => {
+  beforeEach(() =>
+    vi.useFakeTimers({
+      toFake: ["requestAnimationFrame", "cancelAnimationFrame", "performance", "setTimeout"],
+    }),
+  );
+  afterEach(() => vi.useRealTimers());
+
+  for (const k of [" ", "Enter"]) {
+    it(`confirms when ${k === " " ? "Space" : k} is held through key repeat`, async () => {
+      const { onConfirm, key, done } = render();
+      await holdWithRepeat(key, k, 900);
+      expect(onConfirm).toHaveBeenCalledTimes(1);
+      key("keyup", k);
+      done();
+    });
+  }
+
+  it("cancels when the key is let go early", async () => {
+    const { button, onConfirm, key, done } = render();
+    await holdWithRepeat(key, " ", 400);
+    key("keyup", " ");
+    await vi.advanceTimersByTimeAsync(800);
+    expect(onConfirm).not.toHaveBeenCalled();
+    expect(button.dataset.holding).toBe("false");
+    done();
+  });
+
+  // 10 Nov 2026: a screen reader's activate presses and lets go at once, so the hold never completed.
+  it("arms on an assistive-tech click and confirms on a second one", async () => {
+    const { button, onConfirm, done } = render();
+    const status = button.parentElement?.querySelector('[role="status"]');
+    expect(status?.textContent).toBe("");
+    button.dispatchEvent(new MouseEvent("click", { detail: 0, bubbles: true }));
+    flushSync();
+    expect(onConfirm).not.toHaveBeenCalled();
+    expect(status?.textContent).toBe("Press again to confirm");
+    button.dispatchEvent(new MouseEvent("click", { detail: 0, bubbles: true }));
+    flushSync();
+    expect(onConfirm).toHaveBeenCalledTimes(1);
+    done();
+  });
+
+  it("lets the armed state lapse and ignores pointer clicks", async () => {
+    const { button, onConfirm, done } = render();
+    button.dispatchEvent(new MouseEvent("click", { detail: 0, bubbles: true }));
+    await vi.advanceTimersByTimeAsync(6000);
+    button.dispatchEvent(new MouseEvent("click", { detail: 0, bubbles: true }));
+    button.dispatchEvent(new MouseEvent("click", { detail: 1, bubbles: true }));
+    flushSync();
+    expect(onConfirm).not.toHaveBeenCalled();
+    done();
+  });
+
+  it("cancels when focus leaves mid-hold", async () => {
+    const { button, onConfirm, key, done } = render();
+    await holdWithRepeat(key, "Enter", 300);
+    button.dispatchEvent(new FocusEvent("blur"));
+    flushSync();
+    await vi.advanceTimersByTimeAsync(800);
+    expect(onConfirm).not.toHaveBeenCalled();
+    done();
+  });
+});

package/src/components/language-flag/flags.ts

@@ -0,0 +1,5 @@
+/** Language code to flag image. The host serves these files from /flags. */
+export const LANGUAGE_FLAGS: Record<string, string> = {
+  en: "/flags/US.svg",
+  fr: "/flags/FR.svg",
+};

package/src/components/language-flag/index.ts

@@ -1 +1,2 @@
 export { default as LanguageFlag } from "./language-flag.svelte";
+export { LANGUAGE_FLAGS } from "./flags.js";

package/src/components/language-flag/language-flag.svelte

@@ -3,22 +3,14 @@
 	// IMPORTS
 	// =========================
 	import { cn } from "../../lib/utils.js";
-
-	// =========================
-	// CONSTANTS
-	// =========================
-	// The host serves these files from /flags. Pass `flags` for another set or path.
-	const DEFAULT_FLAGS: Record<string, string> = {
-		en: "/flags/US.svg",
-		fr: "/flags/FR.svg",
-	};
+	import { LANGUAGE_FLAGS } from "./flags.js";
 
 	// =========================
 	// PROPS
 	// =========================
 	interface Props {
 		language: string;
-		/** Language code to image URL. */
+		/** Language code to image URL, for another set or path. */
 		flags?: Record<string, string>;
 		size?: "sm" | "md";
 		showLabel?: boolean;
@@ -27,7 +19,7 @@
 
 	let {
 		language,
-		flags = DEFAULT_FLAGS,
+		flags = LANGUAGE_FLAGS,
 		size = "sm",
 		showLabel = false,
 		class: className,
@@ -43,11 +35,12 @@
 <!-- =========================== -->
 <!-- MARKUP -->
 <!-- =========================== -->
+<!-- With the label shown, the flag is decorative, or the code is read twice. -->
 {#if src}
 	<span class={cn("inline-flex items-center gap-1.5", className)}>
 		<img
 			{src}
-			alt={language.toUpperCase()}
+			alt={showLabel ? "" : language.toUpperCase()}
 			class={cn("shrink-0 rounded-sm", sizeClass)}
 			loading="lazy"
 		/>

package/src/components/language-flag/language-flag.svelte.d.ts

@@ -0,0 +1,11 @@
+interface Props {
+    language: string;
+    /** Language code to image URL, for another set or path. */
+    flags?: Record<string, string>;
+    size?: "sm" | "md";
+    showLabel?: boolean;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/list-page/detail-header.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from "svelte";
+interface Props {
+    title: string;
+    badge?: Snippet;
+    leading?: Snippet;
+    meta?: Array<string | null | undefined | false>;
+    note?: string | null;
+    actions?: Snippet;
+    corner?: Snippet;
+    children?: Snippet;
+    class?: string;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/list-page/detail-row.svelte.d.ts

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

package/src/components/list-page/detail-stack.svelte.d.ts

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

package/src/components/list-page/empty-state.svelte

@@ -2,8 +2,10 @@
 	// =========================
 	// IMPORTS
 	// =========================
+	import type { Snippet } from "svelte";
 	import { Button } from "../../shadcn/button/index.js";
 	import * as Empty from "../../shadcn/empty/index.js";
+	import { cn } from "../../lib/utils.js";
 	import type { PhosphorIcon, IconWeight } from "../../lib/icon-types.js";
 
 	// =========================
@@ -12,25 +14,93 @@
 	interface Props {
 		icon?: PhosphorIcon;
 		iconWeight?: IconWeight;
+		/** Replaces the muted colour of a bare icon. Ignored by the tile, which stays foreground. */
+		iconClass?: string;
 		title: string;
 		description?: string;
 		actionLabel?: string;
 		actionHref?: string;
 		onAction?: () => void;
+		/** Several ways out, drawn in one row after the single action. */
+		actions?: Snippet;
+		/** `card` fills the white panel; `dashed` frames a whole dashboard section. */
+		surface?: "plain" | "card" | "dashed";
+		/** `sm` fits a 280px rail: a bare icon and one line of small type. */
+		size?: "default" | "sm";
+		class?: string;
 	}
 
+	/** A null `icon` draws the icon in a white tile. */
+	type Look = {
+		root: string;
+		icon: string | null;
+		header: string;
+		title: string;
+		description: string;
+	};
+
 	// =========================
 	// PROPS
 	// =========================
 	let {
 		icon: Icon,
 		iconWeight,
+		iconClass,
 		title,
 		description,
 		actionLabel,
 		actionHref,
 		onAction,
+		actions,
+		surface = "plain",
+		size = "default",
+		class: className,
 	}: Props = $props();
+
+	// =========================
+	// CONSTANTS
+	// =========================
+	// A white tile, not a brand tint: the accent marks the one action (DESIGN.md rule 1).
+	const PAGE: Look = {
+		root: "py-16",
+		icon: null,
+		header: "max-w-md",
+		title: "font-heading text-base font-semibold text-balance [overflow-wrap:anywhere]",
+		description: "",
+	};
+
+	const RAIL: Look = {
+		root: "gap-2 px-6 py-12",
+		icon: "size-6",
+		header: "max-w-none",
+		title: "",
+		description: "max-w-56 text-xs leading-relaxed",
+	};
+
+	// A dashed box stands in for a whole dashboard section, so it takes a heading's size.
+	const SECTION: Look = {
+		root: "p-10 text-wrap",
+		icon: "size-10",
+		header: "max-w-md gap-1.5",
+		title: "font-heading text-lg font-semibold tracking-normal",
+		description: "text-sm",
+	};
+
+	// A framed box sizes as a block, so a caller's `m-4` insets it instead of pushing it 32px wide.
+	const SURFACE: Record<NonNullable<Props["surface"]>, string> = {
+		plain: "",
+		card: "w-auto flex-initial bg-card",
+		dashed: "w-auto flex-initial border-2 border-border",
+	};
+
+	// =========================
+	// DERIVED
+	// =========================
+	let look = $derived(size === "sm" ? RAIL : surface === "dashed" ? SECTION : PAGE);
+	// Dashboard empties carry their own `t-enter`, and a rail empty flips on every filter keystroke.
+	let reveal = $derived(look === PAGE);
+	let heading = $derived(look === SECTION);
+	let hasAction = $derived(Boolean(actionLabel && (actionHref || onAction)));
 </script>
 
 <!-- =========================== -->
@@ -38,29 +108,37 @@
 <!-- =========================== -->
 <!-- transitions-dev texts reveal: the parts arrive in reading order, so the page reads as
      loaded and empty. Reduced motion keeps the fade. -->
-<Empty.Root class="t-empty py-16">
-	<Empty.Header class="max-w-md">
-		{#if Icon}
-			<!-- A white tile, not a brand tint: the accent marks the one action (DESIGN.md
-			     rule 1), and the button below is it. -->
+<Empty.Root class={cn(reveal && "t-empty", look.root, SURFACE[surface], className)}>
+	{#if Icon && look.icon}
+		<Icon
+			weight={iconWeight}
+			class={cn(look.icon, iconClass ?? "text-muted-foreground")}
+			aria-hidden="true"
+		/>
+	{/if}
+	<Empty.Header class={look.header}>
+		{#if Icon && !look.icon}
 			<Empty.Media class="mb-3 size-12 rounded-xl bg-card text-foreground shadow-card">
-				<Icon weight={iconWeight} class="size-6" />
+				<Icon aria-hidden="true" weight={iconWeight} class="size-6" />
 			</Empty.Media>
 		{/if}
-		<Empty.Title class="font-heading text-base font-semibold text-balance [overflow-wrap:anywhere]"
-			>{title}</Empty.Title
+		<Empty.Title
+			class={look.title}
+			role={heading ? "heading" : undefined}
+			aria-level={heading ? 2 : undefined}>{title}</Empty.Title
 		>
 		{#if description}
-			<Empty.Description>{description}</Empty.Description>
+			<Empty.Description class={look.description}>{description}</Empty.Description>
 		{/if}
 	</Empty.Header>
-	{#if actionLabel && (actionHref || onAction)}
-		<Empty.Content>
-			{#if actionHref}
+	{#if hasAction || actions}
+		<Empty.Content class="max-w-md flex-row flex-wrap justify-center gap-2">
+			{#if hasAction && actionHref}
 				<Button href={actionHref}>{actionLabel}</Button>
-			{:else}
+			{:else if hasAction}
 				<Button onclick={onAction}>{actionLabel}</Button>
 			{/if}
+			{@render actions?.()}
 		</Empty.Content>
 	{/if}
 </Empty.Root>
@@ -69,10 +147,21 @@
 <!-- STYLE -->
 <!-- =========================== -->
 <style>
-	/* Never `:nth-child` here: one such rule makes every DOM insert on the page restyle its later siblings. */
-	:global(.t-empty) > :global(*) {
-		animation: t-empty-in var(--duration-slow) var(--ease-smooth-out) both;
-		animation-delay: calc((sibling-index() - 1) * var(--duration-stagger));
+	@layer theme, base, components, utilities;
+
+	@layer components {
+		/* Never `:nth-child` here: one such rule makes every DOM insert on the page restyle its later siblings. */
+		:global(.t-empty) > :global(*) {
+			animation: t-empty-in var(--duration-slow) var(--ease-smooth-out) both;
+			animation-delay: calc((sibling-index() - 1) * var(--duration-stagger));
+		}
+
+		@media (prefers-reduced-motion: reduce) {
+			:global(.t-empty) > :global(*) {
+				animation-name: t-empty-fade;
+				animation-delay: 0s;
+			}
+		}
 	}
 
 	@keyframes -global-t-empty-in {
@@ -91,11 +180,4 @@
 			opacity: 0;
 		}
 	}
-
-	@media (prefers-reduced-motion: reduce) {
-		:global(.t-empty) > :global(*) {
-			animation-name: t-empty-fade;
-			animation-delay: 0s;
-		}
-	}
 </style>