@cdx-ui/components 0.0.1-beta.14 → 0.0.1-beta.140

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,232 @@
+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 } 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 inset-0 pointer-events-box-none"
+      role="region"
+      aria-label={announceLabel}
+      {...(Platform.OS === 'web' && {
+        'aria-live': 'polite',
+        'aria-atomic': false,
+      })}
+      style={{
+        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>;
+  /** ID of the front-most (last non-pending) toast, or null if none. */
+  frontmostId: string | null;
+}
+
+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);
+}