@asteby/metacore-runtime-react 39.3.0 → 42.0.0

package/dist/use-flip-animation.js

@@ -0,0 +1,123 @@
+import { useEffect, useLayoutEffect, useRef } from 'react';
+import { motionDuration, motionEasing, prefersReducedMotion, } from './motion';
+const DEFAULT_SELECTOR = '[data-flip-key]';
+const MOTION_EASING_KEYS = { standard: 1, emphasized: 1, exit: 1 };
+const defaultKeyOf = (el) => el.dataset.flipKey ?? el.getAttribute('href') ?? (el.textContent?.trim() || null);
+/**
+ * FLIP reorder animation: when `trigger` changes, elements that exist before
+ * and after the change glide from their old position to the new one.
+ *
+ * Positions are snapshotted when the list is at rest (after mount, after each
+ * animation, and after pointer interaction inside the root), never in the
+ * render path, so a re-render costs nothing. Uses the Web Animations API on
+ * `transform` only; with prefers-reduced-motion the change is instant.
+ */
+export function useFlipAnimation(rootRef, trigger, options = {}) {
+    const { selector = DEFAULT_SELECTOR, keyOf = defaultKeyOf, scrollContainer, duration = 'moderate', easing = 'standard', disabled = false, } = options;
+    const positionsRef = useRef(null);
+    const triggerRef = useRef(trigger);
+    const configRef = useRef({ selector, keyOf, scrollContainer });
+    useEffect(() => {
+        configRef.current = { selector, keyOf, scrollContainer };
+    });
+    const measure = () => {
+        const root = rootRef.current;
+        if (!root)
+            return null;
+        const { selector: sel, keyOf: key, scrollContainer: sc } = configRef.current;
+        const origin = (sc ? sc(root) : null) ?? root;
+        const box = origin.getBoundingClientRect();
+        const out = new Map();
+        root.querySelectorAll(sel).forEach((el) => {
+            const k = key(el);
+            if (!k || out.has(k))
+                return;
+            const r = el.getBoundingClientRect();
+            if (r.width === 0 && r.height === 0)
+                return;
+            out.set(k, {
+                top: r.top - box.top + origin.scrollTop,
+                left: r.left - box.left + origin.scrollLeft,
+            });
+        });
+        return out;
+    };
+    const measureRef = useRef(measure);
+    useEffect(() => {
+        measureRef.current = measure;
+    });
+    // Snapshot at rest: after mount and after interactions that move things
+    // without a trigger change (expanding a collapsible, for instance).
+    // Listens on the document and resolves the root per event, so a ref whose
+    // element is swapped (remount, mobile sheet) keeps working.
+    useEffect(() => {
+        let timer = null;
+        const schedule = () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = setTimeout(() => {
+                positionsRef.current = measureRef.current();
+            }, 350);
+        };
+        const onInteraction = (e) => {
+            const root = rootRef.current;
+            if (root && e.target instanceof Node && root.contains(e.target))
+                schedule();
+        };
+        schedule();
+        document.addEventListener('pointerup', onInteraction, true);
+        document.addEventListener('keyup', onInteraction, true);
+        window.addEventListener('resize', schedule);
+        return () => {
+            if (timer)
+                clearTimeout(timer);
+            document.removeEventListener('pointerup', onInteraction, true);
+            document.removeEventListener('keyup', onInteraction, true);
+            window.removeEventListener('resize', schedule);
+        };
+    }, [rootRef]);
+    useLayoutEffect(() => {
+        if (Object.is(triggerRef.current, trigger))
+            return;
+        triggerRef.current = trigger;
+        const before = positionsRef.current;
+        const root = rootRef.current;
+        if (!root)
+            return;
+        const after = measureRef.current();
+        positionsRef.current = after;
+        if (!before || !after || disabled || prefersReducedMotion())
+            return;
+        const durationMs = typeof duration === 'number' ? duration : motionDuration(duration);
+        if (durationMs <= 0)
+            return;
+        const timing = easing in MOTION_EASING_KEYS ? motionEasing(easing) : easing;
+        const { selector: sel, keyOf: key } = configRef.current;
+        // A stale snapshot can report huge jumps; those would read as a glitch.
+        const maxJump = root.clientHeight > 0 ? root.clientHeight * 1.5 : Infinity;
+        root.querySelectorAll(sel).forEach((el) => {
+            const k = key(el);
+            if (!k)
+                return;
+            const from = before.get(k);
+            const to = after.get(k);
+            if (!to || typeof el.animate !== 'function')
+                return;
+            if (!from) {
+                // Entered with this change: fade in instead of popping.
+                el.animate([{ opacity: 0 }, { opacity: 1 }], { duration: durationMs, easing: timing });
+                return;
+            }
+            const dy = from.top - to.top;
+            const dx = from.left - to.left;
+            if (Math.abs(dy) < 1 && Math.abs(dx) < 1)
+                return;
+            if (Math.abs(dy) > maxJump)
+                return;
+            el.animate([
+                { transform: `translate(${dx}px, ${dy}px)` },
+                { transform: 'translate(0, 0)' },
+            ], { duration: durationMs, easing: timing });
+        });
+    }, [trigger, rootRef, disabled, duration, easing]);
+}

