@braccato/core 1.15.3 → 1.16.0

package/README.md

@@ -96,8 +96,9 @@ connects, and everything it was handed by then is applied at once.
 | `tickOptions`   |                | `ElementTickOptions`                | `{}`     | The rest of a tick: four offsets taken off the clock before it is matched, whether passive scrolling is on, when the clock was sampled, and the rate the song is playing at. |
 | `theme`         | `theme`        | `string`                            | `""`     | A compiled stylesheet. See Theming.                                                                                                        |
 | `host`          |                | `Partial<LyricsRendererHost>`       | `{}`     | Overrides for what the renderer asks of its surroundings. Every member has a default. Writing it while connected rebuilds the view.        |
+| `layout`        | `layout`       | `"scroll" \| "stage"`               | `"scroll"` | `stage` shows only the lines being sung. See Entry points. Writing it while connected rebuilds the view.                                    |
 | `renderer`      |                | `LyricsRenderer \| null` (get)      | `null`   | The renderer underneath, for the day the tag runs out. A different one after every reconnection.                                            |
-| `status`        |                | `ElementStatus` (get)               | `"idle"` | `idle`, `rendering`, `theme-conflict` or `no-browsing-context`.                                                                            |
+| `status`        |                | `ElementStatus` (get)               | `"idle"` | `idle`, `rendering`, `theme-conflict`, `unsynced-on-stage` or `no-browsing-context`.                                                                            |
 
 `tickOptions` and `lyricsOptions` are stored on write and read by the next tick or the next build, so
 writing options and the clock on the same frame renders once.
@@ -112,12 +113,13 @@ do not is worse than none of them doing it.
 | -------------- | ------------- | -------------------------------------------------------------------------------------------------- |
 | `source`       | `source`      | The selector form only. Another selector moves the binding, and removing it unbinds.                |
 | `theme`        | `theme`       | A whole stylesheet in an attribute value. It works, but nobody would ship a theme this way.          |
+| `layout`       | `layout`      | `stage` puts the view on a stage. Any other value, or no attribute, scrolls.                       |
 | `current-time` | `currentTime` | Seconds. A value that does not parse as a number is ignored rather than read as zero.               |
 | `playing`      | `playing`     | An ordinary boolean attribute: its presence is what counts, so `playing="false"` is playing.         |
 
 ## Events
 
-All four bubble and are composed, so an element you put inside your own shadow root still reaches
+All five bubble and are composed, so an element you put inside your own shadow root still reaches
 your listener.
 
 | Event                    | Detail                    | When                                                                            |
@@ -125,7 +127,8 @@ your listener.
 | `braccato:lyrics-loaded` | `{ lineCount, syncType }` | Lyrics were applied, including an empty array. A theme change that rebuilds the lines reports itself the same way. |
 | `braccato:line-click`    | `{ timeS }`               | A line was clicked. The seek has already reached the bound media element by the time you hear about it.            |
 | `braccato:scroll-state`  | `{ userScrolling }`       | Autoscroll stopped following the song, or started again.                                                           |
-| `braccato:error`         | `{ phase, error }`        | Connecting, resolving a source, or applying lyrics or a theme went wrong. `phase` is `connect`, `conflict`, `source`, `lyrics` or `theme`. |
+| `braccato:stage-layout`  | `{ box }`                 | Stage layout only. The box around the sung lines in the container's coordinates, or null when nothing sung is on stage. |
+| `braccato:error`         | `{ phase, error }`        | Connecting, resolving a source, or applying lyrics or a theme went wrong, or a stage cannot show what it was given. `phase` is `connect`, `conflict`, `layout`, `source`, `lyrics` or `theme`. |
 
 Errors are dispatched a microtask after they happen rather than where they happen, which is what
 makes them receivable at all: `connectedCallback` runs before any listener a page could have added.
@@ -403,6 +406,20 @@ Everything else is the theme's. Lines are styled exactly as they would be in a s
 `host.onStageLayout(box)` reports the box around the sung lines in the container's coordinates, or null
 when nothing sung is on stage, so you can draw a backdrop outside the container the theme styles.
 
