@fusion.dev/helix-core 0.56.1 → 0.58.0

package/dist/controllers/cue-controller/cue-controller.d.ts

@@ -0,0 +1,85 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** One caption track, named as the menu names it. */
+export interface Caption {
+    label: string;
+    language: string;
+}
+/** A `<track>` as the consumer wrote it, reduced to what naming it needs. */
+interface TrackCopy {
+    attrs: Record<string, string>;
+    tag: string;
+}
+/**
+ * The tracks a reader could choose between, in the order they were written.
+ *
+ * Filtered by kind, because `textTracks` also carries `chapters`, `metadata`
+ * and `descriptions`, and a menu offering "Chapters" as a subtitle language
+ * would be offering something that draws no words. Read off the media element
+ * rather than off the slot: a `<track>` added later is in one and not the
+ * other, and the element is the one that has resolved them.
+ */
+export declare const captionTracks: (media: HTMLMediaElement | null) => TextTrack[];
+/**
+ * Shows one track and disables every other, or shows none at `-1`.
+ *
+ * Every other, rather than only the one that was on. Two tracks in `hidden`
+ * both fire `cuechange`, so the rendered cue becomes whichever fired last and
+ * a reader who switched language gets the two interleaved. Measured as two
+ * subtitles alternating line by line.
+ *
+ * `hidden`, never `showing`. Hidden is the mode where a track still fires
+ * `cuechange` and still fills `activeCues`, and the browser draws nothing,
+ * which is exactly what is wanted when something else is doing the drawing.
+ */
+export declare const showCaption: (tracks: readonly TextTrack[], index: number) => void;
+/**
+ * Whether a track the platform started showing is now ours to draw.
+ *
+ * A `<track default>` arrives `showing`, which is the browser drawing it.
+ * Moved to `hidden` so the cues keep coming and we draw them instead. What
+ * comes back is whether captions are on, which is not always "off": a button
+ * that began there reported the opposite of what was on screen.
+ */
+export declare const adoptTrack: (track: TextTrack) => boolean;
+/**
+ * The caption tracks among the copies, before the render that draws them.
+ *
+ * By the platform's own reading of `kind`, which is what makes a `<track>` a
+ * caption at all: missing is `subtitles` and anything it does not know is
+ * `metadata`. Read from the video's tracks after the render instead, the count
+ * arrived a render late and asked for one more. Choosing one still goes
+ * through the video's tracks, which hold them in the same order.
+ */
+export declare const captionsAmong: (media: readonly TrackCopy[]) => Caption[];
+/**
+ * The cue on screen now, as nodes, or nothing between cues.
+ *
+ * Nodes rather than a string, because `VTTCue.text` is the cue's *source*:
+ * WebVTT carries markup, and a caption file in the wild is full of it. `<v
+ * Hildy>` names who is speaking, `<b>` and `<i>` and `<u>` mark emphasis, and
+ * `<c.loud>` classes a line. Rendered as text every one of those arrives on
+ * screen as visible angle brackets.
+ *
+ * `getCueAsHTML` is the platform parsing its own format, so nothing here has
+ * to know the grammar and no cue text is ever treated as HTML: what comes
+ * back is a fragment the browser built, not a string anybody interpolated.
+ */
+export declare const activeCue: (track: TextTrack | undefined) => DocumentFragment | undefined;
+/**
+ * Listens to one track's cues at a time, so the next one can take it off.
+ *
+ * Taken off whatever it was on before adding it here. `follow` runs from
+ * `loadedmetadata`, which fires again for every source a reader moves to, and
+ * a consumer adding a `<track>` later gets another. Added without removing, a
+ * playlist of six left six listeners on tracks that between them fire for
+ * every cue in the video.
+ */
+export declare class CueController implements ReactiveController {
+    private readonly listener;
+    private track;
+    constructor(host: ReactiveControllerHost, listener: () => void);
+    follow(track: TextTrack): void;
+    hostDisconnected(): void;
+    private stop;
+}
+export {};

package/dist/controllers/cue-controller/cue-controller.js

