@onekeyfe/react-native-native-list 6.7.0-alpha.398 → 6.7.0-alpha.400

package/android/src/main/java/com/onekey/nativelist/NativeListIdentityRenderer.kt

@@ -31,6 +31,7 @@ internal class NativeListIdentityRowView(context: ThemedReactContext, fonts: Nat
   private val titleLine = PackedTitleLineLayout(context)
   private val title = NativeListTextView(context)
   private val titleIcon = OneKeyIconView(context)
+  private var titleImage: NativeListImageSlot? = null
   private val subtitle = NativeListTextView(context)
   private val tertiary = NativeListTextView(context)
   private val badgeLine = NativeListTextView(context)
@@ -79,7 +80,7 @@ internal class NativeListIdentityRowView(context: ThemedReactContext, fonts: Nat
       "single"
     else item.json.optString("groupPosition")
 
-  override val assetFields = listOf("leading")
+  override val assetFields = listOf("leading", "titleImage")
 
   override fun usesSourceScale(item: NativeListItem, provided: Boolean) =
     item.usesSelectorSourceScale || provided
@@ -262,6 +263,29 @@ internal class NativeListIdentityRowView(context: ThemedReactContext, fonts: Nat
     leadingActionIcon.useSourceScale = sourceScale
     leadingActionIcon.setOnClickListener(null)
     bindIdentity(item, theme, item.json.optBoolean("selected"), checkboxState)
+    val titleImageDescriptor = item.json.optJSONObject("titleImage")
+    val titleImageSource = titleImageDescriptor?.optJSONObject("image")
+    if (titleImageSource != null && titleImageSource.optString("uri").isNotEmpty()) {
+      if (item.json.optString("presentation") == "walletSidebar") {
+        titleLine.packsChildrenAtStart = true
+        title.layoutParams = LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)
+      }
+      val slot = titleImage ?: NativeListImageSlot(reactContext).also { titleImage = it }
+      // Reinsert after icons so newly added suffixes cannot precede the image.
+      titleLine.removeView(slot.view)
+      titleLine.addView(slot.view, titleLine.indexOfChild(titleIcon) + 1)
+      val size = stylePx(titleImageSource.optDouble("width"))
+      slot.view.layoutParams = LayoutParams(size, size).apply { marginStart = dp(4) }
+      slot.view.visibility = VISIBLE
+      slot.view.contentDescription = titleImageDescriptor.optString("accessibilityLabel").takeIf(String::isNotEmpty)
+      slot.view.importantForAccessibility = if (slot.view.contentDescription == null)
+        View.IMPORTANT_FOR_ACCESSIBILITY_NO else View.IMPORTANT_FOR_ACCESSIBILITY_YES
+      slot.bind(titleImageSource, "${item.key}:titleImage", placeholder = "#00000000", round = true)
+    } else {
+      titleImage?.recycle()
+      titleImage?.view?.visibility = GONE
+      titleImage?.view?.contentDescription = null
+    }
     TextViewCompat.setLineHeight(
       title,
       dp(if (item.json.optString("presentation") == "walletSidebar") 16 else 24),
@@ -449,7 +473,10 @@ internal class NativeListIdentityRowView(context: ThemedReactContext, fonts: Nat
         val inner = (MeasureSpec.getSize(widthMeasureSpec) - paddingLeft - paddingRight)
           .coerceAtLeast(0)
         val leading = leadingFrame.layoutParams as LayoutParams
-        val icon = if (titleIcon.visibility == VISIBLE) dp(24) else 0
+        val imageWidth = titleImage?.view?.takeIf { it.visibility == VISIBLE }?.let {
+          it.layoutParams.width + dp(4)
+        } ?: 0
+        val icon = (if (titleIcon.visibility == VISIBLE) dp(24) else 0) + imageWidth
         (inner * ratio).roundToInt()
           .minus(leading.width + leading.marginEnd + icon)
           .coerceAtLeast(0)
@@ -555,6 +582,9 @@ internal class NativeListIdentityRowView(context: ThemedReactContext, fonts: Nat
     longPressPoint = null
     longPressPointEpoch = -1L
     leadingFrame.recycle()
+    titleImage?.recycle()
+    titleImage?.view?.visibility = GONE
+    titleImage?.view?.contentDescription = null
     trailingColumn.reset()
     currentItem = null
   }
@@ -562,6 +592,7 @@ internal class NativeListIdentityRowView(context: ThemedReactContext, fonts: Nat
   override fun disposeContent() {
     recycleContent()
     leadingFrame.dispose()
+    titleImage?.dispose()
   }
 
   private fun bindIdentity(

package/android/src/main/java/com/onekey/nativelist/NativeListModels.kt

@@ -378,7 +378,9 @@ internal fun mergeRow(original: JSONObject, changes: JSONObject): JSONObject {
   val keys = changes.keys()
   while (keys.hasNext()) {
     val key = keys.next()
-    if (key != "key" && key != "type") result.put(key, changes.get(key))
+    if (key != "key" && key != "type") {
+      if (changes.isNull(key)) result.remove(key) else result.put(key, changes.get(key))
+    }
   }
   return result
 }

package/android/src/main/java/com/onekey/nativelist/NativeListView.kt

@@ -46,6 +46,7 @@ import androidx.swiperefreshlayout.widget.SwipeRefreshLayout
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.PointerEvents
 import com.facebook.react.uimanager.ReactPointerEventsView
+import com.facebook.react.uimanager.events.NativeGestureUtil
 import com.margelo.nitro.nativelogger.OneKeyLog
 import org.json.JSONArray
 import org.json.JSONObject
@@ -221,6 +222,14 @@ class NativeListView(
       if (isLayoutSuppressed) return
       super.onLayout(changed, left, top, right, bottom)
     }
+
+    override fun dispatchTouchEvent(event: MotionEvent): Boolean {
+      val handled = super.dispatchTouchEvent(event)
+      if (event.actionMasked == MotionEvent.ACTION_UP || event.actionMasked == MotionEvent.ACTION_CANCEL) {
+        finishPagerNativeGesture(event)
+      }
+      return handled
+    }
   }
   private var configuredTopPaddingPx = 0
   private var slotInsetPx = 0
@@ -1843,6 +1852,7 @@ class NativeListView(
   // OneKey patch: vertical lists retain vertical drags and leave horizontal drags to a parent pager.
   private val pagerGestureTouchSlop = ViewConfiguration.get(context).scaledTouchSlop
   private var pagerGestureIsVertical = false
+  private var pagerNativeGestureStarted = false
   private val pagerGestureTouchListener = object : RecyclerView.SimpleOnItemTouchListener() {
     private var downX = 0f
     private var downY = 0f
@@ -1856,30 +1866,43 @@ class NativeListView(
           downY = event.y
           directionResolved = false
           pagerGestureIsVertical = false
+          pagerNativeGestureStarted = false
         }
-        MotionEvent.ACTION_MOVE -> if (!directionResolved) {
+        MotionEvent.ACTION_MOVE -> {
           val deltaX = abs(event.x - downX)
           val deltaY = abs(event.y - downY)
-          if (max(deltaX, deltaY) > pagerGestureTouchSlop) {
+          if (!directionResolved && max(deltaX, deltaY) > pagerGestureTouchSlop) {
             directionResolved = true
             pagerGestureIsVertical = deltaY >= deltaX
             recyclerView.parent?.requestDisallowInterceptTouchEvent(pagerGestureIsVertical)
-            if (
-              pagerGestureIsVertical &&
-              keyboardDismissMode == NativeListKeyboardDismissMode.ON_DRAG
-            ) {
+          } else if (!pagerGestureIsVertical && deltaY > pagerGestureTouchSlop && deltaY >= deltaX) {
+            pagerGestureIsVertical = true
+            recyclerView.parent?.requestDisallowInterceptTouchEvent(true)
+          }
+          if (pagerGestureIsVertical && !pagerNativeGestureStarted) {
+            NativeGestureUtil.notifyNativeGestureStarted(this@NativeListView, event)
+            pagerNativeGestureStarted = true
+            if (keyboardDismissMode == NativeListKeyboardDismissMode.ON_DRAG) {
               dismissKeyboard()
             }
           }
         }
         MotionEvent.ACTION_UP, MotionEvent.ACTION_CANCEL -> {
-          recyclerView.parent?.requestDisallowInterceptTouchEvent(false)
-          pagerGestureIsVertical = false
+          finishPagerNativeGesture(event)
         }
       }
       return false
     }
   }
+
+  private fun finishPagerNativeGesture(event: MotionEvent) {
+    if (pagerNativeGestureStarted) {
+      NativeGestureUtil.notifyNativeGestureEnded(this, event)
+      pagerNativeGestureStarted = false
+    }
+    recyclerView.parent?.requestDisallowInterceptTouchEvent(false)
+    pagerGestureIsVertical = false
+  }
   // Intercept only a completed tap so RecyclerView keeps drag and reorder ownership.
   private val keyboardTapTouchListener = object : RecyclerView.SimpleOnItemTouchListener() {
     private var downX = 0f

package/docs/ROW_TEMPLATES.md

@@ -59,6 +59,10 @@ separately from source implementation in STYLE_SPEC §9.
   a 4-point gap. It has no click action; an optional Web `hoverActionKey`
   emits an icon-anchored tooltip request on hover or touch. A trailing `button` is the fixed small
   secondary text action and uses the normal accessory event slot.
+- **Title image:** optional `titleImage` renders a circular image after the title
+  icons and before suffixes/badges. Its `ImageSource` dimensions must be square,
+  1...40 logical units. Optional Web `hoverActionKey` uses the existing anchored
+  help event; native keeps the image decorative for touch. See SPEC.md.
 - **Second Web help icon:** `secondaryTitleIcon` uses the same descriptor after
   `titleIcon`; each glyph has its own hover/touch anchor. Native ignores it.
 - **Decorative refresh:** a trailing `RefreshCcwOutline` without `actionKey`

package/docs/SPEC.md

@@ -176,6 +176,57 @@ after semantic text styling. Both lines retain their default size, tone, line
 height, right alignment and accessibility text. These fields add no action or
 hit target and travel in existing snapshot JSON without a Nitro ABI change.
 
+### Identity title image
+
+Status: implemented in local source, unreleased. Type checks, JS/Web tests,
+Web runtime checks, package build, iOS XCTest-target compilation, Android
+production/instrumentation-test compilation and JVM tests pass. Focused iOS
+Simulator XCTest and Android emulator instrumentation verify image lifecycle,
+null removal and wallet-sidebar layout. Complete wallet App acceptance remains
+pending.
+An `identity` row may supply `titleImage: { image, accessibilityLabel?,
+hoverActionKey? }`. `image` uses the existing `ImageSource` contract and must
+declare equal finite width and height within 1...40 logical units. The image
+is circular, follows the title and any title icons with a 4-point gap, and
+precedes title suffixes and inline badges. It reserves its declared square
+while loading or after failure, so neither state moves the text. Existing
+rows without this field keep their current layout. The image does not change
+row identity or infer a stock, issuer, or other product meaning.
+
+iOS and Android use the existing OneKeyImage-backed slot, request options and
+retry limits. Slots belong to the mounted row renderer; OneKeyImage owns image
+caches. Text-only rebinds retain an unchanged row/source request. Source or row
+changes, removal, recycling and disposal cancel prior work and prevent stale
+completion from painting the next binding. Failure leaves the reserved square
+empty; the SDK adds no title-image fallback request or separate cache.
+
+On Web, optional `hoverActionKey` uses the title icon's existing help semantics
+and `leadingAction` anchor source: mouse/pen entry opens an anchored help event,
+departure invalidates it, mouse/pen press closes it until departure, and touch
+press toggles it. Pressing this help target does not activate the row. Without
+help, the image participates in the ordinary row press. It adds no tab stop.
+Native renderers ignore this Web-only help field and preserve ordinary row
+presses. The consumer owns the tooltip text and presentation. Omitted
+`accessibilityLabel` makes the image decorative; a supplied label describes it.
+
+Android wallet-sidebar rows with a title image reserve image width and pack the
+wallet name with the image as one centered group. Long names ellipsize within
+the remaining space; removing the image restores the full-width centered name.
+
+Full snapshots without `titleImage` remove the image and old help anchor.
+Explicit patch replacement updates the descriptor; an omitted patch field
+leaves it unchanged. Null patches and empty image URIs remove the image. Development guards
+reject malformed descriptors and invalid display geometry; production sanitizes
+optional decoration as described in the validation contract. A production patch
+that supplies a malformed title-image replacement explicitly clears the old
+image and help target instead of retaining stale decoration. The field travels in existing JSON and does not change the Nitro ABI;
+consumers must use a native SDK that implements the field before enabling it.
+
+Acceptance covers protocol validation, image/source replacement and removal,
+text-only request retention, Web help-action isolation and anchor cleanup,
+native bind/recycle geometry, and native compilation. Device and complete App
+acceptance must be reported separately from source and DOM tests.
+
 ### Identity row risk-management controls
 
 Status: implemented in source for local consumers, unreleased. Focused validation,
@@ -333,6 +384,46 @@ image that already loaded. Common container styling clears what it wrote on the
 next bind, including properties it set on template children. UI mutation remains on the platform
 UI thread; [DESIGN.md](DESIGN.md) describes update and event ownership.
 
+### Android vertical-drag React touch cancellation
+
+Status: implemented; four real Android MotionEvent/JSTouchDispatcher regressions
+passed on a dedicated API 34 emulator on 2026-10-30. The focused regression is
+in `native-tests/android/NativeListTouchDeliveryTest.kt`; build and run
+instructions are in that directory's README. Physical-device press/scroll
+acceptance remains separate.
+
+This behavior applies to every vertical NativeList, including standalone lists
+outside a CollapsiblePager and touches beginning on React container slots.
+On the UI thread, movement exceeding Android touch slop with vertical
+displacement at least equal to horizontal displacement confirms a vertical
+drag. An initially horizontal movement may become vertical while the list still
+receives the stream; once vertical, ownership stays vertical until release or
+cancellation. Horizontal lists retain their existing touch behavior.
+
+The list notifies its React root of native gesture ownership once per confirmed
+drag, cancelling the active React touch before finger-up. Later MOVE events MUST
+NOT repeat that notification. The listener does not consume the stream: native
+RecyclerView scrolling continues. A stationary tap or movement below touch slop
+MUST retain ordinary React touch-end delivery without native-gesture start/end
+notifications. The existing `keyboardDismissMode: 'on-drag'` behavior shares the
+confirmed-drag boundary.
+
+ACTION_UP and ACTION_CANCEL finish a started native gesture exactly once and
+release the parent's interception restriction, even after RecyclerView has
+intercepted its child and stops invoking the item-touch interception listener.
+They clear vertical ownership; the next ACTION_DOWN resets direction and
+gesture tracking. Android's touch-target removal cancellation must finish the
+old stream before a retained list is reattached or its slots are reused, so the
+next tap is not suppressed by the previous drag. Disposal releases the listener
+through the existing detached-resource cleanup. This change adds no prop or
+callback and changes neither iOS nor Web touch handling.
+
+Conformance uses real MotionEvent dispatch through NativeListView/RecyclerView
+and React Native's JSTouchDispatcher: vertical drag produces one touch-cancel
+and one native end, a tap produces touch-end, and cancellation/removal followed
+by reuse leaves the next tap functional. This proves native touch delivery, not
+execution of a JavaScript press handler or physical-device gesture feel.
+
 ### Android reorder cancellation
 
 Status: implemented; three real Android View/callback regressions verified on
@@ -445,37 +536,61 @@ row positions. An accepted complete snapshot reuses that index only when its
 generation and ordered `(key, type)` sequence match the prior accepted
 snapshot; otherwise it replaces the index. Reorder commits rebuild it and
 disposal clears it. Patch batches reuse the index and never include retiring
-presentation rows in it. They validate the whole batch against the current
-accepted row models before changing config or presentation; invalid batches
-leave both unchanged. iOS updates only changed accepted entries in its
+presentation rows in it. Native hosts validate each received canonical batch before changing config or
+presentation; invalid native batches leave both unchanged. The shared production
+JS boundary first isolates rejected row/group units, so a native batch contains
+only accepted canonical updates. iOS updates only changed accepted entries in its
 presentation lookup after a valid patch, preserving any retiring rows.
 
 ### Validation environments and rejected input
 
-Development builds (`__DEV__ === true`) run the complete snapshot and patch
-contract assertions. Production builds run only serialization, required data
-shape, supported renderer, finite geometry, identity and patch consistency
-guards. Display budgets and style allowlists are development assertions.
-Typography token resolution runs in both environments. Production treats empty
-optional image URIs as missing images, preserving the existing visual fallback.
-An empty optional image field omitted from a patch is a no-op, matching its
-serialized native payload. Sparkline sample arrays retain their existing
-256-sample resource bound because the Web renderer passes samples as function
-arguments; this protects the runtime's argument limit.
-
-The component and Web engine contain input validation failures in both modes:
-initial invalid input renders an empty list; rejected later snapshots or patch
-batches preserve the last accepted state and are not dispatched to native.
-On iOS and Android, the React wrapper captures caller data before validation
-and owns an immutable accepted snapshot. Later caller mutation cannot rewrite
-that accepted state. Imperative selection keys are captured on entry. Eligible
-value-only `identity` and `dataRow` patches validate their complete changed
-rows; other patches and snapshots without this private ownership use the
-existing complete-snapshot validation path. This does not change exported
-validators or Web behavior.
-An `undefined` value in an eligible field stays on the changed-row path only
-when that field was already `undefined`; clearing a present value uses the
-complete-snapshot path.
+Status: implemented in source; acceptance and remaining runtime gaps are recorded below.
+
+Development runs strict contract assertions after shared null/empty-image
+normalization. Production sanitizes optional decorations without rejecting
+valid business content: invalid colors/styles are omitted, invalid images use
+existing placeholders, and positive title-image dimensions are clamped to a
+square of 1...40 logical units. Image headers are string dictionaries, never
+interpreted as geometry. Unsafe object graphs are rejected before normalization.
+
+A complete snapshot remains atomic after decoration sanitization: invalid
+schema, duplicate/missing identities, required business fields or wallet-group
+parent/children relationships reject the snapshot. No row is silently removed.
+Production normalizes contiguous group positions and filters selection to
+selectable keys, respecting none/single modes.
+
+Patches use omitted/undefined fields as no-ops. Null explicitly removes an
+optional field on JS, Web, iOS and Android; required fields cannot be cleared.
+Empty optional images and empty top-level segment arrays normalize to null in
+patches and absence in snapshots. Empty images remove their outer titleImage
+or media wrapper. This protocol requires native binaries with null-removal
+support; callers must not enable it against older native SDK implementations.
+
+Market price remains required and nonblank. Updating nonempty priceSegments
+requires a price in the same canonical patch; callers own matching formatted
+text (the validator does not reconstruct subscript prices). Updating price
+without segments clears an existing overlay. For identity/market subtitles,
+updating one representation clears the old other representation unless both
+are supplied; clearing segments alone retains the base text. Activity has no
+subtitle pair. Market quote changes with an existing/new webTable must include
+matching table data or explicitly remove webTable.
+
+Development rejects invalid patch batches atomically. Production isolates
+failures to each target key and its coupled groupId: all updates to a key are
+merged in order before validation, and a failure rejects that unit while other
+valid units commit. Financial-value and interactive accessories with missing
+required data fail their row; malformed purely decorative accessories are
+removed. Diagnostics contain locations, never row values or image URLs.
+
+All targets share the canonical accepted patches. The accepted JS rows and
+serialized native changes derive from the same result. Native owned snapshots
+and accepted Web engine snapshots validate only changed rows during patches;
+unchanged rows are not rescanned. Direct helpers receiving an unowned baseline
+validate that baseline once before incremental merging. Native owned snapshots
+are immutable and indexed by key. Initial invalid snapshots render empty;
+rejected later snapshots retain the last accepted snapshot. Rejected patch
+units retain their previous complete rows. Direct validators still throw on
+unrecoverable input. Image loading failures remain the loader's responsibility.
 
 `planNativeListPatches(previous, next)` is an explicit, pure public helper for
 callers that own two valid, immutable snapshots. It returns a readonly empty
@@ -498,14 +613,25 @@ Rejection emits a diagnostic without including row keys, text or image URLs.
 Explicit calls to the exported validation functions still throw on rejected
 input, so development tooling can inspect the full contract failure. Rejection
 does not imply that the requested update succeeded. No row identity is trimmed,
-truncated or regenerated, and no invalid row is silently dropped from a batch.
-
-Status: implemented. Development/production JS regressions pass, including
-native wrappers for iOS/Android and the Web DOM engine. Real Swift XCTest on an
-iOS 27 simulator and Android instrumentation on API 35 verify production
-serialization, normalized typography, opaque identities and duplicate-key
-protection against the shipping native parsers. Full app/device rendering and
-gesture acceptance remain separate from these input-boundary checks.
+truncated or regenerated, and no row is silently dropped from a snapshot.
+
+Acceptance for this revision: 429 JS/Web tests pass, including native React
+wrapper containment, canonical null/undefined semantics, price/segment pairing,
+production row/group isolation and unchanged-row access checks. Package type
+checks, lint (zero errors; existing warnings) and test-integrity checks pass.
+iOS production/XCTest targets and Android production/instrumentation targets
+compile; 29 Android JVM tests pass. Four focused iOS 26.5 XCTest cases verify
+title-icon packing, title-image reuse and null removal. Android 15/API 35
+instrumentation verifies wallet-sidebar image bounds, long-title ellipsis,
+and full-width title restoration after removal. Shared JS/Web regressions also
+verify that malformed production title-image replacements clear the previous
+image and help anchor. Full App acceptance remains pending.
+
+Wallet groups use the actual embedded parent/children model, not memberKeys
+references. groupId/groupPosition remain snapshot-owned fields; production
+patch failures also reject other patched rows in the same existing groupId.
+Unknown extension fields (including unsupported sparkline/changeHighlight
+models) are ignored in production rather than introducing a new renderer API.
 
 ## Platform contract
 

package/ios/NativeListIdentityRenderer.swift

@@ -91,7 +91,10 @@ final class NativeListIdentityCell: NativeListRendererCell {
       let tertiary = NativeListResolvedText(
         item.data.string("tertiary"), style: style.dictionary("tertiary"), size: 14,
         color: .black, lineHeight: 20, lines: 1, fonts: fonts)
-      let textHeight = title.measure(width: textWidth)
+      let titleImageSize = CGFloat(item.data.dictionary("titleImage")?.dictionary("image")?.double("width") ?? 0)
+      let titleImageWidth = titleImageSize > 0
+        ? titleImageSize + 4 + (item.data.dictionary("titleIcon") == nil ? 0 : 24) : 0
+      let textHeight = max(titleImageSize, title.measure(width: max(1, textWidth - titleImageWidth)))
         + subtitle.measure(width: textWidth)
         + tertiary.measure(width: textWidth)
         + (item.data.string("subtitle").isEmpty ? 0 : CGFloat(style.double("lineGap", default: 0)))
@@ -107,6 +110,8 @@ final class NativeListIdentityCell: NativeListRendererCell {
   private let titleRowStack = UIStackView()
   private let titleLabel = NativeListTextLabel()
   private let titleIconView = UIImageView()
+  private var titleImageSlot: NativeListImageSlot?
+  private var titleImageConstraints: [NSLayoutConstraint] = []
   // Absorbs the title row's slack so the title keeps its intrinsic width and the
   // title icon / badge follow the text (OK-66041); Android's PackedTitleLineLayout
   // and the Web flex row already pack the title row at its start.
@@ -131,7 +136,7 @@ final class NativeListIdentityCell: NativeListRendererCell {
   private var currentItem: NativeListItem?
   private var currentTheme: [String: Any]?
   private var leadingActionKey: String?
-  override var assetFields: [String] { ["leading"] }
+  override var assetFields: [String] { ["leading", "titleImage"] }
   override var defaultSeparatorInset: CGFloat { 60 }
   override var defaultCornerRadius: CGFloat {
     guard let item = currentItem else { return 0 }
@@ -241,6 +246,11 @@ final class NativeListIdentityCell: NativeListRendererCell {
     titleIconView.isHidden = true
     titleIconView.accessibilityLabel = nil
     titleIconView.isAccessibilityElement = false
+    titleImageSlot?.view.isHidden = true
+    titleImageSlot?.view.accessibilityLabel = nil
+    titleImageSlot?.view.isAccessibilityElement = false
+    NSLayoutConstraint.deactivate(titleImageConstraints)
+    titleImageConstraints = []
     titleRowStack.setContentHuggingPriority(.defaultLow, for: .horizontal)
     titleRowStack.setContentCompressionResistancePriority(.defaultHigh, for: .horizontal)
     for label in [titleLabel, subtitleLabel, tertiaryLabel, badgeLabel] {
@@ -303,6 +313,38 @@ final class NativeListIdentityCell: NativeListRendererCell {
       // title at `.required` the icon's 999 width constraint collapsed to 0.
       titleLabel.setContentCompressionResistancePriority(.defaultHigh, for: .horizontal)
     }
+    if let descriptor = item.data.dictionary("titleImage"),
+      let image = descriptor.dictionary("image"), !image.string("uri").isEmpty
+    {
+      let size = CGFloat(image.double("width"))
+      let slot = titleImageSlot ?? NativeListImageSlot()
+      titleImageSlot = slot
+      let view = slot.view
+      if view.superview == nil {
+        let index = titleRowStack.arrangedSubviews.firstIndex(of: titleIconView)! + 1
+        titleRowStack.insertArrangedSubview(view, at: index)
+      }
+      view.clipsToBounds = true
+      view.setContentHuggingPriority(.required, for: .horizontal)
+      view.setContentCompressionResistancePriority(.required, for: .horizontal)
+      view.translatesAutoresizingMaskIntoConstraints = false
+      view.layer.cornerRadius = size / 2
+      view.isHidden = false
+      let label = descriptor.string("accessibilityLabel")
+      view.accessibilityLabel = label.isEmpty ? nil : label
+      view.isAccessibilityElement = !label.isEmpty
+      titleImageConstraints = [
+        view.widthAnchor.constraint(equalToConstant: size),
+        view.heightAnchor.constraint(equalToConstant: size),
+      ]
+      titleImageConstraints.forEach { $0.priority = UILayoutPriority(999) }
+      NSLayoutConstraint.activate(titleImageConstraints)
+      titleRowStack.setCustomSpacing(4, after: titleIconView.isHidden ? titleLabel : titleIconView)
+      titleLabel.setContentCompressionResistancePriority(.defaultHigh, for: .horizontal)
+      slot.bind(image, key: "\(item.key):titleImage", placeholder: "#00000000")
+    } else {
+      titleImageSlot?.recycle()
+    }
     if let ratio = style["leadingContentMaxWidthRatio"] as? NSNumber,
       root.arrangedSubviews.contains(visual)
     {
@@ -339,7 +381,8 @@ final class NativeListIdentityCell: NativeListRendererCell {
       } else {
         titleRowStack.setCustomSpacing(
           CGFloat(style.double("titleBadgeGap")),
-          after: titleIconView.isHidden ? titleLabel : titleIconView)
+          after: titleImageSlot?.view.isHidden == false ? titleImageSlot!.view
+            : titleIconView.isHidden ? titleLabel : titleIconView)
       }
     }
     if style["trailingGap"] != nil { trailingStack.spacing = CGFloat(style.double("trailingGap")) }
@@ -413,6 +456,10 @@ final class NativeListIdentityCell: NativeListRendererCell {
   }
   override func recycleContent() {
     visual.recycle()
+    titleImageSlot?.recycle()
+    titleImageSlot?.view.isHidden = true
+    titleImageSlot?.view.accessibilityLabel = nil
+    titleImageSlot?.view.isAccessibilityElement = false
     trailingStack.reset()
     currentItem = nil
   }

package/ios/RNCNativeListView.swift

@@ -1530,7 +1530,10 @@ final class NativeListView: UIView {
       let previous = current.items[index]
       var merged = current.items[index].data
       changes.forEach { key, value in
-        if key != "key" && key != "type" { merged[key] = value }
+        if key != "key" && key != "type" {
+          if value is NSNull { merged.removeValue(forKey: key) }
+          else { merged[key] = value }
+        }
       }
       guard let item = try? NativeListItem(data: merged) else { return }
       if rowHeight(previous, usingCompactReorderHeight: false) != rowHeight(item, usingCompactReorderHeight: false) ||
@@ -1554,6 +1557,8 @@ final class NativeListView: UIView {
       }
       if let selected = changes["selected"] as? Bool {
         if selected { current.selectedKeys.insert(item.key) } else { current.selectedKeys.remove(item.key) }
+      } else if changes["selected"] is NSNull {
+        current.selectedKeys.remove(item.key)
       }
     }
     if !changedKeys.isEmpty { invalidateActionAnchor(reason: "snapshot") }