@edv4h/usketch-plugin-free-position 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EdV4H
+
+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,46 @@
+# @edv4h/usketch-plugin-free-position
+
+指定した位置から**最も近い、既存 shape と被らない位置**を求める機能を提供するプラグイン（Issue #581）。
+貼り付け/複製/ドロップ/AI 生成などで新規 shape を重ねずに配置したいときに使う。UI は持たない。
+
+## 使い方
+
+```ts
+import { createFreePositionPlugin } from "@edv4h/usketch-plugin-free-position";
+
+const plugins = [
+  // ...
+  createFreePositionPlugin({ strategy: "ring" }), // "ring"（既定）| "push"
+];
+```
+
+登録すると、`free-position:find` イベントで問い合わせできる（snap の `snap:get-settings` と同じ
+同期コールバック方式）:
+
+```ts
+import type { BoundingBox } from "@edv4h/usketch-shared";
+
+let result: BoundingBox | undefined;
+ctx.events.emit("free-position:find", {
+  desired: { x, y, width, height },   // 置きたい位置・サイズ
+  excludeIds: ["shape-1"],            // 任意: 衝突判定から除外（移動対象自身など）
+  strategy: "push",                   // 任意: このリクエストだけ戦略を上書き
+  onResult: (free) => { result = free; },
+});
+// result が「最も近い空き位置」（同サイズ）。プラグイン未登録なら onResult は呼ばれない。
+```
+
+## 探索戦略
+
+- **ring**（既定）: desired 中心から同心リングを外へ広げ、衝突しない最近傍を返す。
+- **push**: desired を起点に、重なる相手から最小重なり軸方向へ押し出して分離する。
+
+回転した shape は `getRotatedAABB` で外接矩形にして衝突判定する。
+
+## 連携
+
+`@edv4h/usketch-plugin-keyboard-shortcuts` の paste/duplicate はこのイベントを使い、複数 shape を
+相対配置を保ったままグループ単位で空き位置へずらす（本プラグイン未登録時は従来の +20 オフセット）。
+drop など他の配置経路も同じイベントを呼べば利用できる。
+
+純ロジックは `@edv4h/usketch-shape-utils` の `findFreePosition` / `overlapsAny` として単体でも使える。

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createFreePositionPlugin, type FreePositionConfig, type FreePositionRequest, } from "./plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createFreePositionPlugin, } from "./plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,wBAAwB,GAGxB,MAAM,aAAa,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,33 @@
+import { type FreePositionStrategy } from "@edv4h/usketch-shape-utils";
+import { type BoundingBox, type UsketchPlugin } from "@edv4h/usketch-shared";
+export interface FreePositionConfig {
+    /** 既定の探索戦略（"ring" | "push"、既定 "ring"）。 */
+    strategy?: FreePositionStrategy;
+    /** ring の半径刻み（world px）。 */
+    step?: number;
+    /** ring の探索上限距離（world px）。 */
+    maxDistance?: number;
+    /** push の反復上限。 */
+    maxIterations?: number;
+}
+/**
+ * `free-position:find` リクエストのペイロード。
+ * snap の `snap:get-settings` と同様、同期コールバック（`onResult`）で結果を返す。
+ */
+export interface FreePositionRequest {
+    /** 置きたい位置・サイズ（回転 shape は回転後 AABB を渡す）。 */
+    desired: BoundingBox;
+    /** 衝突判定から除外する shape ID（移動対象自身など）。 */
+    excludeIds?: string[];
+    /** この問い合わせ限定の戦略上書き。 */
+    strategy?: FreePositionStrategy;
+    /** 結果（同サイズの空き位置）を受け取るコールバック。 */
+    onResult: (free: BoundingBox) => void;
+}
+/**
+ * 指定位置から最も近い「被らない位置」を求める機能を提供するプラグイン（#581）。
+ * EventBus の `free-position:find` で問い合わせると、現在のボード上の shape（回転考慮 AABB）を
+ * 避けた最近傍の空き位置を返す。UI は持たない。
+ */
+export declare function createFreePositionPlugin(config?: FreePositionConfig): UsketchPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAAoB,MAAM,4BAA4B,CAAC;AACzF,OAAO,EACN,KAAK,WAAW,EAIhB,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,kBAAkB;IAClC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,0CAA0C;IAC1C,OAAO,EAAE,WAAW,CAAC;IACrB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,uBAAuB;IACvB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,gCAAgC;IAChC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,GAAE,kBAAuB,GAAG,aAAa,CAoCvF"}

