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

package/lib/commonjs/hooks/index.js

@@ -0,0 +1,19 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "mergeForgeBottomTabScreenOptions", {
+  enumerable: true,
+  get: function () {
+    return _useForgeBottomTabScreenOptions.mergeForgeBottomTabScreenOptions;
+  }
+});
+Object.defineProperty(exports, "useForgeBottomTabScreenOptions", {
+  enumerable: true,
+  get: function () {
+    return _useForgeBottomTabScreenOptions.useForgeBottomTabScreenOptions;
+  }
+});
+var _useForgeBottomTabScreenOptions = require("./useForgeBottomTabScreenOptions");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_useForgeBottomTabScreenOptions","require"],"sourceRoot":"../../../src","sources":["hooks/index.ts"],"mappings":";;;;;;;;;;;;;;;;;AAAA,IAAAA,+BAAA,GAAAC,OAAA","ignoreList":[]}

package/lib/commonjs/hooks/useForgeBottomTabScreenOptions.js

@@ -0,0 +1,246 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.mergeForgeBottomTabScreenOptions = mergeForgeBottomTabScreenOptions;
+exports.useForgeBottomTabScreenOptions = useForgeBottomTabScreenOptions;
+var _uniwind = require("uniwind");
+/**
+ * useForgeBottomTabScreenOptions
+ *
+ * Returns a `screenOptions` object for **React Navigation bottom tab navigators**
+ * (`@react-navigation/bottom-tabs` v7+), populated with CDX UI design-system
+ * token values.
+ *
+ * CDX UI does not import `@react-navigation` — the consumer passes the returned
+ * object to their own navigator. This keeps the dependency out of
+ * `@cdx-ui/components` and works with any React Navigation tab variant:
+ * `createNativeBottomTabNavigator` (iOS/Android) or `createBottomTabNavigator`
+ * (web/JS).
+ *
+ * **Not compatible with:**
+ * - Expo Router `<NativeTabs>` — uses different prop names
+ * - React Router or DOM tab components — these are not React Navigation
+ *
+ * ## Basic usage
+ *
+ * ```tsx
+ * import { useForgeBottomTabScreenOptions } from '@cdx-ui/components';
+ * import { createNativeBottomTabNavigator } from '@react-navigation/bottom-tabs/unstable';
+ *
+ * const Tab = createNativeBottomTabNavigator<AppTabs>();
+ *
+ * function AppTabs() {
+ *   const screenOptions = useForgeBottomTabScreenOptions();
+ *   return (
+ *     <Tab.Navigator screenOptions={screenOptions}>
+ *       <Tab.Screen name="Home" component={HomeScreen} />
+ *     </Tab.Navigator>
+ *   );
+ * }
+ * ```
+ *
+ * ## Overriding individual tokens
+ *
+ * Spread the returned object and override only the keys you need.
+ * Nested style objects (`tabBarLabelStyle`, `tabBarStyle`, `tabBarBadgeStyle`)
+ * must be spread individually to preserve unrelated DS defaults:
+ *
+ * ```tsx
+ * const dsOptions = useForgeBottomTabScreenOptions();
+ * const screenOptions = {
+ *   ...dsOptions,
+ *   tabBarActiveTintColor: '#custom',
+ *   tabBarLabelStyle: { ...dsOptions.tabBarLabelStyle, fontFamily: 'MyFont' },
+ * };
+ * ```
+ *
+ * ## Token variable names
+ *
+ * | screenOption                       | CSS variable                       |
+ * | ---------------------------------- | ---------------------------------- |
+ * | tabBarActiveTintColor              | --color-content-action             |
+ * | tabBarInactiveTintColor            | --color-content-secondary          |
+ * | tabBarStyle.backgroundColor        | --color-surface-primary            |
+ * | tabBarLabelStyle.fontFamily        | --font-body                        |
+ * | tabBarLabelStyle.fontSize          | --text-xs (via `text-xs` class)    |
+ * | tabBarLabelStyle.fontWeight        | --font-weight-medium               |
+ * | tabBarBadgeStyle.backgroundColor   | --color-surface-danger-strong      |
+ *
+ * ## Platform notes
+ *
+ * - `tabBarInactiveTintColor` has no effect on iOS — inactive items always use
+ *   system grey.
+ * - `tabBarStyle.backgroundColor` is ignored on iOS 26+ (liquid glass takes
+ *   over). It is honoured on iOS ≤18 and all Android versions.
+ * - The hook resolves CSS variables via Uniwind's `useCSSVariable`. If the
+ *   Uniwind runtime is not set up (e.g. in a plain Jest test without a CSS
+ *   context), each variable resolves to `undefined` and the hardcoded fallback
+ *   is used instead — fallbacks intentionally match the CDX UI light-theme
+ *   values.
+ * - `tabBarLabelStyle.fontSize` is resolved via Uniwind's
+ *   `useResolveClassNames('text-xs')` rather than reading the rem-valued
+ *   `--text-xs` variable directly. React Navigation v7 requires a numeric
+ *   `fontSize`, and letting Uniwind resolve the class means the rem→px
+ *   conversion uses the consumer's configured rem base (default 16px,
+ *   overridable via the `polyfills.rem` Metro option) instead of a constant
+ *   hardcoded here.
+ */
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * The `screenOptions` shape returned by `useForgeBottomTabScreenOptions`.
+ *
+ * These are concrete types (not the broad `StyleProp<…>` React Navigation
+ * uses internally) so consumers get precise IDE completion. The compile-time
+ * drift guard below ensures this type stays assignable to
+ * `BottomTabNavigationOptions` — the TypeScript compiler will error if CDX UI
+ * adds a key or value that React Navigation no longer accepts.
+ *
+ * Pass directly as `screenOptions` on a `createNativeBottomTabNavigator` or
+ * `createBottomTabNavigator` navigator, or spread and override individual keys.
+ */
+
+/**
+ * Compile-time drift guard.
+ *
+ * `ForgeReactNavigationBottomTabScreenOptions` must be assignable to
+ * `BottomTabNavigationOptions`. TypeScript checks this assignment at build
+ * time — if React Navigation removes or incompatibly narrows one of our keys,
+ * this line becomes a type error before it reaches consumers.
+ *
+ * The `null as unknown as ...` cast keeps the runtime value `null` so tree-
+ * shakers eliminate the variable from the final bundle entirely.
+ */
+
+const _rnDriftGuard =
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+null;
+
+// ── Fallbacks ────────────────────────────────────────────────────────────────
+//
+// Resolved light-theme values for each token. Used when useCSSVariable returns
+// undefined (no Uniwind CSS context in scope, e.g. Jest).
+
+const FALLBACKS = {
+  activeTintColor: '#346099',
+  // --color-brand-700 (--color-content-action)
+  inactiveTintColor: '#4a4c4f',
+  // --color-base-800  (--color-content-secondary)
+  fontFamily: 'Inter',
+  // --font-sans           (--font-body)
+  fontSize: 12,
+  // px                    (--text-xs)
+  fontWeight: '500',
+  // (--font-weight-medium)
+  backgroundColor: '#ffffff',
+  // --color-white         (--color-surface-primary)
+  badgeBackgroundColor: '#c10007' // --color-red-700       (--color-surface-danger-strong)
+};
+
+/**
+ * Coerces a Uniwind-resolved `fontSize` to a finite pixel number, falling
+ * back when the style could not be resolved (e.g. no Uniwind runtime in Jest).
+ *
+ * `useResolveClassNames('text-xs')` performs the rem→px conversion using
+ * Uniwind's configured rem base, so the value is already numeric on native.
+ * React Native Web may surface string values; unit-less and `px` strings are
+ * accepted, but anything else (`rem`, `em`, `%`) falls back rather than
+ * guessing a rem base here.
+ */
+function toPx(value, fallbackPx) {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : fallbackPx;
+  }
+  if (typeof value !== 'string') return fallbackPx;
+  const trimmed = value.trim();
+  if (!/^-?\d*\.?\d+(px)?$/.test(trimmed)) return fallbackPx;
+  return parseFloat(trimmed);
+}
+
+/**
+ * Coerces a Uniwind `useCSSVariable` fontWeight value to a string.
+ *
+ * `--font-weight-*` variables are emitted as unit-less numbers (e.g. `500`),
+ * and `useCSSVariable` may return them as numbers. React Native's `TextStyle`
+ * accepts numeric fontWeight, but react-native-screens' native bottom tabs
+ * declare the corresponding host prop (`tabBarItemTitleFontWeight`) as a
+ * String — passing a number crashes Android Fabric with
+ * "java.lang.Double cannot be cast to java.lang.String".
+ */
+function toFontWeight(value, fallback) {
+  if (value === undefined) return fallback;
+  return String(value);
+}
+
+// ── Hook ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a `screenOptions` object for **React Navigation bottom tab
+ * navigators** (`@react-navigation/bottom-tabs` v7+), populated with CDX UI
+ * design-system token values.
+ *
+ * Must be called inside a React component or custom hook (React hook rules
+ * apply).
+ */
+/**
+ * Deep-merges consumer overrides into a base `ForgeReactNavigationBottomTabScreenOptions`
+ * object. Nested style objects (`tabBarLabelStyle`, `tabBarStyle`,
+ * `tabBarBadgeStyle`) are merged property-by-property so consumers can override
+ * individual style properties without losing unrelated DS defaults.
+ *
+ * Use with `useForgeBottomTabScreenOptions` to apply targeted overrides:
+ *
+ * ```tsx
+ * const dsOptions = useForgeBottomTabScreenOptions();
+ * const screenOptions = mergeForgeBottomTabScreenOptions(dsOptions, {
+ *   tabBarActiveTintColor: '#custom',
+ *   tabBarLabelStyle: { fontFamily: 'MyFont' }, // fontSize + fontWeight preserved
+ * });
+ * ```
+ */
+function mergeForgeBottomTabScreenOptions(base, overrides) {
+  return {
+    ...base,
+    ...overrides,
+    tabBarLabelStyle: {
+      ...base.tabBarLabelStyle,
+      ...overrides.tabBarLabelStyle
+    },
+    tabBarStyle: {
+      ...base.tabBarStyle,
+      ...overrides.tabBarStyle
+    },
+    tabBarBadgeStyle: {
+      ...base.tabBarBadgeStyle,
+      ...overrides.tabBarBadgeStyle
+    }
+  };
+}
+function useForgeBottomTabScreenOptions() {
+  const activeTintColor = (0, _uniwind.useCSSVariable)('--color-content-action');
+  const inactiveTintColor = (0, _uniwind.useCSSVariable)('--color-content-secondary');
+  const fontFamily = (0, _uniwind.useCSSVariable)('--font-body');
+  const labelTextStyle = (0, _uniwind.useResolveClassNames)('text-xs');
+  const fontWeight = (0, _uniwind.useCSSVariable)('--font-weight-medium');
+  const backgroundColor = (0, _uniwind.useCSSVariable)('--color-surface-primary');
+  const badgeBackgroundColor = (0, _uniwind.useCSSVariable)('--color-surface-danger-strong');
+  return {
+    tabBarActiveTintColor: String(activeTintColor ?? FALLBACKS.activeTintColor),
+    tabBarInactiveTintColor: String(inactiveTintColor ?? FALLBACKS.inactiveTintColor),
+    tabBarStyle: {
+      backgroundColor: String(backgroundColor ?? FALLBACKS.backgroundColor)
+    },
+    tabBarLabelStyle: {
+      fontFamily: String(fontFamily ?? FALLBACKS.fontFamily),
+      fontSize: toPx(labelTextStyle?.fontSize, FALLBACKS.fontSize),
+      fontWeight: toFontWeight(fontWeight, FALLBACKS.fontWeight)
+    },
+    tabBarBadgeStyle: {
+      backgroundColor: String(badgeBackgroundColor ?? FALLBACKS.badgeBackgroundColor)
+    }
+  };
+}
+//# sourceMappingURL=useForgeBottomTabScreenOptions.js.map