+The element takes the same layout as `layout="stage"`, and reports the same box as
+`braccato:stage-layout`. Give the element or its parent a size and a position, and load `stage.css`.
+A stage that cannot show what it was given says so rather than staying blank: unsynced lyrics set
+`status` to `unsynced-on-stage`, and both they and a missing `stage.css` dispatch `braccato:error`
+with `phase: "layout"`. Each song is reported once, so a theme that rebuilds the lines stays quiet.
+The stylesheet is checked a frame after the song is built, and only the event reports it.
+
+```html
+<div style="position: relative; aspect-ratio: 16 / 9">
+  <video id="clip" src="clip.mp4"></video>
+  <braccato-lyrics source="#clip" layout="stage"></braccato-lyrics>
+</div>
+```
+
 `@braccato/core/element` registers `<braccato-lyrics>`, and `<better-lyrics>` beside it, on import.
 Registration is a side effect, which is why it is entered separately.
 

package/dist/README.md

@@ -96,8 +96,9 @@ connects, and everything it was handed by then is applied at once.
 | `tickOptions`   |                | `ElementTickOptions`                | `{}`     | The rest of a tick: four offsets taken off the clock before it is matched, whether passive scrolling is on, when the clock was sampled, and the rate the song is playing at. |
 | `theme`         | `theme`        | `string`                            | `""`     | A compiled stylesheet. See Theming.                                                                                                        |
 | `host`          |                | `Partial<LyricsRendererHost>`       | `{}`     | Overrides for what the renderer asks of its surroundings. Every member has a default. Writing it while connected rebuilds the view.        |
+| `layout`        | `layout`       | `"scroll" \| "stage"`               | `"scroll"` | `stage` shows only the lines being sung. See Entry points. Writing it while connected rebuilds the view.                                    |
 | `renderer`      |                | `LyricsRenderer \| null` (get)      | `null`   | The renderer underneath, for the day the tag runs out. A different one after every reconnection.                                            |
-| `status`        |                | `ElementStatus` (get)               | `"idle"` | `idle`, `rendering`, `theme-conflict` or `no-browsing-context`.                                                                            |
+| `status`        |                | `ElementStatus` (get)               | `"idle"` | `idle`, `rendering`, `theme-conflict`, `unsynced-on-stage` or `no-browsing-context`.                                                                            |
 
 `tickOptions` and `lyricsOptions` are stored on write and read by the next tick or the next build, so
 writing options and the clock on the same frame renders once.
@@ -112,12 +113,13 @@ do not is worse than none of them doing it.
 | -------------- | ------------- | -------------------------------------------------------------------------------------------------- |
 | `source`       | `source`      | The selector form only. Another selector moves the binding, and removing it unbinds.                |
 | `theme`        | `theme`       | A whole stylesheet in an attribute value. It works, but nobody would ship a theme this way.          |
+| `layout`       | `layout`      | `stage` puts the view on a stage. Any other value, or no attribute, scrolls.                       |
 | `current-time` | `currentTime` | Seconds. A value that does not parse as a number is ignored rather than read as zero.               |
 | `playing`      | `playing`     | An ordinary boolean attribute: its presence is what counts, so `playing="false"` is playing.         |
 
 ## Events
 
-All four bubble and are composed, so an element you put inside your own shadow root still reaches
+All five bubble and are composed, so an element you put inside your own shadow root still reaches
 your listener.
 
 | Event                    | Detail                    | When                                                                            |
@@ -125,7 +127,8 @@ your listener.
 | `braccato:lyrics-loaded` | `{ lineCount, syncType }` | Lyrics were applied, including an empty array. A theme change that rebuilds the lines reports itself the same way. |
 | `braccato:line-click`    | `{ timeS }`               | A line was clicked. The seek has already reached the bound media element by the time you hear about it.            |
 | `braccato:scroll-state`  | `{ userScrolling }`       | Autoscroll stopped following the song, or started again.                                                           |
