jellies-draw 0.3.4 → 0.4.0

package/README.md

@@ -1,24 +1,238 @@
 # jellies-draw
 
-## Project setup
+A Vue 2 + Konva drawing toolkit that turns any DOM container into a whiteboard. Ships three components — a canvas, a tool palette, and a property picker — that share state via a singleton store, so a single toolbar can drive one or many canvases simultaneously.
+
+Features at a glance:
+
+- **Drawing tools**: pen, rectangle, ellipse, line, arrow, text, image, eraser, clear.
+- **Selection & manipulation**: selector tool with multi-select, drag, transform, copy/cut/paste, undo/redo.
+- **Laser pointer**: temporary red trail for presenting, with a hot-key toggle.
+- **Multi-canvas**: mount any number of `<drawing-canvas>` instances; one toolbar controls whichever canvas was last focused.
+- **Save / load**: serialize a canvas — drawing plus its full undo history — to a JSON string, and restore it later.
+- **Keyboard shortcuts**: tool picking, color/size cycling, clipboard, history, alt-to-penetrate.
+
+## Install
+
 ```
-yarn install
+yarn add jellies-draw
+# or
+npm install jellies-draw
 ```
 
-### Compiles and hot-reloads for development
-```
-yarn serve
+Peer requirements: `vue@^2.7` and `konva@^9`.
+
+## Quick start
+
+Mount all three components inside a parent — the canvas can live anywhere, but `<tool-buttons>` must be mounted to drive the shared tool state, and to enable keyboard shortcuts when `has-short-cuts` is `true`.
+
+```vue
+<template>
+  <div id="app">
+    <div class="toolbar">
+      <tool-buttons :has-short-cuts="true" />
+      <property-pickers />
+    </div>
+    <div class="canvas-area">
+      <drawing-canvas background-color="#ffffff" />
+    </div>
+  </div>
+</template>
+
+<script>
+import { DrawingCanvas, ToolButtons, PropertyPickers } from 'jellies-draw'
+
+export default {
+  components: { DrawingCanvas, ToolButtons, PropertyPickers }
+}
+</script>
+
+<style>
+.toolbar { display: flex; align-items: center; height: 40px; background: #EBEEF3; }
+.canvas-area { position: relative; height: calc(100vh - 40px); }
+</style>
 ```
 
-### Compiles and minifies for production
+The canvas fills its parent (`width: 100%; height: 100%`), so give the wrapper an explicit size. Each canvas observes its container with a `ResizeObserver`, so the Konva stage resizes whenever the wrapper's box changes (window resize, layout reflow, parent resize, etc.).
+
+## Components
+
+### `<drawing-canvas>`
+
+Renders a Konva stage inside its container.
+
+| Prop              | Type     | Default         | Description                                                      |
+| ----------------- | -------- | --------------- | ---------------------------------------------------------------- |
+| `background-color`| `String` | `'transparent'` | CSS color for the whiteboard surface.                            |
+
+Emits:
+
+- `penetrable-updated(isPenetrable: Boolean)` — fires whenever the canvas becomes click-through (laser tool, Alt held, or selector locked).
+
+Methods — call these on a component `ref`:
+
+- `save()` → `String` — serialize the canvas to a JSON string. The JSON holds the **entire undo history** (every snapshot plus the current index), not just the visible drawing.
+- `load(json)` — restore the canvas from a string produced by `save()`, bringing back both the drawing and its undo/redo stack. Pass `null` or `''` to clear the canvas to a blank state.
+
+### `<tool-buttons>`
+
+Renders the tool palette. The palette mutates a shared singleton store, so one instance already drives every mounted canvas — **mount exactly one `<tool-buttons>` per page**. A second instance's `has-short-cuts` / `are-canvases-linked` watchers clobber the first's, so whichever mounted last silently wins.
+
+| Prop                   | Type      | Default | Description                                                                                                                                            |
+| ---------------------- | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `has-short-cuts`       | `Boolean` | `false` | Enables keyboard shortcuts (tool picking, color/size, clipboard, history).                                                                             |
+| `are-canvases-linked`  | `Boolean` | `false` | Treat every mounted canvas as one logical document: `clear` wipes them all, and undo/redo replays a shared history stack across all of them in lockstep. |
+
+Tools in order: `laser`, `selector`, `rectangle`, `ellipse`, `arrow`, `line`, `pen`, `text`, `image`, `eraser`, `clear`. Numeric shortcuts `1`–`9, 0` map to positions 1–10 (laser is intentionally unbound; use `` ` `` to toggle it).
+
+Tool behavior:
+
+- **Lockable** (`selector`, `rectangle`, `ellipse`, `arrow`, `line`): click an active tool again to lock it on — it stays selected after each use instead of falling back to the previous tool.
+- **Continuous** (`pen`, `text`, `eraser`, `laser`): stay selected until the user picks a different tool.
+- **Instant** (`image`, `clear`): perform a one-shot action and revert to the previous tool after ~300 ms. `image` opens a file picker; `clear` wipes the active canvas (or every canvas, when `are-canvases-linked` is `true`).
+
+### `<property-pickers>`
+
+Color and size controls. Two color swatches (fill and stroke) and a size dropdown that switches between stroke widths and font sizes depending on whether a text tool/node is active.
+
+- Right-click the fill swatch to set fill to `transparent`.
+- Stroke widths: `2` (H), `3` (HB), `4` (B), `6` (2B).
+- Font sizes: `15` (S), `20` (M), `35` (L), `50` (XL).
+
+## Multi-canvas usage
+
+Multiple `<drawing-canvas>` instances can coexist on the same page. The most recently interacted-with canvas becomes the active target for the toolbar — pointer events on an inactive canvas first promote it to active, then begin drawing.
+
+```vue
+<template>
+  <div>
+    <div class="toolbar">
+      <tool-buttons :has-short-cuts="true" />
+      <property-pickers />
+    </div>
+    <div class="split">
+      <drawing-canvas background-color="#fffdfa" />
+      <drawing-canvas background-color="#fafdff" />
+    </div>
+  </div>
+</template>
+
+<style>
+.split { display: flex; height: calc(100vh - 40px); }
+.split > * { flex: 1; position: relative; }
+</style>
 ```
