headless-vpl 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import Connector from './core/Connector';
+import Workspace from './core/Workspace';
+import Position from './core/Position';
+import Edge from './core/Edge';
+import Container from './core/Container';
+import AutoLayout from './core/AutoLayout';
+import { EventBus } from './core/EventBus';
+import { SelectionManager } from './core/SelectionManager';
+import { History } from './core/History';
+import { MoveCommand, AddCommand, RemoveCommand, ConnectCommand } from './core/commands';
+import { SvgRenderer } from './rendering/SvgRenderer';
+import { getDistance, getAngle } from './util/distance';
+import { screenToWorld, worldToScreen } from './util/viewport';
+import { getStraightPath, getBezierPath, getStepPath, getSmoothStepPath } from './util/edgePath';
+import { createMarqueeRect, getElementsInMarquee, getElementsInScreenMarquee } from './util/marquee';
+import { snapToGrid, snapDeltaToGrid } from './util/snapToGrid';
+import { copyElements, calculatePastePositions, pasteElements } from './util/clipboard';
+import { KeyboardManager } from './util/keyboard';
+import { computeAutoPan } from './util/autoPan';
+import { detectResizeHandle, beginResize, applyResize } from './util/resize';
+import { EdgeBuilder, isConnectorHit, findNearestConnector } from './util/edgeBuilder';
+export { Connector, Workspace, Position, Edge, Container, AutoLayout, EventBus, SelectionManager, History, MoveCommand, AddCommand, RemoveCommand, ConnectCommand, SvgRenderer, getDistance, getAngle, screenToWorld, worldToScreen, getStraightPath, getBezierPath, getStepPath, getSmoothStepPath, createMarqueeRect, getElementsInMarquee, getElementsInScreenMarquee, snapToGrid, snapDeltaToGrid, copyElements, calculatePastePositions, pasteElements, KeyboardManager, computeAutoPan, detectResizeHandle, beginResize, applyResize, EdgeBuilder, isConnectorHit, findNearestConnector, };
+export type { IWorkspaceElement, IEdge, VplEvent, VplEventType, Viewport, SizingMode, Padding } from './core/types';
+export type { EdgeType, MarkerType, EdgeMarker, ResizeHandleDirection } from './core/types';
+export type { IPosition } from './core/Position';
+export type { Command } from './core/History';
+export type { EdgePathResult } from './util/edgePath';
+export type { MarqueeRect, MarqueeMode, MarqueeElement } from './util/marquee';
+export type { ClipboardData } from './util/clipboard';
+export type { KeyBinding } from './util/keyboard';
+export type { CanvasBounds, AutoPanResult } from './util/autoPan';
+export type { ResizableElement, ResizeState } from './util/resize';
+export type { EdgeBuilderConfig } from './util/edgeBuilder';
+export { SnapConnection, childOnly, parentOnly, either } from './util/snap';
+export type { ConnectionValidator, SnapStrategy, SnapConnectionConfig } from './util/snap';

package/dist/rendering/SvgRenderer.d.ts

@@ -0,0 +1,35 @@
+import type Workspace from '../core/Workspace';
+/**
+ * EventBus を購読し、Workspace の要素を SVG として描画する。
+ * core/ から分離された描画レイヤー。
+ */
+export declare class SvgRenderer {
+    private svgRoot;
+    private viewportGroup;
+    private defsElement;
+    private workspace;
+    private elementMap;
+    private markerDefs;
+    constructor(svgRoot: SVGSVGElement, workspace: Workspace);
+    private updateViewportTransform;
+    private onAdd;
+    private onMove;
+    private onUpdate;
+    private onRemove;
+    private onSelect;
+    private onDeselect;
+    private ensureElement;
+    private createElement;
+    private updateElement;
+    private getId;
+    private createContainerRect;
+    private updateContainerRect;
+    private createConnectorCircle;
+    private updateConnectorCircle;
+    private getMarkerId;
+    private ensureMarkerDef;
+    private createEdgeGroup;
+    private updateEdgePath;
+    private createAutoLayoutRect;
+    private updateAutoLayoutRect;
+}

