@limonify/zest-ui 0.1.0

package/src/drawer/root/DrawerRoot.tsx

@@ -0,0 +1,214 @@
+'use client';
+import * as React from 'react';
+import type { DialogRoot } from '../../dialog/root/DialogRoot';
+import { useRenderDialogRoot } from '../../dialog/root/useRenderDialogRoot';
+import type { DrawerHandle } from '../handle';
+import { useControlled } from '../../hooks/useControlled';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import type { REASONS } from '../../utils/reasons';
+import {
+  DrawerRootContext,
+  type DrawerSnapPoint,
+  type DrawerSwipeDirection,
+} from './DrawerRootContext';
+
+/**
+ * Groups all parts of the drawer.
+ * Doesn't render its own element.
+ *
+ * A drawer is a dialog that can also be dismissed by swiping it away, so it
+ * reuses the dialog store and every dialog part but its own `Drawer.Popup`.
+ *
+ * **Not ported from upstream.** `modal` (a React Native `Modal` is always modal,
+ * and there is no page behind it to scroll-lock) and `onOpenChangeComplete` (see
+ * the animation contract in CLAUDE.md — nothing in RN reports that a closing
+ * animation finished).
+ * Upstream's `Indent`/`IndentBackground` parts have no counterpart either: they
+ * scale the page behind the drawer, which a `Modal` renders in a separate native
+ * window from.
+ */
+export function DrawerRoot<Payload = unknown>(props: DrawerRoot.Props<Payload>) {
+  const {
+    swipeDirection = 'down',
+    snapPoints,
+    snapPoint,
+    defaultSnapPoint,
+    onSnapPointChange,
+    snapToSequentialPoints = false,
+    ...dialogProps
+  } = props;
+
+  const [popupHeight, setPopupHeight] = React.useState(0);
+
+  const [activeSnapPoint, setActiveSnapPointState] = useControlled<DrawerSnapPoint | null>({
+    controlled: snapPoint,
+    default: defaultSnapPoint ?? snapPoints?.[0] ?? null,
+    name: 'Drawer',
+    state: 'snapPoint',
+  });
+
+  const setActiveSnapPoint = useStableCallback(
+    (nextSnapPoint: DrawerSnapPoint | null, eventDetails: DrawerRoot.SnapPointChangeEventDetails) => {
+      if (nextSnapPoint === activeSnapPoint) {
+        return;
+      }
+
+      onSnapPointChange?.(nextSnapPoint, eventDetails);
+
+      if (eventDetails.isCanceled) {
+        return;
+      }
+
+      setActiveSnapPointState(nextSnapPoint);
+    },
+  );
+
+  const onPopupHeightChange = useStableCallback((height: number) => {
+    setPopupHeight(height);
+  });
+
+  const contextValue: DrawerRootContext = React.useMemo(
+    () => ({
+      swipeDirection,
+      snapPoints,
+      snapToSequentialPoints,
+      activeSnapPoint,
+      setActiveSnapPoint,
+      popupHeight,
+      onPopupHeightChange,
+    }),
+    [
+      swipeDirection,
+      snapPoints,
+      snapToSequentialPoints,
+      activeSnapPoint,
+      setActiveSnapPoint,
+      popupHeight,
+      onPopupHeightChange,
+    ],
+  );
+
+  const dialogRoot = useRenderDialogRoot(dialogProps, 'dialog');
+
+  return (
+    <DrawerRootContext.Provider value={contextValue}>{dialogRoot}</DrawerRootContext.Provider>
+  );
+}
+
+export interface DrawerRootState {}
+
+export interface DrawerRootProps<Payload = unknown> {
+  /**
+   * Whether the drawer is currently open.
+   */
+  open?: boolean | undefined;
+  /**
+   * Whether the drawer is initially open.
+   *
+   * To render a controlled drawer, use the `open` prop instead.
+   * @default false
+   */
+  defaultOpen?: boolean | undefined;
+  /**
+   * Event handler called when the drawer is opened or closed.
+   */
+  onOpenChange?:
+    | ((open: boolean, eventDetails: DrawerRoot.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Whether to prevent the drawer from closing on presses outside the popup.
+   * Swipe dismissal is unaffected.
+   * @default false
+   */
+  disablePointerDismissal?: boolean | undefined;
+  /**
+   * The swipe direction used to dismiss the drawer.
+   * @default 'down'
+   */
+  swipeDirection?: DrawerSwipeDirection | undefined;
+  /**
+   * Snap points used to position the drawer. A number `<= 1` is a fraction of
+   * the viewport height, anything larger is a pixel value.
+   *
+   * A snap point describes how much of the drawer is *visible*, so snap points
+   * are vertical by nature and only apply to `swipeDirection: 'down'`.
+   */
+  snapPoints?: readonly DrawerSnapPoint[] | undefined;
+  /**
+   * The currently active snap point. Use with `onSnapPointChange` to control it.
+   */
+  snapPoint?: DrawerSnapPoint | null | undefined;
+  /**
+   * The initial snap point when uncontrolled. Defaults to the first of
+   * `snapPoints`.
+   */
+  defaultSnapPoint?: DrawerSnapPoint | null | undefined;
+  /**
+   * Event handler called when the active snap point changes.
+   */
+  onSnapPointChange?:
+    | ((
+        snapPoint: DrawerSnapPoint | null,
+        eventDetails: DrawerRoot.SnapPointChangeEventDetails,
+      ) => void)
+    | undefined;
+  /**
+   * Disables velocity-based snap skipping, so drag distance alone determines the
+   * next snap point.
+   * @default false
+   */
+  snapToSequentialPoints?: boolean | undefined;
+  /**
+   * A ref to imperative actions.
+   */
+  actionsRef?: React.RefObject<DialogRoot.Actions | null> | undefined;
+  /**
+   * A handle associating this drawer with triggers rendered outside it, and
+   * letting it be opened and closed imperatively. Create one with
+   * `Drawer.createHandle()`.
+   */
+  handle?: DrawerHandle<Payload> | undefined;
+  /**
+   * The id of the trigger the drawer is associated with.
+   */
+  triggerId?: string | null | undefined;
+  /**
+   * The id of the trigger the drawer is initially associated with.
+   */
+  defaultTriggerId?: string | null | undefined;
+  /**
+   * The content of the drawer.
+   *
+   * Pass a function to receive the payload the drawer was opened with.
+   */
+  children?: React.ReactNode | ((payload: Payload) => React.ReactNode);
+}
+
+export type DrawerRootChangeEventReason =
+  | typeof REASONS.triggerPress
+  | typeof REASONS.outsidePress
+  | typeof REASONS.escapeKey
+  | typeof REASONS.closePress
+  | typeof REASONS.swipe
+  | typeof REASONS.imperativeAction
+  | typeof REASONS.none;
+
+export type DrawerRootChangeEventDetails = ZestChangeEventDetails<DrawerRootChangeEventReason>;
+
+export type DrawerRootSnapPointChangeEventReason = DrawerRootChangeEventReason;
+
+export type DrawerRootSnapPointChangeEventDetails =
+  ZestChangeEventDetails<DrawerRootSnapPointChangeEventReason>;
+
+export namespace DrawerRoot {
+  export type State = DrawerRootState;
+  export type Props<Payload = unknown> = DrawerRootProps<Payload>;
+  export type Actions = DialogRoot.Actions;
+  export type ChangeEventReason = DrawerRootChangeEventReason;
+  export type ChangeEventDetails = DrawerRootChangeEventDetails;
+  export type SnapPointChangeEventReason = DrawerRootSnapPointChangeEventReason;
+  export type SnapPointChangeEventDetails = DrawerRootSnapPointChangeEventDetails;
+  export type SwipeDirection = DrawerSwipeDirection;
+  export type SnapPoint = DrawerSnapPoint;
+}

package/src/drawer/root/DrawerRootContext.ts

@@ -0,0 +1,54 @@
+'use client';
+import * as React from 'react';
+import type { DrawerRoot } from './DrawerRoot';
+
+export type DrawerSwipeDirection = 'up' | 'down' | 'left' | 'right';
+
+/**
+ * A number `<= 1` is a fraction of the viewport height; anything larger is a
+ * pixel value. Upstream also accepts `'148px'`/`'30rem'` strings — see
+ * `resolveSnapPointHeight` for why React Native takes numbers only.
+ */
+export type DrawerSnapPoint = number;
+
+export interface DrawerRootContext {
+  /**
+   * The direction a swipe must travel to dismiss the drawer.
+   */
+  swipeDirection: DrawerSwipeDirection;
+  /**
+   * Snap points used to position the drawer, if any.
+   */
+  snapPoints: readonly DrawerSnapPoint[] | undefined;
+  /**
+   * Whether to disable velocity-based snap skipping.
+   */
+  snapToSequentialPoints: boolean;
+  /**
+   * The currently active snap point. `undefined` means "the first one";
+   * `null` means none.
+   */
+  activeSnapPoint: DrawerSnapPoint | null | undefined;
+  setActiveSnapPoint: (
+    snapPoint: DrawerSnapPoint | null,
+    eventDetails: DrawerRoot.SnapPointChangeEventDetails,
+  ) => void;
+  /**
+   * The popup's measured height, which every snap point offset is derived from.
+   */
+  popupHeight: number;
+  onPopupHeightChange: (height: number) => void;
+}
+
+export const DrawerRootContext = React.createContext<DrawerRootContext | undefined>(undefined);
+
+export function useDrawerRootContext() {
+  const context = React.useContext(DrawerRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: DrawerRootContext is missing. Drawer parts must be placed within <Drawer.Root>.',
+    );
+  }
+
+  return context;
+}

package/src/drawer/root/useDrawerSnapPoints.ts

@@ -0,0 +1,185 @@
+'use client';
+import * as React from 'react';
+import { useWindowDimensions } from 'react-native';
+import { useDrawerRootContext } from './DrawerRootContext';
+import type { DrawerSnapPoint } from './DrawerRootContext';
+
+export interface ResolvedDrawerSnapPoint {
+  value: DrawerSnapPoint;
+  /**
+   * How much of the popup is visible at this snap point, in pixels.
+   */
+  height: number;
+  /**
+   * How far the popup is pushed off the edge at this snap point, in pixels.
+   * This is what the consumer translates by.
+   */
+  offset: number;
+}
+
+/**
+ * Damps the swipe once the drag overshoots the fully-open edge (`nextOffset < 0`),
+ * so the popup resists travelling past it instead of tearing off the screen.
+ * Ported from upstream verbatim.
+ */
+export function getSnapPointSwipeMovement(baseOffset: number, movementValue: number): number {
+  const nextOffset = baseOffset + movementValue;
+  if (nextOffset >= 0) {
+    return movementValue;
+  }
+
+  return -Math.sqrt(-nextOffset) - baseOffset;
+}
+
+/**
+ * Turns a snap point into a visible height: a number `<= 1` is a fraction of the
+ * viewport, anything larger is a pixel value.
+ *
+ * **Diverges from upstream:** it accepts `'148px'`/`'30rem'` strings too. React
+ * Native styles are unitless numbers and it has no root font size, so a string
+ * form would have nothing to resolve against — zest takes numbers only.
+ */
+export function resolveSnapPointHeight(snapPoint: DrawerSnapPoint, viewportHeight: number) {
+  if (!Number.isFinite(viewportHeight) || viewportHeight <= 0 || !Number.isFinite(snapPoint)) {
+    return null;
+  }
+
+  if (snapPoint <= 1) {
+    return clamp(snapPoint, 0, 1) * viewportHeight;
+  }
+
+  return snapPoint;
+}
+
+/** The index of the value closest to `target`, or `-1` when there are none. */
+export function closestSnapPointIndex(values: number[], target: number): number {
+  let closestIndex = -1;
+  let closestDistance = Number.POSITIVE_INFINITY;
+
+  values.forEach((value, index) => {
+    const distance = Math.abs(value - target);
+    if (distance < closestDistance) {
+      closestDistance = distance;
+      closestIndex = index;
+    }
+  });
+
+  return closestIndex;
+}
+
+export function resolveSnapPoints(
+  snapPoints: readonly DrawerSnapPoint[] | undefined,
+  popupHeight: number,
+  viewportHeight: number,
+): ResolvedDrawerSnapPoint[] {
+  if (!snapPoints || snapPoints.length === 0 || viewportHeight <= 0 || popupHeight <= 0) {
+    return [];
+  }
+
+  const maxHeight = Math.min(popupHeight, viewportHeight);
+  if (!Number.isFinite(maxHeight) || maxHeight <= 0) {
+    return [];
+  }
+
+  const resolved = snapPoints
+    .map((value): ResolvedDrawerSnapPoint | null => {
+      const resolvedHeight = resolveSnapPointHeight(value, viewportHeight);
+      if (resolvedHeight === null || !Number.isFinite(resolvedHeight)) {
+        return null;
+      }
+
+      const height = clamp(resolvedHeight, 0, maxHeight);
+      return { value, height, offset: Math.max(0, popupHeight - height) };
+    })
+    .filter((point): point is ResolvedDrawerSnapPoint => point !== null);
+
+  if (resolved.length <= 1) {
+    return resolved;
+  }
+
+  // Two snap points that land within a pixel of each other would make the
+  // closest-point search ambiguous. Later duplicates win, matching upstream.
+  const deduped: ResolvedDrawerSnapPoint[] = [];
+  const seenHeights: number[] = [];
+
+  for (let index = resolved.length - 1; index >= 0; index -= 1) {
+    const point = resolved[index]!;
+    if (seenHeights.some((height) => Math.abs(height - point.height) <= 1)) {
+      continue;
+    }
+
+    seenHeights.push(point.height);
+    deduped.push(point);
+  }
+
+  deduped.reverse();
+  return deduped;
+}
+
+/**
+ * Resolves the drawer's snap points against the measured popup and the window.
+ *
+ * Upstream measures the viewport element and watches it with a `ResizeObserver`.
+ * React Native has `useWindowDimensions`, which already re-renders on rotation —
+ * and a drawer's Modal is full-screen (`statusBarTranslucent`), so the window
+ * *is* the viewport.
+ */
+export function useDrawerSnapPoints() {
+  const { snapPoints, activeSnapPoint, setActiveSnapPoint, popupHeight, snapToSequentialPoints } =
+    useDrawerRootContext();
+
+  const { height: viewportHeight } = useWindowDimensions();
+
+  const resolvedSnapPoints = React.useMemo(
+    () => resolveSnapPoints(snapPoints, popupHeight, viewportHeight),
+    [snapPoints, popupHeight, viewportHeight],
+  );
+
+  const activeResolvedSnapPoint = React.useMemo(() => {
+    if (resolvedSnapPoints.length === 0) {
+      return undefined;
+    }
+
+    if (activeSnapPoint === undefined) {
+      return resolvedSnapPoints[0];
+    }
+
+    if (activeSnapPoint === null) {
+      return undefined;
+    }
+
+    const exactMatch = resolvedSnapPoints.find((point) => Object.is(point.value, activeSnapPoint));
+    if (exactMatch) {
+      return exactMatch;
+    }
+
+    // A snap point that is not one of `snapPoints` still resolves, to whichever
+    // of them it lands nearest.
+    const resolvedHeight = resolveSnapPointHeight(activeSnapPoint, viewportHeight);
+    if (resolvedHeight === null) {
+      return undefined;
+    }
+
+    const height = clamp(resolvedHeight, 0, Math.min(popupHeight, viewportHeight));
+    const index = closestSnapPointIndex(
+      resolvedSnapPoints.map((point) => point.height),
+      height,
+    );
+
+    return resolvedSnapPoints[index];
+  }, [activeSnapPoint, popupHeight, resolvedSnapPoints, viewportHeight]);
+
+  return {
+    snapPoints,
+    snapToSequentialPoints,
+    activeSnapPoint,
+    setActiveSnapPoint,
+    resolvedSnapPoints,
+    activeSnapPointOffset: activeResolvedSnapPoint?.offset ?? null,
+    hasSnapPoints: resolvedSnapPoints.length > 0,
+  };
+}
+
+function clamp(value: number, lower: number, upper: number) {
+  return Math.min(Math.max(value, lower), upper);
+}

package/src/drawer/swipe-area/DrawerSwipeArea.tsx

@@ -0,0 +1,172 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import { useDialogRootContext } from '../../dialog/root/DialogRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import { useDrawerRootContext, type DrawerSwipeDirection } from '../root/DrawerRootContext';
+
+/**
+ * How far a swipe must travel, in pixels, before it opens the drawer. Matches
+ * upstream's `FALLBACK_SWIPE_OPEN_THRESHOLD` — upstream also scales this to half
+ * the popup size, but the swipe area is measured before the popup ever mounts, so
+ * a fixed pixel threshold is all React Native can offer here.
+ */
+const DEFAULT_SWIPE_OPEN_THRESHOLD = 40;
+
+const oppositeSwipeDirection: Record<DrawerSwipeDirection, DrawerSwipeDirection> = {
+  up: 'down',
+  down: 'up',
+  left: 'right',
+  right: 'left',
+};
+
+/**
+ * An invisible area, usually pinned to a screen edge, that opens the drawer when
+ * swiped. Renders a `<View>` wrapped in a `GestureDetector`.
+ *
+ * Its swipe direction defaults to the opposite of `Drawer.Root`'s
+ * `swipeDirection`: a drawer dismissed by swiping `down` is opened by swiping
+ * `up`. Place it where the drawer enters from (a bottom drawer's swipe area sits
+ * at the bottom of the screen) and give it a size — it has none of its own.
+ *
+ * Requires `react-native-gesture-handler`, and the app to be wrapped in
+ * `<GestureHandlerRootView>`.
+ */
+export function DrawerSwipeArea(componentProps: DrawerSwipeArea.Props) {
+  const {
+    render,
+    className,
+    style,
+    disabled = false,
+    swipeDirection: swipeDirectionProp,
+    swipeThreshold = DEFAULT_SWIPE_OPEN_THRESHOLD,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const { testID } = elementProps;
+  const store = useDialogRootContext();
+  const { swipeDirection: dismissDirection } = useDrawerRootContext();
+
+  const open = store.useState('open');
+
+  const [swiping, setSwiping] = React.useState(false);
+
+  // The direction that *opens* the drawer is the opposite of the one that
+  // dismisses it, unless the consumer overrides it.
+  const openDirection = swipeDirectionProp ?? oppositeSwipeDirection[dismissDirection];
+
+  const release = useStableCallback((translationX: number, translationY: number) => {
+    if (disabled) {
+      return;
+    }
+
+    const displacement = getDisplacement(openDirection, translationX, translationY);
+    if (displacement > swipeThreshold) {
+      store.setOpen(true, createChangeEventDetails(REASONS.swipe));
+    }
+  });
+
+  const gesture = React.useMemo(
+    () =>
+      Gesture.Pan()
+        // A gesture is invisible to the rendered tree, so tests can only reach it
+        // through gesture-handler's registry, which is keyed by this id.
+        .withTestId(testID ?? 'drawer-swipe-area')
+        .enabled(!disabled)
+        .onBegin(() => {
+          setSwiping(true);
+        })
+        .onEnd((event) => release(event.translationX, event.translationY))
+        .onFinalize(() => {
+          setSwiping(false);
+        })
+        // The handlers touch React state, so they must not run on the UI thread.
+        .runOnJS(true),
+    [testID, disabled, release],
+  );
+
+  const state: DrawerSwipeAreaState = {
+    open,
+    swiping,
+    swipeDirection: openDirection,
+    disabled,
+  };
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        accessibilityElementsHidden: true,
+        importantForAccessibility: 'no-hide-descendants' as const,
+        'aria-hidden': true,
+      },
+      elementProps,
+    ],
+  });
+
+  return <GestureDetector gesture={gesture}>{element}</GestureDetector>;
+}
+
+/** How far a translation has travelled towards `direction`. */
+function getDisplacement(direction: DrawerSwipeDirection, x: number, y: number) {
+  switch (direction) {
+    case 'up':
+      return -y;
+    case 'down':
+      return y;
+    case 'left':
+      return -x;
+    default:
+      return x;
+  }
+}
+
+export interface DrawerSwipeAreaState {
+  /**
+   * Whether the drawer is currently open.
+   */
+  open: boolean;
+  /**
+   * Whether a swipe is currently in progress.
+   */
+  swiping: boolean;
+  /**
+   * The swipe direction that opens the drawer.
+   */
+  swipeDirection: DrawerSwipeDirection;
+  /**
+   * Whether the swipe area is disabled.
+   */
+  disabled: boolean;
+}
+
+export interface DrawerSwipeAreaProps
+  extends ZestUIComponentProps<typeof View, DrawerSwipeAreaState> {
+  /**
+   * Whether the swipe area is disabled.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * The swipe direction that opens the drawer. Defaults to the opposite of
+   * `Drawer.Root`'s `swipeDirection`.
+   */
+  swipeDirection?: DrawerSwipeDirection | undefined;
+  /**
+   * How far a swipe must travel, in pixels, before it opens the drawer.
+   * @default 40
+   */
+  swipeThreshold?: number | undefined;
+}
+
+export namespace DrawerSwipeArea {
+  export type State = DrawerSwipeAreaState;
+  export type Props = DrawerSwipeAreaProps;
+}

