@cdx-ui/primitives 0.0.1-beta.9 → 0.0.1-beta.91

package/src/list-item/types.ts

@@ -1,10 +1,7 @@
-import type { ForwardRefExoticComponent, PropsWithoutRef, ReactNode, RefAttributes } from 'react';
-import type { PressableProps, TextProps, ViewProps } from 'react-native';
+import type { PressableProps, ViewProps } from 'react-native';
 
 export type ListItemSize = 'default' | 'compact';
 
-export type ListItemSurface = 'default' | 'negative';
-
 /**
  * Cross-axis alignment for the row (`flex-direction: row`).
  * - **center**: Leading, content, and trailing are vertically centered (typical transactions).
@@ -16,32 +13,18 @@ export type IListItemPressablePassthrough = Partial<
   Pick<PressableProps, 'onPressIn' | 'onPressOut' | 'onHoverIn' | 'onHoverOut'>
 >;
 
-export interface IListItemProps extends ViewProps, IListItemPressablePassthrough {
+export interface InterfaceListItemProps extends ViewProps, IListItemPressablePassthrough {
   /**
    * Disables press handling when the root is pressable (maps to Pressable `disabled`).
    */
-  disabled?: boolean;
+  isDisabled?: boolean;
   /**
    * When set (and `asChild` is not used), root renders as pressable with interaction props.
    */
   onPress?: PressableProps['onPress'];
-  /**
-   * Vertical density; mapped at styled layer via `data-size`.
-   * @default 'default'
-   */
-  size?: ListItemSize;
-  /**
-   * Semantic row surface (e.g. canceled transaction); mapped via `data-surface`.
-   * @default 'default'
-   */
-  surface?: ListItemSurface;
-  /**
-   * Whether the row shows a bottom separator; mapped via `data-separator`.
-   * @default true
-   */
-  showSeparator?: boolean;
   /**
    * Vertical alignment of leading / content / trailing along the row cross axis.
+   * Drives the primitive's inline row style and the styled-layer CVA in tandem.
    * @default 'center'
    */
   crossAlign?: ListItemCrossAlign;
@@ -52,71 +35,4 @@ export interface IListItemProps extends ViewProps, IListItemPressablePassthrough
   asChild?: boolean;
 }
 
-export interface IListItemContextValue {
-  isPressed: boolean;
-  isHovered: boolean;
-  isDisabled: boolean;
-  crossAlign: ListItemCrossAlign;
-}
-
-export interface IListItemLeadingSlotProps extends ViewProps {
-  /**
-   * Decorative leading content defaults to hidden from the accessibility tree.
-   * Set to `false` when the leading region contains meaningful controls.
-   * @default true
-   */
-  'aria-hidden'?: boolean;
-}
-
-export type IListItemContentProps = ViewProps;
-
-export type IListItemTitleProps = TextProps;
-
-export type IListItemDescriptionProps = TextProps;
-
-export type IListItemMetaProps = TextProps;
-
-export type IListItemTrailingSlotProps = ViewProps;
-
-export interface IListItemSectionHeaderProps extends ViewProps {
-  /** Primary section label (e.g. date heading). */
-  children: ReactNode;
-  /** Optional right-aligned adornment (e.g. section Chip). */
-  trailing?: ReactNode;
-  /**
-   * Whether to expose the top divider marker for styling (`data-divider`).
-   * @default true
-   */
-  showDivider?: boolean;
-}
-
-export type IListItemComponentType<
-  RootRef,
-  LeadingSlot,
-  Content,
-  Title,
-  Description,
-  Meta,
-  TrailingSlot,
-  SectionHeader,
-> = ForwardRefExoticComponent<RefAttributes<RootRef> & IListItemProps> & {
-  LeadingSlot: ForwardRefExoticComponent<
-    RefAttributes<LeadingSlot> & PropsWithoutRef<LeadingSlot> & IListItemLeadingSlotProps
-  >;
-  Content: ForwardRefExoticComponent<
-    RefAttributes<Content> & PropsWithoutRef<Content> & IListItemContentProps
-  >;
-  Title: ForwardRefExoticComponent<
-    RefAttributes<Title> & PropsWithoutRef<Title> & IListItemTitleProps
-  >;
-  Description: ForwardRefExoticComponent<
-    RefAttributes<Description> & PropsWithoutRef<Description> & IListItemDescriptionProps
-  >;
-  Meta: ForwardRefExoticComponent<RefAttributes<Meta> & PropsWithoutRef<Meta> & IListItemMetaProps>;
-  TrailingSlot: ForwardRefExoticComponent<
-    RefAttributes<TrailingSlot> & PropsWithoutRef<TrailingSlot> & IListItemTrailingSlotProps
-  >;
-  SectionHeader: ForwardRefExoticComponent<
-    RefAttributes<SectionHeader> & PropsWithoutRef<SectionHeader> & IListItemSectionHeaderProps
-  >;
-};
+export type IListItemProps = InterfaceListItemProps;

