@joewinke/jatui 0.8.2 → 0.8.3

package/CLAUDE.md

@@ -134,7 +134,7 @@ import { loadLiveKit, isLiveKitAvailable, LiveKitNotInstalledError } from 'jatui
 |-----------|---------|-----------|
 | `ResizablePanel` | Resizable container | `minWidth`, `maxWidth`, `defaultWidth` |
 | `ResizableDivider` | Drag handle between panels | `onResize` |
-| `SectionNav` | Sticky in-page section index for long single-column pages — vertical rail beside the content on xl+, wrapping chip row above it below xl. Built-in IntersectionObserver scroll-spy (omit `activeId` and it just works; bind it to observe/control). Amber dot per `dirtyIds` marks sections holding unsaved edits. `go()` scrolls AND moves focus so keyboard/SR users land where the click did. j/k/Enter via `listNav`. Layout contract: parent is a `flex flex-wrap gap-8 items-start` row, content column `flex-1 min-w-0`; sections need `id` + `scroll-mt-*`. | `sections: {id,label}[]`, `activeId?` (bindable), `dirtyIds?: Set<string>`, `ariaLabel?`, `spy?` |
+| `SectionNav` | Sticky in-page section index for long single-column pages — vertical rail beside the content on xl+, wrapping chip row above it below xl. Built-in scroll-spy (omit `activeId` and it just works; `bind:activeId` to observe/control — the spy writes back to it): on every observer callback + rAF-throttled scroll/resize it measures ALL sections and activates the last one whose top is at/above the activation line (`activationRatio`, default 0.3 of the scroller height); at the bottom of the page the last section wins. Clicking an item activates it immediately and holds the spy off until the smooth scroll lands (`scrollend`, or 800ms after the last scroll event); reduced-motion scrolls instantly. Pure decision fn exported as `computeActiveSection(rects, viewport, scroll, ratio?)`. Amber dot per `dirtyIds` marks sections holding unsaved edits. `go()` scrolls AND moves focus so keyboard/SR users land where the click did. j/k/Enter via `listNav`. Layout contract: parent is a `flex flex-wrap gap-8 items-start` row, content column `flex-1 min-w-0`; sections need `id` + `scroll-mt-*`. | `sections: {id,label}[]`, `activeId?` (bindable), `dirtyIds?: Set<string>`, `ariaLabel?`, `spy?`, `activationRatio?` (0.3) |
 
 ### Audio & Voice
 

package/dist/components/basic/SectionNav.svelte

@@ -19,14 +19,27 @@
 	 * sticky header never covers the heading it lands on.
 	 *
 	 * Scroll-spy: pass `activeId` (optionally bound) to control/observe the
