@cdx-ui/primitives 0.0.1-beta.14 → 0.0.1-beta.141

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/useAnchorPosition.ts

@@ -16,48 +16,130 @@ function measureWeb(element: any): AnchorLayout {
   return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
 }
 
+function setLayoutIfChanged(
+  setLayout: React.Dispatch<React.SetStateAction<AnchorLayout | null>>,
+  next: AnchorLayout,
+) {
+  setLayout((prev) => {
+    if (
+      prev?.x === next.x &&
+      prev.y === next.y &&
+      prev.width === next.width &&
+      prev.height === next.height
+    ) {
+      return prev;
+    }
+    return next;
+  });
+}
+
+export interface UseAnchorPositionOptions {
+  /** Re-run layout measurement when this value changes (e.g. slider value percent). */
+  remeasureKey?: unknown;
+  /** Poll anchor position each animation frame while open (for anchors that move). */
+  trackWhileOpen?: boolean;
+}
+
 /**
  * Measures an anchor element's position and size, re-measuring on scroll/resize
  * (web) so a positioned overlay can track its anchor across layout changes.
  *
  * Returns `null` until the first measurement completes.
  */
-export function useAnchorPosition(anchorRef: RefObject<any>, open: boolean): AnchorLayout | null {
+export function useAnchorPosition(
+  anchorRef: RefObject<any>,
+  open: boolean,
+  options?: UseAnchorPositionOptions,
+): AnchorLayout | null {
+  const { remeasureKey, trackWhileOpen = false } = options ?? {};
   const [layout, setLayout] = useState<AnchorLayout | null>(null);
 
+  const measureAnchor = () => {
+    const anchor = anchorRef.current;
+    if (!anchor) {
+      return;
+    }
+
+    if (Platform.OS === 'web') {
+      setLayoutIfChanged(setLayout, measureWeb(anchor));
+      return;
+    }
+
+    anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
+      setLayoutIfChanged(setLayout, { x, y, width, height });
+    });
+  };
+
   useIsomorphicLayoutEffect(() => {
     if (!open) {
       setLayout(null);
       return;
     }
 
-    const anchor = anchorRef.current;
-    if (!anchor) return;
-
     let cancelled = false;
 
+    const runMeasure = () => {
+      if (!cancelled) {
+        measureAnchor();
+      }
+    };
+
+    runMeasure();
+
     if (Platform.OS === 'web') {
-      setLayout(measureWeb(anchor));
-    } else {
-      anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
-        if (!cancelled) {
-          setLayout({ x, y, width, height });
-        }
-      });
+      const frame = requestAnimationFrame(runMeasure);
+      return () => {
+        cancelled = true;
+        cancelAnimationFrame(frame);
+      };
     }
 
+    const anchor = anchorRef.current;
+    if (!anchor) {
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    anchor.measureInWindow((x: number, y: number, width: number, height: number) => {
+      if (!cancelled) {
+        setLayoutIfChanged(setLayout, { x, y, width, height });
+      }
+    });
+
     return () => {
       cancelled = true;
     };
-  }, [open, anchorRef]);
+  }, [open, anchorRef, remeasureKey]);
+
+  useEffect(() => {
+    if (!open || !trackWhileOpen) {
+      return;
+    }
+
+    let frameId = 0;
+    const tick = () => {
+      measureAnchor();
+      frameId = requestAnimationFrame(tick);
+    };
+    frameId = requestAnimationFrame(tick);
+
+    return () => {
+      cancelAnimationFrame(frameId);
+    };
+  }, [open, anchorRef, remeasureKey, trackWhileOpen]);
 
   useEffect(() => {
-    if (!open || Platform.OS !== 'web') return;
+    if (!open || Platform.OS !== 'web' || trackWhileOpen) {
+      return;
+    }
 
     const anchor = anchorRef.current;
-    if (!anchor) return;
+    if (!anchor) {
+      return;
+    }
 
-    const update = () => setLayout(measureWeb(anchor));
+    const update = () => setLayoutIfChanged(setLayout, measureWeb(anchor));
 
     window.addEventListener('scroll', update, true);
     window.addEventListener('resize', update);
@@ -66,7 +148,7 @@ export function useAnchorPosition(anchorRef: RefObject<any>, open: boolean): Anc
       window.removeEventListener('scroll', update, true);
       window.removeEventListener('resize', update);
     };
-  }, [open, anchorRef]);
+  }, [open, anchorRef, remeasureKey, trackWhileOpen]);
 
   return layout;
 }

package/src/overlay/useDismissOverlay.ts

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

package/src/overlay/useDismissOverlay.web.ts

@@ -1,6 +1,14 @@
 import type { RefObject } from 'react';
 import { useEffect, useRef } from 'react';
 
