orn-ui 0.2.10 → 0.3.0

package/src/organisms/useSlides.ts

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState, type ComponentRef } from 'react';
 import type { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent, ScrollView } from 'react-native';
 import { useReduceMotion } from '../atoms/Transition';
 
@@ -10,13 +10,13 @@ export interface UseSlidesOptions {
   loop: boolean;
   autoPlay: boolean;
   interval: number;
-  /** Índice controlado; sin él manda el estado interno. */
+  /** Controlled index; without it the internal state rules. */
   index?: number;
   defaultIndex: number;
   onIndexChange?: (index: number) => void;
 }
 
-/** Una página del scroll. Los clones del modo infinito repiten el `real` de un vecino. */
+/** A page of the scroll. The infinite mode's clones repeat a neighbor's `real`. */
 export interface SlidesPage {
   real: number;
   clone: 'head' | 'tail' | null;
@@ -28,18 +28,18 @@ export interface UseSlidesResult {
   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ó. */
+  /** Length of a page along the scroll axis. At 0 it hasn't been measured yet. */
   pageSize: number;
-  scrollRef: React.RefObject<ScrollView | null>;
+  scrollRef: React.RefObject<ComponentRef<typeof ScrollView> | null>;
   autoPlayPaused: boolean;
-  /** El sistema pidió reducir movimiento: no hay autoPlay ni transiciones. */
+  /** The system asked to reduce motion: no autoPlay or transitions. */
   motionReduced: boolean;
   goTo: (index: number) => void;
   toggleAutoPlay: () => void;
   onLayout: (event: LayoutChangeEvent) => void;
   onMomentumScrollEnd: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
-  onScrollBeginDrag: () => void;
-  onScrollEndDrag: () => void;
+  onScrollBeginDrag: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
+  onScrollEndDrag: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
 }
 
 export function clampIndex(value: number, total: number): number {
@@ -51,13 +51,16 @@ export function clampIndex(value: number, total: number): number {
 
 /**
  * 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.
+ * Everything in `Slides` that isn't visible: which page is framed, when to
+ * move the scroll, how the infinite mode's clones map to real indexes, and the
+ * autoplay clock.
  *
- * 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`.
+ * It works only with indexes, never with the items: that way it doesn't need
+ * the component's generic `T`, and the UI resolves `pages[i].real` against its own `data`.
  */
+/** Points a finger has to move the slides for the drag to count as a swipe. */
+const DRAG_SLOP = 10;
+
 export function useSlides({
   total,
   orientation,
@@ -70,8 +73,8 @@ export function useSlides({
 }: 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.
+  // A single element has nowhere to cycle to: it would be swipeable between
+  // three copies of the same thing.
   const isLoop = loop && total > 1;
 
   const [uncontrolled, setUncontrolled] = useState(() => clampIndex(defaultIndex, total));
@@ -83,12 +86,19 @@ export function useSlides({
   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 scrollRef = useRef<ComponentRef<typeof ScrollView>>(null);
+  /** The page actually visible (index within `pages`, clones included). */
   const offsetPageRef = useRef(isLoop ? 1 : 0);
   const didInitRef = useRef(false);
   const lastPageSizeRef = useRef(0);
   const draggingRef = useRef(false);
+  /**
+   * Page an animated `scrollTo` was sent to and hasn't reached yet. On iOS a
+   * touch (tapping another indicator) stops that animation midway: the
+   * scroll then ends on the wrong page, and committing it undid the tap.
+   */
+  const pendingPageRef = useRef<number | null>(null);
+  const dragStartRef = useRef(0);
 
   const pages = useMemo<SlidesPage[]>(() => {
     const real = Array.from({ length: total }, (_, i) => ({ real: i, clone: null }));
@@ -118,19 +128,20 @@ export function useSlides({
     [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ó.
+  // Only acts when the index and the visible page disagree: a change that
+  // came from the gesture itself doesn't fire a second scroll on top of the one that stopped.
   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ó.
+    // Neither the first positioning nor the rearrangement on rotation is a
+    // slide change: animating them would be a slide nobody asked for.
     const animated = didInitRef.current && !resized;
     didInitRef.current = true;
     lastPageSizeRef.current = pageSize;
     offsetPageRef.current = target;
+    pendingPageRef.current = animated ? target : null;
     scrollToPage(target, animated);
   }, [active, isLoop, pageSize, scrollToPage, total]);
 
@@ -145,6 +156,16 @@ export function useSlides({
       if (pageSize === 0) return;
       const { contentOffset } = event.nativeEvent;
       const page = Math.round((isHorizontal ? contentOffset.x : contentOffset.y) / pageSize);
+      // A scrollTo still on its way: if it stopped short (a touch interrupted
+      // it), finish the trip instead of committing where it stopped.
+      const pending = pendingPageRef.current;
+      if (pending !== null) {
+        if (page !== pending) {
+          scrollToPage(pending, true);
+          return;
+        }
+        pendingPageRef.current = null;
+      }
 
       if (isLoop) {
         if (page === 0) {
@@ -170,15 +191,28 @@ export function useSlides({
     [goTo, isHorizontal, isLoop, pageSize, scrollToPage, total]
   );
 
-  const onScrollBeginDrag = useCallback(() => {
-    draggingRef.current = true;
-  }, []);
+  const onScrollBeginDrag = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      draggingRef.current = true;
+      const { contentOffset } = event.nativeEvent;
+      dragStartRef.current = isHorizontal ? contentOffset.x : contentOffset.y;
+    },
+    [isHorizontal]
+  );
 
-  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 onScrollEndDrag = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      // A short drag can be released without momentum and not emit
+      // momentumScrollEnd: without this autoPlay would stay paused forever.
+      draggingRef.current = false;
+      // A finger that really moved the slides takes over from a pending
+      // scrollTo; a tap (no movement) doesn't.
+      const { contentOffset } = event.nativeEvent;
+      const moved = Math.abs((isHorizontal ? contentOffset.x : contentOffset.y) - dragStartRef.current);
+      if (moved > DRAG_SLOP) pendingPageRef.current = null;
+    },
+    [isHorizontal]
+  );
 
   const toggleAutoPlay = useCallback(() => setAutoPlayPaused((paused) => !paused), []);
 
@@ -192,9 +226,10 @@ export function useSlides({
         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.
+      // Last one in infinite mode: advances to the clone of the first instead
+      // of rewinding; momentumScrollEnd completes the jump to the original.
       offsetPageRef.current = total + 1;
+      pendingPageRef.current = total + 1;
       scrollToPage(total + 1, true);
     }, interval);
     return () => clearInterval(timer);

package/src/safe-area/SafeAreaUIProvider.tsx

@@ -1,72 +1,11 @@
-import React, { useEffect, useState } from 'react';
-import type { ViewStyle } from 'react-native';
-import { SafeAreaProvider, useSafeAreaInsets } from 'react-native-safe-area-context';
-import {
-  UIProvider,
-  useInsets,
-  type ModalSafeAreaBoundaryProps,
-  type UIProviderProps,
-} from '../theme/UIProvider';
-import type { EdgeInsets } from '../theme/insets';
+import { UIProvider, type UIProviderProps } from '../theme/UIProvider';
 
-export interface SafeAreaUIProviderProps extends Omit<UIProviderProps, 'insets'> {
-  insets?: UIProviderProps['insets'];
-  mountSafeAreaProvider?: boolean;
-}
+/**
+ * @deprecated Use `UIProvider` from 'orn-ui': it now measures the safe area
+ * insets itself (react-native-safe-area-context is a required peer). This
+ * alias stays for one minor version so existing imports keep working.
+ */
+export type SafeAreaUIProviderProps = UIProviderProps;
 
-const probeStyle: ViewStyle = { position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 };
-
-function sameInsets(a: EdgeInsets, b: EdgeInsets) {
-  return a.top === b.top && a.right === b.right && a.bottom === b.bottom && a.left === b.left;
-}
-
-function InsetsProbe({ onMeasure }: { onMeasure: (insets: EdgeInsets) => void }) {
-  const insets = useSafeAreaInsets();
-  useEffect(() => {
-    onMeasure(insets);
-  }, [insets, onMeasure]);
-  return null;
-}
-
-function RemeasuringModalSafeAreaBoundary({ children }: ModalSafeAreaBoundaryProps) {
-  const ambient = useInsets();
-  const [measured, setMeasured] = useState<EdgeInsets | null>(null);
-  const onMeasure = React.useCallback(
-    (next: EdgeInsets) => setMeasured((prev) => (prev && sameInsets(prev, next) ? prev : next)),
-    []
-  );
-
-  return (
-    <>
-      <SafeAreaProvider style={probeStyle} pointerEvents="none">
-        <InsetsProbe onMeasure={onMeasure} />
-      </SafeAreaProvider>
-      {children(measured ?? ambient)}
-    </>
-  );
-}
-
-function Measured({ insets: override, children, ...rest }: SafeAreaUIProviderProps) {
-  const measured = useSafeAreaInsets();
-  return (
-    <UIProvider
-      insets={override ?? measured}
-      ModalSafeAreaBoundary={RemeasuringModalSafeAreaBoundary}
-      {...rest}
-    >
-      {children}
-    </UIProvider>
-  );
-}
-
-export function SafeAreaUIProvider({
-  mountSafeAreaProvider = true,
-  ...props
-}: SafeAreaUIProviderProps) {
-  if (!mountSafeAreaProvider) return <Measured {...props} />;
-  return (
-    <SafeAreaProvider>
-      <Measured {...props} />
-    </SafeAreaProvider>
-  );
-}
+/** @deprecated Use `UIProvider` from 'orn-ui' — same component. */
+export const SafeAreaUIProvider = UIProvider;

package/src/safe-area/index.ts

@@ -1,2 +1,3 @@
+// Deprecated subpath: UIProvider measures the insets itself now.
 export { SafeAreaUIProvider } from './SafeAreaUIProvider';
 export type { SafeAreaUIProviderProps } from './SafeAreaUIProvider';

package/src/theme/KeyboardAvoidance.tsx

@@ -0,0 +1,216 @@
+import React, { createContext, useContext, useEffect, useMemo, useRef, type ComponentRef } from 'react';
+import {
+  Animated,
+  Easing,
+  Keyboard,
+  Platform,
+  StyleSheet,
+  View,
+  type KeyboardEvent,
+} from 'react-native';
+import { useReduceMotion } from './useReduceMotion';
+
+/** A focused field the host has to keep in view. */
+export interface KeyboardField {
+  /** The field's box in window coordinates (label, field and error included). */
+  measure: () => Promise<{ y: number; height: number } | null>;
+}
+
+export interface KeyboardHost {
+  focus: (field: KeyboardField) => void;
+  blur: (field: KeyboardField) => void;
+}
+
+const KeyboardHostContext = createContext<KeyboardHost | null>(null);
+
+/** The active host, or null if a container already handles the keyboard (or it is off). */
+export function useKeyboardHost(): KeyboardHost | null {
+  return useContext(KeyboardHostContext);
+}
+
+/**
+ * For containers that already keep the focused field visible on their own:
+ * a Modal or BottomSheet (its own native window, which the root's shift
+ * doesn't move) or a ScrollView with `automaticallyAdjustKeyboardInsets`.
+ * Inside, Inputs ask nothing of the host and the keyboard isn't compensated
+ * twice.
+ */
+export function KeyboardHandled({ children }: { children: React.ReactNode }) {
+  return <KeyboardHostContext.Provider value={null}>{children}</KeyboardHostContext.Provider>;
+}
+
+/** Duration when the keyboard event doesn't carry one (Android). */
+const FALLBACK_DURATION = 250;
+
+/**
+ * Vertical shift (≤ 0) so the whole field sits above the keyboard, with
+ * `margin` of room, without its top edge going past `topLimit`.
+ * `fieldY` is the position measured with the `current` shift applied.
+ * If the field is already visible, it moves back toward 0: it never rises more than needed.
+ */
+export function computeKeyboardOffset({
+  fieldY,
+  fieldHeight,
+  keyboardTop,
+  current,
+  margin,
+  topLimit,
+}: {
+  fieldY: number;
+  fieldHeight: number;
+  keyboardTop: number;
+  current: number;
+  margin: number;
+  topLimit: number;
+}): number {
+  const base = fieldY - current;
+  let target = Math.min(0, keyboardTop - margin - (base + fieldHeight));
+  // A field taller than the available gap: seeing where you type (its top
+  // part) takes priority over its error.
+  target = Math.max(target, topLimit - base);
+  return Math.min(0, target);
+}
+
+/**
+ * An area that shifts so the focused Input inside it sits above the
+ * keyboard (transform on the native thread; it returns to 0 on close). It is
+ * Android's `adjustPan`, the same on both platforms.
+ *
+ * - The root UIProvider mounts one around the whole app: the fallback, so
+ *   an Input is visible even when it isn't inside a Screen.
+ * - Screen mounts another around its content, with `clip`: only the content
+ *   moves and the header (`header` prop) and the tab bar stay still, as in a
+ *   native app. The Input registers with the nearest area, so inside a
+ *   Screen the root doesn't move.
+ *
+ * With `clip`, whatever rises is clipped at the area's top edge and the field
+ * never goes above that edge (it stays under the header).
+ */
+export function KeyboardPanArea({
+  margin,
+  topLimit,
+  clip = false,
+  children,
+}: {
+  margin: number;
+  /** Top limit in window coordinates. With `clip`, the area's edge is used if it is lower. */
+  topLimit: number;
+  clip?: boolean;
+  children: React.ReactNode;
+}) {
+  const areaRef = useRef<ComponentRef<typeof View>>(null);
+  const pan = useRef(new Animated.Value(0)).current;
+  const offset = useRef(0);
+  const field = useRef<KeyboardField | null>(null);
+  const keyboardTop = useRef<number | null>(null);
+  const reduceMotion = useReduceMotion();
+  const config = useRef({ margin, topLimit, reduceMotion, clip });
+  config.current = { margin, topLimit, reduceMotion, clip };
+
+  const host = useMemo<KeyboardHost>(() => {
+    const animateTo = (to: number, duration: number) => {
+      if (to === offset.current) return;
+      offset.current = to;
+      Animated.timing(pan, {
+        toValue: to,
+        duration: config.current.reduceMotion ? 0 : duration,
+        easing: Easing.out(Easing.cubic),
+        useNativeDriver: true,
+      }).start();
+    };
+
+    const adjust = async (duration: number) => {
+      const current = field.current;
+      const top = keyboardTop.current;
+      if (!current || top === null) return;
+      const box = await current.measure();
+      // While measuring, focus may have moved to another field or the keyboard closed.
+      if (!box || field.current !== current || keyboardTop.current === null) return;
+      let limit = config.current.topLimit;
+      if (config.current.clip) {
+        const areaTop = await measureTop(areaRef.current);
+        if (areaTop !== null) limit = Math.max(limit, areaTop);
+      }
+      animateTo(
+        computeKeyboardOffset({
+          fieldY: box.y,
+          fieldHeight: box.height,
+          keyboardTop: keyboardTop.current,
+          current: offset.current,
+          margin: config.current.margin,
+          topLimit: limit,
+        }),
+        duration
+      );
+    };
+
+    return {
+      focus(next) {
+        field.current = next;
+        // With the keyboard already open (moving from one field to another) it readjusts right away.
+        if (keyboardTop.current !== null) void adjust(FALLBACK_DURATION);
+      },
+      blur(prev) {
+        if (field.current === prev) field.current = null;
+      },
+      // Internal use by the listeners below.
+      _show(e: KeyboardEvent | undefined) {
+        if (!e?.endCoordinates) return;
+        keyboardTop.current = e.endCoordinates.screenY;
+        const duration = e.duration || FALLBACK_DURATION;
+        // Android emits didShow after resizing the window: measure on the
+        // next frame, with the layout already settled.
+        if (Platform.OS === 'android') requestAnimationFrame(() => void adjust(duration));
+        else void adjust(duration);
+      },
+      _hide(e: KeyboardEvent | undefined) {
+        keyboardTop.current = null;
+        animateTo(0, e?.duration || FALLBACK_DURATION);
+      },
+    } as KeyboardHost & { _show: (e: KeyboardEvent) => void; _hide: (e?: KeyboardEvent) => void };
+  }, [pan]);
+
+  useEffect(() => {
+    const h = host as KeyboardHost & { _show: (e: KeyboardEvent) => void; _hide: (e?: KeyboardEvent) => void };
+    // iOS notifies before animating (will*): the shift follows the keyboard.
+    // Android only has did*.
+    const subs =
+      Platform.OS === 'ios'
+        ? [
+            Keyboard.addListener('keyboardWillShow', h._show),
+            Keyboard.addListener('keyboardWillChangeFrame', h._show),
+            Keyboard.addListener('keyboardWillHide', h._hide),
+          ]
+        : [Keyboard.addListener('keyboardDidShow', h._show), Keyboard.addListener('keyboardDidHide', h._hide)];
+    return () => subs.forEach((s) => s.remove());
+  }, [host]);
+
+  const moving = <Animated.View style={[styles.fill, { transform: [{ translateY: pan }] }]}>{children}</Animated.View>;
+  return (
+    <KeyboardHostContext.Provider value={host}>
+      {clip ? (
+        <View ref={areaRef} style={[styles.fill, styles.clip]} collapsable={false}>
+          {moving}
+        </View>
+      ) : (
+        moving
+      )}
+    </KeyboardHostContext.Provider>
+  );
+}
+
+/** If the measurement never comes back (node unmounted), carry on without that limit. */
+const MEASURE_TIMEOUT_MS = 100;
+
+function measureTop(node: ComponentRef<typeof View> | null): Promise<number | null> {
+  return new Promise((resolve) => {
+    if (!node) return resolve(null);
+    const timer = setTimeout(() => resolve(null), MEASURE_TIMEOUT_MS);
+    node.measureInWindow((_x, y) => {
+      clearTimeout(timer);
+      resolve(y);
+    });
+  });
+}
+
+const styles = StyleSheet.create({ fill: { flex: 1 }, clip: { overflow: 'hidden' } });