package/src/otp-input/OtpInputField.tsx

@@ -0,0 +1,122 @@
+import { forwardRef, useMemo } from 'react';
+import {
+  Platform,
+  TextInput,
+  type TextInputKeyPressEvent,
+  type TextInputProps,
+} from 'react-native';
+import { mergeRefs } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { useOtpCellIndexContext, useOtpInputContext } from './context';
+import type { IOtpInputFieldProps } from './types';
+
+export interface OtpInputFieldProps extends IOtpInputFieldProps {
+  asChild?: boolean;
+}
+
+/**
+ * Concrete per-cell TextInput primitive for OTP input.
+ *
+ * Reads OtpInput context (state machine) and OtpCellIndex context (position) to
+ * wire ref registration, accessibility labels, autofill hints, and key-press/
+ * change-text handlers. Renders a `TextInput` by default; supports `asChild` via
+ * `Slot` for element substitution (Standard 2).
+ *
+ * Standards mapping:
+ *   - Standard 3 #1 — behavioral state (ref registration, focus, change handling).
+ *   - Standard 3 #2 — non-host a11y (computed accessibilityLabel, SMS autofill).
+ */
+export const OtpInputField = forwardRef<TextInput, OtpInputFieldProps>((props, ref) => {
+  const { asChild, ...restProps } = props;
+  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
+  } = restProps as TextInputProps;
+  void _omitValue;
+  void _omitDefault;
+  void _omitOnChange;
+
+  const Comp = asChild ? Slot : TextInput;
+
+  return (
+    <Comp
+      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 TextInputProps)}
+      style={[extraStyle, incomingStyle]}
+    />
+  );
+});
+
+OtpInputField.displayName = 'OtpInputField';

package/src/otp-input/index.ts

@@ -0,0 +1,16 @@
+export { applyOtpInputChange } from './utils/applyValueChange';
+export { filterAllowedCharacters, filterByRegExp, filterDigits } from './utils/filterValue';
+export { OtpInputField, type OtpInputFieldProps } from './OtpInputField';
+export { useOtpInput, type UseOtpInputProps, type UseOtpInputReturn } from './useOtpInput';
+export {
+  OtpInputProvider,
+  useOtpInputContext,
+  OtpCellIndexProvider,
+  useOtpCellIndexContext,
+} from './context';
+export type {
+  IOtpInputRootProps,
+  IOtpInputFieldProps,
+  OtpInputContextValue,
+  OtpInputCellIndexContextValue,
+} from './types';

package/src/otp-input/types.ts

