@limonify/zest-ui 0.1.0

package/src/dialog/popup/DialogPopup.tsx

@@ -0,0 +1,37 @@
+'use client';
+import { View } from 'react-native';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../../types';
+import { useDialogPopupProps } from './useDialogPopupProps';
+
+/**
+ * A container for the dialog contents.
+ * Renders a `<View>`.
+ */
+export function DialogPopup(componentProps: DialogPopup.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const { open, props } = useDialogPopupProps();
+
+  const state: DialogPopupState = { open };
+
+  return useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [props, elementProps],
+  });
+}
+
+export interface DialogPopupState {
+  /**
+   * Whether the dialog is currently open.
+   */
+  open: boolean;
+}
+
+export interface DialogPopupProps extends ZestUIComponentProps<typeof View, DialogPopupState> {}
+
+export namespace DialogPopup {
+  export type State = DialogPopupState;
+  export type Props = DialogPopupProps;
+}

package/src/dialog/popup/useDialogPopupProps.ts

@@ -0,0 +1,33 @@
+'use client';
+import { useDialogRootContext } from '../root/DialogRootContext';
+import { useDialogPortalContext } from '../portal/DialogPortalContext';
+
+/**
+ * The state and element props shared by every popup built on the dialog store —
+ * `Dialog.Popup`, `AlertDialog.Popup` and `Drawer.Popup`.
+ */
+export function useDialogPopupProps() {
+  useDialogPortalContext();
+  const store = useDialogRootContext();
+
+  const open = store.useState('open');
+  const titleElementId = store.useState('titleElementId');
+  const descriptionElementId = store.useState('descriptionElementId');
+  const role = store.useState('role');
+
+  return {
+    store,
+    open,
+    props: {
+      role,
+      accessibilityViewIsModal: true,
+      accessibilityLabelledBy: titleElementId,
+      'aria-modal': true,
+      'aria-labelledby': titleElementId,
+      'aria-describedby': descriptionElementId,
+      // Claim the touch responder so presses inside the popup never reach
+      // the viewport's outside-press handler.
+      onStartShouldSetResponder: () => true,
+    },
+  };
+}

package/src/dialog/portal/DialogPortal.tsx

@@ -0,0 +1,59 @@
+'use client';
+import * as React from 'react';
+import { Modal, type NativeSyntheticEvent } from 'react-native';
+import { useDialogRootContext } from '../root/DialogRootContext';
+import { DialogPortalContext } from './DialogPortalContext';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A portal element that moves the popup to the top of the app.
+ *
+ * Implemented with React Native's `Modal`, which mounts its children at the
+ * root of the native view hierarchy, contains accessibility focus, and wires
+ * the Android hardware back button (and Escape on web) to `onRequestClose`.
+ * Rendering is headless: `animationType` is `"none"` so consumers own all
+ * animation.
+ */
+export function DialogPortal(props: DialogPortal.Props) {
+  const { children, keepMounted = false } = props;
+
+  const store = useDialogRootContext();
+  const open = store.useState('open');
+
+  const shouldRender = open || keepMounted;
+  if (!shouldRender) {
+    return null;
+  }
+
+  return (
+    <DialogPortalContext.Provider value={keepMounted}>
+      <Modal
+        transparent
+        visible={open}
+        animationType="none"
+        statusBarTranslucent
+        navigationBarTranslucent
+        onRequestClose={(event: NativeSyntheticEvent<unknown>) => {
+          store.setOpen(false, createChangeEventDetails(REASONS.escapeKey, event));
+        }}
+      >
+        {children}
+      </Modal>
+    </DialogPortalContext.Provider>
+  );
+}
+
+export interface DialogPortalProps {
+  children?: React.ReactNode;
+  /**
+   * Whether to keep the portal mounted (with the modal hidden) while the
+   * dialog is closed.
+   * @default false
+   */
+  keepMounted?: boolean | undefined;
+}
+
+export namespace DialogPortal {
+  export type Props = DialogPortalProps;
+}

package/src/dialog/portal/DialogPortalContext.ts

@@ -0,0 +1,12 @@
+'use client';
+import * as React from 'react';
+
+export const DialogPortalContext = React.createContext<boolean | undefined>(undefined);
+
+export function useDialogPortalContext() {
+  const context = React.useContext(DialogPortalContext);
+  if (context === undefined) {
+    throw new Error('Zest: <Dialog.Popup> and <Dialog.Viewport> must be used within <Dialog.Portal>.');
+  }
+  return context;
+}

package/src/dialog/root/DialogRoot.tsx

