Report Builder: code-defined Bricks (fields + config schema)

[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 1. Part of epic #506, Track A.

Scope

Bricks are defined purely in code — there is no report_blocks table and no DB registry. Each brick is a class in app/Mason/Bricks/ extending Awcodes\Mason\Brick:

• getId(), getLabel(), getIcon()
• allowedBands(): array of ReportBand (header, group_header, details, group_footer, footer)
• configureBrickAction() — slide-over Filament form defining the brick's config schema and defaults (e.g. show_vat_id, font_size)
• toHtml(array $config, array $data) / toPreviewHtml(array $config) — rendered through blade views at resources/views/mason/bricks/<brick>/{index,preview}.blade.php, with all output escaped via {{ }}

Harvest the 17 existing bricks + views from feature/145-report-builder (Header: company, client, invoice-meta, quote-meta, project · Detail: items, invoice-product, quote-product, invoice-project, quote-project, expense, tasks, customer-aging · Footer: totals, summary, notes, terms). Add two utility bricks for #95: PageBreakBrick and SpacerBrick.

Discovery/registry: ReportBricksCollection (harvested), extended with a per-band filter.

Acceptance criteria

• All bricks are discoverable via ReportBricksCollection with zero DB involvement.
• Every brick declares allowedBands(); the collection can filter bricks by band.
• Config values not present in a brick's schema are ignored at render time (unknown keys dropped).
• Every brick view escapes output ({{ }} only — no {!! !!} for user-influenced data).
• PageBreakBrick and SpacerBrick exist and are allowed in every band.

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

• Each brick renders expected HTML from a given config + data array (adapt the harvested MasonBricksTest).
• ReportBricksCollection::forBand(ReportBand::DETAILS) excludes header/footer-only bricks.
• Rendering with an unknown config key produces the same output as without it.

[nielsdrost7]

SMART Plan — Report Builder: code-defined Bricks (fields + config schema)

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

Specific

Bricks should be defined purely in code (no report_blocks table), each declaring allowedBands(), a config schema, and rendering via a Blade view. Current state on develop: resources/views/mason/bricks/ already contains 17 blade view pairs (index.blade.php + preview.blade.php) matching the brick list this issue asks to harvest (header-company, header-client, header-invoice-meta, detail-items, footer-totals, etc. — confirmed by directory listing), and spot-checking header-company/index.blade.php shows it already takes @props(['config' => [], 'data' => []]) and escapes all output via {{ }} — no {!! !!}. What's entirely missing is the PHP class layer: there is no Modules/Core/Mason/Bricks/ directory, no ReportBrick base class, no ReportBricksCollection, and nothing implementing Awcodes\Mason\Brick anywhere (awcodes/mason is a real composer dependency — confirmed in composer.json — just unused in Modules/Core today). So the "harvest" work here is "wrap 17 already-committed views in real brick classes and write the two new ones," not "build the views from scratch."

Measurable

• Every brick is discoverable via a ReportBricksCollection with zero database queries.
  • PHPUnit: it_discovers_every_registered_brick_with_no_database_queries()

    #[Test]
    public function it_discovers_every_registered_brick_with_no_database_queries(): void
    {
        /* Arrange */
        DB::enableQueryLog();

        /* Act */
        $bricks = app(ReportBricksCollection::class)->all();

        /* Assert */
        $this->assertGreaterThanOrEqual(17, $bricks->count());
        $this->assertEmpty(DB::getQueryLog());
    }

• forBand() filters bricks to those allowed in a given band.
  • PHPUnit: it_filters_bricks_to_only_those_allowed_in_the_given_band()

    #[Test]
    public function it_filters_bricks_to_only_those_allowed_in_the_given_band(): void
    {
        /* Act */
        $bricks = app(ReportBricksCollection::class)->forBand(ReportBand::DETAILS);

        /* Assert */
        $this->assertTrue($bricks->contains(fn ($b) => $b->getId() === 'detail_items'));
        $this->assertFalse($bricks->contains(fn ($b) => $b->getId() === 'footer_totals'));
    }

• Config values outside a brick's schema are dropped at render time.

  • PHPUnit: it_drops_unknown_config_keys_when_rendering_a_brick()

• PageBreakBrick and SpacerBrick exist and are allowed in every band.

  • PHPUnit: it_allows_the_page_break_and_spacer_bricks_in_every_band()

• The already-committed header-company view renders without error from a minimal data array (regression-checks the 17 existing blade views once wired to a class).

  • PHPUnit: it_renders_the_header_company_brick_from_a_minimal_data_array()

Achievable

1. Review PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 first — its status note claims all 17 bricks plus PageBreakBrick/SpacerBrick already exist there.
2. If building fresh: create Modules/Core/Mason/Bricks/, one class per existing blade view directory, each extending a new ReportBrick base class that implements allowedBands(): array and points at the matching resources/views/mason/bricks/<slug>/index.blade.php.
3. ReportBricksCollection::forBand(ReportBand $band) can build directly against Modules\Core\Enums\ReportBand, which already has the correct five cases.
4. PageBreakBrick and SpacerBrick need both new PHP classes and new blade views — nothing for either exists yet.

Relevant

This is the foundational registry every other Phase 2 issue (#519, #523, #525) depends on.

Time-bound

Sprint 5.