@graphprotocol/gds-react 0.2.0 → 0.2.1

package/dist/components/base/Presence.d.ts

@@ -0,0 +1,157 @@
+import { type Key, type ReactNode } from 'react';
+import { type RenderProp } from './Render.tsx';
+type VisibleKey = Key | Key[] | null;
+type GetChildKey = (child: ReactNode, index: number) => Key | undefined;
+/**
+ * - "entering": just added / made visible, transitioning in.
+ * - "visible": present and not transitioning.
+ * - "exiting": just removed / made hidden, transitioning out.
+ * - "hidden": kept mounted but not shown (persistent mode only).
+ */
+type Status = 'entering' | 'visible' | 'exiting' | 'hidden';
+interface Item {
+    key: Key;
+    element: ReactNode;
+    status: Status;
+    /**
+     * The previous status before the most recent change, or `null` if status hasn't just changed.
+     * Cleared after next frame.
+     */
+    previousStatus: Status | null;
+    /** Whether this item was present on mount and hasn't re-entered since. */
+    initial: boolean;
+}
+type PresenceItemState = Omit<Item, 'element'>;
+type PresenceWrapperState = {
+    /** Whether at least one item is currently transitioning (entering or exiting). */
+    transitioning: boolean;
+    /** Whether at least one item is present (entering or visible). */
+    hasPresent: boolean;
+    /** Array of all currently rendered items (entering, visible, exiting, and hidden). */
+    items: Item[];
+};
+interface PresenceContextValue {
+    /** The status of the nearest `Presence` item ancestor. */
+    status: Status;
+    /**
+     * Whether all `Presence` item ancestors are present (entering or visible). If any ancestor is
+     * exiting or hidden, this will be `false`.
+     */
+    present: boolean;
+}
+/**
+ * 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 declare function usePresence(): PresenceContextValue | null;
+interface BasePresenceProps {
+    /**
+     * How long, in milliseconds, children stay in the "entering" status before switching to
+     * "visible".
+     *
+     * @default 0
+     */
+    enterMs?: number | undefined;
+    /**
+     * How long, in milliseconds, children stay in the "exiting" status before being unmounted (or
+     * switching to "hidden", in persistent mode).
+     *
+     * @default 0
+     */
+    exitMs?: number | undefined;
+    /**
+     * Whether children that are present on mount should start in the "entering" status, instead of
+     * "visible".
+     *
+     * @default false
+     */
+    initial?: boolean | undefined;
+    /**
+     * Element or render function for the outer wrapper. By default, renders a fragment (no wrapper).
+     *
+     * Receives state with `transitioning`, `hasPresent`, and `items`.
+     */
+    render?: RenderProp<PresenceWrapperState> | undefined;
+    /**
+     * Element or render function for each child's inner wrapper. By default, renders a `div`.
+     *
+     * Receives props (including `hidden`, `inert`, `data-key`, `data-status`, `data-starting-style`,
+     * and `data-initial`) and state (`key`, `status`, `previousStatus`, and `initial`).
+     */
+    renderChild?: RenderProp<PresenceItemState> | undefined;
+    /**
+     * Function to extract a key from a child node. Keys determine identity: when a child's key
+     * changes, the old one exits and the new one enters (triggering exit/enter transitions). If not
+     * provided, falls back to the child's `key` prop (with React's internal prefixes stripped) or the
+     * index.
+     */
+    getChildKey?: GetChildKey | undefined;
+    /**
+     * Called synchronously during state update, before React commits DOM changes. Exiting elements
+     * are still in their original positions; entering elements don't exist yet (only keys provided).
+     * Useful for measuring layout before transitions begin.
+     *
+     * `previouslyTransitioning` contains items that were already in `entering` or `exiting` status
+     * before this transition started (useful for detecting interrupted transitions).
+     */
+    onBeforeTransitionStart?: ((changes: {
+        entering: Set<Key>;
+        exiting: Map<Key, HTMLElement>;
+        previouslyTransitioning: Map<Key, 'entering' | 'exiting'>;
+    }) => void) | undefined;
+    /**
+     * Called in a layout effect after React commits DOM changes but before browser paint. Both
+     * entering and exiting elements are in the DOM. Useful for triggering CSS transitions.
+     *
+     * `previouslyTransitioning` contains items that were already in `entering` or `exiting` status
+     * before this transition started (useful for detecting interrupted transitions).
+     */
+    onTransitionStart?: ((changes: {
+        entering: Map<Key, HTMLElement>;
+        exiting: Map<Key, HTMLElement>;
+        previouslyTransitioning: Map<Key, 'entering' | 'exiting'>;
+    }) => void) | undefined;
+    /**
+     * Called synchronously during state update, before React commits DOM changes. Both entered and
+     * exited elements are still in the DOM. This is the last chance to access exited elements.
+     */
+    onBeforeTransitionEnd?: ((changes: {
+        entered: Map<Key, HTMLElement>;
+        exited: Map<Key, HTMLElement>;
+    }) => void) | undefined;
+    /**
+     * Called in a layout effect after React commits DOM changes but before browser paint. Entered
+     * elements are still in the DOM; exited elements have been removed (only keys provided).
+     */
+    onTransitionEnd?: ((changes: {
+        entered: Map<Key, HTMLElement>;
+        exited: Set<Key>;
+    }) => void) | undefined;
+    children?: ReactNode;
+}
+/** Unmounting mode: delays unmounting for exit transitions (similar to Motion's `AnimatePresence`). */
+interface UnmountingPresenceProps extends BasePresenceProps {
+    visibleKey?: undefined;
+}
+/** Persistent mode: keeps children mounted, but toggles their visibility with a delay. */
+interface PersistentPresenceProps extends BasePresenceProps {
+    /**
+     * Key(s) of children that should be visible. Accepts:
+     *
+     * - Single key: `"foo"`
+     * - Array of keys: `["foo", "bar"]`
+     * - `null`: no child is visible.
+     */
+    visibleKey?: VisibleKey;
+}
+export type PresenceProps = UnmountingPresenceProps | PersistentPresenceProps;
+/**
+ * Presence.
+ *
+ * - If you pass no `visibleKey` → unmounting mode.
+ * - If you pass `visibleKey` → persistent mode.
+ */
+export declare function Presence({ visibleKey, enterMs, exitMs, initial, render, renderChild, getChildKey, onBeforeTransitionStart, onTransitionStart, onBeforeTransitionEnd, onTransitionEnd, children, }: PresenceProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=Presence.d.ts.map

package/dist/components/base/Presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Presence.d.ts","sourceRoot":"","sources":["../../../src/components/base/Presence.tsx"],"names":[],"mappings":"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"}