@cdx-ui/components 0.0.1-beta.17 → 0.0.1-beta.171

package/src/navigation/types.ts

@@ -0,0 +1,54 @@
+import type { ReactElement } from 'react';
+import type { ImageSourcePropType } from 'react-native';
+import type { BottomTabNavigationOptions } from '@react-navigation/bottom-tabs';
+import type { NativeBottomTabNavigationOptions } from '@react-navigation/bottom-tabs/unstable';
+
+/**
+ * Structural mirror of the `image` arm of `NativeBottomTabIcon` from
+ * `@react-navigation/bottom-tabs/unstable`. Declared locally so
+ * `@cdx-ui/components` carries no runtime React Navigation dependency —
+ * the drift guards below fail the build if the upstream shape changes.
+ */
+export interface ForgeNativeBottomTabIcon {
+  type: 'image';
+  /** Metro-resolved asset (e.g. a static `require('./icon.png')`). */
+  source: ImageSourcePropType;
+  /**
+   * Render as a template image tinted with the tab bar's active/inactive
+   * tint color. iOS-only flag — Android always tints tab icons.
+   */
+  tinted?: boolean;
+}
+
+/**
+ * The value `forgeTabIcon()` returns — callable as `tabBarIcon` on **both**
+ * React Navigation bottom tab navigators. The intersection carries both call
+ * signatures; the platform-split implementation guarantees the matching one
+ * at runtime:
+ *
+ * - `createBottomTabNavigator` (web/JS) invokes it with
+ *   `{ focused, color, size }` and renders the returned element.
+ * - `createNativeBottomTabNavigator` (iOS/Android) invokes it with
+ *   `{ focused }` and receives a native icon descriptor.
+ */
+export type ForgeTabBarIcon = ((props: {
+  focused: boolean;
+  color: string;
+  size: number;
+}) => ReactElement) &
+  ((props: { focused: boolean }) => ForgeNativeBottomTabIcon);
+
+/**
+ * Compile-time drift guards (see `useForgeBottomTabScreenOptions` for the
+ * pattern): `ForgeTabBarIcon` must stay assignable to the `tabBarIcon`
+ * option of both navigators. The `null as any` casts keep the runtime
+ * values `null` so tree-shakers eliminate them entirely.
+ */
+
+const _rnDriftGuardWeb: BottomTabNavigationOptions['tabBarIcon'] =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  null as any as ForgeTabBarIcon;
+
+const _rnDriftGuardNative: NativeBottomTabNavigationOptions['tabBarIcon'] =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  null as any as ForgeTabBarIcon;

package/src/providers/animation-settings/index.ts

@@ -0,0 +1,11 @@
+export {
+  GlobalAnimationSettingsProvider,
+  AnimationSettingsProvider,
+  useGlobalAnimationSettings,
+  useAnimationSettings,
+} from './provider';
+export type {
+  GlobalAnimationSettingsContextValue,
+  GlobalAnimationSettingsProviderProps,
+  AnimationSettingsContextValue,
+} from './types';

