@limonify/zest-ui 0.1.0

package/src/dialog/trigger/DialogTrigger.tsx

@@ -0,0 +1,149 @@
+'use client';
+import * as React from 'react';
+import { Pressable, type GestureResponderEvent } from 'react-native';
+import { DialogRootContext } from '../root/DialogRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useButton } from '../../internals/use-button/useButton';
+import { useId } from '../../hooks/useId';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import { usePopupHandleStore } from '../../utils/popups/usePopupHandleStore';
+import type { DialogHandle } from '../store/DialogHandle';
+import type { DialogStore } from '../store/DialogStore';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A button that opens the dialog.
+ * Renders a `<Pressable>`.
+ *
+ * Pass a `handle` to render a trigger outside of its `Dialog.Root`: there is no
+ * context reaching across, so the handle is what connects the two.
+ */
+export function DialogTrigger<Payload = unknown>(componentProps: DialogTrigger.Props<Payload>) {
+  const {
+    render,
+    className,
+    style,
+    disabled = false,
+    handle,
+    nativeID: idProp,
+    payload,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const rootStore = React.useContext(DialogRootContext);
+  const handleStore = usePopupHandleStore(handle);
+
+  // A trigger inside a root uses that root; a detached one follows its handle,
+  // which resolves to the attached root's store or to an inert fallback.
+  const store = (handleStore ?? rootStore) as DialogStore<any> | undefined;
+
+  if (store === undefined) {
+    throw new Error(
+      'Zest: Dialog.Trigger must be placed within <Dialog.Root>, or given a `handle` it shares with one.',
+    );
+  }
+
+  const id = useId(idProp ?? undefined);
+  const open = store.useState('open');
+
+  const [pressed, setPressed] = React.useState(false);
+
+  const { getButtonProps } = useButton({ disabled });
+
+  const triggerRef = React.useRef<unknown>(null);
+  const registerRef = React.useCallback((node: unknown) => {
+    triggerRef.current = node;
+  }, []);
+  const mergedRef = useMergedRefs(ref, registerRef);
+
+  // Registering into whichever store is current is what lets a handle resolve
+  // `open(id)`. The effect re-runs when the handle swaps stores, migrating the
+  // registration to the root that just attached.
+  useIsoLayoutEffect(() => {
+    if (id === undefined) {
+      return undefined;
+    }
+
+    store.context.triggerNodes.add(id, triggerRef.current);
+
+    return () => {
+      store.context.triggerNodes.delete(id);
+    };
+  }, [store, id]);
+
+  const state: DialogTriggerState = { disabled, open, pressed };
+
+  return useRenderElement(Pressable, componentProps, {
+    state,
+    ref: mergedRef,
+    props: [
+      {
+        nativeID: id,
+        onPress(event: GestureResponderEvent) {
+          if (payload !== undefined) {
+            store.set('payload', payload);
+          }
+          if (id !== undefined) {
+            store.set('triggerId', id);
+          }
+
+          store.setOpen(true, createChangeEventDetails(REASONS.triggerPress, event));
+        },
+        onPressIn() {
+          setPressed(true);
+        },
+        onPressOut() {
+          setPressed(false);
+        },
+        accessibilityState: { expanded: open, disabled: disabled || undefined },
+        'aria-haspopup': 'dialog' as const,
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+}
+
+export interface DialogTriggerState {
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the dialog is currently open.
+   */
+  open: boolean;
+  /**
+   * Whether the trigger is currently pressed.
+   */
+  pressed: boolean;
+}
+
+export interface DialogTriggerProps<Payload = unknown>
+  extends ZestUIComponentProps<typeof Pressable, DialogTriggerState> {
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * A handle shared with a `Dialog.Root`, which is what lets this trigger live
+   * outside of it. Create one with `Dialog.createHandle()`.
+   *
+   * The trigger's `nativeID` is the id a handle's `open(triggerId)` resolves.
+   */
+  handle?: DialogHandle<Payload> | undefined;
+  /**
+   * A payload handed to the root's children when they are a function.
+   */
+  payload?: Payload | undefined;
+}
+
+export namespace DialogTrigger {
+  export type State = DialogTriggerState;
+  export type Props<Payload = unknown> = DialogTriggerProps<Payload>;
+}

package/src/dialog/viewport/DialogViewport.tsx

@@ -0,0 +1,62 @@
+'use client';
+import { Pressable, StyleSheet, type GestureResponderEvent } from 'react-native';
+import { useDialogRootContext } from '../root/DialogRootContext';
+import { useDialogPortalContext } from '../portal/DialogPortalContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A positioning container for the dialog popup.
+ * Renders a full-screen `<Pressable>` that dismisses the dialog on outside
+ * press (unless `disablePointerDismissal` is set on the root). Presses inside
+ * `<Dialog.Popup>` are claimed by the popup and never reach the viewport.
+ */
+export function DialogViewport(componentProps: DialogViewport.Props) {
+  const { render, className, style, children, ref, ...elementProps } = componentProps;
+
+  const keepMounted = useDialogPortalContext();
+  const store = useDialogRootContext();
+
+  const open = store.useState('open');
+
+  const state: DialogViewportState = { open };
+
+  const shouldRender = keepMounted || open;
+
+  return useRenderElement(Pressable, componentProps, {
+    enabled: shouldRender,
+    state,
+    ref,
+    props: [
+      {
+        style: StyleSheet.absoluteFill,
+        accessible: false,
+        onPress(event: GestureResponderEvent) {
+          if (store.state.disablePointerDismissal) {
+            return;
+          }
+          store.setOpen(false, createChangeEventDetails(REASONS.outsidePress, event));
+        },
+        children,
+      },
+      elementProps,
+    ],
+  });
+}
+
+export interface DialogViewportState {
+  /**
+   * Whether the dialog is currently open.
+   */
+  open: boolean;
+}
+
+export interface DialogViewportProps
+  extends ZestUIComponentProps<typeof Pressable, DialogViewportState> {}
+
+export namespace DialogViewport {
+  export type State = DialogViewportState;
+  export type Props = DialogViewportProps;
+}

package/src/drawer/handle.ts

@@ -0,0 +1,18 @@
+import { DialogHandle } from '../dialog/store/DialogHandle';
+
+/**
+ * Controls a drawer imperatively, and associates `Drawer.Trigger`s rendered
+ * outside the root with it.
+ *
+ * A drawer reuses the dialog store, so it reuses its handle too — only the name
+ * in warnings differs.
+ */
+export type DrawerHandle<Payload = unknown> = DialogHandle<Payload>;
+
+/**
+ * Creates a handle that connects a `Drawer.Root` to triggers rendered outside it,
+ * and controls it imperatively.
+ */
+export function createDrawerHandle<Payload = unknown>(): DrawerHandle<Payload> {
+  return new DialogHandle<Payload>('Drawer');
+}

package/src/drawer/index.parts.ts

@@ -0,0 +1,14 @@
+export { DrawerRoot as Root } from './root/DrawerRoot';
+export { createDrawerHandle as createHandle } from './handle';
+export { DrawerPopup as Popup } from './popup/DrawerPopup';
+export { DrawerSwipeArea as SwipeArea } from './swipe-area/DrawerSwipeArea';
+
+// A drawer is a dialog with a swipe gesture, so every part but the Root and the
+// Popup is the dialog's own, unchanged — they read the same store.
+export { DialogTrigger as Trigger } from '../dialog/trigger/DialogTrigger';
+export { DialogPortal as Portal } from '../dialog/portal/DialogPortal';
+export { DialogBackdrop as Backdrop } from '../dialog/backdrop/DialogBackdrop';
+export { DialogViewport as Viewport } from '../dialog/viewport/DialogViewport';
+export { DialogTitle as Title } from '../dialog/title/DialogTitle';
+export { DialogDescription as Description } from '../dialog/description/DialogDescription';
+export { DialogClose as Close } from '../dialog/close/DialogClose';

package/src/drawer/index.ts

@@ -0,0 +1,15 @@
+export * as Drawer from './index.parts';
+
+export type * from './root/DrawerRoot';
+export { createDrawerHandle, type DrawerHandle } from './handle';
+export type * from './popup/DrawerPopup';
+export type * from './swipe-area/DrawerSwipeArea';
+export {
+  useDrawerRootContext,
+  type DrawerSnapPoint,
+  type DrawerSwipeDirection,
+} from './root/DrawerRootContext';
+export {
+  useDrawerSnapPoints,
+  type ResolvedDrawerSnapPoint,
+} from './root/useDrawerSnapPoints';

package/src/drawer/popup/DrawerPopup.tsx

@@ -0,0 +1,234 @@
+'use client';
+import * as React from 'react';
+import { View, type LayoutChangeEvent } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import { useDialogPopupProps } from '../../dialog/popup/useDialogPopupProps';
+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 DrawerSnapPoint, type DrawerSwipeDirection } from '../root/DrawerRootContext';
+import {
+  closestSnapPointIndex,
+  getSnapPointSwipeMovement,
+  useDrawerSnapPoints,
+} from '../root/useDrawerSnapPoints';
+
+/**
+ * Matches upstream's `DEFAULT_SWIPE_THRESHOLD`: a swipe dismisses once it has
+ * travelled this far, regardless of how fast it was.
+ */
+const DEFAULT_SWIPE_THRESHOLD = 40;
+
+/**
+ * How far ahead a fling is projected when picking the next snap point, in
+ * seconds of travel at the release velocity. This is what lets a fast flick skip
+ * past a snap point, and what `snapToSequentialPoints` turns off.
+ */
+const VELOCITY_PROJECTION_SECONDS = 0.15;
+
+/**
+ * A container for the drawer contents, dismissable by swiping it away.
+ * Renders a `<View>` wrapped in a `GestureDetector`.
+ *
+ * Follows the animation contract: the popup never moves itself. It publishes how
+ * far the swipe has travelled as `swipeMovement` on the state object, and the
+ * consumer turns that into a transform.
+ *
+ * Requires `react-native-gesture-handler`, and the app to be wrapped in
+ * `<GestureHandlerRootView>`.
+ */
+export function DrawerPopup(componentProps: DrawerPopup.Props) {
+  const {
+    render,
+    className,
+    style,
+    swipeThreshold = DEFAULT_SWIPE_THRESHOLD,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const { testID } = elementProps;
+  const { swipeDirection, onPopupHeightChange } = useDrawerRootContext();
+  const {
+    activeSnapPoint,
+    activeSnapPointOffset,
+    hasSnapPoints,
+    resolvedSnapPoints,
+    setActiveSnapPoint,
+    snapToSequentialPoints,
+  } = useDrawerSnapPoints();
+  const { store, open, props } = useDialogPopupProps();
+
+  const [swiping, setSwiping] = React.useState(false);
+  const [swipeMovement, setSwipeMovement] = React.useState(0);
+
+  // The gesture callbacks read the movement they just published, which React has
+  // not re-rendered yet by the time the release arrives.
+  const swipeMovementRef = React.useRef(0);
+
+  const publishMovement = useStableCallback((movement: number) => {
+    swipeMovementRef.current = movement;
+    setSwipeMovement(movement);
+  });
+
+  const handleLayout = useStableCallback((event: LayoutChangeEvent) => {
+    onPopupHeightChange(event.nativeEvent.layout.height);
+  });
+
+  const baseOffset = activeSnapPointOffset ?? 0;
+
+  const move = useStableCallback((translationX: number, translationY: number) => {
+    const displacement = getDisplacement(swipeDirection, translationX, translationY);
+
+    if (!hasSnapPoints) {
+      // Without snap points there is nowhere to drag back to, so movement never
+      // goes negative: dragging past the resting place would tear the drawer off
+      // the edge it is anchored to.
+      publishMovement(Math.max(displacement, 0));
+      return;
+    }
+
+    // With snap points the drawer can also be dragged open, so a negative
+    // displacement is meaningful — it is only damped past the fully-open edge.
+    publishMovement(getSnapPointSwipeMovement(baseOffset, displacement));
+  });
+
+  const release = useStableCallback(
+    (translationX: number, translationY: number, velocityX: number, velocityY: number) => {
+      const displacement = getDisplacement(swipeDirection, translationX, translationY);
+
+      if (!hasSnapPoints) {
+        if (displacement > swipeThreshold) {
+          store.setOpen(false, createChangeEventDetails(REASONS.swipe));
+        }
+        return;
+      }
+
+      const velocity = getDisplacement(swipeDirection, velocityX, velocityY);
+      // A fling is projected forward so it can skip past a snap point;
+      // `snapToSequentialPoints` reduces the decision to drag distance alone.
+      const projected = snapToSequentialPoints ? 0 : velocity * VELOCITY_PROJECTION_SECONDS;
+      const targetOffset = baseOffset + swipeMovementRef.current + projected;
+
+      const offsets = resolvedSnapPoints.map((point) => point.offset);
+      const largestOffset = Math.max(...offsets);
+
+      // Past the most-closed snap point by the dismiss threshold, the gesture
+      // stops being a snap and becomes a dismissal.
+      if (targetOffset > largestOffset + swipeThreshold) {
+        store.setOpen(false, createChangeEventDetails(REASONS.swipe));
+        return;
+      }
+
+      const nextIndex = closestSnapPointIndex(offsets, targetOffset);
+      const next = resolvedSnapPoints[nextIndex];
+      if (next) {
+        setActiveSnapPoint(next.value, 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-popup')
+        .onBegin(() => {
+          setSwiping(true);
+        })
+        // The move that activates the pan arrives as `onStart`, and every move
+        // after it as `onUpdate` — the drawer has to follow both.
+        .onStart((event) => move(event.translationX, event.translationY))
+        .onUpdate((event) => move(event.translationX, event.translationY))
+        .onEnd((event) =>
+          release(event.translationX, event.translationY, event.velocityX, event.velocityY),
+        )
+        .onFinalize(() => {
+          setSwiping(false);
+          publishMovement(0);
+        })
+        // The handlers touch React state, so they must not run on the UI thread.
+        .runOnJS(true),
+    [testID, move, release, publishMovement],
+  );
+
+  const state: DrawerPopupState = {
+    open,
+    swiping,
+    swipeMovement,
+    swipeDirection,
+    snapPoint: activeSnapPoint ?? null,
+    snapPointOffset: activeSnapPointOffset,
+  };
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [{ ...props, onLayout: handleLayout }, 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 DrawerPopupState {
+  /**
+   * Whether the drawer is currently open.
+   */
+  open: boolean;
+  /**
+   * Whether a swipe is currently in progress.
+   */
+  swiping: boolean;
+  /**
+   * How far the current swipe has travelled towards `swipeDirection`, in pixels,
+   * and `0` whenever no swipe is in progress. Without snap points this is never
+   * negative; with them it goes negative as the drawer is dragged open.
+   */
+  swipeMovement: number;
+  /**
+   * The direction a swipe must travel to dismiss the drawer.
+   */
+  swipeDirection: DrawerSwipeDirection;
+  /**
+   * The currently active snap point, or `null` when there are none.
+   */
+  snapPoint: DrawerSnapPoint | null;
+  /**
+   * How far the active snap point pushes the popup off the edge, in pixels, or
+   * `null` when there are no snap points. Add `swipeMovement` to it to place the
+   * popup mid-drag.
+   */
+  snapPointOffset: number | null;
+}
+
+export interface DrawerPopupProps extends ZestUIComponentProps<typeof View, DrawerPopupState> {
+  /**
+   * How far a swipe must travel, in pixels, before it dismisses the drawer. With
+   * snap points, how far past the most-closed one a swipe must go to dismiss
+   * rather than snap.
+   * @default 40
+   */
+  swipeThreshold?: number | undefined;
+}
+
+export namespace DrawerPopup {
+  export type State = DrawerPopupState;
+  export type Props = DrawerPopupProps;
+}