package/lib/commonjs/hooks/useForgeBottomTabScreenOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_uniwind","require","_rnDriftGuard","FALLBACKS","activeTintColor","inactiveTintColor","fontFamily","fontSize","fontWeight","backgroundColor","badgeBackgroundColor","toPx","value","fallbackPx","Number","isFinite","trimmed","trim","test","parseFloat","toFontWeight","fallback","undefined","String","mergeForgeBottomTabScreenOptions","base","overrides","tabBarLabelStyle","tabBarStyle","tabBarBadgeStyle","useForgeBottomTabScreenOptions","useCSSVariable","labelTextStyle","useResolveClassNames","tabBarActiveTintColor","tabBarInactiveTintColor"],"sourceRoot":"../../../src","sources":["hooks/useForgeBottomTabScreenOptions.ts"],"mappings":";;;;;;;AAkFA,IAAAA,QAAA,GAAAC,OAAA;AAlFA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAKA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA,MAAMC,aAAyC;AAC7C;AACA,IAAyD;;AAE3D;AACA;AACA;AACA;;AAEA,MAAMC,SAAS,GAAG;EAChBC,eAAe,EAAE,SAAS;EAAE;EAC5BC,iBAAiB,EAAE,SAAS;EAAE;EAC9BC,UAAU,EAAE,OAAO;EAAE;EACrBC,QAAQ,EAAE,EAAE;EAAE;EACdC,UAAU,EAAE,KAAgC;EAAE;EAC9CC,eAAe,EAAE,SAAS;EAAE;EAC5BC,oBAAoB,EAAE,SAAS,CAAE;AACnC,CAAU;;AAEV;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASC,IAAIA,CAACC,KAAkC,EAAEC,UAAkB,EAAU;EAC5E,IAAI,OAAOD,KAAK,KAAK,QAAQ,EAAE;IAC7B,OAAOE,MAAM,CAACC,QAAQ,CAACH,KAAK,CAAC,GAAGA,KAAK,GAAGC,UAAU;EACpD;EACA,IAAI,OAAOD,KAAK,KAAK,QAAQ,EAAE,OAAOC,UAAU;EAChD,MAAMG,OAAO,GAAGJ,KAAK,CAACK,IAAI,CAAC,CAAC;EAC5B,IAAI,CAAC,oBAAoB,CAACC,IAAI,CAACF,OAAO,CAAC,EAAE,OAAOH,UAAU;EAC1D,OAAOM,UAAU,CAACH,OAAO,CAAC;AAC5B;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASI,YAAYA,CACnBR,KAAkC,EAClCS,QAAiC,EACR;EACzB,IAAIT,KAAK,KAAKU,SAAS,EAAE,OAAOD,QAAQ;EACxC,OAAOE,MAAM,CAACX,KAAK,CAAC;AACtB;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASY,gCAAgCA,CAC9CC,IAAgD,EAChDC,SAA8D,EAClB;EAC5C,OAAO;IACL,GAAGD,IAAI;IACP,GAAGC,SAAS;IACZC,gBAAgB,EAAE;MAAE,GAAGF,IAAI,CAACE,gBAAgB;MAAE,GAAGD,SAAS,CAACC;IAAiB,CAAC;IAC7EC,WAAW,EAAE;MAAE,GAAGH,IAAI,CAACG,WAAW;MAAE,GAAGF,SAAS,CAACE;IAAY,CAAC;IAC9DC,gBAAgB,EAAE;MAAE,GAAGJ,IAAI,CAACI,gBAAgB;MAAE,GAAGH,SAAS,CAACG;IAAiB;EAC9E,CAAC;AACH;AAEO,SAASC,8BAA8BA,CAAA,EAA+C;EAC3F,MAAM1B,eAAe,GAAG,IAAA2B,uBAAc,EAAC,wBAAwB,CAAC;EAChE,MAAM1B,iBAAiB,GAAG,IAAA0B,uBAAc,EAAC,2BAA2B,CAAC;EACrE,MAAMzB,UAAU,GAAG,IAAAyB,uBAAc,EAAC,aAAa,CAAC;EAChD,MAAMC,cAAc,GAAG,IAAAC,6BAAoB,EAAC,SAAS,CAAC;EACtD,MAAMzB,UAAU,GAAG,IAAAuB,uBAAc,EAAC,sBAAsB,CAAC;EACzD,MAAMtB,eAAe,GAAG,IAAAsB,uBAAc,EAAC,yBAAyB,CAAC;EACjE,MAAMrB,oBAAoB,GAAG,IAAAqB,uBAAc,EAAC,+BAA+B,CAAC;EAE5E,OAAO;IACLG,qBAAqB,EAAEX,MAAM,CAACnB,eAAe,IAAID,SAAS,CAACC,eAAe,CAAC;IAC3E+B,uBAAuB,EAAEZ,MAAM,CAAClB,iBAAiB,IAAIF,SAAS,CAACE,iBAAiB,CAAC;IACjFuB,WAAW,EAAE;MACXnB,eAAe,EAAEc,MAAM,CAACd,eAAe,IAAIN,SAAS,CAACM,eAAe;IACtE,CAAC;IACDkB,gBAAgB,EAAE;MAChBrB,UAAU,EAAEiB,MAAM,CAACjB,UAAU,IAAIH,SAAS,CAACG,UAAU,CAAC;MACtDC,QAAQ,EAAEI,IAAI,CAACqB,cAAc,EAAEzB,QAAQ,EAAEJ,SAAS,CAACI,QAAQ,CAAC;MAC5DC,UAAU,EAAEY,YAAY,CAACZ,UAAU,EAAEL,SAAS,CAACK,UAAU;IAC3D,CAAC;IACDqB,gBAAgB,EAAE;MAChBpB,eAAe,EAAEc,MAAM,CAACb,oBAAoB,IAAIP,SAAS,CAACO,oBAAoB;IAChF;EACF,CAAC;AACH","ignoreList":[]}

