@lynx-js/lynx-ui-swiper 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 (137) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/LICENSE +201 -0
  3. package/README.md +51 -0
  4. package/dist/Swiper/index.d.ts +11 -0
  5. package/dist/Swiper/index.d.ts.map +1 -0
  6. package/dist/Swiper/index.jsx +261 -0
  7. package/dist/Swiper/index.jsx.map +1 -0
  8. package/dist/Swiper/styles.css +47 -0
  9. package/dist/Swiper/styles.css.map +1 -0
  10. package/dist/SwiperItem/index.d.ts +46 -0
  11. package/dist/SwiperItem/index.d.ts.map +1 -0
  12. package/dist/SwiperItem/index.jsx +86 -0
  13. package/dist/SwiperItem/index.jsx.map +1 -0
  14. package/dist/const/index.d.ts +5 -0
  15. package/dist/const/index.d.ts.map +1 -0
  16. package/dist/const/index.jsx +7 -0
  17. package/dist/const/index.jsx.map +1 -0
  18. package/dist/hooks/useAnimate.d.ts +5 -0
  19. package/dist/hooks/useAnimate.d.ts.map +1 -0
  20. package/dist/hooks/useAnimate.jsx +47 -0
  21. package/dist/hooks/useAnimate.jsx.map +1 -0
  22. package/dist/hooks/useAutoPlay.d.ts +16 -0
  23. package/dist/hooks/useAutoPlay.d.ts.map +1 -0
  24. package/dist/hooks/useAutoPlay.jsx +58 -0
  25. package/dist/hooks/useAutoPlay.jsx.map +1 -0
  26. package/dist/hooks/useAxisLock.d.ts +12 -0
  27. package/dist/hooks/useAxisLock.d.ts.map +1 -0
  28. package/dist/hooks/useAxisLock.jsx +58 -0
  29. package/dist/hooks/useAxisLock.jsx.map +1 -0
  30. package/dist/hooks/useBounceConfig.d.ts +12 -0
  31. package/dist/hooks/useBounceConfig.d.ts.map +1 -0
  32. package/dist/hooks/useBounceConfig.jsx +15 -0
  33. package/dist/hooks/useBounceConfig.jsx.map +1 -0
  34. package/dist/hooks/useBounceView.d.ts +17 -0
  35. package/dist/hooks/useBounceView.d.ts.map +1 -0
  36. package/dist/hooks/useBounceView.jsx +16 -0
  37. package/dist/hooks/useBounceView.jsx.map +1 -0
  38. package/dist/hooks/useChange.d.ts +22 -0
  39. package/dist/hooks/useChange.d.ts.map +1 -0
  40. package/dist/hooks/useChange.jsx +53 -0
  41. package/dist/hooks/useChange.jsx.map +1 -0
  42. package/dist/hooks/useDirection.d.ts +13 -0
  43. package/dist/hooks/useDirection.d.ts.map +1 -0
  44. package/dist/hooks/useDirection.jsx +37 -0
  45. package/dist/hooks/useDirection.jsx.map +1 -0
  46. package/dist/hooks/useFirstScreenStyle.d.ts +34 -0
  47. package/dist/hooks/useFirstScreenStyle.d.ts.map +1 -0
  48. package/dist/hooks/useFirstScreenStyle.jsx +63 -0
  49. package/dist/hooks/useFirstScreenStyle.jsx.map +1 -0
  50. package/dist/hooks/useModeConfig.d.ts +14 -0
  51. package/dist/hooks/useModeConfig.d.ts.map +1 -0
  52. package/dist/hooks/useModeConfig.jsx +33 -0
  53. package/dist/hooks/useModeConfig.jsx.map +1 -0
  54. package/dist/hooks/useOffset.d.ts +37 -0
  55. package/dist/hooks/useOffset.d.ts.map +1 -0
  56. package/dist/hooks/useOffset.jsx +362 -0
  57. package/dist/hooks/useOffset.jsx.map +1 -0
  58. package/dist/hooks/useOffsetLimit.d.ts +16 -0
  59. package/dist/hooks/useOffsetLimit.d.ts.map +1 -0
  60. package/dist/hooks/useOffsetLimit.jsx +51 -0
  61. package/dist/hooks/useOffsetLimit.jsx.map +1 -0
  62. package/dist/hooks/useReset.d.ts +16 -0
  63. package/dist/hooks/useReset.d.ts.map +1 -0
  64. package/dist/hooks/useReset.jsx +68 -0
  65. package/dist/hooks/useReset.jsx.map +1 -0
  66. package/dist/hooks/useSwipeCallback.d.ts +14 -0
  67. package/dist/hooks/useSwipeCallback.d.ts.map +1 -0
  68. package/dist/hooks/useSwipeCallback.jsx +40 -0
  69. package/dist/hooks/useSwipeCallback.jsx.map +1 -0
  70. package/dist/hooks/useVelocity.d.ts +14 -0
  71. package/dist/hooks/useVelocity.d.ts.map +1 -0
  72. package/dist/hooks/useVelocity.jsx +62 -0
  73. package/dist/hooks/useVelocity.jsx.map +1 -0
  74. package/dist/hooks/useVelocity_experiment.d.ts +12 -0
  75. package/dist/hooks/useVelocity_experiment.d.ts.map +1 -0
  76. package/dist/hooks/useVelocity_experiment.jsx +38 -0
  77. package/dist/hooks/useVelocity_experiment.jsx.map +1 -0
  78. package/dist/index.d.ts +5 -0
  79. package/dist/index.d.ts.map +1 -0
  80. package/dist/index.jsx +3 -0
  81. package/dist/store/index.d.ts +3 -0
  82. package/dist/store/index.d.ts.map +1 -0
  83. package/dist/store/index.jsx +18 -0
  84. package/dist/store/index.jsx.map +1 -0
  85. package/dist/types/index.d.ts +62 -0
  86. package/dist/types/index.d.ts.map +1 -0
  87. package/dist/types/index.docs.d.ts +448 -0
  88. package/dist/types/index.docs.d.ts.map +1 -0
  89. package/dist/types/index.jsx +9 -0
  90. package/dist/types/index.jsx.map +1 -0
  91. package/dist/utils/animate.d.ts +4 -0
  92. package/dist/utils/animate.d.ts.map +1 -0
  93. package/dist/utils/animate.jsx +29 -0
  94. package/dist/utils/animate.jsx.map +1 -0
  95. package/dist/utils/compareProps.d.ts +2 -0
  96. package/dist/utils/compareProps.d.ts.map +1 -0
  97. package/dist/utils/compareProps.jsx +14 -0
  98. package/dist/utils/compareProps.jsx.map +1 -0
  99. package/dist/utils/customRound.d.ts +10 -0
  100. package/dist/utils/customRound.d.ts.map +1 -0
  101. package/dist/utils/customRound.jsx +9 -0
  102. package/dist/utils/customRound.jsx.map +1 -0
  103. package/dist/utils/index.d.ts +20 -0
  104. package/dist/utils/index.d.ts.map +1 -0
  105. package/dist/utils/index.jsx +55 -0
  106. package/dist/utils/index.jsx.map +1 -0
  107. package/package.json +47 -4
  108. package/src/Swiper/index.tsx +414 -0
  109. package/src/Swiper/styles.css +44 -0
  110. package/src/SwiperItem/index.tsx +205 -0
  111. package/src/const/index.ts +11 -0
  112. package/src/hooks/useAnimate.ts +80 -0
  113. package/src/hooks/useAutoPlay.ts +95 -0
  114. package/src/hooks/useAxisLock.ts +92 -0
  115. package/src/hooks/useBounceConfig.ts +29 -0
  116. package/src/hooks/useBounceView.tsx +50 -0
  117. package/src/hooks/useChange.ts +131 -0
  118. package/src/hooks/useDirection.ts +59 -0
  119. package/src/hooks/useFirstScreenStyle.ts +200 -0
  120. package/src/hooks/useModeConfig.ts +56 -0
  121. package/src/hooks/useOffset.ts +609 -0
  122. package/src/hooks/useOffsetLimit.ts +98 -0
  123. package/src/hooks/useReset.ts +144 -0
  124. package/src/hooks/useSwipeCallback.ts +66 -0
  125. package/src/hooks/useVelocity.ts +83 -0
  126. package/src/hooks/useVelocity_experiment.ts +50 -0
  127. package/src/index.ts +8 -0
  128. package/src/store/index.ts +23 -0
  129. package/src/types/index.docs.ts +465 -0
  130. package/src/types/index.ts +105 -0
  131. package/src/utils/animate.ts +49 -0
  132. package/src/utils/compareProps.ts +54 -0
  133. package/src/utils/customRound.ts +23 -0
  134. package/src/utils/index.ts +117 -0
  135. package/tsconfig.docs.json +7 -0
  136. package/tsconfig.json +9 -0
  137. /package/{index.js → dist/types/index.docs.jsx} +0 -0
