@orbat-mapper/tactical-draw 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orbat Mapper
+
+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,95 @@
+# @orbat-mapper/tactical-draw
+
+The engine-agnostic draw/edit core for the `@orbat-mapper` tactical graphics
+toolkit. It hosts the rubber-band draw/edit controllers, sessions, and
+draw-rule plumbing, the
+`MapAdapter` contract and base adapter, pixel-space hit-testing and the
+`EditPointerDriver` pointer contract, handle rendering, interaction styles, and
+pick helpers.
+
+It depends only on `@orbat-mapper/control-measures` and `geojson` — never on a
+concrete map engine. This is the **bring-your-own-engine** entry point: pair it
+with one of the engine adapter packages, or implement `MapAdapter` yourself.
+
+## Installation
+
+```bash
+# npm
+npm install @orbat-mapper/tactical-draw @orbat-mapper/control-measures
+
+# pnpm
+pnpm add @orbat-mapper/tactical-draw @orbat-mapper/control-measures
+```
+
+Then add an engine adapter (or implement `MapAdapter` against your own engine):
+
+```bash
+# pick one — npm
+npm install @orbat-mapper/tactical-draw-adapter-openlayers ol
+npm install @orbat-mapper/tactical-draw-adapter-maplibre maplibre-gl
+npm install @orbat-mapper/tactical-draw-adapter-leaflet leaflet
+
+# pick one — pnpm
+pnpm add @orbat-mapper/tactical-draw-adapter-openlayers ol
+pnpm add @orbat-mapper/tactical-draw-adapter-maplibre maplibre-gl
+pnpm add @orbat-mapper/tactical-draw-adapter-leaflet leaflet
+```
+
+## What's inside
+
+- **`TacticalDraw`** — the draw/edit controller hosting draw and edit sessions
+  driven by per-measure draw rules.
+- **`MapAdapter`** — the type-only ABI every engine adapter implements, plus
+  **`BaseMapAdapter`** with the shared implementation to extend.
+- **Hit-testing & pointer driver** — pixel-space `hitTestFeature`, hit
+  tolerances, and the `EditPointerDriver` contract adapters implement for the
+  edit controller.
+- **Interaction styles** — `coerceHandleStyle` and the `InteractionStyle` /
+  `GuideStyle` / `HandleStyle` shapes. (Handle _rendering_ itself is not part of
+  the public API.)
+- **Pick helpers** — hit tolerance and control-measure identification utilities.
+
+## Pick to edit
+
+Use `onMeasurePick` to subscribe to committed control measures without accessing
+internal layer ids:
+
+```ts
+const unsubscribe = td.onMeasurePick((event) => {
+  const measure = measures.find((candidate) => candidate.id === event.id);
+  if (measure) void td.edit(measure);
+});
+```
+
+The handler receives the full `PickEvent`, with `event.id` set to the control
+measure id. The returned unsubscribe function is idempotent, and
+`onMeasurePick(handler, { signal })` also supports abort-driven teardown.
+
+## Cancel and inspect the active interaction
+
+Use `cancel()` for a host Cancel button. It aborts draws and edits, including
+fixed-length draws that do not expose a session:
+
+```ts
+cancelButton.onclick = () => td.cancel();
+```
+
+`activeSession` exposes the live `DrawSession` or `EditSession` when one exists,
+and returns `null` while idle or during a fixed-length draw:
+
+```ts
+const session = td.activeSession;
+if (session && "canCommit" in session) {
+  doneButton.disabled = !session.canCommit;
+}
+```
+
+## Bring your own engine
+
+Implement `MapAdapter` (or extend `BaseMapAdapter`) against your map engine and
+hand it to `TacticalDraw`. Everything above the adapter — controllers, sessions,
+gestures, handle rendering — works unchanged.
+
+## License
+
+MIT