@lynx-js/lynx-ui-presence 0.0.0 → 3.130.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.
Files changed (43) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/LICENSE +8 -0
  3. package/README.md +49 -0
  4. package/dist/Presence.d.ts +8 -0
  5. package/dist/Presence.d.ts.map +1 -0
  6. package/dist/Presence.jsx +35 -0
  7. package/dist/Presence.jsx.map +1 -0
  8. package/dist/index.d.ts +6 -0
  9. package/dist/index.d.ts.map +1 -0
  10. package/dist/index.jsx +5 -0
  11. package/dist/types/index.d.ts +2 -0
  12. package/dist/types/index.d.ts.map +1 -0
  13. package/dist/types/index.docs.d.ts +49 -0
  14. package/dist/types/index.docs.d.ts.map +1 -0
  15. package/dist/types/index.jsx +0 -0
  16. package/dist/usePresence.d.ts +8 -0
  17. package/dist/usePresence.d.ts.map +1 -0
  18. package/dist/usePresence.jsx +176 -0
  19. package/dist/usePresence.jsx.map +1 -0
  20. package/dist/usePresenceGroup.d.ts +20 -0
  21. package/dist/usePresenceGroup.d.ts.map +1 -0
  22. package/dist/usePresenceGroup.jsx +79 -0
  23. package/dist/usePresenceGroup.jsx.map +1 -0
  24. package/dist/useVisibilityFromPresence.d.ts +12 -0
  25. package/dist/useVisibilityFromPresence.d.ts.map +1 -0
  26. package/dist/useVisibilityFromPresence.jsx +14 -0
  27. package/dist/useVisibilityFromPresence.jsx.map +1 -0
  28. package/dist/utils.d.ts +24 -0
  29. package/dist/utils.d.ts.map +1 -0
  30. package/dist/utils.jsx +45 -0
  31. package/dist/utils.jsx.map +1 -0
  32. package/package.json +46 -4
  33. package/src/Presence.tsx +64 -0
  34. package/src/index.tsx +17 -0
  35. package/src/types/index.docs.ts +72 -0
  36. package/src/types/index.ts +5 -0
  37. package/src/usePresence.tsx +322 -0
  38. package/src/usePresenceGroup.tsx +187 -0
  39. package/src/useVisibilityFromPresence.ts +39 -0
  40. package/src/utils.tsx +97 -0
  41. package/tsconfig.docs.json +7 -0
  42. package/tsconfig.json +9 -0
  43. /package/{index.js → dist/types/index.docs.jsx} +0 -0
