Report Builder: move bricks between bands (move-to-band action)

[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

Moving a brick between bands (e.g. move the client phone from Header into Footer) happens through a "Move to band…" action on the placed brick — not by dragging across canvases. Since each band is its own Mason canvas (#523), cross-canvas dragging is deliberately out of scope; the action approach is deterministic and testable.

• The action lists only the target bands allowed by the brick's allowedBands().
• Moving preserves the brick's config and width; the brick is appended to the target band.
• The original v1 ask ("move the client's phone number to the company information block") is covered at brick-config level too: field-level visibility toggles in the Company/Client brick configs.

Acceptance criteria

• "Move to band…" on a placed brick offers only its allowed target bands.
• After moving + saving, the brick (with identical config) lives in the target band's array in bands.json and is gone from the source band.
• A brick whose allowedBands() is a single band shows no move targets.

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

• Move a header_client brick from header to footer; assert bands.json reflects source removal + target append with config intact.
• Assert a details-only brick offers no move targets.

[nielsdrost7]

SMART Plan — Report Builder: move bricks between bands (move-to-band action)

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

Specific

Moving a brick between bands (e.g. client phone from Header to Footer) should happen through an explicit "Move to band…" action rather than cross-canvas dragging, since each band is its own Mason field per #523 and Mason's DnD is per-field, not cross-field. Current state on develop: none of this exists — there is no "move to band" action, and it can't meaningfully be built until #523's five-canvas page exists to move a brick between in the first place. The design reasoning in this issue (action instead of DnD, because canvases are per-field) is sound and consistent with how #519 describes Mason's built-in reordering as strictly in-band.

Measurable

• "Move to band…" on a placed brick offers only its allowedBands() targets.
  • PHPUnit: it_offers_only_the_bricks_allowed_target_bands()

    #[Test]
    public function it_offers_only_the_bricks_allowed_target_bands(): void
    {
        /* Arrange */
        $brick = app(ReportBricksCollection::class)->find('header_client');

        /* Act */
        $targets = $brick->allowedBands();

        /* Assert */
        $this->assertContains(ReportBand::HEADER, $targets);
        $this->assertContains(ReportBand::FOOTER, $targets);
        $this->assertNotContains(ReportBand::DETAILS, $targets);
    }

• Moving + saving relocates the brick between bands' arrays in bands.json, with config and width intact.
  • PHPUnit: it_moves_a_bricks_config_and_width_intact_between_bands()

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

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

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

• A brick with a single allowed band shows no move targets.
  • PHPUnit: it_shows_no_move_targets_for_a_single_band_brick()

Achievable

1. Depends on Report Builder: code-defined Bricks (fields + config schema) #521 (allowedBands() per brick) and Report Builder: five band canvases (header, group header, details, group footer, footer) #523 (the five-canvas page the action lives on).
2. Implementation is a Filament Action operating on the mason canvas state, not a DnD handler — simpler and more testable, per this issue's own reasoning.
3. Review PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 first — it claims this exact action already exists there.

Relevant

Without this, moving content between bands (a routine layout adjustment, e.g. relocating a phone number from the header to the footer) requires re-adding the brick from scratch and losing its configuration.

Time-bound

Sprint 6.