jfs-components 0.0.5 → 0.0.7

package/src/components/HStack/HStack.tsx

@@ -0,0 +1,95 @@
+import React from 'react'
+import { View, StyleProp, ViewStyle, ViewProps } from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { cloneChildrenWithModes } from '../../utils/react-utils'
+
+export interface HStackProps extends ViewProps {
+    /**
+     * The content to display inside the stack.
+     */
+    children?: React.ReactNode;
+    /**
+     * Alignment of children along the cross axis (vertical for HStack).
+     * Maps to alignItems.
+     */
+    alignVertical?: ViewStyle['alignItems'];
+    /**
+     * Justification of children along the main axis (horizontal for HStack).
+     * Maps to justifyContent.
+     */
+    justifyHorizontal?: ViewStyle['justifyContent'];
+    /**
+     * Controls whether children can wrap.
+     * Maps to flexWrap.
+     */
+    wrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse';
+    /**
+     * If true, reverses the direction of the stack (row-reverse).
+     */
+    reverse?: boolean;
+    /**
+     * Prop for web semantics, often mapped to HTML tags.
+     */
+    as?: any;
+    /**
+     * Modes object to override default variable values.
+     */
+    modes?: Record<string, any>;
+}
+
+/**
+ * HStack component for horizontal layout using design token spacing.
+ */
+export const HStack = ({
+    children,
+    alignVertical,
+    justifyHorizontal,
+    wrap,
+    reverse = false,
+    as,
+    modes: propModes = {},
+    style,
+    ...rest
+}: HStackProps) => {
+    const { modes: globalModes } = useTokens()
+    const modes = { ...globalModes, ...propModes }
+
+    const paddingTop = getVariableByName('hstack/padding/top', modes)
+    const paddingBottom = getVariableByName('hstack/padding/bottom', modes)
+    const paddingLeft = getVariableByName('hstack/padding/left', modes)
+    const paddingRight = getVariableByName('hstack/padding/right', modes)
+    const gap = getVariableByName('hstack/gap', modes)
+
+    const flexWrap = typeof wrap === 'boolean' ? (wrap ? 'wrap' : 'nowrap') : wrap
+
+    const containerStyle: ViewStyle = {
+        flexDirection: reverse ? 'row-reverse' : 'row',
+        alignItems: alignVertical,
+        justifyContent: justifyHorizontal,
+        flexWrap,
+        paddingTop,
+        paddingBottom,
+        paddingLeft,
+        paddingRight,
+        gap,
+    }
+
+    // Pass modes down to children
+    const processedChildren = children
+        ? cloneChildrenWithModes(children, modes)
+        : null
+
+    const viewProps = {
+        ...rest,
+        as,
+    }
+
+    return (
+        <View style={[containerStyle, style]} {...viewProps}>
+            {processedChildren}
+        </View>
+    )
+}
+
+export default HStack

package/src/components/IconButton/IconButton.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as IconButtonStories from './IconButton.stories';
 import IconButton from './IconButton';
 import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
@@ -28,6 +28,10 @@ This component uses the following design token collections. Each collection supp
 ### Color Mode
 - **Modes:** Light | Dark
 - **Default:** Light
+
+### Colors Router
+- **Modes:** POC | Old
+- **Default:** POC
 ## Usage
 
 <Canvas>

package/src/components/IconCapsule/IconCapsule.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as IconCapsuleStories from './IconCapsule.stories';
 import IconCapsule from './IconCapsule';
 import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
@@ -17,6 +17,10 @@ This component uses the following design token collections. Each collection supp
 - **Modes:** M | L | S
 - **Default:** M
 
+### Emphasis
+- **Modes:** High | Medium | Low
+- **Default:** High
+
 ### Appearance.Brand
 - **Modes:** Primary | Secondary | Neutral
 - **Default:** Primary
@@ -24,6 +28,10 @@ This component uses the following design token collections. Each collection supp
 ### Color Mode
 - **Modes:** Light | Dark
 - **Default:** Light
+
+### Colors Router
+- **Modes:** POC | Old
+- **Default:** POC
 ## Usage
 
 <Canvas>
@@ -62,11 +70,11 @@ This component uses the following design token collections. Each collection supp
 This component uses the following design tokens, resolved through `getVariableByName`:
 
 - **`iconCapsule/background`**
+- **`iconCapsule/border/color`**
+- **`iconCapsule/border/size`**
+- **`iconCapsule/icon/color`**
 - **`iconCapsule/icon/size`**
 - **`iconCapsule/radius`**
 - **`iconCapsule/size`**
-- **`iconCapsuleborder/color`**
-- **`iconCapsuleborder/size`**
-- **`iconCapsuleicon/color`**
 
 All tokens support mode-based theming through the `modes` prop.

