swipefeed 1.1.6 → 1.2.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/README.md +20 -9
- package/dist/__tests__/SwipeDeck.motion-lifecycle.test.d.ts +1 -0
- package/dist/__tests__/SwipeDeck.motion.browser.test.d.ts +1 -0
- package/dist/__tests__/motion.test.d.ts +1 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/motion.d.ts +11 -0
- package/dist/types.d.ts +27 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -21,6 +21,8 @@ Headless React primitives for building TikTok/Reels-style swipe feeds. Ships a r
|
|
|
21
21
|
- Virtualization via `@tanstack/react-virtual` with auto measurement and overscan tuning.
|
|
22
22
|
- Input support: pointer drag/flick, discrete wheel paging with heavy dampening, keyboard (global or scoped).
|
|
23
23
|
- Controlled or uncontrolled index, loopable navigation, programmatic `prev/next/scrollTo`.
|
|
24
|
+
- Animation-frame-throttled motion snapshots for synchronized media and visual effects.
|
|
25
|
+
- Position- or intersection-based activation with exact active/inactive lifecycle callbacks.
|
|
24
26
|
- Accessibility-first: focusable `role="feed"` viewport, per-item `role="article"`, `aria-label`, `aria-busy`, snap alignment.
|
|
25
27
|
- Reduced-motion aware (`prefers-reduced-motion` uses instant scrolling).
|
|
26
28
|
- End-reached callbacks for infinite loading triggers.
|
|
@@ -97,9 +99,9 @@ function CustomLayout({ items }) {
|
|
|
97
99
|
Extends `SwipeDeckOptions<T>` plus:
|
|
98
100
|
|
|
99
101
|
- `as`: custom element/component for the viewport (default `"div"`).
|
|
100
|
-
- `children(context)`: render prop; receives `{ item, index, isActive, props }`.
|
|
102
|
+
- `children(context)`: render prop; receives `{ item, index, isActive, shouldPreload, props }`.
|
|
101
103
|
- `className`, `style`: forwarded to the viewport.
|
|
102
|
-
- `ref`: imperative handle (`SwipeDeckHandle`) with `prev`, `next`, `scrollTo`, `getState`.
|
|
104
|
+
- `ref`: imperative handle (`SwipeDeckHandle`) with `prev`, `next`, `scrollTo`, `getState`, `getMotion`.
|
|
103
105
|
|
|
104
106
|
### `SwipeDeckOptions<T>`
|
|
105
107
|
|
|
@@ -108,7 +110,8 @@ Extends `SwipeDeckOptions<T>` plus:
|
|
|
108
110
|
- `direction`: `"ltr"` (default) | `"rtl"` (affects horizontal gestures/wheel/keyboard).
|
|
109
111
|
- `defaultIndex`: initial index for uncontrolled mode (default `0`).
|
|
110
112
|
- `index`: controlled index. When set, you must manage updates via `onIndexChange`.
|
|
111
|
-
- `onIndexChange(index, source)`: fires on any navigation. `source` is one of `"user:gesture" | "user:wheel" | "user:keyboard" | "programmatic" | "snap"`.
|
|
113
|
+
- `onIndexChange(index, source)`: fires on any navigation. `source` is one of `"user:gesture" | "user:wheel" | "user:keyboard" | "programmatic" | "visibility" | "snap"`.
|
|
114
|
+
- `onMotionChange(motion)`: animation-frame-throttled continuous motion callback. It does not put per-pixel motion into React render state.
|
|
112
115
|
- `loop`: wrap navigation at ends (default `false`).
|
|
113
116
|
- `gesture`: `{ threshold, flickVelocity, lockAxis, ignoreWhileAnimating }` (defaults `10`, `0.1`, `true`, `true`).
|
|
114
117
|
- `wheel`: `{ discretePaging, threshold, debounce, cooldown }` (defaults `true`, `100`, `120ms`, `800ms`) with aggressive dampening to prevent multi-item jumps.
|
|
@@ -118,29 +121,38 @@ Extends `SwipeDeckOptions<T>` plus:
|
|
|
118
121
|
- `endReachedThreshold`: number of items from ends to trigger `onEndReached` (default `3`).
|
|
119
122
|
- `onEndReached({ distanceFromEnd, direction })`: called when within threshold from start or end.
|
|
120
123
|
- `ariaLabel`: label for the feed (default `"Swipe feed"`).
|
|
121
|
-
- `visibility`:
|
|
122
|
-
- `onItemActive`, `onItemInactive`:
|
|
124
|
+
- `visibility`: `{ strategy, intersectionRatio, debounce }`. `strategy` defaults to `"position"`; `"intersection"` activates an item after it crosses `intersectionRatio` (default `0.6`) and falls back to position when `IntersectionObserver` is unavailable.
|
|
125
|
+
- `onItemActive(item, index)`, `onItemInactive(item, index)`: exact lifecycle transitions for the active item. The initial item activates on mount and the final item becomes inactive on unmount.
|
|
123
126
|
|
|
124
127
|
### Render context (`children`)
|
|
125
128
|
|
|
126
129
|
- `item`: the data item.
|
|
127
130
|
- `index`: item index.
|
|
128
131
|
- `isActive`: whether the item is currently centered/active.
|
|
129
|
-
- `
|
|
132
|
+
- `shouldPreload`: whether the item is in the configured forward/backward preload window.
|
|
133
|
+
- `props`: spread onto your item content (data and accessibility attributes; SwipeDeck's outer article owns its internal ref and positioning styles).
|
|
130
134
|
|
|
131
135
|
### Imperative handle (`SwipeDeckHandle`)
|
|
132
136
|
|
|
133
137
|
- `prev()`, `next()`
|
|
134
138
|
- `scrollTo(index, { behavior })`
|
|
135
139
|
- `getState()`: `{ index, isAnimating, canPrev, canNext }`
|
|
140
|
+
- `getMotion()`: latest `SwipeDeckMotion` snapshot without subscribing React render state.
|
|
136
141
|
|
|
137
142
|
### `useSwipeDeck` return shape
|
|
138
143
|
|
|
139
144
|
- State: `index`, `isAnimating`, `canPrev`, `canNext`, `items`, `orientation`.
|
|
140
145
|
- Actions: `prev()`, `next()`, `scrollTo(index, { behavior })`.
|
|
146
|
+
- Motion: `getMotion()` for the latest snapshot; use `onMotionChange` to subscribe.
|
|
141
147
|
- Layout: `virtualItems` (offset/size/key/measureElement), `totalSize`.
|
|
142
148
|
- Props helpers: `getViewportProps()`, `getItemProps(index)`.
|
|
143
149
|
|
|
150
|
+
## Continuous motion
|
|
151
|
+
|
|
152
|
+
`onMotionChange` emits `{ scrollOffset, viewportSize, position, index, offset, offsetRatio, direction, isSettled }`. `position` is fractional, while `index` is the nearest item. `offset` is the nearest item's pixel displacement from its settled position, which makes a shared media layer follow the outgoing and incoming cards without reading the viewport DOM directly.
|
|
153
|
+
|
|
154
|
+
The callback is throttled with `requestAnimationFrame`. Keep high-frequency visual work imperative (for example, update a transform); only copy coarse changes such as `motion.index` into React state.
|
|
155
|
+
|
|
144
156
|
### Helper hook
|
|
145
157
|
|
|
146
158
|
- `useWindowSize()`: throttled window dimensions `{ width, height }`.
|
|
@@ -181,7 +193,7 @@ cd example
|
|
|
181
193
|
bun run dev # starts Vite on http://localhost:5173
|
|
182
194
|
```
|
|
183
195
|
|
|
184
|
-
Key bits: render prop usage, global keyboard navigation, gesture swipe, mute button overlay, and custom chrome.
|
|
196
|
+
Key bits: render prop usage, shared-player synchronization through `onMotionChange`, global keyboard navigation, gesture swipe, mute button overlay, and custom chrome.
|
|
185
197
|
|
|
186
198
|
## Scripts (root)
|
|
187
199
|
|
|
@@ -206,5 +218,4 @@ Key bits: render prop usage, global keyboard navigation, gesture swipe, mute but
|
|
|
206
218
|
|
|
207
219
|
## Notes & limitations
|
|
208
220
|
|
|
209
|
-
-
|
|
210
|
-
- Ensure your viewport has a defined size; virtualization and snap rely on it.
|
|
221
|
+
- Ensure your viewport has a defined size; virtualization, motion snapshots, and snap rely on it.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/dist/index.d.ts
CHANGED
|
@@ -2,4 +2,4 @@ export { useSwipeDeck } from "./hooks/useSwipeDeck";
|
|
|
2
2
|
export { useWindowSize } from "./hooks/useWindowSize";
|
|
3
3
|
export { useSwipeItem } from "./hooks/useSwipeItem";
|
|
4
4
|
export { SwipeDeck } from "./components/SwipeDeck";
|
|
5
|
-
export type { SwipeDeckOptions, SwipeDeckAPI, SwipeDeckState, SwipeDeckActions, SwipeDeckVirtualItem, SwipeDeckProps, SwipeDeckHandle, SwipeDeckRenderContext, IndexChangeSource, Orientation, Direction, ScrollBehavior, } from "./types";
|
|
5
|
+
export type { SwipeDeckOptions, SwipeDeckAPI, SwipeDeckState, SwipeDeckActions, SwipeDeckVirtualItem, SwipeDeckProps, SwipeDeckHandle, SwipeDeckRenderContext, SwipeDeckMotion, SwipeDeckMotionDirection, GestureConfig, WheelConfig, KeyboardConfig, VisibilityConfig, VirtualConfig, IndexChangeSource, Orientation, Direction, ScrollBehavior, } from "./types";
|
package/dist/index.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export{
|
|
1
|
+
export{p as useWindowSize,n as useSwipeItem,o as useSwipeDeck,S as SwipeDeck};
|
|
2
2
|
|
|
3
|
-
//# debugId=
|
|
3
|
+
//# debugId=0FD04F832BA4D05B64756E2164756E21
|
|
4
4
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
package/dist/motion.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { SwipeDeckMotion } from "./types";
|
|
2
|
+
type CalculateSwipeDeckMotionOptions = {
|
|
3
|
+
scrollOffset: number;
|
|
4
|
+
viewportSize: number;
|
|
5
|
+
itemCount: number;
|
|
6
|
+
previousScrollOffset?: number;
|
|
7
|
+
settleTolerance?: number;
|
|
8
|
+
};
|
|
9
|
+
export declare function createInitialSwipeDeckMotion(index?: number): SwipeDeckMotion;
|
|
10
|
+
export declare function calculateSwipeDeckMotion({ scrollOffset, viewportSize, itemCount, previousScrollOffset, settleTolerance, }: CalculateSwipeDeckMotionOptions): SwipeDeckMotion;
|
|
11
|
+
export {};
|
package/dist/types.d.ts
CHANGED
|
@@ -3,7 +3,26 @@ import type { JSX } from "react";
|
|
|
3
3
|
export type Orientation = "vertical" | "horizontal";
|
|
4
4
|
export type Direction = "ltr" | "rtl";
|
|
5
5
|
export type ScrollBehavior = "smooth" | "instant" | "auto";
|
|
6
|
-
export type IndexChangeSource = "user:gesture" | "user:wheel" | "user:keyboard" | "programmatic" | "snap";
|
|
6
|
+
export type IndexChangeSource = "user:gesture" | "user:wheel" | "user:keyboard" | "programmatic" | "visibility" | "snap";
|
|
7
|
+
export type SwipeDeckMotionDirection = "forward" | "backward" | "none";
|
|
8
|
+
export interface SwipeDeckMotion {
|
|
9
|
+
/** Clamped scroll offset along the deck's active axis, in pixels. */
|
|
10
|
+
scrollOffset: number;
|
|
11
|
+
/** Current viewport size along the deck's active axis, in pixels. */
|
|
12
|
+
viewportSize: number;
|
|
13
|
+
/** Continuous item position. For example, 1.5 is halfway from item 1 to item 2. */
|
|
14
|
+
position: number;
|
|
15
|
+
/** Item nearest the viewport center. */
|
|
16
|
+
index: number;
|
|
17
|
+
/** Nearest item's offset from its settled position, in pixels. */
|
|
18
|
+
offset: number;
|
|
19
|
+
/** Nearest item's offset normalized by viewport size. */
|
|
20
|
+
offsetRatio: number;
|
|
21
|
+
/** Direction of the latest observed movement. */
|
|
22
|
+
direction: SwipeDeckMotionDirection;
|
|
23
|
+
/** Whether the nearest item is aligned with the viewport. */
|
|
24
|
+
isSettled: boolean;
|
|
25
|
+
}
|
|
7
26
|
export interface GestureConfig {
|
|
8
27
|
threshold?: number;
|
|
9
28
|
flickVelocity?: number;
|
|
@@ -45,6 +64,11 @@ export interface SwipeDeckOptions<T> {
|
|
|
45
64
|
defaultIndex?: number;
|
|
46
65
|
index?: number;
|
|
47
66
|
onIndexChange?: (index: number, source: IndexChangeSource) => void;
|
|
67
|
+
/**
|
|
68
|
+
* Receives requestAnimationFrame-throttled motion snapshots without making
|
|
69
|
+
* continuous motion part of SwipeDeck's React render state.
|
|
70
|
+
*/
|
|
71
|
+
onMotionChange?: (motion: SwipeDeckMotion) => void;
|
|
48
72
|
loop?: boolean;
|
|
49
73
|
preload?: number;
|
|
50
74
|
preloadPrevious?: number;
|
|
@@ -97,6 +121,7 @@ export interface SwipeDeckAPI<T> extends SwipeDeckState, SwipeDeckActions {
|
|
|
97
121
|
items: readonly T[];
|
|
98
122
|
orientation: Orientation;
|
|
99
123
|
viewport: HTMLElement | null;
|
|
124
|
+
getMotion: () => SwipeDeckMotion;
|
|
100
125
|
}
|
|
101
126
|
export interface SwipeDeckRenderContext<T> {
|
|
102
127
|
item: T;
|
|
@@ -118,5 +143,6 @@ export interface SwipeDeckProps<T> extends SwipeDeckOptions<T> {
|
|
|
118
143
|
}
|
|
119
144
|
export interface SwipeDeckHandle extends SwipeDeckActions {
|
|
120
145
|
getState: () => SwipeDeckState;
|
|
146
|
+
getMotion: () => SwipeDeckMotion;
|
|
121
147
|
viewport: HTMLElement | null;
|
|
122
148
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "swipefeed",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"private": false,
|
|
6
6
|
"type": "module",
|
|
@@ -40,8 +40,8 @@
|
|
|
40
40
|
"site:prepare": "rm -rf site && bun run docs:site && bun run example:build:site && mkdir -p site/example && cp -r example/dist/* site/example/",
|
|
41
41
|
"site:publish": "bun run site:prepare && bunx gh-pages -d site -b gh-pages",
|
|
42
42
|
"prepare": "husky install",
|
|
43
|
-
"test": "vitest run --environment jsdom --exclude src/__tests__/**/*browser.*",
|
|
44
|
-
"test:coverage": "vitest run --coverage --environment jsdom --exclude src/__tests__/**/*browser.*",
|
|
43
|
+
"test": "vitest run --environment jsdom --exclude 'src/__tests__/**/*browser.*'",
|
|
44
|
+
"test:coverage": "vitest run --coverage --environment jsdom --exclude 'src/__tests__/**/*browser.*'",
|
|
45
45
|
"test:browser": "vitest run --config vitest.browser.config.ts",
|
|
46
46
|
"test:example:live": "bun scripts/check-example-videos.ts",
|
|
47
47
|
"test:browser:coverage": "vitest run --config vitest.browser.config.ts --coverage",
|