@loidolt/theme-svelte 0.5.0 → 0.7.0

package/dist/token-colors.svelte.js

@@ -0,0 +1,165 @@
+import { onDestroy } from 'svelte';
+import { resolveRoles, roleVar, } from '@loidolt/theme-tokens';
+const hex = (value) => Math.round(Math.min(255, Math.max(0, value)))
+    .toString(16)
+    .padStart(2, '0');
+/**
+ * A computed colour as `#rrggbb`, or `#rrggbbaa` when it is translucent. Accepts what browsers
+ * return from `getComputedStyle`: `rgb()`/`rgba()` in either syntax, and `color(srgb …)`, which
+ * is what a `color-mix()` token computes to. Anything else is `null`.
+ */
+export function normalizeColor(value) {
+    const text = value.trim().toLowerCase();
+    if (/^#[0-9a-f]{6}([0-9a-f]{2})?$/.test(text))
+        return text;
+    const rgb = /^rgba?\(([^)]+)\)$/.exec(text);
+    const srgb = /^color\(srgb ([^)]+)\)$/.exec(text);
+    const parts = (rgb?.[1] ?? srgb?.[1])?.split(/[\s,/]+/).filter(Boolean);
+    if (!parts || parts.length < 3)
+        return null;
+    const numbers = parts.map((part) => part.endsWith('%') ? Number.parseFloat(part) / 100 : Number(part));
+    if (numbers.some((number) => !Number.isFinite(number)))
+        return null;
+    const channels = numbers.slice(0, 3).map((number, index) => 
+    // `rgb()` channels are 0–255 unless written as percentages; `color(srgb)` channels are 0–1.
+    srgb || parts[index].endsWith('%') ? number * 255 : number);
+    const alpha = numbers.length > 3 ? numbers[3] : 1;
+    const base = `#${channels.map(hex).join('')}`;
+    return alpha >= 1 ? base : `${base}${hex(alpha * 255)}`;
+}
+/**
+ * Reads one role's live value from the page, as the element would paint it — so a scoped
+ * `[data-theme]` subtree or an app's own overrides are honoured. `null` when the environment
+ * cannot say (the server, or a DOM without custom-property support such as jsdom).
+ */
+export function readRoleColor(element, role) {
+    const view = element.ownerDocument?.defaultView;
+    if (!view)
+        return null;
+    const probe = element.ownerDocument.createElement('span');
+    probe.hidden = true;
+    probe.style.color = `var(${roleVar(role)})`;
+    element.appendChild(probe);
+    try {
+        return normalizeColor(view.getComputedStyle(probe).color);
+    }
+    finally {
+        probe.remove();
+    }
+}
+/**
+ * Which theme an element is in: an explicit `data-theme` on it or an ancestor wins, then the
+ * computed `color-scheme` (which the dark stylesheets set, including the system-following one).
+ */
+export function colorSchemeOf(element) {
+    if (!element)
+        return 'light';
+    const explicit = element.closest('[data-theme]')?.getAttribute('data-theme');
+    if (explicit === 'dark' || explicit === 'light')
+        return explicit;
+    const view = element.ownerDocument?.defaultView;
+    const computed = view?.getComputedStyle(element).colorScheme ?? '';
+    return /\bdark\b/.test(computed) && !/\blight\b/.test(computed) ? 'dark' : 'light';
+}
+// eslint-disable-next-line svelte/prefer-svelte-reactivity -- subscriber bookkeeping, never rendered
+const listeners = new Set();
+let teardown;
+/** One set of observers for the whole page, however many charts and maps are listening. */
+function subscribe(listener) {
+    listeners.add(listener);
+    if (!teardown && typeof document !== 'undefined') {
+        let queued = false;
+        const notify = () => {
+            if (queued)
+                return;
+            queued = true;
+            queueMicrotask(() => {
+                queued = false;
+                for (const each of [...listeners])
+                    each();
+            });
+        };
+        const root = document.documentElement;
+        const scoped = new MutationObserver(notify);
+        // A theme can be scoped to any subtree, so `data-theme` is watched everywhere; `class` and
+        // `style` only on the root, where apps toggle theme classes and inline overrides.
+        scoped.observe(root, { attributes: true, attributeFilter: ['data-theme'], subtree: true });
+        const rootObserver = new MutationObserver(notify);
+        rootObserver.observe(root, { attributes: true, attributeFilter: ['class', 'style'] });
+        const media = typeof window.matchMedia === 'function'
+            ? window.matchMedia('(prefers-color-scheme: dark)')
+            : undefined;
+        media?.addEventListener('change', notify);
+        teardown = () => {
+            scoped.disconnect();
+            rootObserver.disconnect();
+            media?.removeEventListener('change', notify);
+            teardown = undefined;
+        };
+    }
+    return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0)
+            teardown?.();
+    };
+}
+/**
+ * Calls `callback` whenever the page's colour scheme may have changed: a `data-theme` anywhere,
+ * a class or inline style on `<html>`, or the system preference. Returns the unsubscribe.
+ */
+export function observeColorScheme(callback) {
+    return subscribe(callback);
+}
+/**
+ * Semantic token values for renderers that cannot read CSS — a chart canvas, a WebGL map. Reads
+ * the live values off the page, so an app's own theme reaches the canvas, and follows theme
+ * changes. On the server, and wherever values cannot be read, it falls back to the reference
+ * light or dark theme.
+ *
+ * ```ts
+ * const palette = createTokenColors({ series: ['chart1', 'chart2'], ink: 'text' }, { element: () => node });
+ * $effect(() => chart?.setOption(build(palette.colors)));
+ * ```
+ */
+export function createTokenColors(spec, options = {}) {
+    const target = () => options.element?.() ?? (typeof document === 'undefined' ? undefined : document.documentElement);
+    const compute = () => {
+        const element = target();
+        const scheme = colorSchemeOf(element);
+        const read = (role) => (element && readRoleColor(element, role)) || resolveRoles({ role }, scheme).role;
+        return { scheme, colors: resolveRoles(spec, scheme, read) };
+    };
+    const initial = compute();
+    let colors = $state.raw(initial.colors);
+    let scheme = $state(initial.scheme);
+    let version = $state(0);
+    const refresh = () => {
+        const next = compute();
+        scheme = next.scheme;
+        if (JSON.stringify(next.colors) === JSON.stringify(colors))
+            return;
+        colors = next.colors;
+        version += 1;
+    };
+    const unsubscribe = subscribe(refresh);
+    const destroy = () => unsubscribe();
+    try {
+        onDestroy(destroy);
+    }
+    catch {
+        /* module scope: the caller owns `destroy()` */
+    }
+    return {
+        get colors() {
+            return colors;
+        },
+        get scheme() {
+            return scheme;
+        },
+        get version() {
+            return version;
+        },
+        refresh,
+        destroy,
+    };
+}