package/src/components/IconCapsule/IconCapsule.tsx

@@ -1,6 +1,7 @@
 import React 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 Icon from '../../icons/Icon'
 
 type IconCapsuleProps = {
@@ -38,20 +39,22 @@ type IconCapsuleProps = {
  * <IconCapsule iconName="ic_card" accessibilityLabel="Credit card icon" />
  * ```
  */
-function IconCapsule({ 
+function IconCapsule({
   iconName = "ic_card",
-  modes = {},
+  modes: propModes = {},
   accessibilityLabel,
   accessibilityRole = "image",
   ...rest
 }: IconCapsuleProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = { ...globalModes, ...propModes }
   // Resolve design tokens using the provided modes
   const size = getVariableByName('iconCapsule/size', modes) || 42
   const radius = getVariableByName('iconCapsule/radius', modes) || 9999
   const backgroundColor = getVariableByName('iconCapsule/background', modes) || '#cfa159'
-  const borderColor = getVariableByName('iconCapsuleborder/color', modes) || 'rgba(255,255,255,0)'
-  const borderSize = getVariableByName('iconCapsuleborder/size', modes) || 1
-  const iconColor = getVariableByName('iconCapsuleicon/color', modes) || '#0f0d0a'
+  const borderColor = getVariableByName('iconCapsule/border/color', modes) || 'rgba(255,255,255,0)'
+  const borderSize = getVariableByName('iconCapsule/border/size', modes) || 1
+  const iconColor = getVariableByName('iconCapsule/icon/color', modes) || '#0f0d0a'
   const iconSize = getVariableByName('iconCapsule/icon/size', modes) || 18
 
   // Convert radius to React Native format (if 9999, use size/2 for perfect circle)
@@ -72,17 +75,17 @@ function IconCapsule({
 
   // Generate default accessibility label from icon name if not provided
   const defaultAccessibilityLabel = accessibilityLabel || iconName.replace(/^ic_/, '').replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase())
-  
+
   return (
-    <View 
+    <View
       style={containerStyle}
       accessibilityRole={accessibilityRole}
       accessibilityLabel={defaultAccessibilityLabel}
       {...rest}
     >
-      <Icon 
-        name={iconName} 
-        size={iconSize} 
+      <Icon
+        name={iconName}
+        size={iconSize}
         color={iconColor}
         accessibilityElementsHidden={true}
         importantForAccessibility="no"

package/src/components/Introduction.mdx

@@ -1,102 +1,7 @@
-import { Meta } from '@storybook/addon-docs/blocks';
+import { Meta } from '@storybook/blocks';
 
 <Meta title="Introduction" />
 
-# Welcome to React Native Storybook
-
-Welcome to the component library documentation for this React Native project. This Storybook instance provides comprehensive documentation and interactive examples of all components in the application.
-
-## What is Storybook?
-
-Storybook is a tool for building UI components in isolation. It makes development, testing, and documentation easier by providing a sandbox environment where you can:
-
-- **Develop components in isolation** - Build components without worrying about app-specific dependencies
-- **Test edge cases** - Easily test components with different props and states
-- **Document components** - Create living documentation that stays in sync with your code
-- **Share with your team** - Provide a visual reference for designers and developers
-
-## Documentation Contract
-
-Every component page now follows a consistent template:
-
-- **Accessibility** — how to label, hint, and expose roles/states so assistive tech users get the right cues.
-- **Anatomy** — key slots/parts you can compose or override (leading/trailing, slots, tokens).
-- **Usage Constraints** — safe overrides, layout expectations, and behaviors to avoid.
-
-Use these sections as a checklist when creating or reviewing stories so guidance stays close to the API.
-
-## Performance Panel
-
-A lightweight performance panel is enabled for all stories. Open the **Performance** addon in the Storybook toolbar to inspect mount/remount timings and interaction costs. Use it to:
-
-- Compare render timing between variants without creating extra stories.
-- Spot regressions when props or modes change.
-- Validate that heavy children (lists, drawers, sheets) still mount within budget.
-
-## Getting Started
-
-### Running Storybook
-
-#### For Web (Development)
-```bash
-yarn storybook-web
-```
-This will start Storybook on `http://localhost:6006`
-
-#### For React Native (iOS/Android)
-```bash
-# iOS
-yarn ios
-
-# Android
-yarn android
-```
-
-### Building Storybook for Production
-```bash
-yarn build:storybook-web
-```
-
-## Component Organization
-
-Components are organized in the `src/components` directory. Each component typically includes:
-
-- **Component file** - The main component implementation
-- **Story file** - Interactive examples and test cases
-- **Documentation** - Comprehensive documentation with usage examples
-
-## Available Components
-
-### Avatar
-- **Avatar** - A flexible avatar component that displays user profile pictures or monogram initials. Supports multiple size modes and is fully integrated with Figma design tokens.
-
-### IconCapsule
-- **IconCapsule** - A flexible icon capsule component that displays an icon within a styled circular or rounded container. Supports different icons and appearance modes, fully integrated with Figma design tokens.
-
-## Documentation Features
-
-This Storybook instance includes:
-
-- ✅ **Automatic documentation** - Generated from JSDoc comments and component metadata
-- ✅ **Interactive examples** - Live, editable component examples
-- ✅ **Props documentation** - Automatic props table generation
-- ✅ **MDX support** - Rich documentation with Markdown and JSX
-
-## Best Practices
-
-When creating new components:
-
-1. **Add JSDoc comments** - Document your components with JSDoc for automatic documentation
-2. **Create stories** - Add multiple stories showing different states and use cases
-3. **Use TypeScript/PropTypes** - Define prop types for better documentation
-4. **Write MDX docs** - Create comprehensive documentation pages when needed
-
-## Resources
-
-- [Storybook Documentation](https://storybook.js.org/)
-- [React Native Storybook](https://github.com/storybookjs/react-native)
-
----
-
-Happy coding! 🚀
+# Introduction
 
+Welcome to the JFS Components Library.

package/src/components/LazyList/LazyList.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as LazyListStories from './LazyList.stories';
 import LazyList from './LazyList';
 import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';

package/src/components/ListGroup/ListGroup.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as ListGroupStories from './ListGroup.stories';
 import ListGroup from './ListGroup';
 import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
@@ -13,6 +13,10 @@ Helper function to recursively clone children and pass modes prop to components
 
 This component uses the following design token collections. Each collection supports multiple modes that can be configured via the `modes` prop.
 
+### Colors Router
+- **Modes:** POC | Old
+- **Default:** POC
+
 ### Title Level
 - **Modes:** Default | Bold
 - **Default:** Default

package/src/components/ListGroup/ListGroup.tsx

@@ -6,45 +6,7 @@ import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
  * 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.
  */
-function cloneChildrenWithModes(
-  children: React.ReactNode,
-  modes: Record<string, any>
-): React.ReactNode[] {
-  const result = React.Children.map(children, (child) => {
-    if (!React.isValidElement(child)) {
-      return child
-    }
-
-    // Get existing children
-    const childChildren = (child.props as any)?.children
-    const hasChildren = childChildren !== undefined && childChildren !== null
-
-    // 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
-    const existingModes = (child.props as any)?.modes
-    const mergedModes = existingModes ? { ...modes, ...existingModes } : modes
-
-    // Recursively process children if they exist
-    const processedChildren: React.ReactNode | undefined = hasChildren
-      ? cloneChildrenWithModes(
-          React.Children.toArray(childChildren),
-          modes
-        )
-      : undefined
-
-    // Clone element with modes and processed children
-    return React.cloneElement(
-      child,
-      {
-        ...(child.props as any),
-        modes: mergedModes,
-      },
-      processedChildren
-    )
-  })
-  return result || []
-}
+import { cloneChildrenWithModes } from '../../utils/react-utils'
 
 type ListGroupProps = {
   label?: string;
@@ -126,7 +88,7 @@ function ListGroup({
   const defaultAccessibilityLabel = accessibilityLabel || label || "List group"
 
   return (
-    <View 
+    <View
       style={[containerStyle, style]}
       accessibilityRole="list"
       accessibilityLabel={defaultAccessibilityLabel}
@@ -134,8 +96,8 @@ function ListGroup({
       {...rest}
     >
       {label ? (
-        <Text 
-          style={[labelStyle, processedSlot && { marginBottom: gap }]} 
+        <Text
+          style={[labelStyle, processedSlot && { marginBottom: gap }]}
           numberOfLines={1}
           accessibilityElementsHidden={true}
           importantForAccessibility="no"
@@ -153,7 +115,7 @@ function ListGroup({
             const items = React.Children.toArray(processedSlot)
             const isLast = index === items.length - 1
             const wrapperStyle = !isLast ? { marginBottom: gap } : {}
-            
+
             return (
               <View key={child.key || `wrapper-${index}`} style={wrapperStyle}>
                 {child}

package/src/components/ListItem/ListItem.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as ListItemStories from './ListItem.stories';
 import ListItem from './ListItem';
 import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
@@ -26,6 +26,10 @@ This component uses the following design token collections. Each collection supp
 ### Color Mode
 - **Modes:** Light | Dark
 - **Default:** Light
+
+### Colors Router
+- **Modes:** POC | Old
+- **Default:** POC
 ## Usage
 
 ### Horizontal Layout with NavArrow

package/src/components/ListItem/ListItem.tsx

@@ -12,52 +12,7 @@ import { usePressableWebSupport, type WebAccessibilityProps } from '../../utils/
  * @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>,
-  forcedModes?: Record<string, any>
-): React.ReactNode[] {
-  const result = React.Children.map(children, (child) => {
-    if (!React.isValidElement(child)) {
-      return child
-    }
-
-    // Get existing children
-    const childChildren = (child.props as any)?.children
-    const hasChildren = childChildren !== undefined && childChildren !== null
-
-    // 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,
-    // then forcedModes (if provided) are applied last and can never be overridden
-    const existingModes = (child.props as any)?.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,
-          forcedModes
-        )
-      : undefined
-
-    // Clone element with modes and processed children
-    return React.cloneElement(
-      child,
-      {
-        ...(child.props as any),
-        modes: mergedModes,
-      },
-      processedChildren
-    )
-  })
-  return result || []
-}
+import { cloneChildrenWithModes } from '../../utils/react-utils'
 
 type ListItemProps = {
   layout?: 'Vertical' | 'Horizontal';
@@ -179,15 +134,15 @@ function ListItem({
   const sharedLayoutStyle: ViewStyle =
     layout === 'Horizontal'
       ? {
-          flexDirection: 'row' as const,
-          alignItems: 'center' as const,
-          gap,
-        }
+        flexDirection: 'row' as const,
+        alignItems: 'center' as const,
+        gap,
+      }
       : {
-          flexDirection: 'column' as const,
-          alignItems: 'center' as const,
-          gap,
-        }
+        flexDirection: 'column' as const,
+        alignItems: 'center' as const,
+        gap,
+      }
 
   const innerContentBaseStyle: ViewStyle = {
     flexDirection: 'row',
@@ -224,8 +179,8 @@ function ListItem({
 
 
   // Generate default accessibility label from title and supportText if not provided
-  const defaultAccessibilityLabel = accessibilityLabel || 
-    (layout === 'Horizontal' 
+  const defaultAccessibilityLabel = accessibilityLabel ||
+    (layout === 'Horizontal'
       ? `${title}${showSupportText && supportText ? `, ${supportText}` : ''}`
       : supportText)
 
@@ -330,8 +285,8 @@ function ListItem({
           accessibilityRole="button"
           accessibilityLabel={defaultAccessibilityLabel}
           accessibilityHint={accessibilityHint}
-          accessibilityState={{ 
-            ...accessibilityState 
+          accessibilityState={{
+            ...accessibilityState
           }}
           onPress={onPress}
           style={({ pressed }) => [
@@ -374,8 +329,8 @@ function ListItem({
         accessibilityRole="button"
         accessibilityLabel={defaultAccessibilityLabel}
         accessibilityHint={accessibilityHint}
-        accessibilityState={{ 
-          ...accessibilityState 
+        accessibilityState={{
+          ...accessibilityState
         }}
         onPress={onPress}
         style={({ pressed }) => [

package/src/components/MediaCard/MediaCard.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as MediaCardStories from './MediaCard.stories';
 import MediaCard from './MediaCard';
 import { AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
@@ -13,6 +13,10 @@ This component uses the following design token collections. Each collection supp
 ### Contrast Context
 - **Modes:** on dark | on light
 - **Default:** on dark
+
+### Colors Router
+- **Modes:** POC | Old
+- **Default:** POC
 ## Usage
 
 <Canvas>

package/src/components/MerchantProfile/MerchantProfile.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as MerchantProfileStories from './MerchantProfile.stories';
 import MerchantProfile from './MerchantProfile';
 import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';

package/src/components/MoneyValue/MoneyValue.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as MoneyValueStories from './MoneyValue.stories';
 import MoneyValue from './MoneyValue';
 import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
@@ -17,8 +17,12 @@ This component uses the following design token collections. Each collection supp
 - **Modes:** Light | Dark
 - **Default:** Light
 
+### Colors Router
+- **Modes:** POC | Old
+- **Default:** POC
+
 ### Context3
-- **Modes:** Default | Transaction Bubble
+- **Modes:** Default | Transaction Bubble | Balance
 - **Default:** Default
 ## Usage
 

package/src/components/NavArrow/NavArrow.mdx

@@ -1,4 +1,4 @@
-import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import { Meta, Story, Canvas, Controls } from '@storybook/blocks';
 import * as NavArrowStories from './NavArrow.stories';
 import NavArrow from './NavArrow';
 
@@ -16,6 +16,10 @@ This component uses the following design token collections. Each collection supp
 - **Modes:** Light | Dark
 - **Default:** Light
 
+### Colors Router
+- **Modes:** POC | Old
+- **Default:** POC
+
 ### Context2
 - **Modes:** Default | AppBar
 - **Default:** Default