jfs-components 0.1.51 → 0.1.54

package/src/components/CategoryCard/CategoryCard.tsx

@@ -26,16 +26,24 @@ import Badge from '../Badge/Badge'
 import Image from '../Image/Image'
 import type { Modes } from '../../design-tokens'
 
-const CATEGORY_CARD_STATE = 'Category Card State'
+/** Canonical Figma collection that drives idle vs active chrome. */
+const CARD_TAB_STATE = 'Card Tab State'
+/**
+ * Legacy collection name used by earlier CategoryCard builds. Still accepted on
+ * `modes` so existing callers keep resolving the correct Active/Default tokens.
+ */
+const LEGACY_CARD_TAB_STATE = 'Category Card State'
+
 const BADGE_OVERLAP = 11
 const DEFAULT_CARD_WIDTH = 60
+const DEFAULT_IMAGE_ASSET = require('./assets/sample.png')
 
 // 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"
+  Radius: 'None',
 })
 
 const toNumber = (value: unknown, fallback: number): number => {
@@ -58,25 +66,67 @@ const toFontWeight = (
   return fallback
 }
 
+/**
+ * Maps any accepted state token (`Default` / `Active`, plus legacy `Idle`) onto
+ * the canonical `Card Tab State` mode names used by the variable resolver.
+ */
+const normalizeCardTabState = (
+  value: unknown
+): 'Default' | 'Active' | undefined => {
+  if (value === 'Active') return 'Active'
+  if (value === 'Default' || value === 'Idle') return 'Default'
+  return undefined
+}
+
+/**
+ * Resolves whether the card should render in the Active (gold stroke) state.
+ *
+ * Precedence (backward compatible):
+ * 1. Explicit `active` boolean prop (existing public API)
+ * 2. `modes['Card Tab State']` / legacy `modes['Category Card State']`
+ * 3. Default → idle (`Default`)
+ */
+const resolveIsActive = (
+  active: boolean | undefined,
+  propModes: Modes
+): boolean => {
+  if (typeof active === 'boolean') return active
+  const fromModes = normalizeCardTabState(
+    propModes[CARD_TAB_STATE] ?? propModes[LEGACY_CARD_TAB_STATE]
+  )
+  return fromModes === 'Active'
+}
+
 export type CategoryCardProps = SafePressableProps & {
   /** Bottom label (e.g. `"Popular"`). */
   label?: string
   /**
-   * Image shown in the card centre. Ignored when `imageSlot` is provided.
-   * Accepts a remote URL string, `{ uri }` object, or `require()`-ed asset.
+   * Image shown in the card centre. Ignored when `imageSlot` / `children` is
+   * provided. Accepts a remote URL string, `{ uri }` object, or `require()`-ed
+   * asset.
    */
   imageSource?: ImageSourcePropType | string
   /**
-   * Slot replacing the default `Image`. Receives `modes` recursively so inner
-   * components inherit theming.
+   * Slot replacing the default `Image` (Figma Image instance / Code Connect).
+   * Receives `modes` recursively so inner components inherit theming.
+   * Prefer this or `children` when swapping the media.
    */
   imageSlot?: React.ReactNode
+  /**
+   * Alias for {@link imageSlot} — the Figma image slot. When both are set,
+   * `imageSlot` wins so existing `imageSlot` callers stay authoritative.
+   */
+  children?: React.ReactNode
   /**
    * Optional badge label rendered as an overlapping pill at the top edge.
    * Omit or pass `undefined` to hide the badge.
    */
   badge?: string
-  /** Whether the card is in the selected / active state. */
+  /**
+   * Whether the card is in the selected / active state (gold stroke).
+   * When omitted, falls back to `modes['Card Tab State'] === 'Active'`
+   * (and the legacy `modes['Category Card State'] === 'Active'` alias).
+   */
   active?: boolean
   /**
    * Fixed width of the card in dp. Defaults to `60` per the Figma spec.
@@ -84,15 +134,16 @@ export type CategoryCardProps = SafePressableProps & {
   width?: number
   /**
    * When `true`, disables text truncation: the trailing ellipsis (`…`) is never
-   * shown and any `numberOfLines` clamp is ignored, so the label wraps to as many
-   * lines as it needs even when horizontal space is tight. Same behaviour as
-   * {@link Text}'s `disableTruncation`.
+   * shown and any `numberOfLines` clamp is ignored. Defaults to `true` (same
+   * overflow behaviour as {@link Text}'s `disableTruncation`). Pass `false` to
+   * restore single-line ellipsis clamping.
    */
   disableTruncation?: boolean
   /**
    * When `true`, forces the label onto a single line with no wrapping (implies
    * `disableTruncation`). On web the line overflows horizontally instead of
-   * wrapping or truncating. Same behaviour as {@link Text}'s `singleLine`.
+   * wrapping or truncating. Defaults to `true` — same API as {@link Text}'s
+   * `singleLine`. Pass `false` to allow wrapping.
    */
   singleLine?: boolean
   /** Press handler — the card is always a `Pressable`. */
@@ -114,70 +165,69 @@ export type CategoryCardProps = SafePressableProps & {
 interface CategoryCardTokens {
   containerStyle: ViewStyle
   labelStyle: TextStyle
-  imageSize: number
+  imageWidth: number
+  imageHeight: number
   imageRadius: number
 }
 
-function resolveCategoryCardTokens(
-  modes: Modes,
-  active: boolean
-): CategoryCardTokens {
-  const idleModes = { ...modes, [CATEGORY_CARD_STATE]: 'Idle' }
-  const activeModes = { ...modes, [CATEGORY_CARD_STATE]: 'Active' }
-  const resolvedModes = active ? activeModes : idleModes
-
-  const gap = toNumber(getVariableByName('cardTab/gap', resolvedModes), 6)
+function resolveCategoryCardTokens(modes: Modes): CategoryCardTokens {
+  const gap = toNumber(getVariableByName('cardTab/gap', modes), 6)
   const paddingHorizontal = toNumber(
-    getVariableByName('cardTab/padding/horizontal', resolvedModes),
+    getVariableByName('cardTab/padding/horizontal', modes),
     8
   )
   const paddingVertical = toNumber(
-    getVariableByName('cardTab/padding/vertical', resolvedModes),
+    getVariableByName('cardTab/padding/vertical', modes),
     8
   )
-  const radius = toNumber(getVariableByName('cardTab/radius', resolvedModes), 8)
+  const radius = toNumber(getVariableByName('cardTab/radius', modes), 8)
   const strokeWidth = toNumber(
-    getVariableByName('cardTab/strokeWidth', resolvedModes),
+    getVariableByName('cardTab/strokeWidth', modes),
     1
   )
+  // Active → gold (`#cea15a`); Default → grey (`#f5f5f5`). Both resolve through
+  // `Card Tab State` on `cardTab/stroke/color`.
   const strokeColor =
-    (getVariableByName('cardTab/stroke/color', resolvedModes) as string | null) ??
+    (getVariableByName('cardTab/stroke/color', modes) as string | null) ??
     '#f5f5f5'
 
-  const idleBackground =
-    (getVariableByName('cardTab/background/color', idleModes) as string | null) ??
+  // Both Idle and Active use a white surface — selection is stroke-only.
+  const backgroundColor =
+    (getVariableByName('cardTab/background/color', modes) as string | null) ??
     '#ffffff'
-  const activeBackground =
-    (getVariableByName('cardTab/background/color', activeModes) as string | null) ??
-    '#f5f5f5'
-  const backgroundColor = active ? activeBackground : idleBackground
 
-  const imageSize = toNumber(
-    getVariableByName('cardTab/image/width', resolvedModes),
+  const imageWidth = toNumber(
+    getVariableByName('cardTab/image/width', modes),
     36
   )
-  const imageRadius = toNumber(
-    getVariableByName('image/radius', resolvedModes),
-    0
+  const imageHeight = toNumber(
+    getVariableByName('cardTab/image/height', modes),
+    imageWidth
   )
+  const imageRadius = toNumber(getVariableByName('image/radius', modes), 0)
 
+  // Prefer component-scoped `cardTab/label/*` (Figma bindings). Do not fall
+  // back to bare `label/fontWeight` / `label/lineHeight` — those currently
+  // resolve from an unrelated Donut Chart collection (400 / 15.6).
   const fontFamily =
-    (getVariableByName('label/fontFamily', resolvedModes) as string | null) ??
+    (getVariableByName('cardTab/label/fontFamily', modes) as string | null) ??
+    (getVariableByName('label/fontFamily', modes) as string | null) ??
     'JioType Var'
   const fontSize = toNumber(
-    getVariableByName('label/fontSize', resolvedModes),
+    getVariableByName('cardTab/label/fontSize', modes) ??
+      getVariableByName('label/fontSize', modes),
     12
   )
   const lineHeight = toNumber(
-    getVariableByName('label/lineHeight', resolvedModes),
-    Math.round(fontSize * 1.3)
+    getVariableByName('cardTab/label/lineHeight', modes),
+    16
   )
   const fontWeight = toFontWeight(
-    getVariableByName('label/fontWeight', resolvedModes),
+    getVariableByName('cardTab/label/fontWeight', modes),
     '500'
   )
   const labelColor =
-    (getVariableByName('cardTab/label/color', resolvedModes) as string | null) ??
+    (getVariableByName('cardTab/label/color', modes) as string | null) ??
     '#000000'
 
   return {
@@ -203,7 +253,8 @@ function resolveCategoryCardTokens(
       lineHeight,
       textAlign: 'center',
     },
-    imageSize,
+    imageWidth,
+    imageHeight,
     imageRadius,
   }
 }
@@ -217,8 +268,13 @@ const disabledOverlayStyle: ViewStyle = { opacity: 0.5 }
  * 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.
+ * Selection is communicated with a gold stroke (`Card Tab State = Active`);
+ * the surface stays white in both Idle and Active. All visual values resolve
+ * through the `cardTab/*` design tokens with sensible Figma defaults so the
+ * card renders correctly out of the box.
+ *
+ * The image area is a real slot (`imageSlot` or `children`) matching the Figma
+ * Image instance — omit both to keep the default `Image`.
  *
  * @component
  * @param {CategoryCardProps} props
@@ -227,11 +283,12 @@ function CategoryCard({
   label = 'Popular',
   imageSource,
   imageSlot,
+  children,
   badge,
-  active = false,
+  active: activeProp,
   width = DEFAULT_CARD_WIDTH,
-  disableTruncation,
-  singleLine,
+  disableTruncation = true,
+  singleLine = true,
   onPress,
   disabled = false,
   modes: propModes = EMPTY_MODES,
@@ -245,28 +302,26 @@ function CategoryCard({
   ...rest
 }: CategoryCardProps) {
   const { modes: globalModes } = useTokens()
+  const active = resolveIsActive(activeProp, propModes)
+  const cardTabState = active ? 'Active' : 'Default'
+
   const modes = useMemo(
     () => ({
       ...globalModes,
       ...CATEGORY_CARD_DEFAULT_MODES,
       ...propModes,
+      // Canonical collection always wins so stroke/background tokens resolve.
+      [CARD_TAB_STATE]: cardTabState,
+      // Keep the legacy key in sync for any nested consumers still reading it.
+      [LEGACY_CARD_TAB_STATE]: active ? 'Active' : 'Idle',
     }),
-    [globalModes, propModes]
-  )
-
-  const resolvedModes = useMemo(
-    () => ({
-      ...modes,
-      [CATEGORY_CARD_STATE]: active ? 'Active' : 'Idle',
-    }),
-    [modes, active]
+    [globalModes, propModes, cardTabState, active]
   )
 
-  const tokens = useMemo(
-    () => resolveCategoryCardTokens(resolvedModes, active),
-    [resolvedModes, active]
-  )
+  const tokens = useMemo(() => resolveCategoryCardTokens(modes), [modes])
 
+  // Same layout merge order as `Text`: consumer `style` first, then layout so
+  // single-line / no-truncation overflow always wins.
   const { style: labelLayoutStyle, ...labelTruncation } = useMemo(
     () =>
       resolveTextLayout({
@@ -278,37 +333,27 @@ function CategoryCard({
     [disableTruncation, singleLine]
   )
 
+  const slotContent = imageSlot ?? children
   const processedImageSlot = useMemo(() => {
-    if (!imageSlot) return null
-    const processed = cloneChildrenWithModes(imageSlot, resolvedModes)
+    if (slotContent == null) return null
+    const processed = cloneChildrenWithModes(slotContent, modes)
     return processed.length === 1 ? processed[0] : processed
-  }, [imageSlot, resolvedModes])
+  }, [slotContent, modes])
 
   const imageNode =
     processedImageSlot ??
-    (imageSource !== undefined ? (
-      <Image
-        imageSource={imageSource}
-        width={tokens.imageSize}
-        height={tokens.imageSize}
-        ratio={1}
-        resizeMode="cover"
-        borderRadius={tokens.imageRadius}
-        accessibilityElementsHidden
-        importantForAccessibility="no"
-      />
-    ) : (
+    (
       <Image
-        imageSource="https://www.figma.com/api/mcp/asset/0ee34871-646f-4736-be06-22fb6c0a4eed"
-        width={tokens.imageSize}
-        height={tokens.imageSize}
+        imageSource={imageSource ?? DEFAULT_IMAGE_ASSET}
+        width={tokens.imageWidth}
+        height={tokens.imageHeight}
         ratio={1}
         resizeMode="cover"
         borderRadius={tokens.imageRadius}
         accessibilityElementsHidden
         importantForAccessibility="no"
       />
-    ))
+    )
 
   const a11yLabel = accessibilityLabel ?? (badge ? `${label}, ${badge}` : label)
 
@@ -322,7 +367,8 @@ function CategoryCard({
 
   const badgeNode = badge ? (
     <View style={BADGE_ANCHOR} pointerEvents="none">
-      <Badge label={badge} modes={resolvedModes} style={BADGE_CENTER_STYLE} />
+      {/* Figma Idle caps the badge at 38dp so it stays within the 60dp card. */}
+      <Badge label={badge} modes={modes} style={BADGE_STYLE} />
     </View>
   ) : null
 
@@ -365,7 +411,7 @@ function CategoryCard({
       {badgeNode}
       {imageNode}
       <Text
-        style={[tokens.labelStyle, labelWidthStyle, labelLayoutStyle, labelStyle]}
+        style={[tokens.labelStyle, labelWidthStyle, labelStyle, labelLayoutStyle]}
         {...labelTruncation}
         accessibilityElementsHidden
         importantForAccessibility="no"
@@ -386,7 +432,7 @@ const BADGE_ANCHOR: ViewStyle = {
   zIndex: 1,
 }
 
-const BADGE_CENTER_STYLE: ViewStyle = { alignSelf: 'center' }
+const BADGE_STYLE: ViewStyle = { alignSelf: 'center', maxWidth: 38 }
 
 /** Lets the label fill the card width so the one-line ellipsis has a bound. */
 const LABEL_FILL_STYLE: TextStyle = { width: '100%', alignSelf: 'stretch' }

package/src/components/CheckboxItem/CheckboxItem.tsx

@@ -6,12 +6,21 @@ import {
   type StyleProp,
   type ViewStyle,
   type TextStyle,
+  type GestureResponderEvent,
 } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
 import Checkbox from '../Checkbox/Checkbox'
 import type { Modes } from '../../design-tokens'
 
+/**
+ * Figma's Checkbox Item label slot lays out `Text` + `Link` (etc.) in a
+ * horizontal auto-layout frame with `Slot gap = XS` (2px). Consumers may still
+ * override via `modes['Slot gap']`. Applied only when resolving the slot gap —
+ * not merged into child `modes` — so nested components are unaffected.
+ */
+const LABEL_SLOT_GAP_DEFAULTS = { 'Slot gap': 'XS' } as const
+
 export type CheckboxItemProps = {
   /** Whether the checkbox is checked (controlled). */
   checked?: boolean
@@ -24,9 +33,13 @@ export type CheckboxItemProps = {
   /**
    * Content rendered in the row's label slot (between the leading and trailing
    * edges). This is the primary way to supply the label and mirrors the Figma
-   * "slot" — pass a plain string for the default token-styled label, or any
-   * custom node (e.g. a `<Text>`, a row of `<Text>` + `<Badge>`, etc.) for full
-   * control. Custom nodes receive the same `modes` as the parent.
+   * "Text" slot — pass a plain string for the default token-styled label, or any
+   * custom node(s) for full control.
+   *
+   * Multiple children are laid out in a horizontal row with `slot/gap` (Figma
+   * default `Slot gap = XS` → 2px), matching the `Text` + `Link` composition in
+   * the design. A single custom node (e.g. a vertical stack) is left as-is.
+   * Custom nodes receive the same `modes` as the parent.
    *
    * When both `children` and the legacy {@link label} prop are provided,
    * `children` wins.
@@ -44,7 +57,8 @@ export type CheckboxItemProps = {
   /**
    * Position of the checkbox control relative to the label.
    * - `'leading'` (default): checkbox is rendered on the left, then label, then optional `endSlot` on the right.
-   * - `'trailing'`: optional `endSlot` is rendered on the left, then label, then checkbox on the right.
+   * - `'trailing'`: optional `endSlot` is rendered on the left, then label, then checkbox on the right
+   *   (row uses `space-between` so the checkbox sits on the trailing edge).
    *
    * Matches the Figma "Control" variant on the Checkbox Item component.
    */
@@ -52,7 +66,8 @@ export type CheckboxItemProps = {
   /**
    * Optional content rendered in the row's end slot (e.g. a `Button`). When provided,
    * it receives the same `modes` as the parent. Wrapped in a fixed-width container
-   * matching the Figma `endSlot` design.
+   * matching the Figma `endSlot` design. Presses on the end slot do not toggle
+   * the checkbox.
    *
    * Placement depends on `control`:
    * - With `control="leading"` the slot appears on the right edge (after the label).
@@ -72,15 +87,21 @@ export type CheckboxItemProps = {
 }
 
 /**
- * CheckboxItem composes a `Checkbox`, a label and an optional `endSlot` into a
+ * CheckboxItem composes a `Checkbox`, a label slot and an optional `endSlot` into a
  * single horizontal pressable row. Pressing anywhere on the row (outside of the
- * `endSlot`) toggles the checkbox, mirroring the typical native form pattern.
+ * `endSlot` and nested interactive children such as `Link`) toggles the checkbox,
+ * mirroring the typical native form pattern.
  *
  * Use the `control` prop to swap the checkbox between the leading (left, default)
  * and trailing (right) edge of the row. The `endSlot` flips to the opposite edge.
  *
+ * The Figma default composition places `Text` + `Link` in the label slot
+ * ("I agree" + "Terms & Conditions"). Pass those as `children` — the slot lays
+ * multiple children out in a horizontal row with `slot/gap`.
+ *
  * Mirrors the Figma "Checkbox Item" component and uses the `checkboxItem/*`
- * design tokens for typography and spacing.
+ * design tokens for row spacing; string labels still resolve `checkboxItem/label/*`
+ * for backward-compatible typography.
  *
  * @component
  * @param {CheckboxItemProps} props
@@ -89,13 +110,19 @@ export type CheckboxItemProps = {
  * ```tsx
  * const [checked, setChecked] = useState(false)
  *
- * // Recommended: pass the label via the children slot.
+ * // Figma default composition — Text + Link in the label slot.
  * <CheckboxItem
  *   checked={checked}
  *   onValueChange={setChecked}
  *   control="leading"
  *   modes={{ 'Color Mode': 'Light' }}
  * >
+ *   <Text text="I agree" autolayout="Hug" />
+ *   <Link text="Terms & Conditions" autolayout="Hug" onPress={openTerms} />
+ * </CheckboxItem>
+ *
+ * // Plain string (still supported).
+ * <CheckboxItem checked={checked} onValueChange={setChecked}>
  *   Fixed deposit • 0245
  * </CheckboxItem>
  *
@@ -124,8 +151,8 @@ const CheckboxItem = forwardRef<View, CheckboxItemProps>(function CheckboxItem({
   //   2. otherwise the legacy `label` prop, whenever it was passed at all —
   //      including an explicit `null`/`false`, which (as before) hides the
   //      label entirely.
-  //   3. otherwise the Figma placeholder, so the default story still renders
-  //      something meaningful.
+  //   3. otherwise the Figma plain-string placeholder, so the default story
+  //      still renders something meaningful when no slot content is supplied.
   const hasChildren = children != null && children !== false
   const slotContent: React.ReactNode = hasChildren
     ? children
@@ -151,6 +178,12 @@ const CheckboxItem = forwardRef<View, CheckboxItemProps>(function CheckboxItem({
     (getVariableByName('checkboxItem/padding/horizontal', modes) as number | null) ?? 0
   const paddingVertical =
     (getVariableByName('checkboxItem/padding/vertical', modes) as number | null) ?? 0
+  // Label-slot internal gap — Figma uses Slot gap = XS (2). Consumer modes win.
+  const labelSlotGap =
+    (getVariableByName('slot/gap', {
+      ...LABEL_SLOT_GAP_DEFAULTS,
+      ...modes,
+    }) as number | null) ?? 2
 
   const labelColor =
     (getVariableByName('checkboxItem/foreground', modes) as string | null) ?? '#1a1c1f'
@@ -168,11 +201,17 @@ const CheckboxItem = forwardRef<View, CheckboxItemProps>(function CheckboxItem({
     flexDirection: 'row',
     alignItems: 'center',
     gap,
+    // Trailing matches Figma: space-between pins the checkbox to the far edge
+    // while the label (and optional endSlot) stay on the leading side.
+    justifyContent: isTrailing ? 'space-between' : 'flex-start',
     paddingHorizontal,
     paddingVertical,
     width: '100%',
   }
 
+  // String labels keep the historical checkboxItem/label/* typography so
+  // existing plain-string call-sites do not change visually. `flex: 1` is
+  // retained in both control modes so long labels still wrap inside the row.
   const resolvedLabelStyle: TextStyle = {
     flex: 1,
     minWidth: 0,
@@ -203,17 +242,36 @@ const CheckboxItem = forwardRef<View, CheckboxItemProps>(function CheckboxItem({
   // behaviour of the `label` prop).
   const isTextSlot =
     typeof slotContent === 'string' || typeof slotContent === 'number'
+
+  const labelSlotStyle: ViewStyle = {
+    // Grow to fill remaining row width so long content wraps. Trailing rows
+    // also set `justifyContent: 'space-between'` so the checkbox stays pinned
+    // to the far edge (Figma Control=Trailing).
+    flex: 1,
+    minWidth: 0,
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    alignItems: 'flex-start',
+    gap: labelSlotGap,
+  }
+
   const labelNode =
     slotContent == null || slotContent === false ? null : isTextSlot ? (
       <Text style={[resolvedLabelStyle, labelStyle]} selectable={false}>
         {slotContent}
       </Text>
     ) : (
-      <View style={{ flex: 1, minWidth: 0 }}>
+      <View style={labelSlotStyle}>
         {cloneChildrenWithModes(slotContent, modes)}
       </View>
     )
 
+  // Capture the end-slot responder so presses on nested actions (e.g. Button)
+  // never bubble to the row Pressable and toggle the checkbox.
+  const suppressRowToggle = useCallback((event: GestureResponderEvent) => {
+    event.stopPropagation?.()
+  }, [])
+
   const endSlotNode = endSlot ? (
     <View
       style={{
@@ -221,6 +279,8 @@ const CheckboxItem = forwardRef<View, CheckboxItemProps>(function CheckboxItem({
         flexShrink: 0,
         alignItems: 'stretch',
       }}
+      onStartShouldSetResponder={() => true}
+      onTouchEnd={suppressRowToggle}
     >
       {cloneChildrenWithModes(endSlot, modes)}
     </View>