react-native-platform-components 0.8.9 → 0.9.0

package/android/src/main/java/com/platformcomponents/PCSegmentedControlView.kt

@@ -1,13 +1,22 @@
 package com.platformcomponents
 
 import android.content.Context
+import android.content.res.ColorStateList
+import android.graphics.Color
+import android.graphics.drawable.BitmapDrawable
 import android.text.TextUtils
+import android.util.TypedValue
 import android.view.View
 import android.widget.FrameLayout
+import android.widget.LinearLayout
 import com.facebook.react.bridge.WritableNativeMap
 import com.facebook.react.uimanager.PixelUtil
 import com.facebook.react.uimanager.StateWrapper
+import com.facebook.react.views.imagehelper.ResourceDrawableIdHelper
 import com.facebook.react.views.scroll.ReactScrollViewHelper
+import com.facebook.react.views.text.ReactTypefaceUtils
+import com.google.android.material.badge.BadgeDrawable
+import com.google.android.material.badge.BadgeUtils
 import com.google.android.material.button.MaterialButton
 import com.google.android.material.button.MaterialButtonToggleGroup
 
@@ -17,8 +26,24 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
     val label: String,
     val value: String,
     val disabled: Boolean,
-    val icon: String
-  )
+    /** "", "sfSymbol" (ignored on Android), "drawable" or "image" */
+    val iconType: String,
+    val iconName: String,
+    val iconUri: String,
+    val iconScale: Float,
+    val iconTinted: Boolean,
+    val badge: String,
+    val accessibilityLabel: String
+  ) {
+    val hasIcon: Boolean get() = iconType == "drawable" || iconType == "image"
+
+    /** What TalkBack announces for the segment, badge included. */
+    val spokenLabel: String
+      get() {
+        val base = accessibilityLabel.ifEmpty { label }
+        return if (badge.isEmpty()) base else "$base, $badge"
+      }
+  }
 
   companion object {
     private const val TAG = "PCSegmentedControl"
@@ -34,9 +59,25 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
   var segments: List<Segment> = emptyList()
   var selectedValue: String = "" // sentinel for none
   var interactivity: String = "enabled" // "enabled" | "disabled"
-  var selectionRequired: Boolean = false
+  var labelVisibility: String = "auto" // "auto" | "labeled" | "unlabeled"
+  // Matches iOS, where a UISegmentedControl selection cannot be cleared by tapping.
+  var selectionRequired: Boolean = true
+
+  // --- Styling (null / empty = Material theme default) ---
+  var selectedSegmentColor: Int? = null
+  var activeTintColor: Int? = null
+  var inactiveTintColor: Int? = null
+  var rippleColor: Int? = null
+  var strokeColor: Int? = null
+  var labelFontFamily: String = ""
+  var labelFontSize: Float = 0f
+  var labelFontWeight: String = ""
+  var labelFontStyle: String = ""
+  var badgeBackgroundColor: Int? = null
+  var badgeTextColor: Int? = null
 
   // --- Events ---
+  /** index -1 with an empty value means the selection was cleared. */
   var onSelect: ((index: Int, value: String) -> Unit)? = null
 
   // --- UI ---
@@ -44,8 +85,14 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
   private val buttonIdToSegment: MutableMap<Int, Segment> = mutableMapOf()
   private var suppressCallbacks = false
 
+  /** Bumped on every rebuild so late image loads can't touch stale buttons. */
+  private var rebuildGeneration = 0
+
   init {
     minimumHeight = (PCConstants.MIN_TOUCH_TARGET_HEIGHT_DP * resources.displayMetrics.density).toInt()
+    // Badges overhang the button corner
+    clipChildren = false
+    clipToPadding = false
     rebuildUI()
   }
 
@@ -70,6 +117,16 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
     updateEnabled()
   }
 
+  fun applyLabelVisibility(value: String?) {
+    val newValue = when (value) {
+      "labeled", "unlabeled" -> value
+      else -> "auto"
+    }
+    if (labelVisibility == newValue) return
+    labelVisibility = newValue
+    rebuildUI()
+  }
+
   fun applyAndroidProps(required: Boolean) {
     if (selectionRequired != required) {
       selectionRequired = required
@@ -77,16 +134,68 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
     }
   }
 
