swipefeed 1.1.5 → 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 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`: reserved for future visibility strategies (currently unused).
122
- - `onItemActive`, `onItemInactive`: reserved hooks for future activation callbacks (currently no-ops).
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
- - `props`: spread onto your item element (includes refs, transforms, snap styles, data attributes).
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
- - `visibility`, `onItemActive`, and `onItemInactive` options are present for future parity with the design spec but are not wired yet.
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 {};
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{t as useWindowSize,S as useSwipeItem,o as useSwipeDeck,w as SwipeDeck};
1
+ export{p as useWindowSize,n as useSwipeItem,o as useSwipeDeck,S as SwipeDeck};
2
2
 
3
- //# debugId=B78098051D0BEAB864756E2164756E21
3
+ //# debugId=0FD04F832BA4D05B64756E2164756E21
4
4
  //# sourceMappingURL=index.js.map
package/dist/index.js.map CHANGED
@@ -4,6 +4,6 @@
4
4
  "sourcesContent": [
5
5
  ],
6
6
  "mappings": "",
7
- "debugId": "B78098051D0BEAB864756E2164756E21",
7
+ "debugId": "0FD04F832BA4D05B64756E2164756E21",
8
8
  "names": []
9
9
  }
@@ -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.1.5",
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",