@graphprotocol/gds-react 0.2.0 → 0.2.1

package/dist/components/base/Presence.js

@@ -0,0 +1,808 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Children, createContext, isValidElement, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { flushSync } from 'react-dom';
+import { Render } from "./Render.js";
+const PresenceContext = createContext(null);
+/**
+ * Hook to access presence information from the nearest `Presence` item ancestor.
+ *
+ * @returns An object with `status` and `present`, or `null` if not inside a `Presence` component.
+ */
+export function usePresence() {
+    return useContext(PresenceContext);
+}
+/**
+ * Presence.
+ *
+ * - If you pass no `visibleKey` → unmounting mode.
+ * - If you pass `visibleKey` → persistent mode.
+ */
+export function Presence({ visibleKey, enterMs = 0, exitMs = 0, initial = false, render, renderChild = _jsx("div", {}), getChildKey, onBeforeTransitionStart, onTransitionStart, onBeforeTransitionEnd, onTransitionEnd, children, }) {
+    if (visibleKey !== undefined) {
+        return (_jsx(PersistentPresence, { visibleKey: visibleKey, enterMs: enterMs, exitMs: exitMs, initial: initial, render: render, renderChild: renderChild, getChildKey: getChildKey, onBeforeTransitionStart: onBeforeTransitionStart, onTransitionStart: onTransitionStart, onBeforeTransitionEnd: onBeforeTransitionEnd, onTransitionEnd: onTransitionEnd, children: children }));
+    }
+    return (_jsx(UnmountingPresence, { enterMs: enterMs, exitMs: exitMs, initial: initial, render: render, renderChild: renderChild, getChildKey: getChildKey, onBeforeTransitionStart: onBeforeTransitionStart, onTransitionStart: onTransitionStart, onBeforeTransitionEnd: onBeforeTransitionEnd, onTransitionEnd: onTransitionEnd, children: children }));
+}
+/**
+ * UnmountingPresence.
+ *
+ * Mental model:
+ *
+ * - Build a map of all items (previous items + current children).
+ * - Update their statuses ("entering" → "visible" when added, "visible" → "exiting" when unmounted,
+ *   "exiting" → "entering" when re-added).
+ * - Sort: streaming merge that walks through previous items, using survivors as anchors. For each
+ *   survivor, flush all unprocessed current children up to and including it. Exiting items are
+ *   inserted at their previous position.
+ */
+function UnmountingPresence({ enterMs, exitMs, initial, render, renderChild, getChildKey, onBeforeTransitionStart, onTransitionStart, onBeforeTransitionEnd, onTransitionEnd, children, }) {
+    const getChildKeyRef = useRef(getChildKey);
+    getChildKeyRef.current = getChildKey;
+    const { setElementRef, fireBeforeTransitionEnd, fireCallbacks } = usePresenceCallbacks(onBeforeTransitionStart, onTransitionStart, onBeforeTransitionEnd, onTransitionEnd);
+    const [items, setItems] = useState(() => {
+        const { array } = buildChildMap(children, getChildKey);
+        const isEntering = initial && enterMs > 0;
+        return array.map((child, index) => ({
+            key: getStableKey(child, index, getChildKey),
+            element: child,
+            status: isEntering ? 'entering' : 'visible',
+            previousStatus: null,
+            initial: true,
+        }));
+    });
+    const { timeoutsRef, addEntered, addExited, flushCallbackRef } = useTransitionTimeouts();
+    // Memoize to avoid re-running `useLayoutEffect` on every render (all callbacks are stable)
+    const callbacks = useMemo(() => ({ setElementRef, fireBeforeTransitionEnd, fireCallbacks }), 
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- all callbacks are stable (useCallback with [])
+    []);
+    // Set up the flush callback to handle batched transition ends
+    flushCallbackRef.current = (entered, exited) => {
+        callbacks.fireBeforeTransitionEnd(entered, exited);
+        setItems((current) => current
+            .filter((item) => !exited.has(item.key))
+            .map((item) => entered.has(item.key)
+            ? { ...item, status: 'visible', previousStatus: item.status }
+            : item));
+    };
+    useInitialTransitions(initial, enterMs, () => {
+        const keys = new Set();
+        items.forEach((item) => {
+            if (item.status === 'entering' && !timeoutsRef.current.has(item.key)) {
+                keys.add(item.key);
+            }
+        });
+        return keys;
+    }, timeoutsRef, callbacks, (key) => setItems((curr) => curr.map((i) => i.key === key ? { ...i, status: 'visible', previousStatus: i.status } : i)));
+    useLayoutEffect(() => {
+        const { map: presentByKey, keys: childKeys } = buildChildMap(children, getChildKeyRef.current);
+        const nextKeySet = new Set(childKeys);
+        setItems((prevItems) => {
+            const keysToScheduleExitEnd = new Set();
+            const keysToScheduleEnterEnd = new Set();
+            const keysEntering = new Set();
+            const keysExiting = new Set();
+            // Build map of items that are currently transitioning (before this update)
+            const previouslyTransitioning = new Map();
+            const prevByKey = new Map();
+            prevItems.forEach((item) => {
+                prevByKey.set(item.key, item);
+                if (item.status === 'entering' || item.status === 'exiting') {
+                    previouslyTransitioning.set(item.key, item.status);
+                }
+            });
+            const nextItems = [];
+            // Process current children
+            childKeys.forEach((key) => {
+                const prev = prevByKey.get(key);
+                const present = presentByKey.get(key);
+                if (prev?.status === 'exiting') {
+                    // Item coming back from exiting
+                    cancelTimeout(key, timeoutsRef);
+                    const status = enterMs > 0 ? 'entering' : 'visible';
+                    nextItems.push({
+                        key,
+                        element: present.element,
+                        status,
+                        previousStatus: prev.status,
+                        initial: false,
+                    });
+                    keysEntering.add(key);
+                    if (status === 'entering') {
+                        keysToScheduleEnterEnd.add(key);
+                    }
+                }
+                else if (prev) {
+                    // Item already exists, keep its status (but instant-transition "entering" → "visible" if `enterMs` changed to 0)
+                    const status = prev.status === 'entering' && enterMs <= 0 ? 'visible' : prev.status;
+                    const statusChanged = status !== prev.status;
+                    nextItems.push({
+                        key,
+                        element: present.element,
+                        status,
+                        previousStatus: statusChanged ? prev.status : prev.previousStatus,
+                        initial: prev.initial,
+                    });
+                }
+                else {
+                    // New item
+                    const status = enterMs > 0 ? 'entering' : 'visible';
+                    nextItems.push({
+                        key,
+                        element: present.element,
+                        status,
+                        previousStatus: 'hidden',
+                        initial: false,
+                    });
+                    keysEntering.add(key);
+                    if (status === 'entering') {
+                        keysToScheduleEnterEnd.add(key);
+                    }
+                }
+            });
+            // Process items being removed
+            prevItems.forEach((item) => {
+                if (!nextKeySet.has(item.key)) {
+                    const wasAlreadyExiting = item.status === 'exiting';
+                    if (!wasAlreadyExiting) {
+                        cancelTimeout(item.key, timeoutsRef);
+                        keysExiting.add(item.key);
+                        if (exitMs > 0) {
+                            keysToScheduleExitEnd.add(item.key);
+                        }
+                    }
+                    // Keep exiting items if:
+                    // - `exitMs` > 0: allows exit transition
+                    // - already exiting: let it finish (e.g., children changed while item was mid-exit)
+                    if (exitMs > 0 || wasAlreadyExiting) {
+                        nextItems.push({
+                            ...item,
+                            status: 'exiting',
+                            previousStatus: wasAlreadyExiting ? item.previousStatus : item.status,
+                        });
+                    }
+                }
+            });
+            // Fire callbacks (handles both timed and instant transitions)
+            callbacks.fireCallbacks(children, enterMs, exitMs, keysEntering, keysExiting, previouslyTransitioning);
+            // Sort: preserve order by merging current children with previous items
+            const itemsByKey = new Map(nextItems.map((item) => [item.key, item]));
+            const childIndexByKey = new Map(childKeys.map((key, index) => [key, index]));
+            const result = [];
+            const added = new Set();
+            let childIndex = 0;
+            const addChild = (key) => {
+                if (!added.has(key)) {
+                    const item = itemsByKey.get(key);
+                    if (item) {
+                        result.push(item);
+                        added.add(key);
+                    }
+                }
+            };
+            // Walk through previous items, inserting current children at their positions
+            prevItems.forEach((prevItem) => {
+                const item = itemsByKey.get(prevItem.key);
+                if (!item)
+                    return;
+                if (item.status === 'exiting') {
+                    // Exiting items stay at their previous position
+                    result.push(item);
+                    added.add(item.key);
+                }
+                else {
+                    // Current child - add all unprocessed children up to and including it
+                    const indexInChildren = childIndexByKey.get(prevItem.key);
+                    if (indexInChildren !== undefined) {
+                        while (childIndex <= indexInChildren) {
+                            addChild(childKeys[childIndex]);
+                            childIndex++;
+                        }
+                    }
+                }
+            });
+            // Add any remaining new children
+            while (childIndex < childKeys.length) {
+                addChild(childKeys[childIndex]);
+                childIndex++;
+            }
+            // Schedule async transitions (after state update completes)
+            scheduleTransitionTimeouts(enterMs, exitMs, keysToScheduleEnterEnd, keysToScheduleExitEnd, timeoutsRef, addEntered, addExited);
+            return result;
+        });
+    }, [children, enterMs, exitMs, timeoutsRef, addEntered, addExited, callbacks]);
+    // Clear `previousStatus` after the browser has painted the new styles
+    useAfterPaint(items.some((item) => item.previousStatus !== null), () => {
+        flushSync(() => {
+            setItems((current) => current.map((item) => item.previousStatus !== null ? { ...item, previousStatus: null } : item));
+        });
+    });
+    return (_jsx(PresenceWrapper, { render: render, items: items, children: items.map((item) => (_jsx(PresenceItemProvider, { status: item.status, children: _jsx(Render, { ref: (el) => callbacks.setElementRef(item.key, el), render: renderChild, inert: item.status === 'exiting', "data-key": item.key, "data-status": item.status, "data-starting-style": item.previousStatus !== null || undefined, "data-initial": item.initial || undefined, state: {
+                    key: item.key,
+                    status: item.status,
+                    previousStatus: item.previousStatus,
+                    initial: item.initial,
+                }, children: item.element }) }, item.key))) }));
+}
+function normalizeVisibleKey(input) {
+    if (input === null) {
+        return new Set();
+    }
+    if (Array.isArray(input)) {
+        return new Set(input);
+    }
+    // Single key - TypeScript can't narrow the union type here
+    return new Set([input]);
+}
+/**
+ * PersistentPresence.
+ *
+ * - Tracks children by key in a `Map`.
+ * - Items are never unmounted _unless_ you stop rendering them at all.
+ * - When a key enters `visibleKey`:
+ *
+ *   - status goes "hidden" → "entering" for `enterMs`
+ *   - then "visible"
+ * - When a key leaves `visibleKey`:
+ *
+ *   - status goes "visible" → "exiting" for `exitMs`
+ *   - then "hidden" (still mounted, but `hidden` attribute on wrapper)
+ */
+function PersistentPresence({ visibleKey, enterMs, exitMs, initial, render, renderChild, getChildKey, onBeforeTransitionStart, onTransitionStart, onBeforeTransitionEnd, onTransitionEnd, children, }) {
+    const getChildKeyRef = useRef(getChildKey);
+    getChildKeyRef.current = getChildKey;
+    const { setElementRef, fireBeforeTransitionEnd, fireCallbacks } = usePresenceCallbacks(onBeforeTransitionStart, onTransitionStart, onBeforeTransitionEnd, onTransitionEnd);
+    const [itemsMap, setItemsMap] = useState(() => {
+        const { array } = buildChildMap(children, getChildKey);
+        const visibleSet = normalizeVisibleKey(visibleKey);
+        const map = new Map();
+        array.forEach((child, index) => {
+            const key = getStableKey(child, index, getChildKey);
+            const status = getInitialStatus(visibleSet.has(key), initial, enterMs);
+            map.set(key, {
+                key,
+                element: child,
+                status,
+                previousStatus: null,
+                initial: true,
+                order: index,
+            });
+        });
+        return map;
+    });
+    const { timeoutsRef, addEntered, addExited, flushCallbackRef } = useTransitionTimeouts();
+    // Memoize to avoid re-running `useLayoutEffect` on every render (all callbacks are stable)
+    const callbacks = useMemo(() => ({ setElementRef, fireBeforeTransitionEnd, fireCallbacks }), 
+    // oxlint-disable-next-line react-hooks/exhaustive-deps -- all callbacks are stable (useCallback with [])
+    []);
+    // Set up the flush callback to handle batched transition ends
+    flushCallbackRef.current = (entered, exited) => {
+        callbacks.fireBeforeTransitionEnd(entered, exited);
+        setItemsMap((current) => {
+            const copy = new Map(current);
+            exited.forEach((key) => {
+                const item = copy.get(key);
+                if (item)
+                    copy.set(key, { ...item, status: 'hidden', previousStatus: item.status });
+            });
+            entered.forEach((key) => {
+                const item = copy.get(key);
+                if (item)
+                    copy.set(key, { ...item, status: 'visible', previousStatus: item.status });
+            });
+            return copy;
+        });
+    };
+    useInitialTransitions(initial, enterMs, () => {
+        const keys = new Set();
+        itemsMap.forEach((item) => {
+            if (item.status === 'entering' && !timeoutsRef.current.has(item.key)) {
+                keys.add(item.key);
+            }
+        });
+        return keys;
+    }, timeoutsRef, callbacks, (key) => setItemsMap((curr) => {
+        const copy = new Map(curr);
+        const item = copy.get(key);
+        if (item?.status === 'entering') {
+            copy.set(key, { ...item, status: 'visible', previousStatus: item.status });
+        }
+        return copy;
+    }));
+    // Sync items with children and handle visibility transitions
+    useLayoutEffect(() => {
+        const { map: presentByKey } = buildChildMap(children, getChildKeyRef.current);
+        const visibleSet = normalizeVisibleKey(visibleKey);
+        setItemsMap((prevMap) => {
+            const nextMap = new Map(prevMap);
+            const keysToScheduleExitEnd = new Set();
+            const keysToScheduleEnterEnd = new Set();
+            const keysEntering = new Set();
+            const keysExiting = new Set();
+            // Build map of items that are currently transitioning (before this update)
+            const previouslyTransitioning = new Map();
+            prevMap.forEach((item) => {
+                if (item.status === 'entering' || item.status === 'exiting') {
+                    previouslyTransitioning.set(item.key, item.status);
+                }
+            });
+            // 1) Update / add all present keys
+            presentByKey.forEach(({ element, index }, key) => {
+                const existing = nextMap.get(key);
+                if (existing) {
+                    nextMap.set(key, { ...existing, element, order: index });
+                }
+                else {
+                    const isVisible = visibleSet.has(key);
+                    const status = getInitialStatus(isVisible, false, enterMs);
+                    nextMap.set(key, {
+                        key,
+                        element,
+                        status,
+                        previousStatus: null,
+                        initial: false,
+                        order: index,
+                    });
+                    // Track new entering items (for callbacks, even if instant)
+                    if (isVisible) {
+                        keysEntering.add(key);
+                        if (status === 'entering') {
+                            keysToScheduleEnterEnd.add(key);
+                        }
+                    }
+                }
+            });
+            // 2) Remove keys that no longer appear in children
+            nextMap.forEach((_item, key) => {
+                if (!presentByKey.has(key))
+                    nextMap.delete(key);
+            });
+            // 3) Handle visibility transitions for existing items
+            nextMap.forEach((item, key) => {
+                // Skip newly added items (already handled above)
+                if (!prevMap.has(key))
+                    return;
+                const shouldBeVisible = visibleSet.has(key);
+                if (shouldBeVisible) {
+                    if (item.status === 'exiting' || item.status === 'hidden') {
+                        cancelTimeout(key, timeoutsRef);
+                        const status = enterMs > 0 ? 'entering' : 'visible';
+                        nextMap.set(key, { ...item, status, previousStatus: item.status, initial: false });
+                        keysEntering.add(key);
+                        if (status === 'entering') {
+                            keysToScheduleEnterEnd.add(key);
+                        }
+                    }
+                    else if (item.status === 'entering' && enterMs <= 0) {
+                        nextMap.set(key, { ...item, status: 'visible', previousStatus: item.status });
+                    }
+                }
+                else if (item.status === 'visible' || item.status === 'entering') {
+                    cancelTimeout(key, timeoutsRef);
+                    const status = exitMs > 0 ? 'exiting' : 'hidden';
+                    nextMap.set(key, { ...item, status, previousStatus: item.status });
+                    keysExiting.add(key);
+                    if (status === 'exiting') {
+                        keysToScheduleExitEnd.add(key);
+                    }
+                }
+                else if (item.status === 'exiting' && exitMs <= 0) {
+                    nextMap.set(key, { ...item, status: 'hidden', previousStatus: item.status });
+                }
+            });
+            // Fire callbacks (handles both timed and instant transitions)
+            callbacks.fireCallbacks(visibleKey, enterMs, exitMs, keysEntering, keysExiting, previouslyTransitioning);
+            // Schedule async transitions (after state update completes)
+            scheduleTransitionTimeouts(enterMs, exitMs, keysToScheduleEnterEnd, keysToScheduleExitEnd, timeoutsRef, addEntered, addExited);
+            return nextMap;
+        });
+    }, [children, visibleKey, enterMs, exitMs, timeoutsRef, addEntered, addExited, callbacks]);
+    const items = Array.from(itemsMap.values()).sort((a, b) => a.order - b.order);
+    // Clear `previousStatus` after the browser has painted the new styles
+    useAfterPaint(items.some((item) => item.previousStatus !== null), () => {
+        flushSync(() => {
+            setItemsMap((current) => {
+                const copy = new Map(current);
+                copy.forEach((item, key) => {
+                    if (item.previousStatus !== null) {
+                        copy.set(key, { ...item, previousStatus: null });
+                    }
+                });
+                return copy;
+            });
+        });
+    });
+    return (_jsx(PresenceWrapper, { render: render, items: items, children: items.map((item) => (_jsx(PresenceItemProvider, { status: item.status, children: _jsx(Render, { ref: (el) => callbacks.setElementRef(item.key, el), render: renderChild, hidden: item.status === 'hidden', inert: item.status === 'exiting', "data-key": item.key, "data-status": item.status, "data-starting-style": item.previousStatus !== null || undefined, "data-initial": item.initial || undefined, state: {
+                    key: item.key,
+                    status: item.status,
+                    previousStatus: item.previousStatus,
+                    initial: item.initial,
+                }, children: item.element }) }, item.key))) }));
+}
+/* -------------------------------------------------------------------------- */
+/*                       Helper components and utilities                      */
+/* -------------------------------------------------------------------------- */
+/** Renders a wrapper with computed state if the `render` prop is passed. */
+function PresenceWrapper({ render, items, children, }) {
+    if (!render) {
+        return children;
+    }
+    return (_jsx(Render, { render: render, state: {
+            transitioning: items.some((item) => item.status === 'entering' || item.status === 'exiting'),
+            hasPresent: items.some((item) => item.status === 'entering' || item.status === 'visible'),
+            items,
+        }, children: children }));
+}
+/**
+ * Provider component that wraps each `Presence` item to provide presence context to descendants.
+ * Computes `present` by checking if this item and all ancestor items are present.
+ */
+function PresenceItemProvider({ status, children }) {
+    const parentContext = useContext(PresenceContext);
+    // Current item is present if it's entering or visible
+    const isPresent = status === 'entering' || status === 'visible';
+    // Overall present state is true only if this item AND all ancestors are present
+    const present = isPresent && (parentContext?.present ?? true);
+    return _jsx(PresenceContext, { value: { status, present }, children: children });
+}
+/**
+ * Get a stable key for our internal arrays.
+ *
+ * - If a custom `getChildKey` function is provided, use it.
+ * - Otherwise, use the element's `key` prop (with React's internal prefixes stripped).
+ * - Fall back to the index if no key is available.
+ */
+function getStableKey(child, index, getChildKey) {
+    // Use custom key function if provided and if it returns a value for this child
+    if (getChildKey) {
+        const customKey = getChildKey(child, index);
+        if (customKey !== undefined) {
+            return customKey;
+        }
+    }
+    // For valid React elements, use their `key` prop
+    if (isValidElement(child)) {
+        if (child.key !== null) {
+            // Undo prefix added by `Children.toArray` for explicit keys: ".$foo" → "foo"
+            if (typeof child.key === 'string' && child.key.startsWith('.$')) {
+                const slicedKey = child.key.slice(2);
+                if (/^-?\d+(\.\d+)?$/.test(slicedKey)) {
+                    return Number(slicedKey);
+                }
+                return slicedKey;
+            }
+            return child.key;
+        }
+    }
+    // Fallback to index for anything else
+    return index;
+}
+/** Build a map of child keys to their elements and indices. */
+function buildChildMap(children, getChildKey) {
+    const array = Children.toArray(children);
+    const map = new Map();
+    const keys = [];
+    array.forEach((child, index) => {
+        const key = getStableKey(child, index, getChildKey);
+        keys.push(key);
+        map.set(key, { element: child, index });
+    });
+    return { array, map, keys };
+}
+/** Cancel a pending timeout and remove it from the timeouts map. */
+function cancelTimeout(key, timeoutsRef) {
+    const timeoutId = timeoutsRef.current.get(key);
+    if (timeoutId !== undefined) {
+        window.clearTimeout(timeoutId);
+        timeoutsRef.current.delete(key);
+    }
+}
+/**
+ * Hook that runs a callback after the browser has painted. Uses double `requestAnimationFrame`: the
+ * first rAF schedules before the next paint, the second runs after that paint completes.
+ */
+function useAfterPaint(shouldRun, callback) {
+    useLayoutEffect(() => {
+        if (!shouldRun)
+            return;
+        let outerFrameId;
+        let innerFrameId;
+        outerFrameId = requestAnimationFrame(() => {
+            innerFrameId = requestAnimationFrame(() => {
+                callback();
+            });
+        });
+        return () => {
+            cancelAnimationFrame(outerFrameId);
+            cancelAnimationFrame(innerFrameId);
+        };
+    });
+}
+/** Determine initial status for an item based on visibility and transition settings. */
+function getInitialStatus(isVisible, initial, enterMs) {
+    if (!isVisible)
+        return 'hidden';
+    return initial && enterMs > 0 ? 'entering' : 'visible';
+}
+/**
+ * Hook to manage transition timeouts with batching. Each key gets its own timeout (so cancelling
+ * one doesn't affect others), but callbacks are batched together when timeouts fire in the same
+ * event loop tick.
+ */
+function useTransitionTimeouts() {
+    const timeoutsRef = useRef(new Map());
+    const pendingEnteredRef = useRef(new Set());
+    const pendingExitedRef = useRef(new Set());
+    const flushScheduledRef = useRef(false);
+    const flushCallbackRef = useRef(null);
+    useEffect(() => {
+        const timeouts = timeoutsRef.current;
+        return () => {
+            for (const id of timeouts.values()) {
+                window.clearTimeout(id);
+            }
+            timeouts.clear();
+        };
+    }, []);
+    const flush = useCallback(() => {
+        flushScheduledRef.current = false;
+        const pendingEntered = pendingEnteredRef.current;
+        const pendingExited = pendingExitedRef.current;
+        if (pendingEntered.size === 0 && pendingExited.size === 0)
+            return;
+        const entered = new Set(pendingEntered);
+        const exited = new Set(pendingExited);
+        pendingEntered.clear();
+        pendingExited.clear();
+        flushCallbackRef.current?.(entered, exited);
+    }, []);
+    const scheduleFlush = useCallback(() => {
+        if (flushScheduledRef.current)
+            return;
+        flushScheduledRef.current = true;
+        // Use setTimeout(0) instead of queueMicrotask because each setTimeout callback is its own
+        // macrotask. Microtasks run at the end of the CURRENT macrotask, so queueMicrotask would flush
+        // before other setTimeout callbacks with the same delay have a chance to run.
+        window.setTimeout(flush, 0);
+    }, [flush]);
+    const addEntered = useCallback((key) => {
+        timeoutsRef.current.delete(key);
+        pendingEnteredRef.current.add(key);
+        scheduleFlush();
+    }, [scheduleFlush]);
+    const addExited = useCallback((key) => {
+        timeoutsRef.current.delete(key);
+        pendingExitedRef.current.add(key);
+        scheduleFlush();
+    }, [scheduleFlush]);
+    return { timeoutsRef, addEntered, addExited, flushCallbackRef };
+}
+/**
+ * Schedule timeouts for entering/exiting transitions. Each key gets its own timeout to ensure
+ * cancelling one key's transition doesn't affect others. Callbacks are batched when timeouts fire
+ * in the same event loop tick.
+ */
+function scheduleTransitionTimeouts(enterMs, exitMs, keysToScheduleEnterEnd, keysToScheduleExitEnd, timeoutsRef, addEntered, addExited) {
+    if (exitMs > 0) {
+        keysToScheduleExitEnd.forEach((key) => {
+            if (timeoutsRef.current.has(key))
+                return;
+            const timeoutId = window.setTimeout(() => addExited(key), exitMs);
+            timeoutsRef.current.set(key, timeoutId);
+        });
+    }
+    if (enterMs > 0) {
+        keysToScheduleEnterEnd.forEach((key) => {
+            if (timeoutsRef.current.has(key))
+                return;
+            const timeoutId = window.setTimeout(() => addEntered(key), enterMs);
+            timeoutsRef.current.set(key, timeoutId);
+        });
+    }
+}
+/** Hook to handle initial "entering" → "visible" transitions on mount (when `initial={true}`). */
+function useInitialTransitions(initial, enterMs, getEnteringKeys, timeoutsRef, callbacks, updateItemStatus) {
+    const initialCallbacksFiredRef = useRef(false);
+    // Fire `onBeforeTransitionStart` and `onTransitionStart` for initial transitions
+    useLayoutEffect(() => {
+        if (!initial || enterMs <= 0 || initialCallbacksFiredRef.current)
+            return;
+        const enteringKeys = getEnteringKeys();
+        if (enteringKeys.size === 0)
+            return;
+        initialCallbacksFiredRef.current = true;
+        // For initial transitions, elements already exist, so we can fire callbacks directly
+        // Use `enterMs > 0` to ensure `fireCallbacks` treats this as a timed transition
+        // No previously transitioning items on initial mount
+        callbacks.fireCallbacks({}, enterMs, 0, enteringKeys, new Set(), new Map());
+        // oxlint-disable-next-line react-hooks/exhaustive-deps -- only run on mount
+    }, []);
+    // Schedule timeouts for "entering" → "visible" transitions
+    // This must be a separate effect without a guard because React Strict Mode clears timeouts
+    // on cleanup, and they need to be re-scheduled on the second run.
+    useEffect(() => {
+        if (!initial || enterMs <= 0)
+            return;
+        const enteringKeys = getEnteringKeys();
+        if (enteringKeys.size === 0)
+            return;
+        enteringKeys.forEach((key) => {
+            const timeoutId = window.setTimeout(() => {
+                callbacks.fireBeforeTransitionEnd(new Set([key]), new Set());
+                updateItemStatus(key);
+                timeoutsRef.current.delete(key);
+            }, enterMs);
+            timeoutsRef.current.set(key, timeoutId);
+        });
+        // oxlint-disable-next-line react-hooks/exhaustive-deps -- only run on mount
+    }, []);
+}
+function createEmptyPending() {
+    return {
+        transitionStartEntering: new Set(),
+        transitionStartExiting: new Set(),
+        transitionStartPreviously: new Map(),
+        beforeEndEntered: new Set(),
+        transitionEndEntered: new Set(),
+        transitionEndExited: new Set(),
+    };
+}
+/** Hook to manage callback-related refs and helpers for `Presence` components. */
+function usePresenceCallbacks(onBeforeTransitionStart, onTransitionStart, onBeforeTransitionEnd, onTransitionEnd) {
+    // Store callbacks in refs to avoid re-creating `useCallback` functions
+    const callbackRefs = useRef({
+        onBeforeTransitionStart,
+        onTransitionStart,
+        onBeforeTransitionEnd,
+        onTransitionEnd,
+    });
+    callbackRefs.current = {
+        onBeforeTransitionStart,
+        onTransitionStart,
+        onBeforeTransitionEnd,
+        onTransitionEnd,
+    };
+    const elementRefsRef = useRef(new Map());
+    const pendingRef = useRef(createEmptyPending());
+    // Guard to prevent double-firing in React Strict Mode
+    // Initialize with a unique symbol to avoid collision with any valid `children` value (including `null`)
+    const guardRef = useRef(Symbol('unset'));
+    const setElementRef = useCallback((key, element) => {
+        if (element) {
+            elementRefsRef.current.set(key, element);
+        }
+        else {
+            elementRefsRef.current.delete(key);
+        }
+    }, []);
+    /** Resolves keys to elements from refs. */
+    const resolveElements = useCallback((keys) => {
+        const map = new Map();
+        keys.forEach((key) => {
+            const element = elementRefsRef.current.get(key);
+            if (element)
+                map.set(key, element);
+        });
+        return map;
+    }, []);
+    /**
+     * Fires `onBeforeTransitionEnd` callback and tracks keys for `onTransitionEnd`. Called from:
+     *
+     * - Render phase for instant exits (`exitMs <= 0`)
+     * - `useLayoutEffect` for instant enters (`enterMs <= 0`)
+     * - `flushCallbackRef.current` for timed transitions (via `useTransitionTimeouts` batching)
+     */
+    const fireBeforeTransitionEnd = useCallback((entered, exited) => {
+        if (entered.size === 0 && exited.size === 0)
+            return;
+        // Track for the `onTransitionEnd` callback (will fire in `useLayoutEffect`)
+        entered.forEach((key) => pendingRef.current.transitionEndEntered.add(key));
+        exited.forEach((key) => pendingRef.current.transitionEndExited.add(key));
+        // Fire the `onBeforeTransitionEnd` callback synchronously
+        callbackRefs.current.onBeforeTransitionEnd?.({
+            entered: resolveElements(entered),
+            exited: resolveElements(exited),
+        });
+    }, [resolveElements]);
+    /**
+     * Main entry point for firing callbacks during state updates. Handles both timed and instant
+     * transitions:
+     *
+     * - `onBeforeTransitionStart`: Always fires synchronously (entering keys + exiting elements)
+     * - `onTransitionStart` for timed: Tracks for `useLayoutEffect`.
+     * - `onTransitionStart` for instant exits: Fires synchronously (element exists, will be unmounted)
+     * - `onTransitionStart` for instant enters: Tracks for `useLayoutEffect` (element doesn't exist
+     *   yet)
+     * - `onBeforeTransitionEnd` for instant exits: Fires synchronously.
+     * - `onBeforeTransitionEnd` for instant enters: Tracks for `useLayoutEffect`.
+     */
+    const fireCallbacks = useCallback((guardValue, enterMs, exitMs, entering, exiting, previouslyTransitioning) => {
+        // Guard against React Strict Mode double-firing
+        if (guardRef.current === guardValue)
+            return;
+        if (entering.size === 0 && exiting.size === 0)
+            return;
+        guardRef.current = guardValue;
+        const pending = pendingRef.current;
+        const hasInstantExits = exitMs <= 0 && exiting.size > 0;
+        const hasInstantEnters = enterMs <= 0 && entering.size > 0;
+        // 1. Fire `onBeforeTransitionStart` synchronously (always)
+        callbackRefs.current.onBeforeTransitionStart?.({
+            entering,
+            exiting: resolveElements(exiting),
+            previouslyTransitioning,
+        });
+        // 2. Handle `onTransitionStart`
+        // - All enters go to `useLayoutEffect` (element may not exist yet)
+        // - Timed exits go to `useLayoutEffect`
+        // - Instant exits fire synchronously (element exists, will be unmounted)
+        entering.forEach((key) => pending.transitionStartEntering.add(key));
+        if (exitMs > 0) {
+            exiting.forEach((key) => pending.transitionStartExiting.add(key));
+        }
+        previouslyTransitioning.forEach((status, key) => {
+            if (!pending.transitionStartPreviously.has(key)) {
+                pending.transitionStartPreviously.set(key, status);
+            }
+        });
+        if (hasInstantExits) {
+            // Fire `onTransitionStart` synchronously for instant exits only
+            callbackRefs.current.onTransitionStart?.({
+                entering: new Map(),
+                exiting: resolveElements(exiting),
+                previouslyTransitioning,
+            });
+        }
+        // 3. Handle `onBeforeTransitionEnd`
+        // - Instant exits: fire synchronously (element exists)
+        // - Instant enters: track for `useLayoutEffect` (element doesn't exist yet)
+        if (hasInstantExits) {
+            fireBeforeTransitionEnd(new Set(), exiting);
+        }
+        if (hasInstantEnters) {
+            entering.forEach((key) => pending.beforeEndEntered.add(key));
+        }
+    }, [resolveElements, fireBeforeTransitionEnd]);
+    // Fire pending callbacks in `useLayoutEffect` (after DOM commit, before paint)
+    useLayoutEffect(() => {
+        const pending = pendingRef.current;
+        const hasStart = pending.transitionStartEntering.size > 0 || pending.transitionStartExiting.size > 0;
+        const hasBeforeEnd = pending.beforeEndEntered.size > 0;
+        const hasEnd = pending.transitionEndEntered.size > 0 || pending.transitionEndExited.size > 0;
+        if (!hasStart && !hasBeforeEnd && !hasEnd)
+            return;
+        // Capture pending state before resetting
+        const { transitionStartEntering, transitionStartExiting, transitionStartPreviously, beforeEndEntered, transitionEndEntered, transitionEndExited, } = pending;
+        pendingRef.current = createEmptyPending();
+        // Fire `onTransitionStart`
+        if (hasStart) {
+            callbackRefs.current.onTransitionStart?.({
+                entering: resolveElements(transitionStartEntering),
+                exiting: resolveElements(transitionStartExiting),
+                previouslyTransitioning: transitionStartPreviously,
+            });
+        }
+        // Fire `onBeforeTransitionEnd` for instant enters (this also tracks for `onTransitionEnd`)
+        if (hasBeforeEnd) {
+            fireBeforeTransitionEnd(beforeEndEntered, new Set());
+        }
+        // Merge any new entries added by `fireBeforeTransitionEnd` above
+        pendingRef.current.transitionEndEntered.forEach((key) => transitionEndEntered.add(key));
+        pendingRef.current.transitionEndExited.forEach((key) => transitionEndExited.add(key));
+        pendingRef.current.transitionEndEntered = new Set();
+        pendingRef.current.transitionEndExited = new Set();
+        // Fire `onTransitionEnd` (includes keys from both synchronous and `useLayoutEffect` paths)
+        if (transitionEndEntered.size > 0 || transitionEndExited.size > 0) {
+            callbackRefs.current.onTransitionEnd?.({
+                entered: resolveElements(transitionEndEntered),
+                exited: transitionEndExited,
+            });
+        }
+    });
+    return {
+        setElementRef,
+        fireBeforeTransitionEnd,
+        fireCallbacks,
+    };
+}
+//# sourceMappingURL=Presence.js.map