@orbat-mapper/tactical-draw 0.2.0-alpha.30 → 0.2.0-alpha.32

package/dist/index.d.mts

@@ -166,6 +166,17 @@ interface IconResource {
   width: number;
   height: number;
   anchor: [number, number];
+  /**
+   * Direct visible mark used to rank icon picks, in unscaled canvas coordinates.
+   * Hits elsewhere in the full canvas measure their distance from this rectangle;
+   * omit it to preserve whole-canvas distance-zero behavior.
+   */
+  coreRect?: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  };
 }
 /**
  * Click-style hit event delivered by {@link MapAdapter.onPick}.
@@ -254,6 +265,9 @@ interface MapAdapter {
    * end of a pan or pinch-zoom gesture.
    *
    * Hit tolerance is pointer-type aware: 4 px for mouse/pen, 12 px for touch.
+   * Outline-only polygon interiors additionally have bounded inward selection
+   * reach from visible viewport-clipped boundaries: 24 px for mouse/pen and
+   * 36 px for touch. A visible solid or patterned fill owns its full interior.
    *
    * Returns an unsubscribe function. The returned function and the optional
    * `signal` are both honoured; either teardown path stops further events,
@@ -443,6 +457,8 @@ declare abstract class BaseMapAdapter<TLayerHandle, TEventToken, TViewToken> imp
 }
 //#endregion
 //#region src/pick-utils.d.ts
+type PickPointerType = "mouse" | "pen" | "touch";
+declare function pickPointerType(originalEvent: unknown): PickPointerType;
 declare function pickHitTolerance(originalEvent: unknown): number;
 declare function tryControlMeasureIdFromFeature(feature: Feature): string | null;
 /**
@@ -453,6 +469,119 @@ declare function tryControlMeasureIdFromFeature(feature: Feature): string | null
  */
 declare function bindAbortable(signal: AbortSignal | undefined, attach: () => () => void): () => void;
 //#endregion
