@q9labsai/chalk-react-native 4.1.17 → 5.0.1

package/src/limbo/Limbo.tsx

@@ -0,0 +1,159 @@
+import { useEffect, useRef } from "react";
+import { AccessibilityInfo, findNodeHandle, StyleSheet, View } from "react-native";
+import Animated, { cancelAnimation, Easing, useAnimatedStyle, useReducedMotion, useSharedValue, withRepeat, withTiming } from "react-native-reanimated";
+import { useMeasuredRef } from "../frame/measurement";
+import { Icon } from "../icons/Icon";
+import { ChalkText } from "../primitives/ChalkText";
+import { PillButton } from "../primitives/PillButton";
+import { useTheme } from "../theme/theme";
+import { fontFamilies } from "../theme/tokens";
+
+/** The waiting states that sit over the blurred call (T1, T3 to T6). */
+export type LimboState =
+  | { readonly kind: "joining"; readonly rejoining: boolean }
+  | { readonly kind: "knocking"; readonly onCancel: () => void }
+  | { readonly kind: "refused"; readonly onAskAgain: () => void }
+  | { readonly kind: "reconnecting"; readonly queuedMessages: number }
+  | { readonly kind: "hold" };
+
+export type LimboProps = {
+  readonly state: LimboState;
+  readonly callName: string;
+  /** Shows the recording consent line while joining or knocking. */
+  readonly recording: boolean;
+};
+
+/** The limbo card (`.lmsg`) centred over the veiled call, with the mockup's copy for each state. */
+export function Limbo({ state, callName, recording }: LimboProps): React.JSX.Element {
+  const { colors } = useTheme();
+  const cardStyle = [styles.card, { backgroundColor: colors.surface, borderColor: colors.line }];
+  const cardRef = useMeasuredRef<View>("limbo.card", cardStyle);
+  const actionRef = useRef<View>(null);
+  const consent = recording && (state.kind === "joining" || state.kind === "knocking") ? <Consent /> : null;
+  // The mockup moves focus to the card's button when a state with one appears.
+  useEffect(() => {
+    const node = actionRef.current && findNodeHandle(actionRef.current);
+    if (node) AccessibilityInfo.setAccessibilityFocus(node);
+  }, [state.kind]);
+
+  return (
+    <View pointerEvents="box-none" style={styles.limbo} testID="frame.limbo">
+      <View accessibilityLiveRegion={state.kind === "refused" ? "assertive" : "polite"} accessibilityRole={state.kind === "refused" ? "alert" : "summary"} ref={cardRef} style={cardStyle} testID="limbo.card">
+        {state.kind === "joining" ? (
+          <Progress message={`${state.rejoining ? "Rejoining" : "Joining"} ${callName}…`} />
+        ) : state.kind === "knocking" ? (
+          <>
+            <Title>{`Asking to join ${callName}`}</Title>
+            <Line>The host will let you in.</Line>
+            {consent}
+            <View style={styles.action}>
+              <PillButton label="Cancel" onPress={state.onCancel} ref={actionRef} testID="limbo.cancel" />
+            </View>
+          </>
+        ) : state.kind === "refused" ? (
+          <>
+            <Title>The host didn’t let you in</Title>
+            <View style={styles.action}>
+              <PillButton label="Ask again" onPress={state.onAskAgain} ref={actionRef} testID="limbo.ask-again" variant="primary" />
+            </View>
+          </>
+        ) : state.kind === "reconnecting" ? (
+          <>
+            <Progress message="Reconnecting…" />
+            {state.queuedMessages > 0 ? <Line>{`${state.queuedMessages} message${state.queuedMessages > 1 ? "s" : ""} will send when you’re back`}</Line> : null}
+          </>
+        ) : (
+          <>
+            <HoldIcon />
+            <Title>Your call is on hold</Title>
+            <Line>{`You’re on a phone call. You’ll be back in ${callName} when it ends.`}</Line>
+          </>
+        )}
+        {state.kind === "joining" ? consent : null}
+      </View>
+    </View>
+  );
+}
+
+function Title({ children }: { readonly children: string }): React.JSX.Element {
+  return (
+    <ChalkText accessibilityRole="header" style={styles.center} testID="limbo.title" variant="limboTitle">
+      {children}
+    </ChalkText>
+  );
+}
+
+function Line({ children }: { readonly children: string }): React.JSX.Element {
+  return (
+    <ChalkText style={styles.center} testID="limbo.line" tone="textSoft">
+      {children}
+    </ChalkText>
+  );
+}
+
+function Progress({ message }: { readonly message: string }): React.JSX.Element {
+  return (
+    <View style={styles.row}>
+      <Spinner />
+      <ChalkText testID="limbo.progress" variant="progress">
+        {message}
+      </ChalkText>
+    </View>
+  );
+}
+
+/** `.hico`: the earpiece in green on a raised circle. */
+function HoldIcon(): React.JSX.Element {
+  const { colors } = useTheme();
+  const style = [styles.holdIcon, { backgroundColor: colors.raised }];
+  const ref = useMeasuredRef<View>("limbo.hold-icon", style);
+  return (
+    <View ref={ref} style={style} testID="limbo.hold-icon">
+      <Icon color={colors.success} name="earpiece" />
+    </View>
+  );
+}
+
+/** `.consent`: everyone who joins a recorded call is told before they're in. */
+function Consent(): React.JSX.Element {
+  const { colors } = useTheme();
+  return (
+    <View style={styles.consent} testID="limbo.consent">
+      <Icon color={colors.dangerText} name="rec" size={14} />
+      <ChalkText tone="textMuted" variant="label" style={styles.consentText}>
+        This call is recorded. By joining, you agree to be recorded.
+      </ChalkText>
+    </View>
+  );
+}
+
+/** `.spin`: an 18 pt ring with a bright quarter, one turn every 0.9 s; still with reduced motion. */
+function Spinner(): React.JSX.Element {
+  const { colors } = useTheme();
+  const reduceMotion = useReducedMotion();
+  const turn = useSharedValue(0);
+  useEffect(() => {
+    if (reduceMotion) return;
+    turn.value = withRepeat(withTiming(1, { duration: 900, easing: Easing.linear }), -1);
+    return () => cancelAnimation(turn);
+  }, [reduceMotion, turn]);
+  const style = useAnimatedStyle(() => {
+    "worklet";
+    return { transform: [{ rotate: `${turn.value * 360}deg` }] };
+  });
+  return <Animated.View style={[styles.spinner, { borderColor: colors.lineStrong, borderTopColor: reduceMotion ? colors.textMuted : colors.text }, style]} />;
+}
+
+const styles = StyleSheet.create({
+  limbo: { ...StyleSheet.absoluteFillObject, alignItems: "center", justifyContent: "center" },
+  card: { alignItems: "center", gap: 8, maxWidth: "100%", paddingVertical: 22, paddingHorizontal: 28, borderWidth: 1, borderRadius: 16, marginHorizontal: 16 },
+  row: { flexDirection: "row", alignItems: "center", gap: 10 },
+  center: { textAlign: "center" },
+  // `.lmsg .pb` adds 10 pt above the button on top of the card's 8 pt gap.
+  action: { marginTop: 10 },
+  holdIcon: { width: 44, height: 44, borderRadius: 22, alignItems: "center", justifyContent: "center", marginBottom: 4 },
+  consent: { flexDirection: "row", alignItems: "center", gap: 6, marginTop: 4 },
+  // `.consent` is 12 pt at the body weight.
+  consentText: { fontFamily: fontFamilies[400], flexShrink: 1 },
+  spinner: { width: 18, height: 18, borderRadius: 9, borderWidth: 2 },
+});

