@delacour/react-native-ui 0.1.0-alpha.20260927220206 → 0.1.0-alpha.20261004035233

package/README.md

@@ -19,14 +19,16 @@ register twice and break at runtime. The complete list — native modules throug
 `expo install`, the rest through your package manager — is derived from the
 components' own imports and kept on the
 [Installation page](https://ui.delacour.co.nz/docs/native/getting-started/installation).
-Four peers are optional and resolve only if you import the subpath that needs them:
+Six peers are optional and resolve only if you import the subpath that needs them:
 
 | Peer | Needed for |
 | --- | --- |
 | `expo-router` | `@delacour/react-native-ui/expo/navigation-theme` |
-| `@legendapp/list` | `Screen.LegendList` and `Screen.ChatList` |
+| `@legendapp/list` | `Screen.LegendList`, `Screen.ChatList` and `BottomSheet.LegendList` |
 | `react-native-screens` | native stack navigation |
 | `@delacour/react-native-charts` | `Chart` |
+| `@delacour/react-native-bottom-sheet` | `BottomSheet` — the engine it skins |
+| `react-native-teleport` | `BottomSheet` — the engine's portal; a native module, so rebuild the dev client after installing |
 
 Granular exports are what make that safe: an app that never imports a subpath
 never makes Metro resolve its peers.
@@ -53,8 +55,10 @@ import { DelacourProvider } from "@delacour/react-native-ui/provider";
 ```
 
 That is the gesture root every `Pressable` needs above it, the safe-area provider
-and keyboard provider `Screen` reads, the bottom-sheet modal provider, and the
-keyboard state sync that keeps them honest.
+and keyboard provider `Screen` reads, and the keyboard state sync that keeps them
+honest. An app with a `BottomSheet` mounts `BottomSheetProvider` inside it, from
+`@delacour/react-native-ui/bottom-sheet` — the sheet's engine is an optional peer,
+so the provider cannot.
 
 ## Usage
 
@@ -78,7 +82,7 @@ import { IconArrowRight } from "@delacour/react-native-ui/icons/central";
 | --- | --- | --- |
 | Accordion | `@delacour/react-native-ui/accordion` | Selection modes, measured panels, indicators |
 | Badge | `@delacour/react-native-ui/badge` | Variants, colours, sizes, dismiss |
-| BottomSheet | `@delacour/react-native-ui/bottom-sheet` | Overlay, snap points, sticky footer, keyboard |
+| BottomSheet | `@delacour/react-native-ui/bottom-sheet` | Detents, keyboard, sticky footer, scrollables, steps, detached, teleported portal |
 | Button | `@delacour/react-native-ui/button` | Variants, sizes, icons, loading |
 | Checkbox | `@delacour/react-native-ui/checkbox` | Colours, sizes, indeterminate, groups |
 | Field | `@delacour/react-native-ui/field` | Form layout, grouping, state cascade |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20260927220206",
+	"version": "0.1.0-alpha.20261004035233",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -71,10 +71,12 @@
 		"./textarea": "./src/components/textarea/index.ts",
 		"./toggle-button": "./src/components/toggle-button/index.ts",
 		"./expo/navigation-theme": "./src/expo/navigation-theme.tsx",
+		"./hooks/use-calm-motion": "./src/hooks/use-calm-motion.tsx",
 		"./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-theme-color": "./src/hooks/use-theme-color.ts",
+		"./lib/calm-motion": "./src/lib/calm-motion.ts",
 		"./lib/cn": "./src/lib/cn.ts",
 		"./lib/color": "./src/lib/color.ts",
 		"./lib/compose-refs": "./src/lib/compose-refs.ts",
@@ -98,8 +100,8 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": "0.1.0-alpha.20260927220206",
-		"@gorhom/bottom-sheet": "^5.2.8",
+		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261004035233",
+		"@delacour/react-native-charts": "0.1.0-alpha.20261004035233",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",
 		"expo-router": ">=57",
@@ -112,11 +114,15 @@
 		"react-native-safe-area-context": ">=5",
 		"react-native-screens": ">=4.16",
 		"react-native-svg": ">=15",
+		"react-native-teleport": ">=1.2",
 		"react-native-worklets": ">=0.5",
 		"tailwindcss": "^4",
 		"uniwind": "^1.11.0"
 	},
 	"peerDependenciesMeta": {
+		"@delacour/react-native-bottom-sheet": {
+			"optional": true
+		},
 		"@delacour/react-native-charts": {
 			"optional": true
 		},
@@ -128,15 +134,20 @@
 		},
 		"react-native-screens": {
 			"optional": true
+		},
+		"react-native-teleport": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
 		"@delacour/biome-config": "workspace:*",
+		"@delacour/react-native-bottom-sheet": "workspace:*",
 		"@delacour/react-native-charts": "workspace:*",
 		"@delacour/tsconfig": "workspace:*",
 		"@types/bun": "^1.3.8",
 		"@types/react": "catalog:",
 		"expo-router": "~57.0.15",
+		"react-native-teleport": "^1.2.2",
 		"typescript": "^5.9.3"
 	}
 }

package/src/components/accordion/AGENTS.md

@@ -24,7 +24,7 @@ a list of rows.
 | `accordion.context.tsx` | `AccordionContext` and `AccordionItemContext`, with their hooks |
 | `accordion.types.ts` | Prop types shared by two or more parts |
 | `accordion.variants.ts` | Pure `tv()` slots + the selection maths, no RN imports |
-| `accordion.variants.test.ts` | |
+| `accordion.variants.test.ts` | `accordionTravelTarget`, and the sweep for a JS-thread `contentHeight.value` read (exports `jsThreadSource` and `CONTENT_HEIGHT_READ` for `Collapsible`'s) |
 
 ## Design
 
@@ -90,12 +90,23 @@ a list of rows.
   effect.** A panel that has never mounted has no height to travel against, so
   springing on the state change would run the whole animation at zero and jump
   the moment a measurement arrived. The item's effect skips exactly that one
-  case and `accordion-content.tsx`'s `onLayout` starts it instead. Every later
-  toggle, in either direction, is the item's.
+  case and `accordion-content.tsx`'s `onLayout` reports the measurement, which
+  flips the item's `isMeasured` state and re-runs the effect. Every later toggle,
+  in either direction, is the item's. The decision is `accordionTravelTarget`,
+  pure and tested.
+- **Nothing on the JS thread reads `contentHeight.value`.** "Has this panel
+  measured?" is React state (`isMeasured`, on both the item and the panel), never
+  a read of the shared value. A JS-thread write to a shared value is *queued* onto
+  the UI runtime, while a JS-thread read runs there synchronously under its lock
+  without draining that queue — so the item's effect, running straight after the
+  `onLayout` that wrote the height, can read `ACCORDION_UNMEASURED`. A Release
+  build does, deterministically: the effect bailed, nothing re-ran it, and the
+  panel reported `expanded` while never opening (a Debug client is slow enough
+  for the write to land first, which is why it hid). `accordion.variants.test.ts`
+  sweeps both files for such a read outside `useAnimatedStyle`.
 - **`ACCORDION_UNMEASURED` is negative, and that is load-bearing.** A panel that
-  measured `0` is a real answer — content that rendered nothing — and an item
-  treating it as "still waiting" would never start its spring, leaving the
-  indicator pointing the wrong way. Only a value no layout can produce can mean
+  measured `0` is a real answer — content that rendered nothing — and must still
+  open, indicator and all. Only a value no layout can produce can mean
   *unmeasured*, so the height style floors it.
 
 ## Selection

package/src/components/accordion/accordion-content.tsx

@@ -2,7 +2,7 @@ import { type ReactElement, type ReactNode, useCallback, useState } from "react"
 import { type LayoutChangeEvent, StyleSheet, View, type ViewProps } from "react-native";
 import Animated, { interpolate, useAnimatedStyle } from "react-native-reanimated";
 import { useAccordionItemPart, useAccordionPart } from "./accordion.context";
-import { ACCORDION_CONTENT_FADE, ACCORDION_UNMEASURED, accordionVariants } from "./accordion.variants";
+import { ACCORDION_CONTENT_FADE, accordionVariants } from "./accordion.variants";
 
 export type AccordionContentProps = Omit<ViewProps, "style"> & {
 	className?: string;
@@ -55,7 +55,6 @@ export function AccordionContent({ className, children, ...props }: AccordionCon
 
 	const handleLayout = useCallback(
 		(event: LayoutChangeEvent) => {
-			const wasMeasured = contentHeight.value > ACCORDION_UNMEASURED;
 			contentHeight.value = event.nativeEvent.layout.height;
 
 			// The panel reports its first measurement and stops there — it must not
@@ -64,11 +63,15 @@ export function AccordionContent({ className, children, ...props }: AccordionCon
 			// is sometimes cancelled a moment later by the cleanup of the item's
 			// effect it raced, leaving the panel shut and the indicator pointing the
 			// wrong way. Telling the item instead leaves one owner of the spring.
-			if (wasMeasured) return;
+			//
+			// "First" is this component's own state, never `contentHeight.value`: the
+			// write above is queued onto the UI runtime, and a JS-thread read straight
+			// after it can still see the old value.
+			if (isMeasured) return;
 			setMeasured(true);
 			onMeasured();
 		},
-		[contentHeight, onMeasured]
+		[contentHeight, isMeasured, onMeasured]
 	);
 
 	// Height and opacity off the one `progress`, never off a timing of their own —

package/src/components/accordion/accordion-item.tsx

@@ -5,6 +5,7 @@ import { type AccordionItemContextValue, AccordionItemProvider, useAccordionPart
 import {
 	ACCORDION_SPRING,
 	ACCORDION_UNMEASURED,
+	accordionTravelTarget,
 	accordionVariants,
 	isItemExpanded,
 	resolveAccordionItemAxes,
@@ -42,25 +43,26 @@ export function AccordionItem({ value, isDisabled, className, children, ...props
 	const progress = useSharedValue(isExpanded ? 1 : 0);
 	const contentHeight = useSharedValue(ACCORDION_UNMEASURED);
 
-	// Bumped the first time this item's panel reports a height, purely to make the
-	// effect below run again. See `onMeasured` on the item context for why the
-	// panel must not start the spring itself.
-	const [measurements, setMeasurements] = useState(0);
-	const onMeasured = useCallback(() => setMeasurements((count) => count + 1), []);
+	// Whether this item's panel has ever reported a height. React state, not a read
+	// of `contentHeight` on the JS thread: that write is queued onto the UI runtime
+	// and a read straight after it can still see `ACCORDION_UNMEASURED` — which a
+	// Release build does, every time. See `accordionTravelTarget`.
+	const [isMeasured, setMeasured] = useState(false);
+	const onMeasured = useCallback(() => setMeasured(true), []);
 
-	// `measurements` is not read in the body — being unread is the whole point of
-	// it, the way `settledDrags` is for a `Switch`. The first expand of a panel
-	// that has never been mounted has no height to travel against, so this run
-	// bails; the measurement that follows is what brings it back.
-	// biome-ignore lint/correctness/useExhaustiveDependencies: the extra dependency is the re-run trigger, see above
+	// The first expand of a panel that has never been mounted has no height to
+	// travel against, so this run waits; the measurement that follows flips
+	// `isMeasured` and brings it back. See `onMeasured` on the item context for why
+	// the panel must not start the spring itself.
 	useEffect(() => {
-		if (isExpanded && contentHeight.value === ACCORDION_UNMEASURED) return;
+		const target = accordionTravelTarget({ isExpanded, isMeasured });
+		if (target === null) return;
 
-		progress.value = withSpring(isExpanded ? 1 : 0, ACCORDION_SPRING);
+		progress.value = withSpring(target, ACCORDION_SPRING);
 
 		// Without this an item unmounted mid-travel leaves its spring running.
 		return () => cancelAnimation(progress);
-	}, [contentHeight, isExpanded, measurements, progress]);
+	}, [isExpanded, isMeasured, progress]);
 
 	const context = useMemo<AccordionItemContextValue>(
 		() => ({ contentHeight, isDisabled: axes.isDisabled, isExpanded, onMeasured, progress, value }),

package/src/components/accordion/accordion.context.tsx

@@ -35,8 +35,9 @@ export type AccordionItemContextValue = {
 	 * The panel's natural height in points, from its own `onLayout`.
 	 *
 	 * Holds {@link ACCORDION_UNMEASURED} until a panel has reported, which is not
-	 * the same as a panel that measured zero: the item's spring waits on the first
-	 * measurement rather than travelling against a height that is not there yet.
+	 * the same as a panel that measured zero. Read on the UI runtime only — by the
+	 * height style — and written from the panel's `onLayout`; nothing on the JS
+	 * thread reads it, because a JS read can lag a JS write. See {@link onMeasured}.
 	 */
 	contentHeight: SharedValue<number>;
 	/**
@@ -46,9 +47,14 @@ export type AccordionItemContextValue = {
 	 * spring. The panel cannot start the travel itself: `onLayout` is dispatched
 	 * from the native side and can land either side of React's effects, so a panel
 	 * that started its own spring would sometimes have it cancelled a moment later
-	 * by the cleanup of the effect it raced. This hands the item a reason to re-run
-	 * instead — `Slider`'s and `Switch`'s `settledDrags`, for the same reason: a
-	 * counter whose only job is to give an effect something to fire on.
+	 * by the cleanup of the effect it raced. This flips the item's own
+	 * `isMeasured` state instead, which is what re-runs the item's effect.
+	 *
+	 * That state, not a JS-thread read of {@link contentHeight}, is how the item
+	 * knows a panel has measured. The panel's write is queued onto the UI runtime
+	 * and a read straight after it can still see `ACCORDION_UNMEASURED` — a Release
+	 * build does, every time, and the panel stayed shut. See
+	 * `accordionTravelTarget`.
 	 */
 	onMeasured: () => void;
 };

package/src/components/accordion/accordion.variants.test.ts

@@ -16,6 +16,7 @@ import {
 	ACCORDION_SPRING,
 	ACCORDION_UNMEASURED,
 	ACCORDION_VARIANTS,
+	accordionTravelTarget,
 	accordionVariants,
 	isItemExpanded,
 	resolveAccordionItemAxes,
@@ -432,3 +433,64 @@ describe("accordion animation", () => {
 		expect(end).toBeLessThan(1);
 	});
 });
+
+describe("accordionTravelTarget", () => {
+	test("an expand waits for the panel's first measurement", () => {
+		expect(accordionTravelTarget({ isExpanded: true, isMeasured: false })).toBeNull();
+	});
+
+	test("an expand travels to 1 once the panel has measured", () => {
+		expect(accordionTravelTarget({ isExpanded: true, isMeasured: true })).toBe(1);
+	});
+
+	test("a collapse never waits, measured or not", () => {
+		expect(accordionTravelTarget({ isExpanded: false, isMeasured: false })).toBe(0);
+		expect(accordionTravelTarget({ isExpanded: false, isMeasured: true })).toBe(0);
+	});
+});
+
+/**
+ * A file's source with comments and every `useAnimatedStyle(...)` call stripped — the one
+ * place a read of a shared value runs on the UI runtime — leaving only code that runs on the
+ * JS thread.
+ */
+export function jsThreadSource(path: string): string {
+	const source = readFileSync(path, "utf8")
+		.replace(/\/\*[\s\S]*?\*\//g, "")
+		.replace(/\/\/.*$/gm, "");
+	let out = "";
+	let index = 0;
+	for (;;) {
+		const start = source.indexOf("useAnimatedStyle(", index);
+		if (start === -1) return out + source.slice(index);
+		out += source.slice(index, start);
+		let depth = 0;
+		let cursor = start + "useAnimatedStyle".length;
+		do {
+			if (source[cursor] === "(") depth++;
+			if (source[cursor] === ")") depth--;
+			cursor++;
+		} while (depth > 0 && cursor < source.length);
+		index = cursor;
+	}
+}
+
+/** `contentHeight.value` as a read: anything but the left side of a plain `=`. */
+export const CONTENT_HEIGHT_READ = /\bcontentHeight\.value\b(?!\s*=(?!=))/;
+
+describe("the measured height is never read on the JS thread", () => {
+	// A JS-thread write to a shared value is queued onto the UI runtime, while a JS-thread read
+	// runs there synchronously under its lock without draining that queue. A read straight after
+	// the write — the item's effect after the panel's `onLayout` — can see the old value. In a
+	// Release build it does, every time: the item read `ACCORDION_UNMEASURED`, bailed, and nothing
+	// re-ran it, so the panel said `expanded` and stayed shut.
+	test.each(["accordion-item.tsx", "accordion-content.tsx"])("%s", (file) => {
+		expect(jsThreadSource(join(import.meta.dirname, file))).not.toMatch(CONTENT_HEIGHT_READ);
+	});
+
+	test("the guard sees a read and ignores a write", () => {
+		expect("if (contentHeight.value === -1) return;").toMatch(CONTENT_HEIGHT_READ);
+		expect("const was = contentHeight.value > -1;").toMatch(CONTENT_HEIGHT_READ);
+		expect("contentHeight.value = event.nativeEvent.layout.height;").not.toMatch(CONTENT_HEIGHT_READ);
+	});
+});

package/src/components/accordion/accordion.variants.ts

@@ -76,17 +76,41 @@ export const ACCORDION_INDICATOR_ROTATION = { collapsed: 0, expanded: 180 } as c
  * What {@link AccordionItemContextValue.contentHeight} holds before a panel has
  * ever reported its own layout.
  *
- * Negative rather than zero, because the two mean different things and the
- * difference is load-bearing. A panel that measured `0` is a real answer — a
- * panel whose content rendered nothing — and an item that treated it as "still
- * waiting" would never start its spring, leaving the indicator stuck pointing the
- * wrong way for an empty panel. Only a value no layout can produce can mean
- * *unmeasured*.
+ * Negative rather than zero, because the two mean different things. A panel that
+ * measured `0` is a real answer — a panel whose content rendered nothing — and
+ * still opens, indicator and all. Only a value no layout can produce can mean
+ * *unmeasured*. Whether a panel *has* measured is never decided by comparing
+ * against this on the JS thread — see {@link accordionTravelTarget}.
  *
  * The height style therefore floors it: `progress * max(contentHeight, 0)`.
  */
 export const ACCORDION_UNMEASURED = -1;
 
+/**
+ * Where an item's `progress` should spring to, or `null` to wait.
+ *
+ * Only an expand waits, and only for a panel that has never measured: it has no
+ * height to travel against yet, and the measurement is what starts it. A collapse
+ * never waits.
+ *
+ * `isMeasured` is **React state**, never a read of `contentHeight` on the JS
+ * thread. A JS-thread write to a shared value is queued onto the UI runtime, while
+ * a JS-thread read runs there synchronously without draining that queue, so a read
+ * straight after the panel's `onLayout` wrote the height can still see
+ * {@link ACCORDION_UNMEASURED}. A Release build does, every time — the item bailed
+ * and nothing re-ran it, so the panel said `expanded` and stayed shut.
+ */
+export function accordionTravelTarget({
+	isExpanded,
+	isMeasured,
+}: {
+	isExpanded: boolean;
+	isMeasured: boolean;
+}): 0 | 1 | null {
+	if (!isExpanded) return 0;
+	return isMeasured ? 1 : null;
+}
+
 /**
  * The window of the travel the panel's opacity ramps across.
  *