release v0.9.7

Author: smastrom

README.md

@@ -14,9 +14,7 @@
 The [Intersection Observer](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) is a great API.
 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 also want to highlight any clicked link even if it will never intersect.
+When smooth-scrolling, you may want to immediately highlight targets when scroll is originated from click/navigation but not when it is originated from wheel/touch. You may 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 any type of scroll behaviors and interactions and always returns the "correct" active target.
 
@@ -26,12 +24,14 @@ For example, you want to immediately highlight targets when scroll is originated
 - 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 offsets for first/last targets
 - Customizable behavior on top/bottom reached
-- Supports containers different than window
+- Supports custom scrolling containers
 
 ### What it doesn't do?
 
 - Mutate elements and inject styles
+- Force specific scroll behavior / callbacks
 - Scroll to targets
 
 <br />
@@ -62,11 +62,9 @@ Assuming your content looks like:
 And your links look like:
 
 ```html
-<nav>
-  <a href="#introduction">Introduction</a>
-  <a href="#quick-start">Quick Start</a>
-  <a href="#props">Props</a>
-</nav>
+<a href="#introduction">Introduction</a>
+<a href="#quick-start">Quick Start</a>
+<a href="#props">Props</a>
 ```
 
 In your menu/sidebar component, provide the IDs to observe to `useActive` (order is not
@@ -78,7 +76,7 @@ important).
 <script setup>
 import { useActive } from 'vue-use-active-scroll'
 
