jfs-components 0.1.25 → 0.1.30

package/CHANGELOG.md

@@ -4,6 +4,59 @@ 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.30] - 2026-07-10
+
+- `MoneyValue` — new `editable` prop (inline edit mode): tapping the value shows a numeric `TextInput` that accepts only digits + one decimal point; edit commits on blur/submit via new `onValueChange` callback; keyboard avoidance lifts the component above the keyboard using `Keyboard.addListener` + `measureInWindow` (same pattern as `ActionFooter`).
+- `ContentSheet` — new `visible` prop controls a bottom pop-up / exit animation driven by Reanimated's `withSpring` (same spring config as `Drawer`: damping 32, stiffness 300). Sheet springs up from below the bottom edge on mount / `visible=true` and springs back down on `visible=false`. Animation composes with keyboard avoidance so both `translateY` offsets are summed in a single `useAnimatedStyle`.
+- `CompareTable` — new `columnWidth` prop enables fixed-width scroll mode: each selection card and table cell gets this exact width; the cards row and every section body become independent horizontal `ScrollView`s whose scroll events are chained so they stay aligned in lockstep; the cards row pins to the top as a sticky header on the vertical axis; gray section-header rows render full-width outside the horizontal scroll so they don't slide with the cells.
+- `PdpCcCard` — new `numberOfLines`, `disableTruncation`, and `singleLine` props passed through to the `Title` component for precise control over title truncation and wrapping.
+- `Table` — new `columnWidth` prop applies a fixed width to every column (header + body) for uniform column sizing in scrollable layouts; new `scrollable` prop wraps the table in a horizontal `ScrollView`.
+- Stories and MDX documentation updated for all new features.
+
+---
+
+## [0.1.28] - 2026-07-07
+
+- Added `FormUpload` — token-driven attachment field with label, support text, `<Form>` validation integration, and a controlled `attachments` / `onAttachmentsChange` API. Renders a row of `Additem` cells (preview + empty upload trigger) with optional `maxCount` cap; accepts an injected `picker` callback so consumers wire their own image/document picker without adding native deps to the library.
+- Added `Additem` — single upload cell used by `FormUpload` and `Grid`; `'empty'` state opens the injected picker, `'preview'` shows the selected asset with remove affordance (`additem/*` tokens).
+- Added `Grid` — token-driven layout primitive with configurable `columns`, optional fixed `rows`, fractional `columnFrs` / `rowFrs` track weights, gap/padding tokens, and `justifyContent` / `alignItems`; each child becomes a cell with `modes` cascade.
+- `ContentSheet` — new optional `title` prop renders a centered sticky header using the same `drawer/title*` token family as `Drawer`, keeping bottom-sheet title styling consistent across surfaces.
+- Added `ic_broken_image`, `ic_image`, `ic_mic`, and `ic_mic_off` icons to the icon registry.
+- Regenerated component MDX token documentation and `.token-metadata.json` across the library.
+
+---
+
+## [0.1.27] - 2026-07-07
+
+- Added `ProfileCard` — dark rounded profile summary card (`profileCard/*` tokens) with an `Attached` monogram `Avatar` (optional `IconCapsule` badge), declarative header props (`name`, `monogram`, `avatarSource`, `upiHandles`) or a full `header` slot override, and a body slot below a `Divider`. Forces `context 10: jioPlus` so nested children (`ListItem`, `UpiHandle`, `Text`, `Button`, …) resolve on-dark profile-card tokens automatically; `Profile Card Appearance` mode (`Default` | `Premium`) recolors the whole card via `modes`.
+- `UpiHandle` — avatar visibility is now **source-driven**: the leading image renders only when `source` / `avatarSource` is provided; omitting it hides the avatar and force-sets `UPI Handle Image: False` so left padding stays symmetric (imageless layout used by `ProfileCard` handle pills). Removed the bundled default `Image.png` placeholder. Consumer `UPI Handle Image` mode values are overridden by source presence so avatar visibility and token layout stay in lockstep. New `WithoutImage` story and MDX usage docs.
+- `Section` — `Section.Bento` stories updated with `UpiHandle` pills that pass explicit avatar `source` values, matching the Figma Bento nav/upi layout (node 216-13845).
+- Figma token sync — `context 10` mode renamed `Profile card` → `jioPlus`; `Profile Card Appearance` collection wired for `ProfileCard` / `UpiHandle`.
+- `Carousel` — new `type="Numbered"` variant: full-bleed slides with floating `AutoplayControl` + `NumberPagination` overlay at the bottom center; interactive play/pause state wired to autoplay.
+- `Carousel` — **Fix:** autoplay pagination no longer flickers back to the previous active page during scroll animations; `activeIndex` is derived from settled offsets instead of intermediate scroll positions.
+- Regenerated component MDX token documentation and `.token-metadata.json` across the library.
+
+---
+
+## [0.1.26] - 2026-07-07
+
+- Added `AutoplayControl` — token-driven play/pause toggle button for carousel autoplay (`autoplayControl/*` tokens; `ic_play` / `ic_pause` icons).
+- Added `NumberPagination` — frosted-glass page-number strip with active/inactive control states (`numberPagination/*`, `controlNumber/*`, `control/*` tokens); supports `children` slot override.
+- Added `ic_play` and `ic_pause` icons to the icon registry.
+- Regenerated component MDX token documentation and `.token-metadata.json` across the library.
+
+---
+
+## [0.1.25] - 2026-07-03
+
+- Added `MetricData` — compact centered metric block (`title`, `value`, optional `caption` and leading `icon`); typography, colours, gaps, and padding resolve from `metricdata/*` tokens; `value` accepts a string or custom node (e.g. `MoneyValue`).
+- Added `Rating` — token-driven star row (`rating/gap`, `ratingStar/*`); filled vs empty stars share one SVG glyph and differ by `Rating Star State`; optional `onChange` for interactive selection, `readOnly` for static display.
+- `CardCTA` — **Fix:** restore true 2fr right-column geometry on Android. Replaces the `flexBasis: 'auto'` workaround (which over-expanded the icon column and caused early body-text wrapping) with `flexBasis: 0` plus an explicit `minWidth` floor sized to the resolved `IconCapsule` + horizontal padding, so the column keeps the design ratio without collapsing when the left text is long.
+- `ChipSelect` — new `showCloseIcon` prop (default `true`); set `showCloseIcon={false}` to hide the close icon in the active state.
+- `ListItem` — vertical layout support text is hard-clamped to exactly two lines via `numberOfLines={2}` (spaces become line breaks, e.g. `"Split Payments"` → two lines). Fixes Bento grid labels wrapping onto a third line on native, where React Native has no `white-space: nowrap` equivalent. Horizontal layout support text uses the same two-line clamp.
+
+---
+
 ## [0.1.23] - 2026-07-01
 
 - Added `Link` — token-driven underlined text link mirroring the `Text` API (`text`/`children`, `autolayout`, `textAlign`, `disableTruncation`, `singleLine`); navigation-agnostic with consumer-provided `onPress`.

