@design-edito/tools 0.5.17 → 0.5.18

package/components/index.js

@@ -1,11 +1,11 @@
 export * as beforeAfter from './BeforeAfter/index.js'
 export * as button from './Button/index.js'
-export * as clippable from './Clippable/index.js'
 export * as disclaimer from './Disclaimer/index.js'
-export * as drawer from './Drawer/index.js'
-export * as gallery from './Gallery/index.js'
+export * as clippable from './Clippable/index.js'
 export * as eventListener from './EventListener/index.js'
+export * as drawer from './Drawer/index.js'
 export * as iframe from './Iframe/index.js'
+export * as gallery from './Gallery/index.js'
 export * as image from './Image/index.js'
 export * as input from './Input/index.js'
 export * as intersectionObserver from './IntersectionObserver/index.js'
@@ -13,15 +13,15 @@ export * as jsonEditor from './JsonEditor/index.js'
 export * as lightbox from './Lightbox/index.js'
 export * as listLoader from './ListLoader/index.js'
 export * as overlayer from './Overlayer/index.js'
-export * as paginator from './Paginator/index.js'
 export * as resizeObserver from './ResizeObserver/index.js'
+export * as paginator from './Paginator/index.js'
 export * as scrllgngn from './Scrllgngn/index.js'
 export * as scrollListener from './ScrollListener/index.js'
 export * as select from './Select/index.js'
 export * as sequencer from './Sequencer/index.js'
 export * as shadowRoot from './ShadowRoot/index.js'
-export * as subtitles from './Subtitles/index.js'
 export * as textarea from './Textarea/index.js'
+export * as subtitles from './Subtitles/index.js'
 export * as uiModule from './UIModule/index.js'
 export * as video from './Video/index.js'
 export * as wipAudioQuote from './_WIP_AudioQuote/index.js'

package/components/utils/index.d.ts

@@ -21,3 +21,24 @@ export declare function mergeClassNames(...names: Array<string | null | undefine
  * effect fires, so it is never a stale one.
  */
 export declare function useChangeDispatch<T>(value: T, onChange?: (value: T) => void, isEqual?: (a: T, b: T) => boolean): void;
+/**
+ * The three forms a `<source>` list is written in, reduced to the one a render uses.
+ *
+ * A bare string is a single source, an array of strings is several, an array of records
+ * is taken as given. **The array is read as homogeneous** — the first element decides for
+ * all of them —, which is what someone writing one by hand means anyway, and the only
+ * reading a static hyper-json array could support.
+ *
+ * `stringKey` is the whole reason this is shared rather than written twice. The parsing
+ * is identical for `Video` and `Image`, but **the shorthand does not name the same
+ * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
+ * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
+ * source also takes `media` and `sizes`, which a video source has no use for, and neither
+ * element accepts the other's key. One element, one shape; only the reading is common.
+ *
+ * @template T - The record shape the caller's element accepts.
+ * @param given - What the consumer wrote.
+ * @param stringKey - Where a bare string goes.
+ * @returns The list as records, empty when there is nothing to render.
+ */
+export declare function parseSourceList<T extends Record<string, unknown>>(given: string | string[] | T[] | undefined, stringKey: keyof T & string): T[];

package/components/utils/index.js

@@ -41,3 +41,43 @@ export function useChangeDispatch(value, onChange, isEqual = Object.is) {
         onChange?.(value);
     }, [value]);
 }
