orn-ui 0.2.9 → 0.3.0

package/src/theme/NativeOverlay.tsx

@@ -0,0 +1,269 @@
+import React, { createContext, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { Modal, Platform, View, type ModalProps, type ViewStyle } from 'react-native';
+
+/**
+ * NativeOverlay
+ * The native `Modal` every orn-ui overlay (Alert, BottomSheet, Modal, Select)
+ * goes through.
+ *
+ * Why: iOS presents a native modal from the root view controller and only one
+ * at a time. A second `<Modal>` that is not rendered inside the first one is
+ * silently ignored while the first is presented, and also while it is still
+ * being dismissed. In practice an Alert from `showAlert()` over an open
+ * BottomSheet never showed, and neither did one opened right after closing a
+ * sheet. Android opens a window per modal and never had the problem: there
+ * this is a plain `Modal`.
+ *
+ * iOS, when an overlay becomes visible:
+ * - Rendered inside another overlay (nested): plain native modal; iOS presents
+ *   it from that one, which works.
+ * - Another overlay is presented and this one is not inside it: it is drawn
+ *   as a layer inside the topmost presented overlay instead of presenting a
+ *   second native modal. Its React context then comes from that overlay's
+ *   position: a provider that wraps only this overlay doesn't reach it.
+ * - Another overlay is closing (exit animation or native dismissal): it waits
+ *   until that one is gone, then presents.
+ */
+
+export interface NativeOverlayProps
+  extends Pick<
+    ModalProps,
+    'transparent' | 'animationType' | 'presentationStyle' | 'statusBarTranslucent' | 'onRequestClose' | 'hardwareAccelerated'
+  > {
+  /**
+   * The overlay is logically hidden but still mounted to play its exit
+   * animation: it stays on screen, but no other overlay may layer into it.
+   */
+  closing?: boolean;
+  /**
+   * A dialog (Alert) always ends up on top: whatever gets layered into it is
+   * drawn beneath its own content, and as a layer it is drawn after any
+   * non-dialog layer of the same host.
+   */
+  dialog?: boolean;
+  children: React.ReactNode;
+}
+
+type Mode = 'pending' | 'native' | 'layer' | 'wait';
+
+interface Host {
+  id: number;
+  closing: boolean;
+}
+
+const fill: ViewStyle = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 };
+/** After unmount, how long iOS may still be dismissing the native modal. */
+const DISMISS_SETTLE_MS = 450;
+
+// Module-level registry: overlays live in different React subtrees, and the
+// constraint they share (one native presentation at a time) is global too.
+const hosts: Host[] = [];
+const layers = new Map<number, Map<number, { node: React.ReactNode; dialog: boolean }>>();
+const ownerOf = new Map<number, number>();
+let nextId = 1;
+
+// Two channels, so publishing a layer (every render of a layered overlay)
+// only re-renders that host's outlet, never the overlays themselves — which
+// would publish again and loop.
+const hostListeners = new Set<() => void>();
+const layerListeners = new Map<number, Set<() => void>>();
+
+/** The host stack changed: waiting/layered overlays re-evaluate. */
+function notify() {
+  hostListeners.forEach((listener) => listener());
+}
+
+/** A host's layers changed: only its outlet re-renders. */
+function notifyLayers(hostId: number) {
+  layerListeners.get(hostId)?.forEach((listener) => listener());
+}
+
+function useChannel(subscribe: (listener: () => void) => () => void) {
+  const [, setVersion] = useState(0);
+  useEffect(() => subscribe(() => setVersion((v) => v + 1)), [subscribe]);
+}
+
+const subscribeHosts = (listener: () => void) => {
+  hostListeners.add(listener);
+  return () => {
+    hostListeners.delete(listener);
+  };
+};
+
+function liveTop(): Host | undefined {
+  const top = hosts[hosts.length - 1];
+  return top && !top.closing ? top : undefined;
+}
+
+function decide(parentHost: number | null): Mode {
+  if (hosts.length === 0) return 'native';
+  const top = liveTop();
+  if (!top) return 'wait';
+  // Nested inside the topmost overlay: iOS can present it from there.
+  if (top.id === parentHost) return 'native';
+  return 'layer';
+}
+
+function unpublish(id: number) {
+  const owner = ownerOf.get(id);
+  if (owner === undefined) return;
+  layers.get(owner)?.delete(id);
+  ownerOf.delete(id);
+  notifyLayers(owner);
+}
+
+/** Takes the native slot right away, before any later overlay decides. */
+function claim(id: number, closing: boolean) {
+  if (hosts.some((h) => h.id === id)) return;
+  hosts.push({ id, closing });
+  notify();
+}
+
+function removeHost(id: number) {
+  const index = hosts.findIndex((h) => h.id === id);
+  if (index < 0) return;
+  hosts.splice(index, 1);
+  notify();
+}
+
+/** Id of the native overlay this subtree is rendered in, if any. */
+const HostContext = createContext<number | null>(null);
+
+/** Draws, inside a native host, the layers other overlays put into it. */
+function LayerOutlet({ hostId }: { hostId: number }) {
+  const [, setVersion] = useState(0);
+  // Layout effect + an immediate re-read: a layer may have been published in
+  // the same commit, before this outlet subscribed.
+  useLayoutEffect(() => {
+    const listener = () => setVersion((v) => v + 1);
+    if (!layerListeners.has(hostId)) layerListeners.set(hostId, new Set());
+    layerListeners.get(hostId)!.add(listener);
+    if (layers.get(hostId)?.size) listener();
+    return () => {
+      layerListeners.get(hostId)?.delete(listener);
+    };
+  }, [hostId]);
+  const own = layers.get(hostId);
+  if (!own || own.size === 0) return null;
+  // Dialogs last, so they are drawn on top of sheets and modals.
+  const ordered = [...own.entries()].sort(([, a], [, b]) => Number(a.dialog) - Number(b.dialog));
+  return (
+    <>
+      {ordered.map(([key, layer]) => (
+        <View key={key} style={fill} pointerEvents="box-none">
+          {layer.node}
+        </View>
+      ))}
+    </>
+  );
+}
+
+export function NativeOverlay({ closing = false, dialog = false, children, ...modalProps }: NativeOverlayProps) {
+  const ios = Platform.OS === 'ios';
+  const parentHost = useContext(HostContext);
+  const idRef = useRef(0);
+  if (idRef.current === 0) idRef.current = nextId++;
+  const id = idRef.current;
+  useChannel(subscribeHosts);
+
+  // Decided in a layout effect, not during render: layout effects run in tree
+  // order before paint, so when two overlays mount in the same commit the
+  // first one claims the native slot before the second one decides.
+  const [mode, setMode] = useState<Mode>(ios ? 'pending' : 'native');
+
+  useLayoutEffect(() => {
+    if (!ios) return;
+    if (mode === 'pending') {
+      const next = decide(parentHost);
+      if (next === 'native') claim(id, closing);
+      setMode(next);
+      return;
+    }
+    if (mode === 'wait' && !closing) {
+      const next = decide(parentHost);
+      if (next === 'native') claim(id, closing);
+      if (next !== 'wait') setMode(next);
+    }
+    // The host it layered into started closing or went away: move out.
+    if (mode === 'layer' && !closing) {
+      const owner = ownerOf.get(id);
+      const host = owner === undefined ? undefined : hosts.find((h) => h.id === owner);
+      if (owner !== undefined && (!host || host.closing)) {
+        unpublish(id);
+        const next = decide(parentHost);
+        if (next === 'native') claim(id, closing);
+        setMode(next);
+      }
+    }
+  });
+
+  // Native host bookkeeping.
+  useLayoutEffect(() => {
+    if (!ios || mode !== 'native') return;
+    const existing = hosts.find((h) => h.id === id);
+    if (!existing) hosts.push({ id, closing });
+    else if (existing.closing !== closing) existing.closing = closing;
+    else return;
+    notify();
+  }, [ios, mode, closing, id]);
+
+  // Layer publishing: every render, so prop changes reach the host.
+  useLayoutEffect(() => {
+    if (!ios || mode !== 'layer') return;
+    let owner = ownerOf.get(id);
+    if (owner === undefined) {
+      owner = liveTop()?.id;
+      // The host it chose started closing in the same commit (a sheet closed
+      // and an alert opened in one tick): decide again, usually to wait.
+      if (owner === undefined) {
+        const next = decide(parentHost);
+        if (next === 'native') claim(id, closing);
+        setMode(next);
+        return;
+      }
+      ownerOf.set(id, owner);
+    }
+    if (!layers.has(owner)) layers.set(owner, new Map());
+    layers.get(owner)!.set(id, { node: <HostContext.Provider value={owner}>{children}</HostContext.Provider>, dialog });
+    notifyLayers(owner);
+  });
+
+  // Unmount: a layer just leaves; a native host stays "closing" while iOS
+  // finishes dismissing it, so the next overlay doesn't present too early.
+  useEffect(
+    () => () => {
+      if (!ios) return;
+      unpublish(id);
+      const host = hosts.find((h) => h.id === id);
+      if (host) {
+        host.closing = true;
+        notify();
+        setTimeout(() => removeHost(id), DISMISS_SETTLE_MS);
+      }
+    },
+    [ios, id]
+  );
+
+  if (!ios || mode === 'native') {
+    return (
+      <Modal visible {...modalProps}>
+        <HostContext.Provider value={id}>
+          {/* A dialog host draws what was layered into it underneath itself. */}
+          {ios && dialog && <LayerOutlet hostId={id} />}
+          {children}
+          {ios && !dialog && <LayerOutlet hostId={id} />}
+        </HostContext.Provider>
+      </Modal>
+    );
+  }
+
+  // 'layer' renders inside the host; 'wait' and 'pending' render nothing yet.
+  return null;
+}
+
+/** Test-only: clears the registry between tests. */
+export function __resetNativeOverlays() {
+  hosts.splice(0);
+  layers.clear();
+  ownerOf.clear();
+}

