Report Builder: drag & drop bricks within band canvases

[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

Drag & drop of bricks within a band canvas, using mason's built-in DnD (each band is its own Mason field — see #523). No custom Alpine grid, no zone overlays: that approach stalled the previous attempt (feature/145-report-builder).

• Reordering bricks inside a band persists the new order in that band's array in bands.json.
• Clicking a placed brick opens its config slide-over (configureBrickAction) pre-filled from the brick's saved config in bands.json — this is the form-population bug that blocked the old branch (it looked the config up in the dropped report_blocks table; now the canvas state itself is the single source of truth).
• Width per placed brick: one_third | half | two_thirds | full (ReportBlockWidth enum, harvested), editable in the slide-over.

Cross-band movement is not DnD — it's the "move to band…" action, tracked in #525.

Acceptance criteria

• Reordering two bricks in a band and saving swaps their positions in bands.json.
• Opening a placed brick's config shows its previously saved values (not defaults).
• Changing a config value + save persists it and the preview reflects it.
• Width choice persists and is honored by the preview layout.

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

• Save canvas state with bricks in order [A, B], then [B, A]; assert bands.json order follows.
• Config slide-over fill test: saved show_vat_id: false appears as unchecked on reopen.
• Width change round-trips through save/load.

[nielsdrost7]

SMART Plan — Report Builder: drag & drop bricks within band canvases

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

Specific

Bricks should be reorderable within a single band's canvas using Mason's built-in drag-and-drop, with a config slide-over that pre-fills from the brick's saved config. Current state on develop: none of this exists — there is no builder page, no Mason canvas wiring, no bands.json, and no configureBrickAction. This issue's own status note claims it's implemented on the open, unmerged feature/130-report-builder branch (PR #608). The specific defect this issue is guarding against — the config slide-over defaulting instead of pre-filling from saved values, because the old code looked the config up in a dropped report_blocks table — was a real bug in the previous, already-abandoned branch feature/145-report-builder; it isn't reproducible on develop today because there's no builder UI at all to reproduce it in.

Measurable

• Reordering two bricks within a band persists the new order.
  • PHPUnit: it_persists_reordered_brick_positions_within_a_band()

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

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

        /* Assert */
        $bands = app(ReportTemplateStorage::class)->loadBands($template->slug, $this->company->id);
        $this->assertSame('header_client', $bands['header'][0]['brick']);
    }

• Opening a placed brick's config slide-over shows its previously saved values, not defaults — the specific bug this issue exists to prevent.
  • Frontend/Livewire: as a company admin I want the config slide-over to show my saved values, not defaults, when I reopen a placed brick.

    #[Test]
    public function it_prefills_the_config_slide_over_with_the_bricks_saved_values(): void
    {
        /* Arrange */
        // bands.json already has header_company saved with show_vat_id => false

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

        /* Assert */
        $component->assertActionDataSet(['show_vat_id' => false]);
    }

• Changing a config value and saving persists it and updates the preview.

  • PHPUnit: it_persists_an_updated_config_value_on_save()

• Width choice (one_third | half | two_thirds | full) persists and is honored by the layout.

  • PHPUnit: it_persists_the_selected_brick_width()

Achievable

1. This cannot be built independently of Report Builder: code-defined Bricks (fields + config schema) #521 (brick registry + config schema) and Report Builder: file-based persistence (manifest + bands JSON), clone + sync-system #528 (bands.json persistence) — there's no canvas, storage format, or brick classes to drag yet.
2. Review PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 before starting fresh — its own notes claim this exact scope is already solved there.
3. If rebuilding: each band becomes its own Awcodes\Mason\Mason field (the awcodes/mason package is already a composer dependency, just unused in application code today); Mason's built-in DnD handles in-band reordering without a custom Alpine grid.
4. Tests belong in Modules/Core/Tests/Feature/ once the builder page exists.

Relevant

The previous attempt at this feature stalled specifically on the config-prefill defect described above — getting it right here unblocks the rest of Phase 2.

Time-bound

Sprint 6 — contingent on Phase 1 (#521, #528) landing and on the PR #608 review outcome.