package/lib/commonjs/index.js

@@ -52,6 +52,30 @@ Object.keys(_components).forEach(function (key) {
     }
   });
 });
+var _hooks = require("./hooks");
+Object.keys(_hooks).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _hooks[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _hooks[key];
+    }
+  });
+});
+var _navigation = require("./navigation");
+Object.keys(_navigation).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _navigation[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _navigation[key];
+    }
+  });
+});
 var _reactNative = require("react-native");
 var _reactNativeSafeAreaContext = require("react-native-safe-area-context");
 //# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_components","require","Object","keys","forEach","key","prototype","hasOwnProperty","call","_exportNames","exports","defineProperty","enumerable","get","_reactNative","_reactNativeSafeAreaContext"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,IAAAA,WAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,WAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAL,WAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAb,WAAA,CAAAK,GAAA;IAAA;EAAA;AAAA;AACA,IAAAS,YAAA,GAAAb,OAAA;AACA,IAAAc,2BAAA,GAAAd,OAAA","ignoreList":[]}
+{"version":3,"names":["_components","require","Object","keys","forEach","key","prototype","hasOwnProperty","call","_exportNames","exports","defineProperty","enumerable","get","_hooks","_navigation","_reactNative","_reactNativeSafeAreaContext"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AACA,IAAAA,WAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,WAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAL,WAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAb,WAAA,CAAAK,GAAA;IAAA;EAAA;AAAA;AACA,IAAAS,MAAA,GAAAb,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAW,MAAA,EAAAV,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAS,MAAA,CAAAT,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAC,MAAA,CAAAT,GAAA;IAAA;EAAA;AAAA;AACA,IAAAU,WAAA,GAAAd,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAY,WAAA,EAAAX,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAH,MAAA,CAAAI,SAAA,CAAAC,cAAA,CAAAC,IAAA,CAAAC,YAAA,EAAAJ,GAAA;EAAA,IAAAA,GAAA,IAAAK,OAAA,IAAAA,OAAA,CAAAL,GAAA,MAAAU,WAAA,CAAAV,GAAA;EAAAH,MAAA,CAAAS,cAAA,CAAAD,OAAA,EAAAL,GAAA;IAAAO,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAE,WAAA,CAAAV,GAAA;IAAA;EAAA;AAAA;AACA,IAAAW,YAAA,GAAAf,OAAA;AACA,IAAAgB,2BAAA,GAAAhB,OAAA","ignoreList":[]}

package/lib/commonjs/metro/withCdxMetroConfig.js

@@ -3,22 +3,11 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.withCdxMetroConfig = withCdxMetroConfig;
-var _metro = require("uniwind/metro");
-/**
- * Wraps a Metro config with CDX 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`).
- */
-function withCdxMetroConfig(config, options) {
-  return (0, _metro.withUniwindConfig)(config, {
-    cssEntryFile: options.cssEntryFile,
-    dtsFile: options.generatedTypesFile
-  });
-}
+Object.defineProperty(exports, "withCdxMetroConfig", {
+  enumerable: true,
+  get: function () {
+    return _withForgeMetroConfig.withForgeMetroConfig;
+  }
+});
+var _withForgeMetroConfig = require("./withForgeMetroConfig");
 //# sourceMappingURL=withCdxMetroConfig.js.map

package/lib/commonjs/metro/withCdxMetroConfig.js.map

@@ -1 +1 @@
-{"version":3,"names":["_metro","require","withCdxMetroConfig","config","options","withUniwindConfig","cssEntryFile","dtsFile","generatedTypesFile"],"sourceRoot":"../../../src","sources":["metro/withCdxMetroConfig.ts"],"mappings":";;;;;;AACA,IAAAA,MAAA,GAAAC,OAAA;AASA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,kBAAkBA,CAChCC,MAAS,EACTC,OAA8B,EAC3B;EACH,OAAO,IAAAC,wBAAiB,EAACF,MAAM,EAAE;IAC/BG,YAAY,EAAEF,OAAO,CAACE,YAAY;IAClCC,OAAO,EAAEH,OAAO,CAACI;EACnB,CAAC,CAAC;AACJ","ignoreList":[]}
+{"version":3,"names":["_withForgeMetroConfig","require"],"sourceRoot":"../../../src","sources":["metro/withCdxMetroConfig.ts"],"mappings":";;;;;;;;;;;AACA,IAAAA,qBAAA,GAAAC,OAAA","ignoreList":[]}

package/lib/commonjs/metro/withForgeMetroConfig.js

@@ -0,0 +1,24 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.withForgeMetroConfig = withForgeMetroConfig;
+var _metro = require("uniwind/metro");
+/**
+ * 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`).
+ */
+function withForgeMetroConfig(config, options) {
+  return (0, _metro.withUniwindConfig)(config, {
+    cssEntryFile: options.cssEntryFile,
+    dtsFile: options.generatedTypesFile
+  });
+}
+//# sourceMappingURL=withForgeMetroConfig.js.map

package/lib/commonjs/metro/withForgeMetroConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_metro","require","withForgeMetroConfig","config","options","withUniwindConfig","cssEntryFile","dtsFile","generatedTypesFile"],"sourceRoot":"../../../src","sources":["metro/withForgeMetroConfig.ts"],"mappings":";;;;;;AACA,IAAAA,MAAA,GAAAC,OAAA;AASA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,oBAAoBA,CAClCC,MAAS,EACTC,OAAgC,EAC7B;EACH,OAAO,IAAAC,wBAAiB,EAACF,MAAM,EAAE;IAC/BG,YAAY,EAAEF,OAAO,CAACE,YAAY;IAClCC,OAAO,EAAEH,OAAO,CAACI;EACnB,CAAC,CAAC;AACJ","ignoreList":[]}

package/lib/commonjs/navigation/forgeTabIcon.js

@@ -0,0 +1,43 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.forgeTabIcon = forgeTabIcon;
+var _react = require("react");
+/**
+ * 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) }}
+ * />
+ * ```
+ */
+function forgeTabIcon(icon) {
+  const render = ({
+    focused,
+    color,
+    size
+  }) => /*#__PURE__*/(0, _react.createElement)(icon.Component, {
+    filled: focused,
+    color,
+    size
+  });
+  return render;
+}
+//# sourceMappingURL=forgeTabIcon.js.map

package/lib/commonjs/navigation/forgeTabIcon.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_react","require","forgeTabIcon","icon","render","focused","color","size","createElement","Component","filled"],"sourceRoot":"../../../src","sources":["navigation/forgeTabIcon.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASC,YAAYA,CAACC,IAAkB,EAAmB;EAChE,MAAMC,MAAM,GAAGA,CAAC;IAAEC,OAAO;IAAEC,KAAK;IAAEC;EAAwD,CAAC,kBACzF,IAAAC,oBAAa,EAACL,IAAI,CAACM,SAAS,EAAE;IAAEC,MAAM,EAAEL,OAAO;IAAEC,KAAK;IAAEC;EAAK,CAAC,CAAC;EAEjE,OAAOH,MAAM;AACf","ignoreList":[]}

package/lib/commonjs/navigation/forgeTabIcon.native.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.forgeTabIcon = forgeTabIcon;
+/**
+ * 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.
+ */
+function forgeTabIcon(icon) {
+  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
+  }) => ({
+    type: 'image',
+    source: focused ? native.filled : native.outlined,
+    tinted: true
+  });
+  return resolve;
+}
+//# sourceMappingURL=forgeTabIcon.native.js.map

