@mxfb/tools 1.0.4 → 1.0.6

package/components/ListLoader/index.controlled.js

@@ -0,0 +1,108 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { integersBetween } from '@design-edito/tools/agnostic/arrays/integers-between/index.js';
+import { clss } from '@design-edito/tools/agnostic/css/clss/index.js';
+import { IntersectionObserverComponent } from '@design-edito/tools/components/IntersectionObserver/index.js';
+import { listLoader as publicClassName } from '../public-classnames.js';
+import { mergeClassNames } from '../utils/index.js';
+import cssModule from './styles.module.css';
+/**
+ * Presentational layer of the paginated list. Renders already-loaded pages as a
+ * single flat item list, and interleaves load buttons wherever a page is missing.
+ *
+ * This component holds no state and performs no fetching. Loaded pages are sorted
+ * by position and flattened, so items appear in page order then in item order,
+ * with no per-page wrapper element.
+ *
+ * ### Load buttons
+ * One button is rendered per missing page position:
+ * - before the first loaded page, unless it is already `firstPagePos`,
+ * - in place of each page missing between two loaded pages,
+ * - after the last loaded page, unless it is already `lastPagePos`.
+ *
+ * ### Root element modifiers
+ * - `--loading` — at least one page is being fetched.
+ *
+ * ### CSS elements
+ * - `item` — wraps each rendered item. Carries `data-page`.
+ * - `load` — a load button. Rendered empty, so its label belongs in CSS.
+ *   Carries `data-page` and a `prev`, `next` or `gap` modifier.
+ * - `load-observer` — the intersection observer wrapping an auto-loading button.
+ *   Present only when `autoLoadPrevWhenVisible` or `autoLoadNextWhenVisible` is on.
+ *   Carries a `prev` or `next` modifier.
+ *
+ * ### Data attributes on the root element
+ * - `data-loading-pages` — comma-separated ascending list of the pages being
+ *   fetched, e.g. `"1,3,6"`. Absent entirely when nothing is loading.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A flat list of items with load buttons in place of missing pages.
+ *
+ * @remarks
+ * Deduplication runs after `filter`, so an item hidden by `filter` never evicts
+ * an earlier duplicate.
+ */
+export const ControlledListLoader = ({ className, pages, firstPagePos, lastPagePos, itemsPages, filter, display, getIdentifier, loadingPages, onLoadPageClicked, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin }) => {
+    const inBoundsPages = pages.filter(pagePos => pagePos >= firstPagePos && pagePos <= lastPagePos);
+    const filteredItems = Array.from(itemsPages)
+        .filter(([pagePos]) => inBoundsPages.includes(pagePos))
+        .sort(([pageA], [pageB]) => pageA - pageB)
+        .flatMap(([pagePos, items]) => items.map((item, itemPos) => ({ item, pagePos, itemPos })))
+        .filter(({ item }) => filter(item));
+    const identifiers = filteredItems.map(({ item }) => getIdentifier?.(item));
+    const displayedItems = filteredItems.filter((_, pos) => {
+        const identifier = identifiers[pos];
+        if (identifier === undefined)
+            return true;
+        return identifiers.lastIndexOf(identifier) === pos;
+    });
+    const loadedPages = Array.from(itemsPages.keys())
+        .filter(pagePos => inBoundsPages.includes(pagePos))
+        .sort((a, b) => a - b);
+    const firstLoadedPage = loadedPages[0];
+    const lastLoadedPage = loadedPages[loadedPages.length - 1];
+    const gapPages = loadedPages.flatMap((pagePos, pos) => {
+        const prevPage = loadedPages[pos - 1];
+        if (prevPage === undefined)
+            return [];
+        return integersBetween(prevPage + 1, pagePos - 1);
+    });
+    const sortedLoadingPages = [...loadingPages ?? []]
+        .filter(pagePos => inBoundsPages.includes(pagePos))
+        .sort((a, b) => a - b);
+    const hasNothing = loadedPages.length === 0 && sortedLoadingPages.length === 0;
+    const slots = hasNothing
+        ? [{
+                pagePos: [...inBoundsPages].sort((a, b) => a - b)[0] ?? firstPagePos,
+                kind: 'gap'
+            }]
+        : [
+            ...firstLoadedPage !== undefined && firstLoadedPage > firstPagePos
+                ? [{ pagePos: firstLoadedPage - 1, kind: 'prev' }]
+                : [],
+            ...loadedPages.map(pagePos => ({ pagePos, kind: 'items' })),
+            ...gapPages.map(pagePos => ({ pagePos, kind: 'gap' })),
+            ...lastLoadedPage !== undefined && lastLoadedPage < lastPagePos
+                ? [{ pagePos: lastLoadedPage + 1, kind: 'next' }]
+                : []
+        ].sort((a, b) => a.pagePos - b.pagePos);
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, { loading: sortedLoadingPages.length > 0 }), className);
+    const renderLoadButton = (pagePos, kind) => {
+        const button = _jsx("button", { className: c('load', kind), "data-page": pagePos, onClick: () => onLoadPageClicked?.(pagePos) }, `load/${pagePos}`);
+        const autoLoads = (kind === 'prev' && autoLoadPrevWhenVisible === true)
+            || (kind === 'next' && autoLoadNextWhenVisible === true);
+        if (!autoLoads)
+            return button;
+        return _jsx(IntersectionObserverComponent, { className: c('load-observer', kind), threshold: threshold, root: root, rootMargin: rootMargin, onIntersected: ({ ioEntry }) => {
+                if (ioEntry?.isIntersecting !== true)
+                    return;
+                onLoadPageClicked?.(pagePos);
+            }, children: button }, `load/${pagePos}`);
+    };
+    return _jsx("div", { className: rootClss, "data-loading-pages": sortedLoadingPages.length === 0 ? undefined : sortedLoadingPages.join(','), children: slots.map(({ pagePos, kind }) => kind === 'items'
+            ? displayedItems
+                .filter(entry => entry.pagePos === pagePos)
+                .map(({ item, itemPos }) => _jsx("div", { className: c('item'), "data-page": pagePos, children: display(item) }, getIdentifier?.(item) ?? `${pagePos}/${itemPos}`))
+            : renderLoadButton(pagePos, kind)) });
+};

