@limonify/zest-ui 0.1.0

package/src/use-render/useRenderElement.tsx

@@ -0,0 +1,218 @@
+import * as React from 'react';
+import { useMergedRefs, useMergedRefsN } from '../hooks/useMergedRefs';
+import { getReactElementRef } from '../utils/getReactElementRef';
+import { warn } from '../utils/warn';
+import { EMPTY_OBJECT } from '../utils/empty';
+import { resolveClassName } from '../utils/resolveClassName';
+import { resolveStyle } from '../utils/resolveStyle';
+import { mergeProps, mergePropsN, mergeClassNames, mergeStyles } from '../merge-props';
+import type { NativeProps, RenderProp, ZestStyle } from '../types';
+
+/**
+ * Renders a Zest element.
+ *
+ * React Native adaptation of Base UI's `useRenderElement`. Differences from the web version:
+ * - The default element is a React Native component (e.g. `View`, `Pressable`) instead of a tag name.
+ * - There is no `data-*` attribute generation: state reaches consumers through `className`/`style`
+ *   functions, the `render` function's second argument, and each component's explicit
+ *   `accessibilityState` props.
+ * - `style` values are merged by array composition (RN flattens arrays), never object spreading.
+ *
+ * @param DefaultComponent The default React Native component to render. Can be overridden by the `render` prop.
+ * @param componentProps An object containing the `render`, `className` and `style` props. Other props are ignored.
+ * @param params Additional parameters for rendering the element.
+ */
+export function useRenderElement<
+  State extends Record<string, any>,
+  RenderedElementType,
+  Enabled extends boolean | undefined = undefined,
+>(
+  DefaultComponent: React.ElementType | undefined,
+  componentProps: UseRenderElementComponentProps<State>,
+  params: UseRenderElementParameters<State, RenderedElementType, Enabled> = {},
+): Enabled extends false ? null : React.ReactElement {
+  const renderProp = componentProps.render;
+  const outProps = useRenderElementProps(componentProps, params);
+  if (params.enabled === false) {
+    return null as Enabled extends false ? null : React.ReactElement;
+  }
+
+  const state = params.state ?? (EMPTY_OBJECT as State);
+  return evaluateRenderProp(DefaultComponent, renderProp, outProps, state) as Enabled extends false
+    ? null
+    : React.ReactElement;
+}
+
+/**
+ * Computes render element final props.
+ */
+function useRenderElementProps<
+  State extends Record<string, any>,
+  RenderedElementType,
+  Enabled extends boolean | undefined,
+>(
+  componentProps: UseRenderElementComponentProps<State>,
+  params: UseRenderElementParameters<State, RenderedElementType, Enabled> = {},
+): NativeProps {
+  const { className: classNameProp, style: styleProp, render: renderProp } = componentProps;
+
+  const { state = EMPTY_OBJECT as State, ref, props, enabled = true } = params;
+
+  const className = enabled ? resolveClassName(classNameProp, state) : undefined;
+  const style = enabled ? resolveStyle(styleProp, state) : undefined;
+
+  // Ensure outProps is always a new mutable object when enabled, never EMPTY_OBJECT,
+  // since EMPTY_OBJECT is frozen and mutations would fail in strict mode.
+  const outProps: NativeProps = enabled && props ? resolveRenderFunctionProps(props) : {};
+
+  // SAFETY: The `useMergedRefs` functions use a single hook to store the same value,
+  // switching between them at runtime is safe. If this assertion fails, React will
+  // throw at runtime anyway.
+  /* eslint-disable react-hooks/rules-of-hooks */
+  if (!enabled) {
+    // Called only to keep the hook order stable when disabled; the merged ref is unused.
+    void useMergedRefs(null, null);
+  } else if (Array.isArray(ref)) {
+    outProps.ref = useMergedRefsN([outProps.ref, getReactElementRef(renderProp), ...ref]);
+  } else {
+    outProps.ref = useMergedRefs(outProps.ref, getReactElementRef(renderProp), ref);
+  }
+  /* eslint-enable react-hooks/rules-of-hooks */
+
+  if (!enabled) {
+    return EMPTY_OBJECT;
+  }
+
+  if (className !== undefined) {
+    outProps.className = mergeClassNames(outProps.className, className);
+  }
+
+  if (style !== undefined) {
+    outProps.style = mergeStyles(outProps.style, style);
+  }
+
+  return outProps;
+}
+
+function resolveRenderFunctionProps(
+  props: NonNullable<UseRenderElementParameters<any, any, any>['props']>,
+): NativeProps {
+  if (Array.isArray(props)) {
+    return mergePropsN(props) as NativeProps;
+  }
+
+  return mergeProps(undefined, props) as NativeProps;
+}
+
+const COMPONENT_IDENTIFIER_PATTERN = /^[A-Z][A-Za-z0-9$]*$/;
+const LOWERCASE_CHARACTER_PATTERN = /[a-z]/;
+
+function evaluateRenderProp<State>(
+  DefaultComponent: React.ElementType | undefined,
+  render: RenderProp<NativeProps, State> | undefined,
+  props: NativeProps,
+  state: State,
+): React.ReactElement {
+  if (render) {
+    if (typeof render === 'function') {
+      if (process.env.NODE_ENV !== 'production') {
+        warnIfRenderPropLooksLikeComponent(render);
+      }
+      return render(props, state);
+    }
+
+    const mergedProps = mergeProps(props, render.props as NativeProps);
+
+    mergedProps.ref = props.ref;
+
+    // There is a high number of indirections, the error message thrown by React.cloneElement() is
+    // hard to use for developers, this logic provides a better context.
+    if (process.env.NODE_ENV !== 'production') {
+      if (!React.isValidElement(render)) {
+        throw new Error(
+          [
+            'Zest: The `render` prop was provided an invalid React element as `React.isValidElement(render)` is `false`.',
+            'A valid React element must be provided to the `render` prop because it is cloned with props to replace the default element.',
+          ].join('\n'),
+        );
+      }
+    }
+
+    return React.cloneElement(render, mergedProps);
+  }
+
+  if (DefaultComponent) {
+    return React.createElement(DefaultComponent, props);
+  }
+
+  throw new Error('Zest: Render element or function are not defined.');
+}
+
+function warnIfRenderPropLooksLikeComponent(renderFn: { name: string }) {
+  const functionName = renderFn.name;
+  if (functionName.length === 0) {
+    return;
+  }
+
+  if (!COMPONENT_IDENTIFIER_PATTERN.test(functionName)) {
+    return;
+  }
+
+  if (!LOWERCASE_CHARACTER_PATTERN.test(functionName)) {
+    return;
+  }
+
+  warn(
+    `The \`render\` prop received a function named \`${functionName}\` that starts with an uppercase letter.`,
+    'This usually means a React component was passed directly as `render={Component}`.',
+    'Zest calls `render` as a plain function, which can break the Rules of Hooks during reconciliation.',
+    'If this is an intentional render callback, rename it to start with a lowercase letter.',
+    'Use `render={<Component />}` or `render={(props) => <Component {...props} />}` instead.',
+  );
+}
+
+export type UseRenderElementParameters<
+  State,
+  RenderedElementType,
+  Enabled extends boolean | undefined,
+> = {
+  /**
+   * If `false`, the hook will skip most of its internal logic and return `null`.
+   * This is useful for rendering a component conditionally.
+   * @default true
+   */
+  enabled?: Enabled | undefined;
+  /**
+   * The ref to apply to the rendered element.
+   */
+  ref?: React.Ref<RenderedElementType> | (React.Ref<RenderedElementType> | undefined)[] | undefined;
+  /**
+   * The state of the component.
+   */
+  state?: State | undefined;
+  /**
+   * Intrinsic props to be spread on the rendered element.
+   */
+  props?:
+    | NativeProps
+    | Array<NativeProps | undefined | ((props: NativeProps) => NativeProps)>
+    | undefined;
+};
+
+export interface UseRenderElementComponentProps<State> {
+  /**
+   * The class name to apply to the rendered element.
+   * Can be a string or a function that accepts the state and returns a string.
+   * Inert in plain React Native; consumed by className-based styling solutions.
+   */
+  className?: string | ((state: State) => string | undefined) | undefined;
+  /**
+   * The render prop or React element to override the default element.
+   */
+  render?: undefined | RenderProp<NativeProps, State>;
+  /**
+   * The style to apply to the rendered element.
+   * Can be a React Native style or a function that accepts the state and returns one.
+   */
+  style?: ZestStyle<State>;
+}

