@lynx-js/lynx-ui-sortable 0.0.0 → 3.131.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/src/index.tsx ADDED
@@ -0,0 +1,11 @@
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
+ export { SortableRoot, SortableItem, SortableItemArea } from './Sortable'
6
+
7
+ export type {
8
+ SortableItemProps,
9
+ SortableRootProps,
10
+ SortableData,
11
+ } from './types'
@@ -0,0 +1,129 @@
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 type { ReactNode } from '@lynx-js/react'
6
+
7
+ /**
8
+ * The data structure for each item in the Sortable component.
9
+ * @zh Sortable 组件中每个项目的数据结构。
10
+ */
11
+ export interface SortableData<T> {
12
+ /**
13
+ * A function that returns the unique key for sorting.
14
+ * @Android
15
+ * @iOS
16
+ * @Harmony
17
+ * @zh 返回子节点用于排序的唯一键的函数。
18
+ */
19
+ getSortingKey: () => string
20
+ /**
21
+ * The original data item.
22
+ * @Android
23
+ * @iOS
24
+ * @Harmony
25
+ * @zh 原始数据项。
26
+ */
27
+ dataItem: T
28
+ }
29
+
30
+ export interface SortableRootProps<T> {
31
+ /**
32
+ * Whether to enable sorting.
33
+ * @defaultValue true
34
+ * @Android
35
+ * @iOS
36
+ * @Harmony
37
+ * @zh 是否启用排序。
38
+ */
39
+ enableSorting?: boolean
40
+ /**
41
+ * Children, which is a function that receives an item and returns a ReactNode.
42
+ * @Android
43
+ * @iOS
44
+ * @Harmony
45
+ * @zh 子节点,是一个接收 item 并返回 ReactNode 的函数。
46
+ */
47
+ children: (item: SortableData<T>) => ReactNode
48
+ /**
49
+ * The data for the sortable list.
50
+ * @Android
51
+ * @iOS
52
+ * @Harmony
53
+ * @zh 拖拽列表的数据。
54
+ */
55
+ data: SortableData<T>[]
56
+ /**
57
+ * The unique key of the item that acts as the boundary. If the item is dragged out of the boundary, the sorting will be canceled.
58
+ * @Android
59
+ * @iOS
60
+ * @Harmony
61
+ * @zh 作为边界限制的项的唯一键。如果项被拖出边界,排序将被取消。
62
+ */
63
+ boundaryId?: string
64
+ /**
65
+ * Callback function that is triggered when sorting ends. The parameter is the sorted data.
66
+ * @Android
67
+ * @iOS
68
+ * @Harmony
69
+ * @zh 排序结束时触发的回调函数。参数为排序后的`data`。
70
+ */
71
+ onSortEnd: (sortedData: SortableData<T>[]) => void
72
+ /**
73
+ * Callback function that is triggered when sorting starts.
74
+ * @Android
75
+ * @iOS
76
+ * @Harmony
77
+ * @zh 拖拽排序开始时触发的回调函数。
78
+ */
79
+ onSortStart?: () => void
80
+ /**
81
+ * Display debug logs. Open it when you find a bug.
82
+ * @defaultValue false
83
+ * @Android
84
+ * @iOS
85
+ * @Harmony
86
+ * @zh 显示调试日志,发现问题时开启。
87
+ */
88
+ debugLog?: boolean
89
+ }
90
+
91
+ /**
92
+ * The item inside Sortable.
93
+ * @zh Sortable 的子项。
94
+ */
95
+ export interface SortableItemProps {
96
+ /**
97
+ * className
98
+ * @zh 类名
99
+ * @Android
100
+ * @iOS
101
+ * @Harmony
102
+ */
103
+ className?: string
104
+ /**
105
+ * The unique key for sorting.
106
+ * @Android
107
+ * @iOS
108
+ * @Harmony
109
+ * @zh 用于排序的唯一键。
110
+ */
111
+ sortingKey: string
112
+ /**
113
+ * Children.
114
+ * @Android
115
+ * @iOS
116
+ * @Harmony
117
+ * @zh 子节点。
118
+ */
119
+ children: ReactNode
120
+ /**
121
+ * Specifies the underlying component to be used.
122
+ * @defaultValue 'Draggable'
123
+ * @Android
124
+ * @iOS
125
+ * @Harmony
126
+ * @zh 指定底层组件。若整个子节点区域均可拖动,使用默认值 'Draggable';否则使用 'DraggableRoot','DraggableRoot' 需与子节点 'DraggableArea' 一起使用。仅触摸其子节点 'DraggableArea' 时可拖动。
127
+ */
128
+ as?: 'Draggable' | 'DraggableRoot'
129
+ }
@@ -0,0 +1,5 @@
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
+ export type * from './index.docs'
@@ -0,0 +1,354 @@
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
+ runOnBackground,
7
+ useCallback,
8
+ useMainThreadRef,
9
+ useMemo,
10
+ } from '@lynx-js/react'
11
+ import type { MainThreadRef, RefObject } from '@lynx-js/react'
12
+
13
+ import { mtsLog } from '@lynx-js/lynx-ui-common'
14
+ import type { Point } from '@lynx-js/lynx-ui-common'
15
+ import type { DraggableRef } from '@lynx-js/lynx-ui-draggable'
16
+ import type { MainThread } from '@lynx-js/types'
17
+
18
+ import type { SortableData } from './types'
19
+
20
+ interface SortableOptionsType {
21
+ data: SortableData<unknown>[] // sorting key array
22
+ sizeMap: MainThreadRef<Record<string, number>> // sorting key -> size
23
+ itemRefMap: RefObject<Record<string, DraggableRef | null>>
24
+ itemMTSRefMap: MainThreadRef<Record<string, DraggableRef | null>> // sortingKey -> element Ref
25
+ onDragEnd?: (sortedKeyArray: SortableData<unknown>[]) => void
26
+ onDragStart?: () => void
27
+ debugLog?: boolean
28
+ }
29
+
30
+ export function useSortable(
31
+ useSortableOptions: SortableOptionsType,
32
+ ) {
33
+ const {
34
+ data,
35
+ sizeMap,
36
+ itemMTSRefMap,
37
+ onDragEnd,
38
+ onDragStart,
39
+ debugLog = false,
40
+ } = useSortableOptions
41
+
42
+ const safeData = Array.isArray(data) ? data : []
43
+ const keyArray = useMemo(() => safeData.map(item => item.getSortingKey()), [
44
+ safeData,
45
+ ])
46
+ const swapConfirmedPercentage = useMainThreadRef<number>(0.5)
47
+ const touchStartPoint = useMainThreadRef<Point>({ x: 0, y: 0 })
48
+ const lastSwappingKey = useMainThreadRef<string>('')
49
+ const swappingItemTranslation = useMainThreadRef<number>(0)
50
+ const changedKey = useMainThreadRef<string[]>([]) // Store all the moved item. Remember to reset them
51
+ const lastSwappedKey = useMainThreadRef<string>('') // Store the last swapped item. Use it to do the sorting.
52
+
53
+ const changeItemZIndex = useCallback((zIndex: number, sortingKey: string) => {
54
+ 'main thread'
55
+ const item = itemMTSRefMap.current[sortingKey]
56
+
57
+ item?.MTSSetOtherStyles({
58
+ 'transform': `translateZ(${zIndex}px)`,
59
+ 'z-index': `${zIndex}`,
60
+ })
61
+ }, [itemMTSRefMap])
62
+
63
+ const handleDragStartJS = useCallback(() => {
64
+ onDragStart?.()
65
+ }, [onDragStart])
66
+
67
+ const handleDragStart = useCallback(
68
+ (
69
+ pagePoint: Point,
70
+ sortingKey: string,
71
+ event: MainThread.MouseEvent | MainThread.TouchEvent,
72
+ ) => {
73
+ 'main thread'
74
+ runOnBackground(handleDragStartJS)()
75
+ touchStartPoint.current = pagePoint
76
+ changedKey.current.push(sortingKey)
77
+ changeItemZIndex(10000, sortingKey)
78
+ mtsLog(debugLog, '[event drag start]', event)
79
+ },
80
+ [handleDragStartJS, touchStartPoint, changedKey, changeItemZIndex],
81
+ )
82
+
83
+ const swappingIndexAndDistance: (
84
+ movingDistance: number,
85
+ sortingKey: string,
86
+ ) => { index: number, distance: number } = useCallback(
87
+ (movingDistance, sortingKey) => {
88
+ 'main thread'
89
+ const index = keyArray.indexOf(sortingKey)
90
+ if (keyArray.length === 0 || index < 0 || index >= keyArray.length) {
91
+ mtsLog(debugLog, '[swappingIndexAndDistance] invalid index', index)
92
+ return { index: -1, distance: 0 }
93
+ }
94
+
95
+ const absDistance = Math.abs(movingDistance)
96
+ const direction = movingDistance > 0 ? 1 : -1
97
+ let currentIndex = index + direction
98
+ let accumulatedDistance = 0
99
+ while (true) {
100
+ if (currentIndex < 0 || currentIndex >= keyArray.length) {
101
+ return {
102
+ index: -1,
103
+ distance: (movingDistance > 0 ? 1 : -1)
104
+ * (absDistance - accumulatedDistance),
105
+ }
106
+ }
107
+ const size = sizeMap.current[keyArray[currentIndex]]
108
+ if (typeof size !== 'number') {
109
+ mtsLog(
110
+ debugLog,
111
+ `[swappingIndexAndDistance] item size not found for key ${sortingKey}, stopping at index ${currentIndex}.`,
112
+ )
113
+ return {
114
+ index: -1,
115
+ distance: (movingDistance > 0 ? 1 : -1) * accumulatedDistance,
116
+ }
117
+ }
118
+ accumulatedDistance += size
119
+
120
+ if (accumulatedDistance >= absDistance) {
121
+ return {
122
+ index: currentIndex,
123
+ // This distance is the remained dragging distance needs to be consumed by current interacting item.
124
+ // E.g.: the total delta is 458 and all item is all 100px tall. Then the first 400 will be consumed the previous clamped items. And the 58 is current interacting item.
125
+ distance: (movingDistance > 0 ? 1 : -1)
126
+ * (accumulatedDistance - size),
127
+ }
128
+ }
129
+ currentIndex += direction
130
+ }
131
+ },
132
+ [keyArray, sizeMap],
133
+ )
134
+
135
+ const setTransform = useCallback(
136
+ (item: DraggableRef | null, translate: number) => {
137
+ 'main thread'
138
+
139
+ item?.MTSSetOtherStyles({ 'transform': `translateY(${translate}px)` })
140
+ },
141
+ [],
142
+ )
143
+
144
+ // Clamp the previous interacting item to the grid
145
+ const clampPreviousItem = (movingDistance: number, sortingKey: string) => {
146
+ 'main thread'
147
+ mtsLog(
148
+ debugLog,
149
+ `clamp ${lastSwappingKey.current} to grid`,
150
+ )
151
+ const draggingItemSize = sizeMap.current[sortingKey]
152
+ if (lastSwappingKey.current !== null) {
153
+ const lastSwappingItem = lastSwappingKey.current
154
+ ? itemMTSRefMap.current[lastSwappingKey.current]
155
+ : null
156
+ if (
157
+ Math.abs(swappingItemTranslation.current)
158
+ > draggingItemSize * swapConfirmedPercentage.current
159
+ ) {
160
+ setTransform(
161
+ lastSwappingItem,
162
+ (movingDistance < 0 ? 1 : -1) * draggingItemSize,
163
+ )
164
+ } else {
165
+ setTransform(lastSwappingItem, 0)
166
+ }
167
+ }
168
+ }
169
+
170
+ const updateLastSwappingItem = (
171
+ movingDistance: number,
172
+ sortingKey: string,
173
+ swappingKey: string,
174
+ ) => {
175
+ 'main thread'
176
+ mtsLog(
177
+ debugLog,
178
+ `interact item from ${lastSwappingKey.current} to ${swappingKey}`,
179
+ )
180
+ clampPreviousItem(movingDistance, sortingKey)
181
+ lastSwappingKey.current = swappingKey
182
+ }
183
+
184
+ // Update the confirmed interacting ID if the condition is met
185
+ const updateConfirmedInteractedID = (
186
+ unconsumedDistance: number,
187
+ sortingKey: string,
188
+ ) => {
189
+ 'main thread'
190
+ mtsLog(
191
+ debugLog,
192
+ `swapping with ${lastSwappingKey.current} at ${unconsumedDistance}`,
193
+ )
194
+ const draggingItemSize = sizeMap.current[sortingKey]
195
+ if (
196
+ Math.abs(unconsumedDistance)
197
+ > draggingItemSize * swapConfirmedPercentage.current
198
+ ) {
199
+ lastSwappedKey.current = lastSwappingKey.current
200
+ mtsLog(
201
+ debugLog,
202
+ `confirmed swapping with ${lastSwappedKey.current} at cross ${unconsumedDistance}`,
203
+ )
204
+ } else if (lastSwappedKey.current === lastSwappingKey.current) {
205
+ // Handle case when dragging back over a previously swapped item
206
+ const swappingIndex = keyArray.indexOf(lastSwappingKey.current)
207
+ const draggedItemIndex = keyArray.indexOf(sortingKey)
208
+
209
+ // Get new swap candidate index based on drag direction reversal
210
+ // Drag down → reverse up: `swappingIndex - 1`
211
+ // Drag up → reverse down: `swappingIndex + 1`
212
+ const indexModifier = swappingIndex > draggedItemIndex ? -1 : 1
213
+ const newSwappedKeyIndex = swappingIndex + indexModifier
214
+
215
+ // The logic should prevent out-of-bounds access, but as a safeguard:
216
+ if (newSwappedKeyIndex >= 0 && newSwappedKeyIndex < keyArray.length) {
217
+ const newSwappedKey = keyArray[newSwappedKeyIndex]
218
+
219
+ // If new candidate's index matches dragged item's index, item returned to original position; no swap confirmed.
220
+ if (newSwappedKeyIndex === draggedItemIndex) {
221
+ lastSwappedKey.current = ''
222
+ } else {
223
+ lastSwappedKey.current = newSwappedKey
224
+ }
225
+ } else {
226
+ // Item is returning to original position when reverting swap at list start/end.
227
+ lastSwappedKey.current = ''
228
+ }
229
+
230
+ mtsLog(
231
+ debugLog,
232
+ `Reverted swap with ${lastSwappingKey.current}. New confirmed swap is with ${
233
+ lastSwappedKey.current || 'none'
234
+ }.`,
235
+ )
236
+ }
237
+ swappingItemTranslation.current = unconsumedDistance
238
+ }
239
+
240
+ const switchHandler = useCallback(
241
+ (movingDistance: number, sortingKey: string) => {
242
+ 'main thread'
243
+ const { index: swappingIndex, distance: consumedDistance } =
244
+ swappingIndexAndDistance(movingDistance, sortingKey)
245
+ mtsLog(
246
+ debugLog,
247
+ 'swappingIndexAndDistance',
248
+ swappingIndex,
249
+ consumedDistance,
250
+ )
251
+ if (swappingIndex < 0) {
252
+ clampPreviousItem(consumedDistance, sortingKey)
253
+ return
254
+ }
255
+ const swappingKey = keyArray[swappingIndex]
256
+ const swappingItem = itemMTSRefMap.current[swappingKey]
257
+
258
+ if (swappingKey !== lastSwappingKey.current) {
259
+ updateLastSwappingItem(movingDistance, sortingKey, swappingKey)
260
+ changedKey.current.push(swappingKey)
261
+ }
262
+
263
+ const unconsumedDistance = movingDistance - consumedDistance
264
+ updateConfirmedInteractedID(unconsumedDistance, sortingKey)
265
+ setTransform(swappingItem, -unconsumedDistance)
266
+ },
267
+ [
268
+ changedKey,
269
+ itemMTSRefMap,
270
+ keyArray,
271
+ lastSwappingKey,
272
+ setTransform,
273
+ swappingIndexAndDistance,
274
+ updateConfirmedInteractedID,
275
+ updateLastSwappingItem,
276
+ ],
277
+ )
278
+
279
+ const handleDragMove = useCallback(
280
+ (
281
+ delta: Point,
282
+ sortingKey: string,
283
+ event: MainThread.MouseEvent | MainThread.TouchEvent,
284
+ ) => {
285
+ 'main thread'
286
+ switchHandler(delta.y, sortingKey)
287
+ mtsLog(debugLog, '[event drag move]', event)
288
+ },
289
+ [switchHandler],
290
+ )
291
+
292
+ const sortArray = useCallback((sortingKey: string) => {
293
+ 'main thread'
294
+ const draggingIndex = keyArray.indexOf(sortingKey)
295
+ const swappedIndex = keyArray.indexOf(lastSwappedKey.current)
296
+ const swappedKeyArray = [...keyArray]
297
+
298
+ mtsLog(debugLog, 'sortArray with lastSwappedKey ', lastSwappedKey.current)
299
+
300
+ if (
301
+ draggingIndex === -1 || swappedIndex === -1
302
+ || draggingIndex === swappedIndex
303
+ ) {
304
+ return swappedKeyArray
305
+ }
306
+
307
+ const [draggedItem] = swappedKeyArray.splice(draggingIndex, 1)
308
+ swappedKeyArray.splice(swappedIndex, 0, draggedItem)
309
+ return swappedKeyArray
310
+ }, [keyArray, lastSwappedKey])
311
+
312
+ const resetStatus = useCallback(() => {
313
+ 'main thread'
314
+ changedKey.current.map((key: string) => {
315
+ const item = itemMTSRefMap?.current?.[key]
316
+ if (item && typeof item.MTSResetInternalTranslateValues === 'function') {
317
+ item?.MTSResetInternalTranslateValues()
318
+ }
319
+ })
320
+ lastSwappedKey.current = ''
321
+ lastSwappingKey.current = ''
322
+ changedKey.current = []
323
+ }, [changedKey, itemMTSRefMap, lastSwappedKey, lastSwappingKey])
324
+
325
+ const rootDragEnd = useCallback((sortedKey: string[]) => {
326
+ const keyToItemMap = new Map(data.map((item, index) => {
327
+ return [keyArray[index], item]
328
+ }))
329
+ const sortedData = sortedKey
330
+ .map(key => keyToItemMap.get(key))
331
+ .filter((item): item is NonNullable<typeof item> => !!item)
332
+ onDragEnd?.(sortedData)
333
+ }, [data, keyArray, onDragEnd])
334
+
335
+ const handleDragEnd = useCallback(
336
+ (
337
+ sortingKey: string,
338
+ event: MainThread.MouseEvent | MainThread.TouchEvent,
339
+ ) => {
340
+ 'main thread'
341
+ mtsLog(debugLog, '[event drag end]', event)
342
+ const sortedKey = sortArray(sortingKey)
343
+ runOnBackground(rootDragEnd)(sortedKey)
344
+ resetStatus()
345
+ },
346
+ [resetStatus, rootDragEnd, sortArray],
347
+ )
348
+
349
+ return {
350
+ handleDragStart,
351
+ handleDragMove,
352
+ handleDragEnd,
353
+ }
354
+ }
@@ -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