@delacour/react-native-ui 0.3.0-alpha.20261017084646 → 0.3.0-alpha.20261017120102

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.3.0-alpha.20261017084646",
+	"version": "0.3.0-alpha.20261017120102",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -93,6 +93,7 @@
 		"./hooks/use-controllable-state": "./src/hooks/use-controllable-state.ts",
 		"./hooks/use-keyboard-state-sync": "./src/hooks/use-keyboard-state-sync.tsx",
 		"./hooks/use-navigation-theme": "./src/hooks/use-navigation-theme.ts",
+		"./hooks/use-scroll-sections": "./src/hooks/use-scroll-sections.ts",
 		"./hooks/use-theme-color": "./src/hooks/use-theme-color.ts",
 		"./lib/calm-motion": "./src/lib/calm-motion.ts",
 		"./lib/cn": "./src/lib/cn.ts",
@@ -102,6 +103,7 @@
 		"./lib/merge-props": "./src/lib/merge-props.ts",
 		"./lib/navigation-theme": "./src/lib/navigation-theme.ts",
 		"./lib/paging": "./src/lib/paging.ts",
+		"./lib/scroll-sections": "./src/lib/scroll-sections.ts",
 		"./lib/slot": "./src/lib/slot.tsx",
 		"./lib/tv": "./src/lib/tv.ts",
 		"./icons/central": "./src/icons/central.ts"

package/src/hooks/use-scroll-sections.ts

@@ -0,0 +1,137 @@
+import { useCallback, useRef, useState } from "react";
+import type { LayoutChangeEvent } from "react-native";
+import type Animated from "react-native-reanimated";
+import {
+	type AnimatedRef,
+	type SharedValue,
+	scrollTo as scrollToWorklet,
+	useAnimatedRef,
+	useAnimatedScrollHandler,
+	useSharedValue,
+} from "react-native-reanimated";
+import { scheduleOnRN, scheduleOnUI } from "react-native-worklets";
+import {
+	resolveActiveSection,
+	resolveScrollProgress,
+	resolveSectionScrollTarget,
+	type SectionOffset,
+} from "../lib/scroll-sections";
+
+export type UseScrollSectionsOptions = {
+	/** Points below the viewport's top where a section counts as entered. Default 0. */
+	readingLine?: number;
+	/** Whether `scrollTo` animates. Default true. */
+	isAnimated?: boolean;
+	/** Fires when the reader crosses into a different section. */
+	onActiveChange?: (id: string) => void;
+};
+
+export type UseScrollSectionsResult = {
+	/** Attach to the `Animated.ScrollView` whose sections are tracked. */
+	scrollRef: AnimatedRef<Animated.ScrollView>;
+	/** Pass as that scroll view's `onScroll`, with `scrollEventThrottle={16}`. */
+	scrollHandler: ReturnType<typeof useAnimatedScrollHandler>;
+	/** `onLayout` for a section's box — a direct child of the scroll content. Stable per id. */
+	register: (id: string) => (event: LayoutChangeEvent) => void;
+	/** The section being read. React state: changes only when the section does. */
+	activeId: string | undefined;
+	/** 0–1, how far down the content the reader is. Updated on the UI thread. */
+	progress: SharedValue<number>;
+	/** The raw scroll offset. */
+	scrollY: SharedValue<number>;
+	/** Scrolls a section's top onto the reading line and makes it active at once. */
+	scrollTo: (id: string) => void;
+};
+
+/**
+ * Tracks which section of a scroll view the reader is in, and how far down they are, on the
+ * UI thread. `SectionProgress` and `SectionRail` read it; any custom table of contents can too.
+ *
+ * The scroll handler resolves the active section every frame but crosses to React only when it
+ * changes, so a scroll costs no renders. A `scrollTo` pins the target as active until the scroll
+ * arrives there (or the reader drags), so a jump from the first section to the last does not
+ * flick the label through every section in between.
+ *
+ * Offsets come from each section's `onLayout`, which reports `y` relative to the parent — so a
+ * registered section must be a direct child of the scroll content.
+ */
+export function useScrollSections({
+	readingLine = 0,
+	isAnimated = true,
+	onActiveChange,
+}: UseScrollSectionsOptions = {}): UseScrollSectionsResult {
+	const scrollRef = useAnimatedRef<Animated.ScrollView>();
+	const sections = useSharedValue<SectionOffset[]>([]);
+	const scrollY = useSharedValue(0);
+	const progress = useSharedValue(0);
+	const lastActive = useSharedValue<string | undefined>(undefined);
+	const pinned = useSharedValue<string | undefined>(undefined);
+	const [activeId, setActiveId] = useState<string | undefined>(undefined);
+
+	const report = useCallback(
+		(id: string) => {
+			setActiveId(id);
+			onActiveChange?.(id);
+		},
+		[onActiveChange]
+	);
+
+	const scrollHandler = useAnimatedScrollHandler({
+		onBeginDrag: () => {
+			pinned.value = undefined;
+		},
+		onScroll: (event) => {
+			const y = event.contentOffset.y;
+			scrollY.value = y;
+			progress.value = resolveScrollProgress(y, event.contentSize.height, event.layoutMeasurement.height);
+			const next = resolveActiveSection(sections.value, y, readingLine);
+			if (pinned.value !== undefined) {
+				if (next !== pinned.value) return;
+				pinned.value = undefined;
+			}
+			if (next !== undefined && next !== lastActive.value) {
+				lastActive.value = next;
+				scheduleOnRN(report, next);
+			}
+		},
+	});
+
+	const handlers = useRef(new Map<string, (event: LayoutChangeEvent) => void>());
+	const register = useCallback(
+		(id: string) => {
+			const cached = handlers.current.get(id);
+			if (cached) return cached;
+			const handler = (event: LayoutChangeEvent) => {
+				const y = event.nativeEvent.layout.y;
+				sections.modify((list) => {
+					"worklet";
+					const index = list.findIndex((section) => section.id === id);
+					if (index === -1) list.push({ id, y });
+					else list[index] = { id, y };
+					return list;
+				});
+			};
+			handlers.current.set(id, handler);
+			return handler;
+		},
+		[sections]
+	);
+
+	const scrollTo = useCallback(
+		(id: string) => {
+			const section = sections.value.find((candidate) => candidate.id === id);
+			if (section === undefined) return;
+			const target = resolveSectionScrollTarget(section.y, readingLine);
+			pinned.value = id;
+			lastActive.value = id;
+			report(id);
+			scheduleOnUI(() => {
+				"worklet";
+				scrollToWorklet(scrollRef, 0, target, isAnimated);
+			});
+		},
+		[isAnimated, lastActive, pinned, readingLine, report, scrollRef, sections]
+	);
+
+	return { scrollRef, scrollHandler, register, activeId, progress, scrollY, scrollTo };
+}