package/src/utils/clamp.ts

@@ -0,0 +1,7 @@
+export function clamp(
+  value: number,
+  min: number = Number.MIN_SAFE_INTEGER,
+  max: number = Number.MAX_SAFE_INTEGER,
+): number {
+  return Math.max(min, Math.min(value, max));
+}

package/src/utils/createChangeEventDetails.ts

@@ -0,0 +1,83 @@
+import type { GestureResponderEvent, NativeSyntheticEvent } from 'react-native';
+import { EMPTY_OBJECT } from './empty';
+
+/**
+ * The native event associated with a change. In React Native there is no DOM
+ * event hierarchy; press interactions produce `GestureResponderEvent`s and
+ * everything else is a `NativeSyntheticEvent`. Events may be absent for
+ * imperative or initial state changes.
+ */
+export type ZestNativeEvent =
+  | GestureResponderEvent
+  | NativeSyntheticEvent<unknown>
+  | undefined;
+
+type ZestChangeEventDetail<Reason extends string, CustomProperties extends object> = {
+  /**
+   * The reason for the event.
+   */
+  reason: Reason;
+  /**
+   * The native event associated with the custom event, if any.
+   */
+  event: ZestNativeEvent;
+  /**
+   * Cancels Zest from handling the event.
+   */
+  cancel: () => void;
+  /**
+   * Allows the event to propagate in cases where Zest will stop the propagation.
+   */
+  allowPropagation: () => void;
+  /**
+   * Indicates whether the event has been canceled.
+   */
+  isCanceled: boolean;
+  /**
+   * Indicates whether the event is allowed to propagate.
+   */
+  isPropagationAllowed: boolean;
+} & CustomProperties;
+
+/**
+ * Details of custom change events emitted by Zest components.
+ */
+export type ZestChangeEventDetails<
+  Reason extends string,
+  CustomProperties extends object = {},
+> = Reason extends string ? ZestChangeEventDetail<Reason, CustomProperties> & {} : never;
+
+/**
+ * Creates a Zest event details object with the given reason and utilities
+ * for preventing Zest's internal event handling.
+ */
+export function createChangeEventDetails<
+  Reason extends string,
+  CustomProperties extends object = {},
+>(
+  reason: Reason,
+  event?: ZestNativeEvent,
+  customProperties?: CustomProperties,
+): ZestChangeEventDetails<Reason, CustomProperties> {
+  let canceled = false;
+  let allowPropagation = false;
+  const custom = customProperties ?? (EMPTY_OBJECT as CustomProperties);
+  const details: ZestChangeEventDetail<Reason, CustomProperties> = {
+    reason,
+    event,
+    cancel() {
+      canceled = true;
+    },
+    allowPropagation() {
+      allowPropagation = true;
+    },
+    get isCanceled() {
+      return canceled;
+    },
+    get isPropagationAllowed() {
+      return allowPropagation;
+    },
+    ...custom,
+  };
+  return details as ZestChangeEventDetails<Reason, CustomProperties>;
+}

