@delacour/react-native-ui 0.4.0-alpha.20261020154654 → 0.4.0-alpha.20261020155114

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.4.0-alpha.20261020154654",
+	"version": "0.4.0-alpha.20261020155114",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -181,7 +181,7 @@
 		"expo-blur": ">=15",
 		"@maplibre/maplibre-react-native": "^11.5.0",
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-bottom-sheet": "0.2.0-alpha.20261020154654",
+		"@delacour/react-native-bottom-sheet": "0.2.0-alpha.20261020155114",
 		"@delacour/react-native-charts": ">=0.1.0",
 		"@legendapp/list": ">=3.3",
 		"@shopify/react-native-skia": ">=2",

package/src/components/item/AGENTS.md

@@ -24,7 +24,7 @@ A row of media, text and actions, for lists and settings. Compound root plus
 | `item-separator.tsx` | `Item.Separator` |
 | `item.context.tsx` | `ItemProvider`, `useItem()`, `useItemContext()`, `useItemPart()` |
 | `item.types.ts` | Prop types shared by two or more parts |
-| `item.variants.ts` | Pure `tv()` slots and the four resolvers, no RN imports |
+| `item.variants.ts` | Pure `tv()` slots, the four resolvers and `wrapItemTextChildren`, no RN imports |
 | `item.variants.test.ts` | |
 
 ## Design
@@ -87,6 +87,10 @@ A row of media, text and actions, for lists and settings. Compound root plus
   hand-placed rule in a group.
 - **String children** are wrapped in a `Content` around a `Title`, consecutive
   strings collapsing into one — the same rule, and the same reason, as
-  [`ListGroup`](../list-group/AGENTS.md).
+  [`ListGroup`](../list-group/AGENTS.md). `wrapItemTextChildren` does it and
+  hands one node back as that node, never a one-item array: `Pressable` with
+  `asChild` passes its children to `Children.only`, which rejects any array,
+  so `<Item asChild onPress={…}><View /></Item>` threw until it did. The
+  tests hold that case.
 - **Text colour goes on the text.** No slot but `title` and `description` holds
   a `text-*` colour; the tests assert the root never does.

package/src/components/item/item.tsx

@@ -1,4 +1,4 @@
-import { Children, type ReactElement, type ReactNode, useMemo } from "react";
+import { type ReactElement, type ReactNode, useMemo } from "react";
 import type { AccessibilityState } from "react-native";
 import Animated from "react-native-reanimated";
 import { useListGroupContext } from "../list-group/list-group.context";
@@ -13,6 +13,7 @@ import {
 	resolveItemRender,
 	resolveItemSize,
 	resolveItemSurface,
+	wrapItemTextChildren,
 } from "./item.variants";
 import { ItemActions } from "./item-actions";
 import { ItemContent } from "./item-content";
@@ -115,40 +116,20 @@ function ItemRoot({
 /**
  * Wraps bare text children in a title inside a content column.
  *
- * Consecutive strings and numbers are collected into a single title rather
- * than one each — `Row {index}` is one piece of text. React Native cannot
- * render a string outside a `<Text>`, so without this `<Item>Wi-Fi</Item>`
- * would crash.
+ * React Native cannot render a string outside a `<Text>`, so without this
+ * `<Item>Wi-Fi</Item>` would crash. The run-collapsing and the single-child
+ * rule `asChild` depends on live in `wrapItemTextChildren`, where they are
+ * tested.
  *
  * Lives with the root because the root is what wraps its own text; a part
  * importing it from here would close a cycle. See AGENTS.md rule 3.
  */
 function wrapTextChildren(children: ReactNode): ReactNode {
-	const items = Children.toArray(children);
-	const output: ReactNode[] = [];
-	let run: (string | number)[] = [];
-
-	const flushRun = () => {
-		if (run.length === 0) return;
-		output.push(
-			<ItemContent key={`content-${output.length}`}>
-				<ItemTitle>{run.join("")}</ItemTitle>
-			</ItemContent>
-		);
-		run = [];
-	};
-
-	for (const child of items) {
-		if (typeof child === "string" || typeof child === "number") {
-			run.push(child);
-			continue;
-		}
-		flushRun();
-		output.push(child);
-	}
-	flushRun();
-
-	return output;
+	return wrapItemTextChildren(children, (text, key) => (
+		<ItemContent key={key}>
+			<ItemTitle>{text}</ItemTitle>
+		</ItemContent>
+	));
 }
 
 /**

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

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { Children, createElement, isValidElement, type ReactElement } from "react";
 import { ICON_SIZE_TOKENS } from "../../styles/tokens";
 import { LIST_GROUP_SIZES, listGroupVariants } from "../list-group/list-group.variants";
 import {
@@ -11,6 +12,7 @@ import {
 	resolveItemRender,
 	resolveItemSize,
 	resolveItemSurface,
+	wrapItemTextChildren,
 } from "./item.variants";
 
 /** Pulls the horizontal padding step out of a class string — `px-4` yields 4. */
@@ -261,3 +263,41 @@ describe("itemVariants orientation", () => {
 		expect(itemVariants({ groupOrientation: "horizontal" }).group()).toContain("flex-row");
 	});
 });
