jfs-components 0.0.64 → 0.0.66

package/lib/commonjs/utils/MediaSource.js

@@ -0,0 +1,181 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _reactNative = require("react-native");
+var _reactNativeSvg = require("react-native-svg");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * 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.
+ */
+
+const SVG_XML_RE = /<svg[\s>]/i;
+const SVG_URI_RE = /\.svg(\?|#|$)/i;
+function isSvgXml(s) {
+  return /^\s*</.test(s) && SVG_XML_RE.test(s);
+}
+function isSvgUri(s) {
+  return SVG_URI_RE.test(s);
+}
+function isUriObject(v) {
+  return typeof v === 'object' && v !== null && 'uri' in v && typeof v.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) {
+  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 (/*#__PURE__*/_react.default.isValidElement(source)) {
+    return source;
+  }
+
+  // SVG / icon component.
+  if (typeof source === 'function') {
+    const Comp = source;
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(Comp, {
+      ...(w !== undefined ? {
+        width: w
+      } : {}),
+      ...(h !== undefined ? {
+        height: h
+      } : {}),
+      ...(tintColor !== undefined ? {
+        color: tintColor,
+        fill: tintColor
+      } : {})
+    });
+  }
+  const sizeStyle = w !== undefined || h !== undefined ? {
+    width: w,
+    height: h
+  } : null;
+  const tintStyle = tintColor ? {
+    tintColor
+  } : null;
+  const composedStyle = [sizeStyle, tintStyle, style];
+  if (typeof source === 'string') {
+    if (isSvgXml(source)) {
+      return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSvg.SvgXml, {
+        xml: source,
+        ...(w !== undefined ? {
+          width: w
+        } : {}),
+        ...(h !== undefined ? {
+          height: h
+        } : {}),
+        ...(tintColor !== undefined ? {
+          color: tintColor
+        } : {})
+      });
+    }
+    if (isSvgUri(source)) {
+      return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSvg.SvgUri, {
+        uri: source,
+        ...(w !== undefined ? {
+          width: w
+        } : {}),
+        ...(h !== undefined ? {
+          height: h
+        } : {}),
+        ...(tintColor !== undefined ? {
+          color: tintColor
+        } : {})
+      });
+    }
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Image, {
+      source: {
+        uri: source
+      },
+      style: composedStyle,
+      resizeMode: resizeMode,
+      ...(accessibilityElementsHidden !== undefined ? {
+        accessibilityElementsHidden
+      } : {}),
+      ...(importantForAccessibility !== undefined ? {
+        importantForAccessibility
+      } : {})
+    });
+  }
+  if (isUriObject(source)) {
+    if (isSvgUri(source.uri)) {
+      return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeSvg.SvgUri, {
+        uri: source.uri,
+        ...(w !== undefined ? {
+          width: w
+        } : {}),
+        ...(h !== undefined ? {
+          height: h
+        } : {}),
+        ...(tintColor !== undefined ? {
+          color: tintColor
+        } : {})
+      });
+    }
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Image, {
+      source: source,
+      style: composedStyle,
+      resizeMode: resizeMode,
+      ...(accessibilityElementsHidden !== undefined ? {
+        accessibilityElementsHidden
+      } : {}),
+      ...(importantForAccessibility !== undefined ? {
+        importantForAccessibility
+      } : {})
+    });
+  }
+  if (typeof source === 'number') {
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Image, {
+      source: source,
+      style: composedStyle,
+      resizeMode: resizeMode,
+      ...(accessibilityElementsHidden !== undefined ? {
+        accessibilityElementsHidden
+      } : {}),
+      ...(importantForAccessibility !== undefined ? {
+        importantForAccessibility
+      } : {})
+    });
+  }
+  return null;
+}
+var _default = exports.default = /*#__PURE__*/_react.default.memo(MediaSource);

package/lib/commonjs/utils/index.js

