@hanzogui/animate-presence 2.0.0

package/src/AnimatePresence.tsx

@@ -0,0 +1,219 @@
+import { useInsertionEffect } from 'react'
+import { useConstant } from '@hanzogui/use-constant'
+import { useForceUpdate } from '@hanzogui/use-force-update'
+import type { FunctionComponent, PropsWithChildren, ReactElement, ReactNode } from 'react'
+import { Children, isValidElement, useContext, useMemo, useRef, useState } from 'react'
+import { LayoutGroupContext } from './LayoutGroupContext'
+import { PresenceChild } from './PresenceChild'
+import type { AnimatePresenceProps } from './types'
+
+type ComponentKey = string | number
+
+const getChildKey = (child: ReactElement<any>): ComponentKey => {
+  return (
+    child.key ||
+    (() => {
+      // we can help a bit by falling back to gui name or component name
+      const ct = child.type
+      const defaultName = ct['displayName'] || ct['name'] || ''
+      if (ct && typeof ct === 'object' && 'staticConfig' in ct) {
+        // @ts-expect-error
+        return ct.staticConfig.componentName || defaultName
+      }
+      return defaultName
+    })()
+  )
+}
+
+function onlyElements(children: ReactNode): ReactElement<any>[] {
+  const filtered: ReactElement<any>[] = []
+  // We use forEach here instead of map as map mutates the component key by preprending `.$`
+  Children.forEach(children, (child) => {
+    if (isValidElement(child)) filtered.push(child)
+  })
+  return filtered
+}
+
+export const AnimatePresence: FunctionComponent<
+  PropsWithChildren<AnimatePresenceProps>
+> = ({
+  children,
+  enterVariant,
+  exitVariant,
+  enterExitVariant,
+  initial = true,
+  onExitComplete,
+  exitBeforeEnter,
+  mode,
+  presenceAffectsLayout = true,
+  custom,
+  passThrough,
+}) => {
+  // Determine effective mode: mode prop takes precedence, then exitBeforeEnter for backwards compatibility
+  const effectiveMode = mode ?? (exitBeforeEnter ? 'wait' : 'sync')
+
+  /**
+   * Filter any children that aren't ReactElements. We can only track components
+   * between renders with a props.key.
+   * IMPORTANT: useMemo ensures reference stability for the comparison below
+   */
+  const presentChildren = useMemo(() => onlyElements(children), [children])
+
+  /**
+   * Track the keys of the currently rendered children.
+   */
+  const presentKeys = presentChildren.map(getChildKey)
+
+  /**
+   * If `initial={false}` we only want to pass this to components in the first render.
+   */
+  const isInitialRender = useRef(true)
+
+  /**
+   * Freeze custom prop for exiting children so direction doesn't reverse mid-exit.
+   */
+  const frozenCustomRef = useRef(new Map<ComponentKey, any>())
+
+  /**
+   * A ref containing the currently present children. When all exit animations
+   * are complete, we use this to re-render with the latest children *committed*
+   * rather than the latest children *rendered*.
+   */
+  const pendingPresentChildren = useRef(presentChildren)
+
+  /**
+   * Track which exiting children have finished animating out.
+   */
+  const exitComplete = useConstant(() => new Map<ComponentKey, boolean>())
+
+  /**
+   * Save children to render as React state. To ensure this component is concurrent-safe,
+   * we check for exiting children via an effect.
+   */
+  const [diffedChildren, setDiffedChildren] = useState(presentChildren)
+  const [renderedChildren, setRenderedChildren] = useState(presentChildren)
+
+  /**
+   * If we've been provided a forceRender function by the LayoutGroupContext,
+   * we can use it to force a re-render amongst all surrounding components once
+   * all components have finished animating out.
+   */
+  const forceRender = useContext(LayoutGroupContext).forceRender ?? useForceUpdate()
+
+  if (passThrough) {
+    return <>{children}</>
+  }
+
+  // useInsertionEffect runs before ALL useLayoutEffects (including children's)
+  // this ensures pendingPresentChildren and exitComplete are set before
+  // animation drivers call sendExitComplete() in their layout effects
+  // (critical for immediate completions like animateOnly=[])
+  useInsertionEffect(() => {
+    isInitialRender.current = false
+    pendingPresentChildren.current = presentChildren
+
+    /**
+     * Update complete status of exiting children.
+     */
+    for (let i = 0; i < renderedChildren.length; i++) {
+      const key = getChildKey(renderedChildren[i])
+
+      if (!presentKeys.includes(key)) {
+        if (exitComplete.get(key) !== true) {
+          exitComplete.set(key, false)
+        }
+      } else {
+        exitComplete.delete(key)
+        frozenCustomRef.current.delete(key)
+      }
+    }
+  }, [renderedChildren, presentKeys.length, presentKeys.join('-')])
+
+  if (presentChildren !== diffedChildren) {
+    let nextChildren = [...presentChildren]
+
+    /**
+     * Loop through all the currently rendered components and decide which
+     * are exiting.
+     */
+    for (let i = 0; i < renderedChildren.length; i++) {
+      const child = renderedChildren[i]
+      const key = getChildKey(child)
+
+      if (!presentKeys.includes(key)) {
+        nextChildren.splice(i, 0, child)
+        // freeze custom at the moment of exit so direction doesn't reverse
+        if (!frozenCustomRef.current.has(key)) {
+          frozenCustomRef.current.set(key, custom)
+        }
+      }
+    }
+
+    /**
+     * If we're in "wait" mode, and we have exiting children, we want to
+     * only render these until they've all exited.
+     */
+    const exitingChildren = renderedChildren.filter(
+      (child) => !presentKeys.includes(getChildKey(child))
+    )
+    if (effectiveMode === 'wait' && exitingChildren.length) {
+      nextChildren = exitingChildren
+    }
+
+    setRenderedChildren(onlyElements(nextChildren))
+    setDiffedChildren(presentChildren)
+
+    /**
+     * Early return to ensure once we've set state with the latest diffed
+     * children, we can immediately re-render.
+     */
+    return null
+  }
+
+  return (
+    <>
+      {renderedChildren.map((child) => {
+        const key = getChildKey(child)
+        const isPresent =
+          presentChildren === renderedChildren || presentKeys.includes(key)
+
+        const onExit = () => {
+          if (exitComplete.has(key)) {
+            exitComplete.set(key, true)
+          } else {
+            return
+          }
+
+          let isEveryExitComplete = true
+          exitComplete.forEach((isExitComplete) => {
+            if (!isExitComplete) isEveryExitComplete = false
+          })
+
+          if (isEveryExitComplete) {
+            forceRender?.()
+            setRenderedChildren(pendingPresentChildren.current)
+            onExitComplete?.()
+          }
+        }
+
+        return (
+          <PresenceChild
+            key={key}
+            isPresent={isPresent}
+            initial={!isInitialRender.current || initial ? undefined : false}
+            custom={isPresent ? custom : (frozenCustomRef.current.get(key) ?? custom)}
+            presenceAffectsLayout={presenceAffectsLayout}
+            enterExitVariant={enterExitVariant}
+            enterVariant={enterVariant}
+            exitVariant={exitVariant}
+            onExitComplete={isPresent ? undefined : onExit}
+          >
+            {child}
+          </PresenceChild>
+        )
+      })}
+    </>
+  )
+}
+
+AnimatePresence.displayName = 'AnimatePresence'