package/dist/use-optimistic-mutation.d.ts

@@ -0,0 +1,73 @@
+import { type QueryKey } from '@tanstack/react-query';
+export interface UseOptimisticMutationOptions<TData, TVariables, TCache> {
+    /** Query whose cached value the mutation changes. */
+    queryKey: QueryKey;
+    mutationFn: (variables: TVariables) => Promise<TData>;
+    /**
+     * Cache value to show while the request is in flight. Runs synchronously on
+     * `mutate`, so the UI repaints on the same frame as the click. Return
+     * `undefined` to leave the cache untouched.
+     */
+    optimistic: (current: TCache | undefined, variables: TVariables) => TCache | undefined;
+    /**
+     * Cache value once the server confirms. Write/apply endpoints that return
+     * the resulting resource should map it here, so nothing is refetched.
+     * Default: keep the optimistic value.
+     */
+    reconcile?: (data: TData, variables: TVariables, current: TCache | undefined) => TCache | undefined;
+    /**
+     * Coalesce bursts (drag and drop, sliders): the cache updates on every
+     * call, and only the last variables are sent once `debounceMs` pass
+     * without a new call. Pending work is flushed on unmount.
+     */
+    debounceMs?: number;
+    /**
+     * A call equal to the one already in flight is ignored (double clicks).
+     * Default: structural equality via JSON.
+     */
+    isEqual?: (a: TVariables, b: TVariables) => boolean;
+    /** Other queries to refresh in the background after a confirmed write. */
+    invalidate?: QueryKey[];
+    onSuccess?: (data: TData, variables: TVariables) => void;
+    /**
+     * Runs after the cache was rolled back to the last confirmed value. Only
+     * the latest call reports: a superseded write that fails stays silent.
+     */
+    onError?: (error: unknown, variables: TVariables) => void;
+}
+export interface UseOptimisticMutationResult<TVariables> {
+    /** Apply optimistically and persist. Safe to call repeatedly. */
+    mutate: (variables: TVariables) => void;
+    /** True from the first `mutate` until the last one settles. */
+    isPending: boolean;
+    /** Variables of the latest unconfirmed call (e.g. which card is applying). */
+    pendingVariables: TVariables | undefined;
+    error: unknown;
+    /** Re-send the variables of the last call that failed (toast "Reintentar"). */
+    retry: () => void;
+}
+/**
+ * Optimistic write over a TanStack Query cache entry, with rollback.
+ *
+ * ```tsx
+ * const apply = useOptimisticMutation({
+ *   queryKey: ['org-sidebar-layout'],
+ *   mutationFn: (key: string) => api.post('/apply', { key }).then((r) => r.data),
+ *   optimistic: (current, key) => ({ ...current, template_key: key }),
+ *   reconcile: (server) => server,
+ *   onError: (_e, key) => toast.error('No se aplicó', {
+ *     action: { label: 'Reintentar', onClick: () => apply.mutate(key) },
+ *   }),
+ * })
+ * <Card aria-busy={apply.pendingVariables === tpl.key} onClick={() => apply.mutate(tpl.key)} />
+ * ```
+ *
+ * - The cache is patched before the request, so the screen answers at once.
+ * - Writes to the same `queryKey` run one at a time, in call order (mutation
+ *   `scope`), so the last click is the last write the server sees.
+ * - Only the latest call decides what the cache shows: an older response
+ *   never overwrites a newer optimistic value. If the latest call fails, the
+ *   cache returns to the last value the server confirmed.
+ */
+export declare function useOptimisticMutation<TData, TVariables, TCache = TData>(options: UseOptimisticMutationOptions<TData, TVariables, TCache>): UseOptimisticMutationResult<TVariables>;
+//# sourceMappingURL=use-optimistic-mutation.d.ts.map