+//#region src/pick-candidates.d.ts
+interface ScreenBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+interface RotatedScreenBounds {
+  center: PixelCoordinate;
+  halfWidth: number;
+  halfHeight: number;
+  angle: number;
+}
+type LabelExtent = ScreenBounds | RotatedScreenBounds;
+interface ResolvedPickPresentation {
+  stroke?: {
+    color?: string;
+    width?: number;
+    dash?: readonly number[];
+  };
+  fill?: {
+    color?: string;
+    pattern?: string;
+    opacity: number;
+  };
+  point?: {
+    fillColor?: string;
+    radius?: number;
+  };
+  text?: TextStyleOptions;
+}
+type PickCandidateHitKind = "native" | "point" | "line" | "polygon-boundary" | "polygon-interior" | "icon" | "label";
+interface PickCandidateHit {
+  kind: PickCandidateHitKind;
+  /** CSS-pixel distance to the visible mark, or null when only the engine knows the hit. */
+  distance: number | null;
+}
+/**
+ * Engine-neutral description of one rendered part eligible at a pointer location.
+ * This is deliberately richer than PickEvent but remains adapter-author plumbing:
+ * ordered candidates are not exposed by the public picking event.
+ */
+interface PickCandidate {
+  feature: Feature;
+  graphicId: string | null;
+  renderedPartId: string | number | null;
+  hit: PickCandidateHit;
+  viewport: ScreenBounds;
+  presentation: ResolvedPickPresentation;
+  visualOrder: number;
+  iconFootprint?: readonly PixelCoordinate[];
+  labelExtent?: LabelExtent;
+}
+/** A rendered part supplied by an adapter or TacticalDraw for shared evaluation. */
+interface PickCandidateInput {
+  feature: Feature;
+  /**
+   * Lower values mean visually topmost. Suppliers must normalize their
+   * native ordering to topmost-first before calling into evaluation.
+   */
+  visualOrder: number;
+  /** The engine already reported this part as hit; retained as a fallback for engine-only marks. */
+  nativeHit?: boolean;
+  icon?: IconResource;
+  labelExtent?: LabelExtent;
+  presentation?: ResolvedPickPresentation;
+  layerStyle?: StyleOptions;
+}
+/**
+ * The `visualOrder` for the feature at `index` of a render-ordered
+ * (bottom-first) list of `total` features: reversing the index makes the
+ * topmost-rendered feature the lowest, and therefore winning, order.
+ */
+declare function renderOrderToVisualOrder(index: number, total: number): number;
+interface MergedPickFeature {
+  feature: Feature;
+  visualOrder: number;
+  nativeHit: boolean;
+}
+/**
+ * Preserve native visual ordering/hit evidence while keeping cached source
+ * geometry authoritative. Native polygon geometry may be tile-clipped and
+ * therefore contain artificial edges that are not part of the graphic.
+ *
+ * Normalizes to the shared `visualOrder` contract (lower = visually
+ * topmost): native hits already arrive topmost-first from the engines and
+ * keep that order at the front. Cached-only features (not among the native
+ * hits) are appended after them, in reverse cache order — cache arrays are
+ * render order (bottom-first), so reversing yields topmost-first — with
+ * `visualOrder` numbering continuing on from the native section.
+ */
+declare function mergeNativeAndCachedPickFeatures(nativeFeatures: readonly Feature[], cachedFeatures: readonly Feature[]): MergedPickFeature[];
+interface PickEvaluationContext {
+  pixel: PixelCoordinate;
+  tolerance: number;
+  pointerType?: PickPointerType;
+  toPixel: (position: Position) => PixelCoordinate | null;
+  viewport: ScreenBounds;
+  bearing?: number;
+}
+/**
+ * Evaluate every relevant rendered part in screen space, then return the
+ * primary candidate under the visible-intent ranking policy: direct visible
+ * marks (strokes, points, icons, labels) outrank visibly filled interiors,
+ * which outrank inferred outline-only reach; competing direct marks rank by
+ * screen-space distance; visual topmost order is only the final tie-break.
+ * See `rankPickCandidates` for the full ordered list — that ordering stays
+ * internal adapter-author plumbing; the public pick event exposes only this
+ * primary candidate.
+ */
+declare function evaluatePickCandidates(inputs: readonly PickCandidateInput[], context: PickEvaluationContext): PickCandidate | null;
+declare function resolvePickPresentation(feature: Feature, layerStyle?: StyleOptions): ResolvedPickPresentation;
+//#endregion
 //#region src/feature-style.d.ts
 /**
  * Coerce a raw `properties.style` value into a `HandleStyle` for the
@@ -474,6 +603,38 @@ declare const DEFAULT_TEXT_SIZE_MAX_PIXELS = 24;
  * clamp inside its per-zoom-stop style expression.
  */
 declare function resolveGroundTextSizePixels(textSizeMeters: number, resolution: number, text?: Pick<TextStyleOptions, "textSizeMinPixels" | "textSizeMaxPixels">): number;
+/**
+ * The size properties a Text graphic's feature carries (see `text.ts` /
+ * `FeaturePartProps`). Mutually exclusive size anchors: `textSizePixels`
+ * (screen-anchored) or `textSizeMeters` (ground-anchored). `textMaxSizePixels`
+ * is the ADR-0037 hide threshold; the min/max band fields are the amplifier
+ * -label clamp bounds, applied only when no max-size threshold is present.
+ */
+interface TextSizeProps {
+  textSizeMeters?: number;
+  textSizePixels?: number;
+  textMaxSizePixels?: number;
+  textSizeMinPixels?: number;
+  textSizeMaxPixels?: number;
+}
+/**
+ * Resolve a Text graphic's on-screen size in pixels, honoring the
+ * `textMaxSizePixels` hide threshold (ADR-0037). Returns `null` — the "hidden"
+ * signal — when the graphic should render no text this frame; adapters emit no
+ * text style for a `null`. Distinct from [[resolveGroundTextSizePixels]], which
+ * keeps the 8–24 px clamp band for amplifier labels: this helper is the Text
+ * graphic's own sizing rule.
+ *
+ *  - screen-anchored (`textSizePixels`): the fixed pixel size, never scaled or
+ *    hidden by zoom.
+ *  - ground-anchored (`textSizeMeters`) with a `textMaxSizePixels` threshold:
+ *    *unclamped* `meters / resolution` (the 8–24 band does NOT apply), hidden
+ *    (`null`) once that exceeds the threshold — text shrinks freely zooming out
+ *    and vanishes rather than clamps zooming in.
+ *  - ground-anchored without a threshold: falls back to the clamped band.
+ *  - no usable size or resolution: `null`.
+ */
+declare function resolveTextSizePixels(props: TextSizeProps, resolution: number): number | null;
 //#endregion
 //#region src/gestures/hit-test.d.ts
 type ToPixel = (lonLat: Position) => PixelCoordinate | null;
