@design-edito/tools 0.5.6 → 0.5.7

package/components/Video/index.js

@@ -4,7 +4,7 @@ import { clss } from '../../agnostic/css/clss/index.js';
 import { IntersectionObserverComponent } from '../IntersectionObserver/index.js';
 import { mergeClassNames } from '../utils/index.js';
 import { videoWrapper as publicClassName } from '../public-classnames.js';
-import { muteAttributeWorkaround } from './utils.js';
+import { muteAttributeWorkaround, shouldRunAutoBehaviour } from './utils.js';
 import cssModule from './styles.module.css';
 import { ControlledVideo } from './index.controlled.js';
 /**
@@ -16,34 +16,72 @@ import { ControlledVideo } from './index.controlled.js';
  * @see {@link Props}
  * @returns A `<figure>` element containing the video, its controls and optional
  * subtitles.
+ *
+ * @remarks
+ * **Audio-only media belongs here too**, carried by the same `<video>` element.
+ * Everything this component drives — play, mute, volume, rate, time, `ended` — is
+ * `HTMLMediaElement`, shared with `<audio>`; only fullscreen is video's own. And an
+ * `<audio>` tag can't be autoplayed: the muted-autoplay exemption browsers grant is
+ * for video, so an `<audio>` waits for a user gesture whatever its muted state.
+ * `autoPlayWhenVisible` on an audio file therefore needs `muted` and `playsInline`
+ * on a `<video>`, which is what this is. The one thing lost is the assistive-tech
+ * label: a screen reader announces a video player. Worth a `tag` prop the day that
+ * matters more than autoplay — not before.
+ *
+ * Each viewport-driven behaviour comes in two flavours: `…When…` fires on every
+ * crossing, `…Once…` only on the first one. A `…Once…` flag is armed by its own
+ * automatic trigger and by nothing else — pressing play does not spend the one
+ * automatic play the component still owed. Setting both flavours of the same
+ * 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.
  */
