@design-edito/tools 0.5.8 → 0.5.10

package/components/Lightbox/index.js

@@ -0,0 +1,191 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createPortal } from 'react-dom';
+import { clss } from '../../agnostic/css/clss/index.js';
+import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
+import { lightbox as publicClassName } from '../public-classnames.js';
+import { close as closeLightbox, getState, membersOf, open as openLightbox, register, soloGroupOf, step, subscribe, unregister } from './store.js';
+import cssModule from './styles.module.css';
+/**
+ * Lightbox component. Holds content in place until opened, then moves it into an
+ * overlay covering the page.
+ *
+ * ### CSS modifiers
+ * - `on` - this member is open.
+ * - `off` - it is not.
+ * - `grouped` - it belongs to a group it did not invent, so navigation is possible.
+ *
+ * ### CSS elements
+ * - `placeholder` - holds the content's last measured size while it is away.
+ * - `backdrop` - the overlay, portalled to `document.body`, mounted only while open.
+ * - `content` - wraps the moved content inside the lightbox.
+ * - `open-btn`, `close-btn`, `prev-btn`, `next-btn`
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A root `<div>` holding the content or its placeholder, plus, while open, a
+ * lightbox portalled to the end of `document.body`.
+ *
+ * @remarks
+ * - **[WIP]** Moving a `<video>` keeps it playing on desktop browsers; iOS has been
+ *   known to pause on a DOM move. Not worth guarding against for now.
+ * - **The content is moved, not copied.** A portal relocates the DOM node without
+ *   changing the element's place in the React tree, so the instance is never
+ *   unmounted: a playing video keeps playing, at its timecode, and lands back where it
+ *   was on close. Rendering `children` twice would mount a second, fresh instance and
+ *   leave the first one running behind the lightbox.
+ * - **The lightbox is portalled to `document.body`.** A `position: fixed` overlay left in
+ *   the article would be trapped by the first ancestor carrying a `transform`, a
+ *   `filter` or a `contain`, which becomes its containing block.
+ * - **A placeholder keeps the layout still.** Its size is the content's last measured
+ *   one, read while closed; without it the article would collapse around the hole the
+ *   content leaves.
+ * - **Groups are held outside React**, in `./store.ts`: a consumer may render each
+ *   component in a root of its own, in which case members of a group share no tree
+ *   and a context could not reach from one to the other.
+ * - The lightbox is rendered by whichever member is on it, so navigating hands it over.
+ *   None of the content is remounted in the process.
+ * - This component ships **no appearance**: covering the page, the backdrop and the
+ *   buttons are the consumer stylesheet's business. Without one, the content is moved
+ *   to the end of the document and nothing looks like a lightbox.
+ */
+export const Lightbox = ({ group, closeBtnContent, openBtnContent, prevBtnContent, nextBtnContent, isOn: isOnProp, defaultIsOn = false, exitOnEscape, exitOnBgClick, navOnArrowKeys, onOpenButtonClicked, onCloseButtonClicked, onPrevButtonClicked, onNextButtonClicked, onBackgroundClicked, onEscapePressed, onPrevArrowPressed, onNextArrowPressed, onIsOnChanged, children, className }) => {
+    // State & refs
+    const id = useId();
+    const rootRef = useRef(null);
+    const backdropRef = useRef(null);
+    const sizeRef = useRef(null);
+    const [hasAppliedDefault, setHasAppliedDefault] = useState(false);
+    const isControlled = isOnProp !== undefined;
+    const declaredGroups = group === undefined
+        ? []
+        : (Array.isArray(group) ? group : [group]);
+    const isGrouped = declaredGroups.length > 0;
+    // A member without a group still needs one to be opened through: its own.
+    const groups = isGrouped ? declaredGroups : [soloGroupOf(id)];
+    // `groups` is never empty: a member without a declared group gets its own.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const ownGroup = groups[0];
+    const groupsKey = groups.join(' ');
+    const storeState = useSyncExternalStore(subscribe, getState, getState);
+    const isOn = isOnProp ?? (storeState.openMemberId === id);
+    const openGroup = storeState.openGroup;
+    const siblingsCount = isOn && openGroup !== null ? membersOf(openGroup).length : 0;
+    // Fx. dep. id, groupsKey - Joins the shared registry, which is what lets another
+    // member reach this one. `getElement` rather than the element itself: the registry
+    // reads it when it needs to order the group, and never holds it.
+    useEffect(() => {
+        register({ id, groups, getElement: () => rootRef.current });
+        return () => unregister(id);
+    }, [id, groupsKey]);
+    // Keeps the last size the content had in place, so the placeholder can hold it once
+    // the content is gone. Measured while closed only, on render rather than through a
+    // standing observer: the content of a lightbox rarely resizes, and one observer per
+    // image on a page is a cost with no return.
+    useLayoutEffect(() => {
+        if (isOn)
+            return;
+        const root = rootRef.current;
+        if (root === null)
+            return;
+        const { width, height } = root.getBoundingClientRect();
+        if (width === 0 && height === 0)
+            return;
+        sizeRef.current = { width, height };
+    });
+    // State dispatch
+    useChangeDispatch(isOn, onIsOnChanged);
+    // User action handlers
+    const requestOpen = useCallback(() => {
+        if (isControlled)
+            return;
+        openLightbox(ownGroup, id);
+    }, [isControlled, ownGroup, id]);
+    const requestClose = useCallback(() => {
+        if (isControlled)
+            return;
+        closeLightbox();
+    }, [isControlled]);
+    const handleOpenButtonClick = () => {
+        onOpenButtonClicked?.(isOn);
+        requestOpen();
+    };
+    const handleCloseButtonClick = () => {
+        onCloseButtonClicked?.(isOn);
+        requestClose();
+    };
+    const handlePrevButtonClick = () => {
+        onPrevButtonClicked?.(isOn);
+        step(-1);
+    };
+    const handleNextButtonClick = () => {
+        onNextButtonClicked?.(isOn);
+        step(1);
+    };
+    const handleBackdropClick = e => {
+        if (exitOnBgClick !== true)
+            return;
+        if (e.target !== backdropRef.current)
+            return;
+        onBackgroundClicked?.(isOn);
+        requestClose();
+    };
+    // Fx. dep. exitOnEscape, isOn, requestClose, onEscapePressed - Escape closes the
+    // lightbox. Listens only while open, so a page of closed lightboxes holds no
+    // listener.
+    useEffect(() => {
+        if (exitOnEscape !== true || !isOn)
+            return;
+        const handleKeyDown = (e) => {
+            if (e.key !== 'Escape')
+                return;
+            onEscapePressed?.(isOn);
+            requestClose();
+        };
+        window.addEventListener('keydown', handleKeyDown);
+        return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [exitOnEscape, isOn, requestClose, onEscapePressed]);
+    // Fx. dep. navOnArrowKeys, isOn, siblingsCount, onPrevArrowPressed,
+    // onNextArrowPressed - The arrow keys walk the open group. Bound only while the
+    // lightbox is open and the group holds someone else, so the keys stay the page's the
+    // rest of the time.
+    useEffect(() => {
+        if (navOnArrowKeys !== true || !isOn || siblingsCount < 2)
+            return;
+        const handleKeyDown = (e) => {
+            if (e.key === 'ArrowLeft') {
+                onPrevArrowPressed?.(isOn);
+                step(-1);
+            }
+            else if (e.key === 'ArrowRight') {
+                onNextArrowPressed?.(isOn);
+                step(1);
+            }
+        };
+        window.addEventListener('keydown', handleKeyDown);
+        return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [navOnArrowKeys, isOn, siblingsCount, onPrevArrowPressed, onNextArrowPressed]);
+    // Fx. dep. hasAppliedDefault, isControlled, defaultIsOn, ownGroup, id - An
+    // uncontrolled lightbox asked to start open says so once, and never again: the
+    // registry owns the state from then on.
+    useEffect(() => {
+        if (hasAppliedDefault || isControlled || !defaultIsOn)
+            return;
+        setHasAppliedDefault(true);
+        openLightbox(ownGroup, id);
+    }, [hasAppliedDefault, isControlled, defaultIsOn, ownGroup, id]);
+    // Rendering
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, {
+        on: isOn,
+        off: !isOn,
+        grouped: isGrouped
+    }), className);
+    const size = sizeRef.current;
+    const overlay = isOn
+        ? createPortal(_jsxs("div", { className: c('backdrop'), onClick: handleBackdropClick, ref: backdropRef, children: [_jsx("div", { className: c('content'), children: children }), _jsx("button", { type: 'button', className: c('close-btn'), onClick: handleCloseButtonClick, children: closeBtnContent }), siblingsCount > 1 && _jsxs(_Fragment, { children: [_jsx("button", { type: 'button', className: c('prev-btn'), onClick: handlePrevButtonClick, children: prevBtnContent }), _jsx("button", { type: 'button', className: c('next-btn'), onClick: handleNextButtonClick, children: nextBtnContent })] })] }), document.body)
+        : null;
+    return _jsxs("div", { className: rootClss, ref: rootRef, children: [isOn
+                ? _jsx("div", { className: c('placeholder'), style: size === null ? undefined : { width: size.width, height: size.height } })
+                : children, _jsx("button", { type: 'button', className: c('open-btn'), onClick: handleOpenButtonClick, children: openBtnContent }), overlay] });
+};