@@ -0,0 +1,45 @@
+export const captionTracks = (media) => {
+    const tracks = media?.textTracks;
+    if (!tracks) {
+        return [];
+    }
+    return [...tracks].filter((one) => one.kind === 'subtitles' || one.kind === 'captions');
+};
+export const showCaption = (tracks, index) => {
+    tracks.forEach((track, at) => {
+        track.mode = at === index ? 'hidden' : 'disabled';
+    });
+};
+export const adoptTrack = (track) => {
+    if (track.mode === 'showing') {
+        track.mode = 'hidden';
+    }
+    return track.mode === 'hidden';
+};
+export const captionsAmong = (media) => media
+    .filter((one) => one.tag === 'track' &&
+    (one.attrs.kind === undefined ||
+        ['captions', 'subtitles'].includes(one.attrs.kind.toLowerCase())))
+    .map((one) => ({ label: one.attrs.label ?? '', language: one.attrs.srclang ?? '' }));
+export const activeCue = (track) => {
+    const active = track?.activeCues?.[0];
+    return active instanceof VTTCue ? active.getCueAsHTML() : undefined;
+};
+export class CueController {
+    constructor(host, listener) {
+        this.listener = listener;
+        host.addController(this);
+    }
+    follow(track) {
+        this.stop();
+        this.track = track;
+        track.addEventListener('cuechange', this.listener);
+    }
+    hostDisconnected() {
+        this.stop();
+    }
+    stop() {
+        this.track?.removeEventListener('cuechange', this.listener);
+        this.track = undefined;
+    }
+}

package/dist/controllers/fullscreen-controller/fullscreen-controller.d.ts

@@ -0,0 +1,32 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * Into fullscreen and back, and honest about where the element is.
+ *
+ * The state follows `fullscreenchange` rather than the request, so a refused
+ * request leaves a button that correctly reports "not fullscreen".
+ *
+ * The document, rather than the host, is what the event is read from: the
+ * platform fires it at the document whichever element went full, so a host that
+ * asked and was overruled by another one still hears about it.
+ */
+export declare class FullscreenController implements ReactiveController {
+    private readonly host;
+    private readonly report;
+    constructor(host: ReactiveControllerHost & HTMLElement, report: (full: boolean) => void);
+    /**
+     * Into fullscreen and back, and quiet about being refused.
+     *
+     * `requestFullscreen` rejects rather than returning false, and the two
+     * refusals a consumer will actually meet are a Permissions Policy that does
+     * not grant `fullscreen` to the frame the player is in, and a call without
+     * user activation. Both are `TypeError: Permissions check failed`, which is
+     * the same message for two different causes.
+     *
+     * Caught rather than `void`ed, or a refusal becomes an unhandled rejection
+     * naming neither the element nor the reason.
+     */
+    toggle(): Promise<void>;
+    hostConnected(): void;
+    hostDisconnected(): void;
+    private readonly handleChange;
+}

package/dist/controllers/fullscreen-controller/fullscreen-controller.js

@@ -0,0 +1,28 @@
+export class FullscreenController {
+    constructor(host, report) {
+        this.host = host;
+        this.report = report;
+        this.handleChange = () => {
+            this.report(document.fullscreenElement === this.host);
+        };
+        host.addController(this);
+    }
+    async toggle() {
+        try {
+            if (document.fullscreenElement === this.host) {
+                await document.exitFullscreen();
+                return;
+            }
+            await this.host.requestFullscreen();
+        }
+        catch (error) {
+            console.warn(`<${this.host.localName}> could not enter fullscreen. If it is inside an iframe, that frame needs allow="fullscreen".`, error);
+        }
+    }
+    hostConnected() {
+        document.addEventListener('fullscreenchange', this.handleChange);
+    }
+    hostDisconnected() {
+        document.removeEventListener('fullscreenchange', this.handleChange);
+    }
+}

package/dist/controllers/idle-controller/idle-controller.d.ts

