@tileflow/interactions 0.0.0-bootstrap.0

package/dist/maplibre-entry.d.ts

@@ -0,0 +1,298 @@
+import { m as TileflowInteractionDiagnostic, T as TileflowInteractionState, c as TileflowAnnotation, d as TileflowAnnotationInteractionEvent, i as TileflowInteractionBinding, G as TileflowResolvedPoiFeatureTarget, r as TileflowInteractionInputModality, o as TileflowInteractionEvent, I as TileflowResolvedSemanticFeatureTarget, k as TileflowInteractionContent } from './validation-Cy6Tz3lz.js';
+import 'zod/mini';
+
+/**
+ * Framework-neutral lifecycle primitives for the MapLibre interaction adapter.
+ *
+ * This module deliberately imports neither MapLibre nor a DOM implementation. A framework
+ * adapter owns the concrete marker/view instances and supplies every lifecycle operation.
+ */
+type TileflowAnnotationRegistryEntry<TKey, TDefinition, TInstance> = Readonly<{
+    definition: TDefinition;
+    instance: TInstance;
+    key: TKey;
+}>;
+type TileflowAnnotationRegistryAdapter<TContext, TKey, TDefinition, TInstance> = Readonly<{
+    context: TContext;
+    create: (context: TContext, definition: TDefinition, key: TKey) => TInstance;
+    getKey: (definition: TDefinition) => TKey;
+    remove: (instance: TInstance, context: TContext, definition: TDefinition, key: TKey) => void;
+    reorder?: (context: TContext, entries: readonly TileflowAnnotationRegistryEntry<TKey, TDefinition, TInstance>[], previousEntries: readonly TileflowAnnotationRegistryEntry<TKey, TDefinition, TInstance>[]) => void;
+    shouldUpdate?: (previous: TDefinition, next: TDefinition, key: TKey) => boolean;
+    update: (instance: TInstance, context: TContext, next: TDefinition, previous: TDefinition, key: TKey) => (() => void) | void;
+}>;
+type TileflowAnnotationRegistry<TKey, TDefinition, TInstance> = Readonly<{
+    readonly size: number;
+    clear: () => void;
+    dispose: () => void;
+    entries: () => readonly TileflowAnnotationRegistryEntry<TKey, TDefinition, TInstance>[];
+    get: (key: TKey) => TileflowAnnotationRegistryEntry<TKey, TDefinition, TInstance> | undefined;
+    reconcile: (definitions: readonly TDefinition[]) => void;
+}>;
+/**
+ * Creates a keyed registry that preserves compatible annotation instances across reconciliations.
+ *
+ * `create` must clean up any resource it allocates before throwing. `remove` must be safe to retry:
+ * failed cleanup remains pending and is attempted again by a later reconciliation or disposal.
+ * An `update` callback may return an exact rollback closure. When it returns nothing, the registry
+ * invokes `update` with its previous and next values reversed if a later operation fails. A failed
+ * `reorder` is reversed by invoking it again with the two entry lists swapped.
+ */
+declare function createTileflowAnnotationRegistry<TContext, TKey, TDefinition, TInstance>(adapter: TileflowAnnotationRegistryAdapter<TContext, TKey, TDefinition, TInstance>): TileflowAnnotationRegistry<TKey, TDefinition, TInstance>;
+type TileflowOverlayState<TTarget> = Readonly<{
+    popup: TTarget | null;
+    tooltip: TTarget | null;
+}>;
+type TileflowOverlayStateChangeReason = 'dispose' | 'popup:close' | 'popup:open' | 'target:remove' | 'targets:reconcile' | 'tooltip:close' | 'tooltip:open';
+type TileflowOverlayStateListener<TTarget> = (state: TileflowOverlayState<TTarget>, previous: TileflowOverlayState<TTarget>, reason: TileflowOverlayStateChangeReason) => void;
+type TileflowOverlayStateController<TTarget> = Readonly<{
+    clearTarget: (target: TTarget) => boolean;
+    dispose: () => void;
+    getState: () => TileflowOverlayState<TTarget>;
+    reconcileTargets: (isAvailable: (target: TTarget) => boolean) => boolean;
+    setPopup: (target: TTarget | null) => boolean;
+    setTooltip: (target: TTarget | null) => boolean;
+    subscribe: (listener: TileflowOverlayStateListener<TTarget>) => () => void;
+}>;
+/**
+ * Owns transient tooltip state and one active popup without knowing the target representation.
+ * Full serializable target references can be used by supplying semantic equality.
+ */
+declare function createTileflowOverlayStateController<TTarget>(options?: {
+    areTargetsEqual?: (left: TTarget, right: TTarget) => boolean;
+    initialPopup?: TTarget | null;
+    initialTooltip?: TTarget | null;
+    onChange?: TileflowOverlayStateListener<TTarget>;
+}): TileflowOverlayStateController<TTarget>;
+
+/** A minimal structural contract shared by MapLibre Marker and Popup instances. */
+type TileflowMapLibrePositioned<TMap> = {
+    addTo: (map: TMap) => unknown;
+    remove: () => unknown;
+    setLngLat: (coordinate: [longitude: number, latitude: number]) => unknown;
+};
+type TileflowMapLibreDomDocument = Pick<Document, 'createElement'>;
+type TileflowMapLibreDomOverlayKind = 'popup' | 'tooltip';
+type TileflowMapLibreDomMarkerFactoryInput<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    annotation: TAnnotation;
+    element: HTMLElement;
+}>;
+type TileflowMapLibreDomOverlayFactoryInput<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    annotation: TAnnotation;
+    container: HTMLElement;
+    kind: TileflowMapLibreDomOverlayKind;
+}>;
+type TileflowMapLibreDomRenderTargetKind = 'marker' | 'popup' | 'tooltip';
+/** A live DOM outlet for framework portals, teleports, and snippets. */
+type TileflowMapLibreDomRenderTarget<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    annotation: TAnnotation;
+    close: () => void;
+    container: HTMLElement;
+    key: string;
+    kind: TileflowMapLibreDomRenderTargetKind;
+}>;
+type TileflowMapLibreDomRenderTargetListener<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = (targets: readonly TileflowMapLibreDomRenderTarget<TAnnotation>[]) => void;
+type TileflowMapLibreDomStateChangeReason = 'popup:close' | 'popup:open' | 'target:remove';
+type TileflowMapLibreDomInteractionStateListener = (state: TileflowInteractionState, previous: TileflowInteractionState, reason: TileflowMapLibreDomStateChangeReason) => void;
+type TileflowMapLibreDomDiagnosticListener = (diagnostics: readonly TileflowInteractionDiagnostic[]) => void;
+type TileflowMapLibreDomCustomRenderers = Readonly<{
+    marker: boolean;
+    popup: boolean;
+    tooltip: boolean;
+}>;
+type TileflowLegacyMarker = Readonly<{
+    color?: string;
+    coordinates: readonly [longitude: number, latitude: number];
+    id: string;
+    label?: string;
+}>;
+type TileflowNormalizedLegacyMarkers = Readonly<{
+    annotations: readonly TileflowAnnotation[];
+    /** Exact legacy element titles, including an explicitly empty label. */
+    titles: ReadonlyMap<string, string>;
+}>;
+/** Normalizes the deprecated plural-coordinate marker shape once for all framework adapters. */
+declare function normalizeTileflowLegacyMarkers(markers: readonly TileflowLegacyMarker[]): TileflowNormalizedLegacyMarkers;
+type TileflowMapLibreDomRuntimeOptions<TMap, TMarker extends TileflowMapLibrePositioned<TMap>, TOverlay extends TileflowMapLibrePositioned<TMap>, TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    createMarker: (input: TileflowMapLibreDomMarkerFactoryInput<TAnnotation>) => TMarker;
+    createOverlay: (input: TileflowMapLibreDomOverlayFactoryInput<TAnnotation>) => TOverlay;
+    customMarker?: boolean;
+    customPopup?: boolean;
+    customTooltip?: boolean;
+    defaultInteractionState?: TileflowInteractionState;
+    document: TileflowMapLibreDomDocument;
+    idPrefix?: string;
+    interactionState?: TileflowInteractionState;
+    map: TMap;
+    onDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
+    onInteractionStateChange?: TileflowMapLibreDomInteractionStateListener;
+    reorderMarkers?: (markers: readonly TMarker[], annotations: readonly TAnnotation[], previousMarkers: readonly TMarker[], previousAnnotations: readonly TAnnotation[]) => void;
+    updateMarker?: (marker: TMarker, input: Readonly<{
+        annotation: TAnnotation;
+        element: HTMLElement;
+        previousAnnotation: TAnnotation;
+    }>) => void;
+    updateOverlay?: (overlay: TOverlay, input: Readonly<{
+        annotation: TAnnotation;
+        container: HTMLElement;
+        kind: TileflowMapLibreDomOverlayKind;
+        previousAnnotation: TAnnotation;
+    }>) => void;
+}>;
+type TileflowMapLibreDomRuntime<TAnnotation extends TileflowAnnotation = TileflowAnnotation> = Readonly<{
+    closePopup: () => boolean;
+    dispose: () => void;
+    getDiagnostics: () => readonly TileflowInteractionDiagnostic[];
+    getInteractionState: () => TileflowInteractionState;
+    getRenderTargets: () => readonly TileflowMapLibreDomRenderTarget<TAnnotation>[];
+    openPopup: (annotationId: string) => boolean;
+    reconcile: (annotations: readonly TAnnotation[]) => void;
+    setCustomRenderers: (renderers: TileflowMapLibreDomCustomRenderers) => void;
+    setInteractionState: (state: TileflowInteractionState) => void;
+    subscribeEvents: (listener: (event: TileflowAnnotationInteractionEvent<TAnnotation>) => void) => () => void;
+    subscribeDiagnostics: (listener: TileflowMapLibreDomDiagnosticListener) => () => void;
+    subscribeRenderTargets: (listener: TileflowMapLibreDomRenderTargetListener<TAnnotation>) => () => void;
+}>;
+/**
+ * Creates an annotation runtime without importing MapLibre or reading browser globals.
+ *
+ * The caller injects a document and factories for MapLibre-compatible positioned instances.
+ * Default content is written exclusively through `textContent`; named views are intentionally
+ * blank unless the corresponding `custom*` outlet is enabled.
+ */
+declare function createTileflowMapLibreDomRuntime<TMap, TMarker extends TileflowMapLibrePositioned<TMap>, TOverlay extends TileflowMapLibrePositioned<TMap>, TAnnotation extends TileflowAnnotation = TileflowAnnotation>(options: TileflowMapLibreDomRuntimeOptions<TMap, TMarker, TOverlay, TAnnotation>): TileflowMapLibreDomRuntime<TAnnotation>;
+
+type TileflowMapLibreInteractionParticipantKind = 'annotation' | 'semantic';
+type TileflowMapLibreInteractionParticipant = Readonly<{
+    setInteractionState: (state: TileflowInteractionState) => void;
+}>;
+type TileflowMapLibreInteractionCoordinatorOptions = Readonly<{
+    defaultInteractionState?: TileflowInteractionState;
+    interactionState?: TileflowInteractionState;
+    onInteractionStateChange?: (state: TileflowInteractionState, previous: TileflowInteractionState, reason: TileflowMapLibreDomStateChangeReason) => void;
+}>;
+type TileflowMapLibreInteractionCoordinator = Readonly<{
+    attach: (kind: TileflowMapLibreInteractionParticipantKind, participant: TileflowMapLibreInteractionParticipant) => () => void;
+    dispose: () => void;
+    getInteractionState: () => TileflowInteractionState;
+    /** Receives a controlled request from either mounted runtime. */
+    requestInteractionState: (state: TileflowInteractionState, previous: TileflowInteractionState, reason: TileflowMapLibreDomStateChangeReason) => void;
+    /** Commits a new application-controlled state to all mounted runtimes. */
+    setInteractionState: (state: TileflowInteractionState) => void;
+}>;
+/**
+ * Coordinates annotation and semantic runtimes around one popup state.
+ * The non-owning runtime commits first, so replacement closes the old popup before opening the new
+ * one. Framework adapters can therefore stay view bridges instead of reimplementing ordering.
+ */
+declare function createTileflowMapLibreInteractionCoordinator(options?: TileflowMapLibreInteractionCoordinatorOptions): TileflowMapLibreInteractionCoordinator;
+
+type TileflowMapLibrePoiFeature = Readonly<{
+    id?: number | string;
+    layer: Readonly<{
+        id: string;
+    }>;
+    properties?: Readonly<Record<string, unknown>>;
+    source?: string;
+    sourceLayer?: string;
+}>;
+type TileflowMapLibrePoiPointerEvent = Readonly<{
+    lngLat: Readonly<{
+        lat: number;
+        lng: number;
+    }>;
+    originalEvent?: Readonly<{
+        pointerType?: string;
+        touches?: unknown;
+    }>;
+    point: unknown;
+}>;
+type TileflowMapLibrePoiMap = Readonly<{
+    getStyle: () => unknown;
+    off?: (event: string, listener: (event: unknown) => void) => unknown;
+    on: (event: string, listener: (event: unknown) => void) => Readonly<{
+        unsubscribe?: () => void;
+    }> | unknown;
+    queryRenderedFeatures: (point: unknown, options: Readonly<{
+        layers: readonly string[];
+    }>) => readonly TileflowMapLibrePoiFeature[];
+}>;
+type TileflowMapLibrePoiMatch = Readonly<{
+    binding: TileflowInteractionBinding;
+    target: TileflowResolvedPoiFeatureTarget;
+}>;
+type TileflowMapLibrePoiControllerOptions = Readonly<{
+    bindings?: readonly TileflowInteractionBinding[];
+    cancelFrame: (frame: number) => void;
+    map: TileflowMapLibrePoiMap;
+    onActivate?: (match: TileflowMapLibrePoiMatch, inputModality: TileflowInteractionInputModality) => void;
+    onDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
+    onDiagnosticResolved?: (code: Extract<TileflowInteractionDiagnostic['code'], 'SEMANTIC_MANIFEST_MISMATCH'>) => void;
+    onHoverChange?: (match: TileflowMapLibrePoiMatch | null) => void;
+    onInteractionEvent?: (event: TileflowInteractionEvent) => void;
+    onManifestChange?: (available: boolean) => void;
+    requestFrame: (callback: () => void) => number;
+}>;
+type TileflowMapLibrePoiController = Readonly<{
+    dispose: () => void;
+    getHovered: () => TileflowMapLibrePoiMatch | null;
+    reconcile: (bindings: readonly TileflowInteractionBinding[]) => void;
+    refreshManifest: () => void;
+}>;
+/**
+ * Resolves semantic POIs from compiler metadata without exposing physical layers to applications.
+ * Pointer hit testing is coalesced to one query per animation frame.
+ */
+declare function createTileflowMapLibrePoiController(options: TileflowMapLibrePoiControllerOptions): TileflowMapLibrePoiController;
+
+type TileflowMapLibreSemanticDomOverlayFactoryInput = Readonly<{
+    binding: TileflowInteractionBinding;
+    container: HTMLElement;
+    kind: TileflowMapLibreDomOverlayKind;
+    target: TileflowResolvedSemanticFeatureTarget;
+}>;
+type TileflowMapLibreSemanticDomRenderTarget = Readonly<{
+    binding: TileflowInteractionBinding;
+    close: () => void;
+    container: HTMLElement;
+    content: TileflowInteractionContent;
+    key: string;
+    kind: TileflowMapLibreDomOverlayKind;
+    target: TileflowResolvedSemanticFeatureTarget;
+    viewName?: string;
+}>;
+type TileflowMapLibreSemanticDomRuntimeOptions<TMap, TOverlay extends TileflowMapLibrePositioned<TMap>> = Readonly<{
+    cancelFrame: (frame: number) => void;
+    createOverlay: (input: TileflowMapLibreSemanticDomOverlayFactoryInput) => TOverlay;
+    customPopup?: boolean;
+    customTooltip?: boolean;
+    defaultInteractionState?: TileflowInteractionState;
+    document: TileflowMapLibreDomDocument;
+    idPrefix?: string;
+    interactionState?: TileflowInteractionState;
+    map: TMap;
+    onDiagnostic?: (diagnostic: TileflowInteractionDiagnostic) => void;
+    onInteractionStateChange?: (state: TileflowInteractionState, previous: TileflowInteractionState, reason: TileflowMapLibreDomStateChangeReason) => void;
+    poiMap: TileflowMapLibrePoiMap;
+    requestFrame: (callback: () => void) => number;
+}>;
+type TileflowMapLibreSemanticDomRuntime = Readonly<{
+    closePopup: () => boolean;
+    dispose: () => void;
+    getDiagnostics: () => readonly TileflowInteractionDiagnostic[];
+    getInteractionState: () => TileflowInteractionState;
+    getRenderTargets: () => readonly TileflowMapLibreSemanticDomRenderTarget[];
+    reconcile: (bindings: readonly TileflowInteractionBinding[]) => void;
+    setCustomRenderers: (renderers: Pick<TileflowMapLibreDomCustomRenderers, 'popup' | 'tooltip'>) => void;
+    setInteractionState: (state: TileflowInteractionState) => void;
+    subscribeDiagnostics: (listener: (diagnostics: readonly TileflowInteractionDiagnostic[]) => void) => () => void;
+    subscribeEvents: (listener: (event: TileflowInteractionEvent) => void) => () => void;
+    subscribeRenderTargets: (listener: (targets: readonly TileflowMapLibreSemanticDomRenderTarget[]) => void) => () => void;
+}>;
+/**
+ * Mounts semantic POI tooltip and popup shells around the manifest-scoped POI hit tester.
+ * MapLibre, the document, and the scheduler are injected so importing this module remains SSR-safe.
+ */
+declare function createTileflowMapLibreSemanticDomRuntime<TMap, TOverlay extends TileflowMapLibrePositioned<TMap>>(options: TileflowMapLibreSemanticDomRuntimeOptions<TMap, TOverlay>): TileflowMapLibreSemanticDomRuntime;
+
+export { type TileflowAnnotationRegistry, type TileflowAnnotationRegistryAdapter, type TileflowAnnotationRegistryEntry, type TileflowLegacyMarker, type TileflowMapLibreDomCustomRenderers, type TileflowMapLibreDomDiagnosticListener, type TileflowMapLibreDomDocument, type TileflowMapLibreDomInteractionStateListener, type TileflowMapLibreDomMarkerFactoryInput, type TileflowMapLibreDomOverlayFactoryInput, type TileflowMapLibreDomOverlayKind, type TileflowMapLibreDomRenderTarget, type TileflowMapLibreDomRenderTargetKind, type TileflowMapLibreDomRenderTargetListener, type TileflowMapLibreDomRuntime, type TileflowMapLibreDomRuntimeOptions, type TileflowMapLibreDomStateChangeReason, type TileflowMapLibreInteractionCoordinator, type TileflowMapLibreInteractionCoordinatorOptions, type TileflowMapLibreInteractionParticipant, type TileflowMapLibreInteractionParticipantKind, type TileflowMapLibrePoiController, type TileflowMapLibrePoiControllerOptions, type TileflowMapLibrePoiFeature, type TileflowMapLibrePoiMap, type TileflowMapLibrePoiMatch, type TileflowMapLibrePoiPointerEvent, type TileflowMapLibrePositioned, type TileflowMapLibreSemanticDomOverlayFactoryInput, type TileflowMapLibreSemanticDomRenderTarget, type TileflowMapLibreSemanticDomRuntime, type TileflowMapLibreSemanticDomRuntimeOptions, type TileflowNormalizedLegacyMarkers, type TileflowOverlayState, type TileflowOverlayStateChangeReason, type TileflowOverlayStateController, type TileflowOverlayStateListener, createTileflowAnnotationRegistry, createTileflowMapLibreDomRuntime, createTileflowMapLibreInteractionCoordinator, createTileflowMapLibrePoiController, createTileflowMapLibreSemanticDomRuntime, createTileflowOverlayStateController, normalizeTileflowLegacyMarkers };