@dorsk/tsumikit 0.46.0 → 0.48.0

package/README.md

@@ -64,6 +64,18 @@ import { Button, Field, Input, Modal, ThemePicker } from '@dorsk/tsumikit';
 - `<ThemePicker />` and `<FontScalePicker />` wire the stores to the UI. Theme
   is persisted to `localStorage` and applied with no flash (head snippet in
   `app.html`) and updates the mobile `<meta name="theme-color">`.
+- The store keeps a **preference**, not just an id: one remembered light theme,
+  one remembered dark theme, and which of the two is pinned — or `auto`, which
+  follows `prefers-color-scheme` and repaints when the system flips.
+  `theme.choose(id | 'auto')`, `theme.mode`, `theme.pref`, `theme.resolved`,
+  `theme.hydrate(pref)` (replay a server-side preference) and
+  `theme.onchange = (pref) => …` (mirror it back). `theme.set(id)` and
+  `theme.current` are unchanged. `<ThemePicker auto />` adds the "Auto" row;
+  its labels (`autoLabel`, `autoHelp`, `lightLabel`, `darkLabel`) are props.
+- **Storage format (0.47):** `localStorage['tsumikit-theme']` now holds
+  `{"mode","light","dark"}` instead of a bare theme id. A bare id left by an
+  older version still loads — it pins its own slot — but a downgrade will not
+  read the new blob and falls back to the default theme.
 
 ### Stylesheets
 

package/dist/components/molecules/Carousel.svelte