@@ -0,0 +1,187 @@
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 {
6
+ createContext,
7
+ useCallback,
8
+ useEffect,
9
+ useMemo,
10
+ useState,
11
+ } from '@lynx-js/react'
12
+ import type { ReactNode } from '@lynx-js/react'
13
+
14
+ import { Presence } from './Presence'
15
+ import type { PresenceChildrenType, PresenceContextType } from './types'
16
+ import { PresenceState } from './utils'
17
+
18
+ export const PresenceContext = createContext<PresenceContextType>(null!)
19
+
20
+ export interface usePresenceGroupProps {
21
+ show: boolean
22
+ forceMount: boolean
23
+ setGroupState?: (state: PresenceState) => void
24
+ enableDelay?: boolean
25
+ children?:
26
+ | ReactNode
27
+ | PresenceChildrenType
28
+ | Array<ReactNode | PresenceChildrenType>
29
+ onOpen?: () => void
30
+ onClose?: () => void
31
+ debugLog?: boolean
32
+ }
33
+
34
+ export interface usePresenceGroupReturnType {
35
+ renderChildren: ReactNode
36
+ mountView: boolean
37
+ }
38
+ // Manage a group of Presence components.
39
+ // Wrap all child nodes with Presence and ensure that the onOpen and onClose events are triggered after all animations are completed.
40
+ export const usePresenceGroup: (
41
+ props: usePresenceGroupProps,
42
+ ) => usePresenceGroupReturnType = (props) => {
43
+ const {
44
+ show,
45
+ forceMount = false,
46
+ children,
47
+ enableDelay = false,
48
+ onOpen,
49
+ onClose,
50
+ setGroupState,
51
+ debugLog,
52
+ } = props
53
+
54
+ const [_, setMountingChildrenCount] = useState<number>(
55
+ 0,
56
+ )
57
+ const [mountView, setMountView] = useState<boolean>(show)
58
+
59
+ const childrenSize = Array.isArray(children)
60
+ ? children.length
61
+ : (children ? 1 : 0)
62
+ const [stateGroup, setStateGroup] = useState<PresenceState[]>(
63
+ Array.from({ length: childrenSize }, () => PresenceState.Left),
64
+ )
65
+
66
+ // Determine the overall state based on the stateGroup
67
+ const getGroupState = (states: PresenceState[]): PresenceState => {
68
+ // 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.
69
+ if (
70
+ states.some(state => state === PresenceState.DelayedEntering)
71
+ ) {
72
+ return PresenceState.DelayedEntering
73
+ }
74
+ if (
75
+ states.some(state => state === PresenceState.Entering)
76
+ ) {
77
+ return PresenceState.Entering
78
+ }
79
+ if (states.some(state => state === PresenceState.Leaving)) {
80
+ return PresenceState.Leaving
81
+ }
82
+ if (states.every(state => state === PresenceState.Entered)) {
83
+ return PresenceState.Entered
84
+ }
85
+ if (states.every(state => state === PresenceState.Left)) {
86
+ return PresenceState.Left
87
+ }
88
+ return PresenceState.Left
89
+ }
90
+
91
+ const updateStateGroup = (index: number, newState: PresenceState) => {
92
+ setStateGroup(prev => {
93
+ const newStateGroup = [...prev]
94
+ newStateGroup[index] = newState
95
+ if (setGroupState) {
96
+ setGroupState(getGroupState(newStateGroup))
97
+ }
98
+ return newStateGroup
99
+ })
100
+ }
101
+
102
+ const onChildOpen = useCallback(() => {
103
+ setMountingChildrenCount((prev) => {
104
+ const count = prev + 1
105
+ if (
106
+ children
107
+ && ((Array.isArray(children) && count === children.length)
108
+ || (!Array.isArray(children) && count === 1))
109
+ ) {
110
+ onOpen?.()
111
+ }
112
+ return count
113
+ })
114
+ }, [children, onOpen])
115
+
116
+ const onChildClose = useCallback(() => {
117
+ setMountingChildrenCount((prev) => {
118
+ const count = prev - 1
119
+ if (count === 0) {
120
+ onClose?.()
121
+ setMountView(false)
122
+ }
123
+ return count
124
+ })
125
+ }, [onClose])
126
+
127
+ const renderChildren = useMemo(() => {
128
+ return Array.isArray(children)
129
+ ? children.map(
130
+ (child: ReactNode | PresenceChildrenType, index: number) => {
131
+ return (
132
+ <Presence
133
+ key={index}
134
+ show={show}
135
+ forceMount={forceMount}
136
+ state={stateGroup[index]}
137
+ setPresenceState={(state: PresenceState) =>
138
+ updateStateGroup(index, state)}
139
+ enableDelay={enableDelay}
140
+ onOpen={onChildOpen}
141
+ onClose={onChildClose}
142
+ debugLog={debugLog}
143
+ >
144
+ {child}
145
+ </Presence>
146
+ )
147
+ },
148
+ )
149
+ : (children
150
+ ? (
151
+ <Presence
152
+ show={show}
153
+ forceMount={forceMount}
154
+ state={stateGroup[0]}
155
+ setPresenceState={(state: PresenceState) =>
156
+ updateStateGroup(0, state)}
157
+ enableDelay={enableDelay}
158
+ onOpen={onChildOpen}
159
+ onClose={onChildClose}
160
+ debugLog={debugLog}
161
+ >
162
+ {children}
163
+ </Presence>
164
+ )
165
+ : null)
166
+ }, [
167
+ show,
168
+ children,
169
+ stateGroup,
170
+ onChildClose,
171
+ onChildOpen,
172
+ forceMount,
173
+ enableDelay,
174
+ debugLog,
175
+ ])
176
+
177
+ useEffect(() => {
178
+ if (show) {
179
+ setMountView(true)
180
+ }
181
+ }, [show])
182
+
183
+ return {
184
+ renderChildren,
185
+ mountView,
186
+ }
187
+ }
@@ -0,0 +1,39 @@
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 { useEffect, useState } from '@lynx-js/react'
6
+
7
+ import type { CSSProperties } from '@lynx-js/types'
8
+
9
+ import { PresenceState } from './utils'
10
+
11
+ /**
12
+ * A hook that derives visibility state from a PresenceState.
13
+ * It returns 'visible' when the presence state indicates the component
14
+ * is entering, present, or leaving, and 'hidden' otherwise.
15
+ *
16
+ * @param state The current PresenceState.
17
+ * @returns CSSProperties['visibility'] ('visible' or 'hidden').
18
+ */
19
+ export function useVisibilityFromPresence(
20
+ state: PresenceState,
21
+ ): CSSProperties['visibility'] {
22
+ const [visibility, setVisibility] = useState<CSSProperties['visibility']>(
23
+ 'hidden',
24
+ )
25
+
26
+ useEffect(() => {
27
+ if (
28
+ state === PresenceState.DelayedEntering
29
+ || state === PresenceState.Entered
30
+ || state === PresenceState.Leaving
31
+ ) {
32
+ setVisibility('visible')
33
+ } else {
34
+ setVisibility('hidden')
35
+ }
36
+ }, [state])
37
+
38
+ return visibility
39
+ }
package/src/utils.tsx ADDED
@@ -0,0 +1,97 @@
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 { clsx } from 'clsx'
6
+
7
+ import type { PresenceAnimationStatus } from './types'
8
+
9
+ export enum PresenceState {
10
+ Initial = 0,
11
+ Entering = 1,
12
+ DelayedEntering = 2, // Special state for delaying the showAnimation. This is used to prevent the content from being layout before the showAnimation.
13
+ Entered = 3,
14
+ Leaving = 4,
15
+ Left = 5,
16
+ }
17
+
18
+ // Convert abstract state to clear animation status for users
19
+ export const resolveAnimationStatus: ({
20
+ state,
21
+ enableDelay,
22
+ grouped,
23
+ }: {
24
+ state: PresenceState
25
+ enableDelay: boolean
26
+ grouped?: boolean
27
+ }) => PresenceAnimationStatus = ({
28
+ state,
29
+ enableDelay,
30
+ grouped = false,
31
+ }) => {
32
+ const enteringStateWithDelay = enableDelay
33
+ ? PresenceState.DelayedEntering
34
+ : PresenceState.Entering
35
+ const isOpen = state === enteringStateWithDelay
36
+ || state === PresenceState.Entered
37
+ const groupedOpen = isOpen || state === PresenceState.Leaving
38
+
39
+ const isClose = state === PresenceState.Leaving
40
+ || state === PresenceState.Left
41
+ || (enableDelay && state === PresenceState.Entering)
42
+ const groupedClosed = state === PresenceState.Left
43
+ return {
44
+ leaving: state === PresenceState.Leaving,
45
+ entering: state === enteringStateWithDelay,
46
+ animating: state === PresenceState.Leaving
47
+ || state === enteringStateWithDelay,
48
+
49
+ // In grouped state, even the member has entered their animation(leaving) state, it has to remain open so it won't hide its children.
50
+ // grouped: open = entering/delayedEntering/entered/leaving
51
+ // normal: open = entering/delayedEntering/entered
52
+ open: grouped ? groupedOpen : isOpen,
53
+ // In grouped state, the grouped element has to wait all its member exit their animations.
54
+ // grouped: closed = left
55
+ // normal: closed = leaving/left
56
+ closed: grouped ? groupedClosed : isClose,
57
+ }
58
+ }
59
+
60
+ interface PresenceClassVariantsProps {
61
+ state: PresenceState
62
+ enableDelay: boolean
63
+ className?: string
64
+ transition?: boolean
65
+ grouped?: boolean
66
+ }
67
+
68
+ export const presenceClassVariants = ({
69
+ state,
70
+ enableDelay,
71
+ className,
72
+ transition,
73
+ grouped,
74
+ }: PresenceClassVariantsProps) => {
75
+ const status = resolveAnimationStatus({
76
+ state,
77
+ enableDelay,
78
+ grouped,
79
+ })
80
+ if (transition) {
81
+ return clsx(
82
+ className,
83
+ {
84
+ 'ui-entering': status.entering,
85
+ 'ui-leaving': status.leaving,
86
+ 'ui-animating': status.animating,
87
+ 'ui-open': status.open,
88
+ 'ui-closed': status.closed,
89
+ },
90
+ )
91
+ } else {
92
+ return clsx(className, {
93
+ 'ui-open': status.open,
94
+ 'ui-closed': status.closed,
95
+ })
96
+ }
97
+ }
@@ -0,0 +1,7 @@
1
+ {
2
+ "extends": "../../tools/configs/tsconfig.docs.json",
3
+ "include": [
4
+ "src",
5
+ "dist/types/index.docs.d.ts"
6
+ ]
7
+ }
package/tsconfig.json ADDED
@@ -0,0 +1,9 @@
1
+ {
2
+ "extends": "../../tools/configs/tsconfig.lib.json",
3
+ "compilerOptions": {
4
+ "rootDir": "./src",
5
+ },
6
+ "include": [
7
+ "src",
8
+ ],
9
+ }
File without changes