resolutionflow/docs/plans/archive/2026-02-19-procedural-editor-redesign-impl-revisions.md

# Procedural Editor Redesign - Implementation Revisions

> **Date:** 2026-02-19
> **Revises:** `docs/plans/2026-02-19-procedural-editor-redesign-impl.md`
> **Related Design Revision:** `docs/plans/2026-02-19-procedural-editor-redesign-design-revisions.md`

## Goal

Revise the implementation plan so it matches actual architecture and APIs, with explicit handling for maintenance schedule persistence, step-list invariants, DnD constraints, and accessibility/test requirements.

## Critical Corrections from Original Impl Plan

1. Do not treat maintenance schedule as part of `tree_structure`.
2. Do not use `display_order` for procedural step reorder.
3. Do not assume `0 steps` state unless store invariant is changed intentionally.
4. Do not list `@dnd-kit/*` as new dependency (already installed).
5. Add explicit save orchestration for unsaved maintenance flows.
6. Add explicit failure handling when tree save succeeds but schedule save fails.

## Phase 0: Scope Lock

### Task 0.1 - Confirm invariants and UX ownership

**Decisions to lock in code before implementation:**
1. `procedure_end` remains fixed, non-draggable, last.
2. Minimum one `procedure_step` remains enforced (recommended).
3. Schedule editing in editor is source-of-truth for create/edit, with detail page as display/secondary entrypoint.

**Files:** none (decision checkpoint)

---

## Phase 1: Layout and Collapsible Sections

### Task 1.1 - Add shared collapsible wrapper

**Files:**
- Create: `frontend/src/components/procedural-editor/CollapsibleEditorSection.tsx`

**Requirements:**
1. Single-row collapsed summary.
2. Keyboard-accessible toggle button.
3. `aria-expanded`, `aria-controls`, and section `id`.
4. Optional `defaultExpanded`.

### Task 1.2 - Convert ProceduralEditorPage to fixed-height editor

**Files:**
- Modify: `frontend/src/pages/ProceduralEditorPage.tsx`

**Changes:**
1. Outer layout becomes `flex h-full flex-col overflow-hidden`.
2. Toolbar becomes sticky.
3. Details and Intake wrapped in `CollapsibleEditorSection`.
4. Steps area becomes `flex-1 min-h-0 overflow-y-auto`.
5. Accordion mode: only one section open at a time (explicit state in page component).

**Summaries:**
1. Details: `"Name" - N tags - Public/Private`.
2. Intake: `N fields: label1, label2...` (truncate).

---

## Phase 2: StepList Behavior and DnD

### Task 2.1 - Align header/empty behavior with current store invariant

**Files:**
- Modify: `frontend/src/components/procedural-editor/StepList.tsx`
- Optional invariant change (if desired): `frontend/src/store/proceduralEditorStore.ts`

**Required behavior (recommended):**
1. Keep minimum one `procedure_step`.
2. Remove/unset any `0 steps` UI paths.
3. Header shows:
- `Steps (N steps - ~M min)` when estimates exist
- `Steps (N steps)` otherwise.

### Task 2.2 - Ensure new step auto-expands + scrolls into view

**Files:**
- Modify: `frontend/src/components/procedural-editor/StepList.tsx`
- Verify existing store behavior in `frontend/src/store/proceduralEditorStore.ts`

**Behavior:**
1. On add step/section, expanded editor opens immediately.
2. Newly inserted row is scrolled into view via stable element refs (prefer scroll target by id over "scroll to bottom").

### Task 2.3 - Implement DnD with current model constraints

**Files:**
- Modify: `frontend/src/components/procedural-editor/StepList.tsx`
- Modify: `frontend/src/store/proceduralEditorStore.ts` (reuse `moveStep`)

**Rules:**
1. Draggable: `procedure_step`, `section_header`.
2. Non-draggable: `procedure_end`.
3. Reorder by array index only.
4. No `display_order` recalculation for steps.
5. Keyboard drag support and visible insertion indicator.

---

## Phase 3: Maintenance Schedule Section (Correct API orchestration)

