@limonify/zest-ui 0.1.0

package/src/hooks/useStableCallback.ts

@@ -0,0 +1,47 @@
+'use client';
+import * as React from 'react';
+import { useRefWithInit } from './useRefWithInit';
+
+type Callback = (...args: any[]) => any;
+
+type Stable<T extends Callback> = {
+  /** The next value for callback */
+  next: T | undefined;
+  /** The function to be called by trampoline. This must fail during the initial render phase. */
+  callback: T | undefined;
+  trampoline: T;
+  effect: () => void;
+};
+
+/**
+ * Stabilizes the function passed so it's always the same between renders.
+ *
+ * The function becomes non-reactive to any values it captures.
+ * It can safely be passed as a dependency of `React.useMemo` and `React.useEffect` without re-triggering them if its captured values change.
+ *
+ * The function must only be called inside effects and event handlers, never during render (which throws an error).
+ */
+export function useStableCallback<T extends Callback>(callback: T | undefined): T {
+  const stable = useRefWithInit(createStableCallback).current;
+  stable.next = callback;
+  React.useInsertionEffect(stable.effect);
+  return stable.trampoline;
+}
+
+function createStableCallback() {
+  const stable: Stable<any> = {
+    next: undefined,
+    callback: assertNotCalled,
+    trampoline: (...args: []) => stable.callback?.(...args),
+    effect: () => {
+      stable.callback = stable.next;
+    },
+  };
+  return stable;
+}
+
+function assertNotCalled() {
+  if (process.env.NODE_ENV !== 'production') {
+    throw new Error('Zest: Cannot call an event handler while rendering.');
+  }
+}

package/src/hooks/useTimeout.ts

@@ -0,0 +1,52 @@
+'use client';
+import { useRefWithInit } from './useRefWithInit';
+import { useOnMount } from './useOnMount';
+
+type TimeoutId = number;
+
+const EMPTY = 0 as TimeoutId;
+
+export class Timeout {
+  static create() {
+    return new Timeout();
+  }
+
+  currentId: TimeoutId = EMPTY;
+
+  /**
+   * Executes `fn` after `delay`, clearing any previously scheduled call.
+   */
+  start(delay: number, fn: Function) {
+    this.clear();
+    this.currentId = setTimeout(() => {
+      this.currentId = EMPTY;
+      fn();
+    }, delay) as unknown as number;
+  }
+
+  isStarted() {
+    return this.currentId !== EMPTY;
+  }
+
+  clear = () => {
+    if (this.currentId !== EMPTY) {
+      clearTimeout(this.currentId as TimeoutId);
+      this.currentId = EMPTY;
+    }
+  };
+
+  disposeEffect = () => {
+    return this.clear;
+  };
+}
+
+/**
+ * A `setTimeout` with automatic cleanup and guard.
+ */
+export function useTimeout() {
+  const timeout = useRefWithInit(Timeout.create).current;
+
+  useOnMount(timeout.disposeEffect);
+
+  return timeout;
+}

package/src/hooks/useValueAsRef.ts

@@ -0,0 +1,30 @@
+'use client';
+import { useIsoLayoutEffect } from './useIsoLayoutEffect';
+import { useRefWithInit } from './useRefWithInit';
+
+/**
+ * Untracks the provided value by turning it into a ref to remove its reactivity.
+ *
+ * Used to access the passed value inside `React.useEffect` without causing the effect to re-run when the value changes.
+ */
+export function useValueAsRef<T>(value: T) {
+  const latest = useRefWithInit(createLatestRef, value).current;
+
+  latest.next = value;
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useIsoLayoutEffect(latest.effect);
+
+  return latest;
+}
+
+function createLatestRef<T>(value: T) {
+  const latest = {
+    current: value,
+    next: value,
+    effect: () => {
+      latest.current = latest.next;
+    },
+  };
+  return latest;
+}

package/src/index.ts