-| `braccato:error`         | `{ phase, error }`        | Connecting, resolving a source, or applying lyrics or a theme went wrong. `phase` is `connect`, `conflict`, `source`, `lyrics` or `theme`. |
+| `braccato:stage-layout`  | `{ box }`                 | Stage layout only. The box around the sung lines in the container's coordinates, or null when nothing sung is on stage. |
+| `braccato:error`         | `{ phase, error }`        | Connecting, resolving a source, or applying lyrics or a theme went wrong, or a stage cannot show what it was given. `phase` is `connect`, `conflict`, `layout`, `source`, `lyrics` or `theme`. |
 
 Errors are dispatched a microtask after they happen rather than where they happen, which is what
 makes them receivable at all: `connectedCallback` runs before any listener a page could have added.
@@ -403,6 +406,20 @@ Everything else is the theme's. Lines are styled exactly as they would be in a s
 `host.onStageLayout(box)` reports the box around the sung lines in the container's coordinates, or null
 when nothing sung is on stage, so you can draw a backdrop outside the container the theme styles.
 
+The element takes the same layout as `layout="stage"`, and reports the same box as
+`braccato:stage-layout`. Give the element or its parent a size and a position, and load `stage.css`.
+A stage that cannot show what it was given says so rather than staying blank: unsynced lyrics set
+`status` to `unsynced-on-stage`, and both they and a missing `stage.css` dispatch `braccato:error`
+with `phase: "layout"`. Each song is reported once, so a theme that rebuilds the lines stays quiet.
+The stylesheet is checked a frame after the song is built, and only the event reports it.
+
+```html
+<div style="position: relative; aspect-ratio: 16 / 9">
+  <video id="clip" src="clip.mp4"></video>
+  <braccato-lyrics source="#clip" layout="stage"></braccato-lyrics>
+</div>
+```
+
 `@braccato/core/element` registers `<braccato-lyrics>`, and `<better-lyrics>` beside it, on import.
 Registration is a side effect, which is why it is entered separately.
 

package/dist/element.d.ts

@@ -1,4 +1,5 @@
-import type { Lyric, LyricsRenderer, LyricsRendererHost, LyricSyncType, TickOptions } from "./types.js";
+import type { StageBox } from "./stage.js";
+import type { Lyric, LyricsLayout, LyricsRenderer, LyricsRendererHost, LyricSyncType, TickOptions } from "./types.js";
 import type { SetLyricsOptions } from "./view.js";
 /**
  * What a tick carries beyond the clock. `isPlaying` is not among them: `playing` is the property
@@ -15,7 +16,7 @@ export type ElementTickOptions = Omit<TickOptions, "isPlaying">;
  */
 export type ElementLyricsOptions = Partial<SetLyricsOptions>;
 /** @public */
