@cdx-ui/components 0.0.1-beta.8 → 0.0.1-beta.80

package/src/metro/withForgeMetroConfig.ts

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import type { MetroConfig } from 'metro-config';
+import { withUniwindConfig } from 'uniwind/metro';
+
+export interface ForgeMetroConfigOptions {
+  /** Path to the CSS entry file (e.g., `'./global.css'`). */
+  cssEntryFile: string;
+  /** Path where generated Tailwind class type definitions are written. */
+  generatedTypesFile?: string;
+}
+
+/**
+ * Wraps a Metro config with Forge UI's styling-layer configuration.
+ *
+ * Today this delegates to Uniwind. If the styling layer is swapped (see
+ * `docs/research/uniwind-to-nativewind-contingency.md`), only the internals
+ * of this function change — consuming Metro configs stay the same.
+ *
+ * Must be the **outermost** Metro config wrapper (after any other wrappers
+ * like `withStorybook`).
+ */
+export function withForgeMetroConfig<T extends MetroConfig>(
+  config: T,
+  options: ForgeMetroConfigOptions,
+): T {
+  const withUniwind = withUniwindConfig(config, {
+    cssEntryFile: options.cssEntryFile,
+    dtsFile: options.generatedTypesFile,
+  }) as T;
+
+  return withUniwindMultiCopyFix(withUniwind);
+}
+
+/**
+ * Fixes Uniwind 1.9's nativeResolver in pnpm monorepos with multiple Uniwind copies.
+ *
+ * Uniwind decides whether to wrap a `react-native` import by comparing
+ * `originModulePath` against a cached internal base path resolved via
+ * `require.resolve('uniwind/package.json')`. In pnpm, the Metro config loaded
+ * by Node and the Uniwind copy bundled for the app may resolve to different
+ * physical paths (different peer-dep hashes in the virtual store), so the
+ * `isInternal` check returns false for Uniwind-internal code. The
+ * nativeResolver then re-routes `react-native` to `uniwind/components`, which
+ * re-exports from `react-native` — a circular `get NativeModules` getter that
+ * overflows the stack at runtime.
+ *
+ * Fix: intercept `react-native` requests originating from inside any Uniwind
+ * copy and resolve them from the app's `projectRoot`, bypassing the broken
+ * `isInternal` check entirely.
+ */
+function withUniwindMultiCopyFix<T extends MetroConfig>(config: T): T {
+  const resolver = config.resolver;
+  if (!resolver) return config;
+
+  const innerResolveRequest = resolver.resolveRequest;
+  const uniwindPathFragment = `${path.sep}node_modules${path.sep}uniwind${path.sep}`;
+  const projectRoot = config.projectRoot;
+  const appOriginModulePath = projectRoot ? path.join(projectRoot, 'package.json') : undefined;
+
+  return {
+    ...config,
+    resolver: {
+      ...resolver,
+      resolveRequest: (context, moduleName, platform) => {
+        const fromUniwind = context.originModulePath?.includes(uniwindPathFragment) ?? false;
+        if (
+          fromUniwind &&
+          (moduleName === 'react-native' || moduleName.startsWith('react-native/'))
+        ) {
+          const rewrittenContext = appOriginModulePath
+            ? { ...context, originModulePath: appOriginModulePath }
+            : context;
+          return context.resolveRequest(rewrittenContext, moduleName, platform);
+        }
+        if (innerResolveRequest) {
+          return innerResolveRequest(context, moduleName, platform);
+        }
+        return context.resolveRequest(context, moduleName, platform);
+      },
+    },
+  } as T;
+}

package/src/navigation/forgeTabIcon.native.ts

