@lynx-js/lynx-ui-sortable 3.139.0 → 3.140.1

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.
@@ -10,19 +10,32 @@ import type { Point } from '@lynx-js/lynx-ui-common'
10
10
  import type { DraggableRef } from '@lynx-js/lynx-ui-draggable'
11
11
  import type { MainThread } from '@lynx-js/types'
12
12
 
13
- import type { SortableData } from './types'
13
+ export interface SortableRect {
14
+ height: number
15
+ width: number
16
+ top: number
17
+ left: number
18
+ bottom: number
19
+ right: number
20
+ }
14
21
 
15
- interface SortableContextType<T = unknown> {
16
- data: SortableData<T>[]
22
+ export interface SortableContextType {
17
23
  isDragOverlay: boolean
24
+ resetItemVisualsRef: MutableRefObject<
25
+ Record<string, (() => void) | undefined>
26
+ >
18
27
  boundaryId?: string
19
28
  scrollableBoundaryId?: string
20
29
  scrollableBoundaryUpperEdgeRef?: MutableRefObject<boolean>
21
30
  scrollableBoundaryLowerEdgeRef?: MutableRefObject<boolean>
31
+ scrollableBoundaryRectRef?: MutableRefObject<SortableRect | null>
22
32
  scrollableScrollTopRef?: MutableRefObject<number>
23
33
  dragOverlayRefMap?: MutableRefObject<
24
34
  Record<string, MainThread.Element | null>
25
35
  >
36
+ dragOverlayActivatorRefMap?: MutableRefObject<
37
+ Record<string, (() => void) | null>
38
+ >
26
39
  dirtyKeysRef: MutableRefObject<Record<string, boolean>>
27
40
  disabledKeysRef: MutableRefObject<Record<string, boolean>>
28
41
  scrollableStickyUpperOffset: number
@@ -39,6 +52,7 @@ interface SortableContextType<T = unknown> {
39
52
  refI: RefObject<MainThread.Element | null>,
40
53
  key: string,
41
54
  ) => void
55
+ clearDragOverlayRef: (key: string) => void
42
56
  handleDragStart: (
43
57
  pagePoint: Point,
44
58
  sortingKey: string,
@@ -52,13 +66,16 @@ interface SortableContextType<T = unknown> {
52
66
  handleDragEnd: (
53
67
  sortingKey: string,
54
68
  event: MainThread.MouseEvent | MainThread.TouchEvent,
55
- ) => void
69
+ ) => boolean
56
70
  }
57
71
 
72
+ // Only legacy geometry observers subscribe to ordering, not gesture owners.
73
+ export const SortableOrderContext = createContext('[]')
74
+
58
75
  export const SortableContext = createContext<SortableContextType>({
59
- data: [],
60
76
  isDragOverlay: false,
61
77
  debugLog: false,
78
+ resetItemVisualsRef: { current: {} },
62
79
  enableSorting: true,
63
80
  scrollableStickyUpperOffset: 0,
64
81
  scrollableStickyLowerOffset: 0,
@@ -68,7 +85,8 @@ export const SortableContext = createContext<SortableContextType>({
68
85
  setChildrenRef: noop,
69
86
  setChildrenMTSRef: noop,
70
87
  setDragOverlayRef: noop,
88
+ clearDragOverlayRef: noop,
71
89
  handleDragStart: noop,
72
90
  handleDragMove: noop,
73
- handleDragEnd: noop,
91
+ handleDragEnd: () => false,
74
92
  })
@@ -0,0 +1,31 @@
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 { MainThreadRef } from '@lynx-js/react'
6
+
7
+ /** Synchronize order and drag visuals before the element tree is flushed. */
8
+ export function commitSortableOrder(
9
+ orderRef: MainThreadRef<string[]>,
10
+ nextOrder: string[],
11
+ dirtyKeysRef: MainThreadRef<Record<string, boolean>>,
12
+ resetItemVisualsRef: MainThreadRef<Record<string, (() => void) | undefined>>,
13
+ dragFinished: boolean,
14
+ ) {
15
+ 'main thread'
16
+ const previousOrder = orderRef.current
17
+ let orderChanged = previousOrder.length !== nextOrder.length
18
+ for (let index = 0; !orderChanged && index < nextOrder.length; index++) {
19
+ orderChanged = previousOrder[index] !== nextOrder[index]
20
+ }
21
+ orderRef.current = nextOrder
22
+ if (!orderChanged && !dragFinished) {
23
+ return
24
+ }
25
+ for (const key of Object.keys(dirtyKeysRef.current)) {
26
+ if (dirtyKeysRef.current[key]) {
27
+ resetItemVisualsRef.current[key]?.()
28
+ delete dirtyKeysRef.current[key]
29
+ }
30
+ }
31
+ }
@@ -2,15 +2,10 @@
2
2
  // Licensed under the Apache License Version 2.0 that can be found in the
3
3
  // LICENSE file in the root directory of this source tree.
4
4
 
5
- import {
6
- runOnBackground,
7
- useCallback,
8
- useMainThreadRef,
9
- useMemo,
10
- } from '@lynx-js/react'
5
+ import { runOnBackground, useCallback, useMainThreadRef } from '@lynx-js/react'
11
6
  import type { MainThreadRef, RefObject } from '@lynx-js/react'
12
7
 
13
- import { mtsLog } from '@lynx-js/lynx-ui-common'
8
+ import { mtsLog, useLatest } from '@lynx-js/lynx-ui-common'
14
9
  import type { Point } from '@lynx-js/lynx-ui-common'
15
10
  import type { DraggableRef } from '@lynx-js/lynx-ui-draggable'
16
11
  import type { MainThread } from '@lynx-js/types'
@@ -19,13 +14,14 @@ import type { SortableData } from './types'
19
14
 
20
15
  interface SortableOptionsType<T> {
21
16
  data: SortableData<T>[] // sorting key array
17
+ orderRef: MainThreadRef<string[]>
22
18
  sizeMap: MainThreadRef<Record<string, number>> // sorting key -> size
23
19
  itemRefMap: RefObject<Record<string, DraggableRef | null>>
24
20
  itemMTSRefMap: MainThreadRef<Record<string, DraggableRef | null>> // sortingKey -> element Ref
25
21
  dirtyKeysRef: MainThreadRef<Record<string, boolean>>
26
22
  disabledKeysRef: MainThreadRef<Record<string, boolean>>
27
23
  onDragEnd?: (sortedKeyArray: SortableData<T>[]) => void
28
- onDragStart?: () => void
24
+ onDragStart?: (sortingKey: string) => void
29
25
  debugLog?: boolean
30
26
  }
31
27
 
@@ -34,6 +30,7 @@ export function useSortable<T>(
34
30
  ) {
35
31
  const {
36
32
  data,
33
+ orderRef,
37
34
  sizeMap,
38
35
  itemMTSRefMap,
39
36
  dirtyKeysRef,
@@ -43,10 +40,8 @@ export function useSortable<T>(
43
40
  debugLog = false,
44
41
  } = useSortableOptions
45
42
 
46
- const safeData = Array.isArray(data) ? data : []
47
- const keyArray = useMemo(() => safeData.map(item => item.getSortingKey()), [
48
- safeData,
49
- ])
43
+ // Business data and callbacks stay on BTS; MTS only captures stable refs.
44
+ const latest = useLatest({ data, onDragEnd, onDragStart })
50
45
  const swapConfirmedPercentage = useMainThreadRef<number>(0.5)
51
46
  const touchStartPoint = useMainThreadRef<Point>({ x: 0, y: 0 })
52
47
  const lastSwappingKey = useMainThreadRef<string>('')
@@ -65,9 +60,9 @@ export function useSortable<T>(
65
60
  dirtyKeysRef.current[sortingKey] = true
66
61
  }, [itemMTSRefMap, dirtyKeysRef])
67
62
 
68
- const handleDragStartJS = useCallback(() => {
69
- onDragStart?.()
70
- }, [onDragStart])
63
+ const handleDragStartJS = useCallback((sortingKey: string) => {
64
+ latest.current.onDragStart?.(sortingKey)
65
+ }, [latest])
71
66
 
72
67
  const handleDragStart = useCallback(
73
68
  (
@@ -76,13 +71,19 @@ export function useSortable<T>(
76
71
  event: MainThread.MouseEvent | MainThread.TouchEvent,
77
72
  ) => {
78
73
  'main thread'
79
- runOnBackground(handleDragStartJS)()
74
+ runOnBackground(handleDragStartJS)(sortingKey)
80
75
  touchStartPoint.current = pagePoint
81
76
  changedKey.current.push(sortingKey)
82
77
  changeItemZIndex(10000, sortingKey)
83
78
  mtsLog(debugLog, '[event drag start]', event)
84
79
  },
85
- [handleDragStartJS, touchStartPoint, changedKey, changeItemZIndex],
80
+ [
81
+ handleDragStartJS,
82
+ touchStartPoint,
83
+ changedKey,
84
+ changeItemZIndex,
85
+ debugLog,
86
+ ],
86
87
  )
87
88
 
88
89
  const swappingIndexAndDistance: (
@@ -92,6 +93,7 @@ export function useSortable<T>(
92
93
  useCallback(
93
94
  (movingDistance, sortingKey) => {
94
95
  'main thread'
96
+ const keyArray = orderRef.current
95
97
  const index = keyArray.indexOf(sortingKey)
96
98
  if (keyArray.length === 0 || index < 0 || index >= keyArray.length) {
97
99
  mtsLog(debugLog, '[swappingIndexAndDistance] invalid index', index)
@@ -195,7 +197,7 @@ export function useSortable<T>(
195
197
  currentIndex += direction
196
198
  }
197
199
  },
198
- [keyArray, sizeMap, disabledKeysRef],
200
+ [orderRef, sizeMap, disabledKeysRef, debugLog],
199
201
  )
200
202
 
201
203
  const setTransform = useCallback(
@@ -212,7 +214,10 @@ export function useSortable<T>(
212
214
  )
213
215
 
214
216
  // Clamp the previous interacting item to the grid
215
- const clampPreviousItem = (movingDistance: number, sortingKey: string) => {
217
+ const clampPreviousItem = useCallback((
218
+ movingDistance: number,
219
+ sortingKey: string,
220
+ ) => {
216
221
  'main thread'
217
222
  mtsLog(
218
223
  debugLog,
@@ -238,9 +243,17 @@ export function useSortable<T>(
238
243
  setTransform(lastSwappingItemKey, 0)
239
244
  }
240
245
  }
241
- }
246
+ }, [
247
+ debugLog,
248
+ lastCrossedDisabledSize,
249
+ lastSwappingKey,
250
+ setTransform,
251
+ sizeMap,
252
+ swapConfirmedPercentage,
253
+ swappingItemTranslation,
254
+ ])
242
255
 
243
- const updateLastSwappingItem = (
256
+ const updateLastSwappingItem = useCallback((
244
257
  movingDistance: number,
245
258
  sortingKey: string,
246
259
  swappingKey: string,
@@ -252,14 +265,15 @@ export function useSortable<T>(
252
265
  )
253
266
  clampPreviousItem(movingDistance, sortingKey)
254
267
  lastSwappingKey.current = swappingKey
255
- }
268
+ }, [clampPreviousItem, debugLog, lastSwappingKey])
256
269
 
257
270
  // Update the confirmed interacting ID if the condition is met
258
- const updateConfirmedInteractedID = (
271
+ const updateConfirmedInteractedID = useCallback((
259
272
  unconsumedDistance: number,
260
273
  sortingKey: string,
261
274
  ) => {
262
275
  'main thread'
276
+ const keyArray = orderRef.current
263
277
  mtsLog(
264
278
  debugLog,
265
279
  `swapping with ${lastSwappingKey.current} at ${unconsumedDistance}`,
@@ -308,11 +322,20 @@ export function useSortable<T>(
308
322
  )
309
323
  }
310
324
  swappingItemTranslation.current = unconsumedDistance
311
- }
325
+ }, [
326
+ debugLog,
327
+ orderRef,
328
+ lastSwappedKey,
329
+ lastSwappingKey,
330
+ sizeMap,
331
+ swapConfirmedPercentage,
332
+ swappingItemTranslation,
333
+ ])
312
334
 
313
335
  const switchHandler = useCallback(
314
336
  (movingDistance: number, sortingKey: string) => {
315
337
  'main thread'
338
+ const keyArray = orderRef.current
316
339
  const {
317
340
  index: swappingIndex,
318
341
  distance: consumedDistance,
@@ -354,7 +377,10 @@ export function useSortable<T>(
354
377
  [
355
378
  changedKey,
356
379
  itemMTSRefMap,
357
- keyArray,
380
+ orderRef,
381
+ debugLog,
382
+ sizeMap,
383
+ lastCrossedDisabledSize,
358
384
  lastSwappingKey,
359
385
  setTransform,
360
386
  swappingIndexAndDistance,
@@ -374,11 +400,12 @@ export function useSortable<T>(
374
400
  changeItemZIndex(10000, sortingKey)
375
401
  mtsLog(debugLog, '[event drag move]', event)
376
402
  },
377
- [switchHandler, changeItemZIndex],
403
+ [switchHandler, changeItemZIndex, debugLog],
378
404
  )
379
405
 
380
406
  const sortArray = useCallback((sortingKey: string) => {
381
407
  'main thread'
408
+ const keyArray = orderRef.current
382
409
  const draggingIndex = keyArray.indexOf(sortingKey)
383
410
  const swappedIndex = keyArray.indexOf(lastSwappedKey.current)
384
411
 
@@ -422,7 +449,7 @@ export function useSortable<T>(
422
449
  }
423
450
  }
424
451
  return result
425
- }, [keyArray, lastSwappedKey, disabledKeysRef])
452
+ }, [orderRef, lastSwappedKey, disabledKeysRef, debugLog])
426
453
 
427
454
  const resetSwapTrackingRefs = useCallback(() => {
428
455
  'main thread'
@@ -460,14 +487,13 @@ export function useSortable<T>(
460
487
  }, [changedKey, itemMTSRefMap, resetSwapTrackingRefs])
461
488
 
462
489
  const rootDragEnd = useCallback((sortedKey: string[]) => {
463
- const keyToItemMap = new Map(data.map((item, index) => {
464
- return [keyArray[index], item]
465
- }))
490
+ const { data, onDragEnd } = latest.current
491
+ const keyToItemMap = new Map(data.map(item => [item.getSortingKey(), item]))
466
492
  const sortedData = sortedKey
467
493
  .map(key => keyToItemMap.get(key))
468
494
  .filter((item): item is NonNullable<typeof item> => !!item)
469
495
  onDragEnd?.(sortedData)
470
- }, [data, keyArray, onDragEnd])
496
+ }, [latest])
471
497
 
472
498
  const handleDragEnd = useCallback(
473
499
  (
@@ -475,6 +501,7 @@ export function useSortable<T>(
475
501
  event: MainThread.MouseEvent | MainThread.TouchEvent,
476
502
  ): boolean => {
477
503
  'main thread'
504
+ const keyArray = orderRef.current
478
505
  mtsLog(debugLog, '[event drag end]', event)
479
506
  const sortedKey = sortArray(sortingKey)
480
507
  let orderChanged = sortedKey.length !== keyArray.length
@@ -499,7 +526,14 @@ export function useSortable<T>(
499
526
  }
500
527
  return orderChanged
501
528
  },
502
- [keyArray, resetStatus, resetSwapTrackingRefs, rootDragEnd, sortArray],
529
+ [
530
+ orderRef,
531
+ resetStatus,
532
+ resetSwapTrackingRefs,
533
+ rootDragEnd,
534
+ sortArray,
535
+ debugLog,
536
+ ],
503
537
  )
504
538
 
505
539
  return {