@orbat-mapper/tactical-draw 0.2.0-alpha.4 → 0.2.0-alpha.6

package/dist/index.d.mts

@@ -165,6 +165,15 @@ interface MapAdapter {
   onPick(layerId: LayerId, handler: PickHandler, opts?: PickOptions): () => void;
   /**
    * Map Event Listeners
+   *
+   * Ordering contract: a `"click"` handler and the `onPick` handlers for the
+   * same user click MUST observe the pick first — adapters deliver picks and
+   * `"click"` from the same underlying engine event, in registration order.
+   * The draw/edit controllers register their pick subscriptions before their
+   * click handler and read the stashed pick inside it (click-away close /
+   * close-then-pick re-dispatch); an adapter that fires `"click"` from an
+   * earlier engine event than its picks breaks that contract (e.g. OL
+   * `click` vs `singleclick`).
    */
   on(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
   off(eventType: "click" | "pointermove" | "dblclick", handler: MapEventHandler): void;
@@ -437,9 +446,10 @@ declare function getSizeAnchor(measure: Pick<ControlMeasure, "kind" | "options">
 //#endregion
 //#region src/tactical-draw/handles.d.ts
 /**
- * Line-only style surface for the rubber-band guide (ADR-0004). Slot inside
- * `InteractionStyle.guide`. Applied as the guide layer's layer style by the
- * façade; not per-feature.
+ * Line-only style surface for the rubber-band guide (ADR-0004) and the
+ * transform-box outline. Slot inside `InteractionStyle.guide` /
+ * `InteractionStyle.boxOutline`. Applied as a layer style for the guide, and
+ * per-feature (`properties.style`) for the box outline — see ADR-0017.
  */
 interface GuideStyle {
   strokeColor?: string;
@@ -447,25 +457,38 @@ interface GuideStyle {
   strokeDash?: readonly number[];
 }
 /**
- * Unified interaction-affordance style surface (ADR-0006). One option object
- * for both the guide line and every handle slot. `guide` is delivered as a
- * layer style; handle slots ride per-feature on `properties.style`.
+ * Unified interaction-affordance style surface (ADR-0006, extended by
+ * ADR-0017 for the transform box). One option object for the guide line,
+ * the box outline, and every handle slot. `guide` and `boxOutline` are line
+ * styles; handle slots ride per-feature on `properties.style`.
  */
 interface InteractionStyle {
   guide?: GuideStyle;
   vertexHandle?: HandleStyle;
   midpointHandle?: HandleStyle;
-  translateHandle?: HandleStyle;
+  scaleHandle?: HandleStyle;
   rotateHandle?: HandleStyle;
+  boxOutline?: GuideStyle;
+  /**
+   * Pixel padding added on every side of the fitted transform box
+   * (`fitTransformBox`, ADR-0017) so the box doesn't tightly hug the rendered
+   * geometry. Default `0`. A scalar, not a style object, but it participates
+   * in the same built-in → façade → per-call resolution slot system as every
+   * other `InteractionStyle` field (see `TacticalDraw.resolveInteractionStyle`).
+   */
+  boxPadding?: number;
 }
 /**
- * Reserved enum from PRD #40. `reshape`, `translate`, and `rotate` produce
- * handles. `delete` is an explicit destructive mode: it renders the vertex
- * handles (so they can be tapped to remove) but no midpoint/translate/rotate
- * grips, and the edit controller deletes the tapped vertex instead of dragging
- * it. `scale` is reserved and throws elsewhere.
+ * Reserved enum from PRD #40, replaced under ADR-0017 by the transform-box UI.
+ * `reshape` renders vertex/midpoint handles; `transform` renders the oriented
+ * selection box (4 corner scale handles + a rotate grip + drag-anywhere
+ * body translate) via `transform-box.ts`. The two can be combined freely —
+ * single-measure edits show both by default. `delete` is an explicit
+ * destructive mode: it renders the vertex handles (so they can be tapped to
+ * remove) but no midpoints or box, and the edit controller deletes the tapped
+ * vertex instead of dragging it.
  */
-type EditMode = "reshape" | "translate" | "rotate" | "scale" | "delete";
+type EditMode = "reshape" | "transform" | "delete";
 //#endregion
 //#region src/tactical-draw/edit-session.d.ts
 /**
@@ -502,9 +525,11 @@ interface EditSession {
   /** Reject the outer `edit` promise with reason `"session"`. */
   abort(): void;
   /**
-   * Switch the active edit-mode set. `"reshape"`, `"translate"`, and `"rotate"`
-   * produce handles; `"delete"` is exclusive (vertex-tap removal) and collapses
-   * the set to delete-only. `"scale"` is rejected with `TypeError` per PRD #40.
+   * Switch the active edit-mode set. `"reshape"` produces vertex/midpoint
+   * handles; `"transform"` renders the oriented selection box (corner scale
+   * handles, rotate grip, body translate — ADR-0017); `"delete"` is exclusive
+   * (vertex-tap removal) and collapses the set to delete-only. An unknown mode
+   * is rejected with `TypeError`.
    */
   setModes(modes: readonly EditMode[]): void;
   /** Shallow-merge per-measure generator options into the live working copy. */
@@ -558,6 +583,84 @@ interface EditChangeEvent {
   abort(): void;
 }
 //#endregion
+//#region src/tactical-draw/transform-session.d.ts
+/**
+ * Surface delivered via `td.editMany(measures, opts).onSession` and
+ * synchronously available from `td.activeTransformSession` while the group
+ * transform is live. The group sibling of `EditSession` (`edit-session.ts`):
+ * no reshape, no per-measure `setOptions`/`setStyle` — only the shared
+ * transform box's corner-scale / rotate / body-translate gestures, applied to
+ * every member at once. See the Phase 3 ("Multi-select") slice of ADR-0017.
+ *
+ * `measures` is the immutable edit-start input, index-aligned with every
+ * snapshot array this session or its change events produce. After the
+ * session settles (`close` / `abort`), every method is a silent no-op.
+ */
+interface TransformSession {
+  /** Immutable edit-start inputs, index-aligned with every snapshot array. */
+  readonly measures: readonly ControlMeasure[];
+  /**
+   * Live working control points for the member whose id is `measureId`, or
+   * `undefined` when no member carries that id. Copy on read.
+   */
+  controlPointsFor(measureId: string): readonly Position[] | undefined;
+  /** `true` when any member's working points differ from its edit-start input beyond tolerance. */
+  readonly dirty: boolean;
+  /**
+   * Live size anchor, applied group-wide (ADR-0020). `"ground"` bakes each
+   * member's pixel size to meters on commit; `"screen"` keeps it zoom-aware.
+   * Initialised from `EditManyOptions.sizeAnchor` and mutated by [[setSizeAnchor]].
+   */
+  readonly sizeAnchor: SizeAnchor;
+  /** Switch the group's size anchor (ADR-0020). Takes effect on the next emitted snapshot and on `close()`. */
+  setSizeAnchor(anchor: SizeAnchor): void;
+  /**
+   * Resolve the outer `editMany` promise with index-aligned
+   * `ControlMeasureSnapshot[]` of the current working state.
+   */
+  close(): void;
+  /** Reject the outer `editMany` promise with reason `"session"`. */
+  abort(): void;
+  /**
+   * Subscribe to working-copy changes. The listener receives a
+   * [[TransformChangeEvent]] for each completed group gesture (corner scale,
+   * rotate, or body-translate drag end) — never on rubber-band ticks. All
+   * currently-registered listeners receive the same event instance, in
+   * registration order.
+   *
+   * Listener exceptions are collected; after every listener has run, they are
+   * rethrown (one if single, aggregated otherwise). `event.reject()` /
+   * `event.close()` / `event.abort()` take effect only after all listeners
+   * have run — mirrors `EditSession.onChange` (issue #49).
+   */
+  onChange(listener: (event: TransformChangeEvent) => void): () => void;
+}
+/**
+ * Delivered to `TransformSession.onChange` listeners once per completed group
+ * gesture. Both `measures` and `previous` are index-aligned with
+ * `session.measures`. See `EditChangeEvent` for the identical emission
+ * contract this mirrors.
+ */
+interface TransformChangeEvent {
+  /** Working state after the completed gesture, index-aligned with `session.measures`. */
+  readonly measures: ControlMeasureSnapshot[];
+  /** State immediately before this gesture, index-aligned with `session.measures`. */
+  readonly previous: ControlMeasureSnapshot[];
+  /** The session the event belongs to. */
+  readonly session: TransformSession;
+  /**
+   * Roll every member's working preview back to `previous` after all
+   * listeners have run. Multiple calls collapse to a single rollback.
+   * Overridden by `close()` or `abort()` if either is also called during this
+   * emission.
+   */
+  reject(): void;
+  /** Shortcut for `event.session.close()`, deferred until the emission ends. */
+  close(): void;
+  /** Shortcut for `event.session.abort()`, deferred until the emission ends. */
+  abort(): void;
+}
+//#endregion
 //#region src/tactical-draw/session.d.ts
 /**
  * Scoped surface delivered via `td.draw({ onSession })` for variable-length
@@ -637,11 +740,12 @@ interface EditOptions {
    */
   closeOnClickAway?: boolean;
   /**
-   * Active edit modes. Defaults to `["reshape"]`. `reshape` renders vertex /
-   * midpoint handles; `translate` renders a grip on the centroid pivot; and
-   * `rotate` renders a grip offset just outside the shape (so it has a lever
-   * arm and orbits with the geometry). The three can be combined freely.
-   * `"scale"` is reserved and throws.
+   * Active edit modes. Defaults to `["reshape", "transform"]`. `reshape`
+   * renders vertex / midpoint handles; `transform` renders the oriented
+   * selection box — 4 corner scale handles, a rotate grip above the top edge,
+   * and drag-anywhere-inside-the-box translate (ADR-0017). The two can be
+   * combined freely (the default does). `"delete"` is exclusive: it collapses
+   * the set to vertex-tap removal only. An unknown mode throws `TypeError`.
    */
   modes?: readonly EditMode[];
   /**
@@ -669,6 +773,32 @@ interface EditOptions {
    */
   sizeAnchor?: SizeAnchor;
 }
+/**
+ * Options for `TacticalDraw.editMany` — the multi-select group transform
+ * (ADR-0017 "Multi-select" slice). Leaner than `EditOptions`: there is no
+ * `modes` (a group transform is always the oriented box — no reshape), no
+ * `guide` (no rubber-band content for a group), and no per-measure `setOptions`
+ * / `setStyle` surface on the resulting session.
+ */
+interface EditManyOptions {
+  signal?: AbortSignal;
+  /**
+   * Called synchronously once when the group transform starts, before any
+   * pointer event is processed. Lets a host wire Done/Cancel/Delete buttons to
+   * the active session.
+   */
+  onSession?: (session: TransformSession) => void;
+  /**
+   * Default `true`. When `true`, a click on empty map (or on a graphics-layer
+   * measure outside the group) closes the active transform. Clicks on preview
+   * / handle features are consumed and keep it open.
+   */
+  closeOnClickAway?: boolean;
+  /** Per-call interaction style override scoped to this transform. See ADR-0006. */
+  interactionStyle?: InteractionStyle;
+  /** Size anchor for the committed measures (ADR-0020), applied group-wide. Default `"ground"`. */
+  sizeAnchor?: SizeAnchor;
+}
 /**
  * Draft control measure handed to `TacticalDraw.draw`. `kind` is required up
  * front so the façade can resolve metadata, draw rule, and controller choice
@@ -746,6 +876,20 @@ declare class TacticalDraw {
    * `EditHandle` so the controller stays the single owner of edit state.
    */
   private activeEdit;
+  /**
+   * Tracked alongside `activeInteraction` whenever the interaction is a group
+   * transform (`editMany`). The `render()` / view-change paths need every
+   * member's id (to exclude all of them from reconcile) — mirrors `activeEdit`
+   * but for `TransformHandle`'s `measureIds` array.
+   */
+  private activeTransform;
+  /**
+   * The live `TransformSession`, exposed via `activeTransformSession`. Set
+   * directly by `editMany`'s `onSession` wrapper (not routed through
+   * `ActiveInteractionTracker.session`, whose type is `DrawSession | EditSession`)
+   * and cleared on settle.
+   */
+  private activeTransformSessionRef;
   /**
    * Host pick handlers registered via `td.onPick` / `td.onMeasurePick`. The
    * façade subscribes once to `adapter.onPick` per layer and routes events
@@ -764,6 +908,7 @@ declare class TacticalDraw {
   private deferredGraphicsPick;
   private idCounter;
   private editCounter;
+  private transformCounter;
   /**
    * Snapshot of the host's last `render()` argument. The edit slice uses it
    * to recompute the graphics-layer state during a lift / restore — the
@@ -789,6 +934,13 @@ declare class TacticalDraw {
    * as in `render()`; the preview's own view-change subscription rescales it.
    */
   private readonly handleViewChange;
+  /**
+   * Every measure id currently lifted onto the preview layer by an active
+   * edit or group transform — excluded from `render()` / view-change
+   * reconciliation because the preview layer (not graphics) owns their
+   * working copy. Empty while idle.
+   */
+  private excludedInteractionIds;
   /**
    * Reconcile the graphics layer against the authoritative list of measures.
    * Idempotent. Throws synchronously on duplicate measure ids *before*
@@ -841,6 +993,13 @@ declare class TacticalDraw {
    * (exposing it via `activeSession`) before the host's own handler runs.
    */
   private trackSession;
+  /**
+   * Wrap a host `onSession` callback for `editMany`, recording the session on
+   * `activeTransformSessionRef` (exposed via `activeTransformSession`) before
+   * the host's own handler runs. Separate from `trackSession` because
+   * `ActiveInteractionTracker.session` is typed `DrawSession | EditSession`.
+   */
+  private trackTransformSession;
   /**
    * Start an interactive draw. Fixed-length kinds commit automatically on the
    * last required click. Variable-length kinds surface a `DrawSession` via
@@ -860,6 +1019,20 @@ declare class TacticalDraw {
    * `false`.
    */
   edit(measure: ControlMeasure, options?: EditOptions): Promise<ControlMeasureSnapshot>;
+  /**
+   * Start an interactive group transform (multi-select) over `measures`
+   * (ADR-0017 "Multi-select" slice). Every member is lifted onto the shared
+   * preview layer; the box (corner scale, rotate grip, drag-anywhere body
+   * translate) applies rigidly to all of them at once. Returns a Promise that
+   * resolves with index-aligned `ControlMeasureSnapshot[]` on
+   * `session.close()` and rejects with `TacticalDrawAbortError` on
+   * signal / Escape / destroy / preempt / `session.abort()`.
+   *
+   * `measures.length` must be >= 1; a single-element array behaves like an
+   * `edit` with only `transform` mode. Throws `TypeError` synchronously (before
+   * any preemption) for an empty array or duplicate ids.
+   */
+  editMany(measures: ControlMeasure[], options?: EditManyOptions): Promise<ControlMeasureSnapshot[]>;
   /**
    * Subscribe to picks on committed control measures.
    *
@@ -895,6 +1068,13 @@ declare class TacticalDraw {
    * fixed-length draws. Safe to read after `destroy()`.
    */
   get activeSession(): DrawSession | EditSession | null;
+  /**
+   * The live `editMany` group-transform session, or `null` while idle (and
+   * during any other interaction). Separate from `activeSession` because
+   * `TransformSession` isn't part of its `DrawSession | EditSession` union —
+   * see `activeTransformSessionRef`. Safe to read after `destroy()`.
+   */
+  get activeTransformSession(): TransformSession | null;
   /**
    * Tear down the façade. Releases only layer slots the façade created; host
    * supplied layer ids are left untouched. Safe to call multiple times. After
@@ -926,9 +1106,19 @@ declare class TacticalDraw {
   private applyGuideStyle;
   private baseGuideStyle;
   /**
-   * Resolve handle slots across built-in → façade → per-call with per-slot,
-   * per-property shallow merge. Explicit `undefined` at a higher-priority
-   * layer unsets the corresponding lower-priority field (ADR-0006).
+   * Resolve handle slots (plus `boxOutline`) across built-in → façade →
+   * per-call with per-slot, per-property shallow merge. Explicit `undefined`
+   * at a higher-priority layer unsets the corresponding lower-priority field
+   * (ADR-0006). `boxOutline` rides this same per-feature merge path (not the
+   * `guide` layer-style path) — the edit controller reads it off
+   * `properties.style` on the box outline `LineString` (ADR-0017).
+   *
+   * `boxPadding` is a scalar, not a mergeable style object, so it resolves
+   * separately with the same façade → per-call precedence and the same
+   * explicit-undefined-wins rule: a `boxPadding` key present at a
+   * higher-priority layer (even set to `undefined`) wins over a lower layer's
+   * value. There is no built-in `boxPadding` — an absent value at every layer
+   * falls through to the controllers' own `?? 0` default.
    *
    * Returns `undefined` only when no slot would carry any value — keeps the
    * downstream "no style on the feature" path intact for tests that assert
@@ -947,4 +1137,52 @@ declare class TacticalDrawDestroyedError extends Error {
   constructor(message?: string);
 }
 //#endregion
-export { BaseMapAdapter, type CombinedAbort, type DrawMeasureDraft, type DrawOptions, type DrawSession, type EditChangeEvent, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type GuideStyle, type HandleStyle, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SizeAnchor, type StyleOptions, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextStyleOptions, type ToPixel, bindAbortable, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, ignoreAbort, isTacticalDrawAbortError, pickHitTolerance, tryControlMeasureIdFromFeature };
+//#region src/tactical-draw/transform-box.d.ts
+/**
+ * The Excalidraw/Felt-style transform box: the oriented bounding box drawn
+ * around a selection, with 4 corner scale handles, a rotate grip above the
+ * top edge, and drag-anywhere-inside-the-box translate. This module is the
+ * single source of truth for box *placement* (`fitTransformBox`,
+ * `boxCorners`, `rotateGripPixel`) AND box *picking* (`pointInBox`,
+ * `pickBoxHandle`) — mirroring the ADR-0016 discipline that keeps
+ * `handles.ts` owning vertex/midpoint placement/pick. Everything here is pure
+ * pixel-space math: no projection, no rendering, no session state.
+ *
+ * **Angle convention**: `angle` is in radians, measured in screen pixel space
+ * (y grows downward). A positive angle rotates the box clockwise as drawn on
+ * screen — the same convention `rotatePointsAround` (`handle-drag.ts`) uses,
+ * so box rotation and control-point rotation stay in lockstep.
+ *
+ * **Corner ordering**: `boxCorners` always returns
+ * `[topLeft, topRight, bottomRight, bottomLeft]` in the box's own (unrotated)
+ * local frame, then rotated into place. "Top" means the smaller-y edge before
+ * rotation — i.e. the edge the rotate grip floats above. The order is stable
+ * across calls so a scale handle's `index` (0–3) always means the same
+ * corner, and its opposite corner is always `(index + 2) % 4`.
+ */
+interface TransformBox {
+  /** Box center, pixel space. */
+  center: PixelCoordinate;
+  /** Half-width along the box's local x-axis (pre-rotation), in pixels. */
+  halfWidth: number;
+  /** Half-height along the box's local y-axis (pre-rotation), in pixels. */
+  halfHeight: number;
+  /** Radians, screen space, positive = clockwise on screen. */
+  angle: number;
+}
+//#endregion
+//#region src/world-wrap.d.ts
+/**
+ * Shift `lng` by whole world widths (360°) onto the copy nearest `refLng`.
+ *
+ * Map engines that wrap pointer longitudes into [-180, 180] (OpenLayers'
+ * `toLonLat`, MapLibre's globe unproject) make positions jump ~360° when a
+ * gesture crosses the antimeridian. Adapters use this to keep delivered
+ * longitudes continuous with the view center, and to project coordinates on
+ * the world copy the view is actually looking at.
+ */
+declare function nearestWorldCopyLng(lng: number, refLng: number): number;
+/** `nearestWorldCopyLng` applied to a lon/lat position. */
+declare function nearestWorldCopyPosition(position: Position, refLng: number): Position;
+//#endregion
+export { BaseMapAdapter, type CombinedAbort, type DrawMeasureDraft, type DrawOptions, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type GuideStyle, type HandleStyle, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SizeAnchor, type StyleOptions, TOUCH_HIT_TOLERANCE_PX, TacticalDraw, TacticalDrawAbortError, type TacticalDrawAbortReason, TacticalDrawDestroyedError, type TacticalDrawLayerOptions, type TacticalDrawOptions, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, bindAbortable, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, ignoreAbort, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, tryControlMeasureIdFromFeature };