orn-ui 0.2.9 → 0.3.0

package/src/atoms/Input.tsx

@@ -1,5 +1,6 @@
-import React, { memo, useRef, useState } from 'react';
+import React, { forwardRef, memo, useEffect, useImperativeHandle, useRef, useState, type ComponentRef } from 'react';
 import {
+  AccessibilityInfo,
   ActivityIndicator,
   Animated,
   Text,
@@ -11,21 +12,51 @@ import {
   type ViewStyle,
 } from 'react-native';
 import { createStyles } from '../theme/createStyles';
-import { useAllowFontScaling, useColors } from '../theme/UIProvider';
+import { useAllowFontScaling, useColors, useLabels, useTheme } from '../theme/UIProvider';
 import { Icon } from '../icons/Icon';
 import type { IconName } from '../icons/types';
+import { useKeyboardField } from '../theme/useKeyboardField';
+import { validateInputValue, type InputRules } from './inputValidation';
+
+export type { InputRules, InputRuleValue } from './inputValidation';
+
+/** The TextInput instance, plus `validate()` to check the field on demand (e.g. on submit). */
+export type InputHandle = ComponentRef<typeof TextInput> & {
+  /** Runs the rules, shows the error (if any) and returns it. */
+  validate: () => string | undefined;
+};
 
 export interface InputProps extends Omit<TextInputProps, 'style'> {
+  /** Text above the field; also its accessible name (falls back to `placeholder`). */
   label?: string;
-  /** Shows an asterisk next to the label. Purely visual, doesn't validate anything. */
+  /** Shows an asterisk next to the label, and an empty value fails validation (`labels.requiredError`). */
   required?: boolean;
+  /** Error shown under the field. Takes precedence over the built-in validation. */
   error?: string;
+  /** Built-in validation: length limits, a pattern and/or a custom check. */
+  rules?: InputRules;
+  /**
+   * When the rules run: on leaving the field, on every change, or only through
+   * `ref.validate()`. Once an error shows, it re-checks on every change so it
+   * clears as soon as the value is fixed. @default 'blur'
+   */
+  validateOn?: 'blur' | 'change' | 'submit';
+  /** Called with the error (or undefined) every time the rules run. */
+  onValidate?: (error: string | undefined) => void;
+  /** Style of the outer wrapper (label, field and error). */
   containerStyle?: StyleProp<ViewStyle>;
   style?: TextInputProps['style'];
+  /** Icon shown inside the field, to the left of the text. */
   leftIconName?: IconName;
+  /** Icon button inside the field, on the right. Ignored with `isPassword` or `isLoading`. */
   rightIconName?: IconName;
+  /** Called when the `rightIconName` button is pressed. Without it the button is disabled. */
   onRightIconPress?: () => void;
+  /** Accessible name of the `rightIconName` button. @default labels.clear */
+  rightIconAccessibilityLabel?: string;
+  /** Hides the text and adds an eye button to show or hide it. @default false */
   isPassword?: boolean;
+  /** Shows a small spinner on the right, in place of the right icon. @default false */
   isLoading?: boolean;
 }
 
@@ -54,25 +85,57 @@ const useStyles = createStyles((theme) => ({
     color: theme.colors.text,
   },
   leftIcon: { marginLeft: theme.tokens.spacing.lg, marginRight: -theme.tokens.spacing.xs },
-  rightIcon: { padding: theme.tokens.spacing.sm + 2, marginRight: theme.tokens.spacing.xs },
+  // 20 icon + md padding (12) per side = 44pt touch area (Fitts).
+  rightIcon: { padding: theme.tokens.spacing.md, marginRight: theme.tokens.spacing.xxs },
+  // Read-only: no fill, so it doesn't look like a field you can tap
+  // (affordance), but the text keeps its contrast to stay readable.
+  readOnly: { backgroundColor: 'transparent' },
   errorText: { marginTop: theme.tokens.spacing.xs, fontSize: theme.tokens.fontSize.sm, color: theme.colors.errorText },
 }));
 
 /**
  * Input
- * El borde anima color entre border/primary/error con Animated (no
- * useNativeDriver: los navegadores de color en RN sin Fabric solo son
- * confiables en el hilo de JS; el costo es despreciable, se anima un borde).
+ * The border animates its color between border/primary/error with Animated
+ * (no useNativeDriver: color drivers in RN without Fabric are only reliable
+ * on the JS thread; the cost is negligible, it animates one border).
+ *
+ * Gestalt:
+ * - Proximity: label (`spacing.sm` above) and error (`spacing.xs` below) sit
+ *   right next to the field and the next field is `spacing.lg` away: each
+ *   label and its error read with their field, not with the neighbor.
+ * - Common region: left icon, text and right action share the same border
+ *   and background, so they read as a single control.
+ * - Focal point: the border turns `primary` on focus and `error` on error;
+ *   the error is also written out (not just color).
+ *
+ * Accessibility: the accessible name includes "required" when applicable, the
+ * error is announced as a hint, and the eye and right-action buttons have a
+ * 44pt touch area and texts from `labels` (translatable).
+ *
+ * Keyboard: on focus it registers with the root UIProvider's host, which
+ * lifts the app just enough for the whole field (label, field and error) to
+ * sit above the keyboard — without depending on Screen or a ScrollView. What
+ * you type is always visible.
+ *
+ * Validation: `required` and `rules` run when leaving the field (`validateOn`),
+ * the error appears in writing, is announced to the screen reader and, once
+ * visible, is revalidated on every change so it disappears as soon as it is
+ * fixed. An `error` passed by hand overrides the internal validation.
  */
 export const Input = memo(
-  ({
+  forwardRef<InputHandle, InputProps>(({
     label,
     required = false,
-    error,
+    error: errorProp,
+    rules,
+    validateOn = 'blur',
+    onValidate,
+    onChangeText,
     containerStyle,
     leftIconName,
     rightIconName,
     onRightIconPress,
+    rightIconAccessibilityLabel,
     isPassword = false,
     isLoading = false,
     style,
@@ -80,43 +143,85 @@ export const Input = memo(
     onBlur,
     testID,
     ...props
-  }: InputProps) => {
+  }, ref) => {
     const colors = useColors();
     const styles = useStyles();
     const allowFontScaling = useAllowFontScaling();
+    const labels = useLabels();
+    const theme = useTheme();
+    const readOnly = props.editable === false;
     const [isFocused, setIsFocused] = useState(false);
     const [showPassword, setShowPassword] = useState(false);
     const focusProgress = useRef(new Animated.Value(0)).current;
+    const inputRef = useRef<ComponentRef<typeof TextInput>>(null);
+    const containerRef = useRef<ComponentRef<typeof View>>(null);
+    const [internalError, setInternalError] = useState<string | undefined>(undefined);
+    // Last known value: the controlled one (`value`) or what was typed (uncontrolled).
+    const valueRef = useRef(props.value ?? props.defaultValue ?? '');
+    if (props.value !== undefined) valueRef.current = props.value;
+    const error = errorProp ?? internalError;
+
+    const runValidation = () => {
+      const next = validateInputValue(valueRef.current, { required, rules }, labels);
+      setInternalError(next);
+      onValidate?.(next);
+      return next;
+    };
+
+    useImperativeHandle(ref, () => Object.assign(inputRef.current as ComponentRef<typeof TextInput>, { validate: runValidation }));
+
+    // The new error is announced right away, not only as a hint when returning to the field.
+    useEffect(() => {
+      if (internalError && errorProp === undefined) AccessibilityInfo.announceForAccessibility(internalError);
+    }, [internalError, errorProp]);
+
+    const keyboard = useKeyboardField(containerRef);
+
+    // If the error appears or changes while the field is focused, the block grows:
+    // a readjustment is requested so the error line isn't covered either.
+    useEffect(() => {
+      if (isFocused) keyboard.focus();
+    }, [error, isFocused, keyboard]);
 
     const handleFocus: TextInputProps['onFocus'] = (e) => {
       setIsFocused(true);
-      Animated.timing(focusProgress, { toValue: 1, duration: 200, useNativeDriver: false }).start();
+      keyboard.focus();
+      Animated.timing(focusProgress, { toValue: 1, duration: theme.tokens.duration.base, useNativeDriver: false }).start();
       onFocus?.(e);
     };
 
     const handleBlur: TextInputProps['onBlur'] = (e) => {
       setIsFocused(false);
-      Animated.timing(focusProgress, { toValue: 0, duration: 200, useNativeDriver: false }).start();
+      keyboard.blur();
+      if (validateOn === 'blur') runValidation();
+      Animated.timing(focusProgress, { toValue: 0, duration: theme.tokens.duration.base, useNativeDriver: false }).start();
       onBlur?.(e);
     };
 
+    const handleChangeText = (text: string) => {
+      valueRef.current = text;
+      onChangeText?.(text);
+      if (validateOn === 'change' || internalError) runValidation();
+    };
+
     const borderColor = error
       ? colors.error
       : focusProgress.interpolate({ outputRange: [colors.border, colors.primary], inputRange: [0, 1] });
 
     return (
-      <View style={[styles.container, containerStyle]} testID={testID}>
-        {label && (
+      <View ref={containerRef} style={[styles.container, containerStyle]} testID={testID}>
+        {!!label && (
           <Text allowFontScaling={allowFontScaling} style={styles.label}>
             {label}
             {required && <Text style={styles.required}> *</Text>}
           </Text>
         )}
 
-        <Animated.View style={[styles.inputWrapper, { borderColor }]}>
+        <Animated.View style={[styles.inputWrapper, readOnly && styles.readOnly, { borderColor }]}>
           {leftIconName && <Icon name={leftIconName} size={20} color={colors.textLight} style={styles.leftIcon} />}
 
           <TextInput
+            ref={inputRef}
             style={[styles.input, style]}
             placeholderTextColor={colors.textLight}
             onFocus={handleFocus}
@@ -124,8 +229,13 @@ export const Input = memo(
             secureTextEntry={isPassword && !showPassword}
             allowFontScaling={allowFontScaling}
             textAlignVertical="center"
-            accessibilityLabel={label ?? props.placeholder}
+            accessibilityLabel={
+              label || props.placeholder ? `${label ?? props.placeholder}${required ? `, ${labels.required}` : ''}` : undefined
+            }
+            accessibilityHint={error || undefined}
+            accessibilityState={{ disabled: readOnly, busy: isLoading }}
             {...props}
+            onChangeText={handleChangeText}
           />
 
           {isLoading ? (
@@ -137,7 +247,7 @@ export const Input = memo(
               onPress={() => setShowPassword((v) => !v)}
               style={styles.rightIcon}
               accessibilityRole="button"
-              accessibilityLabel={showPassword ? 'Hide password' : 'Show password'}
+              accessibilityLabel={showPassword ? labels.hidePassword : labels.showPassword}
             >
               <Icon name={showPassword ? 'eye-off' : 'eye'} size={20} color={colors.textLight} />
             </TouchableOpacity>
@@ -147,7 +257,7 @@ export const Input = memo(
               style={styles.rightIcon}
               disabled={!onRightIconPress}
               accessibilityRole="button"
-              accessibilityLabel="Clear"
+              accessibilityLabel={rightIconAccessibilityLabel ?? labels.clear}
             >
               <Icon name={rightIconName} size={20} color={colors.textLight} />
             </TouchableOpacity>
@@ -161,6 +271,6 @@ export const Input = memo(
         )}
       </View>
     );
-  }
+  })
 );
 Input.displayName = 'Input';

package/src/atoms/KeyValueRow.tsx

@@ -4,45 +4,89 @@ import { createStyles } from '../theme/createStyles';
 import { useAllowFontScaling } from '../theme/UIProvider';
 
 export interface KeyValueRowProps {
+  /** Left side. A string or number gets the default label style; any other node renders as is. */
   label: React.ReactNode;
+  /** Right side. A string or number gets the default value style (tabular digits); any other node renders as is. */
   value: React.ReactNode;
   style?: StyleProp<ViewStyle>;
+  /** Only applies when `label` is a string or number. */
   labelStyle?: StyleProp<TextStyle>;
+  /** Only applies when `value` is a string or number. */
   valueStyle?: StyleProp<TextStyle>;
+  testID?: string;
 }
 
 const useStyles = createStyles((theme) => ({
-  row: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' },
-  label: { fontSize: theme.tokens.fontSize.sm, fontWeight: theme.tokens.fontWeight.semibold, color: theme.colors.textLight },
-  value: { fontSize: theme.tokens.fontSize.sm, textAlign: 'right', color: theme.colors.text },
+  row: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+    gap: theme.tokens.spacing.md,
+  },
+  // Two texts: aligned on the first line, so a value that wraps onto
+  // several lines still reads next to its label.
+  rowText: { alignItems: 'baseline' },
+  // The label keeps its natural width up to half the row; the value
+  // shrinks and wraps instead of pushing the row off the screen.
+  label: {
+    flexShrink: 0,
+    maxWidth: '50%',
+    fontSize: theme.tokens.fontSize.sm,
+    lineHeight: theme.tokens.lineHeight.sm,
+    fontWeight: theme.tokens.fontWeight.semibold,
+    color: theme.colors.textLight,
+  },
+  value: {
+    flexShrink: 1,
+    fontSize: theme.tokens.fontSize.sm,
+    lineHeight: theme.tokens.lineHeight.sm,
+    textAlign: 'right',
+    color: theme.colors.text,
+    // Fixed-width digits: in a column of amounts the figures line up
+    // across rows.
+    fontVariant: ['tabular-nums'],
+  },
 }));
 
+const isPrimitive = (node: React.ReactNode): node is string | number =>
+  typeof node === 'string' || typeof node === 'number';
+
 /**
  * KeyValueRow
- * Fila label (izquierda) / value (derecha). Si label/value son string o
- * number, se renderizan con el estilo default; si ya vienen envueltos en un
- * componente de texto propio, se respetan tal cual.
+ * Label (left) / value (right) row. If label/value are a string or number,
+ * they render with the default style; if they already come wrapped in a
+ * custom component, they are kept as is.
+ *
+ * Gestalt, alignment and similarity: labels share color and weight and values
+ * align to the right edge with tabular digits, so a stack of rows reads as
+ * two columns — what on the left, how much on the right.
+ * With a text label and value, the row is a single accessibility node
+ * ("Subtotal, $300.00"); if either is a custom node (a Badge, a button) it
+ * isn't merged, so as not to hide what that node announces or lets you tap.
  */
-export const KeyValueRow = memo(({ label, value, style, labelStyle, valueStyle }: KeyValueRowProps) => {
-  const styles = useStyles();
-  const allowFontScaling = useAllowFontScaling();
-  return (
-    <View style={[styles.row, style]}>
-      {typeof label === 'string' || typeof label === 'number' ? (
-        <Text allowFontScaling={allowFontScaling} style={[styles.label, labelStyle]}>
-          {label}
-        </Text>
-      ) : (
-        label
-      )}
-      {typeof value === 'string' || typeof value === 'number' ? (
-        <Text allowFontScaling={allowFontScaling} style={[styles.value, valueStyle]}>
-          {value}
-        </Text>
-      ) : (
-        value
-      )}
-    </View>
-  );
-});
+export const KeyValueRow = memo(
+  ({ label, value, style, labelStyle, valueStyle, testID }: KeyValueRowProps) => {
+    const styles = useStyles();
+    const allowFontScaling = useAllowFontScaling();
+    const merge = isPrimitive(label) && isPrimitive(value);
+    return (
+      <View style={[styles.row, merge && styles.rowText, style]} accessible={merge || undefined} testID={testID}>
+        {isPrimitive(label) ? (
+          <Text allowFontScaling={allowFontScaling} style={[styles.label, labelStyle]}>
+            {label}
+          </Text>
+        ) : (
+          label
+        )}
+        {isPrimitive(value) ? (
+          <Text allowFontScaling={allowFontScaling} style={[styles.value, valueStyle]}>
+            {value}
+          </Text>
+        ) : (
+          value
+        )}
+      </View>
+    );
+  }
+);
 KeyValueRow.displayName = 'KeyValueRow';

package/src/atoms/PressableScale.tsx

@@ -7,32 +7,54 @@ import {
   type StyleProp,
   type ViewStyle,
 } from 'react-native';
+import { useReduceMotion } from './Transition';
 
-export interface PressableScaleProps extends Omit<PressableProps, 'style'> {
+export interface PressableScaleProps extends Omit<PressableProps, 'style' | 'children'> {
   /** Target scale when pressed. @default 0.96 */
   scaleTo?: number;
   style?: StyleProp<ViewStyle>;
+  /** Pressable content. */
   children: React.ReactNode;
 }
 
+/** Short spring with almost no bounce: feedback arrives in ~100 ms (Doherty). */
+const PRESS_SPRING = { speed: 50, bounciness: 6 } as const;
+
 const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
 
 /**
  * PressableScale
- * Feedback táctil de "achicarse" al presionar, con Animated.spring de RN
- * (useNativeDriver: true — corre en el hilo nativo, sin coste de JS por frame).
- * No depende de reanimated: la librería entera es cero-dependencias.
+ * Tactile "shrink" feedback on press, with RN's Animated.spring
+ * (useNativeDriver: true — runs on the native thread, no JS cost per frame).
+ * Doesn't depend on reanimated: the whole library is zero-dependency.
+ *
+ * Gestalt, figure/ground: as it sinks, the pressed element separates for an
+ * instant from the rest and confirms what was touched (Doherty: immediate
+ * response). Announces itself as a button by default (`accessibilityRole` can
+ * be changed) and, when disabled, exposes `disabled` to the screen reader.
+ * With Reduce Motion it doesn't scale.
  */
 export const PressableScale = memo(
-  ({ scaleTo = 0.96, style, children, onPressIn, onPressOut, disabled, ...props }: PressableScaleProps) => {
+  ({
+    scaleTo = 0.96,
+    style,
+    children,
+    onPressIn,
+    onPressOut,
+    disabled,
+    accessibilityRole = 'button',
+    accessibilityState,
+    ...props
+  }: PressableScaleProps) => {
     const scale = useRef(new Animated.Value(1)).current;
+    const reduceMotion = useReduceMotion();
 
     const animateTo = (value: number) => {
+      if (reduceMotion) return;
       Animated.spring(scale, {
         toValue: value,
         useNativeDriver: true,
-        speed: 50,
-        bounciness: 6,
+        ...PRESS_SPRING,
       }).start();
     };
 
@@ -49,6 +71,8 @@ export const PressableScale = memo(
     return (
       <AnimatedPressable
         {...props}
+        accessibilityRole={accessibilityRole}
+        accessibilityState={{ ...accessibilityState, disabled: !!disabled }}
         disabled={disabled}
         onPressIn={handlePressIn}
         onPressOut={handlePressOut}

package/src/atoms/ShinyText.tsx

@@ -26,11 +26,11 @@ export interface ShinyTextProps {
   spread?: number;
   /** When false it renders plain text in `shineColor`. @default true */
   animated?: boolean;
-  /** Resting color of the characters. @default theme.colors.textLight */
+  /** Resting color of the characters. Keep it readable on its own (WCAG AA): the shine is decorative. @default theme.colors.textLight */
   color?: string;
   /** Color of the band that travels across. @default theme.colors.primary */
   shineColor?: string;
-  /** @default 'left' */
+  /** Horizontal alignment of the line. @default 'left' */
   align?: 'left' | 'center' | 'right';
   /** Typography only: `color` and `shineColor` win over any color set here. */
   style?: StyleProp<TextStyle>;
@@ -49,11 +49,11 @@ const useStyles = createStyles((theme) => ({
     color: theme.colors.text,
   },
   row: { flexDirection: 'row', flexWrap: 'wrap' },
-  // Sólo top/left: un absoluteFill estiraría la letra al ancho del grupo y la
-  // volvería a alinear. Anclada a la esquina cae exactamente sobre la de abajo.
+  // Only top/left: an absoluteFill would stretch the letter to the group's width
+  // and realign it. Anchored to the corner it lands exactly on the one below.
   overlay: { position: 'absolute', top: 0, left: 0 },
-  // Una palabra y los espacios que la siguen: el salto de línea ocurre entre
-  // grupos, nunca entre las letras de una palabra.
+  // A word and the spaces that follow it: line breaks happen between
+  // groups, never between the letters of a word.
   group: { flexDirection: 'row' },
 }));
 
@@ -63,7 +63,7 @@ const ALIGN: Record<'left' | 'center' | 'right', ViewStyle['justifyContent']> =
   right: 'flex-end',
 };
 
-/** Una palabra con los espacios que la siguen, y el índice de su primera letra. */
+/** A word with the spaces that follow it, and the index of its first letter. */
 interface Group {
   start: number;
   chars: string[];
@@ -79,8 +79,8 @@ function toGroups(text: string): Group[] {
     if (current.length === 0) start = index;
     current.push(char);
     const next = chars[index + 1];
-    // Cierra el grupo cuando termina la racha de espacios que sigue a la
-    // palabra: así el espacio viaja con ella y no abre línea por sí solo.
+    // Closes the group when the run of spaces following the word ends:
+    // that way the space travels with it and never starts a line on its own.
     const isSpace = /\s/.test(char);
     if (isSpace && next !== undefined && !/\s/.test(next)) {
       groups.push({ start, chars: current });
@@ -94,23 +94,23 @@ function toGroups(text: string): Group[] {
 
 /**
  * ShinyText
- * Una banda de luz recorre el texto de izquierda a derecha. Sin
- * `background-clip: text` ni máscaras —que React Native no tiene en el rango
- * soportado— el brillo se compone letra por letra: cada una lleva su color de
- * reposo y encima, superpuesta, la misma letra en el color del brillo con la
- * opacidad animada. La banda es una ventana de interpolación que se desplaza:
- * lo que cambia por frame es sólo `opacity`, o sea que la animación entera
- * corre en el hilo nativo y JS no participa de ningún frame.
+ * A band of light sweeps across the text from left to right. Without
+ * `background-clip: text` or masks —which React Native lacks in the supported
+ * range— the shine is composed letter by letter: each one carries its resting
+ * color and, overlaid on top, the same letter in the shine color with animated
+ * opacity. The band is a moving interpolation window: the only thing that
+ * changes per frame is `opacity`, which means the whole animation runs on the
+ * native thread and JS takes part in no frame.
  *
- * Gestalt, destino común: las letras se encienden en secuencia y con el mismo
- * ritmo, así que se leen como una sola cosa que se mueve —una palabra
- * iluminándose— y no como N letras parpadeando por su cuenta. Por eso el ancho
- * de banda es relativo al texto y no una cantidad fija de píxeles: un título
- * largo y uno corto tardan lo mismo y se perciben igual.
+ * Gestalt, common fate: the letters light up in sequence and at the same
+ * rhythm, so they read as one moving thing —a word lighting up— and not as N
+ * letters blinking on their own. That is why the band width is relative to
+ * the text and not a fixed number of pixels: a long title and a short one take
+ * the same time and are perceived the same.
  *
- * Con "reducir movimiento" activo, o con `animated={false}`, el texto se
- * renderiza plano en `shineColor` —legible, un solo nodo y seleccionable—
- * porque el efecto es decorativo y nada de lo que comunica está en el brillo.
+ * With "reduce motion" on, or with `animated={false}`, the text renders flat
+ * in `shineColor` —legible, a single node and selectable— because the effect
+ * is decorative and nothing it communicates lives in the shine.
  */
 export const ShinyText = memo(
   ({
@@ -132,9 +132,9 @@ export const ShinyText = memo(
     const progress = useRef(new Animated.Value(0)).current;
 
     const base = color ?? theme.colors.textLight;
-    // El acento, no `text`: contra `textLight` la diferencia es sólo de
-    // luminancia y el barrido casi no se ve. El brillo cambia tono además de
-    // claridad, que es lo que hace legible el movimiento.
+    // The accent, not `text`: against `textLight` the difference is only in
+    // luminance and the sweep is barely visible. The shine changes hue as well
+    // as lightness, which is what makes the motion readable.
     const shine = shineColor ?? theme.colors.primary;
     const running = animated && !reduceMotion && text.length > 0;
 
@@ -170,9 +170,9 @@ export const ShinyText = memo(
     }
 
     const total = Array.from(text).length;
-    // La banda entra por la izquierda y sale por la derecha, así que el
-    // recorrido normalizado mide 1 + 2·spread. `half` es media banda en esa
-    // escala: el tramo de progreso que una letra tarda en encenderse.
+    // The band enters on the left and exits on the right, so the normalized
+    // path measures 1 + 2·spread. `half` is half a band on that scale: the
+    // stretch of progress a letter takes to light up.
     const half = spread / (1 + 2 * spread);
 
     return (
@@ -188,7 +188,7 @@ export const ShinyText = memo(
             {group.chars.map((char, offset) => {
               const index = group.start + offset;
               const position = total === 1 ? 0.5 : index / (total - 1);
-              // Progreso en el que el centro de la banda cae sobre esta letra.
+              // Progress at which the center of the band falls on this letter.
               const peak = (position + spread) / (1 + 2 * spread);
               const charStyle: StyleProp<TextStyle> = [styles.text, style];