🚧 These docs are a work in progress — content is incomplete and may change without notice.
Tactical Graphics

Appearance

Draw a control measure ​

draw(draft, options?) starts an interactive draw and resolves on commit with { graphic, render }. The graphic is a defensive copy, so you can safely add it to your application state.

Choose a control measure, select Draw, then select points on the map.

Loading map…
ts
const { graphic } = await td.draw({
  kind: "block",
  style: { color: "#dc2626", strokeWidth: 3 },
  properties: { source: "toolbar" }, // your metadata, copied onto the committed measure
});

measures.push(graphic);
td.render(measures);

The draft ​

Only kind is required. You may also provide id, controlPoints, options, style, and properties. TacticalDraw generates a missing ID. For variable-length kinds, controlPoints seeds the draw with existing points. The TypeScript type is DrawMeasureDraft<K>.

Commit behaviour ​

Fixed-length kinds commit as soon as the user places the final required point (minCoordinates === maxCoordinates). Examples include Block, Disrupt, Attack-By-Fire, Support-By-Fire, and Obstacle-Bypass.

Variable-length kinds commit after one of these actions:

  • Call session.commit().
  • Double-click the map.
  • Select the last point again.

Double-click zoom is disabled during the draw and restored when it ends.

See Variable-length draw with Done / Cancel buttons for wiring a commit UI.

The session ​

Use options.onSession to receive the DrawSession for either kind of draw. It exposes controlPoints, commit(), abort(), and the subscriptions below. You can also read the live session from td.activeSession.

onCommit and onSettled ​

session.onCommit(handler) runs synchronously once when the draw commits, whether by session.commit(), double-click, selecting the last point again, or placing the final point of a fixed-length kind. It receives the same snapshot as the draw() promise and does not run after an abort.

session.onSettled(handler) runs once after either commit or abort, after onCommit and after td.activeSession becomes null. A late subscription runs asynchronously. EditSession follows the same timing.

onTransientChange ​

session.onTransientChange(listener) reports live geometry for every rubber-band pointer movement:

  • points — the working control points, with the live point included.
  • pointIndex — the index of the live point in points.
  • phase — "start" on the first movement, "move" on later movements, and "end" once when the session settles.

Measurements are not precomputed. Derive them from points; for example, haversineDistance from @orbat-mapper/control-measures returns ground distance in meters. See Show a live radius for a full example.

DrawOptions ​

FieldWhat it does
signalAn AbortSignal to cancel the draw. Rejects with reason "signal".
onSessionCalled once for each draw before pointer events flow. Use it to subscribe to session changes; the live session is also available as td.activeSession.
guideOpt out of the rubber-band guide (default true). Auto-suppressed for point kinds, and for fixed-length kinds unless the kind's draw rule opts back in via showGuide.
interactionStylePer-call style override. Only the guide slot applies to draws; it merges over constructor defaults and built-ins.
sizeAnchorSets the anchor for geometry and label pixel sizes. The default "ground" value converts pixels to meters at commit. The "screen" value keeps a constant screen size and renders again after zoom. It has no effect on kinds that contain only meter sizes. TacticalDraw does not store this option.