From 778270e0b9f8812cb94b46e29dc532d6b357b844 Mon Sep 17 00:00:00 2001 From: chihlasm Date: Thu, 19 Feb 2026 02:49:33 -0500 Subject: [PATCH] docs: add procedural/maintenance editor redesign design Collapsible sections, fixed-height layout, drag-to-reorder steps, maintenance schedule section, and step list UX improvements. Co-Authored-By: Claude Opus 4.6 --- ...02-19-procedural-editor-redesign-design.md | 232 ++++++++++++++++++ 1 file changed, 232 insertions(+) create mode 100644 docs/plans/2026-02-19-procedural-editor-redesign-design.md diff --git a/docs/plans/2026-02-19-procedural-editor-redesign-design.md b/docs/plans/2026-02-19-procedural-editor-redesign-design.md new file mode 100644 index 00000000..30555b4b --- /dev/null +++ b/docs/plans/2026-02-19-procedural-editor-redesign-design.md @@ -0,0 +1,232 @@ +# Procedural & Maintenance Editor Redesign — Design + +> **Date:** 2026-02-19 +> **Scope:** Restructure the procedural/maintenance flow editor for better space utilization, collapsible sections, drag-to-reorder steps, and maintenance-specific schedule management + +## Overview + +The current procedural editor (`ProceduralEditorPage.tsx`) uses a scrolling document layout where Details, Intake Form, and Steps stack vertically. The Details and Intake Form sections consume significant screen space, pushing the step list — the core editing surface — to the bottom. This redesign converts the page to a fixed-height editor with collapsible sections and drag-to-reorder steps. + +## Problems Solved + +1. **Steps buried at the bottom** — Details and Intake Form sections are "screen space goblins" that push the step list down, especially on smaller screens +2. **No drag reorder** — grip handles are visible but non-functional; reordering requires deleting and re-creating steps +3. **Adding steps is tedious** — new steps append at the bottom but don't auto-expand, requiring an extra click +4. **No overview at a glance** — collapsed sections don't show useful summaries; users expand just to check what's there +5. **Maintenance flows lack inline schedule management** — schedule/targets are only configurable on the detail page, not during initial creation + +## Layout Architecture + +### Current Layout (Scrolling Document) + +``` +┌─────────────────────────────────────┐ +│ Header (back, title, save, publish) │ ← scrolls with page +├─────────────────────────────────────┤ +│ Details Card (~200px) │ ← always expanded +│ Name, Description, Tags, Public │ +├─────────────────────────────────────┤ +│ Intake Form Card (~150-400px) │ ← always expanded +│ Field editors... │ +├─────────────────────────────────────┤ +│ Steps Card (whatever's left) │ ← pushed to bottom +│ Step list... │ +└─────────────────────────────────────┘ + ↕ entire page scrolls +``` + +### New Layout (Fixed-Height Editor) + +``` +┌─────────────────────────────────────┐ +│ Toolbar (sticky) │ ← fixed, never scrolls +├─────────────────────────────────────┤ +│ ▶ Details: "DC Build" · 3 tags · … │ ← collapsed one-liner +│ ▶ Intake Form: 3 fields: Host, … │ ← collapsed one-liner +│ ▶ Schedule: Mon 2:00 AM · 5 targets│ ← maintenance only +├─────────────────────────────────────┤ +│ │ +│ Steps (flex-1, scrolls alone) │ ← gets all remaining height +│ ┌─ 1. Check prerequisites ───────┐│ +│ ├─ 2. Install AD DS role ────────┤│ +│ ├─ 3. Promote to DC ────────────┤│ +│ ├─ 4. Verify replication ───────┤│ +│ └─ + Add Step ───────────────────┘│ +│ │ +└─────────────────────────────────────┘ +``` + +### Key Layout Changes + +- **Page:** `container mx-auto` scrolling → `flex flex-col h-full overflow-hidden` +- **Toolbar:** Scrolls with page → sticky at top (matches troubleshooting editor pattern) +- **Sections:** Always-expanded cards → collapsible one-liners with rich summaries +- **Step list:** Stacked in scroll flow → `flex-1 overflow-y-auto` (independent scrolling) + +## Collapsible Sections + +### Shared Wrapper: `CollapsibleEditorSection` + +A reusable component used by Details, Intake Form, and Maintenance Schedule. + +**Props:** +- `title` — section label ("Details", "Intake Form", "Schedule") +- `icon` — Lucide icon component +- `summary` — rich one-line summary string shown when collapsed +- `defaultExpanded` — whether to start expanded (default: `false`) +- `children` — expanded content +- `onEdit` — optional callback for the Edit button (alternative to expanding) + +**Collapsed state:** Single row with icon, title, summary text, and expand chevron. Entire row is clickable. + +**Expanded state:** Full content slides down with a subtle animation. Collapse chevron rotates. + +### Details Section — Collapsed Summary + +Format: `"Flow Name" · N tags · Public/Private` + +Examples: +- `"Domain Controller Build" · 3 tags · Public` +- `"New Procedure" · No tags · Private` (new flow, default expanded) + +**New flow behavior:** Details section starts **expanded** when creating a new flow (name is required), collapses after the user provides a name and clicks away or expands another section. + +### Intake Form Section — Collapsed Summary + +Format: `N fields: Field1, Field2, Field3` (field names truncated if many) + +Examples: +- `3 fields: Hostname, Domain Name, IP Address` +- `6 fields: Hostname, Domain, IP, DNS, Gateway, …` (truncated with ellipsis) +- `No fields defined` (empty state) + +### Maintenance Schedule Section + +Only renders when `treeType === 'maintenance'`. + +**New flow (no schedule):** Section starts expanded with: +- Cron expression builder (frequency picker: daily/weekly/monthly + time + timezone) +- Target list selector (dropdown of saved target lists, or create new inline) +- These fields write to the store and get saved with the flow + +**Existing flow (has schedule):** Collapsed summary: +- Format: `"Every Monday at 2:00 AM UTC · 5 targets"` +- Expand to modify schedule and targets + +**Existing flow (no schedule yet):** Shows collapsed with summary `"No schedule configured"` + "Set Up" button that expands the section. + +## Step List Improvements + +### Empty State + +When the step list has 0 steps, show a centered empty state instead of a blank area: + +``` + ┌──────────────────────────┐ + │ 📋 │ + │ Add your first step │ + │ │ + │ Steps define the actions │ + │ engineers follow during │ + │ this procedure. │ + │ │ + │ [+ Add Step] [+ Section]│ + └──────────────────────────┘ +``` + +When 1-2 steps exist, the list renders normally — no special treatment needed since the steps themselves fill the space adequately. + +### Step Count + Time in Header + +The Steps section header shows aggregate info: + +- `Steps (4 steps · ~25 min estimated)` — when steps have time estimates +- `Steps (4 steps)` — when no time estimates set +- `Steps (0 steps)` — empty, triggers the empty state below + +### Auto-Expand New Steps + +When `addStep()` is called, the new step is automatically expanded (`setExpandedStepId(newStep.id)`) and the step list scrolls to the bottom to show it. This eliminates the extra click to start editing. + +Same for `addSectionHeader()` — auto-expand for immediate title editing. + +### Drag-to-Reorder + +**Library:** `@dnd-kit/core` + `@dnd-kit/sortable` + +**Behavior:** +- Drag via the `GripVertical` handle on each step card +- Dragged card lifts with `shadow-lg` and slight scale +- Drop target: blue insertion line between steps +- Section headers are draggable — moving a section header moves it independently (steps below stay in place) +- On drop: update the store's step array order and recalculate `display_order` values +- Keyboard accessible: focus grip handle, Enter to pick up, arrow keys to move, Enter to drop + +**Implementation:** +- Wrap step list in `` + `` +- Each step card wrapped in `useSortable()` hook +- Drag overlay shows a simplified card (just step number + title) +- `onDragEnd` handler reorders the `steps` array in the procedural editor store + +### Collapsed Step Cards + +Current cards are already compact. Minor tightening: +- Step number badge + content type icon + title + time estimate + chevron + delete (on hover) +- No changes to the collapsed card layout — it's already well-designed + +## Toolbar + +Matches the troubleshooting editor's toolbar pattern: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ ← Back Edit Procedure — DC Build [Unsaved] │ Save │ Publish │ +└─────────────────────────────────────────────────────────────┘ +``` + +- **Left:** Back button (→ `/my-trees`), flow type icon, title with flow name +- **Right:** Unsaved indicator, Save Draft button, Publish button (gradient) +- **Sticky:** `sticky top-0 z-10` within the editor area (not the app shell) + +Maintenance flows show `Wrench` icon + "Edit Maintenance Flow" title. + +## File Changes + +### Modified Files + +| File | Changes | +|------|---------| +| `ProceduralEditorPage.tsx` | Layout restructure: scrolling → fixed-height, collapsible sections, toolbar refactor | +| `StepList.tsx` | Drag reorder with @dnd-kit, auto-expand on add, empty state, step count header | +| `IntakeFormBuilder.tsx` | Wrap in collapsible section with field-name summary | +| `proceduralEditorStore.ts` | `reorderSteps(fromIndex, toIndex)` action, auto-expand on add | + +### New Files + +| File | Purpose | +|------|---------| +| `components/procedural-editor/CollapsibleEditorSection.tsx` | Shared collapsible wrapper with summary display | +| `components/procedural-editor/MaintenanceScheduleSection.tsx` | Schedule builder + collapsed summary for maintenance flows | + +### New Dependencies + +- `@dnd-kit/core` — drag-and-drop framework +- `@dnd-kit/sortable` — sortable preset for ordered lists +- `@dnd-kit/utilities` — CSS utilities for transforms + +### Unchanged + +- `StepEditor.tsx` — inline step editing form, no changes +- `IntakeFieldEditor.tsx` — field editor, no changes +- `proceduralEditorStore.ts` steps/intakeForm data model — no schema changes +- Backend — no API changes needed +- Troubleshooting tree editor — completely separate, unaffected + +## Not Included (YAGNI) + +- No drag-to-reorder intake form fields (low value, fields rarely reordered) +- No inline cron expression text input (use friendly frequency picker instead) +- No step templates or presets +- No bulk step operations (select multiple, delete, move) +- No step preview/dry-run from the editor +- No undo/redo for the procedural editor (separate effort)