@vvedantb/native-ui 0.13.0 → 0.17.0

package/src/pagerSwipe.ts

@@ -0,0 +1,102 @@
+/**
+ * The rules of a swiped `Pager`, as plain numbers, so they stay testable
+ * apart from the gesture. The pager's position is in pages: 0 is the first
+ * page, 1.5 is halfway between the second and the third. Distances are in
+ * points and velocities in points per second (the Gesture Handler units),
+ * positive to the right. Each rule is a worklet, so the drag runs it on the
+ * UI thread.
+ */
+
+/**
+ * Sideways travel (pt) before a drag takes the pager: twice a row swipe's
+ * (`SWIPE_ACTIVE_OFFSET_X`), so a swipeable row under the finger takes its
+ * own swipe first, and only a clearly sideways drag moves the pages.
+ */
+export const PAGER_ACTIVE_OFFSET_X = 24;
+
+/** Vertical travel (pt) that leaves the touch to the page's own scroll. */
+export const PAGER_FAIL_OFFSET_Y = 14;
+
+/** A sideways flick at this speed (pt/s) turns the page, however short the drag. */
+const FLICK_VELOCITY = 500;
+
+/** How far ahead (s) the release velocity carries the pages when deciding where they settle. */
+const PROJECTION_S = 0.2;
+
+/** How far the pages move past the first or last page: less and less the further the finger goes. */
+function rubberband(overshoot: number, dimension: number): number {
+  "worklet";
+  const constant = 0.55;
+  return (overshoot * dimension * constant) / (dimension + constant * overshoot);
+}
+
+/**
+ * Where the pages sit for a finger `dx` points from where the drag caught
+ * them at `start`: they follow the finger 1:1 (a drag left shows the next
+ * page), and past the first or last page they meet growing resistance.
+ */
+export function pagerPosition(start: number, dx: number, width: number, count: number): number {
+  "worklet";
+  if (width <= 0) return start;
+  const raw = start - dx / width;
+  const last = count - 1;
+  if (raw < 0) return -rubberband(-raw * width, width) / width;
+  if (raw > last) return last + rubberband((raw - last) * width, width) / width;
+  return raw;
+}
+
+/**
+ * The page a released drag settles on, from the page it started on
+ * (`from`), where it is (`position`) and the finger's speed (`vx`): a flick
+ * past `FLICK_VELOCITY` the way it moved turns one page; else the position
+ * carried on by its speed rounds to the nearest page. Never more than one
+ * page from `from`, and never past the ends.
+ */
+export function pagerSettle(position: number, vx: number, width: number, from: number, count: number): number {
+  "worklet";
+  const moved = position - from;
+  // A drag left (negative `vx`) moves toward the next page (a larger position).
+  const toward = -Math.sign(vx);
+  let target: number;
+  if (Math.abs(vx) >= FLICK_VELOCITY && moved !== 0 && toward === Math.sign(moved)) {
+    target = from + toward;
+  } else {
+    target = Math.round(width > 0 ? position - (vx * PROJECTION_S) / width : position);
+  }
+  return Math.min(count - 1, Math.max(0, Math.min(from + 1, Math.max(from - 1, target))));
+}
+
+/**
+ * Every page from `from` to `to`, both included: the pages a slide from
+ * outside (a tab press) passes, which the pager draws so it never crosses a
+ * blank page.
+ */
+export function pagesBetween(from: number, to: number): number[] {
+  const low = Math.min(from, to);
+  return Array.from({ length: Math.abs(to - from) + 1 }, (_, step) => low + step);
+}
+
+/**
+ * The scroll offset (pt) of a sideways tab row that centres the tab at
+ * `position` (in pages, as the pager's: 1.5 is halfway between the second
+ * and the third tab), given each tab's `x` and `width` in the row and the
+ * row's visible `viewport` width. Between two tabs it blends their centres;
+ * it never scrolls before the first tab or past the last.
+ */
+export function centredTabScroll(
+  tabs: ReadonlyArray<{ x: number; width: number }>,
+  position: number,
+  viewport: number,
+): number {
+  "worklet";
+  const last = tabs[tabs.length - 1];
+  if (!last || viewport <= 0) return 0;
+  const at = Math.min(tabs.length - 1, Math.max(0, position));
+  const below = Math.floor(at);
+  const left = tabs[below] ?? last;
+  const right = tabs[Math.min(tabs.length - 1, below + 1)] ?? last;
+  const share = at - below;
+  const centre = left.x + left.width / 2 + (right.x + right.width / 2 - (left.x + left.width / 2)) * share;
+  const end = Math.max(0, last.x + last.width - viewport);
+  return Math.min(end, Math.max(0, centre - viewport / 2));
+}

package/src/palette.ts

@@ -2,7 +2,7 @@
  * Web semantic colours for React Native, converted from `@vvedantb/ui`
  * `tokens.css` (oklch → sRGB hex, clipped to sRGB). `tokens.ts` holds the
  * neutrals the native app ships; these are the colours it lacks (primary,
- * danger, success, warning, overlay, segment, field placeholder, backdrop,
+ * danger, success, warning, overlay, segment, tab bar pill, field placeholder, backdrop,
  * dialog description).
  *
  * A test in this package converts `tokens.css` and fails when a value here
@@ -25,6 +25,13 @@ export const palette = {
   overlayForeground: { light: "#181818", dark: "#fcfcfc" },
   segment: { light: "#ffffff", dark: "#474747" },
   segmentForeground: { light: "#181818", dark: "#fcfcfc" },
+  /**
+   * The `FloatingTabBar` active pill: `--default` in light (it shows on the
+   * near-white glass bar) and `--segment` in dark. Its own key, so an app that
+   * themes `segment` for the segmented `Tabs` thumb keeps a pill that shows on
+   * the dark glass bar.
+   */
+  tabBarPill: { light: "#ebebeb", dark: "#474747" },
   surfaceTertiary: { light: "#eaeaea", dark: "#282627" },
   fieldPlaceholder: { light: "#727272", dark: "#a0a0a0" },
   backdrop: { light: "rgba(0, 0, 0, 0.5)", dark: "rgba(0, 0, 0, 0.6)" },

package/src/primitives/button.tsx

@@ -3,10 +3,11 @@ import { cn } from "../cn";
 import { cva, type VariantProps } from "class-variance-authority";
 import * as React from "react";
 import { Platform, Pressable } from "react-native";
+import { usePressFeedback } from "../motion";
 
 const buttonVariants = cva(
   cn(
-    "group flex-row items-center justify-center gap-2 shadow-none active:opacity-80",
+    "group flex-row items-center justify-center gap-2 shadow-none",
     Platform.select({
       web: "outline-none transition-all",
     }),
@@ -88,12 +89,14 @@ const Button = React.forwardRef<
   React.ElementRef<typeof Pressable>,
   ButtonProps
 >(({ className, variant, size, shape, ...props }, ref) => {
+  const pressed = usePressFeedback();
   return (
     <TextClassContext.Provider value={buttonTextVariants({ variant, size })}>
       <Pressable
         ref={ref}
         className={cn(
           buttonVariants({ variant, size, shape }),
+          pressed,
           props.disabled && "opacity-45",
           className,
         )}

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>
   );
 }