package/src/lib/scroll-sections.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { resolveActiveSection, resolveScrollProgress, resolveSectionScrollTarget } from "./scroll-sections";
+
+const sections = [
+	{ id: "intro", y: 0 },
+	{ id: "setup", y: 400 },
+	{ id: "usage", y: 1000 },
+];
+
+describe("resolveActiveSection", () => {
+	test("returns undefined with no sections", () => {
+		expect(resolveActiveSection([], 100, 0)).toBeUndefined();
+	});
+
+	test("picks the last section whose top has crossed the reading line", () => {
+		expect(resolveActiveSection(sections, 0, 0)).toBe("intro");
+		expect(resolveActiveSection(sections, 399, 0)).toBe("intro");
+		expect(resolveActiveSection(sections, 400, 0)).toBe("setup");
+		expect(resolveActiveSection(sections, 2000, 0)).toBe("usage");
+	});
+
+	test("the reading line moves the switch earlier", () => {
+		expect(resolveActiveSection(sections, 304, 96)).toBe("setup");
+		expect(resolveActiveSection(sections, 303, 96)).toBe("intro");
+	});
+
+	test("above the first section reads as the first section", () => {
+		expect(resolveActiveSection([{ id: "a", y: 200 }], 0, 0)).toBe("a");
+		expect(resolveActiveSection(sections, -80, 0)).toBe("intro");
+	});
+
+	test("reads sections in offset order, not registration order", () => {
+		const shuffled = [sections[2], sections[0], sections[1]].filter((s) => s !== undefined);
+		expect(resolveActiveSection(shuffled, 500, 0)).toBe("setup");
+	});
+});
+
+describe("resolveScrollProgress", () => {
+	test("is 0 at the top and 1 at the end", () => {
+		expect(resolveScrollProgress(0, 2000, 800)).toBe(0);
+		expect(resolveScrollProgress(1200, 2000, 800)).toBe(1);
+		expect(resolveScrollProgress(600, 2000, 800)).toBe(0.5);
+	});
+
+	test("clamps overscroll at both ends", () => {
+		expect(resolveScrollProgress(-50, 2000, 800)).toBe(0);
+		expect(resolveScrollProgress(1500, 2000, 800)).toBe(1);
+	});
+
+	test("is 1 when nothing scrolls", () => {
+		expect(resolveScrollProgress(0, 500, 800)).toBe(1);
+		expect(resolveScrollProgress(0, 800, 800)).toBe(1);
+	});
+});
+
+describe("resolveSectionScrollTarget", () => {
+	test("puts the section's top on the reading line", () => {
+		expect(resolveSectionScrollTarget(400, 96)).toBe(304);
+	});
+
+	test("never scrolls above the top", () => {
+		expect(resolveSectionScrollTarget(40, 96)).toBe(0);
+	});
+});

package/src/lib/scroll-sections.ts

@@ -0,0 +1,44 @@
+/** A section of a scrolled screen: its id and the top of its box in content coordinates. */
+export type SectionOffset = { id: string; y: number };
+
+/**
+ * The section the reader is in: the last one whose top has crossed the reading line, a fixed
+ * distance below the top of the viewport. Above the first section's top the first section is
+ * still the answer — a screen with a header before its first section is reading that section.
+ *
+ * Sections are read in offset order, not registration order: `onLayout` reports in whatever
+ * order the native views measure, and a section mounted late would otherwise win the tie.
+ */
+export function resolveActiveSection(
+	sections: readonly SectionOffset[],
+	scrollY: number,
+	readingLine: number
+): string | undefined {
+	"worklet";
+	if (sections.length === 0) return undefined;
+	const line = scrollY + readingLine;
+	let first: SectionOffset | undefined;
+	let active: SectionOffset | undefined;
+	for (const section of sections) {
+		if (first === undefined || section.y < first.y) first = section;
+		if (section.y <= line && (active === undefined || section.y >= active.y)) active = section;
+	}
+	return (active ?? first)?.id;
+}
+
+/**
+ * How far down the content the reader is, 0 to 1. Overscroll clamps at both ends, and a screen
+ * whose content fits reads as finished — there is nothing left to read.
+ */
+export function resolveScrollProgress(scrollY: number, contentHeight: number, viewportHeight: number): number {
+	"worklet";
+	const range = contentHeight - viewportHeight;
+	if (range <= 0) return 1;
+	return Math.min(1, Math.max(0, scrollY / range));
+}
+
+/** The scroll offset that puts a section's top on the reading line, never above the top. */
+export function resolveSectionScrollTarget(y: number, readingLine: number): number {
+	"worklet";
+	return Math.max(0, y - readingLine);
+}