TenantAtlas/specs/125-table-ux-standardization/quickstart.md

Quickstart: Filament Table UX Standardization & List Consistency

Goal

Standardize production Filament list surfaces so they are calmer by default, sortable where users expect it, persistent on key resource lists, and consistent in empty states, pagination, and detail visibility.

Foundation Steps

1. Document the repo table standard and review checklist in the feature artifacts.
2. Confirm the audited table inventory and classify each surface by type: resource, relation manager, widget, custom page, or picker.
3. Define the pagination profiles that will apply across those surface types.
4. Confirm that resource-list search, sort, and filter persistence will use native Filament session persistence methods.
5. Identify first-wave critical tables and mark any known query-risk columns before changing sort or search behavior.

First-Wave Implementation Steps

1. Update the critical resource tables first: tenant, policy, backup set, backup schedule, provider connection, finding, and other designated high-value list surfaces.
2. For each critical table, assign columns to Primary, Context, and Detail tiers and reduce default visibility to a calm working set.
3. Add or refine explicit default sort behavior and searchable primary identifiers.
4. Hide technical IDs and secondary timestamps by default where practical, while keeping them accessible on demand.
5. Add or refine domain-specific empty states and align page-size options with the chosen pagination profile.
6. Enable native persistence for search, sort, and filters on resource lists.
7. Preserve existing action surfaces, badge semantics, tenancy boundaries, and authorization behavior.

Broad Rollout Steps

1. Apply the same standard to remaining resources, relation managers, widgets, custom pages, and picker tables.
2. Record documented exceptions for tables where relation-backed or computed columns should not become sortable or searchable.
3. Revisit tables with wide layouts and move lower-value columns into detail before considering any cosmetic workaround.
4. Finish with a pass that normalizes timestamp, placeholder, and ID rendering across remaining outliers.

Verification

Automated

vendor/bin/sail up -d
vendor/bin/sail artisan test --compact tests/Feature/Filament
vendor/bin/sail artisan test --compact tests/Feature/Rbac
vendor/bin/sail bin pint --dirty --format agent

Manual

1. Open each first-wave critical table and verify that the default visible columns feel calmer and remain informative.
2. Search, sort, and filter a resource list, refresh the page, and confirm the same state is preserved.
3. Verify that empty tables or zero-result states show clear domain-specific copy and only authorized next steps.
4. Confirm that long IDs and timestamps remain accessible without causing layout breakage.
5. Review system pages and cross-tenant views to ensure enough visible context remains to avoid ambiguity.
6. Re-check any relation-backed or computed columns that were left as documented exceptions.

Rollback

• Revert the affected table definitions and any tiny shared pagination helper introduced during the rollout.
• Remove or narrow any standardization changes that create unacceptable query cost, keeping documented exceptions in place.
• No database rollback is required unless a later implementation phase introduces unrelated schema changes, which this spec does not plan.