@design-edito/tools 0.5.38 → 0.5.39

package/components/Video/index.d.ts

@@ -6,13 +6,6 @@ import { type Props as ControlledProps } from './index.controlled.js';
  * Props for the {@link Video} component.
  *
  * Extends all ControlledVideo props except play, mute, fullscreen, volume, playbackRate, and their associated event handlers
- * @property behavioursSuspended - Holds back the instructions that **start** something,
- * and lets through those that stop it. For a consumer withholding the video behind
- * something — a warning to accept, typically: a video kept back that plays anyway is not
- * withheld, it is merely hard to see. What was held back is replayed the moment this
- * goes false, so lifting the veil on an already-visible video does what was asked, which
- * a crossing-based trigger could never do. `':force'` does not override it: it speaks of
- * consent not yet given, where a surrender speaks of an intention already expressed.
  * @property visibilityThreshold - How much of the video has to be on screen to count as
  * seen. See {@link VisibilityOptions} for this and the four that follow it.
  * @property whenVisible - What to do each time it becomes visible.
@@ -39,7 +32,6 @@ import { type Props as ControlledProps } from './index.controlled.js';
  */
 export type Props = Omit<ControlledProps, 'play' | 'fullscreen' | 'volume' | 'mute' | 'playbackRate' | 'subtitlesOn' | 'rootRef' | 'videoRef'> & ViewportBehaviours<VideoAction> & {
     defaultSubtitlesOn?: boolean;
-    behavioursSuspended?: boolean;
 };
 /**
  * Full-featured video player component. Wraps a native `<video>` element with

package/components/Video/index.js

@@ -51,7 +51,7 @@ import { ControlledVideo } from './index.controlled.js';
  * The media still won't play, though: autoplay muted, and leave unmuting to the
  * reader.
  */
-export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onVisibilityChanged, onVideoClicked, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, ...controlledProps }) => {
+export const Video = ({ defaultSubtitlesOn = true, visibilityThreshold, visibilityRoot, visibilityRootMargin, visibilityOnAfterMs, visibilityOffAfterMs, whenVisible, whenHidden, onVisibilityChanged, onVideoClicked, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, onSubtitlesButtonClicked, ...controlledProps }) => {
     // State & refs
     const [play, setPlay] = useState(false);
     const [volume, setVolume] = useState(1);
@@ -73,14 +73,11 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
     // **Seeking belongs to `playback`.** A reader who has dragged the timeline has said
     // where they want to be, and an automatic jump would take it back from them.
     const actions = {
-        play: { kind: 'start', domain: 'playback', run: () => setPlay(true) },
-        pause: { kind: 'stop', domain: 'playback', run: () => setPlay(false) },
-        loud: { kind: 'start', domain: 'sound', run: () => setMute(false) },
-        mute: { kind: 'stop', domain: 'sound', run: () => setMute(true) },
-        // A seek starts nothing on its own — it moves a playhead, playing or not — so a gate
-        // has no reason to hold it back.
+        play: { domain: 'playback', run: () => setPlay(true) },
+        pause: { domain: 'playback', run: () => setPlay(false) },
+        loud: { domain: 'sound', run: () => setMute(false) },
+        mute: { domain: 'sound', run: () => setMute(true) },
         'jump-to': {
-            kind: 'stop',
             domain: 'playback',
             run: arg => {
                 const targetMs = Number(arg);
@@ -89,8 +86,8 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
                 forceJumpTo(videoRef.current, targetMs);
             }
         },
-        'jump-start': { kind: 'stop', domain: 'playback', run: () => forceJumpTo(videoRef.current, 0) },
-        'jump-end': { kind: 'stop', domain: 'playback', run: () => forceJumpTo(videoRef.current, -1) }
+        'jump-start': { domain: 'playback', run: () => forceJumpTo(videoRef.current, 0) },
+        'jump-end': { domain: 'playback', run: () => forceJumpTo(videoRef.current, -1) }
     };
     const { surrender: surrenderAnyDomain } = useViewportBehaviours(rootRef, {
         visibilityThreshold,
@@ -101,7 +98,7 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
         whenVisible,
         whenHidden,
         onVisibilityChanged
-    }, actions, behavioursSuspended === true);
+    }, actions);
     // Narrowed back to this component's own domains. The generic layer takes a `string`,
     // having no vocabulary of its own; handing the handlers a typed door means a
     // misspelled domain fails to compile instead of quietly never surrendering anything.
