jfs-components 0.0.1

package/src/components/Introduction.mdx

@@ -0,0 +1,103 @@
+import { Meta } from '@storybook/addon-docs/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)
+- [Styled Components](https://styled-components.com/)
+
+---
+
+Happy coding! 🚀
+

package/src/components/LazyList/LazyList.mdx

@@ -0,0 +1,57 @@
+import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import * as LazyListStories from './LazyList.stories';
+import LazyList from './LazyList';
+import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
+
+<Meta of={LazyListStories} />
+
+# LazyList
+
+Helper function to recursively clone children and pass modes prop to components that accept it.
+
+## Available Collections and Modes
+
+This component does not use any design token collections with multiple modes.
+## Usage
+
+<Canvas>
+  <Story of={LazyListStories.Default} />
+</Canvas>
+
+
+<AccessibilitySection
+  items={[
+    'Set `accessibilityLabel`/`accessibilityHint` to describe the list content (e.g., “Saved beneficiaries”).',
+    'Ensure each child inside uses `accessibilityRole="listitem"` when interactive.',
+    'Keep reading order linear; avoid absolute positioning inside list groups.',
+  ]}
+/>
+
+<AnatomySection>
+  <ul>
+    <li><strong>List container</strong> — padded column with token spacing.</li>
+    <li><strong>listGroupsSlot</strong> — rendered children (typically `ListGroup` components).</li>
+  </ul>
+</AnatomySection>
+
+<UsageConstraintsSection
+  items={[
+    'Pass `modes` so nested groups/items share the same token set.',
+    'Prefer lightweight children; this wrapper does not virtualize scrolling.',
+    'Keep horizontal padding intact to align with the rest of the layout grid.',
+  ]}
+/>
+## Props
+
+<ArgsTable of={LazyList} />
+
+## Design Tokens
+
+This component uses the following design tokens, resolved through `getVariableByName`:
+
+- **`lazyList/gap`**
+- **`lazyList/padding/bottom`**
+- **`lazyList/padding/horizontal`**
+- **`lazyList/padding/top`**
+
+All tokens support mode-based theming through the `modes` prop.

package/src/components/LazyList/LazyList.tsx

@@ -0,0 +1,116 @@
+import React from 'react'
+import { View, type StyleProp, type ViewStyle } from 'react-native'
+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 {
+  return React.Children.map(children, (child) => {
+    if (!React.isValidElement(child)) {
+      return child
+    }
+
+    // Get existing children
+    const childProps = child.props as { children?: React.ReactNode; modes?: Record<string, any>; [key: string]: any }
+    const childChildren = childProps?.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 = childProps?.modes
+    const mergedModes = existingModes ? { ...modes, ...existingModes } : modes
+
+    // Recursively process children if they exist
+    const processedChildren = hasChildren
+      ? cloneChildrenWithModes(
+          React.Children.toArray(childChildren),
+          modes
+        )
+      : undefined
+
+    // Clone element with modes and processed children
+    return React.cloneElement(
+      child,
+      {
+        ...childProps,
+        modes: mergedModes,
+      } as any,
+      processedChildren
+    )
+  })
+}
+
+type LazyListProps = {
+  listGroupsSlot?: React.ReactNode;
+  modes?: Record<string, any>;
+  style?: StyleProp<ViewStyle>;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+} & React.ComponentProps<typeof View>;
+
+/**
+ * LazyList component that mirrors the Figma "LazyList" component.
+ *
+ * This component supports:
+ *  - **listGroupsSlot** for custom content (typically ListGroup components)
+ *  - **design-token driven styling** via `getVariableByName` and `modes`
+ *
+ * Wherever the Figma layer name contains "Slot", this component exposes a
+ * dedicated React "slot" prop:
+ *  - Slot "listGroups" → `listGroupsSlot`
+ *
+ * @component
+ * @param {Object} props
+ * @param {React.ReactNode} [props.listGroupsSlot] - Optional custom slot for list groups (Figma Slot "listGroups")
+ * @param {Object} [props.modes={}] - Modes object passed to `getVariableByName` for all design tokens
+ * @param {Object} [props.style] - Optional container style overrides
+ * @param {string} [props.accessibilityLabel] - Accessibility label for the list
+ * @param {string} [props.accessibilityHint] - Additional accessibility hint for screen readers
+ */
+function LazyList({
+  listGroupsSlot,
+  modes = {},
+  style,
+  accessibilityLabel = "List",
+  accessibilityHint,
+  ...rest
+}: LazyListProps) {
+  // Resolve container tokens
+  const paddingTop = getVariableByName('lazyList/padding/top', modes) ?? 10
+  const paddingBottom = getVariableByName('lazyList/padding/bottom', modes) ?? 10
+  const paddingHorizontal = getVariableByName('lazyList/padding/horizontal', modes) ?? 16
+  const gap = getVariableByName('lazyList/gap', modes) ?? 0
+
+  const containerStyle: ViewStyle = {
+    flexDirection: 'column',
+    alignItems: 'flex-start',
+    paddingTop,
+    paddingBottom,
+    paddingLeft: paddingHorizontal,
+    paddingRight: paddingHorizontal,
+    gap,
+  }
+
+  // Clone listGroupsSlot children and pass modes to all children that accept it
+  const processedSlot = listGroupsSlot
+    ? cloneChildrenWithModes(React.Children.toArray(listGroupsSlot), modes)
+    : null
+
+  return (
+    <View 
+      style={[containerStyle, style]}
+      accessibilityRole="list"
+      accessibilityLabel={accessibilityLabel}
+      accessibilityHint={accessibilityHint}
+      {...rest}
+    >
+      {processedSlot}
+    </View>
+  )
+}
+
+export default LazyList
+

package/src/components/ListGroup/ListGroup.mdx

@@ -0,0 +1,70 @@
+import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import * as ListGroupStories from './ListGroup.stories';
+import ListGroup from './ListGroup';
+import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
+
+<Meta of={ListGroupStories} />
+
+# ListGroup
+
+Helper function to recursively clone children and pass modes prop to components that accept it.
+
+## 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.
+
+### Title Level
+- **Modes:** Default | Bold
+- **Default:** Default
+
+### Color Mode
+- **Modes:** Light | Dark
+- **Default:** Light
+## Usage
+
+<Canvas>
+  <Story of={ListGroupStories.Default} />
+</Canvas>
+
+
+<AccessibilitySection
+  items={[
+    'Provide `accessibilityLabel` (defaults to the label) to describe the group content.',
+    'Ensure each child row exposes a listitem role; keep label announcements concise.',
+    'Use `accessibilityHint` when the group header is pressable or collapsible in your usage.',
+  ]}
+/>
+
+<AnatomySection>
+  <ul>
+    <li><strong>Label</strong> — optional heading text above the group.</li>
+    <li><strong>List group slot</strong> — stacked children spaced by token gap.</li>
+  </ul>
+</AnatomySection>
+
+<UsageConstraintsSection
+  items={[
+    'Keep child width at 100% for consistent alignment; avoid nesting additional padding wrappers.',
+    'Forward `modes` so rows inherit the same theme and typography.',
+    'Avoid empty groups; hide the component when no items exist.',
+  ]}
+/>
+## Props
+
+<ArgsTable of={ListGroup} />
+
+## Design Tokens
+
+This component uses the following design tokens, resolved through `getVariableByName`:
+
+- **`listGroup/background`**
+- **`listGroup/border/color`**
+- **`listGroup/borderWidth`**
+- **`listGroup/fontFamily`**
+- **`listGroup/fontSize`**
+- **`listGroup/fontWeight`**
+- **`listGroup/gap`**
+- **`listGroup/label/color`**
+- **`listGroup/lineHeight`**
+
+All tokens support mode-based theming through the `modes` prop.

package/src/components/ListGroup/ListGroup.tsx

@@ -0,0 +1,170 @@
+import React from 'react'
+import { View, Text, type StyleProp, type ViewStyle } from 'react-native'
+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 || []
+}
+
+type ListGroupProps = {
+  label?: string;
+  listGroupSlot?: React.ReactNode;
+  modes?: Record<string, any>;
+  style?: StyleProp<ViewStyle>;
+  accessibilityLabel?: string;
+  accessibilityHint?: string;
+} & React.ComponentProps<typeof View>;
+
+/**
+ * ListGroup component that mirrors the Figma "List Group" component.
+ *
+ * This component supports:
+ *  - **label** text at the top
+ *  - **listGroupSlot** for custom content (typically ListItem components)
+ *  - **design-token driven styling** via `getVariableByName` and `modes`
+ *
+ * Wherever the Figma layer name contains "Slot", this component exposes a
+ * dedicated React "slot" prop:
+ *  - Slot "List group" → `listGroupSlot`
+ *
+ * @component
+ * @param {Object} props
+ * @param {string} [props.label=''] - Label text displayed at the top of the list group
+ * @param {React.ReactNode} [props.listGroupSlot] - Optional custom slot for list items (Figma Slot "List group")
+ * @param {Object} [props.modes={}] - Modes object passed to `getVariableByName` for all design tokens
+ * @param {Object} [props.style] - Optional container style overrides
+ * @param {string} [props.accessibilityLabel] - Accessibility label for the list group. If not provided, uses label
+ * @param {string} [props.accessibilityHint] - Additional accessibility hint for screen readers
+ */
+function ListGroup({
+  label = '',
+  listGroupSlot,
+  modes = {},
+  style,
+  accessibilityLabel,
+  accessibilityHint,
+  ...rest
+}: ListGroupProps) {
+  // Resolve container tokens
+  const backgroundColor = getVariableByName('listGroup/background', modes) || 'rgba(255,255,255,0)'
+  const borderColor = getVariableByName('listGroup/border/color', modes) || 'rgba(255,255,255,0)'
+  const borderWidth = getVariableByName('listGroup/borderWidth', modes) || 0
+  const gap = getVariableByName('listGroup/gap', modes) || 12
+
+  // Resolve label typography tokens
+  const labelColor = getVariableByName('listGroup/label/color', modes) || '#24262b'
+  const labelFontSize = getVariableByName('listGroup/fontSize', modes) || 14
+  const labelLineHeight = getVariableByName('listGroup/lineHeight', modes) || 18
+  const labelFontFamily = getVariableByName('listGroup/fontFamily', modes) || 'System'
+  const labelFontWeightRaw = getVariableByName('listGroup/fontWeight', modes) || 500
+  const labelFontWeight = typeof labelFontWeightRaw === 'number' ? labelFontWeightRaw.toString() : labelFontWeightRaw
+
+  const containerStyle: ViewStyle = {
+    backgroundColor,
+    borderColor,
+    borderWidth,
+    borderStyle: 'solid' as const,
+    flexDirection: 'column',
+    alignItems: 'flex-start',
+    width: '100%',
+  }
+
+  const labelStyle = {
+    color: labelColor,
+    fontSize: labelFontSize,
+    lineHeight: labelLineHeight,
+    fontFamily: labelFontFamily,
+    fontWeight: labelFontWeight,
+  }
+
+  // Clone listGroupSlot children and pass modes to all children that accept it
+  const processedSlot = listGroupSlot
+    ? cloneChildrenWithModes(React.Children.toArray(listGroupSlot), modes)
+    : null
+
+  // Use provided accessibilityLabel or fall back to label
+  const defaultAccessibilityLabel = accessibilityLabel || label || "List group"
+
+  return (
+    <View 
+      style={[containerStyle, style]}
+      accessibilityRole="list"
+      accessibilityLabel={defaultAccessibilityLabel}
+      accessibilityHint={accessibilityHint}
+      {...rest}
+    >
+      {label ? (
+        <Text 
+          style={[labelStyle, processedSlot && { marginBottom: gap }]} 
+          numberOfLines={1}
+          accessibilityElementsHidden={true}
+          importantForAccessibility="no"
+        >
+          {label}
+        </Text>
+      ) : null}
+      {processedSlot ? (
+        <View style={{ width: '100%' }}>
+          {React.Children.toArray(processedSlot).map((child, index) => {
+            if (!React.isValidElement(child)) {
+              return child
+            }
+            // Wrap each item in a View with marginBottom (except last)
+            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}
+              </View>
+            )
+          })}
+        </View>
+      ) : null}
+    </View>
+  )
+}
+
+export default ListGroup
+