package/components/ListLoader/index.d.ts

@@ -0,0 +1,76 @@
+import { type ReactNode } from 'react';
+import { type Props as ControlledProps } from './index.controlled.js';
+/**
+ * Props for the {@link ListLoader} component.
+ *
+ * Extends {@link ControlledProps} — minus the data it derives itself — with
+ * fetching, staleness and page-set management.
+ *
+ * @template T - The item type carried by each page.
+ *
+ * @property pages - Page positions to keep loaded. When provided, the component
+ * is fully controlled: load buttons only report clicks and never change the set
+ * themselves. When omitted, the set is managed internally.
+ * @property defaultPage - Page loaded first in uncontrolled mode. Clamped into
+ * `firstPagePos`–`lastPagePos`, and defaults to `firstPagePos`. Ignored when
+ * `pages` is provided.
+ * @property fillGaps - When `true` (the default), any page missing between the
+ * lowest and highest requested page is requested automatically, so the loaded
+ * range stays contiguous. Ignored when `pages` is provided.
+ * @property dropPagesFurtherThan - Maximum distance, in pages, kept around a page
+ * loaded through a load button. Pages further away are dropped from state and
+ * from the DOM. Applies to load-button activations only, never to retries or
+ * stale reloads. Ignored when `pages` is provided.
+ * @property fetch - Fetches one page's items. Rejections are reported through
+ * `onPageFetchFailed` and retried according to `fetchRetriesNb`.
+ * @property staleAfterMs - Delay after which a loaded page is refetched, counted
+ * from its own last successful load. When omitted, pages are never refreshed.
+ * @property onPageFetched - Called with `pagePos` and `items` after a page's items
+ * have been stored. Not called for a page dropped while its request was in flight.
+ * @property onPageFetchFailed - Called with `pagePos` and `error` on every failed
+ * attempt, not only once retries are exhausted. When omitted, failures are logged
+ * with `console.warn`.
+ * @property fetchRetriesNb - Number of retries after a failed fetch. Defaults to
+ * `Infinity`, so a page keeps retrying until it succeeds.
+ * @property fetchRetriesDelayMs - Delay between two attempts. Defaults to `1000`.
+ */
+export type Props<T> = Omit<ControlledProps<T>, 'itemsPages' | 'loadingPages' | 'pages'> & {
+    pages?: number[];
+    defaultPage?: number;
+    fillGaps?: boolean;
+    dropPagesFurtherThan?: number;
+    fetch: (page: number) => Promise<T[]>;
+    staleAfterMs?: number;
+    onPageFetched?: (payload: {
+        pagePos: number;
+        items: T[];
+    }) => void;
+    onPageFetchFailed?: (payload: {
+        pagePos: number;
+        error: Error;
+    }) => void;
+    fetchRetriesNb?: number;
+    fetchRetriesDelayMs?: number;
+};
+/**
+ * Paginated list abstraction. Fetches the pages it is asked for, keeps them
+ * fresh, and drives a {@link ControlledListLoader} with the result.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ControlledListLoader} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledListLoader} fed with the loaded pages.
+ *
+ * @remarks
+ * - In controlled mode (`pages` defined), the page set is entirely driven by the
+ *   parent. `fillGaps` and `dropPagesFurtherThan` are inert, and load buttons only
+ *   report through `onLoadPageClicked`.
+ * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
+ *   buttons extend the set themselves. `onLoadPageClicked` still fires, after the
+ *   internal state has been updated.
+ * - A page removed from the effective set is dropped from memory, and a request
+ *   still in flight for it is discarded on arrival rather than re-inserted.
+ * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
+ *   is in use.
+ */
+export declare const ListLoader: <T>({ className, pages, defaultPage, fillGaps, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb, fetchRetriesDelayMs }: Props<T>) => ReactNode;

