@vanduo-oss/vd3-flowchart 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 All notable changes to `@vanduo-oss/vd3-flowchart` are documented here.
 
+## 1.5.0 — 2026-10-25
+
+### Added
+
+- Opt-in `minScale` and `maxScale` (default `0.35` and `3`) and `minNodeSize`
+  and `maxNodeSize` (default `56` and `420`). Junctions stay fixed-size.
+  Hosts that need a closer and wider view, including Oolaflow, can pass
+  `0.05`–`20` and `6`–`4800`.
+- Viewport scale is stored to four decimal places, so a zoom step still moves
+  near 5%. Other geometry stays at two decimal places.
+- Nodes smaller than their default size scale text, wrapping, radius, stroke,
+  markers, curve arms, orthogonal routes, labels, and inline editors in
+  proportion. Larger nodes do not grow that chrome.
+- A wider camera range uses a 240,000-unit grid with spacing that stays
+  readable at 5% and 2000%. The default range keeps the 12,000-unit grid.
+- `fitNode(nodeId, padding?)` frames one visible node. Unknown and hidden
+  nodes do nothing.
+
+### Compatibility
+
+- No methods were removed. Omitting the new options keeps 1.4.0 camera and
+  node limits.
+- `FLOWCHART_DOCUMENT_VERSION` stays `1.3.0`. Older 1.x documents still load.
+  A 1.5.0 document still loads in 1.4.0, where the old clamps apply.
+- This release does not add nested containers, suggestion overlays, floating
+  panels, or an export API.
+
+## 1.4.0 — 2026-10-03
+
+### Changed
+
+- **Behavior change:** with the new default `keyboardShortcuts: 'mindmap'`,
+  Enter on a selected node adds a sibling; F2, Space, or typing edits the
+  label. While editing, Enter saves (Shift+Enter: new line; textbox nodes keep
+  Enter for a new line). Use `keyboardShortcuts: 'basic'` for the 1.3.0 keys.
+- Arrow keys select the nearest node in that direction instead of cycling
+  through document order.
+- Selected nodes no longer draw side resize dots; sides resize by dragging the
+  edge. Corner handles are squares on a slightly outset frame.
+- Connection handles sit outside each side, appear on hover as well as on
+  selection, and no longer shift on hover (the scale transform used the node
+  origin).
+- **Document format 1.3.0:** nodes may carry `collapsed: true` (written only
+  on collapsed nodes). Every 1.x document through 1.3.0 still loads; packages
+  older than 1.4.0 reject 1.3.0 files as a future version.
+- Double-clicking a connection edits its label instead of entering reconnect
+  mode (a single click already shows the reconnect endpoints).
+- The `select` event payload adds `nodeIds`; `selection` keeps its shape.
+
+### Added
+
+- `keyboardShortcuts` option and Vue prop (`'mindmap' | 'basic'`) with
+  `FLOWCHART_KEYBOARD_SHORTCUTS`. Mind-map keys: Tab adds a child, Enter /
+  Shift+Enter add a sibling below / above, Tab while editing saves and adds a
+  child. All modes: Alt+Arrow nudge (Shift for 1 px), Cmd/Ctrl+D duplicate,
+  Cmd/Ctrl + `=` / `-` / `0` zoom, Shift+1 fit, staged Esc, and a `?` overlay
+  (also on the toolbar). Shift+Tab is never captured.
+- Clicking a connection handle adds a connected node in that direction and
+  opens it for editing; dragging still connects.
+- `insertBranchNode()`, `insertSiblingNode()`, `navigateSelection()`,
+  `nudgeNode()`, `duplicateSelection()`, `zoomTo()`, `revealNode()`, and
+  `toggleShortcutsHelp()`; `startTextEdit()` accepts `{ initialText }`.
+- Dashed selection frame for circle, diamond, and label nodes.
+- Multi-select: Shift+click toggles, Shift+drag on empty canvas draws a
+  marquee, Cmd/Ctrl+A selects all. Groups drag, nudge, copy, cut, paste,
+  duplicate (with internal connections), and delete as one undo step each.
+  `selectNodes()`, `toggleNodeSelection()`, `getSelectedNodeIds()`,
+  `isNodeSelected()`, `nudgeNodes()`.
+- Collapsible branches with a "+N" badge, a "−" toggle on a selected parent,
+  and Cmd/Ctrl+/; hidden nodes are skipped by navigation, fit, minimap,
+  guides, connection targets, and selection. `setCollapsed()`,
+  `toggleCollapsed()`, `getVisibleNodes()`, `isNodeHidden()`.
+- Connection labels from the keyboard: Shift+Arrow selects a node's connection
+  on that side (repeat to cycle); Enter, F2, or typing edits inline; arrows
+  move to the end nodes. `startEdgeLabelEdit()`, `selectSideEdge()`.
+- Alignment guides while dragging, with Alt to bypass; `snapGuides` option.
+- Minimap with click/drag panning, a toolbar toggle, and the `minimap` option;
+  it hides on canvases narrower than 480px. `setMinimapEnabled()`,
+  `centerViewOn()`.
+- `autoLayout` option: re-run the current tree or radial layout after
+  keyboard or handle insertions, in the same undo step.
+
+### Fixed
+
+- A node and its edge from `addChildNode()`, a handle click, or the keyboard
+  undo in one step; naming a just-inserted node joins that step. New branch
+  edges copy the sibling's or parent's edge style.
+- Deleting a node from the keyboard selects its parent.
+- The palette "Shapes" title no longer wraps mid-word in narrow columns.
+- Inserted sibling connections keep sibling order for tree and radial layouts.
+- The label editor no longer re-selects text that the user has already
+  started typing.
+
 ## 1.3.0 — 2026-09-17
 
 ### Added

