@fusion.dev/helix-headless 0.25.1 → 0.30.0

package/dist/tour/stop/tour-stop.js

@@ -22,10 +22,10 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
         this.skipLabel = 'Skip';
         this.floating = new PopoverController(this, {
             anchor: () => this.target,
-            arrow: () => this.renderRoot?.querySelector('[part="arrow"]'),
+            arrow: () => this.partNamed('arrow'),
             onDismiss: () => { },
             placement: () => this.placement,
-            surface: () => this.renderRoot?.querySelector('[part="bubble"]'),
+            surface: () => this.partNamed('bubble'),
         });
     }
     get target() {

package/dist/video/root/captions.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 video rather
+ * than off the slot: a `<track>` added later is in one and not the other, and
+ * the video is the one that has resolved them.
+ */
+export declare const captionTracks: (video: HTMLVideoElement | 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/video/root/captions.js

@@ -0,0 +1,45 @@
+export const captionTracks = (video) => {
+    const tracks = video?.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/video/root/fullscreen.d.ts

@@ -0,0 +1,28 @@
+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".
+ */
+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/video/root/fullscreen.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/video/root/idle.d.ts

@@ -0,0 +1,34 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * How long the reader has been still, which decides when the bar goes.
+ *
+ * A wait rather than leaving with the pointer, or a reader moving across the
+ * picture to reach a control watches the bar vanish under them. The wait is
+ * only ever about *idling*: whether a paused video keeps its bar is the
+ * element'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/video/root/idle.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/video/root/media-session.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/video/root/media-session.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/video/root/remote-playback.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 video 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 video;
+    /** Cancels the availability watch, since it outlives a single render. */
+    private watch;
+    constructor(host: ReactiveControllerHost, report: RemoteReport);
+    /** Starts watching the video, once there is one. */
+    attach(video: HTMLVideoElement): 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/video/root/remote-playback.js

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

package/dist/video/root/video-root.d.ts

@@ -338,7 +338,6 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * Whether the reader has been still long enough for the bar to go.
      */
     private idle;
-    private idleTimer?;
     /**
      * Whether anything on the network offers to play this.
      */
@@ -347,8 +346,11 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * Whether it is playing somewhere else right now.
      */
     private remoteConnected;
-    /** Cancels the availability watch, since it outlives a single render. */
-    private remoteWatch;
+    private readonly cues;
+    private readonly fullscreen;
+    private readonly idler;
+    private readonly remote;
+    private readonly session;
     /** Whether this platform can do a named control at all. */
     private offers;
     /** The extras asked for, in order, and only the ones this platform can do. */
@@ -485,17 +487,9 @@ export declare class HelixHeadlessVideo extends HelixElement {
     private readonly handleError;
     private readonly handleState;
     /**
-     * Takes the page's media session, and tells the platform what is playing.
-     *
-     * 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.
-     *
-     * 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.
+     * Takes the page's media session, on play rather than on render: a page
+     * with two players gives it to whichever one the reader started. The skip
+     * keys are offered only where the consumer named something to skip to.
      */
     private claimSession;
     private readonly handleVolume;
@@ -522,28 +516,7 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * presses it twice expects twenty seconds rather than an accelerating jump.
      */
     private skipBy;
-    /**
-     * 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 video rather
-     * than off the slot: a `<track>` added later is in one and not the other, and
-     * the video is the one that has resolved them.
-     */
-    private get captionTracks();
-    /**
-     * 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.
-     */
+    /** Shows one track and disables every other, or shows none at `-1`. */
     private showCaption;
     /** Turns captions on or off, which is what the button means with one track. */
     private toggleCaptions;
@@ -562,46 +535,7 @@ export declare class HelixHeadlessVideo extends HelixElement {
     private skip;
     /** Steps through the speeds offered, which is what one button can do. */
     private cycleSpeed;
-    /**
-     * Starts watching for something to play this 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.
-     */
-    private watchRemote;
-    /** Opens the platform's own device picker. It has no list of its own. */
-    private promptRemote;
     private togglePip;
-    /**
-     * 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. The state stays honest either
-     * way, because `aria-pressed` follows `fullscreenchange` rather than this
-     * call, so a refused request leaves a button that correctly reports "not
-     * fullscreen".
-     */
-    private toggleFullscreen;
-    /**
-     * 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.
-     */
-    private readonly stir;
     /**
      * A press on the picture plays or pauses it.
      *
@@ -623,7 +557,6 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * mouse left resting until the bar faded.
      */
     private readonly handlePicture;
-    private readonly handleFullscreenChange;
     /**
      * The keys every player uses, bound to this element rather than the document.
      *
@@ -636,22 +569,11 @@ export declare class HelixHeadlessVideo extends HelixElement {
      * seeking twice for one press.
      */
     private readonly handleKeydown;
-    /** The track currently being listened to, so the next one can take it off. */
-    private cued;
-    private readonly handleRemoteState;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
     /** The caption tracks among the copies, named as the menu names them. */
     private captions;
     /**
-     * Finds 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.
+     * Reads the copies, and names the caption tracks among them before the
+     * render that draws them.
      */
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;