jfs-components 0.0.63 → 0.0.65

package/lib/commonjs/components/Section/Section.js

@@ -6,8 +6,11 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
 var _reactNative = require("react-native");
+var _reactNativeReanimated = _interopRequireWildcard(require("react-native-reanimated"));
 var _figmaVariablesResolver = require("../../design-tokens/figma-variables-resolver");
 var _NavArrow = _interopRequireDefault(require("../NavArrow/NavArrow"));
+var _IconCapsule = _interopRequireDefault(require("../IconCapsule/IconCapsule"));
+var _ListItem = _interopRequireDefault(require("../ListItem/ListItem"));
 var _webPlatformUtils = require("../../utils/web-platform-utils");
 var _reactUtils = require("../../utils/react-utils");
 var _jsxRuntime = require("react/jsx-runtime");
@@ -37,76 +40,95 @@ const headerFocusStyle = {
 };
 
 // ---------------------------------------------------------------------------
-// Shared grid layout: measures the widest child once per item-count, then
-// renders uniform-width cells laid out with `justify-content: space-between`.
-// This preserves three visual invariants regardless of viewport width:
+// Shared grid layout — first-row-anchored sizing.
+//
+// We measure each cell of the *first row* via `onLayout`, take their max as
+// the canonical cellWidth, then apply that explicit width to every cell in
+// every row. Combined with `justify-content: space-between`, this preserves
+// three visual invariants regardless of viewport width:
 //   1. The first cell hugs the container's left edge.
 //   2. The last cell hugs the container's right edge.
 //   3. Cells in row N column K align with cells in row N+1 column K
 //      (uniform cell width across the whole grid).
-// Pure flex sizing (e.g. `flexBasis: 0; flexGrow: 1`) cannot satisfy (1) and
-// (2) on wide viewports — it distributes extra space inside each cell, which
-// makes the icon+label content drift toward each cell's center and produces
-// visible "dead" margins on the left and right of the grid.
 //
-// To avoid the blank-flash that the previous implementation suffered from
-// (it hid the grid with `opacity: 0` until measurement completed, and reset
-// every measurement when the item count changed):
-//   * Cells render at their *natural* widths during measurement instead of
-//     being hidden. With `space-between`, the first/last cells already hug
-//     the edges; only the column alignment can be off by a few pixels for
-//     the single frame between mount and the onLayout callback.
-//   * On item-count change (e.g. expand / collapse), we clear the per-cell
-//     samples but keep the rendered layout visible — we never blank out.
-//   * No 500ms safety timeout is needed because the grid is visible from the
-//     first frame.
+// Why first-row-anchored?
+//
+// The first row is *always present* (collapsed and expanded both render it),
+// so the measurement happens exactly once on first mount and stays valid for
+// the lifetime of the SlotGrid — the cellWidth is *stable across toggles*.
+// New cells in row 2+ mount when the user expands, and by that time
+// `cellWidth` is already cached, so their `Animated.View` `entering` cascade
+// is never interrupted by a re-measurement-driven re-render.
+//
+// Why not container-width math (e.g. `(containerWidth - gaps) / columns`)?
+// That makes every cell wide enough to fill its share of the row. On wide
+// viewports each cell becomes much wider than its content (icon + label),
+// the content centers inside its oversized cell, and the visible result is
+// a "dead margin" of empty space on the left and right of the grid. Sizing
+// cells to natural content + `space-between` instead pushes the first cell
+// flush left and the last cell flush right, distributing leftover space as
+// the inter-cell gap.
+//
+// Why not measure every cell?
+// The original implementation did, and `max()` could change when the item
+// count changed (collapsed picks one max, expanded another), producing a
+// visible width jump on toggle. The per-cell remeasurement also forced a
+// re-render in the same React batch as the `entering` animation mounting,
+// which Reanimated treats as a cancellation signal — cells visibly didn't
+// animate. Anchoring to the first row eliminates both costs.
+//
+// First-frame behavior is preserved (no blank-flash): until the first-row
+// `onLayout` fires, cells render at their natural width with `space-between`
+// already laying them out correctly; the only thing that changes after
+// measurement is that subsequent rows snap to the same cellWidth so columns
+// align.
 // ---------------------------------------------------------------------------
 const SLOT_GRID_MAX_COLUMNS = 4;
