70 lines
2.6 KiB
Markdown
70 lines
2.6 KiB
Markdown
# 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
|
|
|
|
1. Build or adapt a simple compare input:
|
|
- Baseline associative values
|
|
- Current associative values
|
|
- Optional changed keys
|
|
- Optional label map
|
|
2. Pass that input into `DiffPresenter`.
|
|
3. Render the returned summary with the shared summary partial.
|
|
4. Loop over the returned rows and render each row through the shared row partial.
|
|
5. If a row is list-like, let the row partial delegate to the inline list diff partial.
|
|
|
|
## Example adoption pattern
|
|
|
|
### Presenter usage
|
|
|
|
```php
|
|
$presentation = app(DiffPresenter::class)->present(
|
|
baseline: $baseline,
|
|
current: $current,
|
|
changedKeys: $changedKeys,
|
|
labels: $labels,
|
|
);
|
|
```
|
|
|
|
### 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
|
|
```
|
|
|
|
## 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.
|