jfs-components 0.0.63 → 0.0.65

package/src/components/UpiHandle/UpiHandle.tsx

@@ -3,7 +3,6 @@ import {
   Pressable,
   View,
   Text,
-  Image,
   Platform,
   type ViewStyle,
   type TextStyle,
@@ -15,10 +14,11 @@ import {
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 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'
 
 // Default static asset from the component folder.
-// Consumers can override the image via the `avatarSource` prop if needed.
+// Consumers can override the image via the `source` prop if needed.
 const DEFAULT_AVATAR_IMAGE = require('./Image.png')
 
 const IS_WEB = Platform.OS === 'web'
@@ -33,7 +33,19 @@ type UpiHandleProps = {
   modes?: Record<string, any>;
   showIcon?: boolean;
   iconName?: string;
-  avatarSource?: ImageSourcePropType;
+  /**
+   * Unified avatar source. Accepts a remote URI (raster or `.svg`), an
+   * inline SVG XML string, a `require()` asset, an SVG React component, or
+   * an already-rendered element. See {@link UnifiedSource}. Avatars are
+   * intentionally **not** tinted — the source renders as-is.
+   */
+  source?: UnifiedSource;
+  /**
+   * @deprecated Use `source` instead. Kept as an alias for back-compat.
+   * Accepts the same shapes as `source` plus the legacy
+   * `ImageSourcePropType` from the previous API.
+   */
+  avatarSource?: ImageSourcePropType | UnifiedSource;
   accessibilityLabel?: string;
   accessibilityHint?: string;
   onPress?: () => void;
@@ -115,7 +127,8 @@ function resolveUpiHandleTokens(modes: Record<string, any>): UpiHandleTokens {
  * @param {Object} [props.modes={}] - Modes object passed directly to `getVariableByName`.
  * @param {boolean} [props.showIcon=true] - Toggles the trailing icon visibility.
  * @param {string} [props.iconName='ic_scan_qr_code'] - Icon name from the actions set.
- * @param {ImageSourcePropType} [props.avatarSource] - Optional custom image source for the avatar.
+ * @param {UnifiedSource} [props.source] - Unified avatar source (URI, inline SVG XML, `require()` asset, SVG React component, or React element). Smart-detects raster vs SVG so the same prop works on iOS, Android and web.
+ * @param {ImageSourcePropType|UnifiedSource} [props.avatarSource] - Deprecated alias for `source`; kept for back-compat.
  * @param {Function} [props.onClick] - Click/tap handler. Works as an alias for `onPress`.
  * @param {string} [props.accessibilityLabel] - Accessibility label for screen readers
  * @param {string} [props.accessibilityHint] - Additional accessibility hint for screen readers
@@ -133,6 +146,7 @@ function UpiHandle({
   modes: propModes = EMPTY_MODES,
   showIcon = true,
   iconName = 'ic_scan_qr_code',
+  source,
   avatarSource,
   onPress,
   onClick,
@@ -202,15 +216,27 @@ function UpiHandle({
     [tokens.containerStyle, isFocused]
   )
 
+  // `source` wins; `avatarSource` is the legacy fallback. Both are accepted
+  // as a UnifiedSource (string / number / {uri} / component / element), and
+  // the legacy `ImageSourcePropType` shapes naturally fit that union too.
+  const resolvedAvatarSource: UnifiedSource =
+    (source as UnifiedSource | undefined) ??
+    (avatarSource as UnifiedSource | undefined) ??
+    (DEFAULT_AVATAR_IMAGE as UnifiedSource)
+
+  const avatarSize = (tokens.avatarStyle.width as number | undefined) ?? 23
+
   const innerContent = (
     <>
-      <Image
-        source={avatarSource || DEFAULT_AVATAR_IMAGE}
-        style={tokens.avatarStyle}
-        resizeMode="cover"
-        accessibilityElementsHidden={true}
-        importantForAccessibility="no"
-      />
+      <View style={tokens.avatarStyle}>
+        <MediaSource
+          source={resolvedAvatarSource}
+          size={avatarSize}
+          resizeMode="cover"
+          accessibilityElementsHidden={true}
+          importantForAccessibility="no"
+        />
+      </View>
       <Text
         style={tokens.labelStyle}
         numberOfLines={1}

package/src/icons/Icon.tsx

@@ -1,109 +1,124 @@
 import React from 'react';
-import { View, AccessibilityProps } from 'react-native';
+import { View, AccessibilityProps, type StyleProp, type ViewStyle } from 'react-native';
 import Svg, { Path } from 'react-native-svg';
 import { getIcon, hasIcon } from './registry';
+import MediaSource, { type UnifiedSource } from '../utils/MediaSource';
 
 type IconProps = AccessibilityProps & {
-  name: string;
+  /**
+   * Built-in icon name from the registry (e.g. `'ic_card'`, `'ic_scan_qr_code'`).
+   * If omitted or not found in the registry, the component falls back to
+   * `source` (when provided).
+   */
+  name?: string;
+  /**
+   * Unified fallback source rendered when `name` is missing or not in the
+   * registry. Accepts a remote URI, an inline SVG XML string, a `require()`
+   * asset, an SVG React component, or an already-rendered element. See
+   * {@link UnifiedSource}. The icon is tinted with `color` so it follows
+   * design-token modes the same way built-in icons do.
+   */
+  source?: UnifiedSource;
   size?: number;
   color?: string;
-  style?: any;
+  style?: StyleProp<ViewStyle>;
 };
 
 /**
- * Generic Icon Component
- * 
- * Renders an icon from the registry by name with customizable size and color.
- * 
- * @component
- * @param {Object} props - Component props
- * @param {string} props.name - Icon name from the registry (e.g., 'ic_ccv', 'ic_card')
- * @param {number} [props.size=24] - Icon size in pixels (width and height)
- * @param {string} [props.color='#141414'] - Icon color (hex, rgb, or named color)
- * @param {Object} [props.style] - Additional styles for the container View
- * 
+ * Generic Icon component.
+ *
+ * Renders an icon from the registry by `name`, or falls back to a
+ * smart-detected `source` (SVG / PNG / JPG / require / SVG component /
+ * remote URI). External sources are tinted with `color` so they participate
+ * in the design-token modes just like built-in icons.
+ *
  * @example
- * ```jsx
+ * ```tsx
+ * // Built-in icon from the registry.
  * <Icon name="ic_ccv" size={24} color="#141414" />
- * <Icon name="ic_card" size={32} color="#5c00b5" />
- * <Icon name="ic_cart" size={20} color="red" />
+ *
+ * // Fallback to a remote SVG (auto-detected by the .svg extension).
+ * <Icon source="https://cdn.example.com/avatar.svg" size={24} color="#5c00b5" />
+ *
+ * // Fallback to a local raster asset.
+ * <Icon source={require('./brand.png')} size={32} />
+ *
+ * // Fallback to an SVG React component (e.g. via react-native-svg-transformer).
+ * import BrandLogo from './brand.svg';
+ * <Icon source={BrandLogo} size={24} color="red" />
  * ```
  */
 function Icon({
   name,
+  source,
   size = 24,
   color = '#141414',
   style,
   ...rest
 }: IconProps) {
-  // Validate icon name
-  if (!name) {
-    console.warn('Icon: name prop is required');
-    return null;
-  }
-
-  if (!hasIcon(name)) {
-    const { getIconNames } = require('./registry');
-    console.warn(`Icon: "${name}" not found in registry. Available icons: ${getIconNames().join(', ')}`);
-    return null;
-  }
+  const containerStyle: StyleProp<ViewStyle> = [
+    {
+      width: size,
+      height: size,
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    style,
+  ];
 
-  // Get icon data from registry
-  const iconData = getIcon(name);
-  if (!iconData) {
-    return null;
-  }
+  const iconData = name && hasIcon(name) ? getIcon(name) : null;
 
-  // Parse viewBox to get width and height for aspect ratio
-  const viewBoxParts = iconData.viewBox.split(' ');
-  // @ts-ignore
-  const viewBoxWidth = parseFloat(viewBoxParts[2]) || size;
-  // @ts-ignore
-  const viewBoxHeight = parseFloat(viewBoxParts[3]) || size;
+  if (iconData) {
+    const viewBoxParts = iconData.viewBox.split(' ');
+    const viewBoxWidth = parseFloat(viewBoxParts[2] ?? `${size}`) || size;
+    const viewBoxHeight = parseFloat(viewBoxParts[3] ?? `${size}`) || size;
+    const aspectRatio = viewBoxWidth / viewBoxHeight;
 
-  // Calculate aspect ratio to maintain proper scaling
-  const aspectRatio = viewBoxWidth / viewBoxHeight;
+    let width = size;
+    let height = size;
+    if (Math.abs(aspectRatio - 1) > 0.01) {
+      if (aspectRatio > 1) {
+        height = size / aspectRatio;
+      } else {
+        width = size * aspectRatio;
+      }
+    }
 
-  // Determine actual width and height based on size and aspect ratio
-  let width = size;
-  let height = size;
+    return (
+      <View style={containerStyle} {...rest}>
+        <Svg
+          width={width}
+          height={height}
+          viewBox={iconData.viewBox}
+          preserveAspectRatio="xMidYMid meet"
+        >
+          <Path
+            d={iconData.path}
+            fill={color}
+            fillRule={(iconData.fillRule || 'nonzero') as 'nonzero' | 'evenodd'}
+          />
+        </Svg>
+      </View>
+    );
+  }
 
-  // If viewBox is not square, adjust dimensions to maintain aspect ratio
-  if (Math.abs(aspectRatio - 1) > 0.01) {
-    if (aspectRatio > 1) {
-      // Wider than tall
-      height = size / aspectRatio;
-    } else {
-      // Taller than wide
-      width = size * aspectRatio;
-    }
+  if (source !== undefined) {
+    return (
+      <View style={containerStyle} {...rest}>
+        <MediaSource source={source} size={size} tintColor={color} resizeMode="contain" />
+      </View>
+    );
   }
 
-  const containerStyle = {
-    width: size,
-    height: size,
-    alignItems: 'center',
-    justifyContent: 'center',
-    ...style,
-  };
+  if (!name) {
+    console.warn('Icon: either `name` or `source` is required');
+    return null;
+  }
 
-  return (
-    <View style={containerStyle} {...rest}>
-      <Svg
-        width={width}
-        height={height}
-        viewBox={iconData.viewBox}
-        preserveAspectRatio="xMidYMid meet"
-      >
-        <Path
-          d={iconData.path}
-          fill={color}
-          fillRule={(iconData.fillRule || 'nonzero') as any}
-        />
-      </Svg>
-    </View>
+  console.warn(
+    `Icon: "${name}" not found in registry and no \`source\` fallback was provided.`
   );
+  return null;
 }
 
 export default Icon;
-

package/src/icons/registry.ts

@@ -4,7 +4,7 @@
  * Auto-generated from SVG files in src/icons/
  * DO NOT EDIT MANUALLY - Run "npm run icons:generate" to regenerate
  * 
- * Generated: 2026-04-20T08:18:55.051Z
+ * Generated: 2026-04-21T13:27:57.213Z
  */
 
 // Icon name to SVG data mapping

package/src/utils/MediaSource.tsx

@@ -0,0 +1,220 @@
+import React from 'react'
+import {
+  Image,
+  type ImageStyle,
+  type ImageURISource,
+  type StyleProp,
+} from 'react-native'
+import { SvgUri, SvgXml } from 'react-native-svg'
+
+/**
+ * A unified, "do-the-right-thing" image source accepted by `MediaSource` and
+ * by the `source` prop on `Icon`, `IconCapsule` and `UpiHandle`.
+ *
+ * Accepts any of:
+ *  - `string`   — a URI (raster or `.svg`) **or** an inline SVG XML document
+ *                 (`'<svg …>…</svg>'`).
+ *  - `number`   — a Metro asset id from `require('./foo.png')`.
+ *  - `{ uri, … }` — the standard RN `ImageURISource` object (works for both
+ *                   raster and `.svg` URIs).
+ *  - `React.ComponentType` — an SVG React component (e.g. produced by
+ *                            `react-native-svg-transformer`, by `@svgr/*`,
+ *                            or hand-written). It is rendered with
+ *                            `{ width, height, color, fill }` so it can be
+ *                            tinted just like a built-in icon.
+ *  - `React.ReactElement`  — an already-rendered node, passed through verbatim.
+ *
+ * The helper sniffs the input shape (no extension hint required from the
+ * caller) and picks the correct renderer for the platform.
+ */
+export type UnifiedSource =
+  | string
+  | number
+  | ImageURISource
+  | React.ComponentType<{
+      width?: number
+      height?: number
+      color?: string
+      fill?: string
+    }>
+  | React.ReactElement
+
+export type MediaSourceProps = {
+  /** Smart source. See {@link UnifiedSource}. */
+  source: UnifiedSource
+  /** Convenience shorthand that sets both width and height. */
+  size?: number
+  width?: number
+  height?: number
+  /**
+   * Optional tint applied to the rendered media.
+   *  - Raster `<Image>` → mapped to `style.tintColor` (works on iOS, Android,
+   *    and react-native-web).
+   *  - SVG (XML / URI / component) → mapped to the `color` / `fill` props.
+   *    For an SVG to actually re-color, its source must use `currentColor`
+   *    (or have no hardcoded fill). SVGs with baked-in `fill="#xxx"` cannot
+   *    be re-tinted without parsing — this is a `react-native-svg`
+   *    limitation, not something we can paper over here.
+   */
+  tintColor?: string
+  /** Extra style merged into the underlying `<Image>` (raster path only). */
+  style?: StyleProp<ImageStyle>
+  resizeMode?: 'cover' | 'contain' | 'stretch' | 'center' | 'repeat'
+  accessibilityElementsHidden?: boolean
+  importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants'
+}
+
+const SVG_XML_RE = /<svg[\s>]/i
+const SVG_URI_RE = /\.svg(\?|#|$)/i
+
+function isSvgXml(s: string): boolean {
+  return /^\s*</.test(s) && SVG_XML_RE.test(s)
+}
+
+function isSvgUri(s: string): boolean {
+  return SVG_URI_RE.test(s)
+}
+
+function isUriObject(
+  v: unknown
+): v is ImageURISource & { uri: string } {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    'uri' in v &&
+    typeof (v as { uri: unknown }).uri === 'string'
+  )
+}
+
+/**
+ * Smart renderer that picks the right primitive for the source shape. See
+ * {@link UnifiedSource}.
+ *
+ * Designed to be used internally by `Icon`, `IconCapsule`, and `UpiHandle`,
+ * but also exported for ad-hoc consumer use.
+ */
+function MediaSource(props: MediaSourceProps) {
+  const {
+    source,
+    size,
+    width,
+    height,
+    tintColor,
+    style,
+    resizeMode = 'cover',
+    accessibilityElementsHidden,
+    importantForAccessibility,
+  } = props
+
+  const w = width ?? size
+  const h = height ?? size
+
+  // Pre-rendered element — pass through.
+  if (React.isValidElement(source)) {
+    return source
+  }
+
+  // SVG / icon component.
+  if (typeof source === 'function') {
+    const Comp = source as React.ComponentType<{
+      width?: number
+      height?: number
+      color?: string
+      fill?: string
+    }>
+    return (
+      <Comp
+        {...(w !== undefined ? { width: w } : {})}
+        {...(h !== undefined ? { height: h } : {})}
+        {...(tintColor !== undefined ? { color: tintColor, fill: tintColor } : {})}
+      />
+    )
+  }
+
+  const sizeStyle: ImageStyle | null =
+    w !== undefined || h !== undefined ? { width: w, height: h } : null
+  const tintStyle: ImageStyle | null = tintColor ? { tintColor } : null
+  const composedStyle: StyleProp<ImageStyle> = [sizeStyle, tintStyle, style]
+
+  if (typeof source === 'string') {
+    if (isSvgXml(source)) {
+      return (
+        <SvgXml
+          xml={source}
+          {...(w !== undefined ? { width: w } : {})}
+          {...(h !== undefined ? { height: h } : {})}
+          {...(tintColor !== undefined ? { color: tintColor } : {})}
+        />
+      )
+    }
+    if (isSvgUri(source)) {
+      return (
+        <SvgUri
+          uri={source}
+          {...(w !== undefined ? { width: w } : {})}
+          {...(h !== undefined ? { height: h } : {})}
+          {...(tintColor !== undefined ? { color: tintColor } : {})}
+        />
+      )
+    }
+    return (
+      <Image
+        source={{ uri: source }}
+        style={composedStyle}
+        resizeMode={resizeMode}
+        {...(accessibilityElementsHidden !== undefined
+          ? { accessibilityElementsHidden }
+          : {})}
+        {...(importantForAccessibility !== undefined
+          ? { importantForAccessibility }
+          : {})}
+      />
+    )
+  }
+
+  if (isUriObject(source)) {
+    if (isSvgUri(source.uri)) {
+      return (
+        <SvgUri
+          uri={source.uri}
+          {...(w !== undefined ? { width: w } : {})}
+          {...(h !== undefined ? { height: h } : {})}
+          {...(tintColor !== undefined ? { color: tintColor } : {})}
+        />
+      )
+    }
+    return (
+      <Image
+        source={source}
+        style={composedStyle}
+        resizeMode={resizeMode}
+        {...(accessibilityElementsHidden !== undefined
+          ? { accessibilityElementsHidden }
+          : {})}
+        {...(importantForAccessibility !== undefined
+          ? { importantForAccessibility }
+          : {})}
+      />
+    )
+  }
+
+  if (typeof source === 'number') {
+    return (
+      <Image
+        source={source}
+        style={composedStyle}
+        resizeMode={resizeMode}
+        {...(accessibilityElementsHidden !== undefined
+          ? { accessibilityElementsHidden }
+          : {})}
+        {...(importantForAccessibility !== undefined
+          ? { importantForAccessibility }
+          : {})}
+      />
+    )
+  }
+
+  return null
+}
+
+export default React.memo(MediaSource)

package/src/utils/index.ts

@@ -1 +1,3 @@
 export { cloneChildrenWithModes, flattenChildren } from './react-utils'
+export { default as MediaSource } from './MediaSource'
+export type { UnifiedSource, MediaSourceProps } from './MediaSource'