package/lib/commonjs/navigation/forgeTabIcon.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["forgeTabIcon","icon","native","name","Component","displayName","Error","resolve","focused","type","source","filled","outlined","tinted"],"sourceRoot":"../../../src","sources":["navigation/forgeTabIcon.native.ts"],"mappings":";;;;;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,YAAYA,CAACC,IAAkB,EAAmB;EAChE,MAAM;IAAEC;EAAO,CAAC,GAAGD,IAAI;EAEvB,IAAI,CAACC,MAAM,EAAE;IACX,MAAMC,IAAI,GAAGF,IAAI,CAACG,SAAS,CAACC,WAAW,IAAI,MAAM;IACjD,MAAM,IAAIC,KAAK,CACb,kBAAkBH,IAAI,8CAA8C,GAClE,iEAAiE,GACjE,mEAAmE,GACnE,iEAAiE,GACjE,6DACJ,CAAC;EACH;EAEA,MAAMI,OAAO,GAAGA,CAAC;IAAEC;EAA8B,CAAC,MAAgC;IAChFC,IAAI,EAAE,OAAO;IACbC,MAAM,EAAEF,OAAO,GAAGN,MAAM,CAACS,MAAM,GAAGT,MAAM,CAACU,QAAQ;IACjDC,MAAM,EAAE;EACV,CAAC,CAAC;EAEF,OAAON,OAAO;AAChB","ignoreList":[]}

