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

Steps: 0

📦 Drag me!

⚙️ And me!

💡 Drag nodes → click "Snapshot" → then "Undo"

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