jfs-components 0.1.30 → 0.1.33

package/src/components/CategoryCard/CategoryCard.tsx

@@ -0,0 +1,404 @@
+import React, { useCallback, useMemo } from 'react'
+import {
+  Pressable,
+  Text,
+  View,
+  type AccessibilityState,
+  type ImageSourcePropType,
+  type PressableStateCallbackType,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import {
+  EMPTY_MODES,
+  cloneChildrenWithModes,
+  resolveTextLayout,
+} from '../../utils/react-utils'
+import {
+  usePressableWebSupport,
+  type SafePressableProps,
+  type WebAccessibilityProps,
+} from '../../utils/web-platform-utils'
+import Badge from '../Badge/Badge'
+import Image from '../Image/Image'
+import type { Modes } from '../../design-tokens'
+
+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: unknown, fallback: number): number => {
+  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: unknown,
+  fallback: TextStyle['fontWeight']
+): TextStyle['fontWeight'] => {
+  if (typeof value === 'number') return String(value) as TextStyle['fontWeight']
+  if (typeof value === 'string') return value as TextStyle['fontWeight']
+  return fallback
+}
+
+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.
+   */
+  imageSource?: ImageSourcePropType | string
+  /**
+   * Slot replacing the default `Image`. Receives `modes` recursively so inner
+   * components inherit theming.
+   */
+  imageSlot?: 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. */
+  active?: boolean
+  /**
+   * Fixed width of the card in dp. Defaults to `60` per the Figma spec.
+   */
+  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`.
+   */
+  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`.
+   */
+  singleLine?: boolean
+  /** Press handler — the card is always a `Pressable`. */
+  onPress?: () => void
+  disabled?: boolean
+  /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+  modes?: Modes
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>
+  /** Label style override. */
+  labelStyle?: StyleProp<TextStyle>
+  accessibilityLabel?: string
+  accessibilityHint?: string
+  accessibilityState?: AccessibilityState
+  webAccessibilityProps?: WebAccessibilityProps
+  testID?: string
+}
+
+interface CategoryCardTokens {
+  containerStyle: ViewStyle
+  labelStyle: TextStyle
+  imageSize: 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)
+  const paddingHorizontal = toNumber(
+    getVariableByName('cardTab/padding/horizontal', resolvedModes),
+    8
+  )
+  const paddingVertical = toNumber(
+    getVariableByName('cardTab/padding/vertical', resolvedModes),
+    8
+  )
+  const radius = toNumber(getVariableByName('cardTab/radius', resolvedModes), 8)
+  const strokeWidth = toNumber(
+    getVariableByName('cardTab/strokeWidth', resolvedModes),
+    1
+  )
+  const strokeColor =
+    (getVariableByName('cardTab/stroke/color', resolvedModes) as string | null) ??
+    '#f5f5f5'
+
+  const idleBackground =
+    (getVariableByName('cardTab/background/color', idleModes) 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),
+    36
+  )
+  const imageRadius = toNumber(
+    getVariableByName('image/radius', resolvedModes),
+    0
+  )
+
+  const fontFamily =
+    (getVariableByName('cardTab/label/fontFamily', resolvedModes) as string | null) ??
+    'JioType Var'
+  const fontSize = toNumber(
+    getVariableByName('cardTab/label/fontSize', resolvedModes),
+    12
+  )
+  const lineHeight = toNumber(
+    getVariableByName('cardTab/label/lineHeight', resolvedModes),
+    Math.round(fontSize * 1.3)
+  )
+  const fontWeight = toFontWeight(
+    getVariableByName('cardTab/label/fontWeight', resolvedModes),
+    '500'
+  )
+  const labelColor =
+    (getVariableByName('cardTab/label/color', resolvedModes) as string | null) ??
+    '#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: ViewStyle = { opacity: 0.85 }
+const disabledOverlayStyle: ViewStyle = { 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 = EMPTY_MODES,
+  style,
+  labelStyle,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityState,
+  webAccessibilityProps,
+  testID,
+  ...rest
+}: CategoryCardProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = useMemo(
+    () => ({
+      ...globalModes,
+      ...CATEGORY_CARD_DEFAULT_MODES,
+      ...propModes,
+    }),
+    [globalModes, propModes]
+  )
+
+  const resolvedModes = useMemo(
+    () => ({
+      ...modes,
+      [CATEGORY_CARD_STATE]: active ? 'Active' : 'Idle',
+    }),
+    [modes, active]
+  )
+
+  const tokens = useMemo(
+    () => resolveCategoryCardTokens(resolvedModes, active),
+    [resolvedModes, active]
+  )
+
+  const { style: labelLayoutStyle, ...labelTruncation } = useMemo(
+    () =>
+      resolveTextLayout({
+        disableTruncation,
+        singleLine,
+        numberOfLines: 1,
+        ellipsizeMode: 'tail',
+      }),
+    [disableTruncation, singleLine]
+  )
+
+  const processedImageSlot = useMemo(() => {
+    if (!imageSlot) return null
+    const processed = cloneChildrenWithModes(imageSlot, resolvedModes)
+    return processed.length === 1 ? processed[0] : processed
+  }, [imageSlot, resolvedModes])
+
+  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}
+        ratio={1}
+        resizeMode="cover"
+        borderRadius={tokens.imageRadius}
+        accessibilityElementsHidden
+        importantForAccessibility="no"
+      />
+    ))
+
+  const a11yLabel = accessibilityLabel ?? (badge ? `${label}, ${badge}` : label)
+
+  const webProps = usePressableWebSupport({
+    restProps: rest,
+    onPress: disabled ? undefined : onPress,
+    disabled,
+    accessibilityLabel: a11yLabel,
+    webAccessibilityProps,
+  })
+
+  const badgeNode = badge ? (
+    <View style={BADGE_ANCHOR} pointerEvents="none">
+      <Badge label={badge} modes={resolvedModes} style={BADGE_CENTER_STYLE} />
+    </View>
+  ) : 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 = useCallback(
+    ({ pressed }: PressableStateCallbackType): StyleProp<ViewStyle> => [
+      tokens.containerStyle,
+      { width },
+      badge ? { marginTop: BADGE_OVERLAP } : null,
+      disabled ? disabledOverlayStyle : null,
+      pressed && !disabled ? pressedOverlayStyle : null,
+      style,
+    ],
+    [tokens.containerStyle, width, badge, disabled, style]
+  )
+
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={a11yLabel}
+      accessibilityHint={accessibilityHint}
+      accessibilityState={{
+        disabled,
+        selected: active,
+        ...accessibilityState,
+      }}
+      onPress={onPress}
+      disabled={disabled}
+      style={pressableStyle}
+      testID={testID}
+      {...webProps}
+    >
+      {badgeNode}
+      {imageNode}
+      <Text
+        style={[tokens.labelStyle, labelWidthStyle, labelLayoutStyle, labelStyle]}
+        {...labelTruncation}
+        accessibilityElementsHidden
+        importantForAccessibility="no"
+      >
+        {label}
+      </Text>
+    </Pressable>
+  )
+}
+
+const BADGE_ANCHOR: ViewStyle = {
+  position: 'absolute',
+  top: -BADGE_OVERLAP,
+  left: 0,
+  right: 0,
+  alignItems: 'center',
+  justifyContent: 'center',
+  zIndex: 1,
+}
+
+const BADGE_CENTER_STYLE: ViewStyle = { alignSelf: 'center' }
+
+/** Lets the label fill the card width so the one-line ellipsis has a bound. */
+const LABEL_FILL_STYLE: TextStyle = { 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: TextStyle = {
+  alignSelf: 'center',
+  textAlign: 'center',
+}
+
+export default React.memo(CategoryCard)