orn-ui 0.2.10 → 0.3.0

package/src/organisms/Modal.tsx

@@ -1,49 +1,65 @@
 import React, { memo, useEffect, useState } from 'react';
 import {
-  Dimensions,
   KeyboardAvoidingView,
-  Modal as RNModal,
   Platform,
   Pressable,
   ScrollView,
   View,
+  useWindowDimensions,
   type ModalProps as RNModalProps,
   type ViewStyle,
 } from 'react-native';
 import { createStyles } from '../theme/createStyles';
-import { useColors, useModalSafeAreaBoundary } from '../theme/UIProvider';
+import { useLabels, useModalSafeAreaBoundary, useTheme } from '../theme/UIProvider';
+import { NativeOverlay } from '../theme/NativeOverlay';
+import { KeyboardHandled } from '../theme/KeyboardAvoidance';
 import type { EdgeInsets } from '../theme/insets';
 import { Title } from '../atoms/Text';
 import { IconButton } from '../atoms/IconButton';
 import { Transition, type TransitionPreset } from '../atoms/Transition';
 
-const { height: SCREEN_HEIGHT } = Dimensions.get('window');
-
 export type ModalVariant = 'full' | 'overlay' | 'fullScreen';
 
 export interface ModalProps
   extends Pick<RNModalProps, 'statusBarTranslucent' | 'onRequestClose' | 'hardwareAccelerated'> {
+  /** Shows or hides the modal. The animated variants play their exit before unmounting. */
   visible: boolean;
+  /**
+   * Shows the close button in the header and is called by it, by a tap on the backdrop (`overlay`) and
+   * by Android's back button.
+   */
   onClose?: () => void;
+  /** Header title, on a single line. */
   title?: string;
+  /** Accessible name of the close button. @default labels.close */
   closeAccessibilityLabel?: string;
+  /** Body of the modal. */
   children: React.ReactNode;
+  /** Fixed area below the content (e.g. actions); it doesn't scroll. */
   footer?: React.ReactNode;
+  /** Style of the card (`overlay`) or the full-screen wrapper. */
   containerStyle?: ViewStyle;
+  /** Style of the content area (the scroll container when `scrollable`). */
   contentStyle?: ViewStyle;
+  /**
+   * 'full' slides up a full page, 'overlay' a centered card over a dimmed backdrop, 'fullScreen' uses
+   * the native full-screen presentation. @default 'full'
+   */
   variant?: ModalVariant;
+  /** Wraps the content in a ScrollView. @default true */
   scrollable?: boolean;
 }
 
 const useStyles = createStyles((theme) => ({
   flex1: { flex: 1 },
-  fullWrapper: { flex: 1, backgroundColor: theme.colors.background },
-  overlayContainer: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: theme.tokens.spacing.xxl - 4 },
+  fullWrapper: { flex: 1, backgroundColor: theme.colors.surface },
+  overlayContainer: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: theme.tokens.spacing.xl },
   backdrop: { backgroundColor: theme.colors.overlay },
   overlayCard: {
     width: '100%',
     maxHeight: '85%',
-    backgroundColor: theme.colors.surface,
+    // Raised: in dark mode the plain surface sank into the dimmed backdrop.
+    backgroundColor: theme.colors.surfaceRaised,
     borderRadius: theme.tokens.radius.xxl,
     overflow: 'hidden',
     ...theme.tokens.shadow.lg,
@@ -55,11 +71,11 @@ const useStyles = createStyles((theme) => ({
     padding: theme.tokens.spacing.xl,
     borderBottomWidth: 1,
     borderBottomColor: theme.colors.border,
-    backgroundColor: theme.colors.surface,
   },
   title: { fontSize: theme.tokens.fontSize.xl, fontWeight: theme.tokens.fontWeight.bold, flex: 1 },
   closeButton: { marginLeft: theme.tokens.spacing.md },
-  contentWrapper: { flexShrink: 1, backgroundColor: theme.colors.surface },
+  cardInner: { flexShrink: 1 },
+  contentWrapper: { flexShrink: 1 },
   scrollWrapper: { flexShrink: 1 },
   scrollContent: { padding: theme.tokens.spacing.xl, flexGrow: 1 },
   scrollContentFull: { padding: 0, flexGrow: 1 },
@@ -67,22 +83,38 @@ const useStyles = createStyles((theme) => ({
     padding: theme.tokens.spacing.xl,
     borderTopWidth: 1,
     borderTopColor: theme.colors.border,
-    backgroundColor: theme.colors.surface,
   },
 }));
 
+/** Close glyph: the same size BottomSheet uses; IconButton pads it to 44pt. */
+const CLOSE_ICON_SIZE = 24;
+/** How far the `overlay` card drops in while it scales up. */
+const OVERLAY_ENTER_DISTANCE = 40;
+
+
 /**
  * Modal
- * Un solo componente para todos los modales de la app: maneja scroll,
- * teclado, insets y layout según `variant`. Para una hoja desde abajo está
- * BottomSheet, que además trae arrastre para cerrar.
+ * A single component for all of the app's modals: handles scroll, keyboard,
+ * insets and layout according to `variant`. For a sheet from the bottom there
+ * is BottomSheet, which also comes with drag to close.
+ *
+ * Design:
+ * - Figure and ground (Gestalt): `overlay` dims the screen behind a raised
+ *   card, so the task in front is the only figure.
+ * - Common region: header, content and footer share one surface, split by
+ *   hairlines; the footer stays fixed so its actions are always in reach.
+ * - Jakob's law: title on the left, close at the top right, Android back and
+ *   the VoiceOver escape gesture close it, like the system's own sheets.
+ * - Fitts's law: the close button is a 44pt target.
+ * - Screen readers stay inside the modal (`accessibilityViewIsModal`), which
+ *   matters on iOS when it is drawn inside another open overlay.
  */
 export const Modal = memo(
   ({
     visible,
     onClose,
     title,
-    closeAccessibilityLabel = 'Close',
+    closeAccessibilityLabel,
     children,
     footer,
     containerStyle,
@@ -98,8 +130,12 @@ export const Modal = memo(
     const isFullScreen = variant === 'fullScreen';
     const isAnimatedVariant = isOverlay || isFull;
     const ModalSafeAreaBoundary = useModalSafeAreaBoundary();
-    const colors = useColors();
+    const theme = useTheme();
+    const { colors } = theme;
     const styles = useStyles();
+    const labels = useLabels();
+    const closeLabel = closeAccessibilityLabel ?? labels.close;
+    const { height: windowHeight } = useWindowDimensions();
 
     const [mounted, setMounted] = useState(!isAnimatedVariant && visible);
 
@@ -108,10 +144,10 @@ export const Modal = memo(
       else if (visible) setMounted(true);
     }, [visible, isAnimatedVariant]);
 
-    // La tarjeta nunca anima opacity: hacerlo dispara un bug de Android donde
-    // los hijos con elevation parpadean. El fondo semitransparente sí.
+    // The card never animates opacity: doing so triggers an Android bug where
+    // children with elevation flicker. The semi-transparent backdrop does.
     const cardPreset: TransitionPreset[] = isFull ? ['slide-up'] : ['slide-down', 'scale'];
-    const cardDistance = isFull ? SCREEN_HEIGHT : 40;
+    const cardDistance = isFull ? windowHeight : OVERLAY_ENTER_DISTANCE;
 
     const behavior = Platform.OS === 'ios' ? (isFull ? undefined : 'padding') : 'height';
     const keyboardOffset = Platform.OS === 'ios' ? 0 : 20;
@@ -127,7 +163,14 @@ export const Modal = memo(
           )}
           {!title && <View style={styles.flex1} />}
           {!!onClose && (
-            <IconButton iconName="close" size={24} color={colors.text} onPress={onClose} accessibilityLabel={closeAccessibilityLabel} style={styles.closeButton} />
+            <IconButton
+              iconName="close"
+              size={CLOSE_ICON_SIZE}
+              color={colors.text}
+              onPress={onClose}
+              accessibilityLabel={closeLabel}
+              style={styles.closeButton}
+            />
           )}
         </View>
       );
@@ -156,42 +199,17 @@ export const Modal = memo(
 
     const renderFooter = () => (footer ? <View style={styles.footer}>{footer}</View> : null);
 
-    if (!mounted) return null;
-
-    return (
-      <RNModal
-        visible
-        onRequestClose={onRequestClose ?? onClose}
-        animationType={isAnimatedVariant ? 'none' : 'slide'}
-        // `full` anima su propia entrada (translateY) con animationType="none"
-        // y necesita `transparent` para que no se vea un fondo negro detrás
-        // mientras desliza. RN sólo admite `transparent` junto a
-        // 'overFullScreen' — con 'pageSheet' avisa que la combinación no está
-        // soportada. Por eso `full` usa overFullScreen: la presentación nativa
-        // de pageSheet sería redundante con nuestra animación de todos modos.
-        presentationStyle={
-          Platform.OS === 'ios' ? (isFullScreen ? 'fullScreen' : 'overFullScreen') : undefined
-        }
-        transparent={isOverlay || isFull}
-        statusBarTranslucent={statusBarTranslucent}
-        hardwareAccelerated={hardwareAccelerated}
-      >
-        <KeyboardAvoidingView behavior={behavior} keyboardVerticalOffset={keyboardOffset} style={styles.flex1}>
-          {/* Insets medidos dentro de esta ventana nativa del Modal, no los de
-              la raíz de la app — pueden diferir (Android siempre abre una
-              ventana propia; iOS según `presentationStyle`). */}
-          <ModalSafeAreaBoundary>
-            {(insets: EdgeInsets) =>
+    const renderBody = (insets: EdgeInsets) =>
               isOverlay ? (
                 <View style={styles.overlayContainer}>
-                  {/* Sin accessibilityLabel propio: el header ya expone un botón "Close"
-                      accesible; duplicar el label aquí generaría dos elementos con el
-                      mismo nombre para lectores de pantalla. Tocar afuera es un atajo
-                      puramente táctil. */}
+                  {/* No accessibilityLabel of its own: the header already exposes an
+                      accessible "Close" button; duplicating the label here would create
+                      two elements with the same name for screen readers. Tapping
+                      outside is a purely tactile shortcut. */}
                   <Transition
                     visible={visible}
                     preset="fade"
-                    duration={200}
+                    duration={theme.tokens.duration.base}
                     keepMounted
                     style={[{ ...StyleSheetAbsoluteFill }, styles.backdrop]}
                   >
@@ -202,13 +220,15 @@ export const Modal = memo(
                     visible={visible}
                     preset={cardPreset}
                     distance={cardDistance}
-                    duration={250}
+                    duration={theme.tokens.duration.slow}
                     onExited={() => setMounted(false)}
                     style={[styles.overlayCard, containerStyle]}
                   >
-                    {renderHeader()}
-                    {renderMainContent()}
-                    {renderFooter()}
+                    <View style={styles.cardInner} accessibilityViewIsModal onAccessibilityEscape={onClose}>
+                      {renderHeader()}
+                      {renderMainContent()}
+                      {renderFooter()}
+                    </View>
                   </Transition>
                 </View>
               ) : isFull ? (
@@ -216,29 +236,68 @@ export const Modal = memo(
                   visible={visible}
                   preset={cardPreset}
                   distance={cardDistance}
-                  duration={250}
+                  duration={theme.tokens.duration.slow}
                   onExited={() => setMounted(false)}
                   style={[styles.fullWrapper, containerStyle]}
                 >
-                  <View style={[styles.flex1, { paddingTop: insets.top, paddingBottom: insets.bottom }]}>
+                  <View
+                    style={[styles.flex1, { paddingTop: insets.top, paddingBottom: insets.bottom }]}
+                    accessibilityViewIsModal
+                    onAccessibilityEscape={onClose}
+                  >
                     {renderHeader()}
                     {renderMainContent()}
                     {renderFooter()}
                   </View>
                 </Transition>
               ) : (
-                <View style={[styles.fullWrapper, containerStyle]}>
-                  <View style={[styles.flex1, { paddingTop: insets.top, paddingBottom: insets.bottom }]}>
+                <View
+                  style={[styles.fullWrapper, containerStyle]}
+                >
+                  <View
+                    style={[styles.flex1, { paddingTop: insets.top, paddingBottom: insets.bottom }]}
+                    accessibilityViewIsModal
+                    onAccessibilityEscape={onClose}
+                  >
                     {renderHeader()}
                     {renderMainContent()}
                     {renderFooter()}
                   </View>
                 </View>
-              )
-            }
-          </ModalSafeAreaBoundary>
+              );
+
+    if (!mounted) return null;
+
+
+    return (
+      <NativeOverlay
+        // closing: while the exit animation plays, no other overlay layers into it.
+        closing={!visible}
+        onRequestClose={onRequestClose ?? onClose}
+        animationType={isAnimatedVariant ? 'none' : 'slide'}
+        // `full` animates its own entrance (translateY) with animationType="none"
+        // and needs `transparent` so no black background shows behind it
+        // while sliding. RN only allows `transparent` together with
+        // 'overFullScreen' — with 'pageSheet' it warns that the combination
+        // isn't supported. That's why `full` uses overFullScreen: pageSheet's
+        // native presentation would be redundant with our animation anyway.
+        presentationStyle={
+          Platform.OS === 'ios' ? (isFullScreen ? 'fullScreen' : 'overFullScreen') : undefined
+        }
+        transparent={isOverlay || isFull}
+        statusBarTranslucent={statusBarTranslucent}
+        hardwareAccelerated={hardwareAccelerated}
+      >
+        {/* Its own native window: its KeyboardAvoidingView compensates for it, not the root host. */}
+        <KeyboardHandled>
+        <KeyboardAvoidingView behavior={behavior} keyboardVerticalOffset={keyboardOffset} style={styles.flex1}>
+          {/* Insets measured inside this native Modal window, not the app
+              root's — they may differ (Android always opens its own window;
+              iOS depending on `presentationStyle`). */}
+          <ModalSafeAreaBoundary>{renderBody}</ModalSafeAreaBoundary>
         </KeyboardAvoidingView>
-      </RNModal>
+        </KeyboardHandled>
+      </NativeOverlay>
     );
   }
 );

package/src/organisms/NavigationBar.tsx

@@ -1,6 +1,8 @@
 import React, { memo, useEffect, useRef, useState } from 'react';
 import {
   Animated,
+  Keyboard,
+  Platform,
   StyleSheet,
   Text,
   TouchableOpacity,
@@ -11,6 +13,7 @@ import {
 } from 'react-native';
 import { createStyles } from '../theme/createStyles';
 import { useAllowFontScaling, useColors, useInsets, useTheme } from '../theme/UIProvider';
+import { useReduceMotion } from '../theme/useReduceMotion';
 import { Icon } from '../icons/Icon';
 import type { IconName } from '../icons/types';
 
@@ -18,24 +21,40 @@ export interface NavigationBarItem {
   key: string;
   label: string;
   iconName?: IconName;
-  /** Contador sobre el ícono. `true` pinta sólo el punto. */
+  /** Counter over the icon, also read by screen readers. `true` shows only the dot. */
   badge?: number | string | true;
 }
 
 export interface NavigationBarProps {
+  /** The destinations: key, label, and optionally an icon and a badge. */
   items: NavigationBarItem[];
+  /** Key of the selected item (controlled). */
   activeKey: string;
+  /** Called with the key of the pressed item. */
   onChange: (key: string) => void;
   /** Screen edge where the bar lives. @default 'bottom' */
   position?: 'bottom' | 'top';
-  /** @default true */
+  /** Shows the label under each icon. @default true */
   showLabels?: boolean;
   /** Adds the safe area inset for the edge where the bar lives. @default true */
   safeArea?: boolean;
+  /**
+   * Hides a bottom bar while the keyboard is open, like native tab bars, so
+   * it doesn't sit between the field and the keyboard. Only Android needs it:
+   * on iOS the keyboard already covers the bar. @default true
+   */
+  hideOnKeyboard?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }
 
+/** Counter badge: a pill that still fits two digits over a 22pt icon. */
+const BADGE_SIZE = 16;
+const BADGE_DOT_SIZE = 10;
+const BADGE_FONT_SIZE = 10;
+/** Indicator spring: settles fast without bouncing past the tab. */
+const INDICATOR_SPRING = { friction: 9, tension: 90 };
+
 const useStyles = createStyles((theme) => ({
   bar: {
     flexDirection: 'row',
@@ -50,32 +69,32 @@ const useStyles = createStyles((theme) => ({
     position: 'absolute',
     top: theme.tokens.spacing.xs,
     bottom: theme.tokens.spacing.xs,
-    // El indicador se posiciona contra el borde de la barra, no contra su caja
-    // interna: al `left` hay que sumarle el padding horizontal para que quede
-    // centrado sobre la pestaña y no corrido hacia la izquierda.
+    // The indicator is positioned against the bar's edge, not its inner box:
+    // the horizontal padding has to be added to `left` so it sits centered
+    // over the tab and not shifted to the left.
     left: theme.tokens.spacing.xs + theme.tokens.spacing.sm,
     borderRadius: theme.tokens.radius.lg,
     backgroundColor: theme.colors.primarySoft,
   },
   item: { flex: 1, paddingVertical: theme.tokens.spacing.xs },
-  itemContent: { alignItems: 'center', justifyContent: 'center', gap: 2 },
+  itemContent: { alignItems: 'center', justifyContent: 'center', gap: theme.tokens.spacing.xxs },
   label: { fontSize: theme.tokens.fontSize.xs, fontWeight: theme.tokens.fontWeight.medium },
   badge: {
     position: 'absolute',
-    top: -4,
+    top: -theme.tokens.spacing.xs,
     left: '50%',
-    marginLeft: 4,
-    minWidth: 16,
-    height: 16,
-    paddingHorizontal: 4,
+    marginLeft: theme.tokens.spacing.xs,
+    minWidth: BADGE_SIZE,
+    height: BADGE_SIZE,
+    paddingHorizontal: theme.tokens.spacing.xs,
     borderRadius: theme.tokens.radius.full,
     backgroundColor: theme.colors.error,
     alignItems: 'center',
     justifyContent: 'center',
   },
-  badgeDot: { minWidth: 10, height: 10, top: -2, paddingHorizontal: 0 },
+  badgeDot: { minWidth: BADGE_DOT_SIZE, height: BADGE_DOT_SIZE, top: -theme.tokens.spacing.xxs, paddingHorizontal: 0 },
   badgeText: {
-    fontSize: 10,
+    fontSize: BADGE_FONT_SIZE,
     fontWeight: theme.tokens.fontWeight.bold,
     color: theme.colors.onError,
   },
@@ -85,10 +104,20 @@ const ICON_SIZE = 22;
 
 /**
  * NavigationBar
- * Barra de navegación por pestañas con la misma apariencia y las mismas
- * transiciones en iOS y Android: el indicador se desliza hasta la pestaña
- * activa y su contenido crece y toma el color de acento con un cross-fade.
- * No navega por su cuenta — reporta la pestaña tocada y el consumidor decide.
+ * Tab navigation bar with the same look and the same transitions on iOS and
+ * Android: the indicator slides to the active tab and its content grows and
+ * takes the accent color with a cross-fade.
+ * It doesn't navigate on its own — it reports the tapped tab and the consumer decides.
+ *
+ * Design:
+ * - Jakob's law: the tab bar people know from every app, at the bottom by
+ *   default, icon over label.
+ * - Similarity + Von Restorff: every tab looks the same except the active
+ *   one, which alone gets the accent and the indicator.
+ * - Continuity: the indicator slides from tab to tab instead of jumping
+ *   (in place with Reduce Motion).
+ * - Fitts's law: the whole column is the target, not just the icon.
+ * - Hick's law: meant for 3–5 destinations.
  */
 export const NavigationBar = memo(
   ({
@@ -98,6 +127,7 @@ export const NavigationBar = memo(
     position = 'bottom',
     showLabels = true,
     safeArea = true,
+    hideOnKeyboard = true,
     style,
     testID,
   }: NavigationBarProps) => {
@@ -106,8 +136,23 @@ export const NavigationBar = memo(
     const styles = useStyles();
     const insets = useInsets();
     const allowFontScaling = useAllowFontScaling();
+    const reduceMotion = useReduceMotion();
 
     const [barWidth, setBarWidth] = useState(0);
+    const [keyboardOpen, setKeyboardOpen] = useState(false);
+
+    // On Android the window shrinks with the keyboard and the bar would end up
+    // floating above it, between the field and the keys. On iOS the keyboard
+    // covers it: no need (and hiding it would move the layout midway through
+    // the keyboard animation).
+    useEffect(() => {
+      if (!hideOnKeyboard || position !== 'bottom' || Platform.OS !== 'android') return;
+      const subs = [
+        Keyboard.addListener('keyboardDidShow', () => setKeyboardOpen(true)),
+        Keyboard.addListener('keyboardDidHide', () => setKeyboardOpen(false)),
+      ];
+      return () => subs.forEach((sub) => sub.remove());
+    }, [hideOnKeyboard, position]);
     const slide = useRef(new Animated.Value(0)).current;
     const placed = useRef(false);
 
@@ -120,15 +165,16 @@ export const NavigationBar = memo(
     useEffect(() => {
       if (itemWidth <= 0) return;
       const to = activeIndex * itemWidth;
-      // En el primer layout el indicador aparece en su lugar; animarlo desde 0
-      // sería un deslizamiento que el usuario no pidió.
-      if (!placed.current) {
+      // On the first layout the indicator appears in place; animating it from 0
+      // would be a slide the user didn't ask for.
+      // With Reduce Motion it moves without the slide, too.
+      if (!placed.current || reduceMotion) {
         placed.current = true;
         slide.setValue(to);
         return;
       }
-      Animated.spring(slide, { toValue: to, useNativeDriver: true, friction: 9, tension: 90 }).start();
-    }, [activeIndex, itemWidth, slide]);
+      Animated.spring(slide, { toValue: to, useNativeDriver: true, ...INDICATOR_SPRING }).start();
+    }, [activeIndex, itemWidth, slide, reduceMotion]);
 
     const onLayout = (e: LayoutChangeEvent) => {
       const next = e.nativeEvent.layout.width - theme.tokens.spacing.xs * 2;
@@ -146,6 +192,8 @@ export const NavigationBar = memo(
       </>
     );
 
+    if (keyboardOpen) return null;
+
     return (
       <View
         testID={testID}
@@ -196,10 +244,12 @@ export const NavigationBar = memo(
               accessibilityRole="tab"
               accessibilityLabel={item.label}
               accessibilityState={{ selected: active }}
+              // The badge is drawn, not text the reader reaches: its count goes in the value.
+              accessibilityValue={typeof item.badge === 'number' || typeof item.badge === 'string' ? { text: String(item.badge) } : undefined}
             >
               <Animated.View style={[styles.itemContent, { transform: [{ scale }] }]}>
                 {renderContent(item, colors.textLight)}
-                {/* Copia decorativa: sin ocultarla, el lector lee el label dos veces. */}
+                {/* Decorative copy: if it weren't hidden, the reader would read the label twice. */}
                 <Animated.View
                   pointerEvents="none"
                   accessibilityElementsHidden