package/components/ListLoader/index.js

@@ -0,0 +1,162 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { integersBetween } from '@design-edito/tools/agnostic/arrays/integers-between/index.js';
+import { toError } from '@design-edito/tools/agnostic/misc/cast/index.js';
+import { clamp } from '@design-edito/tools/agnostic/numbers/clamp/index.js';
+import { ControlledListLoader } from './index.controlled.js';
+/**
+ * Paginated list abstraction. Fetches the pages it is asked for, keeps them
+ * fresh, and drives a {@link ControlledListLoader} with the result.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ControlledListLoader} for the rendered markup and CSS elements.
+ * @returns A {@link ControlledListLoader} fed with the loaded pages.
+ *
+ * @remarks
+ * - In controlled mode (`pages` defined), the page set is entirely driven by the
+ *   parent. `fillGaps` and `dropPagesFurtherThan` are inert, and load buttons only
+ *   report through `onLoadPageClicked`.
+ * - In uncontrolled mode, internal state is initialized from `defaultPage` and load
+ *   buttons extend the set themselves. `onLoadPageClicked` still fires, after the
+ *   internal state has been updated.
+ * - A page removed from the effective set is dropped from memory, and a request
+ *   still in flight for it is discarded on arrival rather than re-inserted.
+ * - No page outside `firstPagePos`–`lastPagePos` is ever fetched, whichever mode
+ *   is in use.
+ */
+export const ListLoader = ({ className, pages, defaultPage, fillGaps = true, dropPagesFurtherThan, autoLoadPrevWhenVisible, autoLoadNextWhenVisible, threshold, root, rootMargin, firstPagePos, lastPagePos, fetch, filter, display, getIdentifier, onLoadPageClicked, staleAfterMs, onPageFetched, onPageFetchFailed, fetchRetriesNb = Infinity, fetchRetriesDelayMs = 1000 }) => {
+    const [itemsPages, setItemsPages] = useState(new Map());
+    const [loadingPages, setLoadingPages] = useState(new Set());
+    const [internalPages, setInternalPages] = useState([
+        clamp(defaultPage ?? firstPagePos, firstPagePos, lastPagePos)
+    ]);
+    const requestedPages = useRef(new Set());
+    const retryTimeouts = useRef(new Set());
+    // Single source of truth for what should be loaded. Memoized so the effects
+    // below keep a stable dependency when the page set has not actually changed.
+    const currentPages = useMemo(() => (pages ?? internalPages).filter(page => page >= firstPagePos && page <= lastPagePos), [pages, internalPages, firstPagePos, lastPagePos]);
+    const handleLoadClick = (pagePos) => {
+        if (pages === undefined) {
+            setInternalPages(curr => {
+                const next = curr.includes(pagePos) ? curr : [...curr, pagePos];
+                if (dropPagesFurtherThan === undefined)
+                    return next;
+                const kept = next.filter(page => Math.abs(page - pagePos) <= dropPagesFurtherThan);
+                return kept.length === next.length ? next : kept;
+            });
+        }
+        const gaveUp = requestedPages.current.has(pagePos)
+            && !itemsPages.has(pagePos)
+            && !loadingPages.has(pagePos);
+        if (gaveUp)
+            loadPage(pagePos);
+        onLoadPageClicked?.(pagePos);
+    };
+    const storePage = (page, items) => setItemsPages(curr => {
+        const next = new Map(curr);
+        next.set(page, { loadedAt: new Date(), items });
+        return next;
+    });
+    const setPageLoading = (page, isLoading) => setLoadingPages(curr => {
+        const next = new Set(curr);
+        if (isLoading)
+            next.add(page);
+        else
+            next.delete(page);
+        return next;
+    });
+    const reportFetchError = (page, err) => {
+        const error = toError(err);
+        if (onPageFetchFailed !== undefined)
+            return onPageFetchFailed({ pagePos: page, error });
+        // eslint-disable-next-line no-console
+        console.warn(`ListLoader failed to fetch page ${page}`, error);
+    };
+    // Guards the whole load path at once: a page dropped meanwhile stops its
+    // pending retries and its stale reloads without any further bookkeeping.
+    const loadPage = (page, retriesLeft = fetchRetriesNb) => {
+        if (!requestedPages.current.has(page))
+            return;
+        setPageLoading(page, true);
+        void fetch(page)
+            .then(items => {
+            if (!requestedPages.current.has(page))
+                return;
+            storePage(page, items);
+            onPageFetched?.({ pagePos: page, items });
+            setPageLoading(page, false);
+        })
+            .catch((err) => {
+            reportFetchError(page, err);
+            if (retriesLeft <= 0)
+                return setPageLoading(page, false);
+            const timeout = window.setTimeout(() => {
+                retryTimeouts.current.delete(timeout);
+                loadPage(page, retriesLeft - 1);
+            }, fetchRetriesDelayMs);
+            retryTimeouts.current.add(timeout);
+        });
+    };
+    // Fx. dep. none - Emptying `requestedPages` is what stops a fetch already in flight.
+    useEffect(() => () => {
+        retryTimeouts.current.forEach(timeout => { window.clearTimeout(timeout); });
+        retryTimeouts.current.clear();
+        requestedPages.current.clear();
+    }, []);
+    // Fx. dep. `currentPages` - Drops everything held for pages no longer wanted.
+    // The updaters return `curr` untouched when nothing was removed, so an unstable
+    // `pages` prop cannot spin the render loop.
+    useEffect(() => {
+        Array.from(requestedPages.current)
+            .filter(page => !currentPages.includes(page))
+            .forEach(page => { requestedPages.current.delete(page); });
+        setItemsPages(curr => {
+            const next = new Map(Array.from(curr).filter(([page]) => currentPages.includes(page)));
+            return next.size === curr.size ? curr : next;
+        });
+        setLoadingPages(curr => {
+            const next = new Set(Array.from(curr).filter(page => currentPages.includes(page)));
+            return next.size === curr.size ? curr : next;
+        });
+    }, [currentPages]);
+    useEffect(() => {
+        if (pages !== undefined)
+            return;
+        if (!fillGaps)
+            return;
+        setInternalPages(curr => {
+            if (curr.length === 0)
+                return curr;
+            const missing = integersBetween(Math.min(...curr), Math.max(...curr))
+                .filter(page => !curr.includes(page));
+            if (missing.length === 0)
+                return curr;
+            return [...curr, ...missing];
+        });
+    }, [currentPages, fillGaps, pages]);
+    useEffect(() => {
+        currentPages.forEach(page => {
+            if (requestedPages.current.has(page))
+                return;
+            requestedPages.current.add(page);
+            loadPage(page);
+        });
+    }, [currentPages, fetch]);
+    // Fx. dep. `itemsPages` - Reschedules one timeout per page on every store, each
+    // due from its own `loadedAt`. A refetch updates `loadedAt`, which re-runs this
+    // effect and keeps the cycle going.
+    useEffect(() => {
+        if (staleAfterMs === undefined)
+            return;
+        const timeouts = Array.from(itemsPages).map(([page, { loadedAt }]) => {
+            const dueInMs = Math.max(0, staleAfterMs - (Date.now() - loadedAt.getTime()));
+            return window.setTimeout(() => loadPage(page), dueInMs);
+        });
+        return () => timeouts.forEach(timeout => window.clearTimeout(timeout));
+    }, [itemsPages, staleAfterMs, fetch]);
+    const controlledItemsPages = new Map(Array
+        .from(itemsPages)
+        .map(([page, { items }]) => [page, items]));
+    return _jsx(ControlledListLoader, { className: className, pages: currentPages, firstPagePos: firstPagePos, lastPagePos: lastPagePos, itemsPages: controlledItemsPages, filter: filter, display: display, getIdentifier: getIdentifier, loadingPages: Array.from(loadingPages), onLoadPageClicked: handleLoadClick, autoLoadPrevWhenVisible: autoLoadPrevWhenVisible, autoLoadNextWhenVisible: autoLoadNextWhenVisible, threshold: threshold, root: root, rootMargin: rootMargin });
+};