package/README.md

@@ -6,8 +6,8 @@ Vanduo **flowchart** for Vue 3: a node/edge editor with undo/redo, layout
 modes, and a framework-agnostic core. Extracted 1-to-1 from
 `@vanduo-oss/vd3-cbun` flowchart **1.2.0**.
 
-**Status: 1.3.0.** `VD_FLOWCHART_VERSION` tracks the package release.
-`FLOWCHART_DOCUMENT_VERSION` (currently `1.2.0`) is the value `toJSON()`
+**Status: 1.5.0.** `VD_FLOWCHART_VERSION` tracks the package release.
+`FLOWCHART_DOCUMENT_VERSION` (currently `1.3.0`) is the value `toJSON()`
 writes. Do not reset either independently without a compatibility plan.
 
 ## Install
@@ -40,7 +40,8 @@ Named exports only — no default export. `VdFlowchart` is the Vue wrapper; the
 editor class is re-exported as `VdFlowchartCore` (same class name upstream).
 `computeLayout`, `LAYOUT_MODES`, and the `FLOWCHART_*` tables
 (`FLOWCHART_NODE_TYPES`, `FLOWCHART_PORTS`, `FLOWCHART_EDGE_MARKERS`,
-`FLOWCHART_EDGE_ROUTES`) ship alongside. The core does not import Vue.
+`FLOWCHART_EDGE_ROUTES`, `FLOWCHART_KEYBOARD_SHORTCUTS`) ship alongside. The
+core does not import Vue.
 
 `vue` is never bundled — it stays external in both the esm and cjs outputs.
 The build emits `dist/meta.json` and **fails** if any input leaves `src/` or
@@ -49,15 +50,79 @@ if anything but `vue` is externalized. The package declares
 
 ## Version policy
 
-`package.json` version **is** `VD_FLOWCHART_VERSION` (`1.3.0`). Bump those
+`package.json` version **is** `VD_FLOWCHART_VERSION` (`1.5.0`). Bump those
 together for a package release. Keep `FLOWCHART_DOCUMENT_VERSION` unchanged
 unless the serialized schema changes; add fixtures and explicit compatibility