package/src/utils/empty.ts

@@ -0,0 +1,5 @@
+export function NOOP() {}
+
+export const EMPTY_ARRAY: readonly any[] = Object.freeze([]);
+
+export const EMPTY_OBJECT = Object.freeze({});

package/src/utils/error.ts

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

package/src/utils/fastObjectShallowCompare.ts

@@ -0,0 +1,30 @@
+const is = Object.is;
+
+export function fastObjectShallowCompare<T extends Record<string, any> | null>(a: T, b: T) {
+  if (a === b) {
+    return true;
+  }
+  if (!(a instanceof Object) || !(b instanceof Object)) {
+    return false;
+  }
+
+  let aLength = 0;
+  let bLength = 0;
+
+  /* eslint-disable guard-for-in */
+  for (const key in a) {
+    aLength += 1;
+
+    if (!is(a[key], b[key])) {
+      return false;
+    }
+    if (!(key in b)) {
+      return false;
+    }
+  }
+
+  for (const _ in b) {
+    bLength += 1;
+  }
+  return aLength === bLength;
+}

package/src/utils/formatNumber.ts

@@ -0,0 +1,41 @@
+function stringifyLocale(locale?: Intl.LocalesArgument): string {
+  if (Array.isArray(locale)) {
+    return locale.map((value) => stringifyLocale(value)).join(',');
+  }
+
+  if (locale == null) {
+    return '';
+  }
+
+  return String(locale);
+}
+
+// Constructing an Intl.NumberFormat is expensive, and a number field re-formats
+// on every keystroke.
+const cache = new Map<string, Intl.NumberFormat>();
+
+export function getFormatter(locale?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions) {
+  const key = JSON.stringify({ locale: stringifyLocale(locale), options });
+  const cached = cache.get(key);
+
+  if (cached) {
+    return cached;
+  }
+
+  const formatter = new Intl.NumberFormat(locale as string | string[] | undefined, options);
+  cache.set(key, formatter);
+
+  return formatter;
+}
+
+export function formatNumber(
+  value: number | null,
+  locale?: Intl.LocalesArgument,
+  options?: Intl.NumberFormatOptions,
+) {
+  if (value == null) {
+    return '';
+  }
+
+  return getFormatter(locale, options).format(value);
+}

