orn-ui 0.2.7 → 0.2.8

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/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';

package/src/organisms/useSlides.ts

@@ -0,0 +1,220 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent, ScrollView } from 'react-native';
+import { useReduceMotion } from '../atoms/Transition';
+
+export type SlidesOrientation = 'horizontal' | 'vertical';
+
+export interface UseSlidesOptions {
+  total: number;
+  orientation: SlidesOrientation;
+  loop: boolean;
+  autoPlay: boolean;
+  interval: number;
+  /** Índice controlado; sin él manda el estado interno. */
+  index?: number;
+  defaultIndex: number;
+  onIndexChange?: (index: number) => void;
+}
+
+/** Una página del scroll. Los clones del modo infinito repiten el `real` de un vecino. */
+export interface SlidesPage {
+  real: number;
+  clone: 'head' | 'tail' | null;
+}
+
+export interface UseSlidesResult {
+  active: number;
+  pages: SlidesPage[];
+  isHorizontal: boolean;
+  isLoop: boolean;
+  size: { width: number; height: number };
+  /** Largo de una página sobre el eje del scroll. En 0 todavía no se midió. */
+  pageSize: number;
+  scrollRef: React.RefObject<ScrollView | null>;
+  autoPlayPaused: boolean;
+  /** El sistema pidió reducir movimiento: no hay autoPlay ni transiciones. */
+  motionReduced: boolean;
+  goTo: (index: number) => void;
+  toggleAutoPlay: () => void;
+  onLayout: (event: LayoutChangeEvent) => void;
+  onMomentumScrollEnd: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onScrollBeginDrag: () => void;
+  onScrollEndDrag: () => void;
+}
+
+export function clampIndex(value: number, total: number): number {
+  if (total === 0) return 0;
+  if (value < 0) return 0;
+  if (value > total - 1) return total - 1;
+  return value;
+}
+
+/**
+ * useSlides
+ * Todo lo que en `Slides` no se ve: qué página está encuadrada, cuándo mover el
+ * scroll, cómo se mapean los clones del modo infinito a índices reales, y el
+ * reloj del avance automático.
+ *
+ * Trabaja sólo con índices, nunca con los ítems: así no necesita el genérico
+ * `T` del componente, y el UI resuelve `pages[i].real` contra su propio `data`.
+ */
+export function useSlides({
+  total,
+  orientation,
+  loop,
+  autoPlay,
+  interval,
+  index,
+  defaultIndex,
+  onIndexChange,
+}: UseSlidesOptions): UseSlidesResult {
+  const motionReduced = useReduceMotion();
+  const isHorizontal = orientation === 'horizontal';
+  // Un solo elemento no tiene a dónde ciclar: quedaría deslizable entre tres
+  // copias de lo mismo.
+  const isLoop = loop && total > 1;
+
+  const [uncontrolled, setUncontrolled] = useState(() => clampIndex(defaultIndex, total));
+  const active = clampIndex(index ?? uncontrolled, total);
+  const activeRef = useRef(active);
+  activeRef.current = active;
+
+  const [autoPlayPaused, setAutoPlayPaused] = useState(false);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  const pageSize = isHorizontal ? size.width : size.height;
+
+  const scrollRef = useRef<ScrollView>(null);
+  /** Página realmente visible (índice dentro de `pages`, clones incluidos). */
+  const offsetPageRef = useRef(isLoop ? 1 : 0);
+  const didInitRef = useRef(false);
+  const lastPageSizeRef = useRef(0);
+  const draggingRef = useRef(false);
+
+  const pages = useMemo<SlidesPage[]>(() => {
+    const real = Array.from({ length: total }, (_, i) => ({ real: i, clone: null }));
+    if (!isLoop) return real;
+    return [{ real: total - 1, clone: 'head' }, ...real, { real: 0, clone: 'tail' }];
+  }, [isLoop, total]);
+
+  const scrollToPage = useCallback(
+    (page: number, animated: boolean) => {
+      const offset = page * pageSize;
+      scrollRef.current?.scrollTo({
+        x: isHorizontal ? offset : 0,
+        y: isHorizontal ? 0 : offset,
+        animated,
+      });
+    },
+    [isHorizontal, pageSize]
+  );
+
+  const goTo = useCallback(
+    (next: number) => {
+      if (next === activeRef.current) return;
+      activeRef.current = next;
+      if (index == null) setUncontrolled(next);
+      onIndexChange?.(next);
+    },
+    [index, onIndexChange]
+  );
+
+  // Sólo actúa cuando el índice y la página visible discrepan: un cambio que
+  // vino del propio gesto no dispara un segundo scroll encima del que frenó.
+  useEffect(() => {
+    if (pageSize === 0 || total === 0) return;
+    const target = isLoop ? active + 1 : active;
+    const resized = lastPageSizeRef.current !== pageSize;
+    if (offsetPageRef.current === target && didInitRef.current && !resized) return;
+    // Ni el primer posicionamiento ni el reacomodo por rotación son un cambio
+    // de slide: animarlos sería un deslizamiento que nadie pidió.
+    const animated = didInitRef.current && !resized;
+    didInitRef.current = true;
+    lastPageSizeRef.current = pageSize;
+    offsetPageRef.current = target;
+    scrollToPage(target, animated);
+  }, [active, isLoop, pageSize, scrollToPage, total]);
+
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    const { width, height } = event.nativeEvent.layout;
+    setSize((prev) => (prev.width === width && prev.height === height ? prev : { width, height }));
+  }, []);
+
+  const onMomentumScrollEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      draggingRef.current = false;
+      if (pageSize === 0) return;
+      const { contentOffset } = event.nativeEvent;
+      const page = Math.round((isHorizontal ? contentOffset.x : contentOffset.y) / pageSize);
+
+      if (isLoop) {
+        if (page === 0) {
+          offsetPageRef.current = total;
+          scrollToPage(total, false);
+          goTo(total - 1);
+          return;
+        }
+        if (page === total + 1) {
+          offsetPageRef.current = 1;
+          scrollToPage(1, false);
+          goTo(0);
+          return;
+        }
+        offsetPageRef.current = page;
+        goTo(page - 1);
+        return;
+      }
+
+      offsetPageRef.current = page;
+      goTo(clampIndex(page, total));
+    },
+    [goTo, isHorizontal, isLoop, pageSize, scrollToPage, total]
+  );
+
+  const onScrollBeginDrag = useCallback(() => {
+    draggingRef.current = true;
+  }, []);
+
+  const onScrollEndDrag = useCallback(() => {
+    // Un arrastre corto puede soltarse sin inercia y no emitir
+    // momentumScrollEnd: sin esto el autoPlay quedaría pausado para siempre.
+    draggingRef.current = false;
+  }, []);
+
+  const toggleAutoPlay = useCallback(() => setAutoPlayPaused((paused) => !paused), []);
+
+  useEffect(() => {
+    if (!autoPlay || autoPlayPaused || motionReduced || total < 2 || pageSize === 0) return;
+    const timer = setInterval(() => {
+      if (draggingRef.current) return;
+      const from = activeRef.current;
+      if (from < total - 1) {
+        goTo(from + 1);
+        return;
+      }
+      if (!isLoop) return;
+      // Última en modo infinito: avanza al clon de la primera en vez de
+      // rebobinar; el salto al original lo cierra momentumScrollEnd.
+      offsetPageRef.current = total + 1;
+      scrollToPage(total + 1, true);
+    }, interval);
+    return () => clearInterval(timer);
+  }, [autoPlay, autoPlayPaused, goTo, interval, isLoop, motionReduced, pageSize, scrollToPage, total]);
+
+  return {
+    active,
+    pages,
+    isHorizontal,
+    isLoop,
+    size,
+    pageSize,
+    scrollRef,
+    autoPlayPaused,
+    motionReduced,
+    goTo,
+    toggleAutoPlay,
+    onLayout,
+    onMomentumScrollEnd,
+    onScrollBeginDrag,
+    onScrollEndDrag,
+  };
+}