@joewinke/jatui 0.15.0 → 0.17.0

package/dist/video/settings/SettingsPanel.svelte

@@ -0,0 +1,414 @@
+<script module lang="ts">
+	let nextId = 0;
+</script>
+
+<script lang="ts">
+	/**
+	 * The VideoPlayer settings panel (mos-5lzns.35) — extension-library's
+	 * `openSettings()` ported. Generated wholly from `VIDEO_SETTINGS` via
+	 * `panelGroups`: every row is a label, one control, and the sentence saying
+	 * what the thing does. The sentence is not decoration — it is the reason
+	 * this screen exists rather than a list of switches.
+	 *
+	 * Keyboard: focus lands on the first control and Tab cycles inside the
+	 * dialog; Esc (or `,`) closes and hands focus back. Controls follow the
+	 * ARIA APG patterns — a switch, a radio group (arrows move the choice), a
+	 * native range. It is a FORM, not a list: arrow keys belong to the
+	 * controls (a range and a radio group both need them), so there is no
+	 * row-level listNav to fight them.
+	 *
+	 * Values are live, not on close: these are things you judge by watching
+	 * the result, so the result has to move while you drag.
+	 *
+	 * Token-only chrome; the only motion (a short fade) is dropped under
+	 * prefers-reduced-motion.
+	 */
+	import { onMount } from 'svelte';
+	import type { SettingSpec, SettingValue } from './registry';
+	import { formatSettingValue, stepOption, type SettingsPanelGroup } from './panel';
+
+	let {
+		groups,
+		values,
+		onchange,
+		onclose,
+		helpHref = null,
+		persisted = false
+	}: {
+		groups: SettingsPanelGroup[];
+		/** Effective value per id — what the player is doing right now. */
+		values: Record<string, SettingValue>;
+		onchange: (id: string, value: SettingValue) => void;
+		onclose: () => void;
+		/** A host help page explaining all of this ("How all of this works →"). */
+		helpHref?: string | null;
+		/** The host supplied a store — the footer says choices are remembered. */
+		persisted?: boolean;
+	} = $props();
+
+	const uid = `vp-set-${++nextId}`;
+	let cardEl: HTMLDivElement | undefined = $state();
+
+	function rowId(spec: SettingSpec) {
+		return `${uid}-${spec.id.replace(/[^a-z0-9]/gi, '-')}`;
+	}
+
+	function focusables(): HTMLElement[] {
+		if (!cardEl) return [];
+		return Array.from(
+			cardEl.querySelectorAll<HTMLElement>('button:not([tabindex="-1"]), input, a[href]')
+		).filter((el) => !el.hasAttribute('disabled'));
+	}
+
+	onMount(() => {
+		const first = cardEl?.querySelector<HTMLElement>('.vp-set-control button:not([tabindex="-1"]), .vp-set-control input');
+		(first ?? cardEl)?.focus();
+	});
+
+	function onKeyDown(e: KeyboardEvent) {
+		// The player's own shortcuts must not fire from inside the dialog
+		// (Space on a switch would also play/pause).
+		e.stopPropagation();
+		if (e.key === 'Escape' || (e.key === ',' && (e.target as HTMLElement)?.tagName !== 'INPUT')) {
+			e.preventDefault();
+			onclose();
+			return;
+		}
+		if (e.key === 'Tab') {
+			const els = focusables();
+			if (!els.length) return;
+			const i = els.indexOf(document.activeElement as HTMLElement);
+			const next = e.shiftKey ? (i <= 0 ? els.length - 1 : i - 1) : i === els.length - 1 ? 0 : i + 1;
+			e.preventDefault();
+			els[next].focus();
+		}
+	}
+
+	function onRadioKey(e: KeyboardEvent, spec: SettingSpec) {
+		const dir = e.key === 'ArrowRight' || e.key === 'ArrowDown' ? 1 : e.key === 'ArrowLeft' || e.key === 'ArrowUp' ? -1 : 0;
+		if (!dir) return;
+		e.preventDefault();
+		const next = stepOption(spec, values[spec.id], dir);
+		if (next === undefined) return;
+		onchange(spec.id, next);
+		const group = (e.currentTarget as HTMLElement).closest('[role="radiogroup"]');
+		queueMicrotask(() => group?.querySelector<HTMLElement>(`[data-value="${next}"]`)?.focus());
+	}
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_static_element_interactions -->
+<div class="vp-set-backdrop" onclick={(e) => { if (e.target === e.currentTarget) onclose(); }}>
+	<div
+		class="vp-set"
+		role="dialog"
+		aria-modal="true"
+		aria-labelledby="{uid}-title"
+		tabindex="-1"
+		bind:this={cardEl}
+		onkeydown={onKeyDown}
+	>
+		<div class="vp-set-head">
+			<h2 class="vp-set-title" id="{uid}-title">Settings</h2>
+			<button type="button" class="vp-set-close" aria-label="Close settings" onclick={onclose}>
+				<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+					<path d="M6 6l12 12M18 6 6 18" />
+				</svg>
+			</button>
+		</div>
+
+		<div class="vp-set-body">
+			{#each groups as g (g.group)}
+				<section class="vp-set-group" aria-labelledby="{uid}-g-{g.group}">
+					<h3 class="vp-set-group-title" id="{uid}-g-{g.group}">{g.group}</h3>
+					{#each g.rows as spec (spec.id)}
+						{@const id = rowId(spec)}
+						{@const value = values[spec.id] ?? spec.default}
+						<div class="vp-set-row" data-setting={spec.id}>
+							<span class="vp-set-label" id="{id}-label">{spec.label}</span>
+							<div class="vp-set-control">
+								{#if spec.type === 'bool'}
+									<button
+										type="button"
+										class="vp-set-switch"
+										role="switch"
+										aria-checked={value === true}
+										aria-labelledby="{id}-label"
+										aria-describedby="{id}-hint"
+										onclick={() => onchange(spec.id, value !== true)}
+									>
+										<span class="vp-set-knob" aria-hidden="true"></span>
+										<span class="vp-set-switch-text">{value === true ? 'On' : 'Off'}</span>
+									</button>
+								{:else if spec.type === 'enum'}
+									<div
+										class="vp-set-seg"
+										role="radiogroup"
+										aria-labelledby="{id}-label"
+										aria-describedby="{id}-hint"
+									>
+										{#each spec.options ?? [] as opt (opt.value)}
+											<button
+												type="button"
+												role="radio"
+												data-value={opt.value}
+												aria-checked={value === opt.value}
+												tabindex={value === opt.value ? 0 : -1}
+												onclick={() => onchange(spec.id, opt.value)}
+												onkeydown={(e) => onRadioKey(e, spec)}
+											>
+												{opt.label}
+											</button>
+										{/each}
+									</div>
+								{:else}
+									<input
+										type="range"
+										class="vp-set-range"
+										min={spec.min}
+										max={spec.max}
+										step={spec.step}
+										value={value}
+										aria-labelledby="{id}-label"
+										aria-describedby="{id}-hint"
+										aria-valuetext={formatSettingValue(spec, value)}
+										oninput={(e) => onchange(spec.id, Number((e.currentTarget as HTMLInputElement).value))}
+									/>
+									<span class="vp-set-value" aria-hidden="true">{formatSettingValue(spec, value)}</span>
+								{/if}
+							</div>
+							<p class="vp-set-hint" id="{id}-hint">{spec.hint}</p>
+						</div>
+					{/each}
+				</section>
+			{:else}
+				<p class="vp-set-empty">Nothing on this video can be adjusted yet — settings appear as the features they control arrive.</p>
+			{/each}
+		</div>
+
+		<div class="vp-set-foot">
+			<span>{persisted ? 'Your choices are remembered.' : 'Choices last while this player is open.'} Esc closes.</span>
+			{#if helpHref}
+				<a class="vp-set-help" href={helpHref}>How all of this works →</a>
+			{/if}
+		</div>
+	</div>
+</div>
+
+<style>
+	.vp-set-backdrop {
+		position: absolute;
+		inset: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		padding: var(--jatui-space-lg, 12px);
+		background: color-mix(in oklch, var(--color-base-100) 70%, transparent);
+		z-index: 11;
+		border-radius: inherit;
+		animation: vp-set-in var(--motion-quick, 150ms) var(--motion-glide, ease-out);
+	}
+
+	.vp-set {
+		width: min(28rem, 100%);
+		max-height: 100%;
+		display: flex;
+		flex-direction: column;
+		background: var(--color-base-100);
+		color: var(--color-base-content);
+		border: var(--jatui-border-w, 1px) solid color-mix(in oklch, var(--color-base-content) 18%, transparent);
+		border-radius: var(--jatui-radius-box, 0.5rem);
+		box-shadow: 0 8px 30px color-mix(in oklch, var(--color-base-content) 25%, transparent);
+		outline: none;
+	}
+
+	.vp-set-head {
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		padding: var(--jatui-space-md, 6px) var(--jatui-space-lg, 12px);
+		border-bottom: var(--jatui-border-w, 1px) solid color-mix(in oklch, var(--color-base-content) 10%, transparent);
+	}
+
+	.vp-set-title {
+		margin: 0;
+		font-size: 0.85rem;
+		font-weight: 700;
+	}
+
+	.vp-set-close {
+		display: inline-flex;
+		padding: var(--jatui-space-xs, 2px);
+		background: none;
+		border: none;
+		color: inherit;
+		border-radius: var(--jatui-radius-field, 0.25rem);
+		cursor: pointer;
+	}
+
+	.vp-set-body {
+		overflow-y: auto;
+		padding: var(--jatui-space-sm, 4px) var(--jatui-space-lg, 12px) var(--jatui-space-md, 6px);
+	}
+
+	.vp-set-group-title {
+		margin: var(--jatui-space-md, 6px) 0 var(--jatui-space-xs, 2px);
+		font-size: 0.66rem;
+		font-weight: 700;
+		text-transform: uppercase;
+		letter-spacing: 0.04em;
+		color: color-mix(in oklch, var(--color-base-content) 55%, transparent);
+	}
+
+	.vp-set-row {
+		display: grid;
+		grid-template-columns: minmax(0, 1fr) auto;
+		align-items: center;
+		gap: var(--jatui-space-xs, 2px) var(--jatui-space-md, 6px);
+		padding: var(--jatui-space-sm, 4px) 0;
+		border-top: var(--jatui-border-w, 1px) solid color-mix(in oklch, var(--color-base-content) 6%, transparent);
+	}
+
+	.vp-set-group-title + .vp-set-row {
+		border-top: none;
+	}
+
+	.vp-set-label {
+		font-size: 0.78rem;
+		font-weight: 600;
+	}
+
+	.vp-set-control {
+		display: flex;
+		align-items: center;
+		gap: var(--jatui-space-sm, 4px);
+	}
+
+	.vp-set-hint {
+		grid-column: 1 / -1;
+		margin: 0;
+		font-size: 0.7rem;
+		line-height: 1.4;
+		color: color-mix(in oklch, var(--color-base-content) 68%, transparent);
+	}
+
+	/* Switch: the state reads in text AND position, never colour alone. */
+	.vp-set-switch {
+		display: inline-flex;
+		align-items: center;
+		gap: var(--jatui-space-sm, 4px);
+		padding: 2px var(--jatui-space-sm, 4px) 2px 2px;
+		font: inherit;
+		font-size: 0.7rem;
+		color: inherit;
+		background: color-mix(in oklch, var(--color-base-content) 10%, transparent);
+		border: var(--jatui-border-w, 1px) solid color-mix(in oklch, var(--color-base-content) 20%, transparent);
+		border-radius: 999px;
+		cursor: pointer;
+	}
+
+	.vp-set-knob {
+		width: 0.8rem;
+		height: 0.8rem;
+		border-radius: 999px;
+		background: color-mix(in oklch, var(--color-base-content) 45%, transparent);
+		transition: transform var(--motion-quick, 150ms) var(--motion-glide, ease-out);
+	}
+
+	.vp-set-switch[aria-checked='true'] {
+		background: color-mix(in oklch, var(--color-primary) 22%, transparent);
+		border-color: color-mix(in oklch, var(--color-primary) 55%, transparent);
+	}
+
+	.vp-set-switch[aria-checked='true'] .vp-set-knob {
+		background: var(--color-primary);
+		transform: translateX(0.15rem);
+	}
+
+	.vp-set-switch-text {
+		min-width: 1.6em;
+		text-align: left;
+	}
+
+	.vp-set-seg {
+		display: inline-flex;
+		border: var(--jatui-border-w, 1px) solid color-mix(in oklch, var(--color-base-content) 20%, transparent);
+		border-radius: var(--jatui-radius-field, 0.25rem);
+		overflow: hidden;
+	}
+
+	.vp-set-seg button {
+		padding: 2px var(--jatui-space-md, 6px);
+		font: inherit;
+		font-size: 0.7rem;
+		color: inherit;
+		background: none;
+		border: none;
+		cursor: pointer;
+	}
+
+	.vp-set-seg button + button {
+		border-left: var(--jatui-border-w, 1px) solid color-mix(in oklch, var(--color-base-content) 20%, transparent);
+	}
+
+	.vp-set-seg button[aria-checked='true'] {
+		background: color-mix(in oklch, var(--color-primary) 22%, transparent);
+		font-weight: 700;
+	}
+
+	.vp-set-range {
+		width: 7rem;
+		accent-color: var(--color-primary);
+	}
+
+	.vp-set-value {
+		min-width: 3.2em;
+		font-size: 0.7rem;
+		font-variant-numeric: tabular-nums;
+		text-align: right;
+	}
+
+	.vp-set-switch:focus-visible,
+	.vp-set-seg button:focus-visible,
+	.vp-set-range:focus-visible,
+	.vp-set-close:focus-visible,
+	.vp-set-help:focus-visible {
+		outline: 2px solid var(--color-primary);
+		outline-offset: 1px;
+	}
+
+	.vp-set-empty {
+		margin: var(--jatui-space-md, 6px) 0;
+		font-size: 0.75rem;
+		color: color-mix(in oklch, var(--color-base-content) 68%, transparent);
+	}
+
+	.vp-set-foot {
+		display: flex;
+		flex-wrap: wrap;
+		justify-content: space-between;
+		gap: var(--jatui-space-sm, 4px);
+		padding: var(--jatui-space-md, 6px) var(--jatui-space-lg, 12px);
+		font-size: 0.66rem;
+		color: color-mix(in oklch, var(--color-base-content) 60%, transparent);
+		border-top: var(--jatui-border-w, 1px) solid color-mix(in oklch, var(--color-base-content) 10%, transparent);
+	}
+
+	.vp-set-help {
+		color: var(--color-primary);
+	}
+
+	@keyframes vp-set-in {
+		from {
+			opacity: 0;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.vp-set-backdrop {
+			animation: none;
+		}
+		.vp-set-knob {
+			transition: none;
+		}
+	}
+</style>

package/dist/video/settings/SettingsPanel.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { SettingValue } from './registry';
+import { type SettingsPanelGroup } from './panel';
+type $$ComponentProps = {
+    groups: SettingsPanelGroup[];
+    /** Effective value per id — what the player is doing right now. */
+    values: Record<string, SettingValue>;
+    onchange: (id: string, value: SettingValue) => void;
+    onclose: () => void;
+    /** A host help page explaining all of this ("How all of this works →"). */
+    helpHref?: string | null;
+    /** The host supplied a store — the footer says choices are remembered. */
+    persisted?: boolean;
+};
+declare const SettingsPanel: import("svelte").Component<$$ComponentProps, {}, "">;
+type SettingsPanel = ReturnType<typeof SettingsPanel>;
+export default SettingsPanel;

package/dist/video/settings/panel.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The settings panel's model (mos-5lzns.35) — pure, so what the panel shows
+ * is node-testable without a DOM. The component renders exactly what these
+ * return; nothing about which rows exist is decided in markup.
+ */
+import { type SettingAvailability, type SettingSpec, type SettingValue } from './registry';
+export interface SettingsPanelGroup {
+    group: string;
+    rows: SettingSpec[];
+}
+/**
+ * The rows this player can honestly offer, grouped in panel order. A row
+ * whose `when` is not true in `available` is omitted — never shown disabled:
+ * a switch for a feature this player doesn't have is noise, and a disabled
+ * one invites the question it can't answer.
+ */
+export declare function panelGroups(available: SettingAvailability, specs?: SettingSpec[]): SettingsPanelGroup[];
+/** How a value reads in the panel (the range's readout, an enum's label, On/Off). */
+export declare function formatSettingValue(spec: SettingSpec, value: SettingValue): string;
+/**
+ * Radio-group arrow keys: the next option in `dir`, wrapping (APG radio
+ * pattern). An unknown current value starts from the first option.
+ */
+export declare function stepOption(spec: SettingSpec, current: SettingValue, dir: 1 | -1): string | undefined;

package/dist/video/settings/panel.js

@@ -0,0 +1,58 @@
+/**
+ * The settings panel's model (mos-5lzns.35) — pure, so what the panel shows
+ * is node-testable without a DOM. The component renders exactly what these
+ * return; nothing about which rows exist is decided in markup.
+ */
+import { SETTING_GROUPS, VIDEO_SETTINGS } from './registry';
+/**
+ * The rows this player can honestly offer, grouped in panel order. A row
+ * whose `when` is not true in `available` is omitted — never shown disabled:
+ * a switch for a feature this player doesn't have is noise, and a disabled
+ * one invites the question it can't answer.
+ */
+export function panelGroups(available, specs = VIDEO_SETTINGS) {
+    const order = [...SETTING_GROUPS];
+    for (const s of specs)
+        if (!order.includes(s.group))
+            order.push(s.group);
+    const out = [];
+    for (const group of order) {
+        const rows = specs.filter((s) => s.group === group && s.wired !== false && available[s.when] === true);
+        if (rows.length)
+            out.push({ group, rows });
+    }
+    return out;
+}
+/** How a value reads in the panel (the range's readout, an enum's label, On/Off). */
+export function formatSettingValue(spec, value) {
+    try {
+        if (spec.type === 'bool')
+            return value ? 'On' : 'Off';
+        if (spec.type === 'enum')
+            return spec.options?.find((o) => o.value === value)?.label ?? String(value);
+        const n = typeof value === 'number' ? value : Number(value);
+        if (!Number.isFinite(n))
+            return '';
+        // Round to the step so 0.30000000000000004 never reaches the screen.
+        const step = spec.step && spec.step > 0 ? spec.step : 0;
+        const decimals = step ? Math.max(0, Math.min(6, (String(step).split('.')[1] ?? '').length)) : 2;
+        const shown = Number(n.toFixed(decimals));
+        return spec.format ? spec.format(shown) : String(shown);
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Radio-group arrow keys: the next option in `dir`, wrapping (APG radio
+ * pattern). An unknown current value starts from the first option.
+ */
+export function stepOption(spec, current, dir) {
+    const opts = spec.options ?? [];
+    if (!opts.length)
+        return undefined;
+    const i = opts.findIndex((o) => o.value === current);
+    if (i < 0)
+        return opts[0].value;
+    return opts[(i + dir + opts.length) % opts.length].value;
+}

package/dist/video/settings/registry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The settings registry (mos-5lzns.35) — extension-library's `settings.js`
+ * ported: one array declares every standing CHOICE the player's automatic
+ * behaviours read, and the settings panel is generated from it, so a knob
+ * added here shows up in the UI by existing.
+ *
+ * Three rules carried over verbatim:
+ *
+ * · `coerce` never throws and never returns junk. A bool accepts
+ *   true/"1"/"true" (and their false twins); a range parses and clamps to
+ *   [min, max]; an enum must match a declared option. Anything else returns
+ *   undefined and the caller falls back to the default. A corrupted blob in
+ *   a host's store degrades to defaults, never to a broken player.
+ * · The hint is mandatory. The sentence saying what the thing actually does
+ *   is the entire reason a settings screen exists rather than a list of
+ *   switches; a spec without one fails the unit suite.
+ * · A knob lands WITH its reader. `wired: true` means the `prop` it names is
+ *   read by VideoPlayer today — a switch that visibly does nothing is the
+ *   one thing this registry must never contain. (That is why the extension's
+ *   `night.page`, `night.sunset` and `player.smartSpeedBoost` are absent: the
+ *   player has no reader for them.)
+ *
+ * Labels and hints here are the single source for the panel AND any help
+ * page a host renders (MOS's /help reads `VIDEO_SETTINGS` directly) — never
+ * restate them elsewhere.
+ *
+ * Ephemeral UI state (transcript layout, volume, whether a pane was left
+ * open) is deliberately NOT here: remembering those is not the same thing as
+ * being configurable, and mixing them makes a settings screen that reads
+ * like a debug dump.
+ */
+export type SettingType = 'bool' | 'range' | 'enum';
+export type SettingValue = boolean | number | string;
+/**
+ * When a row exists on a given player. Each names the host opt-in and/or
+ * data the feature needs — a row for a feature this player doesn't have is
+ * a switch that does nothing. The component resolves them (see
+ * `SettingAvailability`); the registry only names them.
+ */
+export type SettingWhen = 'waveform' | 'speakers' | 'ads' | 'loudness' | 'quiet' | 'limiter' | 'night' | 'nightLuma' | 'flashes' | 'windDown' | 'idle' | 'resume' | 'open';
+export type SettingAvailability = Partial<Record<SettingWhen, boolean>>;
+export interface SettingOption {
+    value: string;
+    label: string;
+}
+export interface SettingSpec {
+    /** Stable storage key — a host's store is keyed by this. Never rename. */
+    id: string;
+    type: SettingType;
+    default: SettingValue;
+    /** Panel section heading. Rows keep registry order within their group. */
+    group: string;
+    /** The row's name. Short, a noun phrase or an imperative. */
+    label: string;
+    /** What it actually does, in one or two sentences. Mandatory. */
+    hint: string;
+    /** The VideoPlayer prop this choice drives. */
+    prop: string;
+    /** Availability gate (see `SettingWhen`). */
+    when: SettingWhen;
+    /** range only */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** range only: how the current value reads next to the slider. */
+    format?: (v: number) => string;
+    /** enum only */
+    options?: SettingOption[];
+    /** Which sub-task wired the reader. */
+    owner: string;
+    /** The reader exists (grep VideoPlayer for `prop`). */
+    wired?: boolean;
+}
+/** Groups in panel order. */
+export declare const SETTING_GROUPS: readonly ["Night", "Sound", "Wind-down", "Playback"];
+export declare const VIDEO_SETTINGS: SettingSpec[];
+/** The spec for an id, or undefined. */
+export declare function settingSpec(id: string): SettingSpec | undefined;
+/** Coerce a raw stored value against a spec — never throws, never returns junk. */
+export declare function coerce<T extends SettingSpec>(spec: T, raw: unknown): T['default'] | undefined;
+/** A stored value for an id, coerced; the spec's default when absent or junk. */
+export declare function settingValue(id: string, raw: unknown): SettingValue | undefined;