@design-edito/tools 0.5.7 → 0.5.9

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/ResizeObserver/index.d.ts

@@ -20,9 +20,14 @@ export type Props = PropsWithChildren<WithClassName<{
  * rect on its root element. Both sets stay absent until the first measurement
  * lands.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the sets below are populated.
+ *
  * ### Data attributes
  * `data-x`, `data-y`, `data-top`, `data-left`, `data-bottom`, `data-right`,
- * `data-width` and `data-height` — the content rect, as plain numbers.
+ * `data-width` and `data-height` — the content rect, as plain numbers. They carry
+ * what a custom property cannot reach: `content: attr(data-width)`, and attribute
+ * selectors.
  *
  * ### CSS custom properties
  * The same eight measurements, each exposed twice: `--lm-resize-observer-width`

package/components/ResizeObserver/index.js

@@ -9,9 +9,14 @@ import cssModule from './styles.module.css';
  * rect on its root element. Both sets stay absent until the first measurement
  * lands.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the sets below are populated.
+ *
  * ### Data attributes
  * `data-x`, `data-y`, `data-top`, `data-left`, `data-bottom`, `data-right`,
- * `data-width` and `data-height` — the content rect, as plain numbers.
+ * `data-width` and `data-height` — the content rect, as plain numbers. They carry
+ * what a custom property cannot reach: `content: attr(data-width)`, and attribute
+ * selectors.
  *
  * ### CSS custom properties
  * The same eight measurements, each exposed twice: `--lm-resize-observer-width`
@@ -89,6 +94,6 @@ export const ResizeObserverComponent = ({ className, onResized, children }) => {
         };
     }
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, { measured: contentRect !== undefined }), className);
     return _jsx("div", { ...dataAttributes, className: rootClss, ref: rootRef, style: { ...cssCustomProps }, children: children });
 };

package/components/ScrollListener/index.d.ts

@@ -37,6 +37,11 @@ export type Props = PropsWithChildren<WithClassName<WithViewportObservation<{
  * properties on its root element, so scroll-driven styling needs no JavaScript
  * of its own.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the properties below are set.
+ * - `--scrolling-up` / `--scrolling-down` — the document's last known direction.
+ *   Neither is present before the first scroll.
+ *
  * ### CSS custom properties on the root element
  * Each measurement comes as a `px` length under its bare name, and as a `-raw`
  * twin holding the plain number:

package/components/ScrollListener/index.js

@@ -12,6 +12,11 @@ import cssModule from './styles.module.css';
  * properties on its root element, so scroll-driven styling needs no JavaScript
  * of its own.
  *
+ * ### Root element modifiers
+ * - `--measured` — a first measurement landed, so the properties below are set.
+ * - `--scrolling-up` / `--scrolling-down` — the document's last known direction.
+ *   Neither is present before the first scroll.
+ *
  * ### CSS custom properties on the root element
  * Each measurement comes as a `px` length under its bare name, and as a `-raw`
  * twin holding the plain number:
@@ -92,7 +97,11 @@ export const ScrollListener = ({ startOnVisible, stopOnHidden, threshold, root,
     }, [startOnVisible, stopOnHidden, onVisibilityChanged]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, {
+        measured: scrollState !== undefined,
+        'scrolling-up': scrollDirection === 'up',
+        'scrolling-down': scrollDirection === 'down'
+    }), className);
     const customProps = scrollState === undefined
         ? {}
         : toScrollCssProps(scrollState);

package/components/Select/index.d.ts

@@ -24,6 +24,10 @@ export type Props = SelectHTMLAttributes<HTMLSelectElement> & PropsWithChildren<
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`

package/components/Select/index.js

@@ -15,6 +15,10 @@ import cssModule from './styles.module.css';
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`
@@ -44,6 +48,10 @@ export const Select = ({ label, error, value, defaultValue, onChange, className,
     };
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, {
+        controlled: isControlled,
+        empty: currentValue === '',
+        filled: currentValue !== ''
+    }), className);
     return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("select", { ...rest, id: id, className: rootClss, value: currentValue, onChange: handleChange, children: children }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
 };

package/components/ShadowRoot/index.d.ts

