bump 0.9.6, streamline hashnav, improve ff cancel

Author: smastrom

README.md

@@ -16,14 +16,14 @@ But it may not be the one-size-fits-all solution to highlight menu/sidebar links
 
 You may noticed that's tricky to customize behavior according to different interactions.
 
-For example, you want to immediately highlight targets when scroll is originated from click/navigation but not when it is originated from wheel/touch. You want also to highlight any clicked link even if it will never intersect.
+For example, you want to immediately highlight targets when scroll is originated from click/navigation but not when it is originated from wheel/touch. You also want to highlight any clicked link even if it will never intersect.
 
-**Vue Use Active Scroll** implements a custom scroll observer which automatically adapts to different interactions and always returns the "correct" active target.
+**Vue Use Active Scroll** implements a custom scroll observer which automatically adapts to any type of scroll behaviors and interactions and always returns the "correct" active target.
 
 ### Features
 
 - Precise and stable at any speed
-- CSS scroll-behavior and callback agnostic
+- CSS scroll-behavior or JS scroll agnostic
 - Adaptive behavior on mount, back/forward hash navigation, scroll, click, cancel.
 - Customizable boundary offsets for each direction
 - Customizable behavior on top/bottom reached
@@ -69,7 +69,7 @@ And your links look like:
 </nav>
 ```
 
-In your menu/sidebar component, provide the IDs of the targets to observe to `useActive` (order is not
+In your menu/sidebar component, provide the IDs to observe to `useActive` (order is not
 important).
 
 ```vue