package/src/providers/animation-settings/provider.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import { useReducedMotion } from 'react-native-reanimated';
+import { createContext } from '@cdx-ui/utils';
+import type {
+  GlobalAnimationSettingsContextValue,
+  GlobalAnimationSettingsProviderProps,
+  AnimationSettingsContextValue,
+} from './types';
+
+const [GlobalAnimationSettingsProviderComponent, useGlobalAnimationSettings] =
+  createContext<GlobalAnimationSettingsContextValue>('GlobalAnimationSettingsContext', {
+    strict: false,
+    defaultValue: { globalIsAllAnimationsDisabled: false },
+  });
+
+export { useGlobalAnimationSettings };
+
+/**
+ * GlobalAnimationSettingsProvider Component
+ *
+ * @description
+ * Provider component that controls global animation settings across the application.
+ * When animation is set to 'disable-all', all animations will be disabled globally.
+ * Additionally, if the user has enabled reduce motion in accessibility settings,
+ * all animations will be disabled automatically.
+ *
+ * The global setting is read directly via `useGlobalAnimationSettings`; the
+ * separate `AnimationSettingsProvider` handles per-subtree cascading. Both
+ * contexts are non-strict, so components can read them without a provider
+ * mounted (falling back to "animations enabled").
+ *
+ * @param {GlobalAnimationSettingsProviderProps} props - Provider props
+ * @param {AnimationRootDisableAll} [props.animation] - Global animation setting
+ * @param {ReactNode} props.children - Child components to wrap
+ */
+export const GlobalAnimationSettingsProvider: React.FC<GlobalAnimationSettingsProviderProps> = ({
+  animation,
+  children,
+}) => {
+  const reducedMotion = useReducedMotion();
+  const globalIsAllAnimationsDisabled = animation === 'disable-all' || reducedMotion;
+
+  return (
+    <GlobalAnimationSettingsProviderComponent value={{ globalIsAllAnimationsDisabled }}>
+      {children}
+    </GlobalAnimationSettingsProviderComponent>
+  );
+};
+
+export const [AnimationSettingsProvider, useAnimationSettings] =
+  createContext<AnimationSettingsContextValue>('AnimationSettingsContext', {
+    strict: false,
+    defaultValue: { isAllAnimationsDisabled: false },
+  });

package/src/providers/animation-settings/types.ts

@@ -0,0 +1,37 @@
+import type { ReactNode } from 'react';
+import type { AnimationRootDisableAll } from '../../animation';
+
+/**
+ * Props for GlobalAnimationSettingsProvider component
+ */
+export interface GlobalAnimationSettingsProviderProps {
+  /**
+   * Global animation setting
+   * When set to 'disable-all', all animations across the app will be disabled
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Child components to render within the provider
+   */
+  children: ReactNode;
+}
+
+/**
+ * Context value for global animation settings
+ */
+export interface GlobalAnimationSettingsContextValue {
+  /**
+   * Whether all animations should be disabled globally
+   */
+  globalIsAllAnimationsDisabled: boolean;
+}
+
+/**
+ * Context value for global animation settings
+ */
+export interface AnimationSettingsContextValue {
+  /**
+   * Whether all animations should be disabled (cascading from parent)
+   */
+  isAllAnimationsDisabled: boolean;
+}

package/src/providers/forge-design/index.ts

@@ -0,0 +1,2 @@
+export { default as ForgeDesignProvider } from './provider';
+export * from './types';

package/src/providers/forge-design/provider.tsx

@@ -0,0 +1,80 @@
+import React from 'react';
+import { SafeAreaListener } from 'react-native-safe-area-context';
+import { Uniwind } from 'uniwind';
+import {
+  OverlayInsetsProvider,
+  OverlayStackProvider,
+  PortalHost,
+  PortalProvider,
+  type EdgeInsets,
+} from '@cdx-ui/primitives';
+import { GlobalAnimationSettingsProvider } from '../animation-settings';
+import { TextComponentProvider } from '../text-component/provider';
+import { ToastProvider } from '../toast/provider';
+import type { ForgeDesignProviderProps } from './types';
+
+/**
+ * ForgeDesignProvider Component
+ *
+ * @description
+ * Main provider component for HeroUI Native that configures the application
+ * with global settings. This component should wrap your entire application
+ * or the section where you want to use HeroUI Native components.
+ *
+ * Currently provides:
+ * - Global animation settings
+ * - Global text component configuration
+ * - Toast notification system
+ * - Portal management for overlays
+ *
+ * @param {ForgeDesignProviderProps} props - Provider configuration props
+ * @param {ReactNode} props.children - Child components to wrap
+ * @param {ForgeDesignConfig} [props.config] - Configuration object
+ *
+ */
+const ForgeDesignProvider: React.FC<ForgeDesignProviderProps> = ({ children, config = {} }) => {
+  const { textProps, toast, animation } = config;
+  const [overlayInsets, setOverlayInsets] = React.useState<EdgeInsets>({
+    top: 0,
+    right: 0,
+    bottom: 0,
+    left: 0,
+  });
+
+  // Determine if toast should be enabled and get props
+  const isToastEnabled = toast !== false && toast !== 'disabled';
+  const toastProps = typeof toast === 'object' ? toast : {};
+
+  return (
+    <SafeAreaListener
+      onChange={({ insets }) => {
+        Uniwind.updateInsets(insets);
+        setOverlayInsets(insets);
+      }}
+    >
+      <PortalProvider>
+        <OverlayStackProvider>
+          <OverlayInsetsProvider value={overlayInsets}>
+            <GlobalAnimationSettingsProvider animation={animation}>
+              <TextComponentProvider value={{ textProps }}>
+                {isToastEnabled ? (
+                  <ToastProvider {...toastProps}>
+                    {children}
+                    <PortalHost />
+                  </ToastProvider>
+                ) : (
+                  <>
+                    {children}
+                    <PortalHost />
+                  </>
+                )}
+              </TextComponentProvider>
+            </GlobalAnimationSettingsProvider>
+          </OverlayInsetsProvider>
+        </OverlayStackProvider>
+      </PortalProvider>
+    </SafeAreaListener>
+  );
+};
+
+export default ForgeDesignProvider;