@@ -1,5 +1,3 @@
-import type React from 'react';
-import type { ReactNode } from 'react';
 import type { TextInputProps, ViewProps } from 'react-native';
 
 export interface IOtpInputRootProps extends ViewProps {
@@ -48,10 +46,6 @@ export interface IOtpInputRootProps extends ViewProps {
   cellTestIdPrefix?: string;
 }
 
-export interface IOtpInputCellProps extends ViewProps {
-  children?: ReactNode;
-}
-
 export type IOtpInputFieldProps = TextInputProps;
 
 export interface OtpInputCellIndexContextValue {
@@ -73,20 +67,3 @@ export interface OtpInputContextValue {
   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/useOtpInput.ts

@@ -0,0 +1,156 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import type { TextInput, TextInputProps } from 'react-native';
+import { useFormControlContext } from '@cdx-ui/utils';
+import { applyOtpInputChange } from './utils/applyValueChange';
+import { filterAllowedCharacters, filterByRegExp, filterDigits } from './utils/filterValue';
+import type { IOtpInputRootProps, OtpInputContextValue } from './types';
+
+export type UseOtpInputProps = Omit<IOtpInputRootProps, keyof import('react-native').ViewProps> & {
+  accessibilityLabel?: string;
+};
+
+export interface UseOtpInputReturn extends OtpInputContextValue {}
+
+/**
+ * Headless behavioral primitive for OTP input.
+ *
+ * Owns the controlled value, focus management, masked-input handling, and the
+ * `onComplete` lifecycle. Exposes the context value the styled layer must provide
+ * to `OtpInputField` primitives via `OtpInputProvider`.
+ *
+ * Standards mapping:
+ *   - Standard 3 #1 — controlled state + focus management state machine.
+ *   - Standard 3 #4 — compound contract ownership (context value for Fields).
+ */
+export function useOtpInput(props: UseOtpInputProps): UseOtpInputReturn {
+  const {
+    cellCount,
+    value,
+    onChangeText,
+    onComplete,
+    isDisabled: isDisabledProp,
+    isInvalid: isInvalidProp,
+    isReadOnly: isReadOnlyProp,
+    smsOtpAutofill = true,
+    filterInput,
+    allowedCharacters,
+    characterPattern,
+    getCellProps,
+    cellTestIdPrefix,
+    accessibilityLabel: rootAccessibilityLabel,
+  } = props;
+
+  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]);
+
+  return useMemo<OtpInputContextValue>(
+    () => ({
+      cellCount,
+      value,
+      isDisabled,
+      isInvalid,
+      isReadOnly,
+      smsOtpAutofill,
+      filter,
+      getCellProps: getCellProps as ((index: number) => Partial<TextInputProps>) | undefined,
+      cellTestIdPrefix,
+      rootAccessibilityLabel,
+      setFieldRef,
+      handleFieldChange,
+      handleFieldKeyPress,
+    }),
+    [
+      cellCount,
+      value,
+      isDisabled,
+      isInvalid,
+      isReadOnly,
+      smsOtpAutofill,
+      filter,
+      getCellProps,
+      cellTestIdPrefix,
+      rootAccessibilityLabel,
+      setFieldRef,
+      handleFieldChange,
+      handleFieldKeyPress,
+    ],
+  );
+}

package/src/overlay/useDismissOverlay.ts

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-
 import type { RefObject } from 'react';
 
 /**

package/src/overlay/useEscapeKey.ts

@@ -1,5 +1,3 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-
 /**
  * No-op on native — Escape key dismissal is not applicable.
  * Native uses the system back gesture / hardware button via Modal.

package/src/portal/index.ts

@@ -0,0 +1 @@
+export * from './portal';

package/src/portal/portal.tsx

@@ -0,0 +1,116 @@
+import * as React from 'react';
+import { useEffect, useSyncExternalStore } from 'react';
+import { Platform, type View, type ViewStyle } from 'react-native';
+
+const DEFAULT_PORTAL_HOST = 'FORGE_UI_DEFAULT_HOST_NAME';
+
+type PortalMap = Map<string, React.ReactNode>;
+type PortalHostMap = Map<string, PortalMap>;
+
+interface PortalStore {
+  map: PortalHostMap;
+  listeners: Set<() => void>;
+}
+
+const store: PortalStore = {
+  map: new Map<string, PortalMap>().set(DEFAULT_PORTAL_HOST, new Map<string, React.ReactNode>()),
+  listeners: new Set(),
+};
+
+// --------------------------------------------------
+
+function emit() {
+  for (const cb of store.listeners) cb();
+}
+
+function getSnapshot() {
+  return store.map;
+}
+
+function subscribe(cb: () => void) {
+  store.listeners.add(cb);
+  return () => {
+    store.listeners.delete(cb);
+  };
+}
+
+function updatePortal(hostName: string, name: string, children: React.ReactNode) {
+  const next = new Map(store.map);
+  const portal = next.get(hostName) ?? new Map<string, React.ReactNode>();
+  portal.set(name, children);
+  next.set(hostName, portal);
+  store.map = next;
+  emit();
+}
+
+function removePortal(hostName: string, name: string) {
+  const next = new Map(store.map);
+  const portal = next.get(hostName) ?? new Map<string, React.ReactNode>();
+  portal.delete(name);
+  next.set(hostName, portal);
+  store.map = next;
+  emit();
+}
+
+// --------------------------------------------------
+
+export function PortalHost({ name = DEFAULT_PORTAL_HOST }: { name?: string }) {
+  const map = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const portalMap = map.get(name) ?? new Map<string, React.ReactNode>();
+  if (portalMap.size === 0) return null;
+  return <>{Array.from(portalMap.values())}</>;
+}
+
+// --------------------------------------------------
+
+export function Portal({
+  name,
+  hostName = DEFAULT_PORTAL_HOST,
+  children,
+}: {
+  name: string;
+  hostName?: string;
+  children: React.ReactNode;
+}) {
+  useEffect(() => {
+    updatePortal(hostName, name, children);
+    return () => {
+      removePortal(hostName, name);
+    };
+  }, [hostName, name, children]);
+
+  return null;
+}
+
+// --------------------------------------------------
+
+const ROOT: ViewStyle = {
+  flex: 1,
+};
+
+/**
+ * @deprecated use `FullWindowOverlay` from `react-native-screens` instead
+ * @example
+import { FullWindowOverlay } from "react-native-screens"
+const WindowOverlay = Platform.OS === "ios" ? FullWindowOverlay : Fragment
+// Wrap the `<PortalHost/>` with `<WindowOverlay/>`
+<WindowOverlay><PortalHost/></WindowOverlay>
+ */
+export function useModalPortalRoot() {
+  const ref = React.useRef<View>(null);
+  const [offset, setSideOffSet] = React.useState(0);
+
+  const onLayout = React.useCallback(() => {
+    if (Platform.OS === 'web') return;
+    ref.current?.measure((_x, _y, _width, _height, _pageX, pageY) => {
+      setSideOffSet(-pageY);
+    });
+  }, []);
+
+  return {
+    ref,
+    offset,
+    onLayout,
+    style: ROOT,
+  };
+}

package/src/progress-bar/ProgressBarIndicator.tsx

@@ -0,0 +1,34 @@
+import { forwardRef, useMemo } from 'react';
+import { View, type ViewProps, type ViewStyle } from 'react-native';
+import { Slot } from '../slot';
+import { dataAttributes } from '../utils/dataAttributes';
+import { useProgressContext } from './context';
+
+type PercentString = `${number}%`;
+
+export interface ProgressBarIndicatorProps extends ViewProps {
+  readonly asChild?: boolean;
+}
+
+export const ProgressBarIndicator = forwardRef<View, ProgressBarIndicatorProps>(
+  ({ asChild, style, ...rest }, ref) => {
+    const { percent, state, max, value } = useProgressContext();
+
+    const filledStyle = useMemo((): ViewStyle => {
+      const pct = `${String(percent)}%` as PercentString;
+      return { width: pct, height: '100%' };
+    }, [percent]);
+
+    const dataAttrs = dataAttributes({
+      state,
+      value: value === null ? undefined : String(value),
+      max: String(max),
+    });
+
+    const Comp = asChild ? Slot : View;
+
+    return <Comp ref={ref} {...rest} {...dataAttrs} style={[filledStyle, style]} />;
+  },
+);
+
+ProgressBarIndicator.displayName = 'ProgressBarIndicator';