-// Data used to render your links
+// Data to render links
 const links = ref([
   { href: 'introduction', label: 'Introduction' },
   { href: 'quick-start', label: 'Quick Start' },
@@ -92,6 +90,8 @@ const { isActive } = useActive(targets)
 </script>
 ```
 
+You can provide either a reactive or a plain array of strings. If the array is reactive, the observer will reinitialize whenever it changes.
+
 > :bulb: For a TOC, you want to target (and scroll) the headings of your sections (instead of the whole section) to ensure results better-aligned with users' reading flow.
 
 <details><summary><strong>Nuxt Content 2</strong></summary>
@@ -144,7 +144,7 @@ const { isActive } = useActive(targets)
 
 <br />
 
-## 2. Configure the composable (optional)
+## 2. Customize the composable (optional)
 
 `useActive` accepts an optional configuration object as its second argument:
 
@@ -154,15 +154,16 @@ const { isActive, setActive } = useActive(targets, {
 })
 ```
 
-| Property       | Type               | Default                   | Description                                                                                                                                                                                                       |
-| -------------- | ------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| jumpToFirst    | `boolean`          | true                      | Whether to set the first target on mount as active even if not (yet) intersecting.                                                                                                                                |
-| jumpToLast     | `boolean`          | true                      | Whether to set the last target as active once reached the bottom even if previous targets are entirely visible.                                                                                                   |
-| boundaryOffset | `BoundaryOffset`   | { toTop: 0, toBottom: 0 } | Boundary offset in px for each scroll direction. Tweak them to "anticipate" or "delay" target detection.                                                                                                          |
-| rootId         | `string` \| `null` | null                      | Id of the scrolling element. Set it only if your content **is not scrolled** by the window.                                                                                                                       |
-| replaceHash    | `boolean`          | false                     | Whether to replace URL hash on scroll. First target is ignored if `jumpToFirst` is true.                                                                                                                          |
-| overlayHeight  | `number`           | 0                         | Height in pixels of any **CSS fixed** content that overlaps the top of your scrolling area (e.g. fixed header). Must be paired with a CSS [scroll-margin-top](#setting-scroll-margin-top-for-fixed-headers) rule. |
-| minWidth       | `number`           | 0                         | Whether to toggle listeners and functionalities within a specific width. Useful if hiding the sidebar using `display: none`.                                                                                      |
+| Property       | Type                                                | Default                    | Description                                                                                                                                                                                                       |
+| -------------- | --------------------------------------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| jumpToFirst    | `boolean`                                           | true                       | Whether to set the first target on mount as active even if not (yet) intersecting.                                                                                                                                |
+| jumpToLast     | `boolean`                                           | true                       | Whether to set the last target as active once reached the bottom even if previous targets are entirely visible.                                                                                                   |
+| boundaryOffset | `BoundaryOffset`                                    | { toTop: 0, toBottom: 0 }  | Boundary offset in px for each scroll direction. Tweak them to "anticipate" or "delay" target detection.                                                                                                          |
+| edgeOffset     | `EdgeOffset`                                        | { first: 100, last: -100 } | Offset in px for fist and last target. `first` has no effect if `jumpToFirst` is true. Same for `last` if `jumpToLast` is true.                                                                                   |
+| root           | `HTMLElement \| null` \| `Ref<HTMLElement \| null>` | null                       | Scrolling element. Set it only if your content **is not scrolled** by the window. If _null_, defaults to documentElement.                                                                                         |
+| replaceHash    | `boolean`                                           | false                      | Whether to replace URL hash on scroll. First target is ignored if `jumpToFirst` is true.                                                                                                                          |
+| overlayHeight  | `number`                                            | 0                          | Height in pixels of any **CSS fixed** content that overlaps the top of your scrolling area (e.g. fixed header). Must be paired with a CSS [scroll-margin-top](#setting-scroll-margin-top-for-fixed-headers) rule. |
+| minWidth       | `number`                                            | 0                          | Whether to toggle listeners and functionalities within a specific width. Useful if hiding the sidebar using `display: none`.                                                                                      |
 
 ### Return object
 
@@ -208,7 +209,7 @@ const { isActive, setActive } = useActive(targets)
 
 You're free to choose between CSS (smooth or auto), [scrollIntoView](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) or even a library like [animated-scroll-to](https://github.com/Stanko/animated-scroll-to).
 
-#### A. Using CSS scroll-behavior
+#### A. Using native CSS scroll-behavior
 
 - If content is scrolled by the window, add the following CSS rule to your `html` element:
 
@@ -279,6 +280,7 @@ function scrollTo(event, id) {
 ```vue
 <script setup>
 // ...
+
 const { isActive, setActive } = useActive(targets)
 </script>
 
@@ -367,7 +369,7 @@ useActive(targets, { overlayHeight: 100 })
 
 <br />
 
-## Vue Router Scroll Hash Navigation
+## Vue Router - Scroll to hash onMount / 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.
 
@@ -399,7 +401,7 @@ const router = createRouter({
 
 > :bulb: There's no need need to set overlayHeight if using `scrollIntoView` as the method is aware of target's `scroll-margin-top` property.
 
-### Scrolling from hash to the top of the page
+### Scrolling from hash back 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.
 
@@ -413,7 +415,7 @@ const router = createRouter({
         to.name === 'PageNameUsingContainer' &&
         from.name === 'PageNameUsingContainer'
       ) {
-        return document.querySelector('#ScrollingContainer').scroll(0, 0)
+        return document.getElementById('ScrollingContainer').scroll(0, 0)
       }
 
       // Content scrolled by the window
@@ -425,6 +427,55 @@ const router = createRouter({
 
 <br />
 
+## Vue Router - Prevent hash from being pushed
+
+You may noticed that when clicking on a link, a new entry is added to the history. When navigating back, the page will scroll to the previous target and so on.
+
+If you don't like that, choose to replace instead of pushing the hash:
+
+```vue
+<template>
+  <!-- ... -->
+  <RouterLink
+    @click.native="setActive(link.href)"
+    :to="{ hash: `#${item.href}`, replace: true /* 👈🏻 */ }"
+    :class="{
+      active: isActive(link.href)
+    }"
+  />
+  <!-- ... -->
+</template>
+```
+
+<br />
+
+## Custom initialization / re-initialization
+
+If the targets array is empty, _useActive_ won't initialize the scroll observer.
+
+Whenever `root` or `targets` are updated (and not empty), _useActive_ will re-initialize the observer.
+
+```vue
+<script setup>
+// ...
+
+const targets = ref([])
+const root = ref(null)
+
+const { isActive, setActive } = useActive(targets) // Nothing is initialized
+
+watch(someReactiveValue, async (newValue) => {
+  await someAsyncFunction()
+
+  // Whenever ready, update targets or root and init
+  targets.value = ['id-1', 'id-2', 'id-3']
+  root.value = document.getElementById('MyContainer')
+})
+</script>
+```
+
+<br />
+
 ## License
 
 MIT

demo/components/Sidebar/DemoControls.vue

@@ -1,5 +1,5 @@
 <script lang="ts" setup>
-import { inject, watch, Ref } from 'vue';
+import { inject, watch, type Ref } from 'vue';
 
 const { shiftSection, pushSection } = inject('DemoButtons') as {
 	shiftSection: () => void;

demo/components/Sidebar/TOC.vue

@@ -1,30 +1,26 @@
 <script lang="ts" setup>
-import { computed, ComputedRef, inject } from 'vue';
+import { computed, inject, type ComputedRef, type Ref } from 'vue';
 import { useRoute } from 'vue-router';
 import animateScrollTo from 'animated-scroll-to';
 import { useActive } from '../../../src/useActive';
 
 type TOCData = {
 	menuItems: { label: string; href: string }[];
 	targets: ComputedRef<string[]>;
-	rootId?: string | null;
+	containerRef: Ref<HTMLElement | null>;
 	overlayHeight?: number;
 };
 
-const { menuItems, targets, rootId = null, overlayHeight = 0 } = inject('TOCData') as TOCData;
+const { menuItems, targets, containerRef, overlayHeight = 0 } = inject('TOCData') as TOCData;
 
 const { clickType } = inject('DemoRadios') as {
 	clickType: ComputedRef<'native' | 'custom'>;
 };
 
 const { activeIndex, activeId, setActive, isActive } = useActive(targets, {
-	rootId,
+	root: containerRef,
 	overlayHeight,
 	replaceHash: true,
-	/* 	boundaryOffset: {
-		toBottom: 100,
-		toTop: -100,
-	}, */
 });
 
 const route = useRoute();
@@ -36,7 +32,7 @@ const activeItemHeight = computed(
 function customScroll(id: string) {
 	setActive(id);
 	animateScrollTo(document.getElementById(id) as HTMLElement, {
-		elementToScroll: rootId ? (document.getElementById(rootId) as HTMLElement) : window,
+		elementToScroll: containerRef?.value ?? window,
 		easing: (x: number) => 1 + (1.70158 + 1) * Math.pow(x - 1, 3) + 1.70158 * Math.pow(x - 1, 2),
 		maxDuration: 600,
 		verticalOffset: -overlayHeight || 0,
@@ -56,7 +52,7 @@ const onClick = computed(() => (clickType.value === 'native' ? setActive : custo
 				<RouterLink
 					@click.native="onClick(item.href)"
 					:ariaCurrentValue="`${isActive(item.href)}`"
-					:to="{ hash: `#${item.href}` }"
+					:to="{ hash: `#${item.href}` /* , replace: true */ }"
 					:class="{
 						Active: isActive(item.href),
 					}"

demo/pages/Container.vue

@@ -1,19 +1,21 @@
 <script setup lang="ts">
-import { computed, provide } from 'vue';
+import { computed, provide, ref } from 'vue';
 import PageLayout from './_Layout.vue';
 import { useFakeData } from '../useFakeData';
 
 const { menuItems, sections, /* Demo purposes => */ pushSection, shiftSection } = useFakeData();
 
 const targets = computed<string[]>(() => sections.map((section) => section.id));
 
-provide('TOCData', { menuItems, targets, rootId: 'ScrollingContainer' }); // Injected to TOC.vue
+const containerRef = ref<HTMLElement | null>(null);
+
+provide('TOCData', { menuItems, targets, containerRef }); // Injected to TOC.vue
 provide('DemoButtons', { pushSection, shiftSection }); // Injected to DemoControls.vue
 </script>
 
 <template>
 	<PageLayout>
-		<div id="ScrollingContainer">
+		<div ref="containerRef" class="Container">
 			<section v-for="section in sections" :key="section.id">
 				<h2 :id="section.id">
 					{{ section.title }}
@@ -25,7 +27,7 @@ provide('DemoButtons', { pushSection, shiftSection }); // Injected to DemoContro
 </template>
 
 <style scoped>
-#ScrollingContainer {
+.Container {
 	overflow: auto;
 	max-height: calc(100vh - 160px);
 	scroll-behavior: var(--ScrollBehavior);

demo/useFakeData.ts

@@ -18,8 +18,8 @@ export function useFakeData(length = 10) {
 		}))
 	);
 
-	const lastNum = computed(() => parseInt(sections[sections.length - 1].title));
-	const firstNum = computed(() => parseInt(sections[0].title));
+	const lastNum = computed(() => parseInt(sections[sections.length - 1]?.title ?? '-1'));
+	const firstNum = computed(() => parseInt(sections[0]?.title ?? '-1'));
 
 	const menuItems = computed(() =>
 		sections.map((item) => ({

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vue-use-active-scroll",
-	"version": "0.9.6",
+	"version": "0.9.7",
 	"private": false,
 	"description": "Reactive and accurate TOC/sidebar links without compromises for Vue 3.",
 	"keywords": [
@@ -49,20 +49,20 @@
 		"*.{ts,vue,md}": "prettier --write"
 	},
 	"devDependencies": {
-		"@rollup/plugin-terser": "^0.3.0",
+		"@rollup/plugin-terser": "^0.4.0",
 		"@types/node": "^18.11.18",
-		"@typescript-eslint/eslint-plugin": "^5.48.2",
-		"@typescript-eslint/parser": "^5.48.2",
+		"@typescript-eslint/eslint-plugin": "^5.49.0",
+		"@typescript-eslint/parser": "^5.49.0",
 		"@vitejs/plugin-vue": "^4.0.0",
 		"animated-scroll-to": "^2.3.0",
-		"cypress": "^12.3.0",
-		"eslint": "^8.32.0",
+		"cypress": "^12.4.1",
+		"eslint": "^8.33.0",
 		"eslint-plugin-vue": "^9.9.0",
 		"husky": "^8.0.3",
-		"playwright-webkit": "^1.29.2",
+		"playwright-webkit": "^1.30.0",
 		"prettier": "^2.8.3",
-		"rimraf": "^4.1.1",
-		"typescript": "^4.9.4",
+		"rimraf": "^4.1.2",
+		"typescript": "^4.9.5",
 		"vite": "^4.0.4",
 		"vite-plugin-dts": "^1.7.1",
 		"vue": "^3.2.45",