@heyramzi/ui 2.24.0 → 3.1.0

package/src/components/docs/on-this-page.svelte

@@ -2,8 +2,9 @@
 	// =========================
 	// IMPORTS
 	// =========================
-	import { tick } from "svelte";
 	import { CaretDown, List } from "phosphor-svelte";
+	import * as Popover from "../../shadcn/popover/index.js";
+	import { focusAfterRender } from "../../lib/focus.js";
 	import type { DocHeading } from "./scroll-spy.svelte.js";
 
 	// =========================
@@ -15,7 +16,7 @@
 		active: string;
 		/** What the rail is called: "On this page". Passed in so the library holds no copy. */
 		label: string;
-		onselect: (id: string) => void;
+		onSelect: (id: string) => void;
 		/**
 		 * `rail` sits beside the document, `bar` replaces it on a narrow pane, and `ticks` marks
 		 * each heading in the gutter with a card of headings on hover or focus.
@@ -26,7 +27,7 @@
 	// =========================
 	// PROPS
 	// =========================
-	let { items, active, label, onselect, variant = "rail" }: Props = $props();
+	let { items, active, label, onSelect, variant = "rail" }: Props = $props();
 
 	let hovering = $state(false);
 	let focusing = $state(false);
@@ -37,6 +38,7 @@
 	// =========================
 	let list = $state<HTMLElement | null>(null);
 	let open = $state(false);
+	let menu = $state<HTMLElement | null>(null);
 	let marker = $state({ y: 0, h: 0, ready: false });
 	// Plain, not state: the effect below writes `marker`, so it can't also read it.
 	let placed = false;
@@ -85,22 +87,18 @@
 		}
 	});
 
+	// Closing hands focus back to the bar's trigger, which Bits UI's Popover does.
 	function pick(id: string) {
 		open = false;
-		onselect(id);
-		void tick();
+		onSelect(id);
 	}
-</script>
 
-<svelte:window
-	onkeydown={(event) => {
-		if (event.key === "Escape") open = false;
-	}}
-	onpointerdown={(event) => {
-		if (!open) return;
-		if (!(event.target as HTMLElement).closest("[data-otp-bar]")) open = false;
-	}}
-/>
+	// The menu opens on the heading the reader is in, not on the first one.
+	function focusCurrent(event: Event) {
+		event.preventDefault();
+		void focusAfterRender(menu, '[aria-current="location"]', "button");
+	}
+</script>
 
 <!-- =========================== -->
 <!-- MARKUP -->
@@ -203,105 +201,115 @@
 		</div>
 	</nav>
 {:else}
-	<div data-otp-bar class="relative">
-		<button
-			type="button"
-			aria-expanded={open}
-			aria-label={label}
-			onclick={() => (open = !open)}
-			class="flex h-11 w-full items-center gap-2.5 px-4 text-left transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] hover:bg-muted/50"
-		>
-			<List size={16} class="shrink-0 text-muted-foreground" aria-hidden="true" />
-			<span class="shrink-0 text-xs font-medium text-muted-foreground">{label}</span>
-			<span class="min-w-0 flex-1 truncate text-sm font-medium text-foreground">{activeLabel}</span>
-			<CaretDown
-				size={14}
-				class="shrink-0 text-muted-foreground transition-transform duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {open
-					? 'rotate-180'
-					: ''}"
-			/>
-		</button>
-		<!-- How far through the reader is. The only motion here, and it is the state. -->
-		<span aria-hidden="true" class="absolute inset-x-0 bottom-0 h-px bg-border">
-			<span
-				class="otp-progress block h-full origin-left bg-brand dark:bg-brand-light"
-				style="transform: scaleX({progress});"
-			></span>
-		</span>
-
-		{#if open}
-			<nav
+	<Popover.Root bind:open>
+		<div class="relative">
+			<Popover.Trigger
 				aria-label={label}
-				class="thin-scrollbar absolute inset-x-2 top-full z-20 mt-1 max-h-[60svh] overflow-y-auto rounded-2xl bg-popover p-1.5 shadow-edge-raised"
+				class="flex h-11 w-full items-center gap-2.5 px-4 text-left transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] hover:bg-muted/50"
 			>
-				<ul class="flex flex-col">
-					{#each items as item (item.id)}
-						{@const current = item.id === active}
-						<li>
-							<button
-								type="button"
-								aria-current={current ? "location" : undefined}
-								onclick={() => pick(item.id)}
-								class="block w-full rounded-lg px-3 py-2.5 text-left text-sm leading-snug transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {current
-									? 'bg-muted font-medium text-foreground'
-									: 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'}"
-							>
-								{item.label}
-							</button>
-						</li>
-					{/each}
-				</ul>
-			</nav>
-		{/if}
-	</div>
+				<List size={16} class="shrink-0 text-muted-foreground" aria-hidden="true" />
+				<span class="shrink-0 text-xs font-medium text-muted-foreground">{label}</span>
+				<span class="min-w-0 flex-1 truncate text-sm font-medium text-foreground"
+					>{activeLabel}</span
+				>
+				<CaretDown
+					aria-hidden="true"
+					size={14}
+					class="shrink-0 text-muted-foreground transition-transform duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {open
+						? 'rotate-180'
+						: ''}"
+				/>
+			</Popover.Trigger>
+			<!-- How far through the reader is. The only motion here, and it is the state. -->
+			<span aria-hidden="true" class="absolute inset-x-0 bottom-0 h-px bg-border">
+				<span
+					class="otp-progress block h-full origin-left bg-brand dark:bg-brand-light"
+					style="transform: scaleX({progress});"
+				></span>
+			</span>
+
+			<!-- Bits UI moves focus into the menu, closes it on Esc or a click outside, and returns focus to the trigger. -->
+			<Popover.Content
+				bind:ref={menu}
+				align="start"
+				alignOffset={8}
+				onOpenAutoFocus={focusCurrent}
+				class="thin-scrollbar max-h-[60svh] w-[calc(var(--bits-popover-anchor-width)-1rem)] p-1.5"
+			>
+				<nav aria-label={label}>
+					<ul class="flex flex-col">
+						{#each items as item (item.id)}
+							{@const current = item.id === active}
+							<li>
+								<button
+									type="button"
+									aria-current={current ? "location" : undefined}
+									onclick={() => pick(item.id)}
+									class="block w-full rounded-lg px-3 py-2.5 text-left text-sm leading-snug transition-colors duration-[var(--duration-fast)] ease-[var(--ease-smooth-out)] {current
+										? 'bg-muted font-medium text-foreground'
+										: 'text-muted-foreground hover:bg-muted/60 hover:text-foreground'}"
+								>
+									{item.label}
+								</button>
+							</li>
+						{/each}
+					</ul>
+				</nav>
+			</Popover.Content>
+		</div>
+	</Popover.Root>
 {/if}
 
 <!-- =========================== -->
 <!-- STYLE -->
 <!-- =========================== -->
 <style>
-	.otp-marker.is-ready {
-		transition:
-			transform var(--duration-medium) var(--ease-smooth-out),
-			height var(--duration-medium) var(--ease-smooth-out);
-	}
+	@layer theme, base, components, utilities;
 
-	.otp-progress {
-		transition: transform var(--duration-medium) var(--ease-smooth-out);
-	}
-
-	/* A long list fades into its edges instead of ending on a hard cut. */
-	.otp-fade {
-		mask-image: linear-gradient(
-			to bottom,
-			transparent,
-			#000 0.5rem,
-			#000 calc(100% - 1.5rem),
-			transparent
-		);
-	}
+	@layer components {
+		.otp-marker.is-ready {
+			transition:
+				transform var(--duration-medium) var(--ease-smooth-out),
+				height var(--duration-medium) var(--ease-smooth-out);
+		}
 
-	/* Opacity and a short slide, no scale: the card is anchored to a line of ticks. */
-	.otp-card {
-		opacity: 0;
-		translate: -4px -50%;
-		pointer-events: none;
-		transition:
-			opacity var(--duration-fast) var(--ease-smooth-out),
-			translate var(--duration-fast) var(--ease-smooth-out);
-	}
+		.otp-progress {
+			transition: transform var(--duration-medium) var(--ease-smooth-out);
+		}
 
-	.otp-card[data-open="true"] {
-		opacity: 1;
-		translate: 0 -50%;
-		pointer-events: auto;
-	}
+		/* A long list fades into its edges instead of ending on a hard cut. */
+		.otp-fade {
+			mask-image: linear-gradient(
+				to bottom,
+				transparent,
+				#000 0.5rem,
+				#000 calc(100% - 1.5rem),
+				transparent
+			);
+		}
 
-	@media (prefers-reduced-motion: reduce) {
-		.otp-marker.is-ready,
-		.otp-progress,
+		/* Opacity and a short slide, no scale: the card is anchored to a line of ticks. */
 		.otp-card {
-			transition: none;
+			opacity: 0;
+			translate: -4px -50%;
+			pointer-events: none;
+			transition:
+				opacity var(--duration-fast) var(--ease-smooth-out),
+				translate var(--duration-fast) var(--ease-smooth-out);
+		}
+
+		.otp-card[data-open="true"] {
+			opacity: 1;
+			translate: 0 -50%;
+			pointer-events: auto;
+		}
+
+		@media (prefers-reduced-motion: reduce) {
+			.otp-marker.is-ready,
+			.otp-progress,
+			.otp-card {
+				transition: none;
+			}
 		}
 	}
 </style>

package/src/components/docs/on-this-page.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { DocHeading } from "./scroll-spy.svelte.js";
+interface Props {
+    items: DocHeading[];
+    /** The id the reader is in. */
+    active: string;
+    /** What the rail is called: "On this page". Passed in so the library holds no copy. */
+    label: string;
+    onSelect: (id: string) => void;
+    /**
+     * `rail` sits beside the document, `bar` replaces it on a narrow pane, and `ticks` marks
+     * each heading in the gutter with a card of headings on hover or focus.
+     */
+    variant?: "rail" | "bar" | "ticks";
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

package/src/components/field-row/field-row.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from "svelte";
+interface Props {
+    label: string;
+    /** Id of the control, so the label focuses it. */
+    for: string;
+    description?: string;
+    error?: string;
+    class?: string;
+    /** The control: an Input, a Select trigger. It takes the width the action leaves. */
+    children: Snippet;
+    /** The button that acts on the control. Same height as the control, bottom of the row. */
+    action?: Snippet;
+}
+declare const $$Component: import("svelte").Component<Props, {}, "">;
+type $$Component = ReturnType<typeof $$Component>;
+export default $$Component;

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;