@cdx-ui/components 0.0.1-beta.6 → 0.0.1-beta.61

package/src/metro/withForgeMetroConfig.ts

@@ -0,0 +1,29 @@
+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 {
+  return withUniwindConfig(config, {
+    cssEntryFile: options.cssEntryFile,
+    dtsFile: options.generatedTypesFile,
+  }) 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/styles/primitives.ts

@@ -1,38 +1,67 @@
 // packages/components/src/styles/primitives.ts
-// Semantic constants for CDX UI component styling.
+// Semantic constants for Forge UI component styling.
 
 // ─── Colors ──────────────────────────────────────────────
 // Surface & background
+/** @deprecated Use `bg-surface-primary` (--color-surface-primary) instead. */
 export const COLOR_BG_PRIMARY = 'bg-white';
+/** @deprecated Use `bg-surface-secondary` (--color-surface-secondary) instead. */
 export const COLOR_BG_SUBTLE = 'bg-slate-50';
+/** @deprecated Use `bg-surface-neutral-subtle` (--color-surface-neutral-subtle) instead. */
 export const COLOR_BG_MUTED = 'bg-slate-100';
+/** @deprecated Use `bg-base-950` (--color-base-950) instead. */
 export const COLOR_BG_INVERSE = 'bg-slate-900';
 
 // Border
+/** @deprecated Use `border-stroke-secondary` (--color-stroke-secondary) instead. */
 export const COLOR_BORDER_DEFAULT = 'border-slate-200';
+/** @deprecated Use `border-stroke-hover` (--color-stroke-hover) instead. */
 export const COLOR_BORDER_STRONG = 'border-slate-300';
+/** @deprecated Use `border-stroke-focus` (--color-stroke-focus) instead. */
 export const COLOR_BORDER_FOCUS = 'border-slate-900';
+/** @deprecated Use `border-stroke-danger` (--color-stroke-danger) instead. */
 export const COLOR_BORDER_INVALID = 'border-red-500';
 
 // Text
+/** @deprecated Use `text-content-primary` (--color-content-primary) instead. */
 export const COLOR_TEXT_PRIMARY = 'text-slate-900';
+/** @deprecated Use `text-content-secondary` (--color-content-secondary) instead. */
 export const COLOR_TEXT_SECONDARY = 'text-slate-500';
+/** @deprecated Use `text-content-tertiary` (--color-content-tertiary) instead. */
 export const COLOR_TEXT_MUTED = 'text-slate-400';
+/** @deprecated Use the appropriate `text-content-*-on-strong` token for the surface color, e.g. `text-content-action-on-strong` (--color-content-action-on-strong). */
 export const COLOR_TEXT_INVERSE = 'text-white';
+/** @deprecated Use `text-content-tertiary` (--color-content-tertiary) instead. */
 export const COLOR_TEXT_PLACEHOLDER = 'text-slate-400';
+/** @deprecated Use `text-content-danger` (--color-content-danger) instead. */
 export const COLOR_TEXT_INVALID = 'text-red-600';
 
 // Brand / Action
+/** @deprecated Use `bg-surface-action-strong` (--color-surface-action-strong) instead. */
 export const COLOR_BRAND_DEFAULT = 'bg-slate-900';
+/** @deprecated Use `bg-surface-action-strong-hover` (--color-surface-action-strong-hover) instead. */
 export const COLOR_BRAND_HOVER = 'bg-slate-800';
+/** @deprecated Use `bg-surface-action-strong-active` (--color-surface-action-strong-active) instead. */
 export const COLOR_BRAND_ACTIVE = 'bg-slate-700';
 
 // Accent (for checked states, active indicators)
+/** @deprecated Use `bg-surface-action-strong` (--color-surface-action-strong) instead. */
 export const COLOR_ACCENT_DEFAULT = 'bg-slate-900';
+/** @deprecated Use `border-stroke-action` (--color-stroke-action) instead. */
 export const COLOR_ACCENT_BORDER = 'border-slate-900';
 
-// Semantic colors (danger, warning, success, info)
-// Kept for Button's 5-color system
+/**
+ * @deprecated Use semantic token classes directly instead. Map each color key to its
+ * corresponding `--color-surface-*`, `--color-stroke-*`, and `--color-content-*` tokens:
+ * - `bg` → `bg-surface-{color}-strong` (--color-surface-{color}-strong)
+ * - `bgHover` → `bg-surface-{color}-strong-hover` (--color-surface-{color}-strong-hover)
+ * - `bgActive` → `bg-surface-{color}-strong-active` (--color-surface-{color}-strong-active)
+ * - `border` → `border-stroke-{color}` (--color-stroke-{color})
+ * - `text` → `text-content-{color}` (--color-content-{color})
+ * - `ring` → `ring-[--color-stroke-focus]` (--color-stroke-focus)
+ *
+ * See Button/styles.ts for a complete migration example.
+ */
 export const SEMANTIC_COLORS = {
   action: {
     bg: 'bg-slate-900',
@@ -77,21 +106,29 @@ export const SEMANTIC_COLORS = {
 } as const;
 
 // ─── Focus ───────────────────────────────────────────────
+/** @deprecated Use `ring-2 ring-[--color-stroke-focus] ring-offset-2` (--color-stroke-focus) instead. */
 export const FOCUS_RING = 'ring-2 ring-slate-400/50 ring-offset-2';
 
 // ─── Radius ──────────────────────────────────────────────
-export const RADIUS_SM = 'rounded-lg'; // buttons, inputs, checkboxes
-export const RADIUS_MD = 'rounded-xl'; // cards, dropdowns, modals
-export const RADIUS_FULL = 'rounded-full'; // pills, avatars, switches
+/** @deprecated Use `rounded-[var(--border-radius-button)]` for buttons/inputs or `rounded-[var(--border-radius-default)]` for containers. */
+export const RADIUS_SM = 'rounded-lg';
+/** @deprecated Use `rounded-[var(--border-radius-default)]` for cards/containers. */
+export const RADIUS_MD = 'rounded-xl';
+/** @deprecated Use `rounded-[var(--border-radius-round)]` for circular elements (icon buttons, radio, pills). */
+export const RADIUS_FULL = 'rounded-full';
 
 // ─── Shadows ─────────────────────────────────────────────
+
+/** @deprecated Use `shadow-sm` directly instead */
 export const SHADOW_SM = 'shadow-sm';
+/** @deprecated Use `shadow-md` directly instead */
 export const SHADOW_MD = 'shadow-md';
 
 // ─── Sizing ──────────────────────────────────────────────
 // Unified size scale for interactive/form components (Button, Input, Select, Checkbox).
 // Only two sizes: 'default' (regular) and 'small' (compact).
 // NOTE: Text and Heading use a separate typography scale (xs/sm/md/lg/xl) — not this.
+/** @deprecated */
 export const SIZE_SCALE = {
   default: { height: 'h-10', px: 'px-4', gap: 'gap-2', text: 'text-base' },
   small: { height: 'h-8', px: 'px-3', gap: 'gap-1.5', text: 'text-sm' },