package/dist/use-optimistic-mutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-mutation.d.ts","sourceRoot":"","sources":["../src/use-optimistic-mutation.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,uBAAuB,CAAA;AAE9B,MAAM,WAAW,4BAA4B,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM;IACrE,qDAAqD;IACrD,QAAQ,EAAE,QAAQ,CAAA;IAClB,UAAU,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,OAAO,CAAC,KAAK,CAAC,CAAA;IACrD;;;;OAIG;IACH,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,EAAE,SAAS,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,CAAA;IACtF;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,MAAM,GAAG,SAAS,CAAA;IACnG;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,KAAK,OAAO,CAAA;IACnD,0EAA0E;IAC1E,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAA;IACvB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,KAAK,IAAI,CAAA;IACxD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,UAAU,KAAK,IAAI,CAAA;CAC1D;AAED,MAAM,WAAW,2BAA2B,CAAC,UAAU;IACrD,iEAAiE;IACjE,MAAM,EAAE,CAAC,SAAS,EAAE,UAAU,KAAK,IAAI,CAAA;IACvC,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAA;IAClB,8EAA8E;IAC9E,gBAAgB,EAAE,UAAU,GAAG,SAAS,CAAA;IACxC,KAAK,EAAE,OAAO,CAAA;IACd,+EAA+E;IAC/E,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,GAAG,KAAK,EACrE,OAAO,EAAE,4BAA4B,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,GAC/D,2BAA2B,CAAC,UAAU,CAAC,CAoIzC"}

