jfs-components 0.1.30 → 0.1.33

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.33] - 2026-07-20
+
+- **Use [`D2C.md`](./D2C.md) for Design-to-Code.** This is the playbook we want agents and consumers to follow when implementing a Figma screen with `jfs-components`. It ships in the npm package (see `package.json` `files`) so it is available at `node_modules/jfs-components/D2C.md` after install. The workflow is mandatory end-to-end: Figma MCP (`get_design_context` + `get_screenshot`) → mode extraction via `npx jfs-extract-modes` (REST API; Dev seat / file-read token is enough) → build with exact modes → visual QA against the Figma screenshot. Point Cursor rules / agent instructions at this file rather than inventing a parallel D2C process.
+- Packages `D2C.md` alongside the `jfs-extract-modes` CLI so the guide and the tool travel together in every release.
+
+---
+
+## [0.1.32] - 2026-07-20
+
+- Added `jfs-extract-modes` — a CLI shipped with the npm package (`bin` + `scripts/extract-figma-modes.js`) that extracts explicit Figma variable modes per layer via the **Figma REST API** only (one `GET /v1/files/:key` call). No Plugin API, so it works with a **Dev seat** (or any token with file read access) — you do not need an edit / full design seat. After installing `jfs-components`, run `npx jfs-extract-modes <figma-url>` (or `npm run extract-modes` in this repo) with `FIGMA_ACCESS_TOKEN` set. Optional `--add-keys` patches collection keys into the packaged variables JSON for library maintainers.
+- Packaged `Coin Variables-variables-full.json` updated with collection keys so mode resolution is collection-key exact for consumers.
+- `ValueBackMetric` — new optional `onPress` / `disabled` props make the whole card pressable (`Pressable` + `accessibilityRole="button"`), independent of the bottom link’s `onLinkPress`.
+- Regenerated `figma-modes.generated.ts` (adds `HelloJioInput` modes) and icon registry timestamp.
+
+---
+
+## [0.1.31] - 2026-07-15
+
+- Added `CategoryCard` — compact category rail tile (`categoryCard/*` tokens) with image (or `imageSlot`), optional overlapping `Badge`, fixed 60dp width (overridable via `width`), and `active` / `disabled` press states. Label truncation mirrors `Text` via `disableTruncation` / `singleLine`.
+- Added `HelloJioInput` — pill-shaped HelloJio prompt field (`helloJioInput/*` tokens) with leading brand icon, single-line input, and send `IconButton`. Focus drives Idle → Active; `jioPlus` enables the frosted IdleJioPlus glass surface. Controlled/uncontrolled text with `onSubmit` from the send button and keyboard return key; `leading` / `trailing` slots for customization.
+- Added `CounterBadge` — small token-driven value pill (`counterBadge/*` tokens).
+- Added `FavoriteToggle` — glass circular favorite control (`favoriteToggle/*` tokens) with controlled `isActive` / uncontrolled `defaultActive`, `onChange`, and skeleton loading support.
+- Added `ValueBackMetric` — compact metric card (JioPoints-style) with header icon + title, value, caption, and optional bottom `Link`; colours/gaps/padding from `metricdata/*` tokens.
+- `CompareTable` — new `stickyHeaders` and `stickyHeaderLabel` props (default `true`) for sticky section headers in fixed-width scroll mode; horizontal scroll sync rewritten to track the actively dragged `ScrollView` and eliminate jitter from programmatic `scrollTo` echoes.
+- `ContentSheet` — new `maxHeightPercent` prop (default `0.7`) caps sheet height as a fraction of the window and scrolls overflow content.
+- Stories and MDX documentation updated for all new components and props.
+
+---
+
 ## [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`).

package/D2C.md