@@ -0,0 +1,35 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * How long the reader has been still, which is what an overlay hides itself on.
+ *
+ * A wait rather than leaving with the pointer, or a reader moving across a
+ * surface to reach a control watches the control vanish under them. The wait is
+ * only ever about *idling*: whether anything else keeps the overlay up, a
+ * paused player or an open menu, is the host's decision, and this only says
+ * when the reader stopped.
+ *
+ * The delay is asked for on every restart rather than taken once, because it
+ * is a property the consumer can change while the video plays.
+ */
+export declare class IdleController implements ReactiveController {
+    private readonly delay;
+    private readonly report;
+    private timer;
+    constructor(host: ReactiveControllerHost, delay: () => number, report: (idle: boolean) => void);
+    /**
+     * Restarts the wait, on anything that counts as the reader being here.
+     *
+     * Pointer movement and focus both count, and both have to: a reader using the
+     * keyboard never moves a pointer, and a bar that only answered the mouse
+     * would leave them nothing to look at. Zero turns the wait off and the bar
+     * goes immediately; a large number keeps it up for as long as anyone is
+     * likely to look.
+     */
+    readonly stir: () => void;
+    /**
+     * Leaving is the one case that does not wait: the reader has gone somewhere
+     * else, and there is nothing to reach for.
+     */
+    readonly leave: () => void;
+    hostDisconnected(): void;
+}

package/dist/controllers/idle-controller/idle-controller.js

@@ -0,0 +1,24 @@
+export class IdleController {
+    constructor(host, delay, report) {
+        this.delay = delay;
+        this.report = report;
+        this.stir = () => {
+            this.report(false);
+            clearTimeout(this.timer);
+            const delay = this.delay();
+            if (delay > 0) {
+                this.timer = setTimeout(() => {
+                    this.report(true);
+                }, delay);
+            }
+        };
+        this.leave = () => {
+            clearTimeout(this.timer);
+            this.report(true);
+        };
+        host.addController(this);
+    }
+    hostDisconnected() {
+        clearTimeout(this.timer);
+    }
+}

package/dist/controllers/media-session-controller/media-session-controller.d.ts

@@ -0,0 +1,54 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * How far a skip control moves, in seconds.
+ *
+ * Ten, which is the number every player that has one uses, and the number the
+ * platform names in `seekbackward` and `seekforward` when it hands over a
+ * default. A different length here would be correct only on this player.
+ */
+export declare const SKIP_SECONDS = 10;
+/** What a headset's buttons do, handed over by the player that owns them. */
+export interface SessionHandlers {
+    /**
+     * Asks for the next item, or `null` where the consumer has named nothing to
+     * skip to: the platform draws the key from whether a handler is set.
+     */
+    next: (() => void) | null;
+    /** And the previous one, under the same rule. */
+    previous: (() => void) | null;
+    seek: (seconds: number) => void;
+    skipBy: (seconds: number) => void;
+    toggle: () => void;
+}
+/**
+ * Holds the page's media session for one player, and tells the platform what
+ * is playing.
+ *
+ * The handlers are what make a headset's play, pause and skip work at all.
+ * Without them a platform falls back to guessing which element was meant,
+ * which is right often enough to hide the fault and wrong exactly when there
+ * are two.
+ */
+export declare class MediaSessionController implements ReactiveController {
+    private readonly host;
+    constructor(host: ReactiveControllerHost & HTMLElement);
+    /**
+     * Takes the session.
+     *
+     * On play rather than on render, which is the ownership rule: a page with two
+     * players gives the session to whichever one the reader started, so a
+     * headset's buttons land on what they are listening to rather than on
+     * whichever came first in the markup.
+     */
+    claim(metadata: {
+        artwork: string;
+        title: string;
+    }, handlers: SessionHandlers): void;
+    /** Tells the platform whether the owner is playing, and nothing if it is not the owner. */
+    report(playing: boolean): void;
+    /**
+     * The page's one media session goes back to nobody, but only if this
+     * element is the one holding it.
+     */
+    hostDisconnected(): void;
+}

package/dist/controllers/media-session-controller/media-session-controller.js

