orn-ui 0.2.9 → 0.3.0

package/src/organisms/Slides.tsx

@@ -11,7 +11,7 @@ import {
   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 { useReduceMotion } from '../atoms/Transition';
 import { Gradient, type GradientDirection } from '../atoms/Gradient';
 import { useSlides, type SlidesOrientation } from './useSlides';
@@ -20,53 +20,59 @@ export type { SlidesOrientation } from './useSlides';
 export type SlidesIndicators = 'dots' | 'numbers' | 'none';
 export type SlidesIndicatorPlacement = 'overlay' | 'outside';
 
-/** Un color sólido, o dos o más para un degradado (ver `Gradient`). */
+/** A solid color, or two or more for a gradient (see `Gradient`). */
 export type SlideBackground = string | string[];
 
 export interface SlidesProps<T> {
+  /** One item per slide. */
   data: T[];
+  /** Stable key per item. */
   keyExtractor: (item: T, index: number) => string;
-  /** Contenido de la slide: imágenes, botones, lo que sea. Se dibuja sobre `background`. */
+  /** Slide content: images, buttons, anything. Drawn on top of `background`. */
   renderItem: (item: T, index: number) => React.ReactNode;
-  /** Fondo por slide: `'#101014'` pinta plano, `['#004cef', '#00cae1']` degrada. */
+  /** Per-slide background: `'#101014'` paints flat, `['#004cef', '#00cae1']` paints a gradient. */
   background?: (item: T, index: number) => SlideBackground | undefined;
-  /** Dirección del degradado cuando `background` devuelve varios colores. @default 'vertical' */
+  /** Gradient direction when `background` returns several colors. @default 'vertical' */
   gradientDirection?: GradientDirection;
-  /** @default 'horizontal' */
+  /** Direction of the swipe. @default 'horizontal' */
   orientation?: SlidesOrientation;
-  /** Círculos, círculos numerados, o ninguno. @default 'dots' */
+  /** Dots, numbered dots, or none. @default 'dots' */
   indicators?: SlidesIndicators;
   /**
-   * 'overlay' los apoya sobre la slide, en blanco; 'outside' los saca fuera
-   * del área deslizable, con los colores del tema.
+   * 'overlay' places them on the slide, in white; 'outside' moves them out of
+   * the swipeable area, in theme colors.
    * @default 'overlay'
    */
   indicatorPlacement?: SlidesIndicatorPlacement;
-  /** Después de la última vuelve a la primera (y al revés). @default false */
+  /** After the last slide, wraps to the first (and vice versa). @default false */
   loop?: boolean;
-  /** Avanza solo. Se pausa mientras el dedo arrastra. @default false */
+  /** Advances automatically. Pauses while a finger is dragging. @default false */
   autoPlay?: boolean;
-  /** ms entre avances de `autoPlay`. @default 4000 */
+  /** Milliseconds between `autoPlay` advances. @default 4000 */
   interval?: number;
   /**
-   * Botón para frenar el avance automático. Sólo aparece con `autoPlay`, y va
-   * en `true` porque contenido que se mueve solo necesita una forma de
-   * pausarlo (WCAG 2.2.2).
+   * Button that pauses auto-advance. Only shown with `autoPlay`; on by default
+   * because content that moves on its own needs a way to pause it
+   * (WCAG 2.2.2).
    * @default true
    */
   showAutoPlayToggle?: boolean;
-  /** Hueco entre slides, en px. En 0 quedan pegadas. @default 0 */
+  /** Gap between slides, in px. At 0 they touch. @default 0 */
   spacing?: number;
-  /** Índice controlado. Sin él, el componente maneja el suyo desde `defaultIndex`. */
+  /** Controlled index. Without it, the component manages its own from `defaultIndex`. */
   index?: number;
-  /** @default 0 */
+  /** Starting slide when the index is uncontrolled. @default 0 */
   defaultIndex?: number;
+  /** Called with the new index when the active slide changes. */
   onIndexChange?: (index: number) => void;
-  /** Alto del área deslizable. @default 240 */
+  /** Height of the swipeable area. @default 240 */
   height?: number;
-  /** @default true */
+  /**
+   * Lets the user swipe between slides. When false, they change only through the indicators,
+   * `autoPlay` or `index`. @default true
+   */
   swipeEnabled?: boolean;
-  /** Estilos de la caja visible de cada slide — padding, alineación, radio. */
+  /** Styles for each slide's visible box — padding, alignment, radius. */
   slideStyle?: StyleProp<ViewStyle>;
   style?: StyleProp<ViewStyle>;
   testID?: string;
@@ -80,15 +86,15 @@ const DEFAULT_HEIGHT = 240;
 const DEFAULT_INTERVAL = 4000;
 
 const useStyles = createStyles((theme) => ({
-  // Deja redondear el bloque por `style` sin que el degradado se salga.
+  // Lets the block be rounded via `style` without the gradient spilling out.
   root: { overflow: 'hidden' },
   viewport: { flex: 1 },
-  // La slide visible es la caja de adentro: con `spacing` la página es más
-  // ancha que ella, y el fondo tiene que recortarse acá y no en la página, o
-  // el degradado pinta también el hueco.
+  // The visible slide is the inner box: with `spacing` the page is wider
+  // than it, and the background has to be clipped here and not on the page, or
+  // the gradient paints the gap too.
   slide: { flex: 1, overflow: 'hidden' },
-  // Con indicadores fuera y orientación vertical el contenedor es una fila:
-  // sin flex la ventana no tiene ancho propio y colapsa a 0.
+  // With indicators outside and vertical orientation the container is a row:
+  // without flex the window has no width of its own and collapses to 0.
   viewportInRow: { flex: 1 },
   slideContent: { flex: 1 },
 
@@ -115,7 +121,7 @@ const useStyles = createStyles((theme) => ({
     gap: 3,
   },
   pauseBar: { width: 3, height: 12, borderRadius: 1 },
-  // Triángulo con bordes: un "play" sin SVG ni set de íconos.
+  // Triangle made of borders: a "play" without SVG or an icon set.
   playTriangle: {
     width: 0,
     height: 0,
@@ -145,7 +151,7 @@ const useStyles = createStyles((theme) => ({
 interface DotProps {
   selected: boolean;
   isHorizontal: boolean;
-  /** En overlay el contraste lo da la opacidad; afuera, el color. */
+  /** In overlay the contrast comes from opacity; outside, from color. */
   overlay: boolean;
   activeColor: string;
   inactiveColor: string;
@@ -153,9 +159,9 @@ interface DotProps {
 }
 
 /**
- * El punto activo se estira en vez de saltar: el cambio de golpe se lee como
- * "apareció otro punto", no como "el mismo se movió". Ancho y color son props
- * de layout/pintura, así que van por el driver de JS.
+ * The active dot stretches instead of jumping: an abrupt change reads as
+ * "another dot appeared", not as "the same one moved". Width and color are
+ * layout/paint props, so they go through the JS driver.
  */
 const Dot = memo(({ selected, isHorizontal, overlay, activeColor, inactiveColor, testID }: DotProps) => {
   const styles = useStyles();
@@ -191,13 +197,25 @@ Dot.displayName = 'SlidesDot';
 
 /**
  * Slides
- * Carrusel con fondo propio (color plano o degradado) y contenido libre:
- * `renderItem` decide si adentro va una imagen, texto o botones. El estado
- * vive en `useSlides`; acá sólo está el árbol.
+ * Carousel with its own background (flat color or gradient) and free-form
+ * content: `renderItem` decides whether an image, text or buttons go inside.
+ * The state lives in `useSlides`; only the tree is here.
+ *
+ * Sliding is a `ScrollView` with `pagingEnabled` instead of hand-made
+ * gestures: it is the only thing that gives native snapping on iOS and
+ * Android without `react-native-gesture-handler`, across the whole supported
+ * range of Expo SDKs.
  *
- * El deslizamiento es un `ScrollView` con `pagingEnabled` en vez de gestos a
- * mano: es lo único que da snap nativo en iOS y Android sin
- * `react-native-gesture-handler`, en todo el rango soportado (Expo SDK 54–57).
+ * Design:
+ * - Jakob's law: native paging swipe and dots under the slide, like the
+ *   system's own onboarding carousels.
+ * - Similarity + Von Restorff: every indicator looks the same except the
+ *   current one.
+ * - Continuity: the slides slide (a jump with Reduce Motion, and autoPlay
+ *   stops); infinite mode clones the edges so the swipe never rewinds.
+ * - Fitts's law: indicators have padding around the dot as touch area.
+ * - Screen readers: each indicator is "Slide n of total" (`labels.slideOf`),
+ *   and autoPlay can be paused from its own button.
  */
 export function Slides<T>({
   data,
@@ -223,6 +241,7 @@ export function Slides<T>({
   testID,
 }: SlidesProps<T>) {
   const colors = useColors();
+  const labels = useLabels();
   const styles = useStyles();
   const allowFontScaling = useAllowFontScaling();
 
@@ -296,7 +315,7 @@ export function Slides<T>({
     );
   };
 
-  // Con reduce-motion el autoPlay ya está apagado: no hay nada que pausar.
+  // With reduce-motion autoPlay is already off: there is nothing to pause.
   const renderAutoPlayToggle = () => {
     if (!autoPlay || !showAutoPlayToggle || motionReduced || total < 2) return null;
     return (
@@ -306,7 +325,7 @@ export function Slides<T>({
         activeOpacity={0.7}
         onPress={toggleAutoPlay}
         accessibilityRole="button"
-        accessibilityLabel={autoPlayPaused ? 'Resume automatic slides' : 'Pause automatic slides'}
+        accessibilityLabel={autoPlayPaused ? labels.resumeSlides : labels.pauseSlides}
         accessibilityState={{ selected: !autoPlayPaused }}
       >
         {autoPlayPaused ? (
@@ -346,7 +365,7 @@ export function Slides<T>({
             activeOpacity={0.7}
             onPress={() => goTo(position)}
             accessibilityRole="button"
-            accessibilityLabel={`Slide ${position + 1} of ${total}`}
+            accessibilityLabel={labels.slideOf.replace('{n}', String(position + 1)).replace('{total}', String(total))}
             accessibilityState={{ selected: position === active }}
           >
             {renderIndicator(position)}
@@ -379,9 +398,9 @@ export function Slides<T>({
           pages.map(({ real, clone }) => {
             const item = data[real] as T;
             return (
-              // El hueco se reparte a los dos lados de cada página: así la
-              // separación entre dos slides es `spacing` entero y la página
-              // sigue midiendo exactamente lo que pagina el ScrollView.
+              // The gap is split on both sides of each page: that way the
+              // separation between two slides is a full `spacing` and the page
+              // still measures exactly what the ScrollView pages by.
               <View
                 key={clone ? `slides-clone-${clone}` : keyExtractor(item, real)}
                 style={[

package/src/organisms/ThemeToggle.tsx

@@ -1,29 +1,38 @@
 import React, { memo, useMemo } from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
-import { useThemeMode, type ThemeMode } from '../theme/UIProvider';
+import { useLabels, useThemeMode, type ThemeMode } from '../theme/UIProvider';
 import { SegmentedControl } from '../molecules/SegmentedControl';
 
 export interface ThemeToggleProps {
   style?: StyleProp<ViewStyle>;
+  /** Text of each segment; any mode left out keeps its default (`labels.themeSystem`, `themeLight`, `themeDark`). */
   labels?: Partial<Record<ThemeMode, string>>;
   testID?: string;
 }
 
 const MODES: ThemeMode[] = ['system', 'light', 'dark'];
-const DEFAULT_LABELS: Record<ThemeMode, string> = { system: 'Auto', light: 'Light', dark: 'Dark' };
 
 /**
  * ThemeToggle
- * Conecta un SegmentedControl con UIProvider.setMode. Sin persistencia — el
- * consumidor la resuelve vía onModeChange en <UIProvider>.
+ * Connects a SegmentedControl to UIProvider.setMode. No persistence — the
+ * consumer handles it via onModeChange on <UIProvider>.
+ *
+ * Design: Jakob's law — the same Auto / Light / Dark choice as the system
+ * settings, in that order; Hick's law — three options, nothing to configure.
  */
 export const ThemeToggle = memo(({ style, labels: labelOverrides, testID }: ThemeToggleProps) => {
   const { mode, setMode } = useThemeMode();
+  const providerLabels = useLabels();
 
   const options = useMemo(() => {
-    const labels = { ...DEFAULT_LABELS, ...labelOverrides };
+    const labels: Record<ThemeMode, string> = {
+      system: providerLabels.themeSystem,
+      light: providerLabels.themeLight,
+      dark: providerLabels.themeDark,
+      ...labelOverrides,
+    };
     return MODES.map((value) => ({ value, label: labels[value] }));
-  }, [labelOverrides]);
+  }, [labelOverrides, providerLabels]);
 
   return <SegmentedControl options={options} value={mode} onChange={setMode} style={style} testID={testID} />;
 });

package/src/organisms/Timeline.tsx

@@ -10,15 +10,15 @@ import type { IconName } from '../icons/types';
 export type TimelineStatus = 'done' | 'pending';
 
 /**
- * Qué puede hacer un toque.
- * - 'free': cualquier hito responde y la línea sigue a `items` para donde
- *   vaya, adelante o atrás. Es el que sirve cuando el recorrido no es un
- *   progreso, o cuando lo maneja otra cosa.
- * - 'sequential': sólo responde el que sigue al alcanzado, y la línea no
- *   retrocede nunca. Avance estricto.
- * - 'revisit': responden el que sigue y todos los ya alcanzados, y la línea
- *   tampoco retrocede. Es el caso de "puedo volver a mirar lo anterior sin
- *   perder lo que llevo".
+ * What a tap can do.
+ * - 'free': any milestone responds and the line follows `items` wherever it
+ *   goes, forward or back. It is the one to use when the path isn't
+ *   progress, or when something else drives it.
+ * - 'sequential': only the one after the reached milestone responds, and the
+ *   line never goes back. Strict progression.
+ * - 'revisit': the next one and all those already reached respond, and the
+ *   line doesn't go back either. It is the "I can look at what came before
+ *   without losing my progress" case.
  */
 export type TimelineAdvance = 'free' | 'sequential' | 'revisit';
 
@@ -33,6 +33,7 @@ export interface TimelineItem {
 }
 
 export interface TimelineProps {
+  /** The milestones, in order. Each has a label, optionally an icon or emoji, and its status. */
   items: TimelineItem[];
   /** Pixels the line bows away from the straight path. 0 draws it straight. @default 28 */
   curve?: number;
@@ -71,24 +72,24 @@ const DEFAULT_CURVE = 28;
 const DEFAULT_SPACING = 84;
 const NODE = 14;
 const LINE = 2;
-/** Tramos rectos por cada vano: con menos, la curva se ve poligonal. */
+/** Straight segments per span: with fewer, the curve looks polygonal. */
 const SEGMENTS = 14;
 const DOT = 3;
-/** Un punto cada cuántos tramos: el camino entero va punteado por debajo. */
+/** One dot every how many segments: the whole path is dotted underneath. */
 const DOT_EVERY = 2;
 const DEFAULT_DURATION = 420;
 /**
- * Cuánto tarda un tramo en encenderse, medido en hitos. Chico para que el
- * frente de la línea se lea como un borde y no como un degradado largo.
+ * How long a segment takes to light up, measured in milestones. Small so the
+ * front of the line reads as an edge and not as a long gradient.
  */
 const FADE = 0.06;
 /**
- * Capas del halo, de afuera hacia adentro. Son muchas y muy tenues a
- * propósito: con tres capas se ven los anillos, que es justo lo contrario de
- * un difuminado. Cuantos más escalones y más chico el salto de opacidad, más
- * cerca queda de un degradado.
+ * Halo layers, from the outside in. There are many and very faint on
+ * purpose: with three layers you see the rings, which is exactly the opposite
+ * of a blur. The more steps and the smaller the opacity jump, the closer it
+ * gets to a gradient.
  */
-/** Lo que el halo sobresale de la píldora: es lo que hay que dejarle de aire. */
+/** How far the halo sticks out of the pill: that is the room it needs. */
 const GLOW_BLEED = 20;
 const GLOW_LAYERS = [
   { inset: -GLOW_BLEED, opacity: 0.03 },
@@ -113,7 +114,7 @@ const useStyles = createStyles((theme) => ({
     borderWidth: LINE,
   },
   nodePending: { backgroundColor: 'transparent', borderColor: theme.colors.border },
-  // Ocupa el círculo entero menos el borde, así el relleno no lo tapa.
+  // Takes the whole circle minus the border, so the fill doesn't cover it.
   nodeFill: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, borderRadius: NODE / 2 },
   pill: {
     flexDirection: 'row',
@@ -124,10 +125,10 @@ const useStyles = createStyles((theme) => ({
     borderRadius: theme.tokens.radius.full,
     borderWidth: 1,
     borderColor: theme.colors.border,
-    backgroundColor: theme.colors.surface,
+    backgroundColor: theme.colors.surfaceRaised,
   },
-  // El foco se marca con el borde, no con el relleno: el relleno ya está
-  // diciendo otra cosa (si el hito está alcanzado o no).
+  // Focus is marked with the border, not the fill: the fill is already
+  // saying something else (whether the milestone has been reached or not).
   pillSelected: { borderColor: theme.colors.primary, borderWidth: 2 },
   label: { fontSize: theme.tokens.fontSize.md, color: theme.colors.text },
   labelPending: { color: theme.colors.textLight },
@@ -137,29 +138,45 @@ const useStyles = createStyles((theme) => ({
     borderRadius: theme.tokens.radius.full,
     backgroundColor: theme.colors.text,
   },
-  // La línea y los nodos viven en la misma capa y se posicionan con las mismas
-  // coordenadas. Es lo único que garantiza que el círculo caiga sobre la
-  // curva: en el flujo de la fila el nodo lo corre el flex —y los paddings que
-  // cada lado necesita para no cortar su píldora—, así que terminaba a un
-  // costado de la línea en vez de encima.
+  // The line and the nodes live in the same layer and are positioned with the
+  // same coordinates. It is the only thing that guarantees the circle lands on
+  // the curve: in the row's flow the node gets shifted by flex —and by the
+  // paddings each side needs so its pill isn't clipped—, so it ended up to one
+  // side of the line instead of on top of it.
   lineLayer: { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0, alignItems: 'center' },
-  // Hueco del ancho del nodo en la fila: la píldora se separa del centro lo
-  // mismo que antes, pero el círculo ya no se dibuja acá.
+  // Gap the width of the node in the row: the pill is set apart from the
+  // center the same as before, but the circle is no longer drawn here.
   nodeSlot: { width: NODE },
   segment: { position: 'absolute', width: LINE },
   dot: { position: 'absolute', width: DOT, height: DOT, borderRadius: DOT / 2 },
 }));
 
 /**
- * Desvío horizontal del nodo `index` respecto del eje. Una onda entera a lo
- * largo de la lista: el primero y el último caen sobre el eje, y los del medio
- * se van a un lado y al otro. Es lo que convierte una columna en un camino.
+ * Horizontal offset of node `index` from the axis. One full wave along the
+ * list: the first and the last fall on the axis, and the ones in the middle
+ * swing to one side and the other. It is what turns a column into a path.
  */
 function offsetAt(index: number, count: number, curve: number): number {
   if (count < 2) return 0;
   return curve * Math.sin((2 * Math.PI * index) / (count - 1));
 }
 
+/**
+ * Timeline
+ * Milestones on a path: a line that bows from one to the next and fills up to
+ * the last one reached, with each label in a pill on alternating sides.
+ *
+ * Design:
+ * - Continuity (Gestalt): one curved line joins the milestones, so they read
+ *   as a single path; the reached part of it is filled.
+ * - Similarity + figure/ground: reached and pending milestones differ only by
+ *   fill, so status reads at a glance.
+ * - Common fate: when a milestone is reached the line travels there, gap by
+ *   gap (in place with Reduce Motion).
+ * - Fitts's law: with `onItemPress` the whole pill is the target.
+ * - Screen readers: each milestone is checked or not; with `onItemPress` it
+ *   is a button, disabled when `advance` doesn't let it respond.
+ */
 export const Timeline = memo(
   ({
     items,
@@ -182,9 +199,9 @@ export const Timeline = memo(
     const count = items.length;
 
     /**
-     * Hasta dónde llegó el recorrido, en unidades de hito. Se cuenta desde el
-     * principio y se corta en el primer pendiente: un hito cumplido después de
-     * uno que no lo está no adelanta la línea, porque el camino es un camino.
+     * How far the path has gotten, in milestone units. It is counted from the
+     * start and cut at the first pending one: a milestone completed after one
+     * that isn't doesn't move the line forward, because a path is a path.
      */
     const reached = useMemo(() => {
       let last = -1;
@@ -196,9 +213,9 @@ export const Timeline = memo(
     }, [items]);
 
     /**
-     * Marca de agua: salvo en 'free', la línea se queda en lo más lejos que
-     * llegó. El progreso es del usuario, no del render — que el padre mande
-     * una lista más corta no puede desandar lo que ya recorrió.
+     * High-water mark: except in 'free', the line stays at the furthest point
+     * it reached. Progress belongs to the user, not the render — the parent
+     * sending a shorter list can't undo the distance already covered.
      */
     const furthest = useRef(reached);
     if (advance === 'free') furthest.current = reached;
@@ -210,8 +227,8 @@ export const Timeline = memo(
     useEffect(() => {
       const animation = Animated.timing(progress, {
         toValue: lineTo,
-        // Un hito por `duration`: avanzar tres de una vez tarda tres veces
-        // más, así se ve el recorrido y no un salto.
+        // One milestone per `duration`: advancing three at once takes three
+        // times longer, so you see the path and not a jump.
         duration: reduceMotion ? 0 : duration,
         easing: Easing.inOut(Easing.cubic),
         useNativeDriver: true,
@@ -221,10 +238,10 @@ export const Timeline = memo(
     }, [lineTo, duration, reduceMotion, progress]);
 
     /**
-     * Cada vano partido en tramos rectos cortos, cada uno con su largo y su
-     * ángulo. Es la misma idea que `Gradient`: la plataforma no tiene curvas
-     * sin dependencia nativa, así que la curva se compone con pedazos rectos
-     * lo bastante chicos como para que el ojo no vea el quiebre.
+     * Each span split into short straight segments, each with its own length
+     * and angle. It is the same idea as `Gradient`: the platform has no curves
+     * without a native dependency, so the curve is composed from straight
+     * pieces small enough for the eye not to see the break.
      */
     const pieces = useMemo(() => {
       const out: {
@@ -254,11 +271,11 @@ export const Timeline = memo(
             x: (x1 + x2) / 2,
             y: (y1 + y2) / 2,
             length,
-            // El tramo se dibuja vertical y se gira hasta la pendiente: el
-            // ángulo se mide desde el eje Y, no desde el X.
+            // The segment is drawn vertically and rotated to the slope: the
+            // angle is measured from the Y axis, not the X.
             angle: `${Math.atan2(dx, dy) * (180 / Math.PI) * -1}deg`,
-            // Posición del tramo medida en hitos: es la misma escala que
-            // `progress`, así que comparar una cosa con la otra es directo.
+            // Segment position measured in milestones: it is the same scale as
+            // `progress`, so comparing one with the other is direct.
             at: to,
             dotted: step % DOT_EVERY === 0,
           });
@@ -280,7 +297,7 @@ export const Timeline = memo(
         testID={testID}
       >
         <View style={styles.lineLayer} pointerEvents="none">
-          {/* El camino entero, punteado: es lo que falta recorrer. */}
+          {/* The whole path, dotted: it is what is left to travel. */}
           {pieces.map(
             (piece) =>
               piece.dotted && (
@@ -298,9 +315,9 @@ export const Timeline = memo(
               )
           )}
 
-          {/* Y encima la línea llena, que se revela tramo a tramo a medida que
-              `progress` avanza. Lo único que cambia por frame es `opacity`, o
-              sea que el recorrido se dibuja en el hilo nativo. */}
+          {/* And on top the solid line, revealed segment by segment as
+              `progress` advances. The only thing that changes per frame is
+              `opacity`, which means the path is drawn on the native thread. */}
           {pieces.map((piece) => (
             <Animated.View
               key={`line-${piece.key}`}
@@ -333,8 +350,8 @@ export const Timeline = memo(
                 },
               ]}
             >
-              {/* El relleno es un nodo aparte encima del hueco: el color no se
-                  puede animar en el hilo nativo, la opacidad sí. */}
+              {/* The fill is a separate node on top of the hollow: color can't
+                  be animated on the native thread, opacity can. */}
               <Animated.View
                 style={[
                   styles.nodeFill,
@@ -365,10 +382,10 @@ export const Timeline = memo(
           const pending = item.status === 'pending';
           const onRight = (index % 2 === 0) === (startSide === 'right');
           const offset = offsetAt(index, count, curve);
-          // La fila entera se corre con la curva, píldora incluida, así que el
-          // lado hacia el que se fue pierde ese espacio contra el borde. Se lo
-          // devolvemos como padding, más lo que sobresale el halo: sin esto la
-          // píldora de más afuera queda cortada al ras.
+          // The whole row shifts with the curve, pill included, so the side it
+          // moved toward loses that space against the edge. We give it back as
+          // padding, plus what the halo sticks out: without this the outermost
+          // pill gets clipped flush.
           const bleed = glow ? GLOW_BLEED : 0;
           const roomLeft = Math.max(0, -offset) + bleed;
           const roomRight = Math.max(0, offset) + bleed;
@@ -409,10 +426,10 @@ export const Timeline = memo(
             </View>
           );
 
-          // 'sequential' deja tocar sólo el que sigue; 'revisit' también los
-          // ya recorridos. El que no responde se marca como deshabilitado en
-          // vez de quedarse mudo: un botón que no hace nada y no lo dice es
-          // peor que un botón apagado.
+          // 'sequential' only allows tapping the next one; 'revisit' also the
+          // ones already covered. The one that doesn't respond is marked as
+          // disabled instead of staying silent: a button that does nothing
+          // and doesn't say so is worse than a disabled button.
           const reachable =
             advance === 'sequential'
               ? index === lineTo + 1