@lynx-js/lynx-ui-swiper 3.141.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 CHANGED
@@ -1,5 +1,22 @@
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
+
11
+ ## 3.142.0
12
+
13
+ ### Patch Changes
14
+
15
+ - Accept React 18 and newer types. ReactLynx still defines the compatible versions for each app. ([#383](https://github.com/lynx-family/lynx-ui/pull/383))
16
+
17
+ - Updated dependencies [[`49cb3c5`](https://github.com/lynx-family/lynx-ui/commit/49cb3c5b20d9346ff0f8b314367b4c8e354d195d)]:
18
+ - @lynx-js/lynx-ui-common@3.142.0
19
+
3
20
  ## 3.141.0
4
21
 
5
22
  ### 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.141.0",
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.139.0"
30
+ "@lynx-js/lynx-ui-common": "3.143.0"
30
31
  },
31
32
  "devDependencies": {
32
33
  "@lynx-js/react": "0.123.1",
@@ -38,7 +39,7 @@
38
39
  "peerDependencies": {
39
40
  "@lynx-js/react": ">=0.100.0",
40
41
  "@lynx-js/types": "*",
41
- "@types/react": "^18"
42
+ "@types/react": ">=18"
42
43
  },
43
44
  "publishConfig": {
44
45
  "access": "public"
@@ -1,7 +0,0 @@
1
- {
2
- "extends": "../../tools/configs/tsconfig.docs.json",
3
- "include": [
4
- "src",
5
- "dist/types/index.docs.d.ts"
6
- ]
7
- }
package/tsconfig.json DELETED
@@ -1,14 +0,0 @@
1
- {
2
- "extends": "../../tools/configs/tsconfig.lib.json",
3
- "compilerOptions": {
4
- "rootDir": "./src",
5
- },
6
- "include": [
7
- "src",
8
- ],
9
- "exclude": [
10
- "**/*.test.ts",
11
- "**/*.test.tsx",
12
- "**/__tests__/**",
13
- ],
14
- }