+function refContainsNode(ref: RefObject<unknown>, target: Node): boolean {
+  const current = ref.current as { contains?: (node: Node) => boolean } | null;
+  if (!current || typeof current.contains !== 'function') {
+    return false;
+  }
+  return current.contains(target);
+}
+
 /**
  * Dismisses an overlay when the user clicks/presses outside of it or when
  * focus moves to an element outside the overlay via keyboard.
@@ -24,11 +32,11 @@ export function useDismissOverlay(
     }
 
     const isInsideOverlay = (target: Node) => {
-      if (contentRef.current?.contains?.(target)) {
+      if (refContainsNode(contentRef, target)) {
         return true;
       }
       for (const ref of excludeRefsRef.current) {
-        if (ref.current?.contains?.(target)) {
+        if (refContainsNode(ref, target)) {
           return true;
         }
       }

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/overlay/useOverlayPosition.ts

@@ -37,6 +37,9 @@ export const OverlayInsetsProvider = OverlayInsetsContext.Provider;
 /** Minimum gap (px) between the overlay edge and the viewport/safe-area boundary. */
 const SCREEN_EDGE_PADDING = 8;
 
+/** Gap between anchor and popover content. */
+const POPOVER_GAP = 4;
+
 /** Minimum usable space (px) below the anchor before the overlay flips above. */
 const MIN_CONTENT_HEIGHT = 200;
 
@@ -71,7 +74,7 @@ export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPo
       const maxHeight = Math.max(0, spaceBelow);
       return {
         style: {
-          top: anchorBottom,
+          top: anchorBottom + POPOVER_GAP,
           left: anchorLayout.x,
           width: anchorLayout.width,
           maxHeight,
@@ -84,7 +87,7 @@ export function useOverlayPosition(anchorLayout: AnchorLayout | null): OverlayPo
     const maxHeight = Math.max(0, spaceAbove);
     return {
       style: {
-        bottom: viewportHeight - anchorLayout.y,
+        bottom: viewportHeight - anchorLayout.y + POPOVER_GAP,
         left: anchorLayout.x,
         width: anchorLayout.width,
         maxHeight,

package/src/portal/index.ts

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

package/src/portal/portal.tsx

@@ -0,0 +1,193 @@
+import * as React from 'react';
+import { useEffect, useSyncExternalStore } from 'react';
+import { Platform, type View, type ViewStyle } from 'react-native';
+import { createPortalFn } from '../utils/createPortal';
+
+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(),
+};
+
+/** Tracks mounted PortalHost instances per host name — only the first mount renders portals. */
+const hostStackStore = {
+  stacks: new Map<string, symbol[]>(),
+  listeners: new Set<() => void>(),
+};
+
+let hasWarnedMultiplePortalHosts = false;
+
+// --------------------------------------------------
+
+function emit() {
+  for (const cb of store.listeners) cb();
+}
+
+function emitHostStack() {
+  for (const cb of hostStackStore.listeners) cb();
+}
+
+function getHostStackSnapshot() {
+  return hostStackStore.stacks;
+}
+
+function subscribeHostStack(cb: () => void) {
+  hostStackStore.listeners.add(cb);
+  return () => {
+    hostStackStore.listeners.delete(cb);
+  };
+}
+
+function pushPortalHost(name: string, id: symbol) {
+  const stacks = new Map(hostStackStore.stacks);
+  const stack = [...(stacks.get(name) ?? [])];
+  stack.push(id);
+  stacks.set(name, stack);
+  hostStackStore.stacks = stacks;
+
+  if (__DEV__ && !hasWarnedMultiplePortalHosts && stack.length > 1) {
+    hasWarnedMultiplePortalHosts = true;
+    console.warn(
+      '[Forge UI] Multiple PortalHost instances detected for the same host name. ' +
+        'Only the first mounted PortalHost renders portal content. ' +
+        'Mount a single PortalHost near your app root (ForgeDesignProvider does this automatically).',
+    );
+  }
+
+  emitHostStack();
+}
+
+function popPortalHost(name: string, id: symbol) {
+  const stacks = new Map(hostStackStore.stacks);
+  const stack = (stacks.get(name) ?? []).filter((entry) => entry !== id);
+  stacks.set(name, stack);
+  hostStackStore.stacks = stacks;
+  emitHostStack();
+}
+
+function isActivePortalHost(name: string, id: symbol) {
+  const stack = hostStackStore.stacks.get(name) ?? [];
+  return stack.length > 0 && stack[0] === id;
+}
+
+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 hostId = React.useRef(Symbol()).current;
+
+  useEffect(() => {
+    pushPortalHost(name, hostId);
+    return () => {
+      popPortalHost(name, hostId);
+    };
+  }, [name, hostId]);
+
+  useSyncExternalStore(subscribeHostStack, getHostStackSnapshot, getHostStackSnapshot);
+
+  const map = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const portalMap = map.get(name) ?? new Map<string, React.ReactNode>();
+
+  if (!isActivePortalHost(name, hostId) || portalMap.size === 0) {
+    return null;
+  }
+
+  const content = <>{Array.from(portalMap.values())}</>;
+
+  if (Platform.OS === 'web' && createPortalFn && typeof document !== 'undefined') {
+    return createPortalFn(content, document.body);
+  }
+
+  return content;
+}
+
+// --------------------------------------------------
+
+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';