docs/plans/2026-02-18-canvas-ux-fixes-design.md

@@ -0,0 +1,258 @@
+# Canvas UX Fixes — Design Document
+
+**Date:** 2026-02-18
+**Branch:** `feature/tree-editor-canvas`
+**Status:** Approved, pending implementation
+
+---
+
+## Context
+
+The new TreeCanvas editor (Phase 1–4) was tested and three UX problems were identified:
+
+1. **Scroll**: Expanded card forms have no height limit — long forms are cut off and unreachable
+2. **Busy forms**: Inline hint text (`<p className="text-xs">`) inside NodeForm components creates visual clutter
+3. **Answer stubs**: When building a decision node, users must immediately pick a child node type — there's no way to sketch out answer options first and decide types later
+
+All three fixes apply exclusively to the canvas editor. No session, navigation, backend session-saving, or procedural flow code is affected.
+
+---
+
+## Fix 1: Card Scroll
+
+### Problem
+
+`TreeCanvasNode.tsx` renders the expanded editing area as an unbounded `<div>`. On decision nodes with many options, or on any node when the browser viewport is short, the card overflows off-screen. There is no scrollbar — content is unreachable. Tab cycling doesn't scroll the canvas to bring hidden fields into view.
+
+### Design
+
+Apply `max-h-[70vh] overflow-y-auto` to the expanded editing `<div>` inside `TreeCanvasNode.tsx`.
+
+Make the save/cancel header row sticky (`sticky top-0 z-10 bg-card`) so the action buttons are always visible when the user scrolls the form content.
+
+**Files changed:**
+- `frontend/src/components/tree-editor/TreeCanvasNode.tsx`
+  - Add `max-h-[70vh] overflow-y-auto` to the expanded area `<div>` (currently `border-t border-border px-3 pb-3 pt-3`)
+  - Add `sticky top-0 z-10 bg-card` to the card header `<div>` containing the save/cancel row when in expanded state
+
+**No other files affected.**
+
+---
+
+## Fix 2: Info Tooltips
+
+### Problem
+
+`NodeFormDecision.tsx`, `NodeFormAction.tsx`, and `NodeFormResolution.tsx` each contain `<p className="mb-1 text-xs text-muted-foreground">` hint paragraphs below field labels. These add vertical height and visual noise inside a card that's already compact.
+
+Examples of the current hint text:
+- "Supports markdown: **bold**, *italic*, - lists, 1. numbered lists, \`code\`"
+- "PowerShell or CLI commands to execute"
+- "Step-by-step instructions for resolving the issue"
+
+### Design
+
+Replace each hint `<p>` with a small `ⓘ` icon placed inline next to the field label. The icon shows a tooltip on hover containing the same text.
+
+**Tooltip implementation:**
+
+Use `title=""` on the icon element for a native browser tooltip. No third-party tooltip library needed — keeps the implementation minimal and consistent with the existing codebase pattern (the validation badge already uses `title={nodeErrors.map(...).join('\n')}`).
+
+```tsx
+// Before
+<label className="block text-sm font-medium text-foreground">
+  Description
+</label>
+<p className="mb-1 text-xs text-muted-foreground">
+  Supports markdown: **bold**, *italic*, - lists, 1. numbered lists, `code`
+</p>
+
+// After
+<label className="flex items-center gap-1.5 text-sm font-medium text-foreground">
+  Description
+  <span
+    className="inline-flex items-center justify-center h-3.5 w-3.5 rounded-full border border-muted-foreground/40 text-[9px] text-muted-foreground cursor-help"
+    title="Supports markdown: **bold**, *italic*, - lists, 1. numbered lists, `code`"
+  >
+    i
+  </span>
+</label>
+```
+
+**Files changed:**
+- `frontend/src/components/tree-editor/NodeFormDecision.tsx` — remove help_text hint `<p>`, replace with `ⓘ` on `Help Text` label
+- `frontend/src/components/tree-editor/NodeFormAction.tsx` — remove description markdown hint `<p>` and commands hint `<p>`, add `ⓘ` on those labels
+- `frontend/src/components/tree-editor/NodeFormResolution.tsx` — remove description markdown hint `<p>` and steps hint `<p>`, add `ⓘ` on those labels
+
+---
+
+## Fix 3: Answer Stubs (New `answer` Node Type)
+
+### Problem
+
+Decision nodes require the user to pick child node types at the same time they're creating the decision. This is backwards — you naturally know the answer options before you know what each one should do. The NodePicker in NodeFormDecision forces a concrete type selection (decision / action / solution) or leaves the option disconnected (`next_node_id: null`).
+
+Users want to type answer labels first, see those answers appear as placeholder cards in the canvas, and then click each placeholder to assign a type and fill in details.
+
+### Design
+
+Introduce `'answer'` as a new internal NodeType that represents a typed-but-unresolved branch placeholder. Answer nodes are:
+- Created when a user types an answer label in the decision node form
+- Shown in the canvas as a dashed-border stub card with the answer label
+- Clickable to open a type picker (decision / action / solution) and convert to a real node
+- **Not publishable** — blocked by backend and frontend validation on publish
+
+Answer nodes persist to draft saves so users don't lose their sketch when they navigate away.
+
+### Data Model
+
+**`frontend/src/types/tree.ts`**
+
+```typescript
+// Before
+export type NodeType = 'decision' | 'action' | 'solution'
+
+// After
+export type NodeType = 'decision' | 'action' | 'solution' | 'answer'
+```
+
+`TreeStructure` interface: no new fields needed. Answer nodes use:
+- `id`: auto-generated UUID (same as other nodes)
+- `type`: `'answer'`
+- `title`: the answer label text (e.g. "Server", "Desktop")
+- No other fields required
+
+### NodeFormDecision Redesign
+
+Replace the current options UI (NodePicker per option → picks existing or creates new) with a two-zone layout:
+
+**Zone 1 — Answer Labels**
+A simple list of text inputs, one per answer option. Each input edits `options[i].label`. Add/remove/reorder via `DynamicArrayField` (already available).
+
+No `next_node_id` selection here. When the user saves, for each option that has a label but no `next_node_id`, a new answer-type stub node is created and linked automatically.
+
+```
+Options (answer labels):
+[  Server              ] [×]
+[  Desktop             ] [×]
+[ + Add Answer ]
+```
+
+**Zone 2 — (removed) NodePicker per option**
+The per-option NodePicker is removed entirely. The canvas becomes the way to traverse to a child and set its type.
+
+### TreeCanvas Changes
+
+**Rendering answer nodes:**
+
+When a node has `type === 'answer'`, render an `AnswerStubCard` instead of a full `TreeCanvasNode`. The stub card:
+- Dashed border: `border-2 border-dashed border-border`
+- Colored left accent: none (neutral/muted)
+- Shows the answer label (`node.title`) centered
+- Shows a "+ Choose Type" label below the title
+- On click: opens an inline type picker (3 buttons: Decision / Action / Solution)
+- On type selection: calls `updateNode(node.id, { type: selectedType })` and immediately expands the node for editing
+
+**New component:** `frontend/src/components/tree-editor/AnswerStubCard.tsx`
+
+Props:
+```typescript
+interface AnswerStubCardProps {
+  node: TreeStructure         // type === 'answer'
+  fromOption?: string         // the answer label (same as node.title)
+  onSelectType: (nodeId: string, type: 'decision' | 'action' | 'solution') => void
+}
+```
+
+### Stub Creation Logic (TreeCanvas)
+
+When a decision node is saved (`onSave`), the canvas compares options before/after:
+
+For each option in the saved node:
+- If `option.next_node_id` is null/undefined → create a new answer stub node with `title = option.label` and link `option.next_node_id` to its ID.
+- If `option.next_node_id` already points to a node → leave it.
+
+This creation logic lives in `TreeCanvas.tsx`'s `handleNodeSave()` function, which already handles pending link resolution.
+
+### Backend Validation
+
+**`backend/app/core/tree_validation.py`**
+
+`_validate_node()` currently rejects unknown node types:
+```python
+if node_type not in ('decision', 'action', 'solution'):
+    errors.append(...)
+```
+
+Changes:
+1. Allow `'answer'` type through without structural validation (answer nodes have no required fields beyond `id` and `type`).
+2. Add a publish-time check in `can_publish_tree()` (or in `validate_tree_structure()` before publish): if any node has `type == 'answer'`, reject with a clear message: `"Answer placeholders must be resolved to a node type before publishing."`
+3. The draft save endpoint (`PUT /trees/:id`) does not call `can_publish_tree()`, so draft saves continue to work with answer nodes present.
+
+### Frontend Publish Guard
+
+In `TreeEditorPage.tsx`, before calling the publish API, add a check:
+```typescript
+const hasAnswerNodes = findAllAnswerNodes(tree.tree_structure).length > 0
+if (hasAnswerNodes) {
+  // Show toast or inline error: "Resolve all answer placeholders before publishing."
+  return
+}
+```
+
+`findAllAnswerNodes` is a simple recursive traversal (can be a small utility function in `TreeCanvas.tsx` or a new file `lib/treeUtils.ts`).
+
+### Visual Design (AnswerStubCard)
+
+```
+┌ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐
+  Server
+  [ ? Decision ] [ ⚡ Action ] [ ✓ Solution ]
+└ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┘
+```
+
+- Card: `min-w-[180px] max-w-[280px] rounded-xl border-2 border-dashed border-border bg-card/50`
+- Title: `text-sm font-heading font-medium text-foreground text-center py-2 px-3`
+- Type picker row (default state — not yet clicked): `text-xs text-muted-foreground text-center pb-2 cursor-pointer hover:text-foreground`
+  - Clicking the card reveals three compact buttons for type selection
+- Type picker (expanded): three small buttons side-by-side in the card footer
+
+---
+
+## Files Changed Summary
+
+| File | Change |
+|------|--------|
+| `frontend/src/components/tree-editor/TreeCanvasNode.tsx` | Fix 1: max-h + overflow-y + sticky header |
+| `frontend/src/components/tree-editor/NodeFormDecision.tsx` | Fix 2: ⓘ tooltip on help_text; Fix 3: replace NodePicker with answer label list |
+| `frontend/src/components/tree-editor/NodeFormAction.tsx` | Fix 2: ⓘ tooltips on description + commands fields |
+| `frontend/src/components/tree-editor/NodeFormResolution.tsx` | Fix 2: ⓘ tooltips on description + steps fields |
+| `frontend/src/components/tree-editor/TreeCanvas.tsx` | Fix 3: stub creation in handleNodeSave; AnswerStubCard rendering |
+| `frontend/src/components/tree-editor/AnswerStubCard.tsx` | Fix 3: NEW — dashed stub card with inline type picker |
+| `frontend/src/types/tree.ts` | Fix 3: add `'answer'` to NodeType union |
+| `backend/app/core/tree_validation.py` | Fix 3: allow 'answer' in draft; block on publish |
+| `frontend/src/pages/TreeEditorPage.tsx` | Fix 3: frontend publish guard |
+
+---
+
+## Non-Goals
+
+- No changes to session navigation, procedural flows, or maintenance flows
+- No changes to the Code mode editor
+- No changes to `treeEditorStore.ts` store actions (addNode, updateNode, deleteNode are used as-is)
+- No third-party tooltip library
+- No new backend endpoints
+
+---
+
+## Verification
+
+1. Open a troubleshooting tree in the canvas editor
+2. Click a decision node → card expands, form is scrollable with sticky save/cancel header
+3. Field labels show `ⓘ` icons; hovering reveals the hint text
+4. Type answer labels in the Options section; click ✓ to save
+5. Answer stub cards appear as dashed cards below the decision node
+6. Click a stub card → type picker appears; select "Decision" → card converts and expands for editing
+7. Draft save works with answer nodes present (no backend error)
+8. Attempt to publish with unresolved answer nodes → blocked with a clear error message
+9. `npm run build` passes with no TypeScript errors