@limonify/zest-ui 0.1.0

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

@@ -0,0 +1,300 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useControlled } from '../../hooks/useControlled';
+import { useId } from '../../hooks/useId';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { CompositeList } from '../../internals/composite/list/CompositeList';
+import type { ZestUIComponentProps } from '../../types';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import {
+  getOTPValidationConfig,
+  normalizeOTPValue,
+  normalizeOTPValueWithDetails,
+  type OTPValidationType,
+} from '../utils/otp';
+import { OTPFieldRootContext } from './OTPFieldRootContext';
+
+/**
+ * Groups all parts of the OTP field.
+ * Renders a `<View>`.
+ *
+ * **Not ported from upstream.** `name`/`form`/`required`/`autoSubmit` (the hidden
+ * input and form submission — see the standing decision in CLAUDE.md), and
+ * `pattern`, which is HTML constraint validation.
+ */
+export function OTPFieldRoot(componentProps: OTPFieldRoot.Props) {
+  const {
+    autoComplete = 'one-time-code',
+    className,
+    defaultValue,
+    disabled = false,
+    id: idProp,
+    length,
+    mask = false,
+    normalizeValue,
+    onValueChange,
+    onValueComplete,
+    onValueInvalid,
+    readOnly = false,
+    render,
+    style,
+    validationType = 'numeric',
+    value: valueProp,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const id = useId(idProp);
+
+  const [value, setValueState] = useControlled<string>({
+    controlled:
+      valueProp === undefined
+        ? undefined
+        : normalizeOTPValue(valueProp, length, validationType, normalizeValue),
+    default: normalizeOTPValue(defaultValue, length, validationType, normalizeValue),
+    name: 'OTPField',
+    state: 'value',
+  });
+
+  const [activeIndex, setActiveIndex] = React.useState(-1);
+  const [, setMap] = React.useState(() => new Map());
+
+  const inputsRef = React.useRef(new Map<number, { focus: () => void }>());
+
+  const registerInput = useStableCallback((index: number, node: { focus: () => void } | null) => {
+    if (node) {
+      inputsRef.current.set(index, node);
+    } else {
+      inputsRef.current.delete(index);
+    }
+  });
+
+  const focusInput = useStableCallback((index: number) => {
+    inputsRef.current.get(Math.min(Math.max(index, 0), length - 1))?.focus();
+  });
+
+  const reportValueInvalid = useStableCallback(
+    (invalidValue: string, eventDetails: OTPFieldRoot.InvalidEventDetails) => {
+      onValueInvalid?.(invalidValue, eventDetails);
+    },
+  );
+
+  const setValue = useStableCallback(
+    (nextValue: string, eventDetails: OTPFieldRoot.ChangeEventDetails) => {
+      const [normalized] = normalizeOTPValueWithDetails(
+        nextValue,
+        length,
+        validationType,
+        normalizeValue,
+      );
+
+      if (normalized === value) {
+        return normalized;
+      }
+
+      onValueChange?.(normalized, eventDetails);
+
+      if (eventDetails.isCanceled) {
+        return null;
+      }
+
+      setValueState(normalized);
+
+      if (normalized.length === length) {
+        onValueComplete?.(normalized, createChangeEventDetails(eventDetails.reason));
+      }
+
+      return normalized;
+    },
+  );
+
+  const state: OTPFieldRootState = React.useMemo(
+    () => ({
+      disabled,
+      readOnly,
+      value,
+      length,
+      mask,
+      complete: value.length === length,
+      activeIndex,
+    }),
+    [disabled, readOnly, value, length, mask, activeIndex],
+  );
+
+  const contextValue: OTPFieldRootContext = React.useMemo(
+    () => ({
+      state,
+      value,
+      length,
+      mask,
+      disabled,
+      readOnly,
+      autoComplete,
+      keyboardType: getOTPValidationConfig(validationType)?.inputMode === 'numeric'
+        ? 'number-pad'
+        : 'default',
+      activeIndex,
+      setActiveIndex,
+      validationType,
+      normalizeValue,
+      id,
+      registerInput,
+      focusInput,
+      reportValueInvalid,
+      setValue,
+    }),
+    [
+      state,
+      value,
+      length,
+      mask,
+      disabled,
+      readOnly,
+      autoComplete,
+      validationType,
+      activeIndex,
+      normalizeValue,
+      id,
+      registerInput,
+      focusInput,
+      reportValueInvalid,
+      setValue,
+    ],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: elementProps,
+  });
+
+  return (
+    <OTPFieldRootContext.Provider value={contextValue}>
+      <CompositeList onMapChange={setMap}>{element}</CompositeList>
+    </OTPFieldRootContext.Provider>
+  );
+}
+
+export interface OTPFieldRootState {
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the user should be unable to change the field value.
+   */
+  readOnly: boolean;
+  /**
+   * The current OTP value.
+   */
+  value: string;
+  /**
+   * The number of slots.
+   */
+  length: number;
+  /**
+   * Whether the slots mask their characters.
+   */
+  mask: boolean;
+  /**
+   * Whether every slot is filled.
+   */
+  complete: boolean;
+  /**
+   * The slot that currently has focus, or `-1` when none does.
+   */
+  activeIndex: number;
+}
+
+export interface OTPFieldRootProps
+  extends Omit<ZestUIComponentProps<typeof View, OTPFieldRootState>, 'id'> {
+  /**
+   * The number of OTP input slots.
+   */
+  length: number;
+  /**
+   * The OTP value.
+   */
+  value?: string | undefined;
+  /**
+   * The uncontrolled OTP value when the component is initially rendered.
+   */
+  defaultValue?: string | undefined;
+  /**
+   * The id of the first input. Subsequent inputs derive theirs from it
+   * (`{id}-2`, `{id}-3`, and so on).
+   */
+  id?: string | undefined;
+  /**
+   * The autofill hint applied to the first slot. `'one-time-code'` is what lets
+   * the OS offer a code it read from an SMS.
+   * @default 'one-time-code'
+   */
+  autoComplete?: string | undefined;
+  /**
+   * Whether the slots should mask entered characters.
+   * @default false
+   */
+  mask?: boolean | undefined;
+  /**
+   * The type of validation applied to the OTP value.
+   * @default 'numeric'
+   */
+  validationType?: OTPValidationType | undefined;
+  /**
+   * Normalizes the OTP value after whitespace and `validationType` filtering.
+   * It must be idempotent: the same value may be normalized more than once.
+   */
+  normalizeValue?: ((value: string) => string) | undefined;
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * Whether the user should be unable to change the field value.
+   * @default false
+   */
+  readOnly?: boolean | undefined;
+  /**
+   * Callback fired when the OTP value changes.
+   */
+  onValueChange?:
+    | ((value: string, eventDetails: OTPFieldRoot.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Callback fired when entered text contains characters rejected by validation
+   * or normalization. The `value` argument is what the user attempted to enter,
+   * before normalization.
+   */
+  onValueInvalid?:
+    | ((value: string, eventDetails: OTPFieldRoot.InvalidEventDetails) => void)
+    | undefined;
+  /**
+   * Callback fired when the OTP value becomes complete.
+   */
+  onValueComplete?:
+    | ((value: string, eventDetails: OTPFieldRoot.CompleteEventDetails) => void)
+    | undefined;
+}
+
+export type OTPFieldRootChangeEventReason =
+  | typeof REASONS.inputChange
+  | typeof REASONS.inputClear
+  | typeof REASONS.none;
+
+export type OTPFieldRootChangeEventDetails = ZestChangeEventDetails<OTPFieldRootChangeEventReason>;
+
+export namespace OTPFieldRoot {
+  export type State = OTPFieldRootState;
+  export type Props = OTPFieldRootProps;
+  export type ValidationType = OTPValidationType;
+  export type ChangeEventReason = OTPFieldRootChangeEventReason;
+  export type ChangeEventDetails = OTPFieldRootChangeEventDetails;
+  export type InvalidEventDetails = OTPFieldRootChangeEventDetails;
+  export type CompleteEventDetails = OTPFieldRootChangeEventDetails;
+}

package/src/otp-field/root/OTPFieldRootContext.ts

@@ -0,0 +1,52 @@
+'use client';
+import * as React from 'react';
+import type { OTPFieldRoot, OTPFieldRootState } from './OTPFieldRoot';
+import type { OTPFieldInputState } from '../input/OTPFieldInput';
+
+export interface OTPFieldRootContext {
+  state: OTPFieldRootState;
+  value: string;
+  length: number;
+  mask: boolean;
+  disabled: boolean;
+  readOnly: boolean;
+  autoComplete: string | undefined;
+  keyboardType: 'number-pad' | 'default';
+  activeIndex: number;
+  setActiveIndex: (index: number) => void;
+  validationType: OTPFieldRoot.ValidationType;
+  normalizeValue: ((value: string) => string) | undefined;
+  /**
+   * The id of the first slot; the rest derive theirs from it.
+   */
+  id: string | undefined;
+  registerInput: (index: number, node: { focus: () => void } | null) => void;
+  focusInput: (index: number) => void;
+  reportValueInvalid: (value: string, eventDetails: OTPFieldRoot.InvalidEventDetails) => void;
+  /**
+   * Commits a value, normalized and clamped to `length`. Returns the stored value,
+   * or `null` when the change was vetoed.
+   */
+  setValue: (value: string, eventDetails: OTPFieldRoot.ChangeEventDetails) => string | null;
+}
+
+export const OTPFieldRootContext = React.createContext<OTPFieldRootContext | undefined>(undefined);
+
+export function useOTPFieldRootContext() {
+  const context = React.useContext(OTPFieldRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: OTPFieldRootContext is missing. OTPField parts must be placed within <OTPField.Root>.',
+    );
+  }
+
+  return context;
+}
+
+export function getOTPFieldInputState(
+  state: OTPFieldRootState,
+  value: string,
+  index: number,
+): OTPFieldInputState {
+  return { ...state, value, index, filled: value !== '' };
+}

package/src/otp-field/utils/otp.ts

@@ -0,0 +1,118 @@
+interface OTPValidationConfig {
+  slotPattern: string;
+  getRootPattern: (length: number) => string;
+  regexp: RegExp;
+  inputMode: 'numeric' | 'text';
+}
+
+export type OTPValidationType = 'numeric' | 'alpha' | 'alphanumeric' | 'none';
+
+const OTP_VALIDATION_CONFIG: Record<Exclude<OTPValidationType, 'none'>, OTPValidationConfig> = {
+  numeric: {
+    slotPattern: '\\d{1}',
+    getRootPattern: (length) => `\\d{${length}}`,
+    regexp: /[^\d]/g,
+    inputMode: 'numeric',
+  },
+  alpha: {
+    slotPattern: '[a-zA-Z]{1}',
+    getRootPattern: (length) => `[a-zA-Z]{${length}}`,
+    regexp: /[^a-zA-Z]/g,
+    inputMode: 'text',
+  },
+  alphanumeric: {
+    slotPattern: '[a-zA-Z0-9]{1}',
+    getRootPattern: (length) => `[a-zA-Z0-9]{${length}}`,
+    regexp: /[^a-zA-Z0-9]/g,
+    inputMode: 'text',
+  },
+};
+
+export function getOTPValidationConfig(validationType: OTPValidationType) {
+  if (validationType === 'none') {
+    return null;
+  }
+
+  return OTP_VALIDATION_CONFIG[validationType];
+}
+
+export function stripOTPWhitespace(value: string | null | undefined) {
+  return (value ?? '').replace(/\s/g, '');
+}
+
+function applyOTPValidation(value: string, validation: OTPValidationConfig | null) {
+  return validation ? value.replace(validation.regexp, '') : value;
+}
+
+/**
+ * Normalizes user-entered OTP text by stripping whitespace, applying validation and custom
+ * normalization, and clamping the final value to the configured slot count.
+ */
+export function normalizeOTPValueWithDetails(
+  value: string | null | undefined,
+  length: number,
+  validationType: OTPValidationType,
+  normalizeValue?: ((value: string) => string) | undefined,
+): readonly [value: string, didRejectCharacters: boolean] {
+  const strippedValue = stripOTPWhitespace(value);
+  const validation = getOTPValidationConfig(validationType);
+  let normalizedValue = applyOTPValidation(strippedValue, validation);
+  let didRejectCharacters = strippedValue.length > normalizedValue.length;
+
+  if (normalizeValue) {
+    const customNormalizedValue = normalizeValue(normalizedValue);
+    didRejectCharacters ||= normalizedValue.length > customNormalizedValue.length;
+    normalizedValue = applyOTPValidation(customNormalizedValue, validation);
+    didRejectCharacters ||= customNormalizedValue.length > normalizedValue.length;
+  }
+
+  // Slice by Unicode code points so multi-byte characters do not split across OTP slots.
+  const maxLength = length < 0 ? 0 : length;
+  const normalizedCharacters = Array.from(normalizedValue);
+
+  return [
+    normalizedCharacters.slice(0, maxLength).join(''),
+    didRejectCharacters || normalizedCharacters.length > maxLength,
+  ];
+}
+
+export function normalizeOTPValue(
+  value: string | null | undefined,
+  length: number,
+  validationType: OTPValidationType,
+  normalizeValue?: ((value: string) => string) | undefined,
+) {
+  return normalizeOTPValueWithDetails(value, length, validationType, normalizeValue)[0];
+}
+
+/**
+ * Replaces characters starting at the provided slot index, then re-normalizes the final OTP value
+ * so paste and multi-character edits stay contiguous and length-bounded.
+ */
+export function replaceOTPValue(
+  currentValue: string,
+  index: number,
+  nextValue: string,
+  length: number,
+  validationType: OTPValidationType,
+  normalizeValue?: ((value: string) => string) | undefined,
+) {
+  const normalizedValue = normalizeOTPValue(nextValue, length, validationType, normalizeValue);
+  const prefix = currentValue.slice(0, index);
+  const suffix = currentValue.slice(index + normalizedValue.length);
+
+  return normalizeOTPValue(
+    `${prefix}${normalizedValue}${suffix}`,
+    length,
+    validationType,
+    normalizeValue,
+  );
+}
+
+export function removeOTPCharacter(currentValue: string, index: number) {
+  if (index < 0 || index >= currentValue.length) {
+    return currentValue;
+  }
+
+  return `${currentValue.slice(0, index)}${currentValue.slice(index + 1)}`;
+}

package/src/popover/arrow/PopoverArrow.tsx

@@ -0,0 +1,56 @@
+'use client';
+import { View } from 'react-native';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { usePopoverPositionerContext } from '../positioner/PopoverPositionerContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import type { Align, Side } from '../../utils/useAnchorPositioning';
+import type { ZestUIComponentProps } from '../../types';
+
+/**
+ * Displays an element positioned against the popover anchor.
+ * Renders a `<View>`.
+ *
+ * The arrow is positioned for you; its shape and size are yours. `state.side`
+ * tells you which edge of the popup it sits on.
+ */
+export function PopoverArrow(componentProps: PopoverArrow.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const store = usePopoverRootContext();
+  const { side, align, arrowRef, arrowStyles } = usePopoverPositionerContext();
+
+  const open = store.useState('open');
+
+  const mergedRef = useMergedRefs(ref, arrowRef as React.Ref<unknown>);
+
+  const state: PopoverArrowState = { open, side, align };
+
+  return useRenderElement(View, componentProps, {
+    state,
+    ref: mergedRef,
+    props: [{ style: { position: 'absolute' as const, ...arrowStyles } }, elementProps],
+  });
+}
+
+export interface PopoverArrowState {
+  /**
+   * 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 PopoverArrowProps extends ZestUIComponentProps<typeof View, PopoverArrowState> {}
+
+export namespace PopoverArrow {
+  export type State = PopoverArrowState;
+  export type Props = PopoverArrowProps;
+}

package/src/popover/backdrop/PopoverBackdrop.tsx

@@ -0,0 +1,58 @@
+'use client';
+import { Pressable, StyleSheet, type GestureResponderEvent } from 'react-native';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A backdrop for the popover, and the surface that dismisses it.
+ * Renders a `<Pressable>`.
+ *
+ * Unlike `Dialog`, the popover has no separate viewport part: the backdrop is
+ * both the (optional) dimming layer and the outside-press surface, matching
+ * upstream, where `Popover.Backdrop` is what closes the popup.
+ */
+export function PopoverBackdrop(componentProps: PopoverBackdrop.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const store = usePopoverRootContext();
+  const open = store.useState('open');
+  const disablePointerDismissal = store.useState('disablePointerDismissal');
+
+  const state: PopoverBackdropState = { open };
+
+  return useRenderElement(Pressable, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        style: StyleSheet.absoluteFill,
+        onPress(event: GestureResponderEvent) {
+          if (disablePointerDismissal) {
+            return;
+          }
+
+          store.setOpen(false, createChangeEventDetails(REASONS.outsidePress, event));
+        },
+      },
+      elementProps,
+    ],
+  });
+}
+
+export interface PopoverBackdropState {
+  /**
+   * Whether the popover is currently open.
+   */
+  open: boolean;
+}
+
+export interface PopoverBackdropProps
+  extends ZestUIComponentProps<typeof Pressable, PopoverBackdropState> {}
+
+export namespace PopoverBackdrop {
+  export type State = PopoverBackdropState;
+  export type Props = PopoverBackdropProps;
+}