package/components/Lightbox/store.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The registry of lightbox groups, shared by every {@link Lightbox} on the page.
+ *
+ * Deliberately outside React. lm-link renders each component in its **own React
+ * root** — `renderInTarget` calls `createRoot` per component — so two `<lm-image>`
+ * in the same article never share a tree, and a context could not reach from one to
+ * the other. A module-level store can.
+ *
+ * Members are kept unordered here; the order that matters is the **document's**, and
+ * it is read from the DOM when a group opens. React's mount order is not it.
+ */
+/** What a member hands the store so the group can find and place it. */
+export type LightboxMember = {
+    id: string;
+    groups: string[];
+    /** The member's anchor in the page, for ordering. `null` before it mounts. */
+    getElement: () => HTMLElement | null;
+};
+export type LightboxState = {
+    /** The group currently open, `null` when nothing is. */
+    openGroup: string | null;
+    /** The member currently shown. */
+    openMemberId: string | null;
+};
+export declare function subscribe(listener: () => void): () => void;
+export declare function getState(): LightboxState;
+/** A member's own group, when it declared none: it is a group of one. */
+export declare function soloGroupOf(id: string): string;
+export declare function register(member: LightboxMember): void;
+export declare function unregister(id: string): void;
+/**
+ * The members of a group, in **document order**.
+ *
+ * `compareDocumentPosition` rather than mount order: React mounts a tree in its own
+ * order, and lm-link mounts each component in a root of its own, so nothing
+ * guarantees the two match. Only runs when a group opens or navigates, over a
+ * handful of members.
+ */
+export declare function membersOf(group: string): LightboxMember[];
+export declare function open(group: string, memberId: string): void;
+export declare function close(): void;
+/** Moves to another member of the open group by `offset`, clamped at both ends. */
+export declare function step(offset: number): void;