@@ -0,0 +1,118 @@
+# D2C — Design to Code (jfs-components)
+
+You are implementing a screen from a Figma design using the `jfs-components`
+library. The user has pasted a Figma link. Follow this workflow exactly, in
+order. Do not skip steps and do not improvise substitutes for them.
+
+## Step 1 — Pull the design through the Figma MCP
+
+Extract `fileKey` and `nodeId` from the pasted URL
+(`https://www.figma.com/design/<fileKey>/...?node-id=<a>-<b>` → nodeId is
+`<a>:<b>`).
+
+1. Call `get_design_context` for the node. This gives you the component
+   structure, layout, props, variants, text content, and Code Connect hints.
+2. Call `get_screenshot` for the same node and keep the image. This is the
+   visual ground truth you will QA against in Step 4.
+
+The Figma MCP gives you almost everything — except one thing: the **variable
+modes explicitly set on each layer**. Those are invisible to the MCP and they
+change how components render (size, emphasis, appearance, color mode, etc.).
+That is what Step 2 is for.
+
+## Step 2 — Extract the modes (mandatory, never skip)
+
+Run the mode extractor that ships with this package. It needs a Figma personal
+access token with plain file-read access (a view-only / Dev seat token works;
+no Enterprise scopes, no edit access):
+
+```bash
+export FIGMA_ACCESS_TOKEN=figd_...
+npx jfs-extract-modes "<the pasted Figma URL>" --out modes.json
+```
+
+If `npx` cannot find the bin (e.g. unusual monorepo setup), call the script by
+its path inside the installed package:
+
+```bash
+node node_modules/jfs-components/scripts/extract-figma-modes.js "<figma-url>" --out modes.json
+```
+
+The output is a flat list — one entry per layer that has explicit modes:
+
+```json
+{
+  "modes": [
+    { "layer": "Icon Button", "nodeId": "1:10638",
+      "path": "CC / Unsub > AppBar > Slot 2 > Icon Button",
+      "modes": { "Button / Size": "S", "Emphasis": "Low", "AppearanceBrand": "Neutral" } }
+  ]
+}
+```
+
+Rules for using it:
+
+- Children inherit ancestor modes unless they set their own. To get the
+  effective modes of any layer, merge every entry whose `path` is a prefix of
+  that layer's path, top-down.
+- Correlate entries with the Figma MCP structure by layer name and position;
+  use `nodeId` when two layers share a name.
+- If the output contains an `unresolved` array, STOP and report it to the user
+  before building. It means the packaged variables JSON is out of date and the
+  screen cannot be built faithfully. Do not guess missing modes.
+
+## Step 3 — Build the screen
+
+Implement with `jfs-components` components, mapping Figma component names to
+library exports.
+
+**Modes are non-negotiable.** Apply every extracted mode exactly as given —
+collection name → mode name, on exactly the layer (or subtree) the extractor
+reported. There is zero tolerance for inconsistency here:
+
+- Do not substitute a "close enough" mode (`Emphasis: Medium` is not
+  `Emphasis: Low`).
+- Do not drop modes that seem redundant — if the design sets
+  `AppearanceBrand: Neutral` on one Icon Button and `Appearance: Primary` on
+  another, those are different and intentional.
+- Do not apply a child's modes to its parent or vice versa.
+
+For everything else (spacing, order, text, icons, variants, props), follow the
+Figma MCP output one-to-one. Reuse existing screens in the consuming app as
+convention references for file placement, navigation registration, and asset
+handling.
+
+## Step 4 — QA against the design (mandatory, never skip)
+
+After the screen compiles and renders, you MUST verify it visually against the
+Step 1 screenshot:
+
+- **Native app:** use the mobile MCP — launch the app, navigate to the new
+  screen, and take a screenshot (`mobile_take_screenshot`).
+- **Web deployment:** use the browser tooling — navigate to the deployed/dev
+  URL and take a screenshot.
+
+Compare your screenshot with the Figma screenshot side by side. Check:
+
+1. Component sizes and emphasis levels (these are where wrong modes show up)
+2. Colors / appearance (brand vs neutral vs secondary treatments)
+3. Spacing, padding, and gaps
+4. Text content and truncation
+5. Icon choices and visibility (some layers in the design are hidden)
+
+If there is ANY visible difference, fix it and re-screenshot. Repeat until the
+implementation matches the design. Typical root causes, in order of
+likelihood: a mode applied to the wrong layer, a missing mode (falling back to
+the collection default), a wrong variant, a wrong icon.
+
+## Summary contract
+
+| Step | Tool | Skippable? |
+|---|---|---|
+| Design context + screenshot | Figma MCP | No |
+| Mode extraction | `npx jfs-extract-modes` | No |
+| Build | jfs-components | — |
+| Visual QA loop | Mobile MCP or browser | No |
+
+Report back to the user with: the screen file(s) created, the modes applied per
+layer, and the final QA screenshot comparison.

package/lib/commonjs/components/CategoryCard/CategoryCard.js