-export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMuteWhenHidden, autoLoudWhenVisible, wrapperClassName, onPlayButtonClicked, onPauseButtonClicked, onLoudButtonClicked, onMuteButtonClicked, onVolumeRangeChanged, onRateRangeChanged, onFullscreenButtonClicked, ...controlledProps }) => {
+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
     const [play, setPlay] = useState(false);
     const [volume, setVolume] = useState(1);
     const [mute, setMute] = useState(false);
     const [playbackRate, setPlaybackRate] = useState(1);
     const [fullscreen, setFullscreen] = useState(false);
-    const hasBeenAutoPlayed = useRef(false);
+    // One flag per `…Once…` behaviour, and each is armed by that behaviour's own
+    // automatic trigger. A single shared flag conflated four questions, and being set
+    // on any `play` event — a user click included — meant the first press cancelled
+    // behaviours that had nothing to do with playback.
+    const hasAutoPlayedOnce = useRef(false);
+    const hasAutoPausedOnce = useRef(false);
+    const hasAutoLoudedOnce = useRef(false);
+    const hasAutoMutedOnce = useRef(false);
     // Several paths below ask for playback — the play button, autoPlayWhenVisible,
     // autoPlay itself. None of them may win over a parent-owned time, so the
     // invariant is applied where the state is forwarded rather than guarded at each
     // of those call sites.
     const isTimeControlled = controlledProps.currentTimeMs !== undefined;
-    const needsObserve = useMemo(() => autoLoudWhenVisible === true
+    const needsObserve = useMemo(() => onVisibilityChanged !== undefined
+        || autoLoudWhenVisible === true
+        || autoLoudOnceVisible === true
         || autoMuteWhenHidden === true
+        || autoMuteOnceHidden === true
         || autoPlayWhenVisible === true
-        || autoPauseWhenHidden === true, [
+        || autoPlayOnceVisible === true
+        || autoPauseWhenHidden === true
+        || autoPauseOnceHidden === true, [
         autoLoudWhenVisible,
+        autoLoudOnceVisible,
         autoMuteWhenHidden,
+        autoMuteOnceHidden,
         autoPlayWhenVisible,
-        autoPauseWhenHidden
+        autoPlayOnceVisible,
+        autoPauseWhenHidden,
+        autoPauseOnceHidden,
+        onVisibilityChanged
     ]);
     // Intrisic event handlers
     const handleOnPlayEvent = useCallback((e) => {
         controlledProps.onPlay?.(e);
         setPlay(true);
-        hasBeenAutoPlayed.current = true;
     }, [controlledProps.onPlay]);
     const handleOnPauseEvent = useCallback((e) => {
         setPlay(false);
@@ -100,28 +138,41 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMute
         if (ioEntry === undefined)
             return;
         const { isIntersecting } = ioEntry;
-        if (autoPauseWhenHidden === true && !isIntersecting)
+        onVisibilityChanged?.(isIntersecting);
+        if (isIntersecting) {
+            if (shouldRunAutoBehaviour(autoPlayWhenVisible, autoPlayOnceVisible, hasAutoPlayedOnce.current)) {
+                hasAutoPlayedOnce.current = true;
+                setPlay(true);
+            }
+            if (shouldRunAutoBehaviour(autoLoudWhenVisible, autoLoudOnceVisible, hasAutoLoudedOnce.current)) {
+                hasAutoLoudedOnce.current = true;
+                setMute(false);
+            }
+            return;
+        }
+        if (shouldRunAutoBehaviour(autoPauseWhenHidden, autoPauseOnceHidden, hasAutoPausedOnce.current)) {
+            hasAutoPausedOnce.current = true;
             setPlay(false);
-        if (autoLoudWhenVisible === true && isIntersecting)
-            setMute(false);
-        if (autoPlayWhenVisible === true
-            && !hasBeenAutoPlayed.current
-            && isIntersecting)
-            setPlay(true);
-        if (autoMuteWhenHidden === true
-            && !hasBeenAutoPlayed.current
-            && !isIntersecting)
+        }
+        if (shouldRunAutoBehaviour(autoMuteWhenHidden, autoMuteOnceHidden, hasAutoMutedOnce.current)) {
+            hasAutoMutedOnce.current = true;
             setMute(true);
+        }
     }, [
         autoPlayWhenVisible,
+        autoPlayOnceVisible,
         autoPauseWhenHidden,
+        autoPauseOnceHidden,
         autoMuteWhenHidden,
-        autoLoudWhenVisible
+        autoMuteOnceHidden,
+        autoLoudWhenVisible,
+        autoLoudOnceVisible,
+        onVisibilityChanged
     ]);
     // `autoPlay` is forwarded to the element, but the play state is owned here, so
     // it has to be seeded once on mount for the controls to agree with the element.
     useEffect(() => {
-        if (controlledProps.autoPlay === true && !hasBeenAutoPlayed.current)
+        if (controlledProps.autoPlay === true)
             setPlay(true);
     }, []);
     // Render
@@ -129,6 +180,6 @@ export const Video = ({ loop, autoPlayWhenVisible, autoPauseWhenHidden, autoMute
     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 });
     return _jsx("div", { className: rootClss, children: needsObserve
-            ? _jsx(IntersectionObserverComponent, { onIntersected: onIntersected, children: videoContent })
+            ? _jsx(IntersectionObserverComponent, { threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: onIntersected, children: videoContent })
             : videoContent });
 };

package/components/Video/utils.d.ts

@@ -45,3 +45,17 @@ export declare function formatTime(ms: number, format: string, fps?: number): st
  * @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.
+ */
+export declare const shouldRunAutoBehaviour: (whenCrossed: boolean | undefined, onceOnly: boolean | undefined, hasFired: boolean) => boolean;

package/components/Video/utils.js

@@ -160,3 +160,21 @@ export const getTimelineClickProgress = (event) => {
     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.
+ */
+export const shouldRunAutoBehaviour = (whenCrossed, onceOnly, hasFired) => {
+    if (whenCrossed === true)
+        return true;
+    return onceOnly === true && !hasFired;
+};

package/components/utils/types.d.ts

@@ -6,3 +6,35 @@
 export type WithClassName<T extends Record<string, unknown>> = T & {
     className?: string | Array<string | null | undefined>;
 };
+/**
+ * The settings of an {@link IntersectionObserver} a component mounts internally.
+ *
+ * A component that offers viewport-driven behaviour has to offer its dial too:
+ * `autoPlayWhenVisible` means little if "visible" can't be told to mean *thirty
+ * percent* visible, and an infinite list wants to start loading before its sentinel
+ * shows, which is `rootMargin`'s job.
+ *
+ * They mirror `ObserverOptions` of the `IntersectionObserver` component, where they
+ * end up. Restated here rather than imported from it: that component reads
+ * {@link WithClassName} from this very file, and the two shouldn't import each other.
+ */
+export type ViewportObserverOptions = {
+    threshold?: number | number[];
+    root?: HTMLElement;
+    rootMargin?: string;
+};
+/**
+ * Extends a type with an internal observer's settings and with what it sees.
+ *
+ * For a component observing **one** element — itself, usually. A component with
+ * several observers takes {@link ViewportObserverOptions} alone, since a single
+ * visibility handler couldn't say which of them crossed.
+ *
+ * `Scrllgngn` deliberately stays out of both: its observers take a `rootMargin`
+ * derived from its `viewportOffset*` props, which are its own version of the dial.
+ *
+ * @template T - The base type to extend.
+ */
+export type WithViewportObservation<T extends Record<string, unknown>> = T & ViewportObserverOptions & {
+    onVisibilityChanged?: (isVisible: boolean) => void;
+};

package/index.d.ts

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

package/index.js

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

package/node/@aws-s3/storage/directory/index.d.ts

@@ -1,4 +1,4 @@
-export * as list from './list/index.js'
 export * as copyDir from './copy-dir/index.js'
+export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
 export * as removeDir from './remove-dir/index.js'

package/node/@aws-s3/storage/directory/index.js

@@ -1,4 +1,4 @@
-export * as list from './list/index.js'
 export * as copyDir from './copy-dir/index.js'
+export * as list from './list/index.js'
 export * as moveDir from './move-dir/index.js'
 export * as removeDir from './remove-dir/index.js'

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

@@ -1,11 +1,11 @@
 export * as copy from './copy/index.js'
-export * as exists from './exists/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 getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
-export * as remove from './remove/index.js'
 export * as move from './move/index.js'
+export * as remove from './remove/index.js'
 export * as revokeSignedUrls from './revoke-signed-urls/index.js'
 export * as stat from './stat/index.js'
 export * as updateMetadata from './update-metadata/index.js'

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

@@ -1,11 +1,11 @@
 export * as copy from './copy/index.js'
-export * as exists from './exists/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 getMetadata from './get-metadata/index.js'
 export * as getPermissions from './get-permissions/index.js'
-export * as remove from './remove/index.js'
 export * as move from './move/index.js'
+export * as remove from './remove/index.js'
 export * as revokeSignedUrls from './revoke-signed-urls/index.js'
 export * as stat from './stat/index.js'
 export * as updateMetadata from './update-metadata/index.js'

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

@@ -1,7 +1,7 @@
 export * as copyDir from './copy-dir/index.js'
 export * as copyFile from './copy-file/index.js'
-export * as existsFile from './exists-file/index.js'
 export * as downloadFile from './download-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'

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

@@ -1,7 +1,7 @@
 export * as copyDir from './copy-dir/index.js'
 export * as copyFile from './copy-file/index.js'
-export * as existsFile from './exists-file/index.js'
 export * as downloadFile from './download-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'

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 readWrite from './read-write/index.js'
 export * as subpaths from './subpaths/index.js'
+export * as readWrite from './read-write/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 readWrite from './read-write/index.js'
 export * as subpaths from './subpaths/index.js'
+export * as readWrite from './read-write/index.js'

package/node/images/index.d.ts

@@ -1,5 +1,5 @@
-export * as format from './format/index.js'
 export * as create from './create/index.js'
+export * as format from './format/index.js'
 export * as metadata from './metadata/index.js'
 export * as transform from './transform/index.js'
 export * as utils from './utils/index.js'

package/node/images/index.js

@@ -1,5 +1,5 @@
-export * as format from './format/index.js'
 export * as create from './create/index.js'
+export * as format from './format/index.js'
 export * as metadata from './metadata/index.js'
 export * as transform from './transform/index.js'
 export * as utils from './utils/index.js'

package/node/index.d.ts

@@ -1,6 +1,6 @@
 export * as awsS3 from './@aws-s3/index.js'
-export * as express from './@express/index.js'
 export * as designEdito from './@design-edito/index.js'
+export * as express from './@express/index.js'
 export * as googleCloud from './@google-cloud/index.js'
 export * as cloudStorage from './cloud-storage/index.js'
 export * as encryption from './encryption/index.js'

package/node/index.js

@@ -1,6 +1,6 @@
 export * as awsS3 from './@aws-s3/index.js'
-export * as express from './@express/index.js'
 export * as designEdito from './@design-edito/index.js'
+export * as express from './@express/index.js'
 export * as googleCloud from './@google-cloud/index.js'
 export * as cloudStorage from './cloud-storage/index.js'
 export * as encryption from './encryption/index.js'

package/node/sftp/file/index.d.ts

@@ -1,5 +1,5 @@
-export * as download from './download/index.js'
 export * as copy from './copy/index.js'
+export * as download from './download/index.js'
 export * as exists from './exists/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'

package/node/sftp/file/index.js

@@ -1,5 +1,5 @@
-export * as download from './download/index.js'
 export * as copy from './copy/index.js'
+export * as download from './download/index.js'
 export * as exists from './exists/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-edito/tools",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "",
   "author": "Maxime Fabas",
   "license": "ISC",
@@ -1275,6 +1275,31 @@
     "./agnostic/strings/trim/index.js": {
       "import": "./agnostic/strings/trim/index.js"
     },
+    "./agnostic/subtitles": {
+      "import": "./agnostic/subtitles/index.js",
+      "types": "./agnostic/subtitles/index.d.ts"
+    },
+    "./agnostic/subtitles/index.js": {
+      "import": "./agnostic/subtitles/index.js"
+    },
+    "./agnostic/subtitles/parse-srt": {
+      "import": "./agnostic/subtitles/parse-srt/index.js",
+      "types": "./agnostic/subtitles/parse-srt/index.d.ts"
+    },
+    "./agnostic/subtitles/parse-srt/index.js": {
+      "import": "./agnostic/subtitles/parse-srt/index.js"
+    },
+    "./agnostic/subtitles/parse-srt/types.js": {
+      "import": "./agnostic/subtitles/parse-srt/types.js",
+      "types": "./agnostic/subtitles/parse-srt/types.d.ts"
+    },
+    "./agnostic/subtitles/srt-timecode-to-ms": {
+      "import": "./agnostic/subtitles/srt-timecode-to-ms/index.js",
+      "types": "./agnostic/subtitles/srt-timecode-to-ms/index.d.ts"
+    },
+    "./agnostic/subtitles/srt-timecode-to-ms/index.js": {
+      "import": "./agnostic/subtitles/srt-timecode-to-ms/index.js"
+    },
     "./agnostic/time": {
       "import": "./agnostic/time/index.js",
       "types": "./agnostic/time/index.d.ts"