ahmido
3f6f80f7af
## Summary - add the RBAC role definition diff UX upgrade as the first concrete consumer of the shared diff presentation foundation - refine managed tenant onboarding draft routing, CTA labeling, and cancellation redirect behavior - tighten related Filament and diff rendering regression coverage ## Testing - updated focused Pest coverage for onboarding draft routing and lifecycle behavior - updated focused Pest coverage for shared diff partials and RBAC finding rendering ## Notes - Livewire v4.0+ compliance is preserved within the existing Filament v5 surfaces - provider registration remains unchanged in bootstrap/providers.php - no new Filament assets were added; existing deployment practice still relies on php artisan filament:assets when assets change Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #171
128 lines
4.4 KiB
Markdown
128 lines
4.4 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/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.
|
|
|
|
## 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`:
|
|
|
|
```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.
|