92 lines
7.3 KiB
Markdown
92 lines
7.3 KiB
Markdown
# Mermaid diagrams in editable plans should behave like atomic blocks
|
|
## Summary
|
|
When a planning document renders a Mermaid diagram in editable mode, the rendered diagram should behave like a single diagram block rather than like hidden editable text. Users should be able to select, copy, cut, and delete the diagram as one unit, and ordinary cursor/selection gestures should not silently operate on partial invisible Mermaid source.
|
|
|
|
## Problem
|
|
We recently enabled Mermaid rendering in editable planning documents. This improves readability, but it creates a mismatched editing model:
|
|
|
|
* the user sees an image-like diagram
|
|
* the editor still exposes the underlying Mermaid source text to destructive actions and some selection flows
|
|
|
|
That mismatch is confusing and unsafe. A diagram that looks like an image should not be partially deleted via hidden text offsets.
|
|
|
|
## Goals
|
|
* Make rendered Mermaid diagrams in editable plans feel like atomic block content.
|
|
* Ensure destructive actions act on the entire Mermaid block rather than partial hidden source.
|
|
* Ensure pointer and keyboard selection flows do not place users “inside” invisible Mermaid source text during normal editing.
|
|
* Preserve the authored Mermaid markdown in storage, export, and copy flows.
|
|
* Keep the rendered Mermaid experience visually consistent with the existing notebook/plan block model.
|
|
|
|
## Non-goals
|
|
* Adding a dedicated inline Mermaid source editor for this iteration.
|
|
* Changing the rendering theme, zoom behavior, or clipboard image-byte behavior.
|
|
* Changing the behavior of ordinary non-Mermaid code blocks.
|
|
* Reworking the entire notebook command/block selection model beyond what is needed for rendered Mermaid.
|
|
|
|
## Figma / design references
|
|
Figma: none provided
|
|
|
|
## User experience
|
|
These rules apply to Mermaid diagrams that are visibly rendered inside editable planning documents.
|
|
|
|
### Atomic selection
|
|
* Single-clicking a rendered Mermaid diagram selects the entire diagram block.
|
|
* The selected state must be visually obvious and must read as a block selection, not a text cursor placed inside the diagram.
|
|
* When a Mermaid block is selected, the selection applies to the whole authored Mermaid block, not just to a subset of its source text.
|
|
|
|
### Cursor behavior
|
|
* Ordinary cursor placement should land before or after a rendered Mermaid diagram, not inside the hidden Mermaid source.
|
|
* Keyboard navigation should treat the rendered Mermaid diagram as a boundary in the document flow.
|
|
* Users should not be able to end up with a text cursor at an invisible offset in the middle of the Mermaid source through normal pointer or keyboard interactions.
|
|
* Vertical keyboard traversal must be symmetric around a rendered Mermaid diagram. If the first `Down` press from the visible cursor position immediately above the diagram crosses that block boundary, the first `Up` press from the visible cursor position immediately below the diagram must also cross into the diagram boundary instead of skipping over it.
|
|
|
|
### Delete, backspace, and cut
|
|
* If a rendered Mermaid diagram is selected as a block, `Delete`, `Backspace`, and cut actions remove the entire Mermaid block.
|
|
* “Entire Mermaid block” means the authored fenced Mermaid markdown needed to reconstruct the diagram, not just a substring of the diagram body.
|
|
* Undo and redo should restore and remove the diagram atomically.
|
|
|
|
### Drag and range selection
|
|
* If a drag selection, shift-selection, or other range-based text selection crosses a rendered Mermaid diagram, the resulting selection should include the Mermaid diagram as a whole block.
|
|
* The editor should not create a partially selected hidden Mermaid source range when the visible interaction crosses the diagram.
|
|
* Copying or cutting such a selection should preserve whole-block Mermaid behavior.
|
|
* Horizontal `Shift`-selection must use the same Mermaid boundary semantics as plain left/right cursor movement. If `Right` jumps across a rendered Mermaid block atomically, `Shift+Right` must expand across that same block atomically, and `Shift+Left` must shrink back across it on the next keypress.
|
|
* Vertical `Shift`-selection across a rendered Mermaid diagram must be reversible from both sides of the block. After expanding a selection with `Shift+Up` or `Shift+Down`, pressing the opposite arrow while `Shift` remains held must shrink the selection back across that Mermaid boundary on the very next keypress.
|
|
|
|
### Copy behavior
|
|
* Copying a selected Mermaid block should place the full authored Mermaid fenced block in plain text so that pasting into markdown reconstructs the diagram.
|
|
* When HTML clipboard output is available, the copied content may also include the rendered diagram representation in HTML.
|
|
* Direct image-byte clipboard support remains out of scope.
|
|
|
|
### Storage and export
|
|
* Planning documents must continue to store and export the original Mermaid markdown rather than persisting the rendered image.
|
|
* This feature changes editing semantics, not the saved document format.
|
|
|
|
### Scope
|
|
* This behavior is required for editable planning documents and plan-backed notebook surfaces where Mermaid is rendered.
|
|
* If Mermaid rendering is disabled and the raw code block is shown instead, existing raw markdown editing behavior may remain unchanged.
|
|
|
|
## Success criteria
|
|
* Clicking a rendered Mermaid diagram in an editable plan selects the whole diagram block.
|
|
* Users cannot accidentally delete only part of an invisible Mermaid source block through normal editing flows.
|
|
* `Backspace`, `Delete`, cut, undo, and redo operate on rendered Mermaid diagrams atomically.
|
|
* Copying a selected Mermaid block preserves the authored Mermaid markdown in plain text.
|
|
* Crossing a Mermaid diagram with drag or shift-based selection results in whole-block behavior rather than partial invisible-source behavior.
|
|
* Horizontal left/right movement and horizontal `Shift`-selection use the same atomic Mermaid crossings in both directions, including when reversing an in-progress selection.
|
|
* Vertical movement and vertical `Shift`-selection around a Mermaid block are symmetric and reversible from both the above-diagram and below-diagram cursor positions.
|
|
* The document still round-trips as raw Mermaid markdown when saved or exported.
|
|
|
|
## Validation
|
|
* Add focused editor-model tests for Mermaid block selection, delete/backspace behavior, cut behavior, copy behavior, and undo/redo behavior.
|
|
* Add coverage for range-selection flows that cross a rendered Mermaid block.
|
|
* Add hit-testing or selection tests that verify cursor/selection resolution does not land inside hidden Mermaid source offsets during normal rendered interactions.
|
|
* Add focused keyboard-selection tests that verify `Shift+Left` / `Shift+Right` reuse the same atomic Mermaid crossings as `Left` / `Right`, including reversing an expanded selection from either side of the block.
|
|
* Add focused keyboard-navigation tests that verify `Up`/`Down` and `Shift+Up`/`Shift+Down` behave symmetrically around rendered Mermaid blocks.
|
|
* Manually verify in an editable plan that:
|
|
* clicking selects the whole diagram
|
|
* delete/backspace remove the whole diagram
|
|
* copy produces whole Mermaid markdown
|
|
* drag/range selection does not partially select invisible source
|
|
|
|
## Open questions
|
|
* Do we want a dedicated follow-up affordance for explicitly editing Mermaid source while rendered mode is active, or is block-level delete/reinsert sufficient for now?
|