# List Surface Review Checklist

> Use this checklist for every spec or PR that creates or modifies a Filament table/list surface.
> All items must be satisfied or have a documented exception.

---

## Table Structure

- [ ] Columns follow the tier model (Primary / Context / Detail)
- [ ] Max ~7 visible columns by default (or density justified)
- [ ] Primary identifier is `searchable()` and `sortable()`
- [ ] Explicit `defaultSort()` is defined
- [ ] Timestamps use `->since()` + tooltip in lists
- [ ] Null values use `->placeholder('—')` consistently
- [ ] IDs are `toggleable(isToggledHiddenByDefault: true)` and `copyable()` where useful
- [ ] Status/enum columns use `badge()` via `BadgeCatalog` / `BadgeRenderer`
- [ ] Pagination profile matches the surface type (see table standard)

## Empty State

- [ ] `emptyStateHeading(...)` is domain-specific
- [ ] `emptyStateDescription(...)` explains what the user should do
- [ ] Exactly 1 primary CTA in `emptyStateActions([...])`, RBAC-gated
- [ ] When non-empty, CTA is in header only (not duplicated)

## Filters

- [ ] Tier 1–2 resources use the persistence trio
- [ ] Status/state filters use enum-backed options
- [ ] Soft-deletable resources use standard `TrashedFilter` labels
- [ ] Date range filters use `indicateUsing()`
- [ ] Filter count is reasonable (2–5 for Tier 1–2, 0–3 for Tier 3)
- [ ] Filter labels are clear and consistent with domain vocabulary

## Actions

- [ ] Inspect affordance exists (clickable rows preferred)
- [ ] No lone "View" row action button
- [ ] Max 2 visible row actions; rest in "More" group
- [ ] Destructive actions use `->requiresConfirmation()`
- [ ] Bulk actions use `BulkActionGroup`
- [ ] All actions are server-side authorized

## Persistence & State

- [ ] Resource lists (Tier 1–2) persist filters, search, sort in session
- [ ] Picker/widget tables do NOT persist state
- [ ] Refresh does not destroy user context on critical lists

## Performance

- [ ] No casual `sortable()` / `searchable()` on relations without query review
- [ ] No row-by-row counts in hot lists unless optimized
- [ ] Eager loading where relation-backed columns are rendered
- [ ] Default sort is query-efficient

## RBAC / Tenancy

- [ ] Cross-tenant/workspace tables provide enough context
- [ ] Technical IDs are not more prominent than needed
- [ ] Actions/CTAs are capability-gated
- [ ] Non-member access is 404, not 403

## Responsive

- [ ] No unnecessary horizontal overload
- [ ] Long text uses `wrap()` or `limit()` + `tooltip()`
- [ ] Long IDs do not break layout

---

## How to Use

1. Before submitting a PR that touches a table surface, walk through this checklist.
2. Mark items as checked or note the documented exception.
3. If you're adding a new resource, this checklist applies from the first implementation.
4. Guard tests enforce the most critical items automatically — this checklist catches the rest.