@sveltier/ui 0.0.0-stage → 0.1.0-alpha.1

package/dist/core/locale/locale.d.ts

@@ -0,0 +1,56 @@
+/** Built-in English messages: the labels and announcements of components. */
+export declare const MESSAGES: {
+    close: string;
+    loading: string;
+    notifications: string;
+    progress: string;
+    required: string;
+    tooShort: string;
+    tooLong: string;
+    typeEmail: string;
+    typeUrl: string;
+    patternMismatch: string;
+    badInput: string;
+    rangeUnderflow: string;
+    rangeOverflow: string;
+    stepMismatch: string;
+    increase: string;
+    decrease: string;
+};
+export type MessageKey = keyof typeof MESSAGES;
+export type Messages = Record<MessageKey, string>;
+export interface LocaleOptions {
+    /** BCP 47 locale used for formatting, for example "en-GB". Defaults to "en-US". */
+    locale?: string;
+    /** ISO 4217 currency of formatCurrency(), for example "EUR". Defaults to "USD". */
+    currency?: string;
+    /** IANA time zone of formatDate(), for example "Europe/London". Defaults to the runtime's. */
+    timeZone?: string;
+    /** A translation, or single messages merged over the English ones. */
+    messages?: Partial<Messages>;
+}
+/** Messages and formatting, as seen by `useLocale()`. Settings are reactive. */
+export interface LocaleInstance {
+    readonly locale: string;
+    readonly currency: string;
+    readonly timeZone: string | undefined;
+    /** The message `key`, with `{name}` placeholders replaced from `values`. */
+    t(key: MessageKey, values?: Record<string, string | number>): string;
+    formatNumber(value: number | bigint, options?: Intl.NumberFormatOptions): string;
+    /** Money in `currency` (default: the locale setting). Fraction digits follow the currency. */
+    formatCurrency(value: number | bigint, currency?: string, options?: Intl.NumberFormatOptions): string;
+    /** A ratio as a percentage: 0.0184 is "2%", or "1.84%" with minimumFractionDigits: 2. */
+    formatPercent(value: number, options?: Intl.NumberFormatOptions): string;
+    formatDate(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+    /** Time from `now` in the largest unit that fits: "5 minutes ago", "tomorrow". */
+    formatRelative(value: Date | number, now?: Date | number): string;
+}
+/** Builds a locale whose settings are read through `options` on every call. */
+export declare function createLocale(options: () => LocaleOptions): LocaleInstance;
+/** Gives a subtree its locale, built from the root's options. */
+export declare const setLocaleContext: (locale: LocaleInstance) => LocaleInstance;
+/**
+ * Returns messages and formatters for the current locale. Call it during component
+ * initialisation. Without a provider it returns one shared instance with the defaults.
+ */
+export declare function useLocale(): LocaleInstance;

package/dist/core/locale/locale.js

@@ -0,0 +1,82 @@
+import { getContext, hasContext, setContext } from 'svelte';
+/** Built-in English messages: the labels and announcements of components. */
+export const MESSAGES = {
+    close: 'Close',
+    loading: 'Loading',
+    // The region of toasts, followed by its key: "Notifications (F8)".
+    notifications: 'Notifications',
+    progress: 'Progress',
+    // Validation: the HTML constraints of form fields.
+    required: 'Required',
+    tooShort: 'Enter at least {min} characters',
+    tooLong: 'Enter no more than {max} characters',
+    typeEmail: 'Enter a valid email address',
+    typeUrl: 'Enter a valid web address',
+    patternMismatch: 'Enter a value in the requested format',
+    badInput: 'Enter a number',
+    rangeUnderflow: 'Enter {min} or more',
+    rangeOverflow: 'Enter {max} or less',
+    stepMismatch: 'Enter a value in steps of {step}',
+    // The buttons of a number field.
+    increase: 'Increase',
+    decrease: 'Decrease'
+};
+// Building an Intl formatter is the expensive part, so each one is built once per locale and
+// options. Keys hold no user data, so the cache is safe to share across server requests.
+const cache = new Map();
+function cached(Format, locale, options) {
+    const key = `${Format.name}|${locale}|${JSON.stringify(options)}`;
+    let formatter = cache.get(key);
+    if (!formatter)
+        cache.set(key, (formatter = new Format(locale, options)));
+    return formatter;
+}
+// Largest unit first, with its length in seconds.
+const UNITS = [
+    ['year', 31_536_000],
+    ['month', 2_592_000],
+    ['week', 604_800],
+    ['day', 86_400],
+    ['hour', 3_600],
+    ['minute', 60],
+    ['second', 1]
+];
+/** Builds a locale whose settings are read through `options` on every call. */
+export function createLocale(options) {
+    const locale = () => options().locale ?? 'en-US';
+    const currency = () => options().currency ?? 'USD';
+    const timeZone = () => options().timeZone;
+    const number = (format) => cached(Intl.NumberFormat, locale(), format);
+    return {
+        get locale() {
+            return locale();
+        },
+        get currency() {
+            return currency();
+        },
+        get timeZone() {
+            return timeZone();
+        },
+        t: (key, values) => (options().messages?.[key] ?? MESSAGES[key]).replace(/\{(\w+)\}/g, (match, name) => String(values?.[name] ?? match)),
+        formatNumber: (value, format = {}) => number(format).format(value),
+        formatCurrency: (value, code = currency(), format = {}) => number({ ...format, style: 'currency', currency: code }).format(value),
+        formatPercent: (value, format = {}) => number({ ...format, style: 'percent' }).format(value),
+        formatDate: (value, format = {}) => cached(Intl.DateTimeFormat, locale(), { timeZone: timeZone(), ...format }).format(value),
+        formatRelative: (value, now = Date.now()) => {
+            const seconds = (+value - +now) / 1000;
+            const [unit, length] = UNITS.find(([, size]) => Math.abs(seconds) >= size) ?? ['second', 1];
+            return cached(Intl.RelativeTimeFormat, locale(), { numeric: 'auto' }).format(Math.round(seconds / length), unit);
+        }
+    };
+}
+const KEY = Symbol('sveltier.locale');
+let shared;
+/** Gives a subtree its locale, built from the root's options. */
+export const setLocaleContext = (locale) => setContext(KEY, locale);
+/**
+ * Returns messages and formatters for the current locale. Call it during component
+ * initialisation. Without a provider it returns one shared instance with the defaults.
+ */
+export function useLocale() {
+    return hasContext(KEY) ? getContext(KEY) : (shared ??= createLocale(() => ({})));
+}

package/dist/core/overlay/types.d.ts

@@ -0,0 +1,33 @@
+import type { Attachment } from 'svelte/attachments';
+export declare const CLOSE_REASONS: readonly ["escape", "outside", "focus", "action"];
+/**
+ * Why an overlay closed itself: `'escape'` (the Escape key), `'outside'` (a press outside it,
+ * on the backdrop of a modal), `'focus'` (focus moved out of a menu or a popover) or `'action'`
+ * (its close button, `close()` from its snippets, or a choice made in it).
+ */
+export type CloseReason = (typeof CLOSE_REASONS)[number];
+/**
+ * What an overlay passes to its `trigger` snippet: the ARIA that ties the control to the
+ * overlay, the handlers that open it, and an attachment that tells the overlay which element
+ * opened it (focus goes back there on close). Spread it onto the control.
+ *
+ * @example
+ * <Dialog title="Rename the account">
+ *   {#snippet trigger(attributes)}<Button {...attributes}>Rename</Button>{/snippet}
+ *   …
+ * </Dialog>
+ */
+export interface TriggerAttributes {
+    /** The kind of overlay the control opens. */
+    'aria-haspopup'?: 'dialog' | 'menu' | 'true';
+    /** Whether the overlay is open, for overlays that stay beside the control. */
+    'aria-expanded'?: boolean;
+    /** The overlay's id while it is open. */
+    'aria-controls'?: string;
+    /** The overlay's id, for a tooltip that describes the control. */
+    'aria-describedby'?: string;
+    onclick?: (event: MouseEvent) => void;
+    onkeydown?: (event: KeyboardEvent) => void;
+    /** The attachment that hands the control to the overlay. */
+    [attachment: symbol]: Attachment<HTMLElement>;
+}

package/dist/core/overlay/types.js

@@ -0,0 +1 @@
+export const CLOSE_REASONS = ['escape', 'outside', 'focus', 'action'];

package/dist/core/props/classes.d.ts

@@ -0,0 +1,21 @@
+import { type SharedProps, type Variant } from './types.js';
+/** The shared props that map to classes. */
+export type SharedClassProps = Pick<SharedProps, 'variant' | 'density' | 'size' | 'color' | 'rounded'>;
+/**
+ * Classes for a component's shared props, for example
+ * `sv-variant-flat sv-density-default sv-size-md sv-color-primary sv-rounded`.
+ *
+ * The classes set custom properties (`--sv-color`, `--sv-variant-bg`, `--sv-size-height`,
+ * `--sv-density`, `--sv-rounded`, …) that the component reads. Custom properties inherit,
+ * so pass a value for every shared prop the component has, defaults included (the values
+ * `useDefaults()` resolves); an omitted one would follow the parent component.
+ *
+ * In development, a value outside its list warns with the valid ones, naming `component`.
+ * A component that takes only some variants passes them as `variants`.
+ *
+ * @example
+ * // In a component: resolve the defaults, then name the component for the warnings.
+ * const p = $derived(resolve({ variant, size, color }));
+ * const classes = $derived(['my-pill', sharedClasses(p, 'MyPill')]);
+ */
+export declare function sharedClasses({ variant, density, size, color, rounded }: SharedClassProps, component?: string, variants?: readonly Variant[]): string;

package/dist/core/props/classes.js

@@ -0,0 +1,44 @@
+import { checkValue, DEV } from '#dev';
+import '../../styles/props.css';
+import { INTENT_COLORS } from '../theme/types.js';
+import { DENSITIES, ROUNDED, SIZES, VARIANTS } from './types.js';
+/**
+ * Classes for a component's shared props, for example
+ * `sv-variant-flat sv-density-default sv-size-md sv-color-primary sv-rounded`.
+ *
+ * The classes set custom properties (`--sv-color`, `--sv-variant-bg`, `--sv-size-height`,
+ * `--sv-density`, `--sv-rounded`, …) that the component reads. Custom properties inherit,
+ * so pass a value for every shared prop the component has, defaults included (the values
+ * `useDefaults()` resolves); an omitted one would follow the parent component.
+ *
+ * In development, a value outside its list warns with the valid ones, naming `component`.
+ * A component that takes only some variants passes them as `variants`.
+ *
+ * @example
+ * // In a component: resolve the defaults, then name the component for the warnings.
+ * const p = $derived(resolve({ variant, size, color }));
+ * const classes = $derived(['my-pill', sharedClasses(p, 'MyPill')]);
+ */
+export function sharedClasses({ variant, density, size, color, rounded }, component = 'component', variants = VARIANTS) {
+    if (DEV) {
+        // An intent given as the variant usually meant the colour.
+        const intent = INTENT_COLORS.includes(variant);
+        checkValue(component, 'variant', variant, variants, intent ? `To colour it, use color="${variant}".` : undefined);
+        checkValue(component, 'size', size, SIZES);
+        checkValue(component, 'density', density, DENSITIES);
+        checkValue(component, 'rounded', rounded, ROUNDED);
+    }
+    let classes = '';
+    if (variant)
+        classes += ` sv-variant-${variant}`;
+    if (density)
+        classes += ` sv-density-${density}`;
+    if (size)
+        classes += ` sv-size-${size}`;
+    if (color)
+        classes += ` sv-color-${color}`;
+    if (rounded !== undefined) {
+        classes += rounded === true ? ' sv-rounded' : ` sv-rounded-${rounded || 'none'}`;
+    }
+    return classes.slice(1);
+}

package/dist/core/props/element.d.ts

@@ -0,0 +1,18 @@
+import type { ClassValue } from 'svelte/elements';
+/**
+ * The props of a component rendered as one root element: its own props `Own`, then every
+ * attribute of `Attributes` that `Own` does not redefine (spread onto the root), `class`
+ * (merged after the component's own classes) and a bindable `ref` to the root element.
+ *
+ * Own props win over same-named attributes, so a shared `size` or `color` never clashes
+ * with the HTML attribute of the same name.
+ *
+ * @example
+ * type PillProps = ElementProps<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>, { size?: Size }>;
+ */
+export type ElementProps<Element, Attributes, Own = object> = Own & Omit<Attributes, keyof Own | 'class'> & {
+    /** Classes added after the component's own: a string, an array or an object. */
+    class?: ClassValue | null;
+    /** The root element, bindable with `bind:ref`. */
+    ref?: Element | null;
+};

package/dist/core/props/element.js

@@ -0,0 +1 @@
+export {};

package/dist/core/props/types.d.ts

@@ -0,0 +1,47 @@
+import type { IntentColor } from '../theme/types.js';
+/** How tightly a component packs its content. `default` is the baseline. */
+export declare const DENSITIES: readonly ["compact", "default", "comfortable"];
+export type Density = (typeof DENSITIES)[number];
+/** Overall scale of a component. `md` is the baseline. */
+export declare const SIZES: readonly ["xs", "sm", "md", "lg", "xl"];
+export type Size = (typeof SIZES)[number];
+/**
+ * Visual weight: a raised surface, filled, tinted, outlined, text only, or no decoration at
+ * all.
+ */
+export declare const VARIANTS: readonly ["elevated", "flat", "tonal", "outlined", "text", "plain"];
+export type Variant = (typeof VARIANTS)[number];
+/**
+ * Corner rounding. `true` keeps the theme's radius, `false` / `'none'` removes it,
+ * `sm`–`xl` pick a theme radius, `'full'` makes a pill whatever the theme.
+ */
+export declare const ROUNDED: readonly [true, false, "none", "sm", "md", "lg", "xl", "full"];
+export type Rounded = (typeof ROUNDED)[number];
+/**
+ * Custom colours added with `defineTheme()`. Register them here by declaration merging to
+ * use them as a component's `color`:
+ *
+ * @example
+ * declare module '@sveltier/ui' {
+ *   interface CustomColors {
+ *     brand: true;
+ *   }
+ * }
+ */
+export interface CustomColors {
+}
+/**
+ * A component's colour: an intent, `neutral` (the text colour, with the background as its
+ * on-colour), or a custom colour registered in `CustomColors`.
+ */
+export type Color = IntentColor | 'neutral' | Extract<keyof CustomColors, string> extends infer C ? C : never;
+/** Props shared by every component that supports them. */
+export interface SharedProps {
+    variant?: Variant;
+    density?: Density;
+    size?: Size;
+    color?: Color;
+    rounded?: Rounded;
+    disabled?: boolean;
+    loading?: boolean;
+}

package/dist/core/props/types.js

@@ -0,0 +1,16 @@
+// The shared prop vocabulary. Every component that has one of these props uses exactly
+// these names and these values.
+/** How tightly a component packs its content. `default` is the baseline. */
+export const DENSITIES = ['compact', 'default', 'comfortable'];
+/** Overall scale of a component. `md` is the baseline. */
+export const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'];
+/**
+ * Visual weight: a raised surface, filled, tinted, outlined, text only, or no decoration at
+ * all.
+ */
+export const VARIANTS = ['elevated', 'flat', 'tonal', 'outlined', 'text', 'plain'];
+/**
+ * Corner rounding. `true` keeps the theme's radius, `false` / `'none'` removes it,
+ * `sm`–`xl` pick a theme radius, `'full'` makes a pill whatever the theme.
+ */
+export const ROUNDED = [true, false, 'none', 'sm', 'md', 'lg', 'xl', 'full'];

package/dist/core/provider/UIProvider.svelte

@@ -0,0 +1,63 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { DefaultsConfig } from '../defaults/context.js';
+	import type { DisplayOptions } from '../display/display.js';
+	import type { LocaleOptions } from '../locale/locale.js';
+	import type { ThemeChoice, ThemeDefinition } from '../theme/types.js';
+
+	export interface UIProviderProps {
+		/** The registered themes, for example `monolith` or `{ ...monolith, ...maison }`. */
+		themes: Record<string, ThemeDefinition>;
+		/** "system" or a theme name. Bindable. */
+		theme?: ThemeChoice;
+		/** Theme used by "system" when the OS prefers light. Defaults to the first light theme. */
+		light?: string;
+		/** Theme used by "system" when the OS prefers dark. Defaults to the first dark theme. */
+		dark?: string;
+		/** Where the user's theme choice is remembered; `false` turns persistence off. */
+		storageKey?: string | false;
+		/** CSP nonce for the generated `<style>` and `<script>`. */
+		nonce?: string;
+		/** Default props for every component below. */
+		defaults?: DefaultsConfig;
+		/** Breakpoint thresholds, mobile breakpoint and server width. Read once. */
+		display?: DisplayOptions;
+		/** Locale, currency, time zone and messages. Changes apply at once. */
+		locale?: LocaleOptions;
+		children?: Snippet;
+	}
+</script>
+
+<script lang="ts">
+	// The root of an app: theme, defaults, display, locale and toasts in one component.
+	import { untrack } from 'svelte';
+	import DefaultsProvider from '../defaults/DefaultsProvider.svelte';
+	import { createDisplay, setDisplayContext } from '../display/display.js';
+	import { createLocale, setLocaleContext } from '../locale/locale.js';
+	import ThemeProvider from '../theme/ThemeProvider.svelte';
+	import ToastProvider from '../toast/ToastProvider.svelte';
+
+	let {
+		themes,
+		theme = $bindable(),
+		light,
+		dark,
+		storageKey,
+		nonce,
+		defaults,
+		display,
+		locale,
+		children
+	}: UIProviderProps = $props();
+
+	setDisplayContext(untrack(() => createDisplay(display)));
+	setLocaleContext(createLocale(() => locale ?? {}));
+</script>
+
+<ThemeProvider {themes} bind:theme {light} {dark} {storageKey} {nonce}>
+	<DefaultsProvider defaults={defaults ?? {}}>
+		<ToastProvider>
+			{@render children?.()}
+		</ToastProvider>
+	</DefaultsProvider>
+</ThemeProvider>

package/dist/core/provider/UIProvider.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { Snippet } from 'svelte';
+import type { DefaultsConfig } from '../defaults/context.js';
+import type { DisplayOptions } from '../display/display.js';
+import type { LocaleOptions } from '../locale/locale.js';
+import type { ThemeChoice, ThemeDefinition } from '../theme/types.js';
+export interface UIProviderProps {
+    /** The registered themes, for example `monolith` or `{ ...monolith, ...maison }`. */
+    themes: Record<string, ThemeDefinition>;
+    /** "system" or a theme name. Bindable. */
+    theme?: ThemeChoice;
+    /** Theme used by "system" when the OS prefers light. Defaults to the first light theme. */
+    light?: string;
+    /** Theme used by "system" when the OS prefers dark. Defaults to the first dark theme. */
+    dark?: string;
+    /** Where the user's theme choice is remembered; `false` turns persistence off. */
+    storageKey?: string | false;
+    /** CSP nonce for the generated `<style>` and `<script>`. */
+    nonce?: string;
+    /** Default props for every component below. */
+    defaults?: DefaultsConfig;
+    /** Breakpoint thresholds, mobile breakpoint and server width. Read once. */
+    display?: DisplayOptions;
+    /** Locale, currency, time zone and messages. Changes apply at once. */
+    locale?: LocaleOptions;
+    children?: Snippet;
+}
+declare const UIProvider: import("svelte").Component<UIProviderProps, {}, "theme">;
+type UIProvider = ReturnType<typeof UIProvider>;
+export default UIProvider;

package/dist/core/theme/ThemeProvider.svelte

@@ -0,0 +1,178 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import type { ThemeChoice, ThemeDefinition } from './types.js';
+
+	export interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
+		/** "system" or a theme name. Nested providers inherit their parent's choice by default. */
+		theme?: ThemeChoice;
+		/** Root only, and required there. The registered themes, for example `monolith` or `{ ...monolith, ...maison }`. */
+		themes?: Record<string, ThemeDefinition>;
+		/** Root only. Theme used by "system" when the OS prefers light. Defaults to the first light theme. */
+		light?: string;
+		/** Root only. Theme used by "system" when the OS prefers dark. Defaults to the first dark theme. */
+		dark?: string;
+		/** Root only. Where the user's choice is remembered; `false` turns persistence off. */
+		storageKey?: string | false;
+		/** Root only. CSP nonce for the generated `<style>` and `<script>`. */
+		nonce?: string;
+		/** Nested only. Paint the scope's background. */
+		withBackground?: boolean;
+		/** Nested only. The wrapper element. */
+		ref?: HTMLDivElement | null;
+		children?: Snippet;
+	}
+</script>
+
+<script lang="ts">
+	import { onMount, untrack } from 'svelte';
+	import { MediaQuery } from 'svelte/reactivity';
+	import '../../styles/tokens.css';
+	import '../../styles/base.css';
+	import './theme-provider.css';
+	import { sveltierError } from '../errors/errors.js';
+	import { hasThemeContext, setThemeContext, useTheme, type ThemeInstance } from './context.js';
+	import { THEME_ATTRIBUTE, themeCss, themeHead, themeScript } from './css.js';
+
+	const parent = hasThemeContext() ? useTheme() : undefined;
+
+	let {
+		theme = $bindable(),
+		themes,
+		light,
+		dark,
+		storageKey = 'sv-theme',
+		nonce,
+		withBackground = false,
+		ref = $bindable(null),
+		class: className,
+		children,
+		...rest
+	}: ThemeProviderProps = $props();
+
+	const registry = $derived.by(() => {
+		const registered = parent?.themes ?? themes;
+		if (!registered) {
+			throw sveltierError(
+				'SV1001',
+				"The root <ThemeProvider> has no themes. Pass one, for example themes={monolith} from '@sveltier/ui/themes/monolith'."
+			);
+		}
+		return registered;
+	});
+	const lightName = $derived(parent?.light ?? light ?? first(registry, false));
+	const darkName = $derived(parent?.dark ?? dark ?? first(registry, true));
+	const choice = $derived<ThemeChoice>(theme ?? parent?.choice ?? 'system');
+
+	const prefersDark = new MediaQuery('(prefers-color-scheme: dark)', false);
+	const name = $derived(
+		choice === 'system' ? (prefersDark.current ? darkName : lightName) : choice
+	);
+	const current = $derived(registry[name] ?? (registry[lightName] as ThemeDefinition));
+	const persist = $derived(!parent && storageKey !== false ? storageKey : undefined);
+	/** The first registered theme with the given darkness, or the first theme at all. */
+	function first(themes: Record<string, ThemeDefinition>, isDark: boolean): string {
+		const names = Object.keys(themes);
+		return names.find((n) => themes[n]?.dark === isDark) ?? (names[0] as string);
+	}
+
+	const isChoice = (value: unknown): value is ThemeChoice =>
+		value === 'system' || (typeof value === 'string' && Object.hasOwn(registry, value));
+
+	// The server cannot read a stored choice and the first client render must match the server
+	// HTML. The inline head script has already painted the stored theme, so <html> is only
+	// touched after mount, once the stored choice is known.
+	let mounted = $state(false);
+	const fallback = untrack(() => theme ?? 'system');
+
+	onMount(() => {
+		if (persist) {
+			try {
+				const stored = localStorage.getItem(persist);
+				if (isChoice(stored)) theme = stored;
+			} catch {
+				// Storage blocked (privacy mode, sandboxed iframe): keep the default.
+			}
+		}
+		mounted = true;
+		if (!parent) return () => document.documentElement.removeAttribute(THEME_ATTRIBUTE);
+	});
+
+	$effect(() => {
+		if (mounted && !parent) document.documentElement.setAttribute(THEME_ATTRIBUTE, choice);
+	});
+
+	const head = $derived(
+		parent
+			? ''
+			: themeHead(
+					themeCss({ themes: registry, light: lightName, dark: darkName, fallback }),
+					persist ? themeScript(persist, ['system', ...Object.keys(registry)]) : '',
+					nonce
+				)
+	);
+
+	const instance: ThemeInstance = {
+		get choice() {
+			return choice;
+		},
+		get name() {
+			return name;
+		},
+		get current() {
+			return current;
+		},
+		get isDark() {
+			return current.dark;
+		},
+		get themes() {
+			return registry;
+		},
+		get light() {
+			return lightName;
+		},
+		get dark() {
+			return darkName;
+		},
+		set(next) {
+			if (!isChoice(next)) {
+				const names = Object.keys(registry).join(', ');
+				throw sveltierError(
+					'SV1002',
+					`Unknown theme "${next}". Registered: ${names}, or "system".`
+				);
+			}
+			theme = next;
+			try {
+				if (persist) localStorage.setItem(persist, next);
+			} catch {
+				// Not remembered, but the choice still applies to this page view.
+			}
+		},
+		toggle() {
+			instance.set(current.dark ? lightName : darkName);
+		}
+	};
+
+	setThemeContext(instance);
+</script>
+
+<svelte:head>
+	{#if head}
+		<!-- eslint-disable-next-line svelte/no-at-html-tags -- generated from validated theme values -->
+		{@html head}
+	{/if}
+</svelte:head>
+
+{#if parent}
+	<div
+		bind:this={ref}
+		{...rest}
+		class={['sv-theme-provider', withBackground && 'sv-theme-provider--background', className]}
+		data-sv-theme={choice}
+	>
+		{@render children?.()}
+	</div>
+{:else}
+	{@render children?.()}
+{/if}

package/dist/core/theme/ThemeProvider.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ThemeChoice, ThemeDefinition } from './types.js';
+export interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
+    /** "system" or a theme name. Nested providers inherit their parent's choice by default. */
+    theme?: ThemeChoice;
+    /** Root only, and required there. The registered themes, for example `monolith` or `{ ...monolith, ...maison }`. */
+    themes?: Record<string, ThemeDefinition>;
+    /** Root only. Theme used by "system" when the OS prefers light. Defaults to the first light theme. */
+    light?: string;
+    /** Root only. Theme used by "system" when the OS prefers dark. Defaults to the first dark theme. */
+    dark?: string;
+    /** Root only. Where the user's choice is remembered; `false` turns persistence off. */
+    storageKey?: string | false;
+    /** Root only. CSP nonce for the generated `<style>` and `<script>`. */
+    nonce?: string;
+    /** Nested only. Paint the scope's background. */
+    withBackground?: boolean;
+    /** Nested only. The wrapper element. */
+    ref?: HTMLDivElement | null;
+    children?: Snippet;
+}
+declare const ThemeProvider: import("svelte").Component<ThemeProviderProps, {}, "theme" | "ref">;
+type ThemeProvider = ReturnType<typeof ThemeProvider>;
+export default ThemeProvider;

package/dist/core/theme/color.d.ts

@@ -0,0 +1,23 @@
+export interface Oklch {
+    /** Lightness, 0–1. */
+    l: number;
+    /** Chroma, 0–0.4 in practice. */
+    c: number;
+    /** Hue in degrees. */
+    h: number;
+    /** Alpha, 0–1. */
+    alpha: number;
+}
+/** Parses `oklch(L C H)` or `oklch(L C H / A)` with numbers or percentages. */
+export declare function parseOklch(value: string): Oklch | undefined;
+/** Linear-light sRGB channels, clamped to the sRGB gamut. */
+export declare function toLinearSrgb({ l, c, h }: Oklch): [number, number, number];
+/** WCAG relative luminance of an opaque colour. */
+export declare function luminance(color: Oklch): number;
+/** WCAG 2 contrast ratio between two opaque oklch colours (1–21). */
+export declare function contrast(a: Oklch, b: Oklch): number;
+/**
+ * Picks a readable text colour for a filled background: a deep ink or a near-white, both
+ * tinted with the background's hue, whichever contrasts more.
+ */
+export declare function onColor(background: string): string | undefined;