Report Builder: five band canvases (header, group header, details, group footer, footer)

[nielsdrost7]

Status 2026-07-13: implemented on feature/130-report-builder (#608) — as-built notes in the #130 status section.

---

Parent: #130 (Report Builder — bands + bricks). Phase 2 (needs Phase 1: #521, #528). Part of epic #506, Track A.

Scope

The builder page shows five stacked Mason canvases, one per band, in fixed order:

1. Header
2. Group Header
3. Details
4. Group Footer
5. Footer

(ReportBand enum — harvested from feature/145-report-builder — already defines exactly these five.)

Each canvas is its own Awcodes\Mason\Mason field whose ->bricks() list is ReportBricksCollection::forBand($band) — a brick that isn't allowed in a band never appears in that band's picker. Saving the page merges the five canvas states into one bands.json via ReportTemplateStorage (#528). This replaces the previous single-canvas-with-zone-overlays attempt, which is what stalled the old branch.

Also in scope: the template list page (disk scan: system + current company templates) with Clone / Rename / Delete actions (company templates only; system templates read-only) and a Preview action rendering dummy data. Panel theme imports mason's plugin CSS.

Acceptance criteria

• Builder page renders five canvases in band order for a company template.
• Each band's brick picker only offers bricks whose allowedBands() include that band.
• Save writes all five bands into bands.json; an empty band saves as an empty array.
• System templates open read-only (no save/delete); clones are fully editable.
• Template list shows system + own-company templates only.

Test scenarios (PHPUnit + Livewire, #[Test], no Pest)

• Builder page loads for an admin (AbstractAdminPanelTestCase), asserts five band fields present.
• Saving a modified state persists to the expected storage path and round-trips.
• A details-only brick is absent from the header canvas's available bricks.
• Save action on a system template is rejected/hidden.

[nielsdrost7]

SMART Plan — Report Builder: five band canvases (header, group header, details, group footer, footer)

Context/Epic: Core (Reports), Track A / Phase 2 of epic #506 — parent #130, needs Phase 1 (#521, #528)

Specific

The builder page should show five stacked Mason canvases, one per band, in fixed order. Current state on develop: Modules\Core\Enums\ReportBand already defines exactly the five cases this needs (HEADER, GROUP_HEADER, DETAILS, GROUP_FOOTER, FOOTER, confirmed) with getOrder(), getLabel(), and color-class helpers already implemented — so the band model itself is solid and directly reusable. Everything else is missing: no builder page, no per-band Mason field, no template list page. The existing design-report-template.blade.php at Modules/Core/resources/views/filament/admin/resources/report-template-resource/pages/ is not an earlier version of this — it references a nonexistent ReportTemplateService/BlockTransformer, uses a single freeform drop area with hardcoded band colors rather than five real Mason canvases, and isn't wired into any panel navigation (no ReportTemplateResource PHP class exists to register it). It should be replaced, not extended.

Measurable

• Builder page renders five canvases in ReportBand's order for a company template.
  • Frontend/Livewire: as a company admin I want to see Header, Group Header, Details, Group Footer, Footer in that fixed order so the layout matches what will render.

    #[Test]
    public function it_renders_the_five_bands_in_report_band_order(): void
    {
        /* Arrange */
        $template = ReportTemplateStorage::clone('invoice/default', $this->company->id, 'Test');

        /* Act */
        $component = Livewire::actingAs($this->user)
            ->test(DesignReportTemplate::class, ['tenant' => Str::lower($this->company->search_code), 'slug' => $template->slug]);

        /* Assert */
        $component->assertSuccessful();
        foreach (ReportBand::cases() as $band) {
            $component->assertSee($band->getLabel());
        }
    }

• Each band's brick picker only offers bricks whose allowedBands() include that band.

  • PHPUnit: it_excludes_a_details_only_brick_from_the_header_bands_picker()

• Save writes all five bands into bands.json, including empty arrays for unused bands.

  • PHPUnit: it_saves_an_empty_array_for_a_band_with_no_bricks()

• System templates open read-only.

  • PHPUnit: it_hides_the_save_action_for_a_system_template()

• Template list shows only system templates plus the current company's own (tenant isolation).

  • PHPUnit: it_excludes_another_companys_templates_from_the_list()

Achievable

1. Depends on Report Builder: code-defined Bricks (fields + config schema) #521 (brick registry to populate each canvas's picker) and Report Builder: file-based persistence (manifest + bands JSON), clone + sync-system #528 (bands.json persistence) — cannot render or save without them.
2. Build a new page rather than extend design-report-template.blade.php; retire the ReportTemplateService/BlockTransformer references once this lands, since nothing currently uses that view.
3. Import Mason's plugin CSS via the panel theme — check resources/css/filament/admin/ for where that import belongs.
4. Review PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 before rebuilding — it claims this exact page already exists there.

Relevant

Without this page there is no UI for anything Phase 1 builds — the storage layer and brick registry have nothing to be edited through.

Time-bound

Sprint 6.