jfs-components 0.0.1 → 0.0.3

package/src/components/ListItem/ListItem.tsx

@@ -2,16 +2,20 @@ import React, { useMemo } from 'react'
 import { View, Text, Pressable, type StyleProp, type ViewStyle, type TextStyle, type AccessibilityState } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import IconCapsule from '../IconCapsule/IconCapsule'
-import Button from '../Button/Button'
+import NavArrow from '../NavArrow/NavArrow'
 import { usePressableWebSupport, type WebAccessibilityProps } from '../../utils/web-platform-utils'
 
 /**
  * Helper function to recursively clone children and pass modes prop to components that accept it.
  * This ensures that all child components in slots receive the modes prop from the parent.
+ *
+ * @param forcedModes - Optional modes that will ALWAYS be applied last, overriding any other modes.
+ *                      Useful for slots that need to enforce specific context values.
  */
 function cloneChildrenWithModes(
   children: React.ReactNode,
-  modes: Record<string, any>
+  modes: Record<string, any>,
+  forcedModes?: Record<string, any>
 ): React.ReactNode[] {
   const result = React.Children.map(children, (child) => {
     if (!React.isValidElement(child)) {
@@ -24,15 +28,21 @@ function cloneChildrenWithModes(
 
     // Clone the child with modes prop if it doesn't already have one
     // or merge with existing modes if it does
-    // Merge order: parent modes first, then child's explicit modes override them
+    // Merge order: parent modes first, then child's explicit modes override them,
+    // then forcedModes (if provided) are applied last and can never be overridden
     const existingModes = (child.props as any)?.modes
-    const mergedModes = existingModes ? { ...modes, ...existingModes } : modes
+    const mergedModes = forcedModes
+      ? { ...modes, ...(existingModes || {}), ...forcedModes }
+      : existingModes
+        ? { ...modes, ...existingModes }
+        : modes
 
     // Recursively process children if they exist
     const processedChildren: React.ReactNode | undefined = hasChildren
       ? cloneChildrenWithModes(
           React.Children.toArray(childChildren),
-          modes
+          modes,
+          forcedModes
         )
       : undefined
 
@@ -57,7 +67,8 @@ type ListItemProps = {
   leading?: React.ReactNode;
   supportSlot?: React.ReactNode;
   endSlot?: React.ReactNode;
-  showTrailing?: boolean;
+  /** Whether to show the NavArrow on the far right (Horizontal layout only). Defaults to true. */
+  navArrow?: boolean;
   modes?: Record<string, any>;
   onPress?: () => void;
   style?: StyleProp<ViewStyle>;
@@ -94,7 +105,7 @@ type ListItemProps = {
  * @param {React.ReactNode} [props.leading] - Optional leading element. Defaults to `IconCapsule`.
  * @param {React.ReactNode} [props.supportSlot] - Optional custom slot used instead of the default support text block.
  * @param {React.ReactNode} [props.endSlot] - Optional custom trailing slot (Figma Slot "end").
- * @param {boolean} [props.showTrailing=true] - When `true`, renders the default trailing Button in Horizontal layout if `endSlot` is not provided.
+ * @param {boolean} [props.navArrow=true] - Whether to show NavArrow on the far right (Horizontal layout only).
  * @param {Object} [props.modes={}] - Modes object passed to `getVariableByName` for all design tokens.
  * @param {Function} [props.onPress] - When provided, the entire item becomes pressable (navigation variant).
  * @param {Object} [props.style] - Optional container style overrides.
@@ -111,7 +122,7 @@ function ListItem({
   leading,
   supportSlot,
   endSlot,
-  showTrailing = true,
+  navArrow = true,
   modes = {},
   onPress,
   style,
@@ -275,8 +286,9 @@ function ListItem({
 
   if (layout === 'Horizontal') {
     // Process endSlot to pass modes to children
+    // Force Context: 'ListItem' - this value can never be overridden by external modes
     const processedEndSlot = endSlot
-      ? cloneChildrenWithModes(React.Children.toArray(endSlot), modes)
+      ? cloneChildrenWithModes(React.Children.toArray(endSlot), modes, { "Context": 'ListItem' })
       : []
     // Extract single element if array has one element, otherwise use array
     const trailingContent =
@@ -284,8 +296,6 @@ function ListItem({
         ? processedEndSlot.length === 1
           ? processedEndSlot[0]
           : processedEndSlot
-        : showTrailing
-        ? <Button label="Button" modes={modes} {...({} as any)} />
         : null
 
     const innerContent = (
@@ -310,6 +320,7 @@ function ListItem({
         {trailingContent ? (
           <View style={trailingWrapperStyle}>{trailingContent}</View>
         ) : null}
+        {navArrow && <NavArrow direction="Forward" modes={modes} />}
       </View>
     )
 

package/src/components/MerchantProfile/MerchantProfile.mdx

@@ -0,0 +1,139 @@
+import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import * as MerchantProfileStories from './MerchantProfile.stories';
+import MerchantProfile from './MerchantProfile';
+import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
+
+<Meta of={MerchantProfileStories} />
+
+# MerchantProfile
+
+Displays a merchant's identity in a centered vertical layout with an avatar, title, and subtitle. Commonly used on payment confirmation screens, transaction receipts, and merchant identification flows.
+
+## Props
+
+<ArgsTable of={MerchantProfile} />
+
+## Available Collections and Modes
+
+This component does not use any design token collections with multiple modes.
+## Usage
+
+The default configuration shows the typical merchant profile layout:
+
+<Canvas>
+  <Story of={MerchantProfileStories.Default} />
+</Canvas>
+
+## Examples
+
+### Short Name
+
+For merchants with shorter names:
+
+<Canvas>
+  <Story of={MerchantProfileStories.ShortName} />
+</Canvas>
+
+### Long Name
+
+Handles longer merchant names gracefully with text wrapping:
+
+<Canvas>
+  <Story of={MerchantProfileStories.LongName} />
+</Canvas>
+
+### Without Subtitle
+
+When only the merchant name is needed:
+
+<Canvas>
+  <Story of={MerchantProfileStories.WithoutSubtitle} />
+</Canvas>
+
+### Multiple Profiles
+
+Multiple profiles displayed in a list:
+
+<Canvas>
+  <Story of={MerchantProfileStories.MultipleProfiles} />
+</Canvas>
+
+## Component Usage
+
+```tsx
+import { MerchantProfile } from 'jsf-components';
+
+function PaymentConfirmation() {
+  return (
+    <View style={{ flex: 1 }}>
+      <MerchantProfile
+        title="Uber India Systems Private Limited"
+        subtitle="UPI ID: uberindia@ybl"
+        modes={{}}
+      />
+      
+      {/* Payment amount and other details */}
+    </View>
+  );
+}
+```
+
+### Custom Avatar
+
+You can customize the avatar using the `avatarProps` prop:
+
+```tsx
+<MerchantProfile
+  title="Amazon Pay"
+  subtitle="UPI ID: amazonpay@apl"
+  avatarProps={{
+    imageSource: 'https://example.com/merchant-logo.png',
+    modes: { 'Avatar Size': 'XL' },
+  }}
+/>
+```
+
+<AccessibilitySection
+  items={[
+    'The component uses `accessibilityRole="header"` to identify it as a header region.',
+    'A default accessibility label is generated from the title and subtitle.',
+    'Provide a custom `accessibilityLabel` for more context if needed.',
+    'The Avatar child component handles its own accessibility attributes.',
+  ]}
+/>
+
+<AnatomySection>
+  <ul>
+    <li><strong>Avatar</strong> — circular merchant logo/image at the top.</li>
+    <li><strong>Title</strong> — bold merchant name centered below the avatar.</li>
+    <li><strong>Subtitle</strong> — lighter text, typically the UPI ID or additional info.</li>
+  </ul>
+</AnatomySection>
+
+<UsageConstraintsSection
+  items={[
+    'Keep titles concise; very long names will wrap but may affect layout balance.',
+    'Use consistent modes across the MerchantProfile and its siblings for visual harmony.',
+    'The component is designed for centered layouts; avoid placing in left-aligned contexts.',
+    'For interactive merchant profiles (e.g., tappable), wrap in a Pressable component.',
+  ]}
+/>
+
+## Design Tokens
+
+This component uses the following design tokens, resolved through `getVariableByName`:
+
+- **`merchantProfile/gap`**
+- **`merchantProfile/padding/horizontal`**
+- **`merchantProfile/subtitle/color`**
+- **`merchantProfile/subtitle/fontFamily`**
+- **`merchantProfile/subtitle/fontSize`**
+- **`merchantProfile/subtitle/fontWeight`**
+- **`merchantProfile/subtitle/lineHeight`**
+- **`merchantProfile/title/color`**
+- **`merchantProfile/title/fontFamily`**
+- **`merchantProfile/title/fontSize`**
+- **`merchantProfile/title/fontWeight`**
+- **`merchantProfile/title/lineHeight`**
+
+All tokens support mode-based theming through the `modes` prop.

package/src/components/MerchantProfile/MerchantProfile.tsx

@@ -0,0 +1,174 @@
+import React from 'react'
+import {
+  View,
+  Text,
+  type ViewStyle,
+  type TextStyle,
+  type StyleProp,
+} from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import Avatar, { type AvatarProps } from '../Avatar/Avatar'
+
+export type MerchantProfileProps = {
+  /**
+   * The merchant's display name or title
+   */
+  title?: string
+  /**
+   * Subtitle text, typically the UPI ID or additional merchant info
+   */
+  subtitle?: string
+  /**
+   * Mode configuration passed to the token resolver.
+   * Also passed to the Avatar child component for consistent theming.
+   */
+  modes?: Record<string, any>
+  /**
+   * Optional style overrides for the container
+   */
+  style?: StyleProp<ViewStyle>
+  /**
+   * Props to pass to the Avatar component
+   */
+  avatarProps?: Partial<AvatarProps>
+  /**
+   * Accessibility label for the merchant profile region
+   */
+  accessibilityLabel?: string
+}
+
+/**
+ * MerchantProfile component that displays a merchant's identity.
+ * 
+ * This component shows a centered profile layout with:
+ * - A circular avatar image
+ * - A title (merchant name)
+ * - A subtitle (typically UPI ID)
+ * 
+ * All styling values are resolved from Figma design tokens using the provided modes.
+ * 
+ * @component
+ * @param {Object} props - Component props
+ * @param {string} [props.title="Uber India Systems Private Limited"] - The merchant's display name
+ * @param {string} [props.subtitle="UPI ID: uberindia@ybl"] - Subtitle text, typically the UPI ID
+ * @param {Object} [props.modes={}] - Mode configuration for design tokens
+ * @param {Object} [props.style] - Optional style overrides for the container
+ * @param {Object} [props.avatarProps] - Props to pass to the Avatar component
+ * @param {string} [props.accessibilityLabel] - Accessibility label for the region
+ * 
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <MerchantProfile
+ *   title="Uber India Systems Private Limited"
+ *   subtitle="UPI ID: uberindia@ybl"
+ *   modes={{}}
+ * />
+ * 
+ * // With custom avatar
+ * <MerchantProfile
+ *   title="Amazon Pay"
+ *   subtitle="UPI ID: amazonpay@apl"
+ *   avatarProps={{ imageSource: 'https://example.com/logo.png' }}
+ * />
+ * ```
+ */
+function MerchantProfile({
+  title = 'Uber India Systems Private Limited',
+  subtitle = 'UPI ID: uberindia@ybl',
+  modes = {},
+  style,
+  avatarProps,
+  accessibilityLabel,
+}: MerchantProfileProps) {
+  // Resolve design tokens with fallback values matching Figma design
+  const gap = getVariableByName('merchantProfile/gap', modes) ?? 12
+  const paddingHorizontal = getVariableByName('merchantProfile/padding/horizontal', modes) ?? 16
+
+  // Title typography tokens
+  const titleColor = getVariableByName('merchantProfile/title/color', modes) ?? '#0c0d10'
+  const titleFontSize = getVariableByName('merchantProfile/title/fontSize', modes) ?? 16
+  const titleLineHeight = getVariableByName('merchantProfile/title/lineHeight', modes) ?? 18
+  const titleFontFamily = getVariableByName('merchantProfile/title/fontFamily', modes) ?? 'System'
+  const titleFontWeightRaw = getVariableByName('merchantProfile/title/fontWeight', modes) ?? 700
+  const titleFontWeight = typeof titleFontWeightRaw === 'number'
+    ? titleFontWeightRaw.toString()
+    : titleFontWeightRaw
+
+  // Subtitle typography tokens
+  const subtitleColor = getVariableByName('merchantProfile/subtitle/color', modes) ?? '#191b1e'
+  const subtitleFontSize = getVariableByName('merchantProfile/subtitle/fontSize', modes) ?? 12
+  const subtitleLineHeight = getVariableByName('merchantProfile/subtitle/lineHeight', modes) ?? 16
+  const subtitleFontFamily = getVariableByName('merchantProfile/subtitle/fontFamily', modes) ?? 'System'
+  const subtitleFontWeightRaw = getVariableByName('merchantProfile/subtitle/fontWeight', modes) ?? 500
+  const subtitleFontWeight = typeof subtitleFontWeightRaw === 'number'
+    ? subtitleFontWeightRaw.toString()
+    : subtitleFontWeightRaw
+
+  // Container style
+  const containerStyle: ViewStyle = {
+    alignItems: 'center',
+    paddingHorizontal,
+    gap,
+  }
+
+  // Title text style
+  const titleTextStyle: TextStyle = {
+    color: titleColor,
+    fontSize: titleFontSize,
+    lineHeight: titleLineHeight,
+    fontFamily: titleFontFamily,
+    fontWeight: titleFontWeight as TextStyle['fontWeight'],
+    textAlign: 'center',
+  }
+
+  // Subtitle text style
+  const subtitleTextStyle: TextStyle = {
+    color: subtitleColor,
+    fontSize: subtitleFontSize,
+    lineHeight: subtitleLineHeight,
+    fontFamily: subtitleFontFamily,
+    fontWeight: subtitleFontWeight as TextStyle['fontWeight'],
+    textAlign: 'center',
+  }
+
+  // Default accessibility label
+  const defaultAccessibilityLabel = accessibilityLabel ||
+    `Merchant profile for ${title}${subtitle ? `, ${subtitle}` : ''}`
+
+  // Avatar modes - use provided modes to ensure consistent theming
+  // Override to use a larger avatar size for the merchant profile
+  const avatarModes = {
+    ...modes,
+    ...(avatarProps?.modes || {}),
+  }
+
+  return (
+    <View
+      style={[containerStyle, style]}
+      accessibilityRole="header"
+      accessibilityLabel={defaultAccessibilityLabel}
+    >
+      <Avatar
+        style="Image"
+        modes={avatarModes}
+        {...avatarProps}
+      />
+      <Text
+        style={titleTextStyle}
+        accessibilityRole="text"
+      >
+        {title}
+      </Text>
+      <Text
+        style={subtitleTextStyle}
+        accessibilityRole="text"
+      >
+        {subtitle}
+      </Text>
+    </View>
+  )
+}
+
+export default MerchantProfile
+

package/src/components/MoneyValue/MoneyValue.mdx

@@ -16,6 +16,10 @@ This component uses the following design token collections. Each collection supp
 ### Color Mode
 - **Modes:** Light | Dark
 - **Default:** Light
+
+### Context3
+- **Modes:** Default | Transaction Bubble
+- **Default:** Default
 ## Usage
 
 <Canvas>

package/src/components/MoneyValue/MoneyValue.tsx

@@ -40,10 +40,12 @@ const CURRENCY_SYMBOLS = {
 type MoneyValueProps = {
   value?: string | number;
   currency?: string;
+  negative?: boolean;
   modes?: Record<string, any>;
   style?: StyleProp<ViewStyle>;
   valueStyle?: StyleProp<TextStyle>;
   currencyStyle?: StyleProp<TextStyle>;
+  negativeSignStyle?: StyleProp<TextStyle>;
   accessibilityLabel?: string;
   accessibilityHint?: string;
 } & React.ComponentProps<typeof View>;
@@ -58,29 +60,54 @@ type MoneyValueProps = {
  * (e.g. "INR", "USD"). When an ISO code is provided, it will be mapped to the
  * appropriate symbol, with special care to support INR and other major currencies.
  *
+ * Negative values are auto-detected from the value prop (e.g., -500 or "-500").
+ * The `negative` prop can be used to explicitly override this behavior.
+ *
  * @component
  * @param {Object} props
- * @param {string|number} [props.value="500"] - Monetary value to display.
+ * @param {string|number} [props.value="500"] - Monetary value to display. Negative values are auto-detected.
  * @param {string} [props.currency="₹"] - Currency symbol or ISO code (e.g. "INR").
+ * @param {boolean} [props.negative] - Explicitly override negative display. If undefined, auto-detects from value.
  * @param {Object} [props.modes={}] - Modes object passed directly to `getVariableByName`.
  *                                   Example: {"MoneyValue / Theme": "Default"}
  * @param {Object} [props.style] - Optional container style overrides.
  * @param {Object} [props.valueStyle] - Optional value text style overrides.
  * @param {Object} [props.currencyStyle] - Optional currency text style overrides.
+ * @param {Object} [props.negativeSignStyle] - Optional negative sign text style overrides.
  * @param {string} [props.accessibilityLabel] - Accessibility label for screen readers. If not provided, generates from value and currency
  * @param {string} [props.accessibilityHint] - Additional accessibility hint for screen readers
  */
 function MoneyValue({
   value = '500',
   currency = '₹',
+  negative,
   modes = {},
   style,
   valueStyle,
   currencyStyle,
+  negativeSignStyle,
   accessibilityLabel,
   accessibilityHint,
   ...rest
 }: MoneyValueProps) {
+  // Auto-detect negative from value and compute display value
+  const { isNegative, displayValue } = React.useMemo(() => {
+    const stringValue = String(value)
+    const trimmed = stringValue.trim()
+    const valueIsNegative = trimmed.startsWith('-') || (typeof value === 'number' && value < 0)
+    
+    // Strip leading minus sign for display (we show it separately)
+    const absoluteValue = trimmed.startsWith('-') ? trimmed.slice(1) : trimmed
+    
+    // Use explicit negative prop if provided, otherwise use auto-detected
+    const showNegative = negative !== undefined ? negative : valueIsNegative
+    
+    return {
+      isNegative: showNegative,
+      displayValue: absoluteValue,
+    }
+  }, [value, negative])
+
   // Resolve typography and layout tokens from Figma
   const textColor =
     getVariableByName('moneyValue/text/color', modes) || '#0f0d0a'
@@ -122,7 +149,7 @@ function MoneyValue({
 
   // Generate default accessibility label from value and currency
   const defaultAccessibilityLabel = accessibilityLabel || 
-    `${resolvedCurrency} ${value}`
+    `${isNegative ? 'negative ' : ''}${resolvedCurrency} ${displayValue}`
 
   return (
     <View 
@@ -132,6 +159,15 @@ function MoneyValue({
       accessibilityHint={accessibilityHint}
       {...rest}
     >
+      {isNegative && (
+        <Text 
+          style={[baseTextStyle, negativeSignStyle]}
+          accessibilityElementsHidden={true}
+          importantForAccessibility="no"
+        >
+          -
+        </Text>
+      )}
       <Text 
         style={[baseTextStyle, currencyStyle]}
         accessibilityElementsHidden={true}
@@ -144,7 +180,7 @@ function MoneyValue({
         accessibilityElementsHidden={true}
         importantForAccessibility="no"
       >
-        {value}
+        {displayValue}
       </Text>
     </View>
   )

package/src/components/NavArrow/NavArrow.mdx

@@ -0,0 +1,123 @@
+import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import * as NavArrowStories from './NavArrow.stories';
+import NavArrow from './NavArrow';
+
+<Meta of={NavArrowStories} />
+
+# NavArrow
+
+A small navigation arrow component that displays a chevron for Back or Forward navigation. Commonly used in navigation headers, list items, or anywhere directional navigation cues are needed.
+
+## Available Collections and Modes
+
+This component uses the following design token collections. Each collection supports multiple modes that can be configured via the `modes` prop.
+
+### Color Mode
+- **Modes:** Light | Dark
+- **Default:** Light
+
+### Context2
+- **Modes:** Default | AppBar
+- **Default:** Default
+## Usage
+
+### Basic Usage
+
+<Canvas>
+  <Story of={NavArrowStories.Default} />
+</Canvas>
+
+### Direction Variants
+
+The NavArrow supports two directions:
+
+- **Back** — Left-pointing chevron (‹) for backward navigation
+- **Forward** — Right-pointing chevron (›) for forward navigation
+
+<Canvas>
+  <Story of={NavArrowStories.AllDirections} />
+</Canvas>
+
+### Usage Examples
+
+```jsx
+import { NavArrow } from 'jfs-components';
+
+// Basic back arrow
+<NavArrow direction="Back" />
+
+// Forward arrow
+<NavArrow direction="Forward" />
+
+// With custom modes (for theming)
+<NavArrow direction="Back" modes={{ 'Color Mode': 'Dark' }} />
+
+// With accessibility label
+<NavArrow 
+  direction="Back" 
+  accessibilityLabel="Navigate to previous screen" 
+/>
+```
+
+### Usage in a Header
+
+```jsx
+import { View, Text, Pressable } from 'react-native';
+import { NavArrow } from 'jfs-components';
+
+function Header({ title, onBack }) {
+  return (
+    <View style={{ flexDirection: 'row', alignItems: 'center', padding: 16 }}>
+      <Pressable onPress={onBack} style={{ padding: 8 }}>
+        <NavArrow direction="Back" />
+      </Pressable>
+      <Text style={{ marginLeft: 8, fontSize: 18, fontWeight: '600' }}>
+        {title}
+      </Text>
+    </View>
+  );
+}
+```
+
+### Usage in a List Item
+
+```jsx
+import { View, Text, Pressable } from 'react-native';
+import { NavArrow } from 'jfs-components';
+
+function NavigableListItem({ label, onPress }) {
+  return (
+    <Pressable 
+      onPress={onPress}
+      style={{ 
+        flexDirection: 'row', 
+        alignItems: 'center', 
+        justifyContent: 'space-between',
+        padding: 16 
+      }}
+    >
+      <Text>{label}</Text>
+      <NavArrow direction="Forward" />
+    </Pressable>
+  );
+}
+```
+
+## Props
+
+<ArgsTable of={NavArrow} />
+
+## Design Tokens
+
+This component uses the following design tokens, resolved through `getVariableByName`:
+
+- **`navArrow/background`**
+- **`navArrow/height`**
+- **`navArrow/icon/color`**
+- **`navArrow/icon/height`**
+- **`navArrow/icon/strokeWeight`**
+- **`navArrow/icon/width`**
+- **`navArrow/radius`**
+- **`navArrow/width`**
+
+All tokens support mode-based theming through the `modes` prop.