package/components/Lightbox/store.js

@@ -0,0 +1,94 @@
+/**
+ * The registry of lightbox groups, shared by every {@link Lightbox} on the page.
+ *
+ * Deliberately outside React. lm-link renders each component in its **own React
+ * root** — `renderInTarget` calls `createRoot` per component — so two `<lm-image>`
+ * in the same article never share a tree, and a context could not reach from one to
+ * the other. A module-level store can.
+ *
+ * Members are kept unordered here; the order that matters is the **document's**, and
+ * it is read from the DOM when a group opens. React's mount order is not it.
+ */
+const members = new Map();
+const listeners = new Set();
+let state = {
+    openGroup: null,
+    openMemberId: null
+};
+function emit() {
+    for (const listener of listeners)
+        listener();
+}
+function setState(next) {
+    if (next.openGroup === state.openGroup
+        && next.openMemberId === state.openMemberId)
+        return;
+    state = next;
+    emit();
+}
+export function subscribe(listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}
+export function getState() {
+    return state;
+}
+/** A member's own group, when it declared none: it is a group of one. */
+export function soloGroupOf(id) {
+    return `solo:${id}`;
+}
+export function register(member) {
+    members.set(member.id, member);
+    emit();
+}
+export function unregister(id) {
+    members.delete(id);
+    // A member leaving while it is the one shown would strand the group on nothing.
+    if (state.openMemberId === id)
+        setState({ openGroup: null, openMemberId: null });
+    else
+        emit();
+}
+/**
+ * The members of a group, in **document order**.
+ *
+ * `compareDocumentPosition` rather than mount order: React mounts a tree in its own
+ * order, and lm-link mounts each component in a root of its own, so nothing
+ * guarantees the two match. Only runs when a group opens or navigates, over a
+ * handful of members.
+ */
+export function membersOf(group) {
+    const found = [...members.values()].filter(member => member.groups.includes(group));
+    return found.sort((a, b) => {
+        const aElt = a.getElement();
+        const bElt = b.getElement();
+        if (aElt === null || bElt === null)
+            return 0;
+        const position = aElt.compareDocumentPosition(bElt);
+        if ((position & Node.DOCUMENT_POSITION_FOLLOWING) !== 0)
+            return -1;
+        if ((position & Node.DOCUMENT_POSITION_PRECEDING) !== 0)
+            return 1;
+        return 0;
+    });
+}
+export function open(group, memberId) {
+    setState({ openGroup: group, openMemberId: memberId });
+}
+export function close() {
+    setState({ openGroup: null, openMemberId: null });
+}
+/** Moves to another member of the open group by `offset`, clamped at both ends. */
+export function step(offset) {
+    const { openGroup, openMemberId } = state;
+    if (openGroup === null || openMemberId === null)
+        return;
+    const ordered = membersOf(openGroup);
+    const current = ordered.findIndex(member => member.id === openMemberId);
+    if (current === -1)
+        return;
+    const target = ordered[Math.min(ordered.length - 1, Math.max(0, current + offset))];
+    if (target === undefined)
+        return;
+    setState({ openGroup, openMemberId: target.id });
+}