@@ -0,0 +1,49 @@
+let owner;
+export const SKIP_SECONDS = 10;
+export class MediaSessionController {
+    constructor(host) {
+        this.host = host;
+        host.addController(this);
+    }
+    claim(metadata, handlers) {
+        if (typeof navigator === 'undefined' || !navigator.mediaSession) {
+            return;
+        }
+        owner = this.host;
+        const session = navigator.mediaSession;
+        session.metadata = new MediaMetadata({
+            artwork: metadata.artwork === '' ? [] : [{ src: metadata.artwork }],
+            title: metadata.title,
+        });
+        session.setActionHandler('play', handlers.toggle);
+        session.setActionHandler('pause', handlers.toggle);
+        session.setActionHandler('seekto', (details) => {
+            if (details.seekTime !== undefined && details.seekTime !== null) {
+                handlers.seek(details.seekTime);
+            }
+        });
+        session.setActionHandler('seekbackward', (details) => {
+            handlers.skipBy(-(details.seekOffset ?? SKIP_SECONDS));
+        });
+        session.setActionHandler('seekforward', (details) => {
+            handlers.skipBy(details.seekOffset ?? SKIP_SECONDS);
+        });
+        session.setActionHandler('nexttrack', handlers.next);
+        session.setActionHandler('previoustrack', handlers.previous);
+    }
+    report(playing) {
+        if (owner === this.host && typeof navigator !== 'undefined' && navigator.mediaSession) {
+            navigator.mediaSession.playbackState = playing ? 'playing' : 'paused';
+        }
+    }
+    hostDisconnected() {
+        if (owner !== this.host) {
+            return;
+        }
+        owner = undefined;
+        if (typeof navigator !== 'undefined' && navigator.mediaSession) {
+            navigator.mediaSession.metadata = null;
+            navigator.mediaSession.playbackState = 'none';
+        }
+    }
+}

package/dist/controllers/remote-playback-controller/remote-playback-controller.d.ts

@@ -0,0 +1,34 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/** What the watch reports, as it learns it. */
+export interface RemoteReport {
+    /** Whether anything on the network offers to play this. */
+    available: (available: boolean) => void;
+    /** Whether it is playing somewhere else right now. */
+    connected: (connected: boolean) => void;
+}
+/**
+ * Watches for something to play the media on, and stops on the way out.
+ *
+ * The Remote Playback API is the standard one, and it is what Safari
+ * implements for AirPlay and Chrome for Cast: one call covers both, where the
+ * older `webkitShowPlaybackTargetPicker` covers only the first. Firefox has
+ * neither, and `remote` simply being absent is what turns the control off
+ * there.
+ *
+ * `watchAvailability` returns an id that has to be canceled, or the callback
+ * outlives the element that owns it: a callback holding a removed element is a
+ * leak with a `@state` write on the end.
+ */
+export declare class RemotePlaybackController implements ReactiveController {
+    private readonly report;
+    private media;
+    /** Cancels the availability watch, since it outlives a single render. */
+    private watch;
+    constructor(host: ReactiveControllerHost, report: RemoteReport);
+    /** Starts watching the media element, once there is one. */
+    attach(media: HTMLMediaElement): Promise<void>;
+    /** Opens the platform's own device picker. It has no list of its own. */
+    prompt(): Promise<void>;
+    hostDisconnected(): void;
+    private readonly handleState;
+}

package/dist/controllers/remote-playback-controller/remote-playback-controller.js

@@ -0,0 +1,38 @@
+export class RemotePlaybackController {
+    constructor(host, report) {
+        this.report = report;
+        this.handleState = () => {
+            this.report.connected(this.media?.remote?.state === 'connected');
+        };
+        host.addController(this);
+    }
+    async attach(media) {
+        this.media = media;
+        media.remote?.addEventListener?.('connect', this.handleState);
+        media.remote?.addEventListener?.('disconnect', this.handleState);
+        const remote = media.remote;
+        if (!remote?.watchAvailability) {
+            return;
+        }
+        try {
+            this.watch = await remote.watchAvailability((available) => {
+                this.report.available(available);
+            });
+        }
+        catch {
+        }
+    }
+    async prompt() {
+        try {
+            await this.media?.remote?.prompt();
+        }
+        catch {
+        }
+    }
+    hostDisconnected() {
+        if (this.watch !== undefined) {
+            void this.media?.remote?.cancelWatchAvailability?.(this.watch);
+            this.watch = undefined;
+        }
+    }
+}

package/dist/controllers/token-color-controller/token-color-controller.d.ts

@@ -7,7 +7,9 @@ export type TokenColor = [number, number, number];
  *
  * **Two hops, and both are load-bearing.** A custom property's own value is the
  * unevaluated function text, so `getComputedStyle` on a probe is the only way
- * to see what it resolves to. And what it resolves to is not `rgb()`: the
+ * to see what it resolves to. The second hop is `readColor`, which is shared
+ * with every other caller that has a resolved color and needs channels: what it
+ * resolves to is not `rgb()`, the
  * palette derives from an `oklch()` seed, and Chrome answers `lab(100 0 0)` for
  * white. Parsing that with a regular expression for numbers reads the three
  * channels as 100, 0 and 0, which divided by 255 is a dark red.
