@vanduo-oss/vd3-cbun 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `@vanduo-oss/vd3-cbun` are documented here. This file
 tracks the PACKAGE only — never docs-site content. Per-component VERSION
 constants are listed alongside each bundle release.
 
+## 1.2.0 — 2026-07-22
+
+Adds a sixth component, **`draw`** (`@vanduo-oss/vd3-cbun/draw` + `./draw/css`),
+exposing `VdDraw` — a first-party **vector drawing tool** (SVG world group with
+matrix pan/zoom, the flowchart architecture family) built around a
+dependency-free **brush engine**: freehand strokes are variable-width, smoothed,
+pressure/velocity-driven filled outline paths. It ships **brush presets** (`pen`,
+`pencil`, `marker`, `highlighter`, `calligraphy` — `BRUSH_PRESETS`), a **color
+palette** (swatches + custom color, opacity, brush size, recent colors), a
+**stroke eraser**, and secondary diagram shapes (rectangle / ellipse / arrow /
+text / sticky) with z-order, grouping, copy/paste/duplicate, snapping guides,
+keyboard shortcuts, and PNG + SVG export. The built-in toolbar uses inline
+Phosphor icons. Undo/redo funnels through a single `emitChange → recordHistory`
+whole-document choke point (pan/zoom not recorded); `toJSON()` / `load()`
+serialize `{ version, viewport, shapes }` — freehand strokes carry `brush` /
+`color` / `opacity` / per-point `pressure` — through a `normalizeDocument()`
+migration gateway (a v1 constant-width freehand loads as the default pen brush).
+Chrome theming is CSS-only through a `--vd-draw-*` → `--vd-*` layer; marks carry
+an explicit picked color. No new runtime dependency — `vue` stays the only peer,
+and every input bundled for the entry lives under `src/draw/` (the metafile
+isolation guard passes). The five existing components are untouched (tree-shake
+contract). Additive minor: bundle `1.1.0 → 1.2.0`.
+
+Component versions in this release: **charts 1.0.0, code-editor 1.0.0, draw
+1.1.0, flowchart 1.2.0, hex-grid 1.0.0, music-player 1.0.0** — `draw` entered the
+`component-versions.json` manifest at `1.0.0`, and its serialization (freehand
+`brush` / `color` / `pressure`) takes `VD_DRAW_VERSION` to `1.1.0`; the bundle's own semver
+stays decoupled from the per-component `VERSION` constants.
+
 ## 1.1.0 — 2026-07-21
 
 Adds a fifth component, **`code-editor`** (`@vanduo-oss/vd3-cbun/code-editor` +

package/README.md

@@ -3,15 +3,16 @@
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
 The Vanduo **components bundle** for the vd3 line: Vue3-only charts, code-editor,
-flowchart, hex-grid, and music-player consolidated into ONE package with
+draw, flowchart, hex-grid, and music-player consolidated into ONE package with
 tree-shakeable subpath exports. It replaces the four per-repo publishes
 (`@vanduo-oss/charts`, `@vanduo-oss/flowchart`, `@vanduo-oss/hex-grid`,
 `@vanduo-oss/music-player`) of the old line.
 
-**Status: 1.1.0.** Five Vue3-only component families — charts, code-editor,
+**Status: 1.2.0.** Six Vue3-only component families — charts, code-editor, draw,
 flowchart, hex-grid, music-player — each on its own tree-shakeable subpath, with
-the esbuild metafile isolation guard in place. (1.1.0 adds the first-party
-`code-editor` component; see the [changelog](./CHANGELOG.md).)
+the esbuild metafile isolation guard in place. (1.2.0 adds the first-party
+`draw` vector drawing tool — a brush engine + color palette; see the
+[changelog](./CHANGELOG.md).)
 
 ## Install
 
@@ -35,6 +36,9 @@ import '@vanduo-oss/vd3-cbun/charts/css';
 import { VdCodeEditor } from '@vanduo-oss/vd3-cbun/code-editor';
 import '@vanduo-oss/vd3-cbun/code-editor/css';
 
+import { VdDraw } from '@vanduo-oss/vd3-cbun/draw';
+import '@vanduo-oss/vd3-cbun/draw/css';
+
 import { VdFlowchart } from '@vanduo-oss/vd3-cbun/flowchart';
 import '@vanduo-oss/vd3-cbun/flowchart/css';
 
@@ -79,15 +83,15 @@ The bundle's own semver (`package.json` version) is decoupled from the
 components inside it. Each component carries a VERSION constant tracked in
 `component-versions.json` at the repo root and asserted in tests against the
 exported `VD3_CBUN_VERSIONS` map. charts, code-editor, hex-grid, and
-music-player sit at `1.0.0`; **flowchart continues its old-line lineage at
+music-player sit at `1.0.0`, draw at `1.1.0`; **flowchart continues its old-line lineage at
 `1.2.0`** because `VD_FLOWCHART_VERSION` is load-bearing — it is serialized
 into user documents via `toJSON().version`. A new component enters the manifest
-at `1.0.0` (`code-editor` did, in bundle 1.1.0).
+at `1.0.0` (`draw` did, in bundle 1.2.0).
 
 ## Theming
 
-All five components render against Vanduo's `--vd-*` design tokens — the same
-tokens `@vanduo-oss/vd3` defines. charts, code-editor, flowchart, and hex-grid
+All six components render against Vanduo's `--vd-*` design tokens — the same
+tokens `@vanduo-oss/vd3` defines. charts, code-editor, draw, flowchart, and hex-grid
 carry built-in fallbacks and degrade gracefully without them; **music-player
 expects the tokens**
 and renders with unset colors/backgrounds if none are provided. For correct
@@ -127,6 +131,8 @@ tokens works — but it is the canonical source.)
 | `@vanduo-oss/vd3-cbun/charts/css`         | Charts stylesheet (`dist/charts/vd3-charts.css`)             |
 | `@vanduo-oss/vd3-cbun/code-editor`        | `VdCodeEditor` + `VdCodeEditorCore`, `tokenize`, `highlight`, `LANGUAGES` |
 | `@vanduo-oss/vd3-cbun/code-editor/css`    | Code-editor stylesheet (`dist/code-editor/vd3-code-editor.css`) |
