use-scroller 2.0.0 → 2.1.0

package/README.md

@@ -104,7 +104,8 @@ It sets `touch-action: pan-y pinch-zoom` on the track (`pan-x pinch-zoom` for `a
 cross-axis movement scrolls the page natively and pinch-zoom keeps working. A gesture
 is judged after 8px: mostly sideways and the track follows the finger, otherwise it is left to the
 browser. Release continues with momentum and lands on a CSS scroll-snap position if the track has
-any. A drag doesn't fire a click on whatever is under the finger. Wheel, trackpad, keyboard and the scrollbar stay
+any. Like native scrolling, it never carries past a snap position whose area has
+`scroll-snap-stop: always`. A drag doesn't fire a click on whatever is under the finger. Wheel, trackpad, keyboard and the scrollbar stay
 native. `mouse: true` also lets a mouse drag the track.
 
 ### `useScrollLock`
@@ -298,6 +299,7 @@ const stop = observeActiveSection(sections, (index) => highlight(index), {
 readScroll(target) // { x, y, minX, maxX, maxY, viewportWidth, viewportHeight }
 isScrollable(element, 'y')
 findScrollParent(element, 'y') // nearest scrollable ancestor, or window
+readSnapPositions(element, 'x') // CSS scroll-snap positions the container can rest at, ascending
 ```
 
 ## Recipes
@@ -431,11 +433,12 @@ names its axis, and the package is ESM-only.
 | `createEasingAnimation`, `createMomentumAnimation`                       | Removed. Use `animateScroll`                                                                                  |
 | Types `ScrollOptions`, `EasingOptions`, `UseScrollReturn`                | `AnimateScrollOptions`, `ScrollAnimation`, `Easing`, `ScrollActions`, `ScrollState`                           |
 
-## Example app
+## Demo site
 
-`example/` has a demo of every feature, with native and enhanced versions side by side for the touch
-ones. Run `npm install && npm run dev` inside it; the dev server listens on your LAN so you can open
-it on a phone.
+[silverlila.github.io/use-scroller](https://silverlila.github.io/use-scroller/) walks through every
+export with its code and a live demo. The source is in `site/`: run `yarn` at the root, then
+`npm install && npm run dev` inside `site/`; the dev server listens on your LAN so you can open it on
+a phone.
 
 ## License
 

package/dist/{chunk-BDIJT5M4.js → chunk-IFT3KMZJ.js}

@@ -600,21 +600,25 @@ function fling(target, axis, velocity) {
 // src/core/snap.ts
 var FLICK_VELOCITY = 300;
 function readSnapPositions(container, axis) {
+  return readSnapPoints(container, axis).map(({ position }) => position);
+}
+function readSnapPoints(container, axis) {
   const containerStyle = getComputedStyle(container);
   if (containerStyle.scrollSnapType === "none") return [];
   const rightToLeft = axis === "x" && containerStyle.direction === "rtl";
   const port = scrollport(container, axis);
   const origin = contentOrigin(container, axis);
   const metrics = readScroll(container);
-  const positions = /* @__PURE__ */ new Set();
+  const stops = /* @__PURE__ */ new Map();
   for (const [child, style] of snapAreaCandidates(container)) {
     const logical = snapAlignment(style.scrollSnapAlign, axis);
     if (logical === null) continue;
     const alignment = rightToLeft ? mirrored(logical) : logical;
     const area = snapArea(child, style, origin, axis);
-    positions.add(clampToRange(metrics, axis, alignedPosition(area, port, alignment)));
+    const position = clampToRange(metrics, axis, alignedPosition(area, port, alignment));
+    stops.set(position, stops.get(position) === true || style.scrollSnapStop === "always");
   }
-  return [...positions].sort((a, b) => a - b);
+  return [...stops].map(([position, stop]) => ({ position, stop })).sort((a, b) => a.position - b.position);
 }
 function* snapAreaCandidates(root) {
   for (const child of root.children) {
@@ -636,6 +640,14 @@ function pickSnapTarget(positions, current, projected, velocity) {
   if (ahead.length === 0) return nearest;
   return direction > 0 ? ahead[0] : ahead[ahead.length - 1];
 }
+function stopShortOfSnapStops(points, current, target) {
+  const direction = Math.sign(target - current);
+  const passed = points.filter(
+    ({ position, stop }) => stop && (position - current) * direction > EDGE_TOLERANCE && (target - position) * direction > 0
+  );
+  if (passed.length === 0) return target;
+  return direction > 0 ? passed[0].position : passed[passed.length - 1].position;
+}
 function snapAlignment(value, axis) {
   const [block, inline = block] = value.split(" ");
   const keyword = axis === "x" ? inline : block;
@@ -732,9 +744,9 @@ function dragScroll(element, { axis = "x", mouse = false } = {}) {
   }
   function interruptRelease() {
     if (!release) return null;
-    const { handle, positions } = release;
+    const { handle, points } = release;
     handle.cancel();
-    return { positions, restore: suspendSnap2() };
+    return { points, restore: suspendSnap2() };
   }
   function suspendSnap2() {
     return setInlineStyles(element, { "scroll-snap-type": "none" });
@@ -763,7 +775,7 @@ function dragScroll(element, { axis = "x", mouse = false } = {}) {
     element.setPointerCapture(event.pointerId);
     cancelScroll(element);
     const snap = (_a = pending.snap) != null ? _a : {
-      positions: readSnapPositions(element, axis),
+      points: readSnapPoints(element, axis),
       restore: suspendSnap2()
     };
     const startScroll = readScroll(element)[axis];
@@ -797,24 +809,26 @@ function dragScroll(element, { axis = "x", mouse = false } = {}) {
     if ((ended == null ? void 0 : ended.kind) === "dragging") ended.restoreUserSelect();
     if (ended == null ? void 0 : ended.snap) settle(ended.snap, velocity);
   }
-  function settle({ positions, restore }, velocity) {
-    if (positions.length === 0) {
+  function settle({ points, restore }, velocity) {
+    if (points.length === 0) {
       restore();
-      track(fling(element, axis, velocity), positions);
+      track(fling(element, axis, velocity), points);
       return;
     }
     const current = readScroll(element)[axis];
-    const target = pickSnapTarget(positions, current, current + projectMomentum(velocity), velocity);
+    const positions = points.map(({ position }) => position);
+    const picked = pickSnapTarget(positions, current, current + projectMomentum(velocity), velocity);
+    const target = stopShortOfSnapStops(points, current, picked);
     restore();
     const handle = animateScroll(element, axis === "x" ? { x: target } : { y: target }, {
       animation: { type: "spring", velocity: axis === "x" ? { x: velocity } : { y: velocity } },
       respectReducedMotion: false
     });
-    track(handle, positions);
+    track(handle, points);
   }
-  function track(handle, positions) {
+  function track(handle, points) {
     if (!handle) return;
-    const current = { handle, positions };
+    const current = { handle, points };
     release = current;
     void handle.finished.then(() => {
       if (release === current) release = null;
@@ -1178,6 +1192,7 @@ export {
   initialScrollState,
   observeScroll,
   lockScroll,
+  readSnapPositions,
   dragScroll,
   scrollToEdge,
   scrollBy,

package/dist/core.d.ts

@@ -91,6 +91,8 @@ interface DragScrollOptions {
 }
 declare function dragScroll(element: HTMLElement, { axis, mouse }?: DragScrollOptions): () => void;
 
+declare function readSnapPositions(container: HTMLElement, axis: Axis): number[];
+
 declare function observeActiveSection(sections: HTMLElement[], listener: (index: number) => void, { root, offset }?: {
     root?: ScrollTarget;
     offset?: number;
@@ -118,4 +120,4 @@ interface StickToBottom {
 }
 declare function stickToBottom(element: HTMLElement, onChange?: (isAtBottom: boolean) => void): StickToBottom;
 
-export { type AnimateScrollOptions, type Axis, type DragScrollOptions, type Easing, type Edge, type RestoreScrollOptions, type ScrollAlign, type ScrollAnimation, type ScrollDestination, type ScrollHandle, type ScrollMetrics, type ScrollResult, type ScrollState, type ScrollTarget, type ScrollToElementOptions, type StickToBottom, animateScroll, cancelScroll, cubicBezier, dragScroll, easings, findScrollParent, isScrollable, lockScroll, observeActiveSection, observeScroll, readScroll, restoreScroll, scrollBy, scrollToEdge, scrollToElement, stickToBottom };
+export { type AnimateScrollOptions, type Axis, type DragScrollOptions, type Easing, type Edge, type RestoreScrollOptions, type ScrollAlign, type ScrollAnimation, type ScrollDestination, type ScrollHandle, type ScrollMetrics, type ScrollResult, type ScrollState, type ScrollTarget, type ScrollToElementOptions, type StickToBottom, animateScroll, cancelScroll, cubicBezier, dragScroll, easings, findScrollParent, isScrollable, lockScroll, observeActiveSection, observeScroll, readScroll, readSnapPositions, restoreScroll, scrollBy, scrollToEdge, scrollToElement, stickToBottom };

package/dist/core.js

@@ -10,12 +10,13 @@ import {
   observeActiveSection,
   observeScroll,
   readScroll,
+  readSnapPositions,
   restoreScroll,
   scrollBy,
   scrollToEdge,
   scrollToElement,
   stickToBottom
-} from "./chunk-BDIJT5M4.js";
+} from "./chunk-IFT3KMZJ.js";
 export {
   animateScroll,
   cancelScroll,
@@ -28,6 +29,7 @@ export {
   observeActiveSection,
   observeScroll,
   readScroll,
+  readSnapPositions,
   restoreScroll,
   scrollBy,
   scrollToEdge,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ScrollDestination, AnimateScrollOptions, ScrollHandle, Edge, ScrollToElementOptions, ScrollState, DragScrollOptions, RestoreScrollOptions } from './core.js';
-export { Axis, Easing, ScrollAlign, ScrollAnimation, ScrollMetrics, ScrollResult, ScrollTarget, StickToBottom, animateScroll, cancelScroll, cubicBezier, dragScroll, easings, findScrollParent, isScrollable, lockScroll, observeActiveSection, observeScroll, readScroll, restoreScroll, scrollBy, scrollToEdge, scrollToElement, stickToBottom } from './core.js';
+export { Axis, Easing, ScrollAlign, ScrollAnimation, ScrollMetrics, ScrollResult, ScrollTarget, StickToBottom, animateScroll, cancelScroll, cubicBezier, dragScroll, easings, findScrollParent, isScrollable, lockScroll, observeActiveSection, observeScroll, readScroll, readSnapPositions, restoreScroll, scrollBy, scrollToEdge, scrollToElement, stickToBottom } from './core.js';
 import { RefObject } from 'react';
 
 type ElementTarget = RefObject<HTMLElement | null> | 'window';

package/dist/index.js

@@ -13,12 +13,13 @@ import {
   observeActiveSection,
   observeScroll,
   readScroll,
+  readSnapPositions,
   restoreScroll,
   scrollBy,
   scrollToEdge,
   scrollToElement,
   stickToBottom
-} from "./chunk-BDIJT5M4.js";
+} from "./chunk-IFT3KMZJ.js";
 
 // src/react/use-scroll.ts
 import { useRef as useRef2, useState } from "react";
@@ -330,6 +331,7 @@ export {
   observeActiveSection,
   observeScroll,
   readScroll,
+  readSnapPositions,
   restoreScroll,
   scrollBy,
   scrollToEdge,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroller",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "author": "silvi lila",
   "license": "MIT",
   "type": "module",