jfs-components 0.0.74 → 0.0.78

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
+}

package/src/components/LottiePlayer/loadWebLottieView.tsx

@@ -0,0 +1,64 @@
+import React from 'react'
+import type { CSSProperties } from 'react'
+
+/** Props we forward to the underlying web Lottie view. */
+export type WebLottieViewProps = {
+  animationData: Record<string, unknown>
+  autoplay?: boolean
+  loop?: boolean
+  style?: CSSProperties
+}
+
+const INSTALL_HINT =
+  'LottiePlayer requires lottie-react in your app.\n' +
+  '  npm install lottie-react'
+
+function resolveWebLottieModuleName() {
+  return ['lottie', '-react'].join('')
+}
+
+function LottieUnavailable(props: WebLottieViewProps) {
+  React.useEffect(() => {
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+      console.warn(`[jfs-components/LottiePlayer] ${INSTALL_HINT}`)
+    }
+  }, [])
+
+  return (
+    <div
+      style={{
+        ...props.style,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: 'rgba(255, 196, 0, 0.12)',
+        border: '1px solid rgba(255, 196, 0, 0.45)',
+        borderRadius: 8,
+        padding: 8,
+        color: '#8a6d00',
+        fontSize: 11,
+        textAlign: 'center',
+        lineHeight: '15px',
+      }}
+    >
+      {typeof __DEV__ !== 'undefined' && __DEV__ ? INSTALL_HINT : null}
+    </div>
+  )
+}
+
+let cachedView: React.ComponentType<WebLottieViewProps> | undefined
+
+export function getWebLottieView(): React.ComponentType<WebLottieViewProps> {
+  if (cachedView !== undefined) return cachedView
+
+  try {
+    const mod = require(resolveWebLottieModuleName()) as {
+      default?: React.ComponentType<WebLottieViewProps>
+    }
+    cachedView = mod.default ?? LottieUnavailable
+  } catch {
+    cachedView = LottieUnavailable
+  }
+
+  return cachedView
+}