package/dist/util/animate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 毎フレーム実行されるアニメーションループのユーティリティ関数
+ *
+ * @param onFrame 各フレームで実行するコールバック関数
+ * @param deltaTime 前回フレームからの経過時間 (ms)
+ * @param frame 現在のフレーム数
+ */
+export declare function animate(callback: (deltaTime: number, frame: number) => void): void;

package/dist/util/autoPan.d.ts

@@ -0,0 +1,23 @@
+import type { IPosition } from '../core/Position';
+export type CanvasBounds = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type AutoPanResult = {
+    dx: number;
+    dy: number;
+    active: boolean;
+};
+/**
+ * マウスがキャンバス端に近いとき、パン方向と速度を計算する。
+ * 端からの距離に応じた線形速度を返す。
+ *
+ * @param mousePos スクリーン座標でのマウス位置
+ * @param bounds キャンバスの矩形
+ * @param isDragging ドラッグ中かどうか
+ * @param threshold 端からの判定距離（px）
+ * @param speed パン速度の最大値（px/frame）
+ */
+export declare function computeAutoPan(mousePos: IPosition, bounds: CanvasBounds, isDragging: boolean, threshold?: number, speed?: number): AutoPanResult;

package/dist/util/clipboard.d.ts

@@ -0,0 +1,20 @@
+import type { IPosition } from '../core/Position';
+export type ClipboardData = {
+    elements: Record<string, unknown>[];
+};
+/**
+ * 要素を JSON としてシリアライズし、ClipboardData を生成する。
+ */
+export declare function copyElements(elements: {
+    toJSON(): Record<string, unknown>;
+}[]): ClipboardData;
+/**
+ * 貼り付け時の新しい位置を計算する。
+ * 元の位置から offset 分ずらす。
+ */
+export declare function calculatePastePositions(data: ClipboardData, offset?: IPosition): IPosition[];
+/**
+ * ClipboardData から要素を再生成する。
+ * factory パターンにより、具体的な型の生成はユーザー責務。
+ */
+export declare function pasteElements<T>(data: ClipboardData, factory: (json: Record<string, unknown>, position: IPosition) => T, offset?: IPosition): T[];

package/dist/util/collision_detecion.d.ts

@@ -0,0 +1,3 @@
+import Container from '../core/Container';
+import { IPosition } from '../core/Position';
+export declare function isCollision(container: Container, position: IPosition): boolean;

package/dist/util/distance.d.ts

@@ -0,0 +1,3 @@
+import { IPosition } from '../core/Position';
+export declare function getDistance(point1: IPosition, point2: IPosition): number;
+export declare function getAngle(point1: IPosition, point2: IPosition): number;

package/dist/util/dnd.d.ts

@@ -0,0 +1,18 @@
+import Container from '../core/Container';
+import { IPosition } from '../core/Position';
+import { getMouseState } from './mouse';
+/**
+ * 複数のコンテナーに対してドラッグ＆ドロップの更新を行います。
+ *
+ * @param containers - ドラッグ対象のコンテナーの配列
+ * @param dx - 前フレームからのX軸方向の移動量
+ * @param dy - 前フレームからのY軸方向の移動量
+ * @param mousePosition - マウスの現在位置
+ * @param mouseState - マウスの状態（leftButton は 'down' / 'up'）
+ * @param dragEligible - マウスクリック開始時にコンテナー上でクリックされたかを示すフラグ
+ * @param currentDragContainers - 現在ドラッグ中のコンテナーの配列
+ * @param allowMultiple - 複数のコンテナーをドラッグ可能にするかどうかのフラグ
+ *
+ * @returns 更新後のドラッグ中コンテナーの配列。ドラッグしていなければ空の配列を返します。
+ */
+export declare function DragAndDrop(containers: Container[], delta: IPosition, mouseState: getMouseState, dragEligible: boolean, currentDragContainers: Container[], allowMultiple?: boolean, callback?: () => void): Container[];

package/dist/util/domController.d.ts

@@ -0,0 +1,13 @@
+export declare class DomController {
+    private element;
+    private x;
+    private y;
+    constructor(selector: string);
+    move(x: number, y: number): void;
+    moveBy(dx: number, dy: number): void;
+    getPosition(): {
+        x: number;
+        y: number;
+    };
+    private updatePosition;
+}

