---
phase: screens
kind: level
level: list
---

# Level — List view (SmartListView)

Use this level when the user wants to **see / browse / search** a collection of
entities. Mental model: a single page with a filters bar at the top, a table (or
card grid) below, and row-level / collection-level action buttons. Filters and
table are **always one screen** — never split.

## When to use

Trigger words: "list", "grid", "browse", "show all", "view all", "table",
"liste", "voir", "afficher".

Mandatory when:
- The section code ends in `-list`, `-grid`, `-browse`, `-search` (or is `list`).
- The bound use cases (the section's `use-case.md`) include verbs like "view",
  "browse", "find", "filter", "search", "review".

## What to produce

Produce **exactly one** `SmartListView` per list section. It carries:

- **Filtres** — the filter bar above the table (0+ fields; a list with only a
  global search input is fine).
- **Colonnes** — the table columns (4 to 7).
- **Actions** — collection-level (top toolbar) and row-level buttons, each gated
  by a permission code from the module's `rbac.md`.
- **Navigation** — the row click target: the matching `SmartForm` detail screen
  `code`, so the generator wires row-click navigation.

This one-page model mirrors the React page `scaffold-component` generates
(`<FiltersBar>` + `<DataTable>` in a single `ListPage.tsx`).

`screen.md` entry:

```markdown
### SCR-HR-EMPLOYEES-LIST-001 — Liste des employés (SmartListView)
- **Entité** : Employee (ENT-003)
- **Permission** : `hr.employees.read`
- **Cas d'usage liés** : UC-HR-EMPLOYEES-LIST-001, UC-HR-EMPLOYEES-LIST-002
- **Colonnes** : code (text), fullName (text, tri), department.name (lookup → Department), status (badge: active/inactive/onLeave), hireDate (date)
- **Filtres** : fullName (text/recherche), status (select), department (lookup → Department), hireDate (date-range) — orientation horizontale
- **Actions** : create (header, `hr.employees.create`), export (header, `hr.employees.export`), edit (row, `hr.employees.update`), delete (row, `hr.employees.delete`, scope « own »)
- **Navigation** : clic ligne → SCR-HR-EMPLOYEES-DETAIL-001
```

The richer per-field config-as-data shape (filter `type`, column `type`,
`options`, `entity` on lookups) is documented in `references/smartcomponents.md`.

## Choosing filters

Match what the user filters by **most often**. Pick 3 to 6 fields:

1. **Always** a global text search (the primary display attribute — `fullName`,
   `name`, `code`).
2. **Always** the workflow status filter if the entity has a status enum.
3. The most-cited foreign key (department, category, customer).
4. The primary date as a date-range (`createdAt`, `hireDate`, `dueDate`).
5. 1-2 more filters the use cases reference explicitly.

Orientation is `horizontal` by default; use `vertical` only for portals or
screens with ≥6 filters where a left sidebar makes sense.

## Choosing columns

Pick 4 to 7 columns:

1. **Always** the entity's natural key (`code`, or `id` if no code).
2. **Always** the primary display attribute (`name`, `fullName`, `title`).
3. A `status` badge if the entity has a status enum.
4. The most-cited foreign key.
5. The primary date.
6. 1-2 more attributes the use cases reference.

Avoid: long text fields (use `textarea` in the form), heavy computed fields,
more than 7 columns (stops fitting on a normal screen).

## Choosing actions

Map permissions to top-level (collection) and row-level actions:

| Action key | Where | Permission needed      |
|------------|-------|------------------------|
| `create`   | top   | `*.create`             |
| `export`   | top   | `*.export`             |
| `edit`     | row   | `*.update`             |
| `delete`   | row   | `*.delete`             |
| `approve`  | row   | `*.approve` (workflow) |
| `view`     | row   | `*.read` (default)     |

Always include row-level `edit` when a matching detail `SmartForm` exists, and
name that form as the row click target so navigation is wired.

### Custom (non-CRUD) actions — `sync`, `archive`, `approve`, `analyzeImpact`, …

Anything beyond the standard CRUD verbs above is a **custom action** and MUST be
declared under a separate `- **Actions personnalisées** :` bullet using the
structured format defined in `SKILL.md` (`## Custom actions — format structuré`).
Free-text mentions are silently dropped by `ba-create-prd`.

Two flavours :

- `kind: api` — emits a backend endpoint + service method + React Query hook +
  button. Use for `sync`, `archive`, `approve`, `mapToPce`, `analyzeImpact`, …
- `kind: navigate` — emits ONLY a button that calls `navigate(targetRoute)`.
  Use for row-level open / detail clicks that lead to another screen and
  **must not produce an axios call** (this is the fix for the legacy pattern
  `POST /{id}/open → 405`).

Append the sub-bullet to the list screen exactly as shown in the SKILL example.
The audit (`/ba-audit-screens` SCR-011/012/013) verifies the metadata is
complete and the endpoints/targets are unique and resolvable.

## When to use SmartCard instead

If the section is a customer-facing portal or the entity is best shown as tiles
(gallery, mobile-first), use `SmartCard` instead. Cards embed a search input in
their toolbar rather than a full filter bar — see `references/smartcomponents.md`
for the SmartCard shape.

## Common mistakes

- **Two screens (one filter + one table) for the same section** → deprecated.
  One section = one `SmartListView`.
- **Forgetting `entity` on lookup columns** → fails post-check rule 5.
- **No row click target** → the generated page is not navigable (audit SCR-008
  also fires if the named target is broken).
- **Computed fields in the form's create mode** → fails the type-mapping rule.
- **More than 7 columns** → trim to the most important ones.
