feat: collapsible grouped fields UI for structured objects and arrays (#635) (#739)

Add collapsible/expandable sections for grouped fields in the admin content
form, improving UX for complex nested collection schemas (objects, arrays,
blocks). Includes drag-and-drop reordering, validation visibility, and
proper serialization of nested structures.

Cherry-picked from bobbwal/sonicjs fix/grouped-fields-ui branch.
E2E tests 55-58 skipped pending CI fixture data.

Co-authored-by: Rob Walton <bobbwal@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

my-sonicjs-app/src/collections/page-blocks.collection.ts

@@ -1,5 +1,82 @@
 import type { CollectionConfig } from '@sonicjs-cms/core'
 
+const heroBlock = {
+  label: 'Hero',
+  properties: {
+    heading: { type: 'string', title: 'Heading', required: true },
+    height: {
+      type: 'radio',
+      title: 'Height',
+      enum: ['small', 'medium', 'full'],
+      enumLabels: ['Small', 'Medium', 'Full'],
+      default: 'medium',
+      inline: true,
+    },
+    subheading: { type: 'textarea', title: 'Subheading', maxLength: 600 },
+    image: { type: 'media', title: 'Background/Image' },
+    imageAlt: { type: 'string', title: 'Image Alt' },
+
+    ctaPrimary: {
+      title: 'Primary CTA',
+      type: 'object',
+      properties: {
+        label: { type: 'string', title: 'Label' },
+        link: {
+          title: 'Link',
+          type: 'object',
+          properties: {
+            mode: {
+              type: 'select',
+              title: 'Link type',
+              enum: ['none', 'internal', 'external'],
+              enumLabels: ['None', 'Internal', 'External'],
+              default: 'none',
+            },
+            reference: { type: 'reference', title: 'Internal reference', collection: 'pages' },
+            url: { type: 'url', title: 'External URL' },
+          },
+        },
+        style: {
+          type: 'select',
+          title: 'Button style',
+          enum: ['primary', 'secondary'],
+          enumLabels: ['Primary', 'Secondary'],
+          default: 'primary',
+        },
+      },
+    },
+    ctaSecondary: {
+      title: 'Secondary CTA',
+      type: 'object',
+      properties: {
+        label: { type: 'string', title: 'Label' },
+        link: {
+          title: 'Link',
+          type: 'object',
+          properties: {
+            mode: {
+              type: 'select',
+              title: 'Type',
+              enum: ['none', 'internal', 'external'],
+              enumLabels: ['None', 'Internal', 'External'],
+              default: 'none',
+            },
+            reference: { type: 'reference', title: 'Internal reference', collection: 'pages' },
+            url: { type: 'url', title: 'External URL' },
+          },
+        },
+        style: {
+          type: 'select',
+          title: 'Button style',
+          enum: ['primary', 'secondary'],
+          enumLabels: ['Primary', 'Secondary'],
+          default: 'primary',
+        },
+      },
+    },
+  },
+}
+
 const pageBlocksCollection: CollectionConfig = {
   name: 'page_blocks',
   displayName: 'Page Blocks',
@@ -28,6 +105,7 @@ const pageBlocksCollection: CollectionConfig = {
       seo: {
         type: 'object',
         title: 'SEO',
+        objectLayout: 'flat',
         properties: {
           title: { type: 'string', title: 'SEO title' },
           description: { type: 'textarea', title: 'SEO description' },
@@ -47,11 +125,57 @@ const pageBlocksCollection: CollectionConfig = {
                 name: { type: 'string', title: 'Name', required: true },
                 role: { type: 'string', title: 'Role' },
                 photo: { type: 'media', title: 'Photo' },
+                children: {
+                  type: 'array',
+                  title: 'Children',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      name: { type: 'string', title: 'Name', required: true },
+                    },
+                  },
+                },
               },
             },
           },
         },
       },
