@design-edito/tools 0.5.6 → 0.5.7

package/components/Scrllgngn/utils.js

@@ -75,10 +75,16 @@ export function lazyLoadedBlocks(blocks, depth, currentPagePos, lazyLoadDistance
  * never inherit the same names from an ancestor component. `initial` leaves them
  * behaving exactly as an unset variable would, without opening the hole.
  *
+ * The public set describes the component's own box and nothing else. The private
+ * one is narrowed to what the fixed layers may actually occupy — the component's
+ * box **intersected** with the visible zone — so a viewport offset pushes them off
+ * whatever covers that edge without the stylesheet doing arithmetic.
+ *
  * @param rect - The measured bounding rect, absent until the first resize lands.
+ * @param zone - The measured visible zone, absent until the probe reports.
  * @returns The custom properties, keyed by their full name.
  */
-export function toScreenCssProps(rect) {
+export function toScreenCssProps(rect, zone) {
     const publicProps = rect === undefined
         ? {}
         : {
@@ -91,14 +97,30 @@ export function toScreenCssProps(rect) {
             '--lm-scrllgngn-screen-height': `${rect.height}px`,
             '--lm-scrllgngn-screen-height-raw': `${rect.height}`
         };
+    const inZone = toZoneClampedRect(rect, zone);
     return {
         ...publicProps,
-        '--PRIVATE-left': toPrivateLength(rect?.left),
-        '--PRIVATE-right': toPrivateLength(rect?.right),
-        '--PRIVATE-width': toPrivateLength(rect?.width),
+        '--PRIVATE-left': toPrivateLength(inZone?.left),
+        '--PRIVATE-right': toPrivateLength(inZone?.right),
+        '--PRIVATE-width': toPrivateLength(inZone?.width),
         '--PRIVATE-height': toPrivateLength(rect?.height)
     };
 }
+/** The component's box, cut down to the horizontal span of the visible zone. */
+function toZoneClampedRect(rect, zone) {
+    if (rect === undefined)
+        return undefined;
+    if (zone === undefined)
+        return rect;
+    const left = Math.max(rect.left, zone.left);
+    const right = Math.min(rect.right, window.innerWidth - zone.right);
+    return {
+        left,
+        right,
+        width: Math.max(right - left, 0),
+        height: rect.height
+    };
+}
 function toPrivateLength(value) {
     return value === undefined ? 'initial' : `${value}px`;
 }
@@ -155,12 +177,11 @@ export function contiguousRunContaining(zone, page) {
  *
  * @param pageElements - Every page slot, indexed by position.
  * @param pagePositions - The positions worth measuring.
- * @param thresholdOffsetPercent - The same offset the internal `Paginator` uses,
- * as a percentage of the viewport height.
+ * @param thresholdY - The threshold line, in pixels from the viewport top. See
+ * {@link toThresholdY}.
  * @returns The metrics of each measurable page, keyed by position.
  */
-export function measurePages(pageElements, pagePositions, thresholdOffsetPercent) {
-    const thresholdY = window.innerHeight * (thresholdOffsetPercent ?? 0) / 100;
+export function measurePages(pageElements, pagePositions, thresholdY) {
     const measured = new Map();
     for (const pagePos of pagePositions) {
         const element = pageElements[pagePos];
@@ -293,3 +314,116 @@ export function scrollKey(pagePos, blockPos) {
 export function scrollBlocksOf(page) {
     return page.blocks?.filter(block => block.depth === 'scroll' || block.depth === undefined) ?? [];
 }
+function toCssLength(offset) {
+    if (offset === undefined)
+        return '0px';
+    return typeof offset === 'number' ? `${offset}px` : offset;
+}
+/**
+ * Builds the custom properties carrying the visible zone's insets.
+ *
+ * They are emitted whatever the props hold, `0px` standing in for an edge left
+ * unset: the probe and the fixed layers position themselves against them, and an
+ * absent name would let an enclosing component's value inherit through.
+ *
+ * @param offsets - The edges as authored.
+ * @returns The custom properties, keyed by their full name.
+ */
+export function toViewportOffsetCssProps(offsets) {
+    const top = toCssLength(offsets.top);
+    const right = toCssLength(offsets.right);
+    const bottom = toCssLength(offsets.bottom);
+    const left = toCssLength(offsets.left);
+    return {
+        '--lm-scrllgngn-viewport-offset-top': top,
+        '--lm-scrllgngn-viewport-offset-right': right,
+        '--lm-scrllgngn-viewport-offset-bottom': bottom,
+        '--lm-scrllgngn-viewport-offset-left': left,
+        '--PRIVATE-viewport-offset-top': top,
+        '--PRIVATE-viewport-offset-right': right,
+        '--PRIVATE-viewport-offset-bottom': bottom,
+        '--PRIVATE-viewport-offset-left': left
+    };
+}
+/**
+ * Reads the visible zone off the probe element.
+ *
+ * The probe is fixed and inset by the four offsets, so its rect *is* the zone —
+ * which is how a `var()`, a `clamp()` or a breakpoint-dependent length reaches
+ * JavaScript without anyone parsing a CSS length.
+ *
+ * @param probeRect - The probe's bounding rect.
+ * @returns The zone, as insets from each viewport edge plus its own size.
+ */
+export function toVisibleZoneRect(probeRect) {
+    return {
+        top: probeRect.top,
+        right: window.innerWidth - probeRect.right,
+        bottom: window.innerHeight - probeRect.bottom,
+        left: probeRect.left,
+        width: probeRect.width,
+        height: probeRect.height
+    };
+}
+/**
+ * Shrinks an {@link IntersectionObserver} root down to the visible zone.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @returns A `rootMargin`, or `undefined` to leave the observer on the full
+ * viewport.
+ */
+export function toVisibleZoneRootMargin(zone) {
+    if (zone === undefined)
+        return undefined;
+    return `${-zone.top}px ${-zone.right}px ${-zone.bottom}px ${-zone.left}px`;
+}
+/**
+ * Places the threshold line, in pixels from the viewport top.
+ *
+ * `thresholdOffsetPercent` reads as a percentage **of the visible zone**, not of
+ * the viewport: a threshold at 50% has to sit halfway down what the reader can
+ * actually see, or it lands under whatever covers the top of the screen.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The line's distance from the viewport top.
+ */
+export function toThresholdY(zone, thresholdOffsetPercent) {
+    const percent = thresholdOffsetPercent ?? 0;
+    if (zone === undefined)
+        return window.innerHeight * percent / 100;
+    return zone.top + zone.height * percent / 100;
+}
+/**
+ * Restates the threshold as the percentage of the **viewport** an
+ * {@link IntersectionObserver} needs, since that is the only frame `rootMargin`
+ * knows.
+ *
+ * With no offsets set the zone spans the viewport and the number comes back
+ * unchanged, so nothing moves for a component that never asked for any of this.
+ *
+ * @param zone - The measured zone, absent until the probe reports.
+ * @param thresholdOffsetPercent - The offset as authored.
+ * @returns The equivalent viewport percentage, to hand to the internal `Paginator`.
+ */
+export function toPaginatorThresholdPercent(zone, thresholdOffsetPercent) {
+    if (zone === undefined)
+        return thresholdOffsetPercent;
+    const viewportHeight = window.innerHeight;
+    if (viewportHeight === 0)
+        return thresholdOffsetPercent;
+    return toThresholdY(zone, thresholdOffsetPercent) / viewportHeight * 100;
+}
+/** How often the visible zone is re-read while the component is on screen, in ms. */
+export const visibleZonePollInterval = 100;
+/** Whether two zones hold the same six measurements. */
+export function visibleZonesAreEqual(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a.top === b.top
+        && a.right === b.right
+        && a.bottom === b.bottom
+        && a.left === b.left
+        && a.width === b.width
+        && a.height === b.height;
+}

package/components/ScrollListener/index.d.ts

@@ -1,5 +1,5 @@
 import { type FunctionComponent, type PropsWithChildren } from 'react';
-import type { WithClassName } from '../utils/types.js';
+import type { WithClassName, WithViewportObservation } from '../utils/types.js';
 import { type ScrollState } from './utils.js';
 /**
  * Props for the {@link ScrollListener} component.
@@ -17,17 +17,21 @@ import { type ScrollState } from './utils.js';
  * it has fully left it. Never on mount.
  * @property onScrollDirectionChanged - Called after the document scroll
  * direction changed, with `'up'` or `'down'`. Never on mount.
+ * @property threshold - How much of the component has to be in view before it
+ * counts as visible, forwarded to the internal {@link IntersectionObserver}.
+ * @property root - The observer's root. Defaults to the viewport.
+ * @property rootMargin - Grows or shrinks that root before measuring.
  * @property className - Optional additional class name(s) applied to the root element.
  * @property children - React nodes rendered inside the scroll listener container.
  */
-export type Props = PropsWithChildren<WithClassName<{
+export type Props = PropsWithChildren<WithClassName<WithViewportObservation<{
     startOnVisible?: boolean;
     stopOnHidden?: boolean;
     onScrollStateChanged?: (scrollState?: ScrollState) => void;
     onVisibilityChanged?: (isVisible: boolean) => void;
     onScrollProgressChanged?: (progress: number) => void;
     onScrollDirectionChanged?: (direction: 'up' | 'down') => void;
-}>>;
+}>>>;
 /**
  * Exposes scroll metrics — both the document's and its own — as CSS custom
  * properties on its root element, so scroll-driven styling needs no JavaScript

package/components/ScrollListener/index.js

@@ -45,7 +45,7 @@ import cssModule from './styles.module.css';
  * for everyone, each element only for itself. The listeners exist only while at
  * least one instance is tracking.
  */
-export const ScrollListener = ({ startOnVisible, stopOnHidden, onScrollStateChanged, onVisibilityChanged, onScrollProgressChanged, onScrollDirectionChanged, className, children }) => {
+export const ScrollListener = ({ startOnVisible, stopOnHidden, threshold, root, rootMargin, onScrollStateChanged, onVisibilityChanged, onScrollProgressChanged, onScrollDirectionChanged, className, children }) => {
     // State & refs
     const [subscriberId] = useState(() => randomHash(6));
     const [scrollState, setScrollState] = useState();
@@ -96,5 +96,5 @@ export const ScrollListener = ({ startOnVisible, stopOnHidden, onScrollStateChan
     const customProps = scrollState === undefined
         ? {}
         : toScrollCssProps(scrollState);
-    return _jsx("div", { className: rootClss, ref: rootRef, style: { ...customProps }, children: _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: children }) });
+    return _jsx("div", { className: rootClss, ref: rootRef, style: { ...customProps }, children: _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: handleIntersection, children: children }) });
 };

package/components/Sequencer/index.d.ts

@@ -1,5 +1,6 @@
 import { type FunctionComponent } from 'react';
 import { type Props as IOCompProps } from '../IntersectionObserver/index.js';
+import type { ViewportObserverOptions } from '../utils/types.js';
 import { type Props as ControlledProps } from './index.controlled.js';
 /**
  * Props for the {@link Sequencer} component.
@@ -29,6 +30,13 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * component enters the viewport. No-op when `play` is controlled.
  * @property pauseOnHidden - When `true`, pauses internal playback when the
  * component leaves the viewport. No-op when `play` is controlled.
+ * @property threshold - How much of the component has to be in view before it
+ * counts as visible, forwarded to the internal {@link IntersectionObserver}.
+ * @property root - The observer's root. Defaults to the viewport.
+ * @property rootMargin - Grows or shrinks that root before measuring.
+ * @property onVisibilityChanged - Called on every crossing with the new value.
+ * `onIntersected` is the raw form of the same event, carrying the entry and the
+ * observer; this one carries the answer.
  * @property onIntersected - Forwarded verbatim to the internal
  * {@link IntersectionObserverComponent}, and called on every intersection
  * change whichever mode the sequencer runs in.
@@ -42,7 +50,7 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * @property onReachedLastStep - Called when the forwarded step becomes the last
  * one.
  */
-export type Props = Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
+export type Props = ViewportObserverOptions & Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
     defaultStep?: number;
     tempo?: number;
     play?: boolean;
@@ -54,6 +62,7 @@ export type Props = Omit<ControlledProps, 'isPlaying' | 'tempo'> & {
     playOnVisible?: boolean;
     pauseOnHidden?: boolean;
     onIntersected?: IOCompProps['onIntersected'];
+    onVisibilityChanged?: (isVisible: boolean) => void;
     onIsPlayingChanged?: (isPlaying: boolean) => void;
     onStepChanged?: (step: number) => void;
     onLooped?: () => void;

package/components/Sequencer/index.js

@@ -30,7 +30,7 @@ import { ControlledSequencer } from './index.controlled.js';
  * @returns An {@link IntersectionObserverComponent} wrapping a
  * {@link ControlledSequencer} with the computed step and modifiers applied.
  */
-export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onIsPlayingChanged, onStepChanged, onLooped, onReachedFirstStep, onReachedLastStep, ...controlledProps }) => {
+export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, clampLast, resetOnVisible, resetOnHidden, playOnVisible, pauseOnHidden, onIntersected, onVisibilityChanged, threshold, root, rootMargin, onIsPlayingChanged, onStepChanged, onLooped, onReachedFirstStep, onReachedLastStep, ...controlledProps }) => {
     // State
     const { step, activateOnStep, children } = controlledProps;
     const [internalPlay, setInternalPlay] = useState(play ?? false);
@@ -83,9 +83,13 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
     // Action handlers
     const handleIntersection = useCallback(({ ioEntry, observer }) => {
         onIntersected?.({ ioEntry, observer });
+        const { isIntersecting } = ioEntry ?? {};
+        if (isIntersecting !== undefined)
+            onVisibilityChanged?.(isIntersecting);
+        // Both handlers fire whatever the mode: a controlled sequencer still wants to
+        // hear about the viewport, it just doesn't let it drive the step.
         if (play === true || step !== undefined)
             return;
-        const { isIntersecting } = ioEntry ?? {};
         if (isIntersecting === true) {
             if (resetOnVisible === true)
                 setInternalStep(0);
@@ -108,5 +112,5 @@ export const Sequencer = ({ defaultStep, tempo = 60, play, loop, clampFirst, cla
         onIntersected
     ]);
     // Rendering
-    return _jsx(IntersectionObserverComponent, { onIntersected: handleIntersection, children: _jsx(ControlledSequencer, { ...controlledProps, step: forwardedStep, isPlaying: actualPlay, tempo: tempo }) });
+    return _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: handleIntersection, children: _jsx(ControlledSequencer, { ...controlledProps, step: forwardedStep, isPlaying: actualPlay, tempo: tempo }) });
 };

package/components/Subtitles/index.d.ts

@@ -1,82 +1,73 @@
-import { type FunctionComponent, type PropsWithChildren } from 'react';
+import { type FunctionComponent } from 'react';
+import type { SrtCue } from '../../agnostic/subtitles/parse-srt/types.js';
 import type { WithClassName } from '../utils/types.js';
-/**
- * A single parsed subtitle entry from an SRT file.
- *
- * @property id - Sequential subtitle number.
- * @property start - Start time in milliseconds.
- * @property end - End time in milliseconds.
- * @property content - Subtitle text content.
- */
-export type ParsedSub = {
-    id: number;
-    start?: number;
-    end?: number;
-    content?: string;
-};
-/**
- * The inclusive ID boundaries of a subtitle group.
- *
- * @property startId - ID of the first subtitle in the group.
- * @property endId - ID of the last subtitle in the group.
- */
-export type SubGroupBoundaries = {
-    startId: number;
-    endId: number;
-};
 /**
  * Props for the {@link Subtitles} component.
  *
- * @property src - URL of an SRT file to fetch. Ignored if `srtFileContent` is provided.
- * If both are undefined, no subtitles are loaded.
- * @property srtFileContent - Raw SRT string used directly, bypassing any network fetch.
- * Takes precedence over `src`.
- * @property subsGroups - Optional array of subtitle IDs that act as group boundaries,
- * splitting the full subtitle list into named sections. If omitted, all subtitles
- * belong to a single group.
- * @property timecodeMs - Current media position in milliseconds. Drives which subtitles
- * receive the `--prev` and `--curr` modifiers. When `undefined`, nothing is rendered.
- * @property isEnded - When `true`, forces the last group to be treated as current,
- * regardless of `timecodeMs`. Useful to keep the final subtitle group visible after
- * media playback finishes.
- * @property onLoaded - Called with the raw SRT string once fetched. Not called
- * when `srtFileContent` is used directly, since nothing is fetched then.
- * @property onParsed - Called after the subtitles have been parsed, with the
- * resulting entries.
- * @property onLoadFailed - Called with an `Error` when the fetch or the parse fails.
+ * The three sources are tried in order — `cues`, then `srtFileContent`, then `src` —
+ * and the first one present wins. With none of them, nothing is rendered.
+ *
+ * @property cues - Already parsed cues, used as they are. Spares a consumer that
+ * holds them — from a previous `onParsed`, or from its own call to `parseSrt` —
+ * having to serialise them back to SRT.
+ * @property srtFileContent - A raw SRT string, parsed directly with no network call.
+ * @property src - URL of an SRT file to fetch and parse.
+ * @property subsGroups - Positions to split the cues on, each the **position** of a
+ * group's last cue — not the id written in the file. Order doesn't matter, and
+ * duplicate or out-of-range positions are ignored. Omitted, every cue belongs to one
+ * group.
+ * @property timecodeMs - Current media position in milliseconds. Drives the `--prev`
+ * and `--curr` modifiers. While it is `undefined`, no group is rendered.
+ * @property isEnded - When `true`, the last group is the current one whatever
+ * `timecodeMs` says, so the closing subtitles stay up once playback is over.
+ * @property onLoaded - Called with the raw SRT string once fetched. Only fires for
+ * `src`, since the other two sources fetch nothing.
+ * @property onParsed - Called with the cues after they changed. Never on mount.
+ * @property onLoadFailed - Called with an `Error` when the fetch fails, the response
+ * is not ok, or the parse throws.
  * @property className - Optional additional class name(s) applied to the root element.
- * @property children - React children rendered inside the root element, after the subtitle groups.
  */
-export type Props = PropsWithChildren<WithClassName<{
-    src?: string;
+export type Props = WithClassName<{
+    cues?: SrtCue[];
     srtFileContent?: string;
+    src?: string;
     subsGroups?: number[];
     timecodeMs?: number;
     isEnded?: boolean;
     onLoaded?: (subs: string) => void;
-    onParsed?: (subs: ParsedSub[]) => void;
+    onParsed?: (subs: SrtCue[]) => void;
     onLoadFailed?: (error: Error) => void;
-}>>;
+}>;
 /**
- * Subtitle synchronization component. Fetches or receives an SRT source, parses it,
- * and renders subtitle groups whose individual spans are styled according to the
- * current media timecode.
+ * Subtitle synchronization component. Takes an SRT source — parsed cues, a raw
+ * string, or a URL to fetch — and renders its cues in groups, marking where the
+ * media currently is.
  *
- * ### Group elements
- * Each subtitle group is a `<div>` with the following:
- * - `--curr` modifier when the group contains the subtitle at the current timecode.
- * - `data-start-sub-pos` — ID of the first subtitle in the group.
- * - `data-end-sub-pos` — ID of the last subtitle in the group.
+ * ### CSS elements
+ * - `lm-subtitles` — the root. Carries `--loading` while a fetch is in flight, and
+ * `--error` once one failed. Both are cleared when a new source starts loading.
+ * - `lm-subtitles__group` — one per group. Carries `--curr` when the reader is in it.
+ * - `lm-subtitles__sub` — one per cue. Carries `--prev` once the playhead has passed
+ * its start, and `--curr` while the playhead is inside its interval.
  *
- * ### Subtitle span elements
- * Each individual subtitle is a `<span>` with the following:
- * - `--prev` modifier when the subtitle's start time is at or before the last elapsed subtitle.
- * - `--curr` modifier when `timecodeMs` falls within the subtitle's `[start, end]` interval.
- * - `data-sub-pos` — the subtitle's numeric ID from the SRT source.
+ * ### Data attributes
+ * On a group: `data-start-sub-pos` and `data-end-sub-pos`, its bounds as positions
+ * in the cue array. On a cue: `data-sub-pos`, its position, and `data-sub-id`, the
+ * number written in the file.
  *
  * @param props - Component properties.
  * @see {@link Props}
- * @returns A root `<div>` containing the rendered subtitle groups, or an empty `<div>`
- * when `timecodeMs` is undefined or no subtitles have been parsed yet.
+ * @returns A root `<div>` holding the subtitle groups, empty while there is no
+ * timecode or no cue.
+ *
+ * @remarks
+ * Uncontrolled only. The cues are state, fed by whichever source is set: there is no
+ * controlled variant, because a consumer holding its own cues passes them as `cues`
+ * and owns them outright.
+ *
+ * Cues are rendered back to back with no separator — the space between two of them
+ * is presentation, and belongs in a stylesheet (`lm-subtitles__sub + …::before`, a
+ * `word-spacing`, whatever suits) rather than in the text content, where it would
+ * come back out of `textContent`.
  */
 export declare const Subtitles: FunctionComponent<Props>;