@joewinke/jatui 0.27.1 → 0.29.0

package/dist/motion/store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Motion-level store — a Svelte store (subscribe contract, usable as
+ * `$motion`) that owns a surface's `data-motion` attribute, optionally
+ * persists the user's choice, and tracks `prefers-reduced-motion` live.
+ *
+ *   const motion = createMotionLevelStore({ storageKey: 'app.motion' })
+ *   motion.set('calm')                 // writes data-motion="calm" on <html>
+ *   $motion.level / $motion.reduced    // reactive in components
+ *   $motion.effective                  // 'reduced' when the OS asks, else level
+ *
+ * Plain store (no runes), so it works in .ts, in SSR (no DOM access until a
+ * method or subscriber needs it) and under node:test.
+ */
+import { type MotionLevel } from './level';
+export interface MotionState {
+    /** The level chosen for the surface. */
+    level: MotionLevel;
+    /** `prefers-reduced-motion: reduce` is on — every level yields to it. */
+    reduced: boolean;
+    /** What actually runs: 'reduced' when reduced, else the level. */
+    effective: MotionLevel | 'reduced';
+}
+export interface MotionLevelStoreOptions {
+    /** Element that carries `data-motion`. Default `document.documentElement`, resolved lazily. */
+    target?: Element | (() => Element | null) | null;
+    /** Persist the chosen level in localStorage under this key. Omit = no persistence. */
+    storageKey?: string;
+    /** Level when nothing is stored and the target has no attribute. Default 'standard'. */
+    initial?: MotionLevel;
+}
+export interface MotionLevelStore {
+    subscribe(run: (state: MotionState) => void): () => void;
+    /** Set the level (writes the attribute, persists when configured). */
+    set(level: MotionLevel): void;
+    /** Clear the stored choice and fall back to `initial`. */
+    reset(): void;
+    /** Current state, without subscribing. */
+    get(): MotionState;
+}
+export declare function createMotionLevelStore(options?: MotionLevelStoreOptions): MotionLevelStore;

package/dist/motion/store.js