package/src/popover/close/PopoverClose.tsx

@@ -0,0 +1,70 @@
+'use client';
+import * as React from 'react';
+import { Pressable, type GestureResponderEvent } from 'react-native';
+import { usePopoverRootContext } from '../root/PopoverRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useButton } from '../../internals/use-button/useButton';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * A button that closes the popover.
+ * Renders a `<Pressable>`.
+ */
+export function PopoverClose(componentProps: PopoverClose.Props) {
+  const { render, className, style, disabled = false, ref, ...elementProps } = componentProps;
+
+  const store = usePopoverRootContext();
+
+  const [pressed, setPressed] = React.useState(false);
+
+  const { getButtonProps } = useButton({ disabled });
+
+  const state: PopoverCloseState = { disabled, pressed };
+
+  return useRenderElement(Pressable, componentProps, {
+    state,
+    ref,
+    props: [
+      {
+        onPress(event: GestureResponderEvent) {
+          store.setOpen(false, createChangeEventDetails(REASONS.closePress, event));
+        },
+        onPressIn() {
+          setPressed(true);
+        },
+        onPressOut() {
+          setPressed(false);
+        },
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+}
+
+export interface PopoverCloseState {
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the close button is currently pressed.
+   */
+  pressed: boolean;
+}
+
+export interface PopoverCloseProps
+  extends ZestUIComponentProps<typeof Pressable, PopoverCloseState> {
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+}
+
+export namespace PopoverClose {
+  export type State = PopoverCloseState;
+  export type Props = PopoverCloseProps;
+}

package/src/popover/description/PopoverDescription.tsx

@@ -0,0 +1,35 @@
+'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 paragraph with additional information about the popover.
+ * Renders a `<Text>`.
+ */
+export function PopoverDescription(componentProps: PopoverDescription.Props) {
+  const { render, className, style, nativeID: idProp, ref, ...elementProps } = componentProps;
+
+  const store = usePopoverRootContext();
+
+  const id = useId(idProp ?? undefined);
+
+  store.useSyncedValueWithCleanup('descriptionElementId', id);
+
+  return useRenderElement(Text, componentProps, {
+    ref,
+    props: [{ nativeID: id }, elementProps],
+  });
+}
+
+export interface PopoverDescriptionProps
+  extends ZestUIComponentProps<typeof Text, PopoverDescriptionState> {}
+
+export interface PopoverDescriptionState {}
+
+export namespace PopoverDescription {
+  export type Props = PopoverDescriptionProps;
+  export type State = PopoverDescriptionState;
+}

package/src/popover/index.parts.ts

@@ -0,0 +1,11 @@
+export { PopoverRoot as Root } from './root/PopoverRoot';
+export { createPopoverHandle as createHandle, PopoverHandle as Handle } from './store/PopoverHandle';
+export { PopoverTrigger as Trigger } from './trigger/PopoverTrigger';
+export { PopoverPortal as Portal } from './portal/PopoverPortal';
+export { PopoverBackdrop as Backdrop } from './backdrop/PopoverBackdrop';
+export { PopoverPositioner as Positioner } from './positioner/PopoverPositioner';
+export { PopoverPopup as Popup } from './popup/PopoverPopup';
+export { PopoverArrow as Arrow } from './arrow/PopoverArrow';
+export { PopoverTitle as Title } from './title/PopoverTitle';
+export { PopoverDescription as Description } from './description/PopoverDescription';
+export { PopoverClose as Close } from './close/PopoverClose';