@limonify/zest-ui 0.1.0

package/src/utils/popups/PopupTriggerMap.ts

@@ -0,0 +1,48 @@
+/**
+ * Keeps track of popup trigger nodes by their ids.
+ *
+ * Ported from upstream, with `Element` widened to `unknown`: a React Native
+ * trigger is a native node, and the map only ever stores and hands it back — the
+ * same way the popup stores already carry `triggerNode`.
+ *
+ * Lookups iterate the id map; trigger counts are single digits, so linear scans
+ * on event-frequency paths are cheaper than maintaining a parallel Set.
+ */
+export class PopupTriggerMap {
+  private idMap = new Map<string, unknown>();
+
+  /**
+   * Adds a trigger node under the given id.
+   *
+   * The node is assumed not to be registered under multiple ids.
+   */
+  public add(id: string, node: unknown) {
+    if (process.env.NODE_ENV !== 'production') {
+      for (const [existingId, existingNode] of this.idMap) {
+        if (existingNode === node && existingId !== id) {
+          throw new Error(
+            'Zest: A trigger cannot be registered under multiple ids in PopupTriggerMap.',
+          );
+        }
+      }
+    }
+
+    this.idMap.set(id, node);
+  }
+
+  public delete(id: string) {
+    this.idMap.delete(id);
+  }
+
+  public getById(id: string): unknown {
+    return this.idMap.get(id);
+  }
+
+  public entries(): IterableIterator<[string, unknown]> {
+    return this.idMap.entries();
+  }
+
+  public get size(): number {
+    return this.idMap.size;
+  }
+}

package/src/utils/popups/usePopupHandleStore.ts

