feature: honour gradient backgrounds and add transparent on native:list (iOS)

resources/ios/NativeUIListRenderer.swift

@@ -218,14 +218,29 @@ private struct GroupedOrPlainListStyle: ViewModifier {
 /// renders on the stock gray instead of the app's palette. When the node
 /// declares a background, hide the system scroll background and paint the
 /// node's color — matching how every other container element behaves.
+///
+/// Two more cases hide the system background without painting anything
+/// here, because the node's own `NodeStyleModifier` (which wraps this
+/// renderer) already draws what should show through:
+///   - a gradient (`bg-gradient-to-* from-* via-* to-*`, carried as
+///     `gradient_stops`), which the modifier paints behind the List;
+///   - `transparent` — the list sits directly on the screen's background
+///     (a gradient, an image, the background layer). `bg-transparent`
+///     can't express this: it packs to the same 0 as "no colour".
 private struct ListBackgroundModifier: ViewModifier {
     let node: NativeUINode
     @Environment(\.colorScheme) private var colorScheme
 
     func body(content: Content) -> some View {
         let darkBg = colorScheme == .dark ? node.props.getColor("dark_bg_color", default: 0) : 0
         let argb = darkBg != 0 ? darkBg : (node.style?.bgColor ?? 0)
-        if argb != 0 {
+        let hasGradient = !node.props.getString("gradient_stops", default: "").isEmpty
+        let transparent = node.props.getBool("transparent")
+
+        if transparent || hasGradient {
+            content
+                .scrollContentBackground(.hidden)
+        } else if argb != 0 {
             content
                 .scrollContentBackground(.hidden)
                 .background(Color(argb: argb))

src/Elements/NativeList.php

@@ -37,6 +37,9 @@ public function applyAttributes(array $attrs): void
         if (! empty($attrs['plain'])) {
             $this->plain();
         }
+        if (! empty($attrs['transparent'])) {
+            $this->transparent();
+        }
         if (isset($attrs['on-refresh']) || isset($attrs['onRefresh'])) {
             $this->onRefresh($attrs['on-refresh'] ?? $attrs['onRefresh']);
         }
@@ -81,6 +84,22 @@ public function plain(bool $value = true): static
         return $this;
     }
 
+    /**
+     * Let the screen behind the list show through. SwiftUI's `List` paints
+     * the system grouped background over whatever the screen draws; a
+     * `bg-*` colour or gradient on the list already replaces it, but a
+     * list that should sit directly on the screen's own background (a
+     * gradient, an image, a background layer) has no colour to declare —
+     * `bg-transparent` packs to the same value as "no colour". Android's
+     * `LazyColumn` draws no background of its own, so this is iOS-only.
+     */
+    public function transparent(bool $value = true): static
+    {
+        $this->listProps['transparent'] = $value;
+
+        return $this;
+    }
+
     public function onRefresh(string $method): static
     {
         $this->refreshCallback = $method;

tests/ListTest.php

@@ -0,0 +1,73 @@
+<?php
+
+use Native\Mobile\Edge\CallbackRegistry;
+use Native\Mobile\Edge\ElementRegistry;
+use Native\Mobile\Edge\Elements\Text;
+use Native\Mobile\Edge\NativeElementCollector;
+use Native\Mobile\Edge\TailwindParser;
+use Native\Mobile\UI\Elements\ListItem;
+use Native\Mobile\UI\Elements\ListSection;
+use Native\Mobile\UI\Elements\NativeList;
+
+/**
+ * Attribute → wire-prop behaviour of `native:list`, driven through core's
+ * NativeElementCollector exactly as compiled Blade drives it.
+ */
+beforeEach(function () {
+    NativeElementCollector::reset();
+    TailwindParser::clearCache();
+    ElementRegistry::reset();
+    ElementRegistry::register('text', Text::class);
+    ElementRegistry::register('list', NativeList::class);
+    ElementRegistry::register('list_section', ListSection::class);
+    ElementRegistry::register('list_item', ListItem::class);
+});
+
+afterEach(function () {
+    NativeElementCollector::reset();
+    ElementRegistry::reset();
+});
+
+function collectList(array $attrs): array
+{
+    NativeElementCollector::open('list', $attrs);
+    NativeElementCollector::open('list_section', ['header' => 'Today']);
+    NativeElementCollector::leaf('list_item', ['headline' => 'Alice won']);
+    NativeElementCollector::close();
+    NativeElementCollector::close();
+
+    return NativeElementCollector::collect()->toArray(new CallbackRegistry);
+}
+
+it('leaves the platform scroll background alone by default', function () {
+    $tree = collectList([]);
+
+    expect($tree['type'])->toBe('list')
+        ->and($tree['props'] ?? [])->not->toHaveKey('transparent')
+        ->and($tree['props'] ?? [])->not->toHaveKey('plain')
+        ->and($tree['children'][0]['type'])->toBe('list_section');
+});
+
+it('marks a list transparent so the screen background shows through', function () {
+    $tree = collectList(['transparent' => true]);
+
+    expect($tree['props']['transparent'])->toBeTrue();
+});
+
+it('accepts the list style switches together', function () {
+    $tree = collectList(['transparent' => true, 'plain' => true, 'separator' => true]);
+
+    expect($tree['props']['transparent'])->toBeTrue()
+        ->and($tree['props']['plain'])->toBeTrue()
+        ->and($tree['props']['separator'])->toBeTrue();
+});
+
+it('exposes transparent on the fluent builder', function () {
+    $list = NativeList::make()->transparent();
+
+    expect($list->toArray(new CallbackRegistry)['props']['transparent'])->toBeTrue();
+
+    $opaque = NativeList::make()->transparent(false);
+
+    expect($opaque->toArray(new CallbackRegistry)['props']['transparent'])->toBeFalse();
+});