jfs-components 0.0.73 → 0.0.77

package/src/components/IconButton/IconButton.tsx

@@ -12,6 +12,8 @@ import Icon from '../../icons/Icon'
 import { usePressableWebSupport, type SafePressableProps, type WebAccessibilityProps } from '../../utils/web-platform-utils'
 import { EMPTY_MODES } from '../../utils/react-utils'
 import type { UnifiedSource } from '../../utils/MediaSource'
+import Skeleton from '../../skeleton/Skeleton'
+import { useSkeleton } from '../../skeleton/SkeletonGroup'
 
 type IconButtonProps = SafePressableProps & {
   /** Built-in icon name from the registry (default state). */
@@ -65,6 +67,12 @@ type IconButtonProps = SafePressableProps & {
    * Web-specific accessibility props (only used on web platform)
    */
   webAccessibilityProps?: WebAccessibilityProps;
+  /**
+   * Explicit per-instance loading override. When `true`, renders a
+   * same-size pill-shaped skeleton instead of the button. Defaults to
+   * inheriting from the surrounding `<SkeletonGroup>`.
+   */
+  loading?: boolean;
 };
 
 // ---------------------------------------------------------------------------
@@ -155,6 +163,7 @@ function IconButton({
   inactiveIcon,
   inactiveSource,
   isActive = false,
+  loading,
   ...rest
 }: IconButtonProps) {
   // Merge explicit props with modes for token resolution. Memoize the merged
@@ -174,6 +183,11 @@ function IconButton({
     [componentModes, disabled]
   )
 
+  // Hook called unconditionally — short-circuit below comes AFTER all hooks
+  // to keep React's hook order stable across renders.
+  const { active: groupActive } = useSkeleton()
+  const isLoading = loading ?? groupActive
+
   const [isFocused, setIsFocused] = useState(false)
   const [isHovered, setIsHovered] = useState(false)
 
@@ -271,6 +285,19 @@ function IconButton({
     [tokens.baseContainerStyle, style, isHovered, isFocused, disabled]
   )
 
+  if (isLoading) {
+    const size = tokens.baseContainerStyle.width as number
+    return (
+      <Skeleton
+        kind="other"
+        width={size}
+        height={size}
+        style={style as any}
+        modes={componentModes}
+      />
+    )
+  }
+
   return (
     <Pressable
       accessibilityRole="button"

package/src/components/Image/Image.tsx

@@ -8,6 +8,8 @@ import {
   type ViewStyle,
   type ImageResizeMode,
 } from 'react-native'
+import Skeleton from '../../skeleton/Skeleton'
+import { useSkeleton } from '../../skeleton/SkeletonGroup'
 
 export type ImageProps = {
   /**
@@ -52,6 +54,13 @@ export type ImageProps = {
     | 'no'
     | 'no-hide-descendants'
     | undefined
+  /**
+   * Explicit per-instance loading override. When `true`, the image renders as
+   * a skeleton placeholder at the same box size; when `false`, the
+   * surrounding `<SkeletonGroup>` is ignored. Defaults to inheriting from
+   * the group.
+   */
+  loading?: boolean | undefined
 }
 
 function normalizeSource(
@@ -94,6 +103,7 @@ function Image({
   accessibilityLabel,
   accessibilityElementsHidden,
   importantForAccessibility,
+  loading,
 }: ImageProps) {
   const source = useMemo(() => normalizeSource(imageSource), [imageSource])
 
@@ -112,6 +122,21 @@ function Image({
     return s
   }, [ratio, width, height, borderRadius])
 
+  const { active: groupActive } = useSkeleton()
+  const isLoading = loading ?? groupActive
+  if (isLoading) {
+    // Match the loaded image's exact box. If height is unknown but a ratio
+    // is set, the skeleton uses `aspectRatio` the same way the loaded image
+    // would, so layout never jumps when the load resolves.
+    const skeletonStyle: ViewStyle = {
+      width: (width ?? '100%') as ViewStyle['width'],
+      ...(height != null
+        ? { height: height as number }
+        : { aspectRatio: ratio }),
+    }
+    return <Skeleton kind="image" style={skeletonStyle} />
+  }
+
   if (!source) {
     return <View style={[layoutStyle, style as StyleProp<ViewStyle>]} />
   }

package/src/components/LottieIntroBlock/LottieIntroBlock.tsx

@@ -0,0 +1,202 @@
+import React, { useMemo } from 'react'
+import {
+  View,
+  Text,
+  type StyleProp,
+  type ViewStyle,
+  type TextStyle,
+} from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import Button from '../Button/Button'
+import { EMPTY_MODES, cloneChildrenWithModes } from '../../utils/react-utils'
+
+const DEFAULT_MEDIA_SIZE = 117
+
+export type LottieIntroBlockProps = {
+  /** Headline text shown below the media area. */
+  title?: string
+  /** Whether to render the supportive paragraph below the title. */
+  showSupportText?: boolean
+  /** Body/supportive text shown below the title. */
+  supportText?: string
+  /** Whether to render the action button at the bottom. */
+  showButton?: boolean
+  /** Label for the default action button. Ignored when `buttonSlot` is provided. */
+  buttonLabel?: string
+  /** Press handler for the default action button. Ignored when `buttonSlot` is provided. */
+  onButtonPress?: () => void
+  /**
+   * Custom slot for the media area (Lottie animation, illustration, or image).
+   * Should render at the design size of 117x117. If omitted, a neutral
+   * placeholder of the same size is rendered so the layout stays stable.
+   * `modes` are automatically cascaded into this slot.
+   */
+  media?: React.ReactNode
+  /**
+   * Optional slot to fully override the action button.
+   * When provided, `showButton`, `buttonLabel`, and `onButtonPress` are ignored.
+   * `modes` are automatically cascaded into this slot.
+   */
+  buttonSlot?: React.ReactNode
+  /** Mode configuration for design-token theming. */
+  modes?: Record<string, any>
+  /** Style overrides applied to the outer container. */
+  style?: StyleProp<ViewStyle>
+  testID?: string
+}
+
+/**
+ * LottieIntroBlock displays a centered onboarding/intro block composed of a
+ * media slot (typically a Lottie animation or illustration) above a title,
+ * an optional supportive paragraph, and an optional action button.
+ *
+ * All visual values are resolved from Figma design tokens via
+ * `getVariableByName`. Slots cascade the active `modes` to their children
+ * through `cloneChildrenWithModes`.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <LottieIntroBlock
+ *   title="Let's get to know how your financial health is doing"
+ *   supportText="From assets to taxes, stay on top of everything in one simple view."
+ *   buttonLabel="Get started"
+ *   onButtonPress={() => navigate('NextScreen')}
+ *   media={<MyLottiePlayer source={animationSource} />}
+ * />
+ * ```
+ */
+function LottieIntroBlock({
+  title = "Let's get to know how your financial health is doing",
+  showSupportText = true,
+  supportText = 'From assets to taxes, stay on top of everything in one simple view.',
+  showButton = true,
+  buttonLabel = 'Button',
+  onButtonPress,
+  media,
+  buttonSlot,
+  modes: propModes = EMPTY_MODES,
+  style,
+  testID,
+}: LottieIntroBlockProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = useMemo(
+    () => ({ ...globalModes, ...propModes }),
+    [globalModes, propModes]
+  )
+
+  // Container
+  const gap = Number(getVariableByName('lottieIntroBlock/gap', modes)) || 36
+  const paddingHorizontal =
+    Number(getVariableByName('lottieIntroBlock/padding/horizontal', modes)) || 0
+  const paddingVertical =
+    Number(getVariableByName('lottieIntroBlock/padding/vertical', modes)) || 16
+
+  // Text wrap
+  const textWrapGap =
+    Number(getVariableByName('lottieIntroBlock/textWrap/gap', modes)) || 16
+
+  // Title
+  const titleColor =
+    getVariableByName('lottieIntroBlock/title/foreground', modes) || '#0d0d0f'
+  const titleFontSize =
+    Number(getVariableByName('lottieIntroBlock/title/fontSize', modes)) || 23
+  const titleFontFamily =
+    getVariableByName('lottieIntroBlock/title/fontFamily', modes) || 'System'
+  const titleLineHeight =
+    Number(getVariableByName('lottieIntroBlock/title/lineHeight', modes)) || 23
+  const titleFontWeight =
+    getVariableByName('lottieIntroBlock/title/fontWeight', modes) || 900
+
+  // Support text
+  const supportColor =
+    getVariableByName('lottieIntroBlock/supportText/foreground', modes) ||
+    '#0d0d0f'
+  const supportFontSize =
+    Number(getVariableByName('lottieIntroBlock/supportText/fontSize', modes)) ||
+    14
+  const supportFontFamily =
+    getVariableByName('lottieIntroBlock/supportText/fontFamily', modes) ||
+    'System'
+  const supportLineHeight =
+    Number(
+      getVariableByName('lottieIntroBlock/supportText/lineHeight', modes)
+    ) || 18
+  const supportFontWeight =
+    getVariableByName('lottieIntroBlock/supportText/fontWeight', modes) || 400
+
+  const containerStyle: ViewStyle = {
+    flexDirection: 'column',
+    alignItems: 'center',
+    paddingHorizontal,
+    paddingVertical,
+    gap,
+  }
+
+  const textWrapStyle: ViewStyle = {
+    flexDirection: 'column',
+    alignItems: 'center',
+    gap: textWrapGap,
+    width: '100%',
+  }
+
+  const titleStyle: TextStyle = {
+    color: titleColor,
+    fontSize: titleFontSize,
+    fontFamily: titleFontFamily,
+    lineHeight: titleLineHeight,
+    fontWeight: String(titleFontWeight) as TextStyle['fontWeight'],
+    textAlign: 'center',
+  }
+
+  const supportTextStyle: TextStyle = {
+    color: supportColor,
+    fontSize: supportFontSize,
+    fontFamily: supportFontFamily,
+    lineHeight: supportLineHeight,
+    fontWeight: String(supportFontWeight) as TextStyle['fontWeight'],
+    textAlign: 'center',
+  }
+
+  const mediaContent = useMemo(() => {
+    if (media === undefined || media === null) {
+      return (
+        <View
+          style={{
+            width: DEFAULT_MEDIA_SIZE,
+            height: DEFAULT_MEDIA_SIZE,
+          }}
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+        />
+      )
+    }
+    return cloneChildrenWithModes(media, modes)
+  }, [media, modes])
+
+  const buttonContent = useMemo(() => {
+    if (buttonSlot !== undefined && buttonSlot !== null) {
+      return cloneChildrenWithModes(buttonSlot, modes)
+    }
+    if (!showButton) {
+      return null
+    }
+    return <Button label={buttonLabel} onPress={onButtonPress} modes={modes} />
+  }, [buttonSlot, showButton, buttonLabel, onButtonPress, modes])
+
+  return (
+    <View style={[containerStyle, style]} testID={testID}>
+      {mediaContent}
+      <View style={textWrapStyle}>
+        <Text style={titleStyle}>{title}</Text>
+        {showSupportText && supportText ? (
+          <Text style={supportTextStyle}>{supportText}</Text>
+        ) : null}
+        {buttonContent}
+      </View>
+    </View>
+  )
+}
+
+export default LottieIntroBlock

package/src/components/LottiePlayer/LottiePlayer.tsx

@@ -0,0 +1,145 @@
+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 } from '../../utils/react-utils'
+import { getNativeLottieView } from './loadNativeLottieView'
+
+/**
+ * A parsed Lottie animation. The JSON object you get from
+ * `require('./animation.json')` or `fetch().then(r => r.json())`. We keep the
+ * type intentionally loose because both `lottie-react-native` and `lottie-react`
+ * accept slightly different shapes — `LottiePlayer` narrows back to the
+ * platform-specific type internally.
+ */
+export type LottieAnimationSource = Record<string, unknown>
+
+export type LottiePlayerProps = {
+  /**
+   * Parsed Lottie animation JSON. Use `require('./animation.json')` in React
+   * Native or `import animation from './animation.json'` on web.
+   *
+   * URI sources (`{ uri: '...' }`) are intentionally not accepted here — web
+   * Lottie players require the animation data to be pre-parsed. Fetch and
+   * parse the JSON yourself before passing it in if you need a remote source.
+   */
+  source: LottieAnimationSource
+  /**
+   * Override the rendered size. Pass a number for a square box, or
+   * `{ width, height }` for non-square.
+   *
+   * When omitted, size is resolved from the `media/width` and `media/height`
+   * design tokens (default `117 × 117`). The `Media / Output` collection
+   * exposes `L | M | S` modes (117 / 70 / 20) — pass
+   * `modes={{ 'Media / Output': 'M' }}` to render at 70×70, etc.
+   */
+  size?: number | { width: number; height: number }
+  /** Play the animation on mount. Defaults to `true`. */
+  autoPlay?: boolean
+  /** Loop the animation. Defaults to `true`. */
+  loop?: boolean
+  /** Mode configuration for design-token theming. */
+  modes?: Record<string, any>
+  /** Style overrides applied to the underlying view. */
+  style?: StyleProp<ViewStyle>
+  /** Accessibility label. Lottie is decorative by default. */
+  accessibilityLabel?: string
+  testID?: string
+}
+
+const DEFAULT_SIZE = 117
+
+function resolveSize(
+  size: LottiePlayerProps['size'],
+  modes: Record<string, any>
+) {
+  if (typeof size === 'number') return { width: size, height: size }
+  if (size && typeof size === 'object') return size
+  const width =
+    Number(getVariableByName('media/width', modes)) || DEFAULT_SIZE
+  const height =
+    Number(getVariableByName('media/height', modes)) || DEFAULT_SIZE
+  return { width, height }
+}
+
+/**
+ * Renders a Lottie animation using the consumer's installed
+ * `lottie-react-native` (native) or `lottie-react` (web) — both are declared
+ * as **optional peer dependencies** of `jfs-components`, so installing the
+ * library does not pull them in. Add the relevant package to your app only
+ * if you actually use `LottiePlayer`:
+ *
+ * ```sh
+ * # React Native (iOS / Android)
+ * npm install lottie-react-native
+ * cd ios && pod install
+ *
+ * # Web (or react-native-web)
+ * npm install lottie-react
+ * ```
+ *
+ * The web build (`LottiePlayer.web.tsx`) is picked automatically by Metro /
+ * webpack via platform extensions — same pattern as `MediaCard/GlassFill`.
+ *
+ * Token-driven sizing: when `size` is omitted, `LottiePlayer` reads
+ * `media/width` and `media/height` from the Figma variables resolver, so the
+ * animation matches the surrounding component's `Media / Output` mode
+ * automatically. This is the same sizing contract `PageHero` and
+ * `LottieIntroBlock` use for their `media` slots.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import animation from './assets/loader.json';
+ *
+ * <LottiePlayer source={animation} />                    // 117 × 117 (default)
+ * <LottiePlayer source={animation} size={70} />          // 70 × 70
+ * <LottiePlayer source={animation} modes={{ 'Media / Output': 'S' }} />  // 20 × 20
+ * <PageHero media={<LottiePlayer source={animation} />} />
+ * ```
+ */
+function LottiePlayer({
+  source,
+  size,
+  autoPlay = true,
+  loop = true,
+  modes: propModes = EMPTY_MODES,
+  style,
+  accessibilityLabel,
+  testID,
+}: LottiePlayerProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = useMemo(
+    () =>
+      globalModes === EMPTY_MODES && propModes === EMPTY_MODES
+        ? EMPTY_MODES
+        : { ...globalModes, ...propModes },
+    [globalModes, propModes]
+  )
+
+  const { width, height } = useMemo(
+    () => resolveSize(size, modes),
+    [size, modes]
+  )
+
+  const NativeLottieView = useMemo(() => getNativeLottieView(), [])
+
+  return (
+    <View
+      style={[{ width, height }, style]}
+      testID={testID}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityElementsHidden={accessibilityLabel ? undefined : true}
+      importantForAccessibility={accessibilityLabel ? 'auto' : 'no'}
+    >
+      <NativeLottieView
+        source={source}
+        autoPlay={autoPlay}
+        loop={loop}
+        style={{ width: '100%', height: '100%' }}
+      />
+    </View>
+  )
+}
+
+export default React.memo(LottiePlayer)

package/src/components/LottiePlayer/LottiePlayer.web.tsx

@@ -0,0 +1,94 @@
+import React, { useMemo } from 'react'
+import { type StyleProp, type ViewStyle } from 'react-native'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
+import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { EMPTY_MODES } from '../../utils/react-utils'
+import { getWebLottieView } from './loadWebLottieView'
+
+export type LottieAnimationSource = Record<string, unknown>
+
+export type LottiePlayerProps = {
+  source: LottieAnimationSource
+  size?: number | { width: number; height: number }
+  autoPlay?: boolean
+  loop?: boolean
+  modes?: Record<string, any>
+  style?: StyleProp<ViewStyle>
+  accessibilityLabel?: string
+  testID?: string
+}
+
+const DEFAULT_SIZE = 117
+
+function resolveSize(
+  size: LottiePlayerProps['size'],
+  modes: Record<string, any>
+) {
+  if (typeof size === 'number') return { width: size, height: size }
+  if (size && typeof size === 'object') return size
+  const width =
+    Number(getVariableByName('media/width', modes)) || DEFAULT_SIZE
+  const height =
+    Number(getVariableByName('media/height', modes)) || DEFAULT_SIZE
+  return { width, height }
+}
+
+/**
+ * Web build of `LottiePlayer` — picked automatically by webpack /
+ * Metro-for-web via the `.web.tsx` platform extension. Uses `lottie-react`
+ * (which wraps `lottie-web`) and renders a plain DOM container.
+ *
+ * Public API mirrors `LottiePlayer.tsx` (native). See that file for the
+ * documented prop reference and usage patterns.
+ */
+function LottiePlayer({
+  source,
+  size,
+  autoPlay = true,
+  loop = true,
+  modes: propModes = EMPTY_MODES,
+  style,
+  accessibilityLabel,
+  testID,
+}: LottiePlayerProps) {
+  const { modes: globalModes } = useTokens()
+  const modes = useMemo(
+    () =>
+      globalModes === EMPTY_MODES && propModes === EMPTY_MODES
+        ? EMPTY_MODES
+        : { ...globalModes, ...propModes },
+    [globalModes, propModes]
+  )
+
+  const { width, height } = useMemo(
+    () => resolveSize(size, modes),
+    [size, modes]
+  )
+
+  const WebLottieView = useMemo(() => getWebLottieView(), [])
+
+  return (
+    <div
+      style={{
+        width,
+        height,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        ...(style as React.CSSProperties),
+      }}
+      data-testid={testID}
+      aria-label={accessibilityLabel}
+      aria-hidden={accessibilityLabel ? undefined : true}
+    >
+      <WebLottieView
+        animationData={source}
+        autoplay={autoPlay}
+        loop={loop}
+        style={{ width: '100%', height: '100%' }}
+      />
+    </div>
+  )
+}
+
+export default React.memo(LottiePlayer)

package/src/components/LottiePlayer/loadNativeLottieView.tsx

@@ -0,0 +1,87 @@
+import React from 'react'
+import { Text, View, type ViewStyle } from 'react-native'
+
+/** Props we forward to the underlying native Lottie view. */
+export type NativeLottieViewProps = {
+  source: Record<string, unknown>
+  autoPlay?: boolean
+  loop?: boolean
+  style?: ViewStyle
+}
+
+const INSTALL_HINT =
+  'LottiePlayer requires lottie-react-native in your app.\n' +
+  '  npm install lottie-react-native\n' +
+  '  cd ios && pod install'
+
+/**
+ * Metro resolves `require('lottie-react-native')` at bundle time even inside
+ * try/catch, which breaks apps that import `jfs-components` without having
+ * the optional peer installed. Splitting the module id into a runtime string
+ * keeps Metro from statically linking it — the native module is loaded only
+ * when present in the consumer's node_modules.
+ */
+function resolveNativeLottieModuleName() {
+  return ['lottie', '-react', '-native'].join('')
+}
+
+function LottieUnavailableView({ style }: Pick<NativeLottieViewProps, 'style'>) {
+  if (__DEV__) {
+    return (
+      <View
+        style={[
+          style,
+          {
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: 'rgba(255, 196, 0, 0.12)',
+            borderWidth: 1,
+            borderColor: 'rgba(255, 196, 0, 0.45)',
+            borderRadius: 8,
+            padding: 8,
+          },
+        ]}
+      >
+        <Text
+          style={{
+            color: '#8a6d00',
+            fontSize: 11,
+            textAlign: 'center',
+            lineHeight: 15,
+          }}
+        >
+          {INSTALL_HINT}
+        </Text>
+      </View>
+    )
+  }
+
+  return <View style={style} />
+}
+
+function LottieUnavailable(props: NativeLottieViewProps) {
+  React.useEffect(() => {
+    if (__DEV__) {
+      console.warn(`[jfs-components/LottiePlayer] ${INSTALL_HINT}`)
+    }
+  }, [])
+
+  return <LottieUnavailableView style={props.style} />
+}
+
+let cachedView: React.ComponentType<NativeLottieViewProps> | undefined
+
+export function getNativeLottieView(): React.ComponentType<NativeLottieViewProps> {
+  if (cachedView !== undefined) return cachedView
+
+  try {
+    const mod = require(resolveNativeLottieModuleName()) as {
+      default?: React.ComponentType<NativeLottieViewProps>
+    }
+    cachedView = mod.default ?? LottieUnavailable
+  } catch {
+    cachedView = LottieUnavailable
+  }
+
+  return cachedView
+}