orn-ui 0.2.9 → 0.3.0

package/src/organisms/Alert.tsx

@@ -1,7 +1,8 @@
 import React, { memo } from 'react';
-import { Modal, Text, TouchableWithoutFeedback, View } from 'react-native';
+import { Text, TouchableWithoutFeedback, View } from 'react-native';
+import { NativeOverlay } from '../theme/NativeOverlay';
 import { createStyles } from '../theme/createStyles';
-import { useAllowFontScaling, useColors, useLabels } from '../theme/UIProvider';
+import { useAllowFontScaling, useColors, useLabels, useTheme } from '../theme/UIProvider';
 import { Button, type ButtonVariant } from '../atoms/Button';
 import { Icon } from '../icons/Icon';
 import type { IconName } from '../icons/types';
@@ -9,23 +10,40 @@ import type { IconName } from '../icons/types';
 export type AlertType = 'success' | 'error' | 'warning' | 'info' | 'question';
 
 export interface AlertButton {
+  /** Button label. */
   text: string;
+  /** Called on press; without it the button calls `onClose`. */
   onPress?: () => void;
+  /** 'cancel' renders outline, 'destructive' renders in the error color. */
   style?: 'cancel' | 'default' | 'destructive';
+  /** Explicit Button variant; wins over `style`. */
   variant?: ButtonVariant;
 }
 
 export interface AlertProps {
+  /** Shows or hides the dialog. */
   visible: boolean;
+  /** Short heading; screen readers announce it as a header. */
   title: string;
+  /** Optional explanation under the title. */
   message?: string;
+  /** Icon and color of the dialog. @default 'info' */
   type?: AlertType;
+  /** Tap on the backdrop, Android back, VoiceOver escape. Without it the backdrop does nothing. */
   onClose?: () => void;
+  /** Custom buttons; three or more stack vertically. */
   buttons?: AlertButton[];
+  /** Shorthand: label of the confirm button. @default labels.confirm */
   confirmText?: string;
+  /** Shorthand: label of the cancel button (shown with `onCancel` or `cancelText`). @default labels.cancel */
   cancelText?: string;
+  /** Shorthand: confirm action. */
   onConfirm?: () => void;
+  /** Shorthand: cancel action (falls back to `onClose`). */
   onCancel?: () => void;
+  /** The confirm button uses the destructive color (delete, discard). @default false */
+  destructive?: boolean;
+  /** Draws the dialog inside its parent instead of over the screen (docs, previews). @default false */
   inline?: boolean;
 }
 
@@ -37,31 +55,62 @@ const ICON_BY_TYPE: Record<AlertType, IconName> = {
   info: 'info',
 };
 