package/dist/util/edgeBuilder.d.ts

@@ -0,0 +1,65 @@
+import type Connector from '../core/Connector';
+import type { IPosition } from '../core/Position';
+import type Workspace from '../core/Workspace';
+import type { EdgeType } from '../core/types';
+import Edge from '../core/Edge';
+/**
+ * コネクターがマウス位置のヒット範囲内かを判定する。
+ */
+export declare function isConnectorHit(mousePos: IPosition, connector: {
+    position: IPosition;
+}, hitRadius?: number): boolean;
+/**
+ * マウス位置に最も近いコネクターを返す。hitRadius 内のもののみ。
+ */
+export declare function findNearestConnector(mousePos: IPosition, connectors: Array<{
+    position: IPosition;
+}>, hitRadius?: number): {
+    connector: (typeof connectors)[number];
+    distance: number;
+} | null;
+export type EdgeBuilderConfig = {
+    workspace: Workspace;
+    hitRadius?: number;
+    edgeType?: EdgeType;
+    onPreview?: (path: string, from: IPosition, to: IPosition) => void;
+    onComplete?: (edge: Edge) => void;
+    onCancel?: () => void;
+};
+/**
+ * コネクターからドラッグして Edge を作成するビルダー。
+ * Headless 設計に従い DOM 操作なし。
+ */
+export declare class EdgeBuilder {
+    private workspace;
+    private hitRadius;
+    private edgeType;
+    private onPreview?;
+    private onComplete?;
+    private onCancel?;
+    private _active;
+    private _startConnector;
+    private _previewPath;
+    constructor(config: EdgeBuilderConfig);
+    get active(): boolean;
+    get previewPath(): string | null;
+    get startConnector(): Connector | null;
+    /**
+     * ドラッグ開始。出力コネクターからスタート。
+     */
+    start(connector: Connector): void;
+    /**
+     * マウス移動ごとにプレビューパスを更新。
+     */
+    update(mousePos: IPosition): void;
+    /**
+     * 入力コネクターにドロップして Edge を作成。
+     */
+    complete(connector: Connector): void;
+    /**
+     * キャンセル。
+     */
+    cancel(): void;
+    private reset;
+    private computePath;
+}

package/dist/util/edgePath.d.ts

@@ -0,0 +1,24 @@
+import type { IPosition } from '../core/Position';
+export type EdgePathResult = {
+    path: string;
+    labelPosition: IPosition;
+};
+/**
+ * 直線パス。
+ */
+export declare function getStraightPath(start: IPosition, end: IPosition): EdgePathResult;
+/**
+ * ベジェ曲線パス（3次）。
+ * 制御点は始点・終点の中間 X に配置。
+ */
+export declare function getBezierPath(start: IPosition, end: IPosition): EdgePathResult;
+/**
+ * ステップパス（直角折れ線）。
+ * 中間 X で折れる。
+ */
+export declare function getStepPath(start: IPosition, end: IPosition): EdgePathResult;
+/**
+ * スムースステップパス（角丸の折れ線）。
+ * borderRadius で角丸のサイズを制御。
+ */
+export declare function getSmoothStepPath(start: IPosition, end: IPosition, borderRadius?: number): EdgePathResult;

package/dist/util/keyboard.d.ts

@@ -0,0 +1,21 @@
+export type KeyBinding = {
+    key: string;
+    modifiers?: ('ctrl' | 'shift' | 'alt')[];
+    handler: (event: KeyboardEvent) => void;
+};
+/**
+ * キーボードショートカットを管理するクラス。
+ * Ctrl/Meta を統一し、Mac/Windows の互換性を保証する。
+ */
+export declare class KeyboardManager {
+    private bindings;
+    private element;
+    private listener;
+    constructor(element: HTMLElement);
+    bind(binding: KeyBinding): void;
+    unbind(key: string, modifiers?: ('ctrl' | 'shift' | 'alt')[]): void;
+    destroy(): void;
+    private handleKeyDown;
+    private matches;
+    private modifiersMatch;
+}

package/dist/util/marquee.d.ts