+/**
+ * The three forms a `<source>` list is written in, reduced to the one a render uses.
+ *
+ * A bare string is a single source, an array of strings is several, an array of records
+ * is taken as given. **The array is read as homogeneous** — the first element decides for
+ * all of them —, which is what someone writing one by hand means anyway, and the only
+ * reading a static hyper-json array could support.
+ *
+ * `stringKey` is the whole reason this is shared rather than written twice. The parsing
+ * is identical for `Video` and `Image`, but **the shorthand does not name the same
+ * attribute**: a `<source>` inside a `<video>` carries `src`, one inside a `<picture>`
+ * carries `srcSet`. The two record shapes stay apart for the same reason — the picture
+ * source also takes `media` and `sizes`, which a video source has no use for, and neither
+ * element accepts the other's key. One element, one shape; only the reading is common.
+ *
+ * @template T - The record shape the caller's element accepts.
+ * @param given - What the consumer wrote.
+ * @param stringKey - Where a bare string goes.
+ * @returns The list as records, empty when there is nothing to render.
+ */
+export function parseSourceList(given, stringKey) {
+    const fromString = (value) => {
+        const single = { [stringKey]: value };
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- a one-key record is the narrowest `T` a bare string can describe; every other field is optional by contract
+        return single;
+    };
+    if (given === undefined)
+        return [];
+    if (typeof given === 'string')
+        return [fromString(given)];
+    if (!Array.isArray(given))
+        return [];
+    if (given.length === 0)
+        return [];
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element sampled just above; array is read as homogeneous
+    if (typeof given[0] === 'string')
+        return given.map(fromString);
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- first element was checked not to be a string just above; array is read as homogeneous
+    return given;
+}

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

@@ -0,0 +1,54 @@
+import { type RefObject } from 'react';
+import type { ActionTable, ViewportBehaviours, VisibilityOptions } from './types.js';
+/**
+ * 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.
+ *
+ * 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
+ * therefore never counts as seen at all, rather than counting and being undone.
+ *
+ * @param targetRef - The element to watch.
+ * @param options - The observer's settings, plus the two delays.
+ * @param enabled - `false` mounts no observer. A hook can't be skipped; this is how
+ * a caller with nothing to watch for says so.
+ * @returns `true` or `false` once the first observation has settled, `undefined` before.
+ */
+export declare function useVisibilityState(targetRef: RefObject<Element | null>, options?: VisibilityOptions, enabled?: boolean): boolean | undefined;
+/** The shape `useViewportBehaviours` hands back. */
+export type ViewportBehavioursResult = {
+    isVisible: boolean | undefined;
+    /**
+     * Tells the layer that the reader has taken over a domain, and that its instructions
+     * are to stop firing. Call it from the handlers that count as taking over — and only
+     * those: seeking on a timeline or going fullscreen is not deciding about playback.
+     */
+    surrender: (domain: string) => void;
+};
+/**
+ * Runs a component's visibility instructions, and holds everything that decides whether
+ * they may run at all.
+ *
+ * @template A - The component's vocabulary.
+ * @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
+ * symmetrical: not restarting on its own is a disappointment, restarting against a
+ * reader who has just pressed pause is an hostility they will meet again at every pass.
+ * `':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 type { ActionSpec, ActionTable, Instruction, Modifier, ParsedInstruction, ViewportBehaviours, VisibilityOptions } from './types.js';

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

@@ -0,0 +1,163 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useIntersectionObserver } from '../../IntersectionObserver/index.js';
+import { useChangeDispatch } from '../index.js';
+import { parseInstruction, toInstructionList } from './utils.js';
+/**
+ * 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.
+ *
+ * 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
+ * therefore never counts as seen at all, rather than counting and being undone.
+ *
+ * @param targetRef - The element to watch.
+ * @param options - The observer's settings, plus the two delays.
+ * @param enabled - `false` mounts no observer. A hook can't be skipped; this is how
+ * a caller with nothing to watch for says so.
+ * @returns `true` or `false` once the first observation has settled, `undefined` before.
+ */
+export function useVisibilityState(targetRef, options = {}, enabled = true) {
+    const { visibilityThreshold: threshold, visibilityRoot: root, visibilityRootMargin: rootMargin, visibilityOnAfterMs, visibilityOffAfterMs } = options;
+    const ioEntry = useIntersectionObserver(targetRef, { threshold, root, rootMargin }, undefined, enabled);
+    const reported = ioEntry?.isIntersecting;
+    const [settled, setSettled] = useState(undefined);
+    useEffect(() => {
+        if (reported === undefined)
+            return;
+        const delay = reported ? visibilityOnAfterMs : visibilityOffAfterMs;
+        if (delay === undefined || delay <= 0) {
+            setSettled(reported);
+            return;
+        }
+        const timeout = window.setTimeout(() => setSettled(reported), delay);
+        // The cancellation *is* the debounce: a value that flips back before its timer
+        // fires is never committed, so the short crossing leaves no trace.
+        return () => window.clearTimeout(timeout);
+    }, [reported, visibilityOnAfterMs, visibilityOffAfterMs]);
+    return settled;
+}
+/**
+ * Runs a component's visibility instructions, and holds everything that decides whether
+ * they may run at all.
+ *
+ * @template A - The component's vocabulary.
+ * @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
+ * symmetrical: not restarting on its own is a disappointment, restarting against a
+ * reader who has just pressed pause is an hostility they will meet again at every pass.
+ * `':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) {
+    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.
+    //
+    // Held as a `Map` and not as the record itself: a verb parsed out of a string is a
+    // plain `string`, and looking one up in a `Record<A, …>` would mean asserting it into
+    // the vocabulary before knowing whether it belongs to it. A map answers `undefined`,
+    // which is the honest answer for an instruction nobody recognises.
+    const tableRef = useRef(new Map());
+    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 surrender = useCallback((domain) => {
+        surrenderedRef.current.add(domain);
+    }, []);
+    const needsObserve = whenVisible !== undefined
+        || whenHidden !== undefined
+        || onVisibilityChanged !== undefined;
+    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 => {
+        if (next === undefined)
+            return;
+        onVisibilityChanged?.(next);
+    });
+    useEffect(() => {
+        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)
+            return;
+        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]);
+    return { isVisible, surrender };
+}
+/**
+ * One entry per verb, keeping the **widest** reading when the same verb is written more
+ * than once in a list.
+ *
+ * `['play', 'play:once']` runs on every crossing — the bare form wins, which is the
+ * long-standing rule that declaring both frequencies is declaring the recurring one.
+ * `['play', 'play:force']` is forced, by the same logic read the other way: a consumer
+ * who wrote `force` somewhere asked for it.
+ */
+function dedupe(list) {
+    const byVerb = new Map();
+    for (const instruction of list) {
+        const parsed = parseInstruction(instruction);
+        if (parsed.verb === '')
+            continue;
+        const key = `${parsed.verb}|${parsed.arg ?? ''}`;
+        const seen = byVerb.get(key);
+        if (seen === undefined) {
+            byVerb.set(key, parsed);
+            continue;
+        }
+        byVerb.set(key, {
+            ...parsed,
+            once: seen.once && parsed.once,
+            force: seen.force || parsed.force
+        });
+    }
+    return [...byVerb.values()];
+}

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

