Quickstart: Shared Diff Presentation Foundation

Purpose

Use this foundation when a screen already has simple structured compare data and needs consistent change-state semantics, summary badges, row rendering, inline list add/remove display, and shared value formatting.

Do not use it to replace specialized normalized diff, script diff, or other advanced compare experiences that need domain-specific layout or token/line-level logic.

Prerequisites

The consuming surface already has authorized baseline/current compare data.
The values can be represented as simple keyed fields or simple lists.
The consumer does not need a new route, new persistence model, or new compare engine.

Basic adoption flow

Build or adapt a simple compare input:
- Baseline associative values
- Current associative values
- Optional changed keys
- Optional label map
Pass that input into DiffPresenter.
Render the returned summary with the shared summary partial.
Loop over the returned rows and render each row through the shared row partial.
If a row is list-like, let the row partial delegate to the inline list diff partial.

Example adoption pattern

Presenter usage

$presentation = app(DiffPresenter::class)->present(
    baseline: $baseline,
    current: $current,
    changedKeys: $changedKeys,
    labels: $labels,
);

Blade usage

@include('filament.partials.diff.summary-badges', ['summary' => $presentation->summary])

@foreach ($presentation->rows as $row)
    @include('filament.partials.diff.row', [
        'row' => $row,
        'compact' => false,
        'dimUnchanged' => true,
    ])
@endforeach

Standalone stringifier usage

If a specialized view should not use DiffPresenter, it can still reuse ValueStringifier to standardize how nulls, booleans, scalars, simple lists, and compact structured values appear.

When not to use the foundation

The screen requires line-level or token-level script diff behavior.
The screen needs heavily specialized comparison layout that would become less clear if flattened into generic rows.
The screen would need new domain comparison rules rather than presentation reuse.

Testing expectations

Add Pest unit tests for any new presenter or stringifier behavior.
Add view-level tests for shared partial usage and state-specific rendering.
If a consumer adds a new diff-state badge domain mapping, cover it with badge tests.
Keep docs/ui/shared-diff-presentation-foundation.md aligned with the same presenter and partial names when adoption guidance changes.

2.6 KiB Raw Blame History