@cdx-ui/primitives 0.0.1-alpha.4 → 0.0.1-alpha.40

package/src/input/createInputField.tsx

@@ -6,7 +6,7 @@ import {
   Platform,
   type TextInputKeyPressEvent,
 } from 'react-native';
-import { mergeRefs, useFormControl } from '@cdx-ui/utils';
+import { mergeRefs, useFormControl, useFormControlContext } from '@cdx-ui/utils';
 import { dataAttributes } from '../utils/dataAttributes';
 import { useInputContext } from './context';
 import type { IInputProps } from './types';
@@ -18,7 +18,8 @@ export const createInputField = <T,>(BaseInputField: React.ComponentType<T>) =>
         children,
         onKeyPress,
         type = 'text',
-        'aria-label': ariaLabel = 'Input Field',
+        accessibilityLabel,
+        'aria-label': ariaLabelProp,
         secureTextEntry,
         editable,
         disabled,
@@ -46,15 +47,22 @@ export const createInputField = <T,>(BaseInputField: React.ComponentType<T>) =>
         id: props.id,
       });
 
+      const field = useFormControlContext();
+
       const handleFocus = (focusState: boolean, callback: any) => {
         setIsFocused(focusState);
         callback();
       };
 
-      const mergedRef = mergeRefs(ref, inputFieldRef);
+      const mergedRef =
+        Platform.OS === 'web'
+          ? mergeRefs(ref, inputFieldRef)
+          : mergeRefs(ref, inputFieldRef, field.inputRef);
 
       const isEffectivelyDisabled = isDisabled || inputProps.disabled;
 
