[6.x] Add fluent field layout APIs

[riasvdv]

Description

Adds fluent APIs for creating and modifying field layouts, tabs, and layout elements.

Before:

$layout = $fields->createLayout([
    'type' => Entry::class,
    'tabs' => [
        [
            'name' => 'Content',
            'elements' => [
                [
                    'type' => CustomField::class,
                    'fieldUid' => $fields->getFieldByHandle('body')->uid,
                    'required' => true,
                ],
                [
                    'type' => Heading::class,
                    'heading' => 'Metadata',
                ],
                [
                    'type' => Tip::class,
                    'tip' => 'Keep this concise.',
                ],
            ],
        ],
    ],
]);

After:

$layout = FieldLayout::create(Entry::class)
    ->tab(
        FieldLayout::defaultTabName(),
        fn (FieldLayoutTab $tab) => $tab
            ->field('body', fn (CustomField $field) => $field->required())
            ->heading('Metadata')
            ->tip('Keep this concise.')
    );

or

$layout = FieldLayout::create(Entry::class)
    ->tab(FieldLayout::defaultTabName(), fn (FieldLayoutTab $tab) => $tab->add(
        CustomField::for('body')->required(),
        new Heading('Metadata'),
        new Tip('Keep this concise.'),
    ));

Once #19248 is stable or merged, I'll take another look at both so we have consistent APIs for creating these kind of fluent components/classes.

[github-actions]

📚 Storybook previews

@craftcms/cp — open Storybook

No changed components detected in this Storybook.

resources/js — open Storybook

No changed components detected in this Storybook.

[Copilot]

Pull request overview

Adds fluent/builder-style APIs to FieldLayout, FieldLayoutTab, and several layout elements to make programmatic layout composition (and later Inertia/Vue rendering) more ergonomic for core and plugin developers.

Changes:

• Introduced fluent APIs for creating/modifying layouts (FieldLayout::create(), FieldLayout::tab(), FieldLayoutTab::add(), etc.).
• Added fluent configuration helpers on layout elements/components (e.g. CustomField::for(), FieldLayoutElement::width(), UI element constructors, and condition setters).
• Updated/added test coverage and modernized factories/tests to use the fluent APIs; updated BaseField internals and changelog for the new method signatures/renames.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/Unit/FieldLayout/FluentBuilderTest.php	Adds unit coverage for fluent layout/tab/element APIs and related behaviors (UIDs, cache invalidation, duplicate handling).
tests/Feature/FieldLayout/FluentBuilderTest.php	Adds feature coverage for resolving fields by handle and persisting fluent layout modifications.
tests/Feature/Field/FieldsTest.php	Updates existing feature tests to build layouts via the new fluent APIs.
src/FieldLayout/LayoutElements/Users/EmailField.php	Updates override to renamed protected BaseField method (warningText).
src/FieldLayout/LayoutElements/Users/AffiliatedSiteField.php	Updates override to renamed protected BaseField method (instructionsText).
src/FieldLayout/LayoutElements/Tip.php	Adds string-friendly constructor and fluent setters for dismissible/style.
src/FieldLayout/LayoutElements/Template.php	Adds string-friendly constructor and fluent setter for template mode.
src/FieldLayout/LayoutElements/Markdown.php	Adds string-friendly constructor and fluent setter for displayInPane.
src/FieldLayout/LayoutElements/Heading.php	Adds string-friendly constructor for heading text.
src/FieldLayout/LayoutElements/CustomField.php	Adds CustomField::for() plus fluent mutators that keep field overrides in sync.
src/FieldLayout/LayoutElements/BaseField.php	Renames protected text methods, adds fluent setters (label/instructions/tip/warning/required/etc.).
src/FieldLayout/FieldLayoutTab.php	Adds add() fluent API with duplicate-field protections and dateAdded initialization.
src/FieldLayout/FieldLayoutElement.php	Adds fluent width() setter.
src/FieldLayout/FieldLayoutComponent.php	Adds fluent condition setters (userCondition(), elementCondition()).
src/FieldLayout/FieldLayout.php	Adds fluent layout creation/modification/removal APIs (create(), tab(), getTab(), removeField(), removeTab()).
database/Factories/FieldLayoutFactory.php	Updates factory helpers to build config via the fluent layout APIs.
CHANGELOG.md	Documents the new fluent APIs and the BaseField signature/method-name changes.