@delacour/react-native-bottom-sheet 0.1.0-alpha.0

package/src/core/sheet.types.ts

@@ -0,0 +1,93 @@
+/**
+ * The vocabulary every layer of the engine shares.
+ *
+ * Everything here is a plain type or a plain number so it can cross into a
+ * worklet unchanged. The enums are numeric on purpose: a shared value holding
+ * a string is a serialisation on every write, and `gestureSource` is written on
+ * every frame of a pan.
+ */
+
+/**
+ * A detent as the consumer writes it — pixels of sheet visible above its
+ * resting bottom line, or a percentage of the height available to the sheet.
+ *
+ * Height space throughout: `0` is closed, detents ascend, and `translateY` is
+ * derived from a height only at the moment a view needs it.
+ */
+export type DetentSpec = number | `${number}%`;
+
+/** What the sheet does when a keyboard it owns appears. */
+export type KeyboardBehavior = "interactive" | "extend" | "fillParent" | "none";
+
+/** What the sheet does when the keyboard it lifted for goes away. */
+export type KeyboardBlurBehavior = "none" | "restore";
+
+/**
+ * Which focused inputs count as the sheet's own.
+ *
+ * `registered` — only inputs that went through `useBottomSheetTextInput`.
+ * `inside` — those, plus any focused input whose frame lies inside the sheet.
+ * `always` — every keyboard, whoever asked for it.
+ */
+export type KeyboardScope = "registered" | "inside" | "always";
+
+/** Why an animation started — reported through `onChange` and `onAnimate`. */
+export type AnimationSource = "mount" | "gesture" | "user" | "snapPoints" | "keyboard" | "container";
+
+/**
+ * A request from the JS thread, resolved on the UI thread once layout is ready.
+ *
+ * Intents replace present/dismiss: closing a closed sheet resolves to nothing,
+ * an open before the first layout waits for it, and `forceClose` skips the
+ * animation. The `id` is what a reaction keys on, so two identical requests in
+ * a row both run.
+ */
+export type SheetIntent =
+	| { id: number; kind: "open" }
+	| { id: number; kind: "close" }
+	| { id: number; kind: "forceClose" }
+	| { id: number; kind: "snapToIndex"; index: number }
+	| { id: number; kind: "snapToPosition"; position: DetentSpec }
+	| { id: number; kind: "expand" }
+	| { id: number; kind: "collapse" };
+
+/** Which pan is driving the sheet this frame. */
+export const GESTURE_SOURCE = {
+	NONE: 0,
+	HANDLE: 1,
+	CONTENT: 2,
+} as const;
+
+export type GestureSource = (typeof GESTURE_SOURCE)[keyof typeof GESTURE_SOURCE];
+
+/** Where the sheet sits relative to its detents. */
+export const SHEET_STATE = {
+	CLOSED: 0,
+	OPENED: 1,
+	EXTENDED: 2,
+	OVER_EXTENDED: 3,
+	FILL: 4,
+} as const;
+
+export type SheetState = (typeof SHEET_STATE)[keyof typeof SHEET_STATE];
+
+/** A measurement that has not happened yet. Every measured shared value starts here. */
+export const UNMEASURED = -1;
+
+/** The index the sheet reports while closed. */
+export const CLOSED_INDEX = -1;
+
+/**
+ * What kind of scrollable, if any, is the sheet's body. Written by
+ * `createBottomSheetScrollable` on focus, `NONE` for static content — a
+ * content pan over static content may over-drag past the top, one over a list
+ * lets the list bounce instead.
+ */
+export const SCROLLABLE_TYPE = {
+	NONE: 0,
+	SCROLL_VIEW: 1,
+	FLAT_LIST: 2,
+	SECTION_LIST: 3,
+} as const;
+
+export type ScrollableType = (typeof SCROLLABLE_TYPE)[keyof typeof SCROLLABLE_TYPE];

