README

n-ramos/celebrimbor-filament-plugin

A Filament 5 plugin that plugs the @n-ramos/celebrimbor visual page builder into any Eloquent resource.

It follows the page builder's integration philosophy to the letter:

• blocks stay TypeScript-only — PHP never redefines them;
• Laravel only stores and transports JSON;
• the editor is the web component, two-way bound to Livewire.

What this package adds on top is enforcement: interface contracts that make the compiler/runtime refuse to mount the field unless the model exposes exactly what the editor needs.

Requirements

• PHP 8.2+
• Filament 5

No front-end build step. The plugin ships a self-contained editor bundle (vendored from @n-ramos/celebrimbor-embed) that defines the <my-page-builder> web component with the basic block library.

Installation

composer require n-ramos/celebrimbor-filament-plugin
php artisan filament:assets

That's it — the editor works out of the box. filament:assets publishes the bundled JS/CSS (versioned with the package) into public/.

Publish the config (optional):

php artisan vendor:publish --tag="celebrimbor-config"

Register the plugin on your panel

use NRamos\CelebrimborFilament\PageBuilderPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            PageBuilderPlugin::make()
                ->defaultPreset('marketing')
                ->assetEndpoint('/admin/page-builder/assets/pick'),
        );
}

(Advanced) Bring your own bundle

The default bundle ships the basic block library. To register custom blocks or fields, set celebrimbor.serve_bundle to false and provide your own bundle that defines <my-page-builder> — exactly as in the Celebrimbor docs:

import "@n-ramos/celebrimbor-editor-element/styles.css";
import { createBlockRegistry } from "@n-ramos/celebrimbor-core";
import { registerBasicBlocks } from "@n-ramos/celebrimbor-blocks-basic";
import { definePageBuilderElement } from "@n-ramos/celebrimbor-editor-element";

const registry = registerBasicBlocks(createBlockRegistry());

definePageBuilderElement({ registry }); // defines <my-page-builder>

The plugin's Livewire glue binds to whatever <my-page-builder> you register.

The contracts (what gets enforced)

1. The model must implement HasPageBuilderContent

This is the hard requirement. The field throws MissingPageBuilderContract at mount time if the bound model does not implement it. The InteractsWithPageBuilderContent trait gives you a zero-boilerplate implementation (and auto-casts the column to array).

use NRamos\CelebrimborFilament\Concerns\InteractsWithPageBuilderContent;
use NRamos\CelebrimborFilament\Contracts\HasPageBuilderContent;
use NRamos\CelebrimborFilament\Enums\PageBuilderFormat;
use Illuminate\Database\Eloquent\Model;

class Page extends Model implements HasPageBuilderContent
{
    use InteractsWithPageBuilderContent;

    protected $fillable = ['title', 'slug', 'status', 'document'];

    // Optional overrides (these are the defaults):
    protected string $pageBuilderColumn = 'document';
    protected string $pageBuilderFormat = PageBuilderFormat::Portable->value;
}

Migration:

Schema::create('pages', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->string('slug')->unique();
    $table->string('status')->default('draft');
    $table->json('document');
    $table->timestamps();
});

2. (Optional) declare your blocks with ProvidesPageBuilderBlocks

Implement it on the model or the resource to bind the editor to a specific preset/element without configuring the field every time:

use NRamos\CelebrimborFilament\Contracts\ProvidesPageBuilderBlocks;

class Page extends Model implements HasPageBuilderContent, ProvidesPageBuilderBlocks
{
    use InteractsWithPageBuilderContent;

    public function pageBuilderPreset(): string
    {
        return 'marketing';
    }

    public function pageBuilderEditorElement(): string
    {
        return 'my-page-builder';
    }
}

Usage in a resource form

use NRamos\CelebrimborFilament\Forms\Components\PageBuilderField;
use Filament\Forms;

public static function form(Schema $schema): Schema
{
    return $schema->components([
        Forms\Components\TextInput::make('title')->required(),
        Forms\Components\TextInput::make('slug')->required(),

        PageBuilderField::make('document')
            ->columnSpanFull(),
    ]);
}

Per-field overrides are available when you need them:

PageBuilderField::make('document')
    ->format(PageBuilderFormat::Document)
    ->blocksPreset('landing')
    ->editorElement('my-page-builder')
    ->assetEndpoint('/admin/page-builder/assets/pick')
    ->assetHeaders(['X-CSRF-TOKEN' => csrf_token()])
    ->minHeight('800px')
    ->columnSpanFull();

Resolution order for every option: explicit field setter → model/resource contract → panel plugin default → config file.

How it fits together

Filament form
  └─ PageBuilderField (celebrimbor::field)
       └─ <div x-data="celebrimborField({ state: $entangle(...) })">
            └─ <my-page-builder>   ← provided by the bundled editor (or your own)
                 ├─ emits my-page-builder:change  → updates Livewire state
                 └─ value property               ← seeded from Livewire state

• The field validates the model contract before rendering.
• format/preset/editorElement are resolved from the contracts/config.
• The JSON is persisted by Filament like any other array-cast column.
• Rendering the final page is the host front-end's job (Celebrimbor stays the single source of truth for blocks).

Asset picker

Point assetEndpoint at a route returning a Celebrimbor-compatible payload:

{ "id": "1", "url": "https://cdn/img.jpg", "alt": "…", "width": 1200, "height": 800 }

Documentation

• Installation
• Contracts
• Configuration
• Front-end & rendering
• Testing
• Rendering (preview & public, host-owned)
• Declaring a new block (end to end)
• Releasing (maintainers — the npm → Composer bridge)
• Local Laravel test (copy-paste scaffolding)

Testing

composer install
composer test

A Pest + Testbench suite covers the enum, the trait, the exception, the plugin config, and the field's contract enforcement and option-resolution priority. See docs/05-testing.md.

License

MIT — see LICENSE.md.