package/lib/commonjs/navigation/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "forgeTabIcon", {
+  enumerable: true,
+  get: function () {
+    return _forgeTabIcon.forgeTabIcon;
+  }
+});
+var _forgeTabIcon = require("./forgeTabIcon");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/navigation/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_forgeTabIcon","require"],"sourceRoot":"../../../src","sources":["navigation/index.ts"],"mappings":";;;;;;;;;;;AAAA,IAAAA,aAAA,GAAAC,OAAA","ignoreList":[]}

package/lib/commonjs/navigation/types.js

@@ -0,0 +1,38 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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 =
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+null;
+const _rnDriftGuardNative =
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+null;
+//# sourceMappingURL=types.js.map

package/lib/commonjs/navigation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_rnDriftGuardWeb","_rnDriftGuardNative"],"sourceRoot":"../../../src","sources":["navigation/types.ts"],"mappings":";;;;;AAKA;AACA;AACA;AACA;AACA;AACA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAQA;AACA;AACA;AACA;AACA;AACA;;AAEA,MAAMA,gBAA0D;AAC9D;AACA,IAA8B;AAEhC,MAAMC,mBAAmE;AACvE;AACA,IAA8B","ignoreList":[]}

package/lib/commonjs/styles/primitives.js

@@ -5,40 +5,69 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.TRANSITION_COLORS = exports.SIZE_SCALE = exports.SHADOW_SM = exports.SHADOW_MD = exports.SEMANTIC_COLORS = exports.RADIUS_SM = exports.RADIUS_MD = exports.RADIUS_FULL = exports.FOCUS_RING = exports.DISABLED_OPACITY = exports.DISABLED_CURSOR = exports.COLOR_TEXT_SECONDARY = exports.COLOR_TEXT_PRIMARY = exports.COLOR_TEXT_PLACEHOLDER = exports.COLOR_TEXT_MUTED = exports.COLOR_TEXT_INVERSE = exports.COLOR_TEXT_INVALID = exports.COLOR_BRAND_HOVER = exports.COLOR_BRAND_DEFAULT = exports.COLOR_BRAND_ACTIVE = exports.COLOR_BORDER_STRONG = exports.COLOR_BORDER_INVALID = exports.COLOR_BORDER_FOCUS = exports.COLOR_BORDER_DEFAULT = exports.COLOR_BG_SUBTLE = exports.COLOR_BG_PRIMARY = exports.COLOR_BG_MUTED = exports.COLOR_BG_INVERSE = exports.COLOR_ACCENT_DEFAULT = exports.COLOR_ACCENT_BORDER = void 0;
 // 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. */
 const COLOR_BG_PRIMARY = exports.COLOR_BG_PRIMARY = 'bg-white';