@@ -0,0 +1,109 @@
+/**
+ * The stop conditions an instruction can carry, written as suffixes.
+ *
+ * - `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.
+ *
+ * **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.
+ */
+export declare const MODIFIERS: readonly ["once", "force"];
+export type Modifier = typeof MODIFIERS[number];
+/**
+ * A verb, optionally suffixed by its stop conditions.
+ *
+ * A verb may carry its own argument — `'jump-to:500'` — in which case the argument is
+ * part of `A`, declared by the component that owns the vocabulary. The modifiers then
+ * suffix that whole form: `'jump-to:500:once'` needs nothing written here.
+ *
+ * **No verb may be named after a modifier.** The trailing segments are read as
+ * modifiers first, so a verb called `once` would parse as an instruction with no verb
+ * at all.
+ *
+ * @template A - The component's vocabulary.
+ */
+export type Instruction<A extends string> = A | `${A}:${Modifier}` | `${A}:${Modifier}:${Modifier}`;
+/** An instruction taken apart. @see {@link Instruction} */
+export type ParsedInstruction = {
+    verb: string;
+    /** What followed the verb, when the verb takes one. `'500'` in `'jump-to:500'`. */
+    arg?: string;
+    once: boolean;
+    force: boolean;
+};
+/**
+ * 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
+ * them would confound four questions, which is a mistake this library has made once.
+ * @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;
+};
+/**
+ * A component's whole vocabulary.
+ *
+ * @template A - Its verbs.
+ * @template D - Its domains, when it has a type for them. Naming them is what makes a
+ * typo in `domain` — or in the matching `surrender` call — a compile error rather than
+ * a behaviour that silently never fires.
+ *
+ * @see {@link ActionSpec}
+ */
+export type ActionTable<A extends string, D extends string = string> = Record<A, ActionSpec<D>>;
+/**
+ * Everything that decides **when** a component counts as visible.
+ *
+ * Flat and prefixed rather than grouped in a record: a record reads well in a type and
+ * badly at a call site, where it costs a pair of braces to set one value. The shared
+ * `visibility` prefix does the grouping that a record would have done, and it does it
+ * in the autocomplete list too.
+ *
+ * @property visibilityThreshold - How much of the element must be on screen. `0.3` asks
+ * for a third; omitted, a pixel is enough.
+ * @property visibilityRoot - The box visibility is measured against. Defaults to the
+ * viewport, which is the only one a static structure could name.
+ * @property visibilityRootMargin - Grows or shrinks that box before measuring, in
+ * `IntersectionObserver` syntax.
+ * @property visibilityOnAfterMs - How long it must stay visible to count as visible.
+ * This is a debounce on the state and not a delay on the action: a component crossed
+ * while scrolling fast never counts as seen, so nothing runs and no `once` credit is
+ * spent.
+ * @property visibilityOffAfterMs - The same, on the way out.
+ */
+export type VisibilityOptions = {
+    visibilityThreshold?: number | number[];
+    visibilityRoot?: HTMLElement;
+    visibilityRootMargin?: string;
+    visibilityOnAfterMs?: number;
+    visibilityOffAfterMs?: number;
+};
+/**
+ * The visibility surface of a component: when it counts as seen, and what that does.
+ *
+ * @property whenVisible - Instructions run each time it becomes visible.
+ * @property whenHidden - The same, on the way out.
+ * @property onVisibilityChanged - Fired on the **settled** state, delays included: a
+ * consumer watching visibility and a consumer running instructions are told the same
+ * story.
+ *
+ * @template Action - The component's vocabulary.
+ */
+export type ViewportBehaviours<Action extends string> = VisibilityOptions & {
+    whenVisible?: Instruction<Action> | Array<Instruction<Action>>;
+    whenHidden?: Instruction<Action> | Array<Instruction<Action>>;
+    onVisibilityChanged?: (isVisible: boolean) => void;
+};

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