package/src/theme/UIProvider.tsx

@@ -1,30 +1,58 @@
-import React, { createContext, useContext, useMemo, useState, useCallback, useRef } from 'react';
-import { Appearance, useColorScheme } from 'react-native';
+import React, { createContext, useContext, useMemo, useState, useCallback, useEffect } from 'react';
+import { Appearance, useColorScheme, type ViewStyle } from 'react-native';
+import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';
 import { defaultTheme } from './createTheme';
 import { defaultLabels, type Labels } from './labels';
-import { zeroInsets, type EdgeInsets } from './insets';
+import type { EdgeInsets } from './insets';
 import type { Theme, ThemePair } from './types';
 import { renderDefaultIcon } from '../icons/defaultIcons';
 import type { IconRenderer } from '../icons/types';
+import { KeyboardHandled, KeyboardPanArea } from './KeyboardAvoidance';
 
 export type ThemeMode = 'system' | 'light' | 'dark';
 
 /**
- * Un `<Modal>`/`<BottomSheet>` nativo abre su propia ventana (en Android
- * siempre; en iOS según `presentationStyle`), así que los insets medidos en
- * la raíz de la app pueden no valer ahí adentro. Este boundary es el punto de
- * inyección: el default sólo repite los insets ambientes (comportamiento de
- * siempre, cero deps), pero `SafeAreaUIProvider` lo reemplaza por uno que
- * monta un `<SafeAreaProvider>` nuevo y remide dentro de esa ventana.
+ * A native `<Modal>`/`<BottomSheet>` opens its own window (always on Android;
+ * on iOS depending on `presentationStyle`), so the insets measured at the app
+ * root may not hold in there. The boundary mounts a new `<SafeAreaProvider>`
+ * inside that window and re-measures; until the first measurement arrives it
+ * repeats the ambient insets.
  */
 export interface ModalSafeAreaBoundaryProps {
   children: (insets: EdgeInsets) => React.ReactNode;
 }
 export type ModalSafeAreaBoundaryComponent = React.ComponentType<ModalSafeAreaBoundaryProps>;
 
