@appinternalleads/ui 0.2.0

package/src/ds/overlays.tsx

@@ -0,0 +1,418 @@
+import {
+  createContext, useCallback, useContext, useEffect, useMemo, useRef, useState,
+  type ReactNode,
+} from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Box, Icon, Input, MotionView, Pressable, Scroll, Sheet, Text, usePresence, type IconName } from '../core';
+import { blockRadii, gutter, useDs } from '../tokens';
+import { BackButton } from './SubScreenHeader';
+import { ConnectorLogo } from './rows';
+
+/* ── Toast ───────────────────────────────────────────────────────────────── */
+
+const DURATION = 2200;
+/**
+ * **How long a notice (O1) stays: the Building Blocks handoff's 5s.** A string toast keeps
+ * `DURATION` — changing it would change every existing call site, and the handoff's timing is
+ * specified for the titled notice, which is new. HANDOFF-SOLARIUM-BLOCKS §6 records the split.
+ */
+export const NOTICE_MS = 5000;
+
+/**
+ * **O1 · a titled notice.** Success and information only — "never for failures": a failure the
+ * user must act on belongs where the failure happened (a `Callout`), not in a message that leaves
+ * on its own after five seconds.
+ */
+export type ToastNotice = { title: string; body?: string; tone?: 'success' | 'info' };
+
+type ToastApi = { show: (message: string | ToastNotice) => void; dismiss: () => void };
+const ToastContext = createContext<ToastApi | null>(null);
+
+export function ToastProvider({ children }: { children: ReactNode }) {
+  const [message, setMessage] = useState<string | ToastNotice | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const dismiss = useCallback(() => {
+    if (timer.current) clearTimeout(timer.current);
+    setMessage(null);
+  }, []);
+
+  const show = useCallback((next: string | ToastNotice) => {
+    setMessage(next);
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = setTimeout(() => setMessage(null), typeof next === 'string' ? DURATION : NOTICE_MS);
+  }, []);
+
+  useEffect(() => () => (timer.current ? clearTimeout(timer.current) : undefined), []);
+
+  const api = useMemo(() => ({ show, dismiss }), [show, dismiss]);
+  return (
+    <ToastContext.Provider value={api}>
+      {children}
+      {typeof message === 'string' ? <Toast>{message}</Toast> : null}
+      {message && typeof message !== 'string' ? <NoticeToast notice={message} onDismiss={dismiss} /> : null}
+    </ToastContext.Provider>
+  );
+}
+
+/** **A screen outside the provider must not crash over a confirmation message.** */
+export function useToast(): ToastApi {
+  return useContext(ToastContext) ?? { show: () => {}, dismiss: () => {} };
+}
+
+/**
+ * Docked above the tab bar, never over it.
+ *
+ * `bottom` defaults to the lane the tokens reserve: an overlay sitting on a button swallows the
+ * tap, and from the user's side the button simply does not work.
+ */
+export function Toast({ children, bottom = 104 }: { children: string; bottom?: number }) {
+  const { colors } = useDs();
+  return (
+    <Box
+      role="none"
+      style={{ position: 'absolute', left: 16, right: 16, bottom, alignItems: 'center' }}>
+      <Box bg="surface3" lift={3} radius="control" py="s3" px="s4">
+        <Text variant="caption" style={{ color: colors.textPrimary }}>{children}</Text>
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * **O1 · the notice: 210 wide, padding 12, radius 16, `lift-2`; fades in (M10, opacity only).** Title,
+ * optional body, a dismiss button. A `status` region, so it is announced without taking focus —
+ * a notice that stole focus would interrupt exactly the task it is reporting on.
+ */
+export function NoticeToast({
+  notice, onDismiss, bottom = 104,
+}: { notice: ToastNotice; onDismiss: () => void; bottom?: number }) {
+  const { colors, lift2 } = useDs();
+  /* M10 overlay (0.2.0): opacity only — no slide. */
+  const enter = usePresence(true, { distance: 0, appear: true });
+  const ink = notice.tone === 'info' ? colors.reference.fg : colors.status.executed;
+  return (
+    <Box role="status" aria-live="polite" style={{ position: 'absolute', left: 16, right: 16, bottom, alignItems: 'center' }}>
+      <MotionView style={{ opacity: enter.opacity, transform: [{ translateY: enter.translateY }] }}>
+        <Box
+          row
+          gap="s2"
+          p="s3"
+          style={{ width: 210, maxWidth: '100%', borderRadius: blockRadii.major, backgroundColor: colors.surface1, boxShadow: lift2 }}>
+          <Box pt="s1"><Icon name={notice.tone === 'info' ? 'info' : 'check'} size={14} color={ink} /></Box>
+          <Box flex={1} style={{ minWidth: 0 }}>
+            <Text variant="caption" color="textPrimary" style={{ fontWeight: '600' }}>{notice.title}</Text>
+            {notice.body ? <Text variant="caption" color="textSecondary" style={{ fontSize: 12 }}>{notice.body}</Text> : null}
+          </Box>
+          <Pressable onPress={onDismiss} aria-label="Dismiss" width={24} height={24} radius="pill">
+            <Icon name="close" size={12} color={colors.textSecondary} />
+          </Pressable>
+        </Box>
+      </MotionView>
+    </Box>
+  );
+}
+
+/* ── Confirm ─────────────────────────────────────────────────────────────── */
+
+export type ConfirmRequest = {
+  title: string;
+  /** What leaves, whether it comes back, whether anything else is affected. */
+  body: string;
+  /** **The verb is the verb** — Delete, Sign out — never "OK". */
+  verb?: string;
+};
+
+type ConfirmFn = (request: ConfirmRequest) => Promise<boolean>;
+const ConfirmContext = createContext<ConfirmFn | null>(null);
+
+/**
+ * Destructive confirmation, as a promise.
+ *
+ * A `useConfirm()` call reads as a question with an answer — `if (await confirm({…}))` — rather
+ * than as two callbacks wired to a dialog somewhere else, which is what makes the call site
+ * readable at the point the decision is actually made.
+ */
+export function ConfirmProvider({ children }: { children: ReactNode }) {
+  const [request, setRequest] = useState<ConfirmRequest | null>(null);
+  const settleRef = useRef<((ok: boolean) => void) | null>(null);
+
+  const confirm = useCallback<ConfirmFn>(
+    next =>
+      new Promise<boolean>(resolve => {
+        settleRef.current = resolve;
+        setRequest(next);
+      }),
+    [],
+  );
+
+  const settle = (ok: boolean) => {
+    setRequest(null);
+    settleRef.current?.(ok);
+    settleRef.current = null;
+  };
+
+  return (
+    <ConfirmContext.Provider value={confirm}>
+      {children}
+      <Sheet visible={request !== null} onDismiss={() => settle(false)} destructive testID="confirm-sheet">
+        {request ? (
+          <Box gap="s3">
+            <Text variant="heading">{request.title}</Text>
+            <Text variant="caption" color="textSecondary">{request.body}</Text>
+            <Box row gap="s2" justify="flex-end">
+              <Pressable onPress={() => settle(false)} px="s4" py="s3" radius="control" aria-label="Cancel">
+                <Text color="textSecondary">Cancel</Text>
+              </Pressable>
+              <Pressable
+                onPress={() => settle(true)}
+                px="s4"
+                py="s3"
+                radius="control"
+                aria-label={request.verb ?? 'Confirm'}>
+                <Text color="status.error">{request.verb ?? 'Confirm'}</Text>
+              </Pressable>
+            </Box>
+          </Box>
+        ) : null}
+      </Sheet>
+    </ConfirmContext.Provider>
+  );
+}
+
+/** Throws outside a provider — unlike `useToast`, a confirmation that silently resolves is unsafe. */
+export function useConfirm(): ConfirmFn {
+  const ctx = useContext(ConfirmContext);
+  if (!ctx) throw new Error('useConfirm must be used inside <ConfirmProvider>');
+  return ctx;
+}
+
+/* ── HomeSheet ───────────────────────────────────────────────────────────── */
+
+export type SheetRow = {
+  key: string;
+  label: string;
+  icon?: IconName;
+  /** A connector's brand mark (`ConnectorLogo`), drawn instead of `icon` when set — including
+      `null`, which still reserves the tile so a slow-loading logo does not shift the row. */
+  logo?: string | null;
+  meta?: string;
+  chevron?: boolean;
+  /** Reddens the label only. The row keeps its neutral container — an action the user chose is
+      not a failure, and red is for things that failed. */
+  destructive?: boolean;
+  onPress?: () => void;
+};
+
+export interface SheetGroup {
+  /** `YOUR CONNECTORS`, `YOUR SHORTCUTS`. Omitted for an ungrouped list. */
+  label?: string;
+  rows: SheetRow[];
+  /**
+   * **Already filtered by whoever supplied it — leave it alone.**
+   *
+   * The local filter matches a row's own LABEL, which is right for a fixed list of connector
+   * names and wrong for anything the server ranked: a hit for *"latest posts"* is `Get latest
+   * posts` under `hackernews`, and re-filtering by the same string would drop every result whose
+   * label does not literally contain the query.
+   */
+  preFiltered?: boolean;
+}
+
+/**
+ * A bottom sheet with a filterable list.
+ *
+ * **The search field is present only where the list is long enough to need one.** A connector has
+ * sixty-one actions and picking from that by scrolling is not picking; the overflow menu's two
+ * rows get no field, because a filter over two rows is furniture.
+ *
+ * **The query is lifted out** so the sheet can be fed from the server: a purely local filter
+ * matches only the labels it was already handed, so typing narrows what is on screen rather than
+ * what exists.
+ */
+export function HomeSheet({
+  title, slug, search, query, onQueryChange, emptyLabel = 'Nothing matches.',
+  groups, onSelect, onDismiss, visible = true, maxHeightFraction,
+}: {
+  title: string;
+  slug?: string;
+  search?: string;
+  query?: string;
+  onQueryChange?: (q: string) => void;
+  emptyLabel?: string;
+  groups: SheetGroup[];
+  onSelect?: (key: string) => void;
+  onDismiss: () => void;
+  visible?: boolean;
+  /** See `Sheet`'s prop of the same name. Omitted, the panel sizes to its content as before. */
+  maxHeightFraction?: number;
+}) {
+  const empty = groups.every(g => g.rows.length === 0);
+  const { colors } = useDs();
+  return (
+    <Sheet visible={visible} onDismiss={onDismiss} testID="home-sheet" maxHeightFraction={maxHeightFraction}>
+      <Box gap="s1">
+        <Text variant="heading">{title}</Text>
+        {slug ? <Text variant="monoId" mono color="reference">{slug}</Text> : null}
+      </Box>
+
+      {search ? (
+        <Input value={query ?? ''} onChangeText={onQueryChange ?? (() => {})} placeholder={search} />
+      ) : null}
+
+      {empty ? (
+        <Box py="s4"><Text variant="caption" color="textSecondary">{emptyLabel}</Text></Box>
+      ) : (
+        /* `flexShrink: 1` is a no-op on an uncapped sheet (nothing to shrink against) and is what
+           makes a capped one (`maxHeightFraction`) actually scroll its rows inside the panel
+           instead of growing the panel past the cap. */
+        <Scroll gap="s2" style={{ flexShrink: 1 }}>
+          {groups.map((group, gi) => (
+            <Box key={group.label ?? gi} gap="s1">
+              {group.label ? (
+                <Text variant="eyebrow" color="textTertiary" uppercase>{group.label}</Text>
+              ) : null}
+              {group.rows.map(item => (
+                <Pressable
+                  key={item.key}
+                  onPress={item.onPress ?? (() => onSelect?.(item.key))}
+                  row
+                  align="center"
+                  justify="space-between"
+                  py="s3"
+                  px="s3"
+                  radius="row"
+                  aria-label={item.label}
+                  style={{ minHeight: 44 }}>
+                  <Box row align="center" gap="s2" flex={1}>
+                    {item.logo !== undefined ? (
+                      <ConnectorLogo uri={item.logo} size={28} radius={8} />
+                    ) : item.icon ? (
+                      <Icon name={item.icon} size={16} color={colors.textSecondary} />
+                    ) : null}
+                    <Text color={item.destructive ? 'status.error' : 'textPrimary'}>{item.label}</Text>
+                  </Box>
+                  {item.meta ? <Text variant="caption" color="textTertiary">{item.meta}</Text> : null}
+                  {item.chevron ? <Icon name="chev-r" size={14} color={colors.textDisabled} /> : null}
+                </Pressable>
+              ))}
+            </Box>
+          ))}
+        </Scroll>
+      )}
+    </Sheet>
+  );
+}
+
+/* ── Chrome ──────────────────────────────────────────────────────────────── */
+
+/**
+ * A screen header.
+ *
+ * **Whatever goes in `right` is a drawn glyph, never a character** — `⋯` is U+22EF and renders
+ * differently on every platform, which is exactly what an icon exists to prevent.
+ *
+ * The trailing control shares the BACK row rather than the title line, so the iOS large title
+ * still starts at the gutter — which is the whole shape of that title.
+ */
+export function AppHeader({
+  title, sub, back = false, backLabel = 'Back', onBack, right, accent, style,
+}: {
+  title: string;
+  sub?: string;
+  /**
+   * A screen's own hue (14 Sep 2026, app 1's vibrant tab roots): a short bar under the title and the subtitle set in
+   * that ink at 600. Omitted, the header is exactly what it was — the other apps pass nothing.
+   */
+  accent?: string;
+  back?: boolean;
+  backLabel?: string;
+  onBack?: () => void;
+  right?: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}) {
+  const { headings } = useDs();
+  return (
+    /* The platform gutter, not `s5` (20 on both): on Android that put this header's back control 4dp right of every
+       other screen's (measured on a Nothing Phone 3a, 13 Sep 2026). iOS is unchanged — its gutter is 20. */
+    /* A header with a back control starts at the top, as SubScreenHeader does, so Back sits at one height on every
+       pushed screen; a title-only header (a tab root) keeps its breathing room above. */
+    <Box gap="s2" py="s3" style={[{ paddingHorizontal: gutter }, back ? { paddingTop: 0 } : null, style]}>
+      {back || right ? (
+        <Box row align="center" justify="space-between">
+          {/* The shared control (13 Sep 2026), so a header's back matches every other page's. On Android this
+              is now the M3 round arrow rather than a caret and label — in both apps that use this header. */}
+          {back ? <BackButton onPress={onBack ?? (() => {})} label={backLabel} /> : <Box />}
+          {right}
+        </Box>
+      ) : null}
+      <Box gap="s1">
+        {/* 22px `title` for v2; the KeyShort handoff's 32px `screenTitle` when the app asked
+            for it — see `Ds.headings`. The rung is the app's, never a prop a screen sets. */}
+        <Text variant={headings === 'screen' ? 'screenTitle' : 'title'} role="heading">{title}</Text>
+        {accent ? (
+          <Box style={{ width: 28, height: 4, borderRadius: 2, backgroundColor: accent, boxShadow: `0 0 8px ${accent}` }} />
+        ) : null}
+        {sub ? (
+          <Text variant="caption" color="textSecondary" style={accent ? { color: accent, fontWeight: '600' } : undefined}>
+            {sub}
+          </Text>
+        ) : null}
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * The tab bar's own surface: a ground and one top rule.
+ *
+ * A component rather than a style so the bar's material lives in one place; the navigator supplies
+ * the items and this supplies what they sit on.
+ *
+ * **`flex` is what makes it visible at all, and its absence was a real defect.** React Navigation
+ * renders `tabBarBackground()` inside a `<View style={StyleSheet.absoluteFill}>`, so the element
+ * returned here has to fill that box itself. This was `style={{ width: '100%' }}` with no height,
+ * and since the component is normally given no children there was nothing to give it one — so it
+ * measured zero tall and painted nothing. Both apps set `tabBarStyle.backgroundColor` to
+ * transparent on the strength of this drawing the ground, which meant list content scrolled
+ * straight through the tab labels on every root screen. `flex: 1` fills the height; the default
+ * cross-axis stretch fills the width, which is why the explicit `width` is gone rather than kept.
+ *
+ * **`hairline` replaces `lift={2}`, and this is the one place a border beside a lift would have
+ * been wrong to add rather than a lift being wrong to keep.** The ladder is right that a `0 0 0
+ * 1px` ring IS the border and that drawing both is the usual way this material gets implemented
+ * badly. But a lift only says anything on a surface with room around it, and this one is pinned
+ * flush to the bottom of the screen: the ring draws OUTSIDE the box, the box now exactly fills
+ * the bar, and the bar clips it — while both drop shadows point downward, off-screen. Measured on
+ * device: a card on the same frame renders its ring normally (`#EFEEEA` at the edge), and the bar
+ * went page → white with nothing between. So `lift={2}` here was three shadows rendering nothing,
+ * and there is no double edge to worry about because there was never a first one.
+ *
+ * Both design documents say the same thing independently, which is the reason to trust it over
+ * the inference: the KeyShort handoff specifies `border-top: 1px solid` on `--card`, and the
+ * canvas app describes this component as *"on `--card` over a `--line-soft` hairline"*. Neither
+ * mentions a shadow.
+ *
+ * **Settled (A1n, KEYSHORT-REVAMP.md, 11 Sep 2026): `--line-soft` — `hairline`'s default,
+ * unchanged.** They disagree by one token on the rule's colour — KeyShort says `--line`, the
+ * canvas app `--line-soft`. Chasing the citation rather than trusting the paraphrase above
+ * settles it: `design_handoff_ambi_chat_duplex/README.md:53` states the tab bar's rule
+ * explicitly — `border-top: 1px solid var(--line-soft)` — as a primary spec, not an inference
+ * from this component's own behaviour. KeyShort's `--line` is the one document out of step
+ * between the two, and the softer default was already right for the reason given below: a bar
+ * that under-asserts can be strengthened, one that over-asserts has already drawn a line nobody
+ * asked for.
+ */
+export function TabBarChrome({ children }: { children?: ReactNode }) {
+  return (
+    <Box
+      bg="surface2"
+      hairline={{ side: 'top' }}
+      flex={1}
+      row
+      align="center"
+      justify="space-around">
+      {children}
+    </Box>
+  );
+}

package/src/ds/rows.tsx

@@ -0,0 +1,177 @@
+import { useState, type ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Box, Icon, Input, Pressable, RemoteImage, Text, type IconName } from '../core';
+import { cardRadius, isAndroid, useDs, type Kind } from '../tokens';
+import { KindChip } from './Button';
+
+/**
+ * A connector's brand mark.
+ *
+ * **A logo that fails to fetch leaves the tile rather than removing it.** Without the tile the row
+ * would lose its leading column and the name would slide left — a layout that changes shape
+ * depending on whether a CDN answered. The tile is the stable thing; the mark is what varies.
+ *
+ * The service's own artwork is content, not chrome, so it is never recoloured.
+ */
+export function ConnectorLogo({
+  uri, size = 26, radius = 7,
+}: { uri?: string | null; size?: number; radius?: number }) {
+  const [failed, setFailed] = useState(false);
+  const inner = Math.round(size * 0.7);
+  return (
+    <Box
+      width={size}
+      height={size}
+      align="center"
+      justify="center"
+      bg="surfaceSunken"
+      style={{ borderRadius: radius, overflow: 'hidden' }}>
+      {!uri || failed ? null : (
+        <RemoteImage uri={uri} width={inner} height={inner} onError={() => setFailed(true)} />
+      )}
+    </Box>
+  );
+}
+
+/** A raised surface: rows, cards, sheets. Radius and padding are the caller's to add inside. */
+export function Card({
+  children, onPress, style,
+}: { children: ReactNode; onPress?: () => void; style?: StyleProp<ViewStyle> }) {
+  const inner = (
+    <Box bg="surface1" lift={1} p="s4" style={[{ borderRadius: cardRadius }, style]}>
+      {children}
+    </Box>
+  );
+  if (!onPress) return inner;
+  return (
+    <Pressable onPress={onPress} align="stretch" justify="flex-start">
+      {inner}
+    </Pressable>
+  );
+}
+
+export type ListRowProps = {
+  /** Leading glyph. Mutually exclusive with `leading`. */
+  icon?: IconName;
+  /** A third-party mark — its real artwork, never recoloured. Same slot as `icon`. */
+  leading?: ReactNode;
+  title: string;
+  /**
+   * A destructive row keeps the neutral container and reddens only its LABEL — red is for things
+   * that failed, and an action the user chose is not a failure.
+   */
+  titleTone?: 'default' | 'danger';
+  titleLines?: number;
+  /** Triggers are always mono, always lowercase, punctuation included. */
+  mono?: boolean;
+  meta?: ReactNode;
+  trailing?: ReactNode;
+  /** A short status word on the right of the meta line — `Connected`, `Needs auth`. */
+  state?: string;
+  /** A second meta line beneath the first — a description under a trigger. */
+  note?: string;
+  style?: StyleProp<ViewStyle>;
+  /** `center` when the row has no meta line, so a lone title sits against its leading mark. */
+  align?: ViewStyle['alignItems'];
+  onPress?: () => void;
+};
+
+/** One row of a list: a leading slot, a title with optional meta beneath, and a trailing slot. */
+export function ListRow({
+  icon, leading, title, titleTone = 'default', titleLines = 1, mono, meta, trailing,
+  state, note, align = 'center', style, onPress,
+}: ListRowProps) {
+  const { colors } = useDs();
+  const body = (
+    <Box row align={align ?? 'center'} gap="s3" py="s3" px="s4" style={style}>
+      {leading ?? (icon ? <Icon name={icon} size={18} color={colors.textSecondary} /> : null)}
+      <Box flex={1} gap="s1">
+        <Text
+          mono={mono}
+          numberOfLines={titleLines}
+          color={titleTone === 'danger' ? 'status.error' : 'textPrimary'}>
+          {title}
+        </Text>
+        {typeof meta === 'string'
+          ? <Text variant="caption" color="textTertiary" numberOfLines={1}>{meta}</Text>
+          : meta}
+        {note ? <Text variant="caption" color="textSecondary" numberOfLines={2}>{note}</Text> : null}
+        {state ? <Text variant="caption" color="textSecondary">{state}</Text> : null}
+      </Box>
+      {trailing}
+    </Box>
+  );
+  if (!onPress) return body;
+  return <Pressable onPress={onPress} align="stretch" justify="flex-start">{body}</Pressable>;
+}
+
+/**
+ * A shortcut in a list: its trigger in mono, its description beneath, its kind in the leading chip.
+ *
+ * **The trigger is never set in the sans face** — `/omw` in Switzer reads as a filename.
+ *
+ * `flush` drops the card treatment, which is the Android default: M3 lists sit on the page rather
+ * than on their own raised surface.
+ */
+export function ShortcutRow({
+  trigger, description, kind = 'text', leading, trailing, flush = isAndroid, onPress,
+}: {
+  trigger: string;
+  description?: string;
+  kind?: Kind;
+  /** Replaces the kind chip — a step row shows the connector that does the work (its `ConnectorLogo`). */
+  leading?: ReactNode;
+  trailing?: ReactNode;
+  flush?: boolean;
+  onPress?: () => void;
+}) {
+  const body = (
+    <Box row align="center" gap="s3" py="s3" px="s4">
+      {leading ?? <KindChip kind={kind} />}
+      <Box flex={1} gap="s1">
+        {/* A step heavier than its caption (14 Sep 2026, product ask: the trigger and the line under it read bolder). */}
+        <Text variant="monoTrigger" mono numberOfLines={1} style={{ fontWeight: '600' }}>{trigger}</Text>
+        {description ? (
+          <Text variant="caption" color="textSecondary" numberOfLines={1} style={{ fontWeight: '500' }}>{description}</Text>
+        ) : null}
+      </Box>
+      {trailing}
+    </Box>
+  );
+  const inner = flush
+    ? body
+    : <Box bg="surface1" lift={1} style={{ borderRadius: cardRadius }}>{body}</Box>;
+  if (!onPress) return inner;
+  return <Pressable onPress={onPress} align="stretch" justify="flex-start">{inner}</Pressable>;
+}
+
+/**
+ * The search field. **A field is a hole in the paper, so it never lifts** — `Input` owns that,
+ * and this adds only the glyph and the scope-naming placeholder.
+ *
+ * Placeholders name the scope: *"Search shortcuts"*, never just *"Search"*.
+ */
+export function SearchField({
+  placeholder = 'Search', value, onChangeText, autoFocus,
+}: {
+  placeholder?: string;
+  value?: string;
+  onChangeText?: (t: string) => void;
+  /** A screen whose only job is searching should open with the caret already in the field. */
+  autoFocus?: boolean;
+}) {
+  const { colors } = useDs();
+  return (
+    <Box row align="center" gap="s2">
+      <Icon name="search" size={14} color={colors.textTertiary} />
+      <Box flex={1}>
+        <Input
+          value={value ?? ''}
+          onChangeText={onChangeText ?? (() => {})}
+          placeholder={placeholder}
+          autoFocus={autoFocus}
+        />
+      </Box>
+    </Box>
+  );
+}

package/src/ds/screen.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Box, SafeArea, useInsets } from '../core';
+import { layout, useDs } from '../tokens';
+
+/**
+ * The page, as a style — a gradient drifting cool grey-green at the top to warm cream at the
+ * bottom, the way a sheet lit from one side reads.
+ *
+ * **Keep it subtle**: if you can name it as a gradient at arm's length it is too strong. No
+ * imagery, no illustration, no pattern, no texture. The flat stop stays underneath as the
+ * over-scroll colour.
+ */
+export function useSubstrateStyle(): ViewStyle {
+  const { colors, substrate } = useDs();
+  return { backgroundColor: colors.surfacePage, experimental_backgroundImage: substrate };
+}
+
+/** The page background, full-bleed. Never interactive, never scrolls independently. */
+export function Substrate({ children, style }: { children?: ReactNode; style?: StyleProp<ViewStyle> }) {
+  return <Box flex={1} style={[useSubstrateStyle(), style]}>{children}</Box>;
+}
+
+/**
+ * A tab-level screen: the page substrate with the top and side insets claimed.
+ *
+ * **The bottom inset is deliberately left alone** — the tab bar floats over the content, and each
+ * screen pads for it inside its own scroll container.
+ *
+ * `Substrate` wraps the `SafeAreaView` so the gradient is unambiguously full-bleed: the light
+ * source is anchored off-canvas at the top right and should be positioned against the screen
+ * rather than against whatever the insets leave.
+ */
+export function PanelScreen({ children, style }: { children?: ReactNode; style?: StyleProp<ViewStyle> }) {
+  return (
+    <Substrate>
+      <SafeArea>
+        <Box flex={1} style={style}>{children}</Box>
+      </SafeArea>
+    </Substrate>
+  );
+}
+
+/**
+ * **How much room the tab bar actually takes at the bottom of the screen.**
+ *
+ * `layout.tabBarContent` is the bar's own height and nothing else, so every screen that had to
+ * clear it added the rest back by hand — three different numbers for one distance, none of which
+ * knew about the safe-area inset. This is the one expression that knows where the bar ends.
+ *
+ * **Only the three roots have a bar.** A pushed screen must not call this: reserving one where
+ * there is none leaves a bar's height of dead space that reads as a list which failed to fill.
+ *
+ * Screens add their own breathing room ON TOP of this. It is the floor, not the padding.
+ */
+export function useTabBarSpace(): number {
+  const insets = useInsets();
+  /* Mirrors the navigator's own `max(inset, 34)`. Android reports about 11dp for its gesture
+     handle and draws it far taller, so the reported inset alone puts this padding under it. */
+  return layout.tabBarContent + Math.max(insets.bottom, 34);
+}