orn-ui 0.2.10 → 0.3.0

package/src/molecules/Stepper.tsx

@@ -1,15 +1,27 @@
-import React, { memo, useState } from 'react';
-import { TextInput, TouchableOpacity, View, type StyleProp, type ViewStyle } from 'react-native';
+import React, { memo, useRef, useState, type ComponentRef } from 'react';
+import {
+  TextInput,
+  TouchableOpacity,
+  View,
+  type AccessibilityActionEvent,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
 import { createStyles } from '../theme/createStyles';
-import { useAllowFontScaling, useColors, useTheme } from '../theme/UIProvider';
+import { useAllowFontScaling, useColors, useLabels, useTheme } from '../theme/UIProvider';
+import { useKeyboardField } from '../theme/useKeyboardField';
 import { Icon } from '../icons/Icon';
 
 export type StepperSize = 'sm' | 'md' | 'lg';
 
 export interface StepperProps {
+  /** Current value, as text (it may be mid-typing, e.g. "" or "1."). */
   value: string;
+  /** Receives the cleaned-up text while typing, and the clamped value on blur. */
   onChangeText: (text: string) => void;
+  /** "+" pressed (or swipe up with a screen reader). Do the arithmetic here. */
   onIncrement: () => void;
+  /** "-" pressed (or swipe down with a screen reader). */
   onDecrement: () => void;
   /** Scale of the control: height, buttons, icon and typography. @default 'md' */
   size?: StepperSize;
@@ -30,7 +42,11 @@ export interface StepperProps {
   /** Accepts a decimal separator, normalizing comma to dot. @default false */
   allowDecimals?: boolean;
   style?: StyleProp<ViewStyle>;
+  /** Accessible name of the numeric field. @default labels.quantity */
+  accessibilityLabel?: string;
+  /** Accessible name of the "+" button. @default labels.increment */
   incrementAccessibilityLabel?: string;
+  /** Accessible name of the "-" button. @default labels.decrement */
   decrementAccessibilityLabel?: string;
   testID?: string;
 }
@@ -41,6 +57,14 @@ const SIZES: Record<StepperSize, { height: number; icon: number; inputWidth: num
   lg: { height: 52, icon: 22, inputWidth: 64 },
 };
 
+/** Minimum touch target (Fitts): smaller buttons reach it with hitSlop. */
+const MIN_TOUCH = 44;
+
+const ADJUST_ACTIONS = [
+  { name: 'increment' as const },
+  { name: 'decrement' as const },
+];
+
 const useStyles = createStyles((theme) => ({
   control: {
     flexDirection: 'row',
@@ -60,12 +84,12 @@ const useStyles = createStyles((theme) => ({
     borderRightWidth: 1,
     borderColor: theme.colors.border,
   },
-  // El fondo distingue el campo de un valor de sólo lectura: es la única
-  // señal de que ahí se puede tipear antes de tocarlo.
+  // The background tells the field apart from a read-only value: it is the
+  // only hint that you can type there before touching it.
   editable: { backgroundColor: theme.colors.inputBackground },
 }));
 
-/** Deja sólo lo que puede formar parte del número permitido por el rango. */
+/** Keeps only what can be part of a number allowed by the range. */
 export function sanitizeNumeric(text: string, { allowDecimals = false, allowNegative = false } = {}): string {
   const normalized = allowDecimals ? text.replace(',', '.') : text;
   const negative = allowNegative && normalized.trimStart().startsWith('-');
@@ -77,12 +101,20 @@ export function sanitizeNumeric(text: string, { allowDecimals = false, allowNega
 
 /**
  * Stepper
- * Botón "-" + input numérico editable + botón "+". `size` controla sólo la
- * escala y `block` sólo el ancho, así que los dos ejes se combinan libremente.
+ * "-" button + editable numeric input + "+" button. `size` controls only the
+ * scale and `block` only the width, so both axes combine freely.
+ *
+ * The component doesn't do the buttons' arithmetic —that lives in
+ * `onIncrement`/`onDecrement`—, but it does clean up what is typed and signals
+ * when the value hit an end of the range by disabling the button that would pass it.
  *
- * El componente no hace la aritmética de los botones —eso vive en
- * `onIncrement`/`onDecrement`—, pero sí limpia lo que se tipea y avisa cuándo
- * el valor llegó a un extremo del rango deshabilitando el botón que lo pasaría.
+ * Gestalt, common region: the three parts share one border, so they read as a
+ * single control; the field is set apart by its fill (it can be typed into).
+ * Fitts: every button reaches 44pt, `sm` through hitSlop.
+ *
+ * Accessibility: the field is an adjustable element — VoiceOver/TalkBack users
+ * swipe up/down to step the value — and every name comes from `labels`. Like
+ * Input, it stays visible above the keyboard while typing.
  */
 export const Stepper = memo(
   ({
@@ -97,19 +129,25 @@ export const Stepper = memo(
     max,
     allowDecimals = false,
     style,
-    incrementAccessibilityLabel = 'Increment',
-    decrementAccessibilityLabel = 'Decrement',
+    accessibilityLabel,
+    incrementAccessibilityLabel,
+    decrementAccessibilityLabel,
     testID,
   }: StepperProps) => {
     const theme = useTheme();
     const colors = useColors();
     const styles = useStyles();
+    const labels = useLabels();
     const allowFontScaling = useAllowFontScaling();
     const [focused, setFocused] = useState(false);
+    const controlRef = useRef<ComponentRef<typeof View>>(null);
+    const keyboard = useKeyboardField(controlRef);
 
     const { height, icon, inputWidth } = SIZES[size];
     const fontSize =
       size === 'sm' ? theme.tokens.fontSize.md : size === 'md' ? theme.tokens.fontSize.lg : theme.tokens.fontSize.xl;
+    const slopV = Math.max(0, (MIN_TOUCH - height) / 2);
+    const hitSlop = slopV > 0 ? { top: slopV, bottom: slopV, left: slopV, right: slopV } : undefined;
 
     const allowNegative = min !== undefined && min < 0;
     const numeric = Number(value);
@@ -121,15 +159,22 @@ export const Stepper = memo(
       onChangeText(sanitizeNumeric(text, { allowDecimals, allowNegative }));
     };
 
-    // El recorte al rango espera al blur: hacerlo mientras se tipea impide
-    // llegar a "12" cuando el mínimo es 5, porque el "1" ya se corregiría.
+    // Clamping to the range waits for blur: doing it while typing makes it
+    // impossible to reach "12" when the minimum is 5, because the "1" would
+    // already be corrected.
     const handleBlur = () => {
       setFocused(false);
+      keyboard.blur();
       if (!isNumber) return;
       const clamped = Math.min(max ?? numeric, Math.max(min ?? numeric, numeric));
       if (clamped !== numeric) onChangeText(String(clamped));
     };
 
+    const handleAccessibilityAction = (e: AccessibilityActionEvent) => {
+      if (e.nativeEvent.actionName === 'increment' && !atMax) onIncrement();
+      if (e.nativeEvent.actionName === 'decrement' && !atMin) onDecrement();
+    };
+
     const stepButton = (
       direction: 'decrement' | 'increment',
       onPress: () => void,
@@ -139,6 +184,7 @@ export const Stepper = memo(
       <TouchableOpacity
         onPress={onPress}
         disabled={disabled}
+        hitSlop={hitSlop}
         style={[styles.btn, { width: height }]}
         accessibilityRole="button"
         accessibilityLabel={label}
@@ -155,6 +201,7 @@ export const Stepper = memo(
 
     return (
       <View
+        ref={controlRef}
         testID={testID}
         style={[
           styles.control,
@@ -164,7 +211,7 @@ export const Stepper = memo(
           style,
         ]}
       >
-        {stepButton('decrement', onDecrement, atMin, decrementAccessibilityLabel)}
+        {stepButton('decrement', onDecrement, atMin, decrementAccessibilityLabel ?? labels.decrement)}
         <TextInput
           allowFontScaling={allowFontScaling}
           style={[
@@ -176,14 +223,21 @@ export const Stepper = memo(
           ]}
           value={value}
           onChangeText={handleChangeText}
-          onFocus={() => setFocused(true)}
+          onFocus={() => {
+            setFocused(true);
+            keyboard.focus();
+          }}
           onBlur={handleBlur}
           editable={editable}
           keyboardType={allowDecimals ? 'decimal-pad' : 'number-pad'}
           selectTextOnFocus
-          accessibilityLabel="Quantity"
+          accessibilityLabel={accessibilityLabel ?? labels.quantity}
+          accessibilityRole="adjustable"
+          accessibilityValue={{ text: value }}
+          accessibilityActions={ADJUST_ACTIONS}
+          onAccessibilityAction={handleAccessibilityAction}
         />
-        {stepButton('increment', onIncrement, atMax, incrementAccessibilityLabel)}
+        {stepButton('increment', onIncrement, atMax, incrementAccessibilityLabel ?? labels.increment)}
       </View>
     );
   }

package/src/molecules/Steps.tsx

@@ -1,21 +1,33 @@
-import React, { memo } from 'react';
-import { ScrollView, Text, TouchableOpacity, View, type StyleProp, type ViewStyle } from 'react-native';
+import React, { memo, useEffect, useRef, useState, type ComponentRef } from 'react';
+import {
+  ScrollView,
+  Text,
+  TouchableOpacity,
+  View,
+  type LayoutChangeEvent,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { useReduceMotion } from '../theme/useReduceMotion';
 import { createStyles } from '../theme/createStyles';
-import { useAllowFontScaling, useColors } from '../theme/UIProvider';
+import { useAllowFontScaling, useColors, useLabels } from '../theme/UIProvider';
 import { Icon } from '../icons/Icon';
 
 export interface StepItem {
+  /** Short name of the step ("Payment"). */
   label: string;
+  /** Optional second line with a detail ("Card or cash"). */
   description?: string;
 }
 
 export type StepStatus = 'completed' | 'current' | 'pending';
 
 export interface StepsProps {
+  /** The sequence, in order. */
   steps: StepItem[];
   /** Index of the current step (0-based). Earlier steps become 'completed'. */
   current: number;
-  /** @default 'horizontal' */
+  /** Lays the steps out in a row or in a column. @default 'horizontal' */
   orientation?: 'horizontal' | 'vertical';
   /**
    * What the circle of an already-completed step shows: a check, or its number.
@@ -25,51 +37,73 @@ export interface StepsProps {
   /** If provided, each step is tappable and reports its index. */
   onStepPress?: (index: number) => void;
   style?: StyleProp<ViewStyle>;
+  /** Root testID; each step gets `<testID>-<index>`. */
+  testID?: string;
 }
 
 const CIRCLE = 32;
-/** Ancho mínimo de una columna horizontal: por debajo, las etiquetas se parten. */
+const CIRCLE_BORDER = 2;
+const CHECK_SIZE = 18;
+const CONNECTOR = 2;
+/** Minimum width of a horizontal column: below it, labels break mid-word. */
 const STEP_MIN_WIDTH = 76;
+/** Share of the row a horizontal connector takes next to a step (flex: 1). */
+const CONNECTOR_FLEX = 0.3;
+const PRESSED_OPACITY = 0.7;
 
 const useStyles = createStyles((theme) => ({
   rowContainer: { flexDirection: 'row', alignItems: 'flex-start' },
   columnContainer: { flexDirection: 'column' },
 
   // horizontal
-  // ScrollView trae flexGrow: 1 de fábrica y se comía todo el alto disponible
-  // del contenedor, dejando los pasos pegados arriba de una caja enorme.
+  // ScrollView ships with flexGrow: 1 and was eating all the available height
+  // of the container, leaving the steps stuck to the top of a huge box.
   hScrollView: { flexGrow: 0, flexShrink: 0 },
   hScroll: { flexGrow: 1, flexDirection: 'row', alignItems: 'flex-start' },
-  // `minWidth` es lo que evita que RN parta palabras a la mitad
-  // ("Almacé / n"): antes que apretar la columna por debajo de una palabra
-  // corriente, la fila se vuelve scrollable.
+  // `minWidth` is what keeps RN from breaking words in half
+  // ("Almacé / n"): rather than squeezing the column below a regular
+  // word, the row becomes scrollable.
   hStep: { flex: 1, minWidth: STEP_MIN_WIDTH, alignItems: 'center', gap: theme.tokens.spacing.sm },
-  hLabels: { alignItems: 'center', gap: 2, paddingHorizontal: 4 },
-  // El conector toma una fracción chica del ancho: compitiendo de igual a
-  // igual con los pasos (flex: 1) cada etiqueta se quedaba con 1/(2n-1) del
+  hLabels: { alignItems: 'center', gap: theme.tokens.spacing.xxs, paddingHorizontal: theme.tokens.spacing.xs },
+  // The connector takes a small fraction of the width: competing on equal
+  // terms with the steps (flex: 1), each label ended up with 1/(2n-1) of the
   // total.
-  hConnector: { height: 2, flex: 0.3, minWidth: 12, marginTop: CIRCLE / 2 - 1 },
-  hLabel: { fontSize: theme.tokens.fontSize.sm },
-  hDescription: { fontSize: theme.tokens.fontSize.xs },
+  hConnector: {
+    height: CONNECTOR,
+    flex: CONNECTOR_FLEX,
+    minWidth: theme.tokens.spacing.md,
+    marginTop: CIRCLE / 2 - CONNECTOR / 2,
+  },
+  hLabel: { fontSize: theme.tokens.fontSize.sm, lineHeight: theme.tokens.lineHeight.sm },
+  hDescription: { fontSize: theme.tokens.fontSize.xs, lineHeight: theme.tokens.lineHeight.sm },
 
   // vertical
   vStep: { flexDirection: 'row', gap: theme.tokens.spacing.md },
   vIndicatorColumn: { alignItems: 'center' },
-  vConnector: { width: 2, flex: 1, minHeight: 20, marginVertical: 4 },
-  vLabels: { flex: 1, gap: 2, paddingBottom: theme.tokens.spacing.lg },
+  vConnector: { width: CONNECTOR, flex: 1, minHeight: theme.tokens.spacing.xl, marginVertical: theme.tokens.spacing.xs },
+  vLabels: { flex: 1, gap: theme.tokens.spacing.xxs, paddingBottom: theme.tokens.spacing.lg },
+  // The last step has no connector below: no trailing space either.
+  vLabelsLast: { paddingBottom: 0 },
 
   circle: {
     width: CIRCLE,
     height: CIRCLE,
     borderRadius: CIRCLE / 2,
-    borderWidth: 2,
+    borderWidth: CIRCLE_BORDER,
     alignItems: 'center',
     justifyContent: 'center',
   },
   circleNumber: { fontSize: theme.tokens.fontSize.md, fontWeight: theme.tokens.fontWeight.semibold },
-  label: { fontSize: theme.tokens.fontSize.md, fontWeight: theme.tokens.fontWeight.semibold, color: theme.colors.text },
+  label: {
+    fontSize: theme.tokens.fontSize.md,
+    lineHeight: theme.tokens.lineHeight.md,
+    fontWeight: theme.tokens.fontWeight.semibold,
+    color: theme.colors.text,
+  },
+  labelCurrent: { color: theme.colors.primaryText },
+  labelPending: { color: theme.colors.textLight, fontWeight: theme.tokens.fontWeight.medium },
   labelCentered: { textAlign: 'center' },
-  description: { fontSize: theme.tokens.fontSize.sm, color: theme.colors.textLight },
+  description: { fontSize: theme.tokens.fontSize.sm, lineHeight: theme.tokens.lineHeight.sm, color: theme.colors.textLight },
   descriptionCentered: { textAlign: 'center' },
 }));
 
@@ -81,15 +115,51 @@ function statusOf(index: number, current: number): StepStatus {
 
 /**
  * Steps
- * Indicador de progreso multi-paso. Base visual de `Wizard`, pero utilizable
- * suelto para mostrar el avance de un flujo que se navega de otra forma.
+ * Multi-step progress indicator. The visual base of `Wizard`, but usable on
+ * its own to show progress through a flow that is navigated some other way.
+ *
+ * Gestalt, continuity: a connector line runs through the circles, so the steps
+ * read as one path; the stretch already walked is filled with the accent.
+ * Similarity: every step is the same circle + label, and the state only
+ * changes fill and color (done = filled, current = outlined accent, pending =
+ * grey). Von Restorff: the current step is the only accent-colored label.
+ *
+ * Accessibility: each step announces "Step 2 of 3: Payment, current", with
+ * every word from `labels`.
  */
 export const Steps = memo(
-  ({ steps, current, orientation = 'horizontal', completedIndicator = 'check', onStepPress, style }: StepsProps) => {
+  ({
+    steps,
+    current,
+    orientation = 'horizontal',
+    completedIndicator = 'check',
+    onStepPress,
+    style,
+    testID,
+  }: StepsProps) => {
     const colors = useColors();
+    const labels = useLabels();
     const styles = useStyles();
     const allowFontScaling = useAllowFontScaling();
     const isVertical = orientation === 'vertical';
+    const reduceMotion = useReduceMotion();
+
+    // Horizontal overflow: when the steps don't fit, the row scrolls. A hidden
+    // step gave no hint of existing, so the current step is brought into view
+    // and the scroll bar flashes once (visibility of system status).
+    const scrollRef = useRef<ComponentRef<typeof ScrollView>>(null);
+    const [viewportWidth, setViewportWidth] = useState(0);
+    const [contentWidth, setContentWidth] = useState(0);
+    const stepX = useRef<number[]>([]);
+    const overflows = !isVertical && viewportWidth > 0 && contentWidth > viewportWidth + 1;
+
+    useEffect(() => {
+      if (!overflows) return;
+      const x = stepX.current[current] ?? 0;
+      // A quarter of the row of lead-in: the previous step stays partly visible.
+      scrollRef.current?.scrollTo({ x: Math.max(0, x - viewportWidth / 4), animated: !reduceMotion });
+      scrollRef.current?.flashScrollIndicators();
+    }, [overflows, current, viewportWidth, reduceMotion]);
 
     const colorsFor = (status: StepStatus) => {
       if (status === 'completed') return { bg: colors.primary, border: colors.primary, fg: colors.onPrimary };
@@ -103,7 +173,7 @@ export const Steps = memo(
       return (
         <View style={[styles.circle, { backgroundColor: c.bg, borderColor: c.border }]}>
           {showCheck ? (
-            <Icon name="check" size={18} color={c.fg} />
+            <Icon name="check" size={CHECK_SIZE} color={c.fg} />
           ) : (
             <Text allowFontScaling={allowFontScaling} style={[styles.circleNumber, { color: c.fg }]}>
               {index + 1}
@@ -113,15 +183,16 @@ export const Steps = memo(
       );
     };
 
-    const renderLabels = (step: StepItem, status: StepStatus, centered: boolean) => (
-      <View style={centered ? styles.hLabels : styles.vLabels}>
+    const renderLabels = (step: StepItem, status: StepStatus, centered: boolean, isLast = false) => (
+      <View style={centered ? styles.hLabels : [styles.vLabels, isLast && styles.vLabelsLast]}>
         <Text
           allowFontScaling={allowFontScaling}
           style={[
             styles.label,
             centered && styles.labelCentered,
             centered && styles.hLabel,
-            status === 'pending' && { color: colors.textLight },
+            status === 'current' && styles.labelCurrent,
+            status === 'pending' && styles.labelPending,
           ]}
         >
           {step.label}
@@ -137,23 +208,28 @@ export const Steps = memo(
       </View>
     );
 
+    const statusLabel = { completed: labels.stepCompleted, current: labels.stepCurrent, pending: labels.stepPending };
     const stepAccessibility = (index: number, step: StepItem, status: StepStatus) => ({
       accessibilityRole: (onStepPress ? 'button' : 'text') as 'button' | 'text',
-      accessibilityLabel: `Step ${index + 1}: ${step.label}`,
+      accessibilityLabel: `${labels.stepOf
+        .replace('{n}', String(index + 1))
+        .replace('{total}', String(steps.length))
+        .replace('{label}', step.label)}, ${statusLabel[status]}`,
       accessibilityState: { selected: status === 'current', disabled: false },
+      testID: testID && `${testID}-${index}`,
     });
 
     if (isVertical) {
       return (
-        <View style={[styles.columnContainer, style]}>
+        <View style={[styles.columnContainer, style]} testID={testID}>
           {steps.map((step, index) => {
             const status = statusOf(index, current);
             const isLast = index === steps.length - 1;
             const Wrapper = onStepPress ? TouchableOpacity : View;
-            // Sólo tocable si hay onStepPress: pasarle onPress/activeOpacity
-            // a un View plano no crashea, pero los deja como ruido silencioso.
+            // Only touchable when there is onStepPress: passing onPress/activeOpacity
+            // to a plain View doesn't crash, but leaves them as silent noise.
             const interactiveProps = onStepPress
-              ? { onPress: () => onStepPress(index), activeOpacity: 0.7 }
+              ? { onPress: () => onStepPress(index), activeOpacity: PRESSED_OPACITY }
               : undefined;
             return (
               <Wrapper
@@ -173,7 +249,7 @@ export const Steps = memo(
                     />
                   )}
                 </View>
-                {renderLabels(step, status, false)}
+                {renderLabels(step, status, false, isLast)}
               </Wrapper>
             );
           })}
@@ -183,11 +259,14 @@ export const Steps = memo(
 
     return (
       <ScrollView
-        testID="steps-row"
+        ref={scrollRef}
+        testID={testID}
         horizontal
-        showsHorizontalScrollIndicator={false}
-        // Con espacio de sobra los pasos se reparten la fila igual que antes
-        // (flexGrow); cuando no entran, se desplaza en vez de apretar el texto.
+        showsHorizontalScrollIndicator={overflows}
+        onLayout={(e: LayoutChangeEvent) => setViewportWidth(e.nativeEvent.layout.width)}
+        onContentSizeChange={(width: number) => setContentWidth(width)}
+        // With room to spare the steps share the row just like before
+        // (flexGrow); when they don't fit, it scrolls instead of squeezing the text.
         style={[styles.hScrollView, style]}
         contentContainerStyle={styles.hScroll}
       >
@@ -196,12 +275,15 @@ export const Steps = memo(
           const isLast = index === steps.length - 1;
           const Wrapper = onStepPress ? TouchableOpacity : View;
           const interactiveProps = onStepPress
-            ? { onPress: () => onStepPress(index), activeOpacity: 0.7 }
+            ? { onPress: () => onStepPress(index), activeOpacity: PRESSED_OPACITY }
             : undefined;
           return (
             <React.Fragment key={`${step.label}-${index}`}>
               <Wrapper
                 style={styles.hStep}
+                onLayout={(e: LayoutChangeEvent) => {
+                  stepX.current[index] = e.nativeEvent.layout.x;
+                }}
                 {...interactiveProps}
                 {...stepAccessibility(index, step, status)}
               >

package/src/molecules/SymmetricGrid.tsx

@@ -1,10 +1,14 @@
 import React, { useMemo } from 'react';
 import { View, type StyleProp, type ViewStyle } from 'react-native';
 import { createStyles } from '../theme/createStyles';
+import { useTheme } from '../theme/UIProvider';
 
 export interface SymmetricGridProps<T> {
+  /** Items to lay out, in reading order. */
   data: T[];
+  /** Renders one cell; it gets the full cell width. */
   renderItem: (item: T, index: number) => React.ReactElement;
+  /** Stable key per item. */
   keyExtractor: (item: T, index: number) => string;
   /** Columns per row. @default 2 */
   columns?: number;
@@ -16,11 +20,11 @@ export interface SymmetricGridProps<T> {
    */
   balanceLastRow?: boolean;
   style?: StyleProp<ViewStyle>;
+  testID?: string;
 }
 
-const useStyles = createStyles((theme) => ({
-  grid: { gap: theme.tokens.spacing.md },
-  row: { flexDirection: 'row', gap: theme.tokens.spacing.md },
+const useStyles = createStyles(() => ({
+  row: { flexDirection: 'row' },
   rowBalanced: { justifyContent: 'center' },
   rowFull: { justifyContent: 'flex-start' },
   cell: { flexGrow: 0, flexShrink: 0 },
@@ -34,10 +38,16 @@ function chunk<T>(data: T[], size: number): T[][] {
 
 /**
  * SymmetricGrid
- * Ley de Prägnanz (buena forma): agrupa en filas parejas de N columnas.
- * La última fila, cuando queda incompleta, se centra por defecto en vez de
- * quedar pegada a un borde — eso es lo que la lee como "fila corta" y no
- * como un layout roto con un hueco a un lado.
+ * Law of Prägnanz (good form): groups items into even rows of N columns.
+ * The last row, when incomplete, is centered by default instead of sticking
+ * to one edge — that is what makes it read as a "short row" and not as a
+ * broken layout with a gap on one side.
+ *
+ * Gestalt, similarity: every cell has exactly the same width, also in the
+ * centered short row, so items read as peers. The horizontal gap is padding
+ * inside each cell (and a negative margin on the row), not flex `gap`: a
+ * `100 / columns %` width plus a gap made every row wider than the grid and
+ * pushed the right column out of the container.
  */
 export function SymmetricGrid<T>({
   data,
@@ -47,13 +57,16 @@ export function SymmetricGrid<T>({
   gap,
   balanceLastRow = true,
   style,
+  testID,
 }: SymmetricGridProps<T>) {
+  const theme = useTheme();
   const styles = useStyles();
   const rows = useMemo(() => chunk(data, columns), [data, columns]);
+  const space = gap ?? theme.tokens.spacing.md;
   const cellWidth = `${100 / columns}%` as const;
 
   return (
-    <View style={[styles.grid, gap !== undefined && { gap }, style]}>
+    <View style={[{ gap: space }, style]} testID={testID}>
       {rows.map((row, rowIndex) => {
         const isLastRow = rowIndex === rows.length - 1;
         const isIncomplete = row.length < columns;
@@ -61,15 +74,18 @@ export function SymmetricGrid<T>({
 
         return (
           <View
-            // `columns` en la key: si cambia, las filas no reusan nodos DOM
-            // de una fila armada con otra cantidad de columnas.
+            // `columns` in the key: if it changes, rows don't reuse DOM nodes
+            // from a row built with a different number of columns.
             key={`row-${columns}-${rowIndex}`}
-            style={[styles.row, centered ? styles.rowBalanced : styles.rowFull, gap !== undefined && { gap }]}
+            style={[styles.row, centered ? styles.rowBalanced : styles.rowFull, { marginHorizontal: -space / 2 }]}
           >
             {row.map((item, colIndex) => {
               const index = rowIndex * columns + colIndex;
               return (
-                <View key={keyExtractor(item, index)} style={[styles.cell, { width: cellWidth }]}>
+                <View
+                  key={keyExtractor(item, index)}
+                  style={[styles.cell, { width: cellWidth, paddingHorizontal: space / 2 }]}
+                >
                   {renderItem(item, index)}
                 </View>
               );