@@ -0,0 +1,45 @@
+export * from './accordion';
+export * from './alert-dialog';
+export * from './autocomplete';
+export * from './avatar';
+export * from './button';
+export * from './checkbox';
+export * from './checkbox-group';
+export * from './collapsible';
+export * from './combobox';
+export * from './context-menu';
+export * from './dialog';
+export * from './drawer';
+export * from './field';
+export * from './fieldset';
+export * from './input';
+export * from './menu';
+export * from './meter';
+export * from './number-field';
+export * from './otp-field';
+export * from './popover';
+export * from './progress';
+export * from './radio';
+export * from './radio-group';
+export * from './select';
+export * from './separator';
+export * from './slider';
+export * from './switch';
+export * from './tabs';
+export * from './toast';
+export * from './tooltip';
+export * from './toggle';
+export * from './toggle-group';
+
+export * from './store';
+export * from './hooks';
+export * from './types';
+export { useRender } from './use-render';
+export { mergeProps, mergePropsN } from './merge-props';
+export { REASONS } from './utils/reasons';
+export type { ZestEventReason, ZestEventReasons } from './utils/reasons';
+export {
+  createChangeEventDetails,
+  type ZestChangeEventDetails,
+  type ZestNativeEvent,
+} from './utils/createChangeEventDetails';

package/src/input/Input.tsx