@@ -3,6 +3,12 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "MediaSource", {
+  enumerable: true,
+  get: function () {
+    return _MediaSource.default;
+  }
+});
 Object.defineProperty(exports, "cloneChildrenWithModes", {
   enumerable: true,
   get: function () {
@@ -15,4 +21,6 @@ Object.defineProperty(exports, "flattenChildren", {
     return _reactUtils.flattenChildren;
   }
 });
-var _reactUtils = require("./react-utils");
+var _reactUtils = require("./react-utils");
+var _MediaSource = _interopRequireDefault(require("./MediaSource"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/lib/module/components/CardCTA/CardCTA.js

@@ -56,8 +56,17 @@ function CardCTA({
     flexDirection: 'row',
     overflow: 'hidden'
   };
+
+  // NOTE: `minWidth: 0` + explicit `flexShrink: 1` are required on native.
+  // Without them, Yoga's default `min-width: auto` clamps leftWrap to its
+  // single-line intrinsic text width, which steals all space from rightWrap
+  // and pushes the IconCapsule outside the card. See: text-not-wrapping
+  // inside flex rows on RN.
   const leftWrapStyle = {
     flex: 3,
+    flexShrink: 1,
+    flexBasis: 0,
+    minWidth: 0,
     paddingHorizontal: leftPaddingH,
     paddingVertical: leftPaddingV,
     gap: leftGap,
@@ -66,13 +75,18 @@ function CardCTA({
   };
   const rightWrapStyle = {
     flex: 2,
+    flexShrink: 1,
+    flexBasis: 0,
+    minWidth: 0,
     paddingHorizontal: rightPaddingH,
     paddingVertical: rightPaddingV,
     alignItems: 'flex-end',
     justifyContent: 'flex-start'
   };
   const textWrapStyle = {
-    gap: textGap
+    gap: textGap,
+    alignSelf: 'stretch',
+    minWidth: 0
   };
   const titleStyle = {
     color: titleColor,

package/lib/module/components/Carousel/Carousel.js

@@ -43,7 +43,8 @@ export function Carousel({
   const gap = gapProp ?? tokenGap;
   const containerPaddingH = parseFloat(getVariableByName('carousel/padding/horizontal', modes) || '0');
   const containerPaddingV = parseFloat(getVariableByName('carousel/padding/vertical', modes) || '0');
-  const paginationGap = parseFloat(getVariableByName('carousel/pagination/gap', modes) || '12');
+  // Spacing between the cards row and the pagination dots uses `carousel/gap`.
+  const paginationOffset = gap;
 
   // ---- Refs & state ----
   const scrollRef = useRef(null);
@@ -180,8 +181,26 @@ export function Carousel({
         onScrollBeginDrag: handleScrollBeginDrag,
         onScrollEndDrag: handleScrollEndDrag,
         children: items.map((child, index) => {
-          const itemStyle = {
-            width: effectiveItemWidth > 0 ? effectiveItemWidth : undefined
+          // Strict slot box: width must be honored; never grow or shrink with
+          // content, and clip anything that misbehaves (e.g. a child whose
+          // inner flex layout would otherwise leak into the next slot on
+          // native).
+          const slotStyle = {
+            width: effectiveItemWidth > 0 ? effectiveItemWidth : undefined,
+            flexGrow: 0,
+            flexShrink: 0,
+            flexBasis: effectiveItemWidth > 0 ? effectiveItemWidth : 'auto',
+            overflow: 'hidden'
+          };
+
+          // The cloned style forces the child's outer node to also honor the
+          // slot width strictly. Without this, a child with a weird intrinsic
+          // size can render wider than the slot and visually overflow.
+          const childOverrideStyle = {
+            width: effectiveItemWidth > 0 ? effectiveItemWidth : undefined,
+            maxWidth: effectiveItemWidth > 0 ? effectiveItemWidth : undefined,
+            flexGrow: 0,
+            flexShrink: 0
           };
 
           // Pass modes down to children
@@ -190,17 +209,17 @@ export function Carousel({
               ...(child.props?.modes || {}),
               ...modes
             },
-            style: [itemStyle, child.props?.style]
+            style: [childOverrideStyle, child.props?.style]
           }) : child;
           return /*#__PURE__*/_jsx(View, {
-            style: itemStyle,
+            style: slotStyle,
             children: childWithModes
           }, index);
         })
       }), showPagination && totalItems > 1 && /*#__PURE__*/_jsx(Pagination, {
         modes: modes,
         style: {
-          marginTop: paginationGap
+          marginTop: paginationOffset
         }
       })]
     })
@@ -242,13 +261,15 @@ export function Pagination({
   } = useContext(CarouselContext);
   const modes = propModes || ctxModes || {};
 
-  // Token resolution for dots
-  const dotSize = parseFloat(getVariableByName('carousel/pagination/dotSize', modes) || '8');
-  const dotActiveWidth = parseFloat(getVariableByName('carousel/pagination/dotActiveWidth', modes) || '24');
-  const dotGap = parseFloat(getVariableByName('carousel/pagination/dotGap', modes) || '8');
-  const dotColor = getVariableByName('carousel/pagination/dotColor', modes) || 'rgba(255,255,255,0.35)';
-  const dotActiveColor = getVariableByName('carousel/pagination/dotActiveColor', modes) || '#ffffff';
-  const dotRadius = parseFloat(getVariableByName('carousel/pagination/dotRadius', modes) || '4');
+  // Token resolution for dots — matches Figma tokens
+  // (carousel/pagination/gap, carousel/pagination/indicator/{activecolor,inactivecolor,radius}).
+  // Dot dimensions are fixed per Figma spec: inactive 6x6, active 16x6.
+  const dotSize = 6;
+  const dotActiveWidth = 16;
+  const dotGap = parseFloat(getVariableByName('carousel/pagination/gap', modes) || '4');
+  const dotColor = getVariableByName('carousel/pagination/indicator/inactivecolor', modes) || 'rgba(0,0,0,0.3)';
+  const dotActiveColor = getVariableByName('carousel/pagination/indicator/activecolor', modes) || '#170d0a';
+  const dotRadius = parseFloat(getVariableByName('carousel/pagination/indicator/radius', modes) || '9999');
   const containerStyle = {
     flexDirection: 'row',
     justifyContent: 'center',

package/lib/module/components/Drawer/Drawer.js

@@ -59,7 +59,8 @@ function Drawer({
   accessibilityHint,
   contentContainerStyle,
   showsVerticalScrollIndicator = false,
-  bottomInset = 80
+  bottomInset = 80,
+  onStateChange
 }) {
   const {
     height: screenHeight
@@ -124,8 +125,13 @@ function Drawer({
 
   // Update JS state for accessibility/logic if needed
   const updateMode = useCallback(newMode => {
-    setMode(newMode);
-  }, []);
+    setMode(prev => {
+      if (prev !== newMode) {
+        onStateChange?.(newMode);
+      }
+      return newMode;
+    });
+  }, [onStateChange]);
 
   // Gesture policy:
   //  • activeOffsetY: require a clear *vertical* drag (10px) before this

package/lib/module/components/IconButton/IconButton.js

@@ -72,8 +72,13 @@ function resolveIconButtonTokens(modes, disabled) {
  *    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,
@@ -84,7 +89,9 @@ function IconButton({
   webAccessibilityProps,
   isToggle = false,
   activeIcon,
+  activeSource,
   inactiveIcon,
+  inactiveSource,
   isActive = false,
   ...rest
 }) {
@@ -107,11 +114,35 @@ function IconButton({
   userHandlersRef.current.onHoverIn = rest?.onHoverIn;
   userHandlersRef.current.onHoverOut = rest?.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;
+  let resolvedSource;
+  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,
     onPress: disabled ? undefined : onPress,
@@ -164,7 +195,12 @@ function IconButton({
     style: styleCallback,
     ...webProps,
     children: /*#__PURE__*/_jsx(Icon, {
-      name: finalIconName,
+      ...(resolvedIconName !== undefined ? {
+        name: resolvedIconName
+      } : {}),
+      ...(resolvedSource !== undefined ? {
+        source: resolvedSource
+      } : {}),
       size: tokens.iconSize,
       color: tokens.iconColor,
       accessibilityElementsHidden: true,

package/lib/module/components/IconCapsule/IconCapsule.js

@@ -43,6 +43,7 @@ function resolveIconCapsuleTokens(modes) {
  * @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)
@@ -56,6 +57,7 @@ function resolveIconCapsuleTokens(modes) {
  */
 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
@@ -85,6 +87,9 @@ function IconCapsule({
     ...rest,
     children: /*#__PURE__*/_jsx(Icon, {
       name: iconName,
+      ...(source !== undefined ? {
+        source
+      } : {}),
       size: tokens.iconSize,
       color: tokens.iconColor,
       accessibilityElementsHidden: true,

package/lib/module/components/Popup/Popup.js

@@ -106,12 +106,12 @@ const Popup = /*#__PURE__*/forwardRef(function Popup({
       children: /*#__PURE__*/_jsxs(View, {
         style: styles.overlay,
         children: [/*#__PURE__*/_jsx(Animated.View, {
-          style: [StyleSheet.absoluteFillObject, {
+          style: [StyleSheet.absoluteFill, {
             backgroundColor: backdropColor,
             opacity: backdropAnim
           }],
           children: /*#__PURE__*/_jsx(Pressable, {
-            style: StyleSheet.absoluteFillObject,
+            style: StyleSheet.absoluteFill,
             onPress: closeOnBackdropPress ? handleClose : undefined,
             accessibilityRole: "button",
             accessibilityLabel: "Close popup"

package/lib/module/components/Section/Section.js

@@ -2,7 +2,7 @@
 
 import React, { useState, useMemo, useRef, useCallback } from 'react';
 import { View, Text, Pressable, Platform } from 'react-native';
-import Animated, { FadeInUp, FadeOutUp, ReduceMotion, useAnimatedStyle, useSharedValue, withSpring } from 'react-native-reanimated';
+import Animated, { Easing, FadeInUp, FadeOutUp, ReduceMotion, useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated';
 import { getVariableByName } from '../../design-tokens/figma-variables-resolver';
 import NavArrow from '../NavArrow/NavArrow';
 import IconCapsule from '../IconCapsule/IconCapsule';
@@ -85,7 +85,14 @@ const SLOT_GRID_MAX_COLUMNS = 4;
 const SLOT_GRID_STAGGER_CAP = 8;
 const SLOT_GRID_ENTER_STAGGER_MS = 35;
 const SLOT_GRID_EXIT_STAGGER_MS = 20;
+const SLOT_GRID_ENTER_DURATION_MS = 220;
 const SLOT_GRID_EXIT_DURATION_MS = 160;
+const SLOT_GRID_HEIGHT_DURATION_MS = 280;
+
+// Standard ease-out cubic curve. Calm, professional, no overshoot — matches
+// system-style transitions. Defined once at module scope so it isn't
+// re-allocated per render.
+const SLOT_GRID_EASING = Easing.out(Easing.cubic);
 const slotGridRowFlowStyle = {
   flexDirection: 'row',
   justifyContent: 'space-between'
@@ -131,6 +138,13 @@ const SlotGrid = /*#__PURE__*/React.memo(function SlotGrid({
   const containerStyle = useMemo(() => ({
     gap
   }), [gap]);
+  // Strict `width` (not `minWidth`) so every cell in every row is exactly the
+  // same size — `space-between` then distributes identical leftover into
+  // identical inter-cell gaps on every row, which keeps column N of row 1
+  // aligned with column N of rows 2/3/etc. Cells whose label is wider than
+  // `cellWidth` simply wrap their text onto more lines (taking more vertical
+  // space; the row's height grows naturally to fit the tallest cell, and the
+  // animated-height clip springs to the new total).
   const cellStyle = useMemo(() => cellWidth !== null ? {
     width: cellWidth
   } : undefined, [cellWidth]);
@@ -164,8 +178,9 @@ const SlotGrid = /*#__PURE__*/React.memo(function SlotGrid({
   //      and an explicit `height` driven by a shared value.
   //   3. The inner view reports its natural height via `onLayout`. The first
   //      measurement snaps the shared value (no first-mount animation). Every
-  //      subsequent change (e.g. expand/collapse adds or removes rows) springs
-  //      the shared value to the new natural height.
+  //      subsequent change (e.g. expand/collapse adds or removes rows) eases
+  //      the shared value to the new natural height with a calm ease-out
+  //      timing curve — no spring, no bounce, no overshoot.
   //
   // Visually: the container reveals/conceals content like a curtain, and the
   // cells never deform.
@@ -179,9 +194,9 @@ const SlotGrid = /*#__PURE__*/React.memo(function SlotGrid({
       animatedHeight.value = h;
       return;
     }
-    animatedHeight.value = withSpring(h, {
-      damping: 22,
-      stiffness: 180,
+    animatedHeight.value = withTiming(h, {
+      duration: SLOT_GRID_HEIGHT_DURATION_MS,
+      easing: SLOT_GRID_EASING,
       reduceMotion: ReduceMotion.System
     });
   }, [animatedHeight]);
@@ -205,8 +220,8 @@ const SlotGrid = /*#__PURE__*/React.memo(function SlotGrid({
             const enterStaggerSteps = Math.min(extraOrdinal, SLOT_GRID_STAGGER_CAP);
             const reverseOrdinal = Math.max(0, extrasCount - 1 - extraOrdinal);
             const exitStaggerSteps = Math.min(reverseOrdinal, SLOT_GRID_STAGGER_CAP);
-            const entering = FadeInUp.springify().damping(18).delay(enterStaggerSteps * SLOT_GRID_ENTER_STAGGER_MS).reduceMotion(ReduceMotion.System);
-            const exiting = FadeOutUp.duration(SLOT_GRID_EXIT_DURATION_MS).delay(exitStaggerSteps * SLOT_GRID_EXIT_STAGGER_MS).reduceMotion(ReduceMotion.System);
+            const entering = FadeInUp.duration(SLOT_GRID_ENTER_DURATION_MS).easing(SLOT_GRID_EASING).delay(enterStaggerSteps * SLOT_GRID_ENTER_STAGGER_MS).reduceMotion(ReduceMotion.System);
+            const exiting = FadeOutUp.duration(SLOT_GRID_EXIT_DURATION_MS).easing(SLOT_GRID_EASING).delay(exitStaggerSteps * SLOT_GRID_EXIT_STAGGER_MS).reduceMotion(ReduceMotion.System);
             return /*#__PURE__*/_jsx(Animated.View, {
               entering: entering,
               exiting: exiting,

package/lib/module/components/UpiHandle/UpiHandle.js

@@ -1,14 +1,15 @@
 "use strict";
 
 import React, { useCallback, useMemo, useRef, useState } from 'react';
-import { Pressable, View, Text, Image, Platform } from 'react-native';
+import { Pressable, View, Text, Platform } 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 MediaSource 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.
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const DEFAULT_AVATAR_IMAGE = require('./Image.png');
 const IS_WEB = Platform.OS === 'web';
@@ -83,7 +84,8 @@ function resolveUpiHandleTokens(modes) {
  * @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
@@ -101,6 +103,7 @@ function UpiHandle({
   modes: propModes = EMPTY_MODES,
   showIcon = true,
   iconName = 'ic_scan_qr_code',
+  source,
   avatarSource,
   onPress,
   onClick,
@@ -149,13 +152,22 @@ function UpiHandle({
     pressed
   }) => [tokens.containerStyle, pressed ? pressedOverlayStyle : null, isFocused ? focusOverlayStyle : null], [tokens.containerStyle, isFocused]);
   const staticContainerStyle = useMemo(() => [tokens.containerStyle, isFocused ? focusOverlayStyle : null], [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 = source ?? avatarSource ?? DEFAULT_AVATAR_IMAGE;
+  const avatarSize = tokens.avatarStyle.width ?? 23;
   const innerContent = /*#__PURE__*/_jsxs(_Fragment, {
-    children: [/*#__PURE__*/_jsx(Image, {
-      source: avatarSource || DEFAULT_AVATAR_IMAGE,
+    children: [/*#__PURE__*/_jsx(View, {
       style: tokens.avatarStyle,
-      resizeMode: "cover",
-      accessibilityElementsHidden: true,
-      importantForAccessibility: "no"
+      children: /*#__PURE__*/_jsx(MediaSource, {
+        source: resolvedAvatarSource,
+        size: avatarSize,
+        resizeMode: "cover",
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no"
+      })
     }), /*#__PURE__*/_jsx(Text, {
       style: tokens.labelStyle,
       numberOfLines: 1,