ahmido
a4f5c4f122
## 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
112 lines
6.3 KiB
Markdown
112 lines
6.3 KiB
Markdown
# Data Model: Filament Table UX Standardization & List Consistency
|
|
|
|
## Overview
|
|
|
|
This feature does not introduce new persistent storage. It defines a conceptual model for how production Filament tables are classified, reviewed, and rolled out.
|
|
|
|
## Entities
|
|
|
|
### TableSurface
|
|
|
|
- Purpose: Represents one production Filament-backed list surface that must be brought into the standard.
|
|
- Source: Existing resources, relation managers, widgets, custom pages, and Livewire table components.
|
|
|
|
#### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `surface_key` | string | yes | Stable identifier for the table surface, typically derived from class name and route role |
|
|
| `surface_type` | enum(`resource`,`relation_manager`,`widget`,`custom_page`,`picker`) | yes | Classification used for rollout rules and pagination profile |
|
|
| `plane` | enum(`admin`,`tenant`,`system`) | yes | Authorization plane in which the table is rendered |
|
|
| `route_scope` | enum(`workspace`,`tenant`,`canonical_view`) | yes | Scope used to reason about entitlement and visible context |
|
|
| `class_name` | string | yes | Backing PHP class for the table surface |
|
|
| `primary_route` | string | yes | Main route or route pattern where the table is reached |
|
|
| `data_ownership` | enum(`workspace_owned`,`tenant_owned`,`mixed`,`runtime_only`) | yes | Ownership context of the records displayed |
|
|
| `criticality` | enum(`critical`,`standard`,`special_case`) | yes | Rollout priority and review intensity |
|
|
| `has_empty_state` | boolean | yes | Whether the surface currently defines a domain-specific empty state |
|
|
| `has_default_sort` | boolean | yes | Whether the surface currently defines an explicit default sort |
|
|
| `has_persistence` | boolean | yes | Whether search, sort, and filters persist across refresh in the same session |
|
|
| `query_risk` | enum(`low`,`medium`,`high`) | yes | Risk level for adding or changing sort/search behavior |
|
|
| `exception_reason` | string nullable | no | Documented rationale when a standard rule is intentionally not applied |
|
|
|
|
#### Validation Rules
|
|
|
|
- `surface_key` must be unique across the audited table inventory.
|
|
- `surface_type`, `plane`, `route_scope`, and `criticality` must come from the controlled enums above.
|
|
- `exception_reason` is required when a mandatory standard rule is not applied.
|
|
- `query_risk` must be set before adding sort or search behavior to relation-backed or computed fields.
|
|
|
|
### TableBehaviorProfile
|
|
|
|
- Purpose: Captures the standardized behavior a table surface should implement.
|
|
|
|
#### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `default_sort_column` | string nullable | no | Default sort column when the surface has one |
|
|
| `default_sort_direction` | enum(`asc`,`desc`) nullable | no | Default sort direction |
|
|
| `search_fields` | list<string> | yes | User-facing searchable dimensions |
|
|
| `visible_default_column_limit` | integer | yes | Target number of visible default columns |
|
|
| `persistence_profile` | enum(`resource_list`,`optional`,`none`) | yes | Whether native table state persistence is required |
|
|
| `pagination_profile` | enum(`resource`,`relation_manager`,`widget`,`picker`,`custom_page`) | yes | Page-size rules for the surface class |
|
|
| `empty_state_required` | boolean | yes | Whether a domain-specific empty state is required |
|
|
| `timestamp_profile` | enum(`relative_default`,`absolute_required`,`mixed`) | yes | Default timestamp rendering expectation |
|
|
| `null_placeholder` | string | yes | Standard placeholder for missing values |
|
|
|
|
#### Relationships
|
|
|
|
- One `TableSurface` has one `TableBehaviorProfile`.
|
|
- A `TableBehaviorProfile` is implemented through native Filament table methods on the owning table class.
|
|
|
|
### ColumnProfile
|
|
|
|
- Purpose: Represents one meaningful column in a standardized table.
|
|
|
|
#### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `column_key` | string | yes | Stable column identifier matching the table definition |
|
|
| `tier` | enum(`primary`,`context`,`detail`) | yes | Conceptual visibility tier |
|
|
| `is_default_visible` | boolean | yes | Whether the column is visible in the default table surface |
|
|
| `is_toggleable` | boolean | yes | Whether the column can be toggled by the user |
|
|
| `is_hidden_by_default` | boolean | yes | Whether toggleable detail starts hidden |
|
|
| `is_sortable` | boolean | yes | Whether native sorting is enabled |
|
|
| `is_searchable` | boolean | yes | Whether native search is enabled |
|
|
| `rendering_type` | enum(`text`,`badge`,`icon`,`timestamp`,`count`,`identifier`,`boolean`,`custom`) | yes | Rendering category used for consistency review |
|
|
| `query_risk` | enum(`low`,`medium`,`high`) | yes | Risk of enabling or changing search/sort on the column |
|
|
|
|
#### Validation Rules
|
|
|
|
- Every table must have at least one `primary` column.
|
|
- `detail` columns should normally be toggleable and hidden by default unless a documented exception exists.
|
|
- `is_searchable` and `is_sortable` must remain false when the query risk is unacceptable and no mitigation exists.
|
|
|
|
### TableException
|
|
|
|
- Purpose: Captures a justified deviation from the standard.
|
|
|
|
#### Fields
|
|
|
|
| Field | Type | Required | Description |
|
|
|-------|------|----------|-------------|
|
|
| `surface_key` | string | yes | Referenced table surface |
|
|
| `rule_key` | string | yes | Standard rule being exempted |
|
|
| `reason` | string | yes | Human-readable explanation for the exception |
|
|
| `approved_phase` | enum(`foundation`,`critical_rollout`,`broad_rollout`,`hardening`) | yes | Phase in which the exception was recorded |
|
|
| `review_action` | string nullable | no | Follow-up needed to remove or reduce the exception |
|
|
|
|
## State Transitions
|
|
|
|
- Inventory: audit each production `TableSurface` and record its current `TableBehaviorProfile` and `ColumnProfile` set.
|
|
- Classification: assign each relevant column to `primary`, `context`, or `detail`.
|
|
- Standardization: apply the target behavior profile to the table using native Filament configuration.
|
|
- Exception handling: record a `TableException` where performance, scope, or product clarity prevents full compliance.
|
|
- Hardening: revisit medium- and high-risk exceptions after first-wave rollout and query review.
|
|
|
|
## Notes
|
|
|
|
- No migrations, new Eloquent models, or persistent tables are introduced by this feature.
|
|
- The model exists to support planning, phased rollout, and future review consistency rather than runtime storage.
|