@fuzdev/fuz_ui 0.222.1 → 0.223.0

package/dist/ColorSchemeInput.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { color_schemes, type ColorScheme } from '@fuzdev/fuz_css/theme.ts';
+	import { color_schemes, type ColorSchemePreference } from '@fuzdev/fuz_css/theme.ts';
 	import type { OmitStrict } from '@fuzdev/fuz_util/types.ts';
 	import type { SvelteHTMLElements } from 'svelte/elements';
 
@@ -12,7 +12,7 @@
 		value = get_theme_state(),
 		...rest
 	}: OmitStrict<SvelteHTMLElements['menu'], 'title' | 'children' | 'onselect'> & {
-		value?: { color_scheme: ColorScheme };
+		value?: { color_scheme: ColorSchemePreference };
 	} = $props();
 </script>
 

package/dist/ColorSchemeInput.svelte.d.ts

@@ -1,9 +1,9 @@
-import { type ColorScheme } from '@fuzdev/fuz_css/theme.ts';
+import { type ColorSchemePreference } from '@fuzdev/fuz_css/theme.ts';
 import type { OmitStrict } from '@fuzdev/fuz_util/types.ts';
 import type { SvelteHTMLElements } from 'svelte/elements';
 type $$ComponentProps = OmitStrict<SvelteHTMLElements['menu'], 'title' | 'children' | 'onselect'> & {
     value?: {
-        color_scheme: ColorScheme;
+        color_scheme: ColorSchemePreference;
     };
 };
 declare const ColorSchemeInput: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/ColorSchemeInput.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ColorSchemeInput.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/ColorSchemeInput.svelte"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKzD,KAAK,gBAAgB,GAAI,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC,GAAG;IACpG,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,WAAW,CAAA;KAAE,CAAC;CACtC,CAAC;AAsBH,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"ColorSchemeInput.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/ColorSchemeInput.svelte"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAKzD,KAAK,gBAAgB,GAAI,UAAU,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC,GAAG;IACpG,KAAK,CAAC,EAAE;QAAE,YAAY,EAAE,qBAAqB,CAAA;KAAE,CAAC;CAChD,CAAC;AAsBH,QAAA,MAAM,gBAAgB,sDAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/ContextmenuEntry.svelte

@@ -63,11 +63,11 @@
 				contextmenu.select(entry);
 			}}
 >
-	<div class="content">
-		<div class="icon">
+	<div class="menuitem_content">
+		<div class="menuitem_icon">
 			<ContextmenuIcon {icon} />
 		</div>
-		<div class="title">{@render children()}</div>
+		<div class="menuitem_title">{@render children()}</div>
 		{#if pending}<PendingAnimation />{:else if error_message}⚠️{/if}
 	</div>
 </li>

package/dist/ContextmenuLinkEntry.svelte

@@ -88,15 +88,15 @@
 					contextmenu.select(entry);
 				}}
 	>
-		<div class="content">
-			<div class="icon">
+		<div class="menuitem_content">
+			<div class="menuitem_icon">
 				{#if icon}
 					<ContextmenuIcon {icon} />
 				{:else}
 					<Svg data={external ? icon_external_link : icon_link} />
 				{/if}
 			</div>
-			<div class="title">
+			<div class="menuitem_title">
 				<span class="text">
 					{#if children}{@render children()}{:else}{text}{/if}
 				</span>

package/dist/ContextmenuSubmenu.svelte

@@ -89,11 +89,11 @@
 		}}
 		aria-expanded={selected}
 	>
-		<div class="content">
-			<div class="icon">
+		<div class="menuitem_content">
+			<div class="menuitem_icon">
 				<ContextmenuIcon {icon} />
 			</div>
-			<div class="title">{@render children()}</div>
+			<div class="menuitem_title">{@render children()}</div>
 		</div>
 		<div class="chevron" aria-hidden="true"></div>
 	</div>

package/dist/ThemeRoot.svelte

@@ -3,10 +3,14 @@
 </script>
 
 <script lang="ts">
-	import { onMount, type Snippet } from 'svelte';
-	import { render_theme_style } from '@fuzdev/fuz_css/theme.ts';
+	import { onMount, untrack, type Snippet } from 'svelte';
+	import {
+		render_theme_style,
+		to_theme_stance,
+		type ResolvedTheme
+	} from '@fuzdev/fuz_css/theme.ts';
 	import type { Theme } from '@fuzdev/fuz_css/variable.ts';