+/** @deprecated Use `bg-surface-secondary` (--color-surface-secondary) instead. */
 const COLOR_BG_SUBTLE = exports.COLOR_BG_SUBTLE = 'bg-slate-50';
+/** @deprecated Use `bg-surface-neutral-subtle` (--color-surface-neutral-subtle) instead. */
 const COLOR_BG_MUTED = exports.COLOR_BG_MUTED = 'bg-slate-100';
+/** @deprecated Use `bg-base-950` (--color-base-950) instead. */
 const COLOR_BG_INVERSE = exports.COLOR_BG_INVERSE = 'bg-slate-900';
 
 // Border
+/** @deprecated Use `border-stroke-secondary` (--color-stroke-secondary) instead. */
 const COLOR_BORDER_DEFAULT = exports.COLOR_BORDER_DEFAULT = 'border-slate-200';
+/** @deprecated Use `border-stroke-hover` (--color-stroke-hover) instead. */
 const COLOR_BORDER_STRONG = exports.COLOR_BORDER_STRONG = 'border-slate-300';
+/** @deprecated Use `border-stroke-focus` (--color-stroke-focus) instead. */
 const COLOR_BORDER_FOCUS = exports.COLOR_BORDER_FOCUS = 'border-slate-900';
+/** @deprecated Use `border-stroke-danger` (--color-stroke-danger) instead. */
 const COLOR_BORDER_INVALID = exports.COLOR_BORDER_INVALID = 'border-red-500';
 
 // Text
