@vanduo-oss/vd3-flowchart 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to `@vanduo-oss/vd3-flowchart` are documented here.
+
+## 1.2.0 — 2026-09-13
+
+Extracted from `@vanduo-oss/vd3-cbun@1.4.2` as a standalone package. Component
+API and `VD_FLOWCHART_VERSION` remain `1.2.0` (Vue wrapper + `VdFlowchartCore`,
+`computeLayout`, `LAYOUT_MODES`, `FLOWCHART_*` tables, `{ version, viewport,
+nodes, edges }` serialization, `MAX_NODES`/`MAX_EDGES` caps, `--vd-bg-*`
+chrome). Playwright smoke is new in this repo (cbun never shipped one).

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Vanduo Open Source Foundation
+
+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,118 @@
+# @vanduo-oss/vd3-flowchart
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Vanduo **flowchart** for Vue 3: a node/edge editor with undo/redo, layout
+modes, and a framework-agnostic core. Extracted 1-to-1 from
+`@vanduo-oss/vd3-cbun` flowchart **1.2.0**.
+
+**Status: 1.2.0.** `VD_FLOWCHART_VERSION` matches the package version and is
+**load-bearing** — `toJSON()` writes it into user documents. Do not reset it.
+
+## Install
+
+```sh
+pnpm add @vanduo-oss/vd3-flowchart
+```
+
+`vue >=3.3.0` is a **required** peer dependency (the only runtime dep) — install
+it alongside if your project does not already depend on Vue. For correct
+theming, also provide the Vanduo `--vd-*` design tokens (see
+[Theming](#theming)).
+
+## Import
+
+```js
+import {
+  VdFlowchart,
+  VdFlowchartCore,
+  computeLayout,
+  LAYOUT_MODES,
+  FLOWCHART_NODE_TYPES,
+  VD_FLOWCHART_VERSION,
+} from '@vanduo-oss/vd3-flowchart';
+import '@vanduo-oss/vd3-flowchart/css';
+```
+
+Named exports only — no default export. `VdFlowchart` is the Vue wrapper; the
+editor class is re-exported as `VdFlowchartCore` (same class name upstream).
+`computeLayout`, `LAYOUT_MODES`, and the `FLOWCHART_*` tables
+(`FLOWCHART_NODE_TYPES`, `FLOWCHART_PORTS`, `FLOWCHART_EDGE_MARKERS`,
+`FLOWCHART_EDGE_ROUTES`) ship alongside. The core does not import Vue.
+
+`vue` is never bundled — it stays external in both the esm and cjs outputs.
+The build emits `dist/meta.json` and **fails** if any input leaves `src/` or
+if anything but `vue` is externalized. The package declares
+`sideEffects: ["**/*.css"]`.
+
+## Version policy
+
+`package.json` version **is** `VD_FLOWCHART_VERSION` (`1.2.0`). Bump both
+together, and only when the serialized document format changes. This continues
+the old-line `@vanduo-oss/flowchart` lineage (never reset to `1.0.0`). Do not
+reuse the retired npm name `@vanduo-oss/flowchart`.
+
+## Theming
+
+Flowchart chrome renders against Vanduo `--vd-*` design tokens — the same
+tokens `@vanduo-oss/vd3` defines — with built-in fallbacks. vd3 is not a
+package dependency; any provider of the tokens works.
+
+```js
+import '@vanduo-oss/vd3/css';
+// …or the tokens-only layer:
+import '@vanduo-oss/vd3/css/core';
+```
+
+Tokens consumed include `--vd-bg-primary`, `--vd-bg-secondary`,
+`--vd-text-primary`, `--vd-text-muted`, `--vd-border-color`, and
+`--vd-color-primary` (via `--vd-flowchart-*` locals).
+
+## Security
+
+- **No bundled dependencies** — beyond the `vue` peer, nothing is bundled; the
+  build fails if any other module is externalized or any `node_modules` input
+  is bundled.
+- **Hardened `.npmrc`:** `ignore-scripts`, `minimum-release-age`, `save-exact`,
+  `strict-peer-dependencies`, `trust-policy=no-downgrade`,
+  `block-exotic-subdeps`, and an explicit `registry`.
+- **MIT** licensed ([LICENSE](./LICENSE)); toolbar Phosphor paths are inlined
+  (MIT) so the package vendors no third-party runtime modules.
+
+## Exports
+
+| Export | Contents |
+| --- | --- |
+| `@vanduo-oss/vd3-flowchart` | `VdFlowchart` + `VdFlowchartCore`, layout, `FLOWCHART_*`, `VD_FLOWCHART_VERSION` |
+| `@vanduo-oss/vd3-flowchart/css` | Stylesheet (`dist/vd3-flowchart.css`) |
+
+## Development
+
+```sh
+pnpm install
+pnpm lint          # eslint
+pnpm format:check  # prettier
+pnpm stylelint     # authored CSS
+pnpm test          # vitest (jsdom + node)
+pnpm build         # esbuild harness → dist/
+pnpm test:types    # tsc --noEmit over tests/types (needs dist/)
+pnpm test:e2e      # Playwright Chromium (needs dist/)
+```
+
+`test:types` and `test:e2e` consume the built `dist/` output, so **run
+`pnpm build` first**. Chromium must be installed once:
+`pnpm exec playwright install chromium`.
+
+The published package declares a consumer-friendly `engines.node >=20.19.0`;
+the dev/CI toolchain pins Node 24 via `packageManager` +
+`.github/workflows/ci.yml`.
+
+## Documentation
+
+- Agent / LLM reference — [SKILL.md](./SKILL.md)
+- Contributing — [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Changelog — [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+[MIT](./LICENSE) © Vanduo Open Source Foundation

package/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: vanduo-vd3-flowchart
+description: Use when adding Vanduo Vue 3 flowchart with @vanduo-oss/vd3-flowchart — node/edge editor, undo/redo, layout modes, and a framework-agnostic core. Covers install, CSS, theming, and the load-bearing VD_FLOWCHART_VERSION 1.2.0.
+---
+
+# @vanduo-oss/vd3-flowchart
+
+Standalone Vue 3 flowchart package. `vue >=3.3.0` is a required peer. The root
+import re-exports the Vue wrapper AND the framework-agnostic core
+(`VdFlowchartCore`). `VD_FLOWCHART_VERSION` is `1.2.0` and matches
+`package.json`.
+
+## Install
+
+```sh
+pnpm add @vanduo-oss/vd3-flowchart
+```
+
+Nothing registers globally. For correct theming, provide the Vanduo `--vd-*`
+design tokens (see [Theming](#theming)).
+
+## Flowchart
+
+```js
+import { VdFlowchart, VdFlowchartCore } from '@vanduo-oss/vd3-flowchart';
+import '@vanduo-oss/vd3-flowchart/css';
+```
+
+`VdFlowchart` is the Vue 3 wrapper; the framework-agnostic editor core is the
+same class name upstream, so it is re-exported as `VdFlowchartCore`. The entry
+also re-exports `computeLayout`, `LAYOUT_MODES`, and the `FLOWCHART_*` constant
+tables (`FLOWCHART_NODE_TYPES`, `FLOWCHART_PORTS`, `FLOWCHART_EDGE_MARKERS`,
+`FLOWCHART_EDGE_ROUTES`) plus `VD_FLOWCHART_VERSION`. CSS ships at
+`@vanduo-oss/vd3-flowchart/css`. `VD_FLOWCHART_VERSION` is `1.2.0` — it
+continues the old-line lineage (never reset to `1.0.0`) because the value is
+serialized into user documents via `toJSON().version`; resetting it would
+mislabel documents saved by the old line.
+
+## Theming
+
+Flowchart uses `--vd-*` tokens (via `--vd-flowchart-*` locals) with built-in
+fallbacks. vd3 is not a package dependency.
+
+```js
+import '@vanduo-oss/vd3/css';
+import '@vanduo-oss/vd3/css/core';
+```

package/dist/core.d.ts

@@ -0,0 +1,288 @@
+// Type definitions for the framework-agnostic flowchart editor core.
+// Hand-written to mirror the runtime in ./core.js (the vanilla auto-init layer
+// has been excised).
+
+export type FlowchartNodeType =
+  'rounded-rect' | 'rect' | 'diamond' | 'circle' | 'textbox' | 'label' | 'junction';
+
+export type FlowchartPort = 'top' | 'right' | 'bottom' | 'left';
+export type FlowchartEdgeMarker = 'none' | 'arrow' | 'dot';
+export type FlowchartEdgeRoute = 'curve' | 'straight' | 'orthogonal';
+export type FlowchartEdgeKind = 'line' | 'arrow';
+export type FlowchartDirection = 'right' | 'left' | 'up' | 'down';
+export type LayoutMode = 'tree' | 'radial' | 'grid';
+
+export interface FlowchartViewport {
+  x: number;
+  y: number;
+  scale: number;
+}
+
+export interface FlowchartNode {
+  id: string;
+  type: FlowchartNodeType;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  text: string;
+  data: Record<string, unknown>;
+}
+
+export interface FlowchartEndpoint {
+  nodeId: string;
+  port: FlowchartPort;
+}
+
+export interface FlowchartEdge {
+  id: string;
+  from: FlowchartEndpoint;
+  to: FlowchartEndpoint;
+  kind: FlowchartEdgeKind;
+  startMarker: FlowchartEdgeMarker;
+  endMarker: FlowchartEdgeMarker;
+  strokeWidth: number;
+  route: FlowchartEdgeRoute;
+  label: string;
+  data: Record<string, unknown>;
+}
+
+export interface FlowchartDocument {
+  version: string;
+  viewport: FlowchartViewport;
+  nodes: FlowchartNode[];
+  edges: FlowchartEdge[];
+}
+
+/** Snapshot delivered by the `select` event and `getSelectionSnapshot()`. */
+export type FlowchartSelection =
+  | { kind: 'node'; id: string; node: FlowchartNode }
+  | { kind: 'edge'; id: string; edge: FlowchartEdge };
+
+/** Reference to an anchor node for relative placement. */
+export interface FlowchartRelativeTo {
+  node?: string;
+  nodeId?: string;
+  id?: string;
+  direction?: FlowchartDirection;
+  distance?: number;
+  /** Angle in degrees, screen space (0 = right, 90 = down). Overrides direction. */
+  angle?: number;
+}
+
+export interface FlowchartNodeInput {
+  id?: string;
+  type?: FlowchartNodeType;
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+  text?: string;
+  data?: Record<string, unknown>;
+  /** Place relative to another node instead of at the viewport center. */
+  relativeTo?: string | FlowchartRelativeTo;
+}
+
+export interface FlowchartEndpointInput {
+  nodeId?: string;
+  port?: FlowchartPort;
+}
+
+export interface FlowchartEdgeInput {
+  id?: string;
+  from?: string | FlowchartEndpointInput;
+  to?: string | FlowchartEndpointInput;
+  /** Infer omitted ports from node geometry. */
+  autoPort?: boolean;
+  kind?: FlowchartEdgeKind;
+  startMarker?: FlowchartEdgeMarker;
+  endMarker?: FlowchartEdgeMarker;
+  strokeWidth?: number;
+  route?: FlowchartEdgeRoute;
+  label?: string;
+  data?: Record<string, unknown>;
+}
+
+export interface AddChildNodeOptions extends FlowchartNodeInput {
+  direction?: FlowchartDirection;
+  distance?: number;
+  angle?: number;
+  /** Extra options merged into the parent → child edge. */
+  edge?: FlowchartEdgeInput;
+}
+
+export interface LayoutOptions {
+  /** Force a specific root node id; defaults to nodes with no incoming edges. */
+  root?: string;
+  direction?: FlowchartDirection;
+  levelGap?: number;
+  siblingGap?: number;
+  radius?: number;
+  columns?: number;
+  gap?: number;
+  /** Re-pick edge ports after moving nodes (default true). */
+  reroutePorts?: boolean;
+  /** Call fitView() after arranging. */
+  fit?: boolean;
+}
+
+export interface MutationOptions {
+  reason?: string;
+  inspector?: boolean;
+}
+
+export interface LoadOptions {
+  /** Keep the prior selection if the entity still exists after load. */
+  preserveSelection?: boolean;
+}
+
+export interface RemoveNodeOptions {
+  /** Also remove every node reachable through outgoing edges (cycle-safe). */
+  cascade?: boolean;
+  reason?: string;
+}
+
+export interface FlowchartChangeEvent {
+  reason: string;
+  document: FlowchartDocument;
+  node?: FlowchartNode;
+  edge?: FlowchartEdge;
+  nodeId?: string;
+  nodeIds?: string[];
+  edgeId?: string;
+  mode?: LayoutMode;
+}
+
+export interface FlowchartSelectEvent {
+  selection: FlowchartSelection | null;
+}
+
+export interface FlowchartViewportEvent {
+  reason: string;
+  viewport: FlowchartViewport;
+  document: FlowchartDocument;
+}
+
+export interface FlowchartConnectEvent {
+  edge: FlowchartEdge;
+}
+
+export interface FlowchartHistoryEvent {
+  reason: string;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+export interface FlowchartEventMap {
+  change: FlowchartChangeEvent;
+  select: FlowchartSelectEvent;
+  viewport: FlowchartViewportEvent;
+  connect: FlowchartConnectEvent;
+  history: FlowchartHistoryEvent;
+  ready: VdFlowchart;
+}
+
+export interface VdFlowchartOptions {
+  element?: Element | string;
+  /** Alias for `element`. */
+  target?: Element | string;
+  data?: Partial<FlowchartDocument> | string;
+  readonly?: boolean;
+  gridSize?: number;
+  /** 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;
+}
+
+export class VdFlowchart {
+  constructor(options?: VdFlowchartOptions);
+
+  readonly element: Element;
+  readonly readonly: boolean;
+  readonly gridSize: number;
+
+  // Selection
+  select(selection: { kind: 'node' | 'edge'; id: string } | null): void;
+  selectNode(nodeId: string): this;
+  selectEdge(edgeId: string): this;
+  deselect(): this;
+
+  // Events
+  on<K extends keyof FlowchartEventMap>(
+    event: K,
+    callback: (payload: FlowchartEventMap[K]) => void,
+  ): this;
+  off<K extends keyof FlowchartEventMap>(
+    event: K,
+    callback: (payload: FlowchartEventMap[K]) => void,
+  ): this;
+
+  // Nodes & edges
+  addNode(partialNode?: FlowchartNodeInput): FlowchartNode;
+  addChildNode(
+    parentId: string,
+    options?: AddChildNodeOptions,
+  ): { node: FlowchartNode; edge: FlowchartEdge | null } | null;
+  updateNode(
+    nodeId: string,
+    patch?: Partial<FlowchartNodeInput>,
+    options?: MutationOptions,
+  ): FlowchartNode | null;
+  removeNode(nodeId: string, options?: RemoveNodeOptions): boolean;
+  addEdge(partialEdge?: FlowchartEdgeInput): FlowchartEdge | null;
+  updateEdge(
+    edgeId: string,
+    patch?: FlowchartEdgeInput,
+    options?: MutationOptions,
+  ): FlowchartEdge | null;
+  removeEdge(edgeId: string): boolean;
+  deleteSelection(): boolean;
+
+  // Layout
+  layout(mode?: LayoutMode, options?: LayoutOptions): this;
+  autoArrange(options?: LayoutOptions): this;
+
+  // History
+  undo(): this;
+  redo(): this;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  clearHistory(): this;
+
+  // Viewport
+  setViewport(viewport: Partial<FlowchartViewport>): this;
+  zoomIn(): this;
+  zoomOut(): this;
+  resetView(): this;
+  fitView(): this;
+
+  // Document
+  clear(): this;
+  load(data: Partial<FlowchartDocument> | string, options?: LoadOptions): this;
+  toJSON(): FlowchartDocument;
+
+  // Text editing
+  startTextEdit(nodeId: string): boolean;
+  stopTextEdit(options?: { commit?: boolean }): void;
+
+  // Lifecycle
+  destroy(): void;
+}
+
+/** Pure layout helper: computes node top-left positions without mutating input. */
+export function computeLayout(
+  documentData: Partial<FlowchartDocument>,
+  mode?: LayoutMode,
+  options?: LayoutOptions,
+): Map<string, { x: number; y: number }>;
+
+export const LAYOUT_MODES: readonly LayoutMode[];
+
+export const VD_FLOWCHART_VERSION: string;
+export const FLOWCHART_NODE_TYPES: readonly FlowchartNodeType[];
+export const FLOWCHART_PORTS: readonly FlowchartPort[];
+export const FLOWCHART_EDGE_MARKERS: readonly FlowchartEdgeMarker[];
+export const FLOWCHART_EDGE_ROUTES: readonly FlowchartEdgeRoute[];