@@ -0,0 +1,276 @@
+<script lang="ts" generics="T">
+	/**
+	 * Ordered full-bleed panels stepped with prev/next, dot indicators, arrow
+	 * keys and horizontal swipe.
+	 *
+	 * ARIA follows the WAI-ARIA carousel pattern in its *group* flavour: the
+	 * root is a region with `aria-roledescription="carousel"`, every slide is a
+	 * `group` with `aria-roledescription="slide"` named "N of M", and the dots
+	 * are plain buttons. The tablist flavour was rejected because it makes the
+	 * dots the primary navigation and turns each slide into a `tabpanel`, which
+	 * is the wrong model when prev/next is the main affordance and the panels
+	 * are unlabelled content rather than named destinations. The slide container
+	 * is a polite live region while the carousel is not auto-rotating.
+	 */
+	import type { Snippet } from 'svelte';
+	import IconButton from './IconButton.svelte';
+	import { clampSlide, nextSlideForKey, stepSlide, swipeStep } from './carousel-keyboard.js';
+
+	let {
+		slides,
+		slide,
+		index = $bindable(0),
+		onchange,
+		loop = false,
+		autoplay = 0,
+		dots = true,
+		controls = true,
+		counter = false,
+		label = 'Carousel',
+		class: klass = '',
+		style: styleProp = '',
+		slideClass = ''
+	}: {
+		/** One entry per panel. Entries may themselves be snippets when no `slide` renderer is given. */
+		slides: T[];
+		/** Renders one panel from its entry and position. */
+		slide?: Snippet<[T, number]>;
+		/** Active panel; bindable. Clamped (or wrapped with `loop`) into range. */
+		index?: number;
+		onchange?: (index: number) => void;
+		/** Wrap from the last panel to the first and back. */
+		loop?: boolean;
+		/** Milliseconds between automatic advances. `0` (default) disables it. When
+		 *  on, rotation pauses on hover and focus and a play/pause control appears. */
+		autoplay?: number;
+		dots?: boolean;
+		controls?: boolean;
+		/** Show an `N / M` position counter. */
+		counter?: boolean;
+		label?: string;
+		class?: string;
+		style?: string;
+		slideClass?: string;
+	} = $props();
+
+	const count = $derived(slides.length);
+	const baseId = `carousel-${Math.random().toString(36).slice(2, 8)}`;
+
+	$effect(() => {
+		const clamped = clampSlide(index, count, false);
+		if (clamped !== index) index = clamped;
+	});
+
+	let rootEl = $state<HTMLElement | null>(null);
+
+	function go(next: number, focusDot = false) {
+		const target = clampSlide(next, count, loop);
+		if (target === index) return;
+		index = target;
+		onchange?.(target);
+		if (focusDot) {
+			queueMicrotask(() =>
+				rootEl?.querySelector<HTMLButtonElement>(`#${baseId}-dot-${target}`)?.focus()
+			);
+		}
+	}
+	const prev = () => go(stepSlide(index, count, -1, loop));
+	const next = () => go(stepSlide(index, count, 1, loop));
+	const atStart = $derived(!loop && index <= 0);
+	const atEnd = $derived(!loop && index >= count - 1);
+
+	function onkeydown(e: KeyboardEvent) {
+		const tag = (e.target as HTMLElement | null)?.tagName;
+		if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+		const target = nextSlideForKey(index, count, e.key, loop);
+		if (target === undefined) return;
+		e.preventDefault();
+		const inDots = (e.target as HTMLElement | null)?.closest('.dots') !== null;
+		go(target, inDots);
+	}
+
+	let startX = 0;
+	let startY = 0;
+	let pointerId: number | null = null;
+	function onpointerdown(e: PointerEvent) {
+		if (e.pointerType === 'mouse' && e.button !== 0) return;
+		pointerId = e.pointerId;
+		startX = e.clientX;
+		startY = e.clientY;
+	}
+	function onpointerup(e: PointerEvent) {
+		if (e.pointerId !== pointerId) return;
+		pointerId = null;
+		const step = swipeStep(e.clientX - startX, e.clientY - startY);
+		if (step) go(stepSlide(index, count, step, loop));
+	}
+	function onpointercancel() {
+		pointerId = null;
+	}
+
+	let playing = $derived(autoplay > 0);
+	let hovered = $state(false);
+	let focused = $state(false);
+	const rotating = $derived(playing && autoplay > 0 && count > 1 && !hovered && !focused);
+	$effect(() => {
+		if (!rotating) return;
+		const id = setInterval(() => go(stepSlide(index, count, 1, true)), autoplay);
+		return () => clearInterval(id);
+	});
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<section
+	bind:this={rootEl}
+	class="carousel {klass}"
+	style={styleProp}
+	aria-roledescription="carousel"
+	aria-label={label}
+	data-tsu="Carousel"
+	{onkeydown}
+	onpointerenter={() => (hovered = true)}
+	onpointerleave={() => (hovered = false)}
+	onfocusin={() => (focused = true)}
+	onfocusout={(e) => {
+		if (!rootEl?.contains(e.relatedTarget as Node | null)) focused = false;
+	}}
+>
+	<!-- svelte-ignore a11y_no_static_element_interactions -->
+	<div
+		class="viewport"
+		aria-live={rotating ? 'off' : 'polite'}
+		{onpointerdown}
+		{onpointerup}
+		{onpointercancel}
+	>
+		<div class="track" style:transform="translateX(-{index * 100}%)">
+			{#each slides as item, i (i)}
+				<div
+					class="slide {slideClass}"
+					role="group"
+					aria-roledescription="slide"
+					aria-label="{i + 1} of {count}"
+					aria-hidden={i !== index}
+					inert={i !== index}
+					id="{baseId}-slide-{i}"
+				>
+					{#if slide}
+						{@render slide(item, i)}
+					{:else}
+						{@render (item as unknown as Snippet)()}
+					{/if}
+				</div>
+			{/each}
+		</div>
+	</div>
+
+	{#if count > 1 && (controls || dots || counter || autoplay > 0)}
+		<div class="bar">
+			{#if controls}
+				<IconButton icon="chevron-left" label="Previous slide" variant="ghost" box="sm" disabled={atStart} onclick={prev} />
+			{/if}
+			{#if dots}
+				<div class="dots" role="group" aria-label="Choose slide">
+					{#each slides as _, i (i)}
+						<button
+							type="button"
+							class="dot"
+							class:active={i === index}
+							id="{baseId}-dot-{i}"
+							aria-label="Slide {i + 1}"
+							aria-current={i === index ? 'true' : undefined}
+							aria-controls="{baseId}-slide-{i}"
+							tabindex={i === index ? 0 : -1}
+							onclick={() => go(i)}
+						></button>
+					{/each}
+				</div>
+			{/if}
+			{#if counter}
+				<span class="counter">{index + 1} / {count}</span>
+			{/if}
+			{#if autoplay > 0}
+				<IconButton
+					icon={playing ? 'pause' : 'play'}
+					label={playing ? 'Stop automatic rotation' : 'Start automatic rotation'}
+					variant="ghost"
+					box="sm"
+					pressed={playing}
+					onclick={() => (playing = !playing)}
+				/>
+			{/if}
+			{#if controls}
+				<IconButton icon="chevron-right" label="Next slide" variant="ghost" box="sm" disabled={atEnd} onclick={next} />
+			{/if}
+		</div>
+	{/if}
+</section>
+
+<style>
+	.carousel {
+		display: flex;
+		flex-direction: column;
+		gap: var(--sp-3);
+		min-width: 0;
+	}
+	.viewport {
+		overflow: hidden;
+		border-radius: var(--r-md);
+		touch-action: pan-y;
+		user-select: none;
+	}
+	.track {
+		display: flex;
+		width: 100%;
+		transition: transform 0.35s var(--ease);
+	}
+	.slide {
+		flex: 0 0 100%;
+		min-width: 0;
+	}
+	.bar {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		gap: var(--sp-2);
+	}
+	.dots {
+		display: flex;
+		align-items: center;
+		gap: var(--sp-2);
+	}
+	.dot {
+		width: 0.5rem;
+		height: 0.5rem;
+		padding: 0;
+		border: 0;
+		border-radius: var(--r-pill);
+		background: var(--border);
+		cursor: pointer;
+		transition:
+			background 0.12s var(--ease),
+			transform 0.12s var(--ease);
+	}
+	.dot:hover {
+		background: var(--text-faint);
+	}
+	.dot.active {
+		background: var(--accent);
+		transform: scale(1.25);
+	}
+	.dot:focus-visible {
+		outline: 2px solid var(--accent);
+		outline-offset: 2px;
+	}
+	.counter {
+		color: var(--text-muted);
+		font-size: var(--fs-sm);
+		font-variant-numeric: tabular-nums;
+	}
+	@media (prefers-reduced-motion: reduce) {
+		.track,
+		.dot {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/molecules/Carousel.svelte.d.ts

@@ -0,0 +1,59 @@
+/**
+     * Ordered full-bleed panels stepped with prev/next, dot indicators, arrow
+     * keys and horizontal swipe.
+     *
+     * ARIA follows the WAI-ARIA carousel pattern in its *group* flavour: the
+     * root is a region with `aria-roledescription="carousel"`, every slide is a
+     * `group` with `aria-roledescription="slide"` named "N of M", and the dots
+     * are plain buttons. The tablist flavour was rejected because it makes the
+     * dots the primary navigation and turns each slide into a `tabpanel`, which
+     * is the wrong model when prev/next is the main affordance and the panels
+     * are unlabelled content rather than named destinations. The slide container
+     * is a polite live region while the carousel is not auto-rotating.
+     */
+import type { Snippet } from 'svelte';
+declare function $$render<T>(): {
+    props: {
+        /** One entry per panel. Entries may themselves be snippets when no `slide` renderer is given. */
+        slides: T[];
+        /** Renders one panel from its entry and position. */
+        slide?: Snippet<[T, number]>;
+        /** Active panel; bindable. Clamped (or wrapped with `loop`) into range. */
+        index?: number;
+        onchange?: (index: number) => void;
+        /** Wrap from the last panel to the first and back. */
+        loop?: boolean;
+        /** Milliseconds between automatic advances. `0` (default) disables it. When
+         *  on, rotation pauses on hover and focus and a play/pause control appears. */
+        autoplay?: number;
+        dots?: boolean;
+        controls?: boolean;
+        /** Show an `N / M` position counter. */
+        counter?: boolean;
+        label?: string;
+        class?: string;
+        style?: string;
+        slideClass?: string;
+    };
+    exports: {};
+    bindings: "index";
+    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(): "index";
+    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 Carousel: $$IsomorphicComponent;
+type Carousel<T> = InstanceType<typeof Carousel<T>>;
+export default Carousel;

package/dist/components/molecules/ThemePicker.svelte

@@ -7,17 +7,45 @@
 	// has no [data-theme] block, so its swatch carries the :root values.
 	import Popover from './Popover.svelte';
 	import { type ThemeDef, theme } from '../../stores/theme.svelte';
+	import { AUTO_THEME } from '../../theme-mode';
 
-	let { class: klass = '' }: { class?: string } = $props();
+	let {
+		auto = false,
+		autoLabel = 'Auto',
+		autoHelp = 'Follow the system light/dark setting',
+		lightLabel = 'Light',
+		darkLabel = 'Dark',
+		class: klass = '',
+	}: {
+		/** Offer an "auto" row that follows `prefers-color-scheme`, remembering
+		 *  one light and one dark theme. */
+		auto?: boolean;
+		autoLabel?: string;
+		autoHelp?: string;
+		lightLabel?: string;
+		darkLabel?: string;
+		class?: string;
+	} = $props();
 
 	let hovered = $state<ThemeDef | null>(null);
+	let hoveredAuto = $state(false);
+	const isAuto = $derived(auto && theme.mode === AUTO_THEME);
 	const shown = $derived(hovered ?? theme.option);
 	const groups = $derived(
 		(['light', 'dark'] as const).map((mode) => ({
 			mode,
-			themes: theme.all.filter((t) => t.mode === mode)
+			label: mode === 'light' ? lightLabel : darkLabel,
+			themes: theme.all.filter((t) => t.mode === mode),
 		}))
 	);
+	const named = (id: string) => theme.all.find((t) => t.id === id)?.label ?? id;
+	const autoCaption = $derived(`${autoLabel} · ${named(theme.pref.light)} / ${named(theme.pref.dark)}`);
+	const title = $derived(isAuto ? `${autoLabel} · ${theme.label}` : `Theme: ${theme.label}`);
+	const caption = $derived(
+		hoveredAuto || (isAuto && !hovered)
+			? autoCaption
+			: `${shown.icon ?? theme.fallbackIcon} ${shown.label}`
+	);
 </script>
 
 {#snippet swatch(id: string)}
@@ -26,18 +54,19 @@
 	</span>
 {/snippet}
 
-<Popover label="Theme: {theme.label}" placement="bottom-end" triggerClass={klass} box="md">
-	{#snippet trigger()}<span class="trigger" data-tsu="ThemePicker" title="Theme: {theme.label}">{@render swatch(theme.current)}</span>{/snippet}
+<Popover label={title} placement="bottom-end" triggerClass={klass} box="md">
+	{#snippet trigger()}<span class="trigger" data-tsu="ThemePicker" {title}>{@render swatch(theme.current)}{#if isAuto}<span class="auto-dot" aria-hidden="true">◐</span>{/if}</span>{/snippet}
 	<div class="panel">
 		{#each groups as g (g.mode)}
-			<div class="group-label">{g.mode}</div>
-			<div class="grid" role="group" aria-label="{g.mode} themes">
+			<div class="group-label">{g.label}</div>
+			<div class="grid" role="group" aria-label="{g.label} themes">
 				{#each g.themes as t (t.id)}
 					<button
 						type="button"
 						class="cell"
-						class:current={t.id === theme.current}
-						aria-pressed={t.id === theme.current}
+						class:current={!isAuto && t.id === theme.current}
+						class:remembered={isAuto && t.id === theme.pref[g.mode]}
+						aria-pressed={!isAuto && t.id === theme.current}
 						aria-label={t.label}
 						title="{t.icon ?? theme.fallbackIcon} {t.label}"
 						onclick={() => theme.set(t.id)}
@@ -51,14 +80,50 @@
 				{/each}
 			</div>
 		{/each}
-		<div class="caption" aria-live="polite">{shown.icon ?? theme.fallbackIcon} {shown.label}</div>
+		{#if auto}
+			<button
+				type="button"
+				class="auto"
+				class:current={isAuto}
+				aria-pressed={isAuto}
+				title={autoCaption}
+				onclick={() => theme.choose(AUTO_THEME)}
+				onpointerenter={() => (hoveredAuto = true)}
+				onpointerleave={() => (hoveredAuto = false)}
+				onfocus={() => (hoveredAuto = true)}
+				onblur={() => (hoveredAuto = false)}
+			>
+				<span class="auto-glyph" aria-hidden="true">◐</span>
+				<span class="auto-text">
+					<span class="auto-name">{autoLabel}</span>
+					<span class="auto-help">{autoHelp}</span>
+				</span>
+				<span class="auto-pair" aria-hidden="true">
+					{@render swatch(theme.pref.light)}
+					<span class="slash">/</span>
+					{@render swatch(theme.pref.dark)}
+				</span>
+			</button>
+		{/if}
+		<div class="caption" aria-live="polite">{caption}</div>
 	</div>
 </Popover>
 
 <style>
 	.trigger {
+		position: relative;
 		display: inline-flex;
 	}
+	.auto-dot {
+		position: absolute;
+		right: -0.35rem;
+		bottom: -0.35rem;
+		border-radius: 50%;
+		background: var(--bg);
+		color: var(--text-muted);
+		font-size: var(--fs-xs);
+		line-height: 1;
+	}
 	.swatch {
 		display: grid;
 		grid-template-columns: 1fr 1fr;
@@ -123,14 +188,68 @@
 	.cell.current {
 		border-color: var(--accent);
 	}
-	.cell:focus-visible {
+	.cell.remembered {
+		border-color: var(--accent);
+		border-style: dashed;
+	}
+	.cell:focus-visible,
+	.auto:focus-visible {
 		outline: 2px solid var(--accent);
 		outline-offset: 1px;
 	}
+	.auto {
+		display: flex;
+		align-items: center;
+		gap: var(--sp-2);
+		width: 100%;
+		margin-top: var(--sp-2);
+		padding: var(--sp-1) var(--sp-2);
+		border: 2px solid transparent;
+		border-top: 1px solid var(--border);
+		border-radius: var(--r-md);
+		background: none;
+		color: inherit;
+		text-align: left;
+		cursor: pointer;
+	}
+	.auto:hover {
+		background: var(--bg-elevated-2);
+	}
+	.auto.current {
+		border-color: var(--accent);
+	}
+	.auto-glyph {
+		font-size: var(--fs-md);
+		line-height: 1;
+	}
+	.auto-text {
+		display: flex;
+		flex-direction: column;
+		flex: 1 1 auto;
+		min-width: 0;
+	}
+	.auto-name {
+		font-size: var(--fs-sm);
+	}
+	.auto-help {
+		font-size: var(--fs-xs);
+		color: var(--text-faint);
+		white-space: normal;
+	}
+	.auto-pair {
+		display: inline-flex;
+		align-items: center;
+		gap: var(--sp-1);
+	}
+	.slash {
+		color: var(--text-faint);
+		font-size: var(--fs-xs);
+	}
 	.caption {
 		margin-top: var(--sp-2);
 		text-align: center;
 		font-size: var(--fs-sm);
 		color: var(--text-muted);
+		white-space: normal;
 	}
 </style>

package/dist/components/molecules/ThemePicker.svelte.d.ts

@@ -1,4 +1,11 @@
 type $$ComponentProps = {
+    /** Offer an "auto" row that follows `prefers-color-scheme`, remembering
+     *  one light and one dark theme. */
+    auto?: boolean;
+    autoLabel?: string;
+    autoHelp?: string;
+    lightLabel?: string;
+    darkLabel?: string;
     class?: string;
 };
 declare const ThemePicker: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/molecules/carousel-keyboard.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Clamp a slide index into `[0, count)`, wrapping when `loop` is set.
+ *
+ * @param {number} index
+ * @param {number} count
+ * @param {boolean} [loop]
+ * @returns {number}
+ */
+export function clampSlide(index: number, count: number, loop?: boolean): number;
+/**
+ * Step from `current` by `delta` slides. Without `loop` the edges absorb the
+ * step, so stepping past the last slide stays on it.
+ *
+ * @param {number} current
+ * @param {number} count
+ * @param {number} delta
+ * @param {boolean} [loop]
+ * @returns {number}
+ */
+export function stepSlide(current: number, count: number, delta: number, loop?: boolean): number;
+/**
+ * Resolve a Carousel navigation key to the slide it selects. Left/Right step by
+ * one (wrapping only with `loop`), Home/End jump to the first/last slide.
+ * Unhandled keys return `undefined` so the browser keeps its default.
+ *
+ * @param {number} current
+ * @param {number} count
+ * @param {string} key
+ * @param {boolean} [loop]
+ * @returns {number | undefined}
+ */
+export function nextSlideForKey(current: number, count: number, key: string, loop?: boolean): number | undefined;
+/**
+ * Interpret a completed pointer gesture as a slide step. A gesture counts as a
+ * horizontal swipe only when it travels at least `threshold` px on the x axis
+ * and further on x than on y; anything else is left to the page (vertical
+ * scroll, taps). Swiping left reveals the next slide, so the result is +1.
+ *
+ * @param {number} dx
+ * @param {number} dy
+ * @param {number} [threshold]
+ * @returns {-1 | 0 | 1}
+ */
+export function swipeStep(dx: number, dy: number, threshold?: number): -1 | 0 | 1;

package/dist/components/molecules/carousel-keyboard.js

@@ -0,0 +1,63 @@
+/**
+ * Clamp a slide index into `[0, count)`, wrapping when `loop` is set.
+ *
+ * @param {number} index
+ * @param {number} count
+ * @param {boolean} [loop]
+ * @returns {number}
+ */
+export function clampSlide(index, count, loop = false) {
+	if (count <= 0 || !Number.isFinite(index)) return 0;
+	if (loop) return ((Math.trunc(index) % count) + count) % count;
+	return Math.min(Math.max(Math.trunc(index), 0), count - 1);
+}
+
+/**
+ * Step from `current` by `delta` slides. Without `loop` the edges absorb the
+ * step, so stepping past the last slide stays on it.
+ *
+ * @param {number} current
+ * @param {number} count
+ * @param {number} delta
+ * @param {boolean} [loop]
+ * @returns {number}
+ */
+export function stepSlide(current, count, delta, loop = false) {
+	return clampSlide(current + delta, count, loop);
+}
+
+/**
+ * Resolve a Carousel navigation key to the slide it selects. Left/Right step by
+ * one (wrapping only with `loop`), Home/End jump to the first/last slide.
+ * Unhandled keys return `undefined` so the browser keeps its default.
+ *
+ * @param {number} current
+ * @param {number} count
+ * @param {string} key
+ * @param {boolean} [loop]
+ * @returns {number | undefined}
+ */
+export function nextSlideForKey(current, count, key, loop = false) {
+	if (count <= 0) return undefined;
+	if (key === 'ArrowRight') return stepSlide(current, count, 1, loop);
+	if (key === 'ArrowLeft') return stepSlide(current, count, -1, loop);
+	if (key === 'Home') return 0;
+	if (key === 'End') return count - 1;
+	return undefined;
+}
+
+/**
+ * Interpret a completed pointer gesture as a slide step. A gesture counts as a
+ * horizontal swipe only when it travels at least `threshold` px on the x axis
+ * and further on x than on y; anything else is left to the page (vertical
+ * scroll, taps). Swiping left reveals the next slide, so the result is +1.
+ *
+ * @param {number} dx
+ * @param {number} dy
+ * @param {number} [threshold]
+ * @returns {-1 | 0 | 1}
+ */
+export function swipeStep(dx, dy, threshold = 40) {
+	if (Math.abs(dx) < threshold || Math.abs(dx) <= Math.abs(dy)) return 0;
+	return dx < 0 ? 1 : -1;
+}

package/dist/index.d.ts

@@ -41,6 +41,7 @@ export { type Attachment, default as AttachmentList, } from './components/molecu
 export { type BreadcrumbItem, default as Breadcrumb, } from './components/molecules/Breadcrumb.svelte';
 export { default as Callout } from './components/molecules/Callout.svelte';
 export { default as CapBar } from './components/molecules/CapBar.svelte';
+export { default as Carousel } from './components/molecules/Carousel.svelte';
 export { default as ChatBubble } from './components/molecules/ChatBubble.svelte';
 export { default as CodeBlock } from './components/molecules/CodeBlock.svelte';
 export { default as Composer } from './components/molecules/Composer.svelte';
@@ -90,6 +91,7 @@ export type { ControlSize } from './size';
 export { fontScale, SCALE_LEVELS, type ScaleLevel } from './stores/fontscale.svelte';
 export { type Mode, THEMES, theme } from './stores/theme.svelte';
 export { type Toast, type ToastAction, type ToastOptions, type ToastTone, type ToastToneInput, toasts, } from './stores/toast.svelte';
+export { AUTO_THEME, chooseTheme, DEFAULT_THEME_PREFERENCE, pickerValue, preferenceFrom, resolveTheme, type SlotOf, type ThemeChoice, type ThemePreference, type ThemeSlot, } from './theme-mode';
 export { formatTimestamp, localTimeZone, relativeTime, type TimeInput, type TimestampMode, } from './timestamp';
 export { canonicalTone, type Tone } from './tone';
 export { pathCandidates, type TruncateMode, type TruncateOptions, truncate } from './truncate';

package/dist/index.js

@@ -47,6 +47,7 @@ export { default as AttachmentList, } from './components/molecules/AttachmentLis
 export { default as Breadcrumb, } from './components/molecules/Breadcrumb.svelte';
 export { default as Callout } from './components/molecules/Callout.svelte';
 export { default as CapBar } from './components/molecules/CapBar.svelte';
+export { default as Carousel } from './components/molecules/Carousel.svelte';
 export { default as ChatBubble } from './components/molecules/ChatBubble.svelte';
 export { default as CodeBlock } from './components/molecules/CodeBlock.svelte';
 export { default as Composer } from './components/molecules/Composer.svelte';
@@ -101,6 +102,7 @@ export { fontScale, SCALE_LEVELS } from './stores/fontscale.svelte';
 // ---- stores / actions ----
 export { THEMES, theme } from './stores/theme.svelte';
 export { toasts, } from './stores/toast.svelte';
+export { AUTO_THEME, chooseTheme, DEFAULT_THEME_PREFERENCE, pickerValue, preferenceFrom, resolveTheme, } from './theme-mode';
 export { formatTimestamp, localTimeZone, relativeTime, } from './timestamp';
 export { canonicalTone } from './tone';
 export { pathCandidates, truncate } from './truncate';

package/dist/stores/theme.svelte.d.ts

@@ -1,3 +1,4 @@
+import { type SlotOf, type ThemeChoice, type ThemePreference } from '../theme-mode';
 export declare const THEMES: readonly [{
     readonly id: "light";
     readonly label: "Light";
@@ -155,16 +156,32 @@ export interface ThemeDef {
 }
 declare class Theme {
     current: ThemeId;
+    /** True while the system asks for a dark scheme; only read in `auto`. */
+    systemDark: boolean;
+    pref: ThemePreference;
+    /** Called with the new preference whenever the user changes it, so an app
+     *  can mirror it into its own (server-side) settings. */
+    onchange?: (pref: ThemePreference) => void;
     readonly fallbackIcon = "\u25C8";
     private registered;
     private fallback;
     private saved;
     constructor();
+    get slotOf(): SlotOf;
+    /** `auto`, or the pinned slot. */
+    get mode(): ThemeChoice;
+    /** The theme id painted for the current preference. */
+    get resolved(): ThemeId;
+    /** What a picker shows as selected: `auto`, or the pinned slot's theme id. */
+    get choice(): string;
     get all(): readonly ThemeDef[];
     has(id: string | null | undefined): id is ThemeId;
     register(defs: ThemeDef | ThemeDef[]): void;
     setDefault(id: ThemeId): void;
     private resolve;
+    private read;
+    private paint;
+    private persist;
     private apply;
     get option(): ThemeDef;
     get label(): string;
@@ -172,6 +189,12 @@ declare class Theme {
     get next(): ThemeDef;
     toggle(): void;
     set(mode: ThemeId): void;
+    /** A picker choice: `auto`, or a theme id, which also becomes its slot's
+     *  remembered theme. An unregistered id is ignored. */
+    choose(choice: string): ThemePreference;
+    /** Replay a preference an app persisted itself, without echoing it back
+     *  through `onchange`. */
+    hydrate(pref: ThemePreference): void;
 }
 export declare const theme: Theme;
 export {};

package/dist/stores/theme.svelte.js

@@ -1,10 +1,15 @@
 import { browser } from '../env';
+import { AUTO_THEME, chooseTheme, DEFAULT_THEME_PREFERENCE, preferenceFrom, resolveTheme, } from '../theme-mode';
 // Theme registry. Built-ins live in THEMES (+ one [data-theme="id"] block in
 // styles/themes.css); consumers append their own with theme.register() and ship
 // the matching block in their own stylesheet. `themeColor` drives the mobile
 // browser-chrome <meta theme-color>; `mode` groups the theme into the picker's
 // light/dark sections.
+//
+// `tsumikit-theme` holds a {mode,light,dark} blob; a bare theme id there is a
+// legacy value and migrates through `preferenceFrom`.
 const KEY = 'tsumikit-theme';
+const SCHEME_QUERY = '(prefers-color-scheme: dark)';
 export const THEMES = [
     // ── Light ── bright, paper-white surfaces
     { id: 'light', label: 'Light', icon: '☀', themeColor: '#f6f7f9', mode: 'light' },
@@ -55,16 +60,43 @@ export const THEMES = [
 const FALLBACK_ICON = '◈';
 class Theme {
     current = $state('dark');
+    /** True while the system asks for a dark scheme; only read in `auto`. */
+    systemDark = $state(false);
+    pref = $state(DEFAULT_THEME_PREFERENCE);
+    /** Called with the new preference whenever the user changes it, so an app
+     *  can mirror it into its own (server-side) settings. */
+    onchange;
     fallbackIcon = FALLBACK_ICON;
     registered = $state([]);
     fallback = 'dark';
     saved = null;
     constructor() {
         if (browser) {
+            const mq = typeof matchMedia === 'function' ? matchMedia(SCHEME_QUERY) : null;
+            this.systemDark = mq?.matches ?? false;
+            mq?.addEventListener?.('change', (e) => {
+                this.systemDark = e.matches;
+                this.paint();
+            });
             this.saved = localStorage.getItem(KEY);
             this.resolve();
         }
     }
+    get slotOf() {
+        return (id) => this.all.find((t) => t.id === id)?.mode ?? null;
+    }
+    /** `auto`, or the pinned slot. */
+    get mode() {
+        return this.pref.mode;
+    }
+    /** The theme id painted for the current preference. */
+    get resolved() {
+        return resolveTheme(this.pref, this.systemDark);
+    }
+    /** What a picker shows as selected: `auto`, or the pinned slot's theme id. */
+    get choice() {
+        return this.pref.mode === AUTO_THEME ? AUTO_THEME : this.resolved;
+    }
     get all() {
         const byId = new Map();
         for (const t of THEMES)
@@ -86,9 +118,38 @@ class Theme {
         this.resolve();
     }
     resolve() {
-        this.current = this.has(this.saved) ? this.saved : this.fallback;
+        this.pref = this.read();
+        this.paint();
+    }
+    read() {
+        const seed = chooseTheme(DEFAULT_THEME_PREFERENCE, this.fallback, this.slotOf);
+        if (!this.saved)
+            return seed;
+        let blob = null;
+        try {
+            const parsed = JSON.parse(this.saved);
+            if (parsed && typeof parsed === 'object')
+                blob = parsed;
+        }
+        catch { }
+        return preferenceFrom(blob
+            ? { themeMode: blob.mode, lightTheme: blob.light, darkTheme: blob.dark }
+            : { theme: this.saved }, this.slotOf, seed);
+    }
+    paint() {
+        this.current = this.resolved;
         this.apply();
     }
+    persist() {
+        this.saved = JSON.stringify(this.pref);
+        if (browser) {
+            try {
+                localStorage.setItem(KEY, this.saved);
+            }
+            catch { }
+        }
+        this.onchange?.(this.pref);
+    }
     apply() {
         if (!browser)
             return;
@@ -117,11 +178,22 @@ class Theme {
         this.set(this.next.id);
     }
     set(mode) {
-        this.saved = mode;
-        this.current = mode;
-        if (browser)
-            localStorage.setItem(KEY, mode);
-        this.apply();
+        this.choose(mode);
+    }
+    /** A picker choice: `auto`, or a theme id, which also becomes its slot's
+     *  remembered theme. An unregistered id is ignored. */
+    choose(choice) {
+        this.pref = chooseTheme(this.pref, choice, this.slotOf);
+        this.paint();
+        this.persist();
+        return this.pref;
+    }
+    /** Replay a preference an app persisted itself, without echoing it back
+     *  through `onchange`. */
+    hydrate(pref) {
+        this.pref = pref;
+        this.saved = JSON.stringify(pref);
+        this.paint();
     }
 }
 export const theme = new Theme();

package/dist/theme-mode.d.ts

@@ -0,0 +1,33 @@
+export type ThemeSlot = 'light' | 'dark';
+export type ThemeChoice = ThemeSlot | 'auto';
+export interface ThemePreference {
+    /** `auto` follows the system; `light` / `dark` pin the matching slot. */
+    mode: ThemeChoice;
+    /** Last light theme the user picked. */
+    light: string;
+    /** Last dark theme the user picked. */
+    dark: string;
+}
+/** The picker value that means "follow the system". Never a theme id. */
+export declare const AUTO_THEME = "auto";
+export declare const DEFAULT_THEME_PREFERENCE: ThemePreference;
+/** Which slot a theme id belongs to; `null` when the id is unknown. */
+export type SlotOf = (id: string) => ThemeSlot | null;
+/** The theme id to paint for a preference, given the system's current scheme. */
+export declare function resolveTheme(pref: ThemePreference, systemDark: boolean): string;
+/** Apply a picker choice: `auto` switches mode only; a theme id pins its slot
+ *  AND becomes that slot's remembered theme. Unknown ids leave the preference
+ *  untouched so a stale blob can never paint an unregistered theme. */
+export declare function chooseTheme(pref: ThemePreference, choice: string, slotOf: SlotOf): ThemePreference;
+/** Rebuild a preference from persisted fields. Older blobs only carried a
+ *  single `theme`: it seeds whichever slot it belongs to and pins that mode, so
+ *  nothing changes for a user who never touched the new picker. Unknown ids
+ *  fall back to `defaults` rather than being trusted. */
+export declare function preferenceFrom(raw: {
+    theme?: string | null;
+    themeMode?: string | null;
+    lightTheme?: string | null;
+    darkTheme?: string | null;
+}, slotOf: SlotOf, defaults?: ThemePreference): ThemePreference;
+/** The picker's current value: `auto`, or the pinned slot's theme id. */
+export declare function pickerValue(pref: ThemePreference): string;

package/dist/theme-mode.js

@@ -0,0 +1,45 @@
+// Pure logic behind the light/dark/auto theme preference: the last light and
+// the last dark theme the user picked, plus an `auto` mode that follows the
+// system's `prefers-color-scheme`. Rune-free so it unit-tests in isolation.
+/** The picker value that means "follow the system". Never a theme id. */
+export const AUTO_THEME = 'auto';
+export const DEFAULT_THEME_PREFERENCE = {
+    mode: 'dark',
+    light: 'light',
+    dark: 'dark',
+};
+/** The theme id to paint for a preference, given the system's current scheme. */
+export function resolveTheme(pref, systemDark) {
+    const slot = pref.mode === 'auto' ? (systemDark ? 'dark' : 'light') : pref.mode;
+    return slot === 'dark' ? pref.dark : pref.light;
+}
+/** Apply a picker choice: `auto` switches mode only; a theme id pins its slot
+ *  AND becomes that slot's remembered theme. Unknown ids leave the preference
+ *  untouched so a stale blob can never paint an unregistered theme. */
+export function chooseTheme(pref, choice, slotOf) {
+    if (choice === AUTO_THEME)
+        return { ...pref, mode: 'auto' };
+    const slot = slotOf(choice);
+    if (!slot)
+        return pref;
+    return { ...pref, mode: slot, [slot]: choice };
+}
+/** Rebuild a preference from persisted fields. Older blobs only carried a
+ *  single `theme`: it seeds whichever slot it belongs to and pins that mode, so
+ *  nothing changes for a user who never touched the new picker. Unknown ids
+ *  fall back to `defaults` rather than being trusted. */
+export function preferenceFrom(raw, slotOf, defaults = DEFAULT_THEME_PREFERENCE) {
+    const light = raw.lightTheme && slotOf(raw.lightTheme) === 'light' ? raw.lightTheme : defaults.light;
+    const dark = raw.darkTheme && slotOf(raw.darkTheme) === 'dark' ? raw.darkTheme : defaults.dark;
+    const pref = { mode: defaults.mode, light, dark };
+    if (raw.themeMode === 'auto' || raw.themeMode === 'light' || raw.themeMode === 'dark') {
+        return { ...pref, mode: raw.themeMode };
+    }
+    if (raw.theme)
+        return chooseTheme(pref, raw.theme, slotOf);
+    return pref;
+}
+/** The picker's current value: `auto`, or the pinned slot's theme id. */
+export function pickerValue(pref) {
+    return pref.mode === 'auto' ? AUTO_THEME : pref.mode === 'dark' ? pref.dark : pref.light;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Minimal, dependency-free Svelte 5 + pure-CSS UI kit. Token-driven atoms, molecules & layouts with theming out of the box.",
   "type": "module",
   "license": "MIT",