@lynx-js/lynx-ui-swiper 3.142.0 → 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 +8 -0
- package/SKILL.md +266 -0
- package/package.json +6 -5
- package/tsconfig.docs.json +0 -7
- package/tsconfig.json +0 -14
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# @lynx-js/lynx-ui-swiper
|
|
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
|
+
|
|
3
11
|
## 3.142.0
|
|
4
12
|
|
|
5
13
|
### Patch Changes
|
package/SKILL.md
ADDED
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
# lynx-ui-swiper SKILL
|
|
2
|
+
|
|
3
|
+
`Swiper` is a high-performance, fully customizable carousel. It supports horizontal swiping, looping, auto-play, RTL, edge bounces, and both built-in and custom layouts/animations. This guide is written for AI code agents to generate correct, production-ready code with minimal back-and-forth.
|
|
4
|
+
|
|
5
|
+
## 1. Core Capabilities
|
|
6
|
+
|
|
7
|
+
- Horizontal swipe with inertial paging and configurable `duration` and easing
|
|
8
|
+
- Looping with `loop` and `loopDuplicateCount`
|
|
9
|
+
- Auto Play with `autoPlay` and `autoPlayInterval`
|
|
10
|
+
- Two layout modes: `mode='normal'` and `mode='custom'`
|
|
11
|
+
- Custom per-item animation via `main-thread:customAnimation` (+ `customAnimationFirstScreen` for first screen rendering)
|
|
12
|
+
- Edge bounce views with `bounceConfig` and release callbacks
|
|
13
|
+
- RTL support via `RTL` (`true` or `'lynx-rtl'`)
|
|
14
|
+
- Fine-grained touch-angle control via `consumeSlideEvent`, and event coordination via `blockNativeEvent`
|
|
15
|
+
- Imperative control with `SwiperRef` (`swipeNext`, `swipePrev`, `swipeTo`, `cancelAnimation`)
|
|
16
|
+
- Explicit viewport sizing through numeric `containerWidth` in px
|
|
17
|
+
|
|
18
|
+
## 2. AI Coding Guide
|
|
19
|
+
|
|
20
|
+
### Minimal Usable Example
|
|
21
|
+
|
|
22
|
+
Each `<Swiper>` must provide `data`, `itemWidth`, and `containerWidth`, and render children via a function that returns a `<SwiperItem>`.
|
|
23
|
+
|
|
24
|
+
This example uses a 320px-wide wrapper and 300px-wide items.
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
import { Swiper, SwiperItem } from '@lynx-js/lynx-ui'
|
|
28
|
+
|
|
29
|
+
const data = ['red', 'green', 'blue']
|
|
30
|
+
const CONTAINER_WIDTH = 320
|
|
31
|
+
|
|
32
|
+
function Example() {
|
|
33
|
+
return (
|
|
34
|
+
<view style={{ width: `${CONTAINER_WIDTH}px` }}>
|
|
35
|
+
<Swiper
|
|
36
|
+
data={data}
|
|
37
|
+
itemWidth={300}
|
|
38
|
+
containerWidth={CONTAINER_WIDTH}
|
|
39
|
+
style={{ borderRadius: '12px' }}
|
|
40
|
+
>
|
|
41
|
+
{({ item, index }) => (
|
|
42
|
+
<SwiperItem>
|
|
43
|
+
<view
|
|
44
|
+
style={{ width: '100%', height: '200px', backgroundColor: item }}
|
|
45
|
+
>
|
|
46
|
+
<text>Item {index}</text>
|
|
47
|
+
</view>
|
|
48
|
+
</SwiperItem>
|
|
49
|
+
)}
|
|
50
|
+
</Swiper>
|
|
51
|
+
</view>
|
|
52
|
+
)
|
|
53
|
+
}
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Container Width
|
|
57
|
+
|
|
58
|
+
- Always pass `containerWidth` explicitly as a number in px matching the available viewport width. `itemWidth` is the width of each slide; the two widths may differ to show neighboring slides.
|
|
59
|
+
- For a parent spanning the screen with 16px padding on each side, use `containerWidth={screenWidth - 32}`. For a card or column, use its available width. Measure dynamically sized containers and update this value when their layout changes.
|
|
60
|
+
- Use the same viewport width for custom animation centering and any `offsetLimit` calculation. The snippets below use a 320px viewport; adapt it to the actual layout.
|
|
61
|
+
|
|
62
|
+
### Styling
|
|
63
|
+
|
|
64
|
+
- Use `Swiper.style` for root visuals such as background, borders, border radius, and overflow.
|
|
65
|
+
- Set viewport and slide dimensions through `containerWidth`, `itemWidth`, and `itemHeight`, and direction through `RTL`.
|
|
66
|
+
- Apply CSS classes and outer padding to a surrounding `<view>`. Style slide content on a child `<view>` inside `SwiperItem`.
|
|
67
|
+
|
|
68
|
+
### Render Props Mechanics
|
|
69
|
+
|
|
70
|
+
- `<Swiper>` calls your children function once per item with `{ item, index }`.
|
|
71
|
+
- You must return a single `<SwiperItem>` as the root of that function; place your content inside it.
|
|
72
|
+
- Use `index` for app content such as labels, item lookup, and indicators.
|
|
73
|
+
|
|
74
|
+
### Recommended Prompt Formula
|
|
75
|
+
|
|
76
|
+
> Scenario + Layout Mode/Align + Sizes (`itemWidth`, `containerWidth`) + Data + Interaction (loop, auto-play, bounces, RTL) + Callbacks + Optional custom animation
|
|
77
|
+
|
|
78
|
+
Examples:
|
|
79
|
+
|
|
80
|
+
- “Create a carousel with `modeConfig={{ align: 'center', spaceBetween: 16 }}`, 5 items, `itemWidth=300`, `containerWidth=320`, an indicator, and Prev/Next buttons.”
|
|
81
|
+
- “Implement looped auto-play Swiper (`autoPlayInterval=2500`), align `start`, and an end bounce for ‘Show More’.”
|
|
82
|
+
- “Build a `mode='custom'` Swiper with scale and translateX animation using `main-thread:customAnimation`.”
|
|
83
|
+
|
|
84
|
+
## 3. Use Cases & Best Practices
|
|
85
|
+
|
|
86
|
+
- Basic Horizontal: `mode='normal'` with `modeConfig.align` (`start`/`center`/`end`) and optional `spaceBetween`.
|
|
87
|
+
- Loop & Auto Play: set `loop={true}` and `autoPlay={true}` with `autoPlayInterval`.
|
|
88
|
+
- Bounces: configure `bounceConfig` with `startBounceItem`/`endBounceItem` and widths; release callbacks fire with `{ type, offset }`. Bounces are ignored when `loop=true`.
|
|
89
|
+
- Custom Animation: switch to `mode='custom'` and provide `main-thread:customAnimation(value, index) => style`. Duplicate this logic in `customAnimationFirstScreen` for first-screen rendering.
|
|
90
|
+
- RTL: set `RTL={true}` or `RTL={'lynx-rtl'}`. The latter applies Lynx’s `direction: lynx-rtl` explicitly.
|
|
91
|
+
- In Scroll Containers: when inside `scroll-view` or other vertical scrollers, set `experimentalHorizontalSwipeOnly={true}` and, if native events are being swallowed, set `blockNativeEvent={true}`; tune `consumeSlideEvent` if needed.
|
|
92
|
+
- Indicators & Controls: derive `current` from `onChange`, render an external indicator, and use `SwiperRef` to control navigation.
|
|
93
|
+
- Container Sizing: use the available viewport width as described in Container Width above; use `style={{ overflow: 'visible' }}` if centered items need to bleed.
|
|
94
|
+
|
|
95
|
+
### Loop + Auto Play Example
|
|
96
|
+
|
|
97
|
+
```tsx
|
|
98
|
+
<Swiper
|
|
99
|
+
data={['red', 'green', 'yellow', 'purple']}
|
|
100
|
+
itemWidth={315}
|
|
101
|
+
itemHeight={220}
|
|
102
|
+
containerWidth={320}
|
|
103
|
+
loop
|
|
104
|
+
autoPlay
|
|
105
|
+
autoPlayInterval={2000}
|
|
106
|
+
mode='normal'
|
|
107
|
+
modeConfig={{ align: 'start', spaceBetween: 8 }}
|
|
108
|
+
experimentalHorizontalSwipeOnly
|
|
109
|
+
>
|
|
110
|
+
{({ item, index }) => (
|
|
111
|
+
<SwiperItem>
|
|
112
|
+
<view style={{ width: '100%', height: '100%', backgroundColor: item }} />
|
|
113
|
+
<text>Number.{index}</text>
|
|
114
|
+
</SwiperItem>
|
|
115
|
+
)}
|
|
116
|
+
</Swiper>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Bounces Example
|
|
120
|
+
|
|
121
|
+
Note: `startBounceItemWidth` / `endBounceItemWidth` default to `50`. This example sets `endBounceItemWidth` to `100` to demonstrate a larger overscroll resistance range.
|
|
122
|
+
|
|
123
|
+
```tsx
|
|
124
|
+
<Swiper
|
|
125
|
+
data={colors}
|
|
126
|
+
itemWidth={250}
|
|
127
|
+
itemHeight={200}
|
|
128
|
+
containerWidth={320}
|
|
129
|
+
mode='normal'
|
|
130
|
+
bounceConfig={{
|
|
131
|
+
enable: true,
|
|
132
|
+
endBounceItemWidth: 100,
|
|
133
|
+
endBounceItem: (
|
|
134
|
+
<view style='display: linear; linear-orientation: vertical; height: 100%; width: 30px;'>
|
|
135
|
+
<text>Show More</text>
|
|
136
|
+
</view>
|
|
137
|
+
),
|
|
138
|
+
onEndBounceItemBounce: ({ type, offset }) => {
|
|
139
|
+
console.log('bounce', type, offset)
|
|
140
|
+
},
|
|
141
|
+
}}
|
|
142
|
+
>
|
|
143
|
+
{({ index }) => (
|
|
144
|
+
<SwiperItem>
|
|
145
|
+
{/* content */}
|
|
146
|
+
</SwiperItem>
|
|
147
|
+
)}
|
|
148
|
+
</Swiper>
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Custom Animation Example (`mode='custom'`)
|
|
152
|
+
|
|
153
|
+
```tsx
|
|
154
|
+
import { interpolate, interpolateJS } from '@lynx-js/lynx-ui'
|
|
155
|
+
|
|
156
|
+
const ITEM_WIDTH = 250
|
|
157
|
+
const CONTAINER_WIDTH = 320
|
|
158
|
+
|
|
159
|
+
function customAnimation(value: number) {
|
|
160
|
+
'main thread'
|
|
161
|
+
const scale = interpolate(value, [-1, 0, 1], [0.8, 1, 0.8])
|
|
162
|
+
const centerOffset = (CONTAINER_WIDTH - ITEM_WIDTH) / 2
|
|
163
|
+
const translateX = interpolate(value, [-1, 0, 1], [
|
|
164
|
+
-ITEM_WIDTH + centerOffset,
|
|
165
|
+
centerOffset,
|
|
166
|
+
ITEM_WIDTH + centerOffset,
|
|
167
|
+
], 'extend')
|
|
168
|
+
return {
|
|
169
|
+
transform: `translateX(${translateX}px) scale(${scale})`,
|
|
170
|
+
'transform-origin': 'center',
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
function customAnimationFirstScreen(value: number) {
|
|
175
|
+
const scale = interpolateJS(value, [-1, 0, 1], [0.8, 1, 0.8])
|
|
176
|
+
const centerOffset = (CONTAINER_WIDTH - ITEM_WIDTH) / 2
|
|
177
|
+
const translateX = interpolateJS(value, [-1, 0, 1], [
|
|
178
|
+
-ITEM_WIDTH + centerOffset,
|
|
179
|
+
centerOffset,
|
|
180
|
+
ITEM_WIDTH + centerOffset,
|
|
181
|
+
], 'extend')
|
|
182
|
+
return {
|
|
183
|
+
transform: `translateX(${translateX}px) scale(${scale})`,
|
|
184
|
+
'transform-origin': 'center',
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
<Swiper
|
|
189
|
+
data={colors}
|
|
190
|
+
itemWidth={ITEM_WIDTH}
|
|
191
|
+
itemHeight={200}
|
|
192
|
+
containerWidth={CONTAINER_WIDTH}
|
|
193
|
+
mode='custom'
|
|
194
|
+
main-thread:customAnimation={customAnimation}
|
|
195
|
+
customAnimationFirstScreen={customAnimationFirstScreen}
|
|
196
|
+
>
|
|
197
|
+
{({ index }) => (
|
|
198
|
+
<SwiperItem>
|
|
199
|
+
{/* content */}
|
|
200
|
+
</SwiperItem>
|
|
201
|
+
)}
|
|
202
|
+
</Swiper>
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### RTL Example
|
|
206
|
+
|
|
207
|
+
```tsx
|
|
208
|
+
<Swiper
|
|
209
|
+
data={items}
|
|
210
|
+
itemWidth={300}
|
|
211
|
+
itemHeight={200}
|
|
212
|
+
containerWidth={320}
|
|
213
|
+
mode='normal'
|
|
214
|
+
modeConfig={{ align: 'start', spaceBetween: 8 }}
|
|
215
|
+
RTL={true}
|
|
216
|
+
>
|
|
217
|
+
{({ index }) => (
|
|
218
|
+
<SwiperItem>
|
|
219
|
+
{/* content */}
|
|
220
|
+
</SwiperItem>
|
|
221
|
+
)}
|
|
222
|
+
</Swiper>
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
## 4. Props Highlights
|
|
226
|
+
|
|
227
|
+
- `data`: array of items to render; consumed by children render function
|
|
228
|
+
- `itemWidth`: per-item width in px; required
|
|
229
|
+
- `itemHeight`: optional per-item height; omit for natural/content-driven height
|
|
230
|
+
- `containerWidth`: numeric viewport width in px; always pass the available width explicitly.
|
|
231
|
+
- `style`: styles for the root viewport; apply CSS classes to a wrapper or slide content.
|
|
232
|
+
- `mode`: `'normal' | 'custom'`; affects item placement
|
|
233
|
+
- `modeConfig`: `{ align?: 'start' | 'center' | 'end'; spaceBetween?: number }` for normal mode
|
|
234
|
+
- `loop` / `loopDuplicateCount`: enable loop and control cloned head/tail count
|
|
235
|
+
- `autoPlay` / `autoPlayInterval`: enable and tune auto paging
|
|
236
|
+
- `bounceConfig`: edge views and behavior; ignored when `loop=true`
|
|
237
|
+
- `offsetLimit`: limit offset to avoid blank edges, e.g. `[0, containerWidth - itemWidth]`
|
|
238
|
+
- `consumeSlideEvent`: angle windows for handling touches; default covers horizontal
|
|
239
|
+
- `blockNativeEvent`: when Swiper is inside other scroll containers
|
|
240
|
+
- `RTL`: `true` or `'lynx-rtl'`
|
|
241
|
+
- `onChange`, `onSwipeStart`, `onSwipeStop`, `main-thread:onOffsetChange`
|
|
242
|
+
- `main-thread:easing`, `main-thread:customAnimation`, `customAnimationFirstScreen`
|
|
243
|
+
|
|
244
|
+
## 5. Ref API
|
|
245
|
+
|
|
246
|
+
```ts
|
|
247
|
+
interface SwiperRef {
|
|
248
|
+
swipeNext(): void
|
|
249
|
+
swipePrev(): void
|
|
250
|
+
swipeTo(
|
|
251
|
+
index: number,
|
|
252
|
+
options?: { animate?: boolean, onFinished?: () => void },
|
|
253
|
+
): void
|
|
254
|
+
cancelAnimation(): void // use with caution
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
## 6. FAQ
|
|
259
|
+
|
|
260
|
+
- Do children have to be a function? Yes. It receives `{ item, index }` and must return `<SwiperItem>`.
|
|
261
|
+
- Why doesn’t `initialIndex` update after mount? It is only applied at first screen; later updates are ignored. Use `swiperKey` or `resetOnReuse` to reset.
|
|
262
|
+
- My last item leaves a blank area when `align='start'`. Provide `offsetLimit={[0, containerWidth - itemWidth]}` to clamp the range.
|
|
263
|
+
- Bounces don’t trigger when `loop=true`. Correct—bounce is ignored in looping.
|
|
264
|
+
- I’m in a vertical `scroll-view`, swipes feel conflicted. Set `experimentalHorizontalSwipeOnly={true}` and consider `blockNativeEvent={true}`; adjust `consumeSlideEvent` if needed.
|
|
265
|
+
- Why duplicate `customAnimationFirstScreen`? It mirrors `main-thread:customAnimation` for first-screen rendering until main-thread first-screen support arrives.
|
|
266
|
+
- Opacity rendering glitches? Set `<SwiperItem overlap>` as needed; it applies the attribute to the item view.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lynx-js/lynx-ui-swiper",
|
|
3
|
-
"version": "3.
|
|
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,17 +16,18 @@
|
|
|
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.*",
|
|
20
22
|
"README.md",
|
|
23
|
+
"SKILL.md",
|
|
21
24
|
"CHANGELOG.md",
|
|
22
25
|
"LICENSE",
|
|
23
|
-
"tsconfig.docs.json",
|
|
24
|
-
"tsconfig.json",
|
|
25
26
|
"dist/**"
|
|
26
27
|
],
|
|
27
28
|
"dependencies": {
|
|
28
29
|
"@lynx-js/react-use": "0.2.2",
|
|
29
|
-
"@lynx-js/lynx-ui-common": "3.
|
|
30
|
+
"@lynx-js/lynx-ui-common": "3.143.0"
|
|
30
31
|
},
|
|
31
32
|
"devDependencies": {
|
|
32
33
|
"@lynx-js/react": "0.123.1",
|
package/tsconfig.docs.json
DELETED