package/components/Paginator/index.d.ts

@@ -25,7 +25,9 @@ type DirectionState = 'forwards' | 'backwards' | null;
  *
  * @property thresholdOffsetPercent - Optional percentage offset used to compute
  * the {@link IntersectionObserver} root margin. Determines how far into the viewport
- * a page must be before it is considered `'curr'`. Defaults to `0`.
+ * a page must be before it is considered `'curr'`. Defaults to `0`. Clamped to
+ * 0–100, with a `console.warn` naming the value received — outside that range the
+ * root margin is invalid and the observer would throw.
  *
  * @property onDirectionChanged - Called after the scroll direction changed, with
  * the new {@link DirectionState}. Repeated scrolls in the same direction do not
@@ -64,7 +66,10 @@ export type Props = PropsWithChildren<WithClassName<{
  *   when the direction actually changes, using an internal ref to avoid stale
  *   closure comparisons.
  * - Page visibility is tracked via a single {@link IntersectionObserver} instance
- *   that is recreated when `thresholdOffsetPercent` or `children` change.
+ *   that is recreated when `thresholdOffsetPercent` or the **number** of children
+ *   changes. Not on `children` itself: a parent building its child list inline hands
+ *   over a new array on every render, which would tear down and rebuild one observer
+ *   per page each time, for nothing.
  * - `currCount` on each {@link PageState} increments each time a page transitions
  *   into the `'curr'` position, making it useful as a re-entry counter.
  */

package/components/Paginator/index.js

@@ -4,6 +4,18 @@ import { clss } from '../../agnostic/css/clss/index.js';
 import { mergeClassNames, useChangeDispatch } from '../utils/index.js';
 import { paginator as publicClassName } from '../public-classnames.js';
 import cssModule from './styles.module.css';
+/**
+ * Brings `thresholdOffsetPercent` back into the 0–100 range `rootMargin` accepts.
+ *
+ * Outside it the margin comes out as `--20%`, which the `IntersectionObserver`
+ * constructor rejects by throwing — taking the whole component down with it over a
+ * single setting. A non-finite value falls back to `0` for the same reason.
+ */
+function toThresholdPercent(percent) {
+    if (percent === undefined || !Number.isFinite(percent))
+        return 0;
+    return Math.min(100, Math.max(0, percent));
+}
 /**
  * A scroll-driven pagination component that tracks which child page is currently
  * visible in the viewport and the direction of scroll.
@@ -23,7 +35,10 @@ import cssModule from './styles.module.css';
  *   when the direction actually changes, using an internal ref to avoid stale
  *   closure comparisons.
  * - Page visibility is tracked via a single {@link IntersectionObserver} instance
- *   that is recreated when `thresholdOffsetPercent` or `children` change.
+ *   that is recreated when `thresholdOffsetPercent` or the **number** of children
+ *   changes. Not on `children` itself: a parent building its child list inline hands
+ *   over a new array on every render, which would tear down and rebuild one observer
+ *   per page each time, for nothing.
  * - `currCount` on each {@link PageState} increments each time a page transitions
  *   into the `'curr'` position, making it useful as a re-entry counter.
  */
@@ -33,6 +48,20 @@ export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesC
     const [directionState, setDirectionState] = useState(null);
     const pagesRef = useRef(null);
     const directionRef = useRef(null);
+    const childrenArr = Children.toArray(children);
+    const pagesCount = childrenArr.length;
+    const thresholdPercent = toThresholdPercent(thresholdOffsetPercent);
+    // Fx. dep. thresholdOffsetPercent, thresholdPercent - Says it once per offending
+    // value rather than on every render. Clamping without a word would turn a caller's
+    // bug into a scrolling glitch, hunted for somewhere else entirely.
+    useEffect(() => {
+        if (thresholdOffsetPercent === undefined)
+            return;
+        if (thresholdPercent === thresholdOffsetPercent)
+            return;
+        // eslint-disable-next-line no-console
+        console.warn('Paginator: thresholdOffsetPercent must be a number between 0 and 100, received', thresholdOffsetPercent, `— clamped to ${thresholdPercent}.`);
+    }, [thresholdOffsetPercent, thresholdPercent]);
     // State dispatch
     useChangeDispatch(pagesState, pages => onPagesChanged?.(Array
         .from(pages)
@@ -62,15 +91,24 @@ export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesC
             window.removeEventListener('resize', handleScroll);
         };
     }, []);