@@ -166,12 +166,12 @@ const { isActive, setActive } = useActive(targets, {
 
 ### Return object
 
-| Name        | Type                      | Description                                                                                                                                   |
-| ----------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| setActive   | `(id: string) => void`    | :firecracker: Function to include in your click handler to ensure adaptive behavior between any interaction that may cancel or resume scroll. |
-| isActive    | `(id: string) => boolean` | Whether the given Id is active or not                                                                                                         |
-| activeId    | `Ref<string>`             | Id of the active target                                                                                                                       |
-| activeIndex | `Ref<number>`             | Index of the active target in offset order, `0` for the first target and so on.                                                               |
+| Name        | Type                      | Description                                                                          |
+| ----------- | ------------------------- | ------------------------------------------------------------------------------------ |
+| setActive   | `(id: string) => void`    | :firecracker: Function to include in your click handler to ensure adaptive behavior. |
+| isActive    | `(id: string) => boolean` | Whether the given Id is active or not                                                |
+| activeId    | `Ref<string>`             | Id of the active target                                                              |
+| activeIndex | `Ref<number>`             | Index of the active target in offset order, `0` for the first target and so on.      |
 
 <br />
 
@@ -230,7 +230,7 @@ html {
 }
 ```
 
-<details><summary><strong>B. Custom Scroll Animation</strong></summary>
+<details><summary><strong>B. Custom JS Scroll</strong></summary>
 
 <br />
 
@@ -353,7 +353,7 @@ html {
 
 ## Setting scroll-margin-top for fixed headers
 
-You might noticed that if you have a fixed header and defined an `overlayHeight`, once you click to scroll to a target it may be underneath the header. You must set `scroll-margin-top` to your targets:
+You might noticed that if you have a fixed header and defined an `overlayHeight`, once you click to scroll to a target it may be underneath the header. You must add `scroll-margin-top` to your targets:
 
 ```js
 useActive(targets, { overlayHeight: 100 })
@@ -367,19 +367,25 @@ useActive(targets, { overlayHeight: 100 })
 
 <br />
 
-## Vue Router scroll to hash on mount
+## Vue Router Scroll Hash Navigation
 
-If using Nuxt, Vue Router is already configured to scroll to the URL hash on page load or back/forward navigation.
+> :warning: If using Nuxt 3, Vue Router is already configured to scroll to and from URL hash on page load or back/forward navigation. **So you don't need to do follow the steps below**. Otherwise rules must be defined manually.
 
-If not using Nuxt and you're setting up Vue Router from scratch, you must enable the feature manually.
+### Scrolling to hash
 
-### Window
+For content scrolled by the window, simply return the target element. To scroll to a target scrolled by a container, use _scrollIntoView_ method.
 
 ```js
 const router = createRouter({
   // ...
   scrollBehavior(to) {
     if (to.hash) {
+      // Content scrolled by a container
+      if (to.name === 'PageNameUsingContainer') {
+        return document.querySelector(to.hash).scrollIntoView()
+      }
+
+      // Content scrolled by the window
       return {
         el: to.hash
         // top: 100 // Eventual fixed header (overlayHeight)
@@ -389,32 +395,34 @@ const router = createRouter({
 })
 ```
 
-> :bulb: There's need to define _smooth_ or _auto_ here. Adding the [CSS rule](#2-define-scroll-behavior) is enough. Same applies below.
+> :bulb: There's no need to define _smooth_ or _auto_ here. Adding the [CSS rule](#2-define-scroll-behavior) is enough.
 
-### Container
+> :bulb: There's no need need to set overlayHeight if using `scrollIntoView` as the method is aware of target's `scroll-margin-top` property.
 
-To scroll to a target scrolled by a container, you must use `scrollIntoView`:
+### Scrolling from hash to the top of the page
+
+To navigate back to the top of the same page (e.g. clicking on browser back button from a hash to the page root), use the _scroll_ method for containers and return _top_ for content scrolled by the window.
 
 ```js
 const router = createRouter({
   // ...
-  scrollBehavior(to) {
-    if (to.hash) {
-      // Content scrolled by container
-      if (to.name === 'PageNameWithContainer') {
-        return document.querySelector(to.hash).scrollIntoView()
-      }
-      // Content scrolled by window
-      return {
-        el: to.hash
+  scrollBehavior(to, from) {
+    if (from.hash && !to.hash) {
+      // Content scrolled by a container
+      if (
+        to.name === 'PageNameUsingContainer' &&
+        from.name === 'PageNameUsingContainer'
+      ) {
+        return document.querySelector('#ScrollingContainer').scroll(0, 0)
       }
+
+      // Content scrolled by the window
+      return { top: 0 }
     }
   }
 })
 ```
 
-> :bulb: No need to set overlayHeight if using `scrollIntoView` as the method is aware of target's `scroll-margin-top` property.
-
 <br />
 
 ## License

demo/main.ts

@@ -26,7 +26,15 @@ const router = createRouter({
 			component: () => import('./pages/Sections.vue'),
 		},
 	],
-	scrollBehavior(to) {
+	scrollBehavior(to, from) {
+		if (from.hash && !to.hash) {
+			if (to.name === 'Container' && from.name === 'Container') {
+				return document.querySelector('#ScrollingContainer')?.scroll(0, 0);
+			}
+
+			return { top: 0 };
+		}
+
 		if (to.hash) {
 			if (to.name === 'Container') {
 				return document.querySelector(to.hash)?.scrollIntoView();

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vue-use-active-scroll",
-	"version": "0.9.4",
+	"version": "0.9.6",
 	"private": false,
 	"description": "Reactive and accurate TOC/sidebar links without compromises for Vue 3.",
 	"keywords": [

src/useActive.ts

@@ -114,6 +114,10 @@ export function useActive(
 	}
 
 	function onEdgeReached() {
+		if (!jumpToFirst && !jumpToLast) {
+			return false;
+		}
+
 		const { isBottom, isTop } = getEdges(root.value as HTMLElement);
 
 		if (jumpToFirst && isTop) {
@@ -173,7 +177,7 @@ export function useActive(
 		}
 
 		if (ids.value.indexOf(firstIn) < ids.value.indexOf(activeId.value)) {
-			activeId.value = firstIn;
+			return (activeId.value = firstIn);
 		}
 	}
 
@@ -188,17 +192,9 @@ export function useActive(
 
 	function onHashChange(event: HashChangeEvent) {
 		if (matchMedia.value) {
-			// If hash is not anymore in the URL
+			// If scrolled to top
 			if (!event.newURL.includes('#') && activeId.value) {
-				const prevY = getSentinel();
-
-				requestAnimationFrame(() => {
-					// If scrolled to top on its own, reset activeId
-					const newY = getSentinel();
-					if (prevY !== newY) {
-						return (activeId.value = jumpToFirst ? ids.value[0] : '');
-					}
-				});
+				return (activeId.value = jumpToFirst ? ids.value[0] : '');
 			}
 
 			// Else set hash as active

src/useScroll.ts

@@ -1,5 +1,5 @@
 import { watch, onMounted, ref, computed, type Ref, type ComputedRef } from 'vue';
-import { isFirefox, isSSR, useMediaRef } from './utils';
+import { isSSR, useMediaRef } from './utils';
 
 type UseScrollOptions = {
 	isWindow: ComputedRef<boolean>;
@@ -63,8 +63,10 @@ export function useScroll({
 		const nextY = getY();
 
 		if (nextY < prevY) {
+			console.log('Up');
 			onScrollUp();
 		} else {
+			console.log('Down');
 			onScrollDown({ isCancel });
 		}
 
@@ -87,7 +89,8 @@ export function useScroll({
 	function onPointerDown(event: PointerEvent) {
 		const isAnchor = (event.target as HTMLElement).tagName === 'A';
 
-		if (isFirefox() && !isAnchor) {
+		if (CSS.supports('-moz-appearance', 'none') && !isAnchor) {
+			console.log('PointerDown');
 			reScroll();
 			// ...and force set if canceling scroll
 			setActive({ prevY: clickY.value, isCancel: true });
@@ -136,15 +139,17 @@ export function useScroll({
 			const rootEl = isWindow.value ? document : root.value;
 
 			if (_isClick && rootEl) {
+				console.log('Adding additional listeners');
 				rootEl.addEventListener('wheel', reScroll, ONCE);
 				rootEl.addEventListener('touchmove', reScroll, ONCE);
 				rootEl.addEventListener('scroll', setIdle as unknown as EventListener, ONCE);
 				rootEl.addEventListener('keydown', onSpaceBar as EventListener, ONCE);
-				rootEl.addEventListener('pointerdown', onPointerDown as EventListener, ONCE);
+				rootEl.addEventListener('pointerdown', onPointerDown as EventListener); // Must persist for proper cancel with Firefox
 			}
 
 			onCleanup(() => {
 				if (_isClick && rootEl) {
+					console.log('Removing additional listeners');
 					rootEl.removeEventListener('wheel', reScroll);
 					rootEl.removeEventListener('touchmove', reScroll);
 					rootEl.removeEventListener('scroll', setIdle as unknown as EventListener);

src/utils.ts

@@ -4,10 +4,6 @@ export const isSSR = typeof window === 'undefined';
 
 export const FIXED_OFFSET = 5;
 
-export function isFirefox() {
-	return CSS.supports('-moz-appearance', 'none');
-}
-
 // When users set refs, if no media match, set default value
 export function useMediaRef<T>(matchMedia: Ref<boolean>, defaultValue: T): Ref<T> {
 	const _customRef = customRef<T>((track, trigger) => {
@@ -28,17 +24,15 @@ export function useMediaRef<T>(matchMedia: Ref<boolean>, defaultValue: T): Ref<T
 }
 
 export function getEdges(root: HTMLElement) {
-	// Mobile devices
+	// Mobile devices needs window.innerHeight
 	const clientHeight = root === document.documentElement ? window.innerHeight : root.clientHeight;
 
-	const isTopReached = root.scrollTop <= FIXED_OFFSET * 2;
-	const isBottomReached = Math.abs(root.scrollHeight - clientHeight - root.scrollTop) <= 1;
-	const isOverscrollTop = root.scrollTop < 0;
-	const isOverscrollBottom = root.scrollTop > root.scrollHeight - clientHeight;
+	const isTop = root.scrollTop <= FIXED_OFFSET * 2;
+	const isBottom = Math.abs(root.scrollHeight - clientHeight - root.scrollTop) <= 1;
 
 	return {
-		isTop: isTopReached || isOverscrollTop,
-		isBottom: isBottomReached || isOverscrollBottom,
+		isTop,
+		isBottom,
 	};
 }