ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
codex/132-guid-context-resolver-session-1773161839
TenantAtlas/specs/122-empty-state-consistency/quickstart.md
ahmido 73a3a62451 Spec 122: Empty state consistency pass (#148) 
## Summary
- unify empty-state UX across the six in-scope Filament list pages
- move empty-state ownership toward resource `table()` definitions while preserving existing RBAC behavior
- add focused Pest coverage for empty-state rendering, CTA outcomes, populated-state regression behavior, and action-surface compliance
- add the Spec 122 planning artifacts and product discovery documents used for this pass

## Changed surfaces
- `PolicyResource`
- `BackupSetResource`
- `RestoreRunResource`
- `BackupScheduleResource`
- `WorkspaceResource`
- `AlertDeliveryResource`

## Tests
- `vendor/bin/sail artisan test --compact tests/Feature/Filament/EmptyStateConsistencyTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/Filament/CreateCtaPlacementTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/PolicySyncStartSurfaceTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/BackupScheduling/BackupScheduleLifecycleAuthorizationTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/Filament/BackupSetUiEnforcementTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/Filament/RestoreRunUiEnforcementTest.php`
- `vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php`
- `vendor/bin/sail bin pint --dirty --format agent`

## Notes
- Filament v5 / Livewire v4.0+ compliance is preserved.
- Panel provider registration remains unchanged in `bootstrap/providers.php`.
- No new globally searchable resources were added.
- Destructive actions were not introduced by this pass.
- Alert Deliveries is documented as the explicit no-header-action exemption for the empty-state CTA relocation rule.
- Manual light/dark visual QA evidence is still expected in the PR/review artifact set for the remaining checklist items (`T018`, `T025`).

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #148
2026-03-08 02:17:51 +00:00

4.7 KiB
Raw Permalink Blame History

Quickstart: Empty State Consistency Pass

Feature: 122-empty-state-consistency | Date: 2026-03-08

Scope

Unify the empty-state experience across six primary Filament list pages:

  • Policies
  • Backup Sets
  • Restore Runs
  • Backup Schedules
  • Workspaces
  • Alert Deliveries

The pass adds complete empty-state content (heading, description, icon, CTA), keeps existing RBAC behavior, updates the affected UI action-surface contract where needed, and adds focused regression coverage.

Implementation order

  1. Update the in-scope resource table() definitions so each list owns its empty-state heading, description, icon, and CTA whenever Filament supports it.
  2. Collapse or remove list-page-only empty-state helper responsibility where it would otherwise split the contract across resource and page classes.
  3. Keep existing header CTA placement behavior intact so the CTA remains in the empty state only when there are no rows and relocates to the header when rows exist for create-capable surfaces.
  4. For AlertDeliveryResource, add the guided empty state, update the action-surface declaration to satisfy ListEmptyState rather than exempting it, and preserve the documented no-header-action exemption once rows exist.
  5. Add or extend per-resource tests for empty-state copy, CTA presence, CTA outcomes, and capability-aware visibility or disabled behavior.
  6. Update shared guard and placement tests where the changed surfaces should now be covered explicitly, including representative populated-state regressions.
  7. Perform manual light/dark visual verification and attach evidence to the PR or review.
  8. Run focused Sail-based tests and Pint.

Primary files to modify

Likely test files

Validation commands

vendor/bin/sail artisan test --compact tests/Feature/Filament/CreateCtaPlacementTest.php
vendor/bin/sail artisan test --compact tests/Feature/PolicySyncStartSurfaceTest.php
vendor/bin/sail artisan test --compact tests/Feature/BackupScheduling/BackupScheduleLifecycleAuthorizationTest.php
vendor/bin/sail artisan test --compact tests/Feature/Filament/Alerts/AlertDeliveryViewerTest.php
vendor/bin/sail artisan test --compact tests/Feature/Guards/ActionSurfaceContractTest.php
vendor/bin/sail bin pint --dirty --format agent

Expected outcome

  • Every in-scope list page shows a deliberate, contextual empty state.
  • Each empty state has exactly one CTA and keeps existing authorization behavior.
  • AlertDeliveryResource no longer relies on an empty-state exemption.
  • Existing populated-table behavior and CTA-placement behavior remain intact, with Alert Deliveries preserved as the only documented no-header-action exemption.
  • Light/dark visual QA evidence is attached to review artifacts, not committed to the repository.