@limonify/zest-ui 0.1.0

package/src/popover/index.ts

@@ -0,0 +1,14 @@
+export * as Popover from './index.parts';
+
+export type * from './root/PopoverRoot';
+export { createPopoverHandle, PopoverHandle } from './store/PopoverHandle';
+export type * from './trigger/PopoverTrigger';
+export type * from './portal/PopoverPortal';
+export type * from './backdrop/PopoverBackdrop';
+export type * from './positioner/PopoverPositioner';
+export type * from './popup/PopoverPopup';
+export type * from './arrow/PopoverArrow';
+export type * from './title/PopoverTitle';
+export type * from './description/PopoverDescription';
+export type * from './close/PopoverClose';
+export { usePopoverRootContext } from './root/PopoverRootContext';

package/src/popover/popup/PopoverPopup.tsx

@@ -0,0 +1,63 @@
+'use client';
+import { View } from 'react-native';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { usePopoverPositionerContext } from '../positioner/PopoverPositionerContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { Align, Side } from '../../utils/useAnchorPositioning';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * A container for the popover contents.
+ * Renders a `<View>`.
+ */
+export function PopoverPopup(componentProps: PopoverPopup.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const store = usePopoverRootContext();
+  const { side, align } = usePopoverPositionerContext();
+
+  const open = store.useState('open');
+  const titleElementId = store.useState('titleElementId');
+  const descriptionElementId = store.useState('descriptionElementId');
+
+  const state: PopoverPopupState = { open, side, align };
+
+  return useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        role: 'dialog' as const,
+        accessibilityLabelledBy: titleElementId,
+        'aria-labelledby': titleElementId,
+        'aria-describedby': descriptionElementId,
+        // Claim the touch responder so presses inside the popup never reach the
+        // backdrop's outside-press handler.
+        onStartShouldSetResponder: () => true,
+      },
+      elementProps,
+    ],
+  });
+}
+
+export interface PopoverPopupState {
+  /**
+   * Whether the popover is currently open.
+   */
+  open: boolean;
+  /**
+   * The side the popup was actually placed on, after collision handling.
+   */
+  side: Side;
+  /**
+   * The alignment the popup was actually placed with.
+   */
+  align: Align;
+}
+
+export interface PopoverPopupProps extends ZestUIComponentProps<typeof View, PopoverPopupState> {}
+
+export namespace PopoverPopup {
+  export type State = PopoverPopupState;
+  export type Props = PopoverPopupProps;
+}

package/src/popover/portal/PopoverPortal.tsx

@@ -0,0 +1,60 @@
+'use client';
+import * as React from 'react';
+import { Modal, type NativeSyntheticEvent } from 'react-native';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { PopoverPortalContext } from './PopoverPortalContext';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A portal element that moves the popup to the top of the app.
+ *
+ * Like `Dialog.Portal`, this is React Native's `Modal`. A state-lifting portal
+ * host would drop the React context of the declaration site; `Modal` keeps its
+ * children in the same React tree, so `Popover.Popup` still sees the root store.
+ *
+ * `statusBarTranslucent` matters for positioning: it makes the modal's origin
+ * the top of the screen, which is the coordinate space `useAnchorPositioning`
+ * resolves the anchor into.
+ */
+export function PopoverPortal(props: PopoverPortal.Props) {
+  const { children, keepMounted = false } = props;
+
+  const store = usePopoverRootContext();
+  const open = store.useState('open');
+
+  const shouldRender = open || keepMounted;
+  if (!shouldRender) {
+    return null;
+  }
+
+  return (
+    <PopoverPortalContext.Provider value={keepMounted}>
+      <Modal
+        transparent
+        visible={open}
+        animationType="none"
+        statusBarTranslucent
+        navigationBarTranslucent
+        onRequestClose={(event: NativeSyntheticEvent<unknown>) => {
+          store.setOpen(false, createChangeEventDetails(REASONS.escapeKey, event));
+        }}
+      >
+        {children}
+      </Modal>
+    </PopoverPortalContext.Provider>
+  );
+}
+
+export interface PopoverPortalProps {
+  children?: React.ReactNode;
+  /**
+   * Whether to keep the portal mounted while the popover is closed.
+   * @default false
+   */
+  keepMounted?: boolean | undefined;
+}
+
+export namespace PopoverPortal {
+  export type Props = PopoverPortalProps;
+}

package/src/popover/portal/PopoverPortalContext.ts

@@ -0,0 +1,15 @@
+'use client';
+import * as React from 'react';
+
+export const PopoverPortalContext = React.createContext<boolean | undefined>(undefined);
+
+export function usePopoverPortalContext() {
+  const context = React.useContext(PopoverPortalContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: PopoverPortalContext is missing. <Popover.Positioner> must be placed within <Popover.Portal>.',
+    );
+  }
+
+  return context;
+}

