@orbat-mapper/tactical-draw 0.2.0-alpha.23 → 0.2.0-alpha.25

package/dist/index.d.mts

@@ -220,6 +220,11 @@ interface MapAdapter {
   toLonLat(coordinate: number[]): Position;
   fromLonLat(position: Position): number[];
   getPixelFromCoordinate(position: Position): PixelCoordinate | null;
+  /**
+   * Convert a viewport pixel to longitude/latitude. Optional so third-party
+   * adapters compiled against an older ABI remain valid.
+   */
+  getCoordinateFromPixel?(pixel: PixelCoordinate): Position | null;
   /**
    * Get current viewport size in CSS pixels.
    */
@@ -264,6 +269,12 @@ interface MapAdapter {
    */
   onViewChange(handler: () => void): void;
   offViewChange(handler: () => void): void;
+  /**
+   * The engine evaluates the meters→pixels clamp for ground-sized point
+   * symbols inside its own style layer, so meters-sized point symbols don't
+   * need view-change re-renders for size.
+   */
+  readonly scalesGroundPointSymbolsNatively?: boolean;
   /**
    * Construct an {@link EditPointerDriver} for `TacticalDraw`'s edit
    * controller. The controller subscribes to pointer events on the returned
@@ -465,7 +476,9 @@ type PointSymbolSize = {
   unit: "pixels";
 } | {
   value: number;
-  unit: "meters";
+  unit: "meters"; /** Floor for the on-screen projection of the ground-based size; none when omitted. */
+  minPixels?: number; /** Cap on the on-screen projection of the ground-based size — typically the pixel size the symbol had when anchored to ground; unclamped when omitted. */
+  maxPixels?: number;
 };
 interface PointSymbolGraphicModifiers {
   /** Radians clockwise, relative to the point symbol's own orientation. */
@@ -901,15 +914,20 @@ interface GraphicEditSession<G extends Graphic = Graphic> {
  * 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.
  *
+ * Typed on `Graphic` (ADR-0032): a member is either a `ControlMeasure` or a
+ * point symbol, and the two coexist in one session. Hosts narrow with
+ * `isPointSymbol`. `controlPointsFor` is a control-measure accessor and returns
+ * `undefined` for a point-symbol id.
+ *
  * The member set is mutable via [[setGraphics]] (#187): members can join or
- * leave a live session without a session boundary. Because membership changes
- * over the session's lifetime, snapshot arrays are keyed by **measure id**, not
- * by index — a snapshot's identity is `snapshot.graphic.id`. `graphics` is a
- * live view of the current members' join-time inputs; a `TransformChangeEvent`'s
- * arrays are index-aligned with `session.graphics` *as of that emission*. After
- * the session settles (`close` / `abort` / an emptying `setGraphics`), every
- * method is a silent no-op (except [[onSettled]] — late registration still
- * delivers, asynchronously).
+ * leave a live session without a session boundary — point symbols exactly like
+ * measures. Because membership changes over the session's lifetime, snapshot
+ * arrays are keyed by **graphic id**, not by index — a snapshot's identity is
+ * `snapshot.graphic.id`. `graphics` is a live view of the current members'
+ * join-time inputs; a `TransformChangeEvent`'s arrays are index-aligned with
+ * `session.graphics` *as of that emission*. After the session settles (`close`
+ * / `abort` / an emptying `setGraphics`), every method is a silent no-op
+ * (except [[onSettled]] — late registration still delivers, asynchronously).
  */
 interface TransformSession {
   /** Undo/redo for completed gestures within the current membership baseline. */
@@ -920,29 +938,46 @@ interface TransformSession {
    * adds or removes members. Not stable across membership changes: key
    * snapshots by `snapshot.graphic.id` rather than relying on index alignment.
    */
-  readonly graphics: readonly ControlMeasure[];
+  readonly graphics: readonly Graphic[];
   /**
-   * Live working control points for the member whose id is `graphicId`, or
-   * `undefined` when no member carries that id. Copy on read.
+   * Live view of the current members' working graphics — a fresh array on each
+   * read, in current membership order, reflecting every gesture applied so far.
+   * Measures carry their working control points (and any transform-frozen
+   * options); point symbols carry their working position, size value, and
+   * rotation. Copy on read.
+   */
+  readonly workingGraphics: readonly Graphic[];
+  /**
+   * Live working control points for the control-measure member whose id is
+   * `graphicId`, or `undefined` when no such member carries that id — including
+   * when `graphicId` names a point symbol (which has no control points; read
+   * its working `position` from [[workingGraphics]] instead). Copy on read.
    */
   controlPointsFor(graphicId: string): readonly Position[] | undefined;
-  /** `true` when any member's working points differ from its edit-start input beyond tolerance. */
+  /** `true` when any member's working state differs 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.
+   * Live size anchor, applied group-wide to the **control-measure** members
+   * only (ADR-0020). `"ground"` bakes each measure's pixel size to meters on
+   * commit; `"screen"` keeps it zoom-aware. A point symbol's persisted
+   * pixel/meter size is its own anchor and is never rewritten by this setting.
    * 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()`. */
+  /**
+   * Switch the group's size anchor (ADR-0020) for its control-measure members.
+   * Takes effect on the next emitted snapshot and on `close()`. Point-symbol
+   * members are unaffected.
+   */
   setSizeAnchor(anchor: SizeAnchor): void;
   /**
    * Replace the member set in place — the primitive behind shift-click toggle,
    * marquee replace, and single-edit → group folding, without tearing the
-   * session down (#187). Members are matched to the current set by measure id:
+   * session down (#187). Members (measures and point symbols alike) are matched
+   * to the current set by graphic id:
    *
    * - **Retained** members (id in both the current and next sets) carry their
-   *   current working state forward; the passed measure object is ignored for
+   *   current working state forward; the passed graphic object is ignored for
    *   them. Their `dirty` baseline stays their original join-time input, so a
    *   session that has already moved things stays dirty across the call.
    * - **Removed** members (id in the current set, absent from the next) are
@@ -961,34 +996,37 @@ interface TransformSession {
    * undoable within the live session.
    *
    * **Return value** — the committed exit snapshots of the members removed *by
-   * this call*, built exactly like [[close]]'s snapshots (pixel size baked to
-   * ground unless `sizeAnchor` is `"screen"`, then cloned and rendered); an
-   * empty array when nothing was removed. The outer `editMany` promise resolves
-   * with the snapshots of the members in the set **at close time only**.
-   * Removed members are NOT written back to the graphics layer by the
-   * controller — the host folds the returned snapshots into its document and
-   * calls `td.render()`, the same contract as [[close]]. A removed member's
-   * exit snapshot is also delivered through [[onCommit]] — the recommended
-   * channel, since it covers this return value and the close-time promise
-   * resolution through a single subscription. Returns `undefined` (a silent
-   * no-op) after the session has settled.
+   * this call*, built exactly like [[close]]'s snapshots (a measure's pixel
+   * size baked to ground unless `sizeAnchor` is `"screen"`, a point symbol's
+   * size left untouched, then cloned and rendered); an empty array when nothing
+   * was removed. The outer `editMany` promise resolves with the snapshots of
+   * the members in the set **at close time only**. Removed members are NOT
+   * written back to the graphics layer by the controller — the host folds the
+   * returned snapshots into its document and calls `td.render()`, the same
+   * contract as [[close]]. A removed member's exit snapshot is also delivered
+   * through [[onCommit]] — the recommended channel, since it covers this return
+   * value and the close-time promise resolution through a single subscription.
+   * Returns `undefined` (a silent no-op) after the session has settled.
    *
    * `setGraphics([])` on a live session delegates to [[close]]: it commits every
    * current member, resolves the promise with their snapshots, and returns that
    * same array. Duplicate ids in `graphics` throw `TypeError` synchronously,
-   * without mutating session state.
+   * without mutating session state. A point-symbol member entering a session
+   * whose controller was created without a point-symbol capability throws
+   * `PointSymbolCapabilityRequiredError` synchronously, also without mutating
+   * session state.
    */
-  setGraphics(graphics: readonly ControlMeasure[]): GraphicSnapshot<ControlMeasure>[] | undefined;
+  setGraphics(graphics: readonly Graphic[]): GraphicSnapshot[] | undefined;
   /**
-   * Commit: returns the members' `GraphicSnapshot<ControlMeasure>[]` (the members in the
-   * set at close time) and resolves the outer `editMany` promise with the same
-   * value (the same reference — no double-bake of ground-anchored sizes). A
+   * Commit: returns the members' `GraphicSnapshot[]` (the members in the set at
+   * close time) and resolves the outer `editMany` promise with the same value
+   * (the same reference — no double-bake of ground-anchored measure sizes). A
    * member removed mid-session via [[setGraphics]] is not included here; its exit
    * snapshot was returned from that `setGraphics` call (and delivered to
    * [[onCommit]] at that time). Returns `undefined` after the session has
    * settled (idempotent no-op).
    */
-  close(): GraphicSnapshot<ControlMeasure>[] | undefined;
+  close(): GraphicSnapshot[] | undefined;
   /** Reject the outer `editMany` promise with reason `"session"`. */
   abort(): void;
   /**
@@ -1006,7 +1044,7 @@ interface TransformSession {
   onChange(listener: (event: TransformChangeEvent) => void): () => void;
   /**
    * Subscribe to committed exit-snapshot batches — the single delivery channel
-   * for every `GraphicSnapshot<ControlMeasure>[]` this session ever commits (#191). Fires
+   * for every `GraphicSnapshot[]` this session ever commits (#191). Fires
    * exactly once per batch:
    *
    * - The members [[setGraphics]] removes, but only when that call actually
@@ -1031,7 +1069,7 @@ interface TransformSession {
    * session has settled returns a no-op unsubscribe and the listener never
    * fires.
    */
-  onCommit(handler: (snapshots: GraphicSnapshot<ControlMeasure>[]) => void): () => void;
+  onCommit(handler: (snapshots: GraphicSnapshot[]) => void): () => void;
   /**
    * Subscribe to the session's settlement — the lifecycle complement of
    * [[onCommit]]: `onCommit` delivers *what* was committed, `onSettled` says
@@ -1073,9 +1111,9 @@ interface TransformChangeEvent {
   /** How this working-copy transition was initiated. */
   readonly source: SessionChangeSource;
   /** Working state after the completed gesture, index-aligned with `session.graphics` as of this emission. */
-  readonly graphics: GraphicSnapshot<ControlMeasure>[];
+  readonly graphics: GraphicSnapshot[];
   /** State immediately before this gesture, index-aligned with `session.graphics` as of this emission. */
-  readonly previous: GraphicSnapshot<ControlMeasure>[];
+  readonly previous: GraphicSnapshot[];
   /** The session the event belongs to. */
   readonly session: TransformSession;
   /**
@@ -1092,28 +1130,6 @@ interface TransformChangeEvent {
   abort(): void;
 }
 //#endregion
-//#region src/tactical-draw/graphic-transform-session.d.ts
-interface GraphicTransformChangeEvent {
-  readonly source: SessionChangeSource;
-  readonly graphics: GraphicSnapshot[];
-  readonly previous: GraphicSnapshot[];
-  readonly session: GraphicTransformSession;
-  reject(): void;
-  close(): void;
-  abort(): void;
-}
-interface GraphicTransformSession {
-  readonly history: SessionHistory;
-  readonly graphics: readonly Graphic[];
-  readonly workingGraphics: readonly Graphic[];
-  readonly dirty: boolean;
-  close(): GraphicSnapshot[] | undefined;
-  abort(): void;
-  onChange(listener: (event: GraphicTransformChangeEvent) => void): () => void;
-  onCommit(listener: (snapshots: GraphicSnapshot[]) => void): () => void;
-  onSettled(listener: (reason: SettleReason) => void): () => void;
-}
-//#endregion
 //#region src/tactical-draw/session.d.ts
 /**
  * Scoped surface delivered via `td.draw({ onSession })` for variable-length
@@ -1351,7 +1367,7 @@ interface EditManyOptions {
    * pointer event is processed. Lets a host wire Done/Cancel/Delete buttons to
    * the active session.
    */
-  onSession?: (session: TransformSession | GraphicTransformSession) => void;
+  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
@@ -1642,12 +1658,15 @@ declare class TacticalDraw {
   editMany(measures: ControlMeasure[], options?: EditManyOptions): Promise<GraphicSnapshot<ControlMeasure>[]>;
   editMany(graphics: Graphic[], options?: EditManyOptions): Promise<GraphicSnapshot[]>;
   /**
-   * One-call selection-sync: mutate a live control-measure-only transform's
-   * member set in place, or start a fresh `editMany` when no compatible
-   * transform is live (#191). A selection containing a point symbol uses the
-   * unified graphic transform session, which does not yet support mutable
-   * membership; changing that selection preempts the current session and starts
-   * a new one, resetting its box angle and other session-local state.
+   * One-call selection-sync: mutate a live transform's member set in place, or
+   * start a fresh `editMany` when none is live (#191). Any mix of control
+   * measures and point symbols is handled by the one Graphic-typed session
+   * (ADR-0032): a point symbol joins or leaves the live session exactly like a
+   * measure via `setGraphics`, preserving box angle, size anchor, and history
+   * baseline — no preempt-and-restart. A point symbol in the selection with no
+   * point-symbol capability configured throws `PointSymbolCapabilityRequiredError`
+   * synchronously (from `setGraphics` on a live session, or from `editMany` on a
+   * fresh one).
    *
    * The facade knows session liveness synchronously — `activeTransformSessionRef`
    * is cleared inside the settle path, before control returns to host code — so
@@ -1756,7 +1775,7 @@ declare class TacticalDraw {
    * `TransformSession` isn't part of its `DrawSession | EditSession` union —
    * see `activeTransformSessionRef`. Safe to read after `destroy()`.
    */
-  get activeTransformSession(): TransformSession | GraphicTransformSession | null;
+  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
@@ -1878,4 +1897,4 @@ 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, DEFAULT_LABEL_SIZE_PIXELS, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, type DrawMeasureDraft, type DrawOptions, type DrawPointSymbolDraft, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type Graphic, type GraphicEditChangeEvent, type GraphicEditSession, type GraphicGeometrySnappingOptions, type GraphicRender, type GraphicSnapshot, type GraphicTransformChangeEvent, type GraphicTransformSession, type GuideStyle, type HandleStyle, type IconResource, type InteractionHit, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type SnapCandidate, type SnapCandidateProvider, type SnapCandidateRequest, type SnapInteraction, type SnapResult, type SnappingOptions, 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, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pointSymbolFootprint, resolveGroundTextSizePixels, tryControlMeasureIdFromFeature };
+export { BaseMapAdapter, type CombinedAbort, DEFAULT_LABEL_SIZE_PIXELS, DEFAULT_TEXT_SIZE_MAX_PIXELS, DEFAULT_TEXT_SIZE_MIN_PIXELS, type DrawMeasureDraft, type DrawOptions, type DrawPointSymbolDraft, type DrawSession, type EditChangeEvent, type EditManyOptions, type EditMode, type EditOptions, type EditPointerDriver, type EditSession, type FeatureOps, type Graphic, type GraphicEditChangeEvent, type GraphicEditSession, type GraphicGeometrySnappingOptions, type GraphicRender, type GraphicSnapshot, type GuideStyle, type HandleStyle, type IconResource, type InteractionHit, type InteractionStyle, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type NativeEventEntry, type PickEvent, type PickHandler, type PickOptions, type PixelCoordinate, type PointSymbol, type PointSymbolAnchor, type PointSymbolCapability, PointSymbolCapabilityRequiredError, type PointSymbolColors, type PointSymbolFootprint, type PointSymbolGraphicModifiers, type PointSymbolRender, type PointSymbolSize, type PointSymbolStyle, type PointerCallback, PointerCallbackHub, type PointerEventInfo, type SessionChangeSource, type SessionHistory, type SessionHistoryState, type SettleReason, type SizeAnchor, type SnapCandidate, type SnapCandidateProvider, type SnapCandidateRequest, type SnapInteraction, type SnapResult, type SnappingOptions, 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, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pointSymbolFootprint, resolveGroundTextSizePixels, tryControlMeasureIdFromFeature };