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

# Procedural & Maintenance Editor Redesign - Design Revisions

> **Date:** 2026-02-19
> **Revises:** `docs/plans/2026-02-19-procedural-editor-redesign-design.md`
> **Purpose:** Resolve implementation gaps and make the design decision-complete for engineering handoff

## Summary

This revision tightens the original design to match current architecture and APIs.
It resolves contradictions around maintenance schedule persistence, aligns step-list behavior with store invariants, and defines concrete DnD/accessibility/test expectations.

## Revision Decisions (Locked)

1. Keep fixed-height editor layout with independent StepList scrolling.
2. Use collapsible sections for Details, Intake Form, and Maintenance Schedule.
3. Use existing installed `@dnd-kit/*` packages (no new dependency work).
4. Keep `procedure_end` as non-draggable and always last.
5. Keep schedule as optional for maintenance flows (manual batch launch remains valid).

## Critical Corrections to Original Design

1. **Maintenance schedule persistence**
- Schedule is not embedded in `tree_structure`.
- Schedule must be persisted through maintenance schedule endpoints.
- New unsaved flow requires two-stage save:
  1. Save tree (`treesApi.create` / `treesApi.update`)
  2. Create/update schedule (`maintenanceSchedulesApi.create` or `maintenanceSchedulesApi.update`)
- One schedule per tree (`uq_maintenance_schedules_tree_id`).

2. **Step empty-state semantics**
- Original "0 steps" state conflicts with current store minimum step behavior.
- Revised behavior:
  - If minimum-one-step invariant remains, remove "0 steps" UX language.
  - Empty-state is only shown if invariant is intentionally changed in store.

3. **DnD data model correction**
- Do not mention recalculating `display_order` for procedural steps.
- Reorder is array-index based only.
- Explicitly block dragging `procedure_end`.

4. **Dependencies section correction**
- Replace "New Dependencies" with "Existing Dependencies Used" for `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`.

5. **File impact correction**
- Add API integration surfaces:
  - `frontend/src/api/maintenanceSchedules.ts`
  - target-list integration file(s) if inline list creation is in scope
- Clarify interaction with `frontend/src/pages/MaintenanceFlowDetailPage.tsx` (retain schedule view/edit there or shift entirely to editor).

6. **Collapsible behavior clarification**
- Use single-open accordion mode by default.
- Details defaults expanded for new flows.
- Intake defaults collapsed.
- Maintenance Schedule defaults:
  - new maintenance flow: expanded
  - existing with schedule: collapsed summary
  - existing without schedule: collapsed with "Set Up" affordance

7. **A11y + keyboard DnD acceptance**
- Include keyboard reorder acceptance criteria.
- Include focus order and ARIA labeling criteria for section toggles and drag handles.

## Revised Maintenance Schedule Section Spec

### New maintenance flow (tree not yet saved)

1. Render schedule editor expanded.
2. Keep schedule input in local UI draft state.
3. On Save Draft / Publish:
- Save tree first.
- If tree save succeeds, create schedule with resulting `tree_id`.
4. If schedule create fails:
- Tree save remains successful.
- Show actionable error ("Schedule not saved. Retry.").
- Preserve schedule draft state.

### Existing maintenance flow

1. Load schedule via `maintenanceSchedulesApi.getForTree(treeId)`.
2. Edit and persist via `maintenanceSchedulesApi.update(scheduleId, data)`.
3. If no schedule exists, show collapsed "No schedule configured" summary + setup button.

## Revised StepList Reorder Spec

1. Draggable types:
- `procedure_step`
- `section_header`
2. Non-draggable:
- `procedure_end`
3. Reorder behavior:
- Move item by array index.
- Preserve all step payload fields.
- No implicit grouped movement under section headers.
4. Keyboard behavior:
- Drag handle focusable.
- Enter/Space pick up + drop.
- Arrow keys move while grabbed.
- Escape cancels.

## Acceptance Criteria

1. **Layout**
- Toolbar remains visible while StepList scrolls.
- Details/Intake/Schedule sections collapse without shrinking StepList usability.

2. **Steps**
- New step auto-expands.
- New step scrolls into view.
- Reorder works by pointer and keyboard.
- `procedure_end` remains last and fixed.

3. **Maintenance schedule**
- New unsaved maintenance flow can be saved without schedule.
- Schedule can be created immediately after first tree save.
- Existing schedule loads and updates in editor.
- Schedule failure does not roll back successful tree save.

4. **Accessibility**
- Section toggles keyboard operable.
- Drag handles have accessible labels.
- Focus remains stable after reorder.

5. **Build/Test**
- `npm run build` succeeds.
- Affected component/store tests pass.

## Updated File Impact

### Modified

- `frontend/src/pages/ProceduralEditorPage.tsx`
- `frontend/src/components/procedural-editor/StepList.tsx`
- `frontend/src/components/procedural-editor/IntakeFormBuilder.tsx`
- `frontend/src/store/proceduralEditorStore.ts`
- `frontend/src/api/maintenanceSchedules.ts`
- `frontend/src/pages/MaintenanceFlowDetailPage.tsx` (if schedule UX ownership changes)

### New

- `frontend/src/components/procedural-editor/CollapsibleEditorSection.tsx`
- `frontend/src/components/procedural-editor/MaintenanceScheduleSection.tsx`

### Existing dependencies used

- `@dnd-kit/core`
- `@dnd-kit/sortable`
- `@dnd-kit/utilities`

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