-    // Detect active pages with Intersection Observer
+    // Fx. dep. pagesCount - The page slots are this component's own divs, reused as
+    // long as their number holds, so the set only changes when the count does.
     useEffect(() => {
         if (pagesRef.current === null)
             return;
         const pages = Array.from(pagesRef.current.children);
         onPageElementsChanged?.(pages.filter(page => page instanceof HTMLElement));
-        const observerRootMargin = `-${thresholdOffsetPercent ?? 0}%`
+    }, [pagesCount]);
+    // Detect active pages with Intersection Observer
+    // Fx. dep. thresholdPercent, pagesCount - Same reasoning: rebuilding one observer
+    // per page on every render would cost a full measurement pass for an unchanged set.
+    useEffect(() => {
+        if (pagesRef.current === null)
+            return;
+        const pages = Array.from(pagesRef.current.children);
+        const observerRootMargin = `-${thresholdPercent}%`
             + ' 0px'
-            + ` -${100 - (thresholdOffsetPercent ?? 0)}%`
+            + ` -${100 - thresholdPercent}%`
             + ' 0px';
         const observer = new IntersectionObserver(entries => {
             setPagesState(prevState => {
@@ -100,7 +138,7 @@ export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesC
             observer.observe(page);
         });
         return () => observer.disconnect();
-    }, [thresholdOffsetPercent, children]);
+    }, [thresholdPercent, pagesCount]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(null, {
@@ -108,7 +146,6 @@ export const Paginator = ({ thresholdOffsetPercent, onDirectionChanged, onPagesC
         backwards: directionState === 'backwards'
     }), className);
     const pagesClss = c('pages');
-    const childrenArr = Children.toArray(children);
     return _jsx("div", { className: rootClss, children: _jsx("div", { className: pagesClss, ref: pagesRef, children: childrenArr.map((child, pos) => {
                 const state = pagesState.get(pos);
                 const pageClss = c('page', {

package/components/Video/index.controlled.d.ts

@@ -38,7 +38,9 @@ type TrackData = {
  * @property loudBtnContent - React content for the "loud" (unmute) button.
  * @property muteBtnContent - React content for the mute button.
  * @property fullscreenBtnContent - React content for the fullscreen button.
- * @property play - External control of play state (true = play, false = pause).
+ * @property play - Whether the media should be playing. A **request**, not a
+ * setting: a browser holds a veto over playback — an unmuted media outside a user
+ * gesture is refused — so this prop asks, and `onIsPlayingChanged` answers.
  * @property fullscreen - External control of fullscreen mode.
  * @property volume - External control of volume (0 to 1).
  * @property mute - External control of mute (true = muted).
@@ -67,7 +69,10 @@ type TrackData = {
  * @property onTimelineClicked - Called when the timeline is clicked, before the
  * component reacts, with the target and current times (in seconds). The component
  * seeks to the target right after, unless the time is controlled.
- * @property onIsPlayingChanged - Called once the playback state has changed.
+ * @property onIsPlayingChanged - Called with what the **element** is doing, not
+ * with what `play` asked for. It is how a refused play surfaces, that being the one
+ * case where nothing else does: the promise rejects, no event fires, and without
+ * this a parent would go on believing a media that never started. Never on mount.
  * @property onIsFullscreenChanged - Called once the fullscreen state has changed.
  * @property onIsEndedChanged - Called after playback reached the end, and again
  * once it left it — a seek back or a new play. Never on mount.

package/components/Video/index.controlled.js

@@ -59,6 +59,10 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
     // element, and the two events that turn it on and off are joined by a sync on
     // every time update, which covers a seek away from the end.
     const [isEnded, setIsEnded] = useState(false);
+    // What the element is actually doing, as opposed to what `play` asked for. The
+    // two part ways whenever a browser refuses a play, which it does without firing
+    // anything — see `forcePlay`.
+    const [isElementPlaying, setIsElementPlaying] = useState(false);
     const isTimeControlled = givenCurrentTimeMs !== undefined;
     // The parent owns the time as soon as it provides one, so that is what gets
     // displayed — not what the element reported one render later.
@@ -92,12 +96,18 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
     }, [intrinsicVideoAttributes.onTimeUpdate]);
     const handleEndedEvent = useCallback((e) => {
         setIsEnded(true);
+        setIsElementPlaying(false);
         intrinsicVideoAttributes.onEnded?.(e);
     }, [intrinsicVideoAttributes.onEnded]);
     const handlePlayEvent = useCallback((e) => {
         setIsEnded(false);
+        setIsElementPlaying(true);
         intrinsicVideoAttributes.onPlay?.(e);
     }, [intrinsicVideoAttributes.onPlay]);
+    const handlePauseEvent = useCallback((e) => {
+        setIsElementPlaying(false);
+        intrinsicVideoAttributes.onPause?.(e);
+    }, [intrinsicVideoAttributes.onPause]);
     // Custom action handlers
     const handlePlayButtonClick = useCallback((e) => {
         const wasPlaying = videoRef.current?.paused === false;
@@ -239,12 +249,18 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
             void forcePause(videoRef.current);
             return;
         }
-        if (play === true) {
-            void forcePlay(videoRef.current);
-        }
-        else {
+        if (play !== true) {
             void forcePause(videoRef.current);
+            return;
         }
+        let isCurrent = true;
+        void forcePlay(videoRef.current).then(isNowPlaying => {
+            // A refused play fires nothing, so without this the component would go on
+            // believing a media that never started.
+            if (isCurrent && !isNowPlaying)
+                setIsElementPlaying(false);
+        });
+        return () => { isCurrent = false; };
     }, [play, isTimeControlled]);
     useEffect(() => {
         forceVolume(videoRef.current, volume);
@@ -276,13 +292,13 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
     }, [onFullscreenChange]);
     // State handlers
     useChangeDispatch(currentTimeMs, onCurrentTimeMsChanged);
-    useChangeDispatch(isPlaying, onIsPlayingChanged);
+    useChangeDispatch(isElementPlaying, onIsPlayingChanged);
     useChangeDispatch(isFullscreen, onIsFullscreenChanged);
     useChangeDispatch(isLoud, onIsLoudChanged);
     useChangeDispatch(isEnded, onIsEndedChanged);
     useChangeDispatch(volume, onVolumeChanged);
     useChangeDispatch(playbackRate, onPlaybackRateChanged);
-    return _jsxs("figure", { className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, autoPlay: isTimeControlled ? false : intrinsicVideoAttributes.autoPlay, onLoadedMetadata: handleMetadataLoadEvent, onTimeUpdate: handleOnTimeUpdateEvent, onEnded: handleEndedEvent, onPlay: handlePlayEvent, children: [parsedSources.map((source, index) => typeof source === 'string'
+    return _jsxs("figure", { className: rootClss, style: rootStyles, ...rootAttributes, children: [_jsxs("video", { ref: videoRef, className: videoClss, ...intrinsicVideoAttributes, autoPlay: isTimeControlled ? false : intrinsicVideoAttributes.autoPlay, onLoadedMetadata: handleMetadataLoadEvent, onTimeUpdate: handleOnTimeUpdateEvent, onEnded: handleEndedEvent, onPlay: handlePlayEvent, onPause: handlePauseEvent, children: [parsedSources.map((source, index) => typeof source === 'string'
                         ? _jsx("source", { src: source }, index)
                         : _jsx("source", { src: source.src, type: source.type }, index)), parsedTracks.map((track, index) => typeof track === 'string'
                         ? _jsx("track", { src: track }, index)

package/components/Video/index.d.ts

@@ -74,8 +74,10 @@ export type Props = WithViewportObservation<Omit<ControlledProps, 'play' | 'full
  * behaviour is the same as setting the `…When…` one alone.
  *
  * Browsers refuse an unmuted `play()` outside a user gesture, so pairing an
- * `autoLoud…` with an `autoPlay…` will usually have the playback rejected: the
- * element stays paused while the controls believe otherwise. Autoplay muted, and
- * leave unmuting to the reader.
+ * `autoLoud…` with an `autoPlay…` will usually have the playback rejected. The
+ * refusal is caught rather than ignored — the element is read back once the attempt
+ * settles, and the play state follows what it says — so the controls stay truthful.
+ * The media still won't play, though: autoplay muted, and leave unmuting to the
+ * reader.
  */
 export declare const Video: FunctionComponent<Props>;

package/components/Video/index.js

@@ -35,9 +35,11 @@ import { ControlledVideo } from './index.controlled.js';
  * behaviour is the same as setting the `…When…` one alone.
  *
  * Browsers refuse an unmuted `play()` outside a user gesture, so pairing an
- * `autoLoud…` with an `autoPlay…` will usually have the playback rejected: the
- * element stays paused while the controls believe otherwise. Autoplay muted, and
- * leave unmuting to the reader.
+ * `autoLoud…` with an `autoPlay…` will usually have the playback rejected. The
+ * refusal is caught rather than ignored — the element is read back once the attempt
+ * settles, and the play state follows what it says — so the controls stay truthful.
+ * The media still won't play, though: autoplay muted, and leave unmuting to the
+ * reader.
  */
 export const Video = ({ loop, autoPlayWhenVisible, autoPlayOnceVisible, autoPauseWhenHidden, autoPauseOnceHidden, autoMuteWhenHidden, autoMuteOnceHidden, autoLoudWhenVisible, autoLoudOnceVisible, threshold, root, rootMargin, onVisibilityChanged, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, ...controlledProps }) => {
     // State & refs
@@ -87,6 +89,14 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPlayOnceVisible, autoPaus
         setPlay(false);
         controlledProps.onPause?.(e);
     }, [controlledProps.onPause]);
+    // The element's own account of whether it is playing. It covers what the `play`
+    // and `pause` events do, plus the one case they can't: a play the browser refused,
+    // which fires nothing at all. Without it the controls would stay on `--play-on`
+    // over a media that never started.
+    const handleIsPlayingChanged = useCallback((isPlaying) => {
+        setPlay(isPlaying);
+        controlledProps.onIsPlayingChanged?.(isPlaying);
+    }, [controlledProps.onIsPlayingChanged]);
     const handleOnVolumeChangeEvent = useCallback((e) => {
         setMute(e.currentTarget.muted);
         setVolume(e.currentTarget.volume);
@@ -178,7 +188,7 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPlayOnceVisible, autoPaus
     // Render
     const c = clss(publicClassName, { cssModule });
     const rootClss = mergeClassNames(c(), wrapperClassName);
-    const videoContent = _jsx(ControlledVideo, { ...controlledProps, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick });
+    const videoContent = _jsx(ControlledVideo, { ...controlledProps, play: play && !isTimeControlled, volume: volume, mute: mute, playbackRate: playbackRate, fullscreen: fullscreen, onPlay: handleOnPlayEvent, onPause: handleOnPauseEvent, onIsPlayingChanged: handleIsPlayingChanged, onVolumeChange: handleOnVolumeChangeEvent, onRateChange: handleOnRateChangeEvent, onLoadedMetadata: handleOnLoadedMetadataEvent, onFullscreenChange: handleFullscreenChange, onPlayButtonClicked: handlePlayButtonClick, onPauseButtonClicked: handlePauseButtonClick, onLoudButtonClicked: handleLoudButtonClick, onMuteButtonClicked: handleMuteButtonClick, onVolumeRangeChanged: handleVolumeRangeChange, onRateRangeChanged: handleRateRangeChange, onFullscreenButtonClicked: handleFullscreenButtonClick });
     return _jsx("div", { className: rootClss, children: needsObserve
             ? _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: onIntersected, children: videoContent })
             : videoContent });

package/components/Video/utils.d.ts

@@ -2,6 +2,17 @@ export declare const muteAttributeWorkaround: (video: HTMLVideoElement | null, s
 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;

package/components/Video/utils.js

@@ -28,6 +28,17 @@ 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.
+ */
 export const forcePlay = async (video) => {
     if (video === null)
         return false;
@@ -35,13 +46,11 @@ export const forcePlay = async (video) => {
         return true;
     try {
         await video.play();
-        return video.paused;
     }
-    catch (e) {
-        // eslint-disable-next-line no-console
-        console.error(e);
+    catch (err) {
+        // The refusal itself is the information, and it is in `video.paused` below.
     }
-    return false;
+    return !video.paused;
 };
 export const forcePause = (video) => {
     if (video === null)