@joewinke/jatui 0.38.6 → 0.40.0

package/dist/components/PinInput.svelte

@@ -1,4 +1,20 @@
 <script lang="ts">
+	/**
+	 * PinInput — one box per character for PINs and one-time codes.
+	 *
+	 * OTP autofill (BoardUI wave 1, jatui-owg2z): every cell carries
+	 * `autocomplete="one-time-code"` and accepts multi-character input (no
+	 * maxlength), so iOS/Android SMS autofill and Chrome WebOTP — which drop
+	 * the WHOLE code into whichever cell is focused — fill every cell from the
+	 * first. A paste distributes from the caret cell. Logic: utils/pinInput.ts.
+	 */
+	import {
+		applyCellInput,
+		cellsFromValue,
+		distribute,
+		isPinComplete
+	} from '../utils/pinInput';
+
 	interface Props {
 		length?: number;
 		value?: string;
@@ -7,6 +23,10 @@
 		error?: string;
 		disabled?: boolean;
 		label?: string;
+		/** `name` on the first cell, so a plain form post carries the code. */
+		name?: string;
+		/** Override the autocomplete token. Default `one-time-code`; use `off` for a static PIN. */
+		autocomplete?: HTMLInputElement['autocomplete'];
 		oncomplete?: (value: string) => void;
 	}
 
@@ -18,14 +38,27 @@
 		error = '',
 		disabled = false,
 		label = '',
+		name,
+		autocomplete = 'one-time-code',
 		oncomplete
 	}: Props = $props();
 
-	let cells: string[] = $state(Array(length).fill(''));
+	// Cells mirror `value`; an external write (reset, prefill) re-seeds them.
+	let cells: string[] = $state(cellsFromValue(value, length, numeric));
 	let inputEls: HTMLInputElement[] = $state([]);
 	let poppingCells: boolean[] = $state(Array(length).fill(false));
 	let shaking = $state(false);
 	let hadError = false;
