@dcg-overseas/number-line 0.1.31 → 1.0.0-beta.0

package/README.md

@@ -210,11 +210,12 @@ function App() {
 | `canDelete` | `boolean` | 是否有可删除的选中项（笔迹或弧线） |
 | `canUndo` | `boolean` | 是否有可撤销的操作 |
 | `onTogglePen` | `() => void` | 切换画笔工具 |
-| `onToggleEraser` | `() => void` | 切换橡皮擦 |
-| `onDelete` | `() => void` | 删除当前选中 |
-| `onReset` | `() => void` | 清空所有笔迹与选中，并隐藏全部跳数弧线**及分组边界粗刻度**（重新设置 `groupSize/groupCount/min/max` 后恢复） |
+| `onToggleEraser` | `() => void` | 切换橡皮擦 |
+| `onDelete` | `() => void` | 删除当前选中 |
+| `clearAll` | `() => void` | 可撤销地清空全部笔迹、弧线、选择和分组边界粗刻度；连续清空不会增加空历史项 |
+| `onReset` | `() => void` | `clearAll` 的兼容别名，已弃用；新代码请使用 `clearAll` |
 | `onUndo` | `() => void` | 撤销上一步操作 |
-| `showAllArcs` | `() => void` | 重新显示全部跳数弧线**及分组边界粗刻度**（清空删除记录）。即使参数未变、或刚 `onReset` 隐藏后，也能强制把跳数显示出来，且不影响笔迹 |
+| `showAllArcs` | `() => void` | 重新显示全部跳数弧线**及分组边界粗刻度**（清空删除记录）。即使参数未变、或刚 `clearAll` 隐藏后，也能强制把跳数显示出来，且不影响笔迹 |
 
 #### 缩放 API（仅 `enableZoom=true` 时有效）
 | 字段 | 类型 | 说明 |
@@ -234,7 +235,7 @@ function App() {
 import { NumberLineProvider, NumberLine, useNumberLineContext } from '@dcg-overseas/number-line'
 
 function Toolbar() {
-  const { tool, canDelete, canUndo, onTogglePen, onToggleEraser, onDelete, onReset, onUndo } =
+  const { tool, canDelete, canUndo, onTogglePen, onToggleEraser, onDelete, clearAll, onUndo } =
     useNumberLineContext()
 
   return (
@@ -242,7 +243,7 @@ function Toolbar() {
       <button data-active={tool === 'pen'} onClick={onTogglePen}>✏️ 画笔</button>
       <button data-active={tool === 'eraser'} onClick={onToggleEraser}>🩹 擦除</button>
       <button disabled={!canDelete} onClick={onDelete}>🗑 删除</button>
-      <button onClick={onReset}>♻️ 重置</button>
+      <button onClick={clearAll}>♻️ 全部清除</button>
       <button disabled={!canUndo} onClick={onUndo}>↶ 撤销</button>
     </div>
   )
@@ -304,12 +305,9 @@ import type {
 
 ### 操作级撤销
 
-撤销栈记录的是「操作」而非「状态」（`HistoryOp`），分两类：
-
-- `add` — 新增笔迹，撤销 = 移除指定 id
-- `delete` — 删除笔迹/弧线，撤销 = 恢复删除前完整快照 + 还原弧线 group index
-
-这样即使一次 `delete` 同时删了多条笔迹和多条弧线，撤销也能精确还原。
+撤销栈记录每次操作发生前的完整状态快照，包括笔迹、已删除弧线、已选弧线和粗分组刻度状态。
+画笔、橡皮擦、删除选中及 `clearAll` 都复用同一恢复流程，因此一次清空或批量删除可以完整还原。
+`min`、`max`、`groupSize`、`groupCount` 或 `tickStep` 改变时会执行不可撤销初始化并清空历史，防止把上一道题的数据恢复到新坐标范围。
 
 ---
 

package/dist/index.cjs

@@ -5,27 +5,16 @@ const React = require("react");
 function useHistory() {
   const stackRef = React.useRef([]);
   const [stackLen, setStackLen] = React.useState(0);
-  const push = React.useCallback((op) => {
-    stackRef.current = [...stackRef.current, op];
+  const push = React.useCallback((snapshot) => {
+    stackRef.current = [...stackRef.current, snapshot];
     setStackLen(stackRef.current.length);
   }, []);
-  const undo = React.useCallback((strokes) => {
-    if (stackRef.current.length === 0) return { strokes: null, arcIndices: [] };
-    const op = stackRef.current[stackRef.current.length - 1];
+  const undo = React.useCallback(() => {
+    if (stackRef.current.length === 0) return null;
+    const snapshot = stackRef.current[stackRef.current.length - 1];
     stackRef.current = stackRef.current.slice(0, -1);
     setStackLen(stackRef.current.length);
-    switch (op.type) {
-      case "add":
-        return {
-          strokes: strokes.filter((s) => !op.strokes.some((os) => os.id === s.id)),
-          arcIndices: []
-        };
-      case "delete":
-        return {
-          strokes: op.strokesBefore,
-          arcIndices: op.arcIndices
-        };
-    }
+    return snapshot;
   }, []);
   const clear = React.useCallback(() => {
     stackRef.current = [];
@@ -300,11 +289,33 @@ function NumberLineProvider({
   const svgPoint = React.useRef(null);
   const [eraseHoverIds, setEraseHoverIds] = React.useState(/* @__PURE__ */ new Set());
   const eraseGesture = React.useRef(null);
+  const createHistorySnapshot = React.useCallback(
+    (strokesOverride) => ({
+      strokes: (strokesOverride ?? drawing.strokes).map((stroke) => ({ ...stroke })),
+      deletedArcIndices: [...deletedArcIndices],
+      selectedArcIndices: [...selectedArcIndices],
+      groupTicksHidden
+    }),
+    [drawing.strokes, deletedArcIndices, selectedArcIndices, groupTicksHidden]
+  );
   React.useEffect(() => {
+    drawing.resetStrokes();
+    history.clear();
+    setLiveStroke(null);
+    eraseGesture.current = null;
+    setEraseHoverIds(/* @__PURE__ */ new Set());
     setDeletedArcIndices(/* @__PURE__ */ new Set());
     setSelectedArcIndices(/* @__PURE__ */ new Set());
     setGroupTicksHidden(false);
-  }, [domainMin, domainMax, groupSize, groupCount]);
+  }, [
+    domainMin,
+    domainMax,
+    groupSize,
+    groupCount,
+    tickStep,
+    drawing.resetStrokes,
+    history.clear
+  ]);
   const getLocalCoords = React.useCallback(
     (e) => {
       const svg = svgRef.current;
@@ -396,7 +407,7 @@ function NumberLineProvider({
     if (gesture) {
       eraseGesture.current = null;
       if (gesture.removed.size > 0) {
-        history.push({ type: "delete", strokesBefore: gesture.before, arcIndices: [] });
+        history.push(createHistorySnapshot(gesture.before));
       }
       return;
     }
@@ -404,10 +415,10 @@ function NumberLineProvider({
     const stroke = drawing.endStroke();
     setLiveStroke(null);
     if (stroke) {
+      history.push(createHistorySnapshot());
       drawing.addStroke(stroke);
-      history.push({ type: "add", strokes: [stroke] });
     }
-  }, [drawing, history]);
+  }, [drawing, history, createHistorySnapshot]);
   const onPointerLeave = React.useCallback(() => {
     if (eraseGesture.current) return;
     setEraseHoverIds((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
@@ -437,39 +448,55 @@ function NumberLineProvider({
   );
   const clearArcSelection = React.useCallback(() => setSelectedArcIndices(/* @__PURE__ */ new Set()), []);
   const onDelete = React.useCallback(() => {
-    const strokesBefore = drawing.strokes;
     const deletedStrokes = drawing.strokes.filter((s) => s.selected);
     const deletedArcs = [...selectedArcIndices];
     if (deletedStrokes.length === 0 && deletedArcs.length === 0) return;
+    history.push(createHistorySnapshot());
     if (deletedStrokes.length > 0) drawing.deleteSelected();
     if (deletedArcs.length > 0) {
       setDeletedArcIndices((prev) => /* @__PURE__ */ new Set([...prev, ...deletedArcs]));
       setSelectedArcIndices(/* @__PURE__ */ new Set());
     }
-    history.push({ type: "delete", strokesBefore, arcIndices: deletedArcs });
-  }, [drawing, history, selectedArcIndices]);
-  const onReset = React.useCallback(() => {
-    drawing.resetStrokes();
-    history.clear();
+  }, [drawing, history, selectedArcIndices, createHistorySnapshot]);
+  const clearAll = React.useCallback(() => {
     const arcCount = Math.max(0, Math.ceil(Number(groupCount) || 0));
+    const allArcsDeleted = deletedArcIndices.size >= arcCount && Array.from({ length: arcCount }, (_, index) => index).every(
+      (index) => deletedArcIndices.has(index)
+    );
+    const alreadyClear = drawing.strokes.length === 0 && selectedArcIndices.size === 0 && allArcsDeleted && groupTicksHidden;
+    if (alreadyClear) return;
+    history.push(createHistorySnapshot());
+    drawing.resetStrokes();
+    setLiveStroke(null);
+    eraseGesture.current = null;
+    setEraseHoverIds(/* @__PURE__ */ new Set());
     setDeletedArcIndices(new Set(Array.from({ length: arcCount }, (_, i) => i)));
     setSelectedArcIndices(/* @__PURE__ */ new Set());
     setGroupTicksHidden(true);
-  }, [drawing, history, groupCount]);
+  }, [
+    drawing,
+    history,
+    groupCount,
+    deletedArcIndices,
+    selectedArcIndices,
+    groupTicksHidden,
+    createHistorySnapshot
+  ]);
+  const onReset = clearAll;
   const showAllArcs = React.useCallback(() => {
     setDeletedArcIndices((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
     setGroupTicksHidden(false);
   }, []);
   const onUndo = React.useCallback(() => {
-    const result = history.undo(drawing.strokes);
-    if (result.strokes !== null) drawing.restoreStrokes(result.strokes);
-    if (result.arcIndices.length > 0) {
-      setDeletedArcIndices((prev) => {
-        const next = new Set(prev);
-        result.arcIndices.forEach((i) => next.delete(i));
-        return next;
-      });
-    }
+    const snapshot = history.undo();
+    if (!snapshot) return;
+    drawing.restoreStrokes(snapshot.strokes);
+    setDeletedArcIndices(new Set(snapshot.deletedArcIndices));
+    setSelectedArcIndices(new Set(snapshot.selectedArcIndices));
+    setGroupTicksHidden(snapshot.groupTicksHidden);
+    setLiveStroke(null);
+    eraseGesture.current = null;
+    setEraseHoverIds(/* @__PURE__ */ new Set());
   }, [history, drawing]);
   const onTogglePen = React.useCallback(
     () => {
@@ -554,6 +581,7 @@ function NumberLineProvider({
         onTogglePen,
         onToggleEraser,
         onDelete,
+        clearAll,
         onReset,
         onUndo,
         showAllArcs

package/dist/index.d.ts

@@ -44,6 +44,9 @@ export declare interface NumberLineContextValue {
     onTogglePen: () => void;
     onToggleEraser: () => void;
     onDelete: () => void;
+    /** 可撤销地清空笔迹、弧线、选择和粗分组刻度；已为空时不创建历史项。 */
+    clearAll: () => void;
+    /** @deprecated 请使用语义明确且行为相同的 `clearAll`。 */
     onReset: () => void;
     onUndo: () => void;
     /** restore (re-show) every arc by clearing the deleted-arc record */

package/dist/index.js

@@ -3,27 +3,16 @@ import React, { useRef, useState, useCallback, useLayoutEffect, useEffect, creat
 function useHistory() {
   const stackRef = useRef([]);
   const [stackLen, setStackLen] = useState(0);
-  const push = useCallback((op) => {
-    stackRef.current = [...stackRef.current, op];
+  const push = useCallback((snapshot) => {
+    stackRef.current = [...stackRef.current, snapshot];
     setStackLen(stackRef.current.length);
   }, []);
-  const undo = useCallback((strokes) => {
-    if (stackRef.current.length === 0) return { strokes: null, arcIndices: [] };
-    const op = stackRef.current[stackRef.current.length - 1];
+  const undo = useCallback(() => {
+    if (stackRef.current.length === 0) return null;
+    const snapshot = stackRef.current[stackRef.current.length - 1];
     stackRef.current = stackRef.current.slice(0, -1);
     setStackLen(stackRef.current.length);
-    switch (op.type) {
-      case "add":
-        return {
-          strokes: strokes.filter((s) => !op.strokes.some((os) => os.id === s.id)),
-          arcIndices: []
-        };
-      case "delete":
-        return {
-          strokes: op.strokesBefore,
-          arcIndices: op.arcIndices
-        };
-    }
+    return snapshot;
   }, []);
   const clear = useCallback(() => {
     stackRef.current = [];
@@ -298,11 +287,33 @@ function NumberLineProvider({
   const svgPoint = useRef(null);
   const [eraseHoverIds, setEraseHoverIds] = useState(/* @__PURE__ */ new Set());
   const eraseGesture = useRef(null);
+  const createHistorySnapshot = useCallback(
+    (strokesOverride) => ({
+      strokes: (strokesOverride ?? drawing.strokes).map((stroke) => ({ ...stroke })),
+      deletedArcIndices: [...deletedArcIndices],
+      selectedArcIndices: [...selectedArcIndices],
+      groupTicksHidden
+    }),
+    [drawing.strokes, deletedArcIndices, selectedArcIndices, groupTicksHidden]
+  );
   useEffect(() => {
+    drawing.resetStrokes();
+    history.clear();
+    setLiveStroke(null);
+    eraseGesture.current = null;
+    setEraseHoverIds(/* @__PURE__ */ new Set());
     setDeletedArcIndices(/* @__PURE__ */ new Set());
     setSelectedArcIndices(/* @__PURE__ */ new Set());
     setGroupTicksHidden(false);
-  }, [domainMin, domainMax, groupSize, groupCount]);
+  }, [
+    domainMin,
+    domainMax,
+    groupSize,
+    groupCount,
+    tickStep,
+    drawing.resetStrokes,
+    history.clear
+  ]);
   const getLocalCoords = useCallback(
     (e) => {
       const svg = svgRef.current;
@@ -394,7 +405,7 @@ function NumberLineProvider({
     if (gesture) {
       eraseGesture.current = null;
       if (gesture.removed.size > 0) {
-        history.push({ type: "delete", strokesBefore: gesture.before, arcIndices: [] });
+        history.push(createHistorySnapshot(gesture.before));
       }
       return;
     }
@@ -402,10 +413,10 @@ function NumberLineProvider({
     const stroke = drawing.endStroke();
     setLiveStroke(null);
     if (stroke) {
+      history.push(createHistorySnapshot());
       drawing.addStroke(stroke);
-      history.push({ type: "add", strokes: [stroke] });
     }
-  }, [drawing, history]);
+  }, [drawing, history, createHistorySnapshot]);
   const onPointerLeave = useCallback(() => {
     if (eraseGesture.current) return;
     setEraseHoverIds((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
@@ -435,39 +446,55 @@ function NumberLineProvider({
   );
   const clearArcSelection = useCallback(() => setSelectedArcIndices(/* @__PURE__ */ new Set()), []);
   const onDelete = useCallback(() => {
-    const strokesBefore = drawing.strokes;
     const deletedStrokes = drawing.strokes.filter((s) => s.selected);
     const deletedArcs = [...selectedArcIndices];
     if (deletedStrokes.length === 0 && deletedArcs.length === 0) return;
+    history.push(createHistorySnapshot());
     if (deletedStrokes.length > 0) drawing.deleteSelected();
     if (deletedArcs.length > 0) {
       setDeletedArcIndices((prev) => /* @__PURE__ */ new Set([...prev, ...deletedArcs]));
       setSelectedArcIndices(/* @__PURE__ */ new Set());
     }
-    history.push({ type: "delete", strokesBefore, arcIndices: deletedArcs });
-  }, [drawing, history, selectedArcIndices]);
-  const onReset = useCallback(() => {
-    drawing.resetStrokes();
-    history.clear();
+  }, [drawing, history, selectedArcIndices, createHistorySnapshot]);
+  const clearAll = useCallback(() => {
     const arcCount = Math.max(0, Math.ceil(Number(groupCount) || 0));
+    const allArcsDeleted = deletedArcIndices.size >= arcCount && Array.from({ length: arcCount }, (_, index) => index).every(
+      (index) => deletedArcIndices.has(index)
+    );
+    const alreadyClear = drawing.strokes.length === 0 && selectedArcIndices.size === 0 && allArcsDeleted && groupTicksHidden;
+    if (alreadyClear) return;
+    history.push(createHistorySnapshot());
+    drawing.resetStrokes();
+    setLiveStroke(null);
+    eraseGesture.current = null;
+    setEraseHoverIds(/* @__PURE__ */ new Set());
     setDeletedArcIndices(new Set(Array.from({ length: arcCount }, (_, i) => i)));
     setSelectedArcIndices(/* @__PURE__ */ new Set());
     setGroupTicksHidden(true);
-  }, [drawing, history, groupCount]);
+  }, [
+    drawing,
+    history,
+    groupCount,
+    deletedArcIndices,
+    selectedArcIndices,
+    groupTicksHidden,
+    createHistorySnapshot
+  ]);
+  const onReset = clearAll;
   const showAllArcs = useCallback(() => {
     setDeletedArcIndices((prev) => prev.size === 0 ? prev : /* @__PURE__ */ new Set());
     setGroupTicksHidden(false);
   }, []);
   const onUndo = useCallback(() => {
-    const result = history.undo(drawing.strokes);
-    if (result.strokes !== null) drawing.restoreStrokes(result.strokes);
-    if (result.arcIndices.length > 0) {
-      setDeletedArcIndices((prev) => {
-        const next = new Set(prev);
-        result.arcIndices.forEach((i) => next.delete(i));
-        return next;
-      });
-    }
+    const snapshot = history.undo();
+    if (!snapshot) return;
+    drawing.restoreStrokes(snapshot.strokes);
+    setDeletedArcIndices(new Set(snapshot.deletedArcIndices));
+    setSelectedArcIndices(new Set(snapshot.selectedArcIndices));
+    setGroupTicksHidden(snapshot.groupTicksHidden);
+    setLiveStroke(null);
+    eraseGesture.current = null;
+    setEraseHoverIds(/* @__PURE__ */ new Set());
   }, [history, drawing]);
   const onTogglePen = useCallback(
     () => {
@@ -552,6 +579,7 @@ function NumberLineProvider({
         onTogglePen,
         onToggleEraser,
         onDelete,
+        clearAll,
         onReset,
         onUndo,
         showAllArcs

package/package.json

@@ -1,47 +1,47 @@
-{
-  "name": "@dcg-overseas/number-line",
-  "version": "0.1.31",
-  "description": "Interactive number line component with group arcs and freehand drawing",
-  "type": "module",
-  "license": "MIT",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist"
-  ],
-  "sideEffects": false,
-  "scripts": {
-    "build": "vite build",
-    "build:watch": "vite build --watch",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist *.tsbuildinfo"
-  },
-  "peerDependencies": {
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
-  },
-  "devDependencies": {
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "@vitejs/plugin-react": "^4.3.1",
-    "vite": "^5.3.1",
-    "vite-plugin-dts": "^3.9.1"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  }
-}
+{
+  "name": "@dcg-overseas/number-line",
+  "version": "1.0.0-beta.0",
+  "description": "Interactive number line component with group arcs and freehand drawing",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "vite": "^5.3.1",
+    "vite-plugin-dts": "^3.9.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}