@@ -33,8 +35,6 @@ export type TokenColor = [number, number, number];
 export declare class TokenColorController implements ReactiveController {
     private readonly host;
     private readonly onChange?;
-    /** Where a resolved color is converted, one pixel at a time. */
-    private context;
     /** Watches the document for `data-color-mode`. */
     private modes;
     /** The hidden element a token is resolved against. */

package/dist/controllers/token-color-controller/token-color-controller.js

@@ -1,8 +1,8 @@
+import { readColor } from '../../utils/read-color/read-color.js';
 export class TokenColorController {
     constructor(host, onChange) {
         this.host = host;
         this.onChange = onChange;
-        this.context = null;
         this.announce = () => {
             this.host.requestUpdate();
             this.onChange?.();
@@ -16,10 +16,6 @@ export class TokenColorController {
         this.probe = document.createElement('span');
         this.probe.style.display = 'none';
         document.body.appendChild(this.probe);
-        const swatch = document.createElement('canvas');
-        swatch.width = 1;
-        swatch.height = 1;
-        this.context = swatch.getContext('2d', { willReadFrequently: true });
         this.modes = new MutationObserver(() => this.announce());
         this.modes.observe(document.documentElement, {
             attributeFilter: ['data-color-mode'],
@@ -35,18 +31,18 @@ export class TokenColorController {
         this.scheme = undefined;
         this.probe?.remove();
         this.probe = undefined;
-        this.context = null;
     }
     read(token, fallback) {
-        const { context, probe } = this;
-        if (!context || !probe) {
+        const { probe } = this;
+        if (!probe) {
             return [...fallback];
         }
         probe.style.color = `var(${token})`;
-        context.fillStyle = '#000000';
-        context.fillStyle = getComputedStyle(probe).color;
-        context.fillRect(0, 0, 1, 1);
-        const [r, g, b] = context.getImageData(0, 0, 1, 1).data;
-        return [(r ?? 0) / 255, (g ?? 0) / 255, (b ?? 0) / 255];
+        const read = readColor(getComputedStyle(probe).color);
+        if (!read) {
+            return [...fallback];
+        }
+        const [r, g, b] = read;
+        return [r / 255, g / 255, b / 255];
     }
 }

package/dist/index.d.ts

@@ -2,14 +2,18 @@ export { AriaForwardController, type AriaForwardOptions, } from './controllers/a
 export { ChartPointerController, type ChartPointerHost, } from './controllers/chart-pointer-controller/chart-pointer-controller.js';
 export { CommandController, type CommandOptions, HelixFallbackCommandEvent, supportsInvokers, } from './controllers/command-controller/command-controller.js';
 export { CopyController, type CopyOptions, } from './controllers/copy-controller/copy-controller.js';
+export { activeCue, adoptTrack, type Caption, CueController, captionsAmong, captionTracks, showCaption, } from './controllers/cue-controller/cue-controller.js';
 export { DisabledCascadeController, type DisabledCascadeOptions, } from './controllers/disabled-cascade-controller/disabled-cascade-controller.js';
 export { DismissController, type DismissOptions, } from './controllers/dismiss-controller/dismiss-controller.js';
 export { DrilldownController, type DrilldownOptions, } from './controllers/drilldown-controller/drilldown-controller.js';
 export { FloatingController, type FloatingOptions, type Placement, type Side, } from './controllers/floating-controller/floating-controller.js';
-export { FocusTrapController } from './controllers/focus-trap-controller/focus-trap-controller.js';
+export { FullscreenController } from './controllers/fullscreen-controller/fullscreen-controller.js';
+export { IdleController } from './controllers/idle-controller/idle-controller.js';
 export { IndicatorController, type IndicatorOptions, } from './controllers/indicator-controller/indicator-controller.js';
 export { KeyboardNavigationController, type KeyboardNavigationOptions, type NavigableItem, } from './controllers/keyboard-navigation-controller/keyboard-navigation-controller.js';
+export { MediaSessionController, type SessionHandlers, SKIP_SECONDS, } from './controllers/media-session-controller/media-session-controller.js';
 export { PopoverController, type PopoverOptions, } from './controllers/popover-controller/popover-controller.js';
+export { RemotePlaybackController, type RemoteReport, } from './controllers/remote-playback-controller/remote-playback-controller.js';
 export { SourceController, type SourceHost, } from './controllers/source-controller/source-controller.js';
 export { type TokenColor, TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
 export { type Rendered, VirtualizeController, type VirtualizeOptions, type Window as VirtualizeWindow, } from './controllers/virtualize-controller/virtualize-controller.js';
@@ -33,6 +37,7 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
+export { type Color, type ColorFormat, formatColor, parseColor, splitColors, toCss, } from './utils/css-color/css-color.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
 export { type DrawIconOptions, drawIcon } from './utils/draw-icon/draw-icon.js';
 export { CHART_PLOT, drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
@@ -44,7 +49,9 @@ export { type DisableableItem, forgetDisabled, inheritDisabled, } from './utils/
 export { inlineStep } from './utils/inline-step/inline-step.js';
 export { type Curve, linePath, type Point } from './utils/line-path/line-path.js';
 export { markRegion, type RegionOptions } from './utils/mark-region/mark-region.js';
+export { copiesOf, type MediaCopy, sameCopies, } from './utils/media-copy/media-copy.js';
 export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
+export { type ColorBytes, readColor } from './utils/read-color/read-color.js';
 export { type Row, type RowCell, readRows, readSeries, type Series, type SeriesPoint, } from './utils/read-series/read-series.js';
 export { type Relative, relativeTime, } from './utils/relative-time/relative-time.js';
 export { type ChangeRequestOptions, requestChange, } from './utils/request-change/request-change.js';

package/dist/index.js

@@ -2,14 +2,18 @@ export { AriaForwardController, } from './controllers/aria-forward-controller/ar
 export { ChartPointerController, } from './controllers/chart-pointer-controller/chart-pointer-controller.js';
 export { CommandController, HelixFallbackCommandEvent, supportsInvokers, } from './controllers/command-controller/command-controller.js';
 export { CopyController, } from './controllers/copy-controller/copy-controller.js';
+export { activeCue, adoptTrack, CueController, captionsAmong, captionTracks, showCaption, } from './controllers/cue-controller/cue-controller.js';
 export { DisabledCascadeController, } from './controllers/disabled-cascade-controller/disabled-cascade-controller.js';
 export { DismissController, } from './controllers/dismiss-controller/dismiss-controller.js';
 export { DrilldownController, } from './controllers/drilldown-controller/drilldown-controller.js';
 export { FloatingController, } from './controllers/floating-controller/floating-controller.js';
-export { FocusTrapController } from './controllers/focus-trap-controller/focus-trap-controller.js';
+export { FullscreenController } from './controllers/fullscreen-controller/fullscreen-controller.js';
+export { IdleController } from './controllers/idle-controller/idle-controller.js';
 export { IndicatorController, } from './controllers/indicator-controller/indicator-controller.js';
 export { KeyboardNavigationController, } from './controllers/keyboard-navigation-controller/keyboard-navigation-controller.js';
+export { MediaSessionController, SKIP_SECONDS, } from './controllers/media-session-controller/media-session-controller.js';
 export { PopoverController, } from './controllers/popover-controller/popover-controller.js';
+export { RemotePlaybackController, } from './controllers/remote-playback-controller/remote-playback-controller.js';
 export { SourceController, } from './controllers/source-controller/source-controller.js';
 export { TokenColorController, } from './controllers/token-color-controller/token-color-controller.js';
 export { VirtualizeController, } from './controllers/virtualize-controller/virtualize-controller.js';
@@ -33,6 +37,7 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { closestInstance } from './utils/closest-instance/closest-instance.js';
 export { createSheet } from './utils/create-sheet/create-sheet.js';
+export { formatColor, parseColor, splitColors, toCss, } from './utils/css-color/css-color.js';
 export { customElement, definedTags, duplicateRegistrations, } from './utils/custom-element/custom-element.js';
 export { drawIcon } from './utils/draw-icon/draw-icon.js';
 export { CHART_PLOT, drawTooltip } from './utils/draw-tooltip/draw-tooltip.js';
@@ -44,7 +49,9 @@ export { forgetDisabled, inheritDisabled, } from './utils/inherit-disabled/inher
 export { inlineStep } from './utils/inline-step/inline-step.js';
 export { linePath } from './utils/line-path/line-path.js';
 export { markRegion } from './utils/mark-region/mark-region.js';
+export { copiesOf, sameCopies, } from './utils/media-copy/media-copy.js';
 export { onUnlessFalse } from './utils/on-unless-false/on-unless-false.js';
+export { readColor } from './utils/read-color/read-color.js';
 export { readRows, readSeries, } from './utils/read-series/read-series.js';
 export { relativeTime, } from './utils/relative-time/relative-time.js';
 export { requestChange, } from './utils/request-change/request-change.js';

package/dist/utils/css-color/css-color.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Reading and writing the color syntaxes a field is allowed to hold.
+ *
+ * **The working model is HSB**, hue and saturation and brightness, because that
+ * is what the panel is: a square of saturation against brightness with a hue
+ * ramp beside it. HSL would put the square's corners somewhere a reader does not
+ * expect, since full saturation in HSL is a mid-lightness band rather than a
+ * corner.
+ *
+ * **Every syntax here is read; three are written.** A field that refuses
+ * `rgb(255 0 0)` because it prefers hex is a field arguing with the person using
+ * it, so the space-separated forms, the comma forms, `rgba` and `hsla` are all
+ * taken. What is written back is whichever of hex, rgb or hsl the component is
+ * set to, so a value stays in the shape the consumer asked for however it was
+ * entered.
+ *
+ * **What is written is the comma form.** Both are valid, and the commas are what
+ * a reader recognizes, what most code around them holds, and what pastes into
+ * anything without a second thought. A syntax a value is handed *out* in is not
+ * the place to be early. `rgba` and `hsla` come with them, since a comma form
+ * with a fourth argument is spelled that way.
+ *
+ * **Core's rather than a field's, because the CSS color grammar is the
+ * platform's.** Nothing here needs a color picker to make sense, and two
+ * families read it already. It is arithmetic with no DOM in it, so it runs on a
+ * server, which is also why named colors are refused below: resolving
+ * `rebeccapurple` means asking a browser that is not there.
+ *
+ * **One decision in here is a default rather than a capability.** What
+ * `formatColor` writes back, the comma form and an alpha only where one was
+ * asked for, is a choice about what a value looks like when it is handed out.
+ * It is core's choice now instead of the picker's, and a caller wanting another
+ * shape formats it itself.
+ */
+/** A color as the panel holds it. Alpha and the two percentages are 0 to 100. */
+export interface Color {
+    alpha: number;
+    brightness: number;
+    hue: number;
+    saturation: number;
+}
+/** The syntaxes a value can be written in. */
+export type ColorFormat = 'hex' | 'hsl' | 'rgb';
+/**
+ * Splits a comma-separated list of colors, ignoring the commas inside them.
+ *
+ * A plain `split(',')` cannot hold the legacy syntaxes:
+ * `#ef4444, rgb(249 115 22), rgba(34,197,94,.5)` comes apart into six fragments,
+ * four of them not colors, and the row quietly renders three swatches instead of
+ * four. The modern space-separated forms survive it, which is what makes such a
+ * list look like it works.
+ *
+ * Depth rather than a regular expression, because the thing that matters is
+ * whether a comma is inside a function call and that is exactly what a counter
+ * answers. No color syntax nests, so a single counter is enough.
+ */
+export declare const splitColors: (value: string) => string[];
+/**
+ * Any of the syntaxes to the working model, or `null` where it is not a color.
+ *
+ * Named colors are not here. Resolving `rebeccapurple` means either shipping
+ * the table of a hundred and forty or asking the browser, and the browser is not
+ * present on the server: a field that accepted a name client-side and rejected
+ * it during a server render would be worse than one that never took it.
+ */
+export declare const parseColor: (value: string) => Color | null;
+/**
+ * The working model back out, in the syntax asked for.
+ *
+ * The alpha is written only where the component carries one. A consumer who did
+ * not ask for transparency should not have to strip `ff` off every hex or read
+ * past a fourth argument they never wanted.
+ */
+export declare const formatColor: (color: Color, format: ColorFormat, withAlpha: boolean) => string;
+/** The color as CSS, for the swatches and the tracks. Always with its alpha. */
+export declare const toCss: (color: Color) => string;