package/components/index.d.ts

@@ -1 +1,5 @@
+export * as date from './Date/index.js'
+export * as embed from './Embed/index.js'
+export * as jsonEditor from './JsonEditor/index.js'
+export * as listLoader from './ListLoader/index.js'
 export * as utils from './utils/index.js'

package/components/index.js

@@ -1 +1,5 @@
+export * as date from './Date/index.js'
+export * as embed from './Embed/index.js'
+export * as jsonEditor from './JsonEditor/index.js'
+export * as listLoader from './ListLoader/index.js'
 export * as utils from './utils/index.js'

package/components/public-classnames.d.ts

@@ -1,5 +1,11 @@
 export declare const button = "mxfb-button";
+export declare const date = "mxfb-date";
+export declare const embed = "mxfb-embed";
 export declare const input = "mxfb-input";
 export declare const jsonEditor = "mxfb-json-editor";
+export declare const listLoader = "mxfb-list-loader";
 export declare const select = "mxfb-select";
+export declare const spotifyEmbed = "mxfb-spotify-embed";
 export declare const textarea = "mxfb-textarea";
+export declare const vimeoEmbed = "mxfb-vimeo-embed";
+export declare const youtubeEmbed = "mxfb-youtube-embed";

package/components/public-classnames.js

@@ -1,5 +1,11 @@
 export const button = 'mxfb-button';
