fix: add row overflow strategies to prevent layout overflow

Author: Dev-Beom

README.md

@@ -147,6 +147,26 @@ if (!result.isValid) {
 - `Button`
 - `Image`
 
+`Row` overflow strategy:
+
+- `overflow: "row"` (default): normal `Row`
+- `overflow: "wrap"`: uses `Wrap` to avoid horizontal overflow
+- `overflow: "scroll"`: horizontal scroll container
+
+Example:
+
+```json
+{
+  "type": "Row",
+  "props": {
+    "spacing": 8,
+    "runSpacing": 8,
+    "overflow": "wrap"
+  },
+  "children": ["a", "b", "c"]
+}
+```
+
 ## Example App
 
 A full multi-scenario showcase app is included in `/example`:

example/lib/main.dart

@@ -583,7 +583,11 @@ class _ShowcaseAppState extends State<ShowcaseApp> {
             },
             'buttons': <String, dynamic>{
               'type': 'Row',
-              'props': <String, dynamic>{'spacing': 8},
+              'props': <String, dynamic>{
+                'spacing': 8,
+                'runSpacing': 8,
+                'overflow': 'wrap',
+              },
               'children': <String>['dec', 'inc', 'toggle'],
             },
             'dec': <String, dynamic>{
@@ -656,7 +660,11 @@ class _ShowcaseAppState extends State<ShowcaseApp> {
             },
             'line': <String, dynamic>{
               'type': 'Row',
-              'props': <String, dynamic>{'spacing': 8},
+              'props': <String, dynamic>{
+                'spacing': 8,
+                'runSpacing': 8,
+                'overflow': 'wrap',
+              },
               'children': <String>[
                 'name',
                 'doneChip',

lib/src/components/standard_components.dart

@@ -38,6 +38,16 @@ final Map<String, JsonComponentDefinition> standardComponentDefinitions =
         description: 'Horizontal layout for children widgets.',
         props: <String, JsonPropDefinition>{
           'spacing': JsonPropDefinition(type: 'number', defaultValue: 0),
+          'runSpacing': JsonPropDefinition(
+            type: 'number',
+            description: 'Used when overflow is set to "wrap".',
+          ),
+          'overflow': JsonPropDefinition(
+            type: 'string',
+            enumValues: <String>['row', 'wrap', 'scroll'],
+            defaultValue: 'row',
+            description: 'How to handle narrow widths.',
+          ),
           'mainAxisAlignment': JsonPropDefinition(type: 'string'),
           'crossAxisAlignment': JsonPropDefinition(type: 'string'),
           'mainAxisSize': JsonPropDefinition(
@@ -135,14 +145,31 @@ Map<String, JsonComponentBuilder> standardComponentBuilders() {
     },
     'Row': (context) {
       final spacing = _toDouble(context.props['spacing']) ?? 0;
+      final overflow = _parseRowOverflow(context.props['overflow']);
+
+      if (overflow == _RowOverflowBehavior.wrap) {
+        return Wrap(
+          spacing: spacing,
+          runSpacing: _toDouble(context.props['runSpacing']) ?? spacing,
+          alignment: _parseWrapAlignment(context.props['mainAxisAlignment']),
+          crossAxisAlignment: _parseWrapCrossAlignment(
+            context.props['crossAxisAlignment'],
+          ),
+          children: context.children,
+        );
+      }
+
       final children = _withSpacing(
         context.children,
         spacing: spacing,
         axis: Axis.horizontal,
       );
 
-      return Row(
-        mainAxisSize: _parseMainAxisSize(context.props['mainAxisSize']),
+      final row = Row(
+        // Horizontal scroll views provide unconstrained width, so max is invalid.
+        mainAxisSize: overflow == _RowOverflowBehavior.scroll
+            ? MainAxisSize.min
+            : _parseMainAxisSize(context.props['mainAxisSize']),
         mainAxisAlignment: _parseMainAxisAlignment(
           context.props['mainAxisAlignment'],
         ),
@@ -151,6 +178,15 @@ Map<String, JsonComponentBuilder> standardComponentBuilders() {
         ),
         children: children,
       );
+
+      if (overflow == _RowOverflowBehavior.scroll) {
+        return SingleChildScrollView(
+          scrollDirection: Axis.horizontal,
+          child: row,
+        );
+      }
+
+      return row;
     },
     'Container': (context) {
       final width = _toDouble(context.props['width']);
@@ -465,3 +501,44 @@ int? _toInt(dynamic raw) {
   if (raw is num) return raw.toInt();
   return int.tryParse(raw?.toString() ?? '');
 }
+
+enum _RowOverflowBehavior { row, wrap, scroll }
+
+_RowOverflowBehavior _parseRowOverflow(dynamic raw) {
+  switch (raw?.toString()) {
+    case 'wrap':
+      return _RowOverflowBehavior.wrap;
+    case 'scroll':
+      return _RowOverflowBehavior.scroll;
+    default:
+      return _RowOverflowBehavior.row;
+  }
+}
+
+WrapAlignment _parseWrapAlignment(dynamic raw) {
+  switch (raw?.toString()) {
+    case 'end':
+      return WrapAlignment.end;
+    case 'center':
+      return WrapAlignment.center;
+    case 'spaceBetween':
+      return WrapAlignment.spaceBetween;
+    case 'spaceAround':
+      return WrapAlignment.spaceAround;
+    case 'spaceEvenly':
+      return WrapAlignment.spaceEvenly;
+    default:
+      return WrapAlignment.start;
+  }
+}
+
+WrapCrossAlignment _parseWrapCrossAlignment(dynamic raw) {
+  switch (raw?.toString()) {
+    case 'end':
+      return WrapCrossAlignment.end;
+    case 'center':
+      return WrapCrossAlignment.center;
+    default:
+      return WrapCrossAlignment.start;
+  }
+}

test/flutter_json_render_test.dart

@@ -142,4 +142,49 @@ void main() {
       expect(find.text('Now Visible'), findsOneWidget);
     },
   );
+
+  testWidgets('Row component supports wrap overflow strategy', (tester) async {
+    final spec = JsonRenderSpec.fromJson({
+      'root': 'root',
+      'elements': {
+        'root': {
+          'type': 'Row',
+          'props': {'spacing': 8, 'runSpacing': 8, 'overflow': 'wrap'},
+          'children': ['a', 'b', 'c'],
+        },
+        'a': {
+          'type': 'Button',
+          'props': {'label': 'Very long button A'},
+        },
+        'b': {
+          'type': 'Button',
+          'props': {'label': 'Very long button B'},
+        },
+        'c': {
+          'type': 'Button',
+          'props': {'label': 'Very long button C'},
+        },
+      },
+    });
+
+    await tester.pumpWidget(
+      MaterialApp(
+        home: Scaffold(
+          body: SizedBox(
+            width: 220,
+            child: JsonRenderer(
+              spec: spec,
+              registry: defineRegistry(components: standardComponentBuilders()),
+            ),
+          ),
+        ),
+      ),
+    );
+
+    expect(find.byType(Wrap), findsOneWidget);
+    expect(find.text('Very long button A'), findsOneWidget);
+    expect(find.text('Very long button B'), findsOneWidget);
+    expect(find.text('Very long button C'), findsOneWidget);
+    expect(tester.takeException(), isNull);
+  });
 }