+/** Readable line length for a short dialog on tablets too. */
+const DIALOG_MAX_WIDTH = 340;
+const ICON_SIZE = 48;
+/** Above any sibling of the inline host. */
+const INLINE_Z = 9999;
+
 const useStyles = createStyles((theme) => ({
-  overlay: { flex: 1, backgroundColor: theme.colors.overlay, justifyContent: 'center', alignItems: 'center', padding: theme.tokens.spacing.xl },
-  overlayInline: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, zIndex: 9999 },
+  overlay: {
+    flex: 1,
+    backgroundColor: theme.colors.overlay,
+    justifyContent: 'center',
+    alignItems: 'center',
+    padding: theme.tokens.spacing.xl,
+  },
+  fill: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 },
+  overlayInline: { zIndex: INLINE_Z },
   container: {
-    backgroundColor: theme.colors.surface,
+    // Raised: in dark mode the plain surface sank into the dimmed backdrop.
+    backgroundColor: theme.colors.surfaceRaised,
     borderRadius: theme.tokens.radius.xl,
     padding: theme.tokens.spacing.xl,
     width: '100%',
-    maxWidth: 340,
+    maxWidth: DIALOG_MAX_WIDTH,
     alignItems: 'center',
     ...theme.tokens.shadow.md,
   },
-  iconContainer: { marginBottom: theme.tokens.spacing.lg - 1 },
-  title: { fontSize: theme.tokens.fontSize.xl, fontWeight: theme.tokens.fontWeight.bold, color: theme.colors.text, textAlign: 'center', marginBottom: theme.tokens.spacing.md - 2 },
-  message: { fontSize: theme.tokens.fontSize.md, color: theme.colors.textLight, textAlign: 'center', marginBottom: theme.tokens.spacing.xl, lineHeight: theme.tokens.lineHeight.md },
-  buttonContainer: { flexDirection: 'row', justifyContent: 'center', gap: theme.tokens.spacing.sm + 2, width: '100%' },
+  iconContainer: { marginBottom: theme.tokens.spacing.lg },
+  title: {
+    fontSize: theme.tokens.fontSize.xl,
+    lineHeight: theme.tokens.lineHeight.lg,
+    fontWeight: theme.tokens.fontWeight.bold,
+    color: theme.colors.text,
+    textAlign: 'center',
+    marginBottom: theme.tokens.spacing.sm,
+  },
+  message: {
+    fontSize: theme.tokens.fontSize.md,
+    lineHeight: theme.tokens.lineHeight.md,
+    color: theme.colors.textLight,
+    textAlign: 'center',
+  },
+  buttonContainer: {
+    flexDirection: 'row',
+    justifyContent: 'center',
+    gap: theme.tokens.spacing.sm,
+    width: '100%',
+    marginTop: theme.tokens.spacing.xl,
+  },
   buttonContainerVertical: { flexDirection: 'column' },
-  button: { paddingVertical: theme.tokens.spacing.md - 2, paddingHorizontal: theme.tokens.spacing.xl },
   buttonHorizontal: { flex: 1 },
   buttonVertical: { width: '100%' },
 }));
 