package/lib/commonjs/components/AutoplayControl/AutoplayControl.js

@@ -0,0 +1,66 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = AutoplayControl;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _figmaVariablesResolver = require("../../design-tokens/figma-variables-resolver");
+var _Icon = _interopRequireDefault(require("../../icons/Icon"));
+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); }
+function resolveAutoplayControlTokens(modes, disabled) {
+  const width = (0, _figmaVariablesResolver.getVariableByName)('autoplayControl/width', modes) ?? 36;
+  const height = (0, _figmaVariablesResolver.getVariableByName)('autoplayControl/height', modes) ?? 36;
+  const radiusRaw = (0, _figmaVariablesResolver.getVariableByName)('autoplayControl/radius', modes) ?? 9999;
+  const backgroundColor = (0, _figmaVariablesResolver.getVariableByName)('autoplayControl/background/color', modes) ?? '#ffffff';
+  const iconColor = (0, _figmaVariablesResolver.getVariableByName)('autoplayControl/icon/color', modes) ?? '#000000';
+  const borderRadius = radiusRaw === 9999 ? width / 2 : radiusRaw;
+  return {
+    containerStyle: {
+      width,
+      height,
+      borderRadius,
+      backgroundColor,
+      alignItems: 'center',
+      justifyContent: 'center',
+      opacity: disabled ? 0.5 : 1
+    },
+    iconColor
+  };
+}
+
+/**
+ * AutoplayControl is a button component that toggles between play and pause states.
+ * All styling values are resolved from Figma design tokens.
+ */
+function AutoplayControl({
+  state = 'pause',
+  modes,
+  onPress,
+  disabled = false,
+  style
+}) {
+  const tokens = (0, _react.useMemo)(() => resolveAutoplayControlTokens(modes ?? {}, disabled), [modes, disabled]);
+  const iconName = state === 'play' ? 'ic_play' : 'ic_pause';
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Pressable, {
+    onPress: disabled ? undefined : onPress,
+    disabled: disabled,
+    style: ({
+      pressed
+    }) => [tokens.containerStyle, pressed && {
+      opacity: 0.7
+    }, style],
+    accessibilityRole: "button",
+    accessibilityState: {
+      disabled
+    },
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Icon.default, {
+      name: iconName,
+      size: 24,
+      color: tokens.iconColor
+    })
+  });
+}

