orn-ui 0.2.9 → 0.3.0

package/src/atoms/Fab.tsx

@@ -2,22 +2,43 @@ import React, { memo } from 'react';
 import { type GestureResponderEvent, type StyleProp, type ViewStyle } from 'react-native';
 import { PressableScale } from './PressableScale';
 import { Icon } from '../icons/Icon';
+import { onColor } from '../icons/defaultIcons';
 import type { IconName } from '../icons/types';
 import { createStyles } from '../theme/createStyles';
-import { useColors } from '../theme/UIProvider';
+import { useColors, useInsets, useTheme } from '../theme/UIProvider';
 
 export interface FabProps {
+  /** Called when the button is pressed. */
   onPress: (e: GestureResponderEvent) => void;
+  /** Built-in or custom icon name. Ignored when `icon` is passed. @default 'plus' */
   iconName?: IconName;
+  /** Any node in place of the icon. */
   icon?: React.ReactNode;
+  /** Diameter in pt. @default 60 */
   size?: number;
+  /** Distance from the bottom edge, on top of the safe area. @default tokens.spacing.xl (20) */
   bottom?: number;
+  /** Distance from the right edge, on top of the safe area. @default tokens.spacing.xl (20) */
   right?: number;
+  /**
+   * Adds the safe-area insets to `bottom`/`right`, so the button clears the
+   * home indicator. Pass false above a NavigationBar or tab bar, which
+   * already covers that edge. @default true
+   */
+  safeArea?: boolean;
+  /** Fill color. The icon switches to black or white for contrast. @default theme.colors.primary */
   color?: string;
   style?: StyleProp<ViewStyle>;
+  /** Required: the button has no visible text. */
   accessibilityLabel: string;
+  testID?: string;
 }
 
