@lynx-js/lynx-ui-presence 3.139.0 → 3.142.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,26 @@
1
1
  # @lynx-js/lynx-ui-presence
2
2
 
3
+ ## 3.142.0
4
+
5
+ ### Minor Changes
6
+
7
+ - Add opt-in motion content with spring and tween transitions, arrow-tip transform ([#384](https://github.com/lynx-family/lynx-ui/pull/384))
8
+ origins, interruption handling, and exit retention.
9
+
10
+ ### Patch Changes
11
+
12
+ - Accept React 18 and newer types. ReactLynx still defines the compatible versions for each app. ([#383](https://github.com/lynx-family/lynx-ui/pull/383))
13
+
14
+ - Updated dependencies [[`49cb3c5`](https://github.com/lynx-family/lynx-ui/commit/49cb3c5b20d9346ff0f8b314367b4c8e354d195d)]:
15
+ - @lynx-js/lynx-ui-common@3.142.0
16
+
17
+ ## 3.140.1
18
+
19
+ ### Patch Changes
20
+
21
+ - Add PascalCase names for public hook types and normalize supporting type names, ([#355](https://github.com/lynx-family/lynx-ui/pull/355))
22
+ retaining deprecated aliases for existing public names.
23
+
3
24
  ## 3.139.0
4
25
 
5
26
  ### Minor Changes
package/README.md CHANGED
@@ -33,6 +33,7 @@ It is not expected to be consumed directly in application code, and its API may
33
33
 
34
34
  ```tsx
35
35
  <Presence>
36
+ {/* Your content */}
36
37
  </Presence>
37
38
  ```
38
39
 
package/dist/index.d.ts CHANGED
@@ -2,5 +2,7 @@ export { Presence, PresenceContext, renderPresenceChildren } from './Presence.js
2
2
  export { PresenceState, resolveAnimationStatus, presenceClassVariants, } from './utils.js';
3
3
  export { usePresenceGroup } from './usePresenceGroup.js';
4
4
  export { useVisibilityFromPresence } from './useVisibilityFromPresence.js';
5
+ export { usePresenceAnimation } from './usePresenceAnimation.js';
6
+ export type { PresenceAnimationDriver } from './usePresenceAnimation.js';
5
7
  export type * from './types/index.js';
6
8
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAE9E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAErD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAEvE,mBAAmB,SAAS,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAE9E,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,qBAAqB,GACtB,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAErD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAA;AAEvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAC7D,YAAY,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAErE,mBAAmB,SAAS,CAAA"}
package/dist/index.jsx CHANGED
@@ -2,3 +2,4 @@ export { Presence, PresenceContext, renderPresenceChildren } from "./Presence.js
2
2
  export { PresenceState, presenceClassVariants, resolveAnimationStatus } from "./utils.jsx";
3
3
  export { usePresenceGroup } from "./usePresenceGroup.jsx";
4
4
  export { useVisibilityFromPresence } from "./useVisibilityFromPresence.jsx";
5
+ export { usePresenceAnimation } from "./usePresenceAnimation.jsx";
@@ -32,7 +32,7 @@ export interface PresenceAnimationStatus {
32
32
  /**
33
33
  * UI variants applied by Presence based on animation status.
34
34
  * Use them as CSS selectors to style different states.
35
- * @zh Presence 根据状态注入的 ui-variants,可用于 CSS selector 按状态定制样式。
35
+ * @zh Presence 根据状态注入的 UI variants,可用于 CSS selector 按状态定制样式。
36
36
  */
37
37
  export interface PresenceUIVariants {
38
38
  /**
@@ -77,7 +77,7 @@ export interface PresenceProps {
77
77
  onOpen?: () => void;
78
78
  debugLog?: boolean;
79
79
  }
80
- export interface usePresenceProps {
80
+ export interface UsePresenceProps {
81
81
  show: boolean;
82
82
  forceMount?: boolean;
83
83
  state: PresenceState;
@@ -102,5 +102,9 @@ export interface PresenceContextType {
102
102
  handleTransitionEnd: EventHandler<TransitionEvent>;
103
103
  };
104
104
  }
105
- export type usePresenceReturnType = PresenceContextType;
105
+ export type UsePresenceReturnType = PresenceContextType;
106
+ /** @deprecated Use `UsePresenceProps` instead. */
107
+ export type usePresenceProps = UsePresenceProps;
108
+ /** @deprecated Use `UsePresenceReturnType` instead. */
109
+ export type usePresenceReturnType = UsePresenceReturnType;
106
110
  //# sourceMappingURL=index.docs.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.docs.d.ts","sourceRoot":"","sources":["../../src/types/index.docs.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE/C,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,eAAe,EAChB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE7C,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IAEd;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IAEnB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IAEvB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAA;IAEtB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,CAAA;AAEnD,MAAM,MAAM,oBAAoB,GAAG,CACjC,MAAM,EAAE,uBAAuB,KAC5B,SAAS,CAAA;AAEd,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,OAAO,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,QAAQ,CAAC,EAAE,SAAS,GAAG,oBAAoB,CAAA;IAC3C,KAAK,CAAC,EAAE,aAAa,CAAA;IACrB,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IACjD,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,OAAO,CAAA;IACb,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,KAAK,EAAE,aAAa,CAAA;IACpB,gBAAgB,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;IAChD,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE;QACX,KAAK,EAAE,aAAa,CAAA;QACpB,KAAK,EAAE,OAAO,CAAA;QACd,gBAAgB,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;KAIjD,CAAA;IACD,iBAAiB,EAAE;QACjB,aAAa,EAAE,YAAY,CAAC,cAAc,CAAC,CAAA;QAC3C,cAAc,EAAE,YAAY,CAAC,cAAc,CAAC,CAAA;QAC5C,sBAAsB,EAAE,YAAY,CAAC,eAAe,CAAC,CAAA;QACrD,WAAW,EAAE,YAAY,CAAC,cAAc,CAAC,CAAA;QACzC,qBAAqB,EAAE,YAAY,CAAC,eAAe,CAAC,CAAA;QACpD,mBAAmB,EAAE,YAAY,CAAC,eAAe,CAAC,CAAA;KACnD,CAAA;CACF;AAED,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAA"}
1
+ {"version":3,"file":"index.docs.d.ts","sourceRoot":"","sources":["../../src/types/index.docs.ts"],"names":[],"mappings":"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"}
@@ -1,6 +1,6 @@
1
- import type { PresenceAnimationStatus, PresenceContextType, PresenceProps, usePresenceProps, usePresenceReturnType } from './types/index.js';
1
+ import type { PresenceAnimationStatus, PresenceContextType, PresenceProps, UsePresenceProps, UsePresenceReturnType } from './types/index.js';
2
2
  export declare const PresenceContext: import("react").Context<PresenceContextType>;
3
- export declare function usePresence(props: usePresenceProps): usePresenceReturnType;
3
+ export declare function usePresence(props: UsePresenceProps): UsePresenceReturnType;
4
4
  export declare const renderPresenceChildren: (props: {
5
5
  children: PresenceProps["children"];
6
6
  status: PresenceAnimationStatus;
@@ -1 +1 @@
1
- {"version":3,"file":"usePresence.jsx","sources":["../src/usePresence.tsx"],"sourcesContent":["// Copyright 2026 The Lynx Authors. All rights reserved.\n// Licensed under the Apache License Version 2.0 that can be found in the\n// LICENSE file in the root directory of this source tree.\n\nimport { createContext, useEffect, useRef, useState } from '@lynx-js/react'\n\nimport { delayFrames, log } from '@lynx-js/lynx-ui-common'\nimport type { AnimationEvent, TransitionEvent } from '@lynx-js/types'\n\nimport type {\n PresenceAnimationStatus,\n PresenceContextType,\n PresenceProps,\n usePresenceProps,\n usePresenceReturnType,\n} from './types'\nimport { PresenceState } from './utils'\n\nexport const PresenceContext = createContext<PresenceContextType>(null!)\n\nexport function usePresence(props: usePresenceProps): usePresenceReturnType {\n const {\n show,\n state,\n enableDelay = false,\n setPresenceState,\n onOpen,\n onClose,\n debugLog = false,\n } = props\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] init, show: ${show}, state: ${state}, enableDelay: ${enableDelay}`,\n )\n const enteringStateWithDelay = enableDelay\n ? PresenceState.DelayedEntering\n : PresenceState.Entering\n\n const isTransitionAnimating = useRef<boolean>(false)\n const isKFAnimating = useRef<boolean>(false)\n // Track the initial render, to prevent effects from running on mount.\n const isInitialRender = useRef(true)\n const hasNotifiedOpen = useRef(false)\n const showRef = useRef(show)\n // The core state to control the mounting and unmounting of the component.\n const [mount, setMount] = useState<boolean>(false)\n // These three id record the loop ID for the entering progress animation and show state to prevent race conditions.\n const enteringLoopIdRef = useRef<number>(0)\n const leavingLoopIdRef = useRef<number>(0)\n const showScheduleIdRef = useRef(0)\n // Two timing windows to wait for the animation to start before forcing a state change.\n const enteringWaitFramesRef = useRef<number>(0)\n const leavingWaitFramesRef = useRef<number>(0)\n\n // The maximum number of frames to wait for an animation to start before forcing a state change.\n const MAX_WAIT_FRAMES = 24\n\n showRef.current = show\n\n const cancelShowTimer = () => {\n showScheduleIdRef.current += 1\n }\n\n const cancelEnteringWait = () => {\n enteringLoopIdRef.current += 1\n }\n\n const cancelLeavingWait = () => {\n leavingLoopIdRef.current += 1\n }\n\n const scheduleShow = () => {\n const scheduleId = showScheduleIdRef.current\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] set mount=true',\n )\n setMount(true)\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] schedule set Entering in 8 frames',\n )\n delayFrames(8, () => {\n if (scheduleId !== showScheduleIdRef.current || !showRef.current) return\n setPresenceState(PresenceState.Entering)\n })\n if (enableDelay) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] schedule set DelayedEntering in 16 frames',\n )\n delayFrames(16, () => {\n if (scheduleId !== showScheduleIdRef.current || !showRef.current) {\n return\n }\n setPresenceState(PresenceState.DelayedEntering)\n })\n }\n }\n\n const restartShow = () => {\n cancelShowTimer()\n scheduleShow()\n }\n\n const notAnimating = () => (isKFAnimating.current === false\n && isTransitionAnimating.current === false)\n\n const handleAnimationStart = () => {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] handleAnimationStart state:${state}, show:${show}, isTransition:${isTransitionAnimating.current}, isKFAnimating:${isKFAnimating.current}`,\n )\n }\n\n const handleAnimationEnd = () => {\n // still need to check if the other kind of animation is running.\n if (\n (state === PresenceState.Entering\n || state === PresenceState.DelayedEntering)\n && notAnimating()\n ) {\n if (showRef.current) {\n setPresenceState(PresenceState.Entered)\n } else {\n // Safeguard: entering animation may still fire after show turns false.\n // Why not Left? Because Left will also cancel the ongoing leaving animation.\n setPresenceState(PresenceState.Leaving)\n }\n }\n if (state === PresenceState.Leaving && notAnimating()) {\n cancelLeavingWait()\n if (showRef.current) {\n restartShow()\n } else {\n setPresenceState(PresenceState.Left)\n }\n }\n }\n\n // ==== Animation events =====\n const handleKFStart = () => {\n isKFAnimating.current = true\n enteringLoopIdRef.current += 1\n leavingLoopIdRef.current += 1\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] KF start, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationStart()\n }\n\n const handleTransitionStart = () => {\n isTransitionAnimating.current = true\n enteringLoopIdRef.current += 1\n leavingLoopIdRef.current += 1\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] Transition start, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationStart()\n }\n\n const handleKFEnd = (_e: AnimationEvent) => {\n isKFAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] KF end, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n const handleKFCancel = () => {\n isKFAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] KF cancel, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n const handleTransitionCancel = () => {\n isTransitionAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] Transition cancel, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n const handleTransitionEnd = (_e: TransitionEvent) => {\n isTransitionAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] Transition end, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n // ==== state controller ====\n const handleStateEntered = () => {\n if (hasNotifiedOpen.current) {\n return\n }\n hasNotifiedOpen.current = true\n onOpen?.()\n }\n\n const handleStateLeft = () => {\n if (showRef.current) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] skip mount=false because show=true (Left)',\n )\n restartShow()\n return\n }\n if (!isInitialRender.current && hasNotifiedOpen.current) {\n hasNotifiedOpen.current = false\n onClose?.()\n }\n log(debugLog, '[lynx-ui-presence][usePresence] set mount=false (Left)')\n setMount(false)\n }\n\n const handleStateLeaving = () => {\n cancelEnteringWait()\n leavingWaitFramesRef.current = 0\n leavingLoopIdRef.current += 1\n const loopId = leavingLoopIdRef.current\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] leaving loop scheduled, loopId: ${loopId}`,\n )\n const tryLeft = () => {\n // The loopId is inconsistent with the current animation state, means the animation started during the delay period, so we should stop this trying.\n if (loopId !== leavingLoopIdRef.current) return\n if (!notAnimating()) return\n // timeout reached => treat as no animation\n if (leavingWaitFramesRef.current >= MAX_WAIT_FRAMES) {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] leaving timeout reached, loopId: ${loopId}, frames: ${leavingWaitFramesRef.current}`,\n )\n if (showRef.current) {\n restartShow()\n } else {\n setPresenceState(PresenceState.Left)\n }\n return\n }\n leavingWaitFramesRef.current += 1\n delayFrames(1, tryLeft)\n }\n\n delayFrames(1, tryLeft)\n }\n\n const handleStateEnteringWithDelay = () => {\n cancelLeavingWait()\n enteringWaitFramesRef.current = 0\n enteringLoopIdRef.current += 1\n const loopId = enteringLoopIdRef.current\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] entering loop scheduled, loopId: ${loopId}`,\n )\n const tryEntered = () => {\n // The loopId is inconsistent with the current animation state, means the animation started during the delay period, so we should stop this trying.\n if (loopId !== enteringLoopIdRef.current) return\n if (!notAnimating()) return\n if (enteringWaitFramesRef.current >= MAX_WAIT_FRAMES) {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] entering timeout reached, loopId: ${loopId}, frames: ${enteringWaitFramesRef.current}`,\n )\n if (showRef.current) {\n setPresenceState(PresenceState.Entered)\n } else {\n setPresenceState(PresenceState.Leaving)\n }\n return\n }\n enteringWaitFramesRef.current += 1\n delayFrames(1, tryEntered)\n }\n\n delayFrames(1, tryEntered)\n }\n\n useEffect(() => {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] state effect, state: ${state}, show: ${show}, enableDelay: ${enableDelay}, isTransitionAnimating: ${isTransitionAnimating.current}, isKFAnimating: ${isKFAnimating.current}`,\n )\n if (state === PresenceState.Entered) {\n handleStateEntered()\n }\n if (state === PresenceState.Left) {\n handleStateLeft()\n }\n if (state === PresenceState.Leaving) {\n handleStateLeaving()\n }\n if (state === enteringStateWithDelay) {\n handleStateEnteringWithDelay()\n }\n }, [state])\n\n // ==== Show change part ====\n const handleDismiss = () => {\n if (\n state === PresenceState.Entered || state === PresenceState.Entering\n || state === PresenceState.DelayedEntering\n ) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] show=false -> set PresenceState.Leaving',\n )\n cancelEnteringWait()\n setPresenceState(PresenceState.Leaving)\n } else if (\n (state === PresenceState.Initial || state === PresenceState.Left) && mount\n ) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] show=false before entering -> set mount=false',\n )\n setMount(false)\n }\n }\n\n useEffect(() => {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] show effect show:${show}, enableDelay:${enableDelay}, state:${state}, mount:${mount}`,\n )\n if (show) {\n restartShow()\n } else {\n cancelShowTimer()\n handleDismiss()\n }\n }, [show, enableDelay])\n\n useEffect(() => {\n isInitialRender.current = false\n }, [])\n\n return {\n controllers: { state, mount, setPresenceState },\n animationHandlers: {\n handleKFStart,\n handleKFCancel,\n handleKFEnd,\n handleTransitionStart,\n handleTransitionCancel,\n handleTransitionEnd,\n },\n }\n}\n\nexport const renderPresenceChildren = (\n props: {\n children: PresenceProps['children']\n status: PresenceAnimationStatus\n },\n) => {\n const { children, status } = props\n return typeof children === 'function'\n ? children(status)\n : children\n}\n"],"names":["PresenceContext","createContext","usePresence","props","show","state","enableDelay","setPresenceState","onOpen","onClose","debugLog","log","enteringStateWithDelay","PresenceState","isTransitionAnimating","useRef","isKFAnimating","isInitialRender","hasNotifiedOpen","showRef","mount","setMount","useState","enteringLoopIdRef","leavingLoopIdRef","showScheduleIdRef","enteringWaitFramesRef","leavingWaitFramesRef","MAX_WAIT_FRAMES","cancelShowTimer","cancelEnteringWait","cancelLeavingWait","scheduleShow","scheduleId","delayFrames","restartShow","notAnimating","handleAnimationStart","handleAnimationEnd","handleKFStart","handleTransitionStart","handleKFEnd","_e","handleKFCancel","handleTransitionCancel","handleTransitionEnd","handleStateEntered","handleStateLeft","handleStateLeaving","loopId","tryLeft","handleStateEnteringWithDelay","tryEntered","useEffect","handleDismiss","renderPresenceChildren","children","status"],"mappings":"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"}
1
+ {"version":3,"file":"usePresence.jsx","sources":["../src/usePresence.tsx"],"sourcesContent":["// Copyright 2026 The Lynx Authors. All rights reserved.\n// Licensed under the Apache License Version 2.0 that can be found in the\n// LICENSE file in the root directory of this source tree.\n\nimport { createContext, useEffect, useRef, useState } from '@lynx-js/react'\n\nimport { delayFrames, log } from '@lynx-js/lynx-ui-common'\nimport type { AnimationEvent, TransitionEvent } from '@lynx-js/types'\n\nimport type {\n PresenceAnimationStatus,\n PresenceContextType,\n PresenceProps,\n UsePresenceProps,\n UsePresenceReturnType,\n} from './types'\nimport { PresenceState } from './utils'\n\nexport const PresenceContext = createContext<PresenceContextType>(null!)\n\nexport function usePresence(props: UsePresenceProps): UsePresenceReturnType {\n const {\n show,\n state,\n enableDelay = false,\n setPresenceState,\n onOpen,\n onClose,\n debugLog = false,\n } = props\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] init, show: ${show}, state: ${state}, enableDelay: ${enableDelay}`,\n )\n const enteringStateWithDelay = enableDelay\n ? PresenceState.DelayedEntering\n : PresenceState.Entering\n\n const isTransitionAnimating = useRef<boolean>(false)\n const isKFAnimating = useRef<boolean>(false)\n // Track the initial render, to prevent effects from running on mount.\n const isInitialRender = useRef(true)\n const hasNotifiedOpen = useRef(false)\n const showRef = useRef(show)\n // The core state to control the mounting and unmounting of the component.\n const [mount, setMount] = useState<boolean>(false)\n // These three id record the loop ID for the entering progress animation and show state to prevent race conditions.\n const enteringLoopIdRef = useRef<number>(0)\n const leavingLoopIdRef = useRef<number>(0)\n const showScheduleIdRef = useRef(0)\n // Two timing windows to wait for the animation to start before forcing a state change.\n const enteringWaitFramesRef = useRef<number>(0)\n const leavingWaitFramesRef = useRef<number>(0)\n\n // The maximum number of frames to wait for an animation to start before forcing a state change.\n const MAX_WAIT_FRAMES = 24\n\n showRef.current = show\n\n const cancelShowTimer = () => {\n showScheduleIdRef.current += 1\n }\n\n const cancelEnteringWait = () => {\n enteringLoopIdRef.current += 1\n }\n\n const cancelLeavingWait = () => {\n leavingLoopIdRef.current += 1\n }\n\n const scheduleShow = () => {\n const scheduleId = showScheduleIdRef.current\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] set mount=true',\n )\n setMount(true)\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] schedule set Entering in 8 frames',\n )\n delayFrames(8, () => {\n if (scheduleId !== showScheduleIdRef.current || !showRef.current) return\n setPresenceState(PresenceState.Entering)\n })\n if (enableDelay) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] schedule set DelayedEntering in 16 frames',\n )\n delayFrames(16, () => {\n if (scheduleId !== showScheduleIdRef.current || !showRef.current) {\n return\n }\n setPresenceState(PresenceState.DelayedEntering)\n })\n }\n }\n\n const restartShow = () => {\n cancelShowTimer()\n scheduleShow()\n }\n\n const notAnimating = () => (isKFAnimating.current === false\n && isTransitionAnimating.current === false)\n\n const handleAnimationStart = () => {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] handleAnimationStart state:${state}, show:${show}, isTransition:${isTransitionAnimating.current}, isKFAnimating:${isKFAnimating.current}`,\n )\n }\n\n const handleAnimationEnd = () => {\n // still need to check if the other kind of animation is running.\n if (\n (state === PresenceState.Entering\n || state === PresenceState.DelayedEntering)\n && notAnimating()\n ) {\n if (showRef.current) {\n setPresenceState(PresenceState.Entered)\n } else {\n // Safeguard: entering animation may still fire after show turns false.\n // Why not Left? Because Left will also cancel the ongoing leaving animation.\n setPresenceState(PresenceState.Leaving)\n }\n }\n if (state === PresenceState.Leaving && notAnimating()) {\n cancelLeavingWait()\n if (showRef.current) {\n restartShow()\n } else {\n setPresenceState(PresenceState.Left)\n }\n }\n }\n\n // ==== Animation events =====\n const handleKFStart = () => {\n isKFAnimating.current = true\n enteringLoopIdRef.current += 1\n leavingLoopIdRef.current += 1\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] KF start, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationStart()\n }\n\n const handleTransitionStart = () => {\n isTransitionAnimating.current = true\n enteringLoopIdRef.current += 1\n leavingLoopIdRef.current += 1\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] Transition start, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationStart()\n }\n\n const handleKFEnd = (_e: AnimationEvent) => {\n isKFAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] KF end, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n const handleKFCancel = () => {\n isKFAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] KF cancel, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n const handleTransitionCancel = () => {\n isTransitionAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] Transition cancel, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n const handleTransitionEnd = (_e: TransitionEvent) => {\n isTransitionAnimating.current = false\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] Transition end, loopId: ${leavingLoopIdRef.current}`,\n )\n handleAnimationEnd()\n }\n\n // ==== state controller ====\n const handleStateEntered = () => {\n if (hasNotifiedOpen.current) {\n return\n }\n hasNotifiedOpen.current = true\n onOpen?.()\n }\n\n const handleStateLeft = () => {\n if (showRef.current) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] skip mount=false because show=true (Left)',\n )\n restartShow()\n return\n }\n if (!isInitialRender.current && hasNotifiedOpen.current) {\n hasNotifiedOpen.current = false\n onClose?.()\n }\n log(debugLog, '[lynx-ui-presence][usePresence] set mount=false (Left)')\n setMount(false)\n }\n\n const handleStateLeaving = () => {\n cancelEnteringWait()\n leavingWaitFramesRef.current = 0\n leavingLoopIdRef.current += 1\n const loopId = leavingLoopIdRef.current\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] leaving loop scheduled, loopId: ${loopId}`,\n )\n const tryLeft = () => {\n // The loopId is inconsistent with the current animation state, means the animation started during the delay period, so we should stop this trying.\n if (loopId !== leavingLoopIdRef.current) return\n if (!notAnimating()) return\n // timeout reached => treat as no animation\n if (leavingWaitFramesRef.current >= MAX_WAIT_FRAMES) {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] leaving timeout reached, loopId: ${loopId}, frames: ${leavingWaitFramesRef.current}`,\n )\n if (showRef.current) {\n restartShow()\n } else {\n setPresenceState(PresenceState.Left)\n }\n return\n }\n leavingWaitFramesRef.current += 1\n delayFrames(1, tryLeft)\n }\n\n delayFrames(1, tryLeft)\n }\n\n const handleStateEnteringWithDelay = () => {\n cancelLeavingWait()\n enteringWaitFramesRef.current = 0\n enteringLoopIdRef.current += 1\n const loopId = enteringLoopIdRef.current\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] entering loop scheduled, loopId: ${loopId}`,\n )\n const tryEntered = () => {\n // The loopId is inconsistent with the current animation state, means the animation started during the delay period, so we should stop this trying.\n if (loopId !== enteringLoopIdRef.current) return\n if (!notAnimating()) return\n if (enteringWaitFramesRef.current >= MAX_WAIT_FRAMES) {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] entering timeout reached, loopId: ${loopId}, frames: ${enteringWaitFramesRef.current}`,\n )\n if (showRef.current) {\n setPresenceState(PresenceState.Entered)\n } else {\n setPresenceState(PresenceState.Leaving)\n }\n return\n }\n enteringWaitFramesRef.current += 1\n delayFrames(1, tryEntered)\n }\n\n delayFrames(1, tryEntered)\n }\n\n useEffect(() => {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] state effect, state: ${state}, show: ${show}, enableDelay: ${enableDelay}, isTransitionAnimating: ${isTransitionAnimating.current}, isKFAnimating: ${isKFAnimating.current}`,\n )\n if (state === PresenceState.Entered) {\n handleStateEntered()\n }\n if (state === PresenceState.Left) {\n handleStateLeft()\n }\n if (state === PresenceState.Leaving) {\n handleStateLeaving()\n }\n if (state === enteringStateWithDelay) {\n handleStateEnteringWithDelay()\n }\n }, [state])\n\n // ==== Show change part ====\n const handleDismiss = () => {\n if (\n state === PresenceState.Entered || state === PresenceState.Entering\n || state === PresenceState.DelayedEntering\n ) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] show=false -> set PresenceState.Leaving',\n )\n cancelEnteringWait()\n setPresenceState(PresenceState.Leaving)\n } else if (\n (state === PresenceState.Initial || state === PresenceState.Left) && mount\n ) {\n log(\n debugLog,\n '[lynx-ui-presence][usePresence] show=false before entering -> set mount=false',\n )\n setMount(false)\n }\n }\n\n useEffect(() => {\n log(\n debugLog,\n `[lynx-ui-presence][usePresence] show effect show:${show}, enableDelay:${enableDelay}, state:${state}, mount:${mount}`,\n )\n if (show) {\n restartShow()\n } else {\n cancelShowTimer()\n handleDismiss()\n }\n }, [show, enableDelay])\n\n useEffect(() => {\n isInitialRender.current = false\n }, [])\n\n return {\n controllers: { state, mount, setPresenceState },\n animationHandlers: {\n handleKFStart,\n handleKFCancel,\n handleKFEnd,\n handleTransitionStart,\n handleTransitionCancel,\n handleTransitionEnd,\n },\n }\n}\n\nexport const renderPresenceChildren = (\n props: {\n children: PresenceProps['children']\n status: PresenceAnimationStatus\n },\n) => {\n const { children, status } = props\n return typeof children === 'function'\n ? children(status)\n : children\n}\n"],"names":["PresenceContext","createContext","usePresence","props","show","state","enableDelay","setPresenceState","onOpen","onClose","debugLog","log","enteringStateWithDelay","PresenceState","isTransitionAnimating","useRef","isKFAnimating","isInitialRender","hasNotifiedOpen","showRef","mount","setMount","useState","enteringLoopIdRef","leavingLoopIdRef","showScheduleIdRef","enteringWaitFramesRef","leavingWaitFramesRef","MAX_WAIT_FRAMES","cancelShowTimer","cancelEnteringWait","cancelLeavingWait","scheduleShow","scheduleId","delayFrames","restartShow","notAnimating","handleAnimationStart","handleAnimationEnd","handleKFStart","handleTransitionStart","handleKFEnd","_e","handleKFCancel","handleTransitionCancel","handleTransitionEnd","handleStateEntered","handleStateLeft","handleStateLeaving","loopId","tryLeft","handleStateEnteringWithDelay","tryEntered","useEffect","handleDismiss","renderPresenceChildren","children","status"],"mappings":"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"}
@@ -0,0 +1,31 @@
1
+ import { PresenceState } from './utils.js';
2
+ /** An animation driver must report completion and return an optional cancellation function. */
3
+ export type PresenceAnimationDriver = (animation: {
4
+ open: boolean;
5
+ immediate?: boolean;
6
+ complete: () => void;
7
+ }) => (() => void) | undefined;
8
+ interface UsePresenceAnimationOptions {
9
+ show: boolean;
10
+ onOpen?: () => void;
11
+ onClose?: () => void;
12
+ enableDelay?: boolean;
13
+ waitForReady?: boolean;
14
+ }
15
+ /**
16
+ * Coordinates Presence with an optional external animation driver. Pass the
17
+ * returned state and handlers to Presence using the same `enableDelay` value.
18
+ * With `waitForReady`, signal `markReady` after the current content is ready;
19
+ * readiness is retained across interrupted exits and reset after a full exit.
20
+ */
21
+ export declare function usePresenceAnimation({ show, onOpen, onClose, enableDelay, waitForReady, }: UsePresenceAnimationOptions): {
22
+ state: PresenceState;
23
+ updatePresence: import("react").Dispatch<import("react").SetStateAction<PresenceState>>;
24
+ registerAnimation: (driver: PresenceAnimationDriver) => () => void;
25
+ markReady: () => void;
26
+ animated: boolean;
27
+ handleOpen: () => void;
28
+ handleClose: () => void;
29
+ };
30
+ export {};
31
+ //# sourceMappingURL=usePresenceAnimation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usePresenceAnimation.d.ts","sourceRoot":"","sources":["../src/usePresenceAnimation.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAEvC,+FAA+F;AAC/F,MAAM,MAAM,uBAAuB,GAAG,CACpC,SAAS,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;CAAE,KACpE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;AAE7B,UAAU,2BAA2B;IACnC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IACnB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,YAAY,CAAC,EAAE,OAAO,CAAA;CACvB;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,IAAI,EACJ,MAAM,EACN,OAAO,EACP,WAAmB,EACnB,YAAoB,GACrB,EAAE,2BAA2B;;;gCA2BmB,uBAAuB;;;;;EAmJvE"}
@@ -0,0 +1,165 @@
1
+ import { useCallback, useEffect, useRef, useState } from "@lynx-js/react";
2
+ import { delayFrames } from "@lynx-js/lynx-ui-common";
3
+ import { PresenceState } from "./utils.jsx";
4
+ function usePresenceAnimation({ show, onOpen, onClose, enableDelay = false, waitForReady = false }) {
5
+ const [state, setPresenceState] = useState(PresenceState.Initial);
6
+ const [animation, setAnimation] = useState(null);
7
+ const [ready, setReady] = useState(!waitForReady);
8
+ const entryState = enableDelay ? PresenceState.DelayedEntering : PresenceState.Entering;
9
+ const registrationRef = useRef(null);
10
+ const lastOpenedRef = useRef(null);
11
+ const mounted = useRef(true);
12
+ const latest = useRef({
13
+ show,
14
+ animation,
15
+ onOpen,
16
+ onClose
17
+ });
18
+ latest.current = {
19
+ show,
20
+ animation,
21
+ onOpen,
22
+ onClose
23
+ };
24
+ const currentState = useRef(state);
25
+ currentState.current = state;
26
+ const didAnimate = useRef(false);
27
+ const pendingOpenCompletion = useRef(false);
28
+ const closeNotified = useRef(false);
29
+ const openNotified = useRef(false);
30
+ useEffect(()=>{
31
+ mounted.current = true;
32
+ return ()=>{
33
+ mounted.current = false;
34
+ registrationRef.current = null;
35
+ };
36
+ }, []);
37
+ const registerAnimation = useCallback((driver)=>{
38
+ const registration = {
39
+ driver
40
+ };
41
+ registrationRef.current = registration;
42
+ setAnimation(registration);
43
+ return ()=>{
44
+ if (registrationRef.current !== registration) return;
45
+ registrationRef.current = null;
46
+ delayFrames(1, ()=>{
47
+ if (!mounted.current || registrationRef.current) return;
48
+ setAnimation((current)=>current === registration ? null : current);
49
+ });
50
+ };
51
+ }, []);
52
+ const markReady = useCallback(()=>{
53
+ if (latest.current.show) setReady(true);
54
+ }, []);
55
+ const updatePresence = useCallback((next)=>{
56
+ if ('function' == typeof next) return void setPresenceState((previous)=>{
57
+ const resolved = next(previous);
58
+ if (latest.current.animation && (resolved === PresenceState.Entered || resolved === PresenceState.Left)) return previous;
59
+ return resolved;
60
+ });
61
+ const resolved = next;
62
+ if (latest.current.animation && (resolved === PresenceState.Entered || resolved === PresenceState.Left)) return;
63
+ setPresenceState(resolved);
64
+ }, []);
65
+ const handleClose = useCallback(()=>{
66
+ if (closeNotified.current) return;
67
+ closeNotified.current = true;
68
+ openNotified.current = false;
69
+ latest.current.onClose?.();
70
+ }, []);
71
+ const handleOpen = useCallback(()=>{
72
+ openNotified.current = true;
73
+ latest.current.onOpen?.();
74
+ }, []);
75
+ const finishOpen = useCallback(()=>{
76
+ if (openNotified.current) latest.current.onOpen?.();
77
+ setPresenceState(PresenceState.Entered);
78
+ }, []);
79
+ useEffect(()=>{
80
+ if (show) closeNotified.current = false;
81
+ }, [
82
+ show
83
+ ]);
84
+ useEffect(()=>{
85
+ if (waitForReady && !show && state === PresenceState.Left) setReady(false);
86
+ }, [
87
+ show,
88
+ state,
89
+ waitForReady
90
+ ]);
91
+ const entering = show && ready && (state === entryState || didAnimate.current && (state === PresenceState.Leaving || state === PresenceState.Entering));
92
+ const leaving = !show && state === PresenceState.Leaving;
93
+ let animationPhase = null;
94
+ if (entering) animationPhase = 'open';
95
+ else if (leaving) animationPhase = 'close';
96
+ else if (show && ready && state === PresenceState.Entered) animationPhase = 'sync';
97
+ useEffect(()=>{
98
+ if (!animation || registrationRef.current !== animation || !animationPhase) return;
99
+ const syncing = 'sync' === animationPhase;
100
+ if (syncing && lastOpenedRef.current === animation) return;
101
+ const opening = 'close' !== animationPhase;
102
+ if (opening) lastOpenedRef.current = animation;
103
+ if (!syncing) didAnimate.current = true;
104
+ pendingOpenCompletion.current = false;
105
+ let active = true;
106
+ const cleanup = animation.driver({
107
+ open: opening,
108
+ ...syncing && {
109
+ immediate: true
110
+ },
111
+ complete: ()=>{
112
+ if (!active || registrationRef.current !== animation || latest.current.show !== opening) return;
113
+ active = false;
114
+ if (syncing) return;
115
+ if (opening && currentState.current !== entryState) pendingOpenCompletion.current = true;
116
+ else if (opening) finishOpen();
117
+ else setPresenceState(PresenceState.Left);
118
+ }
119
+ });
120
+ return ()=>{
121
+ active = false;
122
+ pendingOpenCompletion.current = false;
123
+ cleanup?.();
124
+ };
125
+ }, [
126
+ animationPhase,
127
+ animation,
128
+ entryState,
129
+ finishOpen
130
+ ]);
131
+ useEffect(()=>{
132
+ if (state === entryState && show && pendingOpenCompletion.current) {
133
+ pendingOpenCompletion.current = false;
134
+ finishOpen();
135
+ } else if (state === PresenceState.Left && didAnimate.current) {
136
+ didAnimate.current = false;
137
+ handleClose();
138
+ } else if (!animation && didAnimate.current) {
139
+ if (state === PresenceState.Entered) didAnimate.current = false;
140
+ else if (state === entryState && show) {
141
+ didAnimate.current = false;
142
+ finishOpen();
143
+ } else if (state === PresenceState.Leaving && !show) setPresenceState(PresenceState.Left);
144
+ }
145
+ }, [
146
+ state,
147
+ animation,
148
+ show,
149
+ entryState,
150
+ finishOpen,
151
+ handleClose
152
+ ]);
153
+ return {
154
+ state,
155
+ updatePresence,
156
+ registerAnimation,
157
+ markReady,
158
+ animated: !!animation,
159
+ handleOpen,
160
+ handleClose
161
+ };
162
+ }
163
+ export { usePresenceAnimation };
164
+
165
+ //# sourceMappingURL=usePresenceAnimation.jsx.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usePresenceAnimation.jsx","sources":["../src/usePresenceAnimation.ts"],"sourcesContent":["// Copyright 2026 The Lynx Authors. All rights reserved.\n// Licensed under the Apache License Version 2.0 that can be found in the\n// LICENSE file in the root directory of this source tree.\n\nimport { useCallback, useEffect, useRef, useState } from '@lynx-js/react'\n\nimport { delayFrames } from '@lynx-js/lynx-ui-common'\n\nimport { PresenceState } from './utils'\n\n/** An animation driver must report completion and return an optional cancellation function. */\nexport type PresenceAnimationDriver = (\n animation: { open: boolean, immediate?: boolean, complete: () => void },\n) => (() => void) | undefined\n\ninterface UsePresenceAnimationOptions {\n show: boolean\n onOpen?: () => void\n onClose?: () => void\n enableDelay?: boolean\n waitForReady?: boolean\n}\n\ninterface AnimationRegistration {\n driver: PresenceAnimationDriver\n}\n\n/**\n * Coordinates Presence with an optional external animation driver. Pass the\n * returned state and handlers to Presence using the same `enableDelay` value.\n * With `waitForReady`, signal `markReady` after the current content is ready;\n * readiness is retained across interrupted exits and reset after a full exit.\n */\nexport function usePresenceAnimation({\n show,\n onOpen,\n onClose,\n enableDelay = false,\n waitForReady = false,\n}: UsePresenceAnimationOptions) {\n const [state, setPresenceState] = useState(PresenceState.Initial)\n const [animation, setAnimation] = useState<AnimationRegistration | null>(null)\n const [ready, setReady] = useState(!waitForReady)\n const entryState = enableDelay\n ? PresenceState.DelayedEntering\n : PresenceState.Entering\n const registrationRef = useRef<AnimationRegistration | null>(null)\n const lastOpenedRef = useRef<AnimationRegistration | null>(null)\n const mounted = useRef(true)\n const latest = useRef({ show, animation, onOpen, onClose })\n latest.current = { show, animation, onOpen, onClose }\n const currentState = useRef(state)\n currentState.current = state\n const didAnimate = useRef(false)\n const pendingOpenCompletion = useRef(false)\n const closeNotified = useRef(false)\n const openNotified = useRef(false)\n\n useEffect(() => {\n mounted.current = true\n return () => {\n mounted.current = false\n registrationRef.current = null\n }\n }, [])\n\n const registerAnimation = useCallback((driver: PresenceAnimationDriver) => {\n const registration = { driver }\n registrationRef.current = registration\n setAnimation(registration)\n return () => {\n if (registrationRef.current !== registration) return\n registrationRef.current = null\n // A replacement can register during the same commit. Wait one frame\n // before treating the absence of a driver as permanent removal.\n delayFrames(1, () => {\n if (!mounted.current || registrationRef.current) return\n setAnimation(current => current === registration ? null : current)\n })\n }\n }, [])\n\n const markReady = useCallback(() => {\n if (latest.current.show) setReady(true)\n }, [])\n const updatePresence: typeof setPresenceState = useCallback(next => {\n if (typeof next === 'function') {\n setPresenceState(previous => {\n const resolved = next(previous)\n if (\n latest.current.animation\n && (resolved === PresenceState.Entered\n || resolved === PresenceState.Left)\n ) return previous\n return resolved\n })\n return\n }\n const resolved = next\n // Motion, rather than the CSS fallback timer, completes this lifecycle.\n if (\n latest.current.animation\n && (resolved === PresenceState.Entered || resolved === PresenceState.Left)\n ) return\n setPresenceState(resolved)\n }, [])\n const handleClose = useCallback(() => {\n if (closeNotified.current) return\n closeNotified.current = true\n openNotified.current = false\n latest.current.onClose?.()\n }, [])\n const handleOpen = useCallback(() => {\n openNotified.current = true\n latest.current.onOpen?.()\n }, [])\n const finishOpen = useCallback(() => {\n // Presence treats a reversed exit as part of the previous open cycle.\n if (openNotified.current) latest.current.onOpen?.()\n setPresenceState(PresenceState.Entered)\n }, [])\n\n useEffect(() => {\n if (show) closeNotified.current = false\n }, [show])\n\n useEffect(() => {\n if (waitForReady && !show && state === PresenceState.Left) setReady(false)\n }, [show, state, waitForReady])\n\n const entering = show && ready\n && (state === entryState\n || (didAnimate.current\n && (state === PresenceState.Leaving\n || state === PresenceState.Entering)))\n const leaving = !show && state === PresenceState.Leaving\n let animationPhase: 'open' | 'close' | 'sync' | null = null\n if (entering) animationPhase = 'open'\n else if (leaving) animationPhase = 'close'\n else if (show && ready && state === PresenceState.Entered) {\n animationPhase = 'sync'\n }\n\n useEffect(() => {\n if (\n !animation || registrationRef.current !== animation || !animationPhase\n ) {\n return\n }\n const syncing = animationPhase === 'sync'\n if (syncing && lastOpenedRef.current === animation) return\n const opening = animationPhase !== 'close'\n if (opening) lastOpenedRef.current = animation\n if (!syncing) didAnimate.current = true\n pendingOpenCompletion.current = false\n let active = true\n const cleanup = animation.driver({\n open: opening,\n ...(syncing && { immediate: true }),\n complete: () => {\n if (\n !active || registrationRef.current !== animation\n || latest.current.show !== opening\n ) return\n active = false\n if (syncing) return\n if (opening && currentState.current !== entryState) {\n pendingOpenCompletion.current = true\n } else if (opening) {\n finishOpen()\n } else {\n setPresenceState(PresenceState.Left)\n }\n },\n })\n return () => {\n active = false\n pendingOpenCompletion.current = false\n cleanup?.()\n }\n }, [animationPhase, animation, entryState, finishOpen])\n\n useEffect(() => {\n if (\n state === entryState && show\n && pendingOpenCompletion.current\n ) {\n pendingOpenCompletion.current = false\n finishOpen()\n } else if (state === PresenceState.Left && didAnimate.current) {\n didAnimate.current = false\n handleClose()\n } else if (!animation && didAnimate.current) {\n if (state === PresenceState.Entered) {\n didAnimate.current = false\n } else if (state === entryState && show) {\n didAnimate.current = false\n finishOpen()\n } else if (state === PresenceState.Leaving && !show) {\n setPresenceState(PresenceState.Left)\n }\n }\n }, [state, animation, show, entryState, finishOpen, handleClose])\n\n return {\n state,\n updatePresence,\n registerAnimation,\n markReady,\n animated: !!animation,\n handleOpen,\n handleClose,\n }\n}\n"],"names":["usePresenceAnimation","show","onOpen","onClose","enableDelay","waitForReady","state","setPresenceState","useState","PresenceState","animation","setAnimation","ready","setReady","entryState","registrationRef","useRef","lastOpenedRef","mounted","latest","currentState","didAnimate","pendingOpenCompletion","closeNotified","openNotified","useEffect","registerAnimation","useCallback","driver","registration","delayFrames","current","markReady","updatePresence","next","previous","resolved","handleClose","handleOpen","finishOpen","entering","leaving","animationPhase","syncing","opening","active","cleanup"],"mappings":";;;AAiCO,SAASA,qBAAqB,EACnCC,IAAI,EACJC,MAAM,EACNC,OAAO,EACPC,cAAc,KAAK,EACnBC,eAAe,KAAK,EACQ;IAC5B,MAAM,CAACC,OAAOC,iBAAiB,GAAGC,SAASC,cAAc,OAAO;IAChE,MAAM,CAACC,WAAWC,aAAa,GAAGH,SAAuC;IACzE,MAAM,CAACI,OAAOC,SAAS,GAAGL,SAAS,CAACH;IACpC,MAAMS,aAAaV,cACfK,cAAc,eAAe,GAC7BA,cAAc,QAAQ;IAC1B,MAAMM,kBAAkBC,OAAqC;IAC7D,MAAMC,gBAAgBD,OAAqC;IAC3D,MAAME,UAAUF,OAAO;IACvB,MAAMG,SAASH,OAAO;QAAEf;QAAMS;QAAWR;QAAQC;IAAQ;IACzDgB,OAAO,OAAO,GAAG;QAAElB;QAAMS;QAAWR;QAAQC;IAAQ;IACpD,MAAMiB,eAAeJ,OAAOV;IAC5Bc,aAAa,OAAO,GAAGd;IACvB,MAAMe,aAAaL,OAAO;IAC1B,MAAMM,wBAAwBN,OAAO;IACrC,MAAMO,gBAAgBP,OAAO;IAC7B,MAAMQ,eAAeR,OAAO;IAE5BS,UAAU;QACRP,QAAQ,OAAO,GAAG;QAClB,OAAO;YACLA,QAAQ,OAAO,GAAG;YAClBH,gBAAgB,OAAO,GAAG;QAC5B;IACF,GAAG,EAAE;IAEL,MAAMW,oBAAoBC,YAAY,CAACC;QACrC,MAAMC,eAAe;YAAED;QAAO;QAC9Bb,gBAAgB,OAAO,GAAGc;QAC1BlB,aAAakB;QACb,OAAO;YACL,IAAId,gBAAgB,OAAO,KAAKc,cAAc;YAC9Cd,gBAAgB,OAAO,GAAG;YAG1Be,YAAY,GAAG;gBACb,IAAI,CAACZ,QAAQ,OAAO,IAAIH,gBAAgB,OAAO,EAAE;gBACjDJ,aAAaoB,CAAAA,UAAWA,YAAYF,eAAe,OAAOE;YAC5D;QACF;IACF,GAAG,EAAE;IAEL,MAAMC,YAAYL,YAAY;QAC5B,IAAIR,OAAO,OAAO,CAAC,IAAI,EAAEN,SAAS;IACpC,GAAG,EAAE;IACL,MAAMoB,iBAA0CN,YAAYO,CAAAA;QAC1D,IAAI,AAAgB,cAAhB,OAAOA,MAAqB,YAC9B3B,iBAAiB4B,CAAAA;YACf,MAAMC,WAAWF,KAAKC;YACtB,IACEhB,OAAO,OAAO,CAAC,SAAS,IACpBiB,CAAAA,aAAa3B,cAAc,OAAO,IACjC2B,aAAa3B,cAAc,IAAG,GACnC,OAAO0B;YACT,OAAOC;QACT;QAGF,MAAMA,WAAWF;QAEjB,IACEf,OAAO,OAAO,CAAC,SAAS,IACpBiB,CAAAA,aAAa3B,cAAc,OAAO,IAAI2B,aAAa3B,cAAc,IAAG,GACxE;QACFF,iBAAiB6B;IACnB,GAAG,EAAE;IACL,MAAMC,cAAcV,YAAY;QAC9B,IAAIJ,cAAc,OAAO,EAAE;QAC3BA,cAAc,OAAO,GAAG;QACxBC,aAAa,OAAO,GAAG;QACvBL,OAAO,OAAO,CAAC,OAAO;IACxB,GAAG,EAAE;IACL,MAAMmB,aAAaX,YAAY;QAC7BH,aAAa,OAAO,GAAG;QACvBL,OAAO,OAAO,CAAC,MAAM;IACvB,GAAG,EAAE;IACL,MAAMoB,aAAaZ,YAAY;QAE7B,IAAIH,aAAa,OAAO,EAAEL,OAAO,OAAO,CAAC,MAAM;QAC/CZ,iBAAiBE,cAAc,OAAO;IACxC,GAAG,EAAE;IAELgB,UAAU;QACR,IAAIxB,MAAMsB,cAAc,OAAO,GAAG;IACpC,GAAG;QAACtB;KAAK;IAETwB,UAAU;QACR,IAAIpB,gBAAgB,CAACJ,QAAQK,UAAUG,cAAc,IAAI,EAAEI,SAAS;IACtE,GAAG;QAACZ;QAAMK;QAAOD;KAAa;IAE9B,MAAMmC,WAAWvC,QAAQW,SACnBN,CAAAA,UAAUQ,cACRO,WAAW,OAAO,IAChBf,CAAAA,UAAUG,cAAc,OAAO,IAC9BH,UAAUG,cAAc,QAAO;IAC1C,MAAMgC,UAAU,CAACxC,QAAQK,UAAUG,cAAc,OAAO;IACxD,IAAIiC,iBAAmD;IACvD,IAAIF,UAAUE,iBAAiB;SAC1B,IAAID,SAASC,iBAAiB;SAC9B,IAAIzC,QAAQW,SAASN,UAAUG,cAAc,OAAO,EACvDiC,iBAAiB;IAGnBjB,UAAU;QACR,IACE,CAACf,aAAaK,gBAAgB,OAAO,KAAKL,aAAa,CAACgC,gBAExD;QAEF,MAAMC,UAAUD,AAAmB,WAAnBA;QAChB,IAAIC,WAAW1B,cAAc,OAAO,KAAKP,WAAW;QACpD,MAAMkC,UAAUF,AAAmB,YAAnBA;QAChB,IAAIE,SAAS3B,cAAc,OAAO,GAAGP;QACrC,IAAI,CAACiC,SAAStB,WAAW,OAAO,GAAG;QACnCC,sBAAsB,OAAO,GAAG;QAChC,IAAIuB,SAAS;QACb,MAAMC,UAAUpC,UAAU,MAAM,CAAC;YAC/B,MAAMkC;YACN,GAAID,WAAW;gBAAE,WAAW;YAAK,CAAC;YAClC,UAAU;gBACR,IACE,CAACE,UAAU9B,gBAAgB,OAAO,KAAKL,aACpCS,OAAO,OAAO,CAAC,IAAI,KAAKyB,SAC3B;gBACFC,SAAS;gBACT,IAAIF,SAAS;gBACb,IAAIC,WAAWxB,aAAa,OAAO,KAAKN,YACtCQ,sBAAsB,OAAO,GAAG;qBAC3B,IAAIsB,SACTL;qBAEAhC,iBAAiBE,cAAc,IAAI;YAEvC;QACF;QACA,OAAO;YACLoC,SAAS;YACTvB,sBAAsB,OAAO,GAAG;YAChCwB;QACF;IACF,GAAG;QAACJ;QAAgBhC;QAAWI;QAAYyB;KAAW;IAEtDd,UAAU;QACR,IACEnB,UAAUQ,cAAcb,QACrBqB,sBAAsB,OAAO,EAChC;YACAA,sBAAsB,OAAO,GAAG;YAChCiB;QACF,OAAO,IAAIjC,UAAUG,cAAc,IAAI,IAAIY,WAAW,OAAO,EAAE;YAC7DA,WAAW,OAAO,GAAG;YACrBgB;QACF,OAAO,IAAI,CAAC3B,aAAaW,WAAW,OAAO,EACzC;YAAA,IAAIf,UAAUG,cAAc,OAAO,EACjCY,WAAW,OAAO,GAAG;iBAChB,IAAIf,UAAUQ,cAAcb,MAAM;gBACvCoB,WAAW,OAAO,GAAG;gBACrBkB;YACF,OAAO,IAAIjC,UAAUG,cAAc,OAAO,IAAI,CAACR,MAC7CM,iBAAiBE,cAAc,IAAI;QACrC;IAEJ,GAAG;QAACH;QAAOI;QAAWT;QAAMa;QAAYyB;QAAYF;KAAY;IAEhE,OAAO;QACL/B;QACA2B;QACAP;QACAM;QACA,UAAU,CAAC,CAACtB;QACZ4B;QACAD;IACF;AACF"}
@@ -2,7 +2,7 @@ import type { ReactNode } from '@lynx-js/react';
2
2
  import type { PresenceChildrenType, PresenceContextType } from './types/index.js';
3
3
  import { PresenceState } from './utils.js';
4
4
  export declare const PresenceContext: import("react").Context<PresenceContextType>;
5
- export interface usePresenceGroupProps {
5
+ export interface UsePresenceGroupProps {
6
6
  show: boolean;
7
7
  forceMount: boolean;
8
8
  setGroupState?: (state: PresenceState) => void;
@@ -12,9 +12,9 @@ export interface usePresenceGroupProps {
12
12
  onClose?: () => void;
13
13
  debugLog?: boolean;
14
14
  }
15
- export interface usePresenceGroupReturnType {
15
+ export interface UsePresenceGroupReturnType {
16
16
  renderChildren: ReactNode;
17
17
  mountView: boolean;
18
18
  }
19
- export declare const usePresenceGroup: (props: usePresenceGroupProps) => usePresenceGroupReturnType;
19
+ export declare const usePresenceGroup: (props: UsePresenceGroupProps) => UsePresenceGroupReturnType;
20
20
  //# sourceMappingURL=usePresenceGroup.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"usePresenceGroup.jsx","sources":["../src/usePresenceGroup.tsx"],"sourcesContent":["// Copyright 2026 The Lynx Authors. All rights reserved.\n// Licensed under the Apache License Version 2.0 that can be found in the\n// LICENSE file in the root directory of this source tree.\n\nimport {\n createContext,\n useCallback,\n useEffect,\n useMemo,\n useState,\n} from '@lynx-js/react'\nimport type { ReactNode } from '@lynx-js/react'\n\nimport { Presence } from './Presence'\nimport type { PresenceChildrenType, PresenceContextType } from './types'\nimport { PresenceState } from './utils'\n\nexport const PresenceContext = createContext<PresenceContextType>(null!)\n\nexport interface usePresenceGroupProps {\n show: boolean\n forceMount: boolean\n setGroupState?: (state: PresenceState) => void\n enableDelay?: boolean\n children?:\n | ReactNode\n | PresenceChildrenType\n | Array<ReactNode | PresenceChildrenType>\n onOpen?: () => void\n onClose?: () => void\n debugLog?: boolean\n}\n\nexport interface usePresenceGroupReturnType {\n renderChildren: ReactNode\n mountView: boolean\n}\n// Manage a group of Presence components.\n// Wrap all child nodes with Presence and ensure that the onOpen and onClose events are triggered after all animations are completed.\nexport const usePresenceGroup: (\n props: usePresenceGroupProps,\n) => usePresenceGroupReturnType = (props) => {\n const {\n show,\n forceMount = false,\n children,\n enableDelay = false,\n onOpen,\n onClose,\n setGroupState,\n debugLog,\n } = props\n\n const [_, setMountingChildrenCount] = useState<number>(\n 0,\n )\n const [mountView, setMountView] = useState<boolean>(show)\n\n const childrenSize = Array.isArray(children)\n ? children.length\n : (children ? 1 : 0)\n const [stateGroup, setStateGroup] = useState<PresenceState[]>(\n Array.from({ length: childrenSize }, () => PresenceState.Left),\n )\n\n // Determine the overall state based on the stateGroup\n const getGroupState = (states: PresenceState[]): PresenceState => {\n // The state in Presence will stop the PresenceState from changing to DelayedEntering if the delay is disabled. No need to double check it in upper presence group.\n if (\n states.some(state => state === PresenceState.DelayedEntering)\n ) {\n return PresenceState.DelayedEntering\n }\n if (\n states.some(state => state === PresenceState.Entering)\n ) {\n return PresenceState.Entering\n }\n if (states.some(state => state === PresenceState.Leaving)) {\n return PresenceState.Leaving\n }\n if (states.every(state => state === PresenceState.Entered)) {\n return PresenceState.Entered\n }\n if (states.every(state => state === PresenceState.Left)) {\n return PresenceState.Left\n }\n return PresenceState.Left\n }\n\n const updateStateGroup = (index: number, newState: PresenceState) => {\n setStateGroup(prev => {\n const newStateGroup = [...prev]\n newStateGroup[index] = newState\n if (setGroupState) {\n setGroupState(getGroupState(newStateGroup))\n }\n return newStateGroup\n })\n }\n\n const onChildOpen = useCallback(() => {\n setMountingChildrenCount((prev) => {\n const count = prev + 1\n if (\n children\n && ((Array.isArray(children) && count === children.length)\n || (!Array.isArray(children) && count === 1))\n ) {\n onOpen?.()\n }\n return count\n })\n }, [children, onOpen])\n\n const onChildClose = useCallback(() => {\n setMountingChildrenCount((prev) => {\n const count = prev - 1\n if (count === 0) {\n onClose?.()\n }\n return count\n })\n }, [onClose])\n\n const renderChildren = useMemo(() => {\n return Array.isArray(children)\n ? children.map(\n (child: ReactNode | PresenceChildrenType, index: number) => {\n return (\n <Presence\n key={index}\n show={show}\n forceMount={forceMount}\n state={stateGroup[index]}\n setPresenceState={(state: PresenceState) =>\n updateStateGroup(index, state)}\n enableDelay={enableDelay}\n onOpen={onChildOpen}\n onClose={onChildClose}\n debugLog={debugLog}\n >\n {child}\n </Presence>\n )\n },\n )\n : (children\n ? (\n <Presence\n show={show}\n forceMount={forceMount}\n state={stateGroup[0]}\n setPresenceState={(state: PresenceState) =>\n updateStateGroup(0, state)}\n enableDelay={enableDelay}\n onOpen={onChildOpen}\n onClose={onChildClose}\n debugLog={debugLog}\n >\n {children}\n </Presence>\n )\n : null)\n }, [\n show,\n children,\n stateGroup,\n onChildClose,\n onChildOpen,\n forceMount,\n enableDelay,\n debugLog,\n ])\n\n useEffect(() => {\n if (show) {\n setMountView(true)\n } else if (stateGroup.every(state => state === PresenceState.Left)) {\n setMountView(false)\n }\n }, [show, stateGroup])\n\n return {\n renderChildren,\n mountView,\n }\n}\n"],"names":["PresenceContext","createContext","usePresenceGroup","props","show","forceMount","children","enableDelay","onOpen","onClose","setGroupState","debugLog","_","setMountingChildrenCount","useState","mountView","setMountView","childrenSize","Array","stateGroup","setStateGroup","PresenceState","getGroupState","states","state","updateStateGroup","index","newState","prev","newStateGroup","onChildOpen","useCallback","count","onChildClose","renderChildren","useMemo","child","Presence","useEffect"],"mappings":"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"}
1
+ {"version":3,"file":"usePresenceGroup.jsx","sources":["../src/usePresenceGroup.tsx"],"sourcesContent":["// Copyright 2026 The Lynx Authors. All rights reserved.\n// Licensed under the Apache License Version 2.0 that can be found in the\n// LICENSE file in the root directory of this source tree.\n\nimport {\n createContext,\n useCallback,\n useEffect,\n useMemo,\n useState,\n} from '@lynx-js/react'\nimport type { ReactNode } from '@lynx-js/react'\n\nimport { Presence } from './Presence'\nimport type { PresenceChildrenType, PresenceContextType } from './types'\nimport { PresenceState } from './utils'\n\nexport const PresenceContext = createContext<PresenceContextType>(null!)\n\nexport interface UsePresenceGroupProps {\n show: boolean\n forceMount: boolean\n setGroupState?: (state: PresenceState) => void\n enableDelay?: boolean\n children?:\n | ReactNode\n | PresenceChildrenType\n | Array<ReactNode | PresenceChildrenType>\n onOpen?: () => void\n onClose?: () => void\n debugLog?: boolean\n}\n\nexport interface UsePresenceGroupReturnType {\n renderChildren: ReactNode\n mountView: boolean\n}\n// Manage a group of Presence components.\n// Wrap all child nodes with Presence and ensure that the onOpen and onClose events are triggered after all animations are completed.\nexport const usePresenceGroup: (\n props: UsePresenceGroupProps,\n) => UsePresenceGroupReturnType = (props) => {\n const {\n show,\n forceMount = false,\n children,\n enableDelay = false,\n onOpen,\n onClose,\n setGroupState,\n debugLog,\n } = props\n\n const [_, setMountingChildrenCount] = useState<number>(\n 0,\n )\n const [mountView, setMountView] = useState<boolean>(show)\n\n const childrenSize = Array.isArray(children)\n ? children.length\n : (children ? 1 : 0)\n const [stateGroup, setStateGroup] = useState<PresenceState[]>(\n Array.from({ length: childrenSize }, () => PresenceState.Left),\n )\n\n // Determine the overall state based on the stateGroup\n const getGroupState = (states: PresenceState[]): PresenceState => {\n // The state in Presence will stop the PresenceState from changing to DelayedEntering if the delay is disabled. No need to double check it in upper presence group.\n if (\n states.some(state => state === PresenceState.DelayedEntering)\n ) {\n return PresenceState.DelayedEntering\n }\n if (\n states.some(state => state === PresenceState.Entering)\n ) {\n return PresenceState.Entering\n }\n if (states.some(state => state === PresenceState.Leaving)) {\n return PresenceState.Leaving\n }\n if (states.every(state => state === PresenceState.Entered)) {\n return PresenceState.Entered\n }\n if (states.every(state => state === PresenceState.Left)) {\n return PresenceState.Left\n }\n return PresenceState.Left\n }\n\n const updateStateGroup = (index: number, newState: PresenceState) => {\n setStateGroup(prev => {\n const newStateGroup = [...prev]\n newStateGroup[index] = newState\n if (setGroupState) {\n setGroupState(getGroupState(newStateGroup))\n }\n return newStateGroup\n })\n }\n\n const onChildOpen = useCallback(() => {\n setMountingChildrenCount((prev) => {\n const count = prev + 1\n if (\n children\n && ((Array.isArray(children) && count === children.length)\n || (!Array.isArray(children) && count === 1))\n ) {\n onOpen?.()\n }\n return count\n })\n }, [children, onOpen])\n\n const onChildClose = useCallback(() => {\n setMountingChildrenCount((prev) => {\n const count = prev - 1\n if (count === 0) {\n onClose?.()\n }\n return count\n })\n }, [onClose])\n\n const renderChildren = useMemo(() => {\n return Array.isArray(children)\n ? children.map(\n (child: ReactNode | PresenceChildrenType, index: number) => {\n return (\n <Presence\n key={index}\n show={show}\n forceMount={forceMount}\n state={stateGroup[index]}\n setPresenceState={(state: PresenceState) =>\n updateStateGroup(index, state)}\n enableDelay={enableDelay}\n onOpen={onChildOpen}\n onClose={onChildClose}\n debugLog={debugLog}\n >\n {child}\n </Presence>\n )\n },\n )\n : (children\n ? (\n <Presence\n show={show}\n forceMount={forceMount}\n state={stateGroup[0]}\n setPresenceState={(state: PresenceState) =>\n updateStateGroup(0, state)}\n enableDelay={enableDelay}\n onOpen={onChildOpen}\n onClose={onChildClose}\n debugLog={debugLog}\n >\n {children}\n </Presence>\n )\n : null)\n }, [\n show,\n children,\n stateGroup,\n onChildClose,\n onChildOpen,\n forceMount,\n enableDelay,\n debugLog,\n ])\n\n useEffect(() => {\n if (show) {\n setMountView(true)\n } else if (stateGroup.every(state => state === PresenceState.Left)) {\n setMountView(false)\n }\n }, [show, stateGroup])\n\n return {\n renderChildren,\n mountView,\n }\n}\n"],"names":["PresenceContext","createContext","usePresenceGroup","props","show","forceMount","children","enableDelay","onOpen","onClose","setGroupState","debugLog","_","setMountingChildrenCount","useState","mountView","setMountView","childrenSize","Array","stateGroup","setStateGroup","PresenceState","getGroupState","states","state","updateStateGroup","index","newState","prev","newStateGroup","onChildOpen","useCallback","count","onChildClose","renderChildren","useMemo","child","Presence","useEffect"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lynx-js/lynx-ui-presence",
3
- "version": "3.139.0",
3
+ "version": "3.142.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/lynx-family/lynx-ui.git",
@@ -25,7 +25,7 @@
25
25
  ],
26
26
  "dependencies": {
27
27
  "clsx": "^2.1.1",
28
- "@lynx-js/lynx-ui-common": "3.139.0"
28
+ "@lynx-js/lynx-ui-common": "3.142.0"
29
29
  },
30
30
  "devDependencies": {
31
31
  "@lynx-js/react": "0.123.1",
@@ -37,7 +37,7 @@
37
37
  "peerDependencies": {
38
38
  "@lynx-js/react": ">=0.100.0",
39
39
  "@lynx-js/types": "*",
40
- "@types/react": "^18"
40
+ "@types/react": ">=18"
41
41
  },
42
42
  "publishConfig": {
43
43
  "access": "public"
package/src/index.tsx CHANGED
@@ -14,4 +14,7 @@ export { usePresenceGroup } from './usePresenceGroup'
14
14
 
15
15
  export { useVisibilityFromPresence } from './useVisibilityFromPresence'
16
16
 
17
+ export { usePresenceAnimation } from './usePresenceAnimation'
18
+ export type { PresenceAnimationDriver } from './usePresenceAnimation'
19
+
17
20
  export type * from './types'
@@ -48,7 +48,7 @@ export interface PresenceAnimationStatus {
48
48
  /**
49
49
  * UI variants applied by Presence based on animation status.
50
50
  * Use them as CSS selectors to style different states.
51
- * @zh Presence 根据状态注入的 ui-variants,可用于 CSS selector 按状态定制样式。
51
+ * @zh Presence 根据状态注入的 UI variants,可用于 CSS selector 按状态定制样式。
52
52
  */
53
53
  export interface PresenceUIVariants {
54
54
  /**
@@ -104,7 +104,7 @@ export interface PresenceProps {
104
104
  debugLog?: boolean
105
105
  }
106
106
 
107
- export interface usePresenceProps {
107
+ export interface UsePresenceProps {
108
108
  show: boolean // The one and only entry for showing the presence content.
109
109
  forceMount?: boolean // Force to mount the presence container event the content is not shown.
110
110
  state: PresenceState // The core animation state of Presence.
@@ -135,4 +135,12 @@ export interface PresenceContextType {
135
135
  }
136
136
  }
137
137
 
138
- export type usePresenceReturnType = PresenceContextType
138
+ export type UsePresenceReturnType = PresenceContextType
139
+
140
+ /** @deprecated Use `UsePresenceProps` instead. */
141
+ // eslint-disable-next-line @typescript-eslint/naming-convention -- Preserve the deprecated public alias for compatibility.
142
+ export type usePresenceProps = UsePresenceProps
143
+
144
+ /** @deprecated Use `UsePresenceReturnType` instead. */
145
+ // eslint-disable-next-line @typescript-eslint/naming-convention -- Preserve the deprecated public alias for compatibility.
146
+ export type usePresenceReturnType = UsePresenceReturnType
@@ -11,14 +11,14 @@ import type {
11
11
  PresenceAnimationStatus,
12
12
  PresenceContextType,
13
13
  PresenceProps,
14
- usePresenceProps,
15
- usePresenceReturnType,
14
+ UsePresenceProps,
15
+ UsePresenceReturnType,
16
16
  } from './types'
17
17
  import { PresenceState } from './utils'
18
18
 
19
19
  export const PresenceContext = createContext<PresenceContextType>(null!)
20
20
 
21
- export function usePresence(props: usePresenceProps): usePresenceReturnType {
21
+ export function usePresence(props: UsePresenceProps): UsePresenceReturnType {
22
22
  const {
23
23
  show,
24
24
  state,
@@ -0,0 +1,214 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ import { useCallback, useEffect, useRef, useState } from '@lynx-js/react'
6
+
7
+ import { delayFrames } from '@lynx-js/lynx-ui-common'
8
+
9
+ import { PresenceState } from './utils'
10
+
11
+ /** An animation driver must report completion and return an optional cancellation function. */
12
+ export type PresenceAnimationDriver = (
13
+ animation: { open: boolean, immediate?: boolean, complete: () => void },
14
+ ) => (() => void) | undefined
15
+
16
+ interface UsePresenceAnimationOptions {
17
+ show: boolean
18
+ onOpen?: () => void
19
+ onClose?: () => void
20
+ enableDelay?: boolean
21
+ waitForReady?: boolean
22
+ }
23
+
24
+ interface AnimationRegistration {
25
+ driver: PresenceAnimationDriver
26
+ }
27
+
28
+ /**
29
+ * Coordinates Presence with an optional external animation driver. Pass the
30
+ * returned state and handlers to Presence using the same `enableDelay` value.
31
+ * With `waitForReady`, signal `markReady` after the current content is ready;
32
+ * readiness is retained across interrupted exits and reset after a full exit.
33
+ */
34
+ export function usePresenceAnimation({
35
+ show,
36
+ onOpen,
37
+ onClose,
38
+ enableDelay = false,
39
+ waitForReady = false,
40
+ }: UsePresenceAnimationOptions) {
41
+ const [state, setPresenceState] = useState(PresenceState.Initial)
42
+ const [animation, setAnimation] = useState<AnimationRegistration | null>(null)
43
+ const [ready, setReady] = useState(!waitForReady)
44
+ const entryState = enableDelay
45
+ ? PresenceState.DelayedEntering
46
+ : PresenceState.Entering
47
+ const registrationRef = useRef<AnimationRegistration | null>(null)
48
+ const lastOpenedRef = useRef<AnimationRegistration | null>(null)
49
+ const mounted = useRef(true)
50
+ const latest = useRef({ show, animation, onOpen, onClose })
51
+ latest.current = { show, animation, onOpen, onClose }
52
+ const currentState = useRef(state)
53
+ currentState.current = state
54
+ const didAnimate = useRef(false)
55
+ const pendingOpenCompletion = useRef(false)
56
+ const closeNotified = useRef(false)
57
+ const openNotified = useRef(false)
58
+
59
+ useEffect(() => {
60
+ mounted.current = true
61
+ return () => {
62
+ mounted.current = false
63
+ registrationRef.current = null
64
+ }
65
+ }, [])
66
+
67
+ const registerAnimation = useCallback((driver: PresenceAnimationDriver) => {
68
+ const registration = { driver }
69
+ registrationRef.current = registration
70
+ setAnimation(registration)
71
+ return () => {
72
+ if (registrationRef.current !== registration) return
73
+ registrationRef.current = null
74
+ // A replacement can register during the same commit. Wait one frame
75
+ // before treating the absence of a driver as permanent removal.
76
+ delayFrames(1, () => {
77
+ if (!mounted.current || registrationRef.current) return
78
+ setAnimation(current => current === registration ? null : current)
79
+ })
80
+ }
81
+ }, [])
82
+
83
+ const markReady = useCallback(() => {
84
+ if (latest.current.show) setReady(true)
85
+ }, [])
86
+ const updatePresence: typeof setPresenceState = useCallback(next => {
87
+ if (typeof next === 'function') {
88
+ setPresenceState(previous => {
89
+ const resolved = next(previous)
90
+ if (
91
+ latest.current.animation
92
+ && (resolved === PresenceState.Entered
93
+ || resolved === PresenceState.Left)
94
+ ) return previous
95
+ return resolved
96
+ })
97
+ return
98
+ }
99
+ const resolved = next
100
+ // Motion, rather than the CSS fallback timer, completes this lifecycle.
101
+ if (
102
+ latest.current.animation
103
+ && (resolved === PresenceState.Entered || resolved === PresenceState.Left)
104
+ ) return
105
+ setPresenceState(resolved)
106
+ }, [])
107
+ const handleClose = useCallback(() => {
108
+ if (closeNotified.current) return
109
+ closeNotified.current = true
110
+ openNotified.current = false
111
+ latest.current.onClose?.()
112
+ }, [])
113
+ const handleOpen = useCallback(() => {
114
+ openNotified.current = true
115
+ latest.current.onOpen?.()
116
+ }, [])
117
+ const finishOpen = useCallback(() => {
118
+ // Presence treats a reversed exit as part of the previous open cycle.
119
+ if (openNotified.current) latest.current.onOpen?.()
120
+ setPresenceState(PresenceState.Entered)
121
+ }, [])
122
+
123
+ useEffect(() => {
124
+ if (show) closeNotified.current = false
125
+ }, [show])
126
+
127
+ useEffect(() => {
128
+ if (waitForReady && !show && state === PresenceState.Left) setReady(false)
129
+ }, [show, state, waitForReady])
130
+
131
+ const entering = show && ready
132
+ && (state === entryState
133
+ || (didAnimate.current
134
+ && (state === PresenceState.Leaving
135
+ || state === PresenceState.Entering)))
136
+ const leaving = !show && state === PresenceState.Leaving
137
+ let animationPhase: 'open' | 'close' | 'sync' | null = null
138
+ if (entering) animationPhase = 'open'
139
+ else if (leaving) animationPhase = 'close'
140
+ else if (show && ready && state === PresenceState.Entered) {
141
+ animationPhase = 'sync'
142
+ }
143
+
144
+ useEffect(() => {
145
+ if (
146
+ !animation || registrationRef.current !== animation || !animationPhase
147
+ ) {
148
+ return
149
+ }
150
+ const syncing = animationPhase === 'sync'
151
+ if (syncing && lastOpenedRef.current === animation) return
152
+ const opening = animationPhase !== 'close'
153
+ if (opening) lastOpenedRef.current = animation
154
+ if (!syncing) didAnimate.current = true
155
+ pendingOpenCompletion.current = false
156
+ let active = true
157
+ const cleanup = animation.driver({
158
+ open: opening,
159
+ ...(syncing && { immediate: true }),
160
+ complete: () => {
161
+ if (
162
+ !active || registrationRef.current !== animation
163
+ || latest.current.show !== opening
164
+ ) return
165
+ active = false
166
+ if (syncing) return
167
+ if (opening && currentState.current !== entryState) {
168
+ pendingOpenCompletion.current = true
169
+ } else if (opening) {
170
+ finishOpen()
171
+ } else {
172
+ setPresenceState(PresenceState.Left)
173
+ }
174
+ },
175
+ })
176
+ return () => {
177
+ active = false
178
+ pendingOpenCompletion.current = false
179
+ cleanup?.()
180
+ }
181
+ }, [animationPhase, animation, entryState, finishOpen])
182
+
183
+ useEffect(() => {
184
+ if (
185
+ state === entryState && show
186
+ && pendingOpenCompletion.current
187
+ ) {
188
+ pendingOpenCompletion.current = false
189
+ finishOpen()
190
+ } else if (state === PresenceState.Left && didAnimate.current) {
191
+ didAnimate.current = false
192
+ handleClose()
193
+ } else if (!animation && didAnimate.current) {
194
+ if (state === PresenceState.Entered) {
195
+ didAnimate.current = false
196
+ } else if (state === entryState && show) {
197
+ didAnimate.current = false
198
+ finishOpen()
199
+ } else if (state === PresenceState.Leaving && !show) {
200
+ setPresenceState(PresenceState.Left)
201
+ }
202
+ }
203
+ }, [state, animation, show, entryState, finishOpen, handleClose])
204
+
205
+ return {
206
+ state,
207
+ updatePresence,
208
+ registerAnimation,
209
+ markReady,
210
+ animated: !!animation,
211
+ handleOpen,
212
+ handleClose,
213
+ }
214
+ }
@@ -17,7 +17,7 @@ import { PresenceState } from './utils'
17
17
 
18
18
  export const PresenceContext = createContext<PresenceContextType>(null!)
19
19
 
20
- export interface usePresenceGroupProps {
20
+ export interface UsePresenceGroupProps {
21
21
  show: boolean
22
22
  forceMount: boolean
23
23
  setGroupState?: (state: PresenceState) => void
@@ -31,15 +31,15 @@ export interface usePresenceGroupProps {
31
31
  debugLog?: boolean
32
32
  }
33
33
 
34
- export interface usePresenceGroupReturnType {
34
+ export interface UsePresenceGroupReturnType {
35
35
  renderChildren: ReactNode
36
36
  mountView: boolean
37
37
  }
38
38
  // Manage a group of Presence components.
39
39
  // Wrap all child nodes with Presence and ensure that the onOpen and onClose events are triggered after all animations are completed.
40
40
  export const usePresenceGroup: (
41
- props: usePresenceGroupProps,
42
- ) => usePresenceGroupReturnType = (props) => {
41
+ props: UsePresenceGroupProps,
42
+ ) => UsePresenceGroupReturnType = (props) => {
43
43
  const {
44
44
  show,
45
45
  forceMount = false,