package/src/utils/generateId.ts

@@ -0,0 +1,10 @@
+let counter = 0;
+
+/**
+ * A unique id for things React's `useId` cannot cover — values created outside
+ * of rendering, like a toast pushed from an event handler.
+ */
+export function generateId(prefix: string) {
+  counter += 1;
+  return `${prefix}-${Math.random().toString(36).slice(2, 6)}-${counter}`;
+}

package/src/utils/getReactElementRef.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+
+/**
+ * Extracts the `ref` from a React element.
+ * Zest requires React >= 19, where element refs live on `props`.
+ */
+export function getReactElementRef(element: unknown): React.Ref<unknown> | null {
+  if (!React.isValidElement(element)) {
+    return null;
+  }
+
+  const propsWithRef = element.props as { ref?: React.Ref<unknown> | undefined } | undefined;
+
+  return propsWithRef?.ref ?? null;
+}

package/src/utils/mergeObjects.ts

@@ -0,0 +1,15 @@
+export function mergeObjects<A extends object | undefined, B extends object | undefined>(
+  a: A,
+  b: B,
+) {
+  if (a && !b) {
+    return a;
+  }
+  if (!a && b) {
+    return b;
+  }
+  if (a || b) {
+    return { ...a, ...b };
+  }
+  return undefined;
+}

package/src/utils/popups/BasePopupHandle.ts

