jfs-components 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.1.1] - 2026-06-10
+
+- Design tokens — the `modes` prop is now strongly typed end to end. A generated `Modes` type gives autocomplete and validation for both collection-name keys and mode-name values across every component, while staying fully backward compatible (opt-in `StrictModes` turns typos into compile errors). `FIGMA_MODES`, `CollectionName`, and `ModeOf` are exported from the package.
+- Storybook — components now expose per-collection mode `select` controls (auto-generated) in place of the freeform `modes` object control. Collection detection is composition-aware, so wrapper components (e.g. `Balance`, `BubbleChart`, `BrandChip`) surface the modes of the children they theme.
+- `FullscreenModal` — hero media now fills the modal edge to edge: the surface width is measured and an explicit ratio-derived box is applied to the background, fixing the right-side gap / mis-sized image on native.
+
+---
+
 ## [0.1.0] - 2026-06-08
 
 - Added `TestimonialsCard` — compact avatar + title + body card for testimonial carousels.

package/lib/commonjs/components/AreaLineChart/AreaLineChart.js

@@ -99,7 +99,7 @@ const defaultFormatX = label => String(label);
  * @component
  */
 function AreaLineChart({
-  series,
+  series = [],
   xLabels,
   yMin,
   yMax,

package/lib/commonjs/components/Balance/Balance.js

@@ -11,6 +11,13 @@ var _MoneyValue = _interopRequireDefault(require("../MoneyValue/MoneyValue"));
 var _reactUtils = require("../../utils/react-utils");
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// The Balance design renders its money value at the 36 px / 900-weight scale.
+// The `moneyValue/*` tokens alias into the `Context3` collection, where the
+// `Balance & Cards` mode supplies those larger values. Applied *before* the
+// caller's `modes` so any consumer can still override individual keys.
+const DEFAULT_MONEY_VALUE_MODES = {
+  Context3: 'Balance & Cards'
+};
 /**
  * Balance component that displays a title and a monetary value.
  *
@@ -34,7 +41,7 @@ function Balance({
   // Title styles
   const titleColor = (0, _figmaVariablesResolver.getVariableByName)('balance/title/foreground', modes) ?? '#0c0d10';
   const titleFontSize = (0, _figmaVariablesResolver.getVariableByName)('balance/title/fontSize', modes) ?? 14;
-  const titleFontFamily = (0, _figmaVariablesResolver.getVariableByName)('balance/title/fontFamily', modes) ?? 'System';
+  const titleFontFamily = (0, _figmaVariablesResolver.getVariableByName)('balance/title/fontFamily', modes) ?? 'JioType Var';
   const titleLineHeight = (0, _figmaVariablesResolver.getVariableByName)('balance/title/lineHeight', modes) ?? 18;
   const titleFontWeightValue = (0, _figmaVariablesResolver.getVariableByName)('balance/title/fontWeight', modes) ?? 500;
   const titleFontWeight = typeof titleFontWeightValue === 'number' ? titleFontWeightValue.toString() : titleFontWeightValue;
@@ -51,15 +58,13 @@ function Balance({
     fontWeight: titleFontWeight
   };
 
-  // Handle slot children or default content
-  const content = _react.default.Children.map(children, child => {
-    if (/*#__PURE__*/_react.default.isValidElement(child)) {
-      return /*#__PURE__*/_react.default.cloneElement(child, {
-        modes
-      });
-    }
-    return child;
-  });
+  // The money value renders at the Balance & Cards scale. Merge the default
+  // context mode first so the caller's `modes` can still override it, and
+  // force that context onto any slotted children so custom money values match.
+  const moneyValueModes = {
+    ...DEFAULT_MONEY_VALUE_MODES,
+    ...modes
+  };
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
     style: [containerStyle, style],
     "data-node-id": "1986:6203",
@@ -67,10 +72,10 @@ function Balance({
       style: titleStyle,
       "data-node-id": "1986:2613",
       children: title
-    }), children ? content : /*#__PURE__*/(0, _jsxRuntime.jsx)(_MoneyValue.default, {
+    }), children ? (0, _reactUtils.cloneChildrenWithModes)(children, modes, DEFAULT_MONEY_VALUE_MODES) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_MoneyValue.default, {
       value: amount,
       currency: currency,
-      modes: modes
+      modes: moneyValueModes
     })]
   });
 }

package/lib/commonjs/components/Card/Card.js

