@cdx-ui/primitives 0.0.1-alpha.36 → 0.0.1-alpha.38

package/src/otp-input/createOtpInputCell.tsx

@@ -0,0 +1,22 @@
+import type React from 'react';
+import type { PropsWithChildren } from 'react';
+import { forwardRef } from 'react';
+import { useOtpInputContext } from './context';
+import type { IOtpInputCellProps } from './types';
+
+export const createOtpInputCell = <T,>(BaseCell: React.ComponentType<T>) =>
+  forwardRef<unknown, PropsWithChildren<IOtpInputCellProps & T>>(({ children, ...props }, ref) => {
+    const { isDisabled, isInvalid, isReadOnly } = useOtpInputContext();
+
+    return (
+      <BaseCell
+        ref={ref}
+        isDisabled={isDisabled}
+        isInvalid={isInvalid}
+        isReadOnly={isReadOnly}
+        {...(props as T)}
+      >
+        {children}
+      </BaseCell>
+    );
+  });

package/src/otp-input/createOtpInputField.tsx

@@ -0,0 +1,98 @@
+import type React from 'react';
+import { forwardRef, useMemo } from 'react';
+import { Platform, type TextInput, type TextInputKeyPressEvent } from 'react-native';
+import { mergeRefs } from '@cdx-ui/utils';
+import { useOtpCellIndexContext, useOtpInputContext } from './context';
+import type { IOtpInputFieldProps } from './types';
+
+export const createOtpInputField = <T,>(BaseField: React.ComponentType<T>) =>
+  forwardRef<TextInput, IOtpInputFieldProps & Omit<T, keyof IOtpInputFieldProps>>((props, ref) => {
+    const { cellIndex } = useOtpCellIndexContext();
+    const {
+      value,
+      cellCount,
+      isDisabled,
+      isReadOnly,
+      smsOtpAutofill,
+      getCellProps,
+      cellTestIdPrefix,
+      rootAccessibilityLabel,
+      setFieldRef,
+      handleFieldChange,
+      handleFieldKeyPress,
+    } = useOtpInputContext();
+
+    const char = cellIndex < value.length ? (value[cellIndex] ?? '') : '';
+    const extra = getCellProps?.(cellIndex) ?? {};
+
+    const accessibilityLabel = useMemo(() => {
+      const fromExtra = extra.accessibilityLabel;
+      if (typeof fromExtra === 'string' && fromExtra !== '') {
+        return fromExtra;
+      }
+      if (rootAccessibilityLabel) {
+        return `${rootAccessibilityLabel}, ${String(cellIndex + 1)} of ${String(cellCount)}`;
+      }
+      return `OTP digit ${String(cellIndex + 1)} of ${String(cellCount)}`;
+    }, [cellCount, cellIndex, extra.accessibilityLabel, rootAccessibilityLabel]);
+
+    const autofillProps = useMemo(() => {
+      if (!smsOtpAutofill || cellIndex !== 0) {
+        return {};
+      }
+      return Platform.select<Record<string, unknown>>({
+        web: { autoComplete: 'one-time-code' },
+        ios: { textContentType: 'oneTimeCode' },
+        android: { autoComplete: 'sms-otp' },
+        default: {},
+      });
+    }, [cellIndex, smsOtpAutofill]);
+
+    const editable = !(isDisabled || isReadOnly);
+
+    const { style: extraStyle, accessibilityLabel: _omitExtraA11y, ...extraRest } = extra;
+    void _omitExtraA11y;
+    const {
+      style: incomingStyle,
+      value: _omitValue,
+      defaultValue: _omitDefault,
+      onChangeText: _omitOnChange,
+      ...incomingRest
+    } = props as IOtpInputFieldProps;
+    void _omitValue;
+    void _omitDefault;
+    void _omitOnChange;
+
+    // Default digit OTP (`number-pad`). Root `getCellProps` is spread after and may override `keyboardType`.
+    return (
+      <BaseField
+        ref={mergeRefs(ref, (el: TextInput | null) => {
+          setFieldRef(cellIndex, el);
+        })}
+        accessibilityLabel={accessibilityLabel}
+        aria-label={accessibilityLabel}
+        accessible
+        autoFocus={cellIndex === 0 && editable && value.length === 0}
+        editable={editable}
+        keyboardType="number-pad"
+        returnKeyType="done"
+        selectTextOnFocus
+        testID={
+          cellTestIdPrefix
+            ? `${cellTestIdPrefix}:${String(cellIndex)}:textField:changeText`
+            : undefined
+        }
+        value={char}
+        onChangeText={(text: string) => {
+          handleFieldChange(cellIndex, text);
+        }}
+        onKeyPress={(e: TextInputKeyPressEvent) => {
+          handleFieldKeyPress(cellIndex, e.nativeEvent.key);
+        }}
+        {...autofillProps}
+        {...(extraRest as object)}
+        {...(incomingRest as T)}
+        style={[extraStyle, incomingStyle]}
+      />
+    );
+  });

