TenantAtlas/specs/133-detail-page-template/research.md

Research: View Page Template Standard for Enterprise Detail Screens

Feature: 133-detail-page-template | Date: 2026-03-10

R1: Shared composition shape for enterprise detail pages

Decision: Introduce a narrow shared enterprise-detail composition layer that standardizes page header, section ordering, supporting-region cards, related context, and technical-detail treatment, while allowing each page to supply its own domain-specific sections.

Rationale: The target pages currently vary in how much structure they provide. BaselineSnapshot already uses a presenter plus sectioned Infolist, BackupSet and EntraGroup remain flatter, and OperationRun uses a custom viewer that reuses OperationRunResource::infolist(). A shared composition layer reduces layout drift without forcing every page into the same domain content.

Alternatives considered:

• Refactor each page independently with ad hoc sections: rejected because it would preserve page-by-page drift and make future adoption harder.
• Build a fully generic page framework that hides all Filament details: rejected because it would be heavier than the problem requires and would make domain-specific sections harder to express.

R2: Filament implementation pattern for the shared shell

Decision: Keep the standard inside Filament v5 read-only detail flows by composing sectioned Infolists and shared Blade or ViewEntry partials instead of switching pages to disabled edit forms or standalone Blade-only pages.

Rationale: Filament v5 guidance favors Infolists for view pages, and the repo already uses sectioned Infolists with custom Blade entries for richer content. This matches UX-001, preserves existing resource routes, and keeps detail pages inside the same action-surface and authorization model.

Alternatives considered:

• Use disabled forms for detail pages: rejected because UX-001 explicitly requires read-only Infolists or equivalent for view pages.
• Replace target pages with fully custom Blade pages: rejected because it would bypass existing resource behavior and make action-surface consistency harder.

R3: Reuse of centralized badge and related-context helpers

Decision: Continue to source status and classification display from centralized badge domains and continue to assemble linked context via RelatedNavigationResolver wherever applicable.

Rationale: The codebase already centralizes status-like meanings in BadgeRenderer and related links in RelatedNavigationResolver. Reusing those helpers keeps badge semantics aligned with BADGE-001 and ensures related-context entries remain permission-aware.

Alternatives considered:

• Create page-local badge mappings or related-link logic: rejected because it would reintroduce inconsistency and increase RBAC risk.
• Inline all related links directly in each page class: rejected because it would duplicate navigation decisions and erode the structured related-context pattern.

R4: Presenter strategy per target page

Decision: Use page-level presenters or builders to emit a shared page model, adapting existing presenter patterns where they already exist and introducing new builders where pages currently render raw fields directly.

Rationale: The spec explicitly requires a page-level view model or presenter layer. The repo already has a working example in BaselineSnapshotPresenter, and OperationRun already centralizes view structure in OperationRunResource::infolist(). Extending those patterns is lower-risk than embedding layout decisions directly in model-order field lists.

Alternatives considered:

• Keep layout logic directly in the resource infolist() methods for all pages: rejected because it makes section visibility, taxonomy, and reuse harder to enforce.
• Create one giant presenter for every resource type: rejected because the target pages still need domain-specific data assembly.

R5: Main-and-supporting layout handling

Decision: Implement the enterprise detail standard as a main-and-supporting-region shell backed by explicit section classification, not as a visual afterthought on top of existing field lists.

Rationale: The repo does not currently expose an obvious shared MainAsideInfolist or equivalent helper, so the standard needs an explicit composition contract. The supporting region must stay disciplined and compact, carrying status, timestamps, related context, and contextual next actions rather than leftover fields.

Alternatives considered:

• Leave the main/aside decision to each page: rejected because the feature exists specifically to stop those ad hoc layout choices.
• Force every page into the same card count or identical visual shell: rejected because domain-specific sections still need freedom inside the shared hierarchy.

R6: Testing approach for the standard

Decision: Use a combination of focused Pest feature tests for rendered page structure, Livewire tests where pages are mounted as components, unit tests for the shared composition layer, and existing guard tests for action-surface consistency.

Rationale: The repo already has strong detail-page coverage patterns. BaselineSnapshot has feature tests for structured rendering, fallback rendering, degraded states, and authorization. OperationRun has Livewire tests against TenantlessOperationRunViewer. The repo also has guard coverage like ActionSurfaceContractTest and FilamentTableStandardsGuardTest. Extending these patterns provides stable regression coverage without introducing new test infrastructure.

Alternatives considered:

• Rely only on HTTP feature tests: rejected because the shared page-composition layer also needs direct unit coverage.
• Jump straight to browser tests: rejected because the main regression risks are hierarchy, section visibility, and authorization semantics, which are already well covered by feature and Livewire tests.

R7: Contract artifact shape for planning

Decision: Capture the standard as an internal OpenAPI contract that models the read-only composition payload expected by each aligned detail route: header, sections, supporting cards, related context, technical detail, and empty-state metadata.

Rationale: The feature adds no external JSON API, but the planning workflow still requires a contract artifact. Modeling the enterprise detail page as an internal read-model contract creates a stable schema for the shared presenter output and makes it easier to test or extend consistently across the initial targets.

Alternatives considered:

• Skip the contract artifact because the screens are HTML pages: rejected because the planning workflow requires a concrete contract deliverable.
• Create separate contracts for every page with completely different schemas: rejected because the point of the feature is convergence on one shared shell.