### Task 3.1 - Add schedule section component

**Files:**
- Create: `frontend/src/components/procedural-editor/MaintenanceScheduleSection.tsx`
- Modify: `frontend/src/pages/ProceduralEditorPage.tsx`

**Behavior:**
1. Render only for `treeType === 'maintenance'`.
2. Capture:
- cron expression
- timezone
- target list id
3. Collapsed summary:
- configured: human-readable cadence + target list status
- unconfigured: `No schedule configured`.

### Task 3.2 - Add schedule draft UI state and save orchestration

**Files:**
- Modify: `frontend/src/store/proceduralEditorStore.ts` (UI draft state only)
- Modify: `frontend/src/pages/ProceduralEditorPage.tsx`
- Use: `frontend/src/api/maintenanceSchedules.ts`

**Save flow:**
1. Save tree first (`create`/`update`).
2. If maintenance and schedule draft present:
- if existing schedule id: `maintenanceSchedulesApi.update`
- else: `maintenanceSchedulesApi.create` with saved tree id.
3. If schedule save fails:
- keep tree save success
- show actionable error toast/banner
- preserve schedule draft as dirty.

### Task 3.3 - Existing flow load

**Files:**
- Modify: `frontend/src/pages/ProceduralEditorPage.tsx`

**Behavior:**
1. On edit maintenance flow, fetch schedule via `getForTree(treeId)`.
2. 404 = no schedule yet (valid state).
3. Hydrate schedule draft state for section UI.

---

## Phase 4: Integration polish and consistency

### Task 4.1 - Clarify MaintenanceFlowDetailPage role

**Files:**
- Modify (if needed): `frontend/src/pages/MaintenanceFlowDetailPage.tsx`

**Decision implementation:**
1. Keep schedule read-only there, with "Edit in Flow Editor" CTA.
2. Avoid split-brain schedule edits in two places unless explicitly desired.

---

## Phase 5: Tests and verification

### Task 5.1 - Automated tests

**Files (new/updated):**
- `frontend/src/components/procedural-editor/StepList.test.tsx`
- `frontend/src/pages/ProceduralEditorPage.test.tsx`
- `frontend/src/store/proceduralEditorStore.test.ts` (if absent, add focused tests)

**Minimum coverage:**
1. Reorder respects `procedure_end` constraints.
2. New steps auto-expand and scroll target call occurs.
3. Accordion open/close state and summaries.
4. Maintenance save orchestration:
- tree create/update then schedule create/update
- schedule failure does not revert tree success.

### Task 5.2 - Manual acceptance checklist

1. Steps list remains primary viewport focus in fixed-height layout.
2. Details/Intake/Schedule sections collapse and summarize correctly.
3. DnD works by mouse and keyboard.
4. End step never drags.
5. New maintenance flow:
- can save draft without schedule
- can save with schedule in one action (tree first, schedule second).
6. Existing maintenance flow loads schedule and saves edits.

### Task 5.3 - Build and lint gates

1. `cd frontend && npm run build`
2. `cd frontend && npm run test`
3. `cd frontend && npm run lint`

---

## File Impact (Revised)

### Create
1. `frontend/src/components/procedural-editor/CollapsibleEditorSection.tsx`
2. `frontend/src/components/procedural-editor/MaintenanceScheduleSection.tsx`

### Modify
1. `frontend/src/pages/ProceduralEditorPage.tsx`
2. `frontend/src/components/procedural-editor/StepList.tsx`
3. `frontend/src/components/procedural-editor/IntakeFormBuilder.tsx`
4. `frontend/src/store/proceduralEditorStore.ts`
5. `frontend/src/pages/MaintenanceFlowDetailPage.tsx` (if ownership adjusted)

### Existing APIs used
1. `frontend/src/api/maintenanceSchedules.ts`
2. target list API module(s) if inline list selection/creation is implemented

---

## Out of Scope (unchanged)

1. Intake field DnD reorder.
2. Procedural undo/redo parity.
3. Step templates/presets.
4. Bulk step operations.
5. Backend schema/model changes for procedural steps.