@delacour/react-native-ui 0.1.0-alpha.4 → 0.1.0

package/README.md

@@ -11,7 +11,7 @@ arrive with its classNames already dead.
 ## Install
 
 ```bash
-bun add @delacour/react-native-ui@alpha
+bun add @delacour/react-native-ui
 ```
 
 Native modules are **peer dependencies**, because two copies of a native module
@@ -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` | Snap points, 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,7 +1,7 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.4",
-	"description": "React Native UI components \u2014 Uniwind, Reanimated, Gesture Handler",
+	"version": "0.1.0",
+	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -34,30 +34,65 @@
 		"./styles/tokens": "./src/styles/tokens.css",
 		"./styles/theme": "./src/styles/theme.css",
 		"./accordion": "./src/components/accordion/index.ts",
+		"./alert": "./src/components/alert/index.ts",
+		"./avatar": "./src/components/avatar/index.ts",
 		"./badge": "./src/components/badge/index.ts",
 		"./bottom-sheet": "./src/components/bottom-sheet/index.ts",
 		"./button": "./src/components/button/index.ts",
+		"./calendar": "./src/components/calendar/index.ts",
+		"./card": "./src/components/card/index.ts",
 		"./chart": "./src/components/chart/index.ts",
 		"./checkbox": "./src/components/checkbox/index.ts",
+		"./chip": "./src/components/chip/index.ts",
+		"./collapsible": "./src/components/collapsible/index.ts",
+		"./context-menu": "./src/components/context-menu/index.ts",
+		"./dialog": "./src/components/dialog/index.ts",
+		"./drawer": "./src/components/drawer/index.ts",
+		"./empty-state": "./src/components/empty-state/index.ts",
+		"./fab": "./src/components/fab/index.ts",
+		"./feedback": "./src/components/feedback/index.ts",
 		"./field": "./src/components/field/index.ts",
 		"./icon": "./src/components/icon/index.ts",
 		"./input": "./src/components/input/index.ts",
+		"./item": "./src/components/item/index.ts",
+		"./kpi": "./src/components/kpi/index.ts",
+		"./label": "./src/components/label/index.ts",
 		"./list-group": "./src/components/list-group/index.ts",
+		"./menu": "./src/components/menu/index.ts",
+		"./meter": "./src/components/meter/index.ts",
+		"./overlay": "./src/components/overlay/index.ts",
+		"./popover": "./src/components/popover/index.ts",
 		"./pressable": "./src/components/pressable/index.ts",
+		"./progress": "./src/components/progress/index.ts",
+		"./progress-button": "./src/components/progress-button/index.ts",
 		"./provider": "./src/components/provider/index.ts",
 		"./radio": "./src/components/radio/index.ts",
+		"./rating": "./src/components/rating/index.ts",
 		"./screen": "./src/components/screen/index.ts",
+		"./selection-mode": "./src/components/selection-mode/index.ts",
 		"./separator": "./src/components/separator/index.ts",
+		"./skeleton": "./src/components/skeleton/index.ts",
+		"./slide-button": "./src/components/slide-button/index.ts",
 		"./slider": "./src/components/slider/index.ts",
 		"./spinner": "./src/components/spinner/index.ts",
+		"./stack-card": "./src/components/stack-card/index.ts",
+		"./steps": "./src/components/steps/index.ts",
+		"./surface": "./src/components/surface/index.ts",
+		"./swipe": "./src/components/swipe/index.ts",
 		"./switch": "./src/components/switch/index.ts",
 		"./tabs": "./src/components/tabs/index.ts",
 		"./text": "./src/components/text/index.ts",
+		"./textarea": "./src/components/textarea/index.ts",
+		"./toast": "./src/components/toast/index.ts",
+		"./toggle-button": "./src/components/toggle-button/index.ts",
+		"./tooltip": "./src/components/tooltip/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",
@@ -81,8 +116,8 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-charts": ">=0.1.0-alpha.4",
-		"@gorhom/bottom-sheet": "^5.2.8",
+		"@delacour/react-native-bottom-sheet": ">=0.1.0",
+		"@delacour/react-native-charts": ">=0.1.0",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",
 		"expo-router": ">=57",
@@ -95,11 +130,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
 		},
@@ -111,15 +150,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
@@ -139,9 +150,10 @@ a list of rows.
   `onPress` is the one prop `Omit`ed rather than forwarded: the press *is* the
   toggle, and a side effect belongs on `onValueChange`. `Checkbox`'s trade.
 - **The disabled fade lands on the item, never on the trigger.** The trigger is a
-  `Pressable`, whose root `Animated.View` writes `opacity` every frame through a
-  `useAnimatedStyle` of its own — a class on that node is overwritten silently,
-  the failure `Switch` and `Radio` both record. A test sweeps for it.
+  `Pressable`, which now multiplies a className's opacity into its press rather
+  than overwriting it — but the item already fades, header and panel together,
+  and a fade on the trigger as well would compound to a quarter. A test sweeps
+  for it.
 - **The trigger assembles its own row.** Titles and descriptions stack in a
   column, anything else — a leading `Icon`, a `Badge` — stays where it was
   written as a row sibling, and the indicator is moved to the end and composed in

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,
@@ -344,9 +345,8 @@ describe("accordionVariants slots", () => {
 	});
 
 	test("the disabled fade lands on the item, never on the trigger", () => {
-		// The trigger is a `Pressable`, whose root Animated.View writes `opacity`
-		// every frame through a useAnimatedStyle of its own. A class on that node
-		// is overwritten silently — the failure `Switch` and `Radio` both record.
+		// The item fades header and panel together; a fade on the trigger as well
+		// would compound the two to a quarter.
 		for (const size of ACCORDION_SIZES) {
 			const slots = accordionVariants({ isDisabled: true, size, variant: ACCORDION_DEFAULT_VARIANT });
 			expect(cls(slots.item())).toMatch(/\bopacity-50\b/);
@@ -433,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.
  *
@@ -142,9 +166,9 @@ export const ACCORDION_CONTENT_FADE = { start: 0.1, end: 0.6 } as const;
  * because the travel has not started yet.
  *
  * **The disabled fade lands on `item`, never on `trigger`.** The trigger is a
- * `Pressable`, whose root `Animated.View` writes `opacity` every frame through a
- * `useAnimatedStyle` of its own — a class on that node is overwritten silently,
- * which is the failure `Switch` and `Radio` both record.
+ * `Pressable`, which now multiplies a className's opacity into its press rather
+ * than overwriting it — but the item already fades, header and panel together,
+ * and a fade on the trigger as well would compound to a quarter.
  *
  * No slot worn by a `View` carries `text-*`; a React Native `View` does not
  * cascade colour to a `Text` descendant, so the treatment lives on the `title` and

package/src/components/alert/AGENTS.md

@@ -0,0 +1,102 @@
+# Alert
+
+A status message on a `Surface`: a glyph picked from its status, a title, a
+description and, optionally, an action row and a dismiss control. Compound root
+plus `Alert.Indicator`, `Alert.Content`, `Alert.Title`, `Alert.Description`,
+`Alert.Action` and `Alert.CloseButton`.
+
+`import { Alert } from "@delacour/react-native-ui/alert";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/alert` |
+| `alert.tsx` | Root + the `Object.assign` compound surface |
+| `alert-indicator.tsx` | `Alert.Indicator` |
+| `alert-glyphs.ts` | **Leaf.** `ALERT_GLYPHS`, the status → glyph map — `toast/` imports it |
+| `alert-content.tsx` | `Alert.Content` |
+| `alert-title.tsx` | `Alert.Title` |
+| `alert-description.tsx` | `Alert.Description` |
+| `alert-action.tsx` | `Alert.Action` |
+| `alert-close-button.tsx` | `Alert.CloseButton`, the dismiss pressable |
+| `alert.context.tsx` | `AlertProvider`, `useAlert()`, `useAlertContext()`, `useAlertPart()` |
+| `alert.types.ts` | `AlertSlotProps`, shared by `Content` and `Action` |
+| `alert.variants.ts` | The slotted `tv()`, `ALERT_FOREGROUND_TOKEN`, `ALERT_SURFACE_PADDING` and three pure resolvers — no RN imports |
+| `alert.variants.test.ts` | |
+
+## Design
+
+- **Two axes: `status` and `variant`.** `status` says what the message means —
+  `default`, `info`, `success`, `warning`, `destructive` — and `variant` says
+  how loudly: `soft` (the default) washes the surface in the status's `-soft`
+  fill, `surface` keeps a neutral fill and lets the glyph and title carry the
+  colour. **Sizes**: `sm`, `md`, `lg`, which move padding, gap, type and glyph
+  together. `destructive` rather than `danger`, per the package's token rule.
+- **It is built on `Surface`, and it adds only what a surface lacks.** The
+  corner, the continuous curve, the padding (`ALERT_SURFACE_PADDING` maps each
+  size onto the surface's own step) and the neutral fill all come from
+  [Surface](../surface/AGENTS.md). `alertVariants`' root carries the row and the
+  tint, and a test asserts it sets no padding of its own — a second one would
+  fight the surface's through the merge.
+- **Only a tinted alert names a fill.** `resolveAlertTinted` is true for `soft`
+  plus a status, and those four cells swap `bg-card` for `bg-X-soft` and clear
+  the card's hairline: a grey rule around a red wash reads as two components
+  stacked. Every other alert leaves the surface's `variant` undefined
+  (`resolveAlertSurfaceVariant`), so it steps from the plane it sits on — an
+  alert inside a card lands on `secondary` rather than vanishing into the card.
+  A tinted alert pins the surface to `default` instead, so what nests in it
+  steps from a card like anything else.
+- **One colour token per status, not per status and variant.**
+  `ALERT_FOREGROUND_TOKEN` names `X-soft-foreground` for each status and the
+  page's `foreground` for `default`; those are tuned to read on the soft fill
+  and on the neutral fills alike. The title slot emits the same token as a
+  class and the root publishes it through `IconDefaultsProvider`, so the glyph
+  and the title are always one shade. A test pins the pair and asserts every
+  token exists in both themes. The classes are written out literally —
+  Tailwind's scanner is static, so a class assembled from the map at runtime
+  would never be compiled.
+- **The description is always muted.** A long explanation under a red title
+  must not shout; the title carries the status.
+- **`items-start`, and the indicator is as tall as the title's line.** A
+  description that wraps to four lines must not drag the glyph to its middle.
+  The indicator's height is the title's line height at each size (`h-5`/`h-6`/
+  `h-7` against `text-sm`/`base`/`lg`), and it centres the glyph in that box, so
+  the glyph sits level with the first line. Nothing else is a fixed height:
+  `Text` respects OS font scaling, and a fixed box would clip a wrapped title.
+- **Glyphs differ in shape, not just colour.** `warning` is a triangle and
+  `destructive` a circle, so the two stay apart for anyone who cannot tell amber
+  from red. `default` shares `info`'s circle. The map lives in
+  `alert-glyphs.ts`, a leaf `Toast` shares, because the glyphs are RN SVG components and
+  `alert.variants.ts` must stay importable from `bun test`.
+- **The indicator is hidden from assistive technology.** The title says what
+  happened; "image" announced before it adds nothing. Children replace the
+  glyph and inherit the alert's icon size and colour — a `Spinner` for a
+  pending state needs nothing else.
+- **Announced as an `alert`, and as a live region on Android.**
+  `resolveAlertLiveRegion` makes a `warning` or `destructive` alert assertive
+  and anything else polite. The root is not made `accessible`: grouping it
+  would swallow the close control and any action into one element.
+- **Dismissal is controllable.** `isDismissible` composes an
+  `Alert.CloseButton` in at the end. Uncontrolled, the alert hides itself when
+  dismissed (`defaultOpen`); pass `isOpen` with `onOpenChange` to own it.
+  `useAlert().dismiss` is on the context so an action ("Got it") can close the
+  alert without the caller threading a setter down. A dismissed alert fades out
+  over 150 ms rather than vanishing — the one `Animated.View` wrapper exists for
+  that `exiting`, and a caller's `className` still reaches the surface.
+- **The close glyph is muted, not the status colour.** The control is about the
+  alert rather than part of what it says, and a red cross beside a red title
+  reads as a second warning. It presses with `fade` — a spring on a glyph that
+  small is a jitter — and carries `hitSlop={10}` to reach the 44-point target.
+- **`closeTestID` reaches the composed close control.** The root's own `testID`
+  names the alert's surface; the close part is a separate pressable with no id of its own
+  unless the root forwards one, so a flow or test could only find it by its label.
+  `closeTestID` is named like `closeAccessibilityLabel`, the other prop the root
+  passes through to it.
+- **Actions are the caller's.** `Alert.Action` is a wrapping row and styles
+  nothing in it; a `Button` in there is sized and painted however the caller
+  says. It wraps rather than overflowing, because two buttons and a long label
+  outgrow a phone's width.
+- **Parts are composed, not configured.** There is no `title` or `icon` prop:
+  omit `Alert.Indicator` for a text-only alert, omit `Alert.Description` for a
+  one-liner. The same reason `Button` and `Badge` compose their icons.

package/src/components/alert/alert-action.tsx

@@ -0,0 +1,17 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { AlertSlotProps } from "./alert.types";
+import { alertVariants } from "./alert.variants";
+
+/**
+ * A wrapping row for the alert's buttons, placed under the description inside
+ * `Alert.Content`.
+ *
+ * Takes any children — a `Button`, a `Text.Link` — and styles none of them: an
+ * action is the caller's control, sized and painted the way they want it. Read
+ * `useAlert().dismiss` from inside to close the alert from an action.
+ */
+export function AlertAction({ className, ...props }: AlertSlotProps): ReactElement {
+	return <View className={alertVariants().action({ className })} {...props} />;
+}
+AlertAction.displayName = "DelacourUI.Alert.Action";