package/src/otp-input/createOtpInputRoot.tsx

@@ -0,0 +1,179 @@
+import type React from 'react';
+import { forwardRef, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import type { TextInput } from 'react-native';
+import { useFormControlContext } from '@cdx-ui/utils';
+import { applyOtpInputChange } from './utils/applyValueChange';
+import { OtpCellIndexProvider, OtpInputProvider } from './context';
+import { filterAllowedCharacters, filterByRegExp, filterDigits } from './utils/filterValue';
+import type { IOtpInputRootProps } from './types';
+
+export const createOtpInputRoot = <RootProps,>(
+  BaseRoot: React.ComponentType<RootProps>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- slot components are generic across design systems
+  OtpCell: React.ComponentType<any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  OtpField: React.ComponentType<any>,
+) =>
+  forwardRef<unknown, IOtpInputRootProps & RootProps>(
+    (
+      {
+        cellCount,
+        value,
+        onChangeText,
+        onComplete,
+        isDisabled: isDisabledProp,
+        isInvalid: isInvalidProp,
+        isReadOnly: isReadOnlyProp,
+        smsOtpAutofill = true,
+        filterInput,
+        allowedCharacters,
+        characterPattern,
+        getCellProps,
+        cellTestIdPrefix,
+        accessibilityLabel: rootAccessibilityLabel,
+        ...rest
+      },
+      ref,
+    ) => {
+      const form = useFormControlContext();
+      const isDisabled = isDisabledProp ?? form.isDisabled ?? false;
+      const isInvalid = isInvalidProp ?? form.isInvalid ?? false;
+      const isReadOnly = isReadOnlyProp ?? form.isReadOnly ?? false;
+
+      const fieldRefs = useRef<(TextInput | null)[]>([]);
+      const focusAfterApply = useRef<number | null>(null);
+      const prevLenRef = useRef(value.length);
+      const prevValueRef = useRef(value);
+
+      const filter = useMemo(() => {
+        if (filterInput) {
+          return filterInput;
+        }
+        if (allowedCharacters !== undefined) {
+          return filterAllowedCharacters(allowedCharacters);
+        }
+        if (characterPattern !== undefined) {
+          return filterByRegExp(characterPattern);
+        }
+        return filterDigits;
+      }, [filterInput, allowedCharacters, characterPattern]);
+
+      const setFieldRef = useCallback((index: number, el: TextInput | null) => {
+        fieldRefs.current[index] = el;
+      }, []);
+
+      const focusCell = useCallback(
+        (index: number) => {
+          const safe = Math.max(0, Math.min(index, cellCount - 1));
+          fieldRefs.current[safe]?.focus();
+        },
+        [cellCount],
+      );
+
+      const handleFieldChange = useCallback(
+        (index: number, text: string) => {
+          const { nextValue, focusIndex } = applyOtpInputChange(
+            value,
+            index,
+            text,
+            cellCount,
+            filter,
+          );
+          if (nextValue !== value) {
+            onChangeText(nextValue);
+          }
+          focusAfterApply.current = focusIndex;
+        },
+        [cellCount, filter, onChangeText, value],
+      );
+
+      const handleFieldKeyPress = useCallback(
+        (index: number, key: string) => {
+          if (key !== 'Backspace') {
+            return;
+          }
+          const char = index < value.length ? value[index] : '';
+          if (!char && index > 0) {
+            focusCell(index - 1);
+          }
+        },
+        [focusCell, value],
+      );
+
+      useLayoutEffect(() => {
+        if (focusAfterApply.current !== null) {
+          const i = focusAfterApply.current;
+          focusAfterApply.current = null;
+          fieldRefs.current[i]?.focus();
+        }
+      });
+
+      useEffect(() => {
+        const prevLen = prevLenRef.current;
+        const prevVal = prevValueRef.current;
+        const isFull = value.length === cellCount;
+        const becameFullByLength = isFull && prevLen < cellCount;
+        const correctedWhileFull = isFull && prevLen === cellCount && prevVal !== value;
+
+        if (becameFullByLength || correctedWhileFull) {
+          onComplete?.();
+        }
+        prevLenRef.current = value.length;
+        prevValueRef.current = value;
+      }, [cellCount, onComplete, value]);
+
+      const contextValue = useMemo(
+        () => ({
+          cellCount,
+          value,
+          isDisabled,
+          isInvalid,
+          isReadOnly,
+          smsOtpAutofill,
+          filter,
+          getCellProps,
+          cellTestIdPrefix,
+          rootAccessibilityLabel,
+          setFieldRef,
+          handleFieldChange,
+          handleFieldKeyPress,
+        }),
+        [
+          cellCount,
+          value,
+          isDisabled,
+          isInvalid,
+          isReadOnly,
+          smsOtpAutofill,
+          filter,
+          getCellProps,
+          cellTestIdPrefix,
+          rootAccessibilityLabel,
+          setFieldRef,
+          handleFieldChange,
+          handleFieldKeyPress,
+        ],
+      );
+
+      // Hermes drops outer-scope closure vars from its environment record when
+      // they are only referenced inside a nested callback (Array.from). Using a
+      // for-loop keeps OtpCell/OtpField references in the render function's own
+      // scope, avoiding the Hermes closure-capture bug.
+      const cells: React.ReactElement[] = [];
+      for (let i = 0; i < cellCount; i++) {
+        cells.push(
+          <OtpCellIndexProvider key={i} value={{ cellIndex: i }}>
+            <OtpCell>
+              <OtpField />
+            </OtpCell>
+          </OtpCellIndexProvider>,
+        );
+      }
+
+      return (
+        <BaseRoot ref={ref as React.Ref<unknown>} {...(rest as RootProps)}>
+          <OtpInputProvider value={contextValue}>{cells}</OtpInputProvider>
+        </BaseRoot>
+      );
+    },
+  );

package/src/otp-input/index.tsx

@@ -0,0 +1,34 @@
+import type React from 'react';
+import { createOtpInputCell } from './createOtpInputCell';
+import { createOtpInputField } from './createOtpInputField';
+import { createOtpInputRoot } from './createOtpInputRoot';
+import type { IOtpInputComponentType } from './types';
+
+export { applyOtpInputChange } from './utils/applyValueChange';
+export { filterAllowedCharacters, filterByRegExp, filterDigits } from './utils/filterValue';
+export type * from './types';
+
+export function createOtpInput<
+  RootProps,
+  CellProps,
+  FieldProps,
+  RootRef = unknown,
+  FieldRef = unknown,
+>(BaseComponents: {
+  Root: React.ComponentType<RootProps>;
+  Cell: React.ComponentType<CellProps>;
+  Field: React.ComponentType<FieldProps>;
+}) {
+  const Cell = createOtpInputCell(BaseComponents.Cell);
+  const Field = createOtpInputField(BaseComponents.Field);
+  const Root = createOtpInputRoot(BaseComponents.Root, Cell, Field);
+
+  Root.displayName = 'OtpInputPrimitive';
+  Cell.displayName = 'OtpInputPrimitive.Cell';
+  Field.displayName = 'OtpInputPrimitive.Field';
+
+  return Object.assign(Root, {
+    Cell,
+    Field,
+  }) as IOtpInputComponentType<RootProps, CellProps, FieldProps, RootRef, FieldRef>;
+}

package/src/otp-input/types.ts

@@ -0,0 +1,92 @@
+import type React from 'react';
+import type { ReactNode } from 'react';
+import type { TextInputProps, ViewProps } from 'react-native';
+
+export interface IOtpInputRootProps extends ViewProps {
+  /** Number of OTP cells (fixed). */
+  cellCount: number;
+  /** Controlled value: characters in order, length 0..`cellCount` (prefix fill). */
+  value: string;
+  onChangeText: (value: string) => void;
+  /**
+   * Called when the code is ready to verify again:
+   * - `value` becomes full (`length === cellCount`) after being shorter, or
+   * - `value` stays full but the string changes (user corrected a digit without dropping below full length).
+   * Does not fire on mount when `value` is already full and unchanged, nor on re-renders with the same full `value`.
+   */
+  onComplete?: () => void;
+  isDisabled?: boolean;
+  isInvalid?: boolean;
+  isReadOnly?: boolean;
+  /** When false, no SMS / Web OTP autofill hints on the first cell. @default true */
+  smsOtpAutofill?: boolean;
+  /**
+   * Override default digit-only filtering.
+   * Takes priority over `allowedCharacters` and `characterPattern` when truthy.
+   * Does not change the default `keyboardType` (`number-pad`); use `getCellProps` if the allowed
+   * character set needs a different keyboard.
+   */
+  filterInput?: (input: string) => string;
+  /**
+   * Keep only characters present in this string (treated as a set of code units).
+   * Used when `filterInput` is not provided. Takes priority over `characterPattern`.
+   * Default keyboard remains numeric; use `getCellProps` to set `keyboardType` when allowing letters/symbols.
+   */
+  allowedCharacters?: string;
+  /**
+   * Keep only characters matching this pattern (tested per code unit).
+   * Used when neither `filterInput` nor `allowedCharacters` is provided.
+   * Default keyboard remains numeric; use `getCellProps` to set `keyboardType` for non-digit input.
+   */
+  characterPattern?: RegExp;
+  /**
+   * Spread onto each cell after built-in field props (including `keyboardType="number-pad"`),
+   * so consumers can override `keyboardType`, `autoCapitalize`, etc. for non-digit OTPs.
+   */
+  getCellProps?: (index: number) => Partial<TextInputProps>;
+  /** Optional prefix for `testID` on each field: `${cellTestIdPrefix}:${index}:...` */
+  cellTestIdPrefix?: string;
+}
+
+export interface IOtpInputCellProps extends ViewProps {
+  children?: ReactNode;
+}
+
+export type IOtpInputFieldProps = TextInputProps;
+
+export interface OtpInputCellIndexContextValue {
+  cellIndex: number;
+}
+
+export interface OtpInputContextValue {
+  cellCount: number;
+  value: string;
+  isDisabled: boolean;
+  isInvalid: boolean;
+  isReadOnly: boolean;
+  smsOtpAutofill: boolean;
+  filter: (input: string) => string;
+  getCellProps?: (index: number) => Partial<TextInputProps>;
+  cellTestIdPrefix?: string;
+  rootAccessibilityLabel?: string;
+  setFieldRef: (index: number, el: import('react-native').TextInput | null) => void;
+  handleFieldChange: (index: number, text: string) => void;
+  handleFieldKeyPress: (index: number, key: string) => void;
+}
+
+export type IOtpInputComponentType<
+  RootProps,
+  CellProps,
+  FieldProps,
+  RootRef = unknown,
+  FieldRef = unknown,
+> = React.ForwardRefExoticComponent<
+  React.PropsWithoutRef<RootProps & IOtpInputRootProps> & React.RefAttributes<RootRef>
+> & {
+  Cell: React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<CellProps & IOtpInputCellProps> & React.RefAttributes<unknown>
+  >;
+  Field: React.ForwardRefExoticComponent<
+    React.PropsWithoutRef<FieldProps & IOtpInputFieldProps> & React.RefAttributes<FieldRef>
+  >;
+};

package/src/otp-input/utils/applyValueChange.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure OTP value transition for a controlled prefix string (no explicit empty slots).
+ * - Single-character edits use index-based replace/append (no reorder).
+ * - Multi-character input (paste/autofill) writes at `index` forward, then packs left.
+ */
+export function applyOtpInputChange(
+  value: string,
+  index: number,
+  rawText: string,
+  cellCount: number,
+  filter: (input: string) => string,
+): { nextValue: string; focusIndex: number } {
+  const text = filter(rawText);
+
+  if (text.length === 0) {
+    if (index < value.length) {
+      const next = (value.slice(0, index) + value.slice(index + 1)).slice(0, cellCount);
+      return { nextValue: next, focusIndex: Math.max(0, index - 1) };
+    }
+    return { nextValue: value, focusIndex: index };
+  }
+
+  if (text.length === 1) {
+    if (index < value.length) {
+      const next = (value.slice(0, index) + text + value.slice(index + 1)).slice(0, cellCount);
+      return { nextValue: next, focusIndex: Math.min(index + 1, cellCount - 1) };
+    }
+    if (value.length < cellCount) {
+      if (index === value.length) {
+        const next = (value + text).slice(0, cellCount);
+        return { nextValue: next, focusIndex: Math.min(next.length, cellCount - 1) };
+      }
+      const arr = Array.from({ length: cellCount }, (_, i) => (i < value.length ? value[i] : ''));
+      arr[index] = text;
+      const next = arr
+        .filter((c) => c)
+        .join('')
+        .slice(0, cellCount);
+      return { nextValue: next, focusIndex: Math.min(index + 1, cellCount - 1) };
+    }
+    const next = (value.slice(0, index) + text + value.slice(index + 1)).slice(0, cellCount);
+    return { nextValue: next, focusIndex: Math.min(index + 1, cellCount - 1) };
+  }
+
+  const arr = Array.from({ length: cellCount }, (_, i) => (i < value.length ? value[i] : ''));
+  for (let k = 0; k < text.length && index + k < cellCount; k++) {
+    arr[index + k] = text.charAt(k);
+  }
+  const next = arr
+    .filter((c) => c)
+    .join('')
+    .slice(0, cellCount);
+  const lastWritten = Math.min(index + text.length - 1, cellCount - 1);
+  const focusIndex = Math.min(Math.max(lastWritten, next.length - 1), cellCount - 1);
+  return { nextValue: next, focusIndex: Math.max(0, focusIndex) };
+}

package/src/otp-input/utils/filterValue.ts

@@ -0,0 +1,37 @@
+/** Strip to digits (default OTP behavior). */
+export function filterDigits(input: string): string {
+  return input.replace(/\D/g, '');
+}
+
+/** Keep only characters present in `allowed` (treat as a set of UTF-16 code units). */
+export function filterAllowedCharacters(allowed: string) {
+  const allowedSet = new Set<string>();
+  for (let i = 0; i < allowed.length; i++) {
+    allowedSet.add(allowed.charAt(i));
+  }
+  return (input: string) => {
+    let out = '';
+    for (let i = 0; i < input.length; i++) {
+      const ch = input.charAt(i);
+      if (allowedSet.has(ch)) {
+        out += ch;
+      }
+    }
+    return out;
+  };
+}
+
+/** Keep only characters matching `re` (tested per UTF-16 code unit). */
+export function filterByRegExp(re: RegExp) {
+  return (input: string) => {
+    let out = '';
+    for (let i = 0; i < input.length; i++) {
+      const ch = input.charAt(i);
+      re.lastIndex = 0;
+      if (re.test(ch)) {
+        out += ch;
+      }
+    }
+    return out;
+  };
+}