package/src/components/ListItem/ListItem.mdx

@@ -0,0 +1,81 @@
+import { Meta, Story, Canvas, PureArgsTable as ArgsTable } from '@storybook/addon-docs/blocks';
+import * as ListItemStories from './ListItem.stories';
+import ListItem from './ListItem';
+import { AccessibilitySection, AnatomySection, UsageConstraintsSection } from '../docs/DocSections';
+
+<Meta of={ListItemStories} />
+
+# ListItem
+
+Helper function to recursively clone children and pass modes prop to components that accept it.
+
+## 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.
+
+### List Item Style
+- **Modes:** Minimal | Boxed
+- **Default:** Minimal
+
+### Appearance.Brand
+- **Modes:** Primary | Secondary | Neutral
+- **Default:** Primary
+
+### Color Mode
+- **Modes:** Light | Dark
+- **Default:** Light
+## Usage
+
+<Canvas>
+  <Story of={ListItemStories.Default} />
+</Canvas>
+
+
+<AccessibilitySection
+  items={[
+    'Supply `accessibilityLabel` when the title/subtitle are truncated; otherwise the visible title is announced.',
+    'Expose `accessibilityRole` based on behavior (button when pressable, text when static).',
+    'Announce selection or disabled state with `accessibilityState` when applicable.',
+  ]}
+/>
+
+<AnatomySection>
+  <ul>
+    <li><strong>Leading slot</strong> — optional icon/avatar.</li>
+    <li><strong>Title & support</strong> — primary and secondary text.</li>
+    <li><strong>Trailing slot</strong> — optional meta info or action affordance.</li>
+  </ul>
+</AnatomySection>
+
+<UsageConstraintsSection
+  items={[
+    'Keep titles to one line; rely on support text for secondary info.',
+    'Use the trailing slot for status or navigation chevrons, not heavy layouts.',
+    'When making the row pressable, avoid nesting other Pressables inside.',
+  ]}
+/>
+## Props
+
+<ArgsTable of={ListItem} />
+
+## Design Tokens
+
+This component uses the following design tokens, resolved through `getVariableByName`:
+
+- **`listItem/gap`**
+- **`listItem/padding/bottom`**
+- **`listItem/padding/left`**
+- **`listItem/padding/right`**
+- **`listItem/padding/top`**
+- **`listItem/supportText/color`**
+- **`listItem/supportText/fontFamily`**
+- **`listItem/supportText/fontSize`**
+- **`listItem/supportText/fontWeight`**
+- **`listItem/supportText/lineHeight`**
+- **`listItem/title/color`**
+- **`listItem/title/fontFamily`**
+- **`listItem/title/fontSize`**
+- **`listItem/title/fontWeight`**
+- **`listItem/title/lineHeight`**
+
+All tokens support mode-based theming through the `modes` prop.