ahmido
0b5cadc234
## Summary - add a shared diff presentation layer under `app/Support/Diff` with deterministic row classification, summary derivation, and value stringification - centralize diff-state badge semantics through `BadgeCatalog` with a dedicated `DiffRowStatusBadge` - add reusable Filament diff partials, focused Pest coverage, and the full SpecKit artifact set for spec 141 ## Testing - `vendor/bin/sail artisan test --compact tests/Unit/Support/Diff/DiffRowStatusTest.php tests/Unit/Support/Diff/DiffRowTest.php tests/Unit/Support/Diff/DiffPresenterTest.php tests/Unit/Support/Diff/ValueStringifierTest.php tests/Unit/Badges/DiffRowStatusBadgeTest.php tests/Feature/Support/Diff/SharedDiffSummaryPartialTest.php tests/Feature/Support/Diff/SharedDiffRowPartialTest.php tests/Feature/Support/Diff/SharedInlineListDiffPartialTest.php` - `vendor/bin/sail bin pint --dirty --format agent` ## Filament / Livewire Contract - Livewire v4.0+ compliance: unchanged and respected; this feature adds presentation support only within the existing Filament v5 / Livewire v4 stack - Provider registration: unchanged; no panel/provider changes were required, so `bootstrap/providers.php` remains the correct registration location - Global search: unchanged; no Resource or global-search behavior was added or modified - Destructive actions: none introduced in this feature - Asset strategy: no new registered Filament assets; shared Blade partials rely on the existing asset pipeline and standard deploy step for `php artisan filament:assets` when assets change generally - Testing coverage: presenter, DTOs, stringifier, badge semantics, summary partial, row partial, and inline-list partial are covered by focused Pest unit and feature tests ## Notes - Spec checklist status is complete for `specs/141-shared-diff-presentation-foundation/checklists/requirements.md` - This PR preserves specialized diff renderers and documents incremental adoption rather than forcing migration in the same change Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #170
108 lines
3.5 KiB
Markdown
108 lines
3.5 KiB
Markdown
# 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/rbac-role-definition-diff.blade.php`
|
|
- `resources/views/filament/infolists/entries/assignments-diff.blade.php`
|
|
- `resources/views/filament/infolists/entries/scope-tags-diff.blade.php`
|
|
|
|
## Presenter Usage
|
|
|
|
```php
|
|
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
|
|
|
|
```blade
|
|
@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.
|
|
|
|
## Standalone Stringifier Usage
|
|
|
|
If a specialized renderer should not adopt `DiffPresenter`, it can still reuse `ValueStringifier`:
|
|
|
|
```php
|
|
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.
|