@@ -0,0 +1,30 @@
+import type { IPosition } from '../core/Position';
+import type { Viewport } from '../core/types';
+export type MarqueeRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type MarqueeMode = 'full' | 'partial';
+export type MarqueeElement = {
+    id: string;
+    position: IPosition;
+    width: number;
+    height: number;
+};
+/**
+ * 2 点からマーキー矩形を生成する。
+ * どちらの方向にドラッグしても正しい矩形が返る。
+ */
+export declare function createMarqueeRect(start: IPosition, end: IPosition): MarqueeRect;
+/**
+ * マーキー矩形内にある要素をフィルタリングする。
+ * mode: 'full' — 完全に内側にある要素のみ
+ * mode: 'partial' — 一部でも重なる要素を含む
+ */
+export declare function getElementsInMarquee<T extends MarqueeElement>(elements: readonly T[], marquee: MarqueeRect, mode?: MarqueeMode): T[];
+/**
+ * Screen 座標で指定されたマーキーを World 座標に変換してフィルタリングする。
+ */
+export declare function getElementsInScreenMarquee<T extends MarqueeElement>(elements: readonly T[], screenStart: IPosition, screenEnd: IPosition, viewport: Viewport, mode?: MarqueeMode): T[];

package/dist/util/mouse.d.ts

@@ -0,0 +1,16 @@
+import { IPosition } from '../core/Position';
+export declare function getMousePosition(parent: HTMLElement): IPosition;
+export declare function getPositionDelta(currentPosition: IPosition, previousPosition: IPosition): IPosition;
+export type MouseState = {
+    leftButton: 'down' | 'up';
+};
+type getMouseStateProps = {
+    mousedown?: (mouseState: MouseState, mousePosition: IPosition, event: MouseEvent) => void;
+    mouseup?: (mouseState: MouseState, mousePosition: IPosition, event: MouseEvent) => void;
+};
+export type getMouseState = {
+    buttonState: MouseState;
+    mousePosition: IPosition;
+};
+export declare function getMouseState(element: HTMLElement, handlers: getMouseStateProps): getMouseState;
+export {};

package/dist/util/moveContainersGroup.d.ts

@@ -0,0 +1,5 @@
+import Container from '../core/Container';
+export declare function moveGroup(containers: Container[], delta: {
+    x: number;
+    y: number;
+}): void;

package/dist/util/resize.d.ts

@@ -0,0 +1,53 @@
+import type { IPosition } from '../core/Position';
+import type { ResizeHandleDirection } from '../core/types';
+export type ResizableElement = {
+    position: IPosition;
+    width: number;
+    height: number;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+};
+export type ResizeState = {
+    handle: ResizeHandleDirection;
+    startMousePos: IPosition;
+    startBounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+};
+/**
+ * マウス位置が要素のどのリサイズハンドルにヒットしているか判定する。
+ * handleSize は各辺からの判定距離。
+ */
+export declare function detectResizeHandle(mousePos: IPosition, element: {
+    position: IPosition;
+    width: number;
+    height: number;
+}, handleSize?: number): ResizeHandleDirection | null;
+/**
+ * リサイズ開始時の状態を記録する。
+ */
+export declare function beginResize(handle: ResizeHandleDirection, mousePos: IPosition, element: {
+    position: IPosition;
+    width: number;
+    height: number;
+}): ResizeState;
+/**
+ * リサイズを適用し、新しい位置とサイズを返す。
+ * min/max 制約を尊重する。
+ */
+export declare function applyResize(mousePos: IPosition, state: ResizeState, constraints?: {
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+}): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};

package/dist/util/snap.d.ts

