@limonify/zest-ui 0.3.1 → 0.4.0

package/src/otp-field/root/OTPFieldRoot.tsx

@@ -5,6 +5,7 @@ import { useControlled } from '../../hooks/useControlled';
 import { useId } from '../../hooks/useId';
 import { useStableCallback } from '../../hooks/useStableCallback';
 import { useRenderElement } from '../../use-render/useRenderElement';
+import { useFieldControlRegistration } from '../../internals/field/useFieldControlRegistration';
 import { CompositeList } from '../../internals/composite/list/CompositeList';
 import type { ZestUIComponentProps } from '../../types';
 import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
@@ -31,7 +32,7 @@ export function OTPFieldRoot(componentProps: OTPFieldRoot.Props) {
     autoComplete = 'one-time-code',
     className,
     defaultValue,
-    disabled = false,
+    disabled: disabledProp = false,
     id: idProp,
     length,
     mask = false,
@@ -48,6 +49,12 @@ export function OTPFieldRoot(componentProps: OTPFieldRoot.Props) {
     ...elementProps
   } = componentProps;
 
+  const { fieldDisabled, fieldProps, markChanged, markTouched } = useFieldControlRegistration({
+    initialValue: normalizeOTPValue(defaultValue ?? valueProp, length, validationType, normalizeValue),
+  });
+
+  const disabled = disabledProp || fieldDisabled;
+
   const id = useId(idProp);
 
   const [value, setValueState] = useControlled<string>({
@@ -103,8 +110,11 @@ export function OTPFieldRoot(componentProps: OTPFieldRoot.Props) {
       }
 
       setValueState(normalized);
+      markChanged(normalized);
 
       if (normalized.length === length) {
+        // A complete code ends the interaction; there is no blur to wait for.
+        markTouched(normalized);
         onValueComplete?.(normalized, createChangeEventDetails(eventDetails.reason));
       }
 
@@ -169,7 +179,17 @@ export function OTPFieldRoot(componentProps: OTPFieldRoot.Props) {
   const element = useRenderElement(View, componentProps, {
     state,
     ref,
-    props: elementProps,
+    props: [
+      {
+        // The slots are separate inputs but one field: without a group role a
+        // screen reader announces N unrelated text boxes. Pass
+        // `accessibilityLabel` to name the code being entered.
+        role: 'group' as const,
+        accessibilityState: { disabled: disabled || undefined },
+        ...fieldProps,
+      },
+      elementProps,
+    ],
   });
 
   return (

package/src/popover/popup/PopoverPopup.tsx

@@ -20,10 +20,19 @@ export function PopoverPopup(componentProps: PopoverPopup.Props) {
   const { transitionStatus } = usePopoverTransitionContext() ?? { transitionStatus: undefined };
 
   const open = store.useState('open');
+  const triggerWidth = store.useState('triggerWidth');
+  const triggerHeight = store.useState('triggerHeight');
   const titleElementId = store.useState('titleElementId');
   const descriptionElementId = store.useState('descriptionElementId');
 
-  const state: PopoverPopupState = { open, transitionStatus, side, align };
+  const state: PopoverPopupState = {
+    open,
+    transitionStatus,
+    side,
+    align,
+    triggerWidth,
+    triggerHeight,
+  };
 
   return useRenderElement(View, componentProps, {
     state,
@@ -61,6 +70,16 @@ export interface PopoverPopupState {
    * The alignment the popup was actually placed with.
    */
   align: Align;
+  /**
+   * The trigger's measured width, available for consumers to size the popup
+   * against its anchor. This is the React Native equivalent of the web's
+   * `--anchor-width` CSS variable.
+   */
+  triggerWidth: number | undefined;
+  /**
+   * The trigger's measured height.
+   */
+  triggerHeight: number | undefined;
 }
 
 export interface PopoverPopupProps extends ZestUIComponentProps<typeof View, PopoverPopupState> {}

package/src/popover/positioner/PopoverPositioner.tsx

@@ -38,6 +38,8 @@ export function PopoverPositioner(componentProps: PopoverPositioner.Props) {
   usePopoverPortalContext();
   const store = usePopoverRootContext();
   const open = store.useState('open');
+  const triggerWidth = store.useState('triggerWidth');
+  const triggerHeight = store.useState('triggerHeight');
   const triggerNode = store.useState('triggerNode');
 
   const positioning = useAnchorPositioning({
@@ -72,6 +74,8 @@ export function PopoverPositioner(componentProps: PopoverPositioner.Props) {
     open,
     side: positioning.side,
     align: positioning.align,
+    triggerWidth,
+    triggerHeight,
   };
 
   const contextValue: PopoverPositionerContext = React.useMemo(
@@ -114,6 +118,16 @@ export interface PopoverPositionerState {
    * The alignment the popup was actually placed with.
    */
   align: Align;
+  /**
+   * The trigger's measured width, available for consumers to size the popup
+   * against its anchor. This is the React Native equivalent of the web's
+   * `--anchor-width` CSS variable.
+   */
+  triggerWidth: number | undefined;
+  /**
+   * The trigger's measured height.
+   */
+  triggerHeight: number | undefined;
 }
 
 export interface PopoverPositionerProps

package/src/popover/store/PopoverStore.ts

@@ -22,6 +22,15 @@ export type State = {
    * different subtree from the Trigger, so the store is what carries it across.
    */
   triggerNode: unknown;
+  /**
+   * The trigger's measured width, the React Native counterpart of the web's
+   * `--anchor-width` CSS variable.
+   */
+  triggerWidth: number | undefined;
+  /**
+   * The trigger's measured height.
+   */
+  triggerHeight: number | undefined;
   /**
    * Set by the Positioner so the Trigger can request a reposition when it is
    * laid out. React Native has no `autoUpdate`.
@@ -57,6 +66,8 @@ const selectors = {
   descriptionElementId: createSelector((state: State) => state.descriptionElementId),
   disablePointerDismissal: createSelector((state: State) => state.disablePointerDismissal),
   triggerNode: createSelector((state: State) => state.triggerNode),
+  triggerWidth: createSelector((state: State) => state.triggerWidth),
+  triggerHeight: createSelector((state: State) => state.triggerHeight),
   update: createSelector((state: State) => state.update),
   payload: createSelector((state: State) => state.payload),
   triggerId: createSelector((state: State) => state.triggerIdProp ?? state.triggerId),
@@ -75,6 +86,8 @@ export class PopoverStore extends ReactStore<Readonly<State>, Context, typeof se
         descriptionElementId: undefined,
         disablePointerDismissal: false,
         triggerNode: null,
+        triggerWidth: undefined,
+        triggerHeight: undefined,
         update: undefined,
         payload: undefined,
         triggerId: null,

package/src/popover/trigger/PopoverTrigger.tsx

@@ -1,6 +1,6 @@
 'use client';
 import * as React from 'react';
-import { Pressable, type GestureResponderEvent } from 'react-native';
+import { Pressable, type GestureResponderEvent, type LayoutChangeEvent } from 'react-native';
 import { PopoverRootContext } from '../root/PopoverRootContext';
 import { useRenderElement } from '../../use-render/useRenderElement';
 import { useButton } from '../../internals/use-button/useButton';
@@ -99,7 +99,10 @@ export function PopoverTrigger<Payload = unknown>(componentProps: PopoverTrigger
         onPressOut() {
           setPressed(false);
         },
-        onLayout() {
+        onLayout(event: LayoutChangeEvent) {
+          const { width, height } = event.nativeEvent.layout;
+          store.set('triggerWidth', width);
+          store.set('triggerHeight', height);
           // Nothing tracks the anchor globally in React Native, so a moved or
           // resized trigger has to ask the positioner to recompute.
           store.state.update?.();

package/src/progress/root/ProgressRoot.tsx

@@ -62,7 +62,10 @@ export function ProgressRoot(componentProps: ProgressRoot.Props) {
       : formatNumber(percentageValue / 100, locale, { style: 'percent' });
   }
 
-  const state: ProgressRootState = React.useMemo(() => ({ status }), [status]);
+  const state: ProgressRootState = React.useMemo(
+    () => ({ status, value: clampedValue, min, max, percent: percentageValue, formattedValue }),
+    [status, clampedValue, min, max, percentageValue, formattedValue],
+  );
 
   const contextValue: ProgressRootContext = React.useMemo(
     () => ({ formattedValue, percentageValue, setLabelId, state, value }),
@@ -102,6 +105,27 @@ export interface ProgressRootState {
    * The current status.
    */
   status: ProgressStatus;
+  /**
+   * The current value, clamped into `[min, max]`, or `null` while indeterminate.
+   */
+  value: number | null;
+  /**
+   * The minimum value.
+   */
+  min: number;
+  /**
+   * The maximum value.
+   */
+  max: number;
+  /**
+   * How far the value sits through the range, `0`–`100`, or `null` while
+   * indeterminate. This is what an indicator's width comes from.
+   */
+  percent: number | null;
+  /**
+   * The value as text, through `format`/`locale`. Empty while indeterminate.
+   */
+  formattedValue: string;
 }
 
 export interface ProgressRootProps extends ZestUIComponentProps<typeof View, ProgressRootState> {

package/src/radio-group/RadioGroup.tsx

@@ -29,7 +29,9 @@ export function RadioGroup<Value = any>(componentProps: RadioGroup.Props<Value>)
     ...elementProps
   } = componentProps;
 
-  const { fieldDisabled, fieldProps, validateField } = useFieldControlRegistration();
+  const { fieldDisabled, fieldProps, markChanged, markTouched } = useFieldControlRegistration({
+    initialValue: defaultValue ?? valueProp,
+  });
 
   const disabled = disabledProp || fieldDisabled;
 
@@ -49,7 +51,8 @@ export function RadioGroup<Value = any>(componentProps: RadioGroup.Props<Value>)
       }
 
       setCheckedValueUnwrapped(value);
-      validateField(value);
+      markChanged(value);
+      markTouched(value);
     },
   );
 

package/src/select/backdrop/SelectBackdrop.tsx

@@ -25,6 +25,10 @@ export function SelectBackdrop(componentProps: SelectBackdrop.Props) {
       {
         style: StyleSheet.absoluteFill,
         onPress(event: GestureResponderEvent) {
+          if (store.select('disablePointerDismissal')) {
+            return;
+          }
+
           store.setOpen(false, createChangeEventDetails(REASONS.outsidePress, event));
         },
       },

package/src/select/index.parts.ts

@@ -1,4 +1,5 @@
 export { SelectRoot as Root } from './root/SelectRoot';
+export { createSelectHandle as createHandle, SelectHandle as Handle } from './store/SelectHandle';
 export { SelectLabel as Label } from './label/SelectLabel';
 export { SelectTrigger as Trigger } from './trigger/SelectTrigger';
 export { SelectValue as Value } from './value/SelectValue';

package/src/select/popup/SelectPopup.tsx

@@ -21,8 +21,17 @@ export function SelectPopup(componentProps: SelectPopup.Props) {
   const { transitionStatus } = useSelectTransitionContext() ?? { transitionStatus: undefined };
 
   const open = store.useState('open');
+  const triggerWidth = store.useState('triggerWidth');
+  const triggerHeight = store.useState('triggerHeight');
 
-  const state: SelectPopupState = { open, transitionStatus, side, align };
+  const state: SelectPopupState = {
+    open,
+    transitionStatus,
+    side,
+    align,
+    triggerWidth,
+    triggerHeight,
+  };
 
   const element = useRenderElement(View, componentProps, {
     state,
@@ -59,6 +68,14 @@ export interface SelectPopupState {
    * The alignment the popup was actually placed with.
    */
   align: Align;
+  /**
+   * The trigger's measured width, available for consumers to apply to the popup.
+   */
+  triggerWidth: number | undefined;
+  /**
+   * The trigger's measured height.
+   */
+  triggerHeight: number | undefined;
 }
 
 export interface SelectPopupProps extends ZestUIComponentProps<typeof View, SelectPopupState> {}

package/src/select/positioner/SelectPositioner.tsx

@@ -39,6 +39,8 @@ export function SelectPositioner(componentProps: SelectPositioner.Props) {
   const store = useSelectRootContext();
   const open = store.useState('open');
   const triggerNode = store.useState('triggerNode');
+  const triggerWidth = store.useState('triggerWidth');
+  const triggerHeight = store.useState('triggerHeight');
 
   const positioning = useAnchorPositioning({
     align,
@@ -65,7 +67,13 @@ export function SelectPositioner(componentProps: SelectPositioner.Props) {
 
   const mergedRef = useMergedRefs(ref, refs.setFloating);
 
-  const state: SelectPositionerState = { open, side: positioning.side, align: positioning.align };
+  const state: SelectPositionerState = {
+    open,
+    side: positioning.side,
+    align: positioning.align,
+    triggerWidth,
+    triggerHeight,
+  };
 
   const contextValue: SelectPositionerContext = React.useMemo(
     () => ({ side: positioning.side, align: positioning.align, arrowRef, arrowStyles }),
@@ -97,6 +105,15 @@ export interface SelectPositionerState {
   open: boolean;
   side: Side;
   align: Align;
+  /**
+   * The trigger's measured width, available for consumers to apply to the popup.
+   * This is the React Native equivalent of the web's `--anchor-width` CSS variable.
+   */
+  triggerWidth: number | undefined;
+  /**
+   * The trigger's measured height.
+   */
+  triggerHeight: number | undefined;
 }
 
 export interface SelectPositionerProps

package/src/select/root/SelectRoot.tsx

@@ -1,9 +1,13 @@
 'use client';
 import * as React from 'react';
 import { useRefWithInit } from '../../hooks/useRefWithInit';
+import { useStableCallback } from '../../hooks/useStableCallback';
 import { useTransitionStatus } from '../../internals/useTransitionStatus';
+import { usePopupRootHandle } from '../../utils/popups/usePopupRootHandle';
+import { useFieldControlRegistration } from '../../internals/field/useFieldControlRegistration';
 import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
 import type { REASONS } from '../../utils/reasons';
+import type { SelectHandle } from '../store/SelectHandle';
 import { SelectStore, type SelectItems } from '../store/SelectStore';
 import { SelectRootContext } from './SelectRootContext';
 import { SelectTransitionContext } from './SelectTransitionContext';
@@ -15,12 +19,18 @@ import { SelectTransitionContext } from './SelectTransitionContext';
  * Unlike the web version there is no hidden `<select>`: React Native has no form
  * submission, so `name`/`form` are omitted. Multi-select is not ported yet.
  */
-export function SelectRoot<Value = any>(props: SelectRoot.Props<Value>) {
+export function SelectRoot<Value = any, Payload = unknown>(
+  props: SelectRoot.Props<Value, Payload>,
+) {
   const {
+    actionsRef,
     children,
     defaultOpen = false,
+    defaultTriggerId = null,
     defaultValue,
-    disabled = false,
+    disablePointerDismissal = false,
+    disabled: disabledProp = false,
+    handle,
     items,
     multiple = false,
     onOpenChange,
@@ -28,9 +38,16 @@ export function SelectRoot<Value = any>(props: SelectRoot.Props<Value>) {
     open,
     readOnly = false,
     required = false,
+    triggerId,
     value,
   } = props;
 
+  const { fieldDisabled, markChanged, markTouched } = useFieldControlRegistration({
+    initialValue: defaultValue ?? value ?? (multiple ? [] : undefined),
+  });
+
+  const disabled = disabledProp || fieldDisabled;
+
   const store = useRefWithInit(
     () =>
       new SelectStore({
@@ -45,18 +62,60 @@ export function SelectRoot<Value = any>(props: SelectRoot.Props<Value>) {
         disabled,
         readOnly,
         required,
+        disablePointerDismissal,
+        triggerId: defaultTriggerId,
+        triggerIdProp: triggerId,
       }),
   ).current;
 
+  // Wrapping the consumer's callbacks is what lets a select report itself to a
+  // surrounding `Field.Root`: choosing a value makes the field dirty, and
+  // closing the popup is the select's equivalent of a blur.
+  const handleValueChange = useStableCallback(
+    (nextValue: Value, eventDetails: SelectRoot.ChangeEventDetails) => {
+      onValueChange?.(nextValue, eventDetails);
+
+      if (eventDetails.isCanceled) {
+        return;
+      }
+
+      markChanged(nextValue);
+    },
+  );
+
+  const handleOpenChange = useStableCallback(
+    (nextOpen: boolean, eventDetails: SelectRoot.ChangeEventDetails) => {
+      onOpenChange?.(nextOpen, eventDetails);
+
+      if (eventDetails.isCanceled || nextOpen) {
+        return;
+      }
+
+      markTouched(store.select('value'));
+    },
+  );
+
   store.useControlledProp('openProp', open);
   store.useControlledProp('valueProp', value);
-  store.useContextCallback('onOpenChange', onOpenChange);
-  store.useContextCallback('onValueChange', onValueChange);
-  store.useSyncedValues({ disabled, readOnly, required, items, multiple });
+  store.useControlledProp('triggerIdProp', triggerId);
+  store.useContextCallback('onOpenChange', handleOpenChange);
+  store.useContextCallback('onValueChange', handleValueChange);
+  store.useSyncedValues({
+    disabled,
+    readOnly,
+    required,
+    items,
+    multiple,
+    disablePointerDismissal,
+  });
+
+  usePopupRootHandle({ store, handle, actionsRef });
 
   const resolvedOpen = store.useState('open');
   const { transitionStatus } = useTransitionStatus(resolvedOpen, false, true);
 
+  const payload = store.useState('payload') as Payload;
+
   const transitionContextValue = React.useMemo(
     () => ({ transitionStatus }),
     [transitionStatus],
@@ -65,7 +124,7 @@ export function SelectRoot<Value = any>(props: SelectRoot.Props<Value>) {
   return (
     <SelectRootContext.Provider value={store}>
       <SelectTransitionContext.Provider value={transitionContextValue}>
-        {children}
+        {typeof children === 'function' ? children(payload) : children}
       </SelectTransitionContext.Provider>
     </SelectRootContext.Provider>
   );
@@ -73,7 +132,19 @@ export function SelectRoot<Value = any>(props: SelectRoot.Props<Value>) {
 
 export interface SelectRootState {}
 
-export interface SelectRootProps<Value = any> {
+export interface SelectRootActions {
+  /**
+   * 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;
+}
+
+export interface SelectRootProps<Value = any, Payload = unknown> {
   /**
    * The value of the currently selected item.
    *
@@ -145,10 +216,38 @@ export interface SelectRootProps<Value = any> {
    * ```
    */
   items?: SelectItems | undefined;
+  /**
+   * Whether to prevent the popup from closing on presses outside it.
+   * @default false
+   */
+  disablePointerDismissal?: boolean | undefined;
+  /**
+   * A ref to imperative actions.
+   */
+  actionsRef?: React.RefObject<SelectRoot.Actions | null> | undefined;
+  /**
+   * A handle associating this select with triggers rendered outside it, and
+   * letting it be opened and closed imperatively. Create one with
+   * `Select.createHandle()`.
+   */
+  handle?: SelectHandle<Payload> | undefined;
+  /**
+   * The id of the trigger the popup is anchored to. Useful together with the
+   * `open` prop, to control which trigger a controlled select belongs to.
+   */
+  triggerId?: string | null | undefined;
+  /**
+   * The id of the trigger the popup is initially anchored to. Useful together
+   * with `defaultOpen`.
+   */
+  defaultTriggerId?: string | null | undefined;
   /**
    * The content of the select.
+   *
+   * Pass a function to receive the payload the select was opened with, via a
+   * trigger's `payload` prop.
    */
-  children?: React.ReactNode;
+  children?: React.ReactNode | ((payload: Payload) => React.ReactNode);
 }
 
 export type SelectRootChangeEventReason =
@@ -163,7 +262,8 @@ export type SelectRootChangeEventDetails = ZestChangeEventDetails<SelectRootChan
 
 export namespace SelectRoot {
   export type State = SelectRootState;
-  export type Props<TValue = any> = SelectRootProps<TValue>;
+  export type Props<TValue = any, TPayload = unknown> = SelectRootProps<TValue, TPayload>;
+  export type Actions = SelectRootActions;
   export type ChangeEventReason = SelectRootChangeEventReason;
   export type ChangeEventDetails = SelectRootChangeEventDetails;
 }

package/src/select/store/SelectHandle.ts

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