+/** @deprecated Use `text-content-primary` (--color-content-primary) instead. */
 const COLOR_TEXT_PRIMARY = exports.COLOR_TEXT_PRIMARY = 'text-slate-900';
+/** @deprecated Use `text-content-secondary` (--color-content-secondary) instead. */
 const COLOR_TEXT_SECONDARY = exports.COLOR_TEXT_SECONDARY = 'text-slate-500';
+/** @deprecated Use `text-content-tertiary` (--color-content-tertiary) instead. */
 const COLOR_TEXT_MUTED = exports.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). */
 const COLOR_TEXT_INVERSE = exports.COLOR_TEXT_INVERSE = 'text-white';
+/** @deprecated Use `text-content-tertiary` (--color-content-tertiary) instead. */
 const COLOR_TEXT_PLACEHOLDER = exports.COLOR_TEXT_PLACEHOLDER = 'text-slate-400';
+/** @deprecated Use `text-content-danger` (--color-content-danger) instead. */
 const COLOR_TEXT_INVALID = exports.COLOR_TEXT_INVALID = 'text-red-600';
 
 // Brand / Action
+/** @deprecated Use `bg-surface-action-strong` (--color-surface-action-strong) instead. */
 const COLOR_BRAND_DEFAULT = exports.COLOR_BRAND_DEFAULT = 'bg-slate-900';