+  fun applySelectedSegmentColor(color: Int?) {
+    if (selectedSegmentColor == color) return
+    selectedSegmentColor = color
+    rebuildUI()
+  }
+
+  fun applyActiveTintColor(color: Int?) {
+    if (activeTintColor == color) return
+    activeTintColor = color
+    rebuildUI()
+  }
+
+  fun applyInactiveTintColor(color: Int?) {
+    if (inactiveTintColor == color) return
+    inactiveTintColor = color
+    rebuildUI()
+  }
+
+  fun applyRippleColor(color: Int?) {
+    if (rippleColor == color) return
+    rippleColor = color
+    rebuildUI()
+  }
+
+  fun applyStrokeColor(color: Int?) {
+    if (strokeColor == color) return
+    strokeColor = color
+    rebuildUI()
+  }
+
+  fun applyBadgeColors(background: Int?, text: Int?) {
+    if (badgeBackgroundColor == background && badgeTextColor == text) return
+    badgeBackgroundColor = background
+    badgeTextColor = text
+    rebuildUI()
+  }
+
+  fun applyLabelStyle(fontFamily: String, fontSize: Float, fontWeight: String, fontStyle: String) {
+    if (labelFontFamily == fontFamily && labelFontSize == fontSize &&
+      labelFontWeight == fontWeight && labelFontStyle == fontStyle
+    ) return
+    labelFontFamily = fontFamily
+    labelFontSize = fontSize
+    labelFontWeight = fontWeight
+    labelFontStyle = fontStyle
+    rebuildUI()
+  }
+
   // ---- UI Building ----
 
   private fun rebuildUI() {
     removeAllViews()
     buttonIdToSegment.clear()
+    rebuildGeneration += 1
+    val generation = rebuildGeneration
 
     val group = MaterialButtonToggleGroup(context).apply {
       layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.WRAP_CONTENT)
       isSingleSelection = true
       isSelectionRequired = selectionRequired
+      clipChildren = false
+      clipToPadding = false
     }
 
     // Calculate if we need compact mode (many segments or long labels)