@@ -28,6 +28,10 @@ export type Props = PropsWithChildren<WithClassName<{
  * Component that creates a Shadow Root on its host element and renders
  * its children inside that Shadow Root using a React portal.
  *
+ * ### Root element modifiers
+ * - `--attached` — the shadow root exists and the children are rendered into it.
+ * Absent on the first render, before the host element is in the document.
+ *
  * @param props - Component properties
  * @see {@link Props}
  * @returns A host `div` element that owns the created Shadow Root.

package/components/ShadowRoot/index.js

@@ -9,6 +9,10 @@ import cssModule from './styles.module.css';
  * Component that creates a Shadow Root on its host element and renders
  * its children inside that Shadow Root using a React portal.
  *
+ * ### Root element modifiers
+ * - `--attached` — the shadow root exists and the children are rendered into it.
+ * Absent on the first render, before the host element is in the document.
+ *
  * @param props - Component properties
  * @see {@link Props}
  * @returns A host `div` element that owns the created Shadow Root.
@@ -38,6 +42,6 @@ export const ShadowRootComponent = ({ mode = 'open', delegatesFocus, slotAssignm
     ]);
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, { attached: shadowRoot !== null }), className);
     return _jsx("div", { ref: hostRef, className: rootClss, children: shadowRoot !== null && createPortal(_jsxs(_Fragment, { children: [styles !== undefined && _jsx("style", { children: styles }), children] }), shadowRoot) });
 };

package/components/Textarea/index.d.ts