+      const ariaLabel = accessibilityLabel ?? ariaLabelProp;
+
       const editableProp = useMemo(() => {
         if (editable !== undefined) {
           return editable;
@@ -64,6 +72,7 @@ export const createInputField = <T,>(BaseInputField: React.ComponentType<T>) =>
 
       return (
         <BaseInputField
+          {...inputProps}
           {...(props as T)}
           type={type}
           {...dataAttributes({
@@ -78,6 +87,7 @@ export const createInputField = <T,>(BaseInputField: React.ComponentType<T>) =>
           disabled={isEffectivelyDisabled}
           secureTextEntry={secureTextEntry || type === 'password'}
           accessible
+          accessibilityLabel={ariaLabel}
           aria-label={ariaLabel}
           aria-required={isRequired || inputProps.required}
           aria-invalid={isInvalid || inputProps['aria-invalid']}

package/src/input/index.tsx

@@ -1,5 +1,5 @@
+import type React from 'react';
 import { createInputField } from './createInputField';
-import { createInputIcon } from './createInputIcon';
 import { createInputRoot } from './createInputRoot';
 import { createInputSlot } from './createInputSlot';
 import type { IInputComponentType } from './types';
@@ -12,40 +12,27 @@ export type {
   IInputSlotProps,
 } from './types';
 
-export const createInput = <
+export function createInput<
   RootProps,
-  IconProps,
   SlotProps,
   FieldProps,
   RootRef = unknown,
   FieldRef = unknown,
->({
-  Root,
-  Icon,
-  Slot,
-  Field,
-}: {
+>(BaseComponents: {
   Root: React.ComponentType<RootProps>;
-  Icon: React.ComponentType<IconProps>;
   Slot: React.ComponentType<SlotProps>;
   Field: React.ComponentType<FieldProps>;
-}) => {
-  const Input = createInputRoot(Root) as any;
-  Input.Icon = createInputIcon(Icon);
-  Input.Slot = createInputSlot(Slot);
-  Input.Field = createInputField(Field);
+}) {
+  const Input = createInputRoot(BaseComponents.Root);
+  const Slot = createInputSlot(BaseComponents.Slot);
+  const Field = createInputField(BaseComponents.Field);
 
-  Input.displayName = 'Input';
-  Input.Icon.displayName = 'Input.Icon';
-  Input.Slot.displayName = 'Input.Slot';
-  Input.Field.displayName = 'Input.Field';
+  Input.displayName = 'InputPrimitive';
+  Slot.displayName = 'InputPrimitive.Slot';
+  Field.displayName = 'InputPrimitive.Field';
 
-  return Input as IInputComponentType<
-    RootProps,
-    IconProps,
-    SlotProps,
-    FieldProps,
-    RootRef,
-    FieldRef
-  >;
-};
+  return Object.assign(Input, {
+    Slot,
+    Field,
+  }) as IInputComponentType<RootProps, SlotProps, FieldProps, RootRef, FieldRef>;
+}

package/src/input/types.ts

@@ -93,7 +93,6 @@ export interface IInputSlotProps extends ViewProps {
 
 export type IInputComponentType<
   RootProps,
-  IconProps,
   SlotProps,
   FieldProps,
   RootRef = unknown,
@@ -101,9 +100,6 @@ export type IInputComponentType<
 > = React.ForwardRefExoticComponent<
   React.PropsWithoutRef<RootProps & IInputFieldProps> & React.RefAttributes<RootRef>
 > & {
-  Icon: React.ForwardRefExoticComponent<
-    React.PropsWithoutRef<IconProps> & React.RefAttributes<unknown>
-  >;
   Slot: React.ForwardRefExoticComponent<
     React.PropsWithoutRef<SlotProps & IInputSlotProps> & React.RefAttributes<unknown>
   >;

package/src/link/LinkProvider.tsx

@@ -0,0 +1,50 @@
+import { createContext, useContext, type ReactNode } from 'react';
+import type { LinkAction } from './types';
+
+export interface LinkConfig {
+  /**
+   * Global navigation handler for `<Link>` instances whose `href` passes the
+   * `shouldNavigate` check. Called with the `href` and the per-instance `action`.
+   *
+   * @param href   - The URL or path to navigate to.
+   * @param action - Navigation intent from the per-instance `action` prop:
+   *                 `'navigate'` (default) — smart navigation, avoids duplicates.
+   *                 `'push'` — always pushes a new entry onto the stack.
+   *                 `'replace'` — replaces the current entry without stacking.
+   */
+  navigate: (href: string, action: LinkAction) => void | Promise<void>;
+
+  /**
+   * Optional predicate evaluated at **render time** to decide whether the
+   * provider should handle a given `href`.
+   *
+   * - Returns `true`  → the provider's `navigate` is called on press;
+   *   on web the native `<a href>` is **removed** so the browser doesn't
+   *   follow the link.
+   * - Returns `false` → the provider is bypassed; on web the `<a href>` is
+   *   preserved (cmd-click, SEO, etc.); on native `Linking.openURL` is used.
+   *
+   * Defaults to `() => true` when omitted (all hrefs go through the provider).
+   */
+  shouldNavigate?: (href: string) => boolean;
+}
+
+const LinkConfigContext = createContext<LinkConfig | undefined>(undefined);
+
+export function LinkProvider({
+  navigate,
+  shouldNavigate,
+  children,
+}: LinkConfig & { children: ReactNode }) {
+  return (
+    <LinkConfigContext.Provider value={{ navigate, shouldNavigate }}>
+      {children}
+    </LinkConfigContext.Provider>
+  );
+}
+
+LinkProvider.displayName = 'LinkProvider';
+
+export function useLinkConfig(): LinkConfig | undefined {
+  return useContext(LinkConfigContext);
+}

package/src/link/createLink.tsx

@@ -0,0 +1,71 @@
+import React, { forwardRef } from 'react';
+import { composeEventHandlers } from '@cdx-ui/utils';
+import { useFocusRing, useFocus } from '@react-native-aria/focus';
+import { useHover, usePress } from '@react-native-aria/interactions';
+import { dataAttributes } from '../utils/dataAttributes';
+import { useLink } from './useLink';
+import type { ILinkProps } from './types';
+
+export const createLink = <RootT, R = unknown>({ Root }: { Root: React.ComponentType<RootT> }) =>
+  forwardRef(
+    (
+      {
+        children,
+        isHovered: isHoveredProp,
+        isPressed: isPressedProp,
+        isFocused: isFocusedProp,
+        isFocusVisible: isFocusVisibleProp,
+        href,
+        onPress,
+        action,
+        webProps,
+        ...props
+      }: ILinkProps,
+      ref: React.ForwardedRef<R>,
+    ) => {
+      const { isFocused, focusProps } = useFocus();
+      const { isFocusVisible, focusProps: focusRingProps } = useFocusRing() as {
+        isFocusVisible: boolean;
+        focusProps: typeof focusProps;
+      };
+      const { pressProps, isPressed } = usePress({});
+      const { isHovered, hoverProps } = useHover();
+
+      const { linkProps } = useLink({
+        href,
+        onPress,
+        action,
+        webProps,
+      });
+
+      const interactionAttrs = dataAttributes({
+        hover: isHoveredProp || isHovered,
+        focus: isFocusedProp || isFocused,
+        active: isPressedProp || isPressed,
+        focusVisible: isFocusVisibleProp || isFocusVisible,
+      });
+
+      return (
+        <Root
+          ref={ref}
+          {...interactionAttrs}
+          {...linkProps}
+          {...(props as RootT)}
+          onPressIn={composeEventHandlers(props?.onPressIn, pressProps.onPressIn)}
+          onPressOut={composeEventHandlers(props?.onPressOut, pressProps.onPressOut)}
+          onHoverIn={composeEventHandlers(props?.onHoverIn, hoverProps.onHoverIn)}
+          onHoverOut={composeEventHandlers(props?.onHoverOut, hoverProps.onHoverOut)}
+          onFocus={composeEventHandlers(
+            composeEventHandlers(props?.onFocus, focusProps.onFocus),
+            focusRingProps.onFocus,
+          )}
+          onBlur={composeEventHandlers(
+            composeEventHandlers(props?.onBlur, focusProps.onBlur),
+            focusRingProps.onBlur,
+          )}
+        >
+          {children}
+        </Root>
+      );
+    },
+  );

package/src/link/index.tsx

@@ -0,0 +1,5 @@
+export { createLink } from './createLink';
+export { LinkProvider } from './LinkProvider';
+export type { LinkConfig } from './LinkProvider';
+export { useLink } from './useLink';
+export type { ILinkProps, IUseLinkProp, LinkAction } from './types';

package/src/link/types.ts

@@ -0,0 +1,47 @@
+import type React from 'react';
+import type { GestureResponderEvent, PressableProps } from 'react-native';
+
+/**
+ * Navigation action forwarded to the `LinkProvider.navigate` callback.
+ *
+ * - `'navigate'` — (default) Smart navigation. In React Navigation this
+ *    avoids duplicating a screen that is already in the stack. In expo-router
+ *    it maps to `router.navigate()`.
+ * - `'push'`     — Always pushes a new screen onto the navigation stack,
+ *    even if the destination is already present.
+ * - `'replace'`  — Replaces the current screen without adding to the stack.
+ *    Useful for post-login redirects or wizard flows.
+ */
+export type LinkAction = 'navigate' | 'push' | 'replace';
+
+export interface ILinkProps extends PressableProps {
+  /**
+   * URL that should be opened on Link press
+   */
+  href?: string | undefined;
+  /**
+   * Callback that will be invoked on Link press
+   */
+  onPress?: ((event?: GestureResponderEvent) => void) | null | undefined;
+  /**
+   * Navigation action forwarded to the `LinkProvider`.
+   * Defaults to `'navigate'`.
+   */
+  action?: LinkAction;
+  isPressed?: boolean;
+  isHovered?: boolean;
+  isFocused?: boolean;
+  isFocusVisible?: boolean;
+  /**
+   * HTML anchor attributes applied only on web. Ignored on native platforms.
+   * `target`, `rel`, and `download` are forwarded via react-native-web's `hrefAttrs`.
+   */
+  webProps?: React.AnchorHTMLAttributes<HTMLAnchorElement>;
+}
+
+export interface IUseLinkProp {
+  href?: string;
+  onPress: ((event?: GestureResponderEvent) => void) | null | undefined;
+  action?: LinkAction;
+  webProps?: React.AnchorHTMLAttributes<HTMLAnchorElement>;
+}

package/src/link/useLink.ts

@@ -0,0 +1,54 @@
+import { Linking, Platform } from 'react-native';
+import type { AccessibilityRole, GestureResponderEvent } from 'react-native';
+import { useLinkConfig } from './LinkProvider';
+import type { IUseLinkProp } from './types';
+
+function defaultNavigate(href: string): void {
+  Linking.canOpenURL(href)
+    .then((supported) => {
+      if (supported) return Linking.openURL(href);
+      console.warn(`Cannot open URL: ${href}`);
+    })
+    .catch((err: unknown) => console.error('Failed to open URL', err));
+}
+
+export function useLink(props: IUseLinkProp) {
+  const { href, onPress, action = 'navigate', webProps } = props;
+  const config = useLinkConfig();
+
+  const providerHandles = !!config && !!href && (config.shouldNavigate?.(href) ?? true);
+
+  let platformLinkProps = {};
+
+  if (Platform.OS === 'web') {
+    platformLinkProps = {
+      href: providerHandles ? undefined : href,
+      hrefAttrs: webProps,
+      onPress: (event: GestureResponderEvent) => {
+        onPress?.(event);
+        if (providerHandles) void config.navigate(href, action);
+      },
+    };
+  } else {
+    platformLinkProps = {
+      onPress: (event: GestureResponderEvent) => {
+        onPress?.(event);
+        if (href) {
+          if (providerHandles) {
+            void config.navigate(href, action);
+          } else {
+            defaultNavigate(href);
+          }
+        }
+      },
+    };
+  }
+
+  return {
+    linkProps: {
+      ...platformLinkProps,
+      role: 'link' as AccessibilityRole,
+      accessible: true,
+    },
+  };
+}

package/src/otp-input/context.tsx

@@ -0,0 +1,8 @@
+import { createContext } from '@cdx-ui/utils';
+import type { OtpInputCellIndexContextValue, OtpInputContextValue } from './types';
+
+export const [OtpInputProvider, useOtpInputContext] =
+  createContext<OtpInputContextValue>('OtpInputContext');
+
+export const [OtpCellIndexProvider, useOtpCellIndexContext] =
+  createContext<OtpInputCellIndexContextValue>('OtpCellIndexContext');

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>
+      );
+    },
+  );