@@ -0,0 +1,98 @@
+'use client';
+import type * as React from 'react';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import type { REASONS } from '../../utils/reasons';
+import type { DialogHandle } from '../store/DialogHandle';
+import { useRenderDialogRoot } from './useRenderDialogRoot';
+
+/**
+ * Groups all parts of the dialog.
+ * Doesn't render its own element.
+ */
+export function DialogRoot<Payload = unknown>(props: DialogRoot.Props<Payload>) {
+  return useRenderDialogRoot(props, 'dialog');
+}
+
+export interface DialogRootState {}
+
+export interface DialogRootActions {
+  /**
+   * Unmounts the dialog without firing `onOpenChange`. Call it after an
+   * externally controlled closing animation finishes.
+   */
+  unmount: () => void;
+  /**
+   * Closes the dialog, reporting the `imperative-action` reason.
+   */
+  close: () => void;
+}
+
+export interface DialogRootProps<Payload = unknown> {
+  /**
+   * Whether the dialog is currently open.
+   */
+  open?: boolean | undefined;
+  /**
+   * Whether the dialog is initially open.
+   *
+   * To render a controlled dialog, use the `open` prop instead.
+   * @default false
+   */
+  defaultOpen?: boolean | undefined;
+  /**
+   * Event handler called when the dialog is opened or closed.
+   */
+  onOpenChange?:
+    | ((open: boolean, eventDetails: DialogRoot.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Whether to prevent the dialog from closing on presses outside the popup.
+   * @default false
+   */
+  disablePointerDismissal?: boolean | undefined;
+  /**
+   * A ref to imperative actions.
+   */
+  actionsRef?: React.RefObject<DialogRoot.Actions | null> | undefined;
+  /**
+   * A handle associating this dialog with triggers rendered outside it, and
+   * letting it be opened and closed imperatively. Create one with
+   * `Dialog.createHandle()`.
+   */
+  handle?: DialogHandle<Payload> | undefined;
+  /**
+   * The id of the trigger the dialog is associated with. Useful together with
+   * the `open` prop, to control which trigger a controlled dialog belongs to.
+   */
+  triggerId?: string | null | undefined;
+  /**
+   * The id of the trigger the dialog is initially associated with. Useful
+   * together with `defaultOpen`.
+   */
+  defaultTriggerId?: string | null | undefined;
+  /**
+   * The content of the dialog.
+   *
+   * Pass a function to receive the payload the dialog was opened with, via the
+   * handle's `openWithPayload()` or a trigger's `payload` prop.
+   */
+  children?: React.ReactNode | ((payload: Payload) => React.ReactNode);
+}
+
+export type DialogRootChangeEventReason =
+  | typeof REASONS.triggerPress
+  | typeof REASONS.outsidePress
+  | typeof REASONS.escapeKey
+  | typeof REASONS.closePress
+  | typeof REASONS.imperativeAction
+  | typeof REASONS.none;
+
+export type DialogRootChangeEventDetails = ZestChangeEventDetails<DialogRootChangeEventReason>;
+
+export namespace DialogRoot {
+  export type State = DialogRootState;
+  export type Props<Payload = unknown> = DialogRootProps<Payload>;
+  export type Actions = DialogRootActions;
+  export type ChangeEventReason = DialogRootChangeEventReason;
+  export type ChangeEventDetails = DialogRootChangeEventDetails;
+}

package/src/dialog/root/DialogRootContext.ts

@@ -0,0 +1,19 @@
+'use client';
+import * as React from 'react';
+import type { DialogStore } from '../store/DialogStore';
+
+// `any` rather than a concrete reason: the store is generic over the reasons its
+// variant can emit, and typing the context with one variant's union would make
+// the others' stores unassignable. See DialogStore.
+export const DialogRootContext = React.createContext<DialogStore<any> | undefined>(undefined);
+
+export function useDialogRootContext() {
+  const context = React.useContext(DialogRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: DialogRootContext is missing. Dialog parts must be placed within <Dialog.Root>.',
+    );
+  }
+
+  return context;
+}

package/src/dialog/root/useRenderDialogRoot.tsx

@@ -0,0 +1,63 @@
+'use client';
+import * as React from 'react';
+import { useRefWithInit } from '../../hooks/useRefWithInit';
+import { usePopupRootHandle } from '../../utils/popups/usePopupRootHandle';
+import { DialogStore } from '../store/DialogStore';
+import type { DialogRootProps } from './DialogRoot';
+import { DialogRootContext } from './DialogRootContext';
+
+export type DialogRootMode = 'dialog' | 'alert-dialog';
+
+/**
+ * The shared Root implementation behind `Dialog.Root` and `AlertDialog.Root`.
+ *
+ * An alert dialog is a dialog that never dismisses on an outside press and
+ * announces itself as `alertdialog`.
+ */
+export function useRenderDialogRoot<Payload = unknown>(
+  props: DialogRootProps<Payload>,
+  mode: DialogRootMode = 'dialog',
+) {
+  const {
+    actionsRef,
+    children,
+    defaultOpen = false,
+    defaultTriggerId = null,
+    disablePointerDismissal: disablePointerDismissalProp = false,
+    handle,
+    onOpenChange,
+    open,
+    triggerId,
+  } = props;
+
+  const isAlertDialog = mode === 'alert-dialog';
+  const disablePointerDismissal = isAlertDialog || disablePointerDismissalProp;
+  const role: 'dialog' | 'alertdialog' = isAlertDialog ? 'alertdialog' : 'dialog';
+
+  const store = useRefWithInit(
+    () =>
+      new DialogStore({
+        open: defaultOpen,
+        openProp: open,
+        disablePointerDismissal,
+        role,
+        triggerId: defaultTriggerId,
+        triggerIdProp: triggerId,
+      }),
+  ).current;
+
+  store.useControlledProp('openProp', open);
+  store.useControlledProp('triggerIdProp', triggerId);
+  store.useContextCallback('onOpenChange', onOpenChange);
+  store.useSyncedValues({ disablePointerDismissal, role });
+
+  usePopupRootHandle({ store, handle, actionsRef });
+
+  const payload = store.useState('payload') as Payload;
+
+  return (
+    <DialogRootContext.Provider value={store}>
+      {typeof children === 'function' ? children(payload) : children}
+    </DialogRootContext.Provider>
+  );
+}

package/src/dialog/store/DialogHandle.ts

@@ -0,0 +1,83 @@
+import { DialogStore } from './DialogStore';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import { BasePopupHandle } from '../../utils/popups/BasePopupHandle';
+
+/**
+ * Controls a dialog imperatively, and associates `Dialog.Trigger`s rendered
+ * outside the root with it. Create one with `Dialog.createHandle()` and pass it
+ * to the root's and the triggers' `handle` prop.
+ *
+ * The imperative methods only take effect while a root using this handle is
+ * mounted; calls made before one attaches (or after it unmounts) are ignored.
+ */
+export class DialogHandle<Payload = unknown> extends BasePopupHandle<
+  DialogStore<any>,
+  DialogStore<any>
+> {
+  constructor(componentName: string = 'Dialog') {
+    // An inert, closed store for detached triggers to register into while no root
+    // is mounted. `false`: a dialog is not anchored, so opening it by an unknown
+    // trigger id is a warning rather than an error.
+    super(new DialogStore(), componentName, false);
+  }
+
+  /**
+   * Opens the dialog, optionally associating it with a trigger.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   *
+   * @param triggerId The id of a mounted `Dialog.Trigger` carrying this handle,
+   * or `null` to open without associating one.
+   */
+  open(triggerId: string | null = null) {
+    this.openByTrigger(triggerId);
+  }
+
+  /**
+   * Opens the dialog with a payload, without associating it with a trigger. The
+   * payload reaches the root's children when they are a function.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   */
+  openWithPayload(payload: Payload) {
+    const attachedStore = this.attachedStore;
+
+    if (attachedStore === null) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          'Zest: DialogHandle.openWithPayload() was called while no root using this handle is mounted. ' +
+            'The call and its payload were ignored; mount a root with this handle before opening it imperatively.',
+        );
+      }
+      return;
+    }
+
+    attachedStore.set('payload', payload);
+    attachedStore.setOpen(true, createChangeEventDetails(REASONS.imperativeAction));
+  }
+
+  /**
+   * Closes the dialog.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   */
+  close() {
+    this.closePopup();
+  }
+
+  /**
+   * Whether the dialog is open. `false` while no root is attached.
+   */
+  get isOpen() {
+    return this.attachedStore?.select('open') ?? false;
+  }
+}
+
+/**
+ * Creates a handle that connects a `Dialog.Root` to `Dialog.Trigger`s rendered
+ * outside it, and controls it imperatively.
+ */
+export function createDialogHandle<Payload = unknown>(): DialogHandle<Payload> {
+  return new DialogHandle<Payload>();
+}