+| `@vanduo-oss/vd3-cbun/draw`               | `VdDraw` + `VdDrawCore`, `BRUSH_PRESETS`, `DRAW_TOOLS`, `VD_DRAW_VERSION` |
+| `@vanduo-oss/vd3-cbun/draw/css`           | Draw stylesheet (`dist/draw/vd3-draw.css`)                   |
 | `@vanduo-oss/vd3-cbun/flowchart`          | `VdFlowchart` + `VdFlowchartCore`, `computeLayout`, `FLOWCHART_*` |
 | `@vanduo-oss/vd3-cbun/flowchart/css`      | Flowchart stylesheet (`dist/flowchart/vd3-flowchart.css`)    |
 | `@vanduo-oss/vd3-cbun/hex-grid`           | `VdHexGrid` + `VdHexGridCore`, `VD_HEX_VERSION`              |

package/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: vanduo-vd3-cbun
-description: Use when adding Vanduo vd3 components with @vanduo-oss/vd3-cbun — the Vue 3 components bundle (charts, code-editor, flowchart, hex-grid, music-player) with tree-shakeable subpath exports. Covers install, per-subpath imports, CSS, theming, and per-component versioning.
+description: Use when adding Vanduo vd3 components with @vanduo-oss/vd3-cbun — the Vue 3 components bundle (charts, code-editor, draw, flowchart, hex-grid, music-player) with tree-shakeable subpath exports. Covers install, per-subpath imports, CSS, theming, and per-component versioning.
 ---
 
 # @vanduo-oss/vd3-cbun
 
