ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
139-verify-access-permissions-assist
TenantAtlas/specs/125-table-ux-standardization/tasks.md
ahmido a4f5c4f122 Spec 125: standardize Filament table UX (#152) 
## Summary
- standardize Filament table defaults across resources, relation managers, widgets, custom pages, and picker tables
- add shared pagination profiles, calm default column visibility, explicit empty states, and session persistence on designated critical resource lists
- complete Spec 125 artifacts, regression tests, and dashboard widget follow-up for lazy loading, sortable columns, and toggleable detail columns

## Verification
- `docker exec tenantatlas-laravel.test-1 php artisan test --compact --filter=BaselineCompareNow`
- `docker exec tenantatlas-laravel.test-1 php artisan test --compact --filter=TableStandardsBaseline`
- `docker exec tenantatlas-laravel.test-1 php artisan test --compact --filter=TableDetailVisibility`
- `docker exec tenantatlas-laravel.test-1 php artisan test --compact --filter=FilamentTableRiskExceptions`
- full suite run completed: `2017 passed, 10 failed, 8 skipped`
- manual browser QA completed on the tenant dashboard for lazy loading, sortable widget columns, toggleable hidden status columns, badges, and pagination

## Known Failures
The full suite still has 10 pre-existing failures unrelated to this branch:
- `Tests\\Unit\\OpsUx\\SummaryCountsNormalizerTest`
- `Tests\\Feature\\BackupWithAssignmentsConsistencyTest` (2 tests)
- `Tests\\Feature\\BaselineDriftEngine\\CaptureBaselineContentTest`
- `Tests\\Feature\\BaselineDriftEngine\\CompareContentEvidenceTest`
- `Tests\\Feature\\BaselineDriftEngine\\ResolverTest`
- `Tests\\Feature\\Filament\\TenantDashboardDbOnlyTest`
- `Tests\\Feature\\Operations\\ReconcileAdapterRunsJobTrackingTest`
- `Tests\\Feature\\ReviewPack\\ReviewPackRbacTest`
- `Tests\\Feature\\Verification\\VerificationReportRedactionTest`

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #152
2026-03-08 22:54:56 +00:00

21 KiB
Raw Permalink Blame History

Tasks: Filament Table UX Standardization & List Consistency

Input: Design documents from /specs/125-table-ux-standardization/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are REQUIRED for this runtime behavior change. Use Pest feature and guard coverage for critical list defaults, persisted table state, detail visibility, and query-risk exceptions. Operations: No OperationRun work is required because this feature does not introduce long-running, remote, queued, or scheduled behavior. RBAC: No new authorization behavior is introduced. Existing workspace and tenant isolation, capability checks, and destructive-action confirmation behavior must remain unchanged on all touched surfaces. Filament UI Action Surfaces: This feature modifies Filament resources, relation managers, widgets, pages, and picker tables, but preserves their existing action architecture. Tasks must keep record inspection affordances, grouped bulk actions, and destructive confirmations intact. Filament UI UX-001: This feature strengthens the table portions of UX-001 by standardizing empty states, search/sort behavior, and calm default visibility without changing create, edit, or view layouts. Badges: Badge semantics must remain centralized through the existing BadgeCatalog and BadgeRenderer infrastructure; no ad-hoc status mappings are allowed.

Organization: Tasks are grouped by user story so each story remains independently testable.

Phase 1: Setup (Shared Context)

Purpose: Align the rollout scope, target files, and existing test guardrails before touching runtime code.

  • T001 [P] Reconcile the rollout inventory, designated critical resource persistence set, and first-wave hotspot set in specs/125-table-ux-standardization/spec.md, specs/125-table-ux-standardization/plan.md, specs/125-table-ux-standardization/research.md, and specs/125-table-ux-standardization/data-model.md against the target table classes under app/Filament/, app/Livewire/, and tests/Feature/
  • T002 [P] Review existing list-surface guardrails in tests/Feature/Guards/ActionSurfaceContractTest.php, tests/Feature/Guards/NoAdHocStatusBadgesTest.php, and the current list regressions under tests/Feature/Filament/ before changing table defaults

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the shared standard, helper, and baseline test infrastructure that all user stories depend on.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

  • T003 Create the internal table standard and future PR checklist in docs/ui/filament-table-standard.md using the approved Primary / Context / Detail, pagination, persistence, timestamp, null, and ID rules from specs/125-table-ux-standardization/
  • T004 [P] Introduce the narrow shared pagination profile helper in app/Support/Filament/TablePaginationProfiles.php for resource, relation manager, widget, picker, and custom-page page-size conventions without hiding per-surface search, sort, visibility, or empty-state behavior
  • T005 [P] Create baseline cross-surface regression coverage in tests/Feature/Filament/TableStandardsBaselineTest.php for explicit default sort, empty states, and calm default-column expectations on representative list surfaces
  • T006 [P] Create guard coverage in tests/Feature/Guards/FilamentTableStandardsGuardTest.php to block missing default-sort, missing empty-state, and missing designated-resource persistence declarations on in-scope standardized tables, with explicit documented-exception handling for approved no-search or query-risk surfaces

Checkpoint: The standard, pagination profiles, and baseline guardrails are ready; user story work can now proceed.

Phase 3: User Story 1 - Scan Core Lists Predictably (Priority: P1) 🎯 MVP

Goal: Make the highest-value and most overloaded lists calm, sortable, and consistently empty-state-aware by default.

Independent Test: Open each first-wave critical list, verify a searchable and sortable primary identifier, confirm calm default columns with detail available on demand, and verify domain-specific empty-state behavior on empty datasets.

Tests for User Story 1 ⚠️

  • T007 [P] [US1] Create critical-list regression coverage in tests/Feature/Filament/TableStandardsCriticalListsTest.php for tenant, policy, backup set, backup schedule, provider connection, finding, operation run, and backup items relation-manager defaults
  • T008 [P] [US1] Extend existing list regressions in tests/Feature/Filament/TenantResourceIndexIsWorkspaceScopedTest.php, tests/Feature/Filament/PolicyListingTest.php, tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php, and tests/Feature/Findings/FindingsListDefaultsTest.php with sortability, empty-state, and visible-column assertions

Implementation for User Story 1

  • T009 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in app/Filament/Resources/TenantResource.php
  • T010 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in app/Filament/Resources/PolicyResource.php
  • T011 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in app/Filament/Resources/BackupSetResource.php
  • T012 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in app/Filament/Resources/BackupScheduleResource.php
  • T013 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in app/Filament/Resources/ProviderConnectionResource.php and app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php
  • T014 [P] [US1] Standardize primary-identifier search/sort, context columns, detail visibility, and empty-state behavior in app/Filament/Resources/FindingResource.php
  • T015 [P] [US1] Standardize default sort, recency/status columns, detail visibility, and empty-state behavior in app/Filament/Resources/OperationRunResource.php
  • T016 [US1] Standardize the overloaded relation-backed list in app/Filament/Resources/BackupSetResource/RelationManagers/BackupItemsRelationManager.php without changing its existing row, bulk, and confirmation behavior

Checkpoint: The first-wave critical tables should now feel predictable and calmer by default while preserving existing actions and RBAC semantics.

Phase 4: User Story 2 - Keep List Context Across Refresh (Priority: P2)

Goal: Persist search, sort, and filter state on key resource lists and align pagination behavior across table classes.

Independent Test: Apply search, sort, and filters on critical resource lists, refresh the page within the same session, and confirm the same list state remains active while approved page-size options stay consistent.

Tests for User Story 2 ⚠️

  • T017 [P] [US2] Create resource-list persistence coverage in tests/Feature/Filament/TableStatePersistenceTest.php for search, sort, and filter state across refresh on TenantResource, PolicyResource, BackupSetResource, BackupScheduleResource, ProviderConnectionResource, FindingResource, and OperationRunResource
  • T018 [P] [US2] Extend scoped list coverage in tests/Feature/Filament/TenantResourceIndexIsWorkspaceScopedTest.php, tests/Feature/Filament/PolicyListingTest.php, tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php, and tests/Feature/Findings/FindingsListFiltersTest.php with resource pagination and persisted-state assertions

Implementation for User Story 2

  • T019 [P] [US2] Apply native Filament search/sort/filter persistence and resource pagination profiles in app/Filament/Resources/TenantResource.php, app/Filament/Resources/PolicyResource.php, and app/Filament/Resources/BackupSetResource.php
  • T020 [P] [US2] Apply native Filament search/sort/filter persistence and resource pagination profiles in app/Filament/Resources/BackupScheduleResource.php, app/Filament/Resources/ProviderConnectionResource.php, app/Filament/Resources/FindingResource.php, and app/Filament/Resources/OperationRunResource.php
  • T021 [US2] Standardize pagination profiles across non-resource list surfaces in app/Filament/Resources/PolicyResource/RelationManagers/VersionsRelationManager.php, app/Filament/Resources/BackupScheduleResource/RelationManagers/BackupScheduleOperationRunsRelationManager.php, app/Filament/Widgets/Dashboard/RecentDriftFindings.php, app/Filament/Widgets/Dashboard/RecentOperations.php, app/Filament/System/Pages/Ops/Runs.php, app/Filament/System/Pages/Ops/Failures.php, app/Filament/System/Pages/Ops/Stuck.php, app/Filament/System/Pages/Directory/Tenants.php, app/Filament/System/Pages/Directory/Workspaces.php, app/Filament/System/Pages/Security/AccessLogs.php, app/Livewire/BackupSetPolicyPickerTable.php, app/Livewire/EntraGroupCachePickerTable.php, and app/Livewire/SettingsCatalogSettingsTable.php

Checkpoint: Key resource lists should now preserve user context across refresh, and table-class pagination defaults should be consistent across the product.

Phase 5: User Story 3 - Reveal Detail Only When Needed (Priority: P3)

Goal: Bring the remaining table surface into line on searchable primary identifiers, explicit default sort or documented exceptions, domain-specific empty states, hidden-by-default detail, timestamps, placeholders, identifiers, and query-safe exceptions.

Independent Test: Verify remaining resources, system pages, widgets, and picker tables expose a searchable primary identifier where appropriate, define an explicit default sort or documented exception, provide a domain-specific empty state, hide low-value technical detail by default, keep IDs readable without layout breakage, and document any approved no-search or query-risk exceptions.

Tests for User Story 3 ⚠️

  • T022 [P] [US3] Create broad-rollout coverage in tests/Feature/Filament/TableDetailVisibilityTest.php for remaining resource, widget, page, and picker surfaces covering searchable primary identifiers where appropriate, explicit default sorts or documented exceptions, domain-specific empty states, detail visibility, timestamp rendering, placeholders, and identifier presentation
  • T023 [P] [US3] Add query-risk and documented-exception guard coverage in tests/Feature/Guards/FilamentTableRiskExceptionsGuardTest.php for computed and relation-backed columns that intentionally remain non-sortable or non-searchable, plus approved surfaces where search is explicitly documented as providing no user value

Implementation for User Story 3

  • T024 [P] [US3] Standardize searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, calm defaults, toggle-hidden detail columns, timestamps, and null/ID rendering in app/Filament/Resources/EntraGroupResource.php, app/Filament/Resources/AlertDeliveryResource.php, app/Filament/Resources/AlertRuleResource.php, and app/Filament/Resources/AlertDestinationResource.php
  • T025 [P] [US3] Standardize searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, calm defaults, toggle-hidden detail columns, timestamps, and null/ID rendering in app/Filament/Resources/BaselineProfileResource.php, app/Filament/Resources/BaselineSnapshotResource.php, app/Filament/Resources/InventoryItemResource.php, app/Filament/Resources/PolicyVersionResource.php, app/Filament/Resources/ReviewPackResource.php, and app/Filament/Resources/Workspaces/WorkspaceResource.php
  • T026 [P] [US3] Standardize remaining relation-manager surfaces for searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, and calm detail handling in app/Filament/Resources/TenantResource/RelationManagers/TenantMembershipsRelationManager.php, app/Filament/Resources/Workspaces/RelationManagers/WorkspaceMembershipsRelationManager.php, and app/Filament/Resources/BaselineProfileResource/RelationManagers/BaselineTenantAssignmentsRelationManager.php
  • T027 [P] [US3] Standardize custom pages, query-risk system pages, and widgets for searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, and calm detail handling in app/Filament/Pages/InventoryCoverage.php, app/Filament/Pages/Monitoring/Operations.php, app/Filament/System/Pages/Directory/Tenants.php, app/Filament/System/Pages/Directory/Workspaces.php, app/Filament/System/Pages/Ops/Runs.php, app/Filament/System/Pages/Ops/Failures.php, app/Filament/System/Pages/Ops/Stuck.php, app/Filament/System/Pages/Security/AccessLogs.php, app/Filament/System/Pages/RepairWorkspaceOwners.php, app/Filament/Widgets/Dashboard/RecentDriftFindings.php, and app/Filament/Widgets/Dashboard/RecentOperations.php
  • T028 [US3] Standardize picker and selection tables for searchable primary identifiers where useful, explicit default sorts or documented exceptions, domain-specific empty states, and calm detail handling, then document surviving no-search and query-safe exceptions in app/Livewire/BackupSetPolicyPickerTable.php, app/Livewire/EntraGroupCachePickerTable.php, app/Livewire/SettingsCatalogSettingsTable.php, and docs/ui/filament-table-standard.md

Checkpoint: The broader table surface should now use the same default visibility, rendering, and documented-exception model as the first-wave critical lists.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Verify the full rollout, record a full-inventory compliance audit, format touched files, and complete manual QA before merge.

  • T029 [P] Run focused verification from specs/125-table-ux-standardization/quickstart.md with vendor/bin/sail artisan test --compact tests/Feature/Filament/TableStandardsBaselineTest.php tests/Feature/Filament/TableStandardsCriticalListsTest.php tests/Feature/Filament/TableStatePersistenceTest.php tests/Feature/Filament/TableDetailVisibilityTest.php tests/Feature/Filament/TenantResourceIndexIsWorkspaceScopedTest.php tests/Feature/Filament/PolicyListingTest.php tests/Feature/Filament/ProviderConnectionsDbOnlyTest.php tests/Feature/Findings/FindingsListDefaultsTest.php tests/Feature/Findings/FindingsListFiltersTest.php tests/Feature/Guards/FilamentTableStandardsGuardTest.php tests/Feature/Guards/FilamentTableRiskExceptionsGuardTest.php tests/Feature/Guards/ActionSurfaceContractTest.php tests/Feature/Guards/NoAdHocStatusBadgesTest.php
  • T030 Run vendor/bin/sail bin pint --dirty --format agent after changing app/Filament/, app/Livewire/, app/Support/Filament/, docs/ui/, and tests/Feature/
  • T031 Produce the post-rollout audit in docs/ui/filament-table-standard.md or an adjacent rollout appendix by reconciling the full production table inventory against explicit default sort or documented exception, domain-specific empty states, default column-count targets, designated persistence surfaces, and approved no-search or query-risk exceptions
  • T032 [P] Complete manual QA from specs/125-table-ux-standardization/quickstart.md across first-wave and broad-rollout surfaces for persisted state, empty states, overflow handling, and documented no-search and query-risk exceptions before merge

Dependencies & Execution Order

Phase Dependencies

  • Setup (Phase 1): No dependencies; can start immediately.
  • Foundational (Phase 2): Depends on Setup completion; blocks all user stories.
  • User Story 1 (Phase 3): Depends on Foundational completion; this is the MVP slice.
  • User Story 2 (Phase 4): Depends on Foundational completion and should follow User Story 1 because it touches the same critical resource files.
  • User Story 3 (Phase 5): Depends on Foundational completion and is safest after User Stories 1 and 2 establish the critical resource baseline.
  • Polish (Phase 6): Depends on completion of the desired user stories and closes with the final inventory audit.

User Story Dependencies

  • User Story 1 (P1): No dependency on other stories; delivers the first high-value standardization slice.
  • User Story 2 (P2): Can be tested independently, but should land after US1 because it modifies the same critical resource tables to add persistence and shared pagination behavior.
  • User Story 3 (P3): Can be tested independently, but should land after the critical-list baseline is stable so broad-rollout regressions are easier to isolate.

Within Each User Story

  • Test tasks should be added first and observed failing before implementation is considered complete.
  • Resource and relation-manager updates should preserve existing record inspection affordances, row actions, bulk actions, and destructive confirmations.
  • Query-risk surfaces should document exceptions before adding new sorts or searches to computed or relation-backed columns.
  • Shared pagination profiles should be reused where they reduce mechanical duplication, but domain-specific table logic must remain explicit in each table() definition.

Parallel Opportunities

  • T001 and T002 can run in parallel.
  • T004, T005, and T006 can run in parallel once the foundational direction is agreed.
  • T007 and T008 can run in parallel because they touch different test files.
  • T009 through T015 can run in parallel because they touch different resource files.
  • T017 and T018 can run in parallel because they touch different test files.
  • T019 and T020 can run in parallel because they split the critical resource set across different files.
  • T022 and T023 can run in parallel because they touch different test files.
  • T024, T025, T026, and T027 can run in parallel because they address different groups of surfaces.
  • T029 and T032 can run in parallel once implementation is complete.

Parallel Example: User Story 1

# Split first-wave critical resources across separate files:
Task: "T009 [US1] Standardize TenantResource in app/Filament/Resources/TenantResource.php"
Task: "T010 [US1] Standardize PolicyResource in app/Filament/Resources/PolicyResource.php"
Task: "T011 [US1] Standardize BackupSetResource in app/Filament/Resources/BackupSetResource.php"
Task: "T012 [US1] Standardize BackupScheduleResource in app/Filament/Resources/BackupScheduleResource.php"
Task: "T013 [US1] Standardize ProviderConnectionResource in app/Filament/Resources/ProviderConnectionResource.php and app/Filament/Resources/ProviderConnectionResource/Pages/ListProviderConnections.php"
Task: "T014 [US1] Standardize FindingResource in app/Filament/Resources/FindingResource.php"
Task: "T015 [US1] Standardize OperationRunResource in app/Filament/Resources/OperationRunResource.php"

Parallel Example: User Story 2

# Split persistence rollout across the critical resource files:
Task: "T019 [US2] Apply persistence and resource pagination profiles in app/Filament/Resources/TenantResource.php, app/Filament/Resources/PolicyResource.php, and app/Filament/Resources/BackupSetResource.php"
Task: "T020 [US2] Apply persistence and resource pagination profiles in app/Filament/Resources/BackupScheduleResource.php, app/Filament/Resources/ProviderConnectionResource.php, app/Filament/Resources/FindingResource.php, and app/Filament/Resources/OperationRunResource.php"

Parallel Example: User Story 3

# Split the broad rollout by surface group:
Task: "T024 [US3] Standardize remaining alert and group resources"
Task: "T025 [US3] Standardize baseline, inventory, policy-version, review-pack, and workspace resources"
Task: "T026 [US3] Standardize remaining relation managers"
Task: "T027 [US3] Standardize custom pages, system pages, and widgets"

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup.
  2. Complete Phase 2: Foundational.
  3. Complete Phase 3: User Story 1.
  4. Validate the critical list surfaces independently.
  5. Demo or review the first-wave standard before layering persistence and broad-rollout work.

Incremental Delivery

  1. Establish the standard, pagination profiles, and baseline guards.
  2. Ship the first-wave critical lists in US1.
  3. Add persisted list state and aligned pagination in US2.
  4. Finish the remaining surface rollout and documented exceptions in US3.
  5. Close with focused Sail tests, a full inventory audit, Pint, and manual QA.

Suggested MVP Scope

  • Deliver through Phase 3 / User Story 1 for the first merge candidate.
  • Defer persisted-state rollout and broad-surface cleanup until the critical list standards are accepted.

Notes

  • All tasks follow the required checklist format: checkbox, task ID, optional [P], required story label for story phases, and exact file paths.
  • No migrations, queue jobs, Graph integrations, or new authorization rules are part of this task list.
  • The action-surface contract remains in force: no task should remove record inspection affordances, grouped bulk actions, or destructive confirmations from existing list surfaces.