-export type ElementErrorPhase = "connect" | "conflict" | "lyrics" | "source" | "theme";
+export type ElementErrorPhase = "connect" | "conflict" | "layout" | "lyrics" | "source" | "theme";
 /** @public */
 export interface ElementErrorDetail {
     /** What the element was doing. Nothing thrown by a tick is reported here: see the README. */
@@ -30,7 +31,7 @@ export interface ElementErrorDetail {
  *
  * @public
  */
-export type ElementStatus = "idle" | "rendering" | "theme-conflict" | "no-browsing-context";
+export type ElementStatus = "idle" | "rendering" | "theme-conflict" | "unsynced-on-stage" | "no-browsing-context";
 /** @public */
 export interface LyricsLoadedDetail {
     lineCount: number;
@@ -42,6 +43,11 @@ export interface LineClickDetail {
     timeS: number;
 }
 /** @public */
+export interface StageLayoutDetail {
+    /** Around the lines being sung, in the container's coordinates, or null when nothing sung is on stage. */
+    box: StageBox | null;
+}
+/** @public */
 export interface ScrollStateDetail {
     /** Whether the user has scrolled away, so autoscroll is waiting rather than following the song. */
     userScrolling: boolean;
@@ -132,6 +138,13 @@ export declare class BraccatoLyricsElement extends HTMLElement {
      */
     get host(): Partial<LyricsRendererHost>;
     set host(overrides: Partial<LyricsRendererHost>);
+    /**
+     * `"stage"` shows only the lines being sung, for subtitles over a video, and fills the nearest
+     * positioned ancestor. Anything else scrolls. Writing it while connected rebuilds the view: the
+     * renderer is handed its layout once, when it is created.
+     */
+    get layout(): LyricsLayout;
+    set layout(layout: LyricsLayout);
     /**
      * The renderer underneath, for a consumer who outgrows the element. Null while disconnected, and a
      * different one after every reconnection.

package/dist/element.js

@@ -18,6 +18,7 @@ const ALIAS_TAG_NAME = "better-lyrics";
 // the DOM sixty times a second, and one attribute reflecting while the others do not is worse than
 // none of them doing it.
 const CURRENT_TIME_ATTRIBUTE = "current-time";
+const LAYOUT_ATTRIBUTE = "layout";
 const PLAYING_ATTRIBUTE = "playing";
 const SOURCE_ATTRIBUTE = "source";
 const THEME_ATTRIBUTE = "theme";
@@ -52,9 +53,12 @@ const MAX_CLOCK_CARRY_MS = 100;
 const LINE_CLICK_EVENT = "braccato:line-click";
 const LYRICS_LOADED_EVENT = "braccato:lyrics-loaded";
 const SCROLL_STATE_EVENT = "braccato:scroll-state";
+const STAGE_LAYOUT_EVENT = "braccato:stage-layout";
 const ERROR_EVENT = "braccato:error";
 const NO_BROWSING_CONTEXT_MESSAGE = "This element is in a document with no window, so there is nothing to build lyrics against";
 const THEME_DISAGREEMENT_MESSAGE = "Another lyrics element in this document was given a different theme, and the module's theme settings are shared, so both views render against whichever theme was applied last";
+const UNSYNCED_STAGE_MESSAGE = "A stage places lines by their time and these lyrics have none, so the stage shows nothing";
+const MISSING_STAGE_STYLESHEET_MESSAGE = "The stage container is still in the document flow, so @braccato/core/styles/stage.css is not loaded and every line stacks where it was built";
 const NON_MEDIA_SOURCE_MESSAGE = "The source given is not a media element in this element's document, so the lyrics have no clock to follow";
 // -- The views a document is rendering --------------------------------------------
 // Membership means rendering, so an element that threw on the way up or has been disconnected is
@@ -97,7 +101,13 @@ function defineOnce(tagName, elementConstructor) {
  * property here would be a second opinion about a question the platform has already answered.
  */
 export class BraccatoLyricsElement extends HTMLElement {
-    static observedAttributes = [CURRENT_TIME_ATTRIBUTE, PLAYING_ATTRIBUTE, SOURCE_ATTRIBUTE, THEME_ATTRIBUTE];
+    static observedAttributes = [
+        CURRENT_TIME_ATTRIBUTE,
+        LAYOUT_ATTRIBUTE,
+        PLAYING_ATTRIBUTE,
+        SOURCE_ATTRIBUTE,
+        THEME_ATTRIBUTE,
+    ];
     #renderer = null;
     // The document this element registered itself in, rather than whatever it is in now: adopting an
     // element into another document changes `ownerDocument` under the callback that has to take it
@@ -113,6 +123,9 @@ export class BraccatoLyricsElement extends HTMLElement {
     #tickOptions = {};
     #theme = "";
     #hostOverrides = {};
+    #layout = "scroll";
+    // The song the stage last reported on, so a theme that rebuilds the same lines stays quiet.
+    #stageReportedLyrics = null;
     #source = null;
     // Non-null exactly while the element is listening to a media element, so there is no state where
     // one is remembered and its listeners are not.
@@ -246,6 +259,24 @@ export class BraccatoLyricsElement extends HTMLElement {
         this.#destroyRenderer();
         this.#build();
     }
+    /**
+     * `"stage"` shows only the lines being sung, for subtitles over a video, and fills the nearest
+     * positioned ancestor. Anything else scrolls. Writing it while connected rebuilds the view: the
+     * renderer is handed its layout once, when it is created.
+     */
+    get layout() {
+        return this.#layout;
+    }
+    set layout(layout) {
+        const next = layout === "stage" ? "stage" : "scroll";
+        if (next === this.#layout)
+            return;
+        this.#layout = next;
+        if (this.#renderer === null)
+            return;
+        this.#destroyRenderer();
+        this.#build();
+    }
     /**
      * The renderer underneath, for a consumer who outgrows the element. Null while disconnected, and a
      * different one after every reconnection.
@@ -267,6 +298,8 @@ export class BraccatoLyricsElement extends HTMLElement {
     get status() {
         if (this.#renderer === null)
             return this.#missingBrowsingContext ? "no-browsing-context" : "idle";
+        if (this.#isUnsyncedOnStage(this.#renderer))
+            return "unsynced-on-stage";
         return this.#disagreeingPeers().length > 0 ? "theme-conflict" : "rendering";
     }
     // -- Lifecycle --------------------------------------------
@@ -280,6 +313,7 @@ export class BraccatoLyricsElement extends HTMLElement {
         this.#upgradeProperty("playing");
         this.#upgradeProperty("theme");
         this.#upgradeProperty("host");
+        this.#upgradeProperty("layout");
         this.#upgradeProperty("source");
         this.#build();
         // After the view exists, so a build that threw on the way up leaves no listener on a media
@@ -305,6 +339,10 @@ export class BraccatoLyricsElement extends HTMLElement {
                 this.currentTime = currentTimeS;
             return;
         }
+        if (name === LAYOUT_ATTRIBUTE) {
+            this.layout = newValue === "stage" ? "stage" : "scroll";
+            return;
+        }
         if (name === PLAYING_ATTRIBUTE) {
             this.playing = newValue !== null;
             return;
@@ -338,6 +376,7 @@ export class BraccatoLyricsElement extends HTMLElement {
             window: view,
             mount: this,
             host: this.#hostForRenderer(),
+            layout: this.#layout,
         });
         // After the renderer exists and never before, so that a build which threw on the way up leaves
         // nothing behind claiming to be one of the document's views.
@@ -348,6 +387,7 @@ export class BraccatoLyricsElement extends HTMLElement {
     #destroyRenderer() {
         this.#renderer?.destroy();
         this.#renderer = null;
+        this.#stageReportedLyrics = null;
         this.#leaveDocument();
     }
     /**
@@ -372,6 +412,10 @@ export class BraccatoLyricsElement extends HTMLElement {
                 overrides.setResumeAffordanceVisible?.(visible);
                 this.#emit(SCROLL_STATE_EVENT, { userScrolling: visible });
             },
+            onStageLayout: box => {
+                overrides.onStageLayout?.(box);
+                this.#emit(STAGE_LAYOUT_EVENT, { box });
+            },
         };
     }
     #applyLyrics() {
@@ -395,9 +439,33 @@ export class BraccatoLyricsElement extends HTMLElement {
             lineCount: renderer.lines.length,
             syncType: renderer.syncType,
         });
+        this.#reportStageProblems(renderer);
         // So the new lines are where the song is rather than at the top until the clock next moves.
         this.#tick();
     }
+    #isUnsyncedOnStage(renderer) {
+        return this.#layout === "stage" && renderer.lines.length > 0 && renderer.syncType === "none";
+    }
+    /** Both leave an empty or broken stage behind with nothing thrown, so nobody would hear of them. */
+    #reportStageProblems(renderer) {
+        const container = renderer.container;
+        const view = this.ownerDocument.defaultView;
+        if (this.#layout !== "stage" || container === null || view === null)
+            return;
+        if (this.#lyrics === this.#stageReportedLyrics)
+            return;
+        this.#stageReportedLyrics = this.#lyrics;
+        if (this.#isUnsyncedOnStage(renderer))
+            this.#emitError("layout", new Error(UNSYNCED_STAGE_MESSAGE));
+        // A frame later, so a stylesheet that lands just after the build is not reported as missing.
+        view.requestAnimationFrame(() => {
+            if (this.#renderer !== renderer || renderer.container !== container)
+                return;
+            if (view.getComputedStyle(container).position === "absolute")
+                return;
+            this.#emitError("layout", new Error(MISSING_STAGE_STYLESHEET_MESSAGE));
+        });
+    }
     #applyTheme() {
         const renderer = this.#renderer;
         if (renderer === null)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@braccato/core",
-  "version": "1.15.3",
+  "version": "1.16.0",
   "description": "Synchronized lyrics renderer with word-by-word animations",
   "type": "module",
   "license": "MIT",