-One bundle, five Vue 3 components, each on its own tree-shakeable subpath
-(`./charts`, `./code-editor`, `./flowchart`, `./hex-grid`, `./music-player`).
+One bundle, six Vue 3 components, each on its own tree-shakeable subpath
+(`./charts`, `./code-editor`, `./draw`, `./flowchart`, `./hex-grid`, `./music-player`).
 `vue >=3.3.0` is a required peer. The root import exposes only `VD3_CBUN_VERSIONS` — the per-
 component VERSION map. Every subpath re-exports the Vue wrapper AND the
 framework-agnostic core alongside it (the core aliased with a `Core` suffix
@@ -68,6 +68,34 @@ Key props: `language`, `readOnly`, `lineNumbers`, `tabSize`, `wrap`,
 `blur`, `ready`. CSS ships at `@vanduo-oss/vd3-cbun/code-editor/css`.
 `VD_CODE_EDITOR_VERSION` is `1.0.0`.
 
+## Draw
+
+```js
+import { VdDraw, VdDrawCore } from '@vanduo-oss/vd3-cbun/draw';
+import '@vanduo-oss/vd3-cbun/draw/css';
+```
+
+`VdDraw` is the Vue 3 wrapper; the framework-agnostic editor core shares the
+class name, so it is re-exported as `VdDrawCore`. It is a first-party **vector
+drawing tool** (SVG world group with matrix pan/zoom) with a **brush engine** —
+freehand strokes are variable-width, smoothed, pressure/velocity-driven filled
+outline paths — and brush presets (`pen`, `pencil`, `marker`, `highlighter`,
+`calligraphy`, in `BRUSH_PRESETS`), a **color palette** (swatches + custom color,
+opacity, size, recent colors), a **stroke eraser**, plus secondary diagram
+shapes (rectangle / ellipse / arrow / text / sticky), z-order, grouping,
+copy/paste/duplicate, snapping guides, and PNG + SVG export. The built-in toolbar
+uses inline Phosphor icons. Undo/redo runs through a single `emitChange →
+recordHistory` choke point (whole-document snapshots; pan/zoom not recorded);
+`toJSON()` / `load()` serialize `{ version, viewport, shapes }` (freehand strokes
+carry `brush` / `color` / `opacity` / per-point `pressure`) via a
+`normalizeDocument()` migration gateway. Chrome theming is CSS-only via a
+`--vd-draw-*` → `--vd-*` layer; marks carry an explicit picked color. The subpath
+also re-exports `BRUSH_PRESETS`, `DRAW_TOOLS`, `DRAW_SHAPE_TYPES`, and
+`VD_DRAW_VERSION`. Key props: `data`, `tool`, `readonly`, `gridSize`, `snap`,
+`autoFit`, `history`, `historyLimit`; events: `change`, `select`, `viewport`,
+`ready`. CSS ships at `@vanduo-oss/vd3-cbun/draw/css`. `VD_DRAW_VERSION` is
+`1.1.0`.
+
 ## Flowchart
 
 ```js
@@ -129,8 +157,8 @@ core (no name collision, so it keeps its own name) re-exported alongside
 
 ## Theming
 
-All four components render against Vanduo's `--vd-*` design tokens — the same
-tokens `@vanduo-oss/vd3` defines. charts, flowchart, and hex-grid ship built-in
+All six components render against Vanduo's `--vd-*` design tokens — the same
+tokens `@vanduo-oss/vd3` defines. charts, code-editor, draw, flowchart, and hex-grid ship built-in
 fallbacks and degrade gracefully without them; **music-player expects the tokens**
 and renders with unset colors/backgrounds if none are present. Provide them on an
 ancestor element — simplest is to import the vd3 stylesheet (`@vanduo-oss/vd3/css`,

package/dist/draw/core.d.ts

@@ -0,0 +1,249 @@
+// Type definitions for the framework-agnostic draw tool core.
+// Hand-written to mirror the runtime in ./core.js + ./shapes.js. Self-contained
+// (the shipped .d.ts trio is index/core/vue — no shapes.d.ts), so every draw
+// type and constant is declared here.
+
+export type DrawTool =
+  'select' | 'hand' | 'draw' | 'eraser' | 'rectangle' | 'ellipse' | 'line' | 'text' | 'sticky';
+
+export type DrawShapeType = 'rectangle' | 'ellipse' | 'line' | 'freehand' | 'text' | 'sticky';
+
+export type BrushName = 'pen' | 'pencil' | 'marker' | 'highlighter' | 'calligraphy';
+
+export interface BrushPreset {
+  size: number;
+  thinning: number;
+  smoothing: number;
+  streamline: number;
+  taperStart: number;
+  taperEnd: number;
+  opacity: number;
+  blend: string;
+  nibAngle?: number;
+}
+
+export interface DrawViewport {
+  x: number;
+  y: number;
+  scale: number;
+}
+
+/** A world-space point `[x, y]` with an optional third `pressure` (0–1) slot. */
+export type DrawPoint = [number, number] | [number, number, number];
+
+/**
+ * A shape in the document. Box shapes (rectangle/ellipse/text/sticky) use
+ * x/y/w/h; line/freehand use `points`. `color` is the stroke color for shapes /
+ * lines and the fill color for freehand brush strokes.
+ */
+export interface DrawShape {
+  id: string;
+  type: DrawShapeType;
+  x?: number;
+  y?: number;
+  w?: number;
+  h?: number;
+  rotation?: number;
+  points?: DrawPoint[];
+  /** freehand: the brush preset. */
+  brush?: BrushName;
+  /** stroke color (shapes/line) or fill color (freehand). */
+  color?: string;
+  fill?: string;
+  /** freehand brush size. */
+  size?: number;
+  /** shapes/line stroke width. */
+  strokeWidth?: number;
+  opacity?: number;
+  text?: string;
+  arrowStart?: boolean;
+  arrowEnd?: boolean;
+  groupId?: string;
+}
+
+export interface DrawDocument {
+  version: string;
+  viewport: DrawViewport;
+  shapes: DrawShape[];
+}
+
+export interface DrawBounds {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+export interface DrawChangeEvent {
+  reason: string;
+  document: DrawDocument;
+  shape?: DrawShape;
+  shapeId?: string;
+  shapeIds?: string[];
+  groupId?: string;
+}
+
+export interface DrawSelectEvent {
+  ids: string[];
+  shapes: DrawShape[];
+}
+
+export interface DrawViewportEvent {
+  reason: string;
+  viewport: DrawViewport;
+  document: DrawDocument;
+}
+
+export interface DrawHistoryEvent {
+  reason: string;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+export interface DrawEventMap {
+  change: DrawChangeEvent;
+  select: DrawSelectEvent;
+  viewport: DrawViewportEvent;
+  history: DrawHistoryEvent;
+  ready: VdDraw;
+}
+
+export interface VdDrawOptions {
+  element?: Element | string;
+  /** Alias for `element`. */
+  target?: Element | string;
+  data?: Partial<DrawDocument> | string;
+  readonly?: boolean;
+  tool?: DrawTool;
+  gridSize?: number;
+  /** Show the background grid (default true). */
+  showGrid?: boolean;
+  /** Snap to nearby edges/centres while moving/resizing (default true). */
+  snap?: boolean;
+  /** Fit to content once the canvas reports a measurable size. */
+  autoFit?: boolean;
+  /** Enable built-in undo/redo (default true). */
+  history?: boolean;
+  /** Maximum retained history entries (default 100). */
+  historyLimit?: number;
+  /** Initial current-style color / opacity / brush size / brush preset. */
+  color?: string;
+  opacity?: number;
+  brushSize?: number;
+  brush?: BrushName;
+}
+
+export interface StylePatch {
+  color?: string;
+  fill?: string;
+  strokeWidth?: number;
+  opacity?: number;
+  size?: number;
+  brush?: BrushName;
+}
+
+export class VdDraw {
+  constructor(options?: VdDrawOptions);
+
+  readonly element: Element;
+  readonly readonly: boolean;
+  gridSize: number;
+  tool: DrawTool;
+  snap: boolean;
+  showGrid: boolean;
+  destroyed: boolean;
+  /** The current drawing style new marks adopt. */
+  style: { color: string; opacity: number; size: number; brush: BrushName };
+
+  // Events
+  on<K extends keyof DrawEventMap>(event: K, callback: (payload: DrawEventMap[K]) => void): this;
+  off<K extends keyof DrawEventMap>(event: K, callback: (payload: DrawEventMap[K]) => void): this;
+
+  // Tool + current style
+  setTool(tool: DrawTool): this;
+  setColor(color: string): this;
+  setOpacity(opacity: number): this;
+  setBrushSize(size: number): this;
+  setBrush(brush: BrushName): this;
+
+  // Grid
+  setGridSize(size: number): this;
+  setGridVisible(visible: boolean): this;
+  toggleGrid(): this;
+
+  // Shapes
+  getShape(id: string): DrawShape | null;
+  addShape(partial?: Partial<DrawShape>): DrawShape;
+  updateShape(
+    id: string,
+    patch?: Partial<DrawShape>,
+    options?: { reason?: string },
+  ): DrawShape | null;
+  removeShape(id: string): boolean;
+
+  // Selection
+  getSelectedShapes(): DrawShape[];
+  select(ids: string | string[] | null, options?: { additive?: boolean }): this;
+  selectAll(): this;
+  deselect(): this;
+  selectInBounds(box: DrawBounds, options?: { additive?: boolean }): this;
+
+  // Manipulation
+  nudge(dx: number, dy: number): this;
+  setSelectionBounds(target: DrawBounds): this;
+  deleteSelection(): boolean;
+  setStyle(patch: StylePatch): this;
+
+  // Z-order
+  bringForward(): this;
+  sendBackward(): this;
+  bringToFront(): this;
+  sendToBack(): this;
+
+  // Grouping
+  group(): this;
+  ungroup(): this;
+
+  // Clipboard
+  copy(): this;
+  cut(): this;
+  paste(options?: { offset?: number }): this;
+  duplicate(): this;
+
+  // Export
+  toSVG(): string;
+  toPNG(options?: { scale?: number }): Promise<string>;
+
+  // Viewport
+  setViewport(patch: Partial<DrawViewport>): this;
+  scaleAround(factor: number, localX: number, localY: number): this;
+  zoomIn(): this;
+  zoomOut(): this;
+  resetView(): this;
+  fitView(): this;
+
+  // History
+  undo(): this;
+  redo(): this;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  clearHistory(): this;
+
+  // Document
+  clear(): this;
+  load(data: Partial<DrawDocument> | string): this;
+  toJSON(): DrawDocument;
+
+  // Text editing
+  startTextEdit(id: string): boolean;
+  stopTextEdit(options?: { commit?: boolean }): void;
+
+  // Rendering + lifecycle
+  render(flags?: { scene?: boolean; overlay?: boolean }): void;
+  destroy(): void;
+}
+
+export const VD_DRAW_VERSION: string;
+export const DRAW_TOOLS: readonly DrawTool[];
+export const DRAW_SHAPE_TYPES: readonly DrawShapeType[];
+export const BRUSH_PRESETS: Readonly<Record<BrushName, BrushPreset>>;