-	 * active section yourself, or omit it entirely and the built-in
-	 * IntersectionObserver drives the highlight for you. `dirtyIds` marks
-	 * sections holding unsaved edits — any page long enough to need an index
-	 * is long enough to hide a dirty field; don't drop the dot.
+	 * active section yourself, or omit it entirely and the built-in spy drives
+	 * the highlight for you. The spy writes back to `activeId`, so
+	 * `bind:activeId` consumers see every change. `dirtyIds` marks sections
+	 * holding unsaved edits — any page long enough to need an index is long
+	 * enough to hide a dirty field; don't drop the dot.
+	 *
+	 * How the spy decides (mos-fv9gj): on every IntersectionObserver callback,
+	 * scroll (rAF-throttled, passive) and resize it measures ALL sections and
+	 * picks the last one whose top is at or above the activation line
+	 * (`activationRatio` of the scroll area's height, default 30%) — never just
+	 * the observer batch, which misses sections a fast scroll skips over and
+	 * leaves a stale highlight when a section leaves. At the bottom of the page
+	 * the last section wins (it may never reach the line). Clicking an item
+	 * activates it immediately and holds the spy off until the smooth scroll
+	 * settles (`scrollend`, or 800ms after the last scroll event).
 	 *
 	 * Purely navigational — it owns no form state.
 	 */
+	import { untrack } from 'svelte';
 	import { listNav } from '../../actions/listNav';
+	import { computeActiveSection, DEFAULT_ACTIVATION_RATIO, type SectionRect } from './sectionNavSpy';
 
 	type Section = { id: string; label: string };
 
@@ -35,7 +48,8 @@
 		activeId = $bindable(),
 		dirtyIds = new Set<string>(),
 		ariaLabel = 'Sections on this page',
-		spy = true
+		spy = true,
+		activationRatio = DEFAULT_ACTIVATION_RATIO
 	}: {
 		sections: Section[];
 		/** Bindable. Omit (or bind to observe) — the built-in scroll-spy keeps it current either way. */
@@ -43,46 +57,170 @@
 		/** Sections holding unsaved edits, marked so a long page can't hide one. */
 		dirtyIds?: Set<string>;
 		ariaLabel?: string;
-		/** Run the built-in IntersectionObserver scroll-spy. Default true. */
+		/** Run the built-in scroll-spy. Default true. */
 		spy?: boolean;
+		/** Activation line as a fraction of the scroll area's height (0–1). Default 0.3. */
+		activationRatio?: number;
 	} = $props();
 
-	let active = $state(activeId ?? sections[0]?.id ?? '');
+	let active = $state(untrack(() => activeId ?? sections[0]?.id ?? ''));
 
-	// External control wins whenever the consumer passes/updates the prop
-	// (bound consumers get spy updates two-way, so this converges, not fights).
+	// External control wins whenever the consumer passes/updates the prop.
+	// Only `activeId` is tracked, so a spy update is never reverted by a
+	// stale, unbound prop value.
 	$effect(() => {
-		if (activeId !== undefined && activeId !== active) active = activeId;
+		const ext = activeId;
+		if (ext !== undefined && ext !== untrack(() => active)) active = ext;
 	});
 