+export const date = 'mxfb-date';
+export const embed = 'mxfb-embed';
 export const input = 'mxfb-input';
 export const jsonEditor = 'mxfb-json-editor';
+export const listLoader = 'mxfb-list-loader';
 export const select = 'mxfb-select';
+export const spotifyEmbed = 'mxfb-spotify-embed';
 export const textarea = 'mxfb-textarea';
+export const vimeoEmbed = 'mxfb-vimeo-embed';
+export const youtubeEmbed = 'mxfb-youtube-embed';

package/index.d.ts

@@ -1,3 +1,3 @@
-export * as components from './components/index.js'
 export * as agnostic from './agnostic/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 components from './components/index.js'
 export * as agnostic from './agnostic/index.js'
+export * as components from './components/index.js'
 export * as node from './node/index.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mxfb/tools",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "",
   "author": "Maxime Fabas",
   "license": "ISC",
@@ -116,9 +116,70 @@
       "import": "./components/index.js",
       "types": "./components/index.d.ts"
     },
+    "./components/Date": {
+      "import": "./components/Date/index.js",
+      "types": "./components/Date/index.d.ts"
+    },
+    "./components/Date/index.js": {
+      "import": "./components/Date/index.js"
+    },
+    "./components/Date/types.js": {
+      "import": "./components/Date/types.js",
+      "types": "./components/Date/types.d.ts"
+    },
+    "./components/Embed": {
+      "import": "./components/Embed/index.js",
+      "types": "./components/Embed/index.d.ts"
+    },
+    "./components/Embed/index.js": {
+      "import": "./components/Embed/index.js"
+    },
+    "./components/Embed/SpotifyEmbed": {
+      "import": "./components/Embed/SpotifyEmbed/index.js",
+      "types": "./components/Embed/SpotifyEmbed/index.d.ts"
+    },
+    "./components/Embed/SpotifyEmbed/index.js": {
+      "import": "./components/Embed/SpotifyEmbed/index.js"
+    },
+    "./components/Embed/types.js": {
+      "import": "./components/Embed/types.js",
+      "types": "./components/Embed/types.d.ts"
+    },
+    "./components/Embed/VimeoEmbed": {
+      "import": "./components/Embed/VimeoEmbed/index.js",
+      "types": "./components/Embed/VimeoEmbed/index.d.ts"
+    },
+    "./components/Embed/VimeoEmbed/index.js": {
+      "import": "./components/Embed/VimeoEmbed/index.js"
+    },
+    "./components/Embed/YoutubeEmbed": {
+      "import": "./components/Embed/YoutubeEmbed/index.js",
+      "types": "./components/Embed/YoutubeEmbed/index.d.ts"
+    },
+    "./components/Embed/YoutubeEmbed/index.js": {
+      "import": "./components/Embed/YoutubeEmbed/index.js"
+    },
     "./components/index.js": {
       "import": "./components/index.js"
     },
