@oxy.so/bloom 3.6.0 → 4.1.0

package/src/route-stops/RouteStops.tsx

@@ -0,0 +1,264 @@
+import React, { memo, useCallback, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { AddressRow, resolveAddressPaint } from '../address';
+import { Button, GlyphButton } from '../button';
+import { RiAddLine } from '../icons/remix/RiAddLine';
+import { RiArrowUpDownLine } from '../icons/remix/RiArrowUpDownLine';
+import { RiCloseLine } from '../icons/remix/RiCloseLine';
+import { hairlineOn, useSurfaceFill } from '../styles/surface-levels';
+import { resolveAccentColors } from '../theme/accent-colors';
+import { useTheme } from '../theme/use-theme';
+import { ROUTE_STOPS_GEOMETRY, ROUTE_STOP_STATE_LABELS, ROUTE_STOPS_SWAP_COLUMN, ROUTE_STOPS_SWAP_SIZE } from './constants';
+import type { RouteStop, RouteStopState, RouteStopsProps } from './types';
+
+/**
+ * An origin, a destination, and what is between them.
+ *
+ *   marker   the SHAPE says which stop it is, the COLOUR says how far the
+ *            journey got. Origin: a 12 ring (3px). Between: an 8 dot.
+ *            Destination: a 12 square, 3 radius — an end, not another dot.
+ *            `reached` and `current` paint the accent, `pending` the graphical
+ *            rung, and `current` adds a 3px tint halo.
+ *   connector 2px, travelled when the stop BELOW it has been reached or is
+ *            current — so the line fills behind the journey.
+ *   rows     `AddressRow` with `leading={null}`: the marker column is already
+ *            the gutter, so the row draws no tile of its own and every other
+ *            decision — press target, density, selected wash, disabled — stays
+ *            where it already was.
+ *   swap     a column of its own beside the list, centred against the whole of
+ *            it, so with two stops it lands between them without a magic
+ *            offset. Offered only for exactly two stops.
+ *
+ * THE MARKER COLUMN IS TWO HALF-LINES AROUND THE MARKER, each `flex: 1`. The
+ * marker therefore centres itself in whatever height the row turns out to be,
+ * and the half below one row meets the half above the next exactly — for a row
+ * with a subtitle, a badge, a wrapped line or none of those. Nothing measures
+ * anything and nothing is nudged.
+ *
+ * A `list` of `listitem`s named as one. Each row's announced name carries its
+ * POSITION and its STATE before its text — "Destination, not reached, Home,
+ * Carrer de l’Om 14" — because the shape and the colour that say both of
+ * those things on screen say nothing at all to a screen reader.
+ */
+function RouteStopsComponent({
+  stops,
+  onPressStop,
+  onSwap,
+  onAddStop,
+  onRemoveStop,
+  canAddStop = true,
+  density = 'comfortable',
+  labels,
+  addIcon = RiAddLine,
+  accessibilityLabel = 'Route stops',
+  style,
+  testID,
+}: RouteStopsProps) {
+  const theme = useTheme();
+  const surface = useSurfaceFill();
+  const paint = useMemo(() => resolveAddressPaint(theme, surface), [theme, surface]);
+  const connector = useMemo(() => hairlineOn(theme, surface), [theme, surface]);
+  const g = ROUTE_STOPS_GEOMETRY[density];
+
+  const accent = resolveAccentColors(theme.colors, 'primary', 'solid');
+  const halo = resolveAccentColors(theme.colors, 'primary', 'subtle').background;
+
+  const stateWords = { ...ROUTE_STOP_STATE_LABELS, ...labels?.state };
+  const originWord = labels?.origin ?? 'Origin';
+  const destinationWord = labels?.destination ?? 'Destination';
+  const stopWord = labels?.stop ?? ((position: number) => `Stop ${position}`);
+  const removeWord = labels?.remove ?? ((stop: RouteStop) => `Remove ${stop.title}`);
+
+  const travelled = (index: number): boolean => {
+    const stop = stops[index];
+    if (stop === undefined) return false;
+    const state = stop.state ?? 'pending';
+    return state === 'reached' || state === 'current';
+  };
+
+  const press = useCallback(
+    (id: string) => (onPressStop ? () => onPressStop(id) : undefined),
+    [onPressStop],
+  );
+
+  const positionWord = (index: number): string => {
+    if (index === 0) return originWord;
+    if (index === stops.length - 1) return destinationWord;
+    return stopWord(index + 1);
+  };
+
+  const list = (
+    <View role="list" accessibilityLabel={accessibilityLabel} testID={testID ? `${testID}-list` : undefined}>
+      {stops.map((stop, index) => {
+        const state: RouteStopState = stop.state ?? 'pending';
+        const first = index === 0;
+        const last = index === stops.length - 1;
+        const on = state === 'reached' || state === 'current';
+        const id = (part: string) => (testID ? `${testID}-${index}-${part}` : undefined);
+
+        // SHAPE says which stop, COLOUR says how far the journey got, and
+        // SIZE says which one is current. The third is not decoration: at 8px a
+        // tint halo drawn INSIDE the dot is two pixels of fill and reads as the
+        // same dot as the one before it, so the current stop grows by `halo`
+        // and wears the ring on the outside of its own diameter.
+        const current = state === 'current';
+        const base = first || last ? g.terminal : g.waypoint;
+        const size = current ? base + g.halo : base;
+        const marker = (
+          <View
+            testID={id('marker')}
+            style={{
+              width: size,
+              height: size,
+              borderRadius: last && !first ? g.square : size / 2,
+              backgroundColor: first ? surface : on ? accent.background : surface,
+              borderWidth: first || current ? 3 : on ? 0 : 1.5,
+              borderColor: first
+                ? on
+                  ? accent.background
+                  : paint.textGraphical
+                : current
+                  ? halo
+                  : paint.textGraphical,
+            }}
+          />
+        );
+
+        const rail = (side: 'in' | 'out') => (
+          <View
+            testID={id(side === 'in' ? 'rail-in' : 'rail-out')}
+            style={{
+              flex: 1,
+              minHeight: 4,
+              width: g.line,
+              borderRadius: g.line / 2,
+              backgroundColor:
+                side === 'in'
+                  ? first
+                    ? 'transparent'
+                    : travelled(index)
+                      ? accent.background
+                      : connector
+                  : last
+                    ? 'transparent'
+                    : travelled(index + 1)
+                      ? accent.background
+                      : connector,
+            }}
+          />
+        );
+
+        const name =
+          stop.accessibilityLabel ??
+          [positionWord(index), stateWords[state], stop.title, stop.subtitle, stop.meta]
+            .filter((part): part is string => typeof part === 'string' && part !== '')
+            .join(', ');
+
+        return (
+          <View
+            key={stop.id}
+            role="listitem"
+            // WHERE THE NAME GOES depends on whether the row is a control, and
+            // it is one or the other, never both. A pressable row is a BUTTON
+            // and carries the name itself; an unnamed `listitem` around it adds
+            // nothing. A read-only row is not a control at all — `Item`'s
+            // non-pressable branch renders `role="none"`, which is exactly the
+            // element an assistive technology is told to ignore — so the name
+            // has to be on the `listitem`, and naming both would announce the
+            // stop twice.
+            accessibilityLabel={onPressStop ? undefined : name}
+            testID={id('item')}
+            style={{ flexDirection: 'row' }}
+          >
+            <View style={{ width: g.column, alignItems: 'center' }}>
+              {rail('in')}
+              {marker}
+              {rail('out')}
+            </View>
+            {/*
+              The flex goes on a wrapper, not on `AddressRow`'s `style`: `Item`
+              applies that to its CONTENT view, one node below the `Pressable`
+              (or plain `View`) this row actually lays out — so `flex: 1` there
+              is invisible to this row, and the stop took the full min-content
+              width of its own one-line title.
+            */}
+            <View style={{ flex: 1, minWidth: 0 }}>
+            <AddressRow
+              title={stop.title}
+              subtitle={stop.subtitle}
+              meta={stop.meta}
+              badge={stop.badge}
+              kind={stop.kind}
+              leading={null}
+              density={density}
+              onPress={press(stop.id)}
+              accessibilityLabel={onPressStop ? name : undefined}
+              action={
+                <>
+                  {stop.action}
+                  {onRemoveStop ? (
+                    <GlyphButton
+                      size={32}
+                      glyphSize={16}
+                      icon={RiCloseLine}
+                      color={paint.textTertiary}
+                      hoverColor={paint.text}
+                      onPress={() => onRemoveStop(stop.id)}
+                      accessibilityLabel={removeWord(stop)}
+                      testID={id('remove')}
+                    />
+                  ) : null}
+                </>
+              }
+              testID={id('row')}
+            />
+            </View>
+          </View>
+        );
+      })}
+    </View>
+  );
+
+  const swappable = onSwap !== undefined && stops.length === 2;
+
+  return (
+    <View testID={testID} style={style}>
+      <View style={{ flexDirection: 'row', alignItems: 'stretch' }}>
+        <View style={{ flex: 1, minWidth: 0 }}>{list}</View>
+        {swappable ? (
+          <View
+            style={{ width: ROUTE_STOPS_SWAP_COLUMN, alignItems: 'center', justifyContent: 'center' }}
+          >
+            <GlyphButton
+              size={ROUTE_STOPS_SWAP_SIZE}
+              icon={RiArrowUpDownLine}
+              color={paint.textSecondary}
+              hoverColor={paint.text}
+              onPress={onSwap}
+              accessibilityLabel={labels?.swap ?? 'Swap origin and destination'}
+              testID={testID ? `${testID}-swap` : undefined}
+            />
+          </View>
+        ) : null}
+      </View>
+      {onAddStop ? (
+        <View style={{ alignItems: 'flex-start', paddingLeft: 8, paddingTop: 4 }}>
+          <Button
+            variant="text"
+            size="small"
+            leadingIcon={addIcon}
+            onPress={onAddStop}
+            disabled={!canAddStop}
+            testID={testID ? `${testID}-add` : undefined}
+          >
+            {labels?.addStop ?? 'Add a stop'}
+          </Button>
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+export const RouteStops = memo(RouteStopsComponent);
+RouteStops.displayName = 'RouteStops';

package/src/route-stops/constants.ts

@@ -0,0 +1,32 @@
+import type { AddressDensity } from '../address';
+import type { RouteStopState } from './types';
+
+export const ROUTE_STOP_STATE_LABELS: Record<RouteStopState, string> = {
+  reached: 'Reached',
+  current: 'Current stop',
+  pending: 'Not reached',
+};
+
+export interface RouteStopsGeometry {
+  /** The marker column's width. */
+  column: number;
+  /** The origin's ring and the destination's square. */
+  terminal: number;
+  /** A stop between them. */
+  waypoint: number;
+  /** How much wider the CURRENT stop's marker is, for its halo. */
+  halo: number;
+  /** The connector's thickness. */
+  line: number;
+  /** The destination square's corner. */
+  square: number;
+}
+
+export const ROUTE_STOPS_GEOMETRY: Record<AddressDensity, RouteStopsGeometry> = {
+  comfortable: { column: 24, terminal: 12, waypoint: 8, halo: 6, line: 2, square: 3 },
+  compact: { column: 20, terminal: 10, waypoint: 6, halo: 4, line: 2, square: 2 },
+};
+
+/** The swap control's column, wide enough for a 44 target. */
+export const ROUTE_STOPS_SWAP_COLUMN = 44;
+export const ROUTE_STOPS_SWAP_SIZE = 40;

package/src/route-stops/index.ts

@@ -0,0 +1,4 @@
+export { RouteStops } from './RouteStops';
+export { ROUTE_STOPS_GEOMETRY, ROUTE_STOP_STATE_LABELS } from './constants';
+export type { RouteStopsGeometry } from './constants';
+export type { RouteStop, RouteStopState, RouteStopsLabels, RouteStopsProps } from './types';

package/src/route-stops/types.ts

@@ -0,0 +1,82 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { AddressDensity, AddressKind } from '../address';
+import type { BloomIconComponent } from '../icons/icon-component';
+
+/**
+ * How far the journey has got. `reached` is behind, `current` is where the
+ * thing is heading or standing now, `pending` is ahead — so the same component
+ * draws a route being PLANNED (every stop pending) and one being TRAVELLED.
+ */
+export type RouteStopState = 'pending' | 'current' | 'reached';
+
+export interface RouteStop {
+  /** Identifies the stop to `onPressStop` / `onRemoveStop`, and keys the row. */
+  id: string;
+  /** The line the stop is recognised by — "Home", "Carrer de l’Om 14". */
+  title: string;
+  /** The rest of it. */
+  subtitle?: string;
+  /** Default `pending`. */
+  state?: RouteStopState;
+  /** A short trailing reading — "12 min", "1.2 km". */
+  meta?: string;
+  /** Passed to the row: chooses nothing here, because the marker column IS the glyph. */
+  kind?: AddressKind;
+  /** A node after the title — a `Badge`. */
+  badge?: ReactNode;
+  /** A trailing control, drawn before the remove affordance. */
+  action?: ReactNode;
+  /** The row's announced name, overriding the one assembled from its parts. */
+  accessibilityLabel?: string;
+}
+
+/**
+ * Every word `RouteStops` speaks, in one prop rather than seven — all of it is
+ * copy an app localises, and none of it is layout.
+ */
+export interface RouteStopsLabels {
+  /** The first stop's position. Default `"Origin"`. */
+  origin?: string;
+  /** The last stop's position, when there is more than one. Default `"Destination"`. */
+  destination?: string;
+  /** Every stop between them. Default `` (position) => `Stop ${position}` ``. */
+  stop?: (position: number) => string;
+  /** The swap control. Default `"Swap origin and destination"`. */
+  swap?: string;
+  /** The add control's label — it is a labelled button, so this is VISIBLE text. Default `"Add a stop"`. */
+  addStop?: string;
+  /** The remove control, per stop. Default ``(stop) => `Remove ${stop.title}` ``. */
+  remove?: (stop: RouteStop) => string;
+  /** Defaults: `reached` → "Reached", `current` → "Current stop", `pending` → "Not reached". */
+  state?: Partial<Record<RouteStopState, string>>;
+}
+
+export interface RouteStopsProps {
+  /** Origin first, destination last, everything else in between. */
+  stops: readonly RouteStop[];
+  /** Makes each row pressable — an app opens its own picker from here. */
+  onPressStop?: (id: string) => void;
+  /**
+   * Draws the swap control. It is offered ONLY for exactly two stops: with
+   * three or more there is no single swap to make, and a control that silently
+   * meant something different at three stops is worse than no control.
+   */
+  onSwap?: () => void;
+  /** Draws the "add a stop" button under the list. */
+  onAddStop?: () => void;
+  /** Draws a remove affordance on every stop. */
+  onRemoveStop?: (id: string) => void;
+  /** Disables `onAddStop`'s button — an app that caps the number of stops. */
+  canAddStop?: boolean;
+  /** Default `comfortable`. */
+  density?: AddressDensity;
+  labels?: RouteStopsLabels;
+  /** The glyph on the add button. Default a plus. */
+  addIcon?: BloomIconComponent;
+  /** Names the list. Default `"Route stops"`. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/screen/Screen.tsx

@@ -0,0 +1,61 @@
+import React, { useContext, useEffect, useMemo, useState } from 'react';
+import { Keyboard, Platform, View } from 'react-native';
+import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
+import { windowEdgeGap } from '../layout/edge';
+import { useSharedValue } from 'react-native-reanimated';
+import { useTheme } from '../theme/use-theme';
+import { WEB_POSITION_STICKY, WEB_VIEWPORT_HEIGHT } from '../styles/web-view-style';
+import { Z_INDEX } from '../styles/z-index';
+import { ScreenContext, ScreenNavigationContext } from './context';
+import { useScreenWindowBinding } from './use-screen-window-scroll';
+import type { ScreenProps } from './types';
+
+/** One continuous canvas; chrome overlays it and content reserves its measured footprint. */
+export function Screen({ header, bottomBar, primaryAction, active: requestedActive = true, navigationScope = 'inherit', documentScroll = false, headerHeight, bottomBarHeight, contentClearance = 16, children, style, testID, ...props }: ScreenProps) {
+  const { colors } = useTheme();
+  const parentScreen = useContext(ScreenContext);
+  const active = requestedActive && (navigationScope === 'isolated' ? true : parentScreen?.active ?? true);
+  const scrollY = useSharedValue(0);
+  const localProgress = useSharedValue(0);
+  const localTarget = useSharedValue(0);
+  const localScroller = useSharedValue<string | null>(null);
+  const inheritedNavigation = useContext(ScreenNavigationContext);
+  const navigation = useMemo(() => navigationScope === 'inherit' && inheritedNavigation ? inheritedNavigation : { collapseProgress: localProgress, collapseTarget: localTarget, activeScrollerId: localScroller }, [navigationScope, inheritedNavigation, localProgress, localTarget, localScroller]);
+  const { collapseProgress, collapseTarget, activeScrollerId } = navigation;
+  const insets = useContext(SafeAreaInsetsContext);
+  const [measuredTop, setTop] = useState<number | null>(null);
+  const [measuredBottom, setBottom] = useState<number | null>(null);
+  const top = measuredTop ?? headerHeight ?? (56 + (Platform.OS === 'web' ? 0 : insets?.top ?? 0));
+  const bottom = measuredBottom ?? bottomBarHeight ?? (58 + windowEdgeGap(insets?.bottom ?? 0));
+  const [keyboardVisible, setKeyboardVisible] = useState(false);
+  useEffect(() => {
+    if (Platform.OS === 'web') return;
+    const show = Keyboard.addListener('keyboardDidShow', () => setKeyboardVisible(true));
+    const hide = Keyboard.addListener('keyboardDidHide', () => setKeyboardVisible(false));
+    return () => { show.remove(); hide.remove(); };
+  }, []);
+  const hasBottom = !keyboardVisible && Boolean(bottomBar || primaryAction);
+  const document = documentScroll && Platform.OS === 'web';
+  const value = useMemo(() => ({ active, scrollY, collapseProgress, collapseTarget, activeScrollerId,
+    contentInsetsHandled: document, topInset: header ? top : 0, bottomInset: hasBottom ? bottom + contentClearance : navigationScope === 'inherit' ? inheritedNavigation?.bottomInset ?? contentClearance : contentClearance,
+  }), [active, scrollY, collapseProgress, collapseTarget, activeScrollerId, header, hasBottom, top, bottom, contentClearance, navigationScope, inheritedNavigation?.bottomInset, document]);
+  useScreenWindowBinding(value, { active: document });
+  const headerNode = header ? <View testID={testID ? `${testID}-header` : undefined} pointerEvents="box-none" onLayout={event => setTop(event.nativeEvent.layout.height)} style={document ? { position: WEB_POSITION_STICKY, top: 0, zIndex: Z_INDEX.floating, marginBottom: -top } : { position: 'absolute', top: 0, left: 0, right: 0 }}>{header}</View> : null;
+  const bottomNode = hasBottom ? <View testID={testID ? `${testID}-bottom` : undefined} pointerEvents="box-none" onLayout={event => setBottom(event.nativeEvent.layout.height)} style={document ? { position: WEB_POSITION_STICKY, bottom: 0, zIndex: Z_INDEX.floating, marginTop: -bottom } : { position: 'absolute', bottom: 0, left: 0, right: 0 }}>{bottomBar ?? <View pointerEvents="box-none" style={{ alignItems: 'flex-end', paddingHorizontal: 16, paddingBottom: windowEdgeGap(insets?.bottom ?? 0), minHeight: bottom }}>{primaryAction}</View>}</View> : null;
+  return (
+    <ScreenNavigationContext.Provider value={navigationScope === 'inherit' ? inheritedNavigation : { ...navigation, bottomInset: value.bottomInset }}>
+    <ScreenContext.Provider value={value}>
+      <View {...props} testID={testID} style={[document ? { minHeight: WEB_VIEWPORT_HEIGHT, width: '100%', position: 'relative', backgroundColor: colors.background } : { flex: 1, minHeight: 0, position: 'relative', backgroundColor: colors.background }, style]}>
+        {document ? headerNode : null}
+        {document ? <View testID={testID ? `${testID}-content` : undefined} style={{
+          flexGrow: 1, flexShrink: 0,
+          paddingTop: header ? top : 0,
+          paddingBottom: hasBottom ? bottom + contentClearance : 0,
+        }}>{children}</View> : children}
+        {document ? null : headerNode}
+        {bottomNode}
+      </View>
+    </ScreenContext.Provider>
+    </ScreenNavigationContext.Provider>
+  );
+}

package/src/screen/ScreenScrollView.tsx

@@ -0,0 +1,11 @@
+import React, { forwardRef } from 'react';
+import { ScrollView, StyleSheet } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useScreenScroll } from './use-screen-scroll';
+import type { ScreenScrollViewProps } from './types';
+
+export const ScreenScrollView = forwardRef<ScrollView, ScreenScrollViewProps>(function ScreenScrollView({ active, handler, restoration, contentContainerStyle, children, style, ...props }, ref) {
+  const scroll = useScreenScroll({ active, handler, restoration });
+  const contentStyle = StyleSheet.flatten(contentContainerStyle);
+  return <Animated.ScrollView {...props} ref={ref} style={[style, restoration?.restorePending ? { opacity: 0 } : null]} onScroll={scroll.onScroll} scrollEventThrottle={16} contentInsetAdjustmentBehavior="never" automaticallyAdjustContentInsets={false} contentContainerStyle={[contentContainerStyle, { paddingTop: scroll.contentInsets.top + Number(contentStyle?.paddingTop ?? contentStyle?.paddingVertical ?? contentStyle?.padding ?? 0), paddingBottom: scroll.contentInsets.bottom + Number(contentStyle?.paddingBottom ?? contentStyle?.paddingVertical ?? contentStyle?.padding ?? 0) }]}>{children}</Animated.ScrollView>;
+});

package/src/screen/context.ts

@@ -0,0 +1,25 @@
+import { createContext, useContext } from 'react';
+import type { SharedValue } from 'react-native-reanimated';
+
+export interface ScreenContextValue {
+  active: boolean;
+  scrollY: SharedValue<number>;
+  collapseProgress: SharedValue<number>;
+  collapseTarget: SharedValue<number>;
+  activeScrollerId: SharedValue<string | null>;
+  /** Document-flow Screen has already reserved its content clearance. */
+  contentInsetsHandled?: boolean;
+  topInset: number;
+  bottomInset: number;
+}
+
+export type ScreenNavigationState = Pick<ScreenContextValue, 'collapseProgress' | 'collapseTarget' | 'activeScrollerId'> & { bottomInset?: number };
+export const ScreenNavigationContext = createContext<ScreenNavigationState | null>(null);
+
+export const ScreenContext = createContext<ScreenContextValue | null>(null);
+export function useScreenContext() { return useContext(ScreenContext); }
+export function useScreen(): ScreenContextValue {
+  const screen = useScreenContext();
+  if (!screen) throw new Error('Screen content must be rendered inside <Screen>.');
+  return screen;
+}

package/src/screen/index.ts

@@ -0,0 +1,6 @@
+export { Screen } from './Screen';
+export { ScreenScrollView } from './ScreenScrollView';
+export { useScreen } from './context';
+export { useScreenScroll } from './use-screen-scroll';
+export type { ScreenProps, ScreenScrollOptions, ScreenScrollViewProps } from './types';
+export { useScreenWindowScroll } from './use-screen-window-scroll';

package/src/screen/types.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+import type { ScrollViewProps, ViewProps } from 'react-native';
+import type { ScrollRestorationBinding } from '../scroll/types';
+import type { ScrollHandlerProcessed } from 'react-native-reanimated';
+
+export interface ScreenProps extends ViewProps {
+  header?: ReactNode;
+  /** Disable all descendant scroll writers when a navigator retains this screen. */
+  active?: boolean;
+  /** inherit shell navigation motion; shared establishes a shell; isolated resets it for a modal. */
+  navigationScope?: 'inherit' | 'shared' | 'isolated';
+  /** Web document flow: bind window scrolling automatically, reserve chrome clearance, and keep chrome sticky within this column. Explicit list bindings take priority. */
+  documentScroll?: boolean;
+  bottomBar?: ReactNode;
+  /** Standalone action; with navigation use BottomBar.action instead. */
+  primaryAction?: ReactNode;
+  /** Initial footprint before layout; include any safe area in custom values. */
+  headerHeight?: number;
+  bottomBarHeight?: number;
+  /** Extra visual clearance beyond the measured bottom chrome. */
+  contentClearance?: number;
+}
+
+export interface ScreenScrollOptions {
+  /** Only the focused screen/list may drive chrome. */
+  active?: boolean;
+  /** Existing restoration binding for this same scroll ref. */
+  restoration?: ScrollRestorationBinding;
+  handler?: ScrollHandlerProcessed | null;
+}
+
+export interface ScreenScrollViewProps extends Omit<ScrollViewProps, 'onScroll'>, ScreenScrollOptions {}

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

@@ -0,0 +1,38 @@
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
+import { useCallback, useEffect, useId } from 'react';
+import { runOnJS, useAnimatedScrollHandler, useComposedEventHandler, useReducedMotion, useSharedValue, withSpring } from 'react-native-reanimated';
+import { useScreen } from './context';
+import type { ScreenScrollOptions } from './types';
+
+/** Bind an animated ScrollView or virtualized list without moving frame work to JS. */
+export function useScreenScroll({ active: requestedActive = true, handler = null, restoration }: ScreenScrollOptions = {}) {
+  const screen = useScreen();
+  const active = requestedActive && screen.active;
+  const restoring = restoration?.restorePending ?? false;
+  const id = useId();
+  const previousY = useSharedValue(0);
+  const reducedMotion = useReducedMotion();
+  useEffect(() => {
+    if (!active) return;
+    screen.activeScrollerId.value = id;
+    return () => { if (screen.activeScrollerId.value === id) screen.activeScrollerId.value = null; };
+  }, [active, id, screen.activeScrollerId]);
+  const record = useCallback((event: NativeScrollEvent) => restoration?.onScroll({ nativeEvent: event } as NativeSyntheticEvent<NativeScrollEvent>), [restoration?.onScroll]);
+  const hasRestoration = restoration != null;
+  const ownHandler = useAnimatedScrollHandler({ onScroll: event => {
+    if (!active || screen.activeScrollerId.value !== id) return;
+    if (hasRestoration) runOnJS(record)(event);
+    const y = Math.min(Math.max(0, event.contentOffset.y), Math.max(0, event.contentSize.height - event.layoutMeasurement.height));
+    const delta = y - previousY.value;
+    previousY.value = y;
+    screen.scrollY.value = y;
+    if (restoring) return;
+    const target = y < 24 ? 0 : delta > 3 ? 1 : delta < -3 ? 0 : screen.collapseTarget.value;
+    if (target !== screen.collapseTarget.value) {
+      screen.collapseTarget.value = target;
+      screen.collapseProgress.value = reducedMotion ? target : withSpring(target, { duration: 380, dampingRatio: 1 });
+    }
+  } }, [screen, active, id, previousY, reducedMotion, hasRestoration, record, restoring]);
+  const onScroll = useComposedEventHandler([ownHandler, handler]);
+  return { onScroll, scrollerId: id, contentInsets: { top: screen.contentInsetsHandled ? 0 : screen.topInset, bottom: screen.contentInsetsHandled ? 0 : screen.bottomInset }, scrollY: screen.scrollY, collapseProgress: screen.collapseProgress };
+}

package/src/screen/use-screen-window-scroll.ts

@@ -0,0 +1,38 @@
+import { useEffect } from 'react';
+import { useReducedMotion, withSpring } from 'react-native-reanimated';
+import { useScreen, type ScreenContextValue } from './context';
+import { useScreenScroll } from './use-screen-scroll';
+import type { ScreenScrollOptions } from './types';
+
+/** Window-scrolling counterpart for document virtualizers; never creates a nested scroller. */
+export function useScreenWindowScroll(options: ScreenScrollOptions = {}) {
+  const binding = useScreenScroll(options);
+  const screen = useScreen();
+  useScreenWindowBinding(screen, options, binding.scrollerId);
+  return binding;
+}
+
+/** Internal default listener yields to a registered list/virtualizer. */
+export function useScreenWindowBinding(screen: ScreenContextValue, options: ScreenScrollOptions = {}, owner: string | null = null) {
+  const reducedMotion = useReducedMotion();
+  useEffect(() => {
+    if (!screen.active || options.active === false || typeof window === 'undefined') return;
+    let previous = window.scrollY;
+    const update = () => {
+      const y = Math.max(0, window.scrollY);
+      const delta = y - previous;
+      previous = y;
+      if (screen.activeScrollerId.value !== owner) return;
+      screen.scrollY.value = y;
+      if (options.restoration?.restorePending) return;
+      const target = y < 24 ? 0 : delta > 3 ? 1 : delta < -3 ? 0 : screen.collapseTarget.value;
+      if (target !== screen.collapseTarget.value) {
+        screen.collapseTarget.value = target;
+        screen.collapseProgress.value = reducedMotion ? target : withSpring(target, { duration: 380, dampingRatio: 1 });
+      }
+    };
+    if (screen.activeScrollerId.value === owner) screen.scrollY.value = previous;
+    window.addEventListener('scroll', update, { passive: true });
+    return () => window.removeEventListener('scroll', update);
+  }, [screen, options.active, options.restoration?.restorePending, reducedMotion, owner]);
+}