feat: add region metadata support to Template fluent API

Author: eldomagan

packages/core/src/Data/Template.php

@@ -11,6 +11,10 @@ class Template
 
     protected ?array $order = null;
 
+    protected ?string $regionId = null;
+
+    protected ?string $regionName = null;
+
     /**
      * Create a new template.
      */
@@ -52,6 +56,26 @@ public function order(array $order): static
         return $this;
     }
 
+    /**
+     * Set region ID (for single-region templates).
+     */
+    public function id(string $id): static
+    {
+        $this->regionId = $id;
+
+        return $this;
+    }
+
+    /**
+     * Set region name (for single-region templates).
+     */
+    public function name(string $name): static
+    {
+        $this->regionName = $name;
+
+        return $this;
+    }
+
     /**
      * Convert to array.
      */
@@ -68,6 +92,18 @@ public function toArray(): array
             if ($this->order !== null) {
                 $data['order'] = $this->order;
             }
+
+            if ($this->regionId !== null) {
+                $blockIds = $this->order ?? array_keys($data['blocks']);
+
+                $data['regions'] = [
+                    [
+                        'id' => $this->regionId,
+                        'name' => $this->regionName ?? $this->regionId,
+                        'blocks' => $blockIds,
+                    ],
+                ];
+            }
         }
 
         return $data;

tests/laravel/Unit/PhpTemplateTest.php

@@ -379,3 +379,53 @@ protected function build(): void
         expect($template['blocks']['grid']['children'][0]['properties']['featured'])->toBeTrue();
     });
 });
+
+describe('Template region API', function () {
+    it('supports region id and name', function () {
+        $template = Template::make()
+            ->id('header')
+            ->name('Header')
+            ->block('logo', 'logo')
+            ->block('nav', 'navigation')
+            ->toArray();
+
+        expect($template['blocks'])->toHaveCount(2);
+        expect($template['regions'])->toHaveCount(1);
+        expect($template['regions'][0]['id'])->toBe('header');
+        expect($template['regions'][0]['name'])->toBe('Header');
+        expect($template['regions'][0]['blocks'])->toBe(['logo', 'nav']);
+    });
+
+    it('uses region id as name when name not provided', function () {
+        $template = Template::make()
+            ->id('footer')
+            ->block('copyright', 'text')
+            ->toArray();
+
+        expect($template['regions'][0]['id'])->toBe('footer');
+        expect($template['regions'][0]['name'])->toBe('footer');
+        expect($template['regions'][0]['blocks'])->toBe(['copyright']);
+    });
+
+    it('respects block order in region', function () {
+        $template = Template::make()
+            ->id('header')
+            ->name('Header')
+            ->block('logo', 'logo')
+            ->block('nav', 'navigation')
+            ->block('search', 'search')
+            ->order(['nav', 'search', 'logo'])
+            ->toArray();
+
+        expect($template['regions'][0]['blocks'])->toBe(['nav', 'search', 'logo']);
+        expect($template['order'])->toBe(['nav', 'search', 'logo']);
+    });
+
+    it('does not include regions when region id not set', function () {
+        $template = Template::make()
+            ->block('hero', 'hero')
+            ->toArray();
+
+        expect($template)->not()->toHaveKey('regions');
+    });
+});