+    "./components/JsonEditor": {
+      "import": "./components/JsonEditor/index.js",
+      "types": "./components/JsonEditor/index.d.ts"
+    },
+    "./components/JsonEditor/index.js": {
+      "import": "./components/JsonEditor/index.js"
+    },
+    "./components/JsonEditor/types.js": {
+      "import": "./components/JsonEditor/types.js",
+      "types": "./components/JsonEditor/types.d.ts"
+    },
+    "./components/ListLoader": {
+      "import": "./components/ListLoader/index.js",
+      "types": "./components/ListLoader/index.d.ts"
+    },
+    "./components/ListLoader/index.js": {
+      "import": "./components/ListLoader/index.js"
+    },
     "./components/utils": {
       "import": "./components/utils/index.js",
       "types": "./components/utils/index.d.ts"
@@ -174,7 +235,7 @@
     "@aws-sdk/client-s3": "^3.999.0",
     "@aws-sdk/lib-storage": "^3.1008.0",
     "@design-edito/publisher": "^0.1.17",
-    "@design-edito/tools": "^0.5.39",
+    "@design-edito/tools": "^0.5.40",
     "@google-cloud/storage": "^7.19.0",
     "@inquirer/prompts": "^8.3.0",
     "ansi-regex": "^6.2.2",