@vvedantb/native-ui 0.13.0 → 0.17.1

package/src/primitives/keyboard-controller.tsx

@@ -0,0 +1,106 @@
+import type { ComponentProps, ReactNode } from "react";
+import { Platform } from "react-native";
+import {
+  KeyboardAvoidingView,
+  KeyboardChatScrollView,
+  KeyboardGestureArea,
+  KeyboardStickyView,
+  useKeyboardHandler,
+} from "react-native-keyboard-controller";
+import { runOnJS } from "react-native-reanimated";
+import { COMPOSER_INPUT_ID, KeyboardPartsContext, type KeyboardParts } from "./keyboard-parts";
+
+// The keyboard parts on `react-native-keyboard-controller`: the keyboard's
+// real position, frame by frame, on the UI thread. No timing of our own, so
+// the composer can neither lag nor lead the keyboard; with Reduce Motion the
+// system shortens the keyboard's own motion and the parts follow it.
+
+/**
+ * A drag moves the keyboard on iOS (`keyboardDismissMode="interactive"`) and
+ * on Android 11+ (API 30, `WindowInsetsAnimation`). Android 10 and below has
+ * no interactive keyboard: `KeyboardGestureArea` then only renders its
+ * children, and the transcript keeps `on-drag`.
+ */
+const INTERACTIVE = Platform.OS === "ios" || (Platform.OS === "android" && Number(Platform.Version) >= 30);
+
+function AvoidingView(props: ComponentProps<KeyboardParts["AvoidingView"]>) {
+  return <KeyboardAvoidingView {...props} />;
+}
+
+function StickyView({ bottomOffset, ...props }: ComponentProps<KeyboardParts["StickyView"]>) {
+  return <KeyboardStickyView {...props} offset={{ opened: bottomOffset }} />;
+}
+
+/**
+ * `always`: the content rises with the keyboard wherever the reader is, so
+ * what sat on the composer stays there (the newest message, at the end).
+ * Inverted, the keyboard's space is the content's top inset, the visual
+ * bottom: iOS scrolls below offset 0 into it, so the end moves there; Android
+ * moves the content down by it instead, so offset 0 stays the end. While the
+ * keyboard moves, the list scrolls with it, through offsets that are not the
+ * end on either platform.
+ */
+function ChatScrollView({
+  bottomOffset,
+  inverted = false,
+  onInsetChange,
+  onKeyboardMove,
+  ...props
+}: ComponentProps<KeyboardParts["ChatScrollView"]>) {
+  useKeyboardHandler(
+    {
+      onStart: () => {
+        "worklet";
+        runOnJS(onKeyboardMove)(true);
+      },
+      onEnd: () => {
+        "worklet";
+        runOnJS(onKeyboardMove)(false);
+      },
+    },
+    [onKeyboardMove],
+  );
+  return (
+    <KeyboardChatScrollView
+      {...props}
+      inverted={inverted}
+      offset={bottomOffset}
+      keyboardLiftBehavior="always"
+      onContentInsetChange={(insets) =>
+        onInsetChange(inverted ? (Platform.OS === "ios" ? insets.top : 0) : insets.bottom)
+      }
+    />
+  );
+}
+
+/**
+ * `ios`: the keyboard follows once the finger reaches the composer, then 1:1,
+ * and a release carries the finger's velocity, on both platforms.
+ */
+function GestureArea({ offset, style, children }: ComponentProps<KeyboardParts["GestureArea"]>) {
+  return (
+    <KeyboardGestureArea interpolator="ios" offset={offset} textInputNativeID={COMPOSER_INPUT_ID} style={style}>
+      {children}
+    </KeyboardGestureArea>
+  );
+}
+
+const PARTS: KeyboardParts = {
+  AvoidingView,
+  StickyView,
+  ChatScrollView,
+  GestureArea,
+  interactive: INTERACTIVE,
+};
+
+/**
+ * Runs the kit's keyboard handling on `react-native-keyboard-controller`:
+ * the chat composer (`ConversationDock`), its scroll button and the
+ * transcript (`ConversationList`) follow the keyboard frame by frame, a drag
+ * on the transcript moves the keyboard with the finger, and `PromptInput`,
+ * `ChatThread`, the overlays and `KeyboardAvoidingView` pad frame by frame.
+ * Put it inside the app's `KeyboardProvider`.
+ */
+export function KeyboardControllerProvider({ children }: { children: ReactNode }) {
+  return <KeyboardPartsContext.Provider value={PARTS}>{children}</KeyboardPartsContext.Provider>;
+}