@@ -94,49 +203,59 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
     val useCompactMode = segments.size > 3 || totalLabelLength > 20
 
     for ((index, segment) in segments.withIndex()) {
+      // "unlabeled" hides the text of segments that have an icon; segments
+      // without one keep their label. "auto" and "labeled" show icon + label.
+      val iconOnly = labelVisibility == "unlabeled" && segment.hasIcon
+
       val button = MaterialButton(context, null, com.google.android.material.R.attr.materialButtonOutlinedStyle).apply {
         id = View.generateViewId()
-        text = segment.label
+        text = if (iconOnly) "" else segment.label
         isAllCaps = false  // Preserve original text casing
-        contentDescription = segment.label  // For accessibility and Detox matching
+        // Screen readers (and Detox) always get the label, even when hidden
+        contentDescription = segment.spokenLabel
         isEnabled = !segment.disabled && interactivity == "enabled"
 
         // Enable text truncation with ellipsis when space is limited
         ellipsize = TextUtils.TruncateAt.END
         maxLines = 1
 
-        // Reduce horizontal padding in compact mode to fit more content
-        if (useCompactMode) {
-          val compactPadding = (8 * resources.displayMetrics.density).toInt()
-          setPaddingRelative(compactPadding, paddingTop, compactPadding, paddingBottom)
-          iconPadding = (4 * resources.displayMetrics.density).toInt()
+        // Material 3 segmented buttons use 12dp horizontal padding and an 8dp
+        // icon gap (the outlined button style defaults to 24dp); tighten
+        // further when there are many segments or long labels.
+        val density = resources.displayMetrics.density
+        val horizontalPadding = ((if (useCompactMode) 8 else 12) * density).toInt()
+        setPaddingRelative(horizontalPadding, paddingTop, horizontalPadding, paddingBottom)
+        iconPadding = ((if (useCompactMode) 4 else 8) * density).toInt()
+
+        if (iconOnly) {
+          // Centre the icon instead of leaving it at the start edge
+          iconGravity = MaterialButton.ICON_GRAVITY_TEXT_START
+          iconPadding = 0
         }
 
-        // Set icon if available
-        if (segment.icon.isNotEmpty()) {
-          val resId = context.resources.getIdentifier(
-            segment.icon, "drawable", context.packageName
-          )
-          if (resId != 0) {
-            setIconResource(resId)
-          }
-        }
-
-        // Handle click to trigger selection (needed for Detox taps)
-        setOnClickListener {
-          if (!suppressCallbacks && isEnabled) {
-            group.check(id)
-          }
-        }
+        applyIcon(this, segment, generation)
+        styleButton(this, segment)
       }
 
       buttonIdToSegment[button.id] = segment
-      group.addView(button)
+      // Share the width equally (like UISegmentedControl) so trailing segments
+      // never overflow the control; long labels ellipsize instead.
+      group.addView(button, LinearLayout.LayoutParams(0, LinearLayout.LayoutParams.WRAP_CONTENT, 1f))
+      attachBadge(button, segment)
     }
 
-    group.addOnButtonCheckedListener { _, checkedId, isChecked ->
+    group.addOnButtonCheckedListener { toggleGroup, checkedId, isChecked ->
       if (suppressCallbacks) return@addOnButtonCheckedListener
-      if (!isChecked) return@addOnButtonCheckedListener
+
+      if (!isChecked) {
+        // In single-selection mode switching from A to B reports A as unchecked
+        // before B is reported as checked; by then the group already knows B is
+        // checked. Only a tap that leaves nothing checked is a real deselection.
+        if (toggleGroup.checkedButtonId == View.NO_ID) {
+          onSelect?.invoke(-1, "")
+        }
+        return@addOnButtonCheckedListener
+      }
 
       val segment = buttonIdToSegment[checkedId] ?: return@addOnButtonCheckedListener
       val index = segments.indexOf(segment)
@@ -153,6 +272,117 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
     requestLayout()
   }
 
+  /**
+   * Resolves a segment's icon. Drawable names and release-bundled assets (which
+   * React Native ships as drawable resources) resolve synchronously; other
+   * image URIs load in the background and are applied when they arrive.
+   */
+  private fun applyIcon(button: MaterialButton, segment: Segment, generation: Int) {
+    if (!segment.iconTinted) {
+      button.iconTint = null
+    }
+
+    when (segment.iconType) {
+      "drawable" -> {
+        button.icon = ResourceDrawableIdHelper.getResourceDrawable(context, segment.iconName)
+      }
+      "image" -> {
+        val uri = segment.iconUri
+        val isResourceName = !uri.contains(':')
+        if (isResourceName) {
+          button.icon = ResourceDrawableIdHelper.getResourceDrawable(context, uri)
+        } else {
+          PCImageLoader.load(context, uri, segment.iconScale) { bitmap ->
+            if (bitmap == null || generation != rebuildGeneration) return@load
+            button.icon = BitmapDrawable(resources, bitmap)
+            requestLayout()
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Draws a Material badge over the button's top-end corner. The badge lives
+   * in the button's overlay, so it needs the button's final bounds: attach
+   * after the first layout and follow later size changes.
+   */
+  private fun attachBadge(button: MaterialButton, segment: Segment) {
+    if (segment.badge.isEmpty()) return
+
+    val inset = (2 * resources.displayMetrics.density).toInt()
+    val badge = BadgeDrawable.create(context).apply {
+      text = segment.badge
+      badgeGravity = BadgeDrawable.TOP_END
+      badgeBackgroundColor?.let { backgroundColor = it }
+      badgeTextColor?.let { setBadgeTextColor(it) }
+    }
+
+    var attached = false
+    button.addOnLayoutChangeListener { view, _, _, _, _, _, _, _, _ ->
+      if (!attached) {
+        attached = true
+        BadgeUtils.attachBadgeDrawable(badge, view)
+        // The badge's size is only known once it has an anchor. Offset it by
+        // half its size so it sits fully inside the button corner; a badge
+        // that overhangs the last segment would be clipped by the control.
+        badge.horizontalOffset = badge.intrinsicWidth / 2 + inset
+        badge.verticalOffset = badge.intrinsicHeight / 2 + inset
+      }
+      badge.updateBadgeCoordinates(view)
+    }
+  }
+
+  /**
+   * Applies the color and font props on top of the Material theme defaults.
+   * Buttons are rebuilt whenever a style prop changes, so the theme values
+   * read here are always the untouched defaults.
+   */
+  private fun styleButton(button: MaterialButton, segment: Segment) {
+    val checkedState = intArrayOf(android.R.attr.state_checked)
+    val disabledState = intArrayOf(-android.R.attr.state_enabled)
+
+    if (activeTintColor != null || inactiveTintColor != null) {
+      val theme = button.textColors
+      val disabled = theme.getColorForState(disabledState, theme.defaultColor)
+      val checked = activeTintColor ?: theme.getColorForState(checkedState, theme.defaultColor)
+      val normal = inactiveTintColor ?: theme.defaultColor
+      val tint = ColorStateList(
+        arrayOf(disabledState, checkedState, intArrayOf()),
+        intArrayOf(disabled, checked, normal)
+      )
+      button.setTextColor(tint)
+      if (segment.iconTinted) {
+        button.iconTint = tint
+      }
+    }
+
+    selectedSegmentColor?.let { color ->
+      val theme = button.backgroundTintList
+      val normal = theme?.defaultColor ?: Color.TRANSPARENT
+      button.backgroundTintList = ColorStateList(
+        arrayOf(checkedState, intArrayOf()),
+        intArrayOf(color, normal)
+      )
+    }
+
+    rippleColor?.let { button.rippleColor = ColorStateList.valueOf(it) }
+    strokeColor?.let { button.strokeColor = ColorStateList.valueOf(it) }
+
+    if (labelFontSize > 0) {
+      button.setTextSize(TypedValue.COMPLEX_UNIT_SP, labelFontSize)
+    }
+    if (labelFontFamily.isNotEmpty() || labelFontWeight.isNotEmpty() || labelFontStyle.isNotEmpty()) {
+      button.typeface = ReactTypefaceUtils.applyStyles(
+        button.typeface,
+        ReactTypefaceUtils.parseFontStyle(labelFontStyle.ifEmpty { null }),
+        ReactTypefaceUtils.parseFontWeight(labelFontWeight.ifEmpty { null }),
+        labelFontFamily.ifEmpty { null },
+        context.assets
+      )
+    }
+  }
+
   private fun updateSelection() {
     suppressCallbacks = true
     val group = toggleGroup ?: return
@@ -182,6 +412,35 @@ class PCSegmentedControlView(context: Context) : FrameLayout(context), ReactScro
     }
   }
 
+  // ---- Layout ----
+
+  private var manualLayoutPending = false
+
+  /**
+   * React Native's root view ignores requestLayout after the initial pass, so
+   * a native view that changes its own subtree later (rebuilding segments for
+   * a prop change, an icon finishing loading) has to measure and lay itself
+   * out. Coalesced to one pass per frame.
+   */
+  override fun requestLayout() {
+    super.requestLayout()
+    if (!manualLayoutPending) {
+      manualLayoutPending = true
+      post { runManualLayout() }
+    }
+  }
+
+  private fun runManualLayout() {
+    manualLayoutPending = false
+    // Nothing to do until Yoga has placed us; the regular pass covers that.
+    if (width == 0 || height == 0) return
+    measure(
+      MeasureSpec.makeMeasureSpec(width, MeasureSpec.EXACTLY),
+      MeasureSpec.makeMeasureSpec(height, MeasureSpec.EXACTLY)
+    )
+    layout(left, top, right, bottom)
+  }
+
   // ---- Measurement ----
 
   override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {

package/android/src/main/java/com/platformcomponents/PCSegmentedControlViewManager.kt

@@ -52,22 +52,82 @@ class PCSegmentedControlViewManager :
     }
   }
 
-  // segments: array of {label, value, disabled, icon}
+  private fun ReadableMap.stringOr(key: String, fallback: String): String =
+    if (hasKey(key) && !isNull(key)) getString(key) ?: fallback else fallback
+
+  private fun ReadableMap.doubleOr(key: String, fallback: Double): Double =
+    if (hasKey(key) && !isNull(key)) getDouble(key) else fallback
+
+  // segments: array of {label, value, disabled, iconType, iconName, iconUri,
+  //                     iconScale, iconTinted, accessibilityLabel}
   override fun setSegments(view: PCSegmentedControlView, value: ReadableArray?) {
     val out = ArrayList<PCSegmentedControlView.Segment>()
     if (value != null) {
       for (i in 0 until value.size()) {
         val m = value.getMap(i) ?: continue
-        val label = if (m.hasKey("label") && !m.isNull("label")) m.getString("label") ?: "" else ""
-        val segValue = if (m.hasKey("value") && !m.isNull("value")) m.getString("value") ?: "" else ""
-        val disabled = m.hasKey("disabled") && !m.isNull("disabled") && m.getString("disabled") == "disabled"
-        val icon = if (m.hasKey("icon") && !m.isNull("icon")) m.getString("icon") ?: "" else ""
-        out.add(PCSegmentedControlView.Segment(label = label, value = segValue, disabled = disabled, icon = icon))
+        val scale = m.doubleOr("iconScale", 1.0)
+        out.add(
+          PCSegmentedControlView.Segment(
+            label = m.stringOr("label", ""),
+            value = m.stringOr("value", ""),
+            disabled = m.stringOr("disabled", "enabled") == "disabled",
+            iconType = m.stringOr("iconType", ""),
+            iconName = m.stringOr("iconName", ""),
+            iconUri = m.stringOr("iconUri", ""),
+            iconScale = if (scale > 0) scale.toFloat() else 1f,
+            iconTinted = m.stringOr("iconTinted", "true") != "false",
+            badge = m.stringOr("badge", ""),
+            accessibilityLabel = m.stringOr("accessibilityLabel", "")
+          )
+        )
       }
     }
     view.applySegments(out)
   }
 
+  override fun setLabelVisibility(view: PCSegmentedControlView, value: String?) {
+    view.applyLabelVisibility(value)
+  }
+
+  // Colors arrive already processed by React Native (ARGB ints)
+  override fun setSelectedSegmentColor(view: PCSegmentedControlView, value: Int?) {
+    view.applySelectedSegmentColor(value)
+  }
+
+  override fun setActiveTintColor(view: PCSegmentedControlView, value: Int?) {
+    view.applyActiveTintColor(value)
+  }
+
+  override fun setInactiveTintColor(view: PCSegmentedControlView, value: Int?) {
+    view.applyInactiveTintColor(value)
+  }
+
+  override fun setAndroidRippleColor(view: PCSegmentedControlView, value: Int?) {
+    view.applyRippleColor(value)
+  }
+
+  override fun setAndroidStrokeColor(view: PCSegmentedControlView, value: Int?) {
+    view.applyStrokeColor(value)
+  }
+
+  override fun setBadgeBackgroundColor(view: PCSegmentedControlView, value: Int?) {
+    view.applyBadgeColors(value, view.badgeTextColor)
+  }
+
+  override fun setBadgeTextColor(view: PCSegmentedControlView, value: Int?) {
+    view.applyBadgeColors(view.badgeBackgroundColor, value)
+  }
+
+  // labelStyle: {fontFamily, fontSize, fontWeight, fontStyle}; empty / 0 = default
+  override fun setLabelStyle(view: PCSegmentedControlView, value: ReadableMap?) {
+    view.applyLabelStyle(
+      fontFamily = value?.stringOr("fontFamily", "") ?: "",
+      fontSize = value?.doubleOr("fontSize", 0.0)?.toFloat() ?: 0f,
+      fontWeight = value?.stringOr("fontWeight", "") ?: "",
+      fontStyle = value?.stringOr("fontStyle", "") ?: ""
+    )
+  }
+
   override fun setSelectedValue(view: PCSegmentedControlView, value: String?) {
     // Spec sentinel: empty string means "no selection"
     view.applySelectedValue(value ?: "")
@@ -78,8 +138,14 @@ class PCSegmentedControlViewManager :
   }
 
   override fun setAndroid(view: PCSegmentedControlView, value: ReadableMap?) {
-    val selectionRequired = value != null && value.hasKey("selectionRequired") &&
-      !value.isNull("selectionRequired") && value.getString("selectionRequired") == "true"
+    // Spec sentinel: "true" | "false"; missing means the default (required).
+    val selectionRequired = if (
+      value != null && value.hasKey("selectionRequired") && !value.isNull("selectionRequired")
+    ) {
+      value.getString("selectionRequired") != "false"
+    } else {
+      true
+    }
     view.applyAndroidProps(selectionRequired)
   }
 

package/ios/PCConstants.swift

@@ -19,11 +19,47 @@ enum PCConstants {
     /// Minimum row height in selection menu popover (used as baseline)
     static let popoverRowHeightMin: CGFloat = 44
 
-    /// Dynamic row height that respects user's preferred content size
+    /// Horizontal inset applied to each side of a menu row's label
+    static let popoverRowHorizontalInset: CGFloat = 16
+
+    /// Vertical padding added to each menu row's text (top + bottom combined)
+    static let popoverRowVerticalPadding: CGFloat = 16
+
+    /// Estimated single-line row height that respects the user's preferred
+    /// content size. Used only as a table-view estimate; actual rows self-size.
     static var popoverRowHeight: CGFloat {
         let bodyFont = UIFont.preferredFont(forTextStyle: .body)
-        // Row height = font line height + vertical padding (16pt total)
-        return max(popoverRowHeightMin, ceil(bodyFont.lineHeight) + 16)
+        return max(popoverRowHeightMin, ceil(bodyFont.lineHeight) + popoverRowVerticalPadding)
+    }
+
+    /// Measured height of a single menu row for the given label and content
+    /// width, accounting for multi-line wrapping at the current Dynamic Type
+    /// size. Mirrors the Auto Layout sizing of `PCGlassMenuCell` so the popover
+    /// container can be sized to fit its content.
+    static func popoverRowHeight(forLabel label: String, width: CGFloat) -> CGFloat {
+        let bodyFont = UIFont.preferredFont(forTextStyle: .body)
+        let textWidth = max(1, width - popoverRowHorizontalInset * 2)
+        let bounding = (label as NSString).boundingRect(
+            with: CGSize(width: textWidth, height: .greatestFiniteMagnitude),
+            options: [.usesLineFragmentOrigin, .usesFontLeading],
+            attributes: [.font: bodyFont],
+            context: nil
+        )
+        return max(popoverRowHeightMin, ceil(bounding.height) + popoverRowVerticalPadding)
+    }
+
+    /// Adaptive popover width. Widens for accessibility content size categories
+    /// so long labels wrap less aggressively (mirrors system menu behavior).
+    /// The caller is responsible for clamping to the available screen width.
+    static func popoverWidth(forCategory category: UIContentSizeCategory) -> CGFloat {
+        guard category.isAccessibilityCategory else { return popoverWidth }
+        switch category {
+        case .accessibilityMedium: return 300
+        case .accessibilityLarge: return 320
+        case .accessibilityExtraLarge: return 340
+        case .accessibilityExtraExtraLarge: return 360
+        default: return 380 // accessibilityExtraExtraExtraLarge and beyond
+        }
     }
 
     /// Vertical padding in selection menu popover (top + bottom)

package/ios/PCImageLoader.swift

@@ -0,0 +1,58 @@
+import UIKit
+
+/// Loads images referenced by React Native asset URIs for native controls that
+/// take a `UIImage` (segmented control icons).
+///
+/// Release builds bundle local assets next to the JS bundle, so those arrive as
+/// `file://` URLs and load synchronously. Debug builds and remote sources arrive
+/// as `http(s)://` (Metro) or `data:` URLs and load asynchronously.
+///
+/// Must be used from the main thread.
+final class PCImageLoader {
+    static let shared = PCImageLoader()
+
+    private var cache: [String: UIImage] = [:]
+    private var pending: [String: [(UIImage?) -> Void]] = [:]
+
+    /// Returns the image immediately when it is cached or readable from disk.
+    /// Otherwise starts a load and calls `completion` on the main thread with
+    /// the result; the return value is `nil` in that case.
+    @discardableResult
+    func image(
+        uri: String,
+        scale: CGFloat,
+        completion: @escaping (UIImage?) -> Void
+    ) -> UIImage? {
+        let key = "\(uri)@\(scale)x"
+        if let cached = cache[key] {
+            return cached
+        }
+
+        guard let url = URL(string: uri) else { return nil }
+
+        if url.isFileURL {
+            guard let data = try? Data(contentsOf: url),
+                  let image = UIImage(data: data, scale: scale) else { return nil }
+            cache[key] = image
+            return image
+        }
+
+        if pending[key] != nil {
+            pending[key]?.append(completion)
+            return nil
+        }
+        pending[key] = [completion]
+
+        URLSession.shared.dataTask(with: url) { [weak self] data, _, _ in
+            let image = data.flatMap { UIImage(data: $0, scale: scale) }
+            DispatchQueue.main.async {
+                guard let self else { return }
+                if let image { self.cache[key] = image }
+                let callbacks = self.pending.removeValue(forKey: key) ?? []
+                callbacks.forEach { $0(image) }
+            }
+        }.resume()
+
+        return nil
+    }
+}