@design-edito/tools 0.5.37 → 0.5.39

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 };
 }
 /**

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

@@ -3,10 +3,9 @@
  *
  * - `once` — runs on the first crossing only. The credit is per (verb, trigger) pair
  *   and lives for the mount.
- * - `force` — runs even after the reader has taken over the verb's domain. It
- *   overrides the **surrender**, never a suspension: a gate speaks of consent not yet
- *   given, a surrender of an intention already expressed, and an article able to force
- *   its way past a disclaimer would empty it of its purpose.
+ * - `force` — runs even after the reader has taken over the verb's domain. It is the
+ *   one way out of a surrender, and the only one: nothing else holds an instruction
+ *   back.
  *
  * **They are a set, not a sequence.** `'play:once:force'` and `'play:force:once'` are
  * the same instruction, which is what spares the contract an ordering rule.
@@ -38,10 +37,6 @@ export type ParsedInstruction = {
 /**
  * What a component says about one of its verbs.
  *
- * @property kind - Whether the verb starts something or stops it. A suspension — a
- * lm-link gate, typically — holds back `'start'` and lets `'stop'` through, since a
- * verb that quietens a component can never work against a reader who hasn't consented
- * yet.
  * @property domain - Which of the component's controls this verb competes with.
  * `play` and `pause` share `'playback'`, `loud` and `mute` share `'sound'` — so pausing
  * by hand doesn't stop the sound from being cut on the way out. One flag for all of
@@ -49,7 +44,6 @@ export type ParsedInstruction = {
  * @property run - Does the thing. Receives the verb's argument, when it takes one.
  */
 export type ActionSpec<D extends string = string> = {
-    kind: 'start' | 'stop';
     domain: D;
     run: (arg?: string) => void;
 };

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

@@ -3,10 +3,9 @@
  *
  * - `once` — runs on the first crossing only. The credit is per (verb, trigger) pair
  *   and lives for the mount.
- * - `force` — runs even after the reader has taken over the verb's domain. It
- *   overrides the **surrender**, never a suspension: a gate speaks of consent not yet
- *   given, a surrender of an intention already expressed, and an article able to force
- *   its way past a disclaimer would empty it of its purpose.
+ * - `force` — runs even after the reader has taken over the verb's domain. It is the
+ *   one way out of a surrender, and the only one: nothing else holds an instruction
+ *   back.
  *
  * **They are a set, not a sequence.** `'play:once:force'` and `'play:force:once'` are
  * the same instruction, which is what spares the contract an ordering rule.

package/node/ftps/directory/index.d.ts

@@ -1,4 +1,4 @@
-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'
+export * as copyDir from './copy-dir/index.js'

package/node/ftps/directory/index.js

@@ -1,4 +1,4 @@
-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'
+export * as copyDir from './copy-dir/index.js'

package/node/images/index.d.ts

@@ -1,5 +1,5 @@
 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 metadata from './metadata/index.js'
 export * as utils from './utils/index.js'

package/node/images/index.js

@@ -1,5 +1,5 @@
 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 metadata from './metadata/index.js'
 export * as utils from './utils/index.js'

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

@@ -1,15 +1,15 @@
 export * as blur from './blur/index.js'
 export * as brighten from './brighten/index.js'
-export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
+export * as extend from './extend/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 lighten from './lighten/index.js'
 export * as normalize from './normalize/index.js'
-export * as overlay from './overlay/index.js'
-export * as resize from './resize/index.js'
 export * as rotate from './rotate/index.js'
+export * as resize from './resize/index.js'
 export * as saturate from './saturate/index.js'
+export * as overlay from './overlay/index.js'

package/node/images/transform/operations/index.js

@@ -1,15 +1,15 @@
 export * as blur from './blur/index.js'
 export * as brighten from './brighten/index.js'
-export * as extend from './extend/index.js'
 export * as extract from './extract/index.js'
 export * as flatten from './flatten/index.js'
+export * as extend from './extend/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 lighten from './lighten/index.js'
 export * as normalize from './normalize/index.js'
-export * as overlay from './overlay/index.js'
-export * as resize from './resize/index.js'
 export * as rotate from './rotate/index.js'
+export * as resize from './resize/index.js'
 export * as saturate from './saturate/index.js'
+export * as overlay from './overlay/index.js'

package/node/index.d.ts

@@ -1,11 +1,11 @@
 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 googleCloud from './@google-cloud/index.js'
-export * as express from './@express/index.js'
 export * as cloudStorage from './cloud-storage/index.js'
 export * as encryption from './encryption/index.js'
 export * as files from './files/index.js'
 export * as ftps from './ftps/index.js'
-export * as images from './images/index.js'
 export * as process from './process/index.js'
+export * as images from './images/index.js'
 export * as sftp from './sftp/index.js'

package/node/index.js

@@ -1,11 +1,11 @@
 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 googleCloud from './@google-cloud/index.js'