package/src/primitives/keyboard-parts.tsx

@@ -0,0 +1,104 @@
+import { createContext, useContext, type ComponentType, type ReactNode } from "react";
+import {
+  KeyboardAvoidingView as NativeKeyboardAvoidingView,
+  type ScrollViewProps,
+  type StyleProp,
+  type ViewProps,
+  type ViewStyle,
+} from "react-native";
+
+/**
+ * The `react-native-keyboard-controller` build of the keyboard parts, from
+ * `@vvedantb/native-ui/keyboard-controller`. They follow the keyboard frame
+ * by frame on the UI thread, and a drag on the chat transcript moves the
+ * keyboard with the finger. Without them (the peer is optional) the kit keeps
+ * React Native's `KeyboardAvoidingView`. A context, so only that entry imports
+ * the peer and an app without it bundles as before.
+ */
+export type KeyboardParts = {
+  /** A `KeyboardAvoidingView` that pads frame by frame with the keyboard. */
+  AvoidingView: ComponentType<KeyboardAvoidingViewProps>;
+  /**
+   * Moves with the keyboard (`translateY`), less `bottomOffset` while it is
+   * open: the bottom inset the content pads, which the keyboard covers.
+   */
+  StickyView: ComponentType<ViewProps & { bottomOffset: number }>;
+  /**
+   * The chat transcript's scroll view (a `FlatList` `renderScrollComponent`).
+   * Its content gains the keyboard height less `bottomOffset` at the end (at
+   * its start when `inverted`, the visual bottom either way), and moves up
+   * with the keyboard, so the newest message stays in view. `onInsetChange`
+   * gets that extra space as the scroll offset sees it, which `onScroll` does
+   * not report: past the content's end, or when `inverted` before offset 0.
+   * `onKeyboardMove` is true from the start to the end of each keyboard
+   * move, while the keyboard, not the reader, scrolls the list.
+   */
+  ChatScrollView: ComponentType<
+    ScrollViewProps & {
+      bottomOffset: number;
+      inverted?: boolean;
+      onInsetChange: (inset: number) => void;
+      onKeyboardMove: (moving: boolean) => void;
+    }
+  >;
+  /**
+   * Around the transcript: a drag that reaches `offset` above the keyboard
+   * (the composer's top) moves the keyboard with the finger.
+   */
+  GestureArea: ComponentType<{ offset: number; style?: StyleProp<ViewStyle>; children: ReactNode }>;
+  /**
+   * Whether a drag on the transcript moves the keyboard (iOS, Android 11+).
+   * False on Android 10 and below: there a drag lowers it at once.
+   */
+  interactive: boolean;
+};
+
+export const KeyboardPartsContext = createContext<KeyboardParts | null>(null);
+
+/**
+ * True inside a part that already keeps its content clear of the keyboard
+ * (`ConversationDock` with the keyboard-controller parts, `ChatThread`): the
+ * chat parts in it add no lift of their own, so nothing lifts twice.
+ */
+export const KeyboardLiftContext = createContext(false);
+
+/**
+ * The keyboard-controller parts for a chat part that follows the keyboard
+ * itself, or `null`: without `KeyboardControllerProvider`, or inside a part
+ * that already lifts it (`KeyboardLiftContext`).
+ */
+export function useKeyboardParts(): KeyboardParts | null {
+  const parts = useContext(KeyboardPartsContext);
+  const lifted = useContext(KeyboardLiftContext);
+  return lifted ? null : parts;
+}
+
+/**
+ * The `nativeID` of the `PromptInput` field. On iOS the transcript's gesture
+ * area keeps its `offset` (the composer above the keyboard) only for the
+ * focused field with this id.
+ */
+export const COMPOSER_INPUT_ID = "native-ui-composer";
+
+export type KeyboardAvoidingViewProps = {
+  /** Default `padding`, on iOS and Android: Android `height` does nothing edge-to-edge. */
+  behavior?: "padding" | "height" | "position";
+  /** Height of anything above the view's top, such as a navigation header. Default 0. */
+  keyboardVerticalOffset?: number;
+  enabled?: boolean;
+  /** A style, not a class: the keyboard-controller view takes no NativeWind `className`. */
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  children?: ReactNode;
+};
+
+/**
+ * React Native's `KeyboardAvoidingView`, or with
+ * `@vvedantb/native-ui/keyboard-controller` the keyboard-controller one, which
+ * pads frame by frame with the keyboard instead of in one step at its end.
+ */
+export function KeyboardAvoidingView({ behavior = "padding", ...props }: KeyboardAvoidingViewProps) {
+  const parts = useContext(KeyboardPartsContext);
+  const Avoiding = parts?.AvoidingView ?? NativeKeyboardAvoidingView;
+  return <Avoiding behavior={behavior} {...props} />;
+}