package/dist/use-optimistic-mutation.js

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useMutation, useQueryClient, } from '@tanstack/react-query';
+const jsonEqual = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * Optimistic write over a TanStack Query cache entry, with rollback.
+ *
+ * ```tsx
+ * const apply = useOptimisticMutation({
+ *   queryKey: ['org-sidebar-layout'],
+ *   mutationFn: (key: string) => api.post('/apply', { key }).then((r) => r.data),
+ *   optimistic: (current, key) => ({ ...current, template_key: key }),
+ *   reconcile: (server) => server,
+ *   onError: (_e, key) => toast.error('No se aplicó', {
+ *     action: { label: 'Reintentar', onClick: () => apply.mutate(key) },
+ *   }),
+ * })
+ * <Card aria-busy={apply.pendingVariables === tpl.key} onClick={() => apply.mutate(tpl.key)} />
+ * ```
+ *
+ * - The cache is patched before the request, so the screen answers at once.
+ * - Writes to the same `queryKey` run one at a time, in call order (mutation
+ *   `scope`), so the last click is the last write the server sees.
+ * - Only the latest call decides what the cache shows: an older response
+ *   never overwrites a newer optimistic value. If the latest call fails, the
+ *   cache returns to the last value the server confirmed.
+ */
+export function useOptimisticMutation(options) {
+    const qc = useQueryClient();
+    const optionsRef = useRef(options);
+    useEffect(() => {
+        optionsRef.current = options;
+    });
+    const seqRef = useRef(0);
+    // Last value the server confirmed, captured before the first unconfirmed
+    // optimistic write. Null while nothing is in flight.
+    const confirmedRef = useRef(null);
+    const inFlightRef = useRef(undefined);
+    const timerRef = useRef(null);
+    const queuedRef = useRef(null);
+    const [pendingVariables, setPendingVariables] = useState(undefined);
+    const [error, setError] = useState(null);
+    const failedRef = useRef(null);
+    const scopeId = `optimistic:${JSON.stringify(options.queryKey)}`;
+    const settleLatest = useCallback(() => {
+        confirmedRef.current = null;
+        inFlightRef.current = undefined;
+        setPendingVariables(undefined);
+    }, []);
+    const mutation = useMutation({
+        scope: { id: scopeId },
+        mutationFn: ({ variables }) => optionsRef.current.mutationFn(variables),
+        onSuccess: (data, { variables, seq }) => {
+            const opts = optionsRef.current;
+            const latest = seq === seqRef.current && queuedRef.current === null;
+            if (latest) {
+                const current = qc.getQueryData(opts.queryKey);
+                const next = opts.reconcile ? opts.reconcile(data, variables, current) : current;
+                if (next !== undefined)
+                    qc.setQueryData(opts.queryKey, next);
+                settleLatest();
+                setError(null);
+                for (const key of opts.invalidate ?? [])
+                    void qc.invalidateQueries({ queryKey: key });
+            }
+            else if (confirmedRef.current) {
+                // A newer call owns the screen; only move the rollback point forward.
+                const base = confirmedRef.current.value;
+                const next = opts.reconcile
+                    ? opts.reconcile(data, variables, base)
+                    : opts.optimistic(base, variables);
+                confirmedRef.current = { value: next ?? base };
+            }
+            opts.onSuccess?.(data, variables);
+        },
+        onError: (err, { variables, seq }) => {
+            const opts = optionsRef.current;
+            const latest = seq === seqRef.current && queuedRef.current === null;
+            // A superseded write that fails is moot: the newer call decides what
+            // the screen shows and whether the user sees an error.
+            if (!latest)
+                return;
+            const confirmed = confirmedRef.current;
+            if (confirmed && confirmed.value !== undefined) {
+                qc.setQueryData(opts.queryKey, confirmed.value);
+            }
+            settleLatest();
+            // The server may have partially applied; resync in the background.
+            void qc.invalidateQueries({ queryKey: opts.queryKey, exact: true });
+            failedRef.current = { variables };
+            setError(err);
+            opts.onError?.(err, variables);
+        },
+    });
+    const mutateRef = useRef(mutation.mutate);
+    useEffect(() => {
+        mutateRef.current = mutation.mutate;
+    });
+    const send = useCallback((envelope) => {
+        inFlightRef.current = envelope.variables;
+        mutateRef.current(envelope);
+    }, []);
+    const flush = useCallback(() => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        timerRef.current = null;
+        const queued = queuedRef.current;
+        queuedRef.current = null;
+        if (queued)
+            send(queued);
+    }, [send]);
+    const mutate = useCallback((variables) => {
+        const opts = optionsRef.current;
+        const isEqual = opts.isEqual ?? jsonEqual;
+        const latestPending = queuedRef.current?.variables ?? inFlightRef.current;
+        if (latestPending !== undefined && isEqual(latestPending, variables))
+            return;
+        const seq = ++seqRef.current;
+        if (!confirmedRef.current) {
+            confirmedRef.current = { value: qc.getQueryData(opts.queryKey) };
+        }
+        // A refetch landing mid-write would paint the old value back.
+        void qc.cancelQueries({ queryKey: opts.queryKey, exact: true });
+        const next = opts.optimistic(qc.getQueryData(opts.queryKey), variables);
+        if (next !== undefined)
+            qc.setQueryData(opts.queryKey, next);
+        setPendingVariables(variables);
+        setError(null);
+        failedRef.current = null;
+        const envelope = { variables, seq };
+        if (opts.debounceMs && opts.debounceMs > 0) {
+            queuedRef.current = envelope;
+            if (timerRef.current)
+                clearTimeout(timerRef.current);
+            timerRef.current = setTimeout(flush, opts.debounceMs);
+            return;
+        }
+        send(envelope);
+    }, [qc, flush, send]);
+    // Never drop a debounced write because the editor closed.
+    useEffect(() => flush, [flush]);
+    const retry = useCallback(() => {
+        const failed = failedRef.current;
+        if (failed)
+            mutate(failed.variables);
+    }, [mutate]);
+    return {
+        mutate,
+        isPending: pendingVariables !== undefined,
+        pendingVariables,
+        error,
+        retry,
+    };
+}

package/dist/use-persisted-query.d.ts

