orn-ui 0.1.1 → 0.2.1

package/src/organisms/Modal.tsx

@@ -1,6 +1,5 @@
-import React, { memo, useEffect, useRef, useState } from 'react';
+import React, { memo, useEffect, useState } from 'react';
 import {
-  Animated,
   Dimensions,
   KeyboardAvoidingView,
   Modal as RNModal,
@@ -15,10 +14,11 @@ import { createStyles } from '../theme/createStyles';
 import { useColors, useInsets } from '../theme/UIProvider';
 import { Title } from '../atoms/Text';
 import { IconButton } from '../atoms/IconButton';
+import { Transition, type TransitionPreset } from '../atoms/Transition';
 
 const { height: SCREEN_HEIGHT } = Dimensions.get('window');
 
-export type ModalVariant = 'full' | 'overlay' | 'fullScreen' | 'bottomSheet';
+export type ModalVariant = 'full' | 'overlay' | 'fullScreen';
 
 export interface ModalProps
   extends Pick<RNModalProps, 'statusBarTranslucent' | 'onRequestClose' | 'hardwareAccelerated'> {
@@ -38,7 +38,6 @@ const useStyles = createStyles((theme) => ({
   flex1: { flex: 1 },
   fullWrapper: { flex: 1, backgroundColor: theme.colors.background },
   overlayContainer: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: theme.tokens.spacing.xxl - 4 },
-  bottomSheetContainer: { justifyContent: 'flex-end', padding: 0 },
   backdrop: { backgroundColor: theme.colors.overlay },
   overlayCard: {
     width: '100%',
@@ -48,15 +47,6 @@ const useStyles = createStyles((theme) => ({
     overflow: 'hidden',
     ...theme.tokens.shadow.lg,
   },
-  bottomSheetCard: {
-    width: '100%',
-    maxHeight: '90%',
-    backgroundColor: theme.colors.surface,
-    borderTopLeftRadius: theme.tokens.radius.xxl,
-    borderTopRightRadius: theme.tokens.radius.xxl,
-    overflow: 'hidden',
-    ...theme.tokens.shadow.lg,
-  },
   header: {
     flexDirection: 'row',
     justifyContent: 'space-between',
@@ -83,10 +73,8 @@ const useStyles = createStyles((theme) => ({
 /**
  * Modal
  * Un solo componente para todos los modales de la app: maneja scroll,
- * teclado, insets y layout según `variant`. overlay/bottomSheet/full animan
- * su entrada/salida con Animated (solo transform, nunca opacity sobre la
- * tarjeta: animar opacity ahí dispara un bug de Android donde los hijos con
- * elevation parpadean/redibujan). El fondo semitransparente sí anima opacity.
+ * teclado, insets y layout según `variant`. Para una hoja desde abajo está
+ * BottomSheet, que además trae arrastre para cerrar.
  */
 export const Modal = memo(
   ({
@@ -107,43 +95,22 @@ export const Modal = memo(
     const isFull = variant === 'full';
     const isOverlay = variant === 'overlay';
     const isFullScreen = variant === 'fullScreen';
-    const isBottomSheet = variant === 'bottomSheet';
-    const isAnimatedVariant = isOverlay || isBottomSheet || isFull;
+    const isAnimatedVariant = isOverlay || isFull;
     const insets = useInsets();
     const colors = useColors();
     const styles = useStyles();
 
     const [mounted, setMounted] = useState(!isAnimatedVariant && visible);
-    const backdropOpacity = useRef(new Animated.Value(0)).current;
-    const cardProgress = useRef(new Animated.Value(0)).current;
 
     useEffect(() => {
-      if (!isAnimatedVariant) {
-        setMounted(visible);
-        return;
-      }
-      if (visible) {
-        setMounted(true);
-        Animated.timing(backdropOpacity, { toValue: 1, duration: 200, useNativeDriver: true }).start();
-        Animated.timing(cardProgress, { toValue: 1, duration: 250, useNativeDriver: true }).start();
-      } else {
-        Animated.timing(backdropOpacity, { toValue: 0, duration: 180, useNativeDriver: true }).start();
-        Animated.timing(cardProgress, { toValue: 0, duration: 200, useNativeDriver: true }).start(({ finished }) => {
-          if (finished) setMounted(false);
-        });
-      }
-      // eslint-disable-next-line react-hooks/exhaustive-deps
+      if (!isAnimatedVariant) setMounted(visible);
+      else if (visible) setMounted(true);
     }, [visible, isAnimatedVariant]);
 
-    const cardAnimatedStyle =
-      isBottomSheet || isFull
-        ? { transform: [{ translateY: cardProgress.interpolate({ inputRange: [0, 1], outputRange: [SCREEN_HEIGHT, 0] }) }] }
-        : {
-            transform: [
-              { translateY: cardProgress.interpolate({ inputRange: [0, 1], outputRange: [-40, 0] }) },
-              { scale: cardProgress.interpolate({ inputRange: [0, 1], outputRange: [0.9, 1] }) },
-            ],
-          };
+    // La tarjeta nunca anima opacity: hacerlo dispara un bug de Android donde
+    // los hijos con elevation parpadean. El fondo semitransparente sí.
+    const cardPreset: TransitionPreset[] = isFull ? ['slide-up'] : ['slide-down', 'scale'];
+    const cardDistance = isFull ? SCREEN_HEIGHT : 40;
 
     const behavior = Platform.OS === 'ios' ? (isFull ? undefined : 'padding') : 'height';
     const keyboardOffset = Platform.OS === 'ios' ? 0 : 20;
@@ -204,42 +171,63 @@ export const Modal = memo(
         presentationStyle={
           Platform.OS === 'ios' ? (isFullScreen ? 'fullScreen' : 'overFullScreen') : undefined
         }
-        transparent={isOverlay || isBottomSheet || isFull}
+        transparent={isOverlay || isFull}
         statusBarTranslucent={statusBarTranslucent}
         hardwareAccelerated={hardwareAccelerated}
       >
         <KeyboardAvoidingView behavior={behavior} keyboardVerticalOffset={keyboardOffset} style={styles.flex1}>
-          {isOverlay || isBottomSheet ? (
-            <View style={[styles.overlayContainer, isBottomSheet && styles.bottomSheetContainer]}>
+          {isOverlay ? (
+            <View style={styles.overlayContainer}>
               {/* Sin accessibilityLabel propio: el header ya expone un botón "Close"
                   accesible; duplicar el label aquí generaría dos elementos con el
                   mismo nombre para lectores de pantalla. Tocar afuera es un atajo
                   puramente táctil. */}
-              <Animated.View style={[{ ...StyleSheetAbsoluteFill }, styles.backdrop, { opacity: backdropOpacity }]}>
+              <Transition
+                visible={visible}
+                preset="fade"
+                duration={200}
+                keepMounted
+                style={[{ ...StyleSheetAbsoluteFill }, styles.backdrop]}
+              >
                 <Pressable style={StyleSheetAbsoluteFill} onPress={onClose} testID="modal-backdrop" />
-              </Animated.View>
-
-              <Animated.View
-                style={[
-                  isOverlay ? styles.overlayCard : styles.bottomSheetCard,
-                  isBottomSheet && { paddingBottom: Math.max(insets.bottom, Platform.OS === 'ios' ? 20 : 0) },
-                  containerStyle,
-                  cardAnimatedStyle,
-                ]}
+              </Transition>
+
+              <Transition
+                visible={visible}
+                preset={cardPreset}
+                distance={cardDistance}
+                duration={250}
+                onExited={() => setMounted(false)}
+                style={[styles.overlayCard, containerStyle]}
               >
                 {renderHeader()}
                 {renderMainContent()}
                 {renderFooter()}
-              </Animated.View>
+              </Transition>
             </View>
+          ) : isFull ? (
+            <Transition
+              visible={visible}
+              preset={cardPreset}
+              distance={cardDistance}
+              duration={250}
+              onExited={() => setMounted(false)}
+              style={[styles.fullWrapper, containerStyle]}
+            >
+              <View style={[styles.flex1, { paddingTop: insets.top, paddingBottom: insets.bottom }]}>
+                {renderHeader()}
+                {renderMainContent()}
+                {renderFooter()}
+              </View>
+            </Transition>
           ) : (
-            <Animated.View style={[styles.fullWrapper, containerStyle, isFull && cardAnimatedStyle]}>
+            <View style={[styles.fullWrapper, containerStyle]}>
               <View style={[styles.flex1, { paddingTop: insets.top, paddingBottom: insets.bottom }]}>
                 {renderHeader()}
                 {renderMainContent()}
                 {renderFooter()}
               </View>
-            </Animated.View>
+            </View>
           )}
         </KeyboardAvoidingView>
       </RNModal>

package/src/organisms/NavigationBar.tsx

@@ -0,0 +1,226 @@
+import React, { memo, useEffect, useRef, useState } from 'react';
+import {
+  Animated,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+  type LayoutChangeEvent,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { createStyles } from '../theme/createStyles';
+import { useAllowFontScaling, useColors, useInsets, useTheme } from '../theme/UIProvider';
+import { Icon } from '../icons/Icon';
+import type { IconName } from '../icons/types';
+
+export interface NavigationBarItem {
+  key: string;
+  label: string;
+  iconName?: IconName;
+  /** Contador sobre el ícono. `true` pinta sólo el punto. */
+  badge?: number | string | true;
+}
+
+export interface NavigationBarProps {
+  items: NavigationBarItem[];
+  activeKey: string;
+  onChange: (key: string) => void;
+  /** Borde de la pantalla donde vive la barra. @default 'bottom' */
+  position?: 'bottom' | 'top';
+  /** @default true */
+  showLabels?: boolean;
+  /** Suma el inset de safe area del borde donde vive la barra. @default true */
+  safeArea?: boolean;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+const useStyles = createStyles((theme) => ({
+  bar: {
+    flexDirection: 'row',
+    backgroundColor: theme.colors.surface,
+    borderColor: theme.colors.border,
+    paddingHorizontal: theme.tokens.spacing.xs,
+    paddingVertical: theme.tokens.spacing.sm,
+  },
+  barBottom: { borderTopWidth: StyleSheet.hairlineWidth },
+  barTop: { borderBottomWidth: StyleSheet.hairlineWidth },
+  indicator: {
+    position: 'absolute',
+    top: theme.tokens.spacing.xs,
+    bottom: theme.tokens.spacing.xs,
+    left: theme.tokens.spacing.sm,
+    borderRadius: theme.tokens.radius.lg,
+    backgroundColor: theme.colors.primarySoft,
+  },
+  item: { flex: 1, paddingVertical: theme.tokens.spacing.xs },
+  itemContent: { alignItems: 'center', justifyContent: 'center', gap: 2 },
+  label: { fontSize: theme.tokens.fontSize.xs, fontWeight: theme.tokens.fontWeight.medium },
+  badge: {
+    position: 'absolute',
+    top: -4,
+    left: '50%',
+    marginLeft: 4,
+    minWidth: 16,
+    height: 16,
+    paddingHorizontal: 4,
+    borderRadius: theme.tokens.radius.full,
+    backgroundColor: theme.colors.error,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  badgeDot: { minWidth: 10, height: 10, top: -2, paddingHorizontal: 0 },
+  badgeText: {
+    fontSize: 10,
+    fontWeight: theme.tokens.fontWeight.bold,
+    color: theme.colors.onError,
+  },
+}));
+
+const ICON_SIZE = 22;
+
+/**
+ * NavigationBar
+ * Barra de navegación por pestañas con la misma apariencia y las mismas
+ * transiciones en iOS y Android: el indicador se desliza hasta la pestaña
+ * activa y su contenido crece y toma el color de acento con un cross-fade.
+ * No navega por su cuenta — reporta la pestaña tocada y el consumidor decide.
+ */
+export const NavigationBar = memo(
+  ({
+    items,
+    activeKey,
+    onChange,
+    position = 'bottom',
+    showLabels = true,
+    safeArea = true,
+    style,
+    testID,
+  }: NavigationBarProps) => {
+    const theme = useTheme();
+    const colors = useColors();
+    const styles = useStyles();
+    const insets = useInsets();
+    const allowFontScaling = useAllowFontScaling();
+
+    const [barWidth, setBarWidth] = useState(0);
+    const slide = useRef(new Animated.Value(0)).current;
+    const placed = useRef(false);
+
+    const activeIndex = Math.max(
+      0,
+      items.findIndex((item) => item.key === activeKey)
+    );
+    const itemWidth = items.length > 0 ? barWidth / items.length : 0;
+
+    useEffect(() => {
+      if (itemWidth <= 0) return;
+      const to = activeIndex * itemWidth;
+      // En el primer layout el indicador aparece en su lugar; animarlo desde 0
+      // sería un deslizamiento que el usuario no pidió.
+      if (!placed.current) {
+        placed.current = true;
+        slide.setValue(to);
+        return;
+      }
+      Animated.spring(slide, { toValue: to, useNativeDriver: true, friction: 9, tension: 90 }).start();
+    }, [activeIndex, itemWidth, slide]);
+
+    const onLayout = (e: LayoutChangeEvent) => {
+      const next = e.nativeEvent.layout.width - theme.tokens.spacing.xs * 2;
+      if (next !== barWidth) setBarWidth(next);
+    };
+
+    const renderContent = (item: NavigationBarItem, color: string) => (
+      <>
+        {!!item.iconName && <Icon name={item.iconName} size={ICON_SIZE} color={color} />}
+        {showLabels && (
+          <Text allowFontScaling={allowFontScaling} numberOfLines={1} style={[styles.label, { color }]}>
+            {item.label}
+          </Text>
+        )}
+      </>
+    );
+
+    return (
+      <View
+        testID={testID}
+        onLayout={onLayout}
+        accessibilityRole="tablist"
+        style={[
+          styles.bar,
+          position === 'bottom' ? styles.barBottom : styles.barTop,
+          safeArea && position === 'bottom' && { paddingBottom: theme.tokens.spacing.sm + insets.bottom },
+          safeArea && position === 'top' && { paddingTop: theme.tokens.spacing.sm + insets.top },
+          style,
+        ]}
+      >
+        {itemWidth > 0 && (
+          <Animated.View
+            testID="navigation-bar-indicator"
+            pointerEvents="none"
+            style={[
+              styles.indicator,
+              safeArea && position === 'bottom' && { bottom: theme.tokens.spacing.xs + insets.bottom },
+              safeArea && position === 'top' && { top: theme.tokens.spacing.xs + insets.top },
+              {
+                width: itemWidth - theme.tokens.spacing.sm * 2,
+                transform: [{ translateX: slide }],
+              },
+            ]}
+          />
+        )}
+
+        {items.map((item, index) => {
+          const active = index === activeIndex;
+          const range = [(index - 1) * itemWidth, index * itemWidth, (index + 1) * itemWidth];
+          const scale =
+            itemWidth > 0
+              ? slide.interpolate({ inputRange: range, outputRange: [1, 1.08, 1], extrapolate: 'clamp' })
+              : 1;
+          const activeOpacity =
+            itemWidth > 0
+              ? slide.interpolate({ inputRange: range, outputRange: [0, 1, 0], extrapolate: 'clamp' })
+              : 0;
+
+          return (
+            <TouchableOpacity
+              key={item.key}
+              style={styles.item}
+              activeOpacity={0.7}
+              onPress={() => onChange(item.key)}
+              accessibilityRole="tab"
+              accessibilityLabel={item.label}
+              accessibilityState={{ selected: active }}
+            >
+              <Animated.View style={[styles.itemContent, { transform: [{ scale }] }]}>
+                {renderContent(item, colors.textLight)}
+                {/* Copia decorativa: sin ocultarla, el lector lee el label dos veces. */}
+                <Animated.View
+                  pointerEvents="none"
+                  accessibilityElementsHidden
+                  importantForAccessibility="no-hide-descendants"
+                  style={[StyleSheet.absoluteFill, styles.itemContent, { opacity: activeOpacity }]}
+                >
+                  {renderContent(item, colors.primaryText)}
+                </Animated.View>
+
+                {item.badge !== undefined && (
+                  <View style={[styles.badge, item.badge === true && styles.badgeDot]}>
+                    {item.badge !== true && (
+                      <Text allowFontScaling={false} style={styles.badgeText}>
+                        {item.badge}
+                      </Text>
+                    )}
+                  </View>
+                )}
+              </Animated.View>
+            </TouchableOpacity>
+          );
+        })}
+      </View>
+    );
+  }
+);
+NavigationBar.displayName = 'NavigationBar';

package/src/organisms/Screen.tsx

@@ -13,7 +13,8 @@ export interface ScreenProps {
   /** Qué insets de safe area aplicar. @default ['top', 'bottom'] */
   edges?: ScreenEdge[];
   /**
-   * Compensa el teclado con un KeyboardAvoidingView. Ponelo en false cuando
+   * Compensa el teclado: en iOS con scroll lo hace el propio ScrollView, en el
+   * resto de los casos con un KeyboardAvoidingView. Ponelo en false cuando
    * el contenido ya trae su propio scroller que maneja el teclado (Wizard,
    * List, SearchList): las dos compensaciones se suman y el campo enfocado
    * termina empujado fuera de la pantalla.
@@ -46,8 +47,15 @@ export const Screen = memo(({
   const applyTop = edges.includes('top');
   const applyBottom = edges.includes('bottom');
 
-  const KeyboardWrapper: React.ComponentType<any> = keyboardAvoiding ? KeyboardAvoidingView : View;
-  const keyboardProps = keyboardAvoiding
+  // En iOS el ScrollView de abajo ya sube el campo enfocado con
+  // automaticallyAdjustKeyboardInsets; envolverlo además en un
+  // KeyboardAvoidingView compensa el teclado dos veces y el input termina
+  // empujado fuera del borde superior. Android no tiene ese prop, así que ahí
+  // el KeyboardAvoidingView sigue siendo el único mecanismo.
+  const avoidWithView = keyboardAvoiding && !(scrollable && Platform.OS === 'ios');
+
+  const KeyboardWrapper: React.ComponentType<any> = avoidWithView ? KeyboardAvoidingView : View;
+  const keyboardProps = avoidWithView
     ? {
         behavior: Platform.OS === 'ios' ? ('padding' as const) : ('height' as const),
         keyboardVerticalOffset: Platform.OS === 'ios' ? 0 : 20,

package/src/organisms/SearchList.tsx

@@ -1,9 +1,19 @@
-import React, { memo } from 'react';
-import { ActivityIndicator, FlatList, Text, View, type FlatListProps, type StyleProp, type ViewStyle } from 'react-native';
+import React, { useCallback } from 'react';
+import {
+  ActivityIndicator,
+  FlatList,
+  RefreshControl,
+  Text,
+  View,
+  type FlatListProps,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
 import { createStyles } from '../theme/createStyles';
 import { useColors, useLabels } from '../theme/UIProvider';
 import { Input } from '../atoms/Input';
 import { EmptyState } from '../atoms/EmptyState';
+import { Skeleton } from '../atoms/Skeleton';
 import { Spinner } from '../atoms/Spinner';
 import { IconButton } from '../atoms/IconButton';
 import type { IconName } from '../icons/types';
@@ -21,25 +31,44 @@ export interface SearchListProps<T> {
   extraActions?: React.ReactNode;
 
   data: T[];
-  keyExtractor: (item: T) => string;
+  keyExtractor: (item: T, index: number) => string;
   renderItem: FlatListProps<T>['renderItem'];
 
+  /** Carga inicial: mientras sea true y no haya datos, se muestran placeholders. */
   isLoading?: boolean;
-  /** 'replace' cambia toda la lista por un spinner; 'overlay' lo muestra encima manteniendo el layout. */
+  /** 'replace' cambia toda la lista por un spinner/skeleton; 'overlay' lo muestra encima manteniendo el layout. */
   loadingMode?: 'replace' | 'overlay';
-  loadingText?: string;
-
-  onLoadMore?: () => void;
+  /** Recarga con datos ya en pantalla (pull-to-refresh). @default false */
+  isRefreshing?: boolean;
   isLoadingMore?: boolean;
+  /** Controlado por el consumidor: mientras es false, se muestra un spinner de pantalla completa. @default true */
+  isReady?: boolean;
+  loadingText?: string;
   loadingMoreText?: string;
   hasMore?: boolean;
   noMoreText?: string;
 
+  /** Filas fantasma de la carga inicial. @default 6 */
+  skeletonCount?: number;
+  /** Placeholder propio, para que calce con la forma real del ítem. */
+  renderSkeletonItem?: () => React.ReactElement;
+
+  onLoadMore?: () => void;
+  onEndReached?: () => void;
+  onEndReachedThreshold?: number;
+  onRefresh?: () => void;
+
   emptyTitle?: string;
   emptyDescription?: string;
   emptyIconName?: IconName;
 
+  ListHeaderComponent?: FlatListProps<T>['ListHeaderComponent'];
+  ListFooterComponent?: FlatListProps<T>['ListFooterComponent'];
+
   contentContainerStyle?: StyleProp<ViewStyle>;
+  containerStyle?: ViewStyle;
+
+  /** Componente de lista a usar (FlashList, etc). @default FlatList */
   ListComponent?: React.ComponentType<any>;
   listProps?: Record<string, unknown>;
 }
@@ -64,6 +93,13 @@ const useStyles = createStyles((theme) => ({
   },
   footer: { paddingVertical: theme.tokens.spacing.xl, alignItems: 'center', gap: theme.tokens.spacing.md },
   footerText: { color: theme.colors.textLight, fontSize: theme.tokens.fontSize.md },
+  skeletonRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: theme.tokens.spacing.md,
+    padding: theme.tokens.spacing.md,
+  },
+  skeletonText: { flex: 1, gap: theme.tokens.spacing.sm },
 }));
 
 /**
@@ -86,16 +122,26 @@ export function SearchList<T>({
   renderItem,
   isLoading = false,
   loadingMode = 'replace',
-  loadingText,
-  onLoadMore,
+  isRefreshing = false,
   isLoadingMore = false,
+  isReady = true,
+  loadingText,
   loadingMoreText,
   hasMore = false,
   noMoreText,
+  skeletonCount = 6,
+  renderSkeletonItem,
+  onLoadMore,
+  onEndReached,
+  onEndReachedThreshold = 0.3,
+  onRefresh,
   emptyTitle,
   emptyDescription,
   emptyIconName,
+  ListHeaderComponent,
+  ListFooterComponent,
   contentContainerStyle,
+  containerStyle,
   ListComponent = FlatList,
   listProps,
 }: SearchListProps<T>) {
@@ -106,30 +152,55 @@ export function SearchList<T>({
   const resolvedLoadingText = loadingText ?? labels.loading;
   const resolvedLoadingMoreText = loadingMoreText ?? labels.loadingMore;
 
-  const renderFooter = () => {
-    if (isLoadingMore) {
-      return (
-        <View style={styles.footer}>
-          <Spinner text={resolvedLoadingMoreText} fullscreen={false} />
-        </View>
-      );
-    }
-    if (noMoreText && !hasMore && data.length > 0) {
-      return (
-        <View style={styles.footer}>
-          <Text style={styles.footerText}>{noMoreText}</Text>
-        </View>
+  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.
+  const renderFooter = useCallback(() => {
+    const custom =
+      typeof ListFooterComponent === 'function' ? (
+        <ListFooterComponent />
+      ) : (
+        (ListFooterComponent as React.ReactElement | undefined) ?? null
       );
-    }
-    return null;
-  };
 
-  const showReplaceLoading = isLoading && loadingMode === 'replace' && data.length === 0;
+    return (
+      <>
+        {custom}
+        {isLoadingMore && (
+          <View style={styles.footer}>
+            <Spinner text={resolvedLoadingMoreText} fullscreen={false} />
+          </View>
+        )}
+        {noMoreText && !hasMore && data.length > 0 && (
+          <View style={styles.footer}>
+            <Text style={styles.footerText}>{noMoreText}</Text>
+          </View>
+        )}
+      </>
+    );
+  }, [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".
+  const renderEmpty = useCallback(() => {
+    if (isLoading || isRefreshing) return null;
+    return <EmptyState title={emptyTitle} description={emptyDescription} iconName={emptyIconName} style={{ marginTop: 50 }} />;
+  }, [isLoading, isRefreshing, emptyTitle, emptyDescription, emptyIconName]);
+
+  if (!isReady) {
+    return (
+      <View style={[styles.container, containerStyle]}>
+        <Spinner text={resolvedLoadingText} />
+      </View>
+    );
+  }
+
+  const isInitialLoading = isLoading && loadingMode === 'replace' && data.length === 0;
   const showOverlayLoading = isLoading && loadingMode === 'overlay' && data.length === 0;
-  const showEmpty = !isLoading && data.length === 0;
 
   return (
-    <View style={styles.container}>
+    <View style={[styles.container, containerStyle]}>
       {header}
 
       <View style={styles.searchRow}>
@@ -163,20 +234,44 @@ export function SearchList<T>({
           </View>
         )}
 
-        {showReplaceLoading ? (
-          <Spinner text={resolvedLoadingText} />
-        ) : showEmpty ? (
-          <EmptyState title={emptyTitle} description={emptyDescription} iconName={emptyIconName} />
+        {isInitialLoading ? (
+          <View testID="list-skeleton" style={[styles.listContent, contentContainerStyle]}>
+            {Array.from({ length: skeletonCount }, (_, i) => (
+              <React.Fragment key={i}>
+                {renderSkeletonItem?.() ?? (
+                  <View style={styles.skeletonRow}>
+                    <Skeleton variant="circle" width={40} />
+                    <View style={styles.skeletonText}>
+                      <Skeleton width="60%" height={14} />
+                      <Skeleton width="35%" height={12} />
+                    </View>
+                  </View>
+                )}
+              </React.Fragment>
+            ))}
+          </View>
         ) : (
           <ListComponent
             data={data}
             keyExtractor={keyExtractor}
             keyboardDismissMode="on-drag"
-            contentContainerStyle={contentContainerStyle ?? styles.listContent}
-            onEndReached={onLoadMore}
-            onEndReachedThreshold={0.2}
+            contentContainerStyle={[styles.listContent, contentContainerStyle]}
+            onEndReached={handleEndReached}
+            onEndReachedThreshold={onEndReachedThreshold}
+            ListHeaderComponent={ListHeaderComponent}
             ListFooterComponent={renderFooter}
+            ListEmptyComponent={renderEmpty}
             renderItem={renderItem}
+            refreshControl={
+              onRefresh ? (
+                <RefreshControl
+                  refreshing={isRefreshing}
+                  onRefresh={onRefresh}
+                  colors={[colors.primary]}
+                  tintColor={colors.primary}
+                />
+              ) : undefined
+            }
             {...listProps}
           />
         )}
@@ -184,3 +279,4 @@ export function SearchList<T>({
     </View>
   );
 }
+