+/** Default diameter: comfortably above the 44pt touch minimum (Fitts). */
+const DEFAULT_SIZE = 60;
+/** The glyph takes up half the circle. */
+const ICON_RATIO = 0.5;
+
 const useStyles = createStyles((theme) => ({
   fab: {
     position: 'absolute',
@@ -29,14 +50,39 @@ const useStyles = createStyles((theme) => ({
 
 /**
  * Fab
- * Botón flotante circular. `bottom`/`right` en vez del `tabBarHeight`
- * obligatorio de la versión original — el consumidor decide su propio
- * offset (con o sin tab bar).
+ * Circular floating button for the screen's main action.
+ * `bottom`/`right` instead of the required `tabBarHeight` of the original
+ * version — the consumer decides its own offset (with or without a tab bar).
+ *
+ * Gestalt, figure/ground: it is the only thing that floats (`lg` shadow) and
+ * carries the accent, so it stands apart from the content passing beneath it
+ * (Von Restorff: one per screen). Fitts: large and in the thumb's corner,
+ * above the safe area so it doesn't compete with the home gesture.
  */
 export const Fab = memo(
-  ({ onPress, iconName = 'plus', icon, size = 60, bottom = 20, right = 20, color, style, accessibilityLabel }: FabProps) => {
+  ({
+    onPress,
+    iconName = 'plus',
+    icon,
+    size = DEFAULT_SIZE,
+    bottom,
+    right,
+    safeArea = true,
+    color,
+    style,
+    accessibilityLabel,
+    testID,
+  }: FabProps) => {
     const styles = useStyles();
     const colors = useColors();
+    const theme = useTheme();
+    const insets = useInsets();
+    const fill = color ?? colors.primary;
+    // With the theme color, its `onPrimary`; with a custom one, black or white
+    // depending on contrast (a cyan with a white icon was unreadable).
+    const glyph = color ? onColor(color) : colors.onPrimary;
+    const edge = theme.tokens.spacing.xl;
+
     return (
       <PressableScale
         onPress={onPress}
@@ -46,16 +92,17 @@ export const Fab = memo(
             width: size,
             height: size,
             borderRadius: size / 2,
-            bottom,
-            right,
-            backgroundColor: color ?? colors.primary,
+            bottom: (bottom ?? edge) + (safeArea ? insets.bottom : 0),
+            right: (right ?? edge) + (safeArea ? insets.right : 0),
+            backgroundColor: fill,
           },
           style,
         ]}
         accessibilityRole="button"
         accessibilityLabel={accessibilityLabel}
+        testID={testID}
       >
-        {icon ?? <Icon name={iconName} size={size * 0.5} color={colors.onPrimary} />}
+        {icon ?? <Icon name={iconName} size={size * ICON_RATIO} color={glyph} />}
       </PressableScale>
     );
   }

package/src/atoms/Gradient.tsx

@@ -1,60 +1,98 @@
-import React, { memo, useMemo } from 'react';
-import { StyleSheet, View, type StyleProp, type ViewStyle } from 'react-native';
+import React, { memo, useMemo, useState } from 'react';
+import { StyleSheet, View, type LayoutChangeEvent, type StyleProp, type ViewStyle } from 'react-native';
 
 export type GradientDirection = 'vertical' | 'horizontal' | 'diagonal' | 'diagonal-reverse';
 
 export interface GradientProps {
-  /** Paradas del degradado. Uno solo pinta plano; ninguno no pinta nada. */
+  /** Gradient stops. A single color paints flat; none paints nothing. */
   colors: string[];
   /**
-   * 'vertical' va de arriba a abajo, 'horizontal' de izquierda a derecha,
-   * 'diagonal' de arriba-izquierda a abajo-derecha y 'diagonal-reverse' de
-   * arriba-derecha a abajo-izquierda.
+   * 'vertical' runs top to bottom, 'horizontal' left to right, 'diagonal'
+   * top-left to bottom-right and 'diagonal-reverse' top-right to bottom-left.
    * @default 'vertical'
    */
   direction?: GradientDirection;
   /**
-   * Bandas por tramo (un tramo = un par de colores consecutivos). Más bandas
-   * = transición más suave y más vistas en el árbol.
-   * @default 24
+   * Bands per segment (a segment = a pair of consecutive colors). More bands
+   * = a smoother transition and more views in the tree.
+   * @default 48
    */
   steps?: number;
-  /** Contenido por encima del degradado. */
+  /** Content rendered on top of the gradient. */
   children?: React.ReactNode;
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }
 
-const DEFAULT_STEPS = 24;
+const DEFAULT_STEPS = 48;
 
 const styles = StyleSheet.create({
-  // Recorta el plano rotado de las diagonales y el degradado al borderRadius.
+  // Clips the rotated plane of the diagonals and the gradient to the borderRadius.
   root: { overflow: 'hidden' },
-  segment: { flex: 1 },
-  band: { flex: 1 },
-  // Plano √2 centrado: rotado 45° cubre las esquinas sin medir el contenedor.
+  // Centered √2 plane: covers the corners of a SQUARE container without
+  // measuring it. Only used until the first onLayout; after that the plane is
+  // sized with the real diagonal (see `diagonalBox`).
   diagonalPlane: { position: 'absolute', top: '-21%', left: '-21%', width: '142%', height: '142%' },
 });
 
+/**
+ * Opacities of stacked layers: layer k (from 1 to n-1) starts at k/n and
+ * runs to the end of the segment; stacked with "over", the total opacity in
+ * band k is k/(n-1), same as side-by-side bands. The difference: no layer
+ * edge sits next to a gap, so the antialiasing of an edge (especially when
+ * rotated) blends with the color of the layer below and not with what is
+ * behind the gradient — without the thin lines between bands.
+ */
+function layerOpacities(n: number): number[] {
+  const out: number[] = [];
+  let prev = 0;
+  for (let k = 1; k < n; k += 1) {
+    const total = k / (n - 1);
+    out.push(prev >= 1 ? 1 : 1 - (1 - total) / (1 - prev));
+    prev = total;
+  }
+  return out;
+}
+
+/** Square with the diagonal as its side, centered: rotated 45° it covers any rectangle. */
+function diagonalBox(width: number, height: number): ViewStyle {
+  const side = Math.hypot(width, height);
+  return { position: 'absolute', width: side, height: side, left: (width - side) / 2, top: (height - side) / 2 };
+}
+
 /**
  * Gradient
- * Degradado lineal sin dependencias: React Native no trae uno en el rango
- * soportado (Expo SDK 54–57) y `experimental_backgroundImage` no está en toda
- * esa ventana, así que se compone con bandas.
+ * Dependency-free linear gradient: React Native doesn't ship one in the
+ * supported range (Expo SDK 54–57) and `experimental_backgroundImage` isn't
+ * available across that whole window, so it is composed from bands.
+ *
+ * Each segment paints the start color and, on top, layers of the end color
+ * that accumulate (see `layerOpacities`). The compositor blends alpha linearly:
+ * the result is the sRGB interpolation between stops without parsing the
+ * color, which is why any format RN accepts works (hex, `rgba()`, name). The
+ * layers run to the end of the plane so no thin lines are left between
+ * bands, and the diagonals rotate a square the size of the measured diagonal
+ * to cover any rectangle, not just squares.
  *
- * Cada tramo pinta el color inicial y encima N bandas del final con opacidad
- * de 0 a 1. El compositor mezcla alpha linealmente: el resultado es la
- * interpolación sRGB entre paradas sin parsear el color, y por eso vale
- * cualquier formato que acepte RN (hex, `rgba()`, nombre).
+ * Gestalt, figure and ground: content on top must contrast with ALL the
+ * stops, not just the first — white text that reads well over the blue at
+ * the start can get lost over the light blue at the end.
  */
 export const Gradient = memo(
   ({ colors, direction = 'vertical', steps = DEFAULT_STEPS, children, style, testID }: GradientProps) => {
     const isRow = direction === 'horizontal';
     const isDiagonal = direction === 'diagonal' || direction === 'diagonal-reverse';
-    // rotate positivo gira en horario (Y crece hacia abajo): -45° manda el eje
-    // del degradado hacia abajo-derecha.
+    // positive rotate turns clockwise (Y grows downward): -45° sends the
+    // gradient axis down-right.
     const rotate = direction === 'diagonal' ? '-45deg' : '45deg';
     const bandCount = Math.max(2, Math.floor(steps));
+    const [size, setSize] = useState<{ width: number; height: number } | null>(null);
+    const onLayout = isDiagonal
+      ? (e: LayoutChangeEvent) => {
+          const { width, height } = e.nativeEvent.layout;
+          setSize((prev) => (prev && prev.width === width && prev.height === height ? prev : { width, height }));
+        }
+      : undefined;
 
     const painted = useMemo(() => {
       if (colors.length === 0) return null;
@@ -62,32 +100,45 @@ export const Gradient = memo(
         return <View style={[StyleSheet.absoluteFill, { backgroundColor: colors[0] }]} />;
       }
 
-      const segments = colors.slice(0, -1).map((from, index) => {
+      const segmentCount = colors.length - 1;
+      const opacities = layerOpacities(bandCount);
+      // From `start` (fraction of the axis) to the end of the plane.
+      const from = (start: number): ViewStyle =>
+        isRow
+          ? { position: 'absolute', top: 0, bottom: 0, right: 0, left: `${start * 100}%` }
+          : { position: 'absolute', left: 0, right: 0, bottom: 0, top: `${start * 100}%` };
+
+      // Segments are stacked too: each one covers the previous from its start,
+      // and since it begins with the color the previous one ended with, the
+      // edge between segments doesn't show the background.
+      const segments = colors.slice(0, -1).map((start, index) => {
         const to = colors[index + 1] as string;
+        const segStart = index / segmentCount;
+        const segLength = 1 / segmentCount;
+        // The segment runs from segStart to the END of the plane; its layers
+        // sit at fractions of that remaining length.
+        const rest = 1 - segStart;
         return (
-          <View
-            key={`${from}-${to}-${index}`}
-            style={[styles.segment, { backgroundColor: from, flexDirection: isRow ? 'row' : 'column' }]}
-          >
-            {Array.from({ length: bandCount }, (_, band) => (
-              <View key={band} style={[styles.band, { backgroundColor: to, opacity: band / (bandCount - 1) }]} />
+          <View key={`${start}-${to}-${index}`} style={[from(segStart), { backgroundColor: start }]}>
+            {opacities.map((opacity, k) => (
+              <View
+                key={k}
+                style={[from((((k + 1) / bandCount) * segLength) / rest), { backgroundColor: to, opacity }]}
+              />
             ))}
           </View>
         );
       });
 
-      const stack = (
-        <View style={[StyleSheet.absoluteFill, { flexDirection: isRow ? 'row' : 'column' }]}>{segments}</View>
-      );
-
-      if (!isDiagonal) return stack;
-      return <View style={[styles.diagonalPlane, { transform: [{ rotate }] }]}>{segments}</View>;
-    }, [colors, isRow, isDiagonal, rotate, bandCount]);
+      if (!isDiagonal) return <View style={StyleSheet.absoluteFill}>{segments}</View>;
+      const plane = size ? diagonalBox(size.width, size.height) : styles.diagonalPlane;
+      return <View style={[plane, { transform: [{ rotate }] }]}>{segments}</View>;
+    }, [colors, isRow, isDiagonal, rotate, bandCount, size]);
 
     return (
-      <View testID={testID} style={[styles.root, style]}>
-        {/* pointerEvents va en el pintado, no en la raíz: el degradado no debe
-            robarle los toques a lo que el consumidor ponga encima. */}
+      <View testID={testID} style={[styles.root, style]} onLayout={onLayout}>
+        {/* pointerEvents goes on the painted layer, not the root: the gradient
+            must not steal touches from whatever the consumer places on top. */}
         <View style={StyleSheet.absoluteFill} pointerEvents="none">
           {painted}
         </View>

package/src/atoms/IconButton.tsx

@@ -4,15 +4,23 @@ import { PressableScale } from './PressableScale';
 import { Icon } from '../icons/Icon';
 import type { IconName } from '../icons/types';
 import { createStyles } from '../theme/createStyles';
+import { useTheme } from '../theme/UIProvider';
 
 export interface IconButtonProps {
+  /** Icon from the library's set. Ignored when `icon` is passed. */
   iconName?: IconName;
+  /** Custom node in place of the icon. Takes precedence over `iconName`. */
   icon?: React.ReactNode;
+  /** Called on press. Not called while `disabled`. */
   onPress?: (e: GestureResponderEvent) => void;
+  /** Icon size in pt. The touch area is padded up to 44pt with `hitSlop`. @default 24 */
   size?: number;
+  /** Icon color. Defaults to `colors.text`. */
   color?: string;
+  /** Dims the button by half and ignores presses. */
   disabled?: boolean;
   style?: StyleProp<ViewStyle>;
+  /** Required: the button has no visible text, so this is all a screen reader announces. */
   accessibilityLabel: string;
   testID?: string;
 }
@@ -25,20 +33,35 @@ const useStyles = createStyles((theme) => ({
   },
 }));
 
+/** Minimum touch area recommended by Apple (44pt) and Material (48dp ≈ 44pt). */
+const MIN_TOUCH = 44;
+
 /**
  * IconButton
- * Botón de solo ícono con área táctil mínima de 44x44 garantizada por el
- * padding (icon 24 + padding 8*2 = 40; sube a 44 con size>=24 default RN).
- * `accessibilityLabel` es obligatorio: sin texto visible, es la única forma
- * de que un lector de pantalla anuncie qué hace el botón.
+ * Icon-only button. `accessibilityLabel` is required: with no visible text,
+ * it is the only way for a screen reader to announce what it does.
+ *
+ * Fitts: the visible area is icon + `spacing.sm` per side (24 + 16 = 40pt
+ * with the default size, 32pt with `size={16}`). `hitSlop` makes up the
+ * rest up to 44pt without enlarging the layout, so a row of icons keeps its
+ * rhythm and each one is still easy to tap.
+ *
+ * Gestalt, figure and ground: it has no background of its own, the icon is
+ * the figure over whatever is behind it; that is why the default color is
+ * `colors.text` (guaranteed AA contrast) and `disabled` dims it by half.
  */
 export const IconButton = memo(
   ({ iconName, icon, onPress, size = 24, color, disabled, style, accessibilityLabel, testID }: IconButtonProps) => {
     const styles = useStyles();
+    const theme = useTheme();
+    const visible = size + theme.tokens.spacing.sm * 2;
+    const extra = Math.max(0, Math.ceil((MIN_TOUCH - visible) / 2));
+    const hitSlop = extra > 0 ? { top: extra, bottom: extra, left: extra, right: extra } : undefined;
     return (
       <PressableScale
         onPress={onPress}
         disabled={disabled}
+        hitSlop={hitSlop}
         style={[styles.hitArea, { opacity: disabled ? 0.5 : 1 }, style]}
         accessibilityRole="button"
         accessibilityLabel={accessibilityLabel}

package/src/atoms/Image.tsx

@@ -4,27 +4,38 @@ import {
   Platform,
   StyleSheet,
   View,
-  type ImageErrorEventData,
+  type ImageProps as RNImageProps,
   type ImageResizeMode,
   type ImageSourcePropType,
-  type NativeSyntheticEvent,
   type StyleProp,
   type ViewStyle,
 } from 'react-native';
 import { createStyles } from '../theme/createStyles';
+import { useColors, useTheme } from '../theme/UIProvider';
+import { Icon } from '../icons/Icon';
 import { Spinner } from './Spinner';
 
+/**
+ * The event RN's Image passes to `onError`. Taken from its own prop type:
+ * react-native 0.88 (Expo SDK 58) renamed the exported name
+ * (`ImageErrorEventData` -> `ImageErrorEvent`).
+ */
+type ImageErrorEvent = Parameters<NonNullable<RNImageProps['onError']>>[0];
+
 export interface ImageProps {
+  /** Image to load (same as React Native's `source`). */
   source: ImageSourcePropType;
+  /** Width of the image slot, in pt. */
   width?: number;
+  /** Height of the image slot, in pt. */
   height?: number;
-  /** @default 'cover' */
+  /** How the image fits its slot (same as React Native). @default 'cover' */
   resizeMode?: ImageResizeMode;
   /** Corner radius, same pattern as Avatar/Card. @default 0 */
   radius?: number;
   /** What to show while loading. `false` to show nothing. @default true (small spinner) */
   loading?: React.ReactNode | boolean;
-  /** What to show if loading fails. @default a gray placeholder, no content */
+  /** What to show if loading fails. @default placeholder with a warning icon */
   fallback?: React.ReactNode;
   /**
    * 'high' triggers Image.prefetch() on mount, before <Image> starts
@@ -34,15 +45,22 @@ export interface ImageProps {
    */
   priority?: 'low' | 'normal' | 'high';
   style?: StyleProp<ViewStyle>;
+  /** Called when loading finishes, successfully or not (same as RN). */
   onLoadEnd?: () => void;
-  onError?: (error: NativeSyntheticEvent<ImageErrorEventData>) => void;
+  /** Describes the image for screen readers. Without it the image is decorative. */
+  accessibilityLabel?: string;
+  /** Called when loading fails; the `fallback` is shown. */
+  onError?: (error: ImageErrorEvent) => void;
   testID?: string;
 }
 
 const useStyles = createStyles((theme) => ({
-  container: { overflow: 'hidden', backgroundColor: theme.colors.skeleton },
+  container: { overflow: 'hidden' },
+  // Only while loading or on failure: once the image has loaded, a PNG with
+  // transparency (a logo) let this gray show through.
+  placeholder: { backgroundColor: theme.colors.skeleton },
   overlay: { alignItems: 'center', justifyContent: 'center' },
-  fallback: { flex: 1, backgroundColor: theme.colors.skeleton },
+  fallback: { flex: 1, backgroundColor: theme.colors.skeleton, alignItems: 'center', justifyContent: 'center' },
 }));
 
 function sourceUri(source: ImageSourcePropType): string | undefined {
@@ -51,14 +69,22 @@ function sourceUri(source: ImageSourcePropType): string | undefined {
 
 /**
  * Image
- * Wrapper cero-dependencias sobre <Image> de RN: agrega estado de carga y
- * error (con los mismos placeholders que el resto de la librería), y expone
- * `priority="high"` para adelantar la descarga vía Image.prefetch(). El
- * cache real (disco/memoria) lo maneja el motor de imágenes nativo de RN —
- * esto no lo reimplementa, solo no lo deja apagado por accidente: en iOS
- * fuerza `cache="force-cache"` (usa el disco aunque el header HTTP no lo
- * pida); en Android el cache de disco de la imagen nativa ya está siempre
- * activo, no hay knob equivalente que tocar.
+ * Zero-dependency wrapper over RN's <Image>: adds loading and error state
+ * (with the same placeholders as the rest of the library), and exposes
+ * `priority="high"` to start the download early via Image.prefetch(). The
+ * actual cache (disk/memory) is handled by RN's native image engine — this
+ * doesn't reimplement it, it just keeps it from being accidentally turned off:
+ * on iOS it forces `cache="force-cache"` (uses the disk even when the HTTP
+ * header doesn't ask for it); on Android the native image's disk cache is
+ * always on, there is no equivalent knob to touch.
+ *
+ * Gestalt, closure: the container takes its final size from the first frame
+ * (`skeleton` background), so the layout doesn't jump when the image arrives
+ * and the eye completes the shape it will fill. If loading fails, the same
+ * slot shows a warning icon: the state is visible, not a silent gray.
+ *
+ * Success is detected with `onLoad`, not `onLoadEnd`: RN also calls
+ * `onLoadEnd` on failure, and using it for "loaded" overwrote the error.
  */
 export const Image = memo(
   ({
@@ -74,14 +100,17 @@ export const Image = memo(
     onLoadEnd,
     onError,
     testID,
+    accessibilityLabel,
   }: ImageProps) => {
     const styles = useStyles();
+    const colors = useColors();
+    const theme = useTheme();
     const [status, setStatus] = useState<'loading' | 'loaded' | 'error'>('loading');
     const uri = sourceUri(source);
 
     useEffect(() => {
-      // Resetea el estado si cambia la imagen (misma instancia de Image,
-      // source distinto: p.ej. avatar de un usuario a otro en la misma fila).
+      // Resets the state if the image changes (same Image instance, different
+      // source: e.g. one user's avatar to another's in the same row).
       setStatus('loading');
     }, [uri ?? source]);
 
@@ -92,28 +121,34 @@ export const Image = memo(
     }, [priority, uri]);
 
     const handleError = useCallback(
-      (e: NativeSyntheticEvent<ImageErrorEventData>) => {
+      (e: ImageErrorEvent) => {
         setStatus('error');
         onError?.(e);
       },
       [onError]
     );
 
-    const handleLoadEnd = useCallback(() => {
+    const handleLoad = useCallback(() => {
       setStatus('loaded');
-      onLoadEnd?.();
-    }, [onLoadEnd]);
+    }, []);
 
     return (
-      <View style={[styles.container, { width, height, borderRadius: radius }, style]} testID={testID}>
+      <View
+        style={[styles.container, status !== 'loaded' && styles.placeholder, { width, height, borderRadius: radius }, style]}
+        testID={testID}
+        accessible={!!accessibilityLabel}
+        accessibilityRole={accessibilityLabel ? 'image' : undefined}
+        accessibilityLabel={accessibilityLabel}
+      >
         {status !== 'error' && (
           <RNImage
             source={source}
             resizeMode={resizeMode}
             style={StyleSheet.absoluteFill}
-            fadeDuration={Platform.OS === 'android' ? 150 : undefined}
+            fadeDuration={Platform.OS === 'android' ? theme.tokens.duration.fast : undefined}
             {...(Platform.OS === 'ios' ? { cache: 'force-cache' as const } : null)}
-            onLoadEnd={handleLoadEnd}
+            onLoad={handleLoad}
+            onLoadEnd={onLoadEnd}
             onError={handleError}
           />
         )}
@@ -122,7 +157,18 @@ export const Image = memo(
             {loading === true ? <Spinner size="small" fullscreen={false} /> : loading}
           </View>
         )}
-        {status === 'error' && (fallback ?? <View style={styles.fallback} />)}
+        {status === 'error' && (
+          // Custom fallback or the default: always centered in the slot.
+          <View style={styles.fallback}>
+            {fallback ?? (
+              <Icon
+                name="warning"
+                size={Math.max(16, Math.min(32, Math.round(Math.min(width ?? 64, height ?? 64) * 0.3)))}
+                color={colors.textLight}
+              />
+            )}
+          </View>
+        )}
       </View>
     );
   }
@@ -130,8 +176,8 @@ export const Image = memo(
 Image.displayName = 'Image';
 
 /**
- * Precarga una URL antes de montar el componente (p.ej. al recibir la
- * respuesta de un listado, antes de navegar al detalle). Re-exporta
- * Image.prefetch de RN — no hay nada zero-dep que agregarle encima.
+ * Preloads a URL before mounting the component (e.g. on receiving a list
+ * response, before navigating to the detail). Re-exports RN's
+ * Image.prefetch — there is nothing zero-dep to add on top.
  */
 export const prefetchImage = RNImage.prefetch;