Filament Builder Title Laravel Package

Getting Started

Install the package and confirm the macros are registered in a scratch Filament form:

composer require mmoollllee/filament-builder-title

Start with the package README examples for Block::->title() and Repeater::->title(), then look at the testbench nested-builder demo page and render tests if you need to see preview/detached and nested-builder behavior.

First use case: replace a read-only builder block label with an editable header title.

use Filament\Forms\Components\Builder;
use Filament\Forms\Components\Builder\Block;
use Filament\Forms\Components\TextInput;

Builder::make('blocks')
    ->blocks([
        Block::make('hero')
            ->title()
            ->schema([
                TextInput::make('title')->required(),
                // ...
            ]),
    ]);

For repeater rows, pair ->title() with a hidden field so the header input has state to persist:

use Filament\Forms\Components\Hidden;
use Filament\Forms\Components\Repeater;

Repeater::make('items')
    ->title()
    ->schema([
        Hidden::make('title'),
        // ...
    ]);

v0.3.0 is a safe upgrade from v0.2.1: it fixes preview-block titles and adds the repeater title macro, with no user-facing breaking changes noted.

Implementation Patterns

• Builder block headers: use Block::make(...)->title() and keep the title field in the block schema. The macro renders an inline editable title in the block header instead of relying on a static label.
• Repeater row headers: use Repeater::make(...)->title() with Hidden::make($field) in the row schema. This replaces the read-only itemLabel with an editable header input; the hidden field is what persists the value.
• Preview blocks: when a block uses ->preview(), Filament static-renders the preview and does not mount the block schema, so the header input cannot resolve a server-side wire path. v0.3.0 restores the client-side path rebuild from the builder item DOM.
• Nested builders: use the same macros inside nested builder schemas. v0.3.0 resolves deep state paths from the nearest x-sortable-item and the builder-expand event, so nested titles bind correctly.
• Validation display: header inputs use the shared firstError() helper, so validation messages for the title field can surface in the header. Keep normal validation rules on the actual field.
• Integration: the macros work as normal Filament form component macros in resources, relation managers, and custom pages. They should not interfere with sorting/reordering because they only replace the header label rendering.
• Custom headers: if you wrap or override builder/repeater headers, preserve the package’s Alpine bindings rather than reimplementing the title input. The DOM contract is the sortable item wrapper plus the builder expand event.

Gotchas and Tips

• Upgrade to v0.3.0 if using ->preview() blocks. v0.2.0 dropped the client-side fallback and left preview blocks with a plain-text label; v0.3.0 fixes that regression.
• Preview blocks are detached. Do not expect server-side $wire path resolution inside a preview header. The title input rebuilds its path client-side, so custom header markup must keep the builder item’s x-sortable-item attribute and the x-on:builder-expand.window event intact.
• Repeater titles need a hidden field. Repeater::->title() is a header input, not a replacement for the row schema field. Without Hidden::make($field) the title has nowhere to persist.
• Nested builders depend on DOM ancestry. If titles bind to the wrong row in nested builders, inspect whether custom wrappers moved the x-sortable-item attribute or stopped the builder-expand event from bubbling.
• Do not replace the title input with a plain TextInput in the header unless you replicate the client-side path logic. Preview/detached blocks will not bind correctly with a normal server-resolved field.
• Debugging binding issues: use browser devtools to inspect the header input’s Alpine/wire path. Compare a preview block against a normally mounted block; if the path is empty, the client-side rebuild did not find the expected builder item DOM.
• Validation errors missing? Check that the title field is present in the block/repeater schema and has validation rules. The header only surfaces the first error; it does not replace the underlying field.
• Internal macro return types changed in v0.3.0. The macro closures dropped : static to fix a false intelephense(P1006). No action is needed for normal use, but copied macros should avoid the static return type.
• Extension point: the shared titleInput() / firstError() helpers are internal. If you need custom header UI, wrap the package behavior or mirror the DOM contract instead of reimplementing path binding. The package tests for detached blocks and nested builders are the best reference for expected behavior.