package/src/dialog/store/DialogStore.ts

@@ -0,0 +1,110 @@
+import { createSelector } from '../../store/createSelector';
+import { ReactStore } from '../../store/ReactStore';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { PopupTriggerMap } from '../../utils/popups/PopupTriggerMap';
+import type { DialogRootChangeEventReason } from '../root/DialogRoot';
+
+export type State = {
+  /**
+   * The uncontrolled open state. Consumers must read through the `open`
+   * selector, which resolves the controlled prop first.
+   */
+  open: boolean;
+  /**
+   * The controlled `open` prop, when provided. Takes precedence over the
+   * internal `open` state (mirrors Base UI's popup store).
+   */
+  openProp: boolean | undefined;
+  titleElementId: string | undefined;
+  descriptionElementId: string | undefined;
+  disablePointerDismissal: boolean;
+  /**
+   * `alertdialog` for AlertDialog, which reuses this store and every Dialog part.
+   */
+  role: 'dialog' | 'alertdialog';
+  /**
+   * The payload of the trigger the dialog was opened by, handed to the root's
+   * children when they are a function.
+   */
+  payload: unknown;
+  /**
+   * The id of the trigger the dialog is associated with, or `null` for none.
+   */
+  triggerId: string | null;
+  /**
+   * The controlled `triggerId` prop, when provided.
+   */
+  triggerIdProp: string | null | undefined;
+};
+
+type Context<Reason extends string> = {
+  onOpenChange:
+    | ((open: boolean, eventDetails: ZestChangeEventDetails<Reason>) => void)
+    | undefined;
+  /**
+   * Every trigger bound to this dialog, by id. A handle resolves `open(id)`
+   * through this, which is what lets a trigger rendered outside the root open it.
+   */
+  triggerNodes: PopupTriggerMap;
+};
+
+const selectors = {
+  open: createSelector((state: State) => state.openProp ?? state.open),
+  titleElementId: createSelector((state: State) => state.titleElementId),
+  payload: createSelector((state: State) => state.payload),
+  triggerId: createSelector((state: State) => state.triggerIdProp ?? state.triggerId),
+  descriptionElementId: createSelector((state: State) => state.descriptionElementId),
+  disablePointerDismissal: createSelector((state: State) => state.disablePointerDismissal),
+  role: createSelector((state: State) => state.role),
+};
+
+/**
+ * React Native adaptation of Base UI's DialogStore.
+ *
+ * `Dialog`, `AlertDialog` and `Drawer` all share this store but do not dismiss
+ * for the same set of reasons — only a drawer can be swiped away. The store is
+ * generic over that union so no variant advertises a reason it cannot emit, and
+ * `DialogRootContext` erases it to `any` (the same trick the group components
+ * use) so the parts stay non-generic.
+ *
+ * TODO(later): nested dialog counting, openMethod interaction typing,
+ * transitions (`mounted`/`transitionStatus`), handles/payloads.
+ */
+export class DialogStore<Reason extends string = DialogRootChangeEventReason> extends ReactStore<
+  Readonly<State>,
+  Context<Reason>,
+  typeof selectors
+> {
+  constructor(initialState?: Partial<State>) {
+    super(
+      {
+        open: false,
+        openProp: undefined,
+        titleElementId: undefined,
+        descriptionElementId: undefined,
+        disablePointerDismissal: false,
+        role: 'dialog',
+        payload: undefined,
+        triggerId: null,
+        triggerIdProp: undefined,
+        ...initialState,
+      },
+      { onOpenChange: undefined, triggerNodes: new PopupTriggerMap() },
+      selectors,
+    );
+  }
+
+  public setOpen = (nextOpen: boolean, eventDetails: ZestChangeEventDetails<Reason>) => {
+    if (nextOpen === this.select('open')) {
+      return;
+    }
+
+    this.context.onOpenChange?.(nextOpen, eventDetails);
+
+    if (eventDetails.isCanceled) {
+      return;
+    }
+
+    this.set('open', nextOpen);
+  };
+}

package/src/dialog/title/DialogTitle.tsx

@@ -0,0 +1,34 @@
+'use client';
+import { Text } from 'react-native';
+import { useDialogRootContext } from '../root/DialogRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useId } from '../../hooks/useId';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * A heading that labels the dialog.
+ * Renders a `<Text>` with a heading role.
+ */
+export function DialogTitle(componentProps: DialogTitle.Props) {
+  const { render, className, style, nativeID: idProp, ref, ...elementProps } = componentProps;
+
+  const store = useDialogRootContext();
+
+  const id = useId(idProp ?? undefined);
+
+  store.useSyncedValueWithCleanup('titleElementId', id);
+
+  return useRenderElement(Text, componentProps, {
+    ref,
+    props: [{ nativeID: id, role: 'heading' as const }, elementProps],
+  });
+}
+
+export interface DialogTitleProps extends ZestUIComponentProps<typeof Text, DialogTitleState> {}
+
+export interface DialogTitleState {}
+
+export namespace DialogTitle {
+  export type Props = DialogTitleProps;
+  export type State = DialogTitleState;
+}