package/src/display-name.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SRC = import.meta.dirname;
+
+/**
+ * Every component in the package must carry a `DelacourBottomSheet.`-prefixed
+ * displayName.
+ *
+ * React DevTools reads `displayName || name`, so without one a tree row, an
+ * error stack and a profiler entry all read the private symbol —
+ * `BottomSheetHandle` rather than `DelacourBottomSheet.BottomSheet.Handle`.
+ * `bun test` cannot render React Native, so the convention is checked against
+ * the source text instead: this file reads the `.tsx` tree off disk and imports
+ * nothing from it. It is the same test `@delacour/react-native-ui` runs, with
+ * the prefix changed, so a skin and its engine never answer to one name.
+ *
+ * The corpus spans every file at once rather than checking each in isolation,
+ * because a root is declared in one file and named by the `Object.assign` in
+ * another.
+ */
+
+/** Every `.tsx` under `src/`, as a path → source map. */
+function sources(): Map<string, string> {
+	const found = new Map<string, string>();
+	const walk = (dir: string): void => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const path = join(dir, entry.name);
+			if (entry.isDirectory()) walk(path);
+			else if (entry.name.endsWith(".tsx")) found.set(path, readFileSync(path, "utf-8"));
+		}
+	};
+	walk(SRC);
+	return found;
+}
+
+const SOURCES = sources();
+
+/**
+ * A PascalCase `function` declaration, or a `memo(…)` / `forwardRef(…)` const.
+ *
+ * Those are the only three shapes a component takes here: the package has no
+ * arrow-function components. A PascalCase helper would be a false positive —
+ * write helpers in camelCase.
+ */
+const DECLARATIONS = [
+	/^(?:export )?function ([A-Z][A-Za-z0-9]*)\s*[<(]/gm,
+	/^(?:export )?const ([A-Z][A-Za-z0-9]*) = memo\(/gm,
+	/^(?:export )?const ([A-Z][A-Za-z0-9]*) = forwardRef[<(]/gm,
+];
+
+/** The trailing form on a part, and the `Object.assign` form on a root. */
+const BINDINGS = [
+	/^([A-Z][A-Za-z0-9]*)\.displayName = "([^"]*)";/gm,
+	/Object\.assign\(\s*([A-Z][A-Za-z0-9]*)\s*,\s*\{[\s\S]*?displayName: "([^"]*)"/gm,
+];
+
+/** Component name → the file it is declared in. */
+function declared(): Map<string, string> {
+	const found = new Map<string, string>();
+	for (const [path, source] of SOURCES) {
+		for (const pattern of DECLARATIONS) {
+			for (const [, name] of source.matchAll(pattern)) found.set(name, path);
+		}
+	}
+	return found;
+}
+
+/** Component name → every displayName bound to it, across the whole tree. */
+function bound(): Map<string, string[]> {
+	const found = new Map<string, string[]>();
+	for (const source of SOURCES.values()) {
+		for (const pattern of BINDINGS) {
+			for (const [, name, value] of source.matchAll(pattern)) {
+				found.set(name, [...(found.get(name) ?? []), value]);
+			}
+		}
+	}
+	return found;
+}
+
+const DECLARED = declared();
+const BOUND = bound();
+
+/** `DelacourBottomSheet` plus one segment per step down the public API. */
+const SHAPE = /^DelacourBottomSheet(\.[A-Z][A-Za-z0-9]*)+$/;
+
+/**
+ * The floor under the walker: the eleven parts, the root, the slot and the
+ * context file, at the count BSHEET-2 landed. A walker matching nothing cannot
+ * keep the suite green on an empty set.
+ */
+const MIN_SOURCES = 13;
+const MIN_DECLARED = 12;
+
+/**
+ * Every `*.context.tsx`, as a path → source map.
+ *
+ * A context is `createContext<T | null>(null)` with a `useX()` that throws
+ * outside its provider and a `useOptionalX()` that returns `null`. Both are
+ * exported by name from the file that declares the context, so the convention
+ * is checked against the same source text.
+ */
+const CONTEXT_SOURCES = [...SOURCES].filter(([path]) => path.endsWith(".context.tsx"));
+
+const CONTEXT_DECLARATION = /^export const ([A-Z][A-Za-z0-9]*)Context = createContext</gm;
+
+describe("displayName", () => {
+	test("finds the component tree", () => {
+		expect(SOURCES.size).toBeGreaterThanOrEqual(MIN_SOURCES);
+		expect(DECLARED.size).toBeGreaterThanOrEqual(MIN_DECLARED);
+	});
+
+	test("every component has one", () => {
+		const missing = [...DECLARED]
+			.filter(([name]) => !BOUND.has(name))
+			.map(([name, path]) => `${name} (${path.slice(SRC.length + 1)})`);
+		expect(missing).toEqual([]);
+	});
+
+	// Two bindings on one component is a rename that only landed in one place.
+	test("no component has two", () => {
+		const doubled = [...BOUND].filter(([, values]) => values.length > 1).map(([name]) => name);
+		expect(doubled).toEqual([]);
+	});
+
+	test("every name is a DelacourBottomSheet path", () => {
+		const wrong = [...BOUND]
+			.filter(([, values]) => values.some((value) => !SHAPE.test(value)))
+			.map(([name, values]) => `${name} = ${values[0]}`);
+		expect(wrong).toEqual([]);
+	});
+
+	// Two components answering to one name is a copy-pasted part file.
+	test("no two components share a name", () => {
+		const seen = new Map<string, string>();
+		const clashes: string[] = [];
+		for (const [name, values] of BOUND) {
+			for (const value of values) {
+				const owner = seen.get(value);
+				if (owner) clashes.push(`${value}: ${owner} and ${name}`);
+				else seen.set(value, name);
+			}
+		}
+		expect(clashes).toEqual([]);
+	});
+
+	// A part's name is its path in the public API, so its root's name is a prefix
+	// of it. This is what keeps `BottomSheet.Handle` from drifting to `BottomSheet.Grip`.
+	test("every name descends from a component that exists", () => {
+		const names = new Set([...BOUND.values()].flat());
+		const orphans = [...names].filter((name) => {
+			const parent = name.slice(0, name.lastIndexOf("."));
+			return parent !== "DelacourBottomSheet" && !names.has(parent);
+		});
+		expect(orphans).toEqual([]);
+	});
+});
+
+describe("contexts", () => {
+	test("finds the context files", () => {
+		expect(CONTEXT_SOURCES.length).toBeGreaterThanOrEqual(1);
+	});
+
+	test("every context exports a throwing hook and an optional hook", () => {
+		const missing: string[] = [];
+		for (const [path, source] of CONTEXT_SOURCES) {
+			const contexts = [...source.matchAll(CONTEXT_DECLARATION)].map(([, name]) => name as string);
+			if (contexts.length === 0) missing.push(`${path.slice(SRC.length + 1)} declares no context`);
+			for (const name of contexts) {
+				if (!source.includes(`export function use${name}(`)) missing.push(`use${name}`);
+				if (!source.includes(`export function useOptional${name}(`)) missing.push(`useOptional${name}`);
+				if (!source.includes(`${name}Context.displayName = "DelacourBottomSheet.`)) {
+					missing.push(`${name}Context.displayName`);
+				}
+			}
+		}
+		expect(missing).toEqual([]);
+	});
+});

package/src/docs.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT, SRC, sourceFiles } from "./source-tree.test";
+
+/**
+ * Documentation is part of the change.
+ *
+ * `@delacour/react-native-ui` grew this test because `Radio` shipped undocumented
+ * and nothing caught it for fifteen commits. The same applies here, scoped to
+ * the top-level folders rather than every nested one — a doc per directory of
+ * four utility modules is noise, a doc per subsystem is not.
+ */
+describe("docs", () => {
+	const folders = readdirSync(SRC)
+		.map((entry) => join(SRC, entry))
+		.filter((path) => statSync(path).isDirectory())
+		.filter((path) => sourceFiles(path, { skipTests: true }).length > 0);
+
+	test("the package documents itself", () => {
+		const doc = join(PACKAGE_ROOT, "AGENTS.md");
+		expect(existsSync(doc)).toBe(true);
+		expect(readFileSync(doc, "utf8").split("\n").length).toBeGreaterThan(20);
+	});
+
+	test("finds the subsystems, so a broken walker cannot pass silently", () => {
+		expect(folders.length).toBeGreaterThan(0);
+	});
+
+	test("every subsystem has an AGENTS.md that is not a stub", () => {
+		const missing: string[] = [];
+		for (const folder of folders) {
+			const doc = join(folder, "AGENTS.md");
+			if (!existsSync(doc)) {
+				missing.push(`${folder.slice(SRC.length + 1)} has no AGENTS.md`);
+				continue;
+			}
+			const content = readFileSync(doc, "utf8");
+			if (!content.startsWith("# ") || content.split("\n").length < 10) {
+				missing.push(`${folder.slice(SRC.length + 1)}/AGENTS.md is a stub`);
+			}
+		}
+		expect(missing).toEqual([]);
+	});
+});