-	import { DEFAULT_THEME } from '@fuzdev/fuz_css/themes.ts';
+	import { DEFAULT_THEME, default_themes } from '@fuzdev/fuz_css/themes.ts';
 	import { DEV } from 'esm-env';
 
 	import {
@@ -26,9 +30,11 @@
 		save_color_scheme = default_save_color_scheme,
 		load_theme = default_load_theme,
 		save_theme = default_save_theme,
+		themes = default_themes,
+		resolve_theme,
 		theme_fallback,
 		theme_state = new ThemeState({
-			theme: load_theme(theme_fallback),
+			theme: load_theme(themes, theme_fallback),
 			color_scheme: load_color_scheme()
 		}),
 		children
@@ -38,10 +44,29 @@
 		save_color_scheme?: typeof default_save_color_scheme;
 		load_theme?: typeof default_load_theme;
 		save_theme?: typeof default_save_theme;
+		/**
+		 * The app's theme registry. Themes in it persist by name, so a later load
+		 * takes the registry's current version.
+		 * @default default_themes
+		 */
+		themes?: Array<Theme>;
+		/**
+		 * Resolves a theme's derived data for rendering. Inject
+		 * `resolve_theme_stance` from `@fuzdev/fuz_css/theme_stance.ts` when the app
+		 * ships a single-scheme (stanced) theme, which renders its stance mirror
+		 * only through it. Construction throws when `themes` or `theme_fallback`
+		 * holds a stanced theme and this is absent.
+		 */
+		resolve_theme?: (theme: Theme) => ResolvedTheme;
+		/**
+		 * The theme used when storage holds none. When absent, `load_theme` falls
+		 * back to the first of `themes`, or `DEFAULT_THEME` when `themes` is empty.
+		 */
 		theme_fallback?: Theme | undefined;
 		/**
 		 * A reactive class containing the selected theme and color scheme.
-		 * Defaults to the first default theme.
+		 * Defaults to a `ThemeState` over `load_theme(themes, theme_fallback)` and
+		 * the saved color scheme.
 		 */
 		theme_state?: ThemeState;
 		children: Snippet<
@@ -69,14 +94,52 @@
 	 * @module
 	 */
 
+	// The app's own stanced themes fail loudly at construction without a resolver -
+	// they'd render without their mirror, the wrong appearance in one color scheme.
+	// The props are read once, like `theme_state`'s default.
+	untrack(() => {
+		if (!resolve_theme) {
+			for (const [theme, prop] of [
+				...themes.map((t) => [t, 'themes'] as const),
+				...(theme_fallback ? [[theme_fallback, 'theme_fallback'] as const] : [])
+			]) {
+				const stance = to_theme_stance(theme.scheme);
+				if (stance !== null) {
+					throw Error(
+						`ThemeRoot: the theme "${theme.name}" in \`${prop}\` has the "${stance}" scheme stance` +
+							' and no `resolve_theme` is injected - pass `resolve_theme={resolve_theme_stance}`' +
+							' from `@fuzdev/fuz_css/theme_stance.ts`'
+					);
+				}
+			}
+		}
+	});
+
 	theme_state_context.set(() => theme_state);
 
-	const selected_theme_name = $derived(theme_state.theme.name);
-	const style = $derived(
-		selected_theme_name === DEFAULT_THEME.name // TODO @many proper equality check, won't work when we allow editing, need an id or unique names and a deep equality check
-			? null
-			: render_theme_style(theme_state.theme)
-	);
+	let logged_unresolved = false;
+
+	const style = $derived.by(() => {
+		const { theme } = theme_state;
+		// the bundled CSS already renders the default theme, compared by reference
+		// because a custom theme may share its name
+		if (theme === DEFAULT_THEME) return null;
+		if (resolve_theme) {
+			const resolved = resolve_theme(theme);
+			return render_theme_style(resolved.theme, resolved) || null;
+		}
+		// a stanced theme the app didn't ship, like a custom one restored from
+		// storage, renders without its mirror rather than throwing on saved data
+		if (!logged_unresolved && to_theme_stance(theme.scheme) !== null) {
+			logged_unresolved = true;
+			// eslint-disable-next-line no-console -- a lost mirror is a bug the app should see
+			console.error(
+				`ThemeRoot: the theme "${theme.name}" has a scheme stance and no \`resolve_theme\`` +
+					' is injected, so it renders without its stance mirror'
+			);
+		}
+		return render_theme_style(theme) || null;
+	});
 	const theme_style_html = $derived(style ? `<style>${style}</style>` : null);
 
 	effect_with_count((count) => {
@@ -92,7 +155,11 @@
 	effect_with_count((count) => {
 		const v = theme_state.theme;
 		if (count === 1) return;
-		save_theme(v);
+		// a new `themes` array alone doesn't re-save an unchanged theme
+		save_theme(
+			v,
+			untrack(() => themes)
+		);
 	});
 
 	// TODO @many @html making me nervous

package/dist/ThemeRoot.svelte.d.ts

@@ -1,4 +1,5 @@
 import { type Snippet } from 'svelte';
+import { type ResolvedTheme } from '@fuzdev/fuz_css/theme.ts';
 import type { Theme } from '@fuzdev/fuz_css/variable.ts';
 import { load_color_scheme as default_load_color_scheme, save_color_scheme as default_save_color_scheme, sync_color_scheme as default_sync_color_scheme, save_theme as default_save_theme, load_theme as default_load_theme, ThemeState } from './theme_state.svelte.js';
 type $$ComponentProps = {
@@ -7,10 +8,29 @@ type $$ComponentProps = {
     save_color_scheme?: typeof default_save_color_scheme;
     load_theme?: typeof default_load_theme;
     save_theme?: typeof default_save_theme;
+    /**
+     * The app's theme registry. Themes in it persist by name, so a later load
+     * takes the registry's current version.
+     * @default default_themes
+     */
+    themes?: Array<Theme>;
+    /**
+     * Resolves a theme's derived data for rendering. Inject
+     * `resolve_theme_stance` from `@fuzdev/fuz_css/theme_stance.ts` when the app
+     * ships a single-scheme (stanced) theme, which renders its stance mirror
+     * only through it. Construction throws when `themes` or `theme_fallback`
+     * holds a stanced theme and this is absent.
+     */
+    resolve_theme?: (theme: Theme) => ResolvedTheme;
+    /**
+     * The theme used when storage holds none. When absent, `load_theme` falls
+     * back to the first of `themes`, or `DEFAULT_THEME` when `themes` is empty.
+     */
     theme_fallback?: Theme | undefined;
     /**
      * A reactive class containing the selected theme and color scheme.
-     * Defaults to the first default theme.
+     * Defaults to a `ThemeState` over `load_theme(themes, theme_fallback)` and
+     * the saved color scheme.
      */
     theme_state?: ThemeState;
     children: Snippet<[

package/dist/ThemeRoot.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ThemeRoot.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/ThemeRoot.svelte"],"names":[],"mappings":"AAMA,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAIzD,OAAO,EACL,iBAAiB,IAAI,yBAAyB,EAC9C,iBAAiB,IAAI,yBAAyB,EAC9C,iBAAiB,IAAI,yBAAyB,EAC9C,UAAU,IAAI,kBAAkB,EAChC,UAAU,IAAI,kBAAkB,EAEhC,UAAU,EACV,MAAM,yBAAyB,CAAC;AAGjC,KAAK,gBAAgB,GAAI;IACxB,iBAAiB,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,iBAAiB,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,iBAAiB,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,UAAU,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACvC,cAAc,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC;;;OAGG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,QAAQ,EAAE,OAAO,CAChB;QAAC,WAAW,EAAE,UAAU;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI;QAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;KAAC,CAChF,CAAC;CACF,CAAC;AAqFH,QAAA,MAAM,SAAS,sDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}
+{"version":3,"file":"ThemeRoot.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/ThemeRoot.svelte"],"names":[],"mappings":"AAMA,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AACxD,OAAO,EAGL,KAAK,aAAa,EAClB,MAAM,0BAA0B,CAAC;AACnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAIzD,OAAO,EACL,iBAAiB,IAAI,yBAAyB,EAC9C,iBAAiB,IAAI,yBAAyB,EAC9C,iBAAiB,IAAI,yBAAyB,EAC9C,UAAU,IAAI,kBAAkB,EAChC,UAAU,IAAI,kBAAkB,EAEhC,UAAU,EACV,MAAM,yBAAyB,CAAC;AAGjC,KAAK,gBAAgB,GAAI;IACxB,iBAAiB,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,iBAAiB,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,iBAAiB,CAAC,EAAE,OAAO,yBAAyB,CAAC;IACrD,UAAU,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACvC,UAAU,CAAC,EAAE,OAAO,kBAAkB,CAAC;IACvC;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC;IACtB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,aAAa,CAAC;IAChD;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,QAAQ,EAAE,OAAO,CAChB;QAAC,WAAW,EAAE,UAAU;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI;QAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI;KAAC,CAChF,CAAC;CACF,CAAC;AAiIH,QAAA,MAAM,SAAS,sDAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/declaration.svelte.d.ts

@@ -99,8 +99,8 @@ export declare class Declaration {
     get external_types(): Array<string> | undefined;
     /**
      * Whether the exported name also carries a value meaning — a merged
-     * value+type symbol like `const Foo = z.strictObject({...})` beside
-     * `type Foo = z.infer<typeof Foo>`, where the type wins the declaration slot.
+     * value+type symbol like `const Foo = object({...})` beside
+     * `type Foo = Infer<typeof Foo>`, where the type wins the declaration slot.
      * Present on `type` and `interface` kinds.
      */
     get merged_value(): boolean | undefined;

package/dist/declaration.svelte.js

@@ -186,8 +186,8 @@ export class Declaration {
     }
     /**
      * Whether the exported name also carries a value meaning — a merged
-     * value+type symbol like `const Foo = z.strictObject({...})` beside
-     * `type Foo = z.infer<typeof Foo>`, where the type wins the declaration slot.
+     * value+type symbol like `const Foo = object({...})` beside
+     * `type Foo = Infer<typeof Foo>`, where the type wins the declaration slot.
      * Present on `type` and `interface` kinds.
      */
     get merged_value() {

package/dist/projects.js

@@ -11,7 +11,7 @@ export const project_items = [
     { name: 'fuz_template', url: 'https://template.fuz.dev/', logo: logo_fuz_template, description: 'starter template for SvelteKit web apps, Rust native tools, or both', glyph: '❄', color_class: 'color_h_50' },
     { name: 'fuz_blog', url: 'https://blog.fuz.dev/', logo: logo_fuz_blog, description: 'blog software from scratch with SvelteKit', glyph: '🖊️', color_class: 'color_e_50' },
     { name: 'fuz_code', url: 'https://code.fuz.dev/', logo: logo_fuz_code, description: 'syntax styling utilities and components for TypeScript, Svelte, Markdown, and more', glyph: '🎨', color_class: 'color_g_50' },
-    { name: 'mdz', url: 'https://mdz.fuz.dev/', logo: logo_mdz, description: 'a strict markdown dialect built for streaming, Svelte authoring, docs websites, and untrusted content', glyph: '📝', color_class: 'color_d_50' },
+    { name: 'mdz', url: 'https://mdz.fuz.dev/', logo: logo_mdz, description: 'a strict markdown dialect built for streaming, web authoring, docs, and untrusted content', glyph: '📝', color_class: 'color_d_50' },
     { name: 'fuz_repos', url: 'https://repos.fuz.dev/', logo: logo_fuz_repos, description: 'a tool for managing many repos', glyph: '🪄', color_class: 'color_a_50' },
     { name: 'svelte-docinfo', url: 'https://svelte-docinfo.fuz.dev/', logo: logo_svelte_docinfo, description: 'static analysis for TypeScript and Svelte', glyph: '📜', color_class: 'color_i_50' },
     { name: 'fuz_util', url: 'https://util.fuz.dev/', logo: logo_fuz_util, description: 'utility belt for JS', glyph: '🦕', color_class: 'color_f_50' },

package/dist/theme_state.svelte.d.ts

@@ -1,13 +1,13 @@
-import { type ColorScheme } from '@fuzdev/fuz_css/theme.ts';
+import { type ColorSchemePreference } from '@fuzdev/fuz_css/theme.ts';
 import { type Theme } from '@fuzdev/fuz_css/variable.ts';
 export interface ThemeStateJson {
     theme: Theme;
-    color_scheme: ColorScheme;
+    color_scheme: ColorSchemePreference;
 }
 export type ThemeStateOptions = Partial<ThemeStateJson>;
 export declare class ThemeState {
     theme: Theme;
-    color_scheme: ColorScheme;
+    color_scheme: ColorSchemePreference;
     constructor(options?: ThemeStateOptions);
     toJSON(): ThemeStateJson;
 }
@@ -16,11 +16,49 @@ export declare const theme_state_context: {
     get_maybe: () => (() => ThemeState) | undefined;
     set: (value: () => ThemeState) => () => ThemeState;
 };
-export declare const sync_color_scheme: (color_scheme: ColorScheme | null) => void;
+export declare const sync_color_scheme: (color_scheme: ColorSchemePreference | null) => void;
 export declare const COLOR_SCHEME_STORAGE_KEY = "fuz:color-scheme";
 export declare const THEME_STORAGE_KEY = "fuz:theme";
-export declare const save_color_scheme: (color_scheme: ColorScheme | null, key?: string) => void;
-export declare const load_color_scheme: (fallback?: ColorScheme, key?: string) => ColorScheme;
-export declare const save_theme: (theme: Theme | null, key?: string) => void;
-export declare const load_theme: (fallback?: Theme, key?: string) => Theme;
+export declare const save_color_scheme: (color_scheme: ColorSchemePreference | null, key?: string) => void;
+export declare const load_color_scheme: (fallback?: ColorSchemePreference, key?: string) => ColorSchemePreference;
+/**
+ * Saves a theme to storage: a theme in the `themes` registry by its name, a
+ * registry theme composed with a contrast modifier as `{name, contrast}`, and
+ * any other theme whole, trimmed to its authored fields (`name`, `summary`,
+ * `scheme`, `variables`). Saving by reference means a later load takes the
+ * registry's current version, recomposed. Both matches are by name, so a theme
+ * sharing a registry theme's name saves as that registry theme, and one named
+ * like a composition (`ledger (high contrast)`) saves as that composition.
+ *
+ * A composition assigned at runtime, like `theme_state.theme =
+ * compose_themes(ledger_theme, contrast_modifiers.high)`, takes the
+ * `{name, contrast}` path.
+ *
+ * @param theme - the theme to save, or `null` to remove the saved one
+ * @param themes - the app's theme registry
+ * @param key - the storage key
+ */
+export declare const save_theme: (theme: Theme | null, themes?: Array<Theme>, key?: string) => void;
+/**
+ * Loads the saved theme from storage, falling back when there's none or it
+ * doesn't resolve to a theme. A saved name loads the registry theme of that
+ * name, `{name, contrast}` the registry theme composed with that contrast
+ * modifier, an object named like a registry theme the registry theme (so a
+ * whole-object save from before themes saved by name loads the current
+ * version), and any other object its authored fields when they parse as a
+ * `Theme`.
+ *
+ * @param themes - the app's theme registry
+ * @param fallback - the theme to use when storage holds none
+ * @param key - the storage key
+ */
+export declare const load_theme: (themes?: Array<Theme>, fallback?: Theme, key?: string) => Theme;
+/**
+ * Resolves a value from storage to a theme, the parsing half of `load_theme`.
+ *
+ * @param value - the stored value, parsed from JSON
+ * @param themes - the app's theme registry
+ * @returns the theme, or `null` when the value doesn't resolve to one
+ */
+export declare const parse_saved_theme: (value: unknown, themes: Array<Theme>) => Theme | null;
 //# sourceMappingURL=theme_state.svelte.d.ts.map

package/dist/theme_state.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/theme_state.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAOtE,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,WAAW,CAAC;CAC1B;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAExD,qBAAa,UAAU;IACtB,KAAK,EAAE,KAAK,CAAiB;IAC7B,YAAY,EAAE,WAAW,CAAiB;gBAE9B,OAAO,CAAC,EAAE,iBAAiB;IAUvC,MAAM,IAAI,cAAc;CAMxB;AACD,eAAO,MAAM,mBAAmB;2CAAwB,UAAU;4BAAV,UAAU;uBAAV,UAAU,WAAV,UAAU;CAAG,CAAC;AAEtE,eAAO,MAAM,iBAAiB,GAAI,cAAc,WAAW,GAAG,IAAI,KAAG,IAOpE,CAAC;AAEF,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,eAAO,MAAM,iBAAiB,GAC7B,cAAc,WAAW,GAAG,IAAI,EAChC,YAA8B,KAC5B,IAEF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC7B,WAAU,WAAoB,EAC9B,YAA8B,KAC5B,WAA4E,CAAC;AAEhF,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,GAAG,IAAI,EAAE,YAAuB,KAAG,IAEzE,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,WAAU,KAA0B,EAAE,YAAuB,KAAG,KACrC,CAAC"}
+{"version":3,"file":"theme_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/theme_state.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,KAAK,qBAAqB,EAC1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAYtE,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,YAAY,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;AAExD,qBAAa,UAAU;IACtB,KAAK,EAAE,KAAK,CAAiB;IAC7B,YAAY,EAAE,qBAAqB,CAAiB;gBAExC,OAAO,CAAC,EAAE,iBAAiB;IAUvC,MAAM,IAAI,cAAc;CAMxB;AACD,eAAO,MAAM,mBAAmB;2CAAwB,UAAU;4BAAV,UAAU;uBAAV,UAAU,WAAV,UAAU;CAAG,CAAC;AAEtE,eAAO,MAAM,iBAAiB,GAAI,cAAc,qBAAqB,GAAG,IAAI,KAAG,IAO9E,CAAC;AAEF,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAC3D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,eAAO,MAAM,iBAAiB,GAC7B,cAAc,qBAAqB,GAAG,IAAI,EAC1C,YAA8B,KAC5B,IAEF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC7B,WAAU,qBAA8B,EACxC,YAA8B,KAC5B,qBAAsF,CAAC;AAE1F;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,GACtB,OAAO,KAAK,GAAG,IAAI,EACnB,SAAQ,KAAK,CAAC,KAAK,CAAkB,EACrC,YAAuB,KACrB,IAEF,CAAC;AA2BF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,GACtB,SAAQ,KAAK,CAAC,KAAK,CAAkB,EACrC,WAAU,KAAkC,EAC5C,YAAuB,KACrB,KAA8F,CAAC;AAElG;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,EAAE,QAAQ,KAAK,CAAC,KAAK,CAAC,KAAG,KAAK,GAAG,IAahF,CAAC"}

package/dist/theme_state.svelte.js

@@ -1,6 +1,6 @@
-import { color_schemes } from '@fuzdev/fuz_css/theme.ts';
+import { color_schemes, compose_themes } from '@fuzdev/fuz_css/theme.ts';
 import { parse_theme } from '@fuzdev/fuz_css/variable.ts';
-import { default_themes } from '@fuzdev/fuz_css/themes.ts';
+import { contrast_modifiers, default_themes, DEFAULT_THEME } from '@fuzdev/fuz_css/themes.ts';
 import { BROWSER } from 'esm-env';
 import { create_context } from './context_helpers.js';
 import { load_from_storage, save_to_storage } from './storage.js';
@@ -38,9 +38,91 @@ export const save_color_scheme = (color_scheme, key = COLOR_SCHEME_STORAGE_KEY)
     save_to_storage(key, color_scheme);
 };
 export const load_color_scheme = (fallback = 'auto', key = COLOR_SCHEME_STORAGE_KEY) => load_from_storage(key, false, parse_color_scheme) ?? fallback;
-export const save_theme = (theme, key = THEME_STORAGE_KEY) => {
-    save_to_storage(key, theme, true);
+/**
+ * Saves a theme to storage: a theme in the `themes` registry by its name, a
+ * registry theme composed with a contrast modifier as `{name, contrast}`, and
+ * any other theme whole, trimmed to its authored fields (`name`, `summary`,
+ * `scheme`, `variables`). Saving by reference means a later load takes the
+ * registry's current version, recomposed. Both matches are by name, so a theme
+ * sharing a registry theme's name saves as that registry theme, and one named
+ * like a composition (`ledger (high contrast)`) saves as that composition.
+ *
+ * A composition assigned at runtime, like `theme_state.theme =
+ * compose_themes(ledger_theme, contrast_modifiers.high)`, takes the
+ * `{name, contrast}` path.
+ *
+ * @param theme - the theme to save, or `null` to remove the saved one
+ * @param themes - the app's theme registry
+ * @param key - the storage key
+ */
+export const save_theme = (theme, themes = default_themes, key = THEME_STORAGE_KEY) => {
+    save_to_storage(key, theme === null ? null : to_saved_theme(theme, themes), true);
+};
+const CONTRASTS = ['low', 'high'];
+/**
+ * The value `save_theme` stores for a non-null theme.
+ */
+const to_saved_theme = (theme, themes) => {
+    if (themes.some((t) => t.name === theme.name))
+        return theme.name;
+    // recomposing keeps the naming rule in `compose_themes`, and costs one
+    // composition per registry theme and modifier, only when saving
+    for (const t of themes) {
+        for (const contrast of CONTRASTS) {
+            if (compose_themes(t, contrast_modifiers[contrast]).name === theme.name) {
+                return { name: t.name, contrast };
+            }
+        }
+    }
+    return trim_theme(theme);
+};
+/**
+ * Loads the saved theme from storage, falling back when there's none or it
+ * doesn't resolve to a theme. A saved name loads the registry theme of that
+ * name, `{name, contrast}` the registry theme composed with that contrast
+ * modifier, an object named like a registry theme the registry theme (so a
+ * whole-object save from before themes saved by name loads the current
+ * version), and any other object its authored fields when they parse as a
+ * `Theme`.
+ *
+ * @param themes - the app's theme registry
+ * @param fallback - the theme to use when storage holds none
+ * @param key - the storage key
+ */
+export const load_theme = (themes = default_themes, fallback = themes[0] ?? DEFAULT_THEME, key = THEME_STORAGE_KEY) => load_from_storage(key, true, (value) => parse_saved_theme(value, themes)) ?? fallback;
+/**
+ * Resolves a value from storage to a theme, the parsing half of `load_theme`.
+ *
+ * @param value - the stored value, parsed from JSON
+ * @param themes - the app's theme registry
+ * @returns the theme, or `null` when the value doesn't resolve to one
+ */
+export const parse_saved_theme = (value, themes) => {
+    if (typeof value === 'string') {
+        return themes.find((t) => t.name === value) ?? null;
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const { name, contrast } = value;
+    const registry_theme = typeof name === 'string' ? themes.find((t) => t.name === name) : undefined;
+    if (registry_theme) {
+        return contrast === 'low' || contrast === 'high'
+            ? compose_themes(registry_theme, contrast_modifiers[contrast])
+            : registry_theme;
+    }
+    return parse_theme(trim_theme(value));
+};
+/**
+ * Copies a theme's authored fields, dropping anything else it carries.
+ */
+const trim_theme = (theme) => {
+    const trimmed = { name: theme.name };
+    if (theme.summary !== undefined)
+        trimmed.summary = theme.summary;
+    if (theme.scheme !== undefined)
+        trimmed.scheme = theme.scheme;
+    trimmed.variables = theme.variables;
+    return trimmed;
 };
-export const load_theme = (fallback = default_themes[0], key = THEME_STORAGE_KEY) => load_from_storage(key, true, parse_theme) ?? fallback;
 // TODO move to fuz_css
 const parse_color_scheme = (value) => color_schemes.includes(value) ? value : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_ui",
-  "version": "0.222.1",
+  "version": "0.223.0",
   "description": "Svelte component library and frontend helpers",
   "tagline": "friendly user zystem",
   "glyph": "🧶",
@@ -38,7 +38,7 @@
   },
   "peerDependencies": {
     "@fuzdev/fuz_code": ">=0.56.0",
-    "@fuzdev/fuz_css": ">=0.72.0",
+    "@fuzdev/fuz_css": ">=0.74.0",
     "@fuzdev/fuz_util": ">=0.79.0",
     "@fuzdev/gro": ">=0.223.0",
     "@fuzdev/mdz": ">=0.7.0",
@@ -64,7 +64,7 @@
     "@changesets/changelog-git": "^0.2.1",
     "@fuzdev/blake3-wasm": "^0.2.0",
     "@fuzdev/fuz_code": "^0.56.0",
-    "@fuzdev/fuz_css": "^0.72.0",
+    "@fuzdev/fuz_css": "^0.74.0",
     "@fuzdev/fuz_schema": "^0.5.0",
     "@fuzdev/fuz_util": "^0.79.0",
     "@fuzdev/gro": "^0.224.0",

package/src/lib/declaration.svelte.ts

@@ -244,8 +244,8 @@ export class Declaration {
 
 	/**
 	 * Whether the exported name also carries a value meaning — a merged
-	 * value+type symbol like `const Foo = z.strictObject({...})` beside
-	 * `type Foo = z.infer<typeof Foo>`, where the type wins the declaration slot.
+	 * value+type symbol like `const Foo = object({...})` beside
+	 * `type Foo = Infer<typeof Foo>`, where the type wins the declaration slot.
 	 * Present on `type` and `interface` kinds.
 	 */
 	get merged_value(): boolean | undefined {

package/src/lib/projects.ts

@@ -37,7 +37,7 @@ export const project_items: Array<ProjectItem> = [
 	{name: 'fuz_template', url: 'https://template.fuz.dev/', logo: logo_fuz_template, description: 'starter template for SvelteKit web apps, Rust native tools, or both', glyph: '❄', color_class: 'color_h_50'},
 	{name: 'fuz_blog', url: 'https://blog.fuz.dev/', logo: logo_fuz_blog, description: 'blog software from scratch with SvelteKit', glyph: '🖊️', color_class: 'color_e_50'},
 	{name: 'fuz_code', url: 'https://code.fuz.dev/', logo: logo_fuz_code, description: 'syntax styling utilities and components for TypeScript, Svelte, Markdown, and more', glyph: '🎨', color_class: 'color_g_50'},
-	{name: 'mdz', url: 'https://mdz.fuz.dev/', logo: logo_mdz, description: 'a strict markdown dialect built for streaming, Svelte authoring, docs websites, and untrusted content', glyph: '📝', color_class: 'color_d_50'},
+	{name: 'mdz', url: 'https://mdz.fuz.dev/', logo: logo_mdz, description: 'a strict markdown dialect built for streaming, web authoring, docs, and untrusted content', glyph: '📝', color_class: 'color_d_50'},
 	{name: 'fuz_repos', url: 'https://repos.fuz.dev/', logo: logo_fuz_repos, description: 'a tool for managing many repos', glyph: '🪄', color_class: 'color_a_50'},
 	{name: 'svelte-docinfo', url: 'https://svelte-docinfo.fuz.dev/', logo: logo_svelte_docinfo, description: 'static analysis for TypeScript and Svelte', glyph: '📜', color_class: 'color_i_50'},
 	{name: 'fuz_util', url: 'https://util.fuz.dev/', logo: logo_fuz_util, description: 'utility belt for JS', glyph: '🦕', color_class: 'color_f_50'},

package/src/lib/theme_state.svelte.ts

@@ -1,6 +1,15 @@
-import { color_schemes, type ColorScheme } from '@fuzdev/fuz_css/theme.ts';
+import {
+	color_schemes,
+	compose_themes,
+	type ColorSchemePreference
+} from '@fuzdev/fuz_css/theme.ts';
 import { parse_theme, type Theme } from '@fuzdev/fuz_css/variable.ts';
-import { default_themes } from '@fuzdev/fuz_css/themes.ts';
+import {
+	contrast_modifiers,
+	default_themes,
+	DEFAULT_THEME,
+	type ContrastModifiers
+} from '@fuzdev/fuz_css/themes.ts';
 import { BROWSER } from 'esm-env';
 
 import { create_context } from './context_helpers.ts';
@@ -8,14 +17,14 @@ import { load_from_storage, save_to_storage } from './storage.ts';
 
 export interface ThemeStateJson {
 	theme: Theme;
-	color_scheme: ColorScheme;
+	color_scheme: ColorSchemePreference;
 }
 
 export type ThemeStateOptions = Partial<ThemeStateJson>;
 
 export class ThemeState {
 	theme: Theme = $state.raw()!;
-	color_scheme: ColorScheme = $state.raw()!;
+	color_scheme: ColorSchemePreference = $state.raw()!;
 
 	constructor(options?: ThemeStateOptions) {
 		const theme = options?.theme ?? default_themes[0]!;
@@ -36,7 +45,7 @@ export class ThemeState {
 }
 export const theme_state_context = create_context<() => ThemeState>();
 
-export const sync_color_scheme = (color_scheme: ColorScheme | null): void => {
+export const sync_color_scheme = (color_scheme: ColorSchemePreference | null): void => {
 	if (!BROWSER) return;
 	const dark =
 		color_scheme === 'dark' ||
@@ -49,24 +58,119 @@ export const COLOR_SCHEME_STORAGE_KEY = 'fuz:color-scheme';
 export const THEME_STORAGE_KEY = 'fuz:theme';
 
 export const save_color_scheme = (
-	color_scheme: ColorScheme | null,
+	color_scheme: ColorSchemePreference | null,
 	key = COLOR_SCHEME_STORAGE_KEY
 ): void => {
 	save_to_storage(key, color_scheme);
 };
 
 export const load_color_scheme = (
-	fallback: ColorScheme = 'auto',
+	fallback: ColorSchemePreference = 'auto',
 	key = COLOR_SCHEME_STORAGE_KEY
-): ColorScheme => load_from_storage(key, false, parse_color_scheme) ?? fallback;
+): ColorSchemePreference => load_from_storage(key, false, parse_color_scheme) ?? fallback;
 
-export const save_theme = (theme: Theme | null, key = THEME_STORAGE_KEY): void => {
-	save_to_storage(key, theme, true);
+/**
+ * Saves a theme to storage: a theme in the `themes` registry by its name, a
+ * registry theme composed with a contrast modifier as `{name, contrast}`, and
+ * any other theme whole, trimmed to its authored fields (`name`, `summary`,
+ * `scheme`, `variables`). Saving by reference means a later load takes the
+ * registry's current version, recomposed. Both matches are by name, so a theme
+ * sharing a registry theme's name saves as that registry theme, and one named
+ * like a composition (`ledger (high contrast)`) saves as that composition.
+ *
+ * A composition assigned at runtime, like `theme_state.theme =
+ * compose_themes(ledger_theme, contrast_modifiers.high)`, takes the
+ * `{name, contrast}` path.
+ *
+ * @param theme - the theme to save, or `null` to remove the saved one
+ * @param themes - the app's theme registry
+ * @param key - the storage key
+ */
+export const save_theme = (
+	theme: Theme | null,
+	themes: Array<Theme> = default_themes,
+	key = THEME_STORAGE_KEY
+): void => {
+	save_to_storage(key, theme === null ? null : to_saved_theme(theme, themes), true);
 };
 
-export const load_theme = (fallback: Theme = default_themes[0]!, key = THEME_STORAGE_KEY): Theme =>
-	load_from_storage(key, true, parse_theme) ?? fallback;
+const CONTRASTS = ['low', 'high'] as const satisfies ReadonlyArray<keyof ContrastModifiers>;
+
+/**
+ * The value `save_theme` stores for a non-null theme.
+ */
+const to_saved_theme = (theme: Theme, themes: Array<Theme>): SavedTheme => {
+	if (themes.some((t) => t.name === theme.name)) return theme.name;
+	// recomposing keeps the naming rule in `compose_themes`, and costs one
+	// composition per registry theme and modifier, only when saving
+	for (const t of themes) {
+		for (const contrast of CONTRASTS) {
+			if (compose_themes(t, contrast_modifiers[contrast]).name === theme.name) {
+				return { name: t.name, contrast };
+			}
+		}
+	}
+	return trim_theme(theme);
+};
+
+/**
+ * A theme as `save_theme` stores it: a registry theme's name, a registry
+ * theme's name with a contrast modifier, or a whole trimmed theme.
+ */
+type SavedTheme = string | { name: string; contrast: keyof ContrastModifiers } | Theme;
+
+/**
+ * Loads the saved theme from storage, falling back when there's none or it
+ * doesn't resolve to a theme. A saved name loads the registry theme of that
+ * name, `{name, contrast}` the registry theme composed with that contrast
+ * modifier, an object named like a registry theme the registry theme (so a
+ * whole-object save from before themes saved by name loads the current
+ * version), and any other object its authored fields when they parse as a
+ * `Theme`.
+ *
+ * @param themes - the app's theme registry
+ * @param fallback - the theme to use when storage holds none
+ * @param key - the storage key
+ */
+export const load_theme = (
+	themes: Array<Theme> = default_themes,
+	fallback: Theme = themes[0] ?? DEFAULT_THEME,
+	key = THEME_STORAGE_KEY
+): Theme => load_from_storage(key, true, (value) => parse_saved_theme(value, themes)) ?? fallback;
+
+/**
+ * Resolves a value from storage to a theme, the parsing half of `load_theme`.
+ *
+ * @param value - the stored value, parsed from JSON
+ * @param themes - the app's theme registry
+ * @returns the theme, or `null` when the value doesn't resolve to one
+ */
+export const parse_saved_theme = (value: unknown, themes: Array<Theme>): Theme | null => {
+	if (typeof value === 'string') {
+		return themes.find((t) => t.name === value) ?? null;
+	}
+	if (typeof value !== 'object' || value === null || Array.isArray(value)) return null;
+	const { name, contrast } = value as Record<string, unknown>;
+	const registry_theme = typeof name === 'string' ? themes.find((t) => t.name === name) : undefined;
+	if (registry_theme) {
+		return contrast === 'low' || contrast === 'high'
+			? compose_themes(registry_theme, contrast_modifiers[contrast])
+			: registry_theme;
+	}
+	return parse_theme(trim_theme(value as Theme));
+};
+
+/**
+ * Copies a theme's authored fields, dropping anything else it carries.
+ */
+const trim_theme = (theme: Theme): Theme => {
+	const trimmed: Record<string, unknown> = { name: theme.name };
+	if (theme.summary !== undefined) trimmed.summary = theme.summary;
+	if (theme.scheme !== undefined) trimmed.scheme = theme.scheme;
+	trimmed.variables = theme.variables;
+	return trimmed as Theme;
+};
 
 // TODO move to fuz_css
-const parse_color_scheme = (value: unknown): ColorScheme | null =>
-	color_schemes.includes(value as any) ? (value as ColorScheme) : null;
+const parse_color_scheme = (value: unknown): ColorSchemePreference | null =>
+	color_schemes.includes(value as any) ? (value as ColorSchemePreference) : null;