@@ -0,0 +1,36 @@
+import type { ForgeTabIcon } from '@cdx-ui/icons/tab-icons';
+import type { ForgeNativeBottomTabIcon, ForgeTabBarIcon } from './types';
+
+/**
+ * forgeTabIcon — iOS/Android implementation (see `forgeTabIcon.ts` for the
+ * full contract and usage example).
+ *
+ * Returns a `tabBarIcon` function for `createNativeBottomTabNavigator` that
+ * resolves the descriptor's pre-rasterized template PNGs: outlined at rest,
+ * filled when focused (iOS only — Android tabs use one static icon and
+ * express selection via tint). `tinted: true` makes the native tab bar apply
+ * `tabBarActiveTintColor` / `tabBarInactiveTintColor` at runtime, so theming
+ * and dark mode flow through `useForgeBottomTabScreenOptions` unchanged.
+ */
+export function forgeTabIcon(icon: ForgeTabIcon): ForgeTabBarIcon {
+  const { native } = icon;
+
+  if (!native) {
+    const name = icon.Component.displayName ?? 'icon';
+    throw new Error(
+      `forgeTabIcon: "${name}" has no native tab assets. Use a generated ` +
+        `descriptor from '@cdx-ui/icons/tab-icons' (curated in the icon ` +
+        `package's tab-icons.config.json), or pass a descriptor with your ` +
+        `own template PNGs: { native: { outlined: require(...), filled: ` +
+        `require(...) } } at a 24dp base size with @2x/@3x variants.`,
+    );
+  }
+
+  const resolve = ({ focused }: { focused: boolean }): ForgeNativeBottomTabIcon => ({
+    type: 'image',
+    source: focused ? native.filled : native.outlined,
+    tinted: true,
+  });
+
+  return resolve as ForgeTabBarIcon;
+}

package/src/navigation/forgeTabIcon.ts

@@ -0,0 +1,33 @@
+import { createElement } from 'react';
+import type { ForgeTabIcon } from '@cdx-ui/icons/tab-icons';
+import type { ForgeTabBarIcon } from './types';
+
+/**
+ * forgeTabIcon — web/JS-navigator implementation.
+ *
+ * Maps a {@link ForgeTabIcon} descriptor to a React Navigation `tabBarIcon`
+ * value that renders the same Forge UI icon on every platform:
+ *
+ * - **Web** (`createBottomTabNavigator`): renders the SVG icon component with
+ *   `filled={focused}` and the navigator-supplied `color`/`size` — pair with
+ *   `useForgeBottomTabScreenOptions` so tints come from design tokens.
+ * - **iOS/Android** (`createNativeBottomTabNavigator`): the `.native` module
+ *   of this file returns a tinted template-image descriptor instead.
+ *
+ * ```tsx
+ * import { useForgeBottomTabScreenOptions, forgeTabIcon } from '@cdx-ui/components';
+ * import { HomeTabIcon } from '@cdx-ui/icons/tab-icons';
+ *
+ * <Tab.Screen
+ *   name="Home"
+ *   component={HomeScreen}
+ *   options={{ title: 'Home', tabBarIcon: forgeTabIcon(HomeTabIcon) }}
+ * />
+ * ```
+ */
+export function forgeTabIcon(icon: ForgeTabIcon): ForgeTabBarIcon {
+  const render = ({ focused, color, size }: { focused: boolean; color: string; size: number }) =>
+    createElement(icon.Component, { filled: focused, color, size });
+
+  return render as ForgeTabBarIcon;
+}

package/src/navigation/index.ts

@@ -0,0 +1,3 @@
+export { forgeTabIcon } from './forgeTabIcon';
+export type { ForgeNativeBottomTabIcon, ForgeTabBarIcon } from './types';
+export type { ForgeTabIcon, ForgeTabIconNativeSources } from '@cdx-ui/icons/tab-icons';

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,61 @@
+import React from 'react';
+import { SafeAreaListener } from 'react-native-safe-area-context';
+import { Uniwind } from 'uniwind';
+import { PortalHost } 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;
+
+  // 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);
+      }}
+    >
+      <GlobalAnimationSettingsProvider animation={animation}>
+        <TextComponentProvider value={{ textProps }}>
+          {isToastEnabled ? (
+            <ToastProvider {...toastProps}>
+              {children}
+              <PortalHost />
+            </ToastProvider>
+          ) : (
+            <>
+              {children}
+              <PortalHost />
+            </>
+          )}
+        </TextComponentProvider>
+      </GlobalAnimationSettingsProvider>
+    </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';