@limonify/zest-ui 0.1.0

package/src/number-field/root/NumberFieldRoot.tsx

@@ -0,0 +1,373 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { useControlled } from '../../hooks/useControlled';
+import { useIsoLayoutEffect } from '../../hooks/useIsoLayoutEffect';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useFieldControlRegistration } from '../../internals/field/useFieldControlRegistration';
+import { formatNumber } from '../../utils/formatNumber';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import type { ZestChangeEventDetails } from '../../utils/createChangeEventDetails';
+import type { REASONS } from '../../utils/reasons';
+import { toValidatedNumber } from '../utils/validate';
+import {
+  NumberFieldRootContext,
+  type NumberFieldIncrementParameters,
+} from './NumberFieldRootContext';
+
+/**
+ * Groups all parts of the number field.
+ * Renders a `<View>`.
+ *
+ * **Not ported from upstream.** `name`/`form`/`required`/`inputRef` (the hidden
+ * input and form submission — see the standing decision in CLAUDE.md);
+ * `allowWheelScrub` (no mouse wheel); and `smallStep`/`largeStep`, which upstream
+ * steps by while the alt/shift key is held — a touch keyboard has neither, the
+ * same reason `Slider` drops `largeStep`. Arrow-key stepping and the
+ * `input-paste` reason go with them: React Native's `TextInput` reports edits
+ * through `onChangeText`, which cannot tell a paste from typing.
+ */
+export function NumberFieldRoot(componentProps: NumberFieldRoot.Props) {
+  const {
+    allowOutOfRange = false,
+    className,
+    defaultValue,
+    disabled: disabledProp = false,
+    format,
+    id,
+    locale,
+    max,
+    min,
+    onValueChange,
+    onValueCommitted,
+    readOnly = false,
+    render,
+    snapOnStep = false,
+    step = 1,
+    style,
+    value: valueProp,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const { fieldDisabled, validateField } = useFieldControlRegistration();
+
+  const disabled = disabledProp || fieldDisabled;
+
+  const minWithDefault = min ?? Number.MIN_SAFE_INTEGER;
+  const maxWithDefault = max ?? Number.MAX_SAFE_INTEGER;
+  // Seeding an empty field steps from 0, but 0 may be out of range.
+  const minWithZeroDefault = min ?? 0;
+
+  const [value, setValueState] = useControlled<number | null>({
+    controlled: valueProp,
+    default: defaultValue ?? null,
+    name: 'NumberField',
+    state: 'value',
+  });
+
+  const [inputValue, setInputValue] = React.useState(() => formatNumber(value, locale, format));
+  const [scrubbing, setScrubbing] = React.useState(false);
+
+  const valueRef = React.useRef(value);
+  const lastChangedValueRef = React.useRef<number | null>(null);
+  const formatOptionsRef = React.useRef(format);
+  // False while the user is typing, so their text is not reformatted underneath
+  // them until blur.
+  const allowInputSyncRef = React.useRef(true);
+
+  useIsoLayoutEffect(() => {
+    valueRef.current = value;
+    formatOptionsRef.current = format;
+  });
+
+  // A controlled value changing from outside must be reflected in the text, but
+  // not while the user is mid-edit.
+  useIsoLayoutEffect(() => {
+    if (allowInputSyncRef.current) {
+      setInputValue(formatNumber(value, locale, format));
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value, locale, JSON.stringify(format)]);
+
+  const getStepAmount = useStableCallback(() => (step === 'any' ? 1 : step));
+
+  const setValue = useStableCallback(
+    (unvalidatedValue: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => {
+      const direction = eventDetails.direction;
+
+      // Direct text entry behaves natively; step-based interactions (buttons,
+      // scrub) do not. Every direct-entry reason shares the `input-` prefix.
+      const isInputReason =
+        eventDetails.reason.startsWith('input-') || eventDetails.reason === 'none';
+      const shouldClampValue = !allowOutOfRange || !isInputReason;
+
+      const validatedValue = toValidatedNumber(
+        unvalidatedValue,
+        direction ? getStepAmount() * direction : undefined,
+        minWithDefault,
+        maxWithDefault,
+        minWithZeroDefault,
+        formatOptionsRef.current,
+        snapOnStep,
+        // Upstream passes `altKey` here to snap to `smallStep`; there is no alt
+        // key on a touch keyboard, so it is always false.
+        false,
+        shouldClampValue,
+      );
+
+      // Fire even when the number is unchanged for input reasons: the typed text
+      // may clamp or snap back to the current value, and the consumer still needs
+      // to know the text was rejected.
+      const shouldFireChange =
+        validatedValue !== valueRef.current ||
+        (isInputReason &&
+          (unvalidatedValue !== valueRef.current || allowInputSyncRef.current === false));
+
+      if (shouldFireChange) {
+        onValueChange?.(validatedValue, eventDetails);
+
+        if (eventDetails.isCanceled) {
+          return false;
+        }
+
+        valueRef.current = validatedValue;
+        setValueState(validatedValue);
+        validateField(validatedValue);
+      }
+
+      lastChangedValueRef.current = validatedValue;
+
+      if (allowInputSyncRef.current) {
+        setInputValue(formatNumber(validatedValue, locale, format));
+      }
+
+      return shouldFireChange;
+    },
+  );
+
+  const incrementValue = useStableCallback(
+    (amount: number, { direction, currentValue, reason }: NumberFieldIncrementParameters) => {
+      const previousValue = currentValue === undefined ? valueRef.current : currentValue;
+
+      if (typeof previousValue !== 'number') {
+        // Seed an empty field with 0; `setValue` clamps it to the in-range value
+        // nearest 0 (e.g. `max` for a negative range). No `direction`: the seed
+        // is not a step, so it must not be directionally snapped.
+        return setValue(0, createChangeEventDetails(reason));
+      }
+
+      return setValue(
+        previousValue + amount * direction,
+        createChangeEventDetails(reason, undefined, { direction }),
+      );
+    },
+  );
+
+  const handleValueCommitted = useStableCallback(
+    (committedValue: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => {
+      onValueCommitted?.(committedValue, eventDetails);
+    },
+  );
+
+  const state: NumberFieldRootState = React.useMemo(
+    () => ({
+      disabled,
+      readOnly,
+      required: false,
+      scrubbing,
+      value,
+      inputValue,
+      min,
+      max,
+    }),
+    [disabled, readOnly, scrubbing, value, inputValue, min, max],
+  );
+
+  const contextValue: NumberFieldRootContext = React.useMemo(
+    () => ({
+      state,
+      id,
+      min,
+      max,
+      minWithDefault,
+      maxWithDefault,
+      locale,
+      setValue,
+      incrementValue,
+      getStepAmount,
+      setInputValue,
+      setScrubbing,
+      allowInputSyncRef,
+      valueRef,
+      lastChangedValueRef,
+      formatOptionsRef,
+      onValueCommitted: handleValueCommitted,
+    }),
+    [
+      state,
+      id,
+      min,
+      max,
+      minWithDefault,
+      maxWithDefault,
+      locale,
+      setValue,
+      incrementValue,
+      getStepAmount,
+      handleValueCommitted,
+    ],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: elementProps,
+  });
+
+  return (
+    <NumberFieldRootContext.Provider value={contextValue}>{element}</NumberFieldRootContext.Provider>
+  );
+}
+
+export interface NumberFieldRootState {
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the user should be unable to change the field value.
+   */
+  readOnly: boolean;
+  /**
+   * Whether the user must enter a value.
+   */
+  required: boolean;
+  /**
+   * Whether the value is being changed by dragging the scrub area.
+   */
+  scrubbing: boolean;
+  /**
+   * The raw numeric value of the field.
+   */
+  value: number | null;
+  /**
+   * The text currently shown in the input.
+   */
+  inputValue: string;
+  /**
+   * The minimum value of the field.
+   */
+  min: number | undefined;
+  /**
+   * The maximum value of the field.
+   */
+  max: number | undefined;
+}
+
+export interface NumberFieldRootProps
+  extends Omit<ZestUIComponentProps<typeof View, NumberFieldRootState>, 'id'> {
+  /**
+   * The raw numeric value of the field.
+   */
+  value?: number | null | undefined;
+  /**
+   * The uncontrolled value of the field when it's initially rendered.
+   *
+   * To render a controlled number field, use the `value` prop instead.
+   */
+  defaultValue?: number | undefined;
+  /**
+   * The id of the input element.
+   */
+  id?: string | undefined;
+  /**
+   * The minimum value of the field.
+   */
+  min?: number | undefined;
+  /**
+   * The maximum value of the field.
+   */
+  max?: number | undefined;
+  /**
+   * Amount to increment and decrement with the buttons, or to scrub with a drag
+   * in the scrub area.
+   *
+   * Specify `step="any"` to disable step validation; stepping then uses 1.
+   * @default 1
+   */
+  step?: number | 'any' | undefined;
+  /**
+   * Whether the value should snap to the nearest step when incrementing or
+   * decrementing.
+   * @default false
+   */
+  snapOnStep?: boolean | undefined;
+  /**
+   * When true, typed text may fall outside the `min`/`max` range without
+   * clamping. Step-based interactions (buttons, scrub) still clamp.
+   * @default false
+   */
+  allowOutOfRange?: boolean | 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;
+  /**
+   * Options to format the input value.
+   */
+  format?: Intl.NumberFormatOptions | undefined;
+  /**
+   * The locale of the input element.
+   * Defaults to the user's runtime locale.
+   */
+  locale?: Intl.LocalesArgument | undefined;
+  /**
+   * Callback fired when the number value changes.
+   */
+  onValueChange?:
+    | ((value: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void)
+    | undefined;
+  /**
+   * Callback fired when the value is committed: when the input is blurred after
+   * typing, or the press is released after scrubbing or stepping.
+   */
+  onValueCommitted?:
+    | ((value: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void)
+    | undefined;
+}
+
+export type NumberFieldRootChangeEventReason =
+  | typeof REASONS.inputChange
+  | typeof REASONS.inputClear
+  | typeof REASONS.inputBlur
+  | typeof REASONS.incrementPress
+  | typeof REASONS.decrementPress
+  | typeof REASONS.scrub
+  | typeof REASONS.none;
+
+export type NumberFieldRootChangeEventDetails = ZestChangeEventDetails<
+  NumberFieldRootChangeEventReason,
+  {
+    /**
+     * Which way a step went, when the change was a step. Absent for direct text
+     * entry, which must not be directionally snapped.
+     */
+    direction?: 1 | -1 | undefined;
+  }
+>;
+
+export namespace NumberFieldRoot {
+  export type State = NumberFieldRootState;
+  export type Props = NumberFieldRootProps;
+  export type ChangeEventReason = NumberFieldRootChangeEventReason;
+  export type ChangeEventDetails = NumberFieldRootChangeEventDetails;
+}

package/src/number-field/root/NumberFieldRootContext.ts

@@ -0,0 +1,61 @@
+'use client';
+import * as React from 'react';
+import type { NumberFieldRoot, NumberFieldRootState } from './NumberFieldRoot';
+
+export interface NumberFieldRootContext {
+  state: NumberFieldRootState;
+  id: string | undefined;
+  min: number | undefined;
+  max: number | undefined;
+  minWithDefault: number;
+  maxWithDefault: number;
+  locale: Intl.LocalesArgument;
+  /**
+   * Commits a value, validated against min/max/step. Returns whether it was
+   * applied — a vetoed change reports `false` so callers do not commit a value
+   * that was never stored.
+   */
+  setValue: (value: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => boolean;
+  /**
+   * Steps the value by `amount * direction` from the current value, seeding an
+   * empty field with 0.
+   */
+  incrementValue: (amount: number, params: NumberFieldIncrementParameters) => boolean;
+  getStepAmount: () => number;
+  setInputValue: React.Dispatch<React.SetStateAction<string>>;
+  setScrubbing: (scrubbing: boolean) => void;
+  /**
+   * Whether the visible text may be overwritten with the formatted value. It is
+   * false while the user is typing, so their text is not reformatted underneath
+   * them until blur.
+   */
+  allowInputSyncRef: React.RefObject<boolean>;
+  valueRef: React.RefObject<number | null>;
+  lastChangedValueRef: React.RefObject<number | null>;
+  formatOptionsRef: React.RefObject<Intl.NumberFormatOptions | undefined>;
+  onValueCommitted: (
+    value: number | null,
+    eventDetails: NumberFieldRoot.ChangeEventDetails,
+  ) => void;
+}
+
+export interface NumberFieldIncrementParameters {
+  direction: 1 | -1;
+  reason: NumberFieldRoot.ChangeEventReason;
+  currentValue?: number | null | undefined;
+}
+
+export const NumberFieldRootContext = React.createContext<NumberFieldRootContext | undefined>(
+  undefined,
+);
+
+export function useNumberFieldRootContext() {
+  const context = React.useContext(NumberFieldRootContext);
+  if (context === undefined) {
+    throw new Error(
+      'Zest: NumberFieldRootContext is missing. NumberField parts must be placed within <NumberField.Root>.',
+    );
+  }
+
+  return context;
+}

package/src/number-field/root/useNumberFieldStepperButton.tsx

@@ -0,0 +1,136 @@
+'use client';
+import * as React from 'react';
+import { Pressable } from 'react-native';
+import { useNumberFieldRootContext } from './NumberFieldRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useButton } from '../../internals/use-button/useButton';
+import { useInterval } from '../../hooks/useInterval';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import { useTimeout } from '../../hooks/useTimeout';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import type { NumberFieldRootState } from './NumberFieldRoot';
+import { CHANGE_VALUE_TICK_DELAY, START_AUTO_CHANGE_DELAY } from '../utils/constants';
+
+/**
+ * Shared implementation of the increment and decrement buttons. They differ only
+ * in which way they step and which boundary (`max` vs `min`) disables them.
+ *
+ * Holding the button steps repeatedly, as on the web. Upstream builds that on
+ * `usePressAndHold`, which tracks pointer movement to tell a hold from a scroll;
+ * React Native's `Pressable` already cancels a press that turns into a scroll and
+ * calls `onPressOut`, so a timeout and an interval are the whole mechanism here.
+ */
+export function useNumberFieldStepperButton(
+  componentProps: NumberFieldStepperButtonProps,
+  isIncrement: boolean,
+) {
+  const {
+    render,
+    className,
+    disabled: disabledProp = false,
+    style,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const {
+    getStepAmount,
+    incrementValue,
+    lastChangedValueRef,
+    maxWithDefault,
+    minWithDefault,
+    onValueCommitted,
+    state,
+    valueRef,
+  } = useNumberFieldRootContext();
+
+  const { disabled: contextDisabled, readOnly, value } = state;
+
+  const startTimeout = useTimeout();
+  const tickInterval = useInterval();
+
+  const isAtBoundary =
+    value != null && (isIncrement ? value >= maxWithDefault : value <= minWithDefault);
+  const disabled = disabledProp || contextDisabled || readOnly || isAtBoundary;
+
+  const reason = isIncrement ? REASONS.incrementPress : REASONS.decrementPress;
+  const direction = isIncrement ? 1 : -1;
+
+  const [pressed, setPressed] = React.useState(false);
+
+  const step = useStableCallback(() => incrementValue(getStepAmount(), { direction, reason }));
+
+  const stop = useStableCallback(() => {
+    startTimeout.clear();
+    tickInterval.clear();
+    setPressed(false);
+  });
+
+  // A hold that runs past a boundary must stop repeating, even though the button
+  // only re-renders as disabled afterwards.
+  React.useEffect(() => {
+    if (disabled) {
+      startTimeout.clear();
+      tickInterval.clear();
+    }
+  }, [disabled, startTimeout, tickInterval]);
+
+  React.useEffect(() => stop, [stop]);
+
+  const { getButtonProps } = useButton({ disabled });
+
+  const buttonState: NumberFieldStepperButtonState = { ...state, pressed };
+
+  return useRenderElement(Pressable, componentProps, {
+    state: buttonState,
+    ref,
+    props: [
+      {
+        onPressIn() {
+          if (disabled) {
+            return;
+          }
+
+          setPressed(true);
+          step();
+
+          startTimeout.start(START_AUTO_CHANGE_DELAY, () => {
+            tickInterval.start(CHANGE_VALUE_TICK_DELAY, step);
+          });
+        },
+        onPressOut() {
+          if (!pressed) {
+            return;
+          }
+
+          stop();
+          onValueCommitted(
+            lastChangedValueRef.current ?? valueRef.current,
+            createChangeEventDetails(reason),
+          );
+        },
+        accessibilityState: { disabled: disabled || undefined },
+      },
+      elementProps,
+      getButtonProps,
+    ],
+  });
+}
+
+export interface NumberFieldStepperButtonState extends NumberFieldRootState {
+  /**
+   * Whether the button is currently pressed.
+   */
+  pressed: boolean;
+}
+
+export interface NumberFieldStepperButtonProps
+  extends ZestUIComponentProps<typeof Pressable, NumberFieldStepperButtonState> {
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+}

package/src/number-field/scrub-area/NumberFieldScrubArea.tsx

@@ -0,0 +1,137 @@
+'use client';
+import * as React from 'react';
+import { View } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import { useNumberFieldRootContext } from '../root/NumberFieldRootContext';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import type { NumberFieldRootState } from '../root/NumberFieldRoot';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+
+/**
+ * An area where the user can drag to change the field value.
+ * Renders a `<View>` wrapped in a `GestureDetector`.
+ *
+ * **Diverges from the web deliberately.** Upstream holds a pointer lock and reads
+ * `movementX`/`movementY`, which lets the mouse scrub forever in place. A touch
+ * cannot be locked and has no movement deltas, so this is an ordinary drag: the
+ * value steps once for every `pixelSensitivity` pixels travelled. Upstream's
+ * `teleportDistance` and the `ScrubAreaCursor` part go with the pointer lock —
+ * both exist to manage a virtual cursor that a touch screen never shows.
+ *
+ * Requires `react-native-gesture-handler`, and the app to be wrapped in
+ * `<GestureHandlerRootView>`.
+ */
+export function NumberFieldScrubArea(componentProps: NumberFieldScrubArea.Props) {
+  const {
+    render,
+    className,
+    direction = 'horizontal',
+    pixelSensitivity = 2,
+    style,
+    ref,
+    ...elementProps
+  } = componentProps;
+
+  const { testID } = elementProps;
+  const {
+    getStepAmount,
+    incrementValue,
+    lastChangedValueRef,
+    onValueCommitted,
+    setScrubbing,
+    state,
+    valueRef,
+  } = useNumberFieldRootContext();
+
+  const { disabled, readOnly } = state;
+
+  // How much of the drag has already been turned into steps. Kept in a ref
+  // because the gesture runs outside React's render.
+  const appliedRef = React.useRef(0);
+
+  const scrub = useStableCallback((translationX: number, translationY: number) => {
+    const travelled = direction === 'vertical' ? -translationY : translationX;
+    // Only whole steps are applied, and the remainder stays pending so a slow
+    // drag still accumulates instead of being rounded away every frame.
+    const steps = Math.trunc(travelled / pixelSensitivity) - appliedRef.current;
+
+    if (steps === 0) {
+      return;
+    }
+
+    appliedRef.current += steps;
+    incrementValue(getStepAmount() * Math.abs(steps), {
+      direction: steps > 0 ? 1 : -1,
+      reason: REASONS.scrub,
+    });
+  });
+
+  const gesture = React.useMemo(
+    () =>
+      Gesture.Pan()
+        .enabled(!disabled && !readOnly)
+        // A gesture is invisible to the rendered tree, so tests can only reach it
+        // through gesture-handler's registry, which is keyed by this id.
+        .withTestId(testID ?? 'number-field-scrub-area')
+        .onBegin(() => {
+          appliedRef.current = 0;
+          setScrubbing(true);
+        })
+        // The move that activates the pan arrives as `onStart`, and every move
+        // after it as `onUpdate`.
+        .onStart((event) => scrub(event.translationX, event.translationY))
+        .onUpdate((event) => scrub(event.translationX, event.translationY))
+        .onFinalize(() => {
+          setScrubbing(false);
+          onValueCommitted(
+            lastChangedValueRef.current ?? valueRef.current,
+            createChangeEventDetails(REASONS.scrub),
+          );
+        })
+        // The handlers touch React state, so they must not run on the UI thread.
+        .runOnJS(true),
+    [
+      disabled,
+      readOnly,
+      testID,
+      scrub,
+      setScrubbing,
+      onValueCommitted,
+      lastChangedValueRef,
+      valueRef,
+    ],
+  );
+
+  const element = useRenderElement(View, componentProps, {
+    state,
+    ref,
+    props: elementProps,
+  });
+
+  return <GestureDetector gesture={gesture}>{element}</GestureDetector>;
+}
+
+export interface NumberFieldScrubAreaState extends NumberFieldRootState {}
+
+export interface NumberFieldScrubAreaProps
+  extends ZestUIComponentProps<typeof View, NumberFieldScrubAreaState> {
+  /**
+   * The direction the drag is read along.
+   * @default 'horizontal'
+   */
+  direction?: 'horizontal' | 'vertical' | undefined;
+  /**
+   * How many pixels the drag must travel before the value steps once. A higher
+   * value makes scrubbing less sensitive.
+   * @default 2
+   */
+  pixelSensitivity?: number | undefined;
+}
+
+export namespace NumberFieldScrubArea {
+  export type State = NumberFieldScrubAreaState;
+  export type Props = NumberFieldScrubAreaProps;
+}

package/src/number-field/utils/constants.ts

@@ -0,0 +1,3 @@
+export const CHANGE_VALUE_TICK_DELAY = 60;
+export const START_AUTO_CHANGE_DELAY = 400;
+export const SCROLLING_POINTER_MOVE_DISTANCE = 8;