@@ -26,6 +26,10 @@ export type Props = TextareaHTMLAttributes<HTMLTextAreaElement> & WithClassName<
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`

package/components/Textarea/index.js

@@ -15,6 +15,10 @@ import cssModule from './styles.module.css';
  * A stable auto-generated `id` is created on mount and used to associate the
  * rendered label through the `htmlFor` attribute.
  *
+ * ### Root element modifiers
+ * - `--controlled` — the value comes from the parent, not from inside.
+ * - `--empty` / `--filled` — whether the current value is the empty string.
+ *
  * ### CSS elements
  * - `label`
  * - `error`
@@ -53,6 +57,10 @@ export const Textarea = ({ label, error, autoHeight = false, value, defaultValue
     };
     // Rendering
     const c = clss(publicClassName, { cssModule });
-    const rootClss = mergeClassNames(c(), className);
+    const rootClss = mergeClassNames(c(null, {
+        controlled: isControlled,
+        empty: currentValue === '',
+        filled: currentValue !== ''
+    }), className);
     return _jsxs(_Fragment, { children: [isNotFalsy(label) && _jsx("label", { className: c('label'), htmlFor: id, children: label }), _jsx("textarea", { ...rest, ref: textareaRef, id: id, className: rootClss, value: currentValue, onChange: handleChange }), isNotFalsy(error) && _jsx("span", { className: c('error'), children: error })] });
 };

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.
@@ -146,8 +151,14 @@ export type Props = PropsWithChildren<WithClassName<{
  * - `data-total-time-ms` — total duration in milliseconds.
  *
  * ### CSS custom properties on the root element
- * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
- * Useful for driving progress-bar animations purely in CSS.
+ * Durations come as a `ms` time under the bare name and as a plain number under a
+ * `-raw` twin; ratios are unitless and have no twin.
+ * - `--lm-video-current-time` / `--lm-video-current-time-raw`
+ * - `--lm-video-total-time` / `--lm-video-total-time-raw`
+ * - `--lm-video-current-time-ratio` — how far through the media the playhead is.
+ * What a progress bar animates on, with no JavaScript of its own.
+ * - `--lm-video-volume-ratio`
+ * - `--lm-video-playback-rate` — a multiplier, not a ratio: `1` is normal speed.
  *
  * @param props - Component properties.
  * @see {@link Props}

package/components/Video/index.controlled.js

@@ -35,8 +35,14 @@ import { forceExitFullscreen, forceFullscreen, forceLoud, forceMute, forcePause,
  * - `data-total-time-ms` — total duration in milliseconds.
  *
  * ### CSS custom properties on the root element
- * - `--video-current-time-ratio` — current / total ratio, fixed to 8 decimals.
- * Useful for driving progress-bar animations purely in CSS.
+ * Durations come as a `ms` time under the bare name and as a plain number under a
+ * `-raw` twin; ratios are unitless and have no twin.
+ * - `--lm-video-current-time` / `--lm-video-current-time-raw`
+ * - `--lm-video-total-time` / `--lm-video-total-time-raw`
+ * - `--lm-video-current-time-ratio` — how far through the media the playhead is.
+ * What a progress bar animates on, with no JavaScript of its own.
+ * - `--lm-video-volume-ratio`
+ * - `--lm-video-playback-rate` — a multiplier, not a ratio: `1` is normal speed.
  *
  * @param props - Component properties.
  * @see {@link Props}
@@ -53,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.
@@ -86,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;
@@ -159,7 +175,13 @@ export const ControlledVideo = ({ sources, tracks, subtitles, playBtnContent, pa
         'data-total-time-ms': totalTimeMs
     };
     const rootStyles = {
-        [`--${publicClassName}-current-time-ratio`]: currentTimeRatio.toFixed(8)
+        '--lm-video-current-time': `${currentTimeMs}ms`,
+        '--lm-video-current-time-raw': `${currentTimeMs}`,
+        '--lm-video-total-time': `${totalTimeMs}ms`,
+        '--lm-video-total-time-raw': `${totalTimeMs}`,
+        '--lm-video-current-time-ratio': `${currentTimeRatio}`,
+        '--lm-video-volume-ratio': `${volume}`,
+        '--lm-video-playback-rate': `${playbackRate}`
     };
     const parsedSources = useMemo(() => {
         if (sources === undefined)
@@ -227,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);
@@ -264,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)

package/index.d.ts

@@ -1,3 +1,3 @@
 export * as agnostic from './agnostic/index.js'
-export * as node from './node/index.js'
 export * as components from './components/index.js'
+export * as node from './node/index.js'

package/index.js

@@ -1,3 +1,3 @@
 export * as agnostic from './agnostic/index.js'
-export * as node from './node/index.js'
 export * as components from './components/index.js'
+export * as node from './node/index.js'

package/node/@google-cloud/storage/file/index.d.ts

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
-export * as generateSignedUrl from './generate-signed-url/index.js'
 export * as exists from './exists/index.js'
+export * as generateSignedUrl from './generate-signed-url/index.js'
 export * as getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'

package/node/@google-cloud/storage/file/index.js

@@ -1,7 +1,7 @@
 export * as copy from './copy/index.js'
 export * as download from './download/index.js'
-export * as generateSignedUrl from './generate-signed-url/index.js'
 export * as exists from './exists/index.js'
+export * as generateSignedUrl from './generate-signed-url/index.js'
 export * as getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'

package/node/cloud-storage/operations/index.d.ts

@@ -1,11 +1,11 @@
 export * as copyDir from './copy-dir/index.js'
-export * as copyFile from './copy-file/index.js'
 export * as downloadFile from './download-file/index.js'
+export * as copyFile from './copy-file/index.js'
 export * as existsFile from './exists-file/index.js'
 export * as listDir from './list-dir/index.js'
 export * as moveDir from './move-dir/index.js'
-export * as moveFile from './move-file/index.js'
 export * as removeDir from './remove-dir/index.js'
+export * as moveFile from './move-file/index.js'
 export * as removeFile from './remove-file/index.js'
 export * as statFile from './stat-file/index.js'
 export * as uploadFile from './upload-file/index.js'

package/node/cloud-storage/operations/index.js

@@ -1,11 +1,11 @@
 export * as copyDir from './copy-dir/index.js'
-export * as copyFile from './copy-file/index.js'
 export * as downloadFile from './download-file/index.js'
+export * as copyFile from './copy-file/index.js'
 export * as existsFile from './exists-file/index.js'
 export * as listDir from './list-dir/index.js'
 export * as moveDir from './move-dir/index.js'
-export * as moveFile from './move-file/index.js'
 export * as removeDir from './remove-dir/index.js'
+export * as moveFile from './move-file/index.js'
 export * as removeFile from './remove-file/index.js'
 export * as statFile from './stat-file/index.js'
 export * as uploadFile from './upload-file/index.js'

package/node/files/index.d.ts

@@ -1,4 +1,4 @@
 export * as getSize from './get-size/index.js'
 export * as isInDirectory from './is-in-directory/index.js'
-export * as subpaths from './subpaths/index.js'
 export * as readWrite from './read-write/index.js'
+export * as subpaths from './subpaths/index.js'

package/node/files/index.js

@@ -1,4 +1,4 @@
 export * as getSize from './get-size/index.js'
 export * as isInDirectory from './is-in-directory/index.js'
-export * as subpaths from './subpaths/index.js'
 export * as readWrite from './read-write/index.js'
+export * as subpaths from './subpaths/index.js'

package/node/images/transform/operations/index.d.ts

@@ -1,12 +1,12 @@
 export * as blur from './blur/index.js'
-export * as brighten from './brighten/index.js'
 export * as extend from './extend/index.js'
+export * as brighten from './brighten/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
 export * as flip from './flip/index.js'
 export * as flop from './flop/index.js'
-export * as hue from './hue/index.js'
 export * as level from './level/index.js'
+export * as hue from './hue/index.js'
 export * as lighten from './lighten/index.js'
 export * as normalize from './normalize/index.js'
 export * as overlay from './overlay/index.js'