package/src/field/control/FieldControl.tsx

@@ -0,0 +1,64 @@
+'use client';
+import { TextInput } from 'react-native';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useFieldRootContext } from '../root/FieldRootContext';
+import type { FieldRoot } from '../root/FieldRoot';
+import type { ZestUIComponentProps } from '../../types';
+import { useFieldControl } from './useFieldControl';
+
+/**
+ * The field's text input.
+ * Renders a `<TextInput>`.
+ */
+export function FieldControl(componentProps: FieldControl.Props) {
+  const {
+    render,
+    className,
+    style,
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    nativeID,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const { state } = useFieldRootContext();
+
+  const { props } = useFieldControl({
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    nativeID,
+    requireField: true,
+  });
+
+  return useRenderElement(TextInput, componentProps, {
+    state,
+    ref,
+    props: [props, elementProps],
+  });
+}
+
+export interface FieldControlState extends FieldRoot.State {}
+
+export interface FieldControlProps
+  extends Omit<ZestUIComponentProps<typeof TextInput, FieldControlState>, 'value'> {
+  /**
+   * The controlled text value.
+   */
+  value?: string | undefined;
+  /**
+   * The initial text value when uncontrolled.
+   */
+  defaultValue?: string | undefined;
+  /**
+   * Called with the new text as it changes.
+   */
+  onValueChange?: ((value: string) => void) | undefined;
+}
+
+export namespace FieldControl {
+  export type State = FieldControlState;
+  export type Props = FieldControlProps;
+}