package/src/providers/forge-design/types.ts

@@ -0,0 +1,84 @@
+import type { ReactNode } from 'react';
+import type { AnimationRootDisableAll } from '../../animation';
+import type { TextComponentContextValue } from '../text-component/types';
+import type { ToastProviderProps } from '../toast/types';
+
+/**
+ * Configuration object for ForgeDesignProvider
+ *
+ * @interface ForgeDesignConfig
+ * @extends TextComponentContextValue
+ *
+ * @description
+ * Contains configuration options for the HeroUI Native provider.
+ * Additional configuration options can be added in future versions.
+ */
+export interface ForgeDesignConfig extends TextComponentContextValue {
+  /**
+   * Global animation configuration
+   *
+   * @description
+   * When set to 'disable-all', all animations across the application will be disabled.
+   */
+  animation?: AnimationRootDisableAll;
+  /**
+   * Toast configuration
+   *
+   * @description
+   * Configure the global toast system including insets and wrapper components.
+   * Set to `false` or `'disabled'` to disable the toast provider entirely.
+   * Provide a `ToastProviderProps` object for custom configuration.
+   */
+  toast?: boolean | 'disabled' | ToastProviderProps;
+}
+
+/**
+ * Props for ForgeDesignProvider component
+ *
+ * @interface ForgeDesignProviderProps
+ *
+ * @description
+ * Main provider component props that wraps the entire application
+ * or a section of it to provide HeroUI Native functionality.
+ *
+ * @example
+ * ```tsx
+ * <ForgeDesignProvider config={{
+ *   textProps: {
+ *     allowFontScaling: false,
+ *     maxFontSizeMultiplier: 1.5
+ *   }
+ * }}>
+ *   <App />
+ * </ForgeDesignProvider>
+ * ```
+ */
+export interface ForgeDesignProviderProps {
+  /**
+   * Child components to render within the provider
+   *
+   * @description
+   * All children will have access to HeroUI Native theme
+   * and configuration through the provider.
+   */
+  children: ReactNode;
+
+  /**
+   * Configuration object for the provider
+   *
+   * @description
+   * Contains all configuration options including global text component configuration.
+   *
+   * @example
+   * ```tsx
+   * const config: ForgeDesignConfig = {
+   *   textProps: {
+   *     allowFontScaling: false,
+   *     adjustsFontSizeToFit: false,
+   *     maxFontSizeMultiplier: 1.5
+   *   }
+   * };
+   * ```
+   */
+  config?: ForgeDesignConfig;
+}

package/src/providers/text-component/index.ts

@@ -0,0 +1,2 @@
+export * from './provider';
+export * from './types';

package/src/providers/text-component/provider.tsx

@@ -0,0 +1,7 @@
+import { createContext } from '@cdx-ui/utils';
+import type { TextComponentContextValue } from './types';
+
+const [TextComponentProvider, useTextComponent] =
+  createContext<TextComponentContextValue>('TextComponentContext');
+
+export { TextComponentProvider, useTextComponent };

package/src/providers/text-component/types.ts