-rules for a format change. Unversioned 1.x documents through 1.2.0 still load.
+rules for a format change. Unversioned 1.x documents through 1.3.0 still load;
+1.3.0 added the optional node field `collapsed: true`, written only on
+collapsed nodes.
 Malformed JSON and unsupported future versions throw before the active
 document, selection, or history change. This continues the old-line
 `@vanduo-oss/flowchart` lineage (never reset to `1.0.0`). Do not reuse the
 retired npm name `@vanduo-oss/flowchart`.
 
+## Editing and keyboard
+
+Hover or select a node to show a connection handle outside each side. Drag a
+handle to connect; click it to add a connected node in that direction. Resize
+from the corner squares or by dragging a side. Dragged nodes snap to other
+nodes' edges and centres (hold Alt to bypass; `snapGuides: false` turns it
+off). Shift+click or Shift+drag on empty canvas selects several nodes, which
+then move, nudge, copy, duplicate, and delete together. A collapsed branch
+shows a "+N" badge; click it or press Cmd/Ctrl+/ to toggle. The minimap in
+the canvas corner pans the view (`minimap: false` or the toolbar toggle hides
+it). Double-click a connection to edit its label. Set `autoLayout: true` to
+re-run the current tree or radial layout after each keyboard or handle
+insertion.
+
+With the canvas focused, the default `keyboardShortcuts: 'mindmap'` mode
+follows mind-map tools such as XMind and MindNode:
+
+| Keys | Action |
+| --- | --- |
+| Arrow keys | Select the nearest node in that direction |
+| Shift+Arrow | Select a connection on that side (repeat to cycle) |
+| Enter, F2, or typing on a connection | Edit its label |
+| Cmd/Ctrl+A | Select all nodes |
+| Cmd/Ctrl+/ | Collapse or expand the branch |
+| Tab | Add a child node and edit it |
+| Enter / Shift+Enter | Add a sibling below / above and edit it |
+| F2, Space, or typing | Edit the label |
+| Enter / Tab while editing | Save / save and add a child (Shift+Enter: new line) |
+| Alt+Arrow (Shift for 1 px) | Nudge the node by one grid step |
+| Cmd/Ctrl+D | Duplicate the node |
+| Cmd/Ctrl + `=` / `-` / `0`, Shift+1 | Zoom in, out, 100%, fit |
+| Esc | Cancel editing, then the tool, then deselect |
+| Shift+Tab, or Esc then Tab | Leave the canvas |
+| `?` | Show all shortcuts |
+
+`keyboardShortcuts: 'basic'` keeps Tab for focus movement; Enter or F2 edits and
+Ctrl/Cmd+Enter saves. A node plus its edge is one undo step, and naming a
+just-inserted node joins that step.
+
+## Camera and node bounds
+
+`minScale` / `maxScale` default to `0.35` / `3`, and `minNodeSize` /
+`maxNodeSize` default to `56` / `420`. Pass a finite pair to widen either
+range; an invalid pair falls back to those defaults. Junctions stay 28×28.
+`fitNode(id, padding)` frames one visible node. Padding is screen pixels.
+Scale is stored to four decimal places. Nodes smaller than their default size
+scale their text, markers, and routes down with them. The default grid stays
+12,000 units; a wider camera uses a 240,000-unit grid.
+
+```js
+new VdFlowchartCore({
+  element: '#editor',
+  minScale: 0.05,
+  maxScale: 20,
+  minNodeSize: 6,
+  maxNodeSize: 4800,
+});
+```
+
+The same four names are Vue props. The document format is unchanged: scale and
+size remain plain numbers.
+
 ## Theming
 
 Flowchart chrome renders against Vanduo `--vd-*` design tokens — the same
@@ -127,9 +192,11 @@ pnpm test:e2e      # Playwright Chromium (needs dist/)
 `pnpm build` first**. Chromium must be installed once:
 `pnpm exec playwright install chromium`.
 