@@ -0,0 +1,264 @@
+"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 _webPlatformUtils = require("../../utils/web-platform-utils");
+var _Badge = _interopRequireDefault(require("../Badge/Badge"));
+var _Image = _interopRequireDefault(require("../Image/Image"));
+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 CATEGORY_CARD_STATE = 'Category Card State';
+const BADGE_OVERLAP = 11;
+const DEFAULT_CARD_WIDTH = 60;
+
+// Default modes from the Figma CategoryCard component. Overridable via `modes`.
+const CATEGORY_CARD_DEFAULT_MODES = Object.freeze({
+  AppearanceBrand: 'Tertiary',
+  'Badge Size': 'Small',
+  Context4: 'Badge',
+  "Radius": "None"
+});
+const toNumber = (value, fallback) => {
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : fallback;
+  }
+  if (typeof value === 'string') {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+  }
+  return fallback;
+};
+const toFontWeight = (value, fallback) => {
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'string') return value;
+  return fallback;
+};
+function resolveCategoryCardTokens(modes, active) {
+  const idleModes = {
+    ...modes,
+    [CATEGORY_CARD_STATE]: 'Idle'
+  };
+  const activeModes = {
+    ...modes,
+    [CATEGORY_CARD_STATE]: 'Active'
+  };
+  const resolvedModes = active ? activeModes : idleModes;
+  const gap = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/gap', resolvedModes), 6);
+  const paddingHorizontal = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/padding/horizontal', resolvedModes), 8);
+  const paddingVertical = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/padding/vertical', resolvedModes), 8);
+  const radius = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/radius', resolvedModes), 8);
+  const strokeWidth = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/strokeWidth', resolvedModes), 1);
+  const strokeColor = (0, _figmaVariablesResolver.getVariableByName)('cardTab/stroke/color', resolvedModes) ?? '#f5f5f5';
+  const idleBackground = (0, _figmaVariablesResolver.getVariableByName)('cardTab/background/color', idleModes) ?? '#ffffff';
+  const activeBackground = (0, _figmaVariablesResolver.getVariableByName)('cardTab/background/color', activeModes) ?? '#f5f5f5';
+  const backgroundColor = active ? activeBackground : idleBackground;
+  const imageSize = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/image/width', resolvedModes), 36);
+  const imageRadius = toNumber((0, _figmaVariablesResolver.getVariableByName)('image/radius', resolvedModes), 0);
+  const fontFamily = (0, _figmaVariablesResolver.getVariableByName)('cardTab/label/fontFamily', resolvedModes) ?? 'JioType Var';
+  const fontSize = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/label/fontSize', resolvedModes), 12);
+  const lineHeight = toNumber((0, _figmaVariablesResolver.getVariableByName)('cardTab/label/lineHeight', resolvedModes), Math.round(fontSize * 1.3));
+  const fontWeight = toFontWeight((0, _figmaVariablesResolver.getVariableByName)('cardTab/label/fontWeight', resolvedModes), '500');
+  const labelColor = (0, _figmaVariablesResolver.getVariableByName)('cardTab/label/color', resolvedModes) ?? '#000000';
+  return {
+    containerStyle: {
+      position: 'relative',
+      alignItems: 'center',
+      justifyContent: 'center',
+      backgroundColor,
+      borderColor: strokeColor,
+      borderWidth: strokeWidth,
+      borderStyle: 'solid',
+      borderRadius: radius,
+      paddingHorizontal,
+      paddingTop: paddingVertical,
+      paddingBottom: paddingVertical,
+      gap
+    },
+    labelStyle: {
+      color: labelColor,
+      fontFamily,
+      fontSize,
+      fontWeight,
+      lineHeight,
+      textAlign: 'center'
+    },
+    imageSize,
+    imageRadius
+  };
+}
+const pressedOverlayStyle = {
+  opacity: 0.85
+};
+const disabledOverlayStyle = {
+  opacity: 0.5
+};
+
+/**
+ * `CategoryCard` is a compact, tappable tile for category pickers and
+ * merchandising rails. It stacks a square image above a short label and can
+ * optionally show an overlapping badge at the top edge. Cards are typically
+ * laid out in a horizontal `ScrollView` or `HStack`.
+ *
+ * All visual values resolve through the `cardTab/*` design tokens with
+ * sensible Figma defaults so the card renders correctly out of the box.
+ *
+ * @component
+ * @param {CategoryCardProps} props
+ */
+function CategoryCard({
+  label = 'Popular',
+  imageSource,
+  imageSlot,
+  badge,
+  active = false,
+  width = DEFAULT_CARD_WIDTH,
+  disableTruncation,
+  singleLine,
+  onPress,
+  disabled = false,
+  modes: propModes = _reactUtils.EMPTY_MODES,
+  style,
+  labelStyle,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityState,
+  webAccessibilityProps,
+  testID,
+  ...rest
+}) {
+  const {
+    modes: globalModes
+  } = (0, _JFSThemeProvider.useTokens)();
+  const modes = (0, _react.useMemo)(() => ({
+    ...globalModes,
+    ...CATEGORY_CARD_DEFAULT_MODES,
+    ...propModes
+  }), [globalModes, propModes]);
+  const resolvedModes = (0, _react.useMemo)(() => ({
+    ...modes,
+    [CATEGORY_CARD_STATE]: active ? 'Active' : 'Idle'
+  }), [modes, active]);
+  const tokens = (0, _react.useMemo)(() => resolveCategoryCardTokens(resolvedModes, active), [resolvedModes, active]);
+  const {
+    style: labelLayoutStyle,
+    ...labelTruncation
+  } = (0, _react.useMemo)(() => (0, _reactUtils.resolveTextLayout)({
+    disableTruncation,
+    singleLine,
+    numberOfLines: 1,
+    ellipsizeMode: 'tail'
+  }), [disableTruncation, singleLine]);
+  const processedImageSlot = (0, _react.useMemo)(() => {
+    if (!imageSlot) return null;
+    const processed = (0, _reactUtils.cloneChildrenWithModes)(imageSlot, resolvedModes);
+    return processed.length === 1 ? processed[0] : processed;
+  }, [imageSlot, resolvedModes]);
+  const imageNode = processedImageSlot ?? (imageSource !== undefined ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_Image.default, {
+    imageSource: imageSource,
+    width: tokens.imageSize,
+    height: tokens.imageSize,
+    ratio: 1,
+    resizeMode: "cover",
+    borderRadius: tokens.imageRadius,
+    accessibilityElementsHidden: true,
+    importantForAccessibility: "no"
+  }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(_Image.default, {
+    imageSource: "https://www.figma.com/api/mcp/asset/0ee34871-646f-4736-be06-22fb6c0a4eed",
+    width: tokens.imageSize,
+    height: tokens.imageSize,
+    ratio: 1,
+    resizeMode: "cover",
+    borderRadius: tokens.imageRadius,
+    accessibilityElementsHidden: true,
+    importantForAccessibility: "no"
+  }));
+  const a11yLabel = accessibilityLabel ?? (badge ? `${label}, ${badge}` : label);
+  const webProps = (0, _webPlatformUtils.usePressableWebSupport)({
+    restProps: rest,
+    onPress: disabled ? undefined : onPress,
+    disabled,
+    accessibilityLabel: a11yLabel,
+    webAccessibilityProps
+  });
+  const badgeNode = badge ? /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: BADGE_ANCHOR,
+    pointerEvents: "none",
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Badge.default, {
+      label: badge,
+      modes: resolvedModes,
+      style: BADGE_CENTER_STYLE
+    })
+  }) : null;
+
+  // Truncation needs a width bound so the ellipsis engages. `singleLine`
+  // must NOT fill the content box — otherwise the text is pinned to the left
+  // padding edge and only grows rightward. Intrinsic width + centered
+  // alignment lets overflow expand equally on both sides.
+  const labelWidthStyle = singleLine ? LABEL_OVERFLOW_CENTER_STYLE : LABEL_FILL_STYLE;
+  const pressableStyle = (0, _react.useCallback)(({
+    pressed
+  }) => [tokens.containerStyle, {
+    width
+  }, badge ? {
+    marginTop: BADGE_OVERLAP
+  } : null, disabled ? disabledOverlayStyle : null, pressed && !disabled ? pressedOverlayStyle : null, style], [tokens.containerStyle, width, badge, disabled, style]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.Pressable, {
+    accessibilityRole: "button",
+    accessibilityLabel: a11yLabel,
+    accessibilityHint: accessibilityHint,
+    accessibilityState: {
+      disabled,
+      selected: active,
+      ...accessibilityState
+    },
+    onPress: onPress,
+    disabled: disabled,
+    style: pressableStyle,
+    testID: testID,
+    ...webProps,
+    children: [badgeNode, imageNode, /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+      style: [tokens.labelStyle, labelWidthStyle, labelLayoutStyle, labelStyle],
+      ...labelTruncation,
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no",
+      children: label
+    })]
+  });
+}
+const BADGE_ANCHOR = {
+  position: 'absolute',
+  top: -BADGE_OVERLAP,
+  left: 0,
+  right: 0,
+  alignItems: 'center',
+  justifyContent: 'center',
+  zIndex: 1
+};
+const BADGE_CENTER_STYLE = {
+  alignSelf: 'center'
+};
+
+/** Lets the label fill the card width so the one-line ellipsis has a bound. */
+const LABEL_FILL_STYLE = {
+  width: '100%',
+  alignSelf: 'stretch'
+};
+
+/**
+ * Intrinsic width, horizontally centred. When the label is wider than the
+ * card it overflows left and right equally instead of growing only rightward
+ * from the padded content edge.
+ */
+const LABEL_OVERFLOW_CENTER_STYLE = {
+  alignSelf: 'center',
+  textAlign: 'center'
+};
+var _default = exports.default = /*#__PURE__*/_react.default.memo(CategoryCard);