@@ -0,0 +1,52 @@
+import type { TextProps } from 'react-native';
+
+/**
+ * Global text component configuration props.
+ * These props are carefully selected to include only those that make sense
+ * to configure globally across all Text components in the application.
+ *
+ * @description
+ * Includes accessibility and font scaling settings that typically
+ * should be consistent throughout the app for better UX.
+ */
+export interface TextComponentProps {
+  /**
+   * Specifies whether fonts should be scaled down automatically to fit given style constraints.
+   *
+   * @default false
+   */
+  adjustsFontSizeToFit?: TextProps['adjustsFontSizeToFit'];
+  /**
+   * Specifies whether fonts should scale to respect Text Size accessibility settings.
+   *
+   * @default true
+   */
+  allowFontScaling?: TextProps['allowFontScaling'];
+  /**
+   * Specifies the largest possible scale a font can reach when `allowFontScaling` is enabled.
+   *
+   * Possible values:
+   *
+   * - `null` or `undefined`: inherit from the parent node or the global default (0)
+   * - `0`: no max, ignore parent/global default
+   * - `>= 1`: sets the `maxFontSizeMultiplier` of this node to this value
+   *
+   * @default `undefined`
+   */
+  maxFontSizeMultiplier?: TextProps['maxFontSizeMultiplier'];
+  /**
+   * Specifies the smallest possible scale a font can reach when adjustsFontSizeToFit is enabled. (values 0.01-1.0).
+   *
+   * iOS only
+   *
+   * @default `undefined`
+   */
+  minimumFontScale?: TextProps['minimumFontScale'];
+}
+
+/**
+ * Context value for text component configuration
+ */
+export interface TextComponentContextValue {
+  textProps?: TextComponentProps;
+}

package/src/providers/toast/index.ts

@@ -0,0 +1,4 @@
+export { ToastProvider, useToast } from './provider';
+export { useToastConfig } from './toast-config.context';
+export { useToastLifecycle } from './lifecycle.context';
+export type * from './types';

package/src/providers/toast/insets-container.tsx

