orn-ui 0.2.9 → 0.3.0

package/src/organisms/OptionWheel.tsx

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useMemo, useRef } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, type ComponentRef } from 'react';
 import {
   Animated,
   ScrollView,
@@ -24,8 +24,11 @@ export interface OptionWheelOption<T> {
 export type OptionWheelVariant = 'window' | 'spotlight';
 
 export interface OptionWheelProps<T> {
+  /** The range, in order. Each option has a label, its value, and may be disabled. */
   options: OptionWheelOption<T>[];
+  /** Value of the option in the centre row (controlled). */
   selectedValue: T | undefined;
+  /** Called with the value of the option the wheel settles on. */
   onSelect: (value: T) => void;
   /** Title above the wheel. */
   label?: string;
@@ -64,26 +67,27 @@ export interface OptionWheelProps<T> {
   curveRadius?: number;
   /** Which side the wheel's centre is on. @default 'left' */
   curveFrom?: 'left' | 'right';
+  /** Dims the wheel and stops it from turning. @default false */
   disabled?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }
 
 const DEFAULT_VISIBLE_COUNT = 5;
-/** 44pt: el mínimo táctil de iOS, y alcanza para una línea `lg` con aire. */
+/** 44pt: iOS's touch minimum, and enough for an `lg` line with room to spare. */
 const DEFAULT_ITEM_HEIGHT = 44;
 /**
- * Filas hacia cada lado que la interpolación distingue; más lejos, todas
- * iguales (`extrapolate: 'clamp'`). Los tres rangos son simétricos respecto
- * del centro: la fila de arriba y la de abajo se ven igual, sólo que la de
- * arriba se inclina hacia atrás y la de abajo hacia adelante.
+ * Rows toward each side that the interpolation distinguishes; further out,
+ * all the same (`extrapolate: 'clamp'`). The three ranges are symmetric
+ * around the center: the row above and the row below look the same, except
+ * the one above tilts backward and the one below forward.
  */
 const FALLOFF = 2;
 
 /**
- * Cada variante es un juego de rangos. 'spotlight' cae mucho más rápido y se
- * inclina más porque no tiene banda que señale el centro: todo el trabajo de
- * decir cuál está elegida lo hacen el contraste y la nitidez.
+ * Each variant is a set of ranges. 'spotlight' falls off much faster and
+ * tilts more because it has no band marking the center: all the work of
+ * saying which one is selected is done by contrast and sharpness.
  */
 const RANGES: Record<OptionWheelVariant, { opacity: number[]; scale: number[]; rotation: string[] }> = {
   window: {
@@ -99,28 +103,28 @@ const RANGES: Record<OptionWheelVariant, { opacity: number[]; scale: number[]; r
 };
 
 /**
- * React Native no tiene desenfoque sin dependencia nativa, así que en
- * 'spotlight' cada fila que no está en el centro se dibuja además dos veces
- * corrida y a media tinta. La superposición emborrona el trazo: no es un blur
- * gaussiano, pero a ese tamaño y con esa opacidad lee igual, y sigue siendo
- * `opacity` y `transform` sobre el mismo scroll, o sea el hilo nativo.
+ * React Native has no blur without a native dependency, so in 'spotlight'
+ * each row that isn't in the center is also drawn twice, offset and at half
+ * ink. The overlap smears the stroke: it isn't a gaussian blur, but at that
+ * size and opacity it reads the same, and it is still `opacity` and
+ * `transform` over the same scroll, i.e. the native thread.
  */
 /**
- * Dónde cae cada punto del `inputRange` sobre el arco. `Animated` no sabe
- * calcular raíces ni arcosenos, pero no hace falta: las cinco distancias al
- * centro son fijas por fila, así que la flecha del arco y el ángulo de la
- * tangente se resuelven una vez acá y entran como `outputRange`.
+ * Where each point of the `inputRange` falls on the arc. `Animated` can't
+ * compute roots or arcsines, but it doesn't need to: the five distances to
+ * the center are fixed per row, so the arc's sagitta and the tangent's angle
+ * are resolved once here and go in as `outputRange`.
  */
 function arcOffsets(radius: number, itemHeight: number, sign: number) {
   const shift: number[] = [];
   const angle: string[] = [];
   for (let step = -FALLOFF; step <= FALLOFF; step += 1) {
-    // Más allá del radio la fila ya dio la vuelta: se corta ahí en vez de
-    // sacarle la raíz a un negativo.
+    // Beyond the radius the row has already turned over: cut it off there
+    // instead of taking the root of a negative.
     const dy = Math.min(Math.abs(step * itemHeight), radius);
-    // Flecha del arco: cuánto se mete la fila hacia el centro de la rueda.
+    // Arc sagitta: how far the row moves in toward the center of the wheel.
     shift.push(sign * (radius - Math.sqrt(radius * radius - dy * dy)));
-    // La tangente del arco, para que la fila siga la curva en vez de cruzarla.
+    // The arc's tangent, so the row follows the curve instead of crossing it.
     const degrees = Math.asin(dy / radius) * (180 / Math.PI);
     angle.push(`${-sign * Math.sign(step) * degrees}deg`);
   }
@@ -140,7 +144,7 @@ const useStyles = createStyles((theme) => ({
   },
   viewport: { overflow: 'hidden' },
   disabled: { opacity: 0.5 },
-  // La ventana central: figura contra el fondo de opciones que pasan.
+  // The center window: figure against the ground of options passing by.
   window: {
     position: 'absolute',
     left: 0,
@@ -166,7 +170,7 @@ const useStyles = createStyles((theme) => ({
   unit: { fontSize: theme.tokens.fontSize.sm, color: theme.colors.textLight },
 }));
 
-/** El índice habilitado más cercano a `index`, o -1 si no hay ninguno. */
+/** The enabled index closest to `index`, or -1 if there is none. */
 function nearestEnabled<T>(options: OptionWheelOption<T>[], index: number): number {
   if (options.length === 0) return -1;
   for (let step = 0; step < options.length; step += 1) {
@@ -180,25 +184,25 @@ function nearestEnabled<T>(options: OptionWheelOption<T>[], index: number): numb
 
 /**
  * OptionWheel
- * Selector de rueda: las opciones pasan por una ventana fija y la que queda en
- * el centro es la elegida. El scroll hace snap a la altura de fila, así que
- * soltar el dedo en cualquier lado siempre deja una opción centrada y no media.
+ * Wheel picker: the options pass through a fixed window and the one left in
+ * the center is the selected one. The scroll snaps to the row height, so
+ * lifting the finger anywhere always leaves one option centered, never half.
  *
- * Gestalt, figura y fondo: lo que marca la selección no es un estilo sobre la
- * fila —que viajaría con ella— sino una ventana quieta encima de la lista. La
- * figura se queda, el fondo se mueve, y por eso la rueda se lee sin leer: el
- * lugar señala, no el color. Y destino común: todas las filas se achican y se
- * inclinan con la misma ley respecto del centro, de modo que se perciben como
- * una superficie rígida que gira y no como N filas animándose por su cuenta.
+ * Gestalt, figure and ground: what marks the selection isn't a style on the
+ * row —which would travel with it— but a still window on top of the list. The
+ * figure stays, the ground moves, and that is why the wheel reads without
+ * reading: the place signals, not the color. And common fate: all rows shrink
+ * and tilt by the same law relative to the center, so they are perceived as a
+ * rigid surface that turns and not as N rows animating on their own.
  *
- * La escala, la opacidad y la inclinación salen de interpolar el
- * `contentOffset` del scroll, no del estado de React: se calculan en el hilo
- * nativo (`useNativeDriver`) y el hilo de JS sólo participa cuando la rueda ya
- * frenó, para avisar qué quedó elegido. Con "reducir movimiento" activo se
- * apaga la inclinación y queda el tamaño, que es información, no decoración.
+ * Scale, opacity and tilt come from interpolating the scroll's
+ * `contentOffset`, not from React state: they are computed on the native
+ * thread (`useNativeDriver`) and the JS thread only takes part once the wheel
+ * has stopped, to report what was selected. With "reduce motion" on, the tilt
+ * is turned off and the size stays, since it is information, not decoration.
  *
- * `disabled` en una opción no puede impedir que el snap la centre, así que la
- * rueda la centra y se corre sola a la habilitada más cercana.
+ * `disabled` on an option can't keep the snap from centering it, so the
+ * wheel centers it and moves on its own to the nearest enabled one.
  */
 export function OptionWheel<T extends string | number>({
   options,
@@ -223,14 +227,14 @@ export function OptionWheel<T extends string | number>({
   const allowFontScaling = useAllowFontScaling();
   const reduceMotion = useReduceMotion();
 
-  const scrollRef = useRef<ScrollView>(null);
+  const scrollRef = useRef<ComponentRef<typeof ScrollView>>(null);
   const scrollY = useRef(new Animated.Value(0)).current;
-  // El primer posicionamiento no se anima: la rueda tiene que aparecer ya
-  // puesta en su valor, no viajando hasta él.
+  // The first positioning isn't animated: the wheel has to appear already
+  // set at its value, not traveling to it.
   const settled = useRef(false);
 
-  // Impar siempre: con un número par no hay fila central que alinear con la
-  // ventana, y el snap dejaría la selección entre dos filas.
+  // Always odd: with an even number there is no center row to line up with
+  // the window, and the snap would leave the selection between two rows.
   const rows = visibleCount % 2 === 0 ? visibleCount + 1 : visibleCount;
   const padding = ((rows - 1) / 2) * itemHeight;
   const height = rows * itemHeight;
@@ -244,11 +248,11 @@ export function OptionWheel<T extends string | number>({
     (index: number, animated: boolean) => {
       const y = index * itemHeight;
       scrollRef.current?.scrollTo({ y, animated });
-      // `scrollY` sólo lo alimenta `onScroll`, y un salto sin animar no
-      // siempre lo emite: sin esto el valor se queda en 0, la interpolación
-      // cree que la fila centrada es la primera y apaga la que de verdad está
-      // en la ventana. El scroll animado sí emite en todo el recorrido, así
-      // que ahí forzarlo pelearía con la animación.
+      // `scrollY` is only fed by `onScroll`, and an unanimated jump doesn't
+      // always emit it: without this the value stays at 0, the interpolation
+      // thinks the centered row is the first one and dims the one that is
+      // really in the window. The animated scroll does emit along the whole
+      // path, so forcing it there would fight the animation.
       if (!animated) scrollY.setValue(y);
     },
     [itemHeight, scrollY]
@@ -261,10 +265,10 @@ export function OptionWheel<T extends string | number>({
   }, [selectedIndex, scrollToIndex, reduceMotion]);
 
   /**
-   * Corre tanto al final del arrastre como al final de la inercia: en Android
-   * un arrastre corto sin impulso no dispara `onMomentumScrollEnd`, y la rueda
-   * se quedaría con la selección vieja. Reentrar con el mismo índice es inocuo
-   * porque sólo avisa cuando cambia.
+   * Runs both at the end of the drag and at the end of momentum: on Android
+   * a short drag with no momentum doesn't fire `onMomentumScrollEnd`, and the
+   * wheel would keep the old selection. Re-entering with the same index is
+   * harmless because it only reports when it changes.
    */
   const commit = useCallback(
     (event: NativeSyntheticEvent<NativeScrollEvent>) => {
@@ -274,8 +278,8 @@ export function OptionWheel<T extends string | number>({
       if (!landed) return;
       const target = landed.disabled ? nearestEnabled(options, clamped) : clamped;
       const option = options[target];
-      // Sin opciones habilitadas no hay dónde parar: la rueda se queda donde
-      // la dejaron y no avisa nada.
+      // With no enabled options there is nowhere to stop: the wheel stays where
+      // it was left and reports nothing.
       if (!option) return;
       if (target !== clamped) scrollToIndex(target, true);
       if (option.value !== selectedValue) onSelect(option.value);
@@ -283,13 +287,13 @@ export function OptionWheel<T extends string | number>({
     [options, itemHeight, selectedValue, onSelect, scrollToIndex]
   );
 
-  /** VoiceOver/TalkBack recorren la rueda con increment/decrement, no con el dedo. */
+  /** VoiceOver/TalkBack go through the wheel with increment/decrement, not the finger. */
   const step = useCallback(
     (delta: number) => {
       if (disabled || selectedIndex < 0) return;
       const next = nearestEnabled(options, selectedIndex + delta);
       const option = options[next];
-      // En el borde, `nearestEnabled` devuelve la fila donde ya estamos.
+      // At the edge, `nearestEnabled` returns the row we are already on.
       if (!option || next === selectedIndex) return;
       onSelect(option.value);
     },
@@ -305,9 +309,9 @@ export function OptionWheel<T extends string | number>({
 
   const selected = selectedIndex >= 0 ? options[selectedIndex] : undefined;
   const ranges = RANGES[variant];
-  // El desenfoque simulado triplica los nodos de texto: sólo va donde aporta,
-  // y con "reducir movimiento" no va, porque ahí la nitidez es lo único que
-  // queda para distinguir la fila elegida.
+  // The simulated blur triples the text nodes: it only goes where it helps,
+  // and not with "reduce motion", because there sharpness is the only thing
+  // left to tell the selected row apart.
   const smeared = variant === 'spotlight' && !reduceMotion;
   const arc = useMemo(
     () =>
@@ -379,8 +383,8 @@ export function OptionWheel<T extends string | number>({
               { scale: scrollY.interpolate({ inputRange, outputRange: ranges.scale, extrapolate: 'clamp' }) },
             ];
             if (perspective && !reduceMotion) {
-              // El perspective va primero: aplicado después de la rotación no
-              // deforma nada y la fila se ve plana aunque esté rotada.
+              // perspective goes first: applied after the rotation it doesn't
+              // distort anything and the row looks flat even though it's rotated.
               transform.unshift({ perspective: height * 2 });
               transform.push({
                 rotateX: scrollY.interpolate({ inputRange, outputRange: ranges.rotation, extrapolate: 'clamp' }),
@@ -425,9 +429,9 @@ export function OptionWheel<T extends string | number>({
                     <Animated.View
                       key={direction}
                       pointerEvents="none"
-                      // `accessibilityElementsHidden` no alcanza: el lector
-                      // leería la fila tres veces igual, porque la rueda entera
-                      // ya es un solo elemento y esto vive adentro.
+                      // `accessibilityElementsHidden` isn't enough: the reader
+                      // would read the row three times over, because the whole
+                      // wheel is already a single element and this lives inside it.
                       style={[
                         styles.ghost,
                         {

package/src/organisms/ReorderableList.tsx

@@ -1,12 +1,16 @@
 import React, { useRef, useState } from 'react';
 import { Animated, PanResponder, View, type StyleProp, type ViewStyle } from 'react-native';
 import { createStyles } from '../theme/createStyles';
+import { useLabels } from '../theme/UIProvider';
 
 export interface ReorderableListProps<T> {
+  /** Items, in their current order. */
   data: T[];
+  /** Stable key per item. */
   keyExtractor: (item: T, index: number) => string;
   /** Fixed height of each row: needed to calculate the target index without measuring layout async. */
   itemHeight: number;
+  /** Renders each row; the third argument is true while that row is being dragged. */
   renderItem: (item: T, index: number, dragging: boolean) => React.ReactElement;
   /** Called on release, with the array already reordered. Does not mutate `data`. */
   onReorder: (data: T[]) => void;
@@ -19,11 +23,12 @@ export interface ReorderableListProps<T> {
   onDragStart?: (index: number) => void;
   /** Ends the drag — on release or cancellation. Always runs if `onDragStart` ran. */
   onDragEnd?: () => void;
+  /** Turns off dragging. @default false */
   disabled?: boolean;
   style?: StyleProp<ViewStyle>;
 }
 
-/** Reordena moviendo el ítem de `from` a `to`, sin mutar `data`. Exportada aparte por ser testeable sin simular gestos. */
+/** Reorders by moving the item from `from` to `to`, without mutating `data`. Exported separately so it can be tested without simulating gestures. */
 export function move<T>(data: T[], from: number, to: number): T[] {
   const next = data.slice();
   const [item] = next.splice(from, 1) as [T];
@@ -37,18 +42,23 @@ const useStyles = createStyles(() => ({
 
 /**
  * ReorderableList
- * Ley de destino común (common fate): al arrastrar una fila, las filas que
- * tiene que atravesar se desplazan juntas en el mismo sentido — eso es lo
- * que comunica "van a intercambiar lugar" antes de soltar el dedo, no un
- * simple resaltado del ítem activo.
+ * Law of common fate: when dragging a row, the rows it has to cross shift
+ * together in the same direction — that is what communicates "they are
+ * going to swap places" before the finger lifts, not a simple highlight of
+ * the active item.
  *
- * Sin dependencias de gestos/animación externas (reanimated, gesture-handler):
- * PanResponder + Animated alcanzan porque el cálculo de índice destino
- * necesita el valor de arrastre en JS en cada movimiento (no algo que
- * useNativeDriver pueda resolver solo).
+ * No external gesture/animation dependencies (reanimated, gesture-handler):
+ * PanResponder + Animated are enough because computing the target index
+ * needs the drag value in JS on every move (not something useNativeDriver
+ * can resolve on its own).
  *
- * Dentro de un scroll vertical hay que cablear `onDragStart`/`onDragEnd` a
- * `scrollEnabled`, o en iOS el arrastre no llega a empezar:
+ * Inside a vertical scroll you have to wire `onDragStart`/`onDragEnd` to
+ * `scrollEnabled`, or on iOS the drag never gets to start:
+ *
+ * Screen readers can't drag: each row is one accessible element with two
+ * actions, "Move up" and "Move down" (`labels.moveUp` / `labels.moveDown`),
+ * that call `onReorder` the same way a drop does. The row's content is read
+ * as its label, so keep interactive controls out of reorderable rows.
  *
  * ```tsx
  * const [dragging, setDragging] = useState(false);
@@ -69,24 +79,25 @@ export function ReorderableList<T>({
   style,
 }: ReorderableListProps<T>) {
   const styles = useStyles();
+  const labels = useLabels();
   const [activeIndex, setActiveIndex] = useState<number | null>(null);
   const [targetIndex, setTargetIndex] = useState<number | null>(null);
   const dy = useRef(new Animated.Value(0)).current;
   const activeIndexRef = useRef<number | null>(null);
-  // El PanResponder de cada fila se crea una sola vez (se cachea en el Map de
-  // abajo) y su closure queda fijo al render de esa primera vez: leer
-  // `targetIndex` (state) directamente ahí siempre daría el valor del
-  // montaje. Un ref sí refleja la última escritura sin importar cuándo se
-  // creó la closure que lo lee.
+  // Each row's PanResponder is created only once (cached in the Map below)
+  // and its closure stays fixed to that first render: reading `targetIndex`
+  // (state) directly there would always give the value from mount. A ref
+  // does reflect the latest write no matter when the closure reading it was
+  // created.
   const targetIndexRef = useRef<number | null>(null);
   const dataRef = useRef(data);
   dataRef.current = data;
-  // Igual razón que targetIndexRef: el responder de cada fila se crea una
-  // sola vez, así que leer `disabled` directo del closure congelaría el
-  // valor del momento en que esa fila se creó.
+  // Same reason as targetIndexRef: each row's responder is created only
+  // once, so reading `disabled` straight from the closure would freeze the
+  // value from when that row was created.
   const disabledRef = useRef(disabled);
   disabledRef.current = disabled;
-  // Misma razón: los callbacks se leen desde closures creadas una sola vez.
+  // Same reason: the callbacks are read from closures created only once.
   const onReorderRef = useRef(onReorder);
   onReorderRef.current = onReorder;
   const onDragStartRef = useRef(onDragStart);
@@ -95,8 +106,8 @@ export function ReorderableList<T>({
   onDragEndRef.current = onDragEnd;
 
   const panResponders = useRef(new Map<number, ReturnType<typeof PanResponder.create>>()).current;
-  // Si `data` se achica, los responders de índices que ya no existen quedan
-  // colgados en el Map para siempre: se podan en cada render.
+  // If `data` shrinks, the responders for indexes that no longer exist stay
+  // stuck in the Map forever: they are pruned on every render.
   for (const index of panResponders.keys()) {
     if (index >= data.length) panResponders.delete(index);
   }
@@ -117,9 +128,9 @@ export function ReorderableList<T>({
     responder = PanResponder.create({
       onStartShouldSetPanResponder: () => !disabledRef.current,
       onMoveShouldSetPanResponder: (_, gesture) => !disabledRef.current && Math.abs(gesture.dy) > 2,
-      // Un scroll padre pide el responder apenas su gesto vertical arranca —
-      // el mismo eje que el arrastre. Cederlo cancelaría el drag a mitad de
-      // camino, así que la fila se lo queda hasta soltar.
+      // A parent scroll requests the responder as soon as its vertical gesture
+      // starts — the same axis as the drag. Yielding it would cancel the drag
+      // midway, so the row keeps it until release.
       onPanResponderTerminationRequest: () => false,
       onPanResponderGrant: () => {
         activeIndexRef.current = index;
@@ -155,8 +166,8 @@ export function ReorderableList<T>({
     <View style={style}>
       {data.map((item, index) => {
         const isActive = activeIndex === index;
-        // Filas entre el origen y el destino se corren un lugar entero en el
-        // sentido del arrastre: es el efecto de "grupo que se mueve junto".
+        // Rows between the origin and the target shift one full place in the
+        // drag direction: it is the "group moving together" effect.
         let shift = 0;
         if (activeIndex !== null && targetIndex !== null && !isActive) {
           if (activeIndex < targetIndex && index > activeIndex && index <= targetIndex) shift = -itemHeight;
@@ -173,6 +184,17 @@ export function ReorderableList<T>({
                 : { transform: [{ translateY: shift }] },
             ]}
             {...panResponderFor(index).panHandlers}
+            accessible
+            accessibilityActions={[
+              ...(index > 0 ? [{ name: 'moveUp', label: labels.moveUp }] : []),
+              ...(index < data.length - 1 ? [{ name: 'moveDown', label: labels.moveDown }] : []),
+            ]}
+            onAccessibilityAction={(event) => {
+              if (disabled) return;
+              const to = event.nativeEvent.actionName === 'moveUp' ? index - 1 : index + 1;
+              if (to < 0 || to >= data.length) return;
+              onReorder(move(data, index, to));
+            }}
           >
             {renderItem(item, index, isActive)}
           </Animated.View>

package/src/organisms/Screen.tsx

@@ -1,23 +1,32 @@
 import React, { memo } from 'react';
 import { KeyboardAvoidingView, Platform, ScrollView, View, type ViewStyle } from 'react-native';
 import { createStyles } from '../theme/createStyles';
-import { useInsets } from '../theme/UIProvider';
+import { useInsets, useTheme } from '../theme/UIProvider';
+import { KeyboardHandled, KeyboardPanArea, useKeyboardHost } from '../theme/KeyboardAvoidance';
 
 export type ScreenEdge = 'top' | 'bottom';
 
 export interface ScreenProps {
+  /** Content of the screen. */
   children: React.ReactNode;
+  /**
+   * Fixed bar on top (back button, title, actions). It stays in place while
+   * the content scrolls or moves up for the keyboard. The top safe area goes
+   * above it.
+   */
+  header?: React.ReactNode;
   style?: ViewStyle;
+  /** Wraps the content in a ScrollView. @default true */
   scrollable?: boolean;
+  /** Style of the ScrollView's content container. Only applies when `scrollable`. */
   contentContainerStyle?: ViewStyle;
   /** Which safe area insets to apply. @default ['top', 'bottom'] */
   edges?: ScreenEdge[];
   /**
-   * Compensates for the keyboard: on iOS with scroll the ScrollView itself does it, in
-   * other cases a KeyboardAvoidingView does. Set to false when
-   * the content already brings its own scroller that handles the keyboard (Wizard,
-   * List, SearchList): the two compensations add up and the focused field
-   * ends up pushed off screen.
+   * Keeps the focused Input above the keyboard by moving only the content
+   * (the `header` and a tab bar outside the Screen stay put). On iOS with
+   * scroll, the ScrollView scrolls to it instead. Set to false when the
+   * content brings its own keyboard handling.
    * @default true
    */
   keyboardAvoiding?: boolean;
@@ -27,15 +36,28 @@ const useStyles = createStyles((theme) => ({
   wrapper: { flex: 1, backgroundColor: theme.colors.background },
   container: { flex: 1 },
   contentContainer: { flexGrow: 1 },
+  header: { backgroundColor: theme.colors.background },
 }));
 
 /**
  * Screen
- * Contenedor raíz de pantalla: fondo del theme, safe area (via insets del
- * UIProvider), teclado y scroll opcional resueltos de forma consistente.
+ * Root screen container: theme background, safe area (via the UIProvider's
+ * insets), keyboard and optional scroll handled consistently.
+ *
+ * Keyboard: with the UIProvider handling it (default), Screen shifts only its
+ * content — clipped below the `header` — to keep the focused Input above the
+ * keyboard. The header stays fixed and a tab bar outside the Screen stays
+ * behind the keyboard, as in a native app. On iOS with scroll, the ScrollView
+ * already brings the field into view (automaticallyAdjustKeyboardInsets) and
+ * nothing is added. Without a host (`keyboardAvoidance={false}` on the
+ * provider) the usual KeyboardAvoidingView remains.
+ *
+ * Gestalt, common region: the header shares the screen's background and stays
+ * fixed; only the content moves, so navigation isn't lost.
  */
 export const Screen = memo(({
   children,
+  header,
   style,
   scrollable = true,
   contentContainerStyle,
@@ -44,47 +66,62 @@ export const Screen = memo(({
 }: ScreenProps) => {
   const insets = useInsets();
   const styles = useStyles();
+  const theme = useTheme();
+  const host = useKeyboardHost();
   const applyTop = edges.includes('top');
   const applyBottom = edges.includes('bottom');
+  const topInset = applyTop ? insets.top : 0;
+
+  const scrollHandles = keyboardAvoiding && scrollable && Platform.OS === 'ios';
+  const panArea = keyboardAvoiding && !scrollHandles && !!host;
+  const avoidWithView = keyboardAvoiding && !scrollHandles && !host;
 
-  // En iOS el ScrollView de abajo ya sube el campo enfocado con
-  // automaticallyAdjustKeyboardInsets; envolverlo además en un
-  // KeyboardAvoidingView compensa el teclado dos veces y el input termina
-  // empujado fuera del borde superior. Android no tiene ese prop, así que ahí
-  // el KeyboardAvoidingView sigue siendo el único mecanismo.
-  const avoidWithView = keyboardAvoiding && !(scrollable && Platform.OS === 'ios');
+  // With a header, the top inset goes above the header; the content starts
+  // right below it.
+  const contentTop = header ? 0 : topInset;
+
+  let content = scrollable ? (
+    <ScrollView
+      style={styles.container}
+      automaticallyAdjustKeyboardInsets={scrollHandles}
+      contentContainerStyle={[
+        styles.contentContainer,
+        { paddingTop: contentTop },
+        applyBottom && { paddingBottom: insets.bottom },
+        contentContainerStyle,
+      ]}
+      keyboardShouldPersistTaps="handled"
+    >
+      {scrollHandles ? <KeyboardHandled>{children}</KeyboardHandled> : children}
+    </ScrollView>
+  ) : (
+    <View style={[styles.container, { paddingTop: contentTop, paddingBottom: applyBottom ? insets.bottom : 0 }]}>
+      {children}
+    </View>
+  );
 
-  const KeyboardWrapper: React.ComponentType<any> = avoidWithView ? KeyboardAvoidingView : View;
-  const keyboardProps = avoidWithView
-    ? {
-        behavior: Platform.OS === 'ios' ? ('padding' as const) : ('height' as const),
-        keyboardVerticalOffset: Platform.OS === 'ios' ? 0 : 20,
-      }
-    : {};
+  if (panArea) {
+    content = (
+      <KeyboardPanArea margin={theme.tokens.spacing.md} topLimit={insets.top} clip>
+        {content}
+      </KeyboardPanArea>
+    );
+  } else if (avoidWithView) {
+    content = (
+      <KeyboardAvoidingView
+        style={styles.container}
+        behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
+        keyboardVerticalOffset={Platform.OS === 'ios' ? 0 : theme.tokens.spacing.xl}
+      >
+        {content}
+      </KeyboardAvoidingView>
+    );
+  }
 
   return (
     <View style={[styles.wrapper, style]}>
-      <KeyboardWrapper style={styles.container} {...keyboardProps}>
-        {scrollable ? (
-          <ScrollView
-            style={styles.container}
-            automaticallyAdjustKeyboardInsets
-            contentContainerStyle={[
-              styles.contentContainer,
-              { paddingTop: applyTop ? insets.top : 0 },
-              applyBottom && { paddingBottom: insets.bottom },
-              contentContainerStyle,
-            ]}
-            keyboardShouldPersistTaps="handled"
-          >
-            {children}
-          </ScrollView>
-        ) : (
-          <View style={[styles.container, { paddingTop: applyTop ? insets.top : 0, paddingBottom: applyBottom ? insets.bottom : 0 }]}>
-            {children}
-          </View>
-        )}
-      </KeyboardWrapper>
+      {header && <View style={[styles.header, { paddingTop: topInset }]}>{header}</View>}
+      {content}
     </View>
   );
 });