jfs-components 0.1.18 → 0.1.23

package/src/components/DebitCard/DebitCard.tsx

@@ -1,5 +1,5 @@
 import React from 'react'
-import { View, Text, Image, type ViewStyle, type TextStyle, type ImageStyle, type StyleProp, type ImageSourcePropType } from 'react-native'
+import { View, Text, Image, Pressable, type ViewStyle, type TextStyle, type ImageStyle, type StyleProp, type ImageSourcePropType } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { cloneChildrenWithModes, EMPTY_MODES } from '../../utils/react-utils'
@@ -28,6 +28,15 @@ export type DebitCardProps = {
     modes?: Modes;
     /** Container style overrides */
     style?: StyleProp<ViewStyle>;
+    /**
+     * Press handler for the whole card. When set, the card becomes pressable
+     * (rendered through a `Pressable` with `accessibilityRole="button"`).
+     */
+    onPress?: () => void;
+    /** Disable interaction when `onPress` is set. */
+    disabled?: boolean;
+    /** Accessibility label forwarded to the pressable wrapper. */
+    accessibilityLabel?: string;
 };
 
 function DebitCard({
@@ -41,6 +50,9 @@ function DebitCard({
     providerLogoSlot,
     modes: propModes = EMPTY_MODES,
     style,
+    onPress,
+    disabled,
+    accessibilityLabel,
 }: DebitCardProps) {
     const { modes: globalModes } = useTokens()
     const modes = { ...globalModes, ...propModes }
@@ -149,8 +161,8 @@ function DebitCard({
         return cardArtSource
     }, [cardArtSource])
 
-    return (
-        <View style={[containerStyle, style]}>
+    const content = (
+        <>
             <View style={headerStyle}>
                 <View style={headerLeftStyle}>
                     {bankLogoSlot ? cloneChildrenWithModes(bankLogoSlot, modes) : null}
@@ -179,6 +191,27 @@ function DebitCard({
                     <Text style={textStyle}>{expireDate}</Text>
                 </View>
             </View>
+        </>
+    )
+
+    if (onPress) {
+        return (
+            <Pressable
+                style={[containerStyle, style]}
+                onPress={onPress}
+                disabled={disabled}
+                accessibilityRole="button"
+                accessibilityLabel={accessibilityLabel ?? `${bankName} ${cardType} ${cardNumber}`}
+                accessibilityState={{ disabled: !!disabled }}
+            >
+                {content}
+            </Pressable>
+        )
+    }
+
+    return (
+        <View style={[containerStyle, style]} accessibilityLabel={accessibilityLabel}>
+            {content}
         </View>
     )
 }

package/src/components/HeroSection/HeroSection.tsx

@@ -0,0 +1,231 @@
+import React, { useMemo } from 'react'
+import { View, type StyleProp, type ViewStyle } from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+import Title from '../Title/Title'
+import InputSearch from '../InputSearch/InputSearch'
+import IconButton from '../IconButton/IconButton'
+import type { Modes } from '../../design-tokens'
+
+// The filter button in the design is a tonal "secondary" variant (light-purple
+// fill, purple icon). These modes reproduce `iconButton/background = #dbcfff`
+// and `iconButton/icon/color = #5d00b5`. Applied as defaults so the button
+// matches the Figma design out of the box; consumer-provided `modes` still win.
+const FILTER_BUTTON_MODES: Modes = {
+  AppearanceBrand: 'Secondary',
+  Emphasis: 'Medium',
+}
+
+// Inside a Hero Section the Title is flush with the section padding — the
+// `title/padding/*` tokens default to 16 but resolve to 0 in the `Page Hero`
+// context (matching the Figma design). Cascaded so the title lines up with the
+// search row instead of getting a double 16px inset.
+const TITLE_MODES: Modes = {
+  context7: 'Page Hero',
+}
+
+export type HeroSectionProps = {
+  /** Headline text rendered by the internal {@link Title}. */
+  title?: string
+  /** Optional subtitle shown below the title. Omit to hide it. */
+  subtitle?: string
+  /** Horizontal alignment of the title/subtitle block. */
+  titleTextAlign?: 'Left' | 'Center'
+  /** Whether to render the title block. Ignored when `titleSlot` is provided. */
+  showTitle?: boolean
+  /**
+   * Fully replace the default title block. When provided, `title`, `subtitle`,
+   * `titleTextAlign`, and `showTitle` are ignored. `modes` cascade into the slot.
+   */
+  titleSlot?: React.ReactNode
+
+  /**
+   * Whether to render the search + filter row. Ignored when `searchSlot`
+   * is provided.
+   */
+  showSearch?: boolean
+  /** Controlled value for the search input. */
+  searchValue?: string
+  /** Change handler for the search input. */
+  onSearchChange?: (text: string) => void
+  /** Placeholder for the search input. */
+  searchPlaceholder?: string
+  /**
+   * Fully replace the search input (the flexible left part of the row). When
+   * provided, `searchValue`, `onSearchChange`, and `searchPlaceholder` are
+   * ignored. `modes` cascade into the slot.
+   */
+  searchSlot?: React.ReactNode
+
+  /** Whether to render the trailing filter icon button. */
+  showFilter?: boolean
+  /** Icon name for the filter button (from the icon registry). */
+  filterIcon?: string
+  /** Press handler for the filter button. */
+  onFilterPress?: () => void
+  /** Accessibility label for the filter button. */
+  filterAccessibilityLabel?: string
+  /**
+   * Fully replace the trailing filter control. When provided, `filterIcon`,
+   * `onFilterPress`, and `showFilter` are ignored. `modes` cascade into the slot.
+   */
+  filterSlot?: React.ReactNode
+
+  /** Content rendered in the body area below the search row. */
+  children?: React.ReactNode
+
+  /** Mode configuration for design-token theming. */
+  modes?: Modes
+  /** Style overrides applied to the outer container. */
+  style?: StyleProp<ViewStyle>
+  testID?: string
+}
+
+/**
+ * HeroSection is a page-level header block: a title (with optional subtitle),
+ * an optional search row (a flexible search input plus a trailing filter
+ * button), and a free-form content slot below.
+ *
+ * All spacing/background values resolve from the `HeroSection / Output` design
+ * token collection via `getVariableByName`. `modes` cascade to every slot and
+ * child component so downstream tokens stay in sync.
+ *
+ * @example
+ * ```tsx
+ * <HeroSection
+ *   title="Transactions"
+ *   subtitle="Last 30 days"
+ *   searchValue={query}
+ *   onSearchChange={setQuery}
+ *   onFilterPress={openFilters}
+ * >
+ *   <TransactionList data={items} />
+ * </HeroSection>
+ * ```
+ */
+function HeroSection({
+  title = 'Page Title',
+  subtitle = 'Subtitle',
+  titleTextAlign = 'Left',
+  showTitle = true,
+  titleSlot,
+  showSearch = true,
+  searchValue,
+  onSearchChange,
+  searchPlaceholder = 'Search',
+  searchSlot,
+  showFilter = true,
+  filterIcon = 'ic_filter',
+  onFilterPress,
+  filterAccessibilityLabel = 'Filter',
+  filterSlot,
+  children,
+  modes: propModes = EMPTY_MODES,
+  style,
+  testID,
+}: HeroSectionProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = useMemo(
+    () => ({ ...globalModes, ...propModes }),
+    [globalModes, propModes]
+  )
+
+  const gap = Number(getVariableByName('heroSection/gap', modes))
+  const paddingHorizontal = Number(
+    getVariableByName('heroSection/padding/horizontal', modes)
+  )
+  const paddingVertical = Number(
+    getVariableByName('heroSection/padding/vertical', modes)
+  )
+
+  const containerStyle: ViewStyle = {
+    backgroundColor: '#ffffff',
+    flexDirection: 'column',
+    alignItems: 'flex-start',
+    gap,
+    paddingHorizontal,
+    paddingVertical,
+    width: '100%',
+  }
+
+  const titleContent = useMemo<React.ReactNode>(() => {
+    if (titleSlot !== undefined && titleSlot !== null) {
+      return cloneChildrenWithModes(titleSlot, modes)
+    }
+    if (!showTitle) return null
+    return (
+      <Title
+        title={title}
+        subtitle={subtitle}
+        textAlign={titleTextAlign}
+        modes={{ ...TITLE_MODES, ...modes }}
+      />
+    )
+  }, [titleSlot, showTitle, title, subtitle, titleTextAlign, modes])
+
+  const searchInput = useMemo<React.ReactNode>(() => {
+    if (searchSlot !== undefined && searchSlot !== null) {
+      return cloneChildrenWithModes(searchSlot, modes)
+    }
+    return (
+      <InputSearch
+        supportText={false}
+        placeholder={searchPlaceholder}
+        value={searchValue}
+        onChangeText={onSearchChange}
+        containerStyle={{ flex: 1 }}
+        modes={modes}
+      />
+    )
+  }, [searchSlot, searchPlaceholder, searchValue, onSearchChange, modes])
+
+  const filterControl = useMemo<React.ReactNode>(() => {
+    if (filterSlot !== undefined && filterSlot !== null) {
+      return cloneChildrenWithModes(filterSlot, modes)
+    }
+    if (!showFilter) return null
+    return (
+      <IconButton
+        iconName={filterIcon}
+        onPress={onFilterPress}
+        accessibilityLabel={filterAccessibilityLabel}
+        modes={{ ...FILTER_BUTTON_MODES, ...modes }}
+      />
+    )
+  }, [filterSlot, showFilter, filterIcon, onFilterPress, filterAccessibilityLabel, modes])
+
+  const searchRow =
+    searchSlot !== undefined && searchSlot !== null
+      ? true
+      : showSearch
+
+  const bodyContent = useMemo<React.ReactNode>(() => {
+    if (children === undefined || children === null) return null
+    return cloneChildrenWithModes(children, modes)
+  }, [children, modes])
+
+  return (
+    <View style={[containerStyle, style]} testID={testID}>
+      {titleContent}
+      {searchRow ? (
+        <View
+          style={{
+            flexDirection: 'row',
+            alignItems: 'center',
+            gap,
+            width: '100%',
+          }}
+        >
+          {searchInput}
+          {filterControl}
+        </View>
+      ) : null}
+      {bodyContent != null ? (
+        <View style={{ width: '100%' }}>{bodyContent}</View>
+      ) : null}
+    </View>
+  )
+}
+
+export default HeroSection

package/src/components/Image/Image.tsx

@@ -7,9 +7,23 @@ import {
   type StyleProp,
   type ViewStyle,
   type ImageResizeMode,
+  type ImageLoadEventData,
+  type ImageErrorEventData,
+  type NativeSyntheticEvent,
 } from 'react-native'
 
 type ImageResizeMethod = 'auto' | 'resize' | 'scale' | 'none'
+
+/**
+ * iOS URL cache control (maps to RN's `source.cache`, no-op on Android/web):
+ *  - `'default'`        — use the native platform's default caching.
+ *  - `'reload'`         — ignore any cache, always fetch from the network.
+ *  - `'force-cache'`    — use the cached response regardless of age; fetch
+ *                          only if absent.
+ *  - `'only-if-cached'` — use the cache only; never hit the network.
+ */
+type ImageCacheControl = 'default' | 'reload' | 'force-cache' | 'only-if-cached'
+
 import Skeleton from '../../skeleton/Skeleton'
 import { useSkeleton } from '../../skeleton/SkeletonGroup'
 
@@ -78,13 +92,43 @@ export type ImageProps = {
    * the group.
    */
   loading?: boolean | undefined
+  /**
+   * iOS URL cache strategy applied to remote (`{ uri }`) sources. Injected into
+   * the RN `source.cache` field so callers don't have to re-shape the source
+   * object themselves. No-op for local/required assets and on Android/web.
+   */
+  cache?: ImageCacheControl | undefined
+  /**
+   * Called when the image finishes loading successfully. Forwarded straight to
+   * RN's `<Image onLoad>`.
+   */
+  onLoad?: ((event: NativeSyntheticEvent<ImageLoadEventData>) => void) | undefined
+  /**
+   * Called when the image fails to load. Forwarded straight to RN's
+   * `<Image onError>`.
+   */
+  onError?:
+    | ((event: NativeSyntheticEvent<ImageErrorEventData>) => void)
+    | undefined
 }
 
 function normalizeSource(
-  imageSource: ImageProps['imageSource']
+  imageSource: ImageProps['imageSource'],
+  cache?: ImageCacheControl
 ): ImageSourcePropType | undefined {
   if (imageSource == null) return undefined
-  if (typeof imageSource === 'string') return { uri: imageSource }
+  if (typeof imageSource === 'string') {
+    return cache ? { uri: imageSource, cache } : { uri: imageSource }
+  }
+  // Only remote sources (single object with a `uri`) can carry a cache policy.
+  if (
+    cache &&
+    !Array.isArray(imageSource) &&
+    typeof imageSource === 'object' &&
+    'uri' in imageSource
+  ) {
+    return { ...imageSource, cache }
+  }
   return imageSource
 }
 
@@ -122,8 +166,14 @@ function Image({
   accessibilityElementsHidden,
   importantForAccessibility,
   loading,
+  cache,
+  onLoad,
+  onError,
 }: ImageProps) {
-  const source = useMemo(() => normalizeSource(imageSource), [imageSource])
+  const source = useMemo(
+    () => normalizeSource(imageSource, cache),
+    [imageSource, cache]
+  )
 
   // Explicit { width, height } means a "fill an exact box" layout — typically a
   // full-bleed hero/background where the asset is high-res and sharpness
@@ -173,6 +223,8 @@ function Image({
       accessibilityLabel={accessibilityLabel}
       accessibilityElementsHidden={accessibilityElementsHidden}
       importantForAccessibility={importantForAccessibility}
+      onLoad={onLoad}
+      onError={onError}
     />
   )
 }

package/src/components/Link/Link.tsx

@@ -0,0 +1,159 @@
+import React, { useCallback } from 'react'
+import { Text as RNText, type TextStyle, type StyleProp, type GestureResponderEvent } from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { EMPTY_MODES, resolveTextLayout } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
+
+export type LinkProps = {
+  /**
+   * The link label. You may also pass content as JSX children
+   * (e.g. `<Link>Terms</Link>`); when both are provided, `children` wins.
+   * Mirrors the {@link Text} API so `Link` is a near-drop-in, underlined
+   * sibling of `Text`.
+   */
+  text?: string
+  /** Child nodes (string or nested `Text`/`Link`). Wins over `text`. */
+  children?: React.ReactNode
+  /**
+   * Called when the link is activated. Navigation is the consumer's job
+   * (e.g. `Linking.openURL`, a router push) — `Link` is intentionally
+   * navigation-agnostic and React Native friendly (no `href`/`target`).
+   */
+  onPress?: (event: GestureResponderEvent) => void
+  /** Disables interaction and dims the label. */
+  disabled?: boolean
+  /**
+   * Layout sizing (matches the Figma `autolayout` variant).
+   * - `Fill` (default): the label stretches to fill the parent's width, so
+   *   `textAlign="Center"` is visible and the whole line is tappable.
+   * - `Hug`: the label hugs its content width.
+   */
+  autolayout?: 'Fill' | 'Hug'
+  /** Horizontal alignment of the label (matches `Text`). */
+  textAlign?: 'Left' | 'Center'
+  /** Modes configuration for design token resolution (cascades from `TextSegment`). */
+  modes?: Modes
+  /** Style override for the label. */
+  style?: StyleProp<TextStyle>
+  /** Number of lines to limit the label to. */
+  numberOfLines?: number
+  /** Never truncate — drops the clamp/ellipsis and lets the label overflow. See {@link Text}. */
+  disableTruncation?: boolean
+  /** Force a single non-wrapping line (implies `disableTruncation`). See {@link Text}. */
+  singleLine?: boolean
+  /** Accessibility label; defaults to the resolved text content. */
+  accessibilityLabel?: string
+  /** Accessibility hint describing what activating the link does. */
+  accessibilityHint?: string
+}
+
+const TEXT_ALIGN_MAP: Record<NonNullable<LinkProps['textAlign']>, TextStyle['textAlign']> = {
+  Left: 'left',
+  Center: 'center',
+}
+
+const DISABLED_OPACITY = 0.4
+
+/**
+ * Link — an underlined, pressable text primitive.
+ *
+ * It renders a single React Native `<Text>` (not a `Pressable`), so it flows
+ * inline and can be nested inside {@link TextSegment} exactly like a `Text`
+ * run — the React Native equivalent of an `<a>` inside a `<p>`. Font family,
+ * size, weight, line-height and letter-spacing come from the dedicated `link/*`
+ * tokens, while the colour resolves from `text/foreground` (so a link sits on
+ * the same colour as the surrounding copy). The label is always underlined.
+ *
+ * @example Standalone
+ * ```tsx
+ * <Link text="Forgot PIN?" onPress={() => navigation.navigate('ResetPin')} />
+ * ```
+ *
+ * @example Inline inside TextSegment
+ * ```tsx
+ * <TextSegment>
+ *   <Text>By continuing you agree to our </Text>
+ *   <Link onPress={openTerms}>Terms</Link>
+ *   <Text>.</Text>
+ * </TextSegment>
+ * ```
+ */
+function Link({
+  text,
+  children,
+  onPress,
+  disabled = false,
+  autolayout = 'Fill',
+  textAlign = 'Left',
+  modes = EMPTY_MODES,
+  style,
+  numberOfLines,
+  disableTruncation,
+  singleLine,
+  accessibilityLabel,
+  accessibilityHint,
+}: LinkProps) {
+  // Bindings mirror the Figma `Link` node exactly: colour from `text/foreground`
+  // (so the link matches the surrounding copy), everything else from the
+  // dedicated `link/*` tokens.
+  const foreground = getVariableByName('text/foreground', modes) ?? '#000000'
+  const fontFamily = getVariableByName('link/fontFamily', modes) ?? 'JioType Var'
+  const fontSize = getVariableByName('link/fontSize', modes) ?? 12
+  const fontWeight = getVariableByName('link/fontWeight', modes) ?? 400
+  const lineHeight = getVariableByName('link/lineHeight', modes) ?? 16
+  const letterSpacing = getVariableByName('link/letterSpacing', modes) ?? -0.5
+
+  const linkStyle: TextStyle = {
+    color: foreground as string,
+    fontFamily: fontFamily as string,
+    fontSize: fontSize as number,
+    fontWeight: String(fontWeight) as TextStyle['fontWeight'],
+    lineHeight: lineHeight as number,
+    letterSpacing: letterSpacing as number,
+    textAlign: TEXT_ALIGN_MAP[textAlign],
+    textDecorationLine: 'underline',
+    alignSelf: autolayout === 'Fill' ? 'stretch' : 'flex-start',
+    ...(disabled ? { opacity: DISABLED_OPACITY } : null),
+  }
+
+  const content =
+    children !== undefined && children !== null && children !== false
+      ? children
+      : text !== undefined
+        ? text
+        : 'Link'
+
+  const handlePress = useCallback(
+    (event: GestureResponderEvent) => {
+      if (disabled) return
+      onPress?.(event)
+    },
+    [disabled, onPress]
+  )
+
+  const { style: layoutStyle, ...truncation } = resolveTextLayout({
+    disableTruncation,
+    singleLine,
+    numberOfLines,
+  })
+
+  const resolvedLabel =
+    accessibilityLabel ?? (typeof content === 'string' ? content : undefined)
+
+  return (
+    <RNText
+      accessibilityRole="link"
+      accessibilityState={{ disabled }}
+      {...(resolvedLabel !== undefined ? { accessibilityLabel: resolvedLabel } : null)}
+      {...(accessibilityHint !== undefined ? { accessibilityHint } : null)}
+      {...(onPress !== undefined ? { onPress: handlePress } : null)}
+      disabled={disabled}
+      style={[linkStyle, style, layoutStyle]}
+      {...truncation}
+    >
+      {content}
+    </RNText>
+  )
+}
+
+export default React.memo(Link)

package/src/components/ListItem/ListItem.tsx

@@ -107,6 +107,17 @@ function resolveListItemTokens(modes: Modes): ListItemTokens {
   const paddingRight = getVariableByName('listItem/padding/right', resolvedModes) ?? 0
   const textWrapGap = (getVariableByName('listItem/text wrap', resolvedModes) ?? 0) as number
 
+  // Container surface — driven by the `List Item Style` collection
+  // (Default | Boxed | Minimal) plus `ListItem State`, `Selectable`,
+  // `Page type` and `Color Mode`. In the default style these all resolve to a
+  // transparent background / no border / 0 radius, so existing usages are
+  // visually unchanged; the "Boxed" style paints a filled, rounded, bordered
+  // surface.
+  const backgroundColor = getVariableByName('listItem/background/color', resolvedModes)
+  const borderColor = getVariableByName('listItem/border/color', resolvedModes)
+  const borderWidth = (getVariableByName('listItem/borderWidth', resolvedModes) ?? 0) as number
+  const borderRadius = (getVariableByName('listItem/radius', resolvedModes) ?? 0) as number
+
   const titleColor = getVariableByName('listItem/title/color', textModes)
   const titleFontSize = getVariableByName('listItem/title/fontSize', textModes)
   const titleLineHeight = getVariableByName('listItem/title/lineHeight', textModes)
@@ -129,6 +140,10 @@ function resolveListItemTokens(modes: Modes): ListItemTokens {
       paddingBottom: paddingBottom as number,
       paddingLeft: paddingLeft as number,
       paddingRight: paddingRight as number,
+      backgroundColor: backgroundColor as string,
+      borderColor: borderColor as string,
+      borderWidth,
+      borderRadius,
     },
     horizontalLayoutStyle: {
       flexDirection: 'row',

package/src/components/MediaCard/MediaCard.tsx

@@ -1,5 +1,5 @@
 import React, { createContext, useContext } from 'react'
-import { View, Text, StyleSheet, type ViewStyle, type TextStyle, type StyleProp, type ImageSourcePropType } from 'react-native'
+import { View, Text, Pressable, StyleSheet, type ViewStyle, type TextStyle, type StyleProp, type ImageSourcePropType } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import Image from '../Image/Image'
 import GlassFill, { type GlassTint } from '../../utils/GlassFill/GlassFill'
@@ -40,6 +40,15 @@ export interface MediaCardProps {
      * Style overrides for the card container.
      */
     style?: StyleProp<ViewStyle>
+    /**
+     * Press handler for the whole card. When set, the card becomes pressable
+     * (rendered through a `Pressable` with `accessibilityRole="button"`).
+     */
+    onPress?: () => void
+    /** Disable interaction when `onPress` is set. */
+    disabled?: boolean
+    /** Accessibility label forwarded to the pressable wrapper. */
+    accessibilityLabel?: string
 }
 
 /**
@@ -67,6 +76,9 @@ export function MediaCard({
     children,
     modes = EMPTY_MODES,
     style,
+    onPress,
+    disabled,
+    accessibilityLabel,
 }: MediaCardProps) {
     const radius = parseFloat(getVariableByName('cardMedia/radius', modes))
 
@@ -88,16 +100,35 @@ export function MediaCard({
         ) : null
     )
 
+    const content = (
+        <>
+            {background}
+            {children != null ? (
+                <View style={StyleSheet.absoluteFill} pointerEvents="box-none">
+                    {children}
+                </View>
+            ) : null}
+        </>
+    )
+
     return (
         <MediaCardContext.Provider value={{ modes }}>
-            <View style={[containerStyle, style]}>
-                {background}
-                {children != null ? (
-                    <View style={StyleSheet.absoluteFill} pointerEvents="box-none">
-                        {children}
-                    </View>
-                ) : null}
-            </View>
+            {onPress ? (
+                <Pressable
+                    style={[containerStyle, style]}
+                    onPress={onPress}
+                    disabled={disabled}
+                    accessibilityRole="button"
+                    accessibilityLabel={accessibilityLabel}
+                    accessibilityState={{ disabled: !!disabled }}
+                >
+                    {content}
+                </Pressable>
+            ) : (
+                <View style={[containerStyle, style]} accessibilityLabel={accessibilityLabel}>
+                    {content}
+                </View>
+            )}
         </MediaCardContext.Provider>
     )
 }