+
+describe("wrapItemTextChildren", () => {
+	const wrap = (text: string, key: string): ReactElement => createElement("title", { key }, text);
+
+	test("hands a single element back as that element, never a one-item array", () => {
+		const child = createElement("view");
+		const result = wrapItemTextChildren(child, wrap);
+		expect(Array.isArray(result)).toBe(false);
+		expect(isValidElement(result)).toBe(true);
+	});
+
+	test("survives Children.only — the check Pressable asChild makes", () => {
+		const result = wrapItemTextChildren(createElement("view"), wrap);
+		expect(() => Children.only(result)).not.toThrow();
+	});
+
+	test("hands a lone wrapped string back as one element", () => {
+		const result = wrapItemTextChildren("Wi-Fi", wrap);
+		expect(Array.isArray(result)).toBe(false);
+		expect(isValidElement(result) && result.type).toBe("title");
+	});
+
+	test("collapses consecutive strings and numbers into one run", () => {
+		const result = wrapItemTextChildren(["Row ", 3], wrap);
+		expect(isValidElement(result)).toBe(true);
+		expect(isValidElement(result) && (result.props as { children: string }).children).toBe("Row 3");
+	});
+
+	test("keeps an array when there is more than one node", () => {
+		const result = wrapItemTextChildren(["Wi-Fi", createElement("view", { key: "switch" }), "On"], wrap);
+		expect(Array.isArray(result)).toBe(true);
+		expect(Children.count(result)).toBe(3);
+	});
+
+	test("returns nothing for no children", () => {
+		expect(Children.count(wrapItemTextChildren(undefined, wrap))).toBe(0);
+	});
+});

package/src/components/item/item.variants.ts

@@ -1,3 +1,4 @@
+import { Children, type ReactElement, type ReactNode } from "react";
 import type { VariantProps } from "tailwind-variants";
 import { tv } from "../../lib/tv";
 import type { PressableFeedback } from "../pressable/pressable.variants";
