@lupinum/board-history 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Lupinum OG and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+<p align="center"><img src="https://raw.githubusercontent.com/lupinum-dev/nuxt-board/main/docs/public/app-icon.svg" width="128" alt="Nuxt Board icon"></p>
+
+<h1 align="center">@lupinum/board-history</h1>
+
+<p align="center">Add deterministic undo and redo to the Nuxt Board engine.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@lupinum/board-history"><img src="https://img.shields.io/npm/v/@lupinum/board-history?label=npm" alt="npm version"></a>
+  <a href="https://github.com/lupinum-dev/nuxt-board/actions/workflows/ci.yml"><img src="https://github.com/lupinum-dev/nuxt-board/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/lupinum-dev/nuxt-board/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+> [!WARNING]
+> This package has not reached a stable release. Review the changelog before each upgrade.
+
+## Purpose
+
+Use this plugin when users must reverse committed board changes. One completed drag, resize, text edit, or outer batch creates one history frame.
+
+## Requirements
+
+Install the same version of this package and `@lupinum/board-core`. The fixed-version release keeps the plugin ABI aligned with the engine.
+
+## Installation
+
+```bash
+pnpm add @lupinum/board-history @lupinum/board-core
+```
+
+## Quick start
+
+```ts
+import { createBoardEngine } from '@lupinum/board-core'
+import { historyPlugin } from '@lupinum/board-history'
+
+const engine = createBoardEngine({
+  plugins: [historyPlugin({ maxSteps: 200 })],
+})
+
+engine.plugins.history.undo()
+engine.plugins.history.redo()
+```
+
+## Exports
+
+The package exports the history plugin and its typed history controls.
+
+## Documentation
+
+Read the [history reference](https://nuxt-board.lupinum.com/docs/reference/history).
+
+## Support and security
+
+Open a [GitHub issue](https://github.com/lupinum-dev/nuxt-board/issues) for support. Report vulnerabilities through the [private security process](https://github.com/lupinum-dev/nuxt-board/security/policy).
+
+## License
+
+This package uses the [MIT License](https://github.com/lupinum-dev/nuxt-board/blob/main/LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import type { BoardEventMap, BoardPlugin, BoardPluginApis } from '@lupinum/board-core';
+/** Public history state exposed by the history plugin API. */
+export interface HistoryState {
+    undoDepth: number;
+    redoDepth: number;
+    current: string | null;
+}
+/** Public metadata for a single undoable history frame. */
+export interface HistoryEntry {
+    label: string;
+    timestamp: number;
+}
+/** Options for bounding retained structural history roots. */
+export interface HistoryPluginOptions {
+    maxSteps?: number;
+}
+export interface HistoryApi {
+    undo: () => void;
+    redo: () => void;
+    canUndo: () => boolean;
+    canRedo: () => boolean;
+    clear: () => void;
+    getState: () => HistoryState;
+}
+export interface HistoryEventMap extends BoardEventMap {
+    'history:push': (entry: HistoryEntry) => void;
+    'history:undo': (entry: HistoryEntry | null) => void;
+    'history:redo': (entry: HistoryEntry | null) => void;
+    'history:clear': () => void;
+}
+interface HistoryPluginApis extends BoardPluginApis {
+    history: HistoryApi;
+}
+/** Install deterministic undo/redo backed by committed structural roots. */
+export declare function historyPlugin(options?: HistoryPluginOptions): BoardPlugin<HistoryPluginApis, HistoryEventMap>;
+export {};

package/dist/index.js

@@ -0,0 +1,83 @@
+// src/index.ts
+import {
+  defineInternalBoardPlugin
+} from "@lupinum/board-core/internal";
+function toHistoryEntry(frame) {
+  return { label: frame.label, timestamp: frame.timestamp };
+}
+function historyPlugin(options = {}) {
+  const maxSteps = Math.max(1, options.maxSteps ?? 200);
+  return defineInternalBoardPlugin({
+    name: "history",
+    install(engine) {
+      const undoStack = [];
+      const redoStack = [];
+      const offCommit = engine.projectCommit((commit) => {
+        if (commit.metadata.history === "ignore") return () => void 0;
+        const frame = Object.freeze({
+          label: commit.label,
+          timestamp: commit.timestamp,
+          before: commit.before,
+          after: commit.after
+        });
+        return () => {
+          undoStack.push(frame);
+          if (undoStack.length > maxSteps) undoStack.shift();
+          redoStack.length = 0;
+          engine.emit("history:push", toHistoryEntry(frame));
+        };
+      });
+      const api = {
+        undo() {
+          engine.assertActive();
+          const frame = undoStack.pop() ?? null;
+          if (!frame) {
+            engine.emit("history:undo", null);
+            return;
+          }
+          engine.restoreHistoryRoot(frame.before);
+          redoStack.push(frame);
+          engine.emit("history:undo", toHistoryEntry(frame));
+        },
+        redo() {
+          engine.assertActive();
+          const frame = redoStack.pop() ?? null;
+          if (!frame) {
+            engine.emit("history:redo", null);
+            return;
+          }
+          engine.restoreHistoryRoot(frame.after);
+          undoStack.push(frame);
+          engine.emit("history:redo", toHistoryEntry(frame));
+        },
+        canUndo: () => {
+          engine.assertActive();
+          return undoStack.length > 0;
+        },
+        canRedo: () => {
+          engine.assertActive();
+          return redoStack.length > 0;
+        },
+        clear() {
+          engine.assertActive();
+          undoStack.length = 0;
+          redoStack.length = 0;
+          engine.emit("history:clear");
+        },
+        getState: () => {
+          engine.assertActive();
+          return {
+            undoDepth: undoStack.length,
+            redoDepth: redoStack.length,
+            current: undoStack[undoStack.length - 1]?.label ?? null
+          };
+        }
+      };
+      engine.extend("history", api);
+      return offCommit;
+    }
+  });
+}
+export {
+  historyPlugin
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@lupinum/board-history",
+  "version": "0.1.0",
+  "description": "Undo and redo plugin for @lupinum/board-core.",
+  "license": "MIT",
+  "author": "Lupinum OG <info@lupinum.com> (https://lupinum.com)",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lupinum-dev/nuxt-board.git",
+    "directory": "packages/board-history"
+  },
+  "homepage": "https://nuxt-board.lupinum.com",
+  "bugs": {
+    "url": "https://github.com/lupinum-dev/nuxt-board/issues"
+  },
+  "keywords": [
+    "board",
+    "history",
+    "undo",
+    "redo"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@lupinum/board-core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean && tsc -p tsconfig.build.json"
+  }
+}