@@ -0,0 +1,609 @@
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
+ runOnMainThread,
8
+ useMainThreadRef,
9
+ } from '@lynx-js/react'
10
+
11
+ import { useTapLock } from '@lynx-js/react-use'
12
+ import type { MainThread } from '@lynx-js/types'
13
+
14
+ import { limiter } from '../utils'
15
+ import { useAnimate } from './useAnimate'
16
+ import { useAutoplay } from './useAutoPlay'
17
+ import { useAxisLock } from './useAxisLock'
18
+ import { useSwipeCallback } from './useSwipeCallback'
19
+ import { useVelocity } from './useVelocity'
20
+ import { SwipeDirection } from '../types'
21
+ import type {
22
+ BounceConfig,
23
+ CompoundModeConfig,
24
+ OffsetLimitResult,
25
+ ResetOptions,
26
+ SwipeToOptions,
27
+ SwiperProps,
28
+ onBounceParams,
29
+ } from '../types'
30
+ import { useDirection } from './useDirection'
31
+
32
+ interface UseOffsetOpts extends
33
+ Required<
34
+ Pick<
35
+ SwiperProps<unknown>,
36
+ | 'loop'
37
+ | 'duration'
38
+ | 'initialIndex'
39
+ | 'containerWidth'
40
+ | 'autoPlay'
41
+ | 'autoPlayInterval'
42
+ | 'consumeSlideEvent'
43
+ | 'RTL'
44
+ >
45
+ >
46
+ {
47
+ dataCount: number
48
+ size: number
49
+ spaceBetween: number
50
+ easing: NonNullable<SwiperProps<unknown>['main-thread:easing']>
51
+ modeConfig: CompoundModeConfig
52
+ enableBounce: boolean
53
+ startBounceItemWidth: NonNullable<BounceConfig['startBounceItemWidth']>
54
+ endBounceItemWidth: NonNullable<BounceConfig['endBounceItemWidth']>
55
+ onStartBounceItemBounce: BounceConfig['onStartBounceItemBounce']
56
+ onEndBounceItemBounce: BounceConfig['onStartBounceItemBounce']
57
+ experimentalHorizontalSwipeOnly: boolean
58
+ onSwipeStopMT: () => void
59
+ onSwipeStartMT: () => void
60
+ offsetLimit: OffsetLimitResult
61
+ }
62
+
63
+ // TODO(@wangyang.ryan) Use Function from utils.
64
+ // MTS imported from other files has bug now.
65
+ function customRound(num: number, threshold = 0.5) {
66
+ 'main thread'
67
+ const decimal = num - Math.floor(num)
68
+
69
+ // Check if the decimal part is greater than or equal to 0.9
70
+ if (decimal >= threshold) {
71
+ return Math.ceil(num)
72
+ } else {
73
+ return Math.floor(num)
74
+ }
75
+ }
76
+
77
+ function rubberEffect(rubberDelta: number, bounceWidth: number): number {
78
+ 'main thread'
79
+
80
+ if (rubberDelta === 0 || bounceWidth === 0) {
81
+ return 0
82
+ }
83
+
84
+ // Assumes the bounce should max out when the user swipes 2x the bounceWidth.
85
+ const swipeLimit = bounceWidth * 2.0
86
+ const scaleFactor = 1.5 // (2.0 + 1.0) / 2.0
87
+
88
+ const absDelta = Math.abs(rubberDelta)
89
+ const effectiveDelta = Math.min(absDelta, swipeLimit)
90
+
91
+ const bounce = effectiveDelta / (effectiveDelta / bounceWidth + 1.0)
92
+
93
+ return Math.sign(rubberDelta) * bounce * scaleFactor
94
+ }
95
+
96
+ /**
97
+ * This hook are used to maintain a virtual offset, which does not necessarily reflect the actual
98
+ * location of the swiper
99
+ */
100
+ function useOffset(
101
+ {
102
+ loop,
103
+ duration,
104
+ size,
105
+ spaceBetween,
106
+ easing,
107
+ dataCount,
108
+ initialIndex,
109
+ autoPlay,
110
+ autoPlayInterval,
111
+ offsetLimit,
112
+ enableBounce,
113
+ startBounceItemWidth,
114
+ endBounceItemWidth,
115
+ onStartBounceItemBounce,
116
+ onEndBounceItemBounce,
117
+ experimentalHorizontalSwipeOnly,
118
+ onSwipeStartMT,
119
+ onSwipeStopMT,
120
+ consumeSlideEvent,
121
+ RTL,
122
+ }: UseOffsetOpts,
123
+ onOffsetUpdate: (offset: number, direction: SwipeDirection) => void,
124
+ ) {
125
+ // fullSize contains size and spaceBetween
126
+ const fullSize = size + spaceBetween
127
+ function getInitialOffset() {
128
+ return limiter(
129
+ -fullSize * initialIndex,
130
+ dataCount,
131
+ size,
132
+ spaceBetween,
133
+ loop,
134
+ offsetLimit,
135
+ )
136
+ }
137
+
138
+ const touchStartRef = useMainThreadRef<number>(0)
139
+ const touchStartCrossAxisRef = useMainThreadRef<number>(0)
140
+ const lastScrollOffsetRef = useMainThreadRef<number>(getInitialOffset())
141
+ const offsetRef = useMainThreadRef<number>(getInitialOffset())
142
+ // To record the previous index before offset change
143
+ const prevIndexRef = useMainThreadRef<number>(initialIndex)
144
+ const { velocityTouchMove, velocityTouchStart, getVelocity } = useVelocity({
145
+ RTL,
146
+ })
147
+ const { cancel: cancelAnimation, animate } = useAnimate()
148
+
149
+ const reachedBounceRef = useMainThreadRef(false)
150
+ const bounceDeltaRef = useMainThreadRef(0)
151
+
152
+ const {
153
+ directionRef,
154
+ handleTouchStart: directionTouchStart,
155
+ handleTouchMove: directionTouchMove,
156
+ handleTouchEnd: directionTouchEnd,
157
+ overrideDirection,
158
+ } = useDirection({
159
+ RTL,
160
+ })
161
+
162
+ function getCurrentIndex() {
163
+ 'main thread'
164
+ // Guard against dataCount=0 to prevent NaN from modulo by zero
165
+ if (dataCount === 0) {
166
+ return 0
167
+ }
168
+ const totalWidth = fullSize * dataCount
169
+ const currentIndex = ((-offsetRef.current + totalWidth) % totalWidth)
170
+ / fullSize
171
+ return currentIndex
172
+ }
173
+
174
+ // Offset should only be updated by this function.
175
+ function setOffset(offset: number) {
176
+ 'main thread'
177
+ if (isNaN(offset)) {
178
+ throw new Error('calcBounceOffset: invalid offset')
179
+ }
180
+ offsetRef.current = offset
181
+ prevIndexRef.current = getCurrentIndex()
182
+ onOffsetUpdate(offset, directionRef.current)
183
+ }
184
+
185
+ function calcLimitCompact(offset: number, options?: {
186
+ type: 'prev' | 'next'
187
+ }): {
188
+ offset: number
189
+ reachingLimit: -1 | 0 | 1
190
+ } {
191
+ 'main thread'
192
+ let reachingLimit: -1 | 0 | 1 = 0
193
+ let finalOffset = offset
194
+ if (dataCount === 0) {
195
+ if (options?.type === 'prev') {
196
+ return { offset: 0, reachingLimit: -1 }
197
+ }
198
+ return { offset: 0, reachingLimit: 1 }
199
+ }
200
+ if (!loop) {
201
+ if (offset >= -offsetLimit.startLimit) {
202
+ reachingLimit = -1
203
+ finalOffset = -offsetLimit.startLimit
204
+ } else if (offset <= -fullSize * (dataCount - 1) + offsetLimit.endLimit) {
205
+ reachingLimit = 1
206
+ finalOffset = -fullSize * (dataCount - 1) + offsetLimit.endLimit
207
+ }
208
+ }
209
+ return { offset: finalOffset, reachingLimit }
210
+ }
211
+
212
+ function calcBounceOffsetAndLimit(offset: number) {
213
+ 'main thread'
214
+ const { offset: limitOffset, reachingLimit } = calcLimitCompact(offset)
215
+
216
+ if (enableBounce && reachingLimit) {
217
+ const bounceDelta = offset - limitOffset
218
+ const bounceItemWidth = reachingLimit === -1
219
+ ? startBounceItemWidth
220
+ : (offsetLimit.isNotEnoughForScreen ? 0 : endBounceItemWidth)
221
+ reachedBounceRef.current = true
222
+ bounceDeltaRef.current = rubberEffect(bounceDelta, bounceItemWidth)
223
+ return limitOffset + bounceDeltaRef.current
224
+ }
225
+ return limitOffset
226
+ }
227
+
228
+ // We use rounding as threshold of when will the swiper to apply paging.
229
+ // When rounding is 0.7, then index 1.6 will be paged to 1, and 1.8 will be paged to 2
230
+ function calcPaging(offset: number, rounding = 0.5) {
231
+ 'main thread'
232
+ const { offset: limitOffset, reachingLimit } = calcLimitCompact(offset)
233
+ if (reachingLimit) {
234
+ return limitOffset
235
+ }
236
+
237
+ return customRound(-offset / fullSize, rounding) * -fullSize
238
+ }
239
+
240
+ function calcLoop(start: number, end: number) {
241
+ 'main thread'
242
+ let startOffset = start
243
+ let finalOffset = end
244
+ if (dataCount === 0) {
245
+ return { offset: 0, finalOffset: 0 }
246
+ }
247
+ const totalWidth = fullSize * dataCount
248
+ if (loop) {
249
+ if (finalOffset < -totalWidth + fullSize) {
250
+ // If go beyond last item, like n + 1 item, let the destination be 1
251
+ finalOffset = finalOffset + totalWidth
252
+ startOffset = startOffset + totalWidth
253
+ } else if (finalOffset > 0) {
254
+ // If go before first item, like -1 item, let the destination be n - 1
255
+ finalOffset = finalOffset - totalWidth
256
+ startOffset = startOffset - totalWidth
257
+ }
258
+ }
259
+ return {
260
+ offset: startOffset,
261
+ finalOffset,
262
+ }
263
+ }
264
+
265
+ const {
266
+ handleTouchMove: swipeCallbackTouchMove,
267
+ handleTouchStart: swipeCallbackTouchStart,
268
+ setSwipeEndMT,
269
+ setSwipeStartMT,
270
+ } = useSwipeCallback({
271
+ onSwipeStartMT,
272
+ onSwipeStopMT,
273
+ })
274
+
275
+ const {
276
+ handleTouchStart: axisLockTouchStart,
277
+ handleTouchMove: axisLockTouchMove,
278
+ handleTouchEnd: axisLockTouchEnd,
279
+ handleVelocity: axisLockVelocity,
280
+ } = useAxisLock({
281
+ consumeSlideEvent,
282
+ experimentalHorizontalSwipeOnly,
283
+ })
284
+
285
+ const {
286
+ handleTouchStart: tapLockTouchStart,
287
+ handleTouchMove: tapLockTouchMove,
288
+ handleTouchEnd: tapLockTouchEnd,
289
+ } = useTapLock()
290
+
291
+ function easingTo(start: number, end: number, onFinished?: () => void) {
292
+ 'main thread'
293
+ function onProgress(progress: number) {
294
+ const interpolatedProgress = easing(progress / 100)
295
+ const animeOffset = (end - start) * interpolatedProgress + start
296
+
297
+ setOffset(animeOffset)
298
+ }
299
+
300
+ animate(duration, onProgress, onFinished)
301
+ }
302
+
303
+ function hasNextMTS() {
304
+ 'main thread'
305
+ const offset = offsetRef.current
306
+ const { reachingLimit } = calcLimitCompact(offset)
307
+
308
+ return reachingLimit !== 1
309
+ }
310
+
311
+ function hasPrevMTS() {
312
+ 'main thread'
313
+ const offset = offsetRef.current
314
+ const { reachingLimit } = calcLimitCompact(offset)
315
+
316
+ return reachingLimit !== -1
317
+ }
318
+
319
+ function swipeToMTS(index: number, options?: SwipeToOptions) {
320
+ 'main thread'
321
+ if (dataCount === 0) {
322
+ setSwipeEndMT()
323
+ return
324
+ }
325
+
326
+ const finalIndex = Math.max(Math.min(index, dataCount - 1), 0)
327
+ const currentIndex = getCurrentIndex()
328
+ const { offset: finalOffset } = calcLimitCompact(-finalIndex * fullSize)
329
+ setSwipeStartMT()
330
+
331
+ if (finalIndex > currentIndex) {
332
+ overrideDirection(SwipeDirection.NORMAL)
333
+ } else if (finalIndex < currentIndex) {
334
+ overrideDirection(SwipeDirection.REVERT)
335
+ } else {
336
+ overrideDirection(SwipeDirection.NONE)
337
+ }
338
+
339
+ if (options?.animate) {
340
+ easingTo(offsetRef.current, finalOffset, () => {
341
+ if (options?.onFinished) {
342
+ options.onFinished()
343
+ }
344
+ setSwipeEndMT()
345
+ })
346
+ } else {
347
+ setOffset(finalOffset)
348
+ setSwipeEndMT()
349
+ }
350
+ }
351
+
352
+ function swipeNextMTS(options?: SwipeToOptions) {
353
+ 'main thread'
354
+
355
+ if (!hasNextMTS()) {
356
+ setSwipeEndMT()
357
+ return
358
+ }
359
+
360
+ setSwipeStartMT()
361
+ let offset = offsetRef.current
362
+ let finalOffset = calcPaging(offset - fullSize, 0.95)
363
+
364
+ if (loop) {
365
+ const result = calcLoop(offset, finalOffset)
366
+ offset = result.offset
367
+ finalOffset = result.finalOffset
368
+ } else {
369
+ const result = calcLimitCompact(finalOffset)
370
+ finalOffset = result.offset
371
+ }
372
+
373
+ overrideDirection(SwipeDirection.NORMAL)
374
+
375
+ if (options?.animate === false) {
376
+ setOffset(finalOffset)
377
+ setSwipeEndMT()
378
+ } else {
379
+ easingTo(offset, finalOffset, () => {
380
+ if (options?.onFinished) {
381
+ options.onFinished()
382
+ }
383
+ setSwipeEndMT()
384
+ })
385
+ }
386
+ }
387
+
388
+ function swipePrevMTS(options?: SwipeToOptions) {
389
+ 'main thread'
390
+
391
+ if (!hasPrevMTS()) {
392
+ setSwipeEndMT()
393
+ return
394
+ }
395
+
396
+ setSwipeStartMT()
397
+ let offset = offsetRef.current
398
+ let finalOffset = calcPaging(offset + fullSize, 0.05)
399
+ if (loop) {
400
+ const result = calcLoop(offset, finalOffset)
401
+ offset = result.offset
402
+ finalOffset = result.finalOffset
403
+ } else {
404
+ const result = calcLimitCompact(finalOffset)
405
+ finalOffset = result.offset
406
+ }
407
+
408
+ overrideDirection(SwipeDirection.REVERT)
409
+
410
+ if (options?.animate === false) {
411
+ setOffset(finalOffset)
412
+ setSwipeEndMT()
413
+ } else {
414
+ easingTo(offset, finalOffset, () => {
415
+ if (options?.onFinished) {
416
+ options.onFinished()
417
+ }
418
+ setSwipeEndMT()
419
+ })
420
+ }
421
+ }
422
+
423
+ function swipePrev(options?: SwipeToOptions) {
424
+ runOnMainThread(swipePrevMTS)(options)
425
+ }
426
+
427
+ function swipeNext(options?: SwipeToOptions) {
428
+ runOnMainThread(swipeNextMTS)(options)
429
+ }
430
+
431
+ function swipeTo(index: number, options?: SwipeToOptions) {
432
+ runOnMainThread(swipeToMTS)(index, options)
433
+ }
434
+
435
+ function handleOnBounce(params: onBounceParams) {
436
+ if (params.type === 'start' && onStartBounceItemBounce) {
437
+ onStartBounceItemBounce(params)
438
+ } else if (params.type === 'end' && onEndBounceItemBounce) {
439
+ onEndBounceItemBounce(params)
440
+ }
441
+ }
442
+
443
+ function handleBounceCallback(offset: number) {
444
+ 'main thread'
445
+ if (reachedBounceRef.current) {
446
+ runOnBackground(handleOnBounce)({
447
+ type: offset > 0 ? 'start' : 'end',
448
+ offset: Math.abs(bounceDeltaRef.current),
449
+ })
450
+ reachedBounceRef.current = false
451
+ bounceDeltaRef.current = 0
452
+ }
453
+ }
454
+
455
+ const {
456
+ pauseMT: pauseAutoPlayMT,
457
+ startMT: startAutoPlayMT,
458
+ } = useAutoplay({
459
+ autoPlay,
460
+ autoPlayInterval,
461
+ prevMT: swipePrevMTS,
462
+ nextMT: swipeNextMTS,
463
+ duration,
464
+ dataCount,
465
+ })
466
+
467
+ function handleVelocity() {
468
+ 'main thread'
469
+ const VELOCITY_THRESHOLD = 300
470
+
471
+ if (axisLockVelocity()) {
472
+ return false
473
+ }
474
+
475
+ const { velocity: velocityValue, direction } = getVelocity()
476
+ if (Math.abs(velocityValue) > VELOCITY_THRESHOLD) {
477
+ overrideDirection(direction)
478
+ if (direction === SwipeDirection.NORMAL && hasNextMTS()) {
479
+ swipeNextMTS({
480
+ onFinished: () => {
481
+ startAutoPlayMT()
482
+ },
483
+ })
484
+ return true
485
+ } else if (direction === SwipeDirection.REVERT && hasPrevMTS()) {
486
+ swipePrevMTS({
487
+ onFinished: () => {
488
+ startAutoPlayMT()
489
+ },
490
+ })
491
+ return true
492
+ }
493
+ }
494
+ return false
495
+ }
496
+
497
+ function handleTouchStart(event: MainThread.TouchEvent) {
498
+ 'main thread'
499
+ lastScrollOffsetRef.current = offsetRef.current
500
+
501
+ touchStartRef.current = event.detail.x
502
+
503
+ touchStartCrossAxisRef.current = event.detail.y
504
+ axisLockTouchStart(event)
505
+ velocityTouchStart()
506
+ tapLockTouchStart(event)
507
+ cancelAnimation()
508
+ swipeCallbackTouchStart(event)
509
+ directionTouchStart(event)
510
+ pauseAutoPlayMT()
511
+ }
512
+
513
+ function handleTouchMove(event: MainThread.TouchEvent) {
514
+ 'main thread'
515
+
516
+ // Guard against empty data to prevent state corruption
517
+ if (dataCount === 0) {
518
+ return
519
+ }
520
+
521
+ if (axisLockTouchMove(event) || tapLockTouchMove(event)) {
522
+ return
523
+ }
524
+
525
+ const sign = RTL ? -1 : 1
526
+
527
+ let offsetInner = sign * (event.detail.x - touchStartRef.current)
528
+ + lastScrollOffsetRef.current
529
+ offsetInner = calcBounceOffsetAndLimit(offsetInner)
530
+ setOffset(offsetInner)
531
+ velocityTouchMove(event)
532
+ swipeCallbackTouchMove(event)
533
+ directionTouchMove(event)
534
+ }
535
+
536
+ function handleTouchEnd(event: MainThread.TouchEvent) {
537
+ 'main thread'
538
+ let offset = offsetRef.current
539
+
540
+ handleBounceCallback(offset)
541
+
542
+ if (handleVelocity()) {
543
+ return
544
+ }
545
+ axisLockTouchEnd()
546
+ directionTouchEnd(event)
547
+
548
+ let finalOffset = calcPaging(offset)
549
+ if (loop) {
550
+ const result = calcLoop(offset, finalOffset)
551
+ offset = result.offset
552
+ finalOffset = result.finalOffset
553
+ } else {
554
+ const result = calcLimitCompact(finalOffset)
555
+ finalOffset = result.offset
556
+ }
557
+
558
+ tapLockTouchEnd(event)
559
+ easingTo(offset, finalOffset, () => {
560
+ setSwipeEndMT()
561
+ startAutoPlayMT()
562
+ })
563
+ }
564
+
565
+ function resetOffsetMT(resetOptions: ResetOptions) {
566
+ 'main thread'
567
+ cancelAnimation()
568
+ if (dataCount === 0) {
569
+ swipeToMTS(0)
570
+ return
571
+ }
572
+ if (resetOptions.fullReset) {
573
+ swipeToMTS(resetOptions.resetIndex!, {
574
+ animate: false,
575
+ })
576
+ } else {
577
+ const currentIndex = prevIndexRef.current
578
+ // Guard against NaN from previous empty data state
579
+ if (isNaN(currentIndex)) {
580
+ swipeToMTS(0, {
581
+ animate: false,
582
+ })
583
+ } else {
584
+ swipeToMTS(currentIndex, {
585
+ animate: false,
586
+ })
587
+ }
588
+ }
589
+ }
590
+
591
+ function cancelAnimationJS() {
592
+ runOnMainThread(cancelAnimation)()
593
+ }
594
+
595
+ return {
596
+ startAutoPlayMT,
597
+ offsetRef,
598
+ handleTouchStart,
599
+ handleTouchMove,
600
+ handleTouchEnd,
601
+ swipeTo,
602
+ swipeNext,
603
+ swipePrev,
604
+ resetOffsetMT,
605
+ cancelAnimationJS,
606
+ }
607
+ }
608
+
609
+ export { useOffset }
@@ -0,0 +1,98 @@
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 { useMemo } from '@lynx-js/react'
6
+
7
+ import type {
8
+ CompoundModeConfig,
9
+ OffsetLimitResult,
10
+ SwiperProps,
11
+ } from '../types'
12
+
13
+ interface IOffsetLimit extends
14
+ Required<
15
+ Pick<SwiperProps<unknown>, 'loop' | 'itemWidth' | 'containerWidth'>
16
+ >
17
+ {
18
+ offsetLimit: SwiperProps<unknown>['offsetLimit']
19
+ modeConfig: CompoundModeConfig
20
+ dataCount: number
21
+ spaceBetween: number
22
+ }
23
+
24
+ /**
25
+ * `offsetLimit` is used to limit the range of offset. Useful for when setting `align='start'`,
26
+ * the last item should align with right edge, instead of align to the left.
27
+ * This can achieved by setting offsetLimit to `[0, containerWidth - itemWidth]`, which basically
28
+ * prevent further scroll if the last item is bond to right edge.
29
+ */
30
+ export function useOffsetLimit({
31
+ offsetLimit,
32
+ loop,
33
+ modeConfig,
34
+ itemWidth,
35
+ containerWidth,
36
+ spaceBetween,
37
+ dataCount,
38
+ }: IOffsetLimit): OffsetLimitResult {
39
+ const finalOffsetLimit = useMemo<OffsetLimitResult>(() => {
40
+ const epsilon = 0.000001
41
+ const fullSize = itemWidth + spaceBetween
42
+ const totalContentWidth = fullSize * dataCount - spaceBetween
43
+
44
+ if (loop) {
45
+ return {
46
+ startLimit: 0,
47
+ endLimit: 0,
48
+ isNotEnoughForScreen: false,
49
+ }
50
+ } else if (offsetLimit) {
51
+ return {
52
+ startLimit: offsetLimit[0],
53
+ endLimit: offsetLimit[1],
54
+ isNotEnoughForScreen: false,
55
+ }
56
+ } else {
57
+ // If SwiperItem can not occupy the screen, do not apply offsetLimit.
58
+ if (totalContentWidth <= containerWidth + epsilon) {
59
+ return {
60
+ startLimit: 0,
61
+ // Lock both start/end to the same offset to disable scroll.
62
+ endLimit: Math.max(fullSize * (dataCount - 1), 0),
63
+ isNotEnoughForScreen: true,
64
+ }
65
+ }
66
+
67
+ if (modeConfig.mode === 'normal' && modeConfig.align === 'start') {
68
+ return {
69
+ startLimit: 0,
70
+ endLimit: containerWidth - itemWidth,
71
+ isNotEnoughForScreen: false,
72
+ }
73
+ } else if (modeConfig.mode === 'normal' && modeConfig.align === 'end') {
74
+ return {
75
+ startLimit: containerWidth - itemWidth,
76
+ endLimit: 0,
77
+ isNotEnoughForScreen: false,
78
+ }
79
+ }
80
+ return {
81
+ startLimit: 0,
82
+ endLimit: 0,
83
+ isNotEnoughForScreen: false,
84
+ }
85
+ }
86
+ }, [
87
+ dataCount,
88
+ offsetLimit?.[0],
89
+ offsetLimit?.[1],
90
+ modeConfig,
91
+ loop,
92
+ itemWidth,
93
+ spaceBetween,
94
+ containerWidth,
95
+ ])
96
+
97
+ return finalOffsetLimit
98
+ }