@dorsk/tsumikit 0.46.0 → 0.47.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/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/index.d.ts

@@ -90,6 +90,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

@@ -101,6 +101,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.47.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",