@@ -0,0 +1,14 @@
+/**
+ * The stop conditions an instruction can carry, written as suffixes.
+ *
+ * - `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.
+ *
+ * **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.
+ */
+export const MODIFIERS = ['once', 'force'];

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

@@ -0,0 +1,26 @@
+import { type Instruction, type ParsedInstruction } from './types.js';
+/**
+ * Takes an instruction apart: its verb, its argument if it has one, its modifiers.
+ *
+ * **Trailing segments are read as modifiers until one isn't**, and everything left is
+ * the verb — whatever its own internal shape. That single rule is what lets a verb
+ * carry an argument without the grammar having two levels: `'jump-to:500:once'` gives
+ * back `jump-to`, `'500'` and `once`, and the parser never needs to know that `jump-to`
+ * is the kind of verb that takes a number.
+ *
+ * @param instruction - What the consumer wrote.
+ * @returns Its parts. `verb` is empty when the instruction was nothing but modifiers.
+ */
+export declare function parseInstruction(instruction: string): ParsedInstruction;
+/**
+ * The one-or-many shape of a list prop, reduced to the many.
+ *
+ * A single instruction is written bare — `whenVisible='play'` — because that is what an
+ * article writes nine times out of ten, and a one-item array in hyper-json is four
+ * lines to say one word.
+ *
+ * @template A - The component's vocabulary.
+ * @param given - What the consumer wrote.
+ * @returns The instructions in the order they were given, which is the order they run.
+ */
+export declare function toInstructionList<A extends string>(given: Instruction<A> | Array<Instruction<A>> | undefined): Array<Instruction<A>>;

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

