resolutionflow/docs/plans/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.