@@ -0,0 +1,233 @@
+import type { ReactNode } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef } from 'react';
+import { Platform, View } from 'react-native';
+import { SafeAreaInsetsContext, type EdgeInsets } from 'react-native-safe-area-context';
+import { FullWindowOverlay, NOTIFICATION_OVERLAY_Z_INDEX } from '@cdx-ui/primitives';
+import type { ToastInsets } from './types';
+
+const ZERO_INSETS: EdgeInsets = { top: 0, bottom: 0, left: 0, right: 0 };
+
+interface InsetsContainerProps {
+  /**
+   * When true, uses a regular View instead of FullWindowOverlay on iOS.
+   * Enables element inspector but toasts won't appear above native modals.
+   * @default false
+   */
+  disableFullWindowOverlay: boolean;
+  /**
+   * Controls whether VoiceOver treats the overlay window as a modal container.
+   * When `false`, VoiceOver can still access elements behind the overlay.
+   * When `true`, VoiceOver is restricted to elements inside the overlay.
+   * @default false
+   * @platform ios
+   * @unstable This prop maps directly to the native `accessibilityViewIsModal`
+   * on the container view and may change in a future react-native-screens release.
+   */
+  unstable_accessibilityContainerViewIsModal?: boolean;
+  /**
+   * Optional inset values for all edges
+   * If not provided, defaults to platform-specific values:
+   * - iOS: safe area insets + 0px (top), + 6px (bottom), + 12px (left/right)
+   * - Android: safe area insets + 12px (all edges)
+   */
+  insets?: ToastInsets;
+  /**
+   * Accessible label for the toast notification region on web.
+   * @default 'Notifications'
+   * @platform web
+   */
+  announceLabel?: string;
+  /**
+   * Custom wrapper function to wrap the toast content
+   * Receives children and should return a component that wraps them
+   * The wrapper should apply flex: 1 (via className or style) to ensure proper layout
+   * Can be any component wrapper - KeyboardAvoidingView, View, or any custom component
+   */
+  contentWrapper?: (children: ReactNode) => React.ReactElement;
+  /**
+   * Pause all auto-dismiss timers (WCAG 2.2.1).
+   */
+  pauseAll: () => void;
+  /**
+   * Resume all auto-dismiss timers.
+   */
+  resumeAll: () => void;
+  /**
+   * Hide the front-most toast. Used by the Escape key handler on web.
+   */
+  hide: () => void;
+  /**
+   * Children to render inside the container
+   */
+  children: ReactNode;
+}
+
+/**
+ * Container component that applies inset padding to position toasts
+ * away from screen edges and safe areas
+ *
+ * Combines custom insets with safe area insets:
+ * - If custom inset is provided, it overrides safe area + default padding
+ * - If not provided, uses platform-specific defaults:
+ *   - iOS: safe area inset + 0px for top, + 6px for bottom, + 12px for left/right
+ *   - Android: safe area inset + 12px for all edges
+ *
+ * On web, wires pointer/focus/visibility listeners to pause/resume timers
+ * per WCAG 2.2.1 (keyboard/pointer/hidden-tab pausing).
+ */
+export function InsetsContainer({
+  insets,
+  announceLabel = 'Notifications',
+  contentWrapper,
+  children,
+  disableFullWindowOverlay,
+  unstable_accessibilityContainerViewIsModal,
+  pauseAll,
+  resumeAll,
+  hide,
+}: Readonly<InsetsContainerProps>) {
+  const safeAreaInsets = useContext(SafeAreaInsetsContext) ?? ZERO_INSETS;
+
+  const finalInsets = useMemo(() => {
+    return {
+      top: insets?.top ?? safeAreaInsets.top + (Platform.OS === 'ios' ? 0 : 12),
+      bottom: insets?.bottom ?? safeAreaInsets.bottom + (Platform.OS === 'ios' ? 6 : 12),
+      left: insets?.left ?? safeAreaInsets.left + 12,
+      right: insets?.right ?? safeAreaInsets.right + 12,
+    };
+  }, [safeAreaInsets, insets]);
+
+  // Track pause sources independently so overlapping pointer + focus
+  // don't accidentally resume while the other source is still active.
+  const pauseSourcesRef = useRef<Set<string>>(new Set());
+  const pauseAllRef = useRef(pauseAll);
+  const resumeAllRef = useRef(resumeAll);
+  pauseAllRef.current = pauseAll;
+  resumeAllRef.current = resumeAll;
+
+  const addPauseSource = useCallback((source: string) => {
+    const wasEmpty = pauseSourcesRef.current.size === 0;
+    pauseSourcesRef.current.add(source);
+    if (wasEmpty) pauseAllRef.current();
+  }, []);
+
+  const removePauseSource = useCallback((source: string) => {
+    pauseSourcesRef.current.delete(source);
+    if (pauseSourcesRef.current.size === 0) resumeAllRef.current();
+  }, []);
+
+  // Ref for the container so we can attach native DOM listeners on web.
+  const containerRef = useRef<View | null>(null);
+  const hideRef = useRef(hide);
+  hideRef.current = hide;
+
+  // Web-only: attach pointer, focus, visibility, and keyboard listeners
+  // via native DOM APIs to avoid RNW making the container focusable
+  // (RNW adds tabIndex when React onFocus/onBlur handlers are present).
+  useEffect(() => {
+    if (Platform.OS !== 'web') return;
+
+    const node = containerRef.current as unknown as HTMLElement | null;
+    const sources = pauseSourcesRef.current;
+
+    const handleVisibilityChange = () => {
+      if (document.hidden) {
+        addPauseSource('visibility');
+      } else {
+        removePauseSource('visibility');
+      }
+    };
+
+    // The container is `absolute inset-0` (full viewport). Using
+    // pointerenter/pointerleave here would pause as soon as the cursor
+    // is anywhere on the page — far too aggressive.  Instead use
+    // pointerover/pointerout (which bubble) and gate on whether the
+    // pointer is actually over a toast element (identified by the
+    // `data-state` attribute emitted on every toast wrapper).
+    const isInsideToast = (el: EventTarget | null): boolean => {
+      if (!el || !(el instanceof HTMLElement)) return false;
+      return !!el.closest('[data-state]');
+    };
+
+    const handlePointerOver = (e: PointerEvent) => {
+      if (isInsideToast(e.target)) addPauseSource('pointer');
+    };
+    const handlePointerOut = (e: PointerEvent) => {
+      if (!isInsideToast(e.relatedTarget)) removePauseSource('pointer');
+    };
+
+    const handleFocusIn = (e: FocusEvent) => {
+      if (isInsideToast(e.target)) addPauseSource('focus');
+    };
+    const handleFocusOut = (e: FocusEvent) => {
+      if (!isInsideToast(e.relatedTarget)) removePauseSource('focus');
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.stopPropagation();
+        hideRef.current();
+      }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    if (node && typeof node.addEventListener === 'function') {
+      node.addEventListener('pointerover', handlePointerOver);
+      node.addEventListener('pointerout', handlePointerOut);
+      node.addEventListener('focusin', handleFocusIn);
+      node.addEventListener('focusout', handleFocusOut);
+      node.addEventListener('keydown', handleKeyDown);
+    }
+
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+      if (node && typeof node.removeEventListener === 'function') {
+        node.removeEventListener('pointerover', handlePointerOver);
+        node.removeEventListener('pointerout', handlePointerOut);
+        node.removeEventListener('focusin', handleFocusIn);
+        node.removeEventListener('focusout', handleFocusOut);
+        node.removeEventListener('keydown', handleKeyDown);
+      }
+      if (sources.size > 0) {
+        sources.clear();
+        resumeAllRef.current();
+      }
+    };
+  }, [addPauseSource, removePauseSource]);
+
+  const content = (
+    <View
+      ref={containerRef}
+      className="absolute web:fixed inset-0 pointer-events-box-none"
+      role="region"
+      aria-label={announceLabel}
+      {...(Platform.OS === 'web' && {
+        'aria-live': 'polite',
+        'aria-atomic': false,
+      })}
+      style={{
+        ...(Platform.OS === 'web' ? { zIndex: NOTIFICATION_OVERLAY_Z_INDEX } : {}),
+        paddingTop: finalInsets.top,
+        paddingBottom: finalInsets.bottom,
+        paddingLeft: finalInsets.left,
+        paddingRight: finalInsets.right,
+      }}
+    >
+      {contentWrapper ? contentWrapper(children) : children}
+    </View>
+  );
+
+  if (Platform.OS !== 'ios') {
+    return content;
+  }
+
+  return (
+    <FullWindowOverlay
+      disableFullWindowOverlay={disableFullWindowOverlay}
+      unstable_accessibilityContainerViewIsModal={unstable_accessibilityContainerViewIsModal}
+    >
+      {content}
+    </FullWindowOverlay>
+  );
+}

