orn-ui 0.2.9 → 0.3.0

package/src/organisms/Toast.tsx

@@ -1,7 +1,7 @@
 import React, { memo } from 'react';
 import { Pressable, Text, View, type StyleProp, type ViewStyle } from 'react-native';
 import { createStyles } from '../theme/createStyles';
-import { useAllowFontScaling, useColors } from '../theme/UIProvider';
+import { useAllowFontScaling, useColors, useLabels } from '../theme/UIProvider';
 import { Transition } from '../atoms/Transition';
 import { Icon } from '../icons/Icon';
 import type { IconName } from '../icons/types';
@@ -9,11 +9,15 @@ import type { IconName } from '../icons/types';
 export type ToastVariant = 'success' | 'error' | 'warning' | 'info';
 
 export interface ToastProps {
+  /** Main line. */
   title: string;
+  /** Optional second line. */
   message?: string;
+  /** Sets the icon and the color of the side bar. @default 'info' */
   variant?: ToastVariant;
   /** Fires when the toast is tapped (in addition to closing it). */
   onPress?: () => void;
+  /** Shows the close X (unless `hideCloseButton`) and is called when it is pressed. */
   onDismiss?: () => void;
   /** Hides the close X. The toast still auto-dismisses by timeout. */
   hideCloseButton?: boolean;
@@ -28,12 +32,21 @@ const ICON_BY_VARIANT: Record<ToastVariant, IconName> = {
   info: 'info',
 };
 
+/** Width of the colored bar on the left edge. */
+const ACCENT_WIDTH = 4;
+const ICON_SIZE = 22;
+const CLOSE_ICON_SIZE = 18;
+/** Pads the close glyph out to a 44pt target without growing the toast. */
+const CLOSE_HIT_SLOP = (44 - CLOSE_ICON_SIZE) / 2;
+/** How far it drops in from above. */
+const ENTER_DISTANCE = 16;
+
 const useStyles = createStyles((theme) => ({
   container: {
     flexDirection: 'row',
     alignItems: 'center',
     gap: theme.tokens.spacing.md,
-    backgroundColor: theme.colors.surface,
+    backgroundColor: theme.colors.surfaceRaised,
     borderRadius: theme.tokens.radius.lg,
     borderWidth: 1,
     borderColor: theme.colors.border,
@@ -46,11 +59,11 @@ const useStyles = createStyles((theme) => ({
     left: 0,
     top: 0,
     bottom: 0,
-    width: 4,
+    width: ACCENT_WIDTH,
     borderTopLeftRadius: theme.tokens.radius.lg,
     borderBottomLeftRadius: theme.tokens.radius.lg,
   },
-  text: { flex: 1, gap: 2 },
+  text: { flex: 1, gap: theme.tokens.spacing.xxs },
   title: {
     fontSize: theme.tokens.fontSize.md,
     fontWeight: theme.tokens.fontWeight.semibold,
@@ -61,18 +74,30 @@ const useStyles = createStyles((theme) => ({
 
 /**
  * Toast
- * Notificación efímera. Normalmente no se usa directo: `ToastProvider` +
- * `useToast()` la montan y la descartan por vos. Se expone igual por si
- * querés colocarla vos mismo dentro de una pantalla concreta.
+ * Ephemeral notification. Normally not used directly: `ToastProvider` +
+ * `useToast()` mount and dismiss it for you. It is exposed anyway in case
+ * you want to place it yourself inside a specific screen.
+ *
+ * Design:
+ * - Doherty threshold: immediate feedback for an action, without blocking
+ *   the screen; it leaves on its own.
+ * - Similarity: the variant sets both the bar and the icon color, so success,
+ *   error, warning and info read at a glance (and not by color alone: each
+ *   has its own glyph).
+ * - Figure/ground: a raised surface with a shadow, above the content.
+ * - Fitts's law: the close button is a 44pt target.
+ * - Screen readers: `ToastProvider` announces each toast as it appears; a
+ *   pressable toast reads title and message, and offers "Close" as an action.
  */
 export const Toast = memo(
   ({ title, message, variant = 'info', onPress, onDismiss, hideCloseButton, style, testID }: ToastProps) => {
     const colors = useColors();
     const styles = useStyles();
     const allowFontScaling = useAllowFontScaling();
+    const labels = useLabels();
 
-    // La barra lateral es relleno (acento pleno); el ícono es contenido
-    // sobre la superficie del toast y necesita el rol `*Text`.
+    // The side bar is a fill (full accent); the icon is content over the
+    // toast's surface and needs the `*Text` role.
     const barColor: Record<ToastVariant, string> = {
       success: colors.success,
       error: colors.error,
@@ -89,7 +114,7 @@ export const Toast = memo(
     const body = (
       <View style={[styles.container, style]} testID={testID} accessibilityRole="alert">
         <View style={[styles.accent, { backgroundColor: barColor[variant] }]} />
-        <Icon name={ICON_BY_VARIANT[variant]} size={22} color={iconColor[variant]} />
+        <Icon name={ICON_BY_VARIANT[variant]} size={ICON_SIZE} color={iconColor[variant]} />
         <View style={styles.text}>
           <Text allowFontScaling={allowFontScaling} style={styles.title}>
             {title}
@@ -101,8 +126,8 @@ export const Toast = memo(
           )}
         </View>
         {!hideCloseButton && !!onDismiss && (
-          <Pressable onPress={onDismiss} accessibilityRole="button" accessibilityLabel="Dismiss" hitSlop={8}>
-            <Icon name="close" size={18} color={colors.textLight} />
+          <Pressable onPress={onDismiss} accessibilityRole="button" accessibilityLabel={labels.close} hitSlop={CLOSE_HIT_SLOP}>
+            <Icon name="close" size={CLOSE_ICON_SIZE} color={colors.textLight} />
           </Pressable>
         )}
       </View>
@@ -111,7 +136,17 @@ export const Toast = memo(
     if (!onPress) return body;
 
     return (
-      <Pressable onPress={onPress} accessibilityRole="button" accessibilityLabel={title}>
+      <Pressable
+        onPress={onPress}
+        accessibilityRole="button"
+        accessibilityLabel={message ? `${title}, ${message}` : title}
+        // The close X inside a pressable toast isn't reachable on its own:
+        // the reader gets it as an action of the toast.
+        accessibilityActions={!hideCloseButton && onDismiss ? [{ name: 'dismiss', label: labels.close }] : undefined}
+        onAccessibilityAction={(event) => {
+          if (event.nativeEvent.actionName === 'dismiss') onDismiss?.();
+        }}
+      >
         {body}
       </Pressable>
     );
@@ -119,10 +154,10 @@ export const Toast = memo(
 );
 Toast.displayName = 'Toast';
 
-/** Envuelve un Toast con su animación de entrada/salida. Uso interno del provider. */
+/** Wraps a Toast with its enter/exit animation. Internal use by the provider. */
 export const AnimatedToast = memo(
   ({ children, onHeight }: { children: React.ReactNode; onHeight?: (h: number) => void }) => (
-    <Transition preset={['fade', 'slide-down']} distance={16} spring>
+    <Transition preset={['fade', 'slide-down']} distance={ENTER_DISTANCE} spring>
       <View onLayout={(e) => onHeight?.(e.nativeEvent.layout.height)}>{children}</View>
     </Transition>
   )

package/src/organisms/ToastProvider.tsx

@@ -1,5 +1,5 @@
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
-import { View } from 'react-native';
+import { AccessibilityInfo, View } from 'react-native';
 import { AnimatedToast, Toast, type ToastVariant } from './Toast';
 import { useInsets } from '../theme/UIProvider';
 import { createStyles } from '../theme/createStyles';
@@ -9,7 +9,7 @@ export interface ToastOptions {
   title: string;
   message?: string;
   variant?: ToastVariant;
-  /** ms antes de auto-descartar. 0 = no se descarta solo. @default 4000 */
+  /** Milliseconds before auto-dismiss. 0 = never dismisses on its own. @default 4000 */
   duration?: number;
   onPress?: () => void;
   hideCloseButton?: boolean;
@@ -20,7 +20,7 @@ interface ToastEntry extends ToastOptions {
 }
 
 interface ToastContextValue {
-  /** Muestra un toast y devuelve su id (por si querés cerrarlo antes de tiempo). */
+  /** Shows a toast and returns its id (to close it early if needed). */
   show: (options: ToastOptions) => string;
   hide: (id: string) => void;
   hideAll: () => void;
@@ -30,9 +30,9 @@ const ToastContext = createContext<ToastContextValue | undefined>(undefined);
 const bridge = createImperativeBridge<ToastContextValue>('ToastProvider');
 
 /**
- * Muestra un toast desde fuera del árbol de React —un servicio, un
- * interceptor— sin pasar por el hook. Devuelve el id, o '' si no hay
- * <ToastProvider> montado.
+ * Shows a toast from outside the React tree —a service, an interceptor—
+ * without going through the hook. Returns the id, or '' if there is no
+ * mounted <ToastProvider>.
  */
 export function showToast(options: ToastOptions): string {
   return bridge.get()?.show(options) ?? '';
@@ -62,9 +62,9 @@ export interface ToastProviderProps {
 
 /**
  * ToastProvider
- * Monta la capa de toasts sobre el resto de la app. Colocar una vez cerca de
- * la raíz, dentro de UIProvider. Los timers de auto-dismiss se limpian al
- * desmontar y al cerrar cada toast, así que no quedan callbacks colgados.
+ * Mounts the toast layer above the rest of the app. Place it once near the
+ * root, inside UIProvider. The auto-dismiss timers are cleared on unmount and
+ * when each toast closes, so no callbacks are left hanging.
  */
 export function ToastProvider({
   children,
@@ -108,8 +108,8 @@ export function ToastProvider({
 
       setToasts((prev) => {
         const next = [...prev, { ...options, id }];
-        // Se descartan los más viejos, no los recién llegados: un toast nuevo
-        // siempre se ve.
+        // The oldest are dropped, not the newcomers: a new toast is always
+        // visible.
         const overflow = next.length - maxVisible;
         if (overflow > 0) {
           next.slice(0, overflow).forEach((t) => clearTimer(t.id));
@@ -118,6 +118,10 @@ export function ToastProvider({
         return next;
       });
 
+      // It appears without focus: screen readers only hear it if it is
+      // announced (iOS ignores accessibilityRole="alert" on its own).
+      AccessibilityInfo.announceForAccessibility(options.message ? `${options.title}. ${options.message}` : options.title);
+
       if (duration > 0) {
         timers.current.set(
           id,
@@ -129,8 +133,8 @@ export function ToastProvider({
     [defaultDuration, maxVisible, hide, clearTimer]
   );
 
-  // Al desmontar el provider no debe quedar ningún setTimeout apuntando a un
-  // setState de un árbol ya desmontado.
+  // When the provider unmounts no setTimeout must be left pointing at a
+  // setState of an already unmounted tree.
   useEffect(() => {
     const pending = timers.current;
     return () => {

package/src/organisms/Wizard.tsx

@@ -1,29 +1,38 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { ScrollView, View, type StyleProp, type ViewStyle } from 'react-native';
+import { AccessibilityInfo, Platform, ScrollView, View, type StyleProp, type ViewStyle } from 'react-native';
 import { createStyles } from '../theme/createStyles';
+import { useLabels } from '../theme/UIProvider';
+import { KeyboardHandled } from '../theme/KeyboardAvoidance';
 import { Steps, type StepItem } from '../molecules/Steps';
 import { Button } from '../atoms/Button';
 import { Transition } from '../atoms/Transition';
 
 export interface WizardStep extends StepItem {
   content: React.ReactNode;
-  /** false bloquea el avance desde este paso (validación). @default true */
+  /** `false` blocks advancing from this step (validation). @default true */
   canGoNext?: boolean;
 }
 
 export interface WizardProps {
+  /** The steps, in order: label, optional description, content and `canGoNext`. */
   steps: WizardStep[];
   /** Current step (controlled). If omitted, the Wizard manages its own state. */
   current?: number;
+  /** Called with the new index when the step changes (Back, Next or a tap on the indicator). */
   onStepChange?: (index: number) => void;
+  /** Called when the finish button is pressed on the last step. */
   onFinish?: () => void;
-  /** @default 'horizontal' */
+  /** Layout of the step indicator: a row or a column. @default 'horizontal' */
   orientation?: 'horizontal' | 'vertical';
+  /** What the circle of a completed step shows: a check, or its number. @default 'check' */
   completedIndicator?: 'check' | 'number';
   /** Allows returning to an already-completed step by tapping it in the indicator. @default true */
   allowStepNavigation?: boolean;
+  /** Text of the back button (hidden on the first step). @default labels.back */
   backLabel?: string;
+  /** Text of the next button. @default labels.next */
   nextLabel?: string;
+  /** Text of the next button on the last step. @default labels.finish */
   finishLabel?: string;
   /**
    * The step content scrolls when it doesn't fit. Set to false only if
@@ -51,10 +60,21 @@ const useStyles = createStyles((theme) => ({
 
 /**
  * Wizard
- * Flujo multi-paso: indicador (Steps) + contenido del paso actual + barra de
- * navegación. Funciona controlado (`current` + `onStepChange`) o por su
- * cuenta. `canGoNext: false` en un paso deshabilita el avance, que es donde
- * se engancha la validación del formulario de ese paso.
+ * Multi-step flow: indicator (Steps) + content of the current step +
+ * navigation bar. Works controlled (`current` + `onStepChange`) or on its
+ * own. `canGoNext: false` on a step disables moving forward, which is where
+ * that step's form validation hooks in.
+ *
+ * Design:
+ * - Chunking (Miller) + Hick's law: a long form split into a few steps, one
+ *   decision set at a time.
+ * - Continuity: the content slides in the direction of travel (a fade with
+ *   Reduce Motion), so forward and back feel like a path.
+ * - Proximity + Fitts's law: Back and Next share one row at the bottom, full
+ *   width, within thumb reach; Next is the filled one (Von Restorff).
+ * - Error prevention: Next stays disabled until the step is valid, and the
+ *   indicator only jumps back, never past an unvalidated step.
+ * - Screen readers: each step change is announced ("Step 2 of 3: Plan").
  */
 export function Wizard({
   steps,
@@ -64,14 +84,15 @@ export function Wizard({
   orientation = 'horizontal',
   completedIndicator = 'check',
   allowStepNavigation = true,
-  backLabel = 'Back',
-  nextLabel = 'Next',
-  finishLabel = 'Finish',
+  backLabel,
+  nextLabel,
+  finishLabel,
   scrollableContent = true,
   animated = true,
   style,
 }: WizardProps) {
   const styles = useStyles();
+  const labels = useLabels();
   const [uncontrolled, setUncontrolled] = useState(0);
   const isControlled = controlledCurrent !== undefined;
   const current = isControlled ? controlledCurrent : uncontrolled;
@@ -90,13 +111,27 @@ export function Wizard({
     [steps]
   );
 
-  // El ref todavía guarda el paso anterior durante el render que trae el nuevo.
+  // The ref still holds the previous step during the render that brings the new one.
   const previous = useRef(current);
   const forward = current >= previous.current;
   const entered = useRef(false);
   useEffect(() => {
+    // Next/Back keep the focus on the button: without this the reader never
+    // learns that the content changed. Not on mount, only on a change.
+    if (entered.current && previous.current !== current) {
+      const step = steps[current];
+      if (step) {
+        AccessibilityInfo.announceForAccessibility(
+          labels.stepOf
+            .replace('{n}', String(current + 1))
+            .replace('{total}', String(steps.length))
+            .replace('{label}', step.label)
+        );
+      }
+    }
     previous.current = current;
     entered.current = true;
+    // Only a step change announces; new `steps` with the same step don't.
   }, [current]);
 
   const activeStep = steps[current];
@@ -109,8 +144,8 @@ export function Wizard({
     else goTo(current + 1);
   };
 
-  // El paso saliente no se anima: mantener los dos montados a la vez duplicaría
-  // los formularios y su estado.
+  // The outgoing step isn't animated: keeping both mounted at once would
+  // duplicate the forms and their state.
   const renderContent = () =>
     animated ? (
       <Transition
@@ -132,14 +167,14 @@ export function Wizard({
         current={current}
         orientation={orientation}
         completedIndicator={completedIndicator}
-        // Sólo se puede volver atrás tocando el indicador; saltar hacia
-        // adelante se saltearía la validación de los pasos intermedios.
+        // You can only go back by tapping the indicator; jumping forward
+        // would skip the validation of the steps in between.
         onStepPress={allowStepNavigation ? (index) => index < current && goTo(index) : undefined}
       />
 
-      {/* El contenido scrollea en vez de desbordar: con el teclado abierto un
-          form largo se comía el footer y los botones quedaban pintados encima
-          de los campos. */}
+      {/* The content scrolls instead of overflowing: with the keyboard open a
+          long form ate the footer and the buttons ended up painted over the
+          fields. */}
       {scrollableContent ? (
         <ScrollView
           testID="wizard-content"
@@ -149,7 +184,9 @@ export function Wizard({
           automaticallyAdjustKeyboardInsets
           showsVerticalScrollIndicator={false}
         >
-          {renderContent()}
+          {/* iOS: the ScrollView already lifts the field (automaticallyAdjustKeyboardInsets).
+              Android doesn't have that prop: there the root host handles it. */}
+          {Platform.OS === 'ios' ? <KeyboardHandled>{renderContent()}</KeyboardHandled> : renderContent()}
         </ScrollView>
       ) : (
         <View style={styles.content}>{renderContent()}</View>
@@ -157,10 +194,10 @@ export function Wizard({
 
       <View style={styles.footer}>
         {!isFirst && (
-          <Button title={backLabel} variant="outline" onPress={() => goTo(current - 1)} style={styles.footerButton} />
+          <Button title={backLabel ?? labels.back} variant="outline" onPress={() => goTo(current - 1)} style={styles.footerButton} />
         )}
         <Button
-          title={isLast ? finishLabel : nextLabel}
+          title={isLast ? (finishLabel ?? labels.finish) : (nextLabel ?? labels.next)}
           onPress={handleNext}
           disabled={!canGoNext}
           style={styles.footerButton}

package/src/organisms/chart/frame.tsx

@@ -1,13 +1,13 @@
 /**
- * El marco de Chart: todo lo que rodea a las marcas — grilla, ejes, leyenda y
- * tooltip. Nada de acá conoce el tipo de chart; recibe números y textos ya
- * resueltos.
+ * Chart's frame: everything around the marks — grid, axes, legend and
+ * tooltip. Nothing here knows the chart type; it receives numbers and texts
+ * already resolved.
  *
- * Gestalt: la grilla usa `border`, dos escalones por debajo del color de las
- * series, para que el dato quede como figura y la referencia como fondo. La
- * leyenda repite el color exacto de cada serie (similitud) y por eso puede
- * hacer de control de filtro sin explicar qué apaga: se apaga lo que tiene ese
- * color.
+ * Gestalt: the grid uses `border`, two steps below the series' color, so the
+ * data stays as figure and the reference as ground. The legend repeats each
+ * series' exact color (similarity), which is why it can act as a filter
+ * control without explaining what it turns off: whatever has that color
+ * turns off.
  */
 import React, { memo } from 'react';
 import { Text, TouchableOpacity, View, type StyleProp, type ViewStyle } from 'react-native';
@@ -47,7 +47,7 @@ const useStyles = createStyles((theme) => ({
     paddingVertical: theme.tokens.spacing.sm,
     paddingHorizontal: theme.tokens.spacing.md,
     borderRadius: theme.tokens.radius.md,
-    backgroundColor: theme.colors.surface,
+    backgroundColor: theme.colors.surfaceRaised,
     borderWidth: 1,
     borderColor: theme.colors.border,
     gap: theme.tokens.spacing.xxs,
@@ -68,16 +68,16 @@ const useStyles = createStyles((theme) => ({
   },
 }));
 
-// ── grilla y ejes cartesianos ──────────────────────────────────────────────
+// ── grid and cartesian axes ────────────────────────────────────────────────
 
 export interface CartesianGridProps {
   width: number;
   height: number;
-  /** Posición en píxeles de cada línea, sobre el eje perpendicular a ella. */
+  /** Pixel position of each line, along the axis perpendicular to it. */
   lines: number[];
-  /** 'horizontal' dibuja líneas que cruzan a lo ancho (eje y con ticks). */
+  /** 'horizontal' draws lines running across the width (y axis with ticks). */
   orientation: 'horizontal' | 'vertical';
-  /** Índice de la línea del cero, más marcada que el resto. */
+  /** Index of the zero line, more marked than the rest. */
   zeroIndex?: number;
   testID?: string;
 }
@@ -98,8 +98,8 @@ export const CartesianGrid = memo(({ width, height, lines, orientation, zeroInde
               orientation === 'horizontal'
                 ? { left: 0, width, top: position, height: 1 }
                 : { top: 0, height, left: position, width: 1 },
-              // La línea del cero es una referencia distinta de las demás: no
-              // divide el espacio, separa lo que suma de lo que resta.
+              // The zero line is a different reference from the others: it
+              // doesn't divide the space, it separates what adds from what subtracts.
               isZero && { backgroundColor: colors.textLight },
             ]}
           />
@@ -112,11 +112,11 @@ CartesianGrid.displayName = 'CartesianGrid';
 
 export interface AxisLabelsProps {
   labels: { text: string; position: number }[];
-  /** 'x' las reparte a lo ancho debajo del plot; 'y' las apila a la izquierda. */
+  /** 'x' spreads them across the width below the plot; 'y' stacks them on the left. */
   axis: 'x' | 'y';
-  /** Ancho del canal reservado para las etiquetas. */
+  /** Width of the gutter reserved for the labels. */
   gutter: number;
-  /** Tamaño del plot sobre el eje de las etiquetas. */
+  /** Size of the plot along the labels' axis. */
   span: number;
   testID?: string;
 }
@@ -126,8 +126,8 @@ const LABEL_HEIGHT = 14;
 export const AxisLabels = memo(({ labels, axis, gutter, span, testID }: AxisLabelsProps) => {
   const styles = useStyles();
   const allowFontScaling = useAllowFontScaling();
-  // Una etiqueta de x se centra bajo su categoría y puede pisar a la vecina;
-  // se le da como ancho el reparto parejo del plot y se trunca a una línea.
+  // An x label is centered under its category and can overlap its neighbor;
+  // it gets the plot's even share as its width and is truncated to one line.
   const slot = axis === 'x' ? Math.max(24, span / Math.max(1, labels.length)) : gutter;
 
   return (
@@ -152,21 +152,21 @@ export const AxisLabels = memo(({ labels, axis, gutter, span, testID }: AxisLabe
 });
 AxisLabels.displayName = 'AxisLabels';
 
-// ── grilla del radar ───────────────────────────────────────────────────────
+// ── radar grid ─────────────────────────────────────────────────────────────
 
 export interface RadarGridProps {
   center: Point;
   radius: number;
   angles: number[];
-  /** Anillos concéntricos, incluido el borde. */
+  /** Concentric rings, including the edge. */
   levels: number;
   testID?: string;
 }
 
 /**
- * Anillos y radios del radar. Los anillos son polígonos, no círculos: un
- * círculo sugiere que entre eje y eje hay valores, y no los hay — sólo hay
- * los ejes que se pasaron.
+ * The radar's rings and spokes. The rings are polygons, not circles: a circle
+ * suggests there are values between one axis and the next, and there aren't —
+ * there are only the axes that were passed in.
  */
 export const RadarGrid = memo(({ center, radius, angles, levels, testID }: RadarGridProps) => {
   const colors = useColors();
@@ -223,7 +223,7 @@ export const RadarGrid = memo(({ center, radius, angles, levels, testID }: Radar
 });
 RadarGrid.displayName = 'RadarGrid';
 
-// ── leyenda ────────────────────────────────────────────────────────────────
+// ── legend ─────────────────────────────────────────────────────────────────
 
 export interface LegendItem {
   key: string;
@@ -234,7 +234,7 @@ export interface LegendItem {
 export interface LegendProps {
   items: LegendItem[];
   hidden: string[];
-  /** Sin esto la leyenda es sólo referencia; con esto es el filtro. */
+  /** Without this the legend is only a reference; with it, it is the filter. */
   onToggle?: (key: string) => void;
   testID?: string;
 }
@@ -295,9 +295,9 @@ export interface TooltipRow {
 export interface TooltipProps {
   title: string;
   rows: TooltipRow[];
-  /** Punto que describe, en coordenadas del contenedor. */
+  /** The point it describes, in container coordinates. */
   anchor: Point;
-  /** Ancho disponible: el globo se corre para no salirse. */
+  /** Available width: the bubble shifts so it doesn't spill out. */
   containerWidth: number;
   style?: StyleProp<ViewStyle>;
   testID?: string;
@@ -305,19 +305,19 @@ export interface TooltipProps {
 
 const TOOLTIP_WIDTH = 148;
 const TOOLTIP_GAP = 10;
-/** Alto estimado del globo: el real no se sabe hasta después de medirlo, y
- *  medirlo para decidir dónde ponerlo lo haría aparecer corrido un frame. */
+/** Estimated bubble height: the real one isn't known until it's measured, and
+ *  measuring it to decide where to put it would make it show up shifted for a frame. */
 const TOOLTIP_TITLE = 22;
 const TOOLTIP_ROW = 17;
 
 export const Tooltip = memo(({ title, rows, anchor, containerWidth, style, testID }: TooltipProps) => {
   const styles = useStyles();
   const allowFontScaling = useAllowFontScaling();
-  // Clamp en vez de flip: moverlo al otro lado del dedo hace que salte de lado
-  // mientras se arrastra, y el salto se lee como un error.
+  // Clamp instead of flip: moving it to the other side of the finger makes it
+  // jump sides while dragging, and the jump reads as a bug.
   const left = Math.max(0, Math.min(containerWidth - TOOLTIP_WIDTH, anchor.x - TOOLTIP_WIDTH / 2));
-  // Va arriba del punto, salvo que no haya lugar: ahí baja, porque taparse
-  // contra el borde superior lo deja ilegible.
+  // It goes above the point, unless there is no room: then it goes below,
+  // because getting cut off against the top edge makes it unreadable.
   const estimated = TOOLTIP_TITLE + rows.length * TOOLTIP_ROW;
   const above = anchor.y - TOOLTIP_GAP - estimated;
   const top = above >= 0 ? above : anchor.y + TOOLTIP_GAP;