package/src/popover/positioner/PopoverPositioner.tsx

@@ -0,0 +1,126 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { usePopoverPortalContext } from '../portal/PopoverPortalContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import {
+  useAnchorPositioning,
+  type Align,
+  type Side,
+  type UseAnchorPositioningSharedParameters,
+} from '../../utils/useAnchorPositioning';
+import type { ZestUIComponentProps } from '../../types';
+import { PopoverPositionerContext } from './PopoverPositionerContext';
+
+/**
+ * Positions the popover against the trigger.
+ * Renders a `<View>`.
+ */
+export function PopoverPositioner(componentProps: PopoverPositioner.Props) {
+  const {
+    align = 'center',
+    alignOffset = 0,
+    arrowPadding = 5,
+    className,
+    collisionPadding = 5,
+    render,
+    side = 'bottom',
+    sideOffset = 0,
+    sticky = false,
+    style,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  usePopoverPortalContext();
+  const store = usePopoverRootContext();
+  const open = store.useState('open');
+  const triggerNode = store.useState('triggerNode');
+
+  const positioning = useAnchorPositioning({
+    align,
+    alignOffset,
+    arrowPadding,
+    collisionPadding,
+    side,
+    sideOffset,
+    sticky,
+  });
+
+  const { arrowRef, arrowStyles, positionerStyles, refs, update } = positioning;
+
+  // The anchor is measured from the trigger, which lives outside the portal.
+  useIsoLayoutEffect(() => {
+    refs.setReference(triggerNode ?? null);
+  }, [refs, triggerNode]);
+
+  // Nothing observes layout globally, so the trigger asks for a reposition
+  // through the store when it moves.
+  useIsoLayoutEffect(() => {
+    store.set('update', update);
+    return () => {
+      store.set('update', undefined);
+    };
+  }, [store, update]);
+
+  const mergedRef = useMergedRefs(ref, refs.setFloating);
+
+  const state: PopoverPositionerState = {
+    open,
+    side: positioning.side,
+    align: positioning.align,
+  };
+
+  const contextValue: PopoverPositionerContext = React.useMemo(
+    () => ({ side: positioning.side, align: positioning.align, arrowRef, arrowStyles }),
+    [positioning.side, positioning.align, arrowRef, arrowStyles],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref: mergedRef,
+    props: [
+      {
+        style: positionerStyles,
+        onLayout() {
+          // The popup's own size feeds flip/shift, so recompute once it is laid out.
+          update();
+        },
+      },
+      elementProps,
+    ],
+  });
+
+  return (
+    <PopoverPositionerContext.Provider value={contextValue}>
+      {element}
+    </PopoverPositionerContext.Provider>
+  );
+}
+
+export interface PopoverPositionerState {
+  /**
+   * Whether the popover is currently open.
+   */
+  open: boolean;
+  /**
+   * The side the popup was actually placed on, after collision handling.
+   */
+  side: Side;
+  /**
+   * The alignment the popup was actually placed with.
+   */
+  align: Align;
+}
+
+export interface PopoverPositionerProps
+  extends UseAnchorPositioningSharedParameters,
+    ZestUIComponentProps<typeof View, PopoverPositionerState> {}
+
+export namespace PopoverPositioner {
+  export type State = PopoverPositionerState;
+  export type Props = PopoverPositionerProps;
+}

package/src/popover/positioner/PopoverPositionerContext.ts

@@ -0,0 +1,31 @@
+'use client';
+import * as React from 'react';
+import type { Align, Side } from '../../utils/useAnchorPositioning';
+
+export interface PopoverPositionerContext {
+  /**
+   * The side the popup was actually placed on, after collision handling.
+   */
+  side: Side;
+  /**
+   * The alignment the popup was actually placed with.
+   */
+  align: Align;
+  arrowRef: React.RefObject<unknown>;
+  arrowStyles: { left?: number; top?: number };
+}
+
+export const PopoverPositionerContext = React.createContext<PopoverPositionerContext | undefined>(
+  undefined,
+);
+
+export function usePopoverPositionerContext() {
+  const context = React.useContext(PopoverPositionerContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: PopoverPositionerContext is missing. <Popover.Popup> must be placed within <Popover.Positioner>.',
+    );
+  }
+
+  return context;
+}

package/src/popover/root/PopoverRoot.tsx