@@ -0,0 +1,69 @@
+'use client';
+import { TextInput } from 'react-native';
+import { useRenderElement } from '../use-render/useRenderElement';
+import { useFieldControl } from '../field/control/useFieldControl';
+import type { ZestUIComponentProps } from '../types';
+
+/**
+ * A text input. Renders a `<TextInput>`.
+ *
+ * Upstream's `Input` is an alias for `Field.Control`. Here it is the same: use
+ * it standalone, or inside a `Field.Root` to pick up its label, description,
+ * error wiring, and validation automatically.
+ */
+export function Input(componentProps: Input.Props) {
+  const {
+    render,
+    className,
+    style,
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    nativeID,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const { field, props } = useFieldControl({
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    nativeID,
+    requireField: false,
+  });
+
+  const state: Input.State = { disabled: field?.disabled ?? false };
+
+  return useRenderElement(TextInput, componentProps, {
+    state,
+    ref,
+    props: [props, elementProps],
+  });
+}
+
+export interface InputState {
+  /**
+   * Whether the input is disabled (inherited from a surrounding field).
+   */
+  disabled: boolean;
+}
+
+export interface InputProps extends Omit<ZestUIComponentProps<typeof TextInput, InputState>, 'value'> {
+  /**
+   * The controlled text value.
+   */
+  value?: string | undefined;
+  /**
+   * The initial text value when uncontrolled.
+   */
+  defaultValue?: string | undefined;
+  /**
+   * Called with the new text as it changes.
+   */
+  onValueChange?: ((value: string) => void) | undefined;
+}
+
+export namespace Input {
+  export type State = InputState;
+  export type Props = InputProps;
+}

package/src/input/index.ts

@@ -0,0 +1,2 @@
+export { Input } from './Input';
+export type * from './Input';

package/src/internals/composite/list/CompositeList.tsx

@@ -0,0 +1,165 @@
+'use client';
+import * as React from 'react';
+import { useRefWithInit } from '../../../hooks/useRefWithInit';
+import { useStableCallback } from '../../../hooks/useStableCallback';
+import { useIsoLayoutEffect } from '../../../hooks/useIsoLayoutEffect';
+import {
+  CompositeListContext,
+  type CompositeItemKey,
+  type CompositeItemLayout,
+  type CompositeMetadata,
+} from './CompositeListContext';
+
+interface ItemRecord<Metadata> {
+  metadata: Metadata;
+  /** Mount order. React runs layout effects in child order, so this is the tree order at mount. */
+  registrationIndex: number;
+  layout: CompositeItemLayout | undefined;
+}
+
+/**
+ * Provides context for a list of items in a composite component, assigning each
+ * one its index in visual order.
+ *
+ * The web version sorts by `compareDocumentPosition` and watches for reorders
+ * with a `MutationObserver`. React Native has neither a document nor mutation
+ * records, so ordering comes from two sources:
+ *
+ * 1. **Registration order**, which is exact at mount because React runs layout
+ *    effects in child order. This is what upstream itself falls back to via
+ *    `IndexGuessBehavior.GuessFromOrder`.
+ * 2. **Measured layout**, once every item has reported one. Items are then
+ *    sorted in reading order, which is the real visual order — it stays correct
+ *    under `row-reverse`, wrapping, and absolute positioning, and it repairs the
+ *    case registration order cannot see: children reordered without remounting,
+ *    which never re-runs an effect but always moves the item on screen.
+ *
+ * Sorting only switches to layout once *all* items are measured, so the
+ * comparator never mixes the two orderings (which could not be transitive).
+ */
+export function CompositeList<Metadata>(props: CompositeList.Props<Metadata>) {
+  const { children, onMapChange: onMapChangeProp } = props;
+
+  const onMapChange = useStableCallback(onMapChangeProp ?? (() => {}));
+
+  const listeners = useRefWithInit(createListeners).current;
+  const map = useRefWithInit(createMap<Metadata>).current;
+  const nextRegistrationIndexRef = React.useRef(0);
+
+  // `mapTick` is the re-render trigger; `map` itself is stable to avoid
+  // reallocating on every registration.
+  const [mapTick, setMapTick] = React.useState(0);
+  const lastTickRef = React.useRef(mapTick);
+
+  const bumpTick = useStableCallback(() => {
+    lastTickRef.current += 1;
+    setMapTick(lastTickRef.current);
+  });
+
+  const register = useStableCallback((key: CompositeItemKey, metadata: Metadata) => {
+    const existing = map.get(key);
+    map.set(key, {
+      metadata,
+      registrationIndex: existing?.registrationIndex ?? nextRegistrationIndexRef.current++,
+      layout: existing?.layout,
+    });
+    bumpTick();
+  });
+
+  const unregister = useStableCallback((key: CompositeItemKey) => {
+    map.delete(key);
+    bumpTick();
+  });
+
+  const setItemLayout = useStableCallback((key: CompositeItemKey, layout: CompositeItemLayout) => {
+    const existing = map.get(key);
+    if (!existing || isSameLayout(existing.layout, layout)) {
+      return;
+    }
+
+    map.set(key, { ...existing, layout });
+    bumpTick();
+  });
+
+  const sortedMap = React.useMemo(() => {
+    // `mapTick` is the trigger; `map` is stable.
+    void mapTick;
+
+    const entries = Array.from(map.entries());
+    const allMeasured = entries.every(([, record]) => record.layout !== undefined);
+
+    entries.sort(([, a], [, b]) =>
+      allMeasured ? compareReadingOrder(a.layout!, b.layout!) : a.registrationIndex - b.registrationIndex,
+    );
+
+    const newMap = new Map<CompositeItemKey, CompositeMetadata<Metadata>>();
+    entries.forEach(([key, record], index) => {
+      newMap.set(key, { ...record.metadata, index, layout: record.layout });
+    });
+
+    return newMap;
+  }, [map, mapTick]);
+
+  useIsoLayoutEffect(() => {
+    onMapChange(sortedMap);
+    listeners.forEach((listener) => listener(sortedMap));
+  }, [onMapChange, listeners, sortedMap]);
+
+  const subscribeMapChange = useStableCallback(
+    (fn: (newMap: Map<CompositeItemKey, CompositeMetadata<Metadata>>) => void) => {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    },
+  );
+
+  const contextValue: CompositeListContext<Metadata> = React.useMemo(
+    () => ({ register, unregister, setItemLayout, subscribeMapChange }),
+    [register, unregister, setItemLayout, subscribeMapChange],
+  );
+
+  return (
+    <CompositeListContext.Provider value={contextValue}>{children}</CompositeListContext.Provider>
+  );
+}
+
+/**
+ * Reading order: items whose vertical extents overlap are on the same row and
+ * sort left to right; otherwise the higher one comes first. A plain `y` compare
+ * would misorder a row whose items differ in height or vertical alignment.
+ */
+function compareReadingOrder(a: CompositeItemLayout, b: CompositeItemLayout) {
+  const aBottom = a.y + a.height;
+  const bBottom = b.y + b.height;
+  const overlapsVertically = a.y < bBottom && b.y < aBottom;
+
+  if (overlapsVertically) {
+    return a.x - b.x;
+  }
+
+  return a.y - b.y;
+}
+
+function isSameLayout(a: CompositeItemLayout | undefined, b: CompositeItemLayout) {
+  return a != null && a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}
+
+function createMap<Metadata>() {
+  return new Map<CompositeItemKey, ItemRecord<Metadata>>();
+}
+
+function createListeners() {
+  return new Set<(map: Map<CompositeItemKey, any>) => void>();
+}
+
+export interface CompositeListProps<Metadata> {
+  children: React.ReactNode;
+  onMapChange?:
+    | ((newMap: Map<CompositeItemKey, CompositeMetadata<Metadata>>) => void)
+    | undefined;
+}
+
+export namespace CompositeList {
+  export type Props<Metadata> = CompositeListProps<Metadata>;
+}

package/src/internals/composite/list/CompositeListContext.ts

@@ -0,0 +1,44 @@
+'use client';
+import * as React from 'react';
+
+/**
+ * Items are keyed by a stable object identity rather than an element: React
+ * Native has no `Element` to use as a map key.
+ */
+export type CompositeItemKey = object;
+
+export interface CompositeItemLayout {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type CompositeMetadata<CustomMetadata> = {
+  index?: number | null | undefined;
+  layout?: CompositeItemLayout | undefined;
+} & CustomMetadata;
+
+export interface CompositeListContext<Metadata = any> {
+  register: (key: CompositeItemKey, metadata: Metadata) => void;
+  unregister: (key: CompositeItemKey) => void;
+  setItemLayout: (key: CompositeItemKey, layout: CompositeItemLayout) => void;
+  subscribeMapChange: (
+    fn: (map: Map<CompositeItemKey, CompositeMetadata<Metadata>>) => void,
+  ) => () => void;
+}
+
+export const CompositeListContext = React.createContext<CompositeListContext<any> | undefined>(
+  undefined,
+);
+
+export function useCompositeListContext<Metadata = any>() {
+  const context = React.useContext<CompositeListContext<Metadata> | undefined>(
+    CompositeListContext,
+  );
+  if (context === undefined) {
+    throw new Error('Zest: CompositeListContext is missing. Items must be within a CompositeList.');
+  }
+
+  return context;
+}

package/src/internals/composite/list/useCompositeListItem.ts

@@ -0,0 +1,70 @@
+'use client';
+import * as React from 'react';
+import type { LayoutChangeEvent } from 'react-native';
+import { useIsoLayoutEffect } from '../../../hooks/useIsoLayoutEffect';
+import { useRefWithInit } from '../../../hooks/useRefWithInit';
+import { useCompositeListContext } from './CompositeListContext';
+
+export interface UseCompositeListItemParameters<Metadata> {
+  metadata?: Metadata | undefined;
+}
+
+export interface UseCompositeListItemReturnValue {
+  /**
+   * The item's index in visual order. Starts at the item's registration order
+   * and is corrected once the whole list has been measured.
+   */
+  index: number;
+  /**
+   * Must be spread onto the item's element so the list can learn where it
+   * actually sits on screen.
+   */
+  onLayout: (event: LayoutChangeEvent) => void;
+}
+
+/**
+ * Registers a list item with the `CompositeList` and reports its position.
+ */
+export function useCompositeListItem<Metadata>(
+  params: UseCompositeListItemParameters<Metadata> = {},
+): UseCompositeListItemReturnValue {
+  const { metadata } = params;
+
+  const { register, unregister, setItemLayout, subscribeMapChange } =
+    useCompositeListContext<Metadata>();
+
+  // A stable identity for this item instance, standing in for the DOM node the
+  // web version keys its map by.
+  const key = useRefWithInit(createKey).current;
+
+  const [index, setIndex] = React.useState(-1);
+
+  useIsoLayoutEffect(() => {
+    register(key, metadata as Metadata);
+    return () => {
+      unregister(key);
+    };
+  }, [register, unregister, key, metadata]);
+
+  useIsoLayoutEffect(() => {
+    return subscribeMapChange((map) => {
+      const nextIndex = map.get(key)?.index;
+      if (nextIndex != null) {
+        setIndex(nextIndex);
+      }
+    });
+  }, [subscribeMapChange, key]);
+
+  const onLayout = React.useCallback(
+    (event: LayoutChangeEvent) => {
+      setItemLayout(key, event.nativeEvent.layout);
+    },
+    [setItemLayout, key],
+  );
+
+  return { index, onLayout };
+}
+
+function createKey() {
+  return {};
+}

package/src/internals/field/useFieldControlRegistration.ts

@@ -0,0 +1,56 @@
+'use client';
+import { useFieldRootContext } from '../../field/root/FieldRootContext';
+import { useStableCallback } from '../../hooks/useStableCallback';
+
+/**
+ * Wires a non-text form control (Checkbox, Switch, RadioGroup, NumberField) into
+ * a surrounding `Field.Root`, when there is one.
+ *
+ * A field-aware control:
+ * - is labelled by `Field.Label` and described by `Field.Description`/`Error`
+ *   (through `accessibilityLabelledBy`/`accessibilityDescribedBy`);
+ * - inherits the field's (and its fieldset's) `disabled`;
+ * - runs the field's `validate` when its value changes.
+ *
+ * Outside a `Field.Root` everything is `undefined`/no-op, so a standalone
+ * control is unaffected.
+ */
+export function useFieldControlRegistration() {
+  const field = useFieldRootContext(false);
+
+  const validate = useStableCallback((value: unknown) => {
+    if (!field) {
+      return;
+    }
+    const errors = field.runValidation(value);
+    field.setValidityData({ valid: errors.length === 0, errors });
+  });
+
+  const describedBy =
+    field && field.messageIds.length > 0 ? field.messageIds.join(' ') : undefined;
+
+  return {
+    /**
+     * `true` when a surrounding field (or fieldset) is disabled.
+     */
+    fieldDisabled: field?.disabled ?? false,
+    /**
+     * Accessibility props associating the control with the field's label and
+     * messages. Spread into the control's props before `elementProps`.
+     */
+    fieldProps: {
+      accessibilityLabelledBy: field?.labelId,
+      accessibilityDescribedBy: describedBy,
+      'aria-labelledby': field?.labelId,
+      'aria-describedby': describedBy,
+    },
+    /**
+     * Runs the field's validation for a new control value. No-op without a field.
+     */
+    validateField: validate,
+    /**
+     * Whether a surrounding field is present at all.
+     */
+    hasField: field != null,
+  };
+}

package/src/internals/use-button/useButton.ts

@@ -0,0 +1,44 @@
+'use client';
+import { mergeProps } from '../../merge-props';
+import type { NativeProps } from '../../types';
+
+/**
+ * Shared press-target behavior for button-like parts (Button, Dialog.Trigger,
+ * Dialog.Close, Checkbox.Root, ...).
+ *
+ * React Native adaptation of Base UI's `useButton`: the web version's
+ * `nativeButton`, `focusableWhenDisabled` and composite-navigation concerns
+ * are DOM-only and intentionally absent. `Pressable` already suppresses press
+ * events when `disabled` is set; this hook adds the accessibility contract.
+ */
+export function useButton(parameters: useButton.Parameters = {}) {
+  const { disabled = false, buttonProps: extraButtonProps } = parameters;
+
+  const getButtonProps = (externalProps: NativeProps = {}): NativeProps => {
+    return mergeProps<any>(
+      {
+        accessibilityRole: 'button',
+        accessibilityState: { disabled: disabled || undefined },
+        disabled,
+        ...extraButtonProps,
+      },
+      externalProps,
+    );
+  };
+
+  return { getButtonProps };
+}
+
+export namespace useButton {
+  export interface Parameters {
+    /**
+     * Whether the button should ignore user interaction.
+     * @default false
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Additional internal props merged before external ones.
+     */
+    buttonProps?: NativeProps | undefined;
+  }
+}