jfs-components 0.0.64 → 0.0.65

package/src/components/IconButton/IconButton.tsx

@@ -11,9 +11,19 @@ import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 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'
 
 type IconButtonProps = SafePressableProps & {
+  /** Built-in icon name from the registry (default state). */
   iconName?: string;
+  /**
+   * Unified fallback source for the default state, used when `iconName` is
+   * missing or not in the registry. Accepts a remote URI, an inline SVG XML
+   * string, a `require()` asset, an SVG React component, or a React element.
+   * The result is tinted with the button's mode-resolved icon color so it
+   * follows design tokens just like a built-in icon. See {@link UnifiedSource}.
+   */
+  source?: UnifiedSource;
   modes?: Record<string, any>;
   onPress?: () => void;
   disabled?: boolean;
@@ -29,10 +39,24 @@ type IconButtonProps = SafePressableProps & {
    * Icon to display when isToggle is true and isActive is true
    */
   activeIcon?: string;
+  /**
+   * Unified fallback source for the active state. Used when `activeIcon` is
+   * missing or not in the registry (and only when `isToggle` is true and
+   * `isActive` is true). Falls back to the default `source` if not provided.
+   * See {@link UnifiedSource}.
+   */
+  activeSource?: UnifiedSource;
   /**
    * Icon to display when isToggle is true and isActive is false
    */
   inactiveIcon?: string;
+  /**
+   * Unified fallback source for the inactive state. Used when `inactiveIcon`
+   * is missing or not in the registry (and only when `isToggle` is true and
+   * `isActive` is false). Falls back to the default `source` if not provided.
+   * See {@link UnifiedSource}.
+   */
+  inactiveSource?: UnifiedSource;
   /**
    * Whether the toggle button is in active state (only used when isToggle is true)
    */
@@ -109,8 +133,14 @@ function resolveIconButtonTokens(modes: Record<string, any>, disabled: boolean):
  *    pressed transform mirrored via React state) — removed.
  *  - Wrapped in `React.memo`.
  */
+// Legacy default icon used when neither a `name` nor a `source` is supplied
+// for the resolved slot. Kept as a constant rather than a destructuring
+// default so source-only call sites don't accidentally render `'ic_card'`.
+const LEGACY_DEFAULT_ICON_NAME = 'ic_card'
+
 function IconButton({
-  iconName = 'ic_card',
+  iconName,
+  source,
   modes = EMPTY_MODES,
   onPress,
   disabled = false,
@@ -121,7 +151,9 @@ function IconButton({
   webAccessibilityProps,
   isToggle = false,
   activeIcon,
+  activeSource,
   inactiveIcon,
+  inactiveSource,
   isActive = false,
   ...rest
 }: IconButtonProps) {
@@ -160,16 +192,42 @@ function IconButton({
   userHandlersRef.current.onHoverIn = (rest as any)?.onHoverIn
   userHandlersRef.current.onHoverOut = (rest as any)?.onHoverOut
 
-  // Determine which icon to display
-  const finalIconName =
-    isToggle
-      ? (isActive && activeIcon
-        ? activeIcon
-        : (!isActive && inactiveIcon ? inactiveIcon : iconName))
-      : iconName
+  // Resolve the active (name + source) pair for the current slot. Toggle
+  // mode picks active/inactive based on `isActive`; per-state overrides
+  // fall back to the default `iconName` / `source` when omitted. We then
+  // apply the legacy default icon only as a last resort, so a source-only
+  // call site (`<IconButton source="…" />`) renders the source instead of
+  // bleeding through to `'ic_card'`.
+  let resolvedIconName: string | undefined
+  let resolvedSource: UnifiedSource | undefined
+  if (isToggle) {
+    if (isActive) {
+      resolvedIconName = activeIcon ?? iconName
+      resolvedSource = activeSource ?? source
+    } else {
+      resolvedIconName = inactiveIcon ?? iconName
+      resolvedSource = inactiveSource ?? source
+    }
+  } else {
+    resolvedIconName = iconName
+    resolvedSource = source
+  }
+  if (!resolvedIconName && resolvedSource === undefined) {
+    resolvedIconName = LEGACY_DEFAULT_ICON_NAME
+  }
 
-  // Generate default accessibility label from icon name if not provided
-  const defaultAccessibilityLabel = accessibilityLabel || iconName.replace(/^ic_/, '').replace(/_/g, ' ').replace(/\b\w/g, l => l.toUpperCase())
+  // Generate default accessibility label from the resolved icon name when
+  // possible. Source-only call sites should provide an explicit
+  // `accessibilityLabel`; we fall back to a generic 'Icon button' so we
+  // never crash on `iconName.replace(...)` when only a `source` is supplied.
+  const defaultAccessibilityLabel =
+    accessibilityLabel ||
+    (resolvedIconName
+      ? resolvedIconName
+          .replace(/^ic_/, '')
+          .replace(/_/g, ' ')
+          .replace(/\b\w/g, (l) => l.toUpperCase())
+      : 'Icon button')
 
   const webProps = usePressableWebSupport({
     restProps: rest,
@@ -235,7 +293,8 @@ function IconButton({
       {...webProps}
     >
       <Icon
-        name={finalIconName}
+        {...(resolvedIconName !== undefined ? { name: resolvedIconName } : {})}
+        {...(resolvedSource !== undefined ? { source: resolvedSource } : {})}
         size={tokens.iconSize}
         color={tokens.iconColor}
         accessibilityElementsHidden={true}

package/src/components/IconCapsule/IconCapsule.tsx

@@ -4,9 +4,19 @@ import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
 import { EMPTY_MODES } from '../../utils/react-utils'
 import Icon from '../../icons/Icon'
+import type { UnifiedSource } from '../../utils/MediaSource'
 
 type IconCapsuleProps = {
   iconName?: string;
+  /**
+   * Unified fallback source rendered when `iconName` 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. The
+   * resulting media is tinted with the capsule's mode-resolved icon color so
+   * it follows design tokens just like a built-in icon. See
+   * {@link UnifiedSource}.
+   */
+  source?: UnifiedSource;
   modes?: Record<string, any>;
   accessibilityLabel?: string;
   accessibilityRole?: string;
@@ -55,6 +65,7 @@ function resolveIconCapsuleTokens(modes: Record<string, any>): IconCapsuleTokens
  * @component
  * @param {Object} props - Component props
  * @param {string} [props.iconName="ic_card"] - The name of the icon to display from the icon registry
+ * @param {UnifiedSource} [props.source] - Fallback source (remote URI, inline SVG XML, `require()` asset, SVG React component, or React element). Used when `iconName` is missing or unknown. Tinted with the mode-resolved icon color so it follows design tokens just like a built-in icon.
  * @param {Object} [props.modes={}] - Mode configuration for design tokens (e.g., {"Appearance": "Primary"})
  * @param {string} [props.accessibilityLabel] - Accessibility label for screen readers
  * @param {string} [props.accessibilityRole] - Accessibility role (defaults to "image" for decorative icons)
@@ -68,6 +79,7 @@ function resolveIconCapsuleTokens(modes: Record<string, any>): IconCapsuleTokens
  */
 function IconCapsule({
   iconName = 'ic_card',
+  source,
   modes: propModes = EMPTY_MODES,
   // accessibilityLabel is accepted on the type for API back-compat but the
   // component intentionally renders `accessibilityLabel={undefined}` (icons
@@ -105,6 +117,7 @@ function IconCapsule({
     >
       <Icon
         name={iconName}
+        {...(source !== undefined ? { source } : {})}
         size={tokens.iconSize}
         color={tokens.iconColor}
         accessibilityElementsHidden={true}

package/src/components/Popup/Popup.tsx

@@ -162,12 +162,12 @@ const Popup = forwardRef<PopupRef, PopupProps>(function Popup(
                 <View style={styles.overlay}>
                     <Animated.View
                         style={[
-                            StyleSheet.absoluteFillObject,
+                            StyleSheet.absoluteFill,
                             { backgroundColor: backdropColor, opacity: backdropAnim },
                         ]}
                     >
                         <Pressable
-                            style={StyleSheet.absoluteFillObject}
+                            style={StyleSheet.absoluteFill}
                             onPress={closeOnBackdropPress ? handleClose : undefined}
                             accessibilityRole="button"
                             accessibilityLabel="Close popup"

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-20T20:41:14.535Z
+ * Generated: 2026-04-21T13:27:57.213Z
  */
 
 // Icon name to SVG data mapping