@@ -1860,7 +2021,11 @@ declare class TacticalDraw {
    * then `previewLayer`, then `graphicsLayer` — against each layer's current
    * `adapter.getLayerFeatures(...)` cache. The `guideLayer` is deliberately
    * excluded: it is non-interactive draw-guide scaffolding, never a
-   * legitimate "owned" click target.
+   * legitimate "owned" click target. Within each layer, candidates follow
+   * the shared visible-intent ranking (direct marks, then filled interiors,
+   * then inferred outline-only reach, distance within direct marks, then
+   * visual topmost order) — this explicit-affordance layer order is the
+   * tier above all of it.
    *
    * `preview` and `graphics` each get a label text-extent fallback after the
    * geometry pass misses on that layer: for every `Point` feature carrying a
@@ -1871,7 +2036,7 @@ declare class TacticalDraw {
    * This matters most for the active preview, since a click can land
    * anywhere across a rotated/offset label during an edit.
    *
-   * `tolerance` defaults to `mapEventHitTolerance(options?.originalEvent)` —
+   * `tolerance` defaults to `pickHitTolerance(options?.originalEvent)` —
    * pass the host's raw click event as `originalEvent` to get the same
    * pointer-type-aware tolerance (4px mouse/pen, 12px touch) `onPick` uses;
    * pass an explicit `tolerance` to override it outright.
@@ -2031,4 +2196,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 GuideStyle, HATCH_PATTERNS, type HandleStyle, type HatchPattern, 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, type TransientChangeEvent, type TransientPhase, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, effectivePointSymbolPixelSize, fillPatternImageDimension, fillPatternImageId, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, makeFillPatternImage, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pointSymbolFootprint, resizePointSymbolSize, 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, HATCH_PATTERNS, type HandleStyle, type HatchPattern, type IconResource, type InteractionHit, type InteractionStyle, type LabelExtent, type LayerId, type MapAdapter, type MapCursor, type MapEvent, type MapEventHandler, type MergedPickFeature, type NativeEventEntry, type PickCandidate, type PickCandidateHit, type PickCandidateHitKind, type PickCandidateInput, type PickEvaluationContext, type PickEvent, type PickHandler, type PickOptions, type PickPointerType, 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 ResolvedPickPresentation, type RotatedScreenBounds, type ScreenBounds, 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 TextSizeProps, type TextStyleOptions, type ToPixel, type TransformBox, type TransformChangeEvent, type TransformSession, type TransientChangeEvent, type TransientPhase, bindAbortable, clonePointSymbol, coerceHandleStyle, combineWithHostSignal, effectivePointSymbolPixelSize, evaluatePickCandidates, fillPatternImageDimension, fillPatternImageId, getSizeAnchor, hitTestFeature, hitTestIconFeature, ignoreAbort, isPointSymbol, isTacticalDrawAbortError, makeFillPatternImage, mergeNativeAndCachedPickFeatures, nearestWorldCopyLng, nearestWorldCopyPosition, pickHitTolerance, pickPointerType, pointSymbolFootprint, renderOrderToVisualOrder, resizePointSymbolSize, resolveGroundTextSizePixels, resolvePickPresentation, resolveTextSizePixels, tryControlMeasureIdFromFeature };