From 5fc983741b3d159e4aff45bfbc4bbcc81c558fa4 Mon Sep 17 00:00:00 2001
From: Emin Jasarevic <emin@jasarevic.com>
Date: Tue, 8 Sep 2026 10:45:18 +0200
Subject: [PATCH] Allow addons to extend Replicator and Bard set configuration

---
 .../js/components/blueprints/Section.vue      |  19 ++
 .../fieldtypes/replicator/SetsFieldtype.vue   |  23 ++-
 .../components/blueprints/Section.test.js     |  64 ++++++
 src/Fieldtypes/Sets.php                       | 112 +++++++++-
 tests/Fieldtypes/SetConfigTest.php            | 195 ++++++++++++++++++
 5 files changed, 406 insertions(+), 7 deletions(-)
 create mode 100644 resources/js/tests/components/blueprints/Section.test.js
 create mode 100644 tests/Fieldtypes/SetConfigTest.php

diff --git a/resources/js/components/blueprints/Section.vue b/resources/js/components/blueprints/Section.vue
index 59f95fe09a4..720af64d3d8 100644
--- a/resources/js/components/blueprints/Section.vue
+++ b/resources/js/components/blueprints/Section.vue
@@ -124,6 +124,14 @@
                     <ui-field :label="__('Hidden')" v-if="showHideField">
                         <ui-switch v-model="editingSection.hide" />
                     </ui-field>
+                    <ui-publish-container
+                        v-if="editingSection && setConfig?.fields.length"
+                        v-model="editingSection.extraConfig.values"
+                        v-model:meta="editingSection.extraConfig.meta"
+                        :blueprint="setConfigBlueprint"
+                        :errors="setConfigErrors?.(section._id) || {}"
+                        :track-dirty-state="false"
+                    />
                     <div class="py-6 space-x-2 -mx-6 px-6 border-t border-gray-200 dark:border-gray-700">
                         <ui-button :text="isSoloNarrowStack ? __('Save') : __('Confirm')" @click="handleSaveOrConfirm" variant="primary" />
                         <ui-button :text="__('Cancel')" @click="editCancelled" variant="ghost" />