+      openingHoursWeek: {
+        type: 'object',
+        title: 'Opening Hours',
+        properties: {
+          monday: {
+            type: 'object',
+            title: 'Monday',
+            objectLayout: 'flat',
+            properties: {
+              closed: { type: 'boolean', title: 'Closed', default: false },
+              opens: { type: 'string', title: 'Opens', pattern: '^([01]\\d|2[0-3]):(00|30)$' },
+              closes: { type: 'string', title: 'Closes', pattern: '^([01]\\d|2[0-3]):(00|30)$' },
+            },
+          },
+          tuesday: {
+            type: 'object',
+            title: 'Tuesday',
+            objectLayout: 'flat',
+            properties: {
+              closed: { type: 'boolean', title: 'Closed', default: false },
+              opens: { type: 'string', title: 'Opens', pattern: '^([01]\\d|2[0-3]):(00|30)$' },
+              closes: { type: 'string', title: 'Closes', pattern: '^([01]\\d|2[0-3]):(00|30)$' },
+            },
+          },
+          wednesday: {
+            type: 'object',
+            title: 'Wednesday',
+            objectLayout: 'flat',
+            properties: {
+              closed: { type: 'boolean', title: 'Closed', default: false },
+              opens: { type: 'string', title: 'Opens', pattern: '^([01]\\d|2[0-3]):(00|30)$' },
+              closes: { type: 'string', title: 'Closes', pattern: '^([01]\\d|2[0-3]):(00|30)$' },
+            },
+          },
+        },
+      },
 
       body: {
         type: 'array',
@@ -60,6 +184,7 @@ const pageBlocksCollection: CollectionConfig = {
           type: 'object',
           discriminator: 'blockType',
           blocks: {
+            hero: heroBlock,
             text: {
               label: 'Text',
               properties: {
@@ -81,6 +206,24 @@ const pageBlocksCollection: CollectionConfig = {
                 image: { type: 'media', title: 'Image', required: true },
               },
             },
+            gallery: {
+              label: 'Gallery',
+              properties: {
+                heading: { type: 'string', title: 'Heading' },
+                images: {
+                  type: 'array',
+                  title: 'Images',
+                  items: {
+                    type: 'object',
+                    properties: {
+                      image: { type: 'media', title: 'Image' },
+                      alt: { type: 'string', title: 'Alt' },
+                      caption: { type: 'string', title: 'Caption' },
+                    },
+                  },
+                },
+              },
+            },
             callToAction: {
               label: 'Call To Action',
               properties: {

packages/core/src/__tests__/templates/dynamic-field-extended.test.ts

@@ -627,6 +627,46 @@ describe('renderDynamicField - Object Fields', () => {
 
     expect(html).toContain('data-structured-object');
   });
+
+  it('should scope nested object host lookup to the current object container', () => {
+    const field = createTestField({
+      field_type: 'object',
+      field_options: {
+        properties: {
+          monday: {
+            type: 'object',
+            title: 'Monday',
+            objectLayout: 'flat',
+            properties: {
+              opens: { type: 'text', title: 'Opens' },
+              closes: { type: 'text', title: 'Closes' },
+            },
+          },
+          tuesday: {
+            type: 'object',
+            title: 'Tuesday',
+            objectLayout: 'flat',
+            properties: {
+              opens: { type: 'text', title: 'Opens' },
+              closes: { type: 'text', title: 'Closes' },
+            },
+          },
+        },
+      },
+    });
+    const html = renderDynamicField(field, {
+      value: {
+        monday: { opens: '09:00', closes: '17:00' },
+        tuesday: { opens: '10:00', closes: '18:00' },
+      },
+    });
+
+    expect(html).toContain('const getStructuredObjectFieldsHost = (container) =>');
+    expect(html).toContain("getDirectChild(container, '.field-group-content')");
+    expect(html).toContain('const getDirectStructuredObject = (fieldWrapper) =>');
+    expect(html).not.toContain("objectContainer.querySelector('[data-structured-object-fields]')");
+    expect(html).toContain("document.readyState !== 'loading'");
+  });
 });
 
 describe('renderDynamicField - Array Fields', () => {
@@ -678,6 +718,40 @@ describe('renderDynamicField - Array Fields', () => {
     expect(html).toContain('Name');
     expect(html).toContain('URL');
   });
+
+  it('should scope structured array item queries to direct children', () => {
+    const field = createTestField({
+      field_type: 'array',
+      field_options: {
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'text', title: 'Name' },
+            children: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  name: { type: 'text', title: 'Child name' },
+                },
+              },
+            },
+          },
+        },
+      },
+    });
+    const html = renderDynamicField(field, {
+      value: [{ name: 'Parent', children: [{ name: 'Child' }] }],
+    });
+
+    expect(html).toContain(":scope > .structured-array-item");
+    expect(html).not.toContain("querySelectorAll('.structured-array-item')");
+    expect(html).toContain(":scope > [data-structured-array-list]");
+    expect(html).toContain(":scope > input[type=\"hidden\"]");
+    expect(html).toContain(":scope > template[data-structured-array-template]");
+    expect(html).toContain(":scope > [data-structured-empty]");
+    expect(html).toContain('container.__sonicStructuredArrayTemplate');
+  });
 });
 
 describe('renderFieldGroup', () => {

packages/core/src/collections/README.md

@@ -123,6 +123,9 @@ Each field can have:
 - `items`: Schema for array items
 - `itemTitle`: Optional singular item label used in array item cards/buttons (for example, `"Member"`)
 - `properties`: Schema for object properties
+- `objectLayout`: Object field layout mode: `'nested'` (default) or `'flat'`
+- `collapsed`: For nested object layout, initial state (default: `true`; set `false` to start open)
+- Note: `collapsed` is ignored when `objectLayout` is `'flat'`
 
 ## Testing Collections
 

packages/core/src/db/migrations-bundle.ts

@@ -1,7 +1,7 @@
 /**
  * AUTO-GENERATED FILE - DO NOT EDIT
  * Generated by: scripts/generate-migrations.ts
- * Generated at: 2026-04-01T14:08:42.942Z
+ * Generated at: 2026-04-01T19:44:07.907Z
  *
  * This file contains all migration SQL bundled for use in Cloudflare Workers
  * where filesystem access is not available at runtime.

packages/core/src/services/collection-loader.ts

@@ -176,6 +176,15 @@ export function validateCollectionConfig(config: CollectionConfig): { valid: boo
         errors.push(`Reference field "${fieldName}" is missing collection property`)
       }
 
+      const layoutValue = fieldConfig.objectLayout
+      if (layoutValue !== undefined) {
+        if (fieldConfig.type !== 'object') {
+          errors.push(`Field "${fieldName}" uses objectLayout but is not an object field`)
+        } else if (!['nested', 'flat'].includes(layoutValue)) {
+          errors.push(`Object field "${fieldName}" has invalid objectLayout. Use "nested" or "flat"`)
+        }
+      }
+
       // Validate select fields
       if (['select', 'multiselect', 'radio'].includes(fieldConfig.type) && !fieldConfig.enum) {
         errors.push(`Select field "${fieldName}" is missing enum options`)