@@ -0,0 +1,53 @@
+import { type QueryKey, type UseQueryOptions, type UseQueryResult } from '@tanstack/react-query';
+/**
+ * A versioned, scoped copy of a value in localStorage. Shell data that decides
+ * the first paint (navigation, the org's menu layout, installed presets,
+ * permissions) is read from here synchronously, so a reload paints the last
+ * known state instead of a default that reorders when the network answers.
+ *
+ * The entry lives under `<key>:v<version>:<scope>`. Bump `version` when the
+ * stored shape changes; old entries are simply never read again. `scope` keeps
+ * one org or user from seeing another's copy on a shared browser.
+ */
+export interface PersistedSnapshotOptions {
+    key: string;
+    version: number;
+    /** Entries older than this are ignored (default: 30 days). */
+    maxAgeMs?: number;
+}
+export interface PersistedEntry<T> {
+    data: T;
+    /** When the data was fetched (ms epoch). */
+    ts: number;
+}
+export interface PersistedSnapshot<T> {
+    read(scope: string): PersistedEntry<T> | undefined;
+    write(scope: string, data: T, meta?: {
+        ts?: number;
+    }): void;
+    clear(scope: string): void;
+}
+export declare function createPersistedSnapshot<T>({ key, version, maxAgeMs, }: PersistedSnapshotOptions): PersistedSnapshot<T>;
+export type UsePersistedQueryOptions<TQueryFnData, TData, TQueryKey extends QueryKey> = UseQueryOptions<TQueryFnData, Error, TData, TQueryKey> & {
+    persist: {
+        snapshot: PersistedSnapshot<TQueryFnData>;
+        /**
+         * Org/user the data belongs to. Without a scope nothing is read or
+         * written (e.g. before sign-in).
+         */
+        scope: string | null | undefined;
+    };
+};
+/**
+ * `useQuery` seeded from a {@link PersistedSnapshot}: the first render already
+ * has the last fetched value (stale-while-revalidate), and every later value —
+ * a refetch, or a `setQueryData` from a mutation — is written back. The seed is
+ * stale from the start: every page load revalidates it once in the background,
+ * so a change made elsewhere (a plantilla applied, an addon installed,
+ * permissions edited) shows on the next load even inside `staleTime`.
+ *
+ * Persist the raw server payload and derive UI shapes with `select`; the
+ * snapshot must be JSON.
+ */
+export declare function usePersistedQuery<TQueryFnData, TData = TQueryFnData, TQueryKey extends QueryKey = QueryKey>(options: UsePersistedQueryOptions<TQueryFnData, TData, TQueryKey>): UseQueryResult<TData, Error>;
+//# sourceMappingURL=use-persisted-query.d.ts.map

package/dist/use-persisted-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-persisted-query.d.ts","sourceRoot":"","sources":["../src/use-persisted-query.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAA;IACP,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,SAAS,CAAA;IAClD,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAA;IAC3D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAYD,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,EACzC,GAAG,EACH,OAAO,EACP,QAA6B,GAC9B,EAAE,wBAAwB,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAgCjD;AAED,MAAM,MAAM,wBAAwB,CAAC,YAAY,EAAE,KAAK,EAAE,SAAS,SAAS,QAAQ,IAAI,eAAe,CACrG,YAAY,EACZ,KAAK,EACL,KAAK,EACL,SAAS,CACV,GAAG;IACF,OAAO,EAAE;QACP,QAAQ,EAAE,iBAAiB,CAAC,YAAY,CAAC,CAAA;QACzC;;;WAGG;QACH,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;KACjC,CAAA;CACF,CAAA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EACZ,KAAK,GAAG,YAAY,EACpB,SAAS,SAAS,QAAQ,GAAG,QAAQ,EAErC,OAAO,EAAE,wBAAwB,CAAC,YAAY,EAAE,KAAK,EAAE,SAAS,CAAC,GAChE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CA+B9B"}

package/dist/use-persisted-query.js

