@limonify/zest-ui 0.1.0

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

@@ -0,0 +1,222 @@
+import { getFormatter } from '../../utils/formatNumber';
+
+// Han numerals in digit order, with both zero forms first ('零' at 0, '〇' at 1), so a
+// character's digit value is `max(indexOf - 1, 0)`.
+const HAN_NUMERALS = '零〇一二三四五六七八九';
+
+// Arabic-Indic (U+0660–0669), Persian (U+06F0–06F9), and fullwidth (U+FF10–FF19) digits are
+// contiguous ranges whose bases are divisible by 16, so `charCode % 16` is the digit value for
+// all three systems.
+const NON_ASCII_DIGIT_RE = /[٠-٩۰-۹０-９]/g;
+const HAN_RE = /[零〇一二三四五六七八九]/g;
+
+export const PERCENTAGES = ['%', '٪', '％', '﹪'];
+export const PERMILLE = ['‰', '؉'];
+
+// Fullwidth punctuation common in CJK inputs
+export const FULLWIDTH_DECIMAL = '．'; // U+FF0E
+export const FULLWIDTH_GROUP = '，'; // U+FF0C
+
+export const PERCENT_RE = /[%٪％﹪]/;
+export const PERMILLE_RE = /[‰؉]/;
+const PERCENT_GLOBAL_RE = /[%٪％﹪]/g;
+const PERMILLE_GLOBAL_RE = /[‰؉]/g;
+
+// Detection regexes (non-global to avoid lastIndex side effects). Arabic-Indic and Persian
+// digits share one regex because both resolve to the `ar` locale heuristic.
+export const ARABIC_PERSIAN_DETECT_RE = /[٠-٩۰-۹]/;
+export const HAN_DETECT_RE = /[零〇一二三四五六七八九]/;
+
+const ANY_NUMERAL_DETECT_RE = /[0-9٠-٩۰-۹０-９零〇一二三四五六七八九]/;
+
+// Whether the character is a digit in any numeral system the field accepts.
+export function isNumeralChar(char: string) {
+  return ANY_NUMERAL_DETECT_RE.test(char);
+}
+
+export const BASE_NON_NUMERIC_SYMBOLS = [
+  '.',
+  ',',
+  FULLWIDTH_DECIMAL,
+  FULLWIDTH_GROUP,
+  '٫',
+  '٬',
+] as const;
+export const SPACE_SEPARATOR_RE = /\p{Zs}/u;
+// Format/bidi control characters (e.g. the LRM/ALM marks RTL locales insert around exponent and
+// currency signs). `parseNumber` strips these, so input validation must treat them as ignorable
+// rather than rejecting the typed string. Non-global so it's safe for repeated `.test(char)`.
+export const FORMAT_CONTROL_DETECT_RE = /\p{Cf}/u;
+const FORMAT_CONTROL_GLOBAL_RE = /\p{Cf}/gu;
+export const PLUS_SIGNS_WITH_ASCII = ['+', '＋', '﹢'];
+export const MINUS_SIGNS_WITH_ASCII = ['-', '−', '－', '‒', '–', '—', '﹣'];
+
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+function shiftDecimal(value: number, exponentDelta: number) {
+  const [coefficient, exponent = '0'] = String(value).split('e');
+  return Number(`${coefficient}e${Number(exponent) + exponentDelta}`);
+}
+
+export const ANY_MINUS_RE = /[-−－‒–—﹣]/gu;
+export const ANY_PLUS_RE = /[+＋﹢]/gu;
+export const ANY_MINUS_DETECT_RE = /[-−－‒–—﹣]/;
+export const ANY_PLUS_DETECT_RE = /[+＋﹢]/;
+
+// A representative value with a grouping separator and a fractional part, so that the formatter
+// emits every locale-specific part (group, decimal, currency, unit, literal, exponent, …). Shared
+// so the locale-detail and allowed-character derivations enumerate the same parts.
+const SAMPLE_FORMAT_NUMBER = 11111.1;
+
+/**
+ * Returns the `Intl.NumberFormat` parts of a representative number, which surface every
+ * non-numeric symbol a given locale/format renders.
+ */
+export function getFormatParts(locale?: Intl.LocalesArgument, options?: Intl.NumberFormatOptions) {
+  return getFormatter(locale, options).formatToParts(SAMPLE_FORMAT_NUMBER);
+}
+
+export function getNumberLocaleDetails(
+  locale?: Intl.LocalesArgument,
+  options?: Intl.NumberFormatOptions,
+) {
+  const parts = getFormatParts(locale, options);
+  const result: Partial<Record<Intl.NumberFormatPartTypes, string | undefined>> = {};
+
+  parts.forEach((part) => {
+    result[part.type] = part.value;
+  });
+
+  // The formatting options may omit the decimal separator (e.g. integer formats), so resolve it
+  // from the plain locale formatter. This overrides any options-derived decimal too, which is
+  // safe because the separator is locale-determined and identical across format styles.
+  getFormatter(locale)
+    .formatToParts(0.1)
+    .forEach((part) => {
+      if (part.type === 'decimal') {
+        result[part.type] = part.value;
+      }
+    });
+
+  return result;
+}
+
+export function parseNumber(
+  formattedNumber: string,
+  locale?: Intl.LocalesArgument,
+  options?: Intl.NumberFormatOptions,
+) {
+  if (formattedNumber == null) {
+    return null;
+  }
+
+  // Normalize control characters and whitespace; remove bidi/format controls
+  let input = String(formattedNumber).replace(FORMAT_CONTROL_GLOBAL_RE, '').trim();
+
+  // Normalize unicode minus/plus to ASCII, handle leading/trailing signs
+  input = input.replace(ANY_MINUS_RE, '-').replace(ANY_PLUS_RE, '+');
+
+  let isNegative = false;
+
+  // Strips a matched sign (leading "-12" / trailing "1234-") while recording negativity.
+  const takeSign = (match: string, sign: string) => {
+    if (sign === '-') {
+      isNegative = true;
+    }
+    return '';
+  };
+
+  input = input.replace(/([+-])\s*$/, takeSign).replace(/^\s*([+-])/, takeSign);
+
+  // Heuristic locale detection
+  let computedLocale = locale;
+  if (computedLocale === undefined) {
+    if (ARABIC_PERSIAN_DETECT_RE.test(input)) {
+      computedLocale = 'ar';
+    } else if (HAN_DETECT_RE.test(input)) {
+      computedLocale = 'zh';
+    }
+  }
+
+  const { group, decimal, currency, exponentSeparator } = getNumberLocaleDetails(
+    computedLocale,
+    options,
+  );
+
+  // Build robust unit regex from all unit parts (such as "km/h")
+  const unitParts = getFormatter(computedLocale, options)
+    .formatToParts(1)
+    .filter((p) => p.type === 'unit')
+    .map((p) => escapeRegExp(p.value));
+  const unitRegex = unitParts.length ? new RegExp(unitParts.join('|'), 'g') : null;
+
+  let groupRegex: RegExp | null = null;
+  if (group) {
+    const isSpaceGroup = /\p{Zs}/u.test(group);
+    const isApostropheGroup = group === "'" || group === '’';
+
+    // Check if the group separator is a space-like character.
+    // If so, we'll replace all such characters with an empty string.
+    if (isSpaceGroup) {
+      groupRegex = /\p{Zs}/gu;
+    } else if (isApostropheGroup) {
+      // Some environments format numbers with ASCII apostrophe and others with a curly apostrophe.
+      groupRegex = /['’]/g;
+    } else {
+      groupRegex = new RegExp(escapeRegExp(group), 'g');
+    }
+  }
+
+  const replacements: Array<[RegExp | null, string | ((m: string) => string)]> = [
+    [groupRegex, ''],
+    [decimal ? new RegExp(escapeRegExp(decimal), 'g') : null, '.'],
+    // Fullwidth/Arabic punctuation
+    [/[．٫]/g, '.'], // FULLWIDTH_DECIMAL, ARABIC DECIMAL SEPARATOR (U+066B)
+    [/[，٬]/g, ''], // FULLWIDTH_GROUP, ARABIC THOUSANDS SEPARATOR (U+066C)
+    // Currency & unit labels
+    [currency ? new RegExp(escapeRegExp(currency), 'g') : null, ''],
+    [unitRegex, ''],
+    [PERCENT_GLOBAL_RE, ''],
+    [PERMILLE_GLOBAL_RE, ''],
+    [exponentSeparator ? new RegExp(escapeRegExp(exponentSeparator), 'g') : null, 'e'],
+    // Numeral systems to ASCII digits
+    [NON_ASCII_DIGIT_RE, (ch: string) => String(ch.charCodeAt(0) % 16)],
+    [HAN_RE, (ch: string) => String(Math.max(HAN_NUMERALS.indexOf(ch) - 1, 0))],
+  ];
+
+  let unformatted = replacements.reduce((acc, [regex, replacement]) => {
+    return regex ? acc.replace(regex, replacement as any) : acc;
+  }, input);
+
+  // Mixed-locale safety: keep only the last '.' as decimal
+  const lastDot = unformatted.lastIndexOf('.');
+  if (lastDot !== -1) {
+    unformatted = `${unformatted.slice(0, lastDot).replace(/\./g, '')}.${unformatted.slice(lastDot + 1).replace(/\./g, '')}`;
+  }
+
+  // Guard against Infinity inputs (ASCII and symbol)
+  if (/^[-+]?Infinity$/i.test(input) || input.includes('∞')) {
+    return null;
+  }
+
+  const parseTarget = (isNegative ? '-' : '') + unformatted;
+
+  let num = parseFloat(parseTarget);
+
+  const style = options?.style;
+  const isUnitPercent = style === 'unit' && options?.unit === 'percent';
+  const hasPercentSymbol = PERCENT_RE.test(formattedNumber) || style === 'percent';
+  const hasPermilleSymbol = PERMILLE_RE.test(formattedNumber);
+
+  if (hasPermilleSymbol) {
+    num = shiftDecimal(num, -3);
+  } else if (!isUnitPercent && hasPercentSymbol) {
+    num = shiftDecimal(num, -2);
+  }
+
+  if (!Number.isFinite(num)) {
+    return null;
+  }
+
+  return num;
+}

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

@@ -0,0 +1,136 @@
+import { clamp } from '../../utils/clamp';
+import { getFormatter } from '../../utils/formatNumber';
+import { parseNumber } from './parse';
+
+// A relative factor scaled by the step size when snapping (`stepSize * STEP_EPSILON_FACTOR`).
+const STEP_EPSILON_FACTOR = 1e-10;
+// An absolute cap (in the value's own units) on how far floating-point cleanup may move a value.
+// Equal to `STEP_EPSILON_FACTOR` only by coincidence — the two are independent and may diverge.
+const MAX_FLOATING_POINT_CLEANUP_DELTA = 1e-10;
+
+// The repo compiles against es2022 Intl types, so model NumberFormat v3 options locally.
+// Delete this once tsconfig.base.json includes es2023.
+type NumberFormatOptionsWithRounding = Intl.NumberFormatOptions & {
+  roundingIncrement?: number | undefined;
+  roundingMode?: string | undefined;
+  roundingPriority?: string | undefined;
+};
+
+export function hasNumberFormatRoundingOptions(
+  format?: NumberFormatOptionsWithRounding,
+): format is NumberFormatOptionsWithRounding {
+  return (
+    format?.maximumFractionDigits != null ||
+    format?.minimumFractionDigits != null ||
+    format?.maximumSignificantDigits != null ||
+    format?.minimumSignificantDigits != null ||
+    format?.roundingIncrement != null ||
+    format?.roundingMode != null ||
+    format?.roundingPriority != null
+  );
+}
+
+export function removeFloatingPointErrors(value: number, format?: NumberFormatOptionsWithRounding) {
+  if (!Number.isFinite(value)) {
+    return value;
+  }
+
+  if (!hasNumberFormatRoundingOptions(format)) {
+    // Clean binary floating-point noise (e.g. `0.1 + 0.2`) without discarding legitimate
+    // precision. The cleanup is delta-bounded, so it cannot tell noise apart from real digits
+    // that fall within the same epsilon: arithmetic that produces sub-epsilon precision (e.g.
+    // accumulating a high-significance `step` past the first tick) is normalized to ~15
+    // significant digits.
+    const roundedValue = parseFloat(value.toPrecision(15));
+    const cleanupDelta = Math.abs(roundedValue - value);
+    // Cap the cleanup delta so `toPrecision(15)` cannot erase meaningful fractional values
+    // at large magnitudes, where the relative epsilon alone is too permissive. The trade-off is
+    // that from the `2^19` binade (~5.2e5) up, a single ULP exceeds the absolute cap, so genuine
+    // stepping noise is left uncleaned there (e.g. `1000000.1 + 0.2` stays `1000000.2999999999`)
+    // rather than risk corrupting real precision.
+    const cleanupTolerance = Math.min(
+      Number.EPSILON * Math.max(1, Math.abs(value)),
+      MAX_FLOATING_POINT_CLEANUP_DELTA,
+    );
+
+    return cleanupDelta <= cleanupTolerance ? roundedValue : value;
+  }
+
+  const formatter = getFormatter('en-US', {
+    ...format,
+    // These options alter only display decoration, not numeric rounding.
+    signDisplay: 'auto',
+    currencySign: 'standard',
+    notation: format.notation === 'compact' ? 'standard' : format.notation,
+    useGrouping: false,
+  } as NumberFormatOptionsWithRounding);
+  const roundedText = formatter.format(value);
+  const roundedValue = parseNumber(roundedText, 'en-US', format);
+
+  if (roundedValue === null) {
+    return value;
+  }
+
+  return formatter.format(roundedValue) === roundedText ? roundedValue : value;
+}
+
+function snapToStep(value: number, base: number, step: number, nearest: boolean) {
+  const stepSize = Math.abs(step);
+  const direction = Math.sign(step);
+  const tolerance = stepSize * STEP_EPSILON_FACTOR * direction;
+  const rawSteps = value - base + tolerance;
+
+  if (nearest) {
+    return base + Math.round(rawSteps / step) * step;
+  }
+
+  const snappedSteps =
+    direction > 0 ? Math.floor(rawSteps / stepSize) : Math.ceil(rawSteps / stepSize);
+  return base + snappedSteps * stepSize;
+}
+
+export function toValidatedNumber(
+  value: number | null,
+  step: number | undefined,
+  minWithDefault: number,
+  maxWithDefault: number,
+  minWithZeroDefault: number,
+  format: NumberFormatOptionsWithRounding | undefined,
+  snapOnStep: boolean,
+  small: boolean,
+  shouldClamp: boolean,
+) {
+  if (value === null) {
+    return value;
+  }
+
+  let nextValue = value;
+
+  if (step != null && snapOnStep && step !== 0) {
+    const base =
+      small || minWithDefault === Number.MIN_SAFE_INTEGER ? minWithZeroDefault : minWithDefault;
+
+    // Snap before clamping so non-step-aligned boundaries stay reachable. Small (alt-key) steps
+    // snap to the nearest multiple; regular steps snap directionally.
+    nextValue = snapToStep(nextValue, base, step, small);
+  }
+
+  // Clamp before rounding so a value just outside a fractional boundary (e.g. `0.4` with
+  // `min: 0.6`) is pulled in range first, then clamp again after rounding in case rounding
+  // nudges it back out. Both passes are needed for non-integer bounds.
+  if (shouldClamp) {
+    nextValue = clamp(nextValue, minWithDefault, maxWithDefault);
+  }
+
+  // Non-stepping values — parsed input (typing, paste, blur) and externally-supplied controlled
+  // values — involve no arithmetic here, so they carry no binary noise to clean and are returned
+  // verbatim to keep every digit, including values with more than 15 significant digits. Only
+  // stepping/snapping arithmetic can introduce noise (e.g. 0.7 + 0.1), which
+  // `removeFloatingPointErrors` cleans.
+  if (step == null && !hasNumberFormatRoundingOptions(format)) {
+    return nextValue;
+  }
+
+  const roundedValue = removeFloatingPointErrors(nextValue, format);
+  return shouldClamp ? clamp(roundedValue, minWithDefault, maxWithDefault) : roundedValue;
+}

package/src/otp-field/index.parts.ts

@@ -0,0 +1,3 @@
+export { OTPFieldRoot as Root } from './root/OTPFieldRoot';
+export { OTPFieldInput as Input } from './input/OTPFieldInput';
+export { Separator } from '../separator/Separator';

package/src/otp-field/index.ts

@@ -0,0 +1,6 @@
+export * as OTPField from './index.parts';
+
+export type * from './root/OTPFieldRoot';
+export type * from './input/OTPFieldInput';
+export { useOTPFieldRootContext } from './root/OTPFieldRootContext';
+export type { OTPValidationType } from './utils/otp';

package/src/otp-field/input/OTPFieldInput.tsx

@@ -0,0 +1,203 @@
+'use client';
+import * as React from 'react';
+import {
+  TextInput,
+  type NativeSyntheticEvent,
+  type TextInputKeyPressEventData,
+} from 'react-native';
+import { getOTPFieldInputState, useOTPFieldRootContext } from '../root/OTPFieldRootContext';
+import { useCompositeListItem } from '../../internals/composite/list/useCompositeListItem';
+import { useRenderElement } from '../../use-render/useRenderElement';
+import { useStableCallback } from '../../hooks/useStableCallback';
+import { useMergedRefs } from '../../hooks/useMergedRefs';
+import type { OTPFieldRootState } from '../root/OTPFieldRoot';
+import type { ZestUIComponentProps } from '../../types';
+import { createChangeEventDetails } from '../../utils/createChangeEventDetails';
+import { REASONS } from '../../utils/reasons';
+import { normalizeOTPValueWithDetails, removeOTPCharacter, replaceOTPValue } from '../utils/otp';
+
+const MASK_CHARACTER = '\u2022';
+
+/**
+ * A single OTP slot.
+ * Renders a `<TextInput>`.
+ *
+ * Its slot index comes from its position among the other inputs, via
+ * `CompositeList` — so slots need no index prop.
+ *
+ * **Diverges from the web deliberately.** Upstream handles paste through a
+ * `paste` event and selection ranges. React Native reports every edit as a whole
+ * string through `onChangeText` and has no paste event, so both cases go through
+ * the same path: whatever arrives is written from this slot onwards. That is also
+ * what makes OS autofill work — iOS and Android deliver the entire SMS code into
+ * the focused slot, which lands here as one long string.
+ */
+export function OTPFieldInput(componentProps: OTPFieldInput.Props) {
+  const { render, className, style, ref, ...elementProps } = componentProps;
+
+  const {
+    activeIndex,
+    autoComplete,
+    disabled,
+    focusInput,
+    id,
+    keyboardType,
+    length,
+    mask,
+    normalizeValue,
+    readOnly,
+    registerInput,
+    reportValueInvalid,
+    setActiveIndex,
+    setValue,
+    state,
+    validationType,
+    value,
+  } = useOTPFieldRootContext();
+
+  const { index, onLayout } = useCompositeListItem();
+
+  const inputRef = React.useRef<TextInput | null>(null);
+  const mergedRef = useMergedRefs(ref, inputRef);
+
+  React.useEffect(() => {
+    if (index < 0) {
+      return undefined;
+    }
+
+    registerInput(index, inputRef.current);
+    return () => registerInput(index, null);
+  }, [index, registerInput]);
+
+  const slotValue = value[index] ?? '';
+  // What the input actually shows, which is a bullet when masked. Every
+  // comparison against the reported text has to use this rather than the real
+  // character, or a mask would leave its bullet in the entered text.
+  const displayedValue = mask && slotValue ? MASK_CHARACTER : slotValue;
+
+  const handleChangeText = useStableCallback((text: string) => {
+    if (disabled || readOnly || index < 0) {
+      return;
+    }
+
+    if (text === '') {
+      // The slot was emptied, which only a backspace on a filled slot can do.
+      const next = removeOTPCharacter(value, index);
+      setValue(next, createChangeEventDetails(REASONS.inputClear));
+      return;
+    }
+
+    // The slot already showed a character, so RN reports the old one plus what
+    // was added. Only the addition is new.
+    let entered = text;
+    if (displayedValue && text.startsWith(displayedValue) && text.length > displayedValue.length) {
+      entered = text.slice(displayedValue.length);
+    }
+
+    const [normalized, didRejectCharacters] = normalizeOTPValueWithDetails(
+      entered,
+      length - index,
+      validationType,
+      normalizeValue,
+    );
+
+    if (didRejectCharacters) {
+      reportValueInvalid(entered, createChangeEventDetails(REASONS.inputChange));
+    }
+
+    if (normalized === '') {
+      return;
+    }
+
+    const next = replaceOTPValue(value, index, normalized, length, validationType, normalizeValue);
+    const stored = setValue(next, createChangeEventDetails(REASONS.inputChange));
+
+    if (stored === null) {
+      return;
+    }
+
+    // Move to the slot after everything just written, which for a pasted or
+    // autofilled code is the end.
+    focusInput(index + normalized.length);
+  });
+
+  const handleKeyPress = useStableCallback(
+    (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+      if (disabled || readOnly || event.nativeEvent.key !== 'Backspace' || slotValue !== '') {
+        return;
+      }
+
+      // Backspace on an empty slot steps back and clears the one before it —
+      // `onChangeText` never fires, because the text did not change.
+      if (index > 0) {
+        setValue(removeOTPCharacter(value, index - 1), createChangeEventDetails(REASONS.inputClear));
+        focusInput(index - 1);
+      }
+    },
+  );
+
+  const inputState = getOTPFieldInputState(state, slotValue, index);
+
+  return useRenderElement(TextInput, componentProps, {
+    state: inputState,
+    ref: mergedRef,
+    props: [
+      {
+        // Spreading this is what lets CompositeList correct the slot order from
+        // measured layout instead of registration order.
+        onLayout,
+        nativeID: getSlotId(id, index),
+        value: displayedValue,
+        onChangeText: handleChangeText,
+        onKeyPress: handleKeyPress,
+        onFocus: () => setActiveIndex(index),
+        onBlur: () => {
+          if (activeIndex === index) {
+            setActiveIndex(-1);
+          }
+        },
+        editable: !disabled && !readOnly,
+        keyboardType,
+        // Only the first slot advertises the code: the OS fills the field it is
+        // on, and every slot claiming it would make the suggestion ambiguous.
+        autoComplete: (index === 0 ? autoComplete : 'off') as 'one-time-code' | 'off',
+        textContentType: index === 0 ? ('oneTimeCode' as const) : ('none' as const),
+        enterKeyHint: index === length - 1 ? ('done' as const) : ('next' as const),
+        accessibilityState: { disabled: disabled || undefined },
+      },
+      elementProps,
+    ],
+  });
+}
+
+/** The first slot uses the root's id; the rest derive theirs from it. */
+function getSlotId(id: string | undefined, index: number) {
+  if (id === undefined) {
+    return undefined;
+  }
+
+  return index === 0 ? id : `${id}-${index + 1}`;
+}
+
+export interface OTPFieldInputState extends OTPFieldRootState {
+  /**
+   * This slot's character.
+   */
+  value: string;
+  /**
+   * This slot's index.
+   */
+  index: number;
+  /**
+   * Whether this slot has a character.
+   */
+  filled: boolean;
+}
+
+export interface OTPFieldInputProps
+  extends Omit<ZestUIComponentProps<typeof TextInput, OTPFieldInputState>, 'value'> {}
+
+export namespace OTPFieldInput {
+  export type State = OTPFieldInputState;
+  export type Props = OTPFieldInputProps;
+}