@@ -0,0 +1,55 @@
+import { MODIFIERS } from './types.js';
+const isModifier = (segment) => MODIFIERS.includes(segment);
+/**
+ * Takes an instruction apart: its verb, its argument if it has one, its modifiers.
+ *
+ * **Trailing segments are read as modifiers until one isn't**, and everything left is
+ * the verb — whatever its own internal shape. That single rule is what lets a verb
+ * carry an argument without the grammar having two levels: `'jump-to:500:once'` gives
+ * back `jump-to`, `'500'` and `once`, and the parser never needs to know that `jump-to`
+ * is the kind of verb that takes a number.
+ *
+ * @param instruction - What the consumer wrote.
+ * @returns Its parts. `verb` is empty when the instruction was nothing but modifiers.
+ */
+export function parseInstruction(instruction) {
+    const segments = instruction.trim().split(':');
+    const modifiers = new Set();
+    // Walked from the end: the modifiers are a set, so their order carries nothing and
+    // only the boundary with the verb matters.
+    while (segments.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- length checked by the loop
+        const last = segments[segments.length - 1];
+        if (!isModifier(last))
+            break;
+        modifiers.add(last);
+        segments.pop();
+    }
+    const [verb, ...rest] = segments;
+    return {
+        verb: verb ?? '',
+        // Rejoined rather than taken as one segment: an argument holding a colon of its
+        // own stays whole, and nothing in the grammar has to forbid it.
+        ...(rest.length > 0 ? { arg: rest.join(':') } : {}),
+        once: modifiers.has('once'),
+        force: modifiers.has('force')
+    };
+}
+/**
+ * The one-or-many shape of a list prop, reduced to the many.
+ *
+ * A single instruction is written bare — `whenVisible='play'` — because that is what an
+ * article writes nine times out of ten, and a one-item array in hyper-json is four
+ * lines to say one word.
+ *
+ * @template A - The component's vocabulary.
+ * @param given - What the consumer wrote.
+ * @returns The instructions in the order they were given, which is the order they run.
+ */
+export function toInstructionList(given) {
+    if (given === undefined)
+        return [];
+    if (Array.isArray(given))
+        return given;
+    return [given];
+}

package/node/@aws-s3/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 exists from './exists/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'
 export * as stat from './stat/index.js'
 export * as upload from './upload/index.js'
+export * as download from './download/index.js'

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

@@ -1,7 +1,7 @@
 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'
 export * as stat from './stat/index.js'
 export * as upload from './upload/index.js'
+export * as download from './download/index.js'

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

@@ -1,8 +1,8 @@
 export * as copy from './copy/index.js'
 export * as download from './download/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 generateSignedUrl from './generate-signed-url/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/index.js'

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

@@ -1,8 +1,8 @@
 export * as copy from './copy/index.js'
 export * as download from './download/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 generateSignedUrl from './generate-signed-url/index.js'
 export * as getPermissions from './get-permissions/index.js'
 export * as move from './move/index.js'
 export * as remove from './remove/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 utils from './utils/index.js'
+export * as format from './format/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 utils from './utils/index.js'
+export * as format from './format/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 flip from './flip/index.js'
 export * as flop from './flop/index.js'
+export * as brighten from './brighten/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 lighten from './lighten/index.js'
 export * as resize from './resize/index.js'
 export * as rotate from './rotate/index.js'
 export * as saturate from './saturate/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 flip from './flip/index.js'
 export * as flop from './flop/index.js'
+export * as brighten from './brighten/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 lighten from './lighten/index.js'
 export * as resize from './resize/index.js'
 export * as rotate from './rotate/index.js'
 export * as saturate from './saturate/index.js'