@@ -0,0 +1,132 @@
+/**
+ * Motion-level store — a Svelte store (subscribe contract, usable as
+ * `$motion`) that owns a surface's `data-motion` attribute, optionally
+ * persists the user's choice, and tracks `prefers-reduced-motion` live.
+ *
+ *   const motion = createMotionLevelStore({ storageKey: 'app.motion' })
+ *   motion.set('calm')                 // writes data-motion="calm" on <html>
+ *   $motion.level / $motion.reduced    // reactive in components
+ *   $motion.effective                  // 'reduced' when the OS asks, else level
+ *
+ * Plain store (no runes), so it works in .ts, in SSR (no DOM access until a
+ * method or subscriber needs it) and under node:test.
+ */
+import { DEFAULT_MOTION_LEVEL, parseMotionLevel, prefersReducedMotion, resolveMotionLevel, setMotionLevel } from './level';
+function stateOf(level, reduced) {
+    return { level, reduced, effective: reduced ? 'reduced' : level };
+}
+function readStorage(key) {
+    if (!key)
+        return null;
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+function writeStorage(key, value) {
+    if (!key)
+        return;
+    try {
+        if (typeof localStorage === 'undefined')
+            return;
+        if (value === null)
+            localStorage.removeItem(key);
+        else
+            localStorage.setItem(key, value);
+    }
+    catch {
+        // storage blocked (private mode, quota) — the attribute still applies
+    }
+}
+export function createMotionLevelStore(options = {}) {
+    const { storageKey } = options;
+    const initial = options.initial ?? DEFAULT_MOTION_LEVEL;
+    const subscribers = new Set();
+    let state = null;
+    let stopMedia = null;
+    function target() {
+        const t = options.target;
+        if (typeof t === 'function')
+            return t();
+        if (t)
+            return t;
+        return typeof document !== 'undefined' ? document.documentElement : null;
+    }
+    function load() {
+        if (state)
+            return state;
+        const stored = readStorage(storageKey);
+        const el = target();
+        let level;
+        if (stored !== null) {
+            level = parseMotionLevel(stored, initial);
+            setMotionLevel(level, el);
+        }
+        else if (el?.hasAttribute?.('data-motion')) {
+            level = resolveMotionLevel(el);
+        }
+        else {
+            level = initial;
+        }
+        state = stateOf(level, prefersReducedMotion());
+        return state;
+    }
+    function emit(next) {
+        state = next;
+        for (const run of subscribers)
+            run(next);
+    }
+    function watchReducedMotion() {
+        if (stopMedia || typeof window === 'undefined' || typeof window.matchMedia !== 'function')
+            return;
+        let mql;
+        try {
+            mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+        }
+        catch {
+            return;
+        }
+        const onChange = (e) => {
+            const cur = load();
+            if (cur.reduced !== e.matches)
+                emit(stateOf(cur.level, e.matches));
+        };
+        if (typeof mql.addEventListener === 'function') {
+            mql.addEventListener('change', onChange);
+            stopMedia = () => mql.removeEventListener('change', onChange);
+        }
+        else if (typeof mql.addListener === 'function') {
+            mql.addListener(onChange);
+            stopMedia = () => mql.removeListener(onChange);
+        }
+    }
+    return {
+        subscribe(run) {
+            subscribers.add(run);
+            if (subscribers.size === 1)
+                watchReducedMotion();
+            run(load());
+            return () => {
+                subscribers.delete(run);
+                if (subscribers.size === 0 && stopMedia) {
+                    stopMedia();
+                    stopMedia = null;
+                }
+            };
+        },
+        set(level) {
+            const next = parseMotionLevel(level, initial);
+            setMotionLevel(next, target());
+            writeStorage(storageKey, next);
+            emit(stateOf(next, load().reduced));
+        },
+        reset() {
+            writeStorage(storageKey, null);
+            setMotionLevel(initial, target());
+            emit(stateOf(initial, load().reduced));
+        },
+        get: load
+    };
+}

package/dist/motion/transitions.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Token-built Svelte transitions — drop-in replacements for ad-hoc
+ * `svelte/transition` usage that read the `--motion-*` scheme and honour the
+ * surface's motion level (`data-motion`) and `prefers-reduced-motion`.
+ *
+ *   <div transition:motionFade>                       fade, --motion-enter
+ *   <div in:motionScale={{ easing: 'spring' }}>       pop (spring → glide when calm)
+ *   <section transition:motionSlide>                  height collapse, --motion-move
+ *   <aside in:glide={{ from: 'right' }}>              directional (transitions/glide)
+ *
+ * Shared params (all optional):
+ *   duration  a duration token ('instant'|'fast'|'enter'|'move') or a
+ *             STANDARD-level ms value — either way it is scaled by the level.
+ *   delay     standard-level ms, scaled the same way.
+ *   easing    an easing token ('glide'|'spring'|'standard') or a function.
+ *   level     pin the level instead of reading the nearest [data-motion].
+ *
+ * Reduced motion: duration and delay become 0 — the element appears/leaves
+ * in its end state. This matches the global floor in styles/motion.css.
+ */
+import { type EasingFn } from './easing';
+import { type MotionContext, type MotionDurationToken, type MotionEasingToken, type MotionLevel } from './level';
+export interface MotionTransitionParams {
+    duration?: MotionDurationToken | number;
+    delay?: number;
+    easing?: MotionEasingToken | EasingFn;
+    level?: MotionLevel;
+}
+export interface MotionTransitionConfig {
+    delay: number;
+    duration: number;
+    easing: EasingFn;
+    css: (t: number, u: number) => string;
+}
+export interface ResolvedMotionTiming {
+    ctx: MotionContext;
+    delay: number;
+    duration: number;
+    easing: EasingFn;
+}
+/** Resolve the level-aware timing for a transition on `node`. */
+export declare function resolveMotionTiming(node: Element | null, params: MotionTransitionParams, defaults: {
+    duration: MotionDurationToken | number;
+    easing: MotionEasingToken;
+}): ResolvedMotionTiming;
+export interface MotionFadeParams extends MotionTransitionParams {
+}
+/** Opacity fade. Defaults: --motion-enter, glide. */
+export declare function motionFade(node: Element, params?: MotionFadeParams): MotionTransitionConfig;
+export interface MotionScaleParams extends MotionTransitionParams {
+    /** Scale at the start of the enter. Default 0.95. */
+    start?: number;
+    /** Also fade. Default true. */
+    opacity?: boolean;
+}
+/**
+ * Scale + fade. Defaults: --motion-enter, glide. Pass `easing: 'spring'` for
+ * a state-confirmation pop on a SMALL element (policy: never on containers);
+ * calm and reduced surfaces get glide instead.
+ */
+export declare function motionScale(node: Element, params?: MotionScaleParams): MotionTransitionConfig;
+export interface MotionSlideParams extends MotionTransitionParams {
+    /** Collapse axis. Default 'y' (height). */
+    axis?: 'x' | 'y';
+    /** Also fade. Default false (matches svelte's slide). */
+    opacity?: boolean;
+}
+/**
+ * Size collapse/expand along an axis (svelte `slide`, on tokens).
+ * Defaults: --motion-move, standard — a container morph, symmetric move.
+ */
+export declare function motionSlide(node: Element, params?: MotionSlideParams): MotionTransitionConfig;

package/dist/motion/transitions.js

@@ -0,0 +1,112 @@
+/**
+ * Token-built Svelte transitions — drop-in replacements for ad-hoc
+ * `svelte/transition` usage that read the `--motion-*` scheme and honour the
+ * surface's motion level (`data-motion`) and `prefers-reduced-motion`.
+ *
+ *   <div transition:motionFade>                       fade, --motion-enter
+ *   <div in:motionScale={{ easing: 'spring' }}>       pop (spring → glide when calm)
+ *   <section transition:motionSlide>                  height collapse, --motion-move
+ *   <aside in:glide={{ from: 'right' }}>              directional (transitions/glide)
+ *
+ * Shared params (all optional):
+ *   duration  a duration token ('instant'|'fast'|'enter'|'move') or a
+ *             STANDARD-level ms value — either way it is scaled by the level.
+ *   delay     standard-level ms, scaled the same way.
+ *   easing    an easing token ('glide'|'spring'|'standard') or a function.
+ *   level     pin the level instead of reading the nearest [data-motion].
+ *
+ * Reduced motion: duration and delay become 0 — the element appears/leaves
+ * in its end state. This matches the global floor in styles/motion.css.
+ */
+import { motionEasing } from './easing';
+import { effectiveEasing, getMotionContext, motionContextFor, motionDuration, prefersReducedMotion } from './level';
+/** Resolve the level-aware timing for a transition on `node`. */
+export function resolveMotionTiming(node, params, defaults) {
+    const ctx = params.level
+        ? motionContextFor(params.level, prefersReducedMotion())
+        : getMotionContext(node);
+    const duration = motionDuration(params.duration ?? defaults.duration, ctx);
+    const delay = motionDuration(params.delay ?? 0, ctx);
+    const easing = typeof params.easing === 'function'
+        ? params.easing
+        : motionEasing(effectiveEasing(params.easing ?? defaults.easing, ctx));
+    return { ctx, delay, duration, easing };
+}
+const clamp01 = (n) => (n < 0 ? 0 : n > 1 ? 1 : n);
+function baseOpacity(node) {
+    if (typeof getComputedStyle !== 'function')
+        return 1;
+    const o = parseFloat(getComputedStyle(node).opacity);
+    return Number.isFinite(o) ? o : 1;
+}
+/** Opacity fade. Defaults: --motion-enter, glide. */
+export function motionFade(node, params = {}) {
+    const { delay, duration, easing } = resolveMotionTiming(node, params, {
+        duration: 'enter',
+        easing: 'glide'
+    });
+    const o = baseOpacity(node);
+    return { delay, duration, easing, css: (t) => `opacity: ${clamp01(t) * o}` };
+}
+/**
+ * Scale + fade. Defaults: --motion-enter, glide. Pass `easing: 'spring'` for
+ * a state-confirmation pop on a SMALL element (policy: never on containers);
+ * calm and reduced surfaces get glide instead.
+ */
+export function motionScale(node, params = {}) {
+    const { delay, duration, easing } = resolveMotionTiming(node, params, {
+        duration: 'enter',
+        easing: 'glide'
+    });
+    const start = params.start ?? 0.95;
+    const fade = params.opacity ?? true;
+    const o = baseOpacity(node);
+    const existing = typeof getComputedStyle === 'function' ? getComputedStyle(node).transform : 'none';
+    const prefix = existing && existing !== 'none' ? `${existing} ` : '';
+    return {
+        delay,
+        duration,
+        easing,
+        css: (t) => `transform: ${prefix}scale(${start + (1 - start) * t});` +
+            (fade ? ` opacity: ${clamp01(t) * o};` : '')
+    };
+}
+/**
+ * Size collapse/expand along an axis (svelte `slide`, on tokens).
+ * Defaults: --motion-move, standard — a container morph, symmetric move.
+ */
+export function motionSlide(node, params = {}) {
+    const { delay, duration, easing } = resolveMotionTiming(node, params, {
+        duration: 'move',
+        easing: 'standard'
+    });
+    const axis = params.axis ?? 'y';
+    const fade = params.opacity ?? false;
+    if (typeof getComputedStyle !== 'function') {
+        return { delay, duration, easing, css: () => '' };
+    }
+    const style = getComputedStyle(node);
+    const o = +style.opacity || 1;
+    const size = axis === 'y' ? 'height' : 'width';
+    const [a, b] = axis === 'y' ? ['top', 'bottom'] : ['left', 'right'];
+    const px = (prop) => parseFloat(style.getPropertyValue(prop)) || 0;
+    const full = px(size);
+    const padA = px(`padding-${a}`);
+    const padB = px(`padding-${b}`);
+    const marA = px(`margin-${a}`);
+    const marB = px(`margin-${b}`);
+    const borA = px(`border-${a}-width`);
+    const borB = px(`border-${b}-width`);
+    return {
+        delay,
+        duration,
+        easing,
+        css: (t) => 'overflow: hidden;' +
+            (fade ? ` opacity: ${Math.min(t * 20, 1) * o};` : '') +
+            ` ${size}: ${t * full}px;` +
+            ` padding-${a}: ${t * padA}px; padding-${b}: ${t * padB}px;` +
+            ` margin-${a}: ${t * marA}px; margin-${b}: ${t * marB}px;` +
+            ` border-${a}-width: ${t * borA}px; border-${b}-width: ${t * borB}px;` +
+            (axis === 'y' ? ' min-height: 0;' : ' min-width: 0;')
+    };
+}

package/dist/sound/SoundSettings.svelte

@@ -0,0 +1,209 @@
+<script lang="ts">
+	/**
+	 * SoundSettings — drop-in "Sounds" section for an account/settings page.
+	 * A view over the shared sound preferences store: master on/off, volume,
+	 * per-category switches, the quiet (reduced-motion) mode and quiet hours.
+	 * Every change persists immediately (per device), so no save button.
+	 */
+	import { onDestroy } from 'svelte';
+	import Button from '../components/Button.svelte';
+	import { SOUND_CATEGORIES, type SoundCategory } from './names';
+	import {
+		getSoundPreferences,
+		type SoundPreferences,
+		type SoundPreferencesStore,
+		type SoundQuietMode
+	} from './preferences';
+	import { getSoundPlayer, type SoundId, type SoundPlayer } from './player';
+
+	interface Props {
+		/** Defaults to the app-wide store. */
+		preferences?: SoundPreferencesStore;
+		/** Player used by the preview buttons. Defaults to the app-wide player. */
+		player?: SoundPlayer;
+		/** Which category rows to show (an app without calls hides that row). */
+		categories?: SoundCategory[];
+		/** Show the quiet-hours row. */
+		showQuietHours?: boolean;
+		title?: string;
+		class?: string;
+	}
+
+	let {
+		preferences = getSoundPreferences(),
+		player,
+		categories = [...SOUND_CATEGORIES],
+		showQuietHours = true,
+		title = 'Sounds',
+		class: className = ''
+	}: Props = $props();
+
+	const CATEGORY_COPY: Record<SoundCategory, { label: string; hint: string; preview: SoundId }> = {
+		ui: { label: 'Interface', hint: 'Confirmations, errors and toggles', preview: 'confirm' },
+		notifications: { label: 'Notifications', hint: 'Messages and alerts you didn’t trigger', preview: 'notify' },
+		calls: { label: 'Calls', hint: 'Incoming call ringer — plays even in a background tab', preview: 'incoming-call' }
+	};
+
+	const QUIET_OPTIONS: { value: SoundQuietMode; label: string }[] = [
+		{ value: 'auto', label: 'When my device asks for reduced motion' },
+		{ value: 'on', label: 'Always' },
+		{ value: 'off', label: 'Never' }
+	];
+
+	let prefs = $state<SoundPreferences>(preferences.get());
+	const unsubscribe = preferences.subscribe((p) => (prefs = p));
+	onDestroy(unsubscribe);
+
+	const uid = `sound-settings-${Math.random().toString(36).slice(2, 9)}`;
+	const volumePct = $derived(Math.round(prefs.volume * 100));
+
+	// A preview is capped so a long host ringer file can't keep playing.
+	const PREVIEW_MAX_MS = 3000;
+	let previewing: { stop(): void } | null = null;
+	let previewTimer: ReturnType<typeof setTimeout> | undefined;
+	function stopPreview() {
+		clearTimeout(previewTimer);
+		previewing?.stop();
+		previewing = null;
+	}
+	function preview(name: SoundId) {
+		stopPreview();
+		previewing = (player ?? getSoundPlayer()).play(name, { preview: true, loop: false });
+		previewTimer = setTimeout(stopPreview, PREVIEW_MAX_MS);
+	}
+	onDestroy(stopPreview);
+
+	function setQuietHours(on: boolean) {
+		preferences.set({ quietHours: on ? (prefs.quietHours ?? { start: '22:00', end: '07:00' }) : null });
+	}
+</script>
+
+<fieldset class="flex flex-col gap-4 {className}">
+	<legend class="text-base-content mb-2 text-base font-semibold">{title}</legend>
+
+	<label class="flex cursor-pointer items-center justify-between gap-4">
+		<span>
+			<span class="text-base-content block text-sm font-medium">Play interface &amp; notification sounds</span>
+			<span class="text-base-content/60 block text-xs">Off by default. Calls ring unless muted below. Saved on this device only.</span>
+		</span>
+		<input
+			type="checkbox"
+			class="toggle toggle-primary"
+			checked={prefs.enabled}
+			onchange={(e) => preferences.set({ enabled: e.currentTarget.checked })}
+		/>
+	</label>
+
+	<div class="flex flex-col gap-4">
+		<div class="flex flex-col gap-1">
+			<label for="{uid}-volume" class="text-base-content flex justify-between text-sm font-medium">
+				<span>Volume</span>
+				<span class="text-base-content/60 tabular-nums">{volumePct}%</span>
+			</label>
+			<input
+				id="{uid}-volume"
+				type="range"
+				class="range range-sm range-primary"
+				min="0"
+				max="100"
+				step="5"
+				value={volumePct}
+				aria-valuetext="{volumePct} percent"
+				oninput={(e) => preferences.set({ volume: Number(e.currentTarget.value) / 100 })}
+			/>
+		</div>
+
+		<ul class="flex flex-col gap-3">
+			{#each categories as cat (cat)}
+				{@const copy = CATEGORY_COPY[cat]}
+				{@const gated = cat !== 'calls' && !prefs.enabled}
+				<li class="flex items-center justify-between gap-4" class:opacity-50={gated}>
+					<label class="flex flex-1 cursor-pointer items-center justify-between gap-4">
+						<span>
+							<span class="text-base-content block text-sm font-medium">{copy.label}</span>
+							<span class="text-base-content/60 block text-xs">{copy.hint}</span>
+						</span>
+						<input
+							type="checkbox"
+							class="toggle toggle-sm"
+							checked={prefs.categories[cat]}
+							disabled={gated}
+							onchange={(e) => preferences.setCategory(cat, e.currentTarget.checked)}
+						/>
+					</label>
+					<Button
+						variant="ghost"
+						size="sm"
+						disabled={gated || !prefs.categories[cat]}
+						aria-label="Preview {copy.label} sound"
+						onclick={() => preview(copy.preview)}
+					>
+						▷
+					</Button>
+				</li>
+			{/each}
+		</ul>
+
+		<div class="flex flex-col gap-1" class:opacity-50={!prefs.enabled}>
+			<label for="{uid}-quiet" class="text-base-content text-sm font-medium">
+				Silence interface sounds
+			</label>
+			<select
+				id="{uid}-quiet"
+				class="select select-sm w-full"
+				value={prefs.quiet}
+				disabled={!prefs.enabled}
+				onchange={(e) => preferences.set({ quiet: e.currentTarget.value as SoundQuietMode })}
+			>
+				{#each QUIET_OPTIONS as opt (opt.value)}
+					<option value={opt.value}>{opt.label}</option>
+				{/each}
+			</select>
+			<span class="text-base-content/60 text-xs">Errors still play. Notifications and calls are unaffected.</span>
+		</div>
+
+		{#if showQuietHours}
+			<div class="flex flex-col gap-2" class:opacity-50={!prefs.enabled}>
+				<label class="flex cursor-pointer items-center justify-between gap-4">
+					<span>
+						<span class="text-base-content block text-sm font-medium">Quiet hours</span>
+						<span class="text-base-content/60 block text-xs">Only calls ring inside this window.</span>
+					</span>
+					<input
+						type="checkbox"
+						class="toggle toggle-sm"
+						checked={prefs.quietHours != null}
+						disabled={!prefs.enabled}
+						onchange={(e) => setQuietHours(e.currentTarget.checked)}
+					/>
+				</label>
+				{#if prefs.quietHours}
+					<div class="flex items-center gap-2 text-sm">
+						<label for="{uid}-qs" class="text-base-content/70">From</label>
+						<input
+							id="{uid}-qs"
+							type="time"
+							class="input input-sm w-32"
+							value={prefs.quietHours.start}
+							disabled={!prefs.enabled}
+							onchange={(e) =>
+								e.currentTarget.value &&
+								preferences.set({ quietHours: { start: e.currentTarget.value, end: prefs.quietHours!.end } })}
+						/>
+						<label for="{uid}-qe" class="text-base-content/70">to</label>
+						<input
+							id="{uid}-qe"
+							type="time"
+							class="input input-sm w-32"
+							value={prefs.quietHours.end}
+							disabled={!prefs.enabled}
+							onchange={(e) =>
+								e.currentTarget.value &&
+								preferences.set({ quietHours: { start: prefs.quietHours!.start, end: e.currentTarget.value } })}
+						/>
+					</div>
+				{/if}
+			</div>
+		{/if}
+	</div>
+</fieldset>

package/dist/sound/SoundSettings.svelte.d.ts

@@ -0,0 +1,18 @@
+import { type SoundCategory } from './names';
+import { type SoundPreferencesStore } from './preferences';
+import { type SoundPlayer } from './player';
+interface Props {
+    /** Defaults to the app-wide store. */
+    preferences?: SoundPreferencesStore;
+    /** Player used by the preview buttons. Defaults to the app-wide player. */
+    player?: SoundPlayer;
+    /** Which category rows to show (an app without calls hides that row). */
+    categories?: SoundCategory[];
+    /** Show the quiet-hours row. */
+    showQuietHours?: boolean;
+    title?: string;
+    class?: string;
+}
+declare const SoundSettings: import("svelte").Component<Props, {}, "">;
+type SoundSettings = ReturnType<typeof SoundSettings>;
+export default SoundSettings;

package/dist/sound/backend.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Audio output backend. The player talks to this interface so its policy and
+ * bookkeeping run in node tests with a fake; `createWebAudioBackend` is the
+ * real one (lazy AudioContext, decoded-buffer playback through a GainNode).
+ */
+export interface SoundVoice {
+    stop(): void;
+}
+export interface StartOptions {
+    gain: number;
+    loop: boolean;
+    /** Gap between repeats when looping; 0 = seamless. */
+    loopGapMs: number;
+    /** Playback rate (1 = as recorded; 2 = an octave up and twice as short). */
+    playbackRate?: number;
+    /** Called once when a non-looping voice finishes on its own. */
+    onEnded?: () => void;
+}
+export interface SoundBackend {
+    /** Decode a data URI or URL. Resolves `null` when it can't be played here. */
+    load(src: string): Promise<unknown | null>;
+    start(clip: unknown, options: StartOptions): SoundVoice | null;
+}
+export declare function createWebAudioBackend(): SoundBackend;