package/src/providers/toast/lifecycle.context.tsx

@@ -0,0 +1,37 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Internal context that exposes the pending-removal lifecycle for web toasts.
+ *
+ * Web toasts stay mounted after `hide()` is dispatched so the CSS exit
+ * transition can play. The toast component reads `pendingRemovalIds` to
+ * flip its `data-state="closed"` attribute and calls `remove(id)` when
+ * the CSS transition completes (or a safety timeout fires).
+ *
+ * On native this context is provided but effectively unused — Reanimated's
+ * `exiting` layout animation plays before unmount, so nothing lingers.
+ *
+ * @internal
+ */
+export interface ToastLifecycleContextValue {
+  /** Force-remove a toast from the array once its exit transition has played. */
+  remove: (id: string) => void;
+  /** IDs of toasts that have been marked closed but are still mounted. */
+  pendingRemovalIds: ReadonlySet<string>;
+  /** IDs of the front-most non-pending toast in each placement stack. */
+  frontmostIds: ReadonlySet<string>;
+}
+
+export const ToastLifecycleContext = createContext<ToastLifecycleContextValue | null>(null);
+
+/**
+ * Access the toast lifecycle context.
+ *
+ * Returns `null` when the styled Toast is rendered outside a `ToastProvider`
+ * (e.g. in isolated unit tests) so callers must handle the null case.
+ *
+ * @internal
+ */
+export function useToastLifecycle(): ToastLifecycleContextValue | null {
+  return useContext(ToastLifecycleContext);
+}