package/dist/types.d.ts

@@ -5,9 +5,10 @@ export type ActionVariant = 'default' | 'primary' | 'quiet' | 'danger' | 'ghost'
 export type StatusVariant = 'info' | 'success' | 'warning' | 'error';
 /** Badge spans both sets: neutral, brand accent, or a status. */
 export type BadgeVariant = 'default' | 'accent' | StatusVariant;
-/** Shared control scale. Dialogs extend it with `xl`. */
+/** Shared control scale. Dialogs extend it with `xl` and `full`. */
 export type ControlSize = 'sm' | 'md' | 'lg';
-export type DialogSize = ControlSize | 'xl';
+/** `full` takes the viewport less a gutter — for editors and previews that need the room. */
+export type DialogSize = ControlSize | 'xl' | 'full';
 /**
  * Badges default to `inline`: a compact chip sized to the text it annotates, for table cells and
  * running copy. The `ControlSize` steps match the button scale so a badge standing in a row of
@@ -28,6 +29,17 @@ export interface Option<T extends string = string> {
     label: string;
     disabled?: boolean;
 }
+/** A labelled run of options: an `<optgroup>` in `Select`, a group heading in list popups. */
+export interface OptionGroup<T extends string = string> {
+    label: string;
+    options: Option<T>[];
+    /** Disables every option in the group. */
+    disabled?: boolean;
+}
+/** An option with a secondary line, for choices that need a sentence of explanation. */
+export interface ChoiceOption<T extends string = string> extends Option<T> {
+    description?: string;
+}
 /** `Option` is the single vocabulary for choice lists; `NavItem` is kept as a readable alias. */
 export type NavItem<T extends string = string> = Option<T>;
 /** One step in a breadcrumb trail. The final crumb is the current page and takes no `href`. */