@@ -15,7 +15,8 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * Context to share 'modes' with child components like Card.Title and Card.SupportText.
  * This ensures that nested components can resolve their tokens correctly without 
  * needing explicit mode prop passing for every child.
- */const CardContext = /*#__PURE__*/(0, _react.createContext)({});
+ */
+const CardContext = /*#__PURE__*/(0, _react.createContext)({});
 /**
  * Card component implementation from Figma node 765:6186.
  * 

package/lib/commonjs/components/CardFeedback/CardFeedback.js

@@ -19,7 +19,8 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
  * Context to share 'modes' with child components.
- */const CardFeedbackContext = /*#__PURE__*/(0, _react.createContext)({});
+ */
+const CardFeedbackContext = /*#__PURE__*/(0, _react.createContext)({});
 /**
  * CardFeedback component from Figma node 1280:4481.
  * 

package/lib/commonjs/components/Checkbox/Checkbox.js

@@ -15,7 +15,8 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * Tracks whether the last user interaction was a keyboard event (Tab).
  * Capture-phase document listeners fire before any element-level handlers,
  * so the flag is always up-to-date when onFocus runs.
- */function useFocusVisible() {
+ */
+function useFocusVisible() {
   const [isFocusVisible, setIsFocusVisible] = (0, _react.useState)(false);
   const hadKeyboardEventRef = (0, _react.useRef)(false);
   (0, _react.useEffect)(() => {

package/lib/commonjs/components/Drawer/Drawer.js

@@ -10,7 +10,9 @@ var _reactNativeGestureHandler = require("react-native-gesture-handler");
 var _reactNativeReanimated = _interopRequireWildcard(require("react-native-reanimated"));
 var _figmaVariablesResolver = require("../../design-tokens/figma-variables-resolver");
 var _reactUtils = require("../../utils/react-utils");
+var _Overlay = _interopRequireDefault(require("../Overlay/Overlay"));
 var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const AnimatedScrollView = _reactNativeReanimated.default.createAnimatedComponent(_reactNativeGestureHandler.ScrollView);
 
@@ -72,7 +74,9 @@ function DrawerInner({
   contentContainerStyle,
   showsVerticalScrollIndicator = false,
   bottomInset = 80,
-  onStateChange
+  onStateChange,
+  showOverlay = false,
+  onOverlayPress
 }, ref) {
   const {
     height: screenHeight
@@ -370,10 +374,15 @@ function DrawerInner({
     // Per the standard react-native-gesture-handler architecture, a single
     // GestureHandlerRootView must wrap the app root; this overlay only needs to
     // let touches fall through where the sheet isn't.
-    (0, _jsxRuntime.jsx)(_reactNative.View, {
+    (0, _jsxRuntime.jsxs)(_reactNative.View, {
       style: [styles.host, style],
       pointerEvents: "box-none",
-      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeGestureHandler.GestureDetector, {
+      children: [showOverlay ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_Overlay.default, {
+        modes: modes,
+        ...(onOverlayPress ? {
+          onPress: onOverlayPress
+        } : {})
+      }) : null, /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeGestureHandler.GestureDetector, {
         gesture: gesture,
         children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeReanimated.default.View, {
           style: [styles.sheet, {
@@ -446,7 +455,7 @@ function DrawerInner({
             })]
           })
         })
-      })
+      })]
     })
   );
 }

package/lib/commonjs/components/DropdownInput/DropdownInput.js

@@ -537,7 +537,7 @@ function DropdownInput({
       transparent: true,
       statusBarTranslucent: true,
       navigationBarTranslucent: true,
-      animationType: "fade",
+      animationType: "none",
       onRequestClose: closeMenu,
       children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Pressable, {
         style: _reactNative.StyleSheet.absoluteFill,

package/lib/commonjs/components/FullscreenModal/FullscreenModal.js

@@ -253,7 +253,57 @@ function FullscreenModal({
     useNativeDriver: true
   }), [scrollY]);
   const heroTranslateY = (0, _react.useMemo)(() => _reactNative.Animated.multiply(scrollY, -1), [scrollY]);
-  const processedHeroMedia = (0, _react.useMemo)(() => heroMedia ? (0, _reactUtils.cloneChildrenWithModes)(heroMedia, modes, FULLSCREEN_MODAL_FORCED_MODES) : null, [heroMedia, modes]);
+
+  // The hero media is a full-bleed background pinned to the top of the modal.
+  // Its wrapper is absolutely positioned (`top/left/right: 0`) so it never
+  // contributes to scroll height. We measure the modal's own width so we can
+  // give the hero media a DEFINITE { width, height } box (see
+  // `processedHeroMedia` below) — relying on the media's own `width: '100%'` +
+  // `aspectRatio` is unreliable inside an indefinite-height absolute box (RN's
+  // `<Image>` falls back to its intrinsic width and leaves a gap), so we size
+  // it explicitly here instead.
+  const [containerWidth, setContainerWidth] = (0, _react.useState)(0);
+  const onContainerLayout = (0, _react.useCallback)(e => {
+    const w = e.nativeEvent.layout.width;
+    setContainerWidth(prev => prev !== w ? w : prev);
+  }, []);
+  const processedHeroMedia = (0, _react.useMemo)(() => {
+    if (!heroMedia) return null;
+    // Defer rendering the hero until we have measured the modal width. This
+    // matters for image sharpness: React Native decodes a bitmap once, on the
+    // first render, and caches it. If we rendered the media before knowing the
+    // final box, that first decode would be sized/sampled for the wrong box and
+    // the cached (downsampled) bitmap would then just be scaled up — blurry.
+    // Rendering only once the explicit { width, height } box is known means the
+    // very first decode is already full-resolution for the correct box.
+    if (containerWidth <= 0) return null;
+    const withModes = (0, _reactUtils.cloneChildrenWithModes)(heroMedia, modes, FULLSCREEN_MODAL_FORCED_MODES);
+
+    // Force the hero to fill the modal width edge to edge, top-aligned, with the
+    // height derived from the media's native aspect ratio.
+    //
+    // Why we inject explicit width/height instead of relying on the media's own
+    // `width: '100%'` + `aspectRatio`: the hero wrapper is absolutely positioned
+    // with an INDEFINITE height, and in that layout context React Native's
+    // `<Image>` falls back to its INTRINSIC width (so a 361px-wide asset renders
+    // 361px wide and leaves a gap on the right) rather than stretching to the
+    // parent. By computing `height = containerWidth / ratio` here and passing a
+    // DEFINITE { width, height } box (which makes `<Image>` skip aspectRatio and
+    // cover-fit into that exact box), the hero always fills the width with the
+    // correct ratio-derived height.
+    return _react.default.Children.map(withModes, child => {
+      if (! /*#__PURE__*/_react.default.isValidElement(child)) return child;
+      const props = child.props;
+      const ratio = typeof props.ratio === 'number' && props.ratio > 0 ? props.ratio : undefined;
+      // Only size media that exposes a numeric `ratio` and hasn't already been
+      // given an explicit box by the caller.
+      if (ratio == null || props.width != null || props.height != null) return child;
+      return /*#__PURE__*/_react.default.cloneElement(child, {
+        width: containerWidth,
+        height: containerWidth / ratio
+      });
+    });
+  }, [heroMedia, modes, containerWidth]);
   const processedChildren = (0, _react.useMemo)(() => children ? (0, _reactUtils.cloneChildrenWithModes)(children, modes, FULLSCREEN_MODAL_FORCED_MODES) : null, [children, modes]);
 
   // The hero text region always reserves `heroHeight` and anchors its content
@@ -306,8 +356,18 @@ function FullscreenModal({
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
     style: [rootStyle, style],
     testID: testID,
+    onLayout: onContainerLayout,
     children: [processedHeroMedia ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Animated.View, {
-      style: [heroBackgroundStyle, {
+      style: [heroBackgroundStyle,
+      // Give the absolute wrapper a DEFINITE width (the measured modal
+      // width) so the media's `width: '100%'` + `aspectRatio` resolves to
+      // a true edge-to-edge fill with a ratio-derived height, top-aligned.
+      // Before the first layout pass `containerWidth` is 0 — fall back to
+      // stretching via `left/right: 0` so there is no flash of a mis-sized
+      // image.
+      containerWidth > 0 ? {
+        width: containerWidth
+      } : null, {
         transform: [{
           translateY: heroTranslateY
         }]

package/lib/commonjs/components/Image/Image.js

@@ -43,6 +43,7 @@ function Image({
   imageSource,
   ratio = DEFAULT_RATIO,
   resizeMode = 'cover',
+  resizeMethod,
   width,
   height,
   borderRadius,
@@ -53,11 +54,15 @@ function Image({
   loading
 }) {
   const source = (0, _react.useMemo)(() => normalizeSource(imageSource), [imageSource]);
+
+  // Explicit { width, height } means a "fill an exact box" layout — typically a
+  // full-bleed hero/background where the asset is high-res and sharpness
+  // matters most. There, default to `'none'` (full-resolution, no pre-decode
+  // downsample) so detail is never thrown away. Aspect-ratio images keep the
+  // memory-safe `'scale'` default. A caller-supplied `resizeMethod` always wins.
+  const isExplicitBox = width != null && height != null;
+  const effectiveResizeMethod = resizeMethod ?? (isExplicitBox ? 'none' : 'scale');
   const layoutStyle = (0, _react.useMemo)(() => {
-    // If the caller has fully specified width AND height, they're doing a
-    // non-aspect layout (e.g. "fill the parent") — respect that and skip
-    // `aspectRatio` so it doesn't conflict.
-    const isExplicitBox = width != null && height != null;
     const s = {
       width: width ?? '100%',
       ...(isExplicitBox ? {
@@ -71,7 +76,7 @@ function Image({
     };
     if (borderRadius != null) s.borderRadius = borderRadius;
     return s;
-  }, [ratio, width, height, borderRadius]);
+  }, [ratio, width, height, borderRadius, isExplicitBox]);
   const {
     active: groupActive
   } = (0, _SkeletonGroup.useSkeleton)();
@@ -102,6 +107,7 @@ function Image({
     source: source,
     style: [layoutStyle, style],
     resizeMode: resizeMode,
+    resizeMethod: effectiveResizeMethod,
     accessibilityLabel: accessibilityLabel,
     accessibilityElementsHidden: accessibilityElementsHidden,
     importantForAccessibility: importantForAccessibility

package/lib/commonjs/components/LottiePlayer/loadNativeLottieView.js

@@ -11,17 +11,6 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 /** Props we forward to the underlying native Lottie view. */
 
 const INSTALL_HINT = 'LottiePlayer requires lottie-react-native in your app.\n' + '  npm install lottie-react-native\n' + '  cd ios && pod install';
-
-/**
- * Metro resolves `require('lottie-react-native')` at bundle time even inside
- * try/catch, which breaks apps that import `jfs-components` without having
- * the optional peer installed. Splitting the module id into a runtime string
- * keeps Metro from statically linking it — the native module is loaded only
- * when present in the consumer's node_modules.
- */
-function resolveNativeLottieModuleName() {
-  return ['lottie', '-react', '-native'].join('');
-}
 function LottieUnavailableView({
   style
 }) {
@@ -65,8 +54,14 @@ let cachedView;
 function getNativeLottieView() {
   if (cachedView !== undefined) return cachedView;
   try {
-    const mod = require(resolveNativeLottieModuleName());
-    cachedView = mod.default ?? LottieUnavailable;
+    // Static require so Metro resolves the module by its build-time numeric id.
+    // A runtime-constructed string path is NOT resolvable by Metro's `require`
+    // (it indexes modules by number, not path), so it would always throw and
+    // fall back to the install hint even when the package is installed. The
+    // dependency stays an *optional* peer: apps that use LottiePlayer install
+    // it; apps that don't simply never import this module.
+    const mod = require('lottie-react-native');
+    cachedView = mod.default ?? mod.LottieView ?? LottieUnavailable;
   } catch {
     cachedView = LottieUnavailable;
   }

package/lib/commonjs/components/Overlay/Overlay.js

@@ -0,0 +1,92 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _figmaVariablesResolver = require("../../design-tokens/figma-variables-resolver");
+var _JFSThemeProvider = require("../../design-tokens/JFSThemeProvider");
+var _reactUtils = require("../../utils/react-utils");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+const PLACEMENT_STYLE = {
+  center: {
+    justifyContent: 'center',
+    alignItems: 'center'
+  },
+  top: {
+    justifyContent: 'flex-start',
+    alignItems: 'stretch'
+  },
+  bottom: {
+    justifyContent: 'flex-end',
+    alignItems: 'stretch'
+  },
+  stretch: {
+    justifyContent: 'center',
+    alignItems: 'stretch'
+  }
+};
+
+/**
+ * Overlay — a token-driven scrim that dims content behind an overlaid surface.
+ *
+ * Renders a semi-transparent backdrop using the `overlay/background` design
+ * token and optionally hosts content (e.g. a modal, sheet or dialog) on top.
+ * Pair it with a `Modal` for true full-screen overlays, or drop it inside any
+ * relatively-positioned container to dim just that region.
+ *
+ * @example
+ * ```tsx
+ * <Overlay modes={modes} onPress={close}>
+ *   <Card>Dialog content</Card>
+ * </Overlay>
+ * ```
+ */
+function Overlay({
+  children,
+  contentPlacement = 'center',
+  onPress,
+  fill = true,
+  modes: propModes = _reactUtils.EMPTY_MODES,
+  style,
+  ...rest
+}) {
+  const {
+    modes: globalModes
+  } = (0, _JFSThemeProvider.useTokens)();
+  const modes = (0, _react.useMemo)(() => ({
+    ...globalModes,
+    ...propModes
+  }), [globalModes, propModes]);
+  const {
+    containerStyle,
+    processedChildren
+  } = (0, _react.useMemo)(() => {
+    const backgroundColor = (0, _figmaVariablesResolver.getVariableByName)('overlay/background', modes) ?? 'rgba(0, 0, 0, 0.7)';
+    const container = {
+      backgroundColor,
+      overflow: 'hidden',
+      ...PLACEMENT_STYLE[contentPlacement]
+    };
+    const processed = children ? (0, _reactUtils.cloneChildrenWithModes)(children, modes) : null;
+    return {
+      containerStyle: container,
+      processedChildren: processed
+    };
+  }, [children, modes, contentPlacement]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+    style: [fill && _reactNative.StyleSheet.absoluteFill, containerStyle, style],
+    accessibilityViewIsModal: true,
+    ...rest,
+    children: [onPress ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Pressable, {
+      style: _reactNative.StyleSheet.absoluteFill,
+      onPress: onPress,
+      accessibilityRole: "button",
+      accessibilityLabel: "Dismiss overlay"
+    }) : null, processedChildren]
+  });
+}
+var _default = exports.default = /*#__PURE__*/_react.default.memo(Overlay);

package/lib/commonjs/components/PlanComparisonCard/PlanComparisonCard.js

@@ -11,7 +11,8 @@ var _reactUtils = require("../../utils/react-utils");
 var _Icon = _interopRequireDefault(require("../../icons/Icon"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/** Figma grid: label column 1.8fr, each plan column 1fr. */const LABEL_COLUMN_FR = 1.8;
+/** Figma grid: label column 1.8fr, each plan column 1fr. */
+const LABEL_COLUMN_FR = 1.8;
 const PLAN_COLUMN_FR = 1;
 
 /**

package/lib/commonjs/components/TextInput/TextInput.js

@@ -43,7 +43,8 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
 /**
  * Helper function to convert a color to a more transparent version for placeholder text.
  * Takes a color string (hex, rgb, rgba) and returns it with reduced opacity.
- */const IS_WEB = _reactNative.Platform.OS === 'web';
+ */
+const IS_WEB = _reactNative.Platform.OS === 'web';
 function makePlaceholderColor(color, opacity = 0.5) {
   if (!color || typeof color !== 'string') {
     return color || '';

package/lib/commonjs/components/docs/modeControls.js

@@ -0,0 +1,116 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.modeArgTypes = modeArgTypes;
+exports.modeDecorator = modeDecorator;
+exports.withModeControls = withModeControls;
+var _react = _interopRequireDefault(require("react"));
+var _figmaModes = require("../../design-tokens/figma-modes.generated");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Storybook helpers that turn a component's design-token collections into real,
+ * per-collection `select` controls and merge the picked values into the `modes`
+ * prop — so authors get the same enum-driven DX in the Storybook Controls panel
+ * that the typed `modes` prop gives them in code.
+ *
+ * Fully backward compatible:
+ *   - If nothing is picked, `modes` is left exactly as the story provided it.
+ *   - Any `modes` value the story already sets WINS over a control selection,
+ *     so existing stories render identically until someone touches a control.
+ *   - The synthetic control args are stripped before they reach the component,
+ *     so they never leak in as unknown props.
+ */const UNSET = '(default)';
+/**
+ * Resolve the list of collections to expose. Accepts a component name (looked up
+ * in the generated map), an explicit list, or both (merged + de-duplicated).
+ */
+function resolveCollections(componentOrCollections, extra = []) {
+  const fromName = typeof componentOrCollections === 'string' ? _figmaModes.FIGMA_COMPONENT_MODES[componentOrCollections] || [] : componentOrCollections;
+  const merged = new Set([...fromName, ...extra]);
+  // Only keep collections that actually have more than one mode to choose from.
+  return [...merged].filter(name => {
+    const modes = _figmaModes.FIGMA_MODES[name];
+    return Array.isArray(modes) && modes.length > 1;
+  });
+}
+
+/**
+ * Build `argTypes` entries — one `select` per multi-mode collection, grouped
+ * under a "Modes" category. Spread the result into your story `meta.argTypes`.
+ */
+function modeArgTypes(componentOrCollections, extra = []) {
+  const collections = resolveCollections(componentOrCollections, extra);
+  const argTypes = {};
+  for (const name of collections) {
+    const modes = _figmaModes.FIGMA_MODES[name];
+    argTypes[name] = {
+      name,
+      description: `\`${name}\` collection mode`,
+      control: {
+        type: 'select'
+      },
+      options: [UNSET, ...modes],
+      table: {
+        category: 'Modes'
+      }
+    };
+  }
+  return argTypes;
+}
+
+/**
+ * A decorator that merges the picked collection modes into `args.modes` and
+ * strips the synthetic control args before they reach the component.
+ */
+function modeDecorator(componentOrCollections, extra = []) {
+  const collections = resolveCollections(componentOrCollections, extra);
+  return function ModeControlsDecorator(Story, context) {
+    const args = context?.args || {};
+    const picked = {};
+    // Start from the real story args so nothing is dropped. Passing only the
+    // synthetic keys here would REPLACE the story args in this Storybook
+    // renderer, wiping out real props (e.g. `series`, slot nodes) and leaving
+    // the component to render empty/crash.
+    const override = {
+      ...args
+    };
+    for (const name of collections) {
+      const value = args[name];
+      if (value && value !== UNSET) {
+        picked[name] = value;
+      }
+      // Neutralise the synthetic arg so it is never spread onto the component.
+      override[name] = undefined;
+    }
+
+    // Explicit story-provided modes win over control selections.
+    override.modes = {
+      ...picked,
+      ...(args.modes || {})
+    };
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(Story, {
+      args: override
+    });
+  };
+}
+
+/**
+ * Convenience: returns `{ argTypes, decorators }` to spread directly into a
+ * story `meta`.
+ *
+ * @example
+ * const meta = {
+ *   title: 'Components/Button',
+ *   component: Button,
+ *   ...withModeControls('Button'),
+ * }
+ */
+function withModeControls(componentOrCollections, extra = []) {
+  return {
+    argTypes: modeArgTypes(componentOrCollections, extra),
+    decorators: [modeDecorator(componentOrCollections, extra)]
+  };
+}

package/lib/commonjs/components/index.js

@@ -513,6 +513,12 @@ Object.defineProperty(exports, "OTPResend", {
     return _OTP.OTPResend;
   }
 });
+Object.defineProperty(exports, "Overlay", {
+  enumerable: true,
+  get: function () {
+    return _Overlay.default;
+  }
+});
 Object.defineProperty(exports, "PageHero", {
   enumerable: true,
   get: function () {
@@ -924,6 +930,7 @@ var _NoteInput = _interopRequireDefault(require("./NoteInput/NoteInput"));
 var _Nudge = _interopRequireDefault(require("./Nudge/Nudge"));
 var _NavArrow = _interopRequireDefault(require("./NavArrow/NavArrow"));
 var _Numpad = _interopRequireDefault(require("./Numpad/Numpad"));
+var _Overlay = _interopRequireDefault(require("./Overlay/Overlay"));
 var _Title = _interopRequireDefault(require("./Title/Title"));
 var _Screen = _interopRequireDefault(require("./Screen/Screen"));
 var _Section = _interopRequireDefault(require("./Section/Section"));

package/lib/commonjs/design-tokens/JFSThemeProvider.js

@@ -43,7 +43,7 @@ const JFSThemeProvider = ({
  * Hook to access the current design token context.
  *
  * returns {
- *   modes: Record<string, any> - The current active modes
+ *   modes: Modes - The current active modes
  *   getVariable: (name: string) => any - Function to resolve a token value
  * }
  */