package/src/limbo/Veil.tsx

@@ -0,0 +1,36 @@
+import { useEffect } from "react";
+import { StyleSheet } from "react-native";
+import Animated, { ReduceMotion, useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { useTheme } from "../theme/theme";
+import { durations, easings } from "../theme/tokens";
+
+/**
+ * How much of the call shows through. The mockup blurs the call (18 pt while joining or
+ * knocking, 10 pt and greyed while reconnecting or on hold); without a native blur view the
+ * veil covers it with the canvas colour instead.
+ */
+export type VeilLevel = "none" | "limbo" | "paused";
+
+const OPACITY: Readonly<Record<VeilLevel, number>> = { none: 0, limbo: 0.85, paused: 0.75 };
+
+/** `.veil`: the call lifts out of limbo by fading the canvas from 60 % to nothing over 300 ms. */
+const LIFT_FROM = 0.6;
+
+export function Veil({ level }: { readonly level: VeilLevel }): React.JSX.Element {
+  const { colors } = useTheme();
+  const opacity = useSharedValue(OPACITY[level]);
+  useEffect(() => {
+    if (level !== "none") {
+      opacity.value = OPACITY[level];
+      return;
+    }
+    if (opacity.value === 0) return;
+    opacity.value = LIFT_FROM;
+    opacity.value = withTiming(0, { duration: durations.veil, easing: easings.easeOut, reduceMotion: ReduceMotion.System });
+  }, [level, opacity]);
+  const style = useAnimatedStyle(() => {
+    "worklet";
+    return { opacity: opacity.value };
+  });
+  return <Animated.View pointerEvents={level === "none" ? "none" : "auto"} style={[StyleSheet.absoluteFill, { backgroundColor: colors.canvas }, style]} testID="limbo.veil" />;
+}

package/src/media/native-capture-error.test.ts

@@ -0,0 +1,19 @@
+import { describeMediaCaptureError } from "@q9labsai/chalk-client";
+import { describe, expect, it } from "vitest";
+import { toNativeCaptureError } from "./native-capture-error";
+
+describe("toNativeCaptureError", () => {
+  it("makes a native permission denial recoverable through the shared classifier", () => {
+    const denied = toNativeCaptureError({ name: "SecurityError", message: "Permission denied." });
+
+    expect(describeMediaCaptureError(denied).code).toBe("permission_denied");
+  });
+
+  it("leaves every other capture error as it was", () => {
+    const insecure = { name: "SecurityError", message: "The operation is insecure." };
+    const notFound = { name: "NotFoundError", message: "Requested device not found" };
+
+    expect(toNativeCaptureError(insecure)).toBe(insecure);
+    expect(toNativeCaptureError(notFound)).toBe(notFound);
+  });
+});

package/src/media/native-capture-error.ts

@@ -0,0 +1,13 @@
+/**
+ * `@cloudflare/react-native-webrtc` reports a denied microphone or camera as a `SecurityError`, which the
+ * shared capture classifier reads as an unsupported environment. A denial is a `NotAllowedError` on the
+ * web, so the native adapter gives it that name and the call can offer Open Settings.
+ */
+export function toNativeCaptureError(cause: unknown): unknown {
+  if (!isNativePermissionDenial(cause)) return cause;
+  return Object.assign(new Error(cause.message), { name: "NotAllowedError", cause });
+}
+
+function isNativePermissionDenial(cause: unknown): cause is { readonly name: "SecurityError"; readonly message: "Permission denied." } {
+  return typeof cause === "object" && cause !== null && "name" in cause && cause.name === "SecurityError" && "message" in cause && cause.message === "Permission denied.";
+}

package/src/motion/MovingFrame.tsx

@@ -0,0 +1,101 @@
+import { useEffect, useRef, type ReactNode } from "react";
+import { StyleSheet, type StyleProp, type ViewStyle } from "react-native";
+import Animated, { runOnUI, useAnimatedStyle, useReducedMotion, useSharedValue, withTiming } from "react-native-reanimated";
+import { timings } from "./motion";
+
+export type Frame = {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+export type MovingFrameProps = {
+  readonly frame: Frame;
+  readonly children: ReactNode;
+  readonly style?: StyleProp<ViewStyle>;
+  readonly testID?: string;
+};
+
+/**
+ * Places its children in `frame` and, when `frame` changes, moves them there from where they
+ * were drawn: the view takes its new box at once and a translate-and-scale transform plays from
+ * the old box to identity over 220 ms on the UI thread. The children are never remounted, so a
+ * video view inside keeps its surface. A move that starts mid-move begins from the current
+ * on-screen box. Reduced motion jumps straight to the new box.
+ *
+ * Example, a stage tile keyed by participant so React keeps the same view across layouts:
+ *
+ * ```tsx
+ * {tiles.map((tile) => (
+ *   <MovingFrame frame={tile.frame} key={tile.participantId} testID={`tile.${tile.participantId}`}>
+ *     <TileShell cameraOn={tile.cameraOn} level={tile.level}>
+ *       <ParticipantVideo participantId={tile.participantId} />
+ *       <NameTag name={tile.name} muted={tile.muted} />
+ *     </TileShell>
+ *   </MovingFrame>
+ * ))}
+ * ```
+ */
+export function MovingFrame({ frame, children, style, testID }: MovingFrameProps): React.JSX.Element {
+  const reduceMotion = useReducedMotion();
+  const target = useSharedValue<Frame>(frame);
+  const from = useSharedValue<Frame>(frame);
+  const progress = useSharedValue(1);
+  const mounted = useRef(false);
+
+  const { x, y, width, height } = frame;
+  useEffect(() => {
+    if (!mounted.current) {
+      mounted.current = true;
+      return;
+    }
+    runOnUI((next: Frame, instant: boolean) => {
+      "worklet";
+      const t = progress.value;
+      const was = target.value;
+      const start = from.value;
+      const shown: Frame = {
+        x: was.x + (start.x - was.x) * (1 - t),
+        y: was.y + (start.y - was.y) * (1 - t),
+        width: was.width + (start.width - was.width) * (1 - t),
+        height: was.height + (start.height - was.height) * (1 - t),
+      };
+      target.value = next;
+      if (instant) {
+        from.value = next;
+        progress.value = 1;
+        return;
+      }
+      from.value = shown;
+      progress.value = 0;
+      progress.value = withTiming(1, timings.move);
+    })({ x, y, width, height }, reduceMotion);
+  }, [x, y, width, height, reduceMotion, from, progress, target]);
+
+  const animatedStyle = useAnimatedStyle(() => {
+    "worklet";
+    const next = target.value;
+    const start = from.value;
+    const rest = 1 - progress.value;
+    const scaleX = next.width > 0 ? 1 + (start.width / next.width - 1) * rest : 1;
+    const scaleY = next.height > 0 ? 1 + (start.height / next.height - 1) * rest : 1;
+    return {
+      left: next.x,
+      top: next.y,
+      width: next.width,
+      height: next.height,
+      transform: [{ translateX: (start.x - next.x) * rest }, { translateY: (start.y - next.y) * rest }, { scaleX }, { scaleY }],
+    };
+  });
+
+  return (
+    <Animated.View style={[styles.frame, style, animatedStyle]} testID={testID}>
+      {children}
+    </Animated.View>
+  );
+}
+
+const styles = StyleSheet.create({
+  frame: { position: "absolute", transformOrigin: "left top" },
+});

package/src/motion/motion.ts

@@ -0,0 +1,33 @@
+import { ReduceMotion, useReducedMotion, withTiming, type WithTimingConfig } from "react-native-reanimated";
+import { durations, easings } from "../theme/tokens";
+
+export { useReducedMotion };
+
+/**
+ * Named timings from the mockup. Each one also honours the system's reduced-motion setting,
+ * which makes the change instant.
+ */
+export const timings = {
+  press: { duration: durations.press, easing: easings.easeOut, reduceMotion: ReduceMotion.System },
+  fade: { duration: durations.chromeFade, easing: easings.easeOut, reduceMotion: ReduceMotion.System },
+  menu: { duration: durations.menu, easing: easings.emphasized, reduceMotion: ReduceMotion.System },
+  toastIn: { duration: durations.toastIn, easing: easings.emphasized, reduceMotion: ReduceMotion.System },
+  toastOut: { duration: durations.toastOut, easing: easings.easeOut, reduceMotion: ReduceMotion.System },
+  scrim: { duration: durations.scrim, easing: easings.easeOut, reduceMotion: ReduceMotion.System },
+  sheet: { duration: durations.sheet, easing: easings.emphasized, reduceMotion: ReduceMotion.System },
+  move: { duration: durations.move, easing: easings.move, reduceMotion: ReduceMotion.System },
+  enter: { duration: durations.enter, easing: easings.move, reduceMotion: ReduceMotion.System },
+  leave: { duration: durations.leave, easing: easings.easeOut, reduceMotion: ReduceMotion.System },
+  copyMorph: { duration: durations.copyMorph, easing: easings.emphasized, reduceMotion: ReduceMotion.System },
+  switch: { duration: durations.press, easing: easings.easeOut, reduceMotion: ReduceMotion.System },
+  avatarTurn: { duration: durations.avatarTurn, easing: easings.standard, reduceMotion: ReduceMotion.System },
+  level: { duration: durations.speakingLevel, easing: easings.linear, reduceMotion: ReduceMotion.System },
+} as const satisfies Readonly<Record<string, WithTimingConfig>>;
+
+export type TimingName = keyof typeof timings;
+
+/** `withTiming` with one of the named timings. Call it from a worklet or from JS. */
+export function animateTo(value: number, timing: TimingName): number {
+  "worklet";
+  return withTiming(value, timings[timing]);
+}

package/src/motion/presence.ts

@@ -0,0 +1,20 @@
+import { withTiming, type EntryExitAnimationFunction } from "react-native-reanimated";
+import { timings } from "./motion";
+
+/** A new tile fades in from 97 % scale over 220 ms. Pass as `entering` on an Animated.View. */
+export const tileEntering: EntryExitAnimationFunction = () => {
+  "worklet";
+  return {
+    initialValues: { opacity: 0, transform: [{ scale: 0.97 }] },
+    animations: { opacity: withTiming(1, timings.enter), transform: [{ scale: withTiming(1, timings.enter) }] },
+  };
+};
+
+/** A leaving tile fades out over 160 ms. Pass as `exiting` on an Animated.View. */
+export const tileLeaving: EntryExitAnimationFunction = () => {
+  "worklet";
+  return {
+    initialValues: { opacity: 1 },
+    animations: { opacity: withTiming(0, timings.leave) },
+  };
+};

package/src/motion/press.ts

@@ -0,0 +1,35 @@
+import { useCallback } from "react";
+import { useAnimatedStyle, useSharedValue, withTiming, type SharedValue } from "react-native-reanimated";
+import { pressScale } from "../theme/tokens";
+import { timings } from "./motion";
+
+export type PressAnimation = {
+  /** 1 while the finger is down, 0 otherwise; flips at once, for instant colour changes. */
+  readonly down: SharedValue<number>;
+  readonly onPressIn: () => void;
+  readonly onPressOut: () => void;
+  readonly scaleStyle: ReturnType<typeof useAnimatedStyle>;
+};
+
+/**
+ * The mockup's `:active` press: the control scales down over 150 ms ease-out while its
+ * background switches at once. Runs on the UI thread; reduced motion keeps the scale at 1.
+ */
+export function usePressAnimation(family: keyof typeof pressScale): PressAnimation {
+  const down = useSharedValue(0);
+  const scale = useSharedValue(1);
+  const pressedScale = pressScale[family];
+  const onPressIn = useCallback(() => {
+    down.value = 1;
+    scale.value = withTiming(pressedScale, timings.press);
+  }, [down, pressedScale, scale]);
+  const onPressOut = useCallback(() => {
+    down.value = 0;
+    scale.value = withTiming(1, timings.press);
+  }, [down, scale]);
+  const scaleStyle = useAnimatedStyle(() => {
+    "worklet";
+    return { transform: [{ scale: scale.value }] };
+  });
+  return { down, onPressIn, onPressOut, scaleStyle };
+}

package/src/primitives/BottomSheet.tsx

@@ -0,0 +1,211 @@
+import { createContext, useCallback, useContext, useEffect, useRef, useState, type ReactNode, type RefObject } from "react";
+import { AccessibilityInfo, findNodeHandle, Pressable, StyleSheet, View, type LayoutChangeEvent } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, { runOnJS, useAnimatedKeyboard, useAnimatedStyle, useReducedMotion, useSharedValue, withTiming, type SharedValue } from "react-native-reanimated";
+import { useBackHandler } from "../frame/back-handler";
+import { useDeviceLayout } from "../frame/device-layout";
+import { Portal } from "../frame/portal";
+import { useMeasuredRef } from "../frame/measurement";
+import { haptics } from "../haptics/haptics";
+import { timings } from "../motion/motion";
+import { useTheme } from "../theme/theme";
+import { durations, fixed, radii } from "../theme/tokens";
+import { ChalkText } from "./ChalkText";
+
+export type BottomSheetProps = {
+  readonly open: boolean;
+  readonly onClose: () => void;
+  readonly accessibilityLabel: string;
+  readonly children: ReactNode;
+  /** A header line under the grabber (`.shd`); it takes accessibility focus when the sheet opens. */
+  readonly title?: string;
+  /** A fixed height as a share of the screen; People and Chat use 0.78. Without it the sheet fits its content. */
+  readonly heightRatio?: number;
+  /** Side padding: 12 for menu-like sheets (`.sheet`), 20 for card-like ones (`.ready`). */
+  readonly inset?: 12 | 14 | 20;
+  /**
+   * `card` is the People and Chat card (`.phone .card`): no side padding, the grabber 8 pt from the
+   * top with nothing under it, and no bottom padding, because its content runs to the bottom edge
+   * and pads itself for the safe area. `popover` is call details (`.phone .infop`): the popover surface
+   * with a top border.
+   */
+  readonly variant?: "sheet" | "card" | "popover";
+  /** Where accessibility focus returns when the sheet closes, usually the button that opened it. */
+  readonly returnFocusRef?: RefObject<View | null>;
+  readonly testID?: string;
+};
+
+/** Letting go after dragging the sheet down further than this closes it. */
+const CLOSE_DISTANCE = 80;
+/** Padding under the content: on top of the safe area when the keyboard is down, alone when it's up. */
+const BOTTOM_PADDING = 10;
+const KEYBOARD_PADDING = 12;
+
+type SheetDrag = { readonly drag: SharedValue<number>; readonly close: () => void };
+const SheetDragContext = createContext<SheetDrag | null>(null);
+
+/**
+ * The phone bottom sheet. It runs to the very bottom edge of the screen with the safe area as
+ * padding inside, and only its top corners are rounded. Drag the grabber (or a `SheetDragRegion`)
+ * down to close; the sheet follows the finger on the UI thread. It rides above the keyboard,
+ * Android back closes the top sheet, and accessibility focus moves in and back out.
+ */
+export function BottomSheet({ open, onClose, accessibilityLabel, children, title, heightRatio, inset = 12, variant = "sheet", returnFocusRef, testID }: BottomSheetProps): React.JSX.Element | null {
+  const { colors } = useTheme();
+  const layout = useDeviceLayout();
+  const reduceMotion = useReducedMotion();
+  // Expo 55 apps are edge-to-edge on Android, so the keyboard height already counts from the screen edge.
+  const keyboard = useAnimatedKeyboard();
+  const [mounted, setMounted] = useState(open);
+  const height = useSharedValue(0);
+  const offset = useSharedValue(layout.height);
+  const drag = useSharedValue(0);
+  const shown = useSharedValue(0);
+  const titleRef = useRef<View>(null);
+
+  useBackHandler(open, onClose);
+
+  const show = useCallback(() => {
+    drag.value = 0;
+    if (reduceMotion) {
+      offset.value = 0;
+      shown.value = 1;
+    } else {
+      offset.value = withTiming(0, timings.sheet);
+      shown.value = withTiming(1, timings.scrim);
+    }
+    const node = titleRef.current && findNodeHandle(titleRef.current);
+    if (node) setTimeout(() => AccessibilityInfo.setAccessibilityFocus(node), durations.sheet);
+  }, [drag, offset, reduceMotion, shown]);
+
+  const hide = useCallback(() => {
+    if (reduceMotion) {
+      shown.value = 0;
+      offset.value = height.value || layout.height;
+      setMounted(false);
+      return;
+    }
+    const finish = (finished?: boolean) => {
+      "worklet";
+      if (finished) runOnJS(setMounted)(false);
+    };
+    shown.value = withTiming(0, timings.scrim);
+    offset.value = withTiming(height.value || layout.height, timings.sheet, finish);
+  }, [height, layout.height, offset, reduceMotion, shown]);
+
+  const wasOpen = useRef(open);
+  useEffect(() => {
+    if (open === wasOpen.current) return;
+    wasOpen.current = open;
+    if (!open) return hide();
+    setMounted(true);
+    if (height.value > 0) show();
+  }, [height, hide, open, show]);
+
+  const wasMounted = useRef(mounted);
+  useEffect(() => {
+    const closed = wasMounted.current && !mounted;
+    wasMounted.current = mounted;
+    if (!closed || !returnFocusRef?.current) return;
+    const node = findNodeHandle(returnFocusRef.current);
+    if (node) AccessibilityInfo.setAccessibilityFocus(node);
+  }, [mounted, returnFocusRef]);
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const first = height.value === 0;
+      const measured = event.nativeEvent.layout.height;
+      height.value = measured;
+      if (!first || !open) return;
+      // A JS-thread write reaches the UI thread later, so reading height.value back here would still give 0.
+      offset.value = reduceMotion ? 0 : measured;
+      show();
+    },
+    [height, offset, open, reduceMotion, show],
+  );
+
+  const card = variant === "card";
+  const sheetStyle = useAnimatedStyle(() => {
+    "worklet";
+    return {
+      opacity: reduceMotion ? shown.value : 1,
+      paddingBottom: card ? 0 : keyboard.height.value > 0 ? KEYBOARD_PADDING : layout.insets.bottom + BOTTOM_PADDING,
+      maxHeight: layout.height - layout.insets.top - 8 - keyboard.height.value,
+      transform: [{ translateY: offset.value + drag.value - keyboard.height.value }],
+    };
+  });
+  const scrimStyle = useAnimatedStyle(() => {
+    "worklet";
+    return { opacity: shown.value };
+  });
+
+  const width = layout.arrangement === "pad" ? 440 : layout.arrangement === "landscape" ? 460 : layout.width;
+  const surfaceStyle = [
+    styles.sheet,
+    { backgroundColor: variant === "popover" ? colors.popover : colors.surface, width, left: (layout.width - width) / 2, paddingHorizontal: card ? 0 : inset },
+    card ? { borderTopWidth: 1, borderColor: colors.line } : null,
+    variant === "popover" ? { borderTopWidth: 1, borderColor: colors.lineStrong } : null,
+    heightRatio ? { height: layout.height * heightRatio } : null,
+  ];
+  const surfaceRef = useMeasuredRef<View>(testID, surfaceStyle);
+
+  if (!mounted) return null;
+  return (
+    <Portal layer="sheets">
+      <Animated.View style={[StyleSheet.absoluteFill, { backgroundColor: fixed.scrim }, scrimStyle]}>
+        <Pressable accessible={false} onPress={onClose} style={StyleSheet.absoluteFill} testID={testID ? `${testID}.scrim` : undefined} />
+      </Animated.View>
+      <SheetDragContext.Provider value={{ drag, close: onClose }}>
+        <Animated.View accessibilityLabel={accessibilityLabel} accessibilityViewIsModal onAccessibilityEscape={onClose} onLayout={onLayout} ref={surfaceRef} style={[surfaceStyle, sheetStyle]} testID={testID}>
+          <SheetDragRegion>
+            {/* Without a title, the grabber is where screen-reader focus lands, announced by the sheet's label. */}
+            <View accessibilityLabel={title ? undefined : accessibilityLabel} accessibilityRole={title ? undefined : "header"} accessible={!title} ref={title ? undefined : titleRef} style={card ? styles.cardGrabArea : styles.grabArea} testID={testID ? `${testID}.grabber` : undefined}>
+              <View style={[styles.grabber, { backgroundColor: colors.lineStrong }]} />
+            </View>
+            {title ? (
+              <View accessibilityRole="header" accessible ref={titleRef} style={styles.header}>
+                <ChalkText numberOfLines={1} variant="sheetTitle">
+                  {title}
+                </ChalkText>
+              </View>
+            ) : null}
+          </SheetDragRegion>
+          {children}
+        </Animated.View>
+      </SheetDragContext.Provider>
+    </Portal>
+  );
+}
+
+/** Makes its children a handle that drags the enclosing sheet, like the tab row of People and Chat. */
+export function SheetDragRegion({ children }: { readonly children: ReactNode }): React.JSX.Element {
+  const sheet = useContext(SheetDragContext);
+  if (!sheet) throw new Error("SheetDragRegion must be inside a BottomSheet.");
+  const { drag, close } = sheet;
+  const gesture = Gesture.Pan()
+    .activeOffsetY(4)
+    .onUpdate((event) => {
+      "worklet";
+      const next = Math.max(0, event.translationY);
+      if (next > CLOSE_DISTANCE !== drag.value > CLOSE_DISTANCE) runOnJS(haptics.sheetDetent)();
+      drag.value = next;
+    })
+    .onEnd(() => {
+      "worklet";
+      if (drag.value > CLOSE_DISTANCE) runOnJS(close)();
+      else drag.value = withTiming(0, timings.sheet);
+    });
+  return (
+    <GestureDetector gesture={gesture}>
+      <View collapsable={false}>{children}</View>
+    </GestureDetector>
+  );
+}
+
+const styles = StyleSheet.create({
+  sheet: { position: "absolute", bottom: 0, paddingTop: 8, borderTopLeftRadius: radii.sheet, borderTopRightRadius: radii.sheet },
+  grabArea: { alignItems: "center", paddingTop: 4, paddingBottom: 12 },
+  cardGrabArea: { alignItems: "center" },
+  grabber: { width: 36, height: 5, borderRadius: 3 },
+  header: { flexDirection: "row", alignItems: "center", gap: 12, paddingTop: 4, paddingHorizontal: 8, paddingBottom: 14 },
+});

package/src/primitives/ChalkText.tsx

@@ -0,0 +1,23 @@
+import { Text, type TextProps } from "react-native";
+import { useMeasuredRef } from "../frame/measurement";
+import { useTheme } from "../theme/theme";
+import { type, type Palette, type TypeStyle } from "../theme/tokens";
+
+export type ChalkTextProps = TextProps & {
+  readonly variant?: TypeStyle;
+  readonly tone?: keyof Palette;
+  /** A fixed colour for text on video or on a fixed overlay; wins over `tone`. */
+  readonly color?: string;
+  /** Tabular figures, so timers and counts don't jitter. */
+  readonly tabular?: boolean;
+};
+
+/** Figtree text in one of the call's type styles. */
+export function ChalkText({ variant = "body", tone = "text", color, tabular = false, style, ...rest }: ChalkTextProps): React.JSX.Element {
+  const { colors } = useTheme();
+  const textStyle = [type[variant], { color: color ?? colors[tone] }, tabular ? TABULAR : null, style];
+  const ref = useMeasuredRef<Text>(rest.testID, textStyle);
+  return <Text {...rest} ref={ref} style={textStyle} />;
+}
+
+const TABULAR = { fontVariant: ["tabular-nums" as const] };