package/dist/plugin.js

@@ -0,0 +1,43 @@
+import { findFreePosition } from "@edv4h/usketch-shape-utils";
+import { getRotatedAABB, safeRotation, } from "@edv4h/usketch-shared";
+/**
+ * 指定位置から最も近い「被らない位置」を求める機能を提供するプラグイン（#581）。
+ * EventBus の `free-position:find` で問い合わせると、現在のボード上の shape（回転考慮 AABB）を
+ * 避けた最近傍の空き位置を返す。UI は持たない。
+ */
+export function createFreePositionPlugin(config = {}) {
+    return {
+        id: "usketch-plugin-free-position",
+        name: "Free Position",
+        setup(ctx) {
+            function collectOccupied(exclude) {
+                const ex = exclude && exclude.length > 0 ? new Set(exclude) : null;
+                const out = [];
+                for (const [id, shape] of ctx.store.getShapes()) {
+                    if (ex?.has(id))
+                        continue;
+                    const def = ctx.shapes.get(shape.type);
+                    const bounds = def
+                        ? def.getBounds(shape)
+                        : { x: shape.x, y: shape.y, width: shape.width, height: shape.height };
+                    const rotation = safeRotation(shape.rotation);
+                    out.push(rotation ? getRotatedAABB(bounds, rotation) : bounds);
+                }
+                return out;
+            }
+            const off = ctx.events.on("free-position:find", (req) => {
+                const free = findFreePosition({
+                    desired: req.desired,
+                    occupied: collectOccupied(req.excludeIds),
+                    strategy: req.strategy ?? config.strategy,
+                    step: config.step,
+                    maxDistance: config.maxDistance,
+                    maxIterations: config.maxIterations,
+                });
+                req.onResult(free);
+            });
+            return () => off();
+        },
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAEN,cAAc,EAEd,YAAY,GAEZ,MAAM,uBAAuB,CAAC;AA4B/B;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAA6B,EAAE;IACvE,OAAO;QACN,EAAE,EAAE,8BAA8B;QAClC,IAAI,EAAE,eAAe;QAErB,KAAK,CAAC,GAAkB;YACvB,SAAS,eAAe,CAAC,OAAkB;gBAC1C,MAAM,EAAE,GAAG,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;gBACnE,MAAM,GAAG,GAAkB,EAAE,CAAC;gBAC9B,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,CAAC;oBACjD,IAAI,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC;wBAAE,SAAS;oBAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;oBACvC,MAAM,MAAM,GAAG,GAAG;wBACjB,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,CAAC;wBACtB,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;oBACxE,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;oBAC9C,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;gBAChE,CAAC;gBACD,OAAO,GAAG,CAAC;YACZ,CAAC;YAED,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,EAAE,CAAsB,oBAAoB,EAAE,CAAC,GAAG,EAAE,EAAE;gBAC5E,MAAM,IAAI,GAAG,gBAAgB,CAAC;oBAC7B,OAAO,EAAE,GAAG,CAAC,OAAO;oBACpB,QAAQ,EAAE,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC;oBACzC,QAAQ,EAAE,GAAG,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;oBACzC,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,WAAW,EAAE,MAAM,CAAC,WAAW;oBAC/B,aAAa,EAAE,MAAM,CAAC,aAAa;iBACnC,CAAC,CAAC;gBACH,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACpB,CAAC,CAAC,CAAC;YAEH,OAAO,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC;QACpB,CAAC;KACD,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@edv4h/usketch-plugin-free-position",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@edv4h/usketch-shape-utils": "2.1.0",
+    "@edv4h/usketch-shared": "4.2.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EdV4H/usketch.git",
+    "directory": "plugins/usketch-plugin-free-position"
+  },
+  "homepage": "https://github.com/EdV4H/usketch#readme",
+  "bugs": {
+    "url": "https://github.com/EdV4H/usketch/issues"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist"
+  }
+}