# Checklist Feature — Design Instructions

Implement two related capabilities on the existing Maintenance Platform design: **defining Checklist Templates** and **adding a checklist to an Activity** (or linking one to a Maintenance Plan). Follow the platform's existing design system, components, and patterns already established in this file — new screens should look native, not bolted on.

Traceability: requirement IDs (FR-CHK-xx) refer to SRS Addendum 1 — Preventive Maintenance Checklist Extension, v1.7. Use them as a checklist while building, not as user-facing text.

---

## 0. Core concepts to design around

- A **Checklist Template** is a reusable, named, ordered list of item definitions. It has a scope: **Site** (owned by one site's Site Manager) or **Central** (published by Central/Admin, usable as-is by every site — no local cloning).
- A **sub-activity** is a single checklist line once it's attached to an Activity — a lightweight record, not a full Activity. It captures one value according to its **item type**. It is NOT a mini work-order with its own stage pipeline.
- A sub-activity has its own simple **record status**: **New** (no value yet) → **Recorded** (value captured). This is separate from any value the item itself holds — e.g. the Status item type's own Open/On Hold/In Progress/Closed value is unrelated to the sub-activity's New/Recorded status.
- **Seven item types**, no sub-kinds: **Status**, **Select**, **Text Field**, **Number Field**, **Multi-Select**, **Checkbox**, **Message**.
- Checklists attach to **any Activity** (Preventive or Corrective) — but only **Site Manager and Admin** can attach one, build an ad-hoc one, or add a freestanding sub-activity. Ops/Engineer/Portfolio never see these controls.
- The **completion gate**: an activity with a checklist cannot move to Repaired/Done while any non-Message sub-activity is still New. This is absolute — never render an override for any role.
- Once a sub-activity is Recorded, it is **permanently locked** — no edit/delete for anyone, including its creator and Site Manager/Admin.

---

## 1. Item types — reference table

Design a consistent item-row component with 7 visual variants. Use this table for every field/control decision:

| Item type | What it captures | Input control | Completes when |
|---|---|---|---|
| **Status** | One of a fixed set: Open, On Hold, In Progress, Closed | Segmented control or dropdown, options fixed (not editable per-item) | Value = Closed (the only type with this special rule) |
| **Select** | One choice from a list | Dropdown/radio group. Two flavors: **Custom** (author-defined options, ≥2) or **Observation preset** (fixed: Pass, Flag, Fail) | Any option chosen |
| **Text Field** | Free text | Single-line text input | Any text entered |
| **Number Field** | A number | Numeric input | Any number entered |
| **Multi-Select** | Any number of choices | Checkbox group / multi-chip select, author-defined options (≥2) | At least one option selected |
| **Checkbox** | A plain confirmation | Single checkbox/toggle | Ticked |
| **Message** | Read-only text, no input | Styled banner: **Info** (blue) or **Warning** (amber) — author picks the type when building the template | Never — not completable, not counted in progress, excluded from the gate entirely |

Design note: Message should look visually distinct from the other six — it's a banner/callout, not a form field. It never shows a status pill, a lock icon, or a "Recorded" state, because it never becomes Recorded.

---

## 2. Screen: Checklist Template list

**New nav entry** (Settings or Admin area, consistent with where Tags/Disciplines live): "Checklist Templates."

**Visible to:** Site Manager, Admin, Central. Ops/Engineer/Portfolio do not get this nav item at all.

**Layout:** table/list view.

| Column | Notes |
|---|---|
| Name | |
| Scope | Badge: "Site" or "Central" |
| Items | Count |
| Version | e.g. "v3" |
| Status | Active / Inactive toggle or badge |
| Last updated | Date + editor's name |

**Row actions:** Edit, Deactivate (soft — never hard-delete a template that's linked to a plan or has generated activities).

**Primary action:** "New Template" button (top right, standard placement).

**Scoping in the list:**
- Site Manager sees their own site's templates (editable) + all Central templates (read-only row, no Edit action, just "View").
- Admin sees everything, all editable.
- Central sees their own Central templates (editable) + can view but not edit Site templates.

**Empty state:** icon + "No checklist templates yet" + primary CTA to create one. Keep consistent with other empty states already in the design (e.g. empty equipment list).

---

## 3. Screen: Create / Edit Checklist Template

**Header fields:**
- Name (required, text)
- Description (optional, textarea)
- Scope selector: "Site" (default) / "Central" — **Central option only shown/enabled for Central and Admin users**; Site Manager doesn't see it at all.
- Active toggle

**Version indicator:** small label near the header, e.g. "Version 3 · published 2 Aug 2026." On save, if this template is already linked to a Maintenance Plan or has generated activities, show a confirmation: *"Saving will publish a new version. Activities already generated keep their original version; only future ones use this update."*

**Item builder (the main content area):** an ordered, drag-to-reorder list. Each row expands to configure one item:

- **Label** (required, short text — this is what the assignee sees)
- **Item type** dropdown — the 7 types from §1
- **Conditional config**, shown inline once a type is picked:
  - Status → read-only helper text: "Fixed values: Open, On Hold, In Progress, Closed" (nothing to configure)
  - Select → toggle: "Custom options" (reveals an add/remove option-list editor, minimum 2) vs. "Observation preset" (read-only helper text: "Pass, Flag, Fail")
  - Multi-Select → option-list editor, minimum 2, same component as Select-Custom
  - Message → textarea for the message body + a small Info/Warning type toggle (render a live preview chip showing the banner style)
  - Text Field, Number Field, Checkbox → no extra config beyond the label
- **Delete item** icon, **drag handle** for reordering
- **"Add item"** button at the bottom of the list, opening a fresh row in the same pattern

**Footer actions:** Cancel, Save (Save & Publish if this is an edit to an already-linked template — see version note above).

---

## 4. Adding a checklist to an Activity

### 4.1 Entry point — Activity detail page

Add an **"Add Checklist"** control to the activity detail page. **Hide this control entirely** — don't just disable it — for anyone who isn't Site Manager or Admin. There should be nothing on screen hinting the feature exists for other roles.

Clicking it opens a small chooser:
- **"From a template"** → opens a searchable template picker (respecting the same scope rules as §2 — site templates for that site, plus all Central templates)
- **"Build one-off subactivity"** → opens the same item-builder UI as §3's item builder, but with no name/version/scope fields — it's a plain, throwaway ordered list of items for this activity only

### 4.2 Checklist panel on the Activity detail page

Once attached, show a **"Checklist" section** on the activity detail page (or a tab, if the activity page already uses tabs), listing every sub-activity in template order:

Each row:
- Item label
- Small icon indicating item type
- The input control appropriate to its type (from §1's table) — inline, no separate screen needed
- A status pill: **New** (neutral/grey) or **Recorded** (green, with a small lock icon once Recorded)
- Assignee avatar — defaults to the parent activity's assignee(s); clicking it opens a reassign picker (§4.4)
- Edit/Delete icons — **only rendered at all** if: (current user = the sub-activity's creator OR current user is Site Manager/Admin) AND status = New. As soon as status = Recorded, remove these icons entirely for every user, including the creator and Site Manager/Admin — don't grey them out, don't show a locked tooltip explaining why, just don't render them. (A brief, one-time tooltip on hover of the status pill itself — "Locked once recorded" — is fine and helpful; it just shouldn't live on action icons that no longer exist.)

Message-type rows render as the Info/Warning banner from §1 — no status pill, no lock icon, no input control, not part of the list's completion count.

Items are independently interactive — there is no locked ordering; any item can be filled in regardless of whether earlier ones are done. The drag-handle from the template builder does not appear here; order is fixed once instantiated.

### 4.3 Progress indicator and the completion gate

- Above the checklist panel, show a small progress readout: **"3 of 5 recorded"** (Message items excluded from both numbers).
- On the activity's stage control (wherever Repaired/Done is triggered), if any non-Message sub-activity is still New:
  - Block the transition
  - Show an inline validation message, e.g. *"2 checklist items still need to be recorded before this can be marked Done"*
  - Make the message actionable — clicking it scrolls to / highlights the outstanding rows in the checklist panel
- This block has **no override** — don't design an "override" or "force complete" affordance for any role, including Admin.

### 4.4 Reassigning a sub-activity

Clicking a row's assignee avatar opens a small picker (same pattern as reassigning the parent activity, but scoped to this one item). On confirming a new assignee, show a lightweight, low-emphasis notification indicator (e.g. a small badge or toast) — visually distinct from and less prominent than the platform's standard full-assignment notification, since this is a minor, per-item handoff rather than a whole-activity reassignment.

### 4.5 Freestanding sub-activities

On the same checklist panel, Site Manager/Admin get an **"Add item"** action (same item-builder row pattern as §3, minus template linkage) to add a one-off sub-activity that isn't part of any checklist/template. It renders in the same list, same rules for edit/delete/lock apply identically — there's no visual distinction needed between checklist-derived and freestanding rows once they're on the activity, except that a checklist-derived row's tooltip/detail view can note which template it came from.

---

## 5. Maintenance Plan linkage

On the Maintenance Plan create/edit screen, add a **"Checklist Template"** field: a searchable, optional picker (same scope rules as §2). Visible/editable only to Site Manager (their own site's plans) and Admin.

Once set, show the linked template's name and version, with a short helper note: *"Every future-generated activity from this plan will include this checklist."* Editing which template is linked doesn't retroactively touch already-generated activities.

---

## 6. Permissions summary

| Capability | Ops | Engineer | Site Mgr | Portfolio | Central | Admin |
|---|---|---|---|---|---|---|
| Manage site checklist templates | — | — | Own site | — | — | Yes |
| Publish Central (all-site) templates | — | — | — | — | Yes | Yes |
| Add checklist to an activity / link to a plan | — | — | Own site | — | — | Yes |
| Add a freestanding sub-activity | — | — | Own site | — | — | Yes |
| Complete / reassign a sub-activity | Assigned | Assigned | Own site | — | — | Yes |
| Edit/delete a sub-activity while New | Creator only | Creator only | Yes (any) | — | — | Yes (any) |
| Edit/delete a sub-activity once Recorded | Nobody | Nobody | Nobody | Nobody | Nobody | Nobody |
| Force-complete past the gate | Nobody | Nobody | Nobody | Nobody | Nobody | Nobody |

Use this table directly to drive conditional rendering — most rows should be **hidden**, not disabled, when a role lacks the capability, matching the platform's existing convention (see how the baseline hides Close-stage controls from non-Site-Admin roles).

---

## 7. Empty and edge states to design

- **No checklist templates exist yet** (§2) — empty state with CTA.
- **No checklist attached to this activity** — the "Add Checklist" control itself doubles as this empty state; no separate illustration needed.
- **Template picker with no results** — standard "no matches" pattern.
- **Deactivating a template that's linked to an active plan** — confirm dialog: *"This template is linked to [Plan name]. Deactivating won't remove the link, but the plan won't be able to switch back to it later."* (Adjust wording to match whatever confirm-dialog pattern already exists for Tags/Disciplines deactivation.)
- **Attempting to move an activity to Done with items outstanding** — inline validation, §4.3.
- **A Recorded sub-activity row** — locked visual state, no actionable icons, §4.2.