@@ -0,0 +1,133 @@
+'use client';
+import type * as React from 'react';
+import { useRefWithInit } from '../../hooks/useRefWithInit';
+import { usePopupRootHandle } from '../../utils/popups/usePopupRootHandle';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import type { REASONS } from '../../utils/reasons';
+import { PopoverStore } from '../store/PopoverStore';
+import type { PopoverHandle } from '../store/PopoverHandle';
+import { PopoverRootContext } from './PopoverRootContext';
+
+/**
+ * Groups all parts of the popover.
+ * Doesn't render its own element.
+ */
+export function PopoverRoot<Payload = unknown>(props: PopoverRoot.Props<Payload>) {
+  const {
+    actionsRef,
+    children,
+    defaultOpen = false,
+    defaultTriggerId = null,
+    disablePointerDismissal = false,
+    handle,
+    onOpenChange,
+    open,
+    triggerId,
+  } = props;
+
+  const store = useRefWithInit(
+    () =>
+      new PopoverStore({
+        open: defaultOpen,
+        openProp: open,
+        triggerId: defaultTriggerId,
+        triggerIdProp: triggerId,
+        disablePointerDismissal,
+      }),
+  ).current;
+
+  store.useControlledProp('openProp', open);
+  store.useControlledProp('triggerIdProp', triggerId);
+  store.useContextCallback('onOpenChange', onOpenChange);
+  store.useSyncedValues({ disablePointerDismissal });
+
+  usePopupRootHandle({ store, handle, actionsRef });
+
+  const payload = store.useState('payload') as Payload;
+
+  return (
+    <PopoverRootContext.Provider value={store}>
+      {typeof children === 'function' ? children(payload) : children}
+    </PopoverRootContext.Provider>
+  );
+}
+
+export interface PopoverRootState {}
+
+export interface PopoverRootActions {
+  /**
+   * Unmounts the popover without firing `onOpenChange`. Call it after an externally
+   * controlled closing animation finishes.
+   */
+  unmount: () => void;
+  /**
+   * Closes the popover, reporting the `imperative-action` reason.
+   */
+  close: () => void;
+}
+
+export interface PopoverRootProps<Payload = unknown> {
+  /**
+   * Whether the popover is currently open.
+   */
+  open?: boolean | undefined;
+  /**
+   * Whether the popover is initially open.
+   *
+   * To render a controlled popover, use the `open` prop instead.
+   * @default false
+   */
+  defaultOpen?: boolean | undefined;
+  /**
+   * Event handler called when the popover is opened or closed.
+   */
+  onOpenChange?:
+    | ((open: boolean, eventDetails: PopoverRoot.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Whether to prevent the popover from closing on presses outside the popup.
+   * @default false
+   */
+  disablePointerDismissal?: boolean | undefined;
+  /**
+   * A ref to imperative actions.
+   */
+  actionsRef?: React.RefObject<PopoverRoot.Actions | null> | undefined;
+  /**
+   * A handle associating this popover with triggers rendered outside it, and letting
+   * it be opened and closed imperatively. Create one with `Popover.createHandle()`.
+   */
+  handle?: PopoverHandle<Payload> | undefined;
+  /**
+   * The id of the trigger the popover is anchored to and associated with.
+   */
+  triggerId?: string | null | undefined;
+  /**
+   * The id of the trigger the popover is initially associated with.
+   */
+  defaultTriggerId?: string | null | undefined;
+  /**
+   * The content of the popover.
+   *
+   * Pass a function to receive the payload the popover was opened with.
+   */
+  children?: React.ReactNode | ((payload: Payload) => React.ReactNode);
+}
+
+export type PopoverRootChangeEventReason =
+  | typeof REASONS.triggerPress
+  | typeof REASONS.outsidePress
+  | typeof REASONS.escapeKey
+  | typeof REASONS.closePress
+  | typeof REASONS.imperativeAction
+  | typeof REASONS.none;
+
+export type PopoverRootChangeEventDetails = ZestChangeEventDetails<PopoverRootChangeEventReason>;
+
+export namespace PopoverRoot {
+  export type State = PopoverRootState;
+  export type Props<Payload = unknown> = PopoverRootProps<Payload>;
+  export type Actions = PopoverRootActions;
+  export type ChangeEventReason = PopoverRootChangeEventReason;
+  export type ChangeEventDetails = PopoverRootChangeEventDetails;
+}

package/src/popover/root/PopoverRootContext.ts

@@ -0,0 +1,16 @@
+'use client';
+import * as React from 'react';
+import type { PopoverStore } from '../store/PopoverStore';
+
+export const PopoverRootContext = React.createContext<PopoverStore | undefined>(undefined);
+
+export function usePopoverRootContext() {
+  const context = React.useContext(PopoverRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: PopoverRootContext is missing. Popover parts must be placed within <Popover.Root>.',
+    );
+  }
+
+  return context;
+}

package/src/popover/store/PopoverHandle.ts

@@ -0,0 +1,67 @@
+import { PopoverStore } from './PopoverStore';
+import { BasePopupHandle } from '../../utils/popups/BasePopupHandle';
+
+/**
+ * Controls a popover imperatively, and associates `Popover.Trigger`s rendered outside
+ * the root with it. Create one with `Popover.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.
+ */
+// `Payload` is unused in the class body but load-bearing in the public API: a
+// `Popover.Root`'s `handle?: PopoverHandle<Payload>` prop is what infers the
+// payload type its `children(payload)` receives.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export class PopoverHandle<Payload = unknown> extends BasePopupHandle<PopoverStore, PopoverStore> {
+  constructor() {
+    // `true`: a popover is anchored, so opening it by an unknown trigger id is an
+    // error rather than a warning — there would be nothing to anchor to.
+    super(new PopoverStore(), 'Popover', true);
+  }
+
+  /**
+   * Points the positioner at the trigger the popover was opened by. Without this an
+   * imperative open would anchor to whatever was last pressed.
+   */
+  protected override associateTrigger(store: PopoverStore, triggerNode: unknown) {
+    if (triggerNode !== undefined) {
+      store.set('triggerNode', triggerNode);
+    }
+  }
+
+  /**
+   * Opens the popover, anchored to the trigger with the given id.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   *
+   * @param triggerId The `nativeID` of a mounted `Popover.Trigger` carrying this handle.
+   */
+  open(triggerId: string) {
+    this.openByTrigger(triggerId);
+  }
+
+  /**
+   * Closes the popover.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   */
+  close() {
+    this.closePopup();
+  }
+
+  /**
+   * Whether the popover is open. `false` while no root is attached.
+   */
+  get isOpen() {
+    return this.attachedStore?.select('open') ?? false;
+  }
+}
+
+/**
+ * Creates a handle that connects a `Popover.Root` to `Popover.Trigger`s rendered
+ * outside it, and controls it imperatively.
+ */
+export function createPopoverHandle<Payload = unknown>(): PopoverHandle<Payload> {
+  return new PopoverHandle<Payload>();
+}

