Handle non-event on_ fields in diff and protocol logic (#5742)

* Handle non-event 'on_' fields in diff and protocol logic

Updates diffing and protocol encoding logic to distinguish 'on_' fields that are not events using metadata. Adds integration tests for color scheme, new test cases for 'on_' fields, and updates ColorScheme to mark non-event 'on_' fields. This improves accuracy of change detection and serialization for controls with 'on_' prefixed fields.

* Refine event attribute detection in Jinja templates

Updated logic in material Jinja templates to more accurately classify event attributes by checking config.extra.events. Also updated colorscheme.md to pass additional options for documentation rendering.

* Refactor event field handling and update color scheme test

Simplifies checks for 'event' metadata in object_patch.py and protocol.py by using get() with a default value. Updates color scheme integration test to use a more comprehensive set of ColorScheme properties and renames screenshot references for clarity.

* Improve scrollable controls and spacing in views

Added wrapIntoScrollableView option to ScrollableControl and enabled it for Column, Row, and View controls to ensure proper scroll behavior. Enhanced ListViewControl to handle spacing and dividers between children more flexibly. Refined Scrollbar visibility logic and removed unnecessary exception in ViewControl.

* Revamp color scheme integration test and screenshots

Expanded the color scheme integration test to cover palettes, surface roles, accents, buttons, themed card, and error banner. Replaced the single color_scheme.png screenshot with multiple targeted screenshots and updated the test logic and golden images accordingly.

* Rename dismissable files and add declarative example

Renamed 'dismissable_list_tiles.py' and its media file to 'dismissible_list_tiles.py' for consistency. Added a new example 'remove_on_dismiss_declarative.py' demonstrating proper use of keys with Dismissible in declarative components. Updated documentation to reflect these changes and provide guidance on key usage.

* Improve ListView prototype item handling

Enhanced logic for determining the prototype item in ListViewControl (Dart) to use either a provided prototype or the first control when appropriate. Updated Python docstrings to clarify when prototype_item and first_item_prototype properties take effect.

* Update integration test suite and doc formatting

Limits macOS integration tests to the 'controls/theme' suite for focused testing. Improves docstring formatting in ListView by splitting 'Note:' onto its own line for better readability.

* Refactor color scheme test UI and update goldens

Reorganized color palette and button rows in test_color_scheme.py, added ScrollKey to palette rows, removed redundant spacing and text labels, and adjusted error banner border radius. Updated corresponding golden images to reflect UI changes for macOS color scheme integration tests.

* Update macOS color scheme golden images and test

Regenerated golden images for macOS color scheme integration tests and adjusted test window height from 600 to 300 to match new screenshot dimensions.

* Refactor color scheme test to use Screenshot widgets

Updated the color scheme integration test to wrap palette, button, card, and banner controls in Screenshot widgets for more precise screenshot capturing. Adjusted window height and consolidated button rows. Updated screenshot assertions to use the new capture method for each control.

* Enable all test suites in macOS integration workflow

Restores the full test suite matrix in the macOS integration tests workflow, running tests for apps, examples, and all controls. Previously, only the 'controls/theme' suite was enabled.

* Fix doc filter regex and marker doc typo

Corrected a typo in the Marker class docstring in marker_layer.py and updated the filter regex in mkdocs.yml to properly match method names for documentation exclusion.

Author: FeodorFitsner

packages/flet/lib/src/controls/column.dart

@@ -57,6 +57,7 @@ class ColumnControl extends StatelessWidget {
     child = ScrollableControl(
       control: control,
       scrollDirection: wrap ? Axis.horizontal : Axis.vertical,
+      wrapIntoScrollableView: true,
       child: child,
     );
 

packages/flet/lib/src/controls/list_view.dart

@@ -56,10 +56,11 @@ class _ListViewControlState extends State<ListViewControl> {
         widget.control.getBool("build_controls_on_demand", true)!;
     var firstItemPrototype =
         widget.control.getBool("first_item_prototype", false)!;
-    var prototypeItem = firstItemPrototype
-        ? widget.control.buildWidget("prototype_item")
-        : null;
     var controls = widget.control.children("controls");
+    var prototypeItem = widget.control.buildWidget("prototype_item") ??
+        (firstItemPrototype && controls.isNotEmpty
+            ? ControlWidget(control: controls.first)
+            : null);
 
     Widget listView = LayoutBuilder(
       builder: (BuildContext context, BoxConstraints constraints) {
@@ -79,14 +80,31 @@ class _ListViewControlState extends State<ListViewControl> {
                 shrinkWrap: shrinkWrap,
                 padding: padding,
                 semanticChildCount: semanticChildCount,
-                itemExtent: itemExtent,
-                prototypeItem: prototypeItem,
-                children: controls
-                    .map((item) => ControlWidget(
-                          key: ValueKey(item.getKey("key")?.value ?? item.id),
-                          control: item,
-                        ))
-                    .toList(),
+                itemExtent: spacing > 0 ? null : itemExtent,
+                prototypeItem: spacing > 0 ? null : prototypeItem,
+                children: () {
+                  final childWidgets = <Widget>[];
+                  for (var index = 0; index < controls.length; index++) {
+                    final item = controls[index];
+                    childWidgets.add(ControlWidget(
+                      key: ValueKey(item.getKey("key")?.value ?? item.id),
+                      control: item,
+                    ));
+                    if (spacing > 0 && index < controls.length - 1) {
+                      childWidgets.add(horizontal
+                          ? dividerThickness == 0
+                              ? SizedBox(width: spacing)
+                              : VerticalDivider(
+                                  width: spacing, thickness: dividerThickness)
+                          : dividerThickness == 0
+                              ? SizedBox(height: spacing)
+                              : Divider(
+                                  height: spacing,
+                                  thickness: dividerThickness));
+                    }
+                  }
+                  return childWidgets;
+                }(),
               )
             : spacing > 0
                 ? ListView.separated(

packages/flet/lib/src/controls/row.dart

@@ -55,6 +55,7 @@ class RowControl extends StatelessWidget {
     child = ScrollableControl(
         control: control,
         scrollDirection: wrap ? Axis.vertical : Axis.horizontal,
+        wrapIntoScrollableView: true,
         child: child);
 
     if (control.getBool("on_scroll", false)!) {

packages/flet/lib/src/controls/scrollable_control.dart

@@ -8,13 +8,15 @@ class ScrollableControl extends StatefulWidget {
   final Widget child;
   final Axis scrollDirection;
   final ScrollController? scrollController;
+  final bool wrapIntoScrollableView;
 
   ScrollableControl(
       {Key? key,
       required this.control,
       required this.child,
       required this.scrollDirection,
-      this.scrollController})
+      this.scrollController,
+      this.wrapIntoScrollableView = false})
       : super(key: key ?? ValueKey("control_${control.id}"));
 
   @override
@@ -102,22 +104,26 @@ class _ScrollableControlState extends State<ScrollableControl>
     return scrollMode != ScrollMode.none
         ? Scrollbar(
             // todo: create class ScrollBarConfiguration on Py end, for more customizability
-            thumbVisibility: scrollMode == ScrollMode.always ||
-                    (scrollMode == ScrollMode.adaptive && !isMobilePlatform())
-                ? true
-                : false,
-            trackVisibility: scrollMode == ScrollMode.hidden ? false : null,
+            thumbVisibility: (scrollMode == ScrollMode.always ||
+                    (scrollMode == ScrollMode.adaptive &&
+                        !isMobilePlatform())) &&
+                scrollMode != ScrollMode.hidden,
             thickness: scrollMode == ScrollMode.hidden
                 ? 0
                 : isMobilePlatform()
                     ? 4.0
                     : null,
-            //interactive: true,
             controller: _controller,
-            child: SingleChildScrollView(
-              controller: _controller,
-              scrollDirection: widget.scrollDirection,
-              child: widget.child,
+            child: ScrollConfiguration(
+              behavior:
+                  ScrollConfiguration.of(context).copyWith(scrollbars: false),
+              child: widget.wrapIntoScrollableView
+                  ? SingleChildScrollView(
+                      controller: _controller,
+                      scrollDirection: widget.scrollDirection,
+                      child: widget.child,
+                    )
+                  : widget.child,
             ))
         : widget.child;
   }

packages/flet/lib/src/controls/view.dart

@@ -76,8 +76,6 @@ class _ViewControlState extends State<ViewControl> {
         if (_popCompleter != null && !_popCompleter!.isCompleted) {
           _popCompleter?.complete(args["should_pop"]);
         }
-      default:
-        throw Exception("Unknown View method: $name");
     }
   }
 
@@ -130,7 +128,11 @@ class _ViewControlState extends State<ViewControl> {
             .toList());
 
     Widget child = ScrollableControl(
-        control: control, scrollDirection: Axis.vertical, child: column);
+      control: control,
+      scrollDirection: Axis.vertical,
+      wrapIntoScrollableView: true,
+      child: column,
+    );
 
     if (control.getBool("on_scroll", false)!) {
       child = ScrollNotificationControl(control: control, child: child);

sdk/python/examples/controls/dismissible/dismissable_list_tiles.py renamed to sdk/python/examples/controls/dismissible/dismissible_list_tiles.py

@@ -0,0 +1,29 @@
+import flet as ft
+
+
+@ft.component
+def App():
+    items, set_items = ft.use_state(list(range(5)))
+
+    return ft.ListView(
+        controls=[
+            ft.Dismissible(
+                key=i,
+                content=ft.ListTile(title=ft.Text(f"Item {i}")),
+                dismiss_direction=ft.DismissDirection.HORIZONTAL,
+                background=ft.Container(bgcolor=ft.Colors.GREEN),
+                secondary_background=ft.Container(bgcolor=ft.Colors.RED),
+                on_dismiss=lambda e, index=i: set_items(
+                    [item for item in items if item != index]
+                ),
+                dismiss_thresholds={
+                    ft.DismissDirection.HORIZONTAL: 0.1,
+                    ft.DismissDirection.START_TO_END: 0.1,
+                },
+            )
+            for i in items
+        ],
+    )
+
+
+ft.run(lambda page: page.render(App))

sdk/python/examples/controls/dismissible/media/dismissable_list_tiles.gif renamed to sdk/python/examples/controls/dismissible/media/dismissible_list_tiles.gif

@@ -10,13 +10,39 @@ example_images: ../examples/controls/dismissible/media
 
 [Live example](https://flet-controls-gallery.fly.dev/layout/dismissible)
 
-### Dismissable `ListTile`s
+### Dismissible `ListTile`s
 
 ```python
---8<-- "{{ examples }}/dismissable_list_tiles.py"
+--8<-- "{{ examples }}/dismissible_list_tiles.py"
 ```
 
-{{ image(example_images + "/dismissable_list_tiles.gif", alt="dismissable-list-tiles", width="80%") }}
+{{ image(example_images + "/dismissible_list_tiles.gif", alt="dismissible-list-tiles", width="80%") }}
 
+### Remove Dismissible `on_dismiss` inside component
+
+/// admonition | Important
+    type: warning
+Always specify a key for `Dismissible` when using inside Flet component.
+///
+
+The issue you may encounter here is specific to the `Dismissible` control used inside Flet component (declarative UI).
+
+When a user swipes (dismisses) an item, that widget is marked as “dismissed” on the Flutter side and effectively removed from the UI.
+However, when Flet recalculates the UI diff on the Python side, it may attempt to reuse widgets in the list based on their order rather than their identity.
+
+If no key is provided, Flet’s diffing algorithm can’t tell that a particular `Dismissible` corresponds to a specific item — so it assumes the items have merely shifted.
+That leads to update commands like:
+
+> “Update text in items 0…N-1, then delete the last item (N).”
+
+On Flutter’s side, though, the already-dismissed `Dismissible` widget in the middle of the list can’t be updated — it’s gone — causing runtime errors.
+
+**Always assign a stable, unique key to each `Dismissible`, typically based on the item’s identifier or index.**
+
+Example:
+
+```python
+--8<-- "{{ examples }}/remove_on_dismiss_declarative.py"
+```
 
 {{ class_members(class_name) }}

sdk/python/examples/controls/dismissible/remove_on_dismiss_declarative.py

@@ -18,7 +18,7 @@ Context:
   {{ log.debug("Rendering " + attribute.path) }}
 {% endblock logs %}
 
-{% set attr_class_name = "doc-symbol-event" if attribute.name.startswith('on_') else "doc-symbol-attribute" %}
+{% set attr_class_name = "doc-symbol-event" if attribute.name.startswith('on_') and (config.extra.events is not defined or (config.extra.events and attribute.name in config.extra.events)) else "doc-symbol-attribute" %}
 
 <div class="doc doc-object doc-attribute">
   {% with obj = attribute, html_id = attribute.path %}