package/lib/commonjs/components/Carousel/Carousel.js

@@ -11,7 +11,10 @@ var _react = _interopRequireWildcard(require("react"));
 var _reactNative = require("react-native");
 var _figmaVariablesResolver = require("../../design-tokens/figma-variables-resolver");
 var _reactUtils = require("../../utils/react-utils");
+var _AutoplayControl = _interopRequireDefault(require("../AutoplayControl/AutoplayControl"));
+var _NumberPagination = _interopRequireDefault(require("../NumberPagination/NumberPagination"));
 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); }
 // ---------------------------------------------------------------------------
 // Context
@@ -45,9 +48,11 @@ function Carousel({
   itemWidth: itemWidthProp,
   paddingHorizontal: paddingHorizontalProp,
   paddingVertical: paddingVerticalProp,
+  type = 'Default',
   onIndexChange,
   style
 }) {
+  const isNumbered = type === 'Numbered';
   // ---- Token resolution ----
   const tokenGap = parseFloat((0, _figmaVariablesResolver.getVariableByName)('carousel/gap', modes));
   const gap = gapProp ?? tokenGap;
@@ -55,27 +60,43 @@ function Carousel({
   const containerPaddingV = parseFloat((0, _figmaVariablesResolver.getVariableByName)('carousel/padding/vertical', modes));
   // Outer container max height per Figma (`carousel/maxHeight`).
   const maxHeight = parseFloat((0, _figmaVariablesResolver.getVariableByName)('carousel/maxHeight', modes));
+  // Gap between AutoplayControl and NumberPagination in the Numbered overlay.
+  const controlGap = parseFloat((0, _figmaVariablesResolver.getVariableByName)('carouselControl/gap', modes));
+
   // Spacing between the cards row and the pagination dots uses `carousel/gap`.
   const paginationOffset = gap;
 
   // ---- Refs & state ----
   const scrollRef = (0, _react.useRef)(null);
   const [activeIndex, setActiveIndex] = (0, _react.useState)(0);
+  const activeIndexRef = (0, _react.useRef)(0);
   const [containerWidth, setContainerWidth] = (0, _react.useState)(0);
   const autoPlayTimer = (0, _react.useRef)(null);
   const userInteracting = (0, _react.useRef)(false);
+  // Guard: suppress handleScroll index updates during programmatic scrollTo
+  // animations so intermediate offsets don't flicker activeIndex back.
+  const programmaticScroll = (0, _react.useRef)(false);
+  const programmaticTimer = (0, _react.useRef)(null);
+  (0, _react.useEffect)(() => {
+    activeIndexRef.current = activeIndex;
+  }, [activeIndex]);
+
+  // Interactive play/pause state for the Numbered variant.
+  const [isPlaying, setIsPlaying] = (0, _react.useState)(autoPlay);
 
   // Flatten children so we can count items
   const items = (0, _react.useMemo)(() => _react.default.Children.toArray(children).filter(_react.default.isValidElement), [children]);
   const totalItems = items.length;
 
-  // Effective item width: provided prop, or full container width minus peek offsets
+  // Effective item width: provided prop, or full container width minus peek offsets.
+  // For the Numbered variant the items are full-bleed (no peek padding).
   const effectiveItemWidth = (0, _react.useMemo)(() => {
     if (itemWidthProp != null) return itemWidthProp;
     if (containerWidth === 0) return 0;
+    if (isNumbered) return containerWidth;
     // Full-width minus peekOffset on each side
     return containerWidth - containerPaddingH * 4;
-  }, [itemWidthProp, containerWidth, containerPaddingH]);
+  }, [itemWidthProp, containerWidth, containerPaddingH, isNumbered]);
 
   // Snap interval = item width + gap
   const snapInterval = effectiveItemWidth + gap;
@@ -89,6 +110,17 @@ function Carousel({
     } else {
       targetIndex = Math.max(0, Math.min(index, totalItems - 1));
     }
+    // Lock out handleScroll during the animated scroll so intermediate
+    // offsets don't flicker activeIndex back to the old value.
+    if (animated) {
+      programmaticScroll.current = true;
+      if (programmaticTimer.current != null) {
+        clearTimeout(programmaticTimer.current);
+      }
+      programmaticTimer.current = setTimeout(() => {
+        programmaticScroll.current = false;
+      }, 500);
+    }
     scrollRef.current?.scrollTo({
       x: targetIndex * snapInterval,
       animated
@@ -103,6 +135,9 @@ function Carousel({
   // ---- Scroll event handler ----
   const handleScroll = (0, _react.useCallback)(event => {
     if (snapInterval === 0) return;
+    // Skip index recalculation during programmatic scrollTo animations
+    // to prevent the active indicator from flickering back to the old page.
+    if (programmaticScroll.current) return;
     const offsetX = event.nativeEvent.contentOffset.x;
     const newIndex = Math.round(offsetX / snapInterval);
     const clampedIndex = Math.max(0, Math.min(newIndex, totalItems - 1));
@@ -120,22 +155,19 @@ function Carousel({
     }
   }, []);
   const startAutoPlay = (0, _react.useCallback)(() => {
-    if (!autoPlay || totalItems <= 1) return;
+    if (!autoPlay && !isPlaying || totalItems <= 1) return;
+    if (!isPlaying) return;
     clearAutoPlay();
     autoPlayTimer.current = setInterval(() => {
       if (!userInteracting.current) {
-        setActiveIndex(prev => {
-          const next = loop ? (prev + 1) % totalItems : Math.min(prev + 1, totalItems - 1);
-          scrollRef.current?.scrollTo({
-            x: next * snapInterval,
-            animated: true
-          });
-          onIndexChange?.(next);
-          return next;
-        });
+        const prev = activeIndexRef.current;
+        const next = loop ? (prev + 1) % totalItems : Math.min(prev + 1, totalItems - 1);
+        // Route through scrollToIndex so the programmaticScroll guard
+        // suppresses intermediate handleScroll offsets during the animation.
+        scrollToIndex(next, true);
       }
     }, autoPlayInterval);
-  }, [autoPlay, totalItems, loop, snapInterval, autoPlayInterval, clearAutoPlay, onIndexChange]);
+  }, [autoPlay, isPlaying, totalItems, loop, autoPlayInterval, clearAutoPlay, scrollToIndex]);
   (0, _react.useEffect)(() => {
     startAutoPlay();
     return clearAutoPlay;
@@ -146,8 +178,23 @@ function Carousel({
   const handleScrollEndDrag = (0, _react.useCallback)(() => {
     userInteracting.current = false;
     // Reset autoplay timer after interaction
-    if (autoPlay) startAutoPlay();
-  }, [autoPlay, startAutoPlay]);
+    if (autoPlay || isPlaying) startAutoPlay();
+  }, [autoPlay, isPlaying, startAutoPlay]);
+  const finishProgrammaticScroll = (0, _react.useCallback)(event => {
+    programmaticScroll.current = false;
+    if (programmaticTimer.current != null) {
+      clearTimeout(programmaticTimer.current);
+      programmaticTimer.current = null;
+    }
+    if (snapInterval === 0) return;
+    const offsetX = event.nativeEvent.contentOffset.x;
+    const newIndex = Math.round(offsetX / snapInterval);
+    const clampedIndex = Math.max(0, Math.min(newIndex, totalItems - 1));
+    if (clampedIndex !== activeIndexRef.current) {
+      setActiveIndex(clampedIndex);
+      onIndexChange?.(clampedIndex);
+    }
+  }, [snapInterval, totalItems, onIndexChange]);
 
   // ---- Layout ----
   const handleLayout = (0, _react.useCallback)(e => {
@@ -164,14 +211,37 @@ function Carousel({
     goPrev
   }), [modes, activeIndex, totalItems, goTo, goNext, goPrev]);
 
+  // ---- Toggle handler for Numbered variant ----
+  const handleToggleAutoplay = (0, _react.useCallback)(() => {
+    setIsPlaying(prev => {
+      if (prev) {
+        // Pausing
+        clearAutoPlay();
+        return false;
+      }
+      // Resuming — autoplay will restart via the effect
+      return true;
+    });
+  }, [clearAutoPlay]);
+
+  // Restart autoplay whenever isPlaying flips to true
+  (0, _react.useEffect)(() => {
+    if (isPlaying) startAutoPlay();else clearAutoPlay();
+  }, [isPlaying, startAutoPlay, clearAutoPlay]);
+
   // ---- Render ----
   // Explicit padding props win verbatim; otherwise fall back to the
   // token-derived values (horizontal keeps its legacy ×2 "peek" multiplier).
-  const effectivePaddingH = paddingHorizontalProp ?? containerPaddingH;
-  const effectivePaddingV = paddingVerticalProp ?? containerPaddingV;
+  // Numbered variant is full-bleed: zero padding.
+  const effectivePaddingH = isNumbered ? 0 : paddingHorizontalProp ?? containerPaddingH;
+  const effectivePaddingV = isNumbered ? 0 : paddingVerticalProp ?? containerPaddingV;
   const outerStyle = {
     paddingVertical: effectivePaddingV,
-    maxHeight
+    maxHeight: isNumbered ? undefined : maxHeight,
+    // Numbered needs relative positioning for the floating controls overlay.
+    ...(isNumbered ? {
+      overflow: 'hidden'
+    } : {})
   };
   const contentContainerStyle = {
     paddingHorizontal: effectivePaddingH,
@@ -197,6 +267,7 @@ function Carousel({
         scrollEventThrottle: 16,
         onScrollBeginDrag: handleScrollBeginDrag,
         onScrollEndDrag: handleScrollEndDrag,
+        onMomentumScrollEnd: finishProgrammaticScroll,
         children: items.map((child, index) => {
           // Strict slot box: width must be honored; never grow or shrink with
           // content, and clip anything that misbehaves (e.g. a child whose
@@ -233,11 +304,33 @@ function Carousel({
             children: childWithModes
           }, index);
         })
-      }), showPagination && totalItems > 1 && /*#__PURE__*/(0, _jsxRuntime.jsx)(Pagination, {
+      }), !isNumbered && showPagination && totalItems > 1 && /*#__PURE__*/(0, _jsxRuntime.jsx)(Pagination, {
         modes: modes,
         style: {
           marginTop: paginationOffset
         }
+      }), isNumbered && showPagination && totalItems > 1 && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: {
+          position: 'absolute',
+          bottom: 12,
+          left: 0,
+          right: 0,
+          flexDirection: 'row',
+          justifyContent: 'center',
+          alignItems: 'center',
+          gap: controlGap
+        },
+        pointerEvents: "box-none",
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_AutoplayControl.default, {
+          state: isPlaying ? 'pause' : 'play',
+          onPress: handleToggleAutoplay,
+          modes: modes
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_NumberPagination.default, {
+          activePage: activeIndex + 1,
+          totalPages: totalItems,
+          onPageChange: page => goTo(page - 1),
+          modes: modes
+        })]
       })]
     })
   });

package/lib/commonjs/components/CompareTable/CompareTable.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.default = void 0;
-var _react = _interopRequireDefault(require("react"));
+var _react = _interopRequireWildcard(require("react"));
 var _reactNative = require("react-native");
 var _figmaVariablesResolver = require("../../design-tokens/figma-variables-resolver");
 var _reactUtils = require("../../utils/react-utils");
@@ -15,6 +15,7 @@ var _IconButton = _interopRequireDefault(require("../IconButton/IconButton"));
 var _Icon = _interopRequireDefault(require("../../icons/Icon"));
 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); }
 /**
  * Brand link colour used by the selection-card CTA. The Figma node resolves
  * `button/foreground` to this value, but no reproducible token mode currently
@@ -111,7 +112,8 @@ function CompareTable({
   maxColumns = 4,
   modes = _reactUtils.EMPTY_MODES,
   style,
-  disableTruncation
+  disableTruncation,
+  columnWidth
 }) {
   // --- selection card tokens ------------------------------------------------
   const cardBg = (0, _figmaVariablesResolver.getVariableByName)('selectionCard/background/color', modes) ?? '#ffffff';
@@ -168,6 +170,70 @@ function CompareTable({
   const showAddCard = onAddColumn != null && columnCount < maxColumns;
   /** Grid columns shared by the selection-card row and every table row. */
   const gridColumnCount = columnCount + (showAddCard ? 1 : 0);
