Wrapping list views

A list with wrap on and a known item count (itemCount or bound data, no
cloud query) builds all its items in a Wrap along its scroll direction:
the separator spacing between items (no dividers), runSpacing between
runs, aligned to the start, sized by its own fits (shrink-wrap hugs the
runs). It never scrolls. A list with an unknown count ignores wrap.
Items keep their own size in a run instead of being aligned across the
list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SyH8twyrBoe4wFCTw78Cz5

Author: claude

lib/src/transformers/node_transformers/passive_list_view_transformer.dart

@@ -1,4 +1,5 @@
 import 'dart:core';
+import 'dart:math' as math;
 
 import 'package:cloud_firestore/cloud_firestore.dart';
 import 'package:codelessly_api/codelessly_api.dart';
@@ -92,6 +93,7 @@ class PassiveListViewWidget extends StatelessWidget {
     int itemCount,
     IndexedWidgetBuilder itemBuilder,
   ) {
+    if (listWraps(node)) return wrappedList(context, itemCount, itemBuilder);
     final bool vertical = node.scrollDirection == AxisC.vertical;
     final List<Widget> items = [
       for (int index = 0; index < itemCount; index++) ...[
@@ -128,11 +130,51 @@ class PassiveListViewWidget extends StatelessWidget {
     );
   }
 
+  /// Lays out all [itemCount] items of a wrapping list (see [listWraps]) in
+  /// a [Wrap] along the scroll direction: items flow onto a new run when
+  /// they don't fit, with the separator's spacing between items and
+  /// [ListViewProperties.runSpacing] between runs, all aligned to the start.
+  ///
+  /// The list is sized by its own fits: fixed takes its design size, expanded
+  /// fills a bounded axis, and shrink-wrap hugs (along the scroll direction,
+  /// the widest run; across it, the runs).
+  Widget wrappedList(
+    BuildContext context,
+    int itemCount,
+    IndexedWidgetBuilder itemBuilder,
+  ) {
+    final List<Widget> items = [
+      for (int index = 0; index < itemCount; index++)
+        itemBuilder(context, index),
+    ];
+    final Widget wrap = Padding(
+      padding: node.padding.flutterEdgeInsets,
+      child: Wrap(
+        direction: node.scrollDirection.flutterAxis,
+        spacing: listWrapSpacing(node),
+        runSpacing: math.max(0, node.properties.runSpacing),
+        children: node.reverse ? items.reversed.toList() : items,
+      ),
+    );
+    return FitBox(
+      width: node.horizontalFit == SizeFit.shrinkWrap
+          ? null
+          : node.basicBoxLocal.width,
+      height: node.verticalFit == SizeFit.shrinkWrap
+          ? null
+          : node.basicBoxLocal.height,
+      fillWidth: node.horizontalFit == SizeFit.expanded,
+      fillHeight: node.verticalFit == SizeFit.expanded,
+      child: node.clipsContent ? ClipRect(child: wrap) : wrap,
+    );
+  }
+
   /// Builds one item, placed as the editor lays it out; see [ListItemBox].
   Widget buildItem(BaseNode item, BuildContext context) => ListItemBox(
     item: item,
     scrollDirection: node.scrollDirection,
     itemExtent: node.properties.itemExtent,
+    inWrap: listWraps(node),
     child: manager.buildWidgetByID(item.id, context, settings: settings),
   );
 

lib/src/transformers/utils/viewport_sizing.dart

@@ -177,6 +177,9 @@ class ViewportNodeBox extends StatelessWidget {
 /// * Scroll axis: with [itemExtent] the item fills the extent, as in the
 ///   editor. Otherwise an expanded or flexible item, which has nothing to
 ///   fill along an endless axis, takes its design extent.
+///
+/// In a wrapping list ([inWrap]) the item is not aligned across the list:
+/// it sits in its run at its own size, as [Wrap] places it.
 class ListItemBox extends StatelessWidget {
   /// The item node.
   final BaseNode item;
@@ -190,13 +193,17 @@ class ListItemBox extends StatelessWidget {
   /// The built item.
   final Widget child;
 
+  /// Whether the item is a child of a wrapping list's [Wrap].
+  final bool inWrap;
+
   /// Creates a [ListItemBox].
   const ListItemBox({
     super.key,
     required this.item,
     required this.scrollDirection,
     required this.itemExtent,
     required this.child,
+    this.inWrap = false,
   });
 
   @override
@@ -217,6 +224,7 @@ class ListItemBox extends StatelessWidget {
         child: result,
       );
     }
+    if (inWrap) return result;
     return Align(
       alignment: vertical ? Alignment.topCenter : Alignment.centerLeft,
       child: result,
@@ -300,20 +308,41 @@ class DesignCellGridDelegate extends SliverGridDelegate {
       oldDelegate.mainAxisExtent != mainAxisExtent;
 }
 
-/// Whether list [node] builds all its items up front, as a plain [Flex]
-/// rather than a viewport: it doesn't scroll, hugs its items along its axis
-/// and has a known item count (bound data or a set count). Such a list builds
-/// every item either way, so it needs no viewport.
+/// Whether list [node] has a known item count: bound data or a set count,
+/// and no cloud query (whose length is only known once it loads, page by
+/// page).
+bool listHasKnownItemCount(ListViewNode node) =>
+    !node.useCloudDatabase &&
+    (node.variables['data'] != null || node.properties.itemCount != null);
+
+/// Whether list [node] lays its items out in a [Wrap]: it wraps
+/// ([ListViewProperties.wrap]) and has a known item count. Such a list builds
+/// all its items and never scrolls, whatever its scroll settings. A list
+/// with an unknown count ignores [ListViewProperties.wrap] and scrolls.
+bool listWraps(ListViewNode node) =>
+    node.properties.wrap && listHasKnownItemCount(node);
+
+/// Whether list [node] builds all its items up front, as a plain [Flex] or a
+/// [Wrap] rather than a viewport: it wraps (see [listWraps]), or it doesn't
+/// scroll, hugs its items along its axis and has a known item count (bound
+/// data or a set count). Such a list builds every item either way, so it
+/// needs no viewport.
 bool listBuildsAllItems(ListViewNode node) {
+  if (listWraps(node)) return true;
   final SizeFit mainFit = node.scrollDirection == AxisC.vertical
       ? node.verticalFit
       : node.horizontalFit;
   return !node.isScrollable &&
       mainFit == SizeFit.shrinkWrap &&
-      !node.useCloudDatabase &&
-      (node.variables['data'] != null || node.properties.itemCount != null);
+      listHasKnownItemCount(node);
 }
 
+/// The gap between consecutive items of a wrapping list: the separator's
+/// spacing when it has one. A wrapping list draws no dividers.
+double listWrapSpacing(ListViewNode node) => node.properties.hasSeparator
+    ? math.max(0, node.properties.separatorSpacing)
+    : 0;
+
 /// Whether [node] or any node below it builds a widget that cannot report
 /// intrinsic sizes: a list, grid or page view (a viewport behind a
 /// [LayoutBuilder]), a scrolling row, column or frame (a [LayoutBuilder]

test/list_view_wrap_test.dart

@@ -0,0 +1,126 @@
+import 'package:codelessly_api/codelessly_api.dart';
+import 'package:codelessly_sdk/codelessly_sdk.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+import 'viewport_layout_test.dart' as vp;
+
+/// A horizontal list of [itemCount] 100x50 items that wraps, 14 apart with
+/// 6 between runs, and hugs its height.
+ListViewNode wrappingList({
+  double width = 250,
+  int? itemCount = 4,
+  SizeFit horizontalFit = SizeFit.fixed,
+  bool hasSeparator = true,
+}) {
+  final ListViewNode list = vp.list(
+    width: width,
+    height: 50,
+    itemCount: itemCount,
+    horizontalFit: horizontalFit,
+    verticalFit: SizeFit.shrinkWrap,
+    scrollDirection: AxisC.horizontal,
+  );
+  list.properties
+    ..wrap = true
+    ..hasSeparator = hasSeparator
+    ..separatorSpacing = 14
+    ..runSpacing = 6;
+  return list;
+}
+
+List<Rect> itemRects(WidgetTester tester) => [
+  for (final Element element in vp.rectOf('item').evaluate())
+    tester.getRect(find.byWidget(element.widget).first),
+];
+
+void main() {
+  test('a wrapping list with a known count builds all its items', () {
+    final ListViewNode list = wrappingList();
+    expect(list.isScrollable, isTrue);
+    expect(listWraps(list), isTrue);
+    expect(listBuildsAllItems(list), isTrue);
+    expect(listWrapSpacing(list), 14);
+
+    list.properties.itemCount = null;
+    expect(listWraps(list), isFalse, reason: 'endless list');
+    expect(listBuildsAllItems(list), isFalse);
+
+    list
+      ..properties.itemCount = 3
+      ..useCloudDatabase = true;
+    expect(listWraps(list), isFalse, reason: 'cloud query');
+  });
+
+  testWidgets('a wrapping list keeps its items on one run when they fit', (
+    tester,
+  ) async {
+    await vp.pump(tester, const Size(800, 800), vp.Host.loose, wrappingList(
+      width: 500,
+    ), [vp.rect('item', 'list')]);
+    expect(find.byType(Wrap), findsOneWidget);
+    expect(find.byType(ViewportNodeBox), findsNothing);
+    final List<Rect> items = itemRects(tester);
+    expect(items, hasLength(4));
+    for (int i = 1; i < 4; i++) {
+      expect(items[i].top, items[0].top);
+      expect(items[i].left - items[i - 1].right, 14);
+    }
+    expect(tester.getSize(find.byType(Wrap)).height, 50);
+  });
+
+  testWidgets('a wrapping list moves items that do not fit to a new run', (
+    tester,
+  ) async {
+    await vp.pump(tester, const Size(800, 800), vp.Host.loose, wrappingList(), [
+      vp.rect('item', 'list'),
+    ]);
+    final List<Rect> items = itemRects(tester);
+    // 100 + 14 + 100 = 214 fits in 250, a third item does not.
+    expect(items[1].top, items[0].top);
+    expect(items[2].left, items[0].left);
+    expect(items[2].top - items[0].bottom, 6);
+    expect(items[3].top, items[2].top);
+    expect(tester.getSize(find.byType(Wrap)), const Size(250, 106));
+  });
+
+  testWidgets('an expanded wrapping list wraps at the width it gets', (
+    tester,
+  ) async {
+    await vp.pump(
+      tester,
+      const Size(250, 800),
+      vp.Host.tight,
+      wrappingList(width: 800, horizontalFit: SizeFit.expanded),
+      [vp.rect('item', 'list')],
+    );
+    final List<Rect> items = itemRects(tester);
+    expect(items[2].top - items[0].bottom, 6);
+  });
+
+  testWidgets('without a separator the items touch', (tester) async {
+    await vp.pump(
+      tester,
+      const Size(800, 800),
+      vp.Host.loose,
+      wrappingList(width: 500, hasSeparator: false),
+      [vp.rect('item', 'list')],
+    );
+    final List<Rect> items = itemRects(tester);
+    expect(items[1].left, items[0].right);
+  });
+
+  testWidgets('a wrapping list with no count scrolls as before', (
+    tester,
+  ) async {
+    await vp.pump(
+      tester,
+      const Size(800, 800),
+      vp.Host.loose,
+      wrappingList(itemCount: null)..verticalFit = SizeFit.fixed,
+      [vp.rect('item', 'list')],
+    );
+    expect(find.byType(Wrap), findsNothing);
+    expect(find.byType(ViewportNodeBox), findsOneWidget);
+  });
+}