orn-ui 0.2.9 → 0.3.0

package/registry/toast-provider.json

@@ -13,11 +13,11 @@
   "files": [
     {
       "path": "organisms/ToastProvider.tsx",
-      "content": "import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';\nimport { View } from 'react-native';\nimport { AnimatedToast, Toast, type ToastVariant } from './Toast';\nimport { useInsets } from '../theme/UIProvider';\nimport { createStyles } from '../theme/createStyles';\nimport { createImperativeBridge } from './imperativeBridge';\n\nexport interface ToastOptions {\n  title: string;\n  message?: string;\n  variant?: ToastVariant;\n  /** ms antes de auto-descartar. 0 = no se descarta solo. @default 4000 */\n  duration?: number;\n  onPress?: () => void;\n  hideCloseButton?: boolean;\n}\n\ninterface ToastEntry extends ToastOptions {\n  id: string;\n}\n\ninterface ToastContextValue {\n  /** Muestra un toast y devuelve su id (por si querés cerrarlo antes de tiempo). */\n  show: (options: ToastOptions) => string;\n  hide: (id: string) => void;\n  hideAll: () => void;\n}\n\nconst ToastContext = createContext<ToastContextValue | undefined>(undefined);\nconst bridge = createImperativeBridge<ToastContextValue>('ToastProvider');\n\n/**\n * Muestra un toast desde fuera del árbol de React —un servicio, un\n * interceptor— sin pasar por el hook. Devuelve el id, o '' si no hay\n * <ToastProvider> montado.\n */\nexport function showToast(options: ToastOptions): string {\n  return bridge.get()?.show(options) ?? '';\n}\n\nexport function hideToast(id: string): void {\n  bridge.get()?.hide(id);\n}\n\nexport function hideAllToasts(): void {\n  bridge.get()?.hideAll();\n}\n\nconst useStyles = createStyles((theme) => ({\n  host: { position: 'absolute', left: 0, right: 0, paddingHorizontal: theme.tokens.spacing.lg, gap: theme.tokens.spacing.sm },\n}));\n\nexport interface ToastProviderProps {\n  children: React.ReactNode;\n  /** @default 'top' */\n  position?: 'top' | 'bottom';\n  /** Maximum simultaneous toasts; the oldest ones are dropped. @default 3 */\n  maxVisible?: number;\n  /** Default duration in ms. @default 4000 */\n  defaultDuration?: number;\n}\n\n/**\n * ToastProvider\n * Monta la capa de toasts sobre el resto de la app. Colocar una vez cerca de\n * la raíz, dentro de UIProvider. Los timers de auto-dismiss se limpian al\n * desmontar y al cerrar cada toast, así que no quedan callbacks colgados.\n */\nexport function ToastProvider({\n  children,\n  position = 'top',\n  maxVisible = 3,\n  defaultDuration = 4000,\n}: ToastProviderProps) {\n  const [toasts, setToasts] = useState<ToastEntry[]>([]);\n  const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>());\n  const counter = useRef(0);\n  const insets = useInsets();\n  const styles = useStyles();\n\n  const clearTimer = useCallback((id: string) => {\n    const t = timers.current.get(id);\n    if (t) {\n      clearTimeout(t);\n      timers.current.delete(id);\n    }\n  }, []);\n\n  const hide = useCallback(\n    (id: string) => {\n      clearTimer(id);\n      setToasts((prev) => prev.filter((t) => t.id !== id));\n    },\n    [clearTimer]\n  );\n\n  const hideAll = useCallback(() => {\n    timers.current.forEach((t) => clearTimeout(t));\n    timers.current.clear();\n    setToasts([]);\n  }, []);\n\n  const show = useCallback(\n    (options: ToastOptions) => {\n      counter.current += 1;\n      const id = `toast-${counter.current}`;\n      const duration = options.duration ?? defaultDuration;\n\n      setToasts((prev) => {\n        const next = [...prev, { ...options, id }];\n        // Se descartan los más viejos, no los recién llegados: un toast nuevo\n        // siempre se ve.\n        const overflow = next.length - maxVisible;\n        if (overflow > 0) {\n          next.slice(0, overflow).forEach((t) => clearTimer(t.id));\n          return next.slice(overflow);\n        }\n        return next;\n      });\n\n      if (duration > 0) {\n        timers.current.set(\n          id,\n          setTimeout(() => hide(id), duration)\n        );\n      }\n      return id;\n    },\n    [defaultDuration, maxVisible, hide, clearTimer]\n  );\n\n  // Al desmontar el provider no debe quedar ningún setTimeout apuntando a un\n  // setState de un árbol ya desmontado.\n  useEffect(() => {\n    const pending = timers.current;\n    return () => {\n      pending.forEach((t) => clearTimeout(t));\n      pending.clear();\n    };\n  }, []);\n\n  const value = useMemo<ToastContextValue>(() => ({ show, hide, hideAll }), [show, hide, hideAll]);\n\n  useEffect(() => {\n    bridge.set(value);\n    return () => bridge.set(null);\n  }, [value]);\n\n  const hostPosition =\n    position === 'top'\n      ? { top: insets.top + 8 }\n      : { bottom: insets.bottom + 8, flexDirection: 'column-reverse' as const };\n\n  return (\n    <ToastContext.Provider value={value}>\n      {children}\n      {toasts.length > 0 && (\n        <View style={[styles.host, hostPosition]} pointerEvents=\"box-none\" testID=\"toast-host\">\n          {toasts.map((t) => (\n            <AnimatedToast key={t.id}>\n              <Toast\n                title={t.title}\n                message={t.message}\n                variant={t.variant}\n                hideCloseButton={t.hideCloseButton}\n                onDismiss={() => hide(t.id)}\n                onPress={\n                  t.onPress\n                    ? () => {\n                        t.onPress?.();\n                        hide(t.id);\n                      }\n                    : undefined\n                }\n              />\n            </AnimatedToast>\n          ))}\n        </View>\n      )}\n    </ToastContext.Provider>\n  );\n}\n\nexport function useToast(): ToastContextValue {\n  const ctx = useContext(ToastContext);\n  if (!ctx) {\n    throw new Error('orn-ui: useToast must be used within a <ToastProvider>.');\n  }\n  return ctx;\n}\n"
+      "content": "import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';\nimport { AccessibilityInfo, View } from 'react-native';\nimport { AnimatedToast, Toast, type ToastVariant } from './Toast';\nimport { useInsets } from '../theme/UIProvider';\nimport { createStyles } from '../theme/createStyles';\nimport { createImperativeBridge } from './imperativeBridge';\n\nexport interface ToastOptions {\n  title: string;\n  message?: string;\n  variant?: ToastVariant;\n  /** Milliseconds before auto-dismiss. 0 = never dismisses on its own. @default 4000 */\n  duration?: number;\n  onPress?: () => void;\n  hideCloseButton?: boolean;\n}\n\ninterface ToastEntry extends ToastOptions {\n  id: string;\n}\n\ninterface ToastContextValue {\n  /** Shows a toast and returns its id (to close it early if needed). */\n  show: (options: ToastOptions) => string;\n  hide: (id: string) => void;\n  hideAll: () => void;\n}\n\nconst ToastContext = createContext<ToastContextValue | undefined>(undefined);\nconst bridge = createImperativeBridge<ToastContextValue>('ToastProvider');\n\n/**\n * Shows a toast from outside the React tree —a service, an interceptor—\n * without going through the hook. Returns the id, or '' if there is no\n * mounted <ToastProvider>.\n */\nexport function showToast(options: ToastOptions): string {\n  return bridge.get()?.show(options) ?? '';\n}\n\nexport function hideToast(id: string): void {\n  bridge.get()?.hide(id);\n}\n\nexport function hideAllToasts(): void {\n  bridge.get()?.hideAll();\n}\n\nconst useStyles = createStyles((theme) => ({\n  host: { position: 'absolute', left: 0, right: 0, paddingHorizontal: theme.tokens.spacing.lg, gap: theme.tokens.spacing.sm },\n}));\n\nexport interface ToastProviderProps {\n  children: React.ReactNode;\n  /** @default 'top' */\n  position?: 'top' | 'bottom';\n  /** Maximum simultaneous toasts; the oldest ones are dropped. @default 3 */\n  maxVisible?: number;\n  /** Default duration in ms. @default 4000 */\n  defaultDuration?: number;\n}\n\n/**\n * ToastProvider\n * Mounts the toast layer above the rest of the app. Place it once near the\n * root, inside UIProvider. The auto-dismiss timers are cleared on unmount and\n * when each toast closes, so no callbacks are left hanging.\n */\nexport function ToastProvider({\n  children,\n  position = 'top',\n  maxVisible = 3,\n  defaultDuration = 4000,\n}: ToastProviderProps) {\n  const [toasts, setToasts] = useState<ToastEntry[]>([]);\n  const timers = useRef(new Map<string, ReturnType<typeof setTimeout>>());\n  const counter = useRef(0);\n  const insets = useInsets();\n  const styles = useStyles();\n\n  const clearTimer = useCallback((id: string) => {\n    const t = timers.current.get(id);\n    if (t) {\n      clearTimeout(t);\n      timers.current.delete(id);\n    }\n  }, []);\n\n  const hide = useCallback(\n    (id: string) => {\n      clearTimer(id);\n      setToasts((prev) => prev.filter((t) => t.id !== id));\n    },\n    [clearTimer]\n  );\n\n  const hideAll = useCallback(() => {\n    timers.current.forEach((t) => clearTimeout(t));\n    timers.current.clear();\n    setToasts([]);\n  }, []);\n\n  const show = useCallback(\n    (options: ToastOptions) => {\n      counter.current += 1;\n      const id = `toast-${counter.current}`;\n      const duration = options.duration ?? defaultDuration;\n\n      setToasts((prev) => {\n        const next = [...prev, { ...options, id }];\n        // The oldest are dropped, not the newcomers: a new toast is always\n        // visible.\n        const overflow = next.length - maxVisible;\n        if (overflow > 0) {\n          next.slice(0, overflow).forEach((t) => clearTimer(t.id));\n          return next.slice(overflow);\n        }\n        return next;\n      });\n\n      // It appears without focus: screen readers only hear it if it is\n      // announced (iOS ignores accessibilityRole=\"alert\" on its own).\n      AccessibilityInfo.announceForAccessibility(options.message ? `${options.title}. ${options.message}` : options.title);\n\n      if (duration > 0) {\n        timers.current.set(\n          id,\n          setTimeout(() => hide(id), duration)\n        );\n      }\n      return id;\n    },\n    [defaultDuration, maxVisible, hide, clearTimer]\n  );\n\n  // When the provider unmounts no setTimeout must be left pointing at a\n  // setState of an already unmounted tree.\n  useEffect(() => {\n    const pending = timers.current;\n    return () => {\n      pending.forEach((t) => clearTimeout(t));\n      pending.clear();\n    };\n  }, []);\n\n  const value = useMemo<ToastContextValue>(() => ({ show, hide, hideAll }), [show, hide, hideAll]);\n\n  useEffect(() => {\n    bridge.set(value);\n    return () => bridge.set(null);\n  }, [value]);\n\n  const hostPosition =\n    position === 'top'\n      ? { top: insets.top + 8 }\n      : { bottom: insets.bottom + 8, flexDirection: 'column-reverse' as const };\n\n  return (\n    <ToastContext.Provider value={value}>\n      {children}\n      {toasts.length > 0 && (\n        <View style={[styles.host, hostPosition]} pointerEvents=\"box-none\" testID=\"toast-host\">\n          {toasts.map((t) => (\n            <AnimatedToast key={t.id}>\n              <Toast\n                title={t.title}\n                message={t.message}\n                variant={t.variant}\n                hideCloseButton={t.hideCloseButton}\n                onDismiss={() => hide(t.id)}\n                onPress={\n                  t.onPress\n                    ? () => {\n                        t.onPress?.();\n                        hide(t.id);\n                      }\n                    : undefined\n                }\n              />\n            </AnimatedToast>\n          ))}\n        </View>\n      )}\n    </ToastContext.Provider>\n  );\n}\n\nexport function useToast(): ToastContextValue {\n  const ctx = useContext(ToastContext);\n  if (!ctx) {\n    throw new Error('orn-ui: useToast must be used within a <ToastProvider>.');\n  }\n  return ctx;\n}\n"
     },
     {
       "path": "organisms/imperativeBridge.ts",
-      "content": "/**\n * Puente entre el proveedor montado y el código que no es un componente\n * (servicios, capa de API, interceptores). El proveedor se registra al montar y\n * se borra al desmontar, así que fuera del árbol nunca queda una referencia\n * viva a un contexto muerto.\n */\nexport interface ImperativeBridge<T> {\n  set: (value: T | null) => void;\n  get: () => T | null;\n}\n\nexport function createImperativeBridge<T>(providerName: string): ImperativeBridge<T> {\n  let current: T | null = null;\n\n  return {\n    set: (value) => {\n      current = value;\n    },\n    get: () => {\n      if (!current && __DEV__) {\n        console.warn(\n          `orn-ui: se llamó a la API imperativa sin un <${providerName}> montado. La llamada se ignoró.`\n        );\n      }\n      return current;\n    },\n  };\n}\n"
+      "content": "/**\n * Bridge between the mounted provider and code that isn't a component\n * (services, API layer, interceptors). The provider registers itself on mount\n * and clears itself on unmount, so outside the tree there is never a live\n * reference left to a dead context.\n */\nexport interface ImperativeBridge<T> {\n  set: (value: T | null) => void;\n  get: () => T | null;\n}\n\nexport function createImperativeBridge<T>(providerName: string): ImperativeBridge<T> {\n  let current: T | null = null;\n\n  return {\n    set: (value) => {\n      current = value;\n    },\n    get: () => {\n      if (!current && __DEV__) {\n        console.warn(\n          `orn-ui: the imperative API was called without a mounted <${providerName}>. The call was ignored.`\n        );\n      }\n      return current;\n    },\n  };\n}\n"
     }
   ],
   "registryDependencies": [

package/registry/toast.json

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

package/registry/transition.json

@@ -10,7 +10,7 @@
   "files": [
     {
       "path": "atoms/Transition.tsx",
-      "content": "import React, { memo, useEffect, useMemo, useRef, useState } from 'react';\nimport { AccessibilityInfo, Animated, Easing, type StyleProp, type ViewStyle } from 'react-native';\nimport { useTheme } from '../theme/UIProvider';\n\nexport type TransitionPreset =\n  | 'fade'\n  | 'scale'\n  | 'pop'\n  | 'slide-up'\n  | 'slide-down'\n  | 'slide-left'\n  | 'slide-right';\n\nexport interface TransitionProps {\n  children: React.ReactNode;\n  /** Enters when true, exits (and unmounts) when false. @default true */\n  visible?: boolean;\n  /** One or more: 'fade scale' combines opacity and scale. @default 'fade' */\n  preset?: TransitionPreset | TransitionPreset[];\n  /** Timing duration in ms. @default tokens.duration.base */\n  duration?: number;\n  /** ms before starting. A per-index delay staggers a list. @default 0 */\n  delay?: number;\n  /** Pixels traveled by the slide presets. @default 24 */\n  distance?: number;\n  /** Spring instead of timing (implicit in 'pop'). */\n  spring?: boolean;\n  /** Also animates the first render. When false it starts already present. @default true */\n  appear?: boolean;\n  /** Keeps the node mounted on exit, only hides it. @default false */\n  keepMounted?: boolean;\n  /**\n   * 0→1 progress driven from outside. With this, Transition only interpolates:\n   * whoever passes it decides when and how it advances (a PanResponder, for example).\n   */\n  value?: Animated.Value;\n  onEntered?: () => void;\n  onExited?: () => void;\n  style?: StyleProp<ViewStyle>;\n  testID?: string;\n}\n\nconst SCALE_FROM: Record<'scale' | 'pop', number> = { scale: 0.92, pop: 0.8 };\n\n/**\n * Sigue el ajuste de \"reducir movimiento\" del sistema: con él activo las\n * animaciones saltan al estado final en vez de desactivarse, así que los\n * callbacks y el desmontaje siguen ocurriendo igual.\n */\nexport function useReduceMotion(): boolean {\n  const [reduceMotion, setReduceMotion] = useState(false);\n\n  useEffect(() => {\n    let alive = true;\n    // Sólo se actualiza el estado si el ajuste está activo: el valor inicial ya\n    // es `false` y un setState de false a false costaría un render por montaje.\n    AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {\n      if (alive && enabled) setReduceMotion(true);\n    });\n    const sub = AccessibilityInfo.addEventListener('reduceMotionChanged', setReduceMotion);\n    return () => {\n      alive = false;\n      sub.remove();\n    };\n  }, []);\n\n  return reduceMotion;\n}\n\n/**\n * Transition\n * Envuelve cualquier árbol y lo anima al entrar y al salir. Todos los presets\n * se reducen a `opacity` y `transform` sobre un único Animated.Value, que es\n * lo que `useNativeDriver` sabe mandar al hilo nativo: la animación corre ahí\n * y el hilo de JS no participa de ningún frame — por eso no hay presets de\n * alto, ancho o color, que obligarían a volver a JS en cada frame.\n *\n * El nodo se mantiene montado hasta que termina la animación de salida, y el\n * comportamiento es idéntico en iOS y Android: no hay ninguna rama por\n * plataforma.\n */\nexport const Transition = memo(\n  ({\n    children,\n    visible = true,\n    preset = 'fade',\n    duration,\n    delay = 0,\n    distance = 24,\n    spring,\n    appear = true,\n    keepMounted = false,\n    value,\n    onEntered,\n    onExited,\n    style,\n    testID,\n  }: TransitionProps) => {\n    const theme = useTheme();\n    const reduceMotion = useReduceMotion();\n    const internal = useRef(new Animated.Value(visible && !appear ? 1 : 0)).current;\n    const progress = value ?? internal;\n    const driven = value === undefined;\n\n    const [mounted, setMounted] = useState(visible || keepMounted);\n\n    // Los callbacks viven en un ref: pasados inline cambian de identidad en\n    // cada render y, como dependencias del efecto, reiniciarían la animación.\n    const callbacks = useRef({ onEntered, onExited });\n    useEffect(() => {\n      callbacks.current = { onEntered, onExited };\n    });\n\n    const presetKey = Array.isArray(preset) ? preset.join(' ') : preset;\n    const presets = useMemo(() => presetKey.split(' ') as TransitionPreset[], [presetKey]);\n\n    useEffect(() => {\n      if (visible) setMounted(true);\n    }, [visible]);\n\n    useEffect(() => {\n      if (!driven) return;\n      const toValue = visible ? 1 : 0;\n      const useSpring = spring ?? presets.includes('pop');\n\n      const animation = reduceMotion\n        ? Animated.timing(progress, { toValue, duration: 0, delay, useNativeDriver: true })\n        : useSpring\n          ? Animated.spring(progress, { toValue, delay, friction: 9, tension: 90, useNativeDriver: true })\n          : Animated.timing(progress, {\n              toValue,\n              delay,\n              duration: duration ?? theme.tokens.duration.base,\n              easing: visible ? Easing.out(Easing.cubic) : Easing.in(Easing.cubic),\n              useNativeDriver: true,\n            });\n\n      animation.start(({ finished }) => {\n        if (!finished) return;\n        if (visible) {\n          callbacks.current.onEntered?.();\n          return;\n        }\n        callbacks.current.onExited?.();\n        if (!keepMounted) setMounted(false);\n      });\n\n      return () => animation.stop();\n    }, [visible, driven, reduceMotion, spring, delay, duration, keepMounted, presets, progress, theme]);\n\n    const animatedStyle = useMemo(() => {\n      type Interpolated = Animated.AnimatedInterpolation<number>;\n      const transform: Array<{ scale: Interpolated } | { translateX: Interpolated } | { translateY: Interpolated }> = [];\n      let opacity: Animated.Value | undefined;\n\n      for (const item of presets) {\n        if (item === 'fade') {\n          opacity = progress;\n          continue;\n        }\n        if (item === 'scale' || item === 'pop') {\n          transform.push({\n            scale: progress.interpolate({ inputRange: [0, 1], outputRange: [SCALE_FROM[item], 1] }),\n          });\n          continue;\n        }\n        const vertical = item === 'slide-up' || item === 'slide-down';\n        const from = item === 'slide-up' || item === 'slide-left' ? distance : -distance;\n        const offset = progress.interpolate({ inputRange: [0, 1], outputRange: [from, 0] });\n        transform.push(vertical ? { translateY: offset } : { translateX: offset });\n      }\n\n      return { opacity, transform };\n    }, [presets, progress, distance]);\n\n    if (!mounted) return null;\n\n    return (\n      <Animated.View\n        testID={testID}\n        pointerEvents={visible ? undefined : 'none'}\n        style={[style, animatedStyle]}\n      >\n        {children}\n      </Animated.View>\n    );\n  }\n);\nTransition.displayName = 'Transition';\n"
+      "content": "import React, { memo, useEffect, useMemo, useRef, useState } from 'react';\nimport { Animated, Easing, type StyleProp, type ViewStyle } from 'react-native';\nimport { useTheme } from '../theme/UIProvider';\nimport { useReduceMotion } from '../theme/useReduceMotion';\n\nexport type TransitionPreset =\n  | 'fade'\n  | 'scale'\n  | 'pop'\n  | 'slide-up'\n  | 'slide-down'\n  | 'slide-left'\n  | 'slide-right';\n\nexport interface TransitionProps {\n  /** Content that enters and exits. */\n  children: React.ReactNode;\n  /** Enters when true, exits (and unmounts) when false. @default true */\n  visible?: boolean;\n  /** One or more: 'fade scale' combines opacity and scale. @default 'fade' */\n  preset?: TransitionPreset | TransitionPreset[];\n  /** Timing duration in ms. @default tokens.duration.base */\n  duration?: number;\n  /** ms before starting. A per-index delay staggers a list. @default 0 */\n  delay?: number;\n  /** Pixels traveled by the slide presets. @default tokens.spacing.xxl (24) */\n  distance?: number;\n  /** Spring instead of timing (implicit in 'pop'). */\n  spring?: boolean;\n  /** Also animates the first render. When false it starts already present. @default true */\n  appear?: boolean;\n  /** Keeps the node mounted on exit, only hides it. @default false */\n  keepMounted?: boolean;\n  /**\n   * 0→1 progress driven from outside. With this, Transition only interpolates:\n   * whoever passes it decides when and how it advances (a PanResponder, for example).\n   */\n  value?: Animated.Value;\n  /** Called when the enter animation finishes. Not called when driven by `value`. */\n  onEntered?: () => void;\n  /** Called when the exit animation finishes, before unmounting. Not called when driven by `value`. */\n  onExited?: () => void;\n  style?: StyleProp<ViewStyle>;\n  testID?: string;\n}\n\nconst SCALE_FROM: Record<'scale' | 'pop', number> = { scale: 0.92, pop: 0.8 };\nconst hiddenStyle: ViewStyle = { pointerEvents: 'none' };\n/** 'pop' spring: bounces once and settles (~350 ms), without oscillating. */\nconst POP_SPRING = { friction: 9, tension: 90 } as const;\n\n// Lives in theme/ (UIProvider uses it too); re-exported here so existing\n// imports don't break.\nexport { useReduceMotion };\n\n/**\n * Transition\n * Wraps any tree and animates it on enter and exit. Every preset boils down\n * to `opacity` and `transform` over a single Animated.Value, which is what\n * `useNativeDriver` knows how to send to the native thread: the animation runs\n * there and the JS thread takes part in no frame — that is why there are no\n * height, width or color presets, which would force a return to JS every frame.\n *\n * The node stays mounted until the exit animation finishes, and the behavior\n * is identical on iOS and Android: there is no per-platform branch. While\n * exiting (or hidden with `keepMounted`) it stops receiving touches and leaves\n * the accessibility tree: what is invisible isn't read.\n *\n * Gestalt, common fate: what enters or exits together is perceived as a group;\n * with a per-index `delay` the list enters in reading order (continuity).\n * Respects Reduce Motion: jumps to the final state, callbacks still fire.\n */\nexport const Transition = memo(\n  ({\n    children,\n    visible = true,\n    preset = 'fade',\n    duration,\n    delay = 0,\n    distance,\n    spring,\n    appear = true,\n    keepMounted = false,\n    value,\n    onEntered,\n    onExited,\n    style,\n    testID,\n  }: TransitionProps) => {\n    const theme = useTheme();\n    const travel = distance ?? theme.tokens.spacing.xxl;\n    // Resolved here, not inside the effect: depending on `theme` restarted the\n    // animation (and fired onEntered again) every time the theme changed.\n    const resolvedDuration = duration ?? theme.tokens.duration.base;\n    const reduceMotion = useReduceMotion();\n    const internal = useRef(new Animated.Value(visible && !appear ? 1 : 0)).current;\n    const progress = value ?? internal;\n    const driven = value === undefined;\n\n    const [mounted, setMounted] = useState(visible || keepMounted);\n\n    // The callbacks live in a ref: passed inline they change identity on\n    // every render and, as effect dependencies, would restart the animation.\n    const callbacks = useRef({ onEntered, onExited });\n    useEffect(() => {\n      callbacks.current = { onEntered, onExited };\n    });\n\n    const presetKey = Array.isArray(preset) ? preset.join(' ') : preset;\n    const presets = useMemo(() => presetKey.split(' ') as TransitionPreset[], [presetKey]);\n\n    useEffect(() => {\n      if (visible) setMounted(true);\n    }, [visible]);\n\n    useEffect(() => {\n      if (!driven) return;\n      const toValue = visible ? 1 : 0;\n      const useSpring = spring ?? presets.includes('pop');\n\n      const animation = reduceMotion\n        ? Animated.timing(progress, { toValue, duration: 0, delay, useNativeDriver: true })\n        : useSpring\n          ? Animated.spring(progress, { toValue, delay, ...POP_SPRING, useNativeDriver: true })\n          : Animated.timing(progress, {\n              toValue,\n              delay,\n              duration: resolvedDuration,\n              easing: visible ? Easing.out(Easing.cubic) : Easing.in(Easing.cubic),\n              useNativeDriver: true,\n            });\n\n      animation.start(({ finished }) => {\n        if (!finished) return;\n        if (visible) {\n          callbacks.current.onEntered?.();\n          return;\n        }\n        callbacks.current.onExited?.();\n        if (!keepMounted) setMounted(false);\n      });\n\n      return () => animation.stop();\n    }, [visible, driven, reduceMotion, spring, delay, resolvedDuration, keepMounted, presets, progress]);\n\n    const animatedStyle = useMemo(() => {\n      type Interpolated = Animated.AnimatedInterpolation<number>;\n      const transform: Array<{ scale: Interpolated } | { translateX: Interpolated } | { translateY: Interpolated }> = [];\n      let opacity: Animated.Value | undefined;\n\n      for (const item of presets) {\n        if (item === 'fade') {\n          opacity = progress;\n          continue;\n        }\n        if (item === 'scale' || item === 'pop') {\n          transform.push({\n            scale: progress.interpolate({ inputRange: [0, 1], outputRange: [SCALE_FROM[item], 1] }),\n          });\n          continue;\n        }\n        const vertical = item === 'slide-up' || item === 'slide-down';\n        const from = item === 'slide-up' || item === 'slide-left' ? travel : -travel;\n        const offset = progress.interpolate({ inputRange: [0, 1], outputRange: [from, 0] });\n        transform.push(vertical ? { translateY: offset } : { translateX: offset });\n      }\n\n      return { opacity, transform };\n    }, [presets, progress, travel]);\n\n    if (!mounted) return null;\n\n    return (\n      <Animated.View\n        testID={testID}\n        accessibilityElementsHidden={!visible}\n        importantForAccessibility={visible ? 'auto' : 'no-hide-descendants'}\n        style={[style, animatedStyle, !visible && hiddenStyle]}\n      >\n        {children}\n      </Animated.View>\n    );\n  }\n);\nTransition.displayName = 'Transition';\n"
     }
   ],
   "registryDependencies": [

package/registry/wizard.json

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

package/src/atoms/Avatar.tsx

@@ -1,40 +1,131 @@
-import React, { memo } from 'react';
-import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
-import { useColors } from '../theme/UIProvider';
+import React, { memo, useState } from 'react';
+import {
+  Image as RNImage,
+  StyleSheet,
+  Text,
+  View,
+  type ImageSourcePropType,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { useAllowFontScaling, useColors, useTheme } from '../theme/UIProvider';
+import { Icon } from '../icons/Icon';
+import type { IconName } from '../icons/types';
 
 export interface AvatarProps {
+  /** Diameter in pt. @default 44 */
   size?: number;
+  /** Photo. If it fails to load, falls back to the initials of `name` (or the icon). */
+  source?: ImageSourcePropType;
+  /** Person's name: produces the initials and the accessible name. */
+  name?: string;
+  /** Icon shown when there is no photo or name. @default 'user' */
+  iconName?: IconName;
+  /** Fill of the circle. @default colors.primarySoft */
   backgroundColor?: string;
-  children: React.ReactNode;
+  /** Color of the initials and icon. @default colors.primaryText */
+  color?: string;
+  /** Custom content; takes precedence over source/name/iconName. */
+  children?: React.ReactNode;
+  /** Accessible name. Without it (and without `name`) the avatar is decorative. @default name */
+  accessibilityLabel?: string;
   style?: StyleProp<ViewStyle>;
+  testID?: string;
 }
 
 const styles = StyleSheet.create({
-  circle: { justifyContent: 'center', alignItems: 'center' },
+  circle: { justifyContent: 'center', alignItems: 'center', overflow: 'hidden' },
 });
 
+/** "Ada Lovelace" → "AL", "ada" → "A", "  " → "". Handles characters outside the BMP. */
+export function initialsOf(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  if (words.length === 0) return '';
+  const first = Array.from(words[0] as string)[0] ?? '';
+  const last = words.length > 1 ? (Array.from(words[words.length - 1] as string)[0] ?? '') : '';
+  return (first + last).toUpperCase();
+}
+
 /**
  * Avatar
- * Círculo con ícono/iniciales adentro. Usado a la izquierda de filas de
- * lista o como header de detalle (junto a AvatarHeader).
+ * Circle with a photo, initials or an icon. Used on the left of list rows
+ * or as a detail header (alongside AvatarHeader).
+ *
+ * Priority: `children` → `source` (if it loads) → initials of `name` →
+ * `iconName` → `user` icon. A broken photo doesn't leave an empty circle: it
+ * falls back to the initials.
+ *
+ * Gestalt:
+ * - Similarity: all avatars in a list share shape and size, so a column of
+ *   people scans as a series even when it mixes photos, initials and icons.
+ * - Closure: the circle clips the photo (overflow hidden); initials and the
+ *   icon scale with `size` so the content always stays inside.
+ *
+ * Accessibility: with `name` (or `accessibilityLabel`) it announces itself as
+ * an image with that name; with neither it is decorative.
  */
-export const Avatar = memo(({ size = 44, backgroundColor, children, style }: AvatarProps) => {
-  const colors = useColors();
-  return (
-    <View
-      style={[
-        styles.circle,
-        {
-          width: size,
-          height: size,
-          borderRadius: size / 2,
-          backgroundColor: backgroundColor || colors.primarySoft,
-        },
-        style,
-      ]}
-    >
-      {children}
-    </View>
-  );
-});
+export const Avatar = memo(
+  ({
+    size = 44,
+    source,
+    name,
+    iconName,
+    backgroundColor,
+    color,
+    children,
+    accessibilityLabel,
+    style,
+    testID,
+  }: AvatarProps) => {
+    const colors = useColors();
+    const theme = useTheme();
+    const allowFontScaling = useAllowFontScaling();
+    const [failed, setFailed] = useState(false);
+    const fg = color ?? colors.primaryText;
+    const label = accessibilityLabel ?? name;
+    const initials = name ? initialsOf(name) : '';
+
+    let content: React.ReactNode = children;
+    if (content == null) {
+      if (source && !failed) {
+        content = (
+          <RNImage
+            source={source}
+            style={{ width: size, height: size }}
+            onError={() => setFailed(true)}
+            accessibilityIgnoresInvertColors
+          />
+        );
+      } else if (initials) {
+        content = (
+          <Text
+            allowFontScaling={allowFontScaling}
+            numberOfLines={1}
+            style={{ color: fg, fontSize: Math.round(size * 0.4), fontWeight: theme.tokens.fontWeight.semibold }}
+          >
+            {initials}
+          </Text>
+        );
+      } else {
+        content = <Icon name={iconName ?? 'user'} size={Math.round(size * 0.5)} color={fg} />;
+      }
+    }
+
+    return (
+      <View
+        testID={testID}
+        accessible={!!label}
+        accessibilityRole={label ? 'image' : undefined}
+        accessibilityLabel={label}
+        style={[
+          styles.circle,
+          { width: size, height: size, borderRadius: size / 2, backgroundColor: backgroundColor || colors.primarySoft },
+          style,
+        ]}
+      >
+        {content}
+      </View>
+    );
+  }
+);
 Avatar.displayName = 'Avatar';

package/src/atoms/Badge.tsx

@@ -6,29 +6,40 @@ import { useAllowFontScaling, useTheme } from '../theme/UIProvider';
 export type BadgeVariant = 'success' | 'error' | 'warning' | 'info' | 'neutral';
 
 export interface BadgeProps {
+  /** Text of the pill, on a single line (truncated with "…"). */
   label: string;
+  /** Semantic color set: success, error, warning, info or neutral. @default 'neutral' */
   variant?: BadgeVariant;
   /** Manual override, takes precedence over `variant`. */
   backgroundColor?: string;
+  /** Manual text color, takes precedence over `variant`. */
   textColor?: string;
   style?: StyleProp<ViewStyle>;
 }
 
 const useStyles = createStyles((theme) => ({
   badge: {
-    paddingHorizontal: theme.tokens.spacing.md - 2,
-    paddingVertical: theme.tokens.spacing.xs + 1,
+    paddingHorizontal: theme.tokens.spacing.md,
+    paddingVertical: theme.tokens.spacing.xs,
     borderRadius: theme.tokens.radius.full,
     alignSelf: 'flex-start',
   },
-  text: { fontSize: theme.tokens.fontSize.xs, fontWeight: theme.tokens.fontWeight.bold, letterSpacing: 0.3 },
+  text: { fontSize: theme.tokens.fontSize.xs, fontWeight: theme.tokens.fontWeight.bold, letterSpacing: theme.tokens.letterSpacing.wide },
 }));
 
 /**
  * Badge
- * Pill de estado. `variant` cubre los casos comunes (éxito/error/advertencia/
- * info/neutral); `backgroundColor`/`textColor` quedan para casos que no
- * encajan en el set semántico.
+ * Status pill. `variant` covers the common cases (success/error/warning/
+ * info/neutral); `backgroundColor`/`textColor` are for cases that don't
+ * fit the semantic set.
+ *
+ * Gestalt, similarity: all badges share shape, size and typography; only
+ * the color changes, and it changes by meaning (green = ok, red = error…),
+ * so a column of statuses scans at a glance. The meaning also goes in the
+ * text: never rely on color alone (color blindness).
+ * Every `*Soft`/`*Text` pair in the theme meets WCAG AA in light and dark;
+ * with custom colors, contrast is up to whoever passes them.
+ * A single line: a long label is truncated with "…" instead of deforming the pill.
  */
 export const Badge = memo(({ label, variant = 'neutral', backgroundColor, textColor, style }: BadgeProps) => {
   const theme = useTheme();
@@ -37,8 +48,8 @@ export const Badge = memo(({ label, variant = 'neutral', backgroundColor, textCo
   const { colors } = theme;
 
   const palette: Record<BadgeVariant, { bg: string; fg: string }> = {
-    // fg es el rol `*Text`, no el acento pleno: el acento sobre su propio
-    // tinte da ~2.2:1 en light — el label quedaba ilegible.
+    // fg is the `*Text` role, not the full accent: the accent over its own
+    // tint gives ~2.2:1 in light — the label was unreadable.
     success: { bg: colors.successSoft, fg: colors.successText },
     error: { bg: colors.errorSoft, fg: colors.errorText },
     warning: { bg: colors.warningSoft, fg: colors.warningText },
@@ -48,7 +59,7 @@ export const Badge = memo(({ label, variant = 'neutral', backgroundColor, textCo
 
   return (
     <View style={[styles.badge, { backgroundColor: backgroundColor ?? palette[variant].bg }, style]}>
-      <Text allowFontScaling={allowFontScaling} style={[styles.text, { color: textColor ?? palette[variant].fg }]}>
+      <Text allowFontScaling={allowFontScaling} numberOfLines={1} style={[styles.text, { color: textColor ?? palette[variant].fg }]}>
         {label}
       </Text>
     </View>