+  const showCardsRow = columnCount > 0 || showAddCard;
+
+  // --- fixed-width scroll mode -------------------------------------------
+  // `columnWidth` opts the component into scroll mode (see prop doc). In that
+  // mode the cards row and each section's table body are independent
+  // horizontal ScrollViews; their scroll events are chained so they move in
+  // lockstep, and the cards row pins to the top on the vertical axis.
+  const useFixedWidth = columnWidth != null;
+  /** Total scrollable content width shared by every horizontal surface. */
+  const contentWidth = useFixedWidth ? gridColumnCount * columnWidth : 0;
+  const cardsScrollRef = (0, _react.useRef)(null);
+  const bodyScrollRefs = (0, _react.useRef)(new Map());
+  // Stable per-section ref-callback instances so React doesn't detach/reattach
+  // on every render (which would churn the map and re-fire scrollTo).
+  const bodyRefCallbacks = (0, _react.useRef)(new Map());
+  /** Last offset we synced everyone to. Echoed onScroll events reporting this
+   *  same value are ignored — this is what prevents feedback loops. */
+  const lastSyncX = (0, _react.useRef)(0);
+  const applySync = (0, _react.useCallback)((x, source) => {
+    if (Math.abs(x - lastSyncX.current) < 0.5) return;
+    lastSyncX.current = x;
+    if (source !== 'cards' && cardsScrollRef.current) {
+      cardsScrollRef.current.scrollTo({
+        x,
+        animated: false
+      });
+    }
+    bodyScrollRefs.current.forEach((ref, idx) => {
+      if (source === 'cards' || idx !== source) {
+        ref.scrollTo({
+          x,
+          animated: false
+        });
+      }
+    });
+  }, []);
+  const onCardsScroll = (0, _react.useCallback)(e => {
+    applySync(e.nativeEvent.contentOffset.x, 'cards');
+  }, [applySync]);
+  const onBodyScroll = (0, _react.useCallback)(idx => e => {
+    applySync(e.nativeEvent.contentOffset.x, idx);
+  }, [applySync]);
+  const getBodyRefCallback = (0, _react.useCallback)(idx => {
+    let cb = bodyRefCallbacks.current.get(idx);
+    if (!cb) {
+      cb = ref => {
+        if (ref) {
+          bodyScrollRefs.current.set(idx, ref);
+          // Bring a freshly-expanded section's body into sync with
+          // the rest of the surfaces.
+          if (lastSyncX.current > 0) {
+            ref.scrollTo({
+              x: lastSyncX.current,
+              animated: false
+            });
+          }
+        } else {
+          bodyScrollRefs.current.delete(idx);
+        }
+      };
+      bodyRefCallbacks.current.set(idx, cb);
+    }
+    return cb;
+  }, []);
   const cardLabelStyle = {
     ...NO_WRAP_TEXT,
     color: cardLabelColor,
@@ -198,8 +264,12 @@ function CompareTable({
     fontWeight: toWeight(cellFontWeight)
   };
   const cardStyle = {
-    flex: 1,
-    minWidth: 0,
+    ...(useFixedWidth ? {
+      width: columnWidth
+    } : {
+      flex: 1,
+      minWidth: 0
+    }),
     minHeight: 147,
     backgroundColor: cardBg,
     borderRadius: cardRadius,
@@ -318,6 +388,7 @@ function CompareTable({
     return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Table.default.Cell, {
       modes: modes,
       flex: 1,
+      width: useFixedWidth ? columnWidth : undefined,
       align: "left",
       isLastColumn: isLastCol,
       isLastRow: isLastRow,
@@ -371,31 +442,126 @@ function CompareTable({
       })
     })]
   });
-  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-    style: [{
-      width: '100%',
-      backgroundColor: cardBg,
-      borderWidth: 1,
-      borderColor: '#e8e8e8',
-      overflow: 'hidden'
-    }, style],
-    children: [(columnCount > 0 || showAddCard) && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+
+  // Render a single section in fixed-width scroll mode. Unlike `renderTable`
+  // (used in flex mode), the gray header row is rendered full-width OUTSIDE
+  // the body's horizontal ScrollView so it stays put horizontally (it does
+  // not slide with the cells) while still scrolling vertically with the table.
+  // The body rows live inside a horizontal ScrollView that is scroll-synced
+  // with the cards row and every other section's body.
+  const renderSection = (section, index) => /*#__PURE__*/(0, _jsxRuntime.jsxs)(_Accordion.default, {
+    title: section.title,
+    defaultExpanded: section.defaultExpanded ?? index === 0,
+    modes: modes,
+    children: [section.header != null && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
       style: {
-        flexDirection: 'row',
-        width: '100%'
+        width: '100%',
+        backgroundColor: headerBg,
+        paddingHorizontal: headerPaddingH,
+        paddingVertical: headerPaddingV,
+        borderBottomWidth: cellBorderSize,
+        borderBottomColor: cellBorderColor
       },
-      children: [columns.map(renderCard), showAddCard && renderAddCard()]
-    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: headerTextStyle,
+        children: section.header
+      })
+    }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
+      ref: getBodyRefCallback(index),
+      horizontal: true,
+      showsHorizontalScrollIndicator: false,
+      scrollEventThrottle: 16,
+      onScroll: onBodyScroll(index),
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: {
+          width: contentWidth
+        },
+        children: section.rows.map((row, rowIndex) => {
+          const isLastRow = rowIndex === section.rows.length - 1;
+          return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+            style: {
+              flexDirection: 'row',
+              width: '100%'
+            },
+            children: [Array.from({
+              length: columnCount
+            }).map((_, colIndex) => renderTableCell(renderCellContent(row.values?.[colIndex], `${rowIndex}-${colIndex}`), colIndex, isLastRow, colIndex)), showAddCard && renderTableCell(null, gridColumnCount - 1, isLastRow, '__add_spacer__')]
+          }, row.key ?? rowIndex);
+        })
+      })
+    })]
+  }, section.key ?? section.title ?? index);
+  const outerStyle = {
+    width: '100%',
+    backgroundColor: cardBg,
+    borderWidth: 1,
+    borderColor: '#e8e8e8',
+    overflow: 'hidden'
+  };
+
+  // --- flex mode (columnWidth omitted): original behaviour, unchanged -------
+  if (!useFixedWidth) {
+    return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: [outerStyle, style],
+      children: [showCardsRow && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: {
+          flexDirection: 'row',
+          width: '100%'
+        },
+        children: [columns.map(renderCard), showAddCard && renderAddCard()]
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: {
+          width: '100%'
+        },
+        children: sections.map((section, index) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_Accordion.default, {
+          title: section.title,
+          defaultExpanded: section.defaultExpanded ?? index === 0,
+          modes: modes,
+          children: renderTable(section)
+        }, section.key ?? section.title ?? index))
+      })]
+    });
+  }
+
+  // --- fixed-width scroll mode: chained horizontal sync + sticky cards -----
+  // The cards row (index 0) is a sticky header of the vertical ScrollView so
+  // it pins to the top while the sections scroll beneath. The cards row is
+  // itself a horizontal ScrollView, synced with every section body. For the
+  // vertical scroll (and thus the sticky behaviour) to engage, the host must
+  // give CompareTable a bounded height (e.g. a sized container or flex:1).
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: [outerStyle, style, {
+      flexDirection: 'column',
+      flex: 1
+    }],
+    children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.ScrollView, {
       style: {
-        width: '100%'
+        width: '100%',
+        flex: 1
       },
-      children: sections.map((section, index) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_Accordion.default, {
-        title: section.title,
-        defaultExpanded: section.defaultExpanded ?? index === 0,
-        modes: modes,
-        children: renderTable(section)
-      }, section.key ?? section.title ?? index))
-    })]
+      stickyHeaderIndices: showCardsRow ? [0] : [],
+      showsVerticalScrollIndicator: false,
+      directionalLockEnabled: true,
+      children: [showCardsRow && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.ScrollView, {
+        ref: cardsScrollRef,
+        horizontal: true,
+        showsHorizontalScrollIndicator: false,
+        scrollEventThrottle: 16,
+        onScroll: onCardsScroll,
+        children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+          style: {
+            flexDirection: 'row',
+            width: contentWidth
+          },
+          children: [columns.map(renderCard), showAddCard && renderAddCard()]
+        })
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: {
+          width: '100%'
+        },
+        children: sections.map(renderSection)
+      })]
+    })
   });
 }
 var _default = exports.default = CompareTable;