+/** @deprecated Use `bg-surface-action-strong-hover` (--color-surface-action-strong-hover) instead. */
 const COLOR_BRAND_HOVER = exports.COLOR_BRAND_HOVER = 'bg-slate-800';
+/** @deprecated Use `bg-surface-action-strong-active` (--color-surface-action-strong-active) instead. */
 const COLOR_BRAND_ACTIVE = exports.COLOR_BRAND_ACTIVE = 'bg-slate-700';
 
 // Accent (for checked states, active indicators)
+/** @deprecated Use `bg-surface-action-strong` (--color-surface-action-strong) instead. */
 const COLOR_ACCENT_DEFAULT = exports.COLOR_ACCENT_DEFAULT = 'bg-slate-900';
+/** @deprecated Use `border-stroke-action` (--color-stroke-action) instead. */
 const COLOR_ACCENT_BORDER = exports.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.
+ */
 const SEMANTIC_COLORS = exports.SEMANTIC_COLORS = {
   action: {
     bg: 'bg-slate-900',
@@ -83,21 +112,29 @@ const SEMANTIC_COLORS = exports.SEMANTIC_COLORS = {
 };
 
 // ─── Focus ───────────────────────────────────────────────
+/** @deprecated Use `ring-2 ring-[--color-stroke-focus] ring-offset-2` (--color-stroke-focus) instead. */
 const FOCUS_RING = exports.FOCUS_RING = 'ring-2 ring-slate-400/50 ring-offset-2';
 
 // ─── Radius ──────────────────────────────────────────────
-const RADIUS_SM = exports.RADIUS_SM = 'rounded-lg'; // buttons, inputs, checkboxes
-const RADIUS_MD = exports.RADIUS_MD = 'rounded-xl'; // cards, dropdowns, modals
-const RADIUS_FULL = exports.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. */
+const RADIUS_SM = exports.RADIUS_SM = 'rounded-lg';
+/** @deprecated Use `rounded-[var(--border-radius-default)]` for cards/containers. */
+const RADIUS_MD = exports.RADIUS_MD = 'rounded-xl';
+/** @deprecated Use `rounded-[var(--border-radius-round)]` for circular elements (icon buttons, radio, pills). */
+const RADIUS_FULL = exports.RADIUS_FULL = 'rounded-full';
 
 // ─── Shadows ─────────────────────────────────────────────
+
+/** @deprecated Use `shadow-sm` directly instead */
 const SHADOW_SM = exports.SHADOW_SM = 'shadow-sm';
+/** @deprecated Use `shadow-md` directly instead */
 const SHADOW_MD = exports.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 */
 const SIZE_SCALE = exports.SIZE_SCALE = {
   default: {
     height: 'h-10',