-	// Built-in scroll-spy: topmost section whose band crosses the upper third
-	// of the viewport becomes active. Re-observes when `sections` changes.
+	/** Single write path: local highlight + the bindable prop. */
+	function setActive(id: string) {
+		if (!id) return;
+		if (active !== id) active = id;
+		if (activeId !== id) activeId = id;
+	}
+
+	// Click-lock: while a nav-initiated scroll is in flight the spy is muted,
+	// otherwise the landing position can hand the highlight to a neighbour.
+	let clickLocked = false;
+	let lockTarget: HTMLElement | null = null;
+	let unlockTimer: ReturnType<typeof setTimeout> | undefined;
+	const CLICK_LOCK_FALLBACK_MS = 800;
+
+	function unlock() {
+		clickLocked = false;
+		lockTarget = null;
+		clearTimeout(unlockTimer);
+		unlockTimer = undefined;
+	}
+
+	function armUnlockFallback() {
+		clearTimeout(unlockTimer);
+		unlockTimer = setTimeout(unlock, CLICK_LOCK_FALLBACK_MS);
+	}
+
+	/** Nearest ancestor that actually scrolls, or null for the document. */
+	function scrollParent(el: HTMLElement | null): HTMLElement | null {
+		for (let p = el?.parentElement ?? null; p && p !== document.body && p !== document.documentElement; p = p.parentElement) {
+			const oy = getComputedStyle(p).overflowY;
+			if ((oy === 'auto' || oy === 'scroll' || oy === 'overlay') && p.scrollHeight > p.clientHeight) return p;
+		}
+		return null;
+	}
+
+	/** Visible area + scroll position of the section scroller (a container, or the window). */
+	function metrics(container: HTMLElement | null) {
+		if (container) {
+			const r = container.getBoundingClientRect();
+			return {
+				viewport: { top: r.top, height: container.clientHeight },
+				scroll: { scrollTop: container.scrollTop, clientHeight: container.clientHeight, scrollHeight: container.scrollHeight }
+			};
+		}
+		return {
+			viewport: { top: 0, height: window.innerHeight },
+			scroll: { scrollTop: window.scrollY, clientHeight: window.innerHeight, scrollHeight: document.documentElement.scrollHeight }
+		};
+	}
+
+	/**
+	 * Has the click-initiated scroll reached its destination? A `scrollend`
+	 * can belong to a DIFFERENT scroll (one this click interrupted, or a
+	 * scroll-into-view of the button itself), so it only releases the lock
+	 * once the target sits at its landing spot — or the scroller is pinned
+	 * against the edge it would need to pass. Otherwise the fallback timer
+	 * (re-armed on every scroll event) releases it.
+	 */
+	function landed(container: HTMLElement | null): boolean {
+		if (!lockTarget || !lockTarget.isConnected) return true;
+		const { viewport, scroll } = metrics(container);
+		const margin = parseFloat(getComputedStyle(lockTarget).scrollMarginTop) || 0;
+		const delta = lockTarget.getBoundingClientRect().top - (viewport.top + margin);
+		if (Math.abs(delta) <= 2) return true;
+		if (delta > 0 && scroll.scrollTop + scroll.clientHeight >= scroll.scrollHeight - 2) return true;
+		if (delta < 0 && scroll.scrollTop <= 0) return true;
+		return false;
+	}
+
 	$effect(() => {
 		if (!spy) return;
-		const els = sections
-			.map((s) => document.getElementById(s.id))
-			.filter((el): el is HTMLElement => !!el);
+		const ids = sections.map((s) => s.id);
+		const ratio = activationRatio;
+		const els = ids.map((id) => document.getElementById(id)).filter((el): el is HTMLElement => !!el);
 		if (els.length === 0) return;
-		const io = new IntersectionObserver(
-			(entries) => {
-				const visible = entries
-					.filter((e) => e.isIntersecting)
-					.sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
-				if (visible[0]) active = visible[0].target.id;
-			},
-			{ rootMargin: '-10% 0px -70% 0px', threshold: 0 }
-		);
+
+		const container = scrollParent(els[0]);
+		const scrollTarget: HTMLElement | Window = container ?? window;
+		let raf = 0;
+
+		function recompute() {
+			raf = 0;
+			if (clickLocked) return;
+			const rects: SectionRect[] = [];
+			for (const id of ids) {
+				const el = document.getElementById(id);
+				if (el) rects.push({ id, top: el.getBoundingClientRect().top });
+			}
+			const { viewport, scroll } = metrics(container);
+			const id = computeActiveSection(rects, viewport, scroll, ratio);
+			if (id) setActive(id);
+		}
+
+		function schedule() {
+			if (clickLocked) {
+				// Programmatic scroll still moving — push the fallback unlock out.
+				armUnlockFallback();
+				return;
+			}
+			if (!raf) raf = requestAnimationFrame(recompute);
+		}
+
+		const scrollEnd = () => {
+			if (clickLocked && landed(container)) unlock();
+		};
+
+		// Any user-initiated scroll gesture ends the click-lock immediately.
+		const userScroll = () => {
+			if (clickLocked) unlock();
+		};
+
+		// The observer is only a trigger (layout shifts, lazy content); the
+		// decision always comes from measuring every section.
+		const io = new IntersectionObserver(schedule, { root: container, threshold: [0, 1] });
 		for (const el of els) io.observe(el);
-		return () => io.disconnect();
+
+		const passive = { passive: true } as const;
+		scrollTarget.addEventListener('scroll', schedule, passive);
+		scrollTarget.addEventListener('scrollend', scrollEnd, passive);
+		window.addEventListener('resize', schedule, passive);
+		window.addEventListener('wheel', userScroll, passive);
+		window.addEventListener('touchstart', userScroll, passive);
+
+		untrack(schedule);
+
+		return () => {
+			io.disconnect();
+			scrollTarget.removeEventListener('scroll', schedule);
+			scrollTarget.removeEventListener('scrollend', scrollEnd);
+			window.removeEventListener('resize', schedule);
+			window.removeEventListener('wheel', userScroll);
+			window.removeEventListener('touchstart', userScroll);
+			if (raf) cancelAnimationFrame(raf);
+			unlock();
+		};
 	});
 
 	function go(id: string) {
 		const el = document.getElementById(id);
 		if (!el) return;
-		el.scrollIntoView({
-			behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth',
-			block: 'start'
-		});
+		setActive(id);
+		if (spy) {
+			clickLocked = true;
+			lockTarget = el;
+			armUnlockFallback();
+		}
+		const reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+		el.scrollIntoView({ behavior: reduce ? 'instant' : 'smooth', block: 'start' });
 		// Move focus so keyboard and screen-reader users land where the click
 		// did, not back at the top of the document.
 		el.focus({ preventScroll: true });

package/dist/components/basic/SectionNav.svelte.d.ts

@@ -9,8 +9,10 @@ type $$ComponentProps = {
     /** Sections holding unsaved edits, marked so a long page can't hide one. */
     dirtyIds?: Set<string>;
     ariaLabel?: string;
-    /** Run the built-in IntersectionObserver scroll-spy. Default true. */
+    /** Run the built-in scroll-spy. Default true. */
     spy?: boolean;
+    /** Activation line as a fraction of the scroll area's height (0–1). Default 0.3. */
+    activationRatio?: number;
 };
 declare const SectionNav: import("svelte").Component<$$ComponentProps, {}, "activeId">;
 type SectionNav = ReturnType<typeof SectionNav>;

package/dist/components/basic/sectionNavSpy.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure scroll-spy logic for SectionNav (mos-fv9gj).
+ *
+ * Kept DOM-free so it can be unit-tested with node:test (tests/unit/).
+ * The component measures every registered section on each observer callback
+ * and on every (rAF-throttled) scroll, then asks this function which one is
+ * active. It NEVER infers from an IntersectionObserver batch: a batch only
+ * holds the entries whose intersection changed, so a section that left the
+ * band — or that a fast scroll carried straight through it between two
+ * frames — is simply absent from it.
+ */
+/** One registered section, measured in the same coordinate space as `viewport`. */
+export type SectionRect = {
+    id: string;
+    top: number;
+};
+/** The visible scroll area: `window` (top 0, height innerHeight) or a scrolling container's rect. */
+export type SpyViewport = {
+    top: number;
+    height: number;
+};
+/** Scroll position of the scroll area, used for the bottom-of-page rule. */
+export type SpyScrollState = {
+    scrollTop: number;
+    clientHeight: number;
+    scrollHeight: number;
+};
+/** Default activation line: 30% of the way down the visible scroll area. */
+export declare const DEFAULT_ACTIVATION_RATIO = 0.3;
+/** Pixels of slack for "scrolled to the bottom" (sub-pixel rounding, zoom). */
+export declare const BOTTOM_EPSILON = 2;
+/**
+ * Which section is active?
+ *
+ * 1. At the bottom of a scrollable area, the LAST section — on a short page the
+ *    last one or two sections can never climb to the activation line, because
+ *    the page ends first.
+ * 2. Otherwise, the LAST section (in document order) whose top is at or above
+ *    the activation line (`viewport.top + viewport.height * activationRatio`).
+ * 3. Before the first section has reached the line (page header still showing),
+ *    the FIRST section.
+ *
+ * `sections` must be in document order. Returns null only when it is empty.
+ */
+export declare function computeActiveSection(sections: SectionRect[], viewport: SpyViewport, scroll: SpyScrollState, activationRatio?: number): string | null;

package/dist/components/basic/sectionNavSpy.js

@@ -0,0 +1,44 @@
+/**
+ * Pure scroll-spy logic for SectionNav (mos-fv9gj).
+ *
+ * Kept DOM-free so it can be unit-tested with node:test (tests/unit/).
+ * The component measures every registered section on each observer callback
+ * and on every (rAF-throttled) scroll, then asks this function which one is
+ * active. It NEVER infers from an IntersectionObserver batch: a batch only
+ * holds the entries whose intersection changed, so a section that left the
+ * band — or that a fast scroll carried straight through it between two
+ * frames — is simply absent from it.
+ */
+/** Default activation line: 30% of the way down the visible scroll area. */
+export const DEFAULT_ACTIVATION_RATIO = 0.3;
+/** Pixels of slack for "scrolled to the bottom" (sub-pixel rounding, zoom). */
+export const BOTTOM_EPSILON = 2;
+/**
+ * Which section is active?
+ *
+ * 1. At the bottom of a scrollable area, the LAST section — on a short page the
+ *    last one or two sections can never climb to the activation line, because
+ *    the page ends first.
+ * 2. Otherwise, the LAST section (in document order) whose top is at or above
+ *    the activation line (`viewport.top + viewport.height * activationRatio`).
+ * 3. Before the first section has reached the line (page header still showing),
+ *    the FIRST section.
+ *
+ * `sections` must be in document order. Returns null only when it is empty.
+ */
+export function computeActiveSection(sections, viewport, scroll, activationRatio = DEFAULT_ACTIVATION_RATIO) {
+    if (sections.length === 0)
+        return null;
+    const scrollable = scroll.scrollHeight > scroll.clientHeight + BOTTOM_EPSILON;
+    const atBottom = scrollable && scroll.scrollTop + scroll.clientHeight >= scroll.scrollHeight - BOTTOM_EPSILON;
+    if (atBottom)
+        return sections[sections.length - 1].id;
+    const ratio = Number.isFinite(activationRatio) ? Math.min(1, Math.max(0, activationRatio)) : DEFAULT_ACTIVATION_RATIO;
+    const line = viewport.top + viewport.height * ratio;
+    let active = sections[0].id;
+    for (const s of sections) {
+        if (s.top <= line)
+            active = s.id;
+    }
+    return active;
+}

package/dist/index.d.ts

@@ -213,5 +213,7 @@ export { default as RadioGroup } from './components/basic/RadioGroup.svelte';
 export { default as Toggle } from './components/basic/Toggle.svelte';
 export { default as Separator } from './components/basic/Separator.svelte';
 export { default as SectionNav } from './components/basic/SectionNav.svelte';
+export { computeActiveSection, DEFAULT_ACTIVATION_RATIO } from './components/basic/sectionNavSpy';
+export type { SectionRect, SpyViewport, SpyScrollState } from './components/basic/sectionNavSpy';
 export { default as Slider } from './components/basic/Slider.svelte';
 export { default as Pagination } from './components/basic/Pagination.svelte';

package/dist/index.js

@@ -233,5 +233,6 @@ export { default as RadioGroup } from './components/basic/RadioGroup.svelte';
 export { default as Toggle } from './components/basic/Toggle.svelte';
 export { default as Separator } from './components/basic/Separator.svelte';
 export { default as SectionNav } from './components/basic/SectionNav.svelte';
+export { computeActiveSection, DEFAULT_ACTIVATION_RATIO } from './components/basic/sectionNavSpy';
 export { default as Slider } from './components/basic/Slider.svelte';
 export { default as Pagination } from './components/basic/Pagination.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -76,6 +76,7 @@
     "check:demos": "node scripts/check-demo-coverage.mjs",
     "guard": "node scripts/check-demo-coverage.mjs",
     "test:dist": "svelte-kit sync && vitest run --config vitest.dist.config.ts",
+    "test:unit": "node --test tests/unit/",
     "prepublishOnly": "node scripts/guard-ci-publish.mjs && npm run package"
   },
   "peerDependencies": {