# 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.