package/src/LayoutGroupContext.tsx

@@ -0,0 +1,8 @@
+import React from 'react'
+
+export interface LayoutGroupContextProps {
+  id?: string
+  forceRender?: VoidFunction
+}
+
+export const LayoutGroupContext = React.createContext<LayoutGroupContextProps>({})

package/src/PresenceChild.tsx

@@ -0,0 +1,90 @@
+import { useConstant } from '@hanzogui/use-constant'
+import { PresenceContext } from '@hanzogui/use-presence'
+import type { PresenceContextProps } from '@hanzogui/web'
+import * as React from 'react'
+import { useId } from 'react'
+
+import type { VariantLabels } from './types'
+
+interface PresenceChildProps {
+  children: React.ReactElement<any>
+  isPresent: boolean
+  onExitComplete?: () => void
+  initial?: false | VariantLabels
+  custom?: any
+  presenceAffectsLayout?: boolean
+  exitVariant?: string | null
+  enterVariant?: string | null
+  enterExitVariant?: string | null
+}
+
+// this memo seems to help PopoverContent from continuously re-rendering when open
+export const PresenceChild = React.memo(
+  ({
+    children,
+    initial,
+    isPresent,
+    onExitComplete,
+    exitVariant,
+    enterVariant,
+    enterExitVariant,
+    presenceAffectsLayout,
+    custom,
+  }: PresenceChildProps) => {
+    const presenceChildren = useConstant(newChildrenMap)
+    const id = useId() || ''
+
+    const context = React.useMemo(
+      (): PresenceContextProps => {
+        return {
+          id,
+          initial,
+          isPresent,
+          custom,
+          exitVariant,
+          enterVariant,
+          enterExitVariant,
+          onExitComplete: () => {
+            presenceChildren.set(id, true)
+            for (const isComplete of presenceChildren.values()) {
+              if (!isComplete) {
+                return // can stop searching when any is incomplete
+              }
+            }
+            onExitComplete?.()
+          },
+          register: () => {
+            presenceChildren.set(id, false)
+            return () => presenceChildren.delete(id)
+          },
+        }
+      },
+      /**
+       * If the presence of a child affects the layout of the components around it,
+       * we want to make a new context value to ensure they get re-rendered
+       * so they can detect that layout change.
+       */
+
+      // @ts-expect-error its ok
+      presenceAffectsLayout ? undefined : [isPresent, exitVariant, enterVariant]
+    )
+
+    React.useMemo(() => {
+      presenceChildren.forEach((_, key) => presenceChildren.set(key, false))
+    }, [isPresent])
+
+    /**
+     * If there's no animated components to fire exit animations, we want to remove this
+     * component immediately.
+     */
+    React.useEffect(() => {
+      !isPresent && !presenceChildren.size && onExitComplete?.()
+    }, [isPresent])
+
+    return <PresenceContext.Provider value={context}>{children}</PresenceContext.Provider>
+  }
+)
+
+function newChildrenMap(): Map<string, boolean> {
+  return new Map()
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './AnimatePresence'
+export * from '@hanzogui/use-presence'
+export * from './types'
+export * from './PresenceChild'

package/src/types.ts

@@ -0,0 +1,107 @@
+export interface Axis {
+  min: number
+  max: number
+}
+
+export interface Box {
+  x: Axis
+  y: Axis
+}
+
+export type VariantLabels = string | string[]
+
+/**
+ * @public
+ */
+export interface AnimatePresenceProps {
+  /**
+   * Determines how to handle entering and exiting elements.
+   * - "sync": Default. Elements animate in and out simultaneously.
+   * - "wait": Wait for exit to finish before entering.
+   *
+   * @public
+   */
+  mode?: 'sync' | 'wait'
+
+  /**
+   * By passing `initial={false}`, `AnimatePresence` will disable any initial animations on children
+   * that are present when the component is first rendered.
+   *
+   * ```jsx
+   * <AnimatePresence initial={false}>
+   *   {isVisible && (
+   *     <motion.div
+   *       key="modal"
+   *       initial={{ opacity: 0 }}
+   *       animate={{ opacity: 1 }}
+   *       exit={{ opacity: 0 }}
+   *     />
+   *   )}
+   * </AnimatePresence>
+   * ```
+   *
+   * @public
+   */
+  initial?: boolean
+
+  /**
+   * When a component is removed, there's no longer a chance to update its props directly. So if you need to update
+   * a variant for that component as it renders for the exit animation, set `custom` to an object value that
+   * is applied to the animating childrens props before they render once more to determine their final exit styles.
+   *
+   * The custom value must be JSON.stringify-able!
+   * This lets us memoize it and use it across workers for some animationd drivers.
+   *
+   * ```tsx
+   * <AnimatePresence custom={{ direction: 10 }}>
+   *   {isVisible && <Child />}
+   * </AnimatePresence>
+   *
+   * const Child = styled(View, { variants: { direction: ... } })
+   * ```
+   *
+   * @public
+   */
+  custom?: object
+
+  /**
+   * Fires when all exiting nodes have completed animating out.
+   *
+   * @public
+   */
+  onExitComplete?: () => void
+
+  /**
+   * If set to `true`, `AnimatePresence` will only render one component at a time. The exiting component
+   * will finish its exit animation before the entering component is rendered.
+   *
+   * @deprecated Use `mode="wait"` instead.
+   */
+  exitBeforeEnter?: boolean
+
+  /**
+   * Used in Framer to flag that sibling children *shouldn't* re-render as a result of a
+   * child being removed.
+   *
+   * @internal
+   */
+  presenceAffectsLayout?: boolean
+
+  /**
+   * @deprecated use `custom` passing it an Object instead
+   */
+  exitVariant?: string | null
+
+  /**
+   * @deprecated use `custom` passing it an Object instead
+   */
+  enterVariant?: string | null
+
+  /**
+   * Will use a variant on the child component and apply the true styles for when its entering, false styles for when its exiting
+   * @deprecated use `custom` passing it an Object instead
+   */
+  enterExitVariant?: string | null
+
+  passThrough?: boolean
+}

package/types/AnimatePresence.d.ts

@@ -0,0 +1,4 @@
+import type { FunctionComponent, PropsWithChildren } from 'react';
+import type { AnimatePresenceProps } from './types';
+export declare const AnimatePresence: FunctionComponent<PropsWithChildren<AnimatePresenceProps>>;
+//# sourceMappingURL=AnimatePresence.d.ts.map

package/types/LayoutGroupContext.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+export interface LayoutGroupContextProps {
+    id?: string;
+    forceRender?: VoidFunction;
+}
+export declare const LayoutGroupContext: React.Context<LayoutGroupContextProps>;
+//# sourceMappingURL=LayoutGroupContext.d.ts.map

package/types/PresenceChild.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import type { VariantLabels } from './types';
+interface PresenceChildProps {
+    children: React.ReactElement<any>;
+    isPresent: boolean;
+    onExitComplete?: () => void;
+    initial?: false | VariantLabels;
+    custom?: any;
+    presenceAffectsLayout?: boolean;
+    exitVariant?: string | null;
+    enterVariant?: string | null;
+    enterExitVariant?: string | null;
+}
+export declare const PresenceChild: React.MemoExoticComponent<({ children, initial, isPresent, onExitComplete, exitVariant, enterVariant, enterExitVariant, presenceAffectsLayout, custom, }: PresenceChildProps) => import("react/jsx-runtime").JSX.Element>;
+export {};
+//# sourceMappingURL=PresenceChild.d.ts.map

package/types/index.d.ts

@@ -0,0 +1,5 @@
+export * from './AnimatePresence';
+export * from '@gui/use-presence';
+export * from './types';
+export * from './PresenceChild';
+//# sourceMappingURL=index.d.ts.map

package/types/types.d.ts

@@ -0,0 +1,96 @@
+export interface Axis {
+    min: number;
+    max: number;
+}
+export interface Box {
+    x: Axis;
+    y: Axis;
+}
+export type VariantLabels = string | string[];
+/**
+ * @public
+ */
+export interface AnimatePresenceProps {
+    /**
+     * Determines how to handle entering and exiting elements.
+     * - "sync": Default. Elements animate in and out simultaneously.
+     * - "wait": Wait for exit to finish before entering.
+     *
+     * @public
+     */
+    mode?: 'sync' | 'wait';
+    /**
+     * By passing `initial={false}`, `AnimatePresence` will disable any initial animations on children
+     * that are present when the component is first rendered.
+     *
+     * ```jsx
+     * <AnimatePresence initial={false}>
+     *   {isVisible && (
+     *     <motion.div
+     *       key="modal"
+     *       initial={{ opacity: 0 }}
+     *       animate={{ opacity: 1 }}
+     *       exit={{ opacity: 0 }}
+     *     />
+     *   )}
+     * </AnimatePresence>
+     * ```
+     *
+     * @public
+     */
+    initial?: boolean;
+    /**
+     * When a component is removed, there's no longer a chance to update its props directly. So if you need to update
+     * a variant for that component as it renders for the exit animation, set `custom` to an object value that
+     * is applied to the animating childrens props before they render once more to determine their final exit styles.
+     *
+     * The custom value must be JSON.stringify-able!
+     * This lets us memoize it and use it across workers for some animationd drivers.
+     *
+     * ```tsx
+     * <AnimatePresence custom={{ direction: 10 }}>
+     *   {isVisible && <Child />}
+     * </AnimatePresence>
+     *
+     * const Child = styled(View, { variants: { direction: ... } })
+     * ```
+     *
+     * @public
+     */
+    custom?: object;
+    /**
+     * Fires when all exiting nodes have completed animating out.
+     *
+     * @public
+     */
+    onExitComplete?: () => void;
+    /**
+     * If set to `true`, `AnimatePresence` will only render one component at a time. The exiting component
+     * will finish its exit animation before the entering component is rendered.
+     *
+     * @deprecated Use `mode="wait"` instead.
+     */
+    exitBeforeEnter?: boolean;
+    /**
+     * Used in Framer to flag that sibling children *shouldn't* re-render as a result of a
+     * child being removed.
+     *
+     * @internal
+     */
+    presenceAffectsLayout?: boolean;
+    /**
+     * @deprecated use `custom` passing it an Object instead
+     */
+    exitVariant?: string | null;
+    /**
+     * @deprecated use `custom` passing it an Object instead
+     */
+    enterVariant?: string | null;
+    /**
+     * Will use a variant on the child component and apply the true styles for when its entering, false styles for when its exiting
+     * @deprecated use `custom` passing it an Object instead
+     */
+    enterExitVariant?: string | null;
+    passThrough?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map