-The published package declares a consumer-friendly `engines.node >=20.19.0`;
-the dev/CI toolchain pins Node 24 via `packageManager` +
-`.github/workflows/ci.yml`.
+Node 24 LTS is the supported development and CI runtime; run `nvm use` to select
+it for this repository from `.nvmrc`. The existing `engines.node >=20.19.0`
+range remains a temporary consumer compatibility floor, tested on a best-effort
+basis until the next major release; it is not the recommended development
+runtime.
 
 ## Documentation
 

package/SKILL.md

@@ -27,12 +27,41 @@ future versions and malformed JSON are rejected before changing current work.
 `FLOWCHART_DOCUMENT_VERSION` describes saved JSON; `VD_FLOWCHART_VERSION`
 describes the package release. Do not replace document versions with app versions.
 
+## Keyboard
+
+`keyboardShortcuts` defaults to `'mindmap'`: with a node selected on the focused
+canvas, Tab adds a child, Enter adds a sibling (Shift+Enter above), and F2, Space,
+or typing edits the label. While editing, Enter saves and Tab saves and adds a
+child. Arrows select the nearest node in that direction; Alt+Arrow nudges.
+Shift+Tab, or Esc then Tab, leaves the canvas. `?` lists every shortcut. Use
+`'basic'` when Tab must always move focus; Enter then edits and Ctrl/Cmd+Enter
+saves. A node plus its edge, and naming a just-inserted node, undo in one step.
+Shift+Arrow selects a connection on that side; Enter, F2, or typing edits its
+label. Shift+click, Shift+drag, and Cmd/Ctrl+A select several nodes (the
+`select` event lists them in `nodeIds`). Cmd/Ctrl+/ collapses a branch.
+
+## Canvas options
+
+`snapGuides` (default true) snaps drags to alignment guides; `minimap`
+(default true) shows the overview; `autoLayout` (default false) re-runs the
+current tree or radial layout after insertions. Saved JSON uses document
+format 1.3.0, which adds `collapsed: true` on collapsed nodes only.
+
+## Deep zoom
+
+`minScale` and `maxScale` default to `0.35` and `3`. `minNodeSize` and
+`maxNodeSize` default to `56` and `420`. Pass both ends of a pair to opt into
+a wider camera or smaller and larger nodes. Junctions stay fixed-size.
+`getInstance().fitNode(id, padding)` frames one visible node. A node smaller
+than its default size scales its text, markers, and connectors with it. Saved
+JSON stays document format 1.3.0.
+
 ## Verification
 
 Add a node, toggle read-only, and confirm the edit remains. Undo/redo, save/reload,
-and echo a change back through `data`. With only the keyboard, select nodes using
-canvas arrows, edit with Enter, save with Ctrl/Cmd+Enter, and use Graph outline
-to read relationships and connect nodes. Check the consumer's screen reader.
+and echo a change back through `data`. With only the keyboard, build a small map
+with Tab, typing, and Enter, move with arrows, and use Graph outline to read
+relationships and connect nodes. Check the consumer's screen reader.
 
 Use [Vue declarations](dist/vue.d.ts) for component props/events/exposed methods
 and [core declarations](dist/core.d.ts) for document types and editor methods.

package/dist/core.d.ts

@@ -11,6 +11,11 @@ export type FlowchartEdgeRoute = 'curve' | 'straight' | 'orthogonal';
 export type FlowchartEdgeKind = 'line' | 'arrow';
 export type FlowchartDirection = 'right' | 'left' | 'up' | 'down';
 export type LayoutMode = 'tree' | 'radial' | 'grid';
