orn-ui 0.2.10 → 0.3.0

package/src/molecules/AvatarHeader.tsx

@@ -8,62 +8,116 @@ import type { IconName } from '../icons/types';
 export interface AvatarHeaderProps {
   /** Icon to show inside the circle. If omitted, `initials` is used instead. */
   iconName?: IconName;
+  /** Icon color. Keep AA contrast against `primarySoft`, the circle's fill. @default colors.primary */
   iconColor?: string;
-  /** Short text (e.g. 2 letters) shown when `iconName` isn't provided. */
+  /** Short text (e.g. 2 letters) shown when `iconName` isn't provided. Without either, a `user` icon. */
   initials?: string;
+  /** Main heading of the screen or modal; announced as a header. */
   title: string;
+  /** Supporting line under the title. A string gets the muted style; a node renders as is. */
   subtitle?: React.ReactNode;
+  /**
+   * Third and last line, the least important detail ("Joined March 2023").
+   * Three lines is the limit: beyond that the header stops being scannable.
+   */
+  caption?: string;
   style?: StyleProp<ViewStyle>;
+  testID?: string;
 }
 
+const CIRCLE = 80;
+const ICON_SIZE = 40;
+
 const useStyles = createStyles((theme) => ({
-  container: { alignItems: 'center', marginBottom: theme.tokens.spacing.xl },
+  // No outer margin: the space below belongs to the parent's layout.
+  container: { alignItems: 'center' },
   avatar: {
-    width: 80,
-    height: 80,
-    borderRadius: 40,
+    width: CIRCLE,
+    height: CIRCLE,
+    borderRadius: CIRCLE / 2,
     backgroundColor: theme.colors.primarySoft,
     justifyContent: 'center',
     alignItems: 'center',
     marginBottom: theme.tokens.spacing.md,
   },
-  initials: { fontSize: theme.tokens.fontSize.xxl, fontWeight: theme.tokens.fontWeight.bold, color: theme.colors.primaryText },
-  title: { fontSize: theme.tokens.fontSize.xl, fontWeight: theme.tokens.fontWeight.bold, textAlign: 'center', color: theme.colors.text, marginBottom: theme.tokens.spacing.xs },
-  subtitle: { fontSize: theme.tokens.fontSize.md, color: theme.colors.textLight },
+  initials: {
+    fontSize: theme.tokens.fontSize.xxl,
+    fontWeight: theme.tokens.fontWeight.bold,
+    color: theme.colors.primaryText,
+  },
+  title: {
+    fontSize: theme.tokens.fontSize.xl,
+    lineHeight: theme.tokens.lineHeight.lg,
+    fontWeight: theme.tokens.fontWeight.bold,
+    textAlign: 'center',
+    color: theme.colors.text,
+    marginBottom: theme.tokens.spacing.xs,
+  },
+  subtitle: {
+    fontSize: theme.tokens.fontSize.md,
+    lineHeight: theme.tokens.lineHeight.md,
+    color: theme.colors.textLight,
+    textAlign: 'center',
+  },
+  caption: {
+    fontSize: theme.tokens.fontSize.sm,
+    lineHeight: theme.tokens.lineHeight.sm,
+    color: theme.colors.textLight,
+    textAlign: 'center',
+    marginTop: theme.tokens.spacing.xxs,
+  },
 }));
 
 /**
  * AvatarHeader
- * Círculo 80x80 con ícono o iniciales + título/subtítulo centrado. Header
- * típico de modales de detalle (cliente, producto, etc).
+ * 80x80 circle with an icon or initials + centered title/subtitle. Typical
+ * header of detail modals (client, product, etc).
+ *
+ * Gestalt, symmetry and focal point: everything sits on one centered axis and
+ * the circle is the single large shape, so the eye lands there first and then
+ * drops to the title. Proximity: title and subtitle are closer to each other
+ * than to the circle, reading as one name + its detail. Hierarchy by size:
+ * title, subtitle, caption — at most three lines of text. Long text wraps
+ * centered, so the axis holds. No outer margin: the parent sets the spacing.
+ *
+ * Accessibility: the title is a header; the circle is decorative (the
+ * initials would only repeat the title).
  */
