# 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.