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

package/README.md

@@ -87,6 +87,22 @@ if (session && "canCommit" in session) {
 }
 ```
 
+Live edit and transform sessions expose a session-local `history`. Completed
+gestures and authored programmatic mutations are undoable without settling the
+session; pointer-move preview frames are not history steps:
+
+```ts
+const active = td.activeSession;
+const history =
+  (active && "history" in active ? active.history : null) ?? td.activeTransformSession?.history;
+if (history) history.undo();
+```
+
+`history.subscribe(...)` reports `canUndo`, `canRedo`, and optional operation
+labels. Committing folds only the selected working state into the host document
+as one operation. Changing a transform session's members with `setGraphics()`
+establishes a new local baseline and clears both stacks.
+
 ## Bring your own engine
 
 Implement `MapAdapter` (or extend `BaseMapAdapter`) against your map engine

package/dist/index.d.mts

@@ -12,6 +12,11 @@ interface PointerEventInfo {
    * mouse paths populate it; touch leaves it `undefined`.
    */
   altKey?: boolean;
+  /**
+   * Whether Shift was held for this pointer event. Rotation gestures use the
+   * live value to constrain transform-box angles to 15-degree increments.
+   */
+  shiftKey?: boolean;
   /** Engine-native event, for drivers that need to call preventDefault etc. */
   native?: unknown;
 }
@@ -672,6 +677,22 @@ type EditMode = "reshape" | "transform" | "labeldrag" | "delete";
  */
 type SettleReason = "close" | "error" | TacticalDrawAbortReason;
 //#endregion
+//#region src/tactical-draw/session-history.d.ts
+type SessionChangeSource = "gesture" | "undo" | "redo" | "programmatic";
+interface SessionHistoryState {
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel?: string;
+  readonly redoLabel?: string;
+}
+interface SessionHistory {
+  /** Current availability and optional labels. Each session retains at most 100 completed steps. */
+  readonly state: SessionHistoryState;
+  undo(): boolean;
+  redo(): boolean;
+  subscribe(listener: (state: SessionHistoryState) => void): () => void;
+}
+//#endregion
 //#region src/tactical-draw/edit-session.d.ts
 /**
  * Surface delivered via `td.edit(measure, opts).onSession` and synchronously
@@ -683,6 +704,8 @@ type SettleReason = "close" | "error" | TacticalDrawAbortReason;
  * asynchronously).
  */
 interface EditSession {
+  /** Undo/redo for completed mutations within this live session. */
+  readonly history: SessionHistory;
   /** Immutable edit-start input. */
   readonly graphic: ControlMeasure;
   /** Live complete working graphic. Copy on read. */
@@ -820,6 +843,8 @@ interface EditSession {
  * observe partial state. See PRD #40 user-stories 23–24.
  */
 interface EditChangeEvent {
+  /** How this working-copy transition was initiated. */
+  readonly source: SessionChangeSource;
   /** Working state after the completed gesture. */
   readonly graphic: GraphicSnapshot<ControlMeasure>;
   /** State immediately before this gesture. */
@@ -840,6 +865,7 @@ interface EditChangeEvent {
 //#endregion
 //#region src/tactical-draw/graphic-edit-session.d.ts
 interface GraphicEditChangeEvent<G extends Graphic = Graphic> {
+  readonly source: SessionChangeSource;
   readonly graphic: GraphicSnapshot<G>;
   readonly previous: GraphicSnapshot<G>;
   readonly session: GraphicEditSession<G>;
@@ -849,6 +875,7 @@ interface GraphicEditChangeEvent<G extends Graphic = Graphic> {
 }
 /** Common selection/editing contract shared by control measures and point symbols. */
 interface GraphicEditSession<G extends Graphic = Graphic> {
+  readonly history: SessionHistory;
   /** Immutable edit-start input. */
   readonly graphic: G;
   /** Live working graphic. Copy on read. */
@@ -885,6 +912,8 @@ interface GraphicEditSession<G extends Graphic = Graphic> {
  * delivers, asynchronously).
  */
 interface TransformSession {
+  /** Undo/redo for completed gestures within the current membership baseline. */
+  readonly history: SessionHistory;
   /**
    * Live view of the current members' join-time input graphics — a fresh array
    * on each read, in current membership order. Grows/shrinks as [[setGraphics]]
@@ -926,6 +955,11 @@ interface TransformSession {
    * current box angle. Session-scoped state (`sizeAnchor`, box angle,
    * non-geometry dirty) is unchanged.
    *
+   * Calling this establishes a new session-history baseline: both undo and
+   * redo are cleared after retained members carry their working state
+   * forward. Membership changes and already-emitted exit snapshots are not
+   * 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
@@ -1036,6 +1070,8 @@ interface TransformSession {
  * `EditChangeEvent` for the identical emission contract this mirrors.
  */
 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>[];
   /** State immediately before this gesture, index-aligned with `session.graphics` as of this emission. */
@@ -1058,6 +1094,7 @@ interface TransformChangeEvent {
 //#endregion
 //#region src/tactical-draw/graphic-transform-session.d.ts
 interface GraphicTransformChangeEvent {
+  readonly source: SessionChangeSource;
   readonly graphics: GraphicSnapshot[];
   readonly previous: GraphicSnapshot[];
   readonly session: GraphicTransformSession;
@@ -1066,6 +1103,7 @@ interface GraphicTransformChangeEvent {
   abort(): void;
 }
 interface GraphicTransformSession {
+  readonly history: SessionHistory;
   readonly graphics: readonly Graphic[];
   readonly workingGraphics: readonly Graphic[];
   readonly dirty: boolean;
@@ -1146,6 +1184,55 @@ interface DrawSession {
   onSettled(handler: (reason: SettleReason) => void): () => void;
 }
 //#endregion
+//#region src/tactical-draw/snapping.d.ts
+type SnapInteraction = "draw" | "reshape" | "translate" | "label-drag";
+interface SnapCandidateRequest {
+  coordinate: Position;
+  pixel: PixelCoordinate;
+  interaction: SnapInteraction;
+  graphicId?: string;
+  controlPointIndex?: number;
+  originalEvent?: unknown;
+}
+interface SnapCandidate {
+  id: string;
+  coordinate: Position;
+  kind: string;
+  graphicId?: string;
+  controlPointIndex?: number;
+  priority?: number;
+}
+type SnapCandidateProvider = (request: SnapCandidateRequest) => readonly SnapCandidate[];
+interface SnapResult {
+  coordinate: Position;
+  pixel: PixelCoordinate;
+  candidate: SnapCandidate;
+  distancePixels: number;
+}
+interface GraphicGeometrySnappingOptions {
+  /** Snap to the nearest point along generated linework and polygon boundaries. Default `true`. */
+  edges?: boolean;
+  /** Snap to generated geometry vertices. Default `false`. */
+  vertices?: boolean;
+}
+interface SnappingOptions {
+  enabled?: boolean;
+  tolerancePixels?: number;
+  sources?: {
+    graphics?: boolean;
+    /**
+     * Snap to generated control-measure geometry. `true` enables edges with
+     * vertices disabled; pass an object to select either candidate type.
+     * Text/label point features and the active graphic are excluded.
+     */
+    graphicGeometry?: boolean | GraphicGeometrySnappingOptions;
+    external?: SnapCandidateProvider;
+  };
+  bypass?: (originalEvent: unknown) => boolean;
+  /** Called for each resolution attempt; `null` clears a host-rendered indicator. */
+  onSnap?: (result: SnapResult | null) => void;
+}
+//#endregion
 //#region src/tactical-draw/point-symbol-draw-controller.d.ts
 type DrawPointSymbolDraft = Pick<PointSymbol, "kind" | "sidc"> & Partial<Omit<PointSymbol, "kind" | "sidc">>;
 //#endregion
@@ -1196,6 +1283,8 @@ interface TacticalDrawOptions {
    * the draw API itself are deferred (PRD #40 user-story-5 note).
    */
   generateId?: () => string;
+  /** Optional engine-level snapping for draw and edit interactions. */
+  snapping?: SnappingOptions;
 }
 interface EditOptions {
   signal?: AbortSignal;
@@ -1344,6 +1433,8 @@ declare class TacticalDraw {
   private readonly defaultInteractionStyle;
   private readonly generateId;
   private readonly pointSymbols;
+  private snappingOptions;
+  private readonly resolveSnap;
   private destroyed;
   private hasRendered;
   private readonly activeInteraction;
@@ -1394,7 +1485,12 @@ declare class TacticalDraw {
    * surrounding collection state.
    */
   private lastRenderedMeasures;
+  private snapGeometryFeatures;
   constructor(adapter: MapAdapter, options?: TacticalDrawOptions);
+  /** Replace snapping configuration without recreating the map adapter or façade. */
+  setSnappingOptions(options?: SnappingOptions): void;
+  /** Clear transient host affordances when snapping or its interaction ends. */
+  private clearSnapResult;
   /**
    * Render `measures` into features and write them to the graphics layer.
    * Routes every measure through [[renderMeasureForAdapter]] so pixel sizing is
@@ -1782,4 +1878,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 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 SettleReason, 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, 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 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 };