orn-ui 0.2.10 → 0.3.0

package/src/organisms/SearchList.tsx

@@ -22,16 +22,26 @@ export interface SearchListProps<T> {
   /** Optional chrome above the search bar (e.g. back button + title). */
   header?: React.ReactNode;
 
+  /** Text of the search box (controlled). */
   searchValue: string;
+  /** Called with the new text; the clear button calls it with an empty string. */
   onSearchChange: (text: string) => void;
+  /** Placeholder of the search box. @default labels.search */
   searchPlaceholder?: string;
+  /** Shows a spinner inside the search box. @default false */
   searchIsLoading?: boolean;
+  /** Shows a button next to the search box and is called when it is pressed. */
   onScanPress?: () => void;
+  /** Accessible name of the `onScanPress` button. @default labels.scan */
   scanAccessibilityLabel?: string;
+  /** Extra nodes at the end of the search row. */
   extraActions?: React.ReactNode;
 
+  /** Items to render. */
   data: T[];
+  /** Stable key per item. */
   keyExtractor: (item: T, index: number) => string;
+  /** Renders each row (same as FlatList's `renderItem`). */
   renderItem: FlatListProps<T>['renderItem'];
 
   /** Initial load: while true and there's no data, placeholders are shown. */
@@ -40,12 +50,23 @@ export interface SearchListProps<T> {
   loadingMode?: 'replace' | 'overlay';
   /** Reload with data already on screen (pull-to-refresh). @default false */
   isRefreshing?: boolean;
+  /** Shows a spinner in the footer while the next page loads. @default false */
   isLoadingMore?: boolean;
   /** Controlled by the consumer: while false, a fullscreen spinner is shown. @default true */
   isReady?: boolean;
+  /**
+   * Text of the spinner shown while `isReady` is false and of the `overlay` loading. @default
+   * labels.loading
+   */
   loadingText?: string;
+  /** Text of the footer spinner shown with `isLoadingMore`. @default labels.loadingMore */
   loadingMoreText?: string;
+  /**
+   * Whether more pages remain. While false, `noMoreText` shows at the end of a non-empty list.
+   * @default false
+   */
   hasMore?: boolean;
+  /** Text shown at the end of the list when `hasMore` is false. */
   noMoreText?: string;
 
   /** Ghost rows for the initial load. @default 6 */
@@ -53,31 +74,43 @@ export interface SearchListProps<T> {
   /** Custom placeholder, to match the real shape of the item. */
   renderSkeletonItem?: () => React.ReactElement;
 
+  /** Called when scrolling gets close to the end. Takes precedence over `onEndReached`. */
   onLoadMore?: () => void;
+  /** Called when scrolling gets close to the end. Ignored when `onLoadMore` is passed. */
   onEndReached?: () => void;
+  /** How close to the end `onEndReached` fires, in visible lengths of the list. @default 0.3 */
   onEndReachedThreshold?: number;
+  /** Enables pull-to-refresh and is called when the user pulls. */
   onRefresh?: () => void;
 
+  /** Title of the empty state. @default labels.noResultsTitle */
   emptyTitle?: string;
+  /** Supporting line of the empty state. @default labels.noResultsDescription */
   emptyDescription?: string;
+  /** Icon of the empty state. @default 'search' */
   emptyIconName?: IconName;
 
+  /** Rendered above the items, inside the scroll. */
   ListHeaderComponent?: FlatListProps<T>['ListHeaderComponent'];
+  /** Rendered below the items, before the pagination loader and `noMoreText`. */
   ListFooterComponent?: FlatListProps<T>['ListFooterComponent'];
 
+  /** Style of the list's content container (also used by the skeleton). */
   contentContainerStyle?: StyleProp<ViewStyle>;
+  /** Style of the outer wrapper. */
   containerStyle?: ViewStyle;
 
   /** List component to use (FlashList, etc). @default FlatList */
   ListComponent?: React.ComponentType<any>;
+  /** Extra props passed to `ListComponent`; they override the ones set here. */
   listProps?: Record<string, unknown>;
 }
 
 const useStyles = createStyles((theme) => ({
   container: { flex: 1 },
-  searchRow: { flexDirection: 'row', alignItems: 'center', marginBottom: theme.tokens.spacing.lg - 1, gap: theme.tokens.spacing.sm + 2 },
+  searchRow: { flexDirection: 'row', alignItems: 'center', marginBottom: theme.tokens.spacing.lg, gap: theme.tokens.spacing.md },
   searchInput: { flex: 1, marginBottom: 0 },
-  scanButton: { backgroundColor: theme.colors.primary, width: 50, height: 50, borderRadius: theme.tokens.radius.lg, ...theme.tokens.shadow.sm },
+  scanButton: { backgroundColor: theme.colors.primary, width: SCAN_SIZE, height: SCAN_SIZE, borderRadius: theme.tokens.radius.lg, ...theme.tokens.shadow.sm },
   listArea: { flex: 1 },
   listContent: { paddingBottom: theme.tokens.spacing.xl },
   loadingOverlay: {
@@ -99,14 +132,30 @@ const useStyles = createStyles((theme) => ({
     gap: theme.tokens.spacing.md,
     padding: theme.tokens.spacing.md,
   },
-  skeletonText: { flex: 1, gap: theme.tokens.spacing.sm },
+  skeletonText: { flex: 1 },
+  empty: { marginTop: theme.tokens.spacing.xxxl },
 }));
 
+/** The scan button is square and as tall as the search Input beside it. */
+const SCAN_SIZE = 50;
+/** Same as Avatar's default size: the placeholder row matches a typical avatar row. */
+const SKELETON_AVATAR = 44;
+
 /**
  * SearchList
- * Buscador + lista + estados de carga/paginación/vacío. El contenido de
- * cada ítem (renderItem) queda a cargo de quien la usa, ya que difiere por
- * completo entre casos de uso.
+ * Search box + list + loading/pagination/empty states. The content of each
+ * item (renderItem) is up to whoever uses it, since it differs completely
+ * between use cases.
+ *
+ * Design:
+ * - Proximity + common region: the search row (box, scan, extra actions)
+ *   sits right on top of the results it filters.
+ * - Doherty threshold: every wait has immediate feedback (placeholders, a
+ *   spinner in the box while searching, a footer loader while paging), and
+ *   "no results" only appears once it is known there is nothing.
+ * - Jakob's law: the clear (×) inside the box, pull-to-refresh, the keyboard
+ *   dismissed when the list is dragged.
+ * - Fitts's law: the scan button is as tall as the box, a 50pt target.
  */
 export function SearchList<T>({
   header,
@@ -115,7 +164,7 @@ export function SearchList<T>({
   searchPlaceholder,
   searchIsLoading = false,
   onScanPress,
-  scanAccessibilityLabel = 'Scan',
+  scanAccessibilityLabel,
   extraActions,
   data,
   keyExtractor,
@@ -154,8 +203,8 @@ export function SearchList<T>({
 
   const handleEndReached = onLoadMore ?? onEndReached;
 
-  // El footer propio y el loader de paginación conviven: antes el primero
-  // tapaba al segundo y la lista dejaba de avisar que estaba trayendo más.
+  // The custom footer and the pagination loader coexist: previously the first
+  // covered the second and the list stopped signaling it was fetching more.
   const renderFooter = useCallback(() => {
     const custom =
       typeof ListFooterComponent === 'function' ? (
@@ -181,12 +230,12 @@ export function SearchList<T>({
     );
   }, [ListFooterComponent, isLoadingMore, resolvedLoadingMoreText, noMoreText, hasMore, data.length, styles.footer, styles.footerText]);
 
-  // Vacío sólo cuando ya se sabe que no hay nada: durante la carga inicial se
-  // muestran placeholders, no "sin resultados".
+  // Empty only once it is known there is nothing: during the initial load
+  // placeholders are shown, not "no results".
   const renderEmpty = useCallback(() => {
     if (isLoading || isRefreshing) return null;
-    return <EmptyState title={emptyTitle} description={emptyDescription} iconName={emptyIconName} style={{ marginTop: 50 }} />;
-  }, [isLoading, isRefreshing, emptyTitle, emptyDescription, emptyIconName]);
+    return <EmptyState title={emptyTitle} description={emptyDescription} iconName={emptyIconName} style={styles.empty} />;
+  }, [isLoading, isRefreshing, emptyTitle, emptyDescription, emptyIconName, styles.empty]);
 
   if (!isReady) {
     return (
@@ -216,11 +265,11 @@ export function SearchList<T>({
         />
         {onScanPress && (
           <IconButton
-            iconName="search"
+            iconName="scan"
             onPress={onScanPress}
             color={colors.onPrimary}
             style={styles.scanButton}
-            accessibilityLabel={scanAccessibilityLabel}
+            accessibilityLabel={scanAccessibilityLabel ?? labels.scan}
           />
         )}
         {extraActions}
@@ -228,22 +277,37 @@ export function SearchList<T>({
 
       <View style={styles.listArea}>
         {showOverlayLoading && (
-          <View style={styles.loadingOverlay}>
+          <View
+            style={styles.loadingOverlay}
+            accessible
+            accessibilityRole="progressbar"
+            accessibilityLabel={resolvedLoadingText}
+            accessibilityState={{ busy: true }}
+          >
             <ActivityIndicator size="large" color={colors.primary} />
             <Text style={styles.footerText}>{resolvedLoadingText}</Text>
           </View>
         )}
 
         {isInitialLoading ? (
-          <View testID="list-skeleton" style={[styles.listContent, contentContainerStyle]}>
+          <View
+            testID="list-skeleton"
+            style={[styles.listContent, contentContainerStyle]}
+            // The placeholders are hidden from screen readers: the group
+            // announces that the list is loading instead of silence.
+            accessible
+            accessibilityRole="progressbar"
+            accessibilityLabel={resolvedLoadingText}
+            accessibilityState={{ busy: true }}
+          >
             {Array.from({ length: skeletonCount }, (_, i) => (
               <React.Fragment key={i}>
                 {renderSkeletonItem?.() ?? (
                   <View style={styles.skeletonRow}>
-                    <Skeleton variant="circle" width={40} />
+                    <Skeleton variant="circle" width={SKELETON_AVATAR} />
                     <View style={styles.skeletonText}>
-                      <Skeleton width="60%" height={14} />
-                      <Skeleton width="35%" height={12} />
+                      <Skeleton variant="text" width="60%" />
+                      <Skeleton variant="text" width="35%" />
                     </View>
                   </View>
                 )}

package/src/organisms/Select.tsx

@@ -1,8 +1,7 @@
-import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState, type ComponentRef } from 'react';
 import {
   ActivityIndicator,
   Keyboard,
-  Modal,
   Platform,
   Pressable,
   ScrollView,
@@ -14,6 +13,7 @@ import {
   type ViewStyle,
 } from 'react-native';
 import { createStyles } from '../theme/createStyles';
+import { NativeOverlay } from '../theme/NativeOverlay';
 import { useAllowFontScaling, useColors, useLabels } from '../theme/UIProvider';
 import { Icon } from '../icons/Icon';
 import type { IconName } from '../icons/types';
@@ -21,37 +21,53 @@ import type { IconName } from '../icons/types';
 export interface SelectOption<T> {
   label: string;
   value: T;
-  /** Glifo del set de la librería, a la izquierda del label. */
+  /** Glyph from the library's icon set, left of the label. */
   iconName?: IconName;
-  /** Emoji a la izquierda del label. Gana sobre `iconName`. */
+  /** Emoji left of the label. Takes precedence over `iconName`. */
   emoji?: string;
   disabled?: boolean;
 }
 
 export interface SelectProps<T> {
+  /** Text above the field; also its accessible name. */
   label?: string;
+  /** Shows an asterisk next to the label. @default false */
   required?: boolean;
+  /** Options of the dropdown: label, value and, optionally, icon, emoji or disabled. */
   options: SelectOption<T>[];
+  /** Value of the selected option (controlled). `undefined` shows the placeholder. */
   selectedValue: T | undefined;
+  /** Called with the value of the chosen option; the dropdown then closes. */
   onSelect: (value: T) => void;
+  /** Text while nothing is selected. @default labels.selectPlaceholder */
   placeholder?: string;
+  /** Error shown under the field. */
   error?: string;
+  /** Shows a spinner in place of the chevron and blocks opening. @default false */
   isLoading?: boolean;
+  /** Dims the field and blocks opening. @default false */
   disabled?: boolean;
   /** Adds a search box inside the dropdown. @default false */
   searchable?: boolean;
+  /** Placeholder of the search box (with `searchable`). @default labels.search */
   searchPlaceholder?: string;
   /** Maximum height of the dropdown, if the available space allows it. @default 280 */
   maxHeight?: number;
+  /** Called with `true` when the dropdown opens and `false` when it closes. */
   onOpenChange?: (open: boolean) => void;
+  /** Style of the outer wrapper (label, field and error). */
   containerStyle?: StyleProp<ViewStyle>;
   testID?: string;
 }
 
-/** Aire entre el campo y el desplegable. */
+/** Room between the field and the dropdown. */
 const GAP = 8;
-/** Por debajo de esto el desplegable no muestra ni dos filas. */
+/** Below this the dropdown can't even show two rows. */
 const MIN_HEIGHT = 120;
+/** Same height as Input and DateField, so a form's fields line up. */
+const FIELD_MIN_HEIGHT = 50;
+const ICON_SIZE = 20;
+const CHECK_SIZE = 18;
 
 const useStyles = createStyles((theme) => ({
   container: { gap: theme.tokens.spacing.sm },
@@ -65,10 +81,11 @@ const useStyles = createStyles((theme) => ({
     borderColor: theme.colors.border,
     borderRadius: theme.tokens.radius.lg,
     backgroundColor: theme.colors.inputBackground,
-    minHeight: 50,
+    minHeight: FIELD_MIN_HEIGHT,
     paddingHorizontal: theme.tokens.spacing.lg,
   },
   fieldOpen: { borderColor: theme.colors.primary },
+  fieldError: { borderColor: theme.colors.error },
   fieldDisabled: { opacity: 0.5 },
   fieldValue: { flexDirection: 'row', alignItems: 'center', gap: theme.tokens.spacing.sm, flexShrink: 1 },
   fieldText: { fontSize: theme.tokens.fontSize.lg, color: theme.colors.text, flexShrink: 1 },
@@ -79,7 +96,7 @@ const useStyles = createStyles((theme) => ({
     borderWidth: 2,
     borderColor: theme.colors.border,
     borderRadius: theme.tokens.radius.lg,
-    backgroundColor: theme.colors.surface,
+    backgroundColor: theme.colors.surfaceRaised,
     overflow: 'hidden',
     ...theme.tokens.shadow.md,
   },
@@ -96,7 +113,7 @@ const useStyles = createStyles((theme) => ({
     alignItems: 'center',
     justifyContent: 'space-between',
     paddingHorizontal: theme.tokens.spacing.lg,
-    paddingVertical: theme.tokens.spacing.md + 2,
+    paddingVertical: theme.tokens.spacing.md + theme.tokens.spacing.xxs,
     borderBottomWidth: 1,
     borderBottomColor: theme.colors.border,
   },
@@ -104,7 +121,7 @@ const useStyles = createStyles((theme) => ({
   optionRowSelected: { backgroundColor: theme.colors.primarySoft },
   optionRowDisabled: { opacity: 0.4 },
   optionLabel: { flexDirection: 'row', alignItems: 'center', gap: theme.tokens.spacing.sm, flexShrink: 1 },
-  optionText: { fontSize: theme.tokens.fontSize.lg - 1, color: theme.colors.text },
+  optionText: { fontSize: theme.tokens.fontSize.lg, color: theme.colors.text },
   optionTextSelected: { fontWeight: theme.tokens.fontWeight.semibold, color: theme.colors.primaryText },
   emoji: { fontSize: theme.tokens.fontSize.lg },
   empty: {
@@ -125,10 +142,18 @@ interface Anchor {
 
 /**
  * Select
- * Dropdown de una sola opción. La lista se mide contra la ventana y se dibuja
- * dentro de un Modal, no en el árbol del campo: así ningún `overflow: hidden`
- * la recorta, no depende del zIndex (poco confiable en Android) y el fondo del
- * Modal resuelve cerrar tocando afuera y con el botón atrás.
+ * Single-option dropdown. The list is measured against the window and drawn
+ * inside a Modal, not in the field's tree: that way no `overflow: hidden`
+ * clips it, it doesn't depend on zIndex (unreliable on Android) and the
+ * Modal's backdrop handles closing by tapping outside and with the back button.
+ *
+ * Design:
+ * - Proximity + continuity: the list opens right against the field, toward
+ *   wherever there is more room, so the eye goes from field to options.
+ * - Von Restorff: the picked option alone has the accent fill and a check.
+ * - Jakob's law: same field as Input and DateField (height, border, label,
+ *   red border with an error); tap outside or Android back closes it.
+ * - Hick's law: past a handful of options, `searchable` narrows the list.
  */
 export function Select<T extends string | number>({
   label,
@@ -153,12 +178,13 @@ export function Select<T extends string | number>({
   const allowFontScaling = useAllowFontScaling();
   const { height: windowHeight } = useWindowDimensions();
 
-  const fieldRef = useRef<View>(null);
+  const fieldRef = useRef<ComponentRef<typeof View>>(null);
   const [open, setOpen] = useState(false);
   const [anchor, setAnchor] = useState<Anchor | null>(null);
   const [query, setQuery] = useState('');
   const [keyboardHeight, setKeyboardHeight] = useState(0);
   const isDisabled = disabled || isLoading;
+  const fieldName = label ?? placeholder ?? labels.selectPlaceholder;
   const selectedOption = options.find((o) => o.value === selectedValue);
 
   const close = useCallback(() => {
@@ -168,16 +194,16 @@ export function Select<T extends string | number>({
     onOpenChange?.(false);
   }, [onOpenChange]);
 
-  // Abrir no espera a la medición: si `measureInWindow` no responde, la lista
-  // igual aparece (centrada) en vez de que el campo deje de funcionar.
+  // Opening doesn't wait for the measurement: if `measureInWindow` doesn't
+  // respond, the list still appears (centered) instead of the field ceasing to work.
   const openList = () => {
     fieldRef.current?.measureInWindow((x, y, width, height) => setAnchor({ x, y, width, height }));
     setOpen(true);
     onOpenChange?.(true);
   };
 
-  // El buscador abre el teclado encima del desplegable: sin descontarlo, la
-  // lista se dibuja donde ya no se ve.
+  // The search box opens the keyboard over the dropdown: without subtracting
+  // it, the list is drawn where it can no longer be seen.
   useEffect(() => {
     if (!open) return;
     setKeyboardHeight(Keyboard.metrics()?.height ?? 0);
@@ -196,8 +222,8 @@ export function Select<T extends string | number>({
     return options.filter((option) => option.label.toLowerCase().includes(needle));
   }, [options, query, searchable]);
 
-  // Se abre hacia donde haya más aire: contra el borde inferior de la pantalla,
-  // hacia arriba es la única forma de que entre.
+  // It opens toward wherever there is more room: against the bottom edge of
+  // the screen, upward is the only way for it to fit.
   const placement = useMemo((): ViewStyle => {
     if (!anchor) return { left: GAP * 2, right: GAP * 2, top: windowHeight * 0.25, maxHeight };
     const usableHeight = windowHeight - keyboardHeight;
@@ -221,7 +247,7 @@ export function Select<T extends string | number>({
         </Text>
       );
     }
-    return option.iconName ? <Icon name={option.iconName} size={20} color={color} /> : null;
+    return option.iconName ? <Icon name={option.iconName} size={ICON_SIZE} color={color} /> : null;
   };
 
   return (
@@ -235,11 +261,12 @@ export function Select<T extends string | number>({
 
       <Pressable
         ref={fieldRef}
-        style={[styles.field, open && styles.fieldOpen, isDisabled && styles.fieldDisabled]}
+        style={[styles.field, !!error && styles.fieldError, open && styles.fieldOpen, isDisabled && styles.fieldDisabled]}
         onPress={openList}
         disabled={isDisabled}
         accessibilityRole="combobox"
-        accessibilityLabel={label ?? placeholder ?? labels.selectPlaceholder}
+        accessibilityLabel={required ? `${fieldName}, ${labels.required}` : fieldName}
+        accessibilityHint={error || undefined}
         accessibilityValue={{ text: selectedOption?.label ?? '' }}
         accessibilityState={{ expanded: open, disabled: isDisabled }}
       >
@@ -256,15 +283,22 @@ export function Select<T extends string | number>({
         {isLoading ? (
           <ActivityIndicator size="small" color={colors.primary} />
         ) : (
-          <Icon name={open ? 'chevron-up' : 'chevron-down'} size={20} color={colors.textLight} />
+          <Icon name={open ? 'chevron-up' : 'chevron-down'} size={ICON_SIZE} color={colors.textLight} />
         )}
       </Pressable>
 
       {open && (
-        <Modal visible transparent animationType="fade" statusBarTranslucent onRequestClose={close}>
+        <NativeOverlay transparent animationType="fade" statusBarTranslucent onRequestClose={close}>
           <Pressable style={styles.backdrop} onPress={close} testID="select-backdrop" />
 
-          <View style={[styles.sheet, placement]} accessibilityRole="radiogroup" testID="select-list">
+          <View
+            style={[styles.sheet, placement]}
+            accessibilityRole="radiogroup"
+            // On iOS it may be drawn inside another open overlay: the reader stays in the list.
+            accessibilityViewIsModal
+            onAccessibilityEscape={close}
+            testID="select-list"
+          >
             {searchable && (
               <TextInput
                 allowFontScaling={allowFontScaling}
@@ -309,7 +343,7 @@ export function Select<T extends string | number>({
                         {option.label}
                       </Text>
                     </View>
-                    {isSelected && <Icon name="check" size={18} color={colors.primary} />}
+                    {isSelected && <Icon name="check" size={CHECK_SIZE} color={colors.primary} />}
                   </Pressable>
                 );
               })}
@@ -321,7 +355,7 @@ export function Select<T extends string | number>({
               )}
             </ScrollView>
           </View>
-        </Modal>
+        </NativeOverlay>
       )}
 
       {!!error && (