package/src/flat-worklet.test.ts

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import { read, relative, SRC, sourceFiles } from "./source-tree.test";
+
+/**
+ * The flat-worklet rule.
+ *
+ * **A worklet declared at module scope may close over module-scope constants
+ * but never over another function, imported or local.** Any helper it needs is
+ * declared inside its own body.
+ *
+ * Module scope is the whole rule. A module-scope worklet that calls another
+ * module-scope worklet binds at import time in source order, and the UI thread
+ * gets `undefined is not a function` — at the moment a finger touches the
+ * handle, on a device, with a stack that names neither function. Four
+ * components in `@delacour/react-native-ui` document having learned this.
+ *
+ * A worklet created *inside* a hook is captured by ordinary closure and may
+ * call whatever it likes, including the module-scope worklets here. That is
+ * how the pan composes `resistOverDrag` and `selectSnapHeight` without
+ * duplicating them.
+ */
+
+/** Members of these are always safe — they exist in every worklet runtime. */
+const GLOBAL_NAMESPACES = ["Math", "Number", "Array", "Object", "String", "JSON", "Boolean", "Date"];
+
+/** Control-flow keywords that look like calls to a regex. */
+const KEYWORDS = new Set(["if", "for", "while", "switch", "catch", "return", "typeof", "function", "new"]);
+
+/** The body of the block opening at `open`, by brace matching. */
+function blockAt(source: string, open: number): string {
+	let depth = 0;
+	for (let index = open; index < source.length; index += 1) {
+		const char = source[index];
+		if (char === "{") depth += 1;
+		else if (char === "}") {
+			depth -= 1;
+			if (depth === 0) return source.slice(open + 1, index);
+		}
+	}
+	return source.slice(open + 1);
+}
+
+/** Bodies of every column-zero `function` whose first statement is the directive. */
+function moduleScopeWorklets(source: string): { readonly name: string; readonly body: string }[] {
+	const found: { name: string; body: string }[] = [];
+	const declaration = /^(?:export\s+)?function\s+(\w+)/gm;
+
+	for (let match = declaration.exec(source); match !== null; match = declaration.exec(source)) {
+		const open = source.indexOf("{", match.index);
+		if (open === -1) continue;
+		const body = blockAt(source, open);
+		if (!body.trimStart().startsWith('"worklet";')) continue;
+		found.push({ name: match[1] as string, body });
+	}
+
+	return found;
+}
+
+/** Value names this module imports — the ones a module-scope worklet must not call. */
+function importedValues(source: string): Set<string> {
+	const names = new Set<string>();
+	const pattern = /^\s*import\s+([\s\S]*?)\s*from\s*["'][^"']+["']/gm;
+	for (let match = pattern.exec(source); match !== null; match = pattern.exec(source)) {
+		const clause = (match[1] as string).trim();
+		if (clause.startsWith("type ")) continue;
+		const named = clause.match(/\{([\s\S]*)\}/);
+		if (named) {
+			for (const raw of (named[1] as string).split(",")) {
+				const specifier = raw.trim();
+				if (specifier === "" || specifier.startsWith("type ")) continue;
+				names.add((specifier.split(/\s+as\s+/).pop() as string).trim());
+			}
+		}
+		const bare = clause
+			.replace(/\{[\s\S]*\}/, "")
+			.replace(/,/g, "")
+			.trim();
+		if (bare !== "" && !bare.startsWith("*")) names.add(bare);
+	}
+	return names;
+}
+
+/** Functions declared at module scope — also off limits inside a module-scope worklet. */
+function functionNames(source: string): Set<string> {
+	const names = new Set<string>();
+	const patterns = [
+		/(?:^|\n)\s*(?:export\s+)?function\s+(\w+)/g,
+		/(?:^|\n)\s*(?:export\s+)?const\s+(\w+)\s*=\s*(?:\([^)]*\)|\w+)\s*(?::[^=]+)?=>/g,
+	];
+	for (const pattern of patterns) {
+		for (let match = pattern.exec(source); match !== null; match = pattern.exec(source)) {
+			names.add(match[1] as string);
+		}
+	}
+	return names;
+}
+
+describe("flat worklets", () => {
+	const files = sourceFiles(SRC, { skipTests: true });
+
+	test("finds the module-scope worklets, so a broken walker cannot pass silently", () => {
+		const total = files.reduce((count, file) => count + moduleScopeWorklets(read(file)).length, 0);
+		expect(total).toBeGreaterThan(20);
+	});
+
+	test("no module-scope worklet calls an imported or module-scope function", () => {
+		const offenders: string[] = [];
+
+		for (const file of files) {
+			const source = read(file);
+			if (!source.includes('"worklet";')) continue;
+			const forbidden = new Set([...importedValues(source), ...functionNames(source)]);
+
+			for (const worklet of moduleScopeWorklets(source)) {
+				const declaredInside = functionNames(worklet.body);
+				const calls = /(?:^|[^.\w$])(\w+)\s*\(/g;
+
+				for (let call = calls.exec(worklet.body); call !== null; call = calls.exec(worklet.body)) {
+					const name = call[1] as string;
+					if (KEYWORDS.has(name) || GLOBAL_NAMESPACES.includes(name)) continue;
+					if (declaredInside.has(name) || name === worklet.name) continue;
+					if (!forbidden.has(name)) continue;
+					offenders.push(`${relative(file)}: ${worklet.name}() calls ${name}()`);
+				}
+			}
+		}
+
+		expect(offenders).toEqual([]);
+	});
+});

package/src/gesture/AGENTS.md

@@ -0,0 +1,71 @@
+# gesture
+
+The two pans that drive a sheet, and the haptic hooks they fire.
+
+## Files
+
+| Path | What |
+| --- | --- |
+| `gesture.types.ts` | `SheetPans` (handle and content), `SheetHaptics` (the three worklet props), `SheetPanOptions`, the activation constants |
+| `use-sheet-pan.ts` | `useSheetPan(state, geometry, animateTo, settleAt, options)` — both pans from one set of hook-scope handlers |
+
+## The handlers
+
+`onStart` cancels the animation that owns `base`, records the source (handle
+or content), where the drag began and which detent was under it.
+
+`onChange` turns the finger's travel into a height — `startBase −
+translationY`, less the scrollable's offset for a content pan once BSHEET-4
+wires one — rubber-banded by `resistOverDrag` past the lowest and highest
+detent and never above the container. The lowest is the closed height when
+`enablePanDownToClose`, else the first detent. `crossedDetent` decides the
+detent haptic; entering the rubber band fires the over-drag haptic once.
+
+`onFinalize`, not `onEnd`: a gesture that fails after activating never fires
+`onEnd`, and the sheet would be stranded between detents. `selectSnapHeight`
+projects the release velocity a fifth of a second ahead and picks the nearest
+candidate, closing only when the pan may close, and `animateTo` gets half the
+velocity in height space — upward positive, so `−velocityY`.
+
+A content pan over a scrollable is shared with the list. When `listOwnsRelease`
+says the release is the list's — the sheet at its highest detent, the list
+scrolled — the sheet does not snap, but it **still settles**: the finger moved
+`base` by hand, so no animation ran and nothing else would write
+`currentIndex`. `restingDetent` names the detent under `base` and `settleAt`
+does the bookkeeping of a finished animation without the motion —
+`currentIndex`, then `onSettle`, so the handle's accessibility value and
+`onIndexChange` catch up. A `return` there once left the index at the previous
+detent (or at `-1`) under a sheet sitting at 90%, and the next overlay tap did
+nothing because `close` read the sheet as already closed. Between detents,
+which the ownership test should rule out, the sheet snaps to the nearest with
+no velocity and never closes: the release velocity is the list's momentum.
+
+## Activation
+
+The content pan waits six points of vertical travel before it claims a touch
+and gives up after twelve horizontal, so a tap lands on the button or the
+field under it and a horizontal pager inside the sheet keeps its swipe. The
+handle pan claims immediately. Both keep running when the finger leaves the
+view. Scrollables (BSHEET-4) wrap their native gesture in
+`simultaneousWithExternalGesture(pans.content)`.
+
+## Per-gesture memory
+
+Where the drag began, the detent last under it and whether it is over-dragging
+live in shared values rather than closure variables. Each worklet gets its own
+copy of a captured `let`, so a write in `onStart` would never be seen by
+`onChange`.
+
+## Haptics
+
+The package imports nothing from a haptics library. `onDetentHaptic`,
+`onCloseHaptic` and `onOverDragHaptic` are worklets the consumer passes —
+`Presets.System.selection` from pulsar is one already — and they run inside the
+gesture handler, in the frame the crossing happened.
+
+## Why one shared gesture object per pan
+
+A gesture builder mutates in place. `Handle` and `Content` each take their pan
+from context and hand it to a `GestureDetector` untouched; a per-part opt-out
+leaves the detector out rather than calling `.enabled(false)` on the shared
+object, which would switch it off for every other part too.

package/src/gesture/gesture.types.ts

@@ -0,0 +1,37 @@
+import type { GestureType } from "react-native-gesture-handler";
+
+/**
+ * A haptic, as a worklet. The engine imports nothing from a haptics library;
+ * the skin passes `Presets.System.selection` and friends, which are worklets
+ * already, and they fire on the UI thread in the same frame as the crossing.
+ */
+export type HapticWorklet = () => void;
+
+export type SheetHaptics = {
+	/** A drag crossed a detent. */
+	onDetentHaptic?: HapticWorklet;
+	/** A drag let go on a close. */
+	onCloseHaptic?: HapticWorklet;
+	/** A drag left the detent range and the rubber band took over. */
+	onOverDragHaptic?: HapticWorklet;
+};
+
+export type SheetPanOptions = SheetHaptics & {
+	enableHandlePanningGesture: boolean;
+	enableContentPanningGesture: boolean;
+};
+
+/** The two pans, ready for a `GestureDetector` each. */
+export type SheetPans = {
+	handle: GestureType;
+	content: GestureType;
+};
+
+/** Seconds of release velocity the snap projects along — the `0.2` the previous engine used. */
+export const SNAP_PROJECTION = 0.2;
+
+/** How far a finger travels vertically before the content pan claims it, in pixels. */
+export const CONTENT_ACTIVE_OFFSET_Y = 6;
+
+/** Horizontal travel that hands the touch to a horizontal scrollable or pager instead. */
+export const CONTENT_FAIL_OFFSET_X = 12;