TenantAtlas/docs/ui/shared-diff-presentation-foundation.md

Shared Diff Presentation Foundation

Purpose

Use the shared diff presentation foundation when a screen already has simple before/after data and needs:

• one consistent state vocabulary (changed, unchanged, added, removed)
• shared summary badges
• shared row rendering
• inline list add/remove rendering
• one display policy for nulls, booleans, scalars, lists, and compact structured values

This foundation is presentation-only. It does not compare domain records for you, does not fetch data, and does not replace domain-specific diff rules.

Use It When

• a consumer already has keyed baseline/current values
• the comparison can be represented as row-level fields or simple scalar lists
• the screen benefits from reusable summary and row partials without needing a new Filament component type

Do Not Use It When

• the screen needs token-level or line-level diff behavior
• the layout would become less clear if flattened into generic rows
• the screen relies on domain-specific compare semantics that are not simple value presentation

The current specialized renderers stay specialized unless a later spec chooses otherwise:

• resources/views/filament/infolists/entries/normalized-diff.blade.php
• resources/views/filament/infolists/entries/assignments-diff.blade.php
• resources/views/filament/infolists/entries/scope-tags-diff.blade.php

Presenter Usage

use App\Support\Diff\DiffPresenter;

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

Expected input shape:

• baseline: keyed prior values
• current: keyed current values
• changedKeys: optional presenter hint for keys that should be treated as changed
• labels: optional display labels keyed by field key
• meta: optional view-safe metadata keyed by field key

DiffPresenter returns a DiffPresentation containing:

• summary: DiffSummary
• rows: ordered DiffRow instances

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

compact reduces spacing for dense layouts. dimUnchanged keeps unchanged content quieter than meaningful changes.

RBAC Role Definition Adoption

resources/views/filament/infolists/entries/rbac-role-definition-diff.blade.php is the first concrete consumer of the shared diff foundation.

Its consumer-local builder lives in app/Support/Diff/RbacRoleDefinitionDiffBuilder.php and is responsible for:

• preserving the existing RBAC evidence payload as the input contract
• adding fallback rows for Role source and Permission blocks when side metadata exists
• keeping top-level role metadata ahead of permission-block detail in a deterministic order
• designating these RBAC list-like keys for inline add/remove rendering:
  • Role definition > Scope tag IDs
  • Permission block * > Allowed actions
  • Permission block * > Denied actions
  • Permission block * > Conditions

Consumer-local choices for the first RBAC pass:

• unchanged rows stay visible but muted through dimUnchanged
• one-sided RBAC rows render through the shared added and removed states
• no local “show only changes” toggle is shipped in this first pass

Standalone Stringifier Usage

If a specialized renderer should not adopt DiffPresenter, it can still reuse ValueStringifier:

use App\Support\Diff\ValueStringifier;

$displayValue = app(ValueStringifier::class)->stringify($value);

Current shared formatting rules are:

• null -> —
• true / false -> Enabled / Disabled
• empty string -> ""
• empty list -> []
• simple scalar lists -> comma-separated values
• structured values -> compact JSON

Adoption Checklist

Before adopting the foundation in a consumer spec:

1. Confirm the consumer already owns authorization and compare-shape decisions.
2. Confirm the data is simple row/list presentation, not specialized diff logic.
3. Add or update Pest coverage for presenter output and rendered partial output.
4. Keep destructive actions, routes, and resource/global-search behavior unchanged unless the consumer spec explicitly covers them.

See specs/141-shared-diff-presentation-foundation/quickstart.md for the matching feature-level quickstart.