@@ -84,6 +85,44 @@ export function resolveItemRender(options: {
 	return hasHandler ? "pressable" : "static";
 }
 
+/**
+ * Wraps each run of bare text children through `wrap`, leaving every other
+ * child as it is.
+ *
+ * Consecutive strings and numbers are collected into a single run rather than
+ * one each — `Row {index}` is one piece of text.
+ *
+ * One node comes back as that node, never as a one-item array: `Pressable`
+ * with `asChild` hands its children to `Children.only`, which rejects an
+ * array whatever its length, so `<Item asChild onPress={…}><View /></Item>`
+ * threw before this.
+ */
+export function wrapItemTextChildren(
+	children: ReactNode,
+	wrap: (text: string, key: string) => ReactElement
+): ReactNode {
+	const output: ReactNode[] = [];
+	let run: (string | number)[] = [];
+
+	const flushRun = () => {
+		if (run.length === 0) return;
+		output.push(wrap(run.join(""), `content-${output.length}`));
+		run = [];
+	};
+
+	for (const child of Children.toArray(children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			run.push(child);
+			continue;
+		}
+		flushRun();
+		output.push(child);
+	}
+	flushRun();
+
+	return output.length === 1 ? output[0] : output;
+}
+
 /**
  * Styling for every part of an item.
  *

package/src/components/list-group/AGENTS.md

@@ -75,6 +75,8 @@ five slots: `ItemPrefix`, `ItemContent`, `ItemTitle`, `ItemDescription`,
   tunes that glyph and is ignored once it does.
 - **String children** are wrapped in an `ItemContent` around an `ItemTitle`
   automatically, consecutive strings collapsing into one — the same rule, and
-  the same reason, as [`Button`](../button/AGENTS.md).
+  the same reason, as [`Button`](../button/AGENTS.md). A single node comes
+  back unwrapped, not as a one-item array, so `asChild` (which calls
+  `Children.only`) takes it.
 - **Title colour goes on the title.** The `item` slot carries no `text-*`; a row
   is a `View` and cannot cascade colour to a `Text`. The tests assert this.

package/src/components/list-group/list-group-item.tsx

@@ -92,6 +92,9 @@ ListGroupItem.displayName = "DelacourUI.ListGroup.Item";
  * Lives here rather than with the root: it is the row that wraps its own text,
  * and importing it from `./list-group` would close a cycle back through the
  * root. See AGENTS.md rule 3.
+ *
+ * One node comes back as that node, never a one-item array: `Pressable` with
+ * `asChild` hands its children to `Children.only`, which rejects any array.
  */
 function wrapTextChildren(children: ReactNode): ReactNode {
 	const items = Children.toArray(children);
@@ -118,5 +121,5 @@ function wrapTextChildren(children: ReactNode): ReactNode {
 	}
 	flushRun();
 
-	return output;
+	return output.length === 1 ? output[0] : output;
 }

package/src/components/pressable/AGENTS.md

@@ -13,7 +13,7 @@ and only `onPress` and `onLongPress` cross back to JS.
 | `index.ts` | → `@delacour/react-native-ui/pressable` |
 | `pressable.tsx` | The Gesture API primitive |
 | `pressable.variants.ts` | Shared feedback vocabulary, no RN imports |
-| `pressable.variants.test.ts` | |
+| `pressable.variants.test.ts` | Feedback, rest opacity, accessibility state and activation matrices |
 
 ## Design
 
@@ -52,6 +52,30 @@ and only `onPress` and `onLongPress` cross back to JS.
   [`Marker`](../marker/AGENTS.md), a running step that must stay tappable,
   is the case that found it. Neither applies any opacity — that is the
   caller's variant's job, and the point below is what lets it do that job.
+- **A screen reader's activation is wired to `onPress`, not left to the
+  gesture.** A Gesture Handler tap only ever sees touches. VoiceOver's
+  double-tap calls `accessibilityActivate`, which React Native answers only
+  when `onAccessibilityTap` is set; without it UIKit synthesises a touch at the
+  element's centre and the gesture happens to catch it. TalkBack's double-tap
+  performs `ACTION_CLICK`, which React Native routes only to a listed
+  `activate` action and otherwise drops into `View.performClick`, with no
+  listener behind it. `resolvePressableActivation` decides per platform:
+  `onAccessibilityTap` on iOS (an `activate` entry there would become a literal
+  "activate" in every button's rotor, since Fabric lists every entry as a custom
+  action), an appended `activate` action on Android. Both go through
+  `isPressableInteractive`, the same guard the gesture uses, so a disabled or
+  busy control consumes the activation and does nothing. Returning `YES` from
+  `accessibilityActivate` also stops UIKit synthesising the touch, so one
+  double-tap is one `onPress`. A caller that lists `activate` itself — the
+  `NumberInput` stepper, `Message`, `FlipCard`, `SectionRail.Trigger`,
+  `ProgressButton` — owns it on both platforms and the pressable wires nothing;
+  a caller's own `onAccessibilityTap` wins the same way. A caller's other
+  actions and its `onAccessibilityAction` are merged in, never replaced.
+  `Button`, `ListGroup.Item`, `Screen.Navbar.BackButton`, `Dialog.Close`,
+  `BottomSheet.Close` and every other `Pressable` consumer inherit it.
+  Verified on an iOS simulator with `AXPress` through Simulator.app's
+  accessibility bridge, which calls `accessibilityActivate` — `warden ui press`
+  does not, it synthesises a touch, so it cannot tell the two paths apart.
 - **A className's opacity is multiplied into the press, never overwritten.**
   The press feedback is an animated style, and an animated style owns every key
   it writes on the view — so its resting `opacity: 1` silently replaced a

package/src/components/pressable/pressable.tsx

@@ -9,7 +9,7 @@ import {
 	type Ref,
 	useMemo,
 } from "react";
-import type { AccessibilityState, ViewProps } from "react-native";
+import { type AccessibilityActionEvent, type AccessibilityState, Platform, type ViewProps } from "react-native";
 import { Gesture, GestureDetector } from "react-native-gesture-handler";
 import { Presets } from "react-native-pulsar";
 import Animated, { useAnimatedStyle, useSharedValue, withSpring } from "react-native-reanimated";
@@ -18,8 +18,10 @@ import { useResolveClassNames } from "uniwind";
 import { composeRefs } from "../../lib/compose-refs";
 import { mergeProps } from "../../lib/merge-props";
 import {
+	isPressableInteractive,
 	type PressableFeedback,
 	resolvePressableAccessibilityState,
+	resolvePressableActivation,
 	resolvePressedState,
 	resolveRestOpacity,
 } from "./pressable.variants";
@@ -137,6 +139,11 @@ export type PressableProps = Omit<ViewProps, "style"> & {
  * Built on the Gesture API rather than a ready-made pressable so the animation,
  * the haptic and the gesture stay on one thread, and so nothing depends on
  * Gesture Handler's own `Pressable`, which was renamed in its v3.
+ *
+ * A gesture only ever sees touches, so a screen reader's activation is wired
+ * to `onPress` separately — `onAccessibilityTap` on iOS, an `activate` action on
+ * Android — behind the same `disabled` / `busy` guard. See
+ * `resolvePressableActivation`.
  */
 export function Pressable({
 	children,
@@ -151,11 +158,14 @@ export function Pressable({
 	pressedOpacity,
 	asChild = false,
 	accessibilityState,
+	accessibilityActions,
+	onAccessibilityAction,
+	onAccessibilityTap,
 	ref,
 	...props
 }: PressableProps): ReactElement {
 	const pressed = useSharedValue(0);
-	const interactive = !disabled && !busy;
+	const interactive = isPressableInteractive({ busy, disabled });
 	// Destructured to primitives on purpose. Reanimated's plugin collects what
 	// the worklet closes over, and a fresh object each render would rebuild the
 	// animated style every render.
@@ -207,6 +217,31 @@ export function Pressable({
 	// the prop's default — see `resolvePressableAccessibilityState`.
 	const state: AccessibilityState = resolvePressableAccessibilityState({ accessibilityState, busy, disabled });
 
+	const activation = resolvePressableActivation({
+		accessibilityActions,
+		hasAccessibilityTap: onAccessibilityTap !== undefined,
+		hasPress: onPress !== undefined,
+		platform: Platform.OS,
+	});
+	const activate = () => {
+		if (interactive) onPress?.();
+	};
+	// Built once and spread last at both render sites, after `{...props}`, so a
+	// caller's actions and handlers are merged in here rather than replacing the
+	// activation the pressable adds. `activate` is consumed only when the
+	// pressable added it; every other action reaches the caller's handler.
+	const accessibilityWiring = {
+		accessibilityActions: activation.accessibilityActions,
+		onAccessibilityAction: (event: AccessibilityActionEvent) => {
+			if (activation.routesActivate && event.nativeEvent.actionName === "activate") {
+				activate();
+				return;
+			}
+			onAccessibilityAction?.(event);
+		},
+		onAccessibilityTap: activation.wiresAccessibilityTap ? activate : onAccessibilityTap,
+	};
+
 	const content = asChild ? (
 		renderAsChild(children, {
 			accessibilityState: state,
@@ -215,6 +250,7 @@ export function Pressable({
 			ref,
 			style: animatedStyle,
 			...props,
+			...accessibilityWiring,
 		})
 	) : (
 		<Animated.View
@@ -229,6 +265,7 @@ export function Pressable({
 			ref={ref}
 			style={animatedStyle}
 			{...props}
+			{...accessibilityWiring}
 		>
 			{children}
 		</Animated.View>

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

@@ -1,9 +1,11 @@
 import { describe, expect, test } from "bun:test";
 import {
+	isPressableInteractive,
 	PRESSABLE_FEEDBACK,
 	PRESSABLE_FEEDBACK_FALLBACK,
 	PRESSABLE_FEEDBACKS,
 	resolvePressableAccessibilityState,
+	resolvePressableActivation,
 	resolvePressedState,
 	resolveRestOpacity,
 } from "./pressable.variants";
@@ -170,3 +172,93 @@ describe("resolvePressableAccessibilityState", () => {
 		expect(state.expanded).toBe(true);
 	});
 });
+
+describe("isPressableInteractive", () => {
+	test("only a control that is neither disabled nor busy takes a press", () => {
+		expect(isPressableInteractive({ busy: false, disabled: false })).toBe(true);
+		expect(isPressableInteractive({ busy: true, disabled: false })).toBe(false);
+		expect(isPressableInteractive({ busy: false, disabled: true })).toBe(false);
+		expect(isPressableInteractive({ busy: true, disabled: true })).toBe(false);
+	});
+});
+
+describe("resolvePressableActivation", () => {
+	test("iOS wires onAccessibilityTap and adds no custom action", () => {
+		expect(resolvePressableActivation({ hasAccessibilityTap: false, hasPress: true, platform: "ios" })).toEqual({
+			accessibilityActions: undefined,
+			routesActivate: false,
+			wiresAccessibilityTap: true,
+		});
+	});
+
+	test("iOS leaves a caller's own actions untouched, so the rotor gains no 'activate' entry", () => {
+		const actions = [{ label: "Remove", name: "remove" }];
+		const resolved = resolvePressableActivation({
+			accessibilityActions: actions,
+			hasAccessibilityTap: false,
+			hasPress: true,
+			platform: "ios",
+		});
+		expect(resolved.accessibilityActions).toBe(actions);
+		expect(resolved.wiresAccessibilityTap).toBe(true);
+	});
+
+	test("Android appends 'activate' after a caller's actions and routes it", () => {
+		const resolved = resolvePressableActivation({
+			accessibilityActions: [{ label: "Remove", name: "remove" }],
+			hasAccessibilityTap: false,
+			hasPress: true,
+			platform: "android",
+		});
+		expect(resolved).toEqual({
+			accessibilityActions: [{ label: "Remove", name: "remove" }, { name: "activate" }],
+			routesActivate: true,
+			wiresAccessibilityTap: false,
+		});
+	});
+
+	test("Android with no caller actions gets exactly one 'activate'", () => {
+		expect(
+			resolvePressableActivation({ hasAccessibilityTap: false, hasPress: true, platform: "android" })
+				.accessibilityActions
+		).toEqual([{ name: "activate" }]);
+	});
+
+	test("a caller that lists 'activate' owns it on both platforms, so it never fires twice", () => {
+		const actions = [{ name: "activate" }, { name: "increment" }];
+		for (const platform of ["ios", "android"] as const) {
+			expect(
+				resolvePressableActivation({
+					accessibilityActions: actions,
+					hasAccessibilityTap: false,
+					hasPress: true,
+					platform,
+				})
+			).toEqual({ accessibilityActions: actions, routesActivate: false, wiresAccessibilityTap: false });
+		}
+	});
+
+	test("a caller's own onAccessibilityTap wins on iOS", () => {
+		expect(
+			resolvePressableActivation({ hasAccessibilityTap: true, hasPress: true, platform: "ios" }).wiresAccessibilityTap
+		).toBe(false);
+	});
+
+	test("nothing is wired without an onPress to reach", () => {
+		for (const platform of ["ios", "android"] as const) {
+			expect(resolvePressableActivation({ hasAccessibilityTap: false, hasPress: false, platform })).toEqual({
+				accessibilityActions: undefined,
+				routesActivate: false,
+				wiresAccessibilityTap: false,
+			});
+		}
+	});
+
+	test("any other platform is left alone", () => {
+		expect(resolvePressableActivation({ hasAccessibilityTap: false, hasPress: true, platform: "web" })).toEqual({
+			accessibilityActions: undefined,
+			routesActivate: false,
+			wiresAccessibilityTap: false,
+		});
+	});
+});

package/src/components/pressable/pressable.variants.ts

@@ -111,3 +111,82 @@ export function resolvePressableAccessibilityState<S extends GatedAccessibilityS
 		disabled: disabled || accessibilityState?.disabled === true,
 	};
 }
+
+/**
+ * Whether a pressable takes a press at all — the one guard the tap gesture, the
+ * long press and screen-reader activation all go through, so a gated control
+ * cannot be reached by one of them and not the others.
+ */
+export function isPressableInteractive({ busy, disabled }: { busy: boolean; disabled: boolean }): boolean {
+	return !disabled && !busy;
+}
+
+/** The shape of an entry in React Native's `accessibilityActions`. Structural, so no RN import. */
+type PressableAccessibilityAction = { name: string; label?: string };
+
+export type PressableActivation<A extends PressableAccessibilityAction> = {
+	/** What the view's `accessibilityActions` becomes — the caller's own, plus `activate` on Android. */
+	accessibilityActions: ReadonlyArray<A | { name: "activate" }> | undefined;
+	/** The pressable consumes `activate` in `onAccessibilityAction` and calls `onPress` itself. */
+	routesActivate: boolean;
+	/** The pressable sets `onAccessibilityTap`, which is what VoiceOver's double-tap reaches. */
+	wiresAccessibilityTap: boolean;
+};
+
+/**
+ * How a screen reader's activation reaches `onPress`.
+ *
+ * The press is a Gesture Handler tap, which only ever sees touches. Each
+ * platform's activation is something else:
+ *
+ * - **iOS.** A VoiceOver double-tap calls `accessibilityActivate`, which React
+ *   Native answers only when `onAccessibilityTap` is set. Without it UIKit falls
+ *   back to synthesising a touch at the element's centre, which the gesture
+ *   happens to recognise — so it worked, but by accident. Setting it makes the
+ *   call return `YES`, which also stops UIKit synthesising the touch: one
+ *   activation, one `onPress`. An `activate` entry in `accessibilityActions` is
+ *   no use here: Fabric lists every entry as a rotor custom action, so it would
+ *   add a literal "activate" to every button's rotor.
+ * - **Android.** A TalkBack double-tap performs `ACTION_CLICK`, which React
+ *   Native routes to `onAccessibilityAction` only when `activate` is listed.
+ *   Without it the click falls to `View.performClick`, with no listener behind
+ *   it. React Native ignores `onAccessibilityTap` on Android.
+ *
+ * A caller that lists `activate` itself owns it on both platforms — a
+ * `NumberInput` stepper, a `Message`, a `FlipCard` — and the pressable wires
+ * nothing, so the press cannot fire twice. A caller's own `onAccessibilityTap`
+ * wins the same way. With no `onPress` there is nothing to reach.
+ *
+ * The `disabled` / `busy` guard is not decided here: activation stays wired on
+ * a gated control and the handler checks `isPressableInteractive`, so a gated
+ * control's double-tap is consumed and does nothing rather than falling back
+ * to a synthesised touch.
+ */
+export function resolvePressableActivation<A extends PressableAccessibilityAction>({
+	accessibilityActions,
+	hasAccessibilityTap,
+	hasPress,
+	platform,
+}: {
+	accessibilityActions?: ReadonlyArray<A>;
+	hasAccessibilityTap: boolean;
+	hasPress: boolean;
+	platform: string;
+}): PressableActivation<A> {
+	const ownedByCaller = accessibilityActions?.some((action) => action.name === "activate") === true;
+	const wires = hasPress && !ownedByCaller;
+
+	if (wires && platform === "android") {
+		return {
+			accessibilityActions: [...(accessibilityActions ?? []), { name: "activate" }],
+			routesActivate: true,
+			wiresAccessibilityTap: false,
+		};
+	}
+
+	return {
+		accessibilityActions,
+		routesActivate: false,
+		wiresAccessibilityTap: wires && platform === "ios" && !hasAccessibilityTap,
+	};
+}

package/src/components/screen/AGENTS.md

@@ -34,6 +34,8 @@ whole-screen states.
 | `screen-loading.tsx` | `Screen.Loading` |
 | `screen-error.tsx` | `Screen.Error` |
 | `screen-list-component.tsx` | A list header/footer prop, as a node — internal |
+| `screen-scroll-handler.ts` | `classifyScrollHandler` — sorts a caller's `onScroll` into JS or worklet, no RN imports |
+| `screen-scroll-handler.test.ts` | |
 | `screen-debug.ts` | `SCREEN_DEBUG_COLORS` |
 | `screen.context.tsx` | `ScreenProvider`, `useScreen()`, `useScreenContext()`, `useScreenPart()`, `useScreenDebug()` |
 | `screen.types.ts` | Prop types shared by two or more parts |
@@ -122,6 +124,20 @@ whole-screen states.
 
 ## Lists
 
+- **A caller's `onScroll` is composed with the screen's tracking, never
+  swapped for it.** Every scrollable but `ChatList` takes one, and hands it to
+  `useScreenScrollInsets` rather than spreading it. Spread before the screen's
+  handler it never ran; spread after, it replaced the handler and froze
+  `scrollY`, `contentHeight` and `layoutHeight` — so `ScrollShadow`, the
+  navbar's scroll border and every `ScrollSource` effect stopped moving the
+  moment a consumer listened to the scroll. A `useAnimatedScrollHandler` result
+  runs beside the tracking on the UI thread through `useComposedEventHandler`; a
+  plain function is called back on the JS thread with `{ nativeEvent }` only,
+  because a worklet holds the native payload, not React Native's synthetic
+  wrapper. Prefer the worklet form for anything frame-bound.
+- **`Screen.ChatList` takes no `onScroll`.** Its engines own the scroll for
+  anchoring and the keyboard lift, so the prop is omitted from its types rather
+  than half-supported.
 - **`Screen.ChatList` is a discriminated union on `variant`.** `legend`
   (default) takes chronological oldest-first data and LegendList's own
   `renderItem`; `flat` is an inverted `FlatList` with newest-first data and RN's.

package/src/components/screen/screen-flat-list.tsx

@@ -46,11 +46,15 @@ export const ScreenFlatList = forwardRef(function ScreenFlatListRender<ItemT>(
 		contentContainerClassName,
 		ListHeaderComponent: ListHeaderComponentProp,
 		ListFooterComponent: ListFooterComponentProp,
+		onScroll,
 		...props
 	}: ScreenFlatListProps<ItemT>,
 	ref: ForwardedRef<FlatList<ItemT>>
 ): ReactElement {
-	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets("standard");
+	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets(
+		"standard",
+		onScroll
+	);
 
 	const ListHeaderComponent = useMemo<ReactElement>(
 		() => (

package/src/components/screen/screen-legend-list.tsx

@@ -63,11 +63,15 @@ export const ScreenLegendList = forwardRef(function ScreenLegendListRender<ItemT
 		contentContainerClassName,
 		ListHeaderComponent: ListHeaderComponentProp,
 		ListFooterComponent: ListFooterComponentProp,
+		onScroll,
 		...props
 	}: ScreenLegendListProps<ItemT>,
 	ref: ForwardedRef<LegendListRef>
 ): ReactElement {
-	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets("standard");
+	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets(
+		"standard",
+		onScroll
+	);
 
 	const ListHeaderComponent = useMemo<ReactElement>(
 		() => (

package/src/components/screen/screen-scroll-area.tsx

@@ -48,11 +48,12 @@ export type ScreenScrollAreaProps = ScrollViewProps &
  * </Screen.ScrollArea>
  */
 export const ScreenScrollArea = forwardRef<ScreenScrollViewRef, ScreenScrollAreaProps>(function ScreenScrollAreaRender(
-	{ header, className, contentContainerClassName, keyboardAware = false, children, ...props },
+	{ header, className, contentContainerClassName, keyboardAware = false, onScroll, children, ...props },
 	ref
 ): ReactElement {
 	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets(
-		keyboardAware ? "keyboard-aware" : "standard"
+		keyboardAware ? "keyboard-aware" : "standard",
+		onScroll
 	);
 	// A sticky footer rides the keyboard, so the focused field has to clear the
 	// footer too — not just the keyboard. Deliberately not the chat list's
@@ -85,11 +86,11 @@ export const ScreenScrollArea = forwardRef<ScreenScrollViewRef, ScreenScrollArea
 			<StyledKeyboardAwareScrollView
 				className={className}
 				keyboardShouldPersistTaps="handled"
-				onScroll={scrollHandler}
 				showsHorizontalScrollIndicator={false}
 				showsVerticalScrollIndicator={false}
 				bottomOffset={footerClearance}
 				{...props}
+				onScroll={scrollHandler}
 				ref={ref as Ref<KeyboardAwareScrollViewRef>}
 				contentContainerClassName={contentContainer}
 			>
@@ -102,10 +103,10 @@ export const ScreenScrollArea = forwardRef<ScreenScrollViewRef, ScreenScrollArea
 		<Animated.ScrollView
 			className={className}
 			keyboardShouldPersistTaps="handled"
-			onScroll={scrollHandler}
 			showsHorizontalScrollIndicator={false}
 			showsVerticalScrollIndicator={false}
 			{...props}
+			onScroll={scrollHandler}
 			ref={ref}
 			contentContainerClassName={contentContainer}
 		>

package/src/components/screen/screen-scroll-handler.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { classifyScrollHandler } from "./screen-scroll-handler";
+
+describe("classifyScrollHandler", () => {
+	test("nothing supplied is none", () => {
+		expect(classifyScrollHandler(undefined)).toEqual({ kind: "none" });
+		expect(classifyScrollHandler(null)).toEqual({ kind: "none" });
+	});
+
+	test("a plain function is a JS callback", () => {
+		const onScroll = (): void => {};
+		expect(classifyScrollHandler(onScroll)).toEqual({ kind: "js", handler: onScroll });
+	});
+
+	test("a useAnimatedScrollHandler result is a worklet handler", () => {
+		const processed = { workletEventHandler: { eventNames: ["onScroll"] } };
+		expect(classifyScrollHandler(processed)).toEqual({ kind: "worklet", handler: processed });
+	});
+
+	test("an object without a worklet handler is none", () => {
+		expect(classifyScrollHandler({})).toEqual({ kind: "none" });
+	});
+});

package/src/components/screen/screen-scroll-handler.ts

@@ -0,0 +1,33 @@
+import type { NativeScrollEvent, NativeSyntheticEvent } from "react-native";
+
+/** A caller's `onScroll`, as React Native types it. */
+export type ScreenScrollCallback = (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+
+/**
+ * What a caller handed a Screen scrollable as `onScroll`.
+ *
+ * Two shapes reach the same prop and need different plumbing. A
+ * `useAnimatedScrollHandler` result is typed as a function but is really an
+ * object carrying a `workletEventHandler`, and it composes with the screen's own
+ * tracking on the UI thread. A plain function has to be called back on the JS
+ * thread instead — Reanimated replaces the JS listener with a no-op once a
+ * worklet handler owns the prop, so passing it through would drop it.
+ */
+export type ScreenScrollHandler =
+	| { kind: "none" }
+	| { kind: "js"; handler: ScreenScrollCallback }
+	| { kind: "worklet"; handler: object };
+
+/**
+ * Sorts a caller's `onScroll` into the shape the scroll hook can compose.
+ *
+ * Structural rather than `instanceof WorkletEventHandler`: the class is
+ * Reanimated-internal, and the property is what `useComposedEventHandler` reads.
+ */
+export function classifyScrollHandler(value: unknown): ScreenScrollHandler {
+	if (typeof value === "function") return { handler: value as ScreenScrollCallback, kind: "js" };
+	if (typeof value === "object" && value !== null && "workletEventHandler" in value) {
+		return { handler: value, kind: "worklet" };
+	}
+	return { kind: "none" };
+}

package/src/components/screen/screen-section-list.tsx

@@ -42,11 +42,15 @@ export const ScreenSectionList = forwardRef(function ScreenSectionListRender<Ite
 		contentContainerClassName,
 		ListHeaderComponent: ListHeaderComponentProp,
 		ListFooterComponent: ListFooterComponentProp,
+		onScroll,
 		...props
 	}: ScreenSectionListProps<ItemT, SectionT>,
 	ref: ForwardedRef<SectionList<ItemT, SectionT>>
 ): ReactElement {
-	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets("standard");
+	const { scrollHandler, insetTopAnimatedStyle, insetBottomAnimatedStyle } = useScreenScrollInsets(
+		"standard",
+		onScroll
+	);
 
 	const ListHeaderComponent = useMemo<ReactElement>(
 		() => (

package/src/components/screen/use-screen-scroll-insets.ts

@@ -1,4 +1,5 @@
 import { useState } from "react";
+import type { NativeScrollEvent, NativeSyntheticEvent } from "react-native";
 import { useReanimatedKeyboardAnimation } from "react-native-keyboard-controller";
 import {
 	type DerivedValue,
@@ -6,6 +7,7 @@ import {
 	useAnimatedReaction,
 	useAnimatedScrollHandler,
 	useAnimatedStyle,
+	useComposedEventHandler,
 	useDerivedValue,
 } from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
@@ -19,6 +21,7 @@ import {
 	resolveScrollTopInset,
 	type ScreenScrollInsetMode,
 } from "./screen.variants";
+import { classifyScrollHandler, type ScreenScrollCallback } from "./screen-scroll-handler";
 
 /**
  * The footer's collapsed baseline height, as JS state.
@@ -162,25 +165,48 @@ export function useScreenFooterKeyboardClearance(): number {
  * container cannot animate on the UI thread, and the navbar's height is only
  * known after it lays out — so a spacer view whose height is an animated style
  * is what lets the reserve appear in the same frame as the measurement.
+ *
+ * `onScroll` is the caller's own, and it is composed with the screen's tracking
+ * rather than competing with it for the one prop. Pass either a plain callback
+ * or a `useAnimatedScrollHandler` result; the hook sorts them.
  */
-export function useScreenScrollInsets(mode: ScreenScrollInsetMode) {
+export function useScreenScrollInsets(mode: ScreenScrollInsetMode, onScroll?: ScreenScrollCallback | null) {
 	const { navbar, footer, scrollY, contentHeight, layoutHeight } = useScreenPart("a Screen scrollable");
 	const { bottom, top } = useSafeAreaInsets();
 	const keyboard = useReanimatedKeyboardAnimation();
-
-	const scrollHandler = useAnimatedScrollHandler({
-		onScroll: (event) => {
-			scrollY.value = event.contentOffset.y;
-
-			if (event.contentSize.height !== contentHeight.value) {
-				contentHeight.value = event.contentSize.height;
-			}
-
-			if (event.layoutMeasurement.height !== layoutHeight.value) {
-				layoutHeight.value = event.layoutMeasurement.height;
-			}
+	const caller = classifyScrollHandler(onScroll);
+	const callerCallback = caller.kind === "js" ? caller.handler : undefined;
+
+	const trackingHandler = useAnimatedScrollHandler(
+		{
+			onScroll: (event) => {
+				scrollY.value = event.contentOffset.y;
+
+				if (event.contentSize.height !== contentHeight.value) {
+					contentHeight.value = event.contentSize.height;
+				}
+
+				if (event.layoutMeasurement.height !== layoutHeight.value) {
+					layoutHeight.value = event.layoutMeasurement.height;
+				}
+
+				// Only `nativeEvent` is real: a worklet sees the native payload, not
+				// React Native's synthetic wrapper, so `persist()` and the rest of the
+				// wrapper do not exist. A caller needing more passes a worklet handler.
+				if (callerCallback) {
+					scheduleOnRN(callerCallback, { nativeEvent: event } as unknown as NativeSyntheticEvent<NativeScrollEvent>);
+				}
+			},
 		},
-	});
+		[callerCallback]
+	);
+
+	// A caller's `useAnimatedScrollHandler` runs beside the tracking on the UI
+	// thread rather than replacing it — one `onScroll` prop, two worklets.
+	const scrollHandler = useComposedEventHandler([
+		trackingHandler,
+		caller.kind === "worklet" ? (caller.handler as typeof trackingHandler) : null,
+	]);
 
 	const insetTopAnimatedStyle = useAnimatedStyle(() => {
 		return {