@@ -0,0 +1,32 @@
+'use client';
+import * as React from 'react';
+import type { PopupHandleStoreProvider } from './BasePopupHandle';
+
+const NOOP = () => () => {};
+
+/**
+ * Reads the store a handle currently exposes, and follows it as roots attach and
+ * detach: while none is attached the handle exposes its fallback store; once one
+ * does, subscribers re-render and read the live root store.
+ *
+ * Returns `undefined` when no handle is given, so callers fall back to their root
+ * context.
+ *
+ * Upstream reaches for the `use-sync-external-store` shim; zest is React 19-only
+ * and uses `React.useSyncExternalStore` directly.
+ */
+export function usePopupHandleStore<HandleStore>(
+  handle: PopupHandleStoreProvider<HandleStore> | undefined,
+): HandleStore | undefined {
+  const subscribe = React.useCallback(
+    (listener: () => void) => (handle === undefined ? NOOP() : handle.subscribeStore(listener)),
+    [handle],
+  );
+
+  const getSnapshot = React.useCallback(
+    () => (handle === undefined ? undefined : handle.store),
+    [handle],
+  );
+
+  return React.useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/utils/popups/usePopupRootHandle.ts

@@ -0,0 +1,71 @@
+'use client';
+import type * as React from 'react';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import { createChangeEventDetails } from '../createChangeEventDetails';
+import { REASONS } from '../reasons';
+import type { BasePopupHandle } from './BasePopupHandle';
+
+export interface PopupRootActions {
+  /**
+   * Unmounts the popup without firing `onOpenChange`. Call it after an
+   * externally controlled closing animation finishes.
+   */
+  unmount: () => void;
+  /**
+   * Closes the popup, reporting the `imperative-action` reason.
+   */
+  close: () => void;
+}
+
+interface PopupRootHandleStore {
+  set(key: 'open', value: boolean): void;
+  setOpen(open: boolean, eventDetails: any): void;
+}
+
+/**
+ * Wires a root's store to its `handle` and `actionsRef`.
+ *
+ * Shared by every popup root that supports them (Dialog and its variants,
+ * Popover, Menu) — the wiring is identical, only the store type differs.
+ */
+export function usePopupRootHandle<Store extends PopupRootHandleStore>(params: {
+  store: Store;
+  handle: BasePopupHandle<any, any> | undefined;
+  actionsRef: React.RefObject<PopupRootActions | null> | undefined;
+}) {
+  const { store, handle, actionsRef } = params;
+
+  // Points the handle at this root, so its imperative methods and any detached
+  // triggers reach this store rather than the handle's inert fallback.
+  useIsoLayoutEffect(() => {
+    if (!handle) {
+      return undefined;
+    }
+
+    return handle.attachStore(store as never);
+  }, [handle, store]);
+
+  // Sets the uncontrolled key directly rather than going through `setOpen`:
+  // unmounting is not a state change the consumer asked about, and it must not
+  // fire `onOpenChange` a second time after their closing animation.
+  const unmount = useStableCallback(() => {
+    store.set('open', false);
+  });
+
+  const close = useStableCallback(() => {
+    store.setOpen(false, createChangeEventDetails(REASONS.imperativeAction));
+  });
+
+  useIsoLayoutEffect(() => {
+    if (!actionsRef) {
+      return undefined;
+    }
+
+    actionsRef.current = { unmount, close };
+
+    return () => {
+      actionsRef.current = null;
+    };
+  }, [actionsRef, unmount, close]);
+}

package/src/utils/reason-parts.ts

@@ -0,0 +1,39 @@
+export const none = 'none' as const;
+
+export const triggerPress = 'trigger-press' as const;
+export const triggerHover = 'trigger-hover' as const;
+export const triggerFocus = 'trigger-focus' as const;
+
+export const outsidePress = 'outside-press' as const;
+export const itemPress = 'item-press' as const;
+export const closePress = 'close-press' as const;
+export const linkPress = 'link-press' as const;
+export const clearPress = 'clear-press' as const;
+export const chipRemovePress = 'chip-remove-press' as const;
+export const trackPress = 'track-press' as const;
+export const incrementPress = 'increment-press' as const;
+export const decrementPress = 'decrement-press' as const;
+
+export const inputChange = 'input-change' as const;
+export const inputClear = 'input-clear' as const;
+export const inputBlur = 'input-blur' as const;
+export const inputPaste = 'input-paste' as const;
+export const inputPress = 'input-press' as const;
+
+export const focusOut = 'focus-out' as const;
+export const escapeKey = 'escape-key' as const;
+export const listNavigation = 'list-navigation' as const;
+export const keyboard = 'keyboard' as const;
+
+export const pointer = 'pointer' as const;
+export const drag = 'drag' as const;
+export const wheel = 'wheel' as const;
+export const scrub = 'scrub' as const;
+
+export const cancelOpen = 'cancel-open' as const;
+export const siblingOpen = 'sibling-open' as const;
+export const disabled = 'disabled' as const;
+export const missing = 'missing' as const;
+export const initial = 'initial' as const;
+export const imperativeAction = 'imperative-action' as const;
+export const swipe = 'swipe' as const;

package/src/utils/reasons.ts

@@ -0,0 +1,5 @@
+import * as REASONS from './reason-parts';
+
+export { REASONS };
+export type ZestEventReasons = typeof REASONS;
+export type ZestEventReason = ZestEventReasons[keyof ZestEventReasons];

package/src/utils/resolveClassName.ts

@@ -0,0 +1,10 @@
+/**
+ * If the provided className is a string, it will be returned as is.
+ * Otherwise, the function will call the className function with the state as the first argument.
+ */
+export function resolveClassName<State>(
+  className: string | ((state: State) => string | undefined) | undefined,
+  state: State,
+) {
+  return typeof className === 'function' ? className(state) : className;
+}

package/src/utils/resolveStyle.ts

@@ -0,0 +1,12 @@
+import type { ZestStyle, ZestStyleValue } from '../types';
+
+/**
+ * If the provided style is a React Native style value, it will be returned as is.
+ * Otherwise, the function will call the style function with the state as the first argument.
+ */
+export function resolveStyle<State>(
+  style: ZestStyle<State>,
+  state: State,
+): ZestStyleValue | undefined {
+  return typeof style === 'function' ? style(state) : style;
+}

package/src/utils/useAnchorPositioning.ts

@@ -0,0 +1,171 @@
+'use client';
+import * as React from 'react';
+import {
+  arrow,
+  flip,
+  limitShift,
+  offset,
+  shift,
+  useFloating,
+  type Middleware,
+  type Padding,
+  type Placement,
+} from '@floating-ui/react-native';
+
+export type Side = 'top' | 'right' | 'bottom' | 'left';
+export type Align = 'start' | 'center' | 'end';
+
+/**
+ * Positions a floating element against an anchor.
+ *
+ * Upstream vendors `floating-ui-react` and drives it from
+ * `utils/useAnchorPositioning.ts`. Here the same engine is used through its
+ * official React Native binding, so `flip`/`shift`/`limitShift`/`arrow`
+ * behave identically instead of being re-derived.
+ *
+ * `sameScrollView: false` makes floating-ui measure the anchor with
+ * `measureInWindow` (and add the Android status bar height), producing screen
+ * coordinates. Popups therefore have to be rendered in a container whose origin
+ * is the top of the screen — which is what a `statusBarTranslucent` `Modal` is.
+ *
+ * There is no `autoUpdate` equivalent: nothing in React Native observes layout
+ * globally. Call `update()` whenever the anchor or the popup is laid out — the
+ * parts wire this to their `onLayout`.
+ */
+export function useAnchorPositioning(
+  params: UseAnchorPositioningParameters = {},
+): UseAnchorPositioningReturnValue {
+  const {
+    align = 'center',
+    alignOffset = 0,
+    arrowPadding = 5,
+    collisionPadding = 5,
+    side = 'bottom',
+    sideOffset = 0,
+    sticky = false,
+  } = params;
+
+  const arrowRef = React.useRef<unknown>(null);
+
+  const placement: Placement = align === 'center' ? side : (`${side}-${align}` as Placement);
+
+  const middleware: Middleware[] = React.useMemo(
+    () => [
+      offset({ mainAxis: sideOffset, crossAxis: alignOffset }, [sideOffset, alignOffset]),
+      flip({ padding: collisionPadding }, [collisionPadding]),
+      shift(
+        {
+          padding: collisionPadding,
+          // `sticky` keeps the popup glued to the anchor even as it slides out of
+          // view; otherwise `limitShift` stops it at the anchor's edge.
+          limiter: sticky ? undefined : limitShift(),
+        },
+        [collisionPadding, sticky],
+      ),
+      arrow({ element: arrowRef, padding: arrowPadding }, [arrowPadding]),
+    ],
+    [sideOffset, alignOffset, collisionPadding, sticky, arrowPadding],
+  );
+
+  const floating = useFloating({ placement, middleware, sameScrollView: false });
+
+  const { x, y, placement: resolvedPlacement, middlewareData, refs, update } = floating;
+
+  const [resolvedSide, resolvedAlign] = parsePlacement(resolvedPlacement);
+
+  const positionerStyles = React.useMemo(
+    () => ({ position: 'absolute' as const, left: x, top: y }),
+    [x, y],
+  );
+
+  const arrowStyles = React.useMemo(() => {
+    const data = middlewareData.arrow;
+    if (!data) {
+      return {};
+    }
+
+    return {
+      ...(data.x != null ? { left: data.x } : {}),
+      ...(data.y != null ? { top: data.y } : {}),
+    };
+  }, [middlewareData.arrow]);
+
+  return {
+    align: resolvedAlign,
+    arrowRef,
+    arrowStyles,
+    positionerStyles,
+    refs,
+    side: resolvedSide,
+    update,
+  };
+}
+
+function parsePlacement(placement: Placement): [Side, Align] {
+  const [side, alignment] = placement.split('-') as [Side, Alignment | undefined];
+  return [side, alignment ?? 'center'];
+}
+
+type Alignment = 'start' | 'end';
+
+export interface UseAnchorPositioningSharedParameters {
+  /**
+   * Which side of the anchor to position against.
+   * @default 'bottom'
+   */
+  side?: Side | undefined;
+  /**
+   * Distance between the anchor and the popup, in points.
+   * @default 0
+   */
+  sideOffset?: number | undefined;
+  /**
+   * How to align the popup relative to the anchor.
+   * @default 'center'
+   */
+  align?: Align | undefined;
+  /**
+   * Additional offset along the alignment axis, in points.
+   * @default 0
+   */
+  alignOffset?: number | undefined;
+  /**
+   * Minimum distance to keep between the popup and the edge of the screen.
+   * @default 5
+   */
+  collisionPadding?: Padding | undefined;
+  /**
+   * Whether to keep the popup anchored even when it would slide off screen,
+   * instead of stopping it at the anchor's edge.
+   * @default false
+   */
+  sticky?: boolean | undefined;
+  /**
+   * Minimum distance to keep between the arrow and the popup's corners.
+   * @default 5
+   */
+  arrowPadding?: number | undefined;
+}
+
+export interface UseAnchorPositioningParameters extends UseAnchorPositioningSharedParameters {}
+
+export interface UseAnchorPositioningReturnValue {
+  /**
+   * The side the popup was actually placed on, which differs from the requested
+   * `side` when `flip` had to move it.
+   */
+  side: Side;
+  /**
+   * The alignment the popup was actually placed with.
+   */
+  align: Align;
+  positionerStyles: { position: 'absolute'; left: number; top: number };
+  arrowStyles: { left?: number; top?: number };
+  arrowRef: React.RefObject<unknown>;
+  refs: ReturnType<typeof useFloating>['refs'];
+  /**
+   * Recomputes the position. Nothing observes layout globally in React Native,
+   * so parts call this from their `onLayout`.
+   */
+  update: () => void;
+}

package/src/utils/warn.ts

@@ -0,0 +1,14 @@
+let set: Set<string>;
+if (process.env.NODE_ENV !== 'production') {
+  set = new Set<string>();
+}
+
+export function warn(...messages: string[]) {
+  if (process.env.NODE_ENV !== 'production') {
+    const messageKey = messages.join(' ');
+    if (!set.has(messageKey)) {
+      set.add(messageKey);
+      console.warn(`Zest: ${messageKey}`);
+    }
+  }
+}