orn-ui 0.2.6 → 0.2.8

package/src/organisms/SearchList.tsx

@@ -19,7 +19,7 @@ import { IconButton } from '../atoms/IconButton';
 import type { IconName } from '../icons/types';
 
 export interface SearchListProps<T> {
-  /** Chrome opcional arriba del buscador (ej. back button + título). */
+  /** Optional chrome above the search bar (e.g. back button + title). */
   header?: React.ReactNode;
 
   searchValue: string;
@@ -34,23 +34,23 @@ export interface SearchListProps<T> {
   keyExtractor: (item: T, index: number) => string;
   renderItem: FlatListProps<T>['renderItem'];
 
-  /** Carga inicial: mientras sea true y no haya datos, se muestran placeholders. */
+  /** Initial load: while true and there's no data, placeholders are shown. */
   isLoading?: boolean;
-  /** 'replace' cambia toda la lista por un spinner/skeleton; 'overlay' lo muestra encima manteniendo el layout. */
+  /** 'replace' swaps the whole list for a spinner/skeleton; 'overlay' shows it on top while keeping the layout. */
   loadingMode?: 'replace' | 'overlay';
-  /** Recarga con datos ya en pantalla (pull-to-refresh). @default false */
+  /** Reload with data already on screen (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 */
+  /** Controlled by the consumer: while false, a fullscreen spinner is shown. @default true */
   isReady?: boolean;
   loadingText?: string;
   loadingMoreText?: string;
   hasMore?: boolean;
   noMoreText?: string;
 
-  /** Filas fantasma de la carga inicial. @default 6 */
+  /** Ghost rows for the initial load. @default 6 */
   skeletonCount?: number;
-  /** Placeholder propio, para que calce con la forma real del ítem. */
+  /** Custom placeholder, to match the real shape of the item. */
   renderSkeletonItem?: () => React.ReactElement;
 
   onLoadMore?: () => void;
@@ -68,7 +68,7 @@ export interface SearchListProps<T> {
   contentContainerStyle?: StyleProp<ViewStyle>;
   containerStyle?: ViewStyle;
 
-  /** Componente de lista a usar (FlashList, etc). @default FlatList */
+  /** List component to use (FlashList, etc). @default FlatList */
   ListComponent?: React.ComponentType<any>;
   listProps?: Record<string, unknown>;
 }

package/src/organisms/Select.tsx

@@ -38,10 +38,10 @@ export interface SelectProps<T> {
   error?: string;
   isLoading?: boolean;
   disabled?: boolean;
-  /** Agrega un buscador dentro del desplegable. @default false */
+  /** Adds a search box inside the dropdown. @default false */
   searchable?: boolean;
   searchPlaceholder?: string;
-  /** Alto máximo del desplegable, si el espacio disponible lo permite. @default 280 */
+  /** Maximum height of the dropdown, if the available space allows it. @default 280 */
   maxHeight?: number;
   onOpenChange?: (open: boolean) => void;
   containerStyle?: StyleProp<ViewStyle>;

package/src/organisms/Slides.tsx

@@ -0,0 +1,413 @@
+import React, { memo, useEffect, useRef } from 'react';
+import {
+  Animated,
+  Easing,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+import { createStyles } from '../theme/createStyles';
+import { useAllowFontScaling, useColors, useTheme } from '../theme/UIProvider';
+import { useReduceMotion } from '../atoms/Transition';
+import { Gradient, type GradientDirection } from '../atoms/Gradient';
+import { useSlides, type SlidesOrientation } from './useSlides';
+
+export type { SlidesOrientation } from './useSlides';
+export type SlidesIndicators = 'dots' | 'numbers' | 'none';
+export type SlidesIndicatorPlacement = 'overlay' | 'outside';
+
+/** Un color sólido, o dos o más para un degradado (ver `Gradient`). */
+export type SlideBackground = string | string[];
+
+export interface SlidesProps<T> {
+  data: T[];
+  keyExtractor: (item: T, index: number) => string;
+  /** Contenido de la slide: imágenes, botones, lo que sea. Se dibuja sobre `background`. */
+  renderItem: (item: T, index: number) => React.ReactNode;
+  /** Fondo por slide: `'#101014'` pinta plano, `['#004cef', '#00cae1']` degrada. */
+  background?: (item: T, index: number) => SlideBackground | undefined;
+  /** Dirección del degradado cuando `background` devuelve varios colores. @default 'vertical' */
+  gradientDirection?: GradientDirection;
+  /** @default 'horizontal' */
+  orientation?: SlidesOrientation;
+  /** Círculos, círculos numerados, o ninguno. @default 'dots' */
+  indicators?: SlidesIndicators;
+  /**
+   * 'overlay' los apoya sobre la slide, en blanco; 'outside' los saca fuera
+   * del área deslizable, con los colores del tema.
+   * @default 'overlay'
+   */
+  indicatorPlacement?: SlidesIndicatorPlacement;
+  /** Después de la última vuelve a la primera (y al revés). @default false */
+  loop?: boolean;
+  /** Avanza solo. Se pausa mientras el dedo arrastra. @default false */
+  autoPlay?: boolean;
+  /** ms entre avances de `autoPlay`. @default 4000 */
+  interval?: number;
+  /**
+   * Botón para frenar el avance automático. Sólo aparece con `autoPlay`, y va
+   * en `true` porque contenido que se mueve solo necesita una forma de
+   * pausarlo (WCAG 2.2.2).
+   * @default true
+   */
+  showAutoPlayToggle?: boolean;
+  /** Hueco entre slides, en px. En 0 quedan pegadas. @default 0 */
+  spacing?: number;
+  /** Índice controlado. Sin él, el componente maneja el suyo desde `defaultIndex`. */
+  index?: number;
+  /** @default 0 */
+  defaultIndex?: number;
+  onIndexChange?: (index: number) => void;
+  /** Alto del área deslizable. @default 240 */
+  height?: number;
+  /** @default true */
+  swipeEnabled?: boolean;
+  /** Estilos de la caja visible de cada slide — padding, alineación, radio. */
+  slideStyle?: StyleProp<ViewStyle>;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+const DOT = 8;
+const DOT_ACTIVE = 20;
+const NUMBER_CIRCLE = 24;
+const TOGGLE = 32;
+const DEFAULT_HEIGHT = 240;
+const DEFAULT_INTERVAL = 4000;
+
+const useStyles = createStyles((theme) => ({
+  // Deja redondear el bloque por `style` sin que el degradado se salga.
+  root: { overflow: 'hidden' },
+  viewport: { flex: 1 },
+  // La slide visible es la caja de adentro: con `spacing` la página es más
+  // ancha que ella, y el fondo tiene que recortarse acá y no en la página, o
+  // el degradado pinta también el hueco.
+  slide: { flex: 1, overflow: 'hidden' },
+  // Con indicadores fuera y orientación vertical el contenedor es una fila:
+  // sin flex la ventana no tiene ancho propio y colapsa a 0.
+  viewportInRow: { flex: 1 },
+  slideContent: { flex: 1 },
+
+  indicatorsRow: { flexDirection: 'row', alignItems: 'center', justifyContent: 'center' },
+  indicatorsColumn: { flexDirection: 'column', alignItems: 'center', justifyContent: 'center' },
+  indicatorsOverlayHorizontal: { position: 'absolute', left: 0, right: 0, bottom: theme.tokens.spacing.md },
+  indicatorsOverlayVertical: { position: 'absolute', top: 0, bottom: 0, right: theme.tokens.spacing.md },
+  indicatorsOutsideHorizontal: { paddingTop: theme.tokens.spacing.md },
+  indicatorsOutsideVertical: { paddingLeft: theme.tokens.spacing.md },
+  indicatorSlot: { padding: theme.tokens.spacing.xs },
+
+  dot: { width: DOT, height: DOT, borderRadius: DOT / 2 },
+
+  autoPlayToggle: {
+    position: 'absolute',
+    top: theme.tokens.spacing.md,
+    right: theme.tokens.spacing.md,
+    width: TOGGLE,
+    height: TOGGLE,
+    borderRadius: TOGGLE / 2,
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'row',
+    gap: 3,
+  },
+  pauseBar: { width: 3, height: 12, borderRadius: 1 },
+  // Triángulo con bordes: un "play" sin SVG ni set de íconos.
+  playTriangle: {
+    width: 0,
+    height: 0,
+    marginLeft: 2,
+    borderTopWidth: 6,
+    borderBottomWidth: 6,
+    borderLeftWidth: 10,
+    borderTopColor: 'transparent',
+    borderBottomColor: 'transparent',
+  },
+
+  numberCircle: {
+    minWidth: NUMBER_CIRCLE,
+    height: NUMBER_CIRCLE,
+    borderRadius: NUMBER_CIRCLE / 2,
+    borderWidth: 1,
+    paddingHorizontal: theme.tokens.spacing.xs,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  numberText: { fontSize: theme.tokens.fontSize.xs, fontWeight: theme.tokens.fontWeight.semibold },
+
+  outsideHorizontal: { flexDirection: 'column' },
+  outsideVertical: { flexDirection: 'row' },
+}));
+
+interface DotProps {
+  selected: boolean;
+  isHorizontal: boolean;
+  /** En overlay el contraste lo da la opacidad; afuera, el color. */
+  overlay: boolean;
+  activeColor: string;
+  inactiveColor: string;
+  testID?: string;
+}
+
+/**
+ * El punto activo se estira en vez de saltar: el cambio de golpe se lee como
+ * "apareció otro punto", no como "el mismo se movió". Ancho y color son props
+ * de layout/pintura, así que van por el driver de JS.
+ */
+const Dot = memo(({ selected, isHorizontal, overlay, activeColor, inactiveColor, testID }: DotProps) => {
+  const styles = useStyles();
+  const theme = useTheme();
+  const reduceMotion = useReduceMotion();
+  const progress = useRef(new Animated.Value(selected ? 1 : 0)).current;
+
+  useEffect(() => {
+    Animated.timing(progress, {
+      toValue: selected ? 1 : 0,
+      duration: reduceMotion ? 0 : theme.tokens.duration.base,
+      easing: Easing.out(Easing.quad),
+      useNativeDriver: false,
+    }).start();
+  }, [progress, reduceMotion, selected, theme]);
+
+  const length = progress.interpolate({ inputRange: [0, 1], outputRange: [DOT, DOT_ACTIVE] });
+  const backgroundColor = progress.interpolate({ inputRange: [0, 1], outputRange: [inactiveColor, activeColor] });
+
+  return (
+    <Animated.View
+      testID={testID}
+      style={[
+        styles.dot,
+        isHorizontal ? { width: length } : { height: length },
+        { backgroundColor },
+        overlay && { opacity: progress.interpolate({ inputRange: [0, 1], outputRange: [0.45, 1] }) },
+      ]}
+    />
+  );
+});
+Dot.displayName = 'SlidesDot';
+
+/**
+ * Slides
+ * Carrusel con fondo propio (color plano o degradado) y contenido libre:
+ * `renderItem` decide si adentro va una imagen, texto o botones. El estado
+ * vive en `useSlides`; acá sólo está el árbol.
+ *
+ * El deslizamiento es un `ScrollView` con `pagingEnabled` en vez de gestos a
+ * mano: es lo único que da snap nativo en iOS y Android sin
+ * `react-native-gesture-handler`, en todo el rango soportado (Expo SDK 54–57).
+ */
+export function Slides<T>({
+  data,
+  keyExtractor,
+  renderItem,
+  background,
+  gradientDirection = 'vertical',
+  orientation = 'horizontal',
+  indicators = 'dots',
+  indicatorPlacement = 'overlay',
+  loop = false,
+  autoPlay = false,
+  interval = DEFAULT_INTERVAL,
+  showAutoPlayToggle = true,
+  spacing = 0,
+  index,
+  defaultIndex = 0,
+  onIndexChange,
+  height = DEFAULT_HEIGHT,
+  swipeEnabled = true,
+  slideStyle,
+  style,
+  testID,
+}: SlidesProps<T>) {
+  const colors = useColors();
+  const styles = useStyles();
+  const allowFontScaling = useAllowFontScaling();
+
+  const total = data.length;
+  const {
+    active,
+    pages,
+    isHorizontal,
+    size,
+    pageSize,
+    scrollRef,
+    autoPlayPaused,
+    motionReduced,
+    goTo,
+    toggleAutoPlay,
+    onLayout,
+    onMomentumScrollEnd,
+    onScrollBeginDrag,
+    onScrollEndDrag,
+  } = useSlides({ total, orientation, loop, autoPlay, interval, index, defaultIndex, onIndexChange });
+
+  const isOverlay = indicatorPlacement === 'overlay';
+
+  const renderBackground = (item: T, real: number) => {
+    const value = background?.(item, real);
+    if (!value) return null;
+    if (Array.isArray(value)) {
+      return <Gradient colors={value} direction={gradientDirection} style={StyleSheet.absoluteFill} />;
+    }
+    return <View style={[StyleSheet.absoluteFill, { backgroundColor: value }]} pointerEvents="none" />;
+  };
+
+  const renderIndicator = (position: number) => {
+    const selected = position === active;
+
+    if (indicators === 'numbers') {
+      const numberColors = isOverlay
+        ? {
+            background: selected ? colors.white : 'transparent',
+            border: colors.white,
+            text: selected ? colors.black : colors.white,
+          }
+        : {
+            background: selected ? colors.primary : 'transparent',
+            border: selected ? colors.primary : colors.border,
+            text: selected ? colors.onPrimary : colors.textLight,
+          };
+      return (
+        <View
+          style={[
+            styles.numberCircle,
+            { backgroundColor: numberColors.background, borderColor: numberColors.border },
+          ]}
+        >
+          <Text allowFontScaling={allowFontScaling} style={[styles.numberText, { color: numberColors.text }]}>
+            {position + 1}
+          </Text>
+        </View>
+      );
+    }
+
+    return (
+      <Dot
+        testID={`${testID ?? 'slides'}-dot-${position}`}
+        selected={selected}
+        isHorizontal={isHorizontal}
+        overlay={isOverlay}
+        activeColor={isOverlay ? colors.white : colors.primary}
+        inactiveColor={isOverlay ? colors.white : colors.border}
+      />
+    );
+  };
+
+  // Con reduce-motion el autoPlay ya está apagado: no hay nada que pausar.
+  const renderAutoPlayToggle = () => {
+    if (!autoPlay || !showAutoPlayToggle || motionReduced || total < 2) return null;
+    return (
+      <TouchableOpacity
+        testID={`${testID ?? 'slides'}-autoplay-toggle`}
+        style={[styles.autoPlayToggle, { backgroundColor: colors.black, opacity: 0.55 }]}
+        activeOpacity={0.7}
+        onPress={toggleAutoPlay}
+        accessibilityRole="button"
+        accessibilityLabel={autoPlayPaused ? 'Resume automatic slides' : 'Pause automatic slides'}
+        accessibilityState={{ selected: !autoPlayPaused }}
+      >
+        {autoPlayPaused ? (
+          <View style={[styles.playTriangle, { borderLeftColor: colors.white }]} />
+        ) : (
+          <>
+            <View style={[styles.pauseBar, { backgroundColor: colors.white }]} />
+            <View style={[styles.pauseBar, { backgroundColor: colors.white }]} />
+          </>
+        )}
+      </TouchableOpacity>
+    );
+  };
+
+  const renderIndicators = () => {
+    if (indicators === 'none' || total < 2) return null;
+    return (
+      <View
+        testID={`${testID ?? 'slides'}-indicators`}
+        style={[
+          isHorizontal ? styles.indicatorsRow : styles.indicatorsColumn,
+          isOverlay
+            ? isHorizontal
+              ? styles.indicatorsOverlayHorizontal
+              : styles.indicatorsOverlayVertical
+            : isHorizontal
+              ? styles.indicatorsOutsideHorizontal
+              : styles.indicatorsOutsideVertical,
+        ]}
+        pointerEvents="box-none"
+      >
+        {data.map((item, position) => (
+          <TouchableOpacity
+            key={`indicator-${keyExtractor(item, position)}`}
+            testID={`${testID ?? 'slides'}-indicator-${position}`}
+            style={styles.indicatorSlot}
+            activeOpacity={0.7}
+            onPress={() => goTo(position)}
+            accessibilityRole="button"
+            accessibilityLabel={`Slide ${position + 1} of ${total}`}
+            accessibilityState={{ selected: position === active }}
+          >
+            {renderIndicator(position)}
+          </TouchableOpacity>
+        ))}
+      </View>
+    );
+  };
+
+  const viewport = (
+    <View
+      testID={testID}
+      style={[styles.root, { height }, !isOverlay && !isHorizontal && styles.viewportInRow, isOverlay && style]}
+      onLayout={onLayout}
+    >
+      <ScrollView
+        ref={scrollRef}
+        testID={`${testID ?? 'slides'}-scroll`}
+        style={styles.viewport}
+        horizontal={isHorizontal}
+        pagingEnabled
+        scrollEnabled={swipeEnabled && total > 1}
+        showsHorizontalScrollIndicator={false}
+        showsVerticalScrollIndicator={false}
+        onMomentumScrollEnd={onMomentumScrollEnd}
+        onScrollBeginDrag={onScrollBeginDrag}
+        onScrollEndDrag={onScrollEndDrag}
+      >
+        {pageSize > 0 &&
+          pages.map(({ real, clone }) => {
+            const item = data[real] as T;
+            return (
+              // El hueco se reparte a los dos lados de cada página: así la
+              // separación entre dos slides es `spacing` entero y la página
+              // sigue midiendo exactamente lo que pagina el ScrollView.
+              <View
+                key={clone ? `slides-clone-${clone}` : keyExtractor(item, real)}
+                style={[
+                  { width: size.width, height: size.height },
+                  isHorizontal ? { paddingHorizontal: spacing / 2 } : { paddingVertical: spacing / 2 },
+                ]}
+              >
+                <View style={[styles.slide, slideStyle]}>
+                  {renderBackground(item, real)}
+                  <View style={styles.slideContent}>{renderItem(item, real)}</View>
+                </View>
+              </View>
+            );
+          })}
+      </ScrollView>
+      {renderAutoPlayToggle()}
+      {isOverlay && renderIndicators()}
+    </View>
+  );
+
+  if (isOverlay) return viewport;
+
+  return (
+    <View style={[isHorizontal ? styles.outsideHorizontal : styles.outsideVertical, style]}>
+      {viewport}
+      {renderIndicators()}
+    </View>
+  );
+}

package/src/organisms/Toast.tsx

@@ -12,10 +12,10 @@ export interface ToastProps {
   title: string;
   message?: string;
   variant?: ToastVariant;
-  /** Se dispara al tocar el toast (además de cerrarlo). */
+  /** Fires when the toast is tapped (in addition to closing it). */
   onPress?: () => void;
   onDismiss?: () => void;
-  /** Oculta la X de cerrar. El toast igual se auto-descarta por tiempo. */
+  /** Hides the close X. The toast still auto-dismisses by timeout. */
   hideCloseButton?: boolean;
   style?: StyleProp<ViewStyle>;
   testID?: string;

package/src/organisms/ToastProvider.tsx

@@ -54,9 +54,9 @@ export interface ToastProviderProps {
   children: React.ReactNode;
   /** @default 'top' */
   position?: 'top' | 'bottom';
-  /** Máximo de toasts simultáneos; los más viejos se descartan. @default 3 */
+  /** Maximum simultaneous toasts; the oldest ones are dropped. @default 3 */
   maxVisible?: number;
-  /** Duración por defecto en ms. @default 4000 */
+  /** Default duration in ms. @default 4000 */
   defaultDuration?: number;
 }
 

package/src/organisms/Wizard.tsx

@@ -13,28 +13,28 @@ export interface WizardStep extends StepItem {
 
 export interface WizardProps {
   steps: WizardStep[];
-  /** Paso actual (controlado). Si se omite, el Wizard maneja su propio estado. */
+  /** Current step (controlled). If omitted, the Wizard manages its own state. */
   current?: number;
   onStepChange?: (index: number) => void;
   onFinish?: () => void;
   /** @default 'horizontal' */
   orientation?: 'horizontal' | 'vertical';
   completedIndicator?: 'check' | 'number';
-  /** Permite volver a un paso ya completado tocándolo en el indicador. @default true */
+  /** Allows returning to an already-completed step by tapping it in the indicator. @default true */
   allowStepNavigation?: boolean;
   backLabel?: string;
   nextLabel?: string;
   finishLabel?: string;
   /**
-   * El contenido del paso scrollea cuando no entra. Ponelo en false sólo si
-   * un paso renderiza su propia lista virtualizada (anidar una
-   * VirtualizedList dentro de un ScrollView rompe la virtualización).
+   * The step content scrolls when it doesn't fit. Set to false only if
+   * a step renders its own virtualized list (nesting a
+   * VirtualizedList inside a ScrollView breaks virtualization).
    * @default true
    */
   scrollableContent?: boolean;
   /**
-   * El contenido del paso entra deslizándose en el sentido de la navegación.
-   * Sólo opacity y transform, así que la animación corre en el hilo nativo.
+   * The step content slides in following the navigation direction.
+   * Only opacity and transform, so the animation runs on the native thread.
    * @default true
    */
   animated?: boolean;

package/src/organisms/index.ts

@@ -30,3 +30,11 @@ export { NavigationBar } from './NavigationBar';
 export type { NavigationBarProps, NavigationBarItem } from './NavigationBar';
 export { ReorderableList } from './ReorderableList';
 export type { ReorderableListProps } from './ReorderableList';
+export { Slides } from './Slides';
+export type {
+  SlidesProps,
+  SlidesOrientation,
+  SlidesIndicators,
+  SlidesIndicatorPlacement,
+  SlideBackground,
+} from './Slides';