package/src/primitives/overlay.tsx

@@ -1,22 +1,34 @@
 import * as Slot from "@rn-primitives/slot";
 import {
   createContext,
+  Fragment,
   useContext,
+  useEffect,
+  useState,
   type ComponentPropsWithoutRef,
   type ReactNode,
 } from "react";
 import {
-  KeyboardAvoidingView,
   Modal,
   Pressable,
   StyleSheet,
   View,
   type GestureResponderEvent,
 } from "react-native";
+import Animated from "react-native-reanimated";
 import { useSafeAreaInsets } from "react-native-safe-area-context";
 import { palette } from "../palette";
+import { KeyboardAvoidingView, KeyboardLiftContext } from "./keyboard-parts";
 import { useReduceMotion } from "../useReduceMotion";
 import { useScheme } from "../useScheme";
+import {
+  SheetDragProvider,
+  SheetGestureContext,
+  slideSheetIn,
+  slideSheetOut,
+  useSheetBackdropStyle,
+  useSheetDragState,
+} from "./sheet-drag";
 import { useControllableState } from "./use-controllable-state";
 
 type OverlayContextValue = {
@@ -98,77 +110,153 @@ export function OverlayClose(props: OverlayPressableProps & { part: string }) {
 }
 
 /**
- * RN `Modal` with a tinted backdrop, safe-area padding and keyboard avoidance.
+ * RN `Modal` with a tinted backdrop, safe-area padding and keyboard avoidance
+ * (`KeyboardAvoidingView`: frame by frame with `KeyboardControllerProvider`).
  * `placement="center"` centres the child (dialogs) inside the insets on every
- * side; `"bottom"` pins it to the bottom edge (sheets), which pad their own
- * bottom inset. The backdrop closes the overlay only when `dismissible`;
- * Android back and the VoiceOver escape gesture always close it, as Escape
- * does on the web. With Reduce Motion on, the fade is off.
+ * side, and the `Modal` fades in and out. `"bottom"` pins it to the bottom
+ * edge (sheets), which pad their own bottom inset: the sheet slides up on
+ * open and back down on close, however it closes, and may be dragged down to
+ * close (`SheetDragView`); the backdrop fades with the sheet's position. The
+ * `Modal` stays up until the sheet is out of sight. The backdrop closes the
+ * overlay only when `dismissible`; Android back and the VoiceOver escape
+ * gesture always close it, as Escape does on the web. With Reduce Motion on,
+ * overlays appear and leave in place. With the Gesture Handler parts
+ * (`GestureHandlerProvider`), the content sits in its own root view: on
+ * Android a `Modal` is a separate root, and without one there every gesture
+ * in it silently does nothing.
  */
 export function OverlayModal({
   part,
   placement,
   dismissible,
+  onShow,
   children,
 }: {
   part: string;
   placement: "center" | "bottom";
   dismissible: boolean;
+  /** Once the overlay is on screen: where to focus a field (see `DialogContent`'s `onShow`). */
+  onShow?: () => void;
   children: ReactNode;
 }) {
   const { open, setOpen } = useOverlay(part);
-  const scheme = useScheme();
-  const insets = useSafeAreaInsets();
   const reduceMotion = useReduceMotion();
+  const slides = placement === "bottom" && !reduceMotion;
+  // Up while open, and after a close until a sliding sheet is out of sight.
+  const [shown, setShown] = useState(open);
+  if (open && !shown) setShown(true);
+  if (!open && shown && !slides) setShown(false);
   const close = () => setOpen(false);
+  const ModalRoot = useContext(SheetGestureContext)?.ModalRoot ?? Fragment;
 
   return (
     <Modal
-      visible={open}
+      visible={shown}
       transparent
-      animationType={reduceMotion ? "none" : "fade"}
+      animationType={slides || reduceMotion ? "none" : "fade"}
       statusBarTranslucent
       onRequestClose={close}
+      onShow={onShow}
     >
+      <ModalRoot>
+        <OverlayModalBody
+          placement={placement}
+          dismissible={dismissible}
+          open={open}
+          slides={slides}
+          close={close}
+          onHidden={() => setShown(false)}
+          part={part}
+        >
+          {children}
+        </OverlayModalBody>
+      </ModalRoot>
+    </Modal>
+  );
+}
+
+/** The `Modal`'s content: mounted with each opening, so a sheet starts below the screen (or at rest). */
+function OverlayModalBody({
+  part,
+  placement,
+  dismissible,
+  open,
+  slides,
+  close,
+  onHidden,
+  children,
+}: {
+  part: string;
+  placement: "center" | "bottom";
+  dismissible: boolean;
+  open: boolean;
+  slides: boolean;
+  close: () => void;
+  onHidden: () => void;
+  children: ReactNode;
+}) {
+  const scheme = useScheme();
+  const insets = useSafeAreaInsets();
+  const drag = useSheetDragState(close, slides);
+  const backdropStyle = useSheetBackdropStyle(drag);
+  // The open state lives in React, the sheet's position on the UI thread:
+  // each change of `open` starts the slide that matches it. The slide in on
+  // opening starts from the sheet's first layout (`SheetDragView`).
+  useEffect(() => {
+    if (!slides) return;
+    if (open) slideSheetIn(drag);
+    else slideSheetOut(drag, onHidden);
+    // Only a change of `open` starts a slide; `drag` and `onHidden` keep their meaning.
+  }, [open, slides]);
+  return (
+    <SheetDragProvider value={drag}>
       {/* Android too: a modal window with `statusBarTranslucent` may not
           resize for the keyboard, which then covers the fields. The padding
           is the measured overlap, so it drops to 0 where the window does
-          resize. */}
-      <KeyboardAvoidingView behavior="padding" style={styles.fill}>
-        <Pressable
-          testID={`${part}-backdrop`}
-          accessible={dismissible}
-          accessibilityRole="button"
-          accessibilityLabel="Close"
-          disabled={!dismissible}
-          onPress={close}
-          style={[StyleSheet.absoluteFill, { backgroundColor: palette.backdrop[scheme] }]}
-        />
-        <View
-          pointerEvents="box-none"
-          onAccessibilityEscape={close}
-          style={[
-            styles.fill,
-            placement === "bottom"
-              ? {
-                  justifyContent: "flex-end",
-                  paddingTop: insets.top + 16,
-                  paddingLeft: insets.left,
-                  paddingRight: insets.right,
-                }
-              : {
-                  justifyContent: "center",
-                  paddingTop: insets.top + 16,
-                  paddingBottom: insets.bottom + 16,
-                  paddingLeft: insets.left + 16,
-                  paddingRight: insets.right + 16,
-                },
-          ]}
-        >
-          {children}
-        </View>
+          resize. Frame by frame with `KeyboardControllerProvider`. */}
+      <KeyboardAvoidingView style={styles.fill}>
+        {/* A `Modal` is its own window: a dock it opened from does not lift what is in it. */}
+        <KeyboardLiftContext.Provider value={false}>
+          <Animated.View
+            pointerEvents="box-none"
+            style={[StyleSheet.absoluteFill, { backgroundColor: palette.backdrop[scheme] }, backdropStyle]}
+          >
+            <Pressable
+              testID={`${part}-backdrop`}
+              accessible={dismissible}
+              accessibilityRole="button"
+              accessibilityLabel="Close"
+              disabled={!dismissible}
+              onPress={close}
+              style={StyleSheet.absoluteFill}
+            />
+          </Animated.View>
+          <View
+            pointerEvents="box-none"
+            onAccessibilityEscape={close}
+            style={[
+              styles.fill,
+              placement === "bottom"
+                ? {
+                    justifyContent: "flex-end",
+                    paddingTop: insets.top + 16,
+                    paddingLeft: insets.left,
+                    paddingRight: insets.right,
+                  }
+                : {
+                    justifyContent: "center",
+                    paddingTop: insets.top + 16,
+                    paddingBottom: insets.bottom + 16,
+                    paddingLeft: insets.left + 16,
+                    paddingRight: insets.right + 16,
+                  },
+            ]}
+          >
+            {children}
+          </View>
+        </KeyboardLiftContext.Provider>
       </KeyboardAvoidingView>
-    </Modal>
+    </SheetDragProvider>
   );
 }
 