+	let lastCompleted = '';
+
+	$effect(() => {
+		const v = value ?? '';
+		const n = length;
+		if (v !== cells.join('') || cells.length !== n) {
+			cells = cellsFromValue(v, n, numeric);
+			poppingCells = Array(n).fill(false);
+		}
+	});
 
 	$effect(() => {
 		const hasError = !!error;
@@ -48,50 +81,73 @@
 		setTimeout(() => { poppingCells[i] = false; }, 350);
 	}
 
-	function onInput(i: number, e: Event) {
-		const el = e.target as HTMLInputElement;
-		let char = el.value;
-
-		if (numeric) char = char.replace(/\D/g, '');
-
-		if (char.length > 1) {
-			// paste — split across cells
-			const chars = char.slice(0, length - i).split('');
-			chars.forEach((c, offset) => {
-				if (i + offset < length) {
-					cells[i + offset] = c;
-					if (c) popCell(i + offset);
-				}
-			});
-			const nextIdx = Math.min(i + chars.length, length - 1);
-			inputEls[nextIdx]?.focus();
-		} else {
-			cells[i] = char.slice(-1);
-			if (cells[i]) {
-				popCell(i);
-				inputEls[i + 1]?.focus();
+	function commit(next: string[], focus: number) {
+		next.forEach((c, i) => {
+			if (c && c !== cells[i]) popCell(i);
+		});
+		cells = next;
+		// The DOM value may hold extra characters (no maxlength, so OS autofill
+		// can deliver a whole code) — write each cell back to its single char.
+		inputEls.forEach((el, i) => {
+			if (el && el.value !== next[i]) el.value = next[i];
+		});
+		value = next.join('');
+		inputEls[focus]?.focus();
+		if (isPinComplete(next, length)) {
+			if (value !== lastCompleted) {
+				lastCompleted = value;
+				oncomplete?.(value);
 			}
+		} else {
+			lastCompleted = '';
 		}
+	}
 
-		value = cells.join('');
-		if (value.length === length && !value.includes('')) {
-			oncomplete?.(value);
-		}
+	function onInput(i: number, e: Event) {
+		const el = e.target as HTMLInputElement;
+		const r = applyCellInput(cells, i, el.value, { length, numeric });
+		commit(r.cells, r.focus);
+	}
+
+	function onPaste(i: number, e: ClipboardEvent) {
+		const text = e.clipboardData?.getData('text') ?? '';
+		if (!text) return;
+		e.preventDefault();
+		const r = distribute(cells, i, text, { length, numeric });
+		commit(r.cells, r.focus);
 	}
 
 	function onKeydown(i: number, e: KeyboardEvent) {
 		if (e.key === 'Backspace') {
+			e.preventDefault();
 			if (!cells[i]) {
-				inputEls[i - 1]?.focus();
+				if (i > 0) {
+					const next = [...cells];
+					next[i - 1] = '';
+					commit(next, i - 1);
+				}
 			} else {
-				cells[i] = '';
-				value = cells.join('');
+				const next = [...cells];
+				next[i] = '';
+				commit(next, i);
 			}
+		} else if (e.key === 'Delete') {
 			e.preventDefault();
+			const next = [...cells];
+			next[i] = '';
+			commit(next, i);
 		} else if (e.key === 'ArrowLeft') {
+			e.preventDefault();
 			inputEls[i - 1]?.focus();
 		} else if (e.key === 'ArrowRight') {
+			e.preventDefault();
 			inputEls[i + 1]?.focus();
+		} else if (e.key === 'Home') {
+			e.preventDefault();
+			inputEls[0]?.focus();
+		} else if (e.key === 'End') {
+			e.preventDefault();
+			inputEls[length - 1]?.focus();
 		}
 	}
 
@@ -111,6 +167,7 @@
 
 	<div
 		class="flex gap-2"
+		dir="ltr"
 		role="group"
 		aria-label={label || 'PIN input'}
 		aria-describedby={error ? `${groupId}-error` : undefined}
@@ -120,7 +177,12 @@
 				bind:this={inputEls[i]}
 				type={masked ? 'password' : 'text'}
 				inputmode={numeric ? 'numeric' : 'text'}
-				maxlength={1}
+				pattern={numeric ? '[0-9]*' : undefined}
+				autocomplete={autocomplete as any}
+				name={i === 0 ? name : undefined}
+				dir="ltr"
+				spellcheck="false"
+				autocapitalize="off"
 				value={cells[i]}
 				{disabled}
 				aria-label={`Digit ${i + 1} of ${length}`}
@@ -129,6 +191,7 @@
 				class:pin-cell--filled={!!cells[i]}
 				class:pin-cell--pop={poppingCells[i]}
 				oninput={(e) => onInput(i, e)}
+				onpaste={(e) => onPaste(i, e)}
 				onkeydown={(e) => onKeydown(i, e)}
 				onfocus={(e) => onFocus(e.target as HTMLInputElement)}
 			/>

package/dist/components/PinInput.svelte.d.ts

@@ -6,6 +6,10 @@ interface Props {
     error?: string;
     disabled?: boolean;
     label?: string;
+    /** `name` on the first cell, so a plain form post carries the code. */
+    name?: string;
+    /** Override the autocomplete token. Default `one-time-code`; use `off` for a static PIN. */
+    autocomplete?: HTMLInputElement['autocomplete'];
     oncomplete?: (value: string) => void;
 }
 declare const PinInput: import("svelte").Component<Props, {}, "value">;

package/dist/components/SearchDropdown.svelte

@@ -40,6 +40,8 @@
 		searchDebounceMs = 250,
 		onCreate,
 		createLabel = (q: string) => `Create "${q}"`,
+		option: optionSnippet,
+		searchLabel,
 	}: {
 		value: string;
 		groups: SearchDropdownGroup[];
@@ -92,8 +94,22 @@
 		onCreate?: (query: string) => void;
 		/** Label for the create row; receives the trimmed query. */
 		createLabel?: (query: string) => string;
+		/**
+		 * Custom body for each option row (replaces the default avatar, label and
+		 * check). The row itself (click, highlight, keyboard) stays the
+		 * component's; the snippet only draws what is inside it — e.g. a colour
+		 * dot, the label with the matched letters marked, and a status note.
+		 */
+		option?: Snippet<[SearchDropdownOption, { highlighted: boolean; selected: boolean }]>;
+		/** Accessible name for the search box and its list (defaults to the placeholder). */
+		searchLabel?: string;
 	} = $props();
 
+	// ARIA combobox wiring: the search box owns the listbox and points at the
+	// highlighted row, so arrows + Enter are announced without moving focus.
+	const listId = `sd-${Math.random().toString(36).slice(2, 9)}`;
+	const optionId = (i: number) => `${listId}-${i}`;
+
 	let open = $state(false);
 	let searchQuery = $state('');
 	let highlightedIndex = $state(-1);
@@ -166,10 +182,18 @@
 		highlightedIndex = idx >= 0 ? idx : 0;
 	});
 
+	// Embedded panels stay open after a pick (several picks in a row): hand
+	// focus back to the search box so the next one is typed straight away,
+	// even when the pick was a click that moved focus onto the row.
+	function refocusEmbedded() {
+		if (embedded) tick().then(() => searchInput?.focus());
+	}
+
 	function select(optionValue: string) {
 		open = false;
 		searchQuery = '';
 		onChange(optionValue);
+		refocusEmbedded();
 	}
 
 	function doCreate() {
@@ -178,6 +202,7 @@
 		open = false;
 		searchQuery = '';
 		onCreate(q);
+		refocusEmbedded();
 	}
 
 	function scrollHighlightedIntoView() {
@@ -202,6 +227,9 @@
 
 	function handleSearchKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape') {
+			// An embedded panel with an empty search has nothing of its own to
+			// close: let Escape reach the host (e.g. close the dialog it sits in).
+			if (embedded && !searchQuery) return;
 			e.stopPropagation();
 			open = false;
 			searchQuery = '';
@@ -319,6 +347,12 @@
 				{placeholder}
 				class="sd-search-input"
 				autocomplete="off"
+				role="combobox"
+				aria-label={searchLabel ?? placeholder}
+				aria-expanded={open || embedded}
+				aria-controls={listId}
+				aria-autocomplete="list"
+				aria-activedescendant={(open || embedded) && highlightedIndex >= 0 && highlightedIndex <= maxIndex ? optionId(highlightedIndex) : undefined}
 			/>
 			{#if searchQuery}
 				<button type="button" aria-label="Clear search" onclick={() => { searchQuery = ''; searchInput?.focus(); }} class="sd-search-clear">
@@ -329,17 +363,21 @@
 	</div>
 
 	<!-- Options list -->
-	<ul class="sd-list" bind:this={optionListRef}>
+	<ul class="sd-list" bind:this={optionListRef} id={listId} role="listbox" aria-label={searchLabel ?? placeholder}>
 		{#if filteredGroups.length > 0}
 			{#each filteredGroups as group, _gi}
-				<li class="sd-group-label">
+				<li class="sd-group-label" role="presentation">
 					<span>{group.label}</span>
 				</li>
 				{#each group.options as option}
 					{@const flatIdx = flatOptions.indexOf(option)}
-					<li>
+					<li role="presentation">
 						<button
 							type="button"
+							id={optionId(flatIdx)}
+							role="option"
+							tabindex="-1"
+							aria-selected={flatIdx === highlightedIndex}
 							onclick={() => select(option.value)}
 							class="sd-option"
 							class:sd-option-selected={value === option.value}
@@ -351,7 +389,9 @@
 									: `border-left-color: ${colorFn(option.value)}; color: ${colorFn(option.value)};`
 								: ''}
 						>
-							{#if option.image}
+							{#if optionSnippet}
+								{@render optionSnippet(option, { highlighted: flatIdx === highlightedIndex, selected: value === option.value })}
+							{:else if option.image}
 								<img src={option.image} alt="" class="sd-avatar" />
 							{:else if option.icon}
 								<span class="sd-option-icon">{option.icon}</span>
@@ -360,12 +400,14 @@
 									{option.label.charAt(0).toUpperCase()}
 								</span>
 							{/if}
-							{#if variant === 'chip' && colorFn && colorFn(option.value)}
+							{#if optionSnippet}
+								<!-- the snippet drew the whole row body -->
+							{:else if variant === 'chip' && colorFn && colorFn(option.value)}
 								<span class="sd-option-chip">{option.label}</span>
 							{:else}
 								<span class="truncate">{option.label}</span>
 							{/if}
-							{#if value === option.value}
+							{#if !optionSnippet && value === option.value}
 								<svg class="sd-check" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2.5"><path stroke-linecap="round" stroke-linejoin="round" d="M5 13l4 4L19 7" /></svg>
 							{/if}
 						</button>
@@ -373,13 +415,17 @@
 				{/each}
 			{/each}
 		{:else if !canCreate}
-			<li class="sd-empty">No matches for "{searchQuery}"</li>
+			<li class="sd-empty" role="presentation">No matches for "{searchQuery}"</li>
 		{/if}
 		{#if canCreate}
 			{@const createIdx = flatOptions.length}
-			<li>
+			<li role="presentation">
 				<button
 					type="button"
+					id={optionId(createIdx)}
+					role="option"
+					tabindex="-1"
+					aria-selected={highlightedIndex === createIdx}
 					onclick={doCreate}
 					class="sd-option sd-option-create"
 					class:sd-option-highlighted={highlightedIndex === createIdx}

package/dist/components/SearchDropdown.svelte.d.ts

@@ -61,6 +61,18 @@ type $$ComponentProps = {
     onCreate?: (query: string) => void;
     /** Label for the create row; receives the trimmed query. */
     createLabel?: (query: string) => string;
+    /**
+     * Custom body for each option row (replaces the default avatar, label and
+     * check). The row itself (click, highlight, keyboard) stays the
+     * component's; the snippet only draws what is inside it — e.g. a colour
+     * dot, the label with the matched letters marked, and a status note.
+     */
+    option?: Snippet<[SearchDropdownOption, {
+        highlighted: boolean;
+        selected: boolean;
+    }]>;
+    /** Accessible name for the search box and its list (defaults to the placeholder). */
+    searchLabel?: string;
 };
 declare const SearchDropdown: import("svelte").Component<$$ComponentProps, {
     openDropdown: () => void;

package/dist/components/TextArea.svelte

@@ -4,7 +4,14 @@
 	 *
 	 * Multi-line text input with validation, auto-resize, and character count.
 	 * Converted from Svelte 4 to Svelte 5 runes.
+	 *
+	 * Auto-grow (`autoResize`, or implied by `maxRows`) grows a whole line at a
+	 * time from `minRows` (default `rows`) up to `maxRows`, then scrolls. Where
+	 * the browser supports CSS `field-sizing: content` the growth is pure CSS
+	 * (no per-keystroke measuring); elsewhere it falls back to the row-quantized
+	 * JS path in utils/textareaRows.ts.
 	 */
+	import { textareaRowsHeight } from '../utils/textareaRows';
 
 	interface Props {
 		label?: string;
@@ -17,6 +24,10 @@
 		disabled?: boolean;
 		readonly?: boolean;
 		autoResize?: boolean;
+		/** Auto-grow floor in rows. Default `rows`. */
+		minRows?: number;
+		/** Auto-grow ceiling in rows; past it the field scrolls. Setting it turns auto-grow on. */
+		maxRows?: number;
 		error?: string;
 		helpText?: string;
 		showCount?: boolean;
@@ -39,6 +50,8 @@
 		disabled = false,
 		readonly = false,
 		autoResize = false,
+		minRows,
+		maxRows,
 		error = '',
 		helpText = '',
 		showCount = false,
@@ -73,24 +86,73 @@
 	const characterCount = $derived(value?.length || 0);
 	const isOverLimit = $derived(maxlength ? characterCount > maxlength : false);
 
+	const grows = $derived(autoResize || maxRows != null);
+	const floorRows = $derived(Math.max(1, minRows ?? rows));
+	// Decided after mount: SSR has no CSS.supports, and hydration does not
+	// repair a style attribute that differs from the server render.
+	let fieldSizing = $state(false);
+	$effect(() => {
+		fieldSizing = typeof CSS !== 'undefined' && CSS.supports?.('field-sizing', 'content') === true;
+	});
+
+	// Vertical padding + border, measured once mounted (border-box sizing).
+	let chromePx = $state(18);
+	let paddingPx = $state(16);
+	let lineHeightPx = $state(24);
+
+	function measureChrome(el: HTMLTextAreaElement) {
+		const cs = getComputedStyle(el);
+		const n = (v: string) => parseFloat(v) || 0;
+		paddingPx = n(cs.paddingTop) + n(cs.paddingBottom);
+		chromePx = paddingPx + n(cs.borderTopWidth) + n(cs.borderBottomWidth);
+		const lh = n(cs.lineHeight);
+		lineHeightPx = lh > 0 ? lh : n(cs.fontSize) * 1.5 || 24;
+	}
+
 	function handleInput(event: Event) {
 		const target = event.target as HTMLTextAreaElement;
 		value = target.value;
-		if (autoResize) autoResizeTextarea(target);
+		if (grows && !fieldSizing) autoResizeTextarea(target);
 		oninput?.(value);
 	}
 
 	function autoResizeTextarea(textarea: HTMLTextAreaElement) {
 		textarea.style.height = 'auto';
-		textarea.style.height = textarea.scrollHeight + 'px';
+		const r = textareaRowsHeight({
+			scrollHeight: textarea.scrollHeight,
+			lineHeight: lineHeightPx,
+			chrome: chromePx,
+			padding: paddingPx,
+			minRows: floorRows,
+			maxRows
+		});
+		textarea.style.height = r.height + 'px';
+		textarea.style.overflowY = r.overflow;
 	}
 
 	$effect(() => {
-		if (autoResize && textareaElement && value !== undefined) {
+		if (grows && textareaElement) measureChrome(textareaElement);
+	});
+
+	$effect(() => {
+		if (grows && !fieldSizing && textareaElement && value !== undefined) {
+			void floorRows;
+			void maxRows;
 			autoResizeTextarea(textareaElement);
 		}
 	});
 
+	const growStyle = $derived.by(() => {
+		if (!grows) return '';
+		const min = `min-height: ${Math.round(floorRows * lineHeightPx + chromePx)}px;`;
+		if (!fieldSizing) return min;
+		const max =
+			maxRows != null
+				? ` max-height: ${Math.round(Math.max(floorRows, maxRows) * lineHeightPx + chromePx)}px; overflow-y: auto;`
+				: '';
+		return `field-sizing: content; ${min}${max}`;
+	});
+
 	// Error-state shake (transitions.dev). Replays `t-input-shake` when `error`
 	// becomes set. See TextInput for the full rationale.
 	let hadError = false;
@@ -127,7 +189,7 @@
 		{id}
 		{name}
 		{placeholder}
-		{rows}
+		rows={grows ? floorRows : rows}
 		{maxlength}
 		{minlength}
 		{required}
@@ -138,7 +200,7 @@
 		class={textareaClass}
 		aria-describedby={error ? `${id}-error` : helpText ? `${id}-help` : undefined}
 		aria-invalid={error ? 'true' : 'false'}
-		style={autoResize ? `min-height: calc(1.5em * ${rows} + 1rem);` : ''}
+		style={growStyle}
 		onanimationend={() => textareaElement?.classList.remove('t-input-shake')}
 	></textarea>
 

package/dist/components/TextArea.svelte.d.ts

@@ -1,9 +1,3 @@
-/**
- * TextArea Component
- *
- * Multi-line text input with validation, auto-resize, and character count.
- * Converted from Svelte 4 to Svelte 5 runes.
- */
 interface Props {
     label?: string;
     value?: string;
@@ -15,6 +9,10 @@ interface Props {
     disabled?: boolean;
     readonly?: boolean;
     autoResize?: boolean;
+    /** Auto-grow floor in rows. Default `rows`. */
+    minRows?: number;
+    /** Auto-grow ceiling in rows; past it the field scrolls. Setting it turns auto-grow on. */
+    maxRows?: number;
     error?: string;
     helpText?: string;
     showCount?: boolean;

package/dist/components/ThemeSelector.svelte

@@ -6,6 +6,7 @@
 	 * By default includes all 33 standard DaisyUI themes. Pass custom `themes` prop to override.
 	 */
 	import { onMount } from 'svelte';
+	import { themeWipe } from '../utils/themeWipe';
 
 	interface ThemeOption {
 		name: string;
@@ -55,6 +56,7 @@
 		onThemeChange,
 		compact = false,
 		inline = false,
+		reveal = false,
 	}: {
 		dropUp?: boolean;
 		themes?: ThemeOption[];
@@ -65,6 +67,12 @@
 		compact?: boolean;
 		/** Render a collapsible `<details>` theme list instead of a dropdown — for embedding inside another menu. */
 		inline?: boolean;
+		/**
+		 * Reveal the new theme with a circular View Transition wipe from the
+		 * clicked item (`themeWipe`). `true`/'hard' = crisp edge, 'soft' =
+		 * feathered. Level-scaled; instant under reduced motion. Default off.
+		 */
+		reveal?: boolean | 'hard' | 'soft';
 	} = $props();
 
 	// svelte-ignore state_referenced_locally
@@ -87,9 +95,26 @@
 		}
 	});
 
-	function handleThemeChange(themeName: string) {
+	function applyTheme(themeName: string) {
+		currentTheme = themeName;
+		document.documentElement.setAttribute('data-theme', themeName);
+		localStorage.setItem(storageKey, themeName);
+		onThemeChange?.(themeName);
+	}
+
+	function handleThemeChange(themeName: string, event?: MouseEvent) {
 		if (themeName === currentTheme) return;
 
+		if (reveal) {
+			// Close the menu first so the snapshot doesn't freeze it open. The
+			// origin (pointer, or the item's centre on keyboard) is read now.
+			if (document.activeElement instanceof HTMLElement) document.activeElement.blur();
+			void themeWipe(event ?? null, () => applyTheme(themeName), {
+				edge: reveal === 'soft' ? 'soft' : 'hard'
+			});
+			return;
+		}
+
 		// Close dropdown first so the trigger is visible during animation
 		if (document.activeElement instanceof HTMLElement) {
 			document.activeElement.blur();
@@ -97,12 +122,7 @@
 
 		isAnimating = true;
 
-		setTimeout(() => {
-			currentTheme = themeName;
-			document.documentElement.setAttribute('data-theme', themeName);
-			localStorage.setItem(storageKey, themeName);
-			onThemeChange?.(themeName);
-		}, 150);
+		setTimeout(() => applyTheme(themeName), 150);
 
 		setTimeout(() => {
 			isAnimating = false;
@@ -133,7 +153,7 @@
 			{#each themes as theme}
 				<button
 					class="flex items-center gap-2 w-full px-2 py-1 rounded transition-colors hover:bg-base-300 {currentTheme === theme.name ? 'bg-primary/20' : ''}"
-					onclick={() => handleThemeChange(theme.name)}
+					onclick={(e) => handleThemeChange(theme.name, e)}
 				>
 					<div
 						data-theme={theme.name}
@@ -193,7 +213,7 @@
 				<li>
 					<button
 						class="gap-3 px-2"
-						onclick={() => handleThemeChange(theme.name)}
+						onclick={(e) => handleThemeChange(theme.name, e)}
 						class:active={currentTheme === theme.name}
 					>
 						<div

package/dist/components/ThemeSelector.svelte.d.ts

@@ -12,6 +12,12 @@ type $$ComponentProps = {
     compact?: boolean;
     /** Render a collapsible `<details>` theme list instead of a dropdown — for embedding inside another menu. */
     inline?: boolean;
+    /**
+     * Reveal the new theme with a circular View Transition wipe from the
+     * clicked item (`themeWipe`). `true`/'hard' = crisp edge, 'soft' =
+     * feathered. Level-scaled; instant under reduced motion. Default off.
+     */
+    reveal?: boolean | 'hard' | 'soft';
 };
 declare const ThemeSelector: import("svelte").Component<$$ComponentProps, {}, "">;
 type ThemeSelector = ReturnType<typeof ThemeSelector>;

package/dist/components/ThemeToggle.svelte

@@ -19,12 +19,16 @@
 	 * motion.css global floor and a component-local guard, since not every
 	 * consumer loads motion.css). Colours are token-only — no literals.
 	 */
+	import { flushSync } from 'svelte';
+	import { themeWipe } from '../utils/themeWipe';
+
 	let {
 		theme = $bindable('light'),
 		lightTheme = 'light',
 		darkTheme = 'dark',
 		onchange,
-		size = 'md'
+		size = 'md',
+		reveal = false
 	}: {
 		/** Current theme name (bindable). Anything that is not `darkTheme` reads as light. */
 		theme?: string;
@@ -36,6 +40,15 @@
 		onchange?: (theme: string) => void;
 		/** Hit-target size — sm 40px, md 44px, lg 48px. Never below the 40px touch floor. */
 		size?: 'sm' | 'md' | 'lg';
+		/**
+		 * Reveal the new theme with a circular View Transition wipe from the
+		 * button (`themeWipe`): `true`/'hard' = crisp edge, 'soft' = feathered.
+		 * The flip (bound `theme` + `onchange`) runs inside the transition, so
+		 * the consumer's theme write must be synchronous in `onchange` or in an
+		 * effect (it is flushed). Keyboard activation grows from the button's
+		 * centre; reduced motion swaps instantly. Default off.
+		 */
+		reveal?: boolean | 'hard' | 'soft';
 	} = $props();
 
 	let isDark = $derived(theme === darkTheme);
@@ -50,11 +63,23 @@
 
 	const label = $derived(isDark ? 'Switch to light mode' : 'Switch to dark mode');
 
-	function toggle() {
-		const next = isDark ? lightTheme : darkTheme;
+	function flip(next: string) {
 		theme = next;
 		onchange?.(next);
 	}
+
+	function toggle(event: MouseEvent) {
+		const next = isDark ? lightTheme : darkTheme;
+		if (!reveal) {
+			flip(next);
+			return;
+		}
+		// The origin is read synchronously: pointer position, or this button's
+		// centre for a keyboard activation.
+		void themeWipe(event, () => flushSync(() => flip(next)), {
+			edge: reveal === 'soft' ? 'soft' : 'hard'
+		});
+	}
 </script>
 
 <button