-export * as express from './@express/index.js'
 export * as cloudStorage from './cloud-storage/index.js'
 export * as encryption from './encryption/index.js'
 export * as files from './files/index.js'
 export * as ftps from './ftps/index.js'
-export * as images from './images/index.js'
 export * as process from './process/index.js'
+export * as images from './images/index.js'
 export * as sftp from './sftp/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design-edito/tools",
-  "version": "0.5.37",
+  "version": "0.5.39",
   "description": "",
   "author": "Maxime Fabas",
   "license": "ISC",
@@ -20,6 +20,27 @@
       "import": "./agnostic/index.js",
       "types": "./agnostic/index.d.ts"
     },
+    "./agnostic/@react": {
+      "import": "./agnostic/@react/index.js",
+      "types": "./agnostic/@react/index.d.ts"
+    },
+    "./agnostic/@react/effects": {
+      "import": "./agnostic/@react/effects/index.js",
+      "types": "./agnostic/@react/effects/index.d.ts"
+    },
+    "./agnostic/@react/effects/index.js": {
+      "import": "./agnostic/@react/effects/index.js"
+    },
+    "./agnostic/@react/effects/use-state-change-dispatch": {
+      "import": "./agnostic/@react/effects/use-state-change-dispatch/index.js",
+      "types": "./agnostic/@react/effects/use-state-change-dispatch/index.d.ts"
+    },
+    "./agnostic/@react/effects/use-state-change-dispatch/index.js": {
+      "import": "./agnostic/@react/effects/use-state-change-dispatch/index.js"
+    },
+    "./agnostic/@react/index.js": {
+      "import": "./agnostic/@react/index.js"
+    },
     "./agnostic/arrays": {
       "import": "./agnostic/arrays/index.js",
       "types": "./agnostic/arrays/index.d.ts"
@@ -41,6 +62,13 @@
     "./agnostic/arrays/index.js": {
       "import": "./agnostic/arrays/index.js"
     },
+    "./agnostic/arrays/integers-between": {
+      "import": "./agnostic/arrays/integers-between/index.js",
+      "types": "./agnostic/arrays/integers-between/index.d.ts"
+    },
+    "./agnostic/arrays/integers-between/index.js": {
+      "import": "./agnostic/arrays/integers-between/index.js"
+    },
     "./agnostic/arrays/is-array-of": {
       "import": "./agnostic/arrays/is-array-of/index.js",
       "types": "./agnostic/arrays/is-array-of/index.d.ts"
@@ -213,6 +241,13 @@
     "./agnostic/css/is-valid-css-class-name/index.js": {
       "import": "./agnostic/css/is-valid-css-class-name/index.js"
     },
+    "./agnostic/css/merge-class-names": {
+      "import": "./agnostic/css/merge-class-names/index.js",
+      "types": "./agnostic/css/merge-class-names/index.d.ts"
+    },
+    "./agnostic/css/merge-class-names/index.js": {
+      "import": "./agnostic/css/merge-class-names/index.js"
+    },
     "./agnostic/css/scale": {
       "import": "./agnostic/css/scale/index.js",
       "types": "./agnostic/css/scale/index.d.ts"
@@ -1502,6 +1537,10 @@
     "./components/Lightbox/index.js": {
       "import": "./components/Lightbox/index.js"
     },
+    "./components/Lightbox/types.js": {
+      "import": "./components/Lightbox/types.js",
+      "types": "./components/Lightbox/types.d.ts"
+    },
     "./components/ListLoader": {
       "import": "./components/ListLoader/index.js",
       "types": "./components/ListLoader/index.d.ts"
@@ -1537,6 +1576,10 @@
     "./components/Scrllgngn/index.js": {
       "import": "./components/Scrllgngn/index.js"
     },
+    "./components/Scrllgngn/types.js": {
+      "import": "./components/Scrllgngn/types.js",
+      "types": "./components/Scrllgngn/types.d.ts"
+    },
     "./components/ScrollListener": {
       "import": "./components/ScrollListener/index.js",
       "types": "./components/ScrollListener/index.d.ts"

package/components/ListLoader/utils.d.ts

@@ -1,8 +0,0 @@
-/**
- * Lists every integer from `from` to `to`, both included.
- *
- * @param from - Lower bound.
- * @param to - Upper bound. When lower than `from`, the range is empty.
- * @returns The integers in ascending order.
- */
-export declare function rangeBetween(from: number, to: number): number[];

package/components/ListLoader/utils.js

@@ -1,10 +0,0 @@
-/**
- * Lists every integer from `from` to `to`, both included.
- *
- * @param from - Lower bound.
- * @param to - Upper bound. When lower than `from`, the range is empty.
- * @returns The integers in ascending order.
- */
-export function rangeBetween(from, to) {
-    return Array.from({ length: Math.max(0, to - from + 1) }, (_, pos) => from + pos);
-}