package/src/primitives/pager-gesture.tsx

@@ -0,0 +1,131 @@
+import { useEffect, useRef, useState } from "react";
+import { StyleSheet, View } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+  cancelAnimation,
+  ReduceMotion,
+  runOnJS,
+  useAnimatedStyle,
+  useSharedValue,
+  withSpring,
+  withTiming,
+} from "react-native-reanimated";
+import { selectionHaptic } from "../haptics";
+import { InsidePagerContext, type PagerProps } from "../Pager";
+import { PAGER_ACTIVE_OFFSET_X, PAGER_FAIL_OFFSET_Y, pagerPosition, pagerSettle, pagesBetween } from "../pagerSwipe";
+import { useWebClickGuard } from "./web-click-guard";
+
+// The pager on Gesture Handler: the track phase and the release run as
+// worklets on the UI thread, so the pages never lag the finger. The rules are
+// plain worklets in `pagerSwipe`.
+
+/** The release: springs on at the finger's speed, no bounce (an overshoot would flash the next page's edge). */
+const PAGER_SPRING = { duration: 250, dampingRatio: 1, reduceMotion: ReduceMotion.System } as const;
+
+/** A page set from outside (a tab press) slides there; at once with Reduce Motion. */
+const PAGER_SLIDE = { duration: 220, reduceMotion: ReduceMotion.System } as const;
+
+export function GesturePager({ index, count, onIndexChange, progress, renderPage }: PagerProps) {
+  const width = useSharedValue(0);
+  // Where the pages were when the finger caught them, and the finger's travel then.
+  const start = useSharedValue(0);
+  const startX = useSharedValue(0);
+  const [mounted, setMounted] = useState<ReadonlySet<number>>(() => new Set([index]));
+  const [shown, setShown] = useState(index);
+  // A page reached from outside is drawn from then on, with every page the
+  // slide there passes, so it never crosses a blank page.
+  if (shown !== index) {
+    setShown(index);
+    setMounted(new Set([...mounted, ...pagesBetween(shown, index)]));
+  }
+  // The page a swipe settled on, until the new `index` comes back: that one must not stop the spring.
+  const settling = useRef<number | null>(null);
+  // A page set from outside slides there. An effect: a shared value is never
+  // written in render.
+  useEffect(() => {
+    const fromSwipe = settling.current === index;
+    settling.current = null;
+    if (fromSwipe) return;
+    progress.set(withTiming(index, PAGER_SLIDE));
+  }, [index, progress]);
+
+  const webClicks = useWebClickGuard();
+  const dragStarted = () => {
+    webClicks.swallowNext();
+    // Both neighbours, so the finger finds a page there.
+    setMounted((current) => new Set([...current, index - 1, index + 1].filter((page) => page >= 0 && page < count)));
+  };
+  const settled = (page: number) => {
+    settling.current = page;
+    selectionHaptic();
+    onIndexChange(page);
+  };
+
+  // Built on each render (for `index` and `count`): the detector keeps the
+  // same handler, and a drag in flight, and only takes the new config.
+  const pan = Gesture.Pan()
+    .enabled(count > 1)
+    // Clearly sideways only: a vertical drag is the page's scroll, and a row swipe starts sooner.
+    .activeOffsetX([-PAGER_ACTIVE_OFFSET_X, PAGER_ACTIVE_OFFSET_X])
+    .failOffsetY([-PAGER_FAIL_OFFSET_Y, PAGER_FAIL_OFFSET_Y])
+    .onStart((event) => {
+      cancelAnimation(progress);
+      start.set(progress.get());
+      // Count from here, so the pages do not jump by the slop the drag needed to start.
+      startX.set(event.translationX);
+      runOnJS(dragStarted)();
+    })
+    // Track phase: one shared value write per frame, on the UI thread.
+    .onUpdate((event) => {
+      progress.set(pagerPosition(start.get(), event.translationX - startX.get(), width.get(), count));
+    })
+    .onEnd((event) => {
+      const pageWidth = width.get();
+      const target = pagerSettle(progress.get(), event.velocityX, pageWidth, Math.round(start.get()), count);
+      // The finger's speed in pages per second, the unit of `progress`.
+      const velocity = pageWidth > 0 ? -event.velocityX / pageWidth : 0;
+      progress.set(withSpring(target, { ...PAGER_SPRING, velocity }));
+      if (target !== index) runOnJS(settled)(target);
+    });
+
+  const trackStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: `${(-progress.get() * 100) / count}%` }],
+  }));
+  return (
+    <InsidePagerContext.Provider value>
+      <View style={styles.clip} onLayout={(event) => width.set(event.nativeEvent.layout.width)}>
+        <GestureDetector gesture={pan}>
+          <Animated.View style={[styles.fill, { width: `${count * 100}%` }, trackStyle]}>
+            <View ref={webClicks.ref} style={styles.track}>
+              {Array.from({ length: count }, (_, page) => (
+                <View
+                  key={page}
+                  // Off-screen pages are hidden from screen readers; the tabs above switch pages for them.
+                  accessibilityElementsHidden={page !== index}
+                  importantForAccessibility={page === index ? "auto" : "no-hide-descendants"}
+                  style={{ width: `${100 / count}%` }}
+                >
+                  {mounted.has(page) ? renderPage(page) : null}
+                </View>
+              ))}
+            </View>
+          </Animated.View>
+        </GestureDetector>
+      </View>
+    </InsidePagerContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  clip: {
+    flex: 1,
+    overflow: "hidden",
+  },
+  fill: {
+    flex: 1,
+  },
+  track: {
+    flex: 1,
+    flexDirection: "row",
+  },
+});