@@ -0,0 +1,230 @@
+import { AnimationFrame } from '../../hooks/useAnimationFrame';
+import { createChangeEventDetails, type ZestChangeEventDetails } from '../createChangeEventDetails';
+import { REASONS } from '../reasons';
+import type { PopupTriggerMap } from './PopupTriggerMap';
+
+/**
+ * The minimal store contract a handle exposes to detached triggers.
+ *
+ * Detached triggers read `store` during render and subscribe so they are notified
+ * when the handle switches between its fallback store and a mounted root's live
+ * store.
+ */
+export interface PopupHandleStoreProvider<HandleStore> {
+  readonly store: HandleStore;
+  subscribeStore(listener: () => void): () => void;
+}
+
+/**
+ * The store shape a handle needs to resolve a trigger by id.
+ */
+export interface PopupHandleStoreWithTriggers {
+  readonly context: { readonly triggerNodes: PopupTriggerMap };
+}
+
+/**
+ * The store shape a handle needs to drive open state. Only the root-owned store
+ * needs this — the view exposed to detached triggers never has `setOpen` called
+ * on it.
+ */
+export interface PopupHandleStoreWithOpen extends PopupHandleStoreWithTriggers {
+  setOpen(open: boolean, eventDetails: ZestChangeEventDetails<typeof REASONS.imperativeAction>): void;
+}
+
+/**
+ * The shared implementation behind every popup handle: it coordinates detached
+ * triggers with a mounted root.
+ *
+ * Ported from upstream near-verbatim — it is pure state, and the only DOM in it
+ * was the trigger element's type (see `PopupTriggerMap`). Subclasses add the
+ * component-specific imperative methods; this owns the fallback store, the root
+ * attachment stack, and subscriber notification.
+ */
+export class BasePopupHandle<
+  HandleStore extends PopupHandleStoreWithTriggers,
+  Store extends HandleStore & PopupHandleStoreWithOpen,
+> {
+  /**
+   * The stores of every root currently using this handle, in attach order. A
+   * handle is meant for a single mounted root, but roots can transiently overlap
+   * (an animated screen transition, say), so this stack lets `attachStore`'s
+   * cleanup restore the previous root rather than leaving a still-mounted root
+   * uncontrollable when a newer one detaches first.
+   */
+  private readonly attachedStores: Store[] = [];
+
+  private attachedStoreValue: Store | null = null;
+
+  private readonly storeListeners = new Set<() => void>();
+
+  /**
+   * @param fallbackStore An inert, closed store handed to detached triggers while
+   * no root is attached, so they can render and register without one. Triggers
+   * register into whichever store `store` resolves to and migrate themselves as
+   * roots attach and detach.
+   * @param componentName Prefixes dev warnings, e.g. `'Menu'` produces
+   * `MenuHandle.open()`.
+   * @param throwOnMissingTrigger Whether `open(triggerId)` throws when no trigger
+   * with that id is registered. Anchored popups (Menu, Popover) need a trigger to
+   * anchor to, so they throw; a Dialog is not anchored and opens unassociated
+   * with a warning instead.
+   */
+  constructor(
+    protected readonly fallbackStore: HandleStore,
+    private readonly componentName: string,
+    private readonly throwOnMissingTrigger: boolean = true,
+  ) {}
+
+  protected get attachedStore() {
+    return this.attachedStoreValue;
+  }
+
+  /**
+   * The store detached triggers read from: the attached root's, or the inert
+   * fallback while none is attached.
+   * @internal
+   */
+  get store(): HandleStore {
+    return this.attachedStoreValue ?? this.fallbackStore;
+  }
+
+  /** @internal */
+  subscribeStore(listener: () => void) {
+    this.storeListeners.add(listener);
+
+    return () => {
+      this.storeListeners.delete(listener);
+    };
+  }
+
+  /**
+   * Points the handle at a root's store and notifies subscribers, so detached
+   * triggers re-render and re-register into it. Returns a cleanup that detaches.
+   * @internal
+   */
+  attachStore(newStore: Store) {
+    this.attachedStores.push(newStore);
+    this.setActiveStore(newStore);
+
+    if (process.env.NODE_ENV !== 'production') {
+      if (this.attachedStores.length > 1) {
+        // More than one root is attached. This is usually a transient overlap
+        // during a screen transition, where the outgoing root unmounts shortly
+        // after the incoming one mounts. Defer a frame and only warn if the
+        // overlap is still there once things have settled, so a clean handoff
+        // stays quiet regardless of unmount timing.
+        const dev = this as this & { overlapWarningFrame?: AnimationFrame | undefined };
+        (dev.overlapWarningFrame ??= AnimationFrame.create()).request(() => {
+          if (this.attachedStores.length > 1) {
+            console.warn(
+              'Zest: A handle is attached to more than one mounted root at the same time. ' +
+                'The most recently mounted root takes over and the previous one stops being controlled by the handle. ' +
+                'A handle should be used by a single root that stays mounted for the lifetime of the handle.',
+            );
+          }
+        });
+      }
+    }
+
+    return () => {
+      const index = this.attachedStores.lastIndexOf(newStore);
+      if (index !== -1) {
+        this.attachedStores.splice(index, 1);
+      }
+      // Restore control to the most recently attached root that is still
+      // mounted, rather than detaching unconditionally.
+      this.setActiveStore(this.attachedStores[this.attachedStores.length - 1] ?? null);
+    };
+  }
+
+  private setActiveStore(store: Store | null) {
+    if (this.attachedStoreValue !== store) {
+      this.attachedStoreValue = store;
+      this.storeListeners.forEach((listener) => {
+        listener();
+      });
+    }
+  }
+
+  /**
+   * Opens the attached root, associating it with the trigger of the given id.
+   * A no-op while no root is attached.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   */
+  protected openByTrigger(triggerId: string | null | undefined) {
+    const attachedStore = this.attachedStore;
+
+    if (attachedStore === null) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          `Zest: ${this.componentName}Handle.open() was called while no root using this handle is mounted. ` +
+            'The call was ignored; mount a root with this handle before opening it imperatively.',
+        );
+      }
+      return;
+    }
+
+    // A trigger normally lives in the active root's store, but during the commit
+    // in which a root attaches, a still-mounted detached trigger has not
+    // migrated yet — it is registered wherever it lived before. Search the whole
+    // stack (newest first) and the fallback, so an imperative open-by-id in that
+    // commit still resolves it.
+    let triggerNode: unknown;
+    if (triggerId) {
+      for (let i = this.attachedStores.length - 1; i >= 0 && triggerNode === undefined; i -= 1) {
+        triggerNode = this.attachedStores[i]!.context.triggerNodes.getById(triggerId);
+      }
+      triggerNode ??= this.fallbackStore.context.triggerNodes.getById(triggerId);
+    }
+
+    if (triggerId && triggerNode === undefined) {
+      if (this.throwOnMissingTrigger) {
+        throw new Error(
+          `Zest: ${this.componentName}Handle.open() was called with the trigger id "${triggerId}", ` +
+            'but no matching trigger is registered with this handle. ' +
+            'An anchored popup cannot open without a trigger to anchor to. ' +
+            `Pass the id of a mounted ${this.componentName}.Trigger that has this handle set on its "handle" prop.`,
+        );
+      }
+
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          `Zest: ${this.componentName}Handle.open: No trigger found with id "${triggerId}". ` +
+            'The popup will open, but the trigger will not be associated with it.',
+        );
+      }
+    }
+
+    this.associateTrigger(attachedStore, triggerNode);
+    attachedStore.setOpen(true, createChangeEventDetails(REASONS.imperativeAction));
+  }
+
+  /**
+   * Points the popup at the trigger it was opened by. Anchored popups override
+   * this to set the store's `triggerNode`, without which their positioner would
+   * have nothing to anchor to; an unanchored one (Dialog) has nothing to do.
+   */
+  protected associateTrigger(_store: Store, _triggerNode: unknown) {}
+
+  /**
+   * Closes the popup. A no-op while no root is attached.
+   *
+   * Call this from an event handler or an effect, never during rendering.
+   */
+  protected closePopup() {
+    const attachedStore = this.attachedStore;
+
+    if (attachedStore === null) {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          `Zest: ${this.componentName}Handle.close() was called while no root using this handle is mounted. ` +
+            'The call was ignored.',
+        );
+      }
+      return;
+    }
+
+    attachedStore.setOpen(false, createChangeEventDetails(REASONS.imperativeAction));
+  }
+}