-export const AvatarHeader = memo(({ iconName, iconColor, initials, title, subtitle, style }: AvatarHeaderProps) => {
-  const colors = useColors();
-  const styles = useStyles();
-  const allowFontScaling = useAllowFontScaling();
+export const AvatarHeader = memo(
+  ({ iconName, iconColor, initials, title, subtitle, caption, style, testID }: AvatarHeaderProps) => {
+    const colors = useColors();
+    const styles = useStyles();
+    const allowFontScaling = useAllowFontScaling();
+    const fallbackIcon: IconName | undefined = iconName ?? (initials ? undefined : 'user');
 
-  return (
-    <View style={[styles.container, style]}>
-      <View style={styles.avatar}>
-        {iconName ? (
-          <Icon name={iconName} size={40} color={iconColor || colors.primary} />
+    return (
+      <View style={[styles.container, style]} testID={testID}>
+        <View style={styles.avatar} accessibilityElementsHidden importantForAccessibility="no-hide-descendants">
+          {fallbackIcon ? (
+            <Icon name={fallbackIcon} size={ICON_SIZE} color={iconColor ?? colors.primary} />
+          ) : (
+            <Text allowFontScaling={allowFontScaling} style={styles.initials}>
+              {initials}
+            </Text>
+          )}
+        </View>
+        <Text allowFontScaling={allowFontScaling} style={styles.title} accessibilityRole="header">
+          {title}
+        </Text>
+        {typeof subtitle === 'string' ? (
+          <Text allowFontScaling={allowFontScaling} style={styles.subtitle}>
+            {subtitle}
+          </Text>
         ) : (
-          <Text allowFontScaling={allowFontScaling} style={styles.initials}>
-            {initials}
+          subtitle
+        )}
+        {!!caption && (
+          <Text allowFontScaling={allowFontScaling} style={styles.caption}>
+            {caption}
           </Text>
         )}
       </View>
-      <Text allowFontScaling={allowFontScaling} style={styles.title}>
-        {title}
-      </Text>
-      {typeof subtitle === 'string' ? (
-        <Text allowFontScaling={allowFontScaling} style={styles.subtitle}>
-          {subtitle}
-        </Text>
-      ) : (
-        subtitle
-      )}
-    </View>
-  );
-});
+    );
+  }
+);
 AvatarHeader.displayName = 'AvatarHeader';

package/src/molecules/FormActions.tsx

@@ -3,23 +3,45 @@ import { View, type StyleProp, type ViewStyle } from 'react-native';
 import { Button } from '../atoms/Button';
 import type { IconName } from '../icons/types';
 import { useLabels } from '../theme/UIProvider';
+import { createStyles } from '../theme/createStyles';
 
 export interface FormActionsProps {
-  /** If omitted, only the secondary button is shown. */
+  /** Label of the main action ("Save"). The primary button shows only with both this and `onPrimaryPress`. */
   primaryLabel?: string;
+  /** Main action. */
   onPrimaryPress?: () => void;
+  /** Blocks the main action, e.g. while the form is invalid. @default false */
   primaryDisabled?: boolean;
+  /**
+   * The main action is running: shows a spinner and ignores presses, so it
+   * can't be sent twice. The secondary button stays usable. @default false
+   */
   primaryLoading?: boolean;
+  /** Icon before the primary label. */
   primaryLeftIconName?: IconName;
+  /** Label of the ghost button. @default labels.close */
   secondaryLabel?: string;
+  /** Close / cancel action. */
   onSecondaryPress: () => void;
   style?: StyleProp<ViewStyle>;
+  /** Root testID; the buttons get `<testID>-primary` and `<testID>-secondary`. */
+  testID?: string;
 }
 
+const useStyles = createStyles((theme) => ({
+  root: { gap: theme.tokens.spacing.md },
+}));
+
 /**
  * FormActions
- * Par de botones: uno primario (guardar/editar) y uno ghost (cerrar/cancelar).
- * Uso típico: al final de un form, o en el footer de un Modal.
+ * Pair of buttons: a primary one (save/edit) and a ghost one (close/cancel).
+ * Typical use: at the end of a form, or in a Modal's footer.
+ *
+ * Gestalt, proximity: both buttons sit close together and apart from the
+ * fields, so they read as the form's closing actions. Von Restorff: only the
+ * primary is filled; the secondary is ghost, so the main path is obvious and
+ * the two never compete (Hick: one clear choice). Fitts: full width, primary
+ * first, closest to the content it acts on.
  */
 export const FormActions = memo(
   ({
@@ -31,20 +53,28 @@ export const FormActions = memo(
     secondaryLabel,
     onSecondaryPress,
     style,
+    testID,
   }: FormActionsProps) => {
     const labels = useLabels();
+    const styles = useStyles();
     return (
-      <View style={[{ gap: 12 }, style]}>
-        {primaryLabel && onPrimaryPress && (
+      <View style={[styles.root, style]} testID={testID}>
+        {!!primaryLabel && !!onPrimaryPress && (
           <Button
             title={primaryLabel}
             onPress={onPrimaryPress}
             disabled={primaryDisabled}
             loading={primaryLoading}
             leftIconName={primaryLeftIconName}
+            testID={testID && `${testID}-primary`}
           />
         )}
-        <Button title={secondaryLabel ?? labels.close} onPress={onSecondaryPress} variant="ghost" />
+        <Button
+          title={secondaryLabel ?? labels.close}
+          onPress={onSecondaryPress}
+          variant="ghost"
+          testID={testID && `${testID}-secondary`}
+        />
       </View>
     );
   }

package/src/molecules/InfoRow.tsx

@@ -7,43 +7,70 @@ import type { IconName } from '../icons/types';
 import { Avatar } from '../atoms/Avatar';
 
 export interface InfoRowProps {
+  /** Icon that identifies the kind of data at a glance (decorative for screen readers). */
   icon: IconName;
+  /** What the value is ("Email", "Address"). */
   label: string;
+  /** The data itself. Empty, `null` or `undefined` shows `placeholder`. */
   value: string | null | undefined;
+  /** Text shown, in italics, when there is no value ("No phone number"). */
   placeholder: string;
   style?: StyleProp<ViewStyle>;
+  testID?: string;
 }
 
+const ICON_BADGE = 40;
+const ICON_SIZE = 20;
+
 const useStyles = createStyles((theme) => ({
-  row: { flexDirection: 'row', alignItems: 'center' },
-  icon: { marginRight: theme.tokens.spacing.md },
+  row: { flexDirection: 'row', alignItems: 'center', gap: theme.tokens.spacing.md },
   textContainer: { flex: 1 },
-  label: { fontSize: theme.tokens.fontSize.sm, color: theme.colors.textLight, marginBottom: 2 },
-  value: { fontSize: theme.tokens.fontSize.md + 1, color: theme.colors.text, fontWeight: theme.tokens.fontWeight.medium },
-  placeholder: { color: theme.colors.textLight, fontStyle: 'italic' },
+  label: {
+    fontSize: theme.tokens.fontSize.sm,
+    lineHeight: theme.tokens.lineHeight.sm,
+    color: theme.colors.textLight,
+    marginBottom: theme.tokens.spacing.xxs,
+  },
+  value: {
+    fontSize: theme.tokens.fontSize.md,
+    lineHeight: theme.tokens.lineHeight.md,
+    color: theme.colors.text,
+    fontWeight: theme.tokens.fontWeight.medium,
+  },
+  placeholder: { color: theme.colors.textLight, fontStyle: 'italic', fontWeight: theme.tokens.fontWeight.regular },
 }));
 
 /**
  * InfoRow
- * Ícono circular a la izquierda + label/valor apilado a la derecha. Muestra
- * `placeholder` en itálica si no hay valor. Pensado para modales de detalle.
+ * Circular icon on the left + stacked label/value on the right. Shows
+ * `placeholder` in italics when there is no value. Meant for detail modals.
+ *
+ * Gestalt, proximity: label and value sit 2pt apart and the icon a token
+ * further, so each row reads as one fact; stack rows with a larger gap.
+ * Similarity: every label shares the small muted style and every value the
+ * strong one, so a list of rows scans by column. A missing value changes
+ * style (muted italics) so it can't be mistaken for data.
+ *
+ * Accessibility: the row is a single element ("Email, jane@example.com");
+ * the icon is decorative.
  */
-export const InfoRow = memo(({ icon, label, value, placeholder, style }: InfoRowProps) => {
+export const InfoRow = memo(({ icon, label, value, placeholder, style, testID }: InfoRowProps) => {
   const colors = useColors();
   const styles = useStyles();
   const allowFontScaling = useAllowFontScaling();
+  const shown = value || placeholder;
 
   return (
-    <View style={[styles.row, style]}>
-      <Avatar size={40} backgroundColor={colors.inputBackground} style={styles.icon}>
-        <Icon name={icon} size={20} color={colors.textLight} />
+    <View style={[styles.row, style]} accessible accessibilityLabel={`${label}, ${shown}`} testID={testID}>
+      <Avatar size={ICON_BADGE} backgroundColor={colors.inputBackground}>
+        <Icon name={icon} size={ICON_SIZE} color={colors.textLight} />
       </Avatar>
       <View style={styles.textContainer}>
         <Text allowFontScaling={allowFontScaling} style={styles.label}>
           {label}
         </Text>
         <Text allowFontScaling={allowFontScaling} style={[styles.value, !value && styles.placeholder]}>
-          {value || placeholder}
+          {shown}
         </Text>
       </View>
     </View>

package/src/molecules/OptionCard.tsx

@@ -7,12 +7,21 @@ import { PressableScale } from '../atoms/PressableScale';
 import type { IconName } from '../icons/types';
 
 export interface OptionCardProps {
+  /** Name of the option. It is also the start of its accessible name. */
   label: string;
-  /** Secondary line: the detail that decides the choice ("arrives in 3 days"). */
+  /**
+   * Secondary line: the detail that decides the choice ("arrives in 3 days").
+   * Screen readers read it right after the label, not as a hint, because
+   * hints can be turned off and this detail is part of the choice.
+   */
   description?: string;
+  /** Icon that helps recognize the option. Avoid `check`: it reads as "selected". */
   iconName?: IconName;
+  /** Whether this is the chosen option of its group. */
   isSelected: boolean;
+  /** Called on press; the group decides which option is selected. */
   onPress: () => void;
+  /** Dims the card and ignores presses. @default false */
   disabled?: boolean;
   /** 'vertical': icon on top, text centered below. 'horizontal': in a row. @default 'horizontal' */
   layout?: 'vertical' | 'horizontal';
@@ -20,43 +29,70 @@ export interface OptionCardProps {
   testID?: string;
 }
 
+const ICON_SIZE = 24;
+/** Same height for every vertical card in a row, even with a short label. */
+const VERTICAL_MIN_HEIGHT = 100;
+const DISABLED_OPACITY = 0.5;
+/** The selected border is thicker; its padding gives back the difference so content doesn't shift. */
+const BORDER = 1;
+const BORDER_SELECTED = 1.5;
+
 const useStyles = createStyles((theme) => ({
   card: {
-    // Las tarjetas se reparten la fila que las contenga, sean dos o cinco.
+    // The cards share whatever row contains them, whether two or five.
     flex: 1,
     alignItems: 'center',
     justifyContent: 'center',
-    backgroundColor: theme.colors.surface,
+    // Raised: in dark it stays a visible tile on a surface (Card does the same).
+    backgroundColor: theme.colors.surfaceRaised,
     borderRadius: theme.tokens.radius.md,
-    borderWidth: 1,
+    borderWidth: BORDER,
     borderColor: theme.colors.border,
+    padding: theme.tokens.spacing.md,
     ...theme.tokens.shadow.sm,
   },
-  cardHorizontal: { flexDirection: 'row', padding: theme.tokens.spacing.md - 2, gap: theme.tokens.spacing.sm },
-  cardVertical: { padding: theme.tokens.spacing.md - 2, gap: 6, minHeight: 100 },
+  cardHorizontal: { flexDirection: 'row', gap: theme.tokens.spacing.sm },
+  cardVertical: { gap: theme.tokens.spacing.sm, minHeight: VERTICAL_MIN_HEIGHT },
   cardSelected: {
     borderColor: theme.colors.primary,
     backgroundColor: theme.colors.primarySoft,
-    borderWidth: 1.5,
+    borderWidth: BORDER_SELECTED,
+    padding: theme.tokens.spacing.md - (BORDER_SELECTED - BORDER),
     elevation: 0,
     shadowOpacity: 0,
   },
-  cardDisabled: { opacity: 0.5 },
+  cardDisabled: { opacity: DISABLED_OPACITY },
   text: { flexShrink: 1 },
   textVertical: { alignItems: 'center' },
-  label: { color: theme.colors.textLight, fontWeight: theme.tokens.fontWeight.medium },
-  labelVertical: { fontSize: theme.tokens.fontSize.xs, textAlign: 'center' },
+  label: {
+    color: theme.colors.text,
+    fontSize: theme.tokens.fontSize.md,
+    lineHeight: theme.tokens.lineHeight.md,
+    fontWeight: theme.tokens.fontWeight.medium,
+  },
+  labelVertical: { textAlign: 'center' },
   labelSelected: { color: theme.colors.primaryText },
-  description: { fontSize: theme.tokens.fontSize.xs, color: theme.colors.textLight, marginTop: 2 },
+  description: {
+    fontSize: theme.tokens.fontSize.sm,
+    lineHeight: theme.tokens.lineHeight.sm,
+    color: theme.colors.textLight,
+    marginTop: theme.tokens.spacing.xxs,
+  },
   descriptionVertical: { textAlign: 'center' },
 }));
 
 /**
  * OptionCard
- * Opción excluyente con ícono y label que resalta cuando `isSelected`. Es un
- * radio con cara de tarjeta, así que se anuncia como tal: envolver el grupo en
- * una View con `accessibilityRole="radiogroup"` para que el lector de pantalla
- * lea "1 de 3".
+ * Mutually exclusive option with an icon and label that highlights when
+ * `isSelected`. It is a radio with a card's face, so it announces itself as
+ * one: wrap the group in a View with `accessibilityRole="radiogroup"` so the
+ * screen reader reads "1 of 3".
+ *
+ * Gestalt, similarity: every card in a group shares shape, size and type, so
+ * they read as alternatives of one question. Von Restorff / figure-ground: the
+ * selected one is the only filled card with an accent border and no shadow —
+ * it stands out without the others losing legibility (their labels keep the
+ * `text` color). The thicker selected border doesn't move the content.
  */
 export const OptionCard = memo(
   ({
@@ -75,8 +111,8 @@ export const OptionCard = memo(
     const allowFontScaling = useAllowFontScaling();
     const isVertical = layout === 'vertical';
 
-    // Feedback por transform y no por opacity: con elevation, animar la opacity
-    // dispara un bug de Android que redibuja la sombra como un borde oscuro.
+    // Feedback through transform, not opacity: with elevation, animating opacity
+    // triggers an Android bug that redraws the shadow as a dark border.
     return (
       <PressableScale
         style={[
@@ -90,11 +126,10 @@ export const OptionCard = memo(
         disabled={disabled}
         accessibilityRole="radio"
         accessibilityState={{ selected: isSelected, checked: isSelected, disabled }}
-        accessibilityLabel={label}
-        accessibilityHint={description}
+        accessibilityLabel={description ? `${label}, ${description}` : label}
         testID={testID}
       >
-        {!!iconName && <Icon name={iconName} size={24} color={isSelected ? colors.primary : colors.textLight} />}
+        {!!iconName && <Icon name={iconName} size={ICON_SIZE} color={isSelected ? colors.primary : colors.textLight} />}
 
         <View style={[styles.text, isVertical && styles.textVertical]}>
           <Text

package/src/molecules/SegmentedControl.tsx

@@ -1,46 +1,103 @@
-import React, { memo } from 'react';
-import { Text, TouchableOpacity, View, type StyleProp, type ViewStyle } from 'react-native';
+import React, { memo, useEffect, useRef, useState } from 'react';
+import {
+  Animated,
+  Easing,
+  I18nManager,
+  Text,
+  TouchableOpacity,
+  View,
+  type LayoutChangeEvent,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
 import { createStyles } from '../theme/createStyles';
-import { useAllowFontScaling } from '../theme/UIProvider';
+import { useAllowFontScaling, useTheme } from '../theme/UIProvider';
+import { useReduceMotion } from '../theme/useReduceMotion';
 
 export interface SegmentedControlOption<T extends string = string> {
   value: T;
+  /** Visible text. Kept to one line (ellipsized); screen readers get it whole. */
   label: string;
+  /** Disables only this segment. */
   disabled?: boolean;
 }
 
 export interface SegmentedControlProps<T extends string = string> {
+  /** The choices, all visible at once. Two to four read best (Hick); more belong in a Select. */
   options: SegmentedControlOption<T>[];
+  /** The selected option's value. */
   value: T;
+  /** Called with the new value; not called when pressing the segment already selected. */
   onChange: (value: T) => void;
+  /** Disables the whole control. @default false */
   disabled?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }
 
+/** Inset between the track and the segments. */
+const TRACK_PADDING = 3;
+/** Minimum touch target (Fitts): the segment plus the track inset reach it. */
+const MIN_TOUCH = 44;
+const DISABLED_OPACITY = 0.5;
+const HIT_SLOP = { top: TRACK_PADDING, bottom: TRACK_PADDING };
+
 const useStyles = createStyles((theme) => ({
   track: {
     flexDirection: 'row',
     backgroundColor: theme.colors.inputBackground,
     borderRadius: theme.tokens.radius.md,
-    padding: 3,
+    padding: TRACK_PADDING,
   },
   segment: {
     flex: 1,
+    minHeight: MIN_TOUCH - TRACK_PADDING * 2,
     paddingVertical: theme.tokens.spacing.sm,
+    paddingHorizontal: theme.tokens.spacing.xs,
     borderRadius: theme.tokens.radius.sm,
     alignItems: 'center',
+    justifyContent: 'center',
+  },
+  // Light: a white segment with a shadow over the grey track. Dark: shadows
+  // don't show and `surface` is darker than the track (the segment looked
+  // sunken), so the selected one takes the soft accent fill instead.
+  // One shared indicator slides under the segments; until the track is
+  // measured, the selected segment paints this same fill itself.
+  indicator: {
+    position: 'absolute',
+    top: TRACK_PADDING,
+    bottom: TRACK_PADDING,
+    start: TRACK_PADDING,
+    borderRadius: theme.tokens.radius.sm,
+  },
+  segmentActive:
+    theme.scheme === 'dark'
+      ? { backgroundColor: theme.colors.primarySoft }
+      : { backgroundColor: theme.colors.surface, ...theme.tokens.shadow.sm },
+  segmentDisabled: { opacity: DISABLED_OPACITY },
+  label: {
+    fontSize: theme.tokens.fontSize.md,
+    lineHeight: theme.tokens.lineHeight.md,
+    fontWeight: theme.tokens.fontWeight.medium,
+    color: theme.colors.textLight,
   },
-  segmentActive: { backgroundColor: theme.colors.surface, ...theme.tokens.shadow.sm },
-  segmentDisabled: { opacity: 0.5 },
-  label: { fontSize: theme.tokens.fontSize.sm, fontWeight: theme.tokens.fontWeight.medium, color: theme.colors.textLight },
   labelActive: { color: theme.colors.primaryText, fontWeight: theme.tokens.fontWeight.semibold },
 }));
 
 /**
  * SegmentedControl
- * Elige una opción entre pocas, todas visibles. No conoce ningún estado
- * global: recibe `value` y avisa por `onChange`.
+ * Picks one option among a few, all visible. It knows no global state:
+ * it receives `value` and reports through `onChange`.
+ *
+ * Gestalt, common region: one track holds every segment, so they read as a
+ * single question. Similarity: equal widths and one line each, so no option
+ * looks more important. Figure-ground: the selected segment is raised (surface
+ * + shadow) above the sunken track; in dark, where shadows vanish, it takes
+ * the soft accent fill. Fitts: every segment reaches 44pt.
+ *
+ * Continuity: the selection is one indicator that slides from the old segment
+ * to the new one, so the eye follows the change instead of seeing one fill
+ * vanish and another appear. With Reduce Motion it jumps.
  */
 function SegmentedControlInner<T extends string>({
   options,
@@ -51,25 +108,88 @@ function SegmentedControlInner<T extends string>({
   testID,
 }: SegmentedControlProps<T>) {
   const styles = useStyles();
+  const theme = useTheme();
   const allowFontScaling = useAllowFontScaling();
+  const reduceMotion = useReduceMotion();
+  const [trackWidth, setTrackWidth] = useState(0);
+  const offset = useRef(new Animated.Value(0)).current;
+  const placed = useRef(false);
+
+  const index = options.findIndex((option) => option.value === value);
+  const segmentWidth = trackWidth > 0 && options.length > 0 ? (trackWidth - TRACK_PADDING * 2) / options.length : 0;
+  const showIndicator = segmentWidth > 0 && index >= 0;
+  // transform isn't mirrored in RTL: the indicator starts at the right edge
+  // (`start`), so it moves left.
+  const target = index * segmentWidth * (I18nManager.isRTL ? -1 : 1);
+
+  useEffect(() => {
+    if (!showIndicator) return;
+    // First placement (and Reduce Motion) jumps; only a change of value slides.
+    if (!placed.current || reduceMotion) {
+      placed.current = true;
+      offset.setValue(target);
+      return;
+    }
+    const animation = Animated.timing(offset, {
+      toValue: target,
+      duration: theme.tokens.duration.base,
+      easing: Easing.out(Easing.cubic),
+      useNativeDriver: true,
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [target, showIndicator, reduceMotion, offset, theme.tokens.duration.base]);
+
+  // A new width (rotation, resize) places the indicator without animating.
+  const onLayout = (e: LayoutChangeEvent) => {
+    const width = e.nativeEvent.layout.width;
+    if (width === trackWidth) return;
+    placed.current = false;
+    setTrackWidth(width);
+  };
+
+  const activeDisabled = disabled || !!options[index]?.disabled;
 
   return (
-    <View style={[styles.track, style]} accessibilityRole="radiogroup" testID={testID}>
+    <View style={[styles.track, style]} accessibilityRole="radiogroup" testID={testID} onLayout={onLayout}>
+      {showIndicator && (
+        <Animated.View
+          pointerEvents="none"
+          testID={testID && `${testID}-indicator`}
+          style={[
+            styles.indicator,
+            styles.segmentActive,
+            { width: segmentWidth, transform: [{ translateX: offset }] },
+            activeDisabled && styles.segmentDisabled,
+          ]}
+        />
+      )}
       {options.map((option) => {
         const active = option.value === value;
         const isDisabled = disabled || !!option.disabled;
         return (
           <TouchableOpacity
             key={option.value}
-            style={[styles.segment, active && styles.segmentActive, isDisabled && styles.segmentDisabled]}
-            onPress={() => onChange(option.value)}
+            style={[
+              styles.segment,
+              active && !showIndicator && styles.segmentActive,
+              isDisabled && styles.segmentDisabled,
+            ]}
+            onPress={() => {
+              if (!active) onChange(option.value);
+            }}
             disabled={isDisabled}
+            hitSlop={HIT_SLOP}
             accessibilityRole="radio"
             accessibilityState={{ selected: active, checked: active, disabled: isDisabled }}
             accessibilityLabel={option.label}
             testID={testID && `${testID}-${option.value}`}
           >
-            <Text allowFontScaling={allowFontScaling} style={[styles.label, active && styles.labelActive]}>
+            <Text
+              allowFontScaling={allowFontScaling}
+              numberOfLines={1}
+              style={[styles.label, active && styles.labelActive]}
+            >
               {option.label}
             </Text>
           </TouchableOpacity>
@@ -79,6 +199,6 @@ function SegmentedControlInner<T extends string>({
   );
 }
 
-// memo() pierde los genéricos al envolver: el cast los devuelve para que
-// `value` y `onChange` sigan atados al union de `options`.
+// memo() loses generics when wrapping: the cast restores them so that
+// `value` and `onChange` stay tied to the union of `options`.
 export const SegmentedControl = memo(SegmentedControlInner) as typeof SegmentedControlInner;