-const slotGridRowStyle = {
+
+// Beyond this many "extra" cells, additional cells reuse the cap delay so very
+// large grids (16, 32, …) still feel snappy instead of cascading for >1s.
+const SLOT_GRID_STAGGER_CAP = 8;
+const SLOT_GRID_ENTER_STAGGER_MS = 35;
+const SLOT_GRID_EXIT_STAGGER_MS = 20;
+const SLOT_GRID_EXIT_DURATION_MS = 160;
+const slotGridRowFlowStyle = {
   flexDirection: 'row',
   justifyContent: 'space-between'
 };
 const SlotGrid = /*#__PURE__*/_react.default.memo(function SlotGrid({
   items,
   gap,
-  maxColumns = SLOT_GRID_MAX_COLUMNS
+  maxColumns = SLOT_GRID_MAX_COLUMNS,
+  animateExtrasFromIndex,
+  animateContainerLayout
 }) {
   const totalItems = items.length;
-  const [maxItemWidth, setMaxItemWidth] = (0, _react.useState)(null);
-  // Tracks the item-count that `maxItemWidth` corresponds to. When the
-  // current `totalItems` differs, the existing measurement is considered
-  // stale and cells fall back to natural widths until remeasurement.
-  const [measuredForCount, setMeasuredForCount] = (0, _react.useState)(0);
-  const itemWidthsRef = (0, _react.useRef)(new Map());
+  const columns = Math.min(maxColumns, totalItems || 1);
+  // Number of cells in the first row. Capped by `columns` (a fully-filled row)
+  // and by `totalItems` (e.g. a 1-item grid has a 1-cell first row).
+  const firstRowSize = Math.min(columns, totalItems);
 
-  // Synchronously invalidate per-cell samples when the item count changes
-  // (e.g. show more / less). We deliberately do NOT touch `maxItemWidth` or
-  // `measuredForCount` state here — flipping them would force an extra render
-  // pass; instead we let the count mismatch (`measuredForCount !== totalItems`)
-  // gate the use of the stale value, and the next onLayout cycle will publish
-  // a fresh `maxItemWidth` for the new count.
-  const prevTotalRef = (0, _react.useRef)(totalItems);
-  if (prevTotalRef.current !== totalItems) {
-    prevTotalRef.current = totalItems;
-    itemWidthsRef.current = new Map();
-  }
-  const handleItemLayout = (0, _react.useCallback)((index, width) => {
-    const widths = itemWidthsRef.current;
+  // First-row width measurement. Only cells whose `itemIndex < firstRowSize`
+  // get an `onLayout` callback. Once we have a width sample for each first-row
+  // cell, we publish the max and the callbacks become inert — no further
+  // measurement happens for the rest of the SlotGrid's lifetime, so toggles
+  // never trigger a re-measurement-driven re-render.
+  const [firstRowMaxWidth, setFirstRowMaxWidth] = (0, _react.useState)(null);
+  const firstRowWidthsRef = (0, _react.useRef)(new Map());
+  const handleFirstRowItemLayout = (0, _react.useCallback)((index, width) => {
+    const widths = firstRowWidthsRef.current;
     const previous = widths.get(index);
     if (previous !== undefined && Math.abs(previous - width) < 0.5) return;
     widths.set(index, width);
-    if (widths.size >= totalItems && totalItems > 0) {
+    if (widths.size >= firstRowSize && firstRowSize > 0) {
       let newMax = 0;
       for (const w of widths.values()) {
         if (w > newMax) newMax = w;
       }
-      setMaxItemWidth(prev => prev !== null && Math.abs(prev - newMax) < 0.5 ? prev : newMax);
-      setMeasuredForCount(totalItems);
+      setFirstRowMaxWidth(prev => prev !== null && Math.abs(prev - newMax) < 0.5 ? prev : newMax);
     }
-  }, [totalItems]);
-  const hasFreshMeasurement = maxItemWidth !== null && measuredForCount === totalItems;
-  const cellWidth = hasFreshMeasurement ? maxItemWidth : undefined;
-  const columns = Math.min(maxColumns, totalItems || 1);
+  }, [firstRowSize]);
+  const cellWidth = firstRowMaxWidth;
   const rows = [];
   for (let i = 0; i < items.length; i += columns) {
     rows.push(items.slice(i, i + columns));
@@ -114,34 +136,131 @@ const SlotGrid = /*#__PURE__*/_react.default.memo(function SlotGrid({
   const containerStyle = (0, _react.useMemo)(() => ({
     gap
   }), [gap]);
-  const measuredCellStyle = (0, _react.useMemo)(() => cellWidth !== undefined ? {
+  const cellStyle = (0, _react.useMemo)(() => cellWidth !== null ? {
     width: cellWidth
   } : undefined, [cellWidth]);
-  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-    style: containerStyle,
+
+  // `space-between` distributes any leftover row space as inter-cell gap, so
+  // the first cell is flush-left and the last cell is flush-right regardless
+  // of whether cellWidth has been measured yet. Identical layout strategy
+  // before and after measurement — no first-frame layout shift.
+  const rowStyle = slotGridRowFlowStyle;
+  const animationsEnabled = animateExtrasFromIndex !== undefined;
+  // Resolve the threshold once. When undefined we treat it as
+  // Number.POSITIVE_INFINITY so the per-cell branch always picks the plain
+  // `<View>` path.
+  const extrasThreshold = animationsEnabled ? animateExtrasFromIndex : Number.POSITIVE_INFINITY;
+  // Total count of "extra" cells currently rendered. Used to compute the
+  // reverse-stagger delay for the exiting animation so that the last cell
+  // leaves first.
+  const extrasCount = animationsEnabled ? Math.max(0, totalItems - extrasThreshold) : 0;
+  const useAnimatedContainer = animateContainerLayout === true;
+
+  // Explicit-height clip animation:
+  //
+  // Reanimated's `LinearTransition` interpolates the container's bounds, and
+  // in practice that interpolation drags on the cells inside (they momentarily
+  // appear squashed because the parent is shorter than its natural content
+  // for the duration of the animation). To keep cells at their *natural size
+  // throughout*, we instead:
+  //   1. Render the rows inside an inner `<View>` that sizes to its content
+  //      naturally — cells are never squeezed, never resized.
+  //   2. Wrap that inner view in an `Animated.View` with `overflow: 'hidden'`
+  //      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.
+  //
+  // Visually: the container reveals/conceals content like a curtain, and the
+  // cells never deform.
+  const animatedHeight = (0, _reactNativeReanimated.useSharedValue)(-1);
+  const isFirstHeightLayoutRef = (0, _react.useRef)(true);
+  const handleContentLayout = (0, _react.useCallback)(e => {
+    const h = e.nativeEvent.layout.height;
+    if (h <= 0) return;
+    if (isFirstHeightLayoutRef.current) {
+      isFirstHeightLayoutRef.current = false;
+      animatedHeight.value = h;
+      return;
+    }
+    animatedHeight.value = (0, _reactNativeReanimated.withSpring)(h, {
+      damping: 22,
+      stiffness: 180,
+      reduceMotion: _reactNativeReanimated.ReduceMotion.System
+    });
+  }, [animatedHeight]);
+  const animatedHeightStyle = (0, _reactNativeReanimated.useAnimatedStyle)(() => animatedHeight.value < 0 ? {} : {
+    height: animatedHeight.value,
+    overflow: 'hidden'
+  });
+  const rowsChildren = /*#__PURE__*/(0, _jsxRuntime.jsx)(_jsxRuntime.Fragment, {
     children: rows.map((row, rowIndex) => {
       const spacersNeeded = row.length < columns ? columns - row.length : 0;
       return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
-        style: slotGridRowStyle,
+        style: rowStyle,
         children: [row.map((child, colIndex) => {
           const itemIndex = rowIndex * columns + colIndex;
+          // Only first-row cells participate in measurement, and only
+          // until firstRowMaxWidth has been published. After that the
+          // onLayout becomes a no-op (we elide it).
+          const onLayoutHandler = firstRowMaxWidth === null && itemIndex < firstRowSize ? e => handleFirstRowItemLayout(itemIndex, e.nativeEvent.layout.width) : undefined;
+          if (itemIndex >= extrasThreshold) {
+            const extraOrdinal = itemIndex - extrasThreshold;
+            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 = _reactNativeReanimated.FadeInUp.springify().damping(18).delay(enterStaggerSteps * SLOT_GRID_ENTER_STAGGER_MS).reduceMotion(_reactNativeReanimated.ReduceMotion.System);
+            const exiting = _reactNativeReanimated.FadeOutUp.duration(SLOT_GRID_EXIT_DURATION_MS).delay(exitStaggerSteps * SLOT_GRID_EXIT_STAGGER_MS).reduceMotion(_reactNativeReanimated.ReduceMotion.System);
+            return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeReanimated.default.View, {
+              entering: entering,
+              exiting: exiting,
+              ...(onLayoutHandler ? {
+                onLayout: onLayoutHandler
+              } : null),
+              style: cellStyle,
+              children: child
+            }, itemIndex);
+          }
           return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-            onLayout: hasFreshMeasurement ? undefined : e => handleItemLayout(itemIndex, e.nativeEvent.layout.width),
-            style: measuredCellStyle,
+            ...(onLayoutHandler ? {
+              onLayout: onLayoutHandler
+            } : null),
+            style: cellStyle,
             children: child
           }, itemIndex);
-        }), hasFreshMeasurement && spacersNeeded > 0 && Array.from({
+        }), cellWidth !== null && spacersNeeded > 0 && Array.from({
           length: spacersNeeded
         }, (_, i) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
-          style: measuredCellStyle
+          style: cellStyle
         }, `spacer-${i}`))]
       }, rowIndex);
     })
   });
+  if (useAnimatedContainer) {
+    // Outer Animated.View clips and animates height. Inner View holds the
+    // rows at natural size and reports its natural height for the spring
+    // target. Cell-width measurement happens on the cells themselves
+    // (first-row only) — no container-level onLayout is needed.
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNativeReanimated.default.View, {
+      style: animatedHeightStyle,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: containerStyle,
+        onLayout: handleContentLayout,
+        children: rowsChildren
+      })
+    });
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: containerStyle,
+    children: rowsChildren
+  });
 }, slotGridPropsAreEqual);
 function slotGridPropsAreEqual(prev, next) {
   if (prev.gap !== next.gap) return false;
   if ((prev.maxColumns ?? SLOT_GRID_MAX_COLUMNS) !== (next.maxColumns ?? SLOT_GRID_MAX_COLUMNS)) return false;
+  if (prev.animateExtrasFromIndex !== next.animateExtrasFromIndex) return false;
+  if (prev.animateContainerLayout !== next.animateContainerLayout) return false;
   if (prev.items === next.items) return true;
   if (prev.items.length !== next.items.length) return false;
   for (let i = 0; i < prev.items.length; i++) {
@@ -428,9 +547,17 @@ function SectionBento({
   // Same rationale as Section: accepted on the type but unused internally.
   accessibilityLabel: _accessibilityLabel,
   accessibilityHint,
+  collapsedCount = SLOT_GRID_MAX_COLUMNS,
+  defaultExpanded = false,
+  expanded: controlledExpanded,
+  onExpandedChange,
+  toggleMoreLabel = 'More',
+  toggleLessLabel = 'Less',
+  toggleMoreIcon = 'ic_chevron_down',
+  toggleLessIcon = 'ic_chevron_up',
+  renderToggle,
   ...rest
 }) {
-  // Resolve section container tokens
   const backgroundColor = (0, _figmaVariablesResolver.getVariableByName)('section/background/color', modes) || '#ffffff';
   const gap = (0, _figmaVariablesResolver.getVariableByName)('section/gap', modes) || 12;
   const paddingHorizontal = (0, _figmaVariablesResolver.getVariableByName)('section/padding/horizontal', modes) || 12;
@@ -445,6 +572,51 @@ function SectionBento({
   }), [backgroundColor, paddingHorizontal, paddingVertical, radius, gap]);
   const processedNavSlot = (0, _react.useMemo)(() => navSlot ? (0, _reactUtils.cloneChildrenWithModes)((0, _reactUtils.flattenChildren)(navSlot), modes) : null, [navSlot, modes]);
   const processedUpiSlot = (0, _react.useMemo)(() => upiSlot ? (0, _reactUtils.cloneChildrenWithModes)((0, _reactUtils.flattenChildren)(upiSlot), modes) : null, [upiSlot, modes]);
+
+  // `canExpand` is true iff there are strictly more real items than fit into
+  // the collapsed grid. When `allRealItems.length === collapsedCount` we just
+  // render them all with no toggle — identical to the pre-feature behavior.
+  const allRealItems = (0, _react.useMemo)(() => processedNavSlot ?? [], [processedNavSlot]);
+  const canExpand = allRealItems.length > collapsedCount;
+  const isControlled = controlledExpanded !== undefined;
+  const [internalExpanded, setInternalExpanded] = (0, _react.useState)(defaultExpanded);
+  const expanded = isControlled ? controlledExpanded : internalExpanded;
+
+  // Mirror onExpandedChange in a ref so `toggle` can stay referentially stable.
+  const onExpandedChangeRef = (0, _react.useRef)(onExpandedChange);
+  onExpandedChangeRef.current = onExpandedChange;
+  const isControlledRef = (0, _react.useRef)(isControlled);
+  isControlledRef.current = isControlled;
+  const expandedRef = (0, _react.useRef)(expanded);
+  expandedRef.current = expanded;
+  const toggle = (0, _react.useCallback)(() => {
+    const next = !expandedRef.current;
+    if (!isControlledRef.current) {
+      setInternalExpanded(next);
+    }
+    onExpandedChangeRef.current?.(next);
+  }, []);
+  const navGridItems = (0, _react.useMemo)(() => {
+    if (!canExpand) {
+      return allRealItems;
+    }
+    // Leave the last collapsed slot for the toggle cell.
+    const visibleRealItems = expanded ? allRealItems : allRealItems.slice(0, collapsedCount - 1);
+    const toggleNode = renderToggle ? renderToggle({
+      expanded,
+      toggle
+    }) : /*#__PURE__*/(0, _jsxRuntime.jsx)(DefaultBentoToggle, {
+      expanded: expanded,
+      onPress: toggle,
+      modes: modes,
+      moreLabel: toggleMoreLabel,
+      lessLabel: toggleLessLabel,
+      moreIcon: toggleMoreIcon,
+      lessIcon: toggleLessIcon,
+      extraCount: allRealItems.length - (collapsedCount - 1)
+    });
+    return [...visibleRealItems, toggleNode];
+  }, [canExpand, allRealItems, expanded, collapsedCount, renderToggle, toggle, modes, toggleMoreLabel, toggleLessLabel, toggleMoreIcon, toggleLessIcon]);
   return /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
     style: [containerStyle, style],
     ...(_reactNative.Platform.OS === 'web' ? {
@@ -453,9 +625,13 @@ function SectionBento({
     accessibilityLabel: undefined,
     accessibilityHint: accessibilityHint,
     ...rest,
-    children: [processedNavSlot && /*#__PURE__*/(0, _jsxRuntime.jsx)(SlotGrid, {
-      items: processedNavSlot,
-      gap: gap
+    children: [navGridItems.length > 0 && /*#__PURE__*/(0, _jsxRuntime.jsx)(SlotGrid, {
+      items: navGridItems,
+      gap: gap,
+      ...(canExpand ? {
+        animateExtrasFromIndex: collapsedCount,
+        animateContainerLayout: true
+      } : null)
     }), processedUpiSlot && /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
       style: sectionBentoUpiRowStyle,
       children: processedUpiSlot
@@ -463,6 +639,52 @@ function SectionBento({
   });
 }
 
+// ---------------------------------------------------------------------------
+// DefaultBentoToggle — internal toggle cell rendered by `SectionBento` when no
+// `renderToggle` prop is provided. Uses a vertical `ListItem` so the cell
+// matches the visual rhythm of the surrounding nav items in every mode.
+//
+// Two icons (`ic_chevron_down` / `ic_chevron_up`) are used instead of a
+// rotating single icon, because the toggle cell is reconciled by position
+// (collapsed: end of row 1; expanded: end of last row), so any persistent
+// shared-value-driven rotation would lose its anchor across toggles.
+// ---------------------------------------------------------------------------
+
+function DefaultBentoToggle({
+  expanded,
+  onPress,
+  modes,
+  moreLabel,
+  lessLabel,
+  moreIcon,
+  lessIcon,
+  extraCount
+}) {
+  const label = expanded ? lessLabel : moreLabel;
+  const iconName = expanded ? lessIcon : moreIcon;
+  const accessibilityState = (0, _react.useMemo)(() => ({
+    expanded
+  }), [expanded]);
+  const webAccessibilityProps = (0, _react.useMemo)(() => ({
+    ariaExpanded: expanded
+  }), [expanded]);
+  const accessibilityHint = expanded ? `Hides ${extraCount} additional ${extraCount === 1 ? 'action' : 'actions'}` : `Shows ${extraCount} additional ${extraCount === 1 ? 'action' : 'actions'}`;
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_ListItem.default, {
+    layout: "Vertical",
+    supportText: label,
+    leading: /*#__PURE__*/(0, _jsxRuntime.jsx)(_IconCapsule.default, {
+      iconName: iconName,
+      modes: modes
+    }),
+    modes: modes,
+    onPress: onPress,
+    accessibilityLabel: label,
+    accessibilityHint: accessibilityHint,
+    accessibilityState: accessibilityState,
+    webAccessibilityProps: webAccessibilityProps
+  });
+}
+
 // Attach Bento as a property of Section using namespace pattern
 Section.Bento = SectionBento;
 var _default = exports.default = Section;

package/lib/commonjs/components/UpiHandle/UpiHandle.js

@@ -9,12 +9,13 @@ var _reactNative = require("react-native");
 var _figmaVariablesResolver = require("../../design-tokens/figma-variables-resolver");
 var _JFSThemeProvider = require("../../design-tokens/JFSThemeProvider");
 var _reactUtils = require("../../utils/react-utils");
+var _MediaSource = _interopRequireDefault(require("../../utils/MediaSource"));
 var _Icon = _interopRequireDefault(require("../../icons/Icon"));
 var _jsxRuntime = require("react/jsx-runtime");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 // 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 = _reactNative.Platform.OS === 'web';
 const IS_IOS = _reactNative.Platform.OS === 'ios';
@@ -88,7 +89,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
@@ -106,6 +108,7 @@ function UpiHandle({
   modes: propModes = _reactUtils.EMPTY_MODES,
   showIcon = true,
   iconName = 'ic_scan_qr_code',
+  source,
   avatarSource,
   onPress,
   onClick,
@@ -154,13 +157,22 @@ function UpiHandle({
     pressed
   }) => [tokens.containerStyle, pressed ? pressedOverlayStyle : null, isFocused ? focusOverlayStyle : null], [tokens.containerStyle, isFocused]);
   const staticContainerStyle = (0, _react.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__*/(0, _jsxRuntime.jsxs)(_jsxRuntime.Fragment, {
-    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Image, {
-      source: avatarSource || DEFAULT_AVATAR_IMAGE,
+    children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
       style: tokens.avatarStyle,
-      resizeMode: "cover",
-      accessibilityElementsHidden: true,
-      importantForAccessibility: "no"
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_MediaSource.default, {
+        source: resolvedAvatarSource,
+        size: avatarSize,
+        resizeMode: "cover",
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no"
+      })
     }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
       style: tokens.labelStyle,
       numberOfLines: 1,