-/** Deriva la lista de botones a partir de props, sin mutar `buttons` recibido por props. */
+/** Derives the list of buttons from props, without mutating the `buttons` received through props. */
 function resolveButtons(props: AlertProps, labels: { confirm: string; cancel: string; close: string }): AlertButton[] {
-  const { buttons, confirmText, cancelText, onConfirm, onCancel, onClose } = props;
+  const { buttons, confirmText, cancelText, onConfirm, onCancel, onClose, destructive } = props;
   if (buttons && buttons.length > 0) return buttons;
 
   if (confirmText || onConfirm) {
@@ -69,7 +118,7 @@ function resolveButtons(props: AlertProps, labels: { confirm: string; cancel: st
     if (cancelText || onCancel) {
       list.push({ text: cancelText || labels.cancel, onPress: onCancel || onClose, variant: 'outline', style: 'cancel' });
     }
-    list.push({ text: confirmText || labels.confirm, onPress: onConfirm, variant: 'primary' });
+    list.push({ text: confirmText || labels.confirm, onPress: onConfirm, variant: destructive ? 'destructive' : 'primary' });
     return list;
   }
 
@@ -78,11 +127,21 @@ function resolveButtons(props: AlertProps, labels: { confirm: string; cancel: st
 
 /**
  * Alert
- * Componente declarativo de diálogo. Para uso imperativo (mostrar desde
- * un handler sin levantar estado propio), usar AlertProvider + useAlert().
+ * Declarative dialog component. For imperative use (showing it from a
+ * handler without lifting your own state), use AlertProvider + useAlert().
+ *
+ * Gestalt, figure-ground: the overlay dims everything behind, so the dialog
+ * is the only figure. Proximity: icon, title and message sit together and the
+ * buttons a larger step below, as the answer block. Von Restorff: only the
+ * main action is filled (or red when `destructive`); cancel is outline.
+ * Hick: two buttons side by side; three or more stack so each reads alone.
+ *
+ * Accessibility: the title is a header, the dialog is modal for VoiceOver and
+ * the escape gesture (two-finger Z) calls `onClose`.
  */
 export const Alert = memo((props: AlertProps) => {
   const { visible, title, message, type = 'info', onClose, inline = false } = props;
+  const theme = useTheme();
   const colors = useColors();
   const styles = useStyles();
   const labels = useLabels();
@@ -91,7 +150,7 @@ export const Alert = memo((props: AlertProps) => {
   if (!visible) return null;
 
   const iconColor: Record<AlertType, string> = {
-    // Íconos sobre la superficie del diálogo: rol `*Text`, no el acento pleno.
+    // Icons over the dialog's surface: `*Text` role, not the full accent.
     success: colors.successText,
     error: colors.errorText,
     warning: colors.warningText,
@@ -104,14 +163,19 @@ export const Alert = memo((props: AlertProps) => {
 
   const content = (
     <TouchableWithoutFeedback onPress={onClose} accessibilityRole="none">
-      <View style={[styles.overlay, inline && styles.overlayInline]}>
+      <View style={[styles.overlay, inline && [styles.fill, styles.overlayInline]]}>
         <TouchableWithoutFeedback>
-          <View style={styles.container} accessibilityRole="alert" accessibilityViewIsModal>
+          <View
+            style={styles.container}
+            accessibilityRole="alert"
+            accessibilityViewIsModal
+            onAccessibilityEscape={onClose}
+          >
             <View style={styles.iconContainer}>
-              <Icon name={ICON_BY_TYPE[type]} size={48} color={iconColor[type]} />
+              <Icon name={ICON_BY_TYPE[type]} size={ICON_SIZE} color={iconColor[type]} />
             </View>
 
-            <Text allowFontScaling={allowFontScaling} style={styles.title}>
+            <Text allowFontScaling={allowFontScaling} style={styles.title} accessibilityRole="header">
               {title}
             </Text>
 
@@ -134,8 +198,8 @@ export const Alert = memo((props: AlertProps) => {
                     title={btn.text}
                     onPress={btn.onPress || onClose || (() => {})}
                     variant={variant}
-                    style={[styles.button, vertical ? styles.buttonVertical : styles.buttonHorizontal]}
-                    textStyle={{ fontSize: 14 }}
+                    style={vertical ? styles.buttonVertical : styles.buttonHorizontal}
+                    textStyle={{ fontSize: theme.tokens.fontSize.md }}
                   />
                 );
               })}
@@ -148,16 +212,23 @@ export const Alert = memo((props: AlertProps) => {
 
   if (inline) {
     return (
-      <View style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }} pointerEvents="box-none">
+      <View style={styles.fill} pointerEvents="box-none">
         {content}
       </View>
     );
   }
 
   return (
-    <Modal transparent visible={visible} animationType="fade" statusBarTranslucent presentationStyle="overFullScreen" onRequestClose={onClose || (() => {})}>
+    <NativeOverlay
+      dialog
+      transparent
+      animationType="fade"
+      statusBarTranslucent
+      presentationStyle="overFullScreen"
+      onRequestClose={onClose || (() => {})}
+    >
       {content}
-    </Modal>
+    </NativeOverlay>
   );
 });
 Alert.displayName = 'Alert';

package/src/organisms/AlertProvider.tsx

@@ -11,14 +11,14 @@ export interface AlertOptions {
 }
 
 export interface ConfirmOptions extends AlertOptions {
-  /** Botón de confirmar en rojo/destructivo (para "eliminar", etc). */
+  /** Shows the confirm button as destructive/red (for "delete", etc.). */
   destructive?: boolean;
 }
 
 interface AlertContextValue {
-  /** Muestra un alert de un solo botón. Resuelve cuando se cierra. */
+  /** Shows a single-button alert. Resolves when it closes. */
   alert: (options: AlertOptions) => Promise<void>;
-  /** Muestra confirmar/cancelar. Resuelve true si se confirmó, false si se canceló. */
+  /** Shows confirm/cancel. Resolves true if confirmed, false if cancelled. */
   confirm: (options: ConfirmOptions) => Promise<boolean>;
   hide: () => void;
 }
@@ -27,15 +27,15 @@ const AlertContext = createContext<AlertContextValue | undefined>(undefined);
 const bridge = createImperativeBridge<AlertContextValue>('AlertProvider');
 
 /**
- * Abre un alert desde fuera del árbol de React —un servicio, un interceptor—
- * sin pasar por el hook. Sin <AlertProvider> montado resuelve de inmediato, así
- * que un `await` nunca queda colgado.
+ * Opens an alert from outside the React tree —a service, an interceptor—
+ * without going through the hook. Without a mounted <AlertProvider> it
+ * resolves immediately, so an `await` never hangs.
  */
 export function showAlert(options: AlertOptions): Promise<void> {
   return bridge.get()?.alert(options) ?? Promise.resolve();
 }
 
-/** Igual que showAlert, pero resuelve true/false. Sin provider, false. */
+/** Same as showAlert, but resolves true/false. Without a provider, false. */
 export function showConfirm(options: ConfirmOptions): Promise<boolean> {
   return bridge.get()?.confirm(options) ?? Promise.resolve(false);
 }
@@ -56,16 +56,16 @@ const HIDDEN: InternalState = { visible: false, title: '', type: 'info', buttons
 
 /**
  * AlertProvider
- * Monta un único <Alert> controlado imperativamente. Colocar una vez cerca
- * de la raíz (dentro de UIProvider). Los handlers async pueden hacer
- * `const ok = await confirm({ title: 'Eliminar', destructive: true })`.
+ * Mounts a single imperatively controlled <Alert>. Place it once near the
+ * root (inside UIProvider). Async handlers can do
+ * `const ok = await confirm({ title: 'Delete', destructive: true })`.
  */
 export function AlertProvider({ children }: { children: React.ReactNode }) {
   const [state, setState] = useState<InternalState>(HIDDEN);
   const resolverRef = useRef<((value: any) => void) | null>(null);
-  // Si alert()/confirm() se llaman de nuevo mientras ya hay uno abierto, el
-  // pedido anterior se resuelve (no se descarta) antes de mostrar el nuevo:
-  // evita que su promise quede colgada para siempre.
+  // If alert()/confirm() are called again while one is already open, the
+  // previous request is resolved (not discarded) before showing the new one:
+  // this keeps its promise from hanging forever.
   const settlePending = useCallback(() => {
     resolverRef.current?.(undefined);
     resolverRef.current = null;

package/src/organisms/BottomSheet.tsx

@@ -1,31 +1,42 @@
 import React, { memo, useEffect, useRef, useState } from 'react';
 import {
   Animated,
-  Dimensions,
   Keyboard,
   KeyboardAvoidingView,
-  Modal,
   PanResponder,
   Platform,
   Pressable,
   ScrollView,
   View,
+  useWindowDimensions,
   type ViewStyle,
 } from 'react-native';
 import { createStyles } from '../theme/createStyles';
-import { useColors, useModalSafeAreaBoundary } from '../theme/UIProvider';
+import { useColors, useLabels, useModalSafeAreaBoundary, useTheme } from '../theme/UIProvider';
+import { useReduceMotion } from '../theme/useReduceMotion';
+import { KeyboardHandled } from '../theme/KeyboardAvoidance';
+import { NativeOverlay } from '../theme/NativeOverlay';
 import { Title } from '../atoms/Text';
 import { IconButton } from '../atoms/IconButton';
 import { Transition } from '../atoms/Transition';
 
-const { height: SCREEN_HEIGHT } = Dimensions.get('window');
-const DISMISS_THRESHOLD = 100;
+/** Drag distance (pt) that closes the sheet on release. */
+const DISMISS_DISTANCE = 100;
+/** Downward release speed that closes it even after a short drag (a flick). */
+const DISMISS_VELOCITY = 0.5;
+const HANDLE_WIDTH = 40;
+const HANDLE_HEIGHT = 5;
+const HANDLE_OPACITY = 0.4;
+const CLOSE_ICON_SIZE = 24;
 
 export type FooterPlacement = 'fixed' | 'scroll' | 'hide-with-keyboard';
 
 export interface BottomSheetProps {
+  /** Shows or hides the sheet (it slides in and out). */
   visible: boolean;
+  /** Called by the backdrop, the close button, the drag and Android back. */
   onClose: () => void;
+  /** Sheet content. */
   children: React.ReactNode;
   /** With a title, the header appears, with its close button. */
   title?: string;
@@ -43,9 +54,14 @@ export interface BottomSheetProps {
   draggable?: boolean;
   /** Fraction of the screen (0-1) or pixels. @default 0.9 */
   maxHeight?: number;
+  /** Accessible name of the close button and backdrop. @default labels.close */
   closeAccessibilityLabel?: string;
+  /** Style of the sheet itself (background, radius). */
   containerStyle?: ViewStyle;
+  /** Style of the content area (padding). */
   contentStyle?: ViewStyle;
+  /** Draws the sheet inside its parent instead of over the screen (docs, previews). @default false */
+  inline?: boolean;
   testID?: string;
 }
 
@@ -53,13 +69,22 @@ const useStyles = createStyles((theme) => ({
   container: { flex: 1, justifyContent: 'flex-end' },
   backdrop: { backgroundColor: theme.colors.overlay },
   sheet: {
-    backgroundColor: theme.colors.surface,
+    // Raised: in dark mode the plain surface sank into the dimmed backdrop.
+    backgroundColor: theme.colors.surfaceRaised,
     borderTopLeftRadius: theme.tokens.radius.xxl,
     borderTopRightRadius: theme.tokens.radius.xxl,
     ...theme.tokens.shadow.lg,
   },
   handleArea: { paddingVertical: theme.tokens.spacing.md, alignItems: 'center' },
-  handle: { width: 40, height: 5, borderRadius: 3, backgroundColor: theme.colors.border },
+  handle: {
+    width: HANDLE_WIDTH,
+    height: HANDLE_HEIGHT,
+    borderRadius: HANDLE_HEIGHT / 2,
+    // textLight, faded: `border` was nearly invisible on a white sheet, and
+    // the handle is the only hint that the sheet can be dragged.
+    backgroundColor: theme.colors.textLight,
+    opacity: HANDLE_OPACITY,
+  },
   header: {
     flexDirection: 'row',
     alignItems: 'center',
@@ -84,10 +109,17 @@ const absoluteFill: ViewStyle = { position: 'absolute', top: 0, left: 0, right:
 
 /**
  * BottomSheet
- * Hoja que entra desde abajo, con arrastre para cerrar (PanResponder, no un
- * gesture-handler externo: la librería es cero dependencias). Header, footer y
- * scroll son opcionales, así que cubre tanto la hoja desnuda como el formulario
- * completo.
+ * Sheet that slides in from the bottom, with drag to close (PanResponder, not
+ * an external gesture-handler: the library is zero-dependency). Header, footer
+ * and scroll are optional, so it covers both the bare sheet and the full
+ * form.
+ *
+ * Gestalt, figure-ground: the backdrop dims the screen, so the sheet is the
+ * only figure. Common region: header, content and footer share one panel;
+ * the footer's top border separates the actions from the content. Continuity:
+ * it slides from the edge it lives on and the drag follows the finger back
+ * down; a short flick closes it too. Fitts: content sits in the thumb zone.
+ * Reduce Motion: it appears and leaves without sliding.
  */
 export const BottomSheet = memo(
   ({
@@ -100,36 +132,50 @@ export const BottomSheet = memo(
     scrollable = true,
     draggable = true,
     maxHeight = 0.9,
-    closeAccessibilityLabel = 'Close',
+    closeAccessibilityLabel,
     containerStyle,
     contentStyle,
+    inline = false,
     testID,
   }: BottomSheetProps) => {
     const styles = useStyles();
     const colors = useColors();
+    const theme = useTheme();
+    const labels = useLabels();
+    const reduceMotion = useReduceMotion();
+    const { height: screenHeight } = useWindowDimensions();
+    const closeLabel = closeAccessibilityLabel ?? labels.close;
+    const { duration } = theme.tokens;
+    // The PanResponder is created once: it reads these through refs.
+    const screenHeightRef = useRef(screenHeight);
+    screenHeightRef.current = screenHeight;
+    const snapBackMs = useRef(duration.fast);
+    snapBackMs.current = reduceMotion ? 0 : duration.fast;
     const ModalSafeAreaBoundary = useModalSafeAreaBoundary();
     const [mounted, setMounted] = useState(visible);
     const [keyboardOpen, setKeyboardOpen] = useState(false);
     const progress = useRef(new Animated.Value(0)).current;
-    // El PanResponder de más abajo se crea una sola vez; leer `onClose`
-    // directo del closure daría siempre el de ese primer render. El ref
-    // refleja la última prop sin importar cuándo se creó la closure.
+    // The PanResponder further down is created only once; reading `onClose`
+    // straight from the closure would always give the one from that first
+    // render. The ref reflects the latest prop no matter when the closure was created.
     const onCloseRef = useRef(onClose);
     onCloseRef.current = onClose;
 
     useEffect(() => {
-      const animation = visible
-        ? Animated.timing(progress, { toValue: 1, duration: 250, useNativeDriver: true })
-        : Animated.timing(progress, { toValue: 0, duration: 200, useNativeDriver: true });
+      const animation = Animated.timing(progress, {
+        toValue: visible ? 1 : 0,
+        duration: reduceMotion ? 0 : visible ? duration.slow : duration.base,
+        useNativeDriver: true,
+      });
       if (visible) setMounted(true);
       animation.start(({ finished }) => {
         if (!visible && finished) setMounted(false);
       });
-      // Si el efecto vuelve a correr (o el componente se desmonta) antes de
-      // que termine, se corta: si no, un `finished` tardío podría llamar
-      // `setMounted` sobre un componente ya desmontado.
+      // If the effect runs again (or the component unmounts) before it
+      // finishes, it is cut short: otherwise, a late `finished` could call
+      // `setMounted` on an already unmounted component.
       return () => animation.stop();
-    }, [visible, progress]);
+    }, [visible, progress, reduceMotion, duration.slow, duration.base]);
 
     useEffect(() => {
       if (footerPlacement !== 'hide-with-keyboard') return;
@@ -146,13 +192,14 @@ export const BottomSheet = memo(
       PanResponder.create({
         onMoveShouldSetPanResponder: (_, gesture) => gesture.dy > 5 && Math.abs(gesture.dy) > Math.abs(gesture.dx),
         onPanResponderMove: (_, gesture) => {
-          if (gesture.dy > 0) progress.setValue(1 - Math.min(gesture.dy, SCREEN_HEIGHT) / SCREEN_HEIGHT);
+          const h = screenHeightRef.current;
+          if (gesture.dy > 0) progress.setValue(1 - Math.min(gesture.dy, h) / h);
         },
         onPanResponderRelease: (_, gesture) => {
-          if (gesture.dy > DISMISS_THRESHOLD) {
+          if (gesture.dy > DISMISS_DISTANCE || (gesture.dy > 0 && gesture.vy > DISMISS_VELOCITY)) {
             onCloseRef.current();
           } else {
-            Animated.timing(progress, { toValue: 1, duration: 150, useNativeDriver: true }).start();
+            Animated.timing(progress, { toValue: 1, duration: snapBackMs.current, useNativeDriver: true }).start();
           }
         },
       })
@@ -160,8 +207,8 @@ export const BottomSheet = memo(
 
     if (!mounted) return null;
 
-    // Porcentaje y no píxeles: se mide contra el contenedor, que con el teclado
-    // abierto es más bajo, así que la hoja entra siempre entera.
+    // Percentage, not pixels: it is measured against the container, which is
+    // shorter with the keyboard open, so the sheet always fits entirely.
     const resolvedMaxHeight: number | `${number}%` = maxHeight <= 1 ? `${maxHeight * 100}%` : maxHeight;
     const hasHeader = !!title;
 
@@ -190,44 +237,53 @@ export const BottomSheet = memo(
       </View>
     );
 
-    return (
-      <Modal visible transparent animationType="none" statusBarTranslucent onRequestClose={onClose}>
-        {/* La hoja está anclada abajo, así que el teclado la tapa entera: hay
-            que empujarla, no ajustar insets adentro del scroll. Una sola
-            compensación, la del contenedor. */}
+    const tree = (
+        <>
+        {/* The sheet is anchored at the bottom, so the keyboard covers it
+            entirely: it has to be pushed up, not adjusted with insets inside
+            the scroll. A single compensation, the container's. */}
+        <KeyboardHandled>
         <KeyboardAvoidingView
           style={styles.container}
           behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
         >
           <Transition value={progress} preset="fade" style={[absoluteFill, styles.backdrop]}>
-            {/* Con header, el botón de cerrar ya expone la acción: repetir el
-                label acá deja dos elementos con el mismo nombre. */}
+            {/* With a header, the close button already exposes the action:
+                repeating the label here leaves two elements with the same name. */}
             <Pressable
               style={absoluteFill}
               onPress={onClose}
               testID="bottom-sheet-backdrop"
               accessibilityRole={hasHeader ? undefined : 'button'}
-              accessibilityLabel={hasHeader ? undefined : closeAccessibilityLabel}
+              accessibilityLabel={hasHeader ? undefined : closeLabel}
             />
           </Transition>
 
-          {/* Insets medidos dentro de esta ventana nativa (el Modal nativo que
-              usa BottomSheet por debajo), no los de la raíz de la app. */}
+          {/* Insets measured inside this native window (the native Modal
+              BottomSheet uses underneath), not the app root's. */}
           <ModalSafeAreaBoundary>
             {(insets) => (
               <Transition
                 value={progress}
                 preset="slide-up"
-                distance={SCREEN_HEIGHT}
+                distance={screenHeight}
                 testID={testID}
                 style={[
                   styles.sheet,
-                  { maxHeight: resolvedMaxHeight, paddingBottom: Math.max(insets.bottom, 20) },
+                  { maxHeight: resolvedMaxHeight, paddingBottom: Math.max(insets.bottom, theme.tokens.spacing.xl) },
                   containerStyle,
                 ]}
               >
                 {draggable && (
-                  <View style={styles.handleArea} testID="bottom-sheet-handle" {...panResponder.panHandlers}>
+                  // Decorative for screen readers: closing is already exposed by the
+                  // close button (with a title) or by the backdrop (without one).
+                  <View
+                    style={styles.handleArea}
+                    testID="bottom-sheet-handle"
+                    accessibilityElementsHidden
+                    importantForAccessibility="no-hide-descendants"
+                    {...panResponder.panHandlers}
+                  >
                     <View style={styles.handle} />
                   </View>
                 )}
@@ -239,10 +295,10 @@ export const BottomSheet = memo(
                     </Title>
                     <IconButton
                       iconName="close"
-                      size={24}
+                      size={CLOSE_ICON_SIZE}
                       color={colors.text}
                       onPress={onClose}
-                      accessibilityLabel={closeAccessibilityLabel}
+                      accessibilityLabel={closeLabel}
                     />
                   </View>
                 )}
@@ -254,7 +310,23 @@ export const BottomSheet = memo(
             )}
           </ModalSafeAreaBoundary>
         </KeyboardAvoidingView>
-      </Modal>
+        </KeyboardHandled>
+        </>
+    );
+
+    if (inline) {
+      return (
+        <View style={absoluteFill} pointerEvents="box-none">
+          {tree}
+        </View>
+      );
+    }
+
+    return (
+      // closing: while the exit animation plays, no other overlay layers into it.
+      <NativeOverlay closing={!visible} transparent animationType="none" statusBarTranslucent onRequestClose={onClose}>
+        {tree}
+      </NativeOverlay>
     );
   }
 );