@@ -0,0 +1,68 @@
+import { Container, Position } from '../../headless-vpl';
+import { getMouseState } from './mouse';
+import Workspace from '../core/Workspace';
+/**
+ * 接続バリデーター。snap の前に呼ばれ、false を返すと接続を拒否する。
+ */
+export type ConnectionValidator = () => boolean;
+/**
+ * 指定されたソースとターゲットのコネクタ間で、ソースコンテナを動かしてスナップを試みます。
+ *
+ * @param source ソースコンテナ（スナップ対象）
+ * @param sourcePosition ソースの座標
+ * @param targetPosition ターゲットの座標
+ * @param mouseState 現在のマウス状態。左ボタンが 'up' の場合にのみスナップを試みる。
+ * @param snapDistance スナップを発動する距離の閾値
+ * @param onSnap スナップが成功した場合に実行するコールバック
+ * @param onFail スナップが失敗した場合に実行するコールバック
+ * @param validator 接続の可否を判定するバリデーター
+ * @returns スナップが実行された場合は true を返します。
+ */
+export declare function snap(source: Container, sourcePosition: Position, targetPosition: Position, mouseState: getMouseState, snapDistance?: number, onSnap?: () => void, onFail?: () => void, validator?: ConnectionValidator): boolean;
+/**
+ * スナップを試みるかどうかの判定関数。
+ * source（子）と target（親）のどちらがドラッグされているかで制御できる。
+ */
+export type SnapStrategy = (source: Container, target: Container, dragContainers: Container[]) => boolean;
+/** デフォルト: 子（source）が親に近づいた時だけスナップ */
+export declare const childOnly: SnapStrategy;
+/** 親（target）が子に近づいた時だけスナップ */
+export declare const parentOnly: SnapStrategy;
+/** どちらが近づいてもスナップ */
+export declare const either: SnapStrategy;
+export type SnapConnectionConfig = {
+    source: Container;
+    sourcePosition: Position;
+    target: Container;
+    targetPosition: Position;
+    workspace: Workspace;
+    snapDistance?: number;
+    strategy?: SnapStrategy;
+    validator?: ConnectionValidator;
+};
+/**
+ * スナップ接続の状態管理を統合するクラス。
+ * snap() + SnapStrategy + Parent/Children 管理 + イベント発火をまとめる。
+ */
+export declare class SnapConnection {
+    readonly source: Container;
+    readonly sourcePosition: Position;
+    readonly target: Container;
+    readonly targetPosition: Position;
+    readonly workspace: Workspace;
+    readonly snapDistance: number;
+    readonly strategy: SnapStrategy;
+    readonly validator?: ConnectionValidator;
+    private _locked;
+    private _hasFailed;
+    private _destroyed;
+    private _lastDragContainers;
+    constructor(config: SnapConnectionConfig);
+    get locked(): boolean;
+    get destroyed(): boolean;
+    destroy(): void;
+    tick(mouseState: getMouseState, dragContainers: Container[]): void;
+    unlock(): void;
+    private onSnap;
+    private onFail;
+}

package/dist/util/snapToGrid.d.ts

@@ -0,0 +1,10 @@
+import type { IPosition } from '../core/Position';
+/**
+ * 座標をグリッドの倍数に丸める。
+ */
+export declare function snapToGrid(position: IPosition, gridSize: number): IPosition;
+/**
+ * 移動量をグリッドの倍数に丸める。
+ * DnD の delta 前処理として使う。
+ */
+export declare function snapDeltaToGrid(delta: IPosition, gridSize: number): IPosition;

package/dist/util/viewport.d.ts

@@ -0,0 +1,4 @@
+import type { IPosition } from '../core/Position';
+import type { Viewport } from '../core/types';
+export declare function screenToWorld(screen: IPosition, viewport: Viewport): IPosition;
+export declare function worldToScreen(world: IPosition, viewport: Viewport): IPosition;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "headless-vpl",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A headless library for building visual programming languages",
+  "module": "./dist/headless-vpl.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/headless-vpl.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "visual-programming",
+    "vpl",
+    "headless",
+    "drag-and-drop",
+    "node-editor",
+    "block-programming"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/headless-vpl/headless-vpl"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "build:lib": "vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json",
+    "prepublishOnly": "npm run build:lib",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.19.0",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react-swc": "^3.5.0",
+    "eslint": "^9.19.0",
+    "eslint-plugin-react-hooks": "^5.0.0",
+    "eslint-plugin-react-refresh": "^0.4.18",
+    "globals": "^15.14.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "~5.7.2",
+    "typescript-eslint": "^8.22.0",
+    "vite": "^6.1.0"
+  }
+}