@@ -144,6 +152,8 @@ export default {
 
     inject: {
         suggestableConditionFieldsProvider: { default: null },
+        setConfig: { default: null },
+        setConfigErrors: { default: null },
     },
 
     components: {
@@ -173,6 +183,12 @@ export default {
     },
 
     computed: {
+        setConfigBlueprint() {
+            return {
+                tabs: [{ handle: 'main', sections: [{ fields: this.setConfig?.fields || [] }] }],
+            };
+        },
+
         suggestableConditionFields() {
             return this.suggestableConditionFieldsProvider?.suggestableFields(this) || [];
         },
@@ -271,6 +287,9 @@ export default {
                 hide: this.section.hide,
                 collapsible: this.section.collapsible,
                 collapsed: this.section.collapsed,
+                ...(this.setConfig?.fields.length || this.section.extraConfig ? {
+                    extraConfig: clone(this.section.extraConfig || this.setConfig.defaults),
+                } : {}),
             };
         },
 
diff --git a/resources/js/components/fieldtypes/replicator/SetsFieldtype.vue b/resources/js/components/fieldtypes/replicator/SetsFieldtype.vue
index 05e20973a46..fea9577bfa7 100644
--- a/resources/js/components/fieldtypes/replicator/SetsFieldtype.vue
+++ b/resources/js/components/fieldtypes/replicator/SetsFieldtype.vue
@@ -19,6 +19,7 @@
 </template>
 
 <script>
+import { computed } from 'vue';
 import Fieldtype from '../Fieldtype.vue';
 import SuggestsConditionalFields from '../../blueprints/SuggestsConditionalFields';
 import Tabs from '../../blueprints/Tabs.vue';
@@ -36,11 +37,29 @@ export default {
         };
     },
 
-    provide: {
-        isInsideSet: true,
+    provide() {
+        return {
+            isInsideSet: true,
+            setConfig: computed(() => this.meta?.setConfig),
+            setConfigErrors: this.setConfigErrors,
+        };
     },
 
     methods: {
+        setConfigErrors(id) {
+            for (const [tabIndex, tab] of this.value.entries()) {
+                const sectionIndex = tab.sections.findIndex(section => section._id === id);
+                if (sectionIndex === -1) continue;
+
+                const prefix = [this.fieldPathPrefix, this.handle, tabIndex, 'sections', sectionIndex, 'extraConfig', 'values'].filter(part => part !== undefined && part !== '').join('.') + '.';
+                return Object.fromEntries(Object.entries(this.publishContainer.errors || {})
+                    .filter(([key]) => key.startsWith(prefix))
+                    .map(([key, value]) => [key.slice(prefix.length), value]));
+            }
+
+            return {};
+        },
+
         tabsUpdated(tabs) {
             this.update(tabs);
         },
diff --git a/resources/js/tests/components/blueprints/Section.test.js b/resources/js/tests/components/blueprints/Section.test.js
new file mode 100644
index 00000000000..921b0dee761
--- /dev/null
+++ b/resources/js/tests/components/blueprints/Section.test.js
@@ -0,0 +1,64 @@
+import { shallowMount } from '@vue/test-utils';
+import { beforeEach, expect, test, vi } from 'vitest';
+import Section from '@/components/blueprints/Section.vue';
+
+beforeEach(() => {
+    global.clone = (value) => JSON.parse(JSON.stringify(value));
+    global.snake_case = (value) => value.toLowerCase().replaceAll(' ', '_');
+});
+
+function mountSection(extraConfig = undefined, setConfig = null) {
+    return shallowMount(Section, {
+        props: {
+            canDefineLocalizable: false,
+            section: { _id: 'hero', handle: 'hero', display: 'Hero', fields: [], ...(extraConfig && { extraConfig }) },
+        },
+        global: {
+            provide: { setConfig },
+            mocks: {
+                $config: { get: () => null },
+                $stacks: { stacks: () => [] },
+                $keys: { bindGlobal: () => ({ destroy: vi.fn() }) },
+            },
+            stubs: { 'ui-stack': true, Fields: true },
+        },
+    });
+}
+
+test('cancelling nested config edits leaves the original set unchanged', async () => {
+    const config = { values: { addon: { note: 'Original' } }, meta: {} };
+    const wrapper = mountSection(config);
+    wrapper.vm.edit();
+    wrapper.vm.editingSection.extraConfig.values.addon.note = 'Changed';
+    await wrapper.vm.$nextTick();
+    wrapper.vm.editCancelled();
+    expect(wrapper.props('section').extraConfig.values.addon.note).toBe('Original');
+    wrapper.vm.edit();
+    expect(wrapper.vm.editingSection.extraConfig.values.addon.note).toBe('Original');
+    wrapper.unmount();
+});
+
+test('confirming includes edited config in the updated set', () => {
+    const wrapper = mountSection({ values: { addon: { note: 'Original' } }, meta: {} });
+    wrapper.vm.edit();
+    wrapper.vm.editingSection.extraConfig.values.addon.note = 'Changed';
+    wrapper.vm.editConfirmed();
+    expect(wrapper.emitted('updated').at(-1)[0].extraConfig.values.addon.note).toBe('Changed');
+    wrapper.unmount();
+});
+
+test('new sets get independent copies of registered defaults', () => {
+    const setConfig = { fields: [{ handle: 'addon' }], defaults: { values: { addon: { note: 'Default' } }, meta: {} } };
+    const wrapper = mountSection(undefined, setConfig);
+    wrapper.vm.edit();
+    wrapper.vm.editingSection.extraConfig.values.addon.note = 'Changed';
+    expect(setConfig.defaults.values.addon.note).toBe('Default');
+    wrapper.unmount();
+});
+
+test('ordinary blueprint sections do not acquire set configuration', () => {
+    const wrapper = mountSection();
+    wrapper.vm.edit();
+    expect(wrapper.vm.editingSection).not.toHaveProperty('extraConfig');
+    wrapper.unmount();
+});
diff --git a/src/Fieldtypes/Sets.php b/src/Fieldtypes/Sets.php
index 4448d8ebebe..c8a304c3b27 100644
--- a/src/Fieldtypes/Sets.php
+++ b/src/Fieldtypes/Sets.php
@@ -6,7 +6,7 @@
 use Statamic\Facades\Asset;
 use Statamic\Facades\AssetContainer;
 use Statamic\Facades\Icon;
-use Statamic\Fields\Fieldset;
+use Statamic\Fields\ConfigFields;
 use Statamic\Fields\FieldTransformer;
 use Statamic\Fields\Fieldtype;
 use Statamic\Statamic;
@@ -18,6 +18,108 @@ class Sets extends Fieldtype
 {
     protected $selectable = false;
 
+    protected static $setConfigFields = [];
+
+    private const SET_KEYS = ['_id', 'handle', 'display', 'instructions', 'icon', 'image', 'hide', 'fields', 'extraConfig'];
+
+    public static function appendSetConfigFields(array $fields): void
+    {
+        foreach ($fields as $handle => $config) {
+            if (! is_string($handle) || in_array($handle, self::SET_KEYS)) {
+                throw new \InvalidArgumentException("Cannot append set config field [{$handle}]. Use a unique field handle.");
+            }
+        }
+
+        static::$setConfigFields = array_merge(static::$setConfigFields, $fields);
+    }
+
+    public static function appendSetConfigField(string $handle, array $config): void
+    {
+        static::appendSetConfigFields([$handle => $config]);
+    }
+
+    private function setConfigFields(): ConfigFields
+    {
+        return new ConfigFields(collect(static::$setConfigFields)->map(fn ($field, $handle) => compact('handle', 'field')));
+    }
+
+    private function preProcessSetConfig(array $set): array
+    {
+        $values = Arr::except($set, self::SET_KEYS);
+        $fields = $this->setConfigFields()->addValues($values)->preProcess();
+
+        if (! $values && $fields->all()->isEmpty()) {
+            return [];
+        }
+
+        return ['extraConfig' => [
+            'values' => array_merge($values, $fields->values()->all()),
+            'meta' => $fields->meta()->all(),
+        ]];
+    }
+
+    private function processSetConfig(array $section): array
+    {
+        $values = Arr::except($section['extraConfig']['values'] ?? [], self::SET_KEYS);
+
+        return array_merge($values, $this->setConfigFields()->addValues($values)->process()->values()->all());
+    }
+
+    public function preload()
+    {
+        $fields = $this->setConfigFields()->preProcess();
+
+        return ['setConfig' => [
+            'fields' => $fields->toPublishArray(),
+            'defaults' => [
+                'values' => $fields->values()->all(),
+                'meta' => $fields->meta()->all(),
+            ],
+        ]];
+    }
+
+    public function extraRules(): array
+    {
+        return $this->setConfigValidation('rules');
+    }
+
+    public function extraValidationAttributes(): array
+    {
+        return $this->setConfigValidation('attributes');
+    }
+
+    private function setConfigValidation(string $method): array
+    {
+        return collect($this->field->value())->flatMap(function ($tab, $tabIndex) use ($method) {
+            return collect($tab['sections'] ?? [])->flatMap(function ($section, $sectionIndex) use ($tabIndex, $method) {
+                $prefix = "{$this->field->handle()}.{$tabIndex}.sections.{$sectionIndex}.extraConfig.values.";
+                $validator = $this->setConfigFields()
+                    ->addValues($section['extraConfig']['values'] ?? [])
+                    ->validator()
+                    ->withContext(['prefix' => $this->field->validationContext('prefix').$prefix]);
+
+                return collect($validator->{$method}())->mapWithKeys(fn ($value, $handle) => [$prefix.$handle => $value]);
+            });
+        })->all();
+    }
+
+    public function preProcessValidatable($value)
+    {
+        return collect($value)->map(function ($tab) {
+            $tab['sections'] = collect($tab['sections'] ?? [])->map(function ($section) {
+                if (static::$setConfigFields) {
+                    $values = $section['extraConfig']['values'] ?? [];
+                    $section['extraConfig']['values'] = array_merge($values, $this->setConfigFields()
+                        ->addValues($values)->preProcessValidatables()->values()->all());
+                }
+
+                return $section;
+            })->all();
+
+            return $tab;
+        })->all();
+    }
+
     /**
      * Converts the "sets" array of a Replicator (or Bard) field into what the
      * <sets-fieldtype> Vue component is expecting, within either the Blueprint
@@ -50,7 +152,7 @@ public function preProcess($sets)
                 'instructions' => $group['instructions'] ?? null,
                 'icon' => $group['icon'] ?? null,
                 'sections' => collect($group['sets'] ?? [])->map(function ($set, $setHandle) use ($groupId) {
-                    return [
+                    return array_merge($this->preProcessSetConfig($set), [
                         '_id' => $setId = $groupId.'-section-'.$setHandle,
                         'handle' => $setHandle,
                         'display' => $set['display'] ?? null,
@@ -61,7 +163,7 @@ public function preProcess($sets)
                         'fields' => collect($set['fields'] ?? [])->map(function ($field, $i) use ($setId) {
                             return array_merge(FieldTransformer::toVue($field), ['_id' => $setId.'-'.$i]);
                         })->all(),
-                    ];
+                    ]);
                 })->values()->all(),
             ];
         })->values()->all();
@@ -122,7 +224,7 @@ public function process($tabs)
                     'icon' => $tab['icon'] ?? null,
                     'sets' => collect($tab['sections'])->mapWithKeys(function ($section) {
                         return [
-                            $section['handle'] => [
+                            $section['handle'] => array_merge($this->processSetConfig($section), [
                                 'display' => $section['display'],
                                 'instructions' => $section['instructions'] ?? null,
                                 'icon' => $section['icon'] ?? null,
@@ -131,7 +233,7 @@ public function process($tabs)
                                 'fields' => collect($section['fields'])->map(function ($field) {
                                     return FieldTransformer::fromVue($field);
                                 })->all(),
-                            ],
+                            ]),
                         ];
                     })->all(),
                 ],
diff --git a/tests/Fieldtypes/SetConfigTest.php b/tests/Fieldtypes/SetConfigTest.php
new file mode 100644
index 00000000000..34f12738126
--- /dev/null
+++ b/tests/Fieldtypes/SetConfigTest.php
@@ -0,0 +1,195 @@
+<?php
+
+namespace Tests\Fieldtypes;
+
+use Illuminate\Validation\ValidationException;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use ReflectionProperty;
+use Statamic\Facades\User;
+use Statamic\Fields\Field;
+use Statamic\Fields\Fields;
+use Statamic\Fields\FieldTransformer;
+use Statamic\Fieldtypes\Sets;
+use Tests\PreventSavingStacheItemsToDisk;
+use Tests\TestCase;
+
+class SetConfigTest extends TestCase
+{
+    use PreventSavingStacheItemsToDisk;
+
+    public function tearDown(): void
+    {
+        (new ReflectionProperty(Sets::class, 'setConfigFields'))->setValue(null, []);
+
+        parent::tearDown();
+    }
+
+    #[Test]
+    public function it_preloads_registered_fields_and_their_processed_defaults()
+    {
+        Sets::appendSetConfigField('note', ['type' => 'textarea', 'display' => 'Note']);
+        Sets::appendSetConfigFields(['enabled' => ['type' => 'toggle', 'default' => true]]);
+
+        $meta = (new Sets)->preload()['setConfig'];
+
+        $this->assertEquals(['note', 'enabled'], array_column($meta['fields'], 'handle'));
+        $this->assertSame(true, $meta['defaults']['values']['enabled']);
+        $this->assertArrayHasKey('note', $meta['defaults']['meta']);
+        $this->assertFalse((new Sets)->configFields()->all()->has('note'));
+    }
+
+    #[Test]
+    #[DataProvider('fieldtypes')]
+    public function it_round_trips_nested_config_through_field_configuration_and_yaml($type)
+    {
+        $this->registerFields();
+        $fieldtype = (new Field('content', ['type' => $type]))->fieldtype();
+        $sets = $this->sets();
+        $values = $fieldtype->configBlueprint()->fields()->addValues(['sets' => $sets])->preProcess()->values()->all();
+        $section = &$values['sets'][0]['sections'][0];
+
+        $this->assertEquals('Original note', $section['extraConfig']['values']['addon']['note']);
+        $this->assertArrayHasKey('addon', $section['extraConfig']['meta']);
+        $section['handle'] = 'renamed';
+        $section['extraConfig']['values']['addon']['note'] = 'Edited note';
+        $section['extraConfig']['values']['addon']['enabled'] = false;
+
+        $fields = $fieldtype->configBlueprint()->fields()->addValues($values);
+        $fields->validate();
+        $processed = $fields->process()->values()->all();
+        $yaml = FieldTransformer::fromVue([
+            'type' => 'inline',
+            'handle' => 'content',
+            'fieldtype' => $type,
+            'config' => array_merge($processed, ['type' => $type]),
+        ]);
+        $saved = $yaml['field']['sets']['main']['sets']['renamed'];
+
+        $this->assertEquals(['note' => 'Edited note', 'enabled' => false], $saved['addon']);
+        $this->assertEquals(['keep' => 'Unknown addon data'], $saved['other_addon']);
+        $this->assertEquals($sets['main']['sets']['hero']['fields'], $saved['fields']);
+        $this->assertArrayNotHasKey('extraConfig', $saved);
+        $this->assertArrayNotHasKey('_id', $saved);
+        $reopened = $fieldtype->configBlueprint()->fields()->addValues($yaml['field'])->preProcess()->values()->get('sets');
+        $this->assertEquals('Edited note', $reopened[0]['sections'][0]['extraConfig']['values']['addon']['note']);
+    }
+
+    public static function fieldtypes(): array
+    {
+        return [['replicator'], ['bard']];
+    }
+
+    #[Test]
+    public function it_preserves_metadata_without_the_registering_addon_and_in_legacy_sets()
+    {
+        $legacy = $this->sets()['main']['sets'];
+        $fieldtype = new Sets;
+        $preprocessed = $fieldtype->preProcess($legacy);
+        $saved = $fieldtype->process($preprocessed)['main']['sets']['hero'];
+
+        $this->assertEquals($legacy['hero']['addon'], $saved['addon']);
+        $this->assertEquals($legacy['hero']['other_addon'], $saved['other_addon']);
+    }
+
+    #[Test]
+    public function it_keeps_config_with_its_set_when_reordering_or_duplicating()
+    {
+        $this->registerFields();
+        $fieldtype = new Sets;
+        $tabs = $fieldtype->preProcess($this->sets());
+        $copy = $tabs[0]['sections'][0];
+        $copy['handle'] = 'copy';
+        $copy['extraConfig']['values']['addon']['note'] = 'Copied note';
+        array_unshift($tabs[0]['sections'], $copy);
+        $saved = $fieldtype->process($tabs)['main']['sets'];
+
+        $this->assertEquals(['copy', 'hero'], array_keys($saved));
+        $this->assertEquals('Copied note', $saved['copy']['addon']['note']);
+        $this->assertEquals('Original note', $saved['hero']['addon']['note']);
+    }
+
+    #[Test]
+    public function it_validates_nested_config_with_the_set_path_and_field_display()
+    {
+        $this->registerFields();
+        $tabs = (new Sets)->preProcess($this->sets());
+        $tabs[0]['sections'][0]['extraConfig']['values']['addon']['note'] = '';
+        $fields = (new Fields([['handle' => 'sets', 'field' => ['type' => 'sets']]]))->addValues(['sets' => $tabs]);
+
+        try {
+            $fields->validate();
+            $this->fail('Expected validation to reject the empty note.');
+        } catch (ValidationException $e) {
+            $errors = $e->errors();
+            $this->assertArrayHasKey('sets.0.sections.0.extraConfig.values.addon.note', $errors);
+            $this->assertStringContainsString('Guidance note', $errors['sets.0.sections.0.extraConfig.values.addon.note'][0]);
+        }
+    }
+
+    #[Test]
+    public function it_does_not_allow_extra_values_to_overwrite_native_set_settings()
+    {
+        $tabs = (new Sets)->preProcess($this->sets());
+        $tabs[0]['sections'][0]['extraConfig']['values']['fields'] = ['overwritten'];
+        $tabs[0]['sections'][0]['extraConfig']['values']['display'] = 'Overwritten';
+        $tabs[0]['sections'][0]['extraConfig']['values']['_id'] = 'internal';
+        $saved = (new Sets)->process($tabs)['main']['sets']['hero'];
+
+        $this->assertEquals('Hero', $saved['display']);
+        $this->assertEquals($this->sets()['main']['sets']['hero']['fields'], $saved['fields']);
+        $this->assertArrayNotHasKey('_id', $saved);
+    }
+
+    #[Test]
+    public function it_rejects_registration_of_reserved_handles()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+
+        Sets::appendSetConfigField('fields', ['type' => 'text']);
+    }
+
+    #[Test]
+    #[DataProvider('fieldtypes')]
+    public function the_field_editor_returns_config_and_rejects_invalid_set_values($type)
+    {
+        $this->registerFields();
+        $user = User::make()->id('editor')->set('super', true);
+        $values = $this->actingAs($user)->postJson(cp_route('fields.edit'), [
+            'type' => $type,
+            'values' => ['handle' => 'content', 'type' => $type, 'sets' => $this->sets()],
+        ])->assertOk()->assertJsonPath('meta.sets.setConfig.fields.0.handle', 'addon')->json('values');
+
+        $values['sets'][0]['sections'][0]['extraConfig']['values']['addon']['note'] = '';
+        $this->postJson(cp_route('fields.update'), ['type' => $type, 'values' => $values])
+            ->assertUnprocessable()
+            ->assertJsonValidationErrors(['sets.0.sections.0.extraConfig.values.addon.note']);
+
+        $values['sets'][0]['sections'][0]['extraConfig']['values']['addon']['note'] = 'Valid note';
+        $this->postJson(cp_route('fields.update'), ['type' => $type, 'values' => $values])
+            ->assertOk()->assertJsonPath('sets.main.sets.hero.addon.note', 'Valid note');
+    }
+
+    private function registerFields(): void
+    {
+        Sets::appendSetConfigField('addon', [
+            'type' => 'group',
+            'display' => 'Addon configuration',
+            'fields' => [
+                ['handle' => 'note', 'field' => ['type' => 'textarea', 'display' => 'Guidance note', 'validate' => 'required']],
+                ['handle' => 'enabled', 'field' => ['type' => 'toggle']],
+            ],
+        ]);
+    }
+
+    private function sets(): array
+    {
+        return ['main' => ['display' => 'Main', 'sets' => ['hero' => [
+            'display' => 'Hero',
+            'instructions' => 'Native instructions',
+            'addon' => ['note' => 'Original note', 'enabled' => true],
+            'other_addon' => ['keep' => 'Unknown addon data'],
+            'fields' => [['handle' => 'heading', 'field' => ['type' => 'text']]],
+        ]]]];
+    }
+}