-function DefaultModalSafeAreaBoundary({ children }: ModalSafeAreaBoundaryProps) {
-  const insets = useInsets();
-  return <>{children(insets)}</>;
+const probeStyle: ViewStyle = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 };
+
+function sameInsets(a: EdgeInsets, b: EdgeInsets) {
+  return a.top === b.top && a.right === b.right && a.bottom === b.bottom && a.left === b.left;
+}
+
+function InsetsProbe({ onMeasure }: { onMeasure: (insets: EdgeInsets) => void }) {
+  const insets = useSafeAreaInsets();
+  useEffect(() => {
+    onMeasure(insets);
+  }, [insets, onMeasure]);
+  return null;
+}
+
+function RemeasuringModalSafeAreaBoundary({ children }: ModalSafeAreaBoundaryProps) {
+  const ambient = useInsets();
+  const [measured, setMeasured] = useState<EdgeInsets | null>(null);
+  const onMeasure = useCallback(
+    (next: EdgeInsets) => setMeasured((prev) => (prev && sameInsets(prev, next) ? prev : next)),
+    []
+  );
+
+  return (
+    <>
+      <SafeAreaProvider style={probeStyle} pointerEvents="none">
+        <InsetsProbe onMeasure={onMeasure} />
+      </SafeAreaProvider>
+      {children(measured ?? ambient)}
+    </>
+  );
 }
 
 interface UIContextValue {
@@ -51,38 +79,79 @@ export interface UIProviderProps {
   onModeChange?: (mode: ThemeMode) => void;
   /** Icon renderer. Defaults to the included zero-dep glyphs. */
   icons?: IconRenderer;
-  /** Safe area insets (from useSafeAreaInsets()). Defaults to {0,0,0,0}. */
+  /**
+   * Overrides the measured safe area insets. Leave it out: the provider
+   * measures them itself with react-native-safe-area-context.
+   */
   insets?: EdgeInsets;
   labels?: Partial<Labels>;
-  /** @default false, for parity with the rest of the library (accessibility first). */
+  /**
+   * Lets every orn-ui text follow the system font size (Dynamic Type / Android
+   * font scale). Opt-in: layouts are tuned for the default size, so turn it on
+   * only after checking your screens at large sizes.
+   * @default false
+   */
   allowFontScaling?: boolean;
   /**
-   * Source of insets used by `Modal`/`BottomSheet` for their own native
-   * window. Don't pass this by hand — `SafeAreaUIProvider` wires it up itself.
-   * @default repeats the ambient insets (behavior without safe-area-context)
+   * Mounts a `<SafeAreaProvider>` around the app. Pass `false` only if the app
+   * already mounts one above (e.g. expo-router does): insets are then read
+   * from that one.
+   * @default true
+   */
+  mountSafeAreaProvider?: boolean;
+  /**
+   * Keeps the focused Input visible above the keyboard by moving the whole app
+   * up just enough (like Android's adjustPan, on both platforms), with no
+   * Screen or ScrollView needed. Only the root provider does it. Turn it off if
+   * your app already handles the keyboard its own way.
+   * @default true
    */
-  ModalSafeAreaBoundary?: ModalSafeAreaBoundaryComponent;
+  keyboardAvoidance?: boolean;
+}
+
+interface UIProviderBaseProps extends Omit<UIProviderProps, 'insets' | 'mountSafeAreaProvider'> {
+  insets: EdgeInsets;
 }
 
 /**
  * UIProvider
- * Único punto de entrada de la librería: resuelve el theme activo (sistema u
- * override manual), e inyecta íconos, insets y textos por defecto a todo el
- * árbol. No persiste el modo — si el consumidor quiere recordar la preferencia
- * entre sesiones, controla `mode`/`onModeChange` y persiste donde prefiera.
+ * The library's single entry point: resolves the active theme (system or
+ * manual override), measures the safe area insets (react-native-safe-area-context,
+ * a required peer) and injects icons, insets and default texts into the whole
+ * tree. It doesn't persist the mode — if the consumer wants to remember the
+ * preference across sessions, it controls `mode`/`onModeChange` and persists
+ * wherever it prefers.
  */
-export function UIProvider({
+export function UIProvider({ mountSafeAreaProvider = true, ...props }: UIProviderProps) {
+  if (!mountSafeAreaProvider) return <MeasuredUIProvider {...props} />;
+  return (
+    <SafeAreaProvider>
+      <MeasuredUIProvider {...props} />
+    </SafeAreaProvider>
+  );
+}
+
+function MeasuredUIProvider({ insets: override, ...rest }: Omit<UIProviderProps, 'mountSafeAreaProvider'>) {
+  const measured = useSafeAreaInsets();
+  return <UIProviderBase insets={override ?? measured} {...rest} />;
+}
+
+function UIProviderBase({
   children,
   theme = defaultTheme,
   defaultMode = 'system',
   mode: controlledMode,
   onModeChange,
   icons = renderDefaultIcon,
-  insets = zeroInsets,
+  insets,
   labels: labelOverrides,
   allowFontScaling = false,
-  ModalSafeAreaBoundary = DefaultModalSafeAreaBoundary,
-}: UIProviderProps) {
+  keyboardAvoidance = true,
+}: UIProviderBaseProps) {
+  // Only the root provider shifts the app: a nested one (a modal with its own
+  // provider, a test) wraps nothing and doesn't change the layout.
+  const isRoot = useContext(UIContext) === undefined;
+  const ModalSafeAreaBoundary = RemeasuringModalSafeAreaBoundary;
   const systemScheme = useColorScheme();
   const [uncontrolledMode, setUncontrolledMode] = useState<ThemeMode>(defaultMode);
   const isControlled = controlledMode !== undefined;
@@ -96,23 +165,6 @@ export function UIProvider({
     [isControlled, onModeChange]
   );
 
-  // Por instancia, no por módulo: dos `<UIProvider>` en el mismo árbol (tests,
-  // un modal con su propio provider) avisan cada uno si le faltan insets, en
-  // vez de que el segundo se calle porque el primero ya avisó una vez.
-  const warnedAboutInsets = useRef(false);
-
-  // Olvidar `insets` no rompe nada visible al montar: el default de ceros
-  // recién se nota cuando abrís un Modal `full` (se mete abajo del notch) o un
-  // BottomSheet (queda pegado a la barra de gestos). El aviso llega antes.
-  if (__DEV__ && insets === zeroInsets && !warnedAboutInsets.current) {
-    warnedAboutInsets.current = true;
-    console.warn(
-      'orn-ui: <UIProvider> sin `insets`, se usan {top:0,bottom:0,left:0,right:0}. ' +
-        'Los modales y el Screen quedan sin safe area. Pasá `insets={useSafeAreaInsets()}` ' +
-        "o usá <SafeAreaUIProvider> de 'orn-ui/safe-area', que lo cablea solo."
-    );
-  }
-
   const scheme: 'light' | 'dark' =
     mode === 'system' ? (systemScheme === 'dark' ? 'dark' : 'light') : mode;
 
@@ -137,7 +189,18 @@ export function UIProvider({
     [resolvedTheme, mode, setMode, icons, insets, labels, allowFontScaling, ModalSafeAreaBoundary]
   );
 
-  return <UIContext.Provider value={value}>{children}</UIContext.Provider>;
+  let content = children;
+  if (isRoot) {
+    content = keyboardAvoidance ? (
+      <KeyboardPanArea margin={resolvedTheme.tokens.spacing.md} topLimit={insets.top}>
+        {children}
+      </KeyboardPanArea>
+    ) : (
+      <KeyboardHandled>{children}</KeyboardHandled>
+    );
+  }
+
+  return <UIContext.Provider value={value}>{content}</UIContext.Provider>;
 }
 
 function useUIContext(): UIContextValue {
@@ -177,10 +240,10 @@ export function useAllowFontScaling(): boolean {
   return useUIContext().allowFontScaling;
 }
 
-/** Interno: lo consumen `Modal`/`BottomSheet` para remedir insets dentro de su propia ventana nativa. */
+/** Internal: consumed by `Modal`/`BottomSheet` to re-measure insets inside their own native window. */
 export function useModalSafeAreaBoundary(): ModalSafeAreaBoundaryComponent {
   return useUIContext().ModalSafeAreaBoundary;
 }
 
-/** Re-exportado para que tests/consumidores puedan simular cambios de sistema sin RN real. */
+/** Re-exported so tests/consumers can simulate system changes without real RN. */
 export const __testUtils = { Appearance };

package/src/theme/colors.ts

@@ -1,9 +1,9 @@
 /**
- * Utilidades de color sin dependencias, usadas para derivar una familia de
- * roles (relleno / encima / tenue / legible) a partir de un solo hex de marca.
+ * Dependency-free color utilities, used to derive a family of roles
+ * (fill / on-top / soft / readable) from a single brand hex.
  */
 
-/** Contraste mínimo AA para texto normal. */
+/** Minimum AA contrast for normal text. */
 export const AA_CONTRAST = 4.5;
 
 export interface Rgb {
@@ -18,15 +18,15 @@ export interface Hsl {
   l: number;
 }
 
-/** Roles que necesita un acento del theme, en un esquema concreto. */
+/** Roles a theme accent needs, in a given scheme. */
 export interface AccentRoles {
-  /** Relleno pleno: fondo de botón, círculo del paso actual. */
+  /** Solid fill: button background, current step's circle. */
   base: string;
-  /** Texto/ícono que va encima del relleno. */
+  /** Text/icon placed on top of the fill. */
   on: string;
-  /** Fondo tenue: badges, pill del indicador activo. */
+  /** Subtle background: badges, active indicator pill. */
   soft: string;
-  /** El acento legible sobre `surface`: labels, links. */
+  /** The accent legible on `surface`: labels, links. */
   text: string;
 }
 
@@ -35,7 +35,7 @@ const HEX = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
 export function hexToRgb(hex: string): Rgb {
   const match = HEX.exec(hex.trim());
   if (!match) {
-    throw new Error(`orn-ui: se esperaba un color hex como "#7c3aed", se recibió "${hex}".`);
+    throw new Error(`orn-ui: expected a hex color like "#7c3aed", got "${hex}".`);
   }
   const digits = match[1]!;
   const full = digits.length === 3 ? digits.replace(/./g, (c) => c + c) : digits;
@@ -100,13 +100,13 @@ function channelLuminance(value: number) {
   return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
 }
 
-/** Luminancia relativa WCAG de un hex. */
+/** WCAG relative luminance of a hex. */
 export function luminance(hex: string): number {
   const { r, g, b } = hexToRgb(hex);
   return 0.2126 * channelLuminance(r) + 0.7152 * channelLuminance(g) + 0.0722 * channelLuminance(b);
 }
 
-/** Ratio de contraste WCAG entre dos hex: 1 (igual) a 21 (blanco sobre negro). */
+/** WCAG contrast ratio between two hexes: 1 (equal) to 21 (white on black). */
 export function contrast(a: string, b: string): number {
   const la = luminance(a);
   const lb = luminance(b);
@@ -114,8 +114,8 @@ export function contrast(a: string, b: string): number {
 }
 
 /**
- * Blanco si alcanza el contraste AA —es lo que se espera encima de un relleno
- * de color— y si no, el extremo que más contraste dé.
+ * White if it reaches AA contrast —which is what you expect on top of a color
+ * fill— and otherwise whichever extreme gives the most contrast.
  */
 function bestOnColor(background: string, light: string, dark: string): string {
   if (contrast(background, light) >= AA_CONTRAST) return light;
@@ -123,9 +123,9 @@ function bestOnColor(background: string, light: string, dark: string): string {
 }
 
 /**
- * Mueve la luminosidad del tono hasta alcanzar el contraste pedido contra
- * `against`. Si ni el extremo llega —un amarillo puro sobre blanco, por
- * ejemplo— devuelve el más contrastado que encontró en el camino.
+ * Shifts the hue's lightness until it reaches the requested contrast against
+ * `against`. If not even the extreme gets there —pure yellow on white, for
+ * example— it returns the most contrasting one found along the way.
  */
 function reachContrast(hsl: Hsl, against: string, target: number, direction: 'darker' | 'lighter'): string {
   const step = direction === 'darker' ? -0.02 : 0.02;
@@ -146,9 +146,9 @@ function reachContrast(hsl: Hsl, against: string, target: number, direction: 'da
 }
 
 /**
- * Deriva los cuatro roles de un acento a partir de un hex, para un esquema.
- * `surface` es el fondo sobre el que tiene que leerse el rol `text`, así que
- * cada esquema pasa el suyo.
+ * Derives an accent's four roles from a hex, for one scheme.
+ * `surface` is the background the `text` role has to be read on, so each
+ * scheme passes its own.
  */
 export function deriveAccent(hex: string, scheme: 'light' | 'dark', surface: string): AccentRoles {
   const hsl = toHsl(hex);
@@ -163,8 +163,8 @@ export function deriveAccent(hex: string, scheme: 'light' | 'dark', surface: str
     };
   }
 
-  // En oscuro el acento sube de luminosidad y lo que va encima baja: un
-  // #004cef sobre #1e1e1e no se distingue del fondo.
+  // In dark the accent goes up in lightness and what sits on top goes down: a
+  // #004cef over #1e1e1e can't be told apart from the background.
   const base = toHex({ ...hsl, l: 0.72 });
   return {
     base,

package/src/theme/createStyles.ts

@@ -1,26 +1,30 @@
-import { StyleSheet } from 'react-native';
+import { StyleSheet, type ImageStyle, type TextStyle, type ViewStyle } from 'react-native';
 import { useTheme } from './UIProvider';
 import type { Theme } from './types';
 
 /**
  * createStyles(factory)
- * Devuelve un hook useStyles() que memoiza el StyleSheet resultante por
- * theme (WeakMap<Theme, Styles>), no por instancia de componente. Todas las
- * filas de una lista comparten el mismo objeto de estilos: sin esto, N filas
- * ⇒ N StyleSheet.create() por render, que es lo que hacía cada componente
- * de la app original con `useMemo(() => createStyles(colors), [colors])`.
+ * Returns a useStyles() hook that memoizes the resulting StyleSheet per
+ * theme (WeakMap<Theme, Styles>), not per component instance. All rows of a
+ * list share the same styles object: without this, N rows ⇒ N
+ * StyleSheet.create() per render, which is what every component of the
+ * original app did with `useMemo(() => createStyles(colors), [colors])`.
  *
- * La cache vive en el closure del factory (una WeakMap por llamada a
- * createStyles, es decir, una por componente), así que temas de distintos
- * <UIProvider> en el mismo árbol no colisionan entre sí.
+ * The cache lives in the factory's closure (one WeakMap per createStyles
+ * call, i.e. one per component), so themes from different <UIProvider>s in
+ * the same tree don't collide with each other.
  *
- * El tipo de `factory` sigue el patrón oficial de RN para StyleSheet
- * tipados (`T extends StyleSheet.NamedStyles<T> | StyleSheet.NamedStyles<any>`):
- * es lo que le da contexto a TS para inferir literales ('row', 'center', ...)
- * en vez de ensancharlos a `string` dentro del objeto devuelto.
+ * The `factory` type follows RN's pattern for typed StyleSheets
+ * (`T extends NamedStyles<T> | NamedStyles<any>`): it is what gives TS the
+ * context to infer literals ('row', 'center', ...) instead of widening them
+ * to `string` inside the returned object. `NamedStyles` is declared here:
+ * react-native 0.88's generated types (Expo SDK 58) no longer export
+ * `StyleSheet.NamedStyles`.
  */
-export function createStyles<T extends StyleSheet.NamedStyles<T> | StyleSheet.NamedStyles<any>>(
-  factory: (theme: Theme) => T | StyleSheet.NamedStyles<T>
+type NamedStyles<T> = { [P in keyof T]: ViewStyle | TextStyle | ImageStyle };
+
+export function createStyles<T extends NamedStyles<T> | NamedStyles<any>>(
+  factory: (theme: Theme) => T | NamedStyles<T>
 ): () => T {
   const cache = new WeakMap<Theme, T>();
 
@@ -28,10 +32,10 @@ export function createStyles<T extends StyleSheet.NamedStyles<T> | StyleSheet.Na
     const theme = useTheme();
     let styles = cache.get(theme);
     if (!styles) {
-      // El cast es seguro: StyleSheet.create<T>(...) con el mismo T del
-      // factory siempre devuelve T; TS no puede probarlo por sí solo dentro
-      // de un cuerpo genérico (T podría "instanciarse" con un subtipo no
-      // relacionado desde su punto de vista, aunque en runtime es el mismo).
+      // The cast is safe: StyleSheet.create<T>(...) with the factory's same T
+      // always returns T; TS can't prove it on its own inside a generic body
+      // (T could be "instantiated" with an unrelated subtype from its point
+      // of view, even though at runtime it is the same).
       styles = StyleSheet.create(factory(theme)) as T;
       cache.set(theme, styles);
     }