@@ -43,14 +55,61 @@ export interface Disclosure<T extends string = string> {
 }
 /** A `DropdownMenu` row. Renders as a link when `href` is set. */
 export interface MenuItem<T extends string = string> extends Option<T> {
+    type?: 'item';
     href?: string;
-    /** Trailing hint, e.g. a keyboard shortcut. */
+    /** Trailing hint. Defaults to `shortcut` when that is set. */
     hint?: string;
+    /**
+     * The keyboard shortcut this action also has elsewhere in the app, in `aria-keyshortcuts`
+     * syntax (`'Control+D'`). Announced with the item and shown as its hint. The menu does not
+     * bind the key — your app does.
+     */
+    shortcut?: string;
+    /** Styles the row as destructive. Pair it with a confirmation for anything irreversible. */
+    destructive?: boolean;
     /** Leading visual. */
     icon?: Snippet;
     /** Draw a separator above this item. */
     separatorBefore?: boolean;
 }
+/** Rows under an optional heading, announced as one group. */
+export interface MenuGroup<T extends string = string> {
+    type: 'group';
+    label?: string;
+    items: MenuEntry<T>[];
+    separatorBefore?: boolean;
+}
+/** A toggle that stays in the menu, e.g. "Show grid". Reported through `onCheckedChange`. */
+export interface MenuCheckboxItem<T extends string = string> {
+    type: 'checkbox';
+    value: T;
+    label: string;
+    checked: boolean;
+    disabled?: boolean;
+    hint?: string;
+    separatorBefore?: boolean;
+}
+/** A one-of-many choice inside a menu, e.g. a sort order. Reported through `onValueChange`. */
+export interface MenuRadioGroup<T extends string = string> {
+    type: 'radio';
+    /** Identifies the group in `onValueChange`. */
+    name: string;
+    label?: string;
+    value: T | '';
+    options: Option<T>[];
+    separatorBefore?: boolean;
+}
+/** A nested menu that opens beside its row. */
+export interface MenuSub<T extends string = string> {
+    type: 'sub';
+    label: string;
+    icon?: Snippet;
+    disabled?: boolean;
+    items: MenuEntry<T>[];
+    separatorBefore?: boolean;
+}
+/** Anything `DropdownMenu`'s `items` can hold. A plain `MenuItem` needs no `type`. */
+export type MenuEntry<T extends string = string> = MenuItem<T> | MenuGroup<T> | MenuCheckboxItem<T> | MenuRadioGroup<T> | MenuSub<T>;
 /**
  * Payload of Bits UI's `child` snippet: spread `props` onto your own element to take over
  * rendering of a trigger without nesting an extra button inside it.

package/dist/utils.d.ts

@@ -3,3 +3,12 @@
  * Accepts the `class` prop of any component in this package.
  */
 export declare function cx(...values: Array<string | false | null | undefined>): string;
+/**
+ * Joins the ids of the elements that describe a control into one `aria-describedby` value, or
+ * `undefined` when there are none — an empty attribute is still an attribute.
+ *
+ * ```svelte
+ * <input aria-describedby={describedBy(hint && hintId, error && errorId)} />
+ * ```
+ */
+export declare function describedBy(...ids: Array<string | false | null | undefined>): string | undefined;

package/dist/utils.js

@@ -5,3 +5,14 @@
 export function cx(...values) {
     return values.filter(Boolean).join(' ');
 }
+/**
+ * Joins the ids of the elements that describe a control into one `aria-describedby` value, or
+ * `undefined` when there are none — an empty attribute is still an attribute.
+ *
+ * ```svelte
+ * <input aria-describedby={describedBy(hint && hintId, error && errorId)} />
+ * ```
+ */
+export function describedBy(...ids) {
+    return ids.filter(Boolean).join(' ') || undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loidolt/theme-svelte",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Accessible Svelte 5 components for Loidolt applications",
   "license": "MIT",
   "type": "module",
@@ -31,12 +31,18 @@
     "clean": "rimraf dist"
   },
   "dependencies": {
-    "@loidolt/theme-styles": "^0.5.0",
-    "@loidolt/theme-tokens": "^0.5.0",
+    "@loidolt/theme-styles": "^0.7.0",
+    "@loidolt/theme-tokens": "^0.7.0",
     "bits-ui": "^2.19.0"
   },
   "peerDependencies": {
-    "svelte": "^5.33.0"
+    "svelte": "^5.33.0",
+    "hls.js": "^1.5.0"
+  },
+  "peerDependenciesMeta": {
+    "hls.js": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.13.0",