jfs-components 0.0.99 → 0.1.2

package/src/components/ThreadHero/ThreadHero.tsx

@@ -2,6 +2,7 @@ import React, { isValidElement, cloneElement, type ReactNode } from 'react'
 import { View, Text, type ViewStyle, type TextStyle } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 export type ThreadHeroProps = {
     /** Title text, e.g. "Subhash Rajan" */
@@ -13,7 +14,7 @@ export type ThreadHeroProps = {
     /** Slot for Avatar component */
     renderAvatar?: ReactNode
     /** Modes for design token resolution */
-    modes?: Record<string, any>
+    modes?: Modes
     /** Optional container style */
     style?: ViewStyle
 }

package/src/components/Title/Title.tsx

@@ -3,6 +3,7 @@ import { View, Text, type StyleProp, type ViewStyle, type TextStyle } from 'reac
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 export type TitleProps = {
   title?: string;
@@ -10,7 +11,7 @@ export type TitleProps = {
   subtitle?: string;
   /** Horizontal alignment of the title text. */
   textAlign?: 'Left' | 'Center';
-  modes?: Record<string, any>;
+  modes?: Modes;
   style?: StyleProp<ViewStyle>;
   textStyle?: StyleProp<TextStyle>;
   /** Optional style overrides for the subtitle text. */

package/src/components/Toast/Toast.tsx

@@ -4,13 +4,14 @@ import Animated, { FadeIn, FadeOut, SlideInDown, SlideInUp } from 'react-native-
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { closeToast, type ToastPlacement } from './useToast'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 export interface ToastProps {
   id: string
   title: string
   timeout?: number | undefined
   onClose?: (() => void) | undefined
-  modes?: Record<string, any> | undefined
+  modes?: Modes | undefined
   placement?: ToastPlacement | undefined
   style?: StyleProp<ViewStyle> | undefined
 }

package/src/components/Toast/ToastProvider.tsx

@@ -3,12 +3,13 @@ import { StyleSheet, View } from 'react-native'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { useToast, type ToastPlacement } from './useToast'
 import Toast from './Toast'
+import type { Modes } from '../../design-tokens'
 
 export interface ToastProviderProps {
   children: React.ReactNode
   maxVisibleToasts?: number
   placement?: ToastPlacement
-  modes?: Record<string, any>
+  modes?: Modes
 }
 
 function ToastProvider({

package/src/components/Toast/useToast.ts

@@ -1,4 +1,5 @@
 import { useCallback, useSyncExternalStore } from 'react'
+import type { Modes } from '../../design-tokens'
 
 export type ToastPlacement = 'top' | 'bottom'
 
@@ -6,7 +7,7 @@ export interface ToastOptions {
   title: string
   timeout?: number
   onClose?: () => void
-  modes?: Record<string, any>
+  modes?: Modes
 }
 
 export interface ToastEntry {
@@ -14,7 +15,7 @@ export interface ToastEntry {
   title: string
   timeout: number
   onClose?: (() => void) | undefined
-  modes?: Record<string, any> | undefined
+  modes?: Modes | undefined
 }
 
 type Listener = () => void

package/src/components/Toggle/Toggle.tsx

@@ -8,6 +8,7 @@ import {
 } from 'react-native'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 export interface ToggleProps {
   /** Whether the toggle is on (controlled) */
@@ -19,7 +20,7 @@ export interface ToggleProps {
   /** Whether the toggle is disabled */
   disabled?: boolean
   /** Design token modes for theming */
-  modes?: Record<string, any>
+  modes?: Modes
   /** Override container styles */
   style?: StyleProp<ViewStyle>
   /** Accessibility label for screen readers */

package/src/components/Tooltip/Tooltip.tsx

@@ -22,6 +22,7 @@ import Svg, { Path } from 'react-native-svg'
 import { useSafeAreaInsets } from 'react-native-safe-area-context'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 // --- Types ---
 
@@ -49,7 +50,7 @@ type TooltipContextValue = {
   setTriggerRect: (rect: Rect | null) => void
   contentSize: Size | null
   setContentSize: (size: Size) => void
-  modes: Record<string, any>
+  modes: Modes
   placement: Placement
 }
 
@@ -81,7 +82,7 @@ function useTooltipContext() {
 
 export type TooltipProps = {
   children: ReactNode
-  modes?: Record<string, any>
+  modes?: Modes
   /** Initial visibility state (controlled) */
   open?: boolean
   /** Callback when visibility changes */

package/src/components/TransactionBubble/TransactionBubble.tsx

@@ -6,6 +6,7 @@ import TransactionStatus from '../TransactionStatus/TransactionStatus'
 import NavArrow from '../NavArrow/NavArrow'
 import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
 import { usePressableWebSupport, type WebAccessibilityProps } from '../../utils/web-platform-utils'
+import type { Modes } from '../../design-tokens'
 
 export type TransactionBubbleProps = {
   description?: string
@@ -16,7 +17,7 @@ export type TransactionBubbleProps = {
   /** Slot for the status area. When provided, replaces the default TransactionStatus + NavArrow. */
   statusSlot?: React.ReactNode
   children?: React.ReactNode
-  modes?: Record<string, any>
+  modes?: Modes
   onPress?: () => void
   style?: ViewStyle
   accessibilityLabel?: string

package/src/components/TransactionDetails/TransactionDetails.tsx

@@ -3,6 +3,7 @@ import { View, Text, type StyleProp, type ViewStyle, type TextStyle } from 'reac
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 
 import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 // ===== Item Subcomponent =====
 
@@ -12,7 +13,7 @@ export type TransactionDetailsItemProps = {
   /** The value text displayed below the label (e.g., "101674916166") */
   value?: string
   /** Modes object passed to `getVariableByName` for design token resolution */
-  modes?: Record<string, any>
+  modes?: Modes
   /** Optional container style overrides */
   style?: StyleProp<ViewStyle>
   /** Optional label text style overrides */
@@ -126,7 +127,7 @@ export type TransactionDetailsProps = {
   /** Slot for TransactionDetails.Item children */
   children?: React.ReactNode
   /** Modes object passed to `getVariableByName` for design token resolution */
-  modes?: Record<string, any>
+  modes?: Modes
   /** Optional container style overrides */
   style?: StyleProp<ViewStyle>
   /** Accessibility label for screen readers */

package/src/components/TransactionStatus/TransactionStatus.tsx

@@ -3,10 +3,11 @@ import { View, Text, type ViewStyle, type TextStyle } from 'react-native'
 import { Svg, Path } from 'react-native-svg'
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { EMPTY_MODES } from '../../utils/react-utils'
+import type { Modes } from '../../design-tokens'
 
 // --- Internal Icon Component ---
 type StatusIconProps = {
-    modes?: Record<string, any>
+    modes?: Modes
     width?: number
     height?: number
     color?: string
@@ -44,7 +45,7 @@ export type TransactionStatusProps = {
     /** Date text, e.g. "20 Mar 2025" */
     date?: string
     /** Modes for design token resolution */
-    modes?: Record<string, any>
+    modes?: Modes
     /** Optional container style */
     style?: ViewStyle
 }

package/src/components/UpiHandle/UpiHandle.tsx

@@ -16,6 +16,7 @@ import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { EMPTY_MODES } from '../../utils/react-utils'
 import MediaSource, { type UnifiedSource } from '../../utils/MediaSource'
 import Icon from '../../icons/Icon'
+import type { Modes } from '../../design-tokens'
 
 // Default static asset from the component folder.
 // Consumers can override the image via the `source` prop if needed.
@@ -30,7 +31,7 @@ const focusOverlayStyle: ViewStyle = { borderWidth: 1, borderColor: '#222' }
 
 type UpiHandleProps = {
   label?: string;
-  modes?: Record<string, any>;
+  modes?: Modes;
   showIcon?: boolean;
   iconName?: string;
   /**
@@ -62,7 +63,7 @@ interface UpiHandleTokens {
   iconPlaceholderStyle: ViewStyle;
 }
 
-function resolveUpiHandleTokens(modes: Record<string, any>): UpiHandleTokens {
+function resolveUpiHandleTokens(modes: Modes): UpiHandleTokens {
   const backgroundColor = (getVariableByName('upiHandle/background', modes) || '#f5f5f5') as string
   const radius = (getVariableByName('upiHandle/radius', modes) || 99999) as number
   const paddingLeft = (getVariableByName('upiHandle/padding/left', modes) || 4) as number

package/src/components/VStack/VStack.tsx

@@ -3,6 +3,7 @@ import { View, StyleProp, ViewStyle, ViewProps } 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'
+import type { Modes } from '../../design-tokens'
 
 export interface VStackProps extends ViewProps {
     /**
@@ -35,7 +36,7 @@ export interface VStackProps extends ViewProps {
     /**
      * Modes object to override default variable values.
      */
-    modes?: Record<string, any>;
+    modes?: Modes;
 }
 
 /**

package/src/components/docs/modeControls.tsx

@@ -0,0 +1,122 @@
+import React from 'react'
+import {
+  FIGMA_MODES,
+  FIGMA_COMPONENT_MODES,
+} from '../../design-tokens/figma-modes.generated'
+
+/**
+ * Storybook helpers that turn a component's design-token collections into real,
+ * per-collection `select` controls and merge the picked values into the `modes`
+ * prop — so authors get the same enum-driven DX in the Storybook Controls panel
+ * that the typed `modes` prop gives them in code.
+ *
+ * Fully backward compatible:
+ *   - If nothing is picked, `modes` is left exactly as the story provided it.
+ *   - Any `modes` value the story already sets WINS over a control selection,
+ *     so existing stories render identically until someone touches a control.
+ *   - The synthetic control args are stripped before they reach the component,
+ *     so they never leak in as unknown props.
+ */
+
+const UNSET = '(default)'
+
+type Collections = readonly string[]
+
+/**
+ * Resolve the list of collections to expose. Accepts a component name (looked up
+ * in the generated map), an explicit list, or both (merged + de-duplicated).
+ */
+function resolveCollections(
+  componentOrCollections: string | Collections,
+  extra: Collections = []
+): string[] {
+  const fromName =
+    typeof componentOrCollections === 'string'
+      ? FIGMA_COMPONENT_MODES[componentOrCollections] || []
+      : componentOrCollections
+  const merged = new Set<string>([...fromName, ...extra])
+  // Only keep collections that actually have more than one mode to choose from.
+  return [...merged].filter((name) => {
+    const modes = (FIGMA_MODES as Record<string, readonly string[]>)[name]
+    return Array.isArray(modes) && modes.length > 1
+  })
+}
+
+/**
+ * Build `argTypes` entries — one `select` per multi-mode collection, grouped
+ * under a "Modes" category. Spread the result into your story `meta.argTypes`.
+ */
+export function modeArgTypes(
+  componentOrCollections: string | Collections,
+  extra: Collections = []
+): Record<string, unknown> {
+  const collections = resolveCollections(componentOrCollections, extra)
+  const argTypes: Record<string, unknown> = {}
+  for (const name of collections) {
+    const modes = (FIGMA_MODES as Record<string, readonly string[]>)[name]
+    argTypes[name] = {
+      name,
+      description: `\`${name}\` collection mode`,
+      control: { type: 'select' },
+      options: [UNSET, ...modes],
+      table: { category: 'Modes' },
+    }
+  }
+  return argTypes
+}
+
+/**
+ * A decorator that merges the picked collection modes into `args.modes` and
+ * strips the synthetic control args before they reach the component.
+ */
+export function modeDecorator(
+  componentOrCollections: string | Collections,
+  extra: Collections = []
+) {
+  const collections = resolveCollections(componentOrCollections, extra)
+
+  return function ModeControlsDecorator(Story: any, context: any) {
+    const args = context?.args || {}
+    const picked: Record<string, string> = {}
+    // Start from the real story args so nothing is dropped. Passing only the
+    // synthetic keys here would REPLACE the story args in this Storybook
+    // renderer, wiping out real props (e.g. `series`, slot nodes) and leaving
+    // the component to render empty/crash.
+    const override: Record<string, unknown> = { ...args }
+
+    for (const name of collections) {
+      const value = args[name]
+      if (value && value !== UNSET) {
+        picked[name] = value
+      }
+      // Neutralise the synthetic arg so it is never spread onto the component.
+      override[name] = undefined
+    }
+
+    // Explicit story-provided modes win over control selections.
+    override.modes = { ...picked, ...(args.modes || {}) }
+
+    return <Story args={override} />
+  }
+}
+
+/**
+ * Convenience: returns `{ argTypes, decorators }` to spread directly into a
+ * story `meta`.
+ *
+ * @example
+ * const meta = {
+ *   title: 'Components/Button',
+ *   component: Button,
+ *   ...withModeControls('Button'),
+ * }
+ */
+export function withModeControls(
+  componentOrCollections: string | Collections,
+  extra: Collections = []
+): { argTypes: Record<string, unknown>; decorators: unknown[] } {
+  return {
+    argTypes: modeArgTypes(componentOrCollections, extra),
+    decorators: [modeDecorator(componentOrCollections, extra)],
+  }
+}

package/src/components/index.ts

@@ -63,6 +63,7 @@ export { default as NoteInput, type NoteInputProps } from './NoteInput/NoteInput
 export { default as Nudge, type NudgeProps } from './Nudge/Nudge';
 export { default as NavArrow } from './NavArrow/NavArrow';
 export { default as Numpad, type NumpadProps, type NumpadKeyValue } from './Numpad/Numpad';
+export { default as Overlay, type OverlayProps } from './Overlay/Overlay';
 export { default as Title, type TitleProps } from './Title/Title';
 export { default as Screen, type ScreenProps } from './Screen/Screen';
 export { default as Section } from './Section/Section';
@@ -149,6 +150,7 @@ export { default as StatItem, type StatItemProps, type StatItemLabelPosition } f
 export { default as StatGroup, type StatGroupProps, type StatGroupItem } from './StatGroup/StatGroup';
 export { default as StrengthIndicator, type StrengthIndicatorProps, type StrengthIndicatorConfidence, type StrengthIndicatorConfidenceValue } from './StrengthIndicator/StrengthIndicator';
 export { default as SummaryTile, type SummaryTileProps } from './SummaryTile/SummaryTile';
+export { default as TestimonialsCard, type TestimonialsCardProps } from './TestimonialsCard/TestimonialsCard';
 export { default as Text, type TextProps } from './Text/Text';
 export { default as SegmentedControl, type SegmentedControlProps, type SegmentedControlItem } from './SegmentedControl/SegmentedControl';
 export { default as Toggle, type ToggleProps } from './Toggle/Toggle';

package/src/design-tokens/JFSThemeProvider.tsx

@@ -1,6 +1,7 @@
 
 import React, { createContext, useContext, ReactNode, useMemo } from 'react';
 import { getVariableByName } from './figma-variables-resolver';
+import type { Modes } from './figma-modes.generated'
 
 /**
  * Shape of the TokenContext
@@ -10,7 +11,7 @@ interface TokenContextType {
      * Current active modes map
      * @example { 'Color Mode': 'Dark', 'Platform': 'mobile' }
      */
-    modes: Record<string, any>;
+    modes: Modes;
     /**
      * Helper to resolve variable by name using the current context modes.
      */
@@ -24,7 +25,7 @@ interface JFSThemeProviderProps {
      * Modes to apply globally.
      * Can be used to set 'Color Mode', 'Platform', 'Density', etc.
      */
-    modes?: Record<string, any>;
+    modes?: Modes;
     children: ReactNode;
 }
 
@@ -61,7 +62,7 @@ export const JFSThemeProvider: React.FC<JFSThemeProviderProps> = ({
  * Hook to access the current design token context.
  *
  * returns {
- *   modes: Record<string, any> - The current active modes
+ *   modes: Modes - The current active modes
  *   getVariable: (name: string) => any - Function to resolve a token value
  * }
  */