@lynx-js/lynx-ui-presence 3.140.1 → 3.143.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,27 @@
1
1
  # @lynx-js/lynx-ui-presence
2
2
 
3
+ ## 3.143.0
4
+
5
+ ### Patch Changes
6
+
7
+ - Include missing README/CHANGELOG/SKILL/LICENSE files in published tarballs and exclude test and workspace-only config files. ([#404](https://github.com/lynx-family/lynx-ui/pull/404))
8
+ - Updated dependencies [[`29beec7`](https://github.com/lynx-family/lynx-ui/commit/29beec7b241026010b83c417f7e1d1c961cd4f09)]:
9
+ - @lynx-js/lynx-ui-common@3.143.0
10
+
11
+ ## 3.142.0
12
+
13
+ ### Minor Changes
14
+
15
+ - Add opt-in motion content with spring and tween transitions, arrow-tip transform ([#384](https://github.com/lynx-family/lynx-ui/pull/384))
16
+ origins, interruption handling, and exit retention.
17
+
18
+ ### Patch Changes
19
+
20
+ - 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))
21
+
22
+ - Updated dependencies [[`49cb3c5`](https://github.com/lynx-family/lynx-ui/commit/49cb3c5b20d9346ff0f8b314367b4c8e354d195d)]:
23
+ - @lynx-js/lynx-ui-common@3.142.0
24
+
3
25
  ## 3.140.1
4
26
 
5
27
  ### Patch 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";
@@ -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;AAEvD,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GAAG,gBAAgB,CAAA;AAE/C,uDAAuD;AACvD,MAAM,MAAM,qBAAqB,GAAG,qBAAqB,CAAA"}
1
+ {"version":3,"file":"index.docs.d.ts","sourceRoot":"","sources":["../../src/types/index.docs.ts"],"names":[],"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":"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"}
@@ -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.140.1",
3
+ "version": "3.143.0",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "git+https://github.com/lynx-family/lynx-ui.git",
@@ -16,16 +16,17 @@
16
16
  "module": "./dist/index.jsx",
17
17
  "types": "./dist/index.d.ts",
18
18
  "files": [
19
- "src/**",
19
+ "src",
20
+ "!src/**/__tests__/**",
21
+ "!src/**/*.test.*",
22
+ "README.md",
20
23
  "CHANGELOG.md",
21
24
  "LICENSE",
22
- "tsconfig.docs.json",
23
- "tsconfig.json",
24
25
  "dist/**"
25
26
  ],
26
27
  "dependencies": {
27
28
  "clsx": "^2.1.1",
28
- "@lynx-js/lynx-ui-common": "3.139.0"
29
+ "@lynx-js/lynx-ui-common": "3.143.0"
29
30
  },
30
31
  "devDependencies": {
31
32
  "@lynx-js/react": "0.123.1",
@@ -37,7 +38,7 @@
37
38
  "peerDependencies": {
38
39
  "@lynx-js/react": ">=0.100.0",
39
40
  "@lynx-js/types": "*",
40
- "@types/react": "^18"
41
+ "@types/react": ">=18"
41
42
  },
42
43
  "publishConfig": {
43
44
  "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'
@@ -138,7 +138,9 @@ export interface PresenceContextType {
138
138
  export type UsePresenceReturnType = PresenceContextType
139
139
 
140
140
  /** @deprecated Use `UsePresenceProps` instead. */
141
+ // eslint-disable-next-line @typescript-eslint/naming-convention -- Preserve the deprecated public alias for compatibility.
141
142
  export type usePresenceProps = UsePresenceProps
142
143
 
143
144
  /** @deprecated Use `UsePresenceReturnType` instead. */
145
+ // eslint-disable-next-line @typescript-eslint/naming-convention -- Preserve the deprecated public alias for compatibility.
144
146
  export type usePresenceReturnType = UsePresenceReturnType
@@ -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,
@@ -1,7 +0,0 @@
1
- {
2
- "extends": "../../tools/configs/tsconfig.docs.json",
3
- "include": [
4
- "src",
5
- "dist/types/index.docs.d.ts"
6
- ]
7
- }
package/tsconfig.json DELETED
@@ -1,14 +0,0 @@
1
- {
2
- "extends": "../../tools/configs/tsconfig.lib.json",
3
- "compilerOptions": {
4
- "rootDir": "./src",
5
- },
6
- "include": [
7
- "src",
8
- ],
9
- "exclude": [
10
- "**/*.test.ts",
11
- "**/*.test.tsx",
12
- "**/__tests__/**",
13
- ],
14
- }