History & Undo/Redo (HistoryPlugin)

createHistoryPlugin provides a complete operation history management system based on a pure snapshot stack. It supports Ctrl+Z / Ctrl+Y shortcuts and advanced time travel to jump directly to any historical step.

Quick Start

import { createHistoryPlugin } from '@yh-ui/flow'

onMounted(() => {
  // 1. Create and install plugin
  const plugin = createHistoryPlugin({
    maxHistory: 100, // Keep up to 100 steps
    enableKeyboard: true, // Bind Ctrl+Z / Ctrl+Y
    onHistoryChange: (canUndo, canRedo, length) => {
      // update UI states like disabled buttons
    }
  })
  flowRef.value?.usePlugin(plugin)

  // 2. Once installed, manually save snapshot on user actions
})

// 3. Call this on drag end, node connect, or delete
const handleDragEnd = () => flowRef.value?.saveSnapshot?.('Drag node')

// 4. Undo / Redo programmatically
const undo = () => flowRef.value?.undo?.()
const redo = () => flowRef.value?.redo?.()

IMPORTANT

saveSnapshot, undo, redo methods are dynamically mounted to flowRef.value only after usePlugin is called. Only call these methods within or after the onMounted hook.

Basic Usage Demo

Save snaphots then Undo/Redo changes

API

HistoryPluginOptions

Prop	Type	Default	Description
enabled	boolean	true	Enable plugin
maxHistory	number	100	Maximum history steps
enableKeyboard	boolean	true	Enable Ctrl+Z/Y global window shortcuts
onHistoryChange	(canUndo, canRedo, length) => void	—	Callback on history change

FlowInstance Extended Methods

Automatically mounted onto flowRef.value after usePlugin is called

Method/Prop	Type	Description
undo()	() => void	Undo to previous step
redo()	() => void	Redo to next step
saveSnapshot(desc?)	(description?: string) => void	Manually save current snapshot
clearHistory()	() => void	Clear all history
jumpToStep(index)	(index: number) => void	Jump to specific step (time travel)
getHistory()	() => FlowHistorySnapshot[]	Get full history stack
canUndo	Ref<boolean>	Whether undo is available (reactive)
canRedo	Ref<boolean>	Whether redo is available (reactive)
historyLength	Ref<number>	Total step count (reactive)

FlowHistorySnapshot

interface FlowHistorySnapshot {
  nodes: Node[]
  edges: Edge[]
  timestamp: number
  description?: string
}

Keyboard Shortcuts

Shortcut	Action
Ctrl + Z / ⌘ + Z	Undo
Ctrl + Y / ⌘ + Y	Redo
Ctrl + Shift + Z / ⌘ + ⇧ + Z	Redo (macOS alternative)

Best Practices

TIP

Manual snapshot saving is recommended over auto-capturing every tiny change. Calling saveSnapshot at key moments ensures meaningful steps for your users:

// ✅ Recommended: Save on drag complete
flowRef.value?.on('node:dragend', () => flowRef.value?.saveSnapshot?.('Drag node'))

// e.g. Call after connection established
// e.g. Call before bulk delete

Next Steps

• Node Grouping
• Data Flow Edge
• Auto Layout