-yarn build
+
+Use `are-canvases-linked` on `<tool-buttons>` to choose how the mounted canvases relate to each other:
+
+- **`are-canvases-linked="false"` (default — independent documents).** Each canvas keeps its own undo/redo stack and its own clear action. Pick this when several canvases are mounted at once as separate artboards. (For pages shown one at a time, keep a single canvas and swap content instead — see [Paged documents](#paged-documents).)
+- **`are-canvases-linked="true"` (one logical document).** All mounted canvases share a single history stack; undo/redo replays every canvas in lockstep, and `clear` wipes them all. Pick this when the canvases together form one drawing surface (e.g. a split view, or canvases overlaid on a long scrollable page).
+
+Always shared (regardless of mode):
+
+- **Tool selection, colors, sizes, and the laser pointer.** Picking a tool or color in the toolbar applies to whichever canvas the user interacts with next.
+- **The active canvas.** Pointer events on an inactive canvas first promote it to active, then begin drawing.
+
+Limitations:
+
+- **A drawing stays on the canvas it started on.** A stroke or shape begun on one canvas is bound to that canvas until the pointer is released. Dragging onto another canvas (or off-canvas) mid-draw is not captured there, and leaves a straight gap if the pointer returns. You cannot draw one continuous stroke spanning two canvases — treat each as a separate drawing surface.
+- **Line / arrow attachments are scoped to a single canvas.** Endpoints that snap to a rectangle/ellipse only track shapes on the same canvas; cross-canvas attachments are not supported.
+- **Pick a mode at mount time.** The linked and per-canvas modes maintain separate history stacks under the hood; flipping `are-canvases-linked` mid-session switches which stack drives undo/redo, but does not migrate entries between them. If you need to flip dynamically, unmount and remount the canvases (the demo's mode switcher does this by toggling `v-if`).
+
+## Paged documents
+
+When pages are shown one at a time — a carousel, a paged reader, a slide deck — don't mount one canvas per page. As pages scroll out of view their DOM is usually unmounted, which destroys the canvas and its drawing along with it.
+
+Instead, keep a **single** `<drawing-canvas>` overlaid on the page area and swap each page's content with `save()` / `load()`. The host stores one JSON string per page:
+
+```vue
+<template>
+  <div class="reader">
+    <div class="page-stage">
+      <div :key="page" class="page" v-html="pages[page - 1]" />
+      <drawing-canvas ref="board" class="overlay" background-color="transparent" />
+    </div>
+    <button :disabled="page === 1" @click="go(page - 1)">Prev</button>
+    <button :disabled="page === pages.length" @click="go(page + 1)">Next</button>
+  </div>
+</template>
+
+<script>
+import { DrawingCanvas } from 'jellies-draw'
+
+export default {
+  components: { DrawingCanvas },
+  data: () => ({
+    page: 1,
+    pages: ['<h2>Page 1</h2>', '<h2>Page 2</h2>'],
+    drawings: {}
+  }),
+  methods: {
+    go(target) {
+      if (target < 1 || target > this.pages.length) return
+      this.drawings[this.page] = this.$refs.board.save()   // stash the page being left
+      this.page = target
+      this.$refs.board.load(this.drawings[target] || null) // restore the page being entered
+    }
+  }
+}
+</script>
+
+<style>
+.page-stage { position: relative; height: 70vh; }
+.overlay { position: absolute; inset: 0; }
+</style>
 ```
 
-### Lints and fixes files
+Because `save()` captures the full undo history, undo/redo keeps working per page after you navigate away and back. Persist the `drawings` map to a backend if annotations must outlive a reload.
+
+A couple of things to keep in mind:
+
+- The single canvas is one fixed overlay — it does not scroll with page content. If a page scrolls internally, mount the canvas inside the scrolling element (sized to the full content) rather than over the viewport.
+- While a drawing tool is active the overlay captures pointer events. Keep navigation controls outside the overlay, or rely on [penetrable mode](#penetrable-mode) so clicks fall through when you are not drawing.
+
+The demo's **Paged** layout is a working example of this pattern.
+
+## Keyboard shortcuts
+
+Enabled when `<tool-buttons :has-short-cuts="true">` is mounted and an input/text field is not focused.
+
+| Key                  | Action                                                    |
+| -------------------- | --------------------------------------------------------- |
+| `1`–`9`, `0`         | Select tool 1–10 (see tool order above).                  |
+| `` ` ``              | Toggle laser pointer.                                     |
+| `Esc`                | Deselect all nodes.                                       |
+| `Backspace`          | Delete selected nodes.                                    |
+| `Cmd/Ctrl + A`       | Select all nodes.                                         |
+| `Cmd/Ctrl + C/X/V`   | Copy / cut / paste.                                       |
+| `Cmd/Ctrl + Z`       | Undo.                                                     |
+| `Cmd/Ctrl + Shift+Z` | Redo.                                                     |
+| `Shift + 1`–`9`      | Pick stroke color (red, green, orange, blue, pink, yellow, purple, light gray, dark gray). |
+| `Shift + =` / `-`    | Increase / decrease size (font size or stroke width).     |
+| Hold `Alt`           | Make the canvas click-through temporarily.                |
+
+Text editing suspends shortcuts so typing is uninterrupted.
+
+## Penetrable mode
+
+The canvas becomes click-through when:
+
+- The `laser` tool is active.
+- `Alt` is held.
+- The `selector` tool is locked.
+
+While penetrable, pointer events fall through to whatever sits behind the canvas — useful for annotating over an underlying UI.
+
+## Demo / development
+
+The repo includes a Vue CLI demo app showing single, split, paged, and scrollable layouts.
+
 ```
+yarn install
+yarn serve            # dev server with hot reload
+yarn build            # build the UMD bundle to dist/jellies-draw.js
 yarn lint
 ```
 
-### Customize configuration
-See [Configuration Reference](https://cli.vuejs.org/config/).
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jellies-draw",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "A drawer for jellies",
   "private": false,
   "main": "./src/index.js",

package/src/App.vue

@@ -1,18 +1,82 @@
 <template>
   <div id="app">
     <div class="toolbar" v-show="isCanvasEnabled">
-      <tool-buttons :has-short-cuts="isCanvasEnabled" />
+      <tool-buttons
+        :has-short-cuts="isCanvasEnabled"
+        :are-canvases-linked="mode !== 'paged'"
+      />
       <div class="toolbar-divider"/>
       <property-pickers />
     </div>
     <div class="demo-entry">
-      <input type="checkbox" v-model="isCanvasEnabled"/> Enable Canvas
+      <label>
+        <input type="checkbox" v-model="isCanvasEnabled"/> Enable Canvas
+      </label>
+      <span v-if="isCanvasEnabled" class="mode-switcher">
+        <button
+          v-for="opt in modes"
+          :key="opt.value"
+          :class="['mode-btn', { active: mode === opt.value }]"
+          @click="mode = opt.value"
+        >
+          {{ opt.label }}
+        </button>
+      </span>
+    </div>
+    <div v-if="isCanvasCreated" v-show="isCanvasVisible" class="canvas-area">
+      <template v-if="mode === 'split'">
+        <div key="split-layout" class="split-layout">
+          <div class="split-pane">
+            <div class="pane-label">Left</div>
+            <drawing-canvas background-color="#fffdfa" />
+          </div>
+          <div class="split-divider"/>
+          <div class="split-pane">
+            <div class="pane-label">Right</div>
+            <drawing-canvas background-color="#fafdff" />
+          </div>
+        </div>
+      </template>
+      <template v-else-if="mode === 'paged'">
+        <div key="lesson-layout" class="lesson-layout">
+          <div class="lesson-stage">
+            <div :key="currentPage" class="lesson-page" v-html="currentPageHtml" />
+            <div class="lesson-board">
+              <drawing-canvas ref="board" background-color="transparent" />
+            </div>
+          </div>
+          <div class="lesson-nav">
+            <button
+              class="nav-arrow"
+              :disabled="currentPage === 1"
+              @click="goToPage(currentPage - 1)"
+            >‹</button>
+            <button
+              v-for="page in pages.length"
+              :key="page"
+              :class="['page-dot', { active: currentPage === page }]"
+              @click="goToPage(page)"
+            >
+              {{ page }}
+            </button>
+            <button
+              class="nav-arrow"
+              :disabled="currentPage === pages.length"
+              @click="goToPage(currentPage + 1)"
+            >›</button>
+          </div>
+        </div>
+      </template>
+      <template v-else-if="mode === 'scroll'">
+        <div key="scroll-layout" class="scroll-layout">
+          <div class="scroll-viewport">
+            <div class="scroll-content">
+              <drawing-canvas background-color="#fafafa" />
+            </div>
+          </div>
+        </div>
+      </template>
     </div>
-    <drawing-canvas
-      ref="drawingCanvas"
-      v-if="isCanvasCreated"
-      v-show="isCanvasVisible"
-    />
   </div>
 </template>
 
@@ -29,7 +93,21 @@ export default {
   },
   data: () => ({
     isCanvasCreated: false,
-    isCanvasVisible: false
+    isCanvasVisible: false,
+    mode: 'split',
+    currentPage: 1,
+    pages: [
+      '<h2>Lesson 1 · Variables</h2><p>A <strong>variable</strong> is a named place to keep a value. Put a value in, read it back later.</p><p>Try it: circle the word <em>variable</em> with the pen, then turn the page.</p>',
+      '<h2>Lesson 2 · Loops</h2><p>A <strong>loop</strong> repeats a block of code, so you do not write the same line ten times.</p><p>Your drawing from Lesson 1 stays on its own page — flip back and check.</p>',
+      '<h2>Lesson 3 · Functions</h2><p>A <strong>function</strong> wraps logic under a name so you can reuse it. Call the name, get the result.</p><p>Each page keeps its own annotations.</p>',
+      '<h2>Lesson 4 · Recap</h2><p>Variables hold values, loops repeat work, functions package logic.</p><p>One whiteboard overlays every page; <code>save()</code> and <code>load()</code> swap the drawing as you navigate.</p>'
+    ],
+    drawings: {},
+    modes: [
+      { value: 'split', label: 'Split' },
+      { value: 'paged', label: 'Paged' },
+      { value: 'scroll', label: 'Scroll' }
+    ]
   }),
   computed: {
     isCanvasEnabled: {
@@ -38,16 +116,30 @@ export default {
       },
       set(isEnabled) {
         if (isEnabled) {
-          if (this.isCanvasCreated) {
-            this.isCanvasVisible = true
-          } else {
-            this.isCanvasCreated = true
-            this.isCanvasVisible = true
-          }
+          if (!this.isCanvasCreated) this.isCanvasCreated = true
+          this.isCanvasVisible = true
         } else {
           this.isCanvasVisible = false
         }
       }
+    },
+    currentPageHtml() {
+      return this.pages[this.currentPage - 1] || ''
+    }
+  },
+  watch: {
+    mode() {
+      this.currentPage = 1
+      this.drawings = {}
+    }
+  },
+  methods: {
+    goToPage(target) {
+      if (target < 1 || target > this.pages.length || target === this.currentPage) return
+      const board = this.$refs.board
+      if (board) this.drawings[this.currentPage] = board.save()
+      this.currentPage = target
+      if (board) board.load(this.drawings[target] || null)
     }
   }
 }
@@ -69,6 +161,8 @@ body {
 #app {
   height: 100%;
   width: 100%;
+  display: flex;
+  flex-direction: column;
 }
 .toolbar {
   height: 40px;
@@ -77,6 +171,7 @@ body {
   justify-content: center;
   align-items: center;
   background: #EBEEF3;
+  flex-shrink: 0;
 }
 .toolbar-divider {
   height: 30px;
@@ -86,8 +181,157 @@ body {
 }
 .demo-entry {
   position: absolute;
-  top: 0;
-  right: 0;
-  z-index: 2;
+  top: 6px;
+  right: 12px;
+  z-index: 10;
+  display: flex;
+  gap: 12px;
+  align-items: center;
+  font-size: 12px;
+}
+.mode-switcher {
+  display: inline-flex;
+  border: 1px solid rgba(0, 0, 0, 0.12);
+  border-radius: 4px;
+  overflow: hidden;
+  background: #fff;
+}
+.mode-btn {
+  border: none;
+  background: transparent;
+  padding: 3px 10px;
+  cursor: pointer;
+  font-size: 12px;
+  color: #555;
+}
+.mode-btn + .mode-btn {
+  border-left: 1px solid rgba(0, 0, 0, 0.08);
+}
+.mode-btn.active {
+  background: #399af4;
+  color: #fff;
+}
+.canvas-area {
+  flex: 1;
+  min-height: 0;
+  width: 100%;
+  position: relative;
+}
+.split-layout {
+  height: 100%;
+  width: 100%;
+  display: flex;
+}
+.split-pane {
+  flex: 1;
+  position: relative;
+  min-width: 0;
+}
+.split-divider {
+  width: 1px;
+  background: rgba(0, 0, 0, 0.08);
+}
+.pane-label {
+  position: absolute;
+  top: 6px;
+  left: 8px;
+  z-index: 10000;
+  font-size: 11px;
+  color: rgba(0, 0, 0, 0.45);
+  pointer-events: none;
+}
+.lesson-layout {
+  height: 100%;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+}
+.lesson-stage {
+  flex: 1;
+  min-height: 0;
+  position: relative;
+  background: #ffffff;
+}
+.lesson-page {
+  position: absolute;
+  inset: 0;
+  overflow: auto;
+  box-sizing: border-box;
+  padding: 24px 32px;
+  text-align: left;
+  font-size: 14px;
+  color: #333;
+}
+.lesson-page h2 {
+  margin: 0 0 12px;
+  font-size: 17px;
+  color: #1f2d3d;
+}
+.lesson-page p {
+  margin: 0 0 10px;
+  line-height: 1.6;
+}
+.lesson-page code {
+  background: #f1f3f5;
+  border-radius: 3px;
+  padding: 1px 5px;
+  font-size: 13px;
+}
+.lesson-board {
+  position: absolute;
+  inset: 0;
+}
+.lesson-nav {
+  flex-shrink: 0;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  gap: 6px;
+  padding: 6px;
+  background: #f5f6f8;
+  border-top: 1px solid rgba(0, 0, 0, 0.06);
+}
+.nav-arrow,
+.page-dot {
+  border: 1px solid rgba(0, 0, 0, 0.12);
+  background: #fff;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 12px;
+  color: #555;
+}
+.nav-arrow {
+  width: 26px;
+  height: 26px;
+  line-height: 1;
+}
+.nav-arrow:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+.page-dot {
+  min-width: 26px;
+  height: 26px;
+  padding: 0 6px;
+}
+.page-dot.active {
+  background: #399af4;
+  color: #fff;
+  border-color: #399af4;
+}
+.scroll-layout {
+  height: 100%;
+  width: 100%;
+  overflow: hidden;
+}
+.scroll-viewport {
+  height: 100%;
+  width: 100%;
+  overflow: auto;
+}
+.scroll-content {
+  width: 100%;
+  height: 1800px;
+  position: relative;
 }
 </style>

package/src/components/DrawingCanvas.vue

@@ -31,7 +31,7 @@ export default {
   props: {
     backgroundColor: {
       type: String,
-      default: 'penetrable'
+      default: 'transparent'
     }
   },
   computed: {
@@ -64,7 +64,13 @@ export default {
       Canvas.initialize(this.canvas, this.container)
     },
     destroyStage() {
-      Canvas.destroy()
+      Canvas.destroy(this.canvas)
+    },
+    save() {
+      return Canvas.exportJSON(this.canvas)
+    },
+    load(json) {
+      Canvas.loadJSON(this.canvas, json)
     }
   }
 }
@@ -78,6 +84,8 @@ export default {
 .container {
   width: 100%;
   height: 100%;
+  position: relative;
+  box-sizing: border-box;
 }
 .container-penetrable,
 .container-penetrable * {
@@ -88,6 +96,8 @@ export default {
 }
 .whiteboard {
   position: relative;
-  z-index: 9999; /* 确保画板在最上层 */
+  width: 100%;
+  height: 100%;
+  z-index: 9999;
 }
 </style>

package/src/components/ToolButton.vue

@@ -142,13 +142,6 @@ button {
   content: "\e7a9";
 }
 .tool-laser:before {
-  content: "";
-  display: inline-block;
-  width: 8px;
-  height: 8px;
-  border-radius: 50%;
-  background: #f33b29;
-  box-shadow: 0 0 4px #f33b29, 0 0 8px rgba(243, 59, 41, 0.6);
-  vertical-align: middle;
+  content: "\e900";
 }
 </style>

package/src/components/ToolButtons.vue

@@ -22,6 +22,7 @@ import ToolButton from './ToolButton.vue'
 import Properties from './functions/properties'
 import Tools from './functions/tools'
 import Canvas from './functions/canvas'
+
 export default {
   name: 'ToolButtons',
   components: {
@@ -31,6 +32,10 @@ export default {
     hasShortCuts: {
       type: Boolean,
       default: false
+    },
+    areCanvasesLinked: {
+      type: Boolean,
+      default: false
     }
   },
   mounted() {
@@ -99,8 +104,17 @@ export default {
     }
   },
   watch: {
-    hasShortCuts(hasShortCuts) {
-      Canvas.hasShortCuts = hasShortCuts
+    hasShortCuts: {
+      immediate: true,
+      handler(hasShortCuts) {
+        Canvas.hasShortCuts = hasShortCuts
+      }
+    },
+    areCanvasesLinked: {
+      immediate: true,
+      handler(areCanvasesLinked) {
+        Properties.areCanvasesLinked = areCanvasesLinked
+      }
     }
   },
   methods: {