@braccato/core 1.3.0 → 1.4.0

package/README.md

@@ -235,7 +235,11 @@ package's stylesheets are yours to load for the same reason.
 `@braccato/core` is the facade and registers nothing. `createLyricsRenderer(options)` returns one
 `LyricsRenderer`: give it lyrics, tick it, and it owns the DOM it builds and every re-measurement
 that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization` and
-`injectTranslation` are published beside it, for what one instance cannot answer for on its own.
+`injectTranslation` are published beside it, for what one instance cannot answer for on its own. Hang
+one onto a built line and call `renderer.scheduleLyricPositionUpdate` the way you already would to
+catch the layout up: the hung line floats into place while the lines around it slide to make room,
+rather than the rest of the lyric jumping down. `--blyrics-animate-decoration-entry` set to `0` drops
+both for an instant insert, and reduced-motion does the same.
 
 `@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

@@ -235,7 +235,11 @@ package's stylesheets are yours to load for the same reason.
 `@braccato/core` is the facade and registers nothing. `createLyricsRenderer(options)` returns one
 `LyricsRenderer`: give it lyrics, tick it, and it owns the DOM it builds and every re-measurement
 that DOM needs. `resetPlaybackClock`, `resumeAllAutoscroll`, `injectRomanization` and
-`injectTranslation` are published beside it, for what one instance cannot answer for on its own.
+`injectTranslation` are published beside it, for what one instance cannot answer for on its own. Hang
+one onto a built line and call `renderer.scheduleLyricPositionUpdate` the way you already would to
+catch the layout up: the hung line floats into place while the lines around it slide to make room,
+rather than the rest of the lyric jumping down. `--blyrics-animate-decoration-entry` set to `0` drops
+both for an instant insert, and reduced-motion does the same.
 
 `@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/engine.js

@@ -16,7 +16,7 @@
 // playback clock the last tick wrote. Their unit is a bundle rather than a document, and this
 // module is bundled into the isolated world and the page world separately, so those are two clocks
 // that never meet. `themeSettings.ts` holds the third thing under that rule.
-import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
+import { ANIMATING_CLASS, CURRENT_LYRICS_CLASS, FOOTER_CLASS, LINE_CLASS, PAUSED_CLASS, ROMANIZED_LYRICS_CLASS, TRANSLATED_LYRICS_CLASS, USER_SCROLLING_CLASS, } from "./constants.js";
 import { INSTRUMENTAL_WAVE_PATH_HIGH, INSTRUMENTAL_WAVE_PATH_LOW } from "./instrumental.js";
 import { registerThemeSetting } from "./themeSettings.js";
 import { clamp, getRelativeLayoutBounds, positiveModulo, roundedMs, toMs } from "./util.js";
@@ -1930,10 +1930,61 @@ export function relayout(engine, measureLines) {
         const bounds = getRelativeLayoutBounds(lyricsElement, line.lyricElement);
         line.position = bounds.y;
         line.height = bounds.height;
+        line.decorations = new Map(lineDecorators(line.lyricElement).map(element => [element, getRelativeLayoutBounds(lyricsElement, element).y]));
     }
     engine.wasUserScrolling = true; // trigger rescrolls
     engine.host.debug?.resize();
 }
+// -- Decoration slide --------------------------
+const DECORATION_SLIDE_MS = 350;
+const DECORATION_SLIDE_EASING = "cubic-bezier(0.25, 1, 0.5, 1)";
+const DECORATION_MIN_SHIFT_PX = 0.5;
+function slideElementBy(element, dy) {
+    element.animate({ translate: [`0 ${dy}px`, "0 0"] }, { duration: DECORATION_SLIDE_MS, easing: DECORATION_SLIDE_EASING, composite: "add" });
+}
+function decorationSlideAllowed(engine, container) {
+    if (engine.window.matchMedia(REDUCED_MOTION_QUERY).matches)
+        return false;
+    return (engine.window.getComputedStyle(container).getPropertyValue("--blyrics-animate-decoration-entry").trim() !== "0");
+}
+function lineDecorators(lineElement) {
+    return [
+        ...lineElement.querySelectorAll(`.${ROMANIZED_LYRICS_CLASS}`),
+        ...lineElement.querySelectorAll(`.${TRANSLATED_LYRICS_CLASS}`),
+    ];
+}
+/**
+ * Snapshots where the lines and their decorators sit now, so the remeasure that follows can slide
+ * each one from there to wherever a streamed decoration just pushed it. Returns null when nothing
+ * should animate, and otherwise a function to call once the new layout is measured: the line rides
+ * its own shift and a decorator rides only the part of its shift its line did not already carry, so
+ * a survivor whose line held still still slides into the gap a removed sibling left.
+ */
+function captureDecorationSlide(engine) {
+    const container = engine.lyricsContainer;
+    if (!container || !decorationSlideAllowed(engine, container))
+        return null;
+    const before = engine.lines.map(line => ({
+        line,
+        position: line.position,
+        decorations: new Map(line.decorations),
+    }));
+    return () => {
+        for (const { line, position, decorations } of before) {
+            const lineShift = position - line.position;
+            if (Math.abs(lineShift) >= DECORATION_MIN_SHIFT_PX)
+                slideElementBy(line.lyricElement, lineShift);
+            for (const [element, was] of decorations) {
+                const now = line.decorations.get(element);
+                if (now === undefined)
+                    continue;
+                const shift = was - now - lineShift;
+                if (Math.abs(shift) >= DECORATION_MIN_SHIFT_PX)
+                    slideElementBy(element, shift);
+            }
+        }
+    };
+}
 // -- Debounced Lyrics Update --------------------------
 function cancelLyricPositionUpdate(engine) {
     if (engine.pendingLyricsUpdateFrame === null)
@@ -1971,7 +2022,9 @@ export function scheduleLyricPositionUpdate(engine, isViewRendering, retick) {
     engine.pendingLyricsUpdateFrame = engine.window.requestAnimationFrame(() => {
         engine.pendingLyricsUpdateFrame = null;
         const isRendering = isViewRendering();
+        const playSlide = isRendering ? captureDecorationSlide(engine) : null;
         relayout(engine, isRendering);
+        playSlide?.();
         if (!isRendering)
             return;
         retick();

package/dist/inject.d.ts

@@ -28,6 +28,7 @@ export type LineData = {
     isSelected: boolean;
     height: number;
     position: number;
+    decorations: Map<HTMLElement, number>;
 } & AnimationData;
 export declare function newLineData(lyricElement: HTMLElement, startTimeMs: number, durationMs: number): LineData;
 export declare function applyDirection(element: HTMLElement, text: string): void;

package/dist/inject.js

@@ -83,6 +83,7 @@ export function newLineData(lyricElement, startTimeMs, durationMs) {
         isSelected: false,
         height: -1,
         position: -1,
+        decorations: new Map(),
         animations: [],
     };
 }

package/dist/styles/lyrics.css

@@ -184,6 +184,8 @@
 
 .blyrics--translated,
 .blyrics--romanized {
+	animation: blyrics-decoration-in calc(var(--blyrics-animate-decoration-entry) * 0.35s)
+		cubic-bezier(0.25, 1, 0.5, 1) both;
 	color: var(--blyrics-translated-color);
 	display: block;
 	font-family: var(--blyrics-translated-font-family);
@@ -197,6 +199,13 @@
 	white-space: normal;
 }
 
+@keyframes blyrics-decoration-in {
+	from {
+		opacity: 0;
+		transform: translateY(-0.4em);
+	}
+}
+
 .blyrics--romanized {
 	background: rgba(255, 255, 255, 0.05);
 	border: 1px solid rgba(255, 255, 255, 0.1);

package/dist/styles/variables.css

@@ -63,6 +63,7 @@
 	--blyrics-animate-highlight-fade: 1;
 	--blyrics-animate-scroll: 1;
 	--blyrics-animate-instrumental: 1;
+	--blyrics-animate-decoration-entry: 1;
 
 	--blyrics-loader-transition-duration: 0.6s;
 	--blyrics-loader-transition-easing: cubic-bezier(0.22, 1, 0.36, 1);
@@ -176,6 +177,7 @@
 		--blyrics-animate-line-scale: 0;
 		--blyrics-animate-word-wobble: 0;
 		--blyrics-animate-instrumental: 0;
+		--blyrics-animate-decoration-entry: 0;
 
 		--blyrics-scale: 1;
 		--blyrics-active-scale: 1;

package/dist/types.d.ts

@@ -163,9 +163,14 @@ export interface LyricsRenderer {
      */
     clearOnScreenLyrics(): boolean;
     /**
-     * Re-measures the lines on the next frame and renders the view again against them. The predicate
-     * is the caller's half of whether that frame does anything, and only that half: whether the lines
-     * are on the screen to be measured at all is the renderer's own question, and it asks it itself.
+     * Re-measures the lines on the next frame and renders the view again against them. This is the door
+     * a consumer knocks on after streaming in a translation or romanization, and it is what slides the
+     * lines the new decoration moved from where they were to where it put them, together with any
+     * surviving decorator that shifted within its own line, so the rest of the lyric eases down rather
+     * than jumping. The slide honours reduced motion and `--blyrics-animate-decoration-entry`; with
+     * either off the lines are re-measured with no slide. The predicate is the caller's half of whether
+     * that frame does anything, and only that half: whether the lines are on the screen to be measured
+     * at all is the renderer's own question, and it asks it itself.
      *
      * @param isTicking - Whether whoever drives this view is still driving it, asked on the frame
      *   rather than now. A driver that has stopped is one whose lines may no longer be rendered, and

package/package.json

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