@@ -185,10 +182,9 @@ export const Video = ({ defaultSubtitlesOn = true, behavioursSuspended, visibili
         onFullscreenButtonClicked?.(payload);
         setFullscreen(!payload.isFullscreen);
     }, [onFullscreenButtonClicked]);
-    // Un seul bouton pour les deux sens, contrairement à lecture/pause et son/muet qui en
-    // ont un chacun : ceux-là existent en paire dans le DOM et la feuille en montre un,
-    // parce qu'ils portent deux glyphes opposés. Les sous-titres n'en portent qu'un, dont
-    // seul l'habillage change — inutile d'en rendre deux pour n'en montrer jamais qu'un.
+    // One button for both directions, where play/pause and loud/mute get one each: those
+    // carry two opposed glyphs, so both are rendered and the stylesheet shows one. The
+    // subtitles button carries a single glyph whose styling alone changes.
     const handleSubtitlesButtonClick = useCallback(payload => {
         onSubtitlesButtonClicked?.(payload);
         setSubtitlesOn(!payload.isSubtitlesOn);

package/components/Video/types.d.ts

@@ -40,3 +40,36 @@ export type VideoAction = Exclude<VideoVerb, 'jump-to'> | `jump-to:${number}`;
  * want to be, and an automatic jump would take it back from them.
  */
 export type VideoDomain = 'playback' | 'sound';
+/**
+ * One `<source>` of a `<video>`.
+ *
+ * **Not interchangeable with a picture source**: a `<source>` inside a `<video>` carries
+ * `src`, one inside a `<picture>` carries `srcSet`, `media` and `sizes`, and neither
+ * element accepts the other's attributes.
+ *
+ * @property src - URL of the video file.
+ * @property type - MIME type, so the browser can skip what it cannot play
+ * (`'video/mp4'`).
+ */
+export type SourceData = {
+    src?: string;
+    type?: string;
+};
+/**
+ * One `<track>` of a `<video>` — subtitles, captions, chapters.
+ *
+ * @property src - URL of the WebVTT file.
+ * @property kind - What the track holds. Browsers default to `'subtitles'`.
+ * @property srclang - Its BCP 47 language tag, required by the element whenever `kind`
+ * is `'subtitles'`.
+ * @property label - The name a browser shows in its own track menu.
+ * @property default - Whether it is the one enabled when no preference says otherwise.
+ * At most one track per element may carry it.
+ */
+export type TrackData = {
+    src?: string;
+    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
+    srclang?: string;
+    label?: string;
+    default?: boolean;
+};

package/components/Video/utils.d.ts

@@ -1,41 +1,7 @@
-/**
- * The two list shapes a `<video>` accepts as children, as records.
- *
- * They live here and not next to the component because nothing about them is React:
- * they describe a `<source>` and a `<track>` element.
- *
- * **A video source is not a picture source**, which is why `Image` keeps a shape of its
- * own rather than sharing this one: a `<source>` inside a `<video>` carries `src`, one
- * inside a `<picture>` carries `srcSet`, `media` and `sizes`, and neither element accepts
- * the other's attributes. What the two do share is how a list of them is read — see
- * `parseSourceList` in `components/utils`.
- */
-export type SourceData = {
-    src?: string;
-    type?: string;
-};
-export type TrackData = {
-    src?: string;
-    kind?: 'subtitles' | 'captions' | 'descriptions' | 'chapters' | 'metadata';
-    srclang?: string;
-    label?: string;
-    default?: boolean;
-};
 export declare const muteAttributeWorkaround: (video: HTMLVideoElement | null, shouldMute: boolean) => void;
 export declare const forceMute: (video: HTMLVideoElement | null) => void;
 export declare const forceLoud: (video: HTMLVideoElement | null) => void;
 export declare const forceVolume: (video: HTMLVideoElement | null, volume: number) => void;
-/**
- * Asks the element to play, and reports what came of it.
- *
- * A browser may refuse — an unmuted media outside a user gesture, typically — and
- * it refuses **silently**: the promise rejects and no event fires, so this is the
- * only moment the outcome can be known. Hence the return value, and hence no
- * logging: a refusal is not an anomaly to print, it is an answer to hand back.
- *
- * @param video - The element, or `null` before it mounts.
- * @returns Whether it is playing now.
- */
 export declare const forcePlay: (video: HTMLVideoElement | null) => Promise<boolean>;
 export declare const forcePause: (video: HTMLVideoElement | null) => boolean;
 export declare const forcePlaybackRate: (video: HTMLVideoElement | null, rate: number) => void;
@@ -43,38 +9,6 @@ export declare const forceFullscreen: (video: HTMLVideoElement | null) => Promis
 export declare const forceExitFullscreen: (video: HTMLVideoElement | null) => Promise<boolean>;
 export declare function secondsToMs(seconds: number): number;
 export declare function msToSeconds(ms: number): number;
-/**
- * Where along the timeline a click landed.
- *
- * @param event - The click on the timeline element.
- * @returns A ratio between `0` and `1`, clamped to the element's own bounds.
- */
 export declare const getTimelineClickProgress: (event: React.MouseEvent<HTMLDivElement>) => number;
-/**
- * Whether a viewport-driven behaviour should run on this crossing.
- *
- * Each behaviour comes in two flavours: `…When…` on every crossing, `…Once…` on the
- * first one only. Setting both is the same as setting `…When…` alone.
- *
- * @param whenCrossed - The `…When…` prop.
- * @param onceOnly - The `…Once…` prop.
- * @param hasFired - Whether this behaviour's own automatic trigger already ran. It
- * tracks that behaviour and nothing else: a user pressing play must not spend an
- * automatic mute the component still owed.
- * @returns Whether to apply it now.
- */
-/**
- * Seeks the element, in milliseconds, counting from the end when asked negatively.
- *
- * **A negative target counts back from the duration**, so `-1` is the last reachable
- * timecode. It is `-1` and not `-0` because `-0 === 0` in JavaScript, which would make
- * the end of a video indistinguishable from its start.
- *
- * Nothing happens before the metadata lands: the duration is `NaN` until then, and a
- * seek computed against it would land anywhere. An instruction asking for the end of a
- * video whose length is still unknown is simply not yet answerable.
- *
- * @param video - The element, or `null` before it mounts.
- * @param targetMs - Where to go. Negative counts from the end.
- */
 export declare const forceJumpTo: (video: HTMLVideoElement | null, targetMs: number) => void;
+export declare function parseSrcSetSourcesList<T extends Record<string, unknown>>(given: string | string[] | T[] | undefined, stringKey: keyof T & string): T[];

package/components/Video/utils.js

@@ -28,17 +28,8 @@ export const forceVolume = (video, volume) => {
     // eslint-disable-next-line no-param-reassign
     video.volume = volume;
 };
-/**
- * Asks the element to play, and reports what came of it.
- *
- * A browser may refuse — an unmuted media outside a user gesture, typically — and
- * it refuses **silently**: the promise rejects and no event fires, so this is the
- * only moment the outcome can be known. Hence the return value, and hence no
- * logging: a refusal is not an anomaly to print, it is an answer to hand back.
- *
- * @param video - The element, or `null` before it mounts.
- * @returns Whether it is playing now.
- */
+// A browser refuses playback silently: the promise rejects and no event fires, so the
+// return value is the only way the caller learns the outcome.
 export const forcePlay = async (video) => {
     if (video === null)
         return false;
@@ -107,44 +98,13 @@ export function secondsToMs(seconds) {
 export function msToSeconds(ms) {
     return ms / 1000;
 }
-/**
- * Where along the timeline a click landed.
- *
- * @param event - The click on the timeline element.
- * @returns A ratio between `0` and `1`, clamped to the element's own bounds.
- */
 export const getTimelineClickProgress = (event) => {
     const timelineRect = event.currentTarget.getBoundingClientRect();
     const position = event.clientX - timelineRect.left;
     return Math.min(1, Math.max(0, position / timelineRect.width));
 };
-/**
- * Whether a viewport-driven behaviour should run on this crossing.
- *
- * Each behaviour comes in two flavours: `…When…` on every crossing, `…Once…` on the
- * first one only. Setting both is the same as setting `…When…` alone.
- *
- * @param whenCrossed - The `…When…` prop.
- * @param onceOnly - The `…Once…` prop.
- * @param hasFired - Whether this behaviour's own automatic trigger already ran. It
- * tracks that behaviour and nothing else: a user pressing play must not spend an
- * automatic mute the component still owed.
- * @returns Whether to apply it now.
- */
-/**
- * Seeks the element, in milliseconds, counting from the end when asked negatively.
- *
- * **A negative target counts back from the duration**, so `-1` is the last reachable
- * timecode. It is `-1` and not `-0` because `-0 === 0` in JavaScript, which would make
- * the end of a video indistinguishable from its start.
- *
- * Nothing happens before the metadata lands: the duration is `NaN` until then, and a
- * seek computed against it would land anywhere. An instruction asking for the end of a
- * video whose length is still unknown is simply not yet answerable.
- *
- * @param video - The element, or `null` before it mounts.
- * @param targetMs - Where to go. Negative counts from the end.
- */
+// A negative target counts back from the duration, `-1` being the last reachable
+// timecode — not `-0`, which `===` makes indistinguishable from the start.
 export const forceJumpTo = (video, targetMs) => {
     if (video === null)
         return;
@@ -155,3 +115,24 @@ export const forceJumpTo = (video, targetMs) => {
     // eslint-disable-next-line no-param-reassign
     video.currentTime = msToSeconds(Math.min(Math.max(absolute, 0), durationMs));
 };
+/* Source lists */
+export function parseSrcSetSourcesList(given, stringKey) {
+    const fromString = (value) => {
+        const single = { [stringKey]: value };
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a one-key record is the narrowest `T` a bare string can describe; every other field is optional by contract
+        return single;
+    };
+    if (given === undefined)
+        return [];
+    if (typeof given === 'string')
+        return [fromString(given)];
+    if (!Array.isArray(given))
+        return [];
+    if (given.length === 0)
+        return [];
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is read as homogeneous
+    if (typeof given[0] === 'string')
+        return given.map(fromString);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is read as homogeneous
+    return given;
+}

package/components/index.d.ts

@@ -1,6 +1,6 @@
 export * as beforeAfter from './BeforeAfter/index.js'
-export * as clippable from './Clippable/index.js'
 export * as button from './Button/index.js'
+export * as clippable from './Clippable/index.js'
 export * as disclaimer from './Disclaimer/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
@@ -11,8 +11,8 @@ export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as jsonEditor from './JsonEditor/index.js'
 export * as lightbox from './Lightbox/index.js'
-export * as overlayer from './Overlayer/index.js'
 export * as listLoader from './ListLoader/index.js'
+export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
 export * as scrllgngn from './Scrllgngn/index.js'

package/components/index.js

@@ -1,6 +1,6 @@
 export * as beforeAfter from './BeforeAfter/index.js'
-export * as clippable from './Clippable/index.js'
 export * as button from './Button/index.js'
+export * as clippable from './Clippable/index.js'
 export * as disclaimer from './Disclaimer/index.js'
 export * as drawer from './Drawer/index.js'
 export * as eventListener from './EventListener/index.js'
@@ -11,8 +11,8 @@ export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
 export * as jsonEditor from './JsonEditor/index.js'
 export * as lightbox from './Lightbox/index.js'
-export * as overlayer from './Overlayer/index.js'
 export * as listLoader from './ListLoader/index.js'
+export * as overlayer from './Overlayer/index.js'
 export * as paginator from './Paginator/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
 export * as scrllgngn from './Scrllgngn/index.js'

package/components/utils/index.d.ts

@@ -1,44 +1 @@
-export declare function mergeClassNames(...names: Array<string | null | undefined | Array<string | null | undefined>>): string;
-/**
- * Calls `onChange` whenever `value` changes, and only then — never on mount.
- *
- * This is how a component reports one of its state items to its consumer:
- * a bare `useEffect` on the value would also fire on the first render, telling
- * the consumer something changed when nothing did.
- *
- * @template T - Type of the watched value.
- * @param value - The value to watch.
- * @param onChange - Called with the new value, once the change has happened.
- * @param isEqual - Decides whether the value actually changed. Defaults to
- * `Object.is`, which covers booleans, numbers and strings. Pass a custom
- * comparison for values rebuilt on every render, such as an array or an object
- * derived from state, whose identity always differs.
- *
- * @remarks
- * `onChange` is deliberately left out of the effect's dependencies. A consumer
- * passing an inline arrow creates a new function on every render, which would
- * re-run the effect each time and defeat the guard. The handler is read when the
- * effect fires, so it is never a stale one.
- */
-export declare function useChangeDispatch<T>(value: T, onChange?: (value: T) => void, isEqual?: (a: T, b: T) => boolean): void;
-/**
- * The three forms a `<source>` list is written in, reduced to the one a render uses.
- *
- * A bare string is a single source, an array of strings is several, an array of records
- * is taken as given. **The array is read as homogeneous** — the first element decides for
- * all of them —, which is what someone writing one by hand means anyway, and the only
- * reading a static hyper-json array could support.
- *
- * `stringKey` is the whole reason this is shared rather than written twice. The parsing
- * is identical for `Video` and `Image`, but **the shorthand does not name the same
- * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
- * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
- * source also takes `media` and `sizes`, which a video source has no use for, and neither
- * element accepts the other's key. One element, one shape; only the reading is common.
- *
- * @template T - The record shape the caller's element accepts.
- * @param given - What the consumer wrote.
- * @param stringKey - Where a bare string goes.
- * @returns The list as records, empty when there is nothing to render.
- */
-export declare function parseSourceList<T extends Record<string, unknown>>(given: string | string[] | T[] | undefined, stringKey: keyof T & string): T[];
+export * as viewportBehaviours from './viewport-behaviours/index.js'

package/components/utils/index.js

@@ -1,83 +1 @@
-import { useEffect, useRef } from 'react';
-export function mergeClassNames(...names) {
-    return names.map(name => {
-        if (typeof name !== 'string' && !Array.isArray(name))
-            return false;
-        if (Array.isArray(name))
-            return mergeClassNames(...name);
-        if (name.trim() === '')
-            return false;
-        return name.trim();
-    }).filter((name) => typeof name === 'string')
-        .join(' ');
-}
-/**
- * Calls `onChange` whenever `value` changes, and only then — never on mount.
- *
- * This is how a component reports one of its state items to its consumer:
- * a bare `useEffect` on the value would also fire on the first render, telling
- * the consumer something changed when nothing did.
- *
- * @template T - Type of the watched value.
- * @param value - The value to watch.
- * @param onChange - Called with the new value, once the change has happened.
- * @param isEqual - Decides whether the value actually changed. Defaults to
- * `Object.is`, which covers booleans, numbers and strings. Pass a custom
- * comparison for values rebuilt on every render, such as an array or an object
- * derived from state, whose identity always differs.
- *
- * @remarks
- * `onChange` is deliberately left out of the effect's dependencies. A consumer
- * passing an inline arrow creates a new function on every render, which would
- * re-run the effect each time and defeat the guard. The handler is read when the
- * effect fires, so it is never a stale one.
- */
-export function useChangeDispatch(value, onChange, isEqual = Object.is) {
-    const previousRef = useRef(value);
-    useEffect(() => {
-        if (isEqual(previousRef.current, value))
-            return;
-        previousRef.current = value;
-        onChange?.(value);
-    }, [value]);
-}
-/**
- * The three forms a `<source>` list is written in, reduced to the one a render uses.
- *
- * A bare string is a single source, an array of strings is several, an array of records
- * is taken as given. **The array is read as homogeneous** — the first element decides for
- * all of them —, which is what someone writing one by hand means anyway, and the only
- * reading a static hyper-json array could support.
- *
- * `stringKey` is the whole reason this is shared rather than written twice. The parsing
- * is identical for `Video` and `Image`, but **the shorthand does not name the same
- * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
- * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
- * source also takes `media` and `sizes`, which a video source has no use for, and neither
- * element accepts the other's key. One element, one shape; only the reading is common.
- *
- * @template T - The record shape the caller's element accepts.
- * @param given - What the consumer wrote.
- * @param stringKey - Where a bare string goes.
- * @returns The list as records, empty when there is nothing to render.
- */
-export function parseSourceList(given, stringKey) {
-    const fromString = (value) => {
-        const single = { [stringKey]: value };
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a one-key record is the narrowest `T` a bare string can describe; every other field is optional by contract
-        return single;
-    };
-    if (given === undefined)
-        return [];
-    if (typeof given === 'string')
-        return [fromString(given)];
-    if (!Array.isArray(given))
-        return [];
-    if (given.length === 0)
-        return [];
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is read as homogeneous
-    if (typeof given[0] === 'string')
-        return given.map(fromString);
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is read as homogeneous
-    return given;
-}
+export * as viewportBehaviours from './viewport-behaviours/index.js'

package/components/utils/viewport-behaviours/index.d.ts

@@ -7,10 +7,10 @@ import type { ActionTable, ViewportBehaviours, VisibilityOptions } from './types
  * belongs by subject, because the publish step only maps `index.js` and `types.js` into
  * the package's exports — a `utils.js` is unreachable from outside, whatever it holds.
  *
- * **Exported for the consumers that receive their props as text.** lm-link reads an
- * article's XML, where nothing is typed, and has to reject `'jump-to:banana'` before it
- * reaches a component. Written on its side, the rule would exist twice and drift in
- * silence — a verb added here would be rejected there for no visible reason.
+ * **Exported for the callers that build an instruction at runtime**, out of a string
+ * nothing has typed, and have to reject `'jump-to:banana'` before it reaches a
+ * component. Written on their side, the rule would exist twice and drift in silence —
+ * a verb added here would be rejected there for no visible reason.
  *
  * Returns a plain boolean rather than a type predicate, and that is not an oversight: a
  * verb taking an argument is written `'jump-to:500'`, which is not a member of the verb
@@ -28,11 +28,9 @@ export declare function isInstruction(value: unknown, verbs: readonly string[],
 /**
  * Whether the element counts as visible — **as a state, not as a crossing**.
  *
- * That distinction is the whole point. An `IntersectionObserver` reports an event, and
- * a behaviour hung on the event only ever runs when the screen is traversed. A
- * component already visible whose behaviour was held back — behind a lm-link gate,
- * typically — never gets a second chance, because nothing crosses when the gate lifts.
- * Held as a state, the condition can be recombined with whatever else gates it.
+ * That distinction is what the delays below are built on, and what lets a caller
+ * recombine visibility with whatever else it tracks: an `IntersectionObserver` reports
+ * an event, which is readable once, where a state is readable at any moment.
  *
  * The delays are a debounce **on this state**: the element has to hold its new value
  * for that long before the value is committed. A component crossed while scrolling fast
@@ -63,10 +61,6 @@ export type ViewportBehavioursResult = {
  * @param targetRef - The element to watch.
  * @param props - The component's visibility props.
  * @param table - What each of its verbs does. @see {@link ActionTable}
- * @param suspended - Holds back the verbs that **start** something, and lets through
- * those that stop something. This is a capability's doing — a lm-link gate — and it is
- * not the same as a surrender: a gate speaks of consent not yet given, so `':force'`
- * does not override it.
  *
  * @remarks
  * **An instruction yields to the reader by default.** The failure modes are not
@@ -75,4 +69,4 @@ export type ViewportBehavioursResult = {
  * `':force'` opts out, and is expected to be rare — which is why it is the written form
  * and yielding is the silent one.
  */
-export declare function useViewportBehaviours<A extends string>(targetRef: RefObject<Element | null>, props: ViewportBehaviours<A>, table: ActionTable<A>, suspended?: boolean): ViewportBehavioursResult;
+export declare function useViewportBehaviours<A extends string>(targetRef: RefObject<Element | null>, props: ViewportBehaviours<A>, table: ActionTable<A>): ViewportBehavioursResult;

package/components/utils/viewport-behaviours/index.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useIntersectionObserver } from '../../IntersectionObserver/index.js';
-import { useChangeDispatch } from '../index.js';
+import { useStateChangeDispatch } from '../../../agnostic/@react/effects/use-state-change-dispatch/index.js';
 import { parseInstruction, toInstructionList } from './utils.js';
 /**
  * Whether a string is an instruction this vocabulary answers to.
@@ -9,10 +9,10 @@ import { parseInstruction, toInstructionList } from './utils.js';
  * belongs by subject, because the publish step only maps `index.js` and `types.js` into
  * the package's exports — a `utils.js` is unreachable from outside, whatever it holds.
  *
- * **Exported for the consumers that receive their props as text.** lm-link reads an
- * article's XML, where nothing is typed, and has to reject `'jump-to:banana'` before it
- * reaches a component. Written on its side, the rule would exist twice and drift in
- * silence — a verb added here would be rejected there for no visible reason.
+ * **Exported for the callers that build an instruction at runtime**, out of a string
+ * nothing has typed, and have to reject `'jump-to:banana'` before it reaches a
+ * component. Written on their side, the rule would exist twice and drift in silence —
+ * a verb added here would be rejected there for no visible reason.
  *
  * Returns a plain boolean rather than a type predicate, and that is not an oversight: a
  * verb taking an argument is written `'jump-to:500'`, which is not a member of the verb
@@ -40,11 +40,9 @@ export function isInstruction(value, verbs, withArgument = {}) {
 /**
  * Whether the element counts as visible — **as a state, not as a crossing**.
  *
- * That distinction is the whole point. An `IntersectionObserver` reports an event, and
- * a behaviour hung on the event only ever runs when the screen is traversed. A
- * component already visible whose behaviour was held back — behind a lm-link gate,
- * typically — never gets a second chance, because nothing crosses when the gate lifts.
- * Held as a state, the condition can be recombined with whatever else gates it.
+ * That distinction is what the delays below are built on, and what lets a caller
+ * recombine visibility with whatever else it tracks: an `IntersectionObserver` reports
+ * an event, which is readable once, where a state is readable at any moment.
  *
  * The delays are a debounce **on this state**: the element has to hold its new value
  * for that long before the value is committed. A component crossed while scrolling fast
@@ -84,10 +82,6 @@ export function useVisibilityState(targetRef, options = {}, enabled = true) {
  * @param targetRef - The element to watch.
  * @param props - The component's visibility props.
  * @param table - What each of its verbs does. @see {@link ActionTable}
- * @param suspended - Holds back the verbs that **start** something, and lets through
- * those that stop something. This is a capability's doing — a lm-link gate — and it is
- * not the same as a surrender: a gate speaks of consent not yet given, so `':force'`
- * does not override it.
  *
  * @remarks
  * **An instruction yields to the reader by default.** The failure modes are not
@@ -96,7 +90,7 @@ export function useVisibilityState(targetRef, options = {}, enabled = true) {
  * `':force'` opts out, and is expected to be rare — which is why it is the written form
  * and yielding is the silent one.
  */
-export function useViewportBehaviours(targetRef, props, table, suspended = false) {
+export function useViewportBehaviours(targetRef, props, table) {
     const { whenVisible, whenHidden, onVisibilityChanged } = props;
     // The table closes over the component's state, so it is a new object on every render
     // and has no business in a dependency list. Read through a ref, it is never stale.
@@ -109,8 +103,7 @@ export function useViewportBehaviours(targetRef, props, table, suspended = false
     tableRef.current = new Map(Object.entries(table));
     const surrenderedRef = useRef(new Set());
     const spentRef = useRef(new Set());
-    const heldBackRef = useRef(new Set());
-    const lastRunRef = useRef({ suspended });
+    const lastRunRef = useRef({});
     const surrender = useCallback((domain) => {
         surrenderedRef.current.add(domain);
     }, []);
@@ -120,7 +113,7 @@ export function useViewportBehaviours(targetRef, props, table, suspended = false
     const isVisible = useVisibilityState(targetRef, props, needsObserve);
     // Reported on the **settled** state, delays included: a consumer watching visibility
     // and a consumer running instructions have to be told the same story.
-    useChangeDispatch(isVisible, next => {
+    useStateChangeDispatch(isVisible, next => {
         if (next === undefined)
             return;
         onVisibilityChanged?.(next);
@@ -129,42 +122,27 @@ export function useViewportBehaviours(targetRef, props, table, suspended = false
         if (isVisible === undefined)
             return;
         const last = lastRunRef.current;
-        const crossed = last.isVisible !== isVisible;
-        const released = !crossed && last.suspended && !suspended;
-        lastRunRef.current = { isVisible, suspended };
-        // Neither the state nor the suspension moved: nothing to do. Without this, any
-        // unrelated re-render would replay the list.
-        if (!crossed && !released)
+        // Without this, any unrelated re-render would replay the list.
+        if (last.isVisible === isVisible)
             return;
+        lastRunRef.current = { isVisible };
         const trigger = isVisible ? 'visible' : 'hidden';
         const list = toInstructionList(isVisible ? whenVisible : whenHidden);
         const runnable = dedupe(list);
-        if (released)
-            heldBackRef.current.clear();
         for (const parsed of runnable) {
             const key = `${trigger}|${parsed.verb}|${parsed.arg ?? ''}`;
-            // A suspension only reaches a verb that *starts* something, and it is the only
-            // one of the two brakes that can be lifted — hence the held-back list, replayed
-            // on release so a gate opening on a visible component does what it was asked.
             const spec = tableRef.current.get(parsed.verb);
             if (spec === undefined)
                 continue;
-            if (released && !heldBackRef.current.has(key))
-                continue;
-            if (suspended && spec.kind === 'start') {
-                heldBackRef.current.add(key);
-                continue;
-            }
             if (!parsed.force && surrenderedRef.current.has(spec.domain))
                 continue;
             if (parsed.once && spentRef.current.has(key))
                 continue;
             if (parsed.once)
                 spentRef.current.add(key);
-            heldBackRef.current.delete(key);
             spec.run(parsed.arg);
         }
-    }, [isVisible, suspended, whenVisible, whenHidden]);
+    }, [isVisible, whenVisible, whenHidden]);
     return { isVisible, surrender };
 }
 /**