TenantAtlas/specs/125-table-ux-standardization/data-model.md

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