+/**
+ * `'mindmap'` (default): Tab adds a child, Enter adds a sibling, F2/Space or
+ * typing edits. `'basic'`: Enter edits and Tab moves focus as usual.
+ */
+export type FlowchartKeyboardShortcuts = 'mindmap' | 'basic';
 
 export interface FlowchartViewport {
   x: number;
@@ -27,6 +32,8 @@ export interface FlowchartNode {
   height: number;
   text: string;
   data: Record<string, unknown>;
+  /** Present (and true) only on collapsed nodes; document format 1.3.0. */
+  collapsed?: true;
 }
 
 export interface FlowchartEndpoint {
@@ -79,6 +86,7 @@ export interface FlowchartNodeInput {
   height?: number;
   text?: string;
   data?: Record<string, unknown>;
+  collapsed?: boolean;
   /** Place relative to another node instead of at the viewport center. */
   relativeTo?: string | FlowchartRelativeTo;
 }
@@ -111,6 +119,27 @@ export interface AddChildNodeOptions extends FlowchartNodeInput {
   edge?: FlowchartEdgeInput;
 }
 
+export interface InsertBranchNodeOptions {
+  /** Side of the parent to grow on; defaults to the branch's growth direction. */
+  direction?: FlowchartDirection;
+  /** Sibling to stack next to; defaults to the last sibling on that side. */
+  anchorId?: string;
+  /** Place before `anchorId` instead of after it. */
+  before?: boolean;
+  /** Open the label editor on the new node. */
+  edit?: boolean;
+}
+
+export interface InsertSiblingNodeOptions {
+  before?: boolean;
+  edit?: boolean;
+}
+
+export interface StartTextEditOptions {
+  /** Replace the label with this text and place the caret at the end. */
+  initialText?: string;
+}
+
 export interface LayoutOptions {
   /** Force a specific root node id; defaults to nodes with no incoming edges. */
   root?: string;
@@ -156,7 +185,10 @@ export interface FlowchartChangeEvent {
 }
 
 export interface FlowchartSelectEvent {
+  /** Primary item; keeps its single-item shape when several nodes are selected. */
   selection: FlowchartSelection | null;
+  /** Every selected node id, the primary node included. */
+  nodeIds: string[];
 }
 
 export interface FlowchartViewportEvent {
@@ -197,6 +229,22 @@ export interface VdFlowchartOptions {
   history?: boolean;
   /** Maximum retained history entries (default 100). */
   historyLimit?: number;
+  /** Keyboard model on the focused canvas (default `'mindmap'`). */
+  keyboardShortcuts?: FlowchartKeyboardShortcuts;
+  /** Snap dragged nodes to other nodes' edges and centres; Alt bypasses (default true). */
+  snapGuides?: boolean;
+  /** Show the overview minimap; it hides on canvases narrower than 480px (default true). */
+  minimap?: boolean;
+  /** Re-run the current tree or radial layout after insertions, in the same undo step (default false). */
+  autoLayout?: boolean;
+  /** Lowest camera scale. Default `0.35`. Pair with `maxScale`. */
+  minScale?: number;
+  /** Highest camera scale. Default `3`. Pair with `minScale`. */
+  maxScale?: number;
+  /** Smallest resizable-node side. Default `56`. Junctions stay fixed. Pair with `maxNodeSize`. */
+  minNodeSize?: number;
+  /** Largest resizable-node side. Default `420`. Pair with `minNodeSize`. */
+  maxNodeSize?: number;
 }
 
 export class VdFlowchart {
@@ -211,6 +259,11 @@ export class VdFlowchart {
   selectNode(nodeId: string): this;
   selectEdge(edgeId: string): this;
   deselect(): this;
+  /** Select several nodes; `primary` (default: the last id) drives single-node UI. */
+  selectNodes(nodeIds: string[], options?: { primary?: string }): this;
+  toggleNodeSelection(nodeId: string): this;
+  getSelectedNodeIds(): string[];
+  isNodeSelected(nodeId: string): boolean;
 
   // Events
   on<K extends keyof FlowchartEventMap>(
@@ -228,6 +281,27 @@ export class VdFlowchart {
     parentId: string,
     options?: AddChildNodeOptions,
   ): { node: FlowchartNode; edge: FlowchartEdge | null } | null;
+  /** Add a connected node on a side of the parent; node and edge undo as one step. */
+  insertBranchNode(
+    parentId: string,
+    options?: InsertBranchNodeOptions,
+  ): { node: FlowchartNode; edge: FlowchartEdge | null } | null;
+  /** Add a sibling next to a node (a child when the node has no parent). */
+  insertSiblingNode(
+    nodeId: string,
+    options?: InsertSiblingNodeOptions,
+  ): { node: FlowchartNode; edge: FlowchartEdge | null } | null;
+  duplicateSelection(): FlowchartNode | FlowchartNode[] | null;
+  /** Collapse or expand a node's branch; undoable, reason `node:collapse`. */
+  setCollapsed(nodeId: string, collapsed: boolean): boolean;
+  toggleCollapsed(nodeId: string): boolean;
+  /** Nodes not hidden inside a collapsed branch. */
+  getVisibleNodes(): FlowchartNode[];
+  isNodeHidden(nodeId: string): boolean;
+  nudgeNode(nodeId: string, direction: FlowchartDirection, distance: number): FlowchartNode | null;
+  nudgeNodes(nodeIds: string[], direction: FlowchartDirection, distance: number): FlowchartNode[];
+  /** Select the nearest node in a direction (spatial keyboard navigation). */
+  navigateSelection(direction: FlowchartDirection): boolean;
   updateNode(
     nodeId: string,
     patch?: Partial<FlowchartNodeInput>,
@@ -260,6 +334,18 @@ export class VdFlowchart {
   zoomOut(): this;
   resetView(): this;
   fitView(): this;
+  /** Zoom around the view centre to an absolute scale (clamped). */
+  zoomTo(scale: number): this;
+  /** Pan just enough to bring a node into view. */
+  revealNode(nodeId: string): void;
+  /** Centre and frame one visible node. Padding is screen pixels. */
+  fitNode(nodeId: string, padding?: number): this;
+  /** Show or hide the minimap. */
+  setMinimapEnabled(enabled: boolean): this;
+  /** Pan so a world point is at the centre of the view. */
+  centerViewOn(worldX: number, worldY: number): this;
+  /** Open, close, or toggle the keyboard shortcuts overlay. */
+  toggleShortcutsHelp(force?: boolean): this;
 
   // Document
   clear(): this;
@@ -267,7 +353,11 @@ export class VdFlowchart {
   toJSON(): FlowchartDocument;
 
   // Text editing
-  startTextEdit(nodeId: string): boolean;
+  startTextEdit(nodeId: string, options?: StartTextEditOptions): boolean;
+  /** Open the inline label editor on a connection. */
+  startEdgeLabelEdit(edgeId: string, options?: StartTextEditOptions): boolean;
+  /** Select a connection on one side of a node; repeated calls cycle. */
+  selectSideEdge(nodeId: string, direction: FlowchartDirection): boolean;
   stopTextEdit(options?: { commit?: boolean }): void;
 
   // Lifecycle
@@ -275,7 +365,19 @@ export class VdFlowchart {
   updateOptions(
     options: Pick<
       VdFlowchartOptions,
-      'readonly' | 'gridSize' | 'autoFit' | 'history' | 'historyLimit'
+      | 'readonly'
+      | 'gridSize'
+      | 'autoFit'
+      | 'history'
+      | 'historyLimit'
+      | 'keyboardShortcuts'
+      | 'snapGuides'
+      | 'minimap'
+      | 'autoLayout'
+      | 'minScale'
+      | 'maxScale'
+      | 'minNodeSize'
+      | 'maxNodeSize'
     >,
   ): this;
   destroy(): void;
@@ -297,3 +399,4 @@ export const FLOWCHART_NODE_TYPES: readonly FlowchartNodeType[];
 export const FLOWCHART_PORTS: readonly FlowchartPort[];
 export const FLOWCHART_EDGE_MARKERS: readonly FlowchartEdgeMarker[];
 export const FLOWCHART_EDGE_ROUTES: readonly FlowchartEdgeRoute[];
+export const FLOWCHART_KEYBOARD_SHORTCUTS: readonly FlowchartKeyboardShortcuts[];