ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
440e63edff
TenantAtlas/specs/141-shared-diff-presentation-foundation/data-model.md
ahmido 0b5cadc234 feat: add shared diff presentation foundation (#170) 
## 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
2026-03-14 12:32:08 +00:00

4.6 KiB
Raw Blame History

Data Model: Shared Diff Presentation Foundation

Overview

This feature adds presentation-layer value objects and support types only. No database schema or persisted business record changes are introduced.

Entities

1. DiffRowStatus

  • Type: PHP backed enum
  • Purpose: Canonical presentation-state vocabulary for shared diff rendering
  • Values:
    • unchanged
    • changed
    • added
    • removed
  • Rules:
    • Treated as a presentation concern only
    • Drives summary counts, badge semantics, icons, and row-state rendering
    • Must remain reusable outside any single resource or domain service

2. DiffRow

  • Type: Immutable value object / DTO
  • Purpose: Render-ready representation of one compare row
  • Fields:
    • key: string
    • label: string
    • status: DiffRowStatus
    • oldValue: mixed
    • newValue: mixed
    • isListLike: bool
    • addedItems: array<int, mixed>
    • removedItems: array<int, mixed>
    • unchangedItems: array<int, mixed>
    • meta: array<string, scalar|array|null>
  • Validation rules:
    • key must be non-empty
    • label must be non-empty
    • status must be one of the enum values
    • List fragment arrays must be present as empty arrays when not used
    • meta must stay presentation-safe and serializable for view consumption

3. DiffSummary

  • Type: Immutable value object / DTO
  • Purpose: Shared summary counts and high-level message context for a rendered compare block
  • Fields:
    • changedCount: int
    • addedCount: int
    • removedCount: int
    • unchangedCount: int
    • hasRows: bool
    • message: ?string
  • Validation rules:
    • Counts are non-negative integers
    • hasRows is derived from total count
    • message is optional and consumer-supplied or presenter-generated fallback copy

4. DiffPresentation

  • Type: Immutable value object / DTO
  • Purpose: Stable wrapper returned by DiffPresenter so consumers can pass one object containing summary and ordered rows into shared partials or downstream adapters
  • Fields:
    • summary: DiffSummary
    • rows: array<int, DiffRow>
  • Validation rules:
    • summary must always be present
    • rows must preserve deterministic ordering
    • Empty compares are represented as an empty rows collection plus an explicit summary state

5. StructuredCompareInput

  • Type: Internal input shape consumed by DiffPresenter
  • Purpose: Minimal adaptation contract for simple compare payloads
  • Fields:
    • baseline: array<string, mixed>
    • current: array<string, mixed>
    • changedKeys: array<int, string>
    • labels: array<string, string>
    • meta: array<string, array<string, scalar|array|null>>
  • Rules:
    • baseline and current may each omit keys that exist on the other side
    • changedKeys is optional hint data; presenter can still derive state from values
    • labels is optional and must not block rendering when absent

6. InlineListFragments

  • Type: Derived presentation fragment embedded in DiffRow
  • Purpose: Simple inline list diff rendering for string or scalar lists
  • Fields:
    • addedItems: array<int, mixed>
    • removedItems: array<int, mixed>
    • unchangedItems: array<int, mixed>
  • Rules:
    • Built only when both values are simple list-like collections appropriate for inline comparison
    • Ordering should remain deterministic for stable rendering and tests
    • Not intended for token-level or line-level diff logic

Relationships

  • One DiffSummary describes a collection of DiffRow instances.
  • Each DiffRow has exactly one DiffRowStatus.
  • DiffPresenter converts one StructuredCompareInput into one DiffPresentation, containing one DiffSummary plus an ordered list of DiffRow instances.
  • ValueStringifier formats DiffRow.oldValue, DiffRow.newValue, and inline list items for display, but can also be used independently by specialized views.

State transitions

Row classification

  • Missing in baseline + present in current → added
  • Present in baseline + missing in current → removed
  • Present on both sides + materially equal → unchanged
  • Present on both sides + materially different → changed

Summary derivation

  • Summary counts are derived from the final DiffRow list.
  • Empty compare input produces either an empty summary or a no-data state, but never synthetic changes.

Non-persistent boundaries

  • None of these entities map to database tables.
  • None of these entities may fetch models or rely on Livewire runtime state.
  • None of these entities define authoritative business drift, compare, or restore logic.