package/src/popover/store/PopoverStore.ts

@@ -0,0 +1,102 @@
+import { createSelector } from '../../store/createSelector';
+import { ReactStore } from '../../store/ReactStore';
+import { PopupTriggerMap } from '../../utils/popups/PopupTriggerMap';
+import type { PopoverRoot } from '../root/PopoverRoot';
+
+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;
+  /**
+   * The anchor's native node. The Positioner lives inside the portal, in a
+   * different subtree from the Trigger, so the store is what carries it across.
+   */
+  triggerNode: unknown;
+  /**
+   * Set by the Positioner so the Trigger can request a reposition when it is
+   * laid out. React Native has no `autoUpdate`.
+   */
+  update: (() => void) | undefined;
+  /**
+   * The payload of the trigger the popup was opened by, handed to the root's
+   * children when they are a function.
+   */
+  payload: unknown;
+  /**
+   * The id of the trigger the popup is associated with, or `null` for none.
+   */
+  triggerId: string | null;
+  /**
+   * The controlled `triggerId` prop, when provided.
+   */
+  triggerIdProp: string | null | undefined;
+};
+
+type Context = {
+  onOpenChange: ((open: boolean, eventDetails: PopoverRoot.ChangeEventDetails) => void) | undefined;
+  /**
+   * Every trigger bound to this popup, 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),
+  descriptionElementId: createSelector((state: State) => state.descriptionElementId),
+  disablePointerDismissal: createSelector((state: State) => state.disablePointerDismissal),
+  triggerNode: createSelector((state: State) => state.triggerNode),
+  update: createSelector((state: State) => state.update),
+  payload: createSelector((state: State) => state.payload),
+  triggerId: createSelector((state: State) => state.triggerIdProp ?? state.triggerId),
+};
+
+/**
+ * React Native adaptation of Base UI's PopoverStore.
+ */
+export class PopoverStore extends ReactStore<Readonly<State>, Context, typeof selectors> {
+  constructor(initialState?: Partial<State>) {
+    super(
+      {
+        open: false,
+        openProp: undefined,
+        titleElementId: undefined,
+        descriptionElementId: undefined,
+        disablePointerDismissal: false,
+        triggerNode: null,
+        update: undefined,
+        payload: undefined,
+        triggerId: null,
+        triggerIdProp: undefined,
+        ...initialState,
+      },
+      { onOpenChange: undefined, triggerNodes: new PopupTriggerMap() },
+      selectors,
+    );
+  }
+
+  public setOpen = (nextOpen: boolean, eventDetails: PopoverRoot.ChangeEventDetails) => {
+    if (nextOpen === this.select('open')) {
+      return;
+    }
+
+    this.context.onOpenChange?.(nextOpen, eventDetails);
+
+    if (eventDetails.isCanceled) {
+      return;
+    }
+
+    this.set('open', nextOpen);
+  };
+}

package/src/popover/title/PopoverTitle.tsx

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