@@ -0,0 +1,92 @@
+import { useEffect, useMemo } from 'react';
+import { useQuery, useQueryClient, } from '@tanstack/react-query';
+const DEFAULT_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+function storage() {
+    try {
+        return typeof localStorage === 'undefined' ? null : localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+export function createPersistedSnapshot({ key, version, maxAgeMs = DEFAULT_MAX_AGE_MS, }) {
+    const slot = (scope) => `${key}:v${version}:${scope}`;
+    return {
+        read(scope) {
+            const s = storage();
+            if (!s)
+                return undefined;
+            try {
+                const raw = s.getItem(slot(scope));
+                if (!raw)
+                    return undefined;
+                const parsed = JSON.parse(raw);
+                if (typeof parsed?.ts !== 'number' || !('data' in parsed))
+                    return undefined;
+                if (Date.now() - parsed.ts > maxAgeMs)
+                    return undefined;
+                return { data: parsed.data, ts: parsed.ts };
+            }
+            catch {
+                return undefined;
+            }
+        },
+        write(scope, data, { ts = Date.now() } = {}) {
+            try {
+                storage()?.setItem(slot(scope), JSON.stringify({ data, ts }));
+            }
+            catch {
+                // quota / private mode: the snapshot is an optimization, never fatal
+            }
+        },
+        clear(scope) {
+            try {
+                storage()?.removeItem(slot(scope));
+            }
+            catch {
+                /* ignore */
+            }
+        },
+    };
+}
+/**
+ * `useQuery` seeded from a {@link PersistedSnapshot}: the first render already
+ * has the last fetched value (stale-while-revalidate), and every later value —
+ * a refetch, or a `setQueryData` from a mutation — is written back. The seed is
+ * stale from the start: every page load revalidates it once in the background,
+ * so a change made elsewhere (a plantilla applied, an addon installed,
+ * permissions edited) shows on the next load even inside `staleTime`.
+ *
+ * Persist the raw server payload and derive UI shapes with `select`; the
+ * snapshot must be JSON.
+ */
+export function usePersistedQuery(options) {
+    const { persist, ...queryOptions } = options;
+    const { snapshot, scope } = persist;
+    const seed = useMemo(() => (scope ? snapshot.read(scope) : undefined), [snapshot, scope]);
+    const query = useQuery({
+        ...queryOptions,
+        ...(seed && queryOptions.initialData === undefined
+            ? { initialData: seed.data, initialDataUpdatedAt: 0 }
+            : {}),
+    });
+    const queryClient = useQueryClient();
+    const { dataUpdatedAt, status, isPlaceholderData } = query;
+    const queryKey = queryOptions.queryKey;
+    useEffect(() => {
+        if (!scope || status !== 'success' || isPlaceholderData)
+            return;
+        // Still the seed: nothing new to store.
+        if (dataUpdatedAt === 0)
+            return;
+        // `query.data` is the selected shape; persist the raw cache value.
+        const raw = queryClient.getQueryData(queryKey);
+        if (raw === undefined)
+            return;
+        snapshot.write(scope, raw, { ts: dataUpdatedAt });
+        // queryKey is compared by react-query's hash, not identity: a new array
+        // each render must not rewrite the snapshot.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [queryClient, scope, snapshot, seed, status, isPlaceholderData, dataUpdatedAt]);
+    return query;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "39.3.0",
+  "version": "42.0.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "zod": "^4.3.0"
   },
   "peerDependencies": {
-    "@asteby/metacore-sdk": "^3.8.0",
-    "@asteby/metacore-ui": "^2.18.3",
+    "@asteby/metacore-sdk": "^3.9.0",
+    "@asteby/metacore-ui": "^2.22.0",
     "@tanstack/react-query": ">=5",
     "@tanstack/react-router": ">=1.100",
     "@tanstack/react-table": ">=8",
@@ -50,8 +50,8 @@
     }
   },
   "devDependencies": {
-    "@asteby/metacore-sdk": "3.8.0",
-    "@asteby/metacore-ui": "2.18.3",
+    "@asteby/metacore-sdk": "3.9.0",
+    "@asteby/metacore-ui": "2.22.0",
     "@tanstack/react-query": "^5.95.0",
     "@tanstack/react-router": "^1.168.0",
     "@tanstack/react-table": "^8.20.0",

package/src/__tests__/motion.test.ts

@@ -0,0 +1,29 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, afterEach, vi } from 'vitest'
+import { motionDuration, motionEasing, MOTION_DEFAULTS } from '../motion'
+
+afterEach(() => {
+  document.documentElement.style.cssText = ''
+  vi.restoreAllMocks()
+})
+
+describe('motion tokens', () => {
+  it('falls back to the theme defaults when the host defines no variables', () => {
+    expect(motionDuration('moderate')).toBe(MOTION_DEFAULTS.duration.moderate)
+    expect(motionEasing('standard')).toBe(MOTION_DEFAULTS.easing.standard)
+  })
+
+  it('reads the host theme variables (ms and s)', () => {
+    document.documentElement.style.setProperty('--motion-duration-moderate', '0.3s')
+    document.documentElement.style.setProperty('--motion-duration-fast', '90ms')
+    document.documentElement.style.setProperty('--motion-ease-standard', 'linear')
+    expect(motionDuration('moderate')).toBe(300)
+    expect(motionDuration('fast')).toBe(90)
+    expect(motionEasing('standard')).toBe('linear')
+  })
+
+  it('is zero under prefers-reduced-motion', () => {
+    vi.spyOn(window, 'matchMedia').mockReturnValue({ matches: true } as MediaQueryList)
+    expect(motionDuration('slow')).toBe(0)
+  })
+})

package/src/__tests__/use-flip-animation.test.tsx

@@ -0,0 +1,109 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi, afterEach } from 'vitest'
+import { render } from '@testing-library/react'
+import { useRef } from 'react'
+import { useFlipAnimation } from '../use-flip-animation'
+
+function List({ order, reduced }: { order: string[]; reduced?: boolean }) {
+  const ref = useRef<HTMLUListElement>(null)
+  useFlipAnimation(ref, order.join(','), { disabled: reduced })
+  return (
+    <ul ref={ref}>
+      {order.map((k) => (
+        <li key={k} data-flip-key={k}>
+          {k}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+// happy-dom has no layout: place each item by its index in the list.
+function fakeLayout() {
+  vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(function (this: HTMLElement) {
+    const parent = this.parentElement
+    const index = parent && this.dataset.flipKey ? Array.from(parent.children).indexOf(this) : 0
+    const top = this.dataset.flipKey ? index * 40 : 0
+    return { top, left: 0, width: 100, height: 40, right: 100, bottom: top + 40, x: 0, y: top, toJSON() {} } as DOMRect
+  })
+}
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  vi.useRealTimers()
+})
+
+describe('useFlipAnimation', () => {
+  it('animates moved items from their old position', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+
+    const view = render(<List order={['a', 'b', 'c']} />)
+    vi.advanceTimersByTime(400) // at-rest snapshot
+    view.rerender(<List order={['c', 'a', 'b']} />)
+
+    const moves = animate.mock.calls.map(([frames]) => (frames as Keyframe[])[0]!.transform)
+    // c: 80 → 0, a: 0 → 40, b: 40 → 80
+    expect(moves).toContain('translate(0px, 80px)')
+    expect(moves).toContain('translate(0px, -40px)')
+    expect(animate).toHaveBeenCalledTimes(3)
+  })
+
+  it('stays still when disabled (reduced motion path)', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+
+    const view = render(<List order={['a', 'b']} reduced />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<List order={['b', 'a']} reduced />)
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('stays still under prefers-reduced-motion', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+    vi.spyOn(window, 'matchMedia').mockImplementation(
+      (query: string) => ({ matches: query.includes('reduce'), media: query }) as MediaQueryList,
+    )
+
+    const view = render(<List order={['a', 'b']} />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<List order={['b', 'a']} />)
+    expect(animate).not.toHaveBeenCalled()
+  })
+
+  it('works with a root resolved from the DOM instead of a wrapper element', () => {
+    vi.useFakeTimers()
+    fakeLayout()
+    const animate = vi.fn()
+    HTMLElement.prototype.animate = animate as never
+    const domRef = {
+      get current() {
+        return document.querySelector<HTMLElement>('[data-slot="list"]')
+      },
+    }
+    function Resolved({ order }: { order: string[] }) {
+      useFlipAnimation(domRef, order.join(','))
+      return (
+        <ul data-slot="list">
+          {order.map((k) => (
+            <li key={k} data-flip-key={k}>
+              {k}
+            </li>
+          ))}
+        </ul>
+      )
+    }
+
+    const view = render(<Resolved order={['a', 'b']} />)
+    vi.advanceTimersByTime(400)
+    view.rerender(<Resolved order={['b', 'a']} />)
+    expect(animate).toHaveBeenCalledTimes(2)
+  })
+})