@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/api/events.d.ts

@@ -0,0 +1,316 @@
+/**
+ * The events: one list, `DrawEvents`, that applications and extensions subscribe to alike
+ *
+ * An event is named `resource.pastParticiple`. A change of the document carries its source,
+ * and `document.changed` arrives once per transaction with every change of it.
+ */
+import type { Position } from 'geojson';
+import type { Dataset, DatasetRow } from './datasets.js';
+import type { DrawError } from './errors.js';
+import type { Hit } from './extension/provider.js';
+import type { UpdateSource } from './extension/store.js';
+import type { Feature, FeatureInput, FileData, Group, Layer, LoadResult, Metadata, MoveTarget } from './model.js';
+import type { RuntimeOptions } from './options.js';
+import type { LayerStackEntry, Mode, Selection, SelectionType, SnapResult, VertexSelection } from './state.js';
+/** A point on the screen, as `[x, y]` in CSS pixels. */
+export type ScreenPoint = [number, number];
+/**
+ * Everything one transaction changed, as `document.changed` and the subscribers of the Store
+ * receive it. It arrives once per transaction, and each category is present only when the
+ * transaction changed it.
+ *
+ * `document.changed` fires only for a transaction that changed the document (features, layers,
+ * groups, metadata or files); the selection, the editing and the mode are carried along when
+ * the same transaction changed them. A change of the state of this client alone has its own
+ * event (`selection.changed`, `mode.changed` and so on).
+ */
+export interface DocumentChange {
+    /** Where the writes came from */
+    source?: UpdateSource;
+    /**
+     * True when the notification replaces the whole document at once, as a Store given in the
+     * `store` option does when it takes a document from elsewhere. The current mode drops what
+     * it was drawing then (`ModeHandler.onCancel`), because the shape it holds may refer to
+     * what is gone. A Store sets it; the changes that come with it list what was replaced.
+     */
+    reset?: boolean;
+    /** The features created, updated and deleted */
+    features?: {
+        created?: Feature[];
+        updated?: Array<{
+            id: string;
+            feature: Feature;
+            previous: Feature;
+            /** True while a drag or a drawing is in progress; a final update always follows */
+            isIntermediate?: boolean;
+        }>;
+        deleted?: Feature[];
+    };
+    /** The layers created, updated and deleted, and the change of their stacking order */
+    layers?: {
+        created?: Layer[];
+        updated?: Array<{
+            id: string;
+            layer: Layer;
+            previous: Layer;
+        }>;
+        deleted?: Layer[];
+        orderChanged?: {
+            order: string[];
+            previous: string[];
+        };
+    };
+    /** The groups created, updated and deleted */
+    groups?: {
+        created?: Group[];
+        updated?: Array<{
+            id: string;
+            group: Group;
+            previous: Group;
+        }>;
+        deleted?: Group[];
+    };
+    /** The new order of the items of a layer */
+    layerReorder?: {
+        layerId: string;
+        order: string[];
+        previous: string[];
+    };
+    /** The new order of the features of a group */
+    groupReorder?: {
+        groupId: string;
+        featureIds: string[];
+        previous: string[];
+    };
+    /** The new selection and the one before it */
+    selection?: {
+        type: SelectionType | null;
+        ids: string[];
+        previousType: SelectionType | null;
+        previousIds: string[];
+    };
+    /** The IDs of the features whose editing started and ended */
+    editing?: {
+        started?: string[];
+        ended?: string[];
+    };
+    /** The new mode and the one before it */
+    mode?: {
+        mode: Mode;
+        previous: Mode;
+    };
+    /** The new metadata and the one before it */
+    metadata?: {
+        metadata: Metadata;
+        previous: Metadata;
+    };
+    /** The embedded files created and deleted */
+    files?: {
+        created?: FileData[];
+        deleted?: FileData[];
+    };
+}
+/**
+ * The events, by name, with their payloads.
+ */
+export interface DrawEvents {
+    /** A feature was created */
+    'feature.created': {
+        feature: Feature;
+        source: string;
+    };
+    /** A feature changed; `intermediate` is true while a drag is in progress */
+    'feature.updated': {
+        feature: Feature;
+        previous: Feature;
+        source: string;
+        intermediate: boolean;
+    };
+    /** A feature was deleted */
+    'feature.deleted': {
+        feature: Feature;
+        source: string;
+    };
+    /** A feature moved between layers or groups */
+    'feature.moved': {
+        feature: Feature;
+        from: MoveTarget;
+        to: MoveTarget;
+        source: string;
+    };
+    /** A layer was created */
+    'layer.created': {
+        layer: Layer;
+        source: string;
+    };
+    /** A layer changed */
+    'layer.updated': {
+        layer: Layer;
+        previous: Layer;
+        source: string;
+    };
+    /** A layer was deleted */
+    'layer.deleted': {
+        layer: Layer;
+        source: string;
+    };
+    /** The stacking order of the layers changed */
+    'layer.reordered': {
+        order: readonly string[];
+        previous: readonly string[];
+        source: string;
+    };
+    /** A group was created */
+    'group.created': {
+        group: Group;
+        source: string;
+    };
+    /** A group changed */
+    'group.updated': {
+        group: Group;
+        previous: Group;
+        source: string;
+    };
+    /** A group was ungrouped */
+    'group.deleted': {
+        group: Group;
+        source: string;
+    };
+    /** The title or the description changed */
+    'metadata.updated': {
+        metadata: Metadata;
+        previous: Metadata;
+        source: string;
+    };
+    /**
+     * Every change of one transaction that changed the document (features, layers, groups,
+     * metadata or files); it arrives once per such transaction, after the events of the
+     * resources. A change of the selection, the mode or another state of this client alone does
+     * not fire it.
+     */
+    'document.changed': DocumentChange;
+    /** A document was loaded */
+    'document.loaded': {
+        result: LoadResult;
+        source: string;
+    };
+    /** The selection changed */
+    'selection.changed': {
+        selection: Selection;
+        previous: Selection;
+    };
+    /** The vertex selection changed */
+    'vertexSelection.changed': {
+        selection: VertexSelection | null;
+        previous: VertexSelection | null;
+    };
+    /** A drag started */
+    'drag.started': {
+        kind: 'feature' | 'vertex' | 'handle';
+        featureIds: string[];
+    };
+    /** A drag ended; `cancelled` is true when it was cancelled */
+    'drag.ended': {
+        kind: 'feature' | 'vertex' | 'handle';
+        featureIds: string[];
+        cancelled: boolean;
+    };
+    /** The mode changed */
+    'mode.changed': {
+        mode: Mode;
+        previous: Mode;
+    };
+    /** The items this client hides changed; `ids` is the whole set after the change */
+    'hidden.changed': {
+        ids: readonly string[];
+    };
+    /** Read-only was turned on or off */
+    'readOnly.changed': {
+        readOnly: boolean;
+    };
+    /** The interaction lock was turned on or off */
+    'interactionLock.changed': {
+        locked: boolean;
+    };
+    /**
+     * `draw.options.update` changed the options; `options` and `previous` are what
+     * `draw.options.get()` returns after and before the change. An update that leaves every
+     * value as it was does not fire it
+     */
+    'options.changed': {
+        options: Readonly<RuntimeOptions>;
+        previous: Readonly<RuntimeOptions>;
+    };
+    /** The snapping target changed */
+    'snap.changed': {
+        result: SnapResult | null;
+    };
+    /**
+     * The shape being drawn changed, or was cleared (`feature` is `null`). It fires once per
+     * change, with no throttling: at each vertex, at each move of the pointer that moves the
+     * shape, and when the shape is created, cancelled or left. `feature` has the type, the
+     * geometry and the layer of the shape, the ID it will be created with, and the radius of a
+     * circle; it is a copy that the drawing does not change afterwards. `confirmedVertices` and
+     * `highlightVertex` are the options the shape was shown with (`ModeContext.preview.set`):
+     * each is left out when it was not given, and both when the shape is cleared.
+     */
+    'preview.changed': {
+        feature: FeatureInput | null;
+        confirmedVertices?: number;
+        highlightVertex?: number;
+    };
+    /**
+     * A click on the map in the select mode, whether it hit something or not. `lngLat` is the
+     * position of the pointer before snapping, and `hit` the frontmost thing under it (a feature,
+     * a row of a dataset, a companion), or `null` when the click hit nothing
+     */
+    'map.clicked': {
+        lngLat: Position;
+        point: ScreenPoint;
+        hit: Hit | null;
+    };
+    /** A row of a dataset was clicked */
+    'dataset.clicked': {
+        datasetId: string;
+        rowIndex: number;
+        row: DatasetRow;
+        lngLat: Position;
+        point: ScreenPoint;
+    };
+    /** A dataset was added */
+    'dataset.added': {
+        dataset: Dataset;
+    };
+    /** A dataset was removed */
+    'dataset.removed': {
+        datasetId: string;
+    };
+    /** The stacking order of the datasets changed */
+    'dataset.reordered': {
+        order: readonly string[];
+        previous: readonly string[];
+    };
+    /**
+     * The image mode asks for an image to place at a position: the application picks a file
+     * and loads it with `document.load(file, { coordinate: lngLat, zoom, layerId })`. `lngLat` is
+     * the clicked position when a click led to the mode (a listener of `map.clicked` entered it),
+     * and the center of the map when the mode was entered otherwise
+     */
+    'image.requested': {
+        lngLat: Position;
+        zoom: number;
+        layerId: string;
+    };
+    /** The divisions of the stacking order changed */
+    'layerStack.changed': {
+        entries: readonly LayerStackEntry[];
+    };
+    /** Loading or reading an image failed */
+    error: {
+        error: DrawError;
+        source: string;
+        featureId?: string;
+    };
+}
+/** A function that receives the payload of an event. */
+export type DrawEventListener<K extends keyof DrawEvents = keyof DrawEvents> = (payload: DrawEvents[K]) => void;

package/dist/api/extension/context.d.ts

@@ -0,0 +1,247 @@
+/**
+ * The contexts an extension works through
+ *
+ * Each kind of extension receives one narrow context with only what that kind needs. Every
+ * type a context holds is part of the public API and follows semver.
+ */
+import type { Position } from 'geojson';
+import type { BBox } from '../../geometry/types.js';
+import type { DatasetRow } from '../datasets.js';
+import type { Draw } from '../draw.js';
+import type { DrawingResource } from '../drawing.js';
+import type { DrawEvents, ScreenPoint } from '../events.js';
+import type { ExtensionsCollections } from '../extensions.js';
+import type { Feature, FeatureInput, FeatureType, Layer } from '../model.js';
+import type { SelectionStyleOptions } from '../options.js';
+import type { Mode, SnapResult } from '../state.js';
+import type { Hit } from './provider.js';
+import type { StoreView } from './store.js';
+/** The positions and the heights on the terrain, for placing things on it. */
+export interface TerrainAnchors {
+    /**
+     * The point on the screen of a position lifted to the ground.
+     *
+     * @returns The point, or `null` when the terrain is off or not ready
+     */
+    project(lngLat: Position): ScreenPoint | null;
+    /**
+     * The height of the ground at a position.
+     *
+     * @returns The height in meters; 0 when the terrain is off
+     */
+    elevation(lngLat: Position): number;
+    /**
+     * The opacity for a mark at a position: lower when the terrain hides it from the camera.
+     *
+     * @returns A value from 0 to 1; 1 when the terrain is off
+     */
+    ghostOpacity(lngLat: Position): number;
+    /** A number that changes whenever the heights `elevation` returns may have changed. */
+    generation(): number;
+}
+/** The automatic names of new features, layers and groups. */
+export interface NameGenerator {
+    /**
+     * The next name for a type.
+     *
+     * @returns The name, or `undefined` for a feature when automatic names are off
+     */
+    next(type: FeatureType | 'Layer' | 'Group'): string | undefined;
+}
+/** The conversion between positions on the map and points on the screen. */
+export interface ScreenContext {
+    /** The point on the screen of a position. */
+    project(lngLat: Position): ScreenPoint;
+    /** The position on the map of a point on the screen. */
+    unproject(point: ScreenPoint): Position;
+    /**
+     * The extent of a feature on the screen, in pixels; a feature off the screen still has
+     * one.
+     *
+     * @returns The corners of the extent, or `null` when the feature has nothing to draw
+     */
+    bounds(feature: Feature): {
+        min: ScreenPoint;
+        max: ScreenPoint;
+    } | null;
+    /**
+     * The outline of the selection frame of a feature on the screen, in pixels, without the
+     * margin the frame is drawn with (`selectionStyle.boundingBox.margin`): its four corners in
+     * the order top left, top right, bottom right, bottom left of the shape as it stands
+     * unturned. It answers for every type: an image and any other turned shape give the turned
+     * corners, a line or an area the corners of its extent, a point the square its marker
+     * spans (its radius and its outline), and a custom type the corners of its `outline`, or of
+     * its `bounds` when it has none. A feature
+     * off the screen still has one. The engine draws the frame with every edge moved the margin
+     * outward from these corners.
+     *
+     * A custom type must not call it for its own features from its `outline` or `bounds`, which
+     * it calls.
+     *
+     * @returns The four corners, or an empty array when the feature has nothing to draw
+     */
+    outline(feature: Feature): ScreenPoint[];
+    /** The zoom of the map */
+    readonly zoom: number;
+    /** The pixel ratio the drawing uses */
+    readonly pixelRatio: number;
+}
+/**
+ * What every context of an extension has: the public API, the Store, the events, the
+ * terrain, the automatic names, the screen and a way to redraw, and the shape being drawn.
+ */
+export interface ExtensionContext {
+    /** The whole public API; an extension reads and writes the document through it */
+    readonly draw: Draw;
+    /** The Store, to read the document and the state and to subscribe to their changes */
+    readonly store: StoreView;
+    /**
+     * Subscribes to an event, with the same names as `draw.on`. The subscription ends by itself
+     * when the extension is removed.
+     *
+     * @returns The function that unsubscribes
+     */
+    on<K extends keyof DrawEvents>(event: K, listener: (payload: DrawEvents[K]) => void): () => void;
+    /** Unsubscribes from an event. */
+    off<K extends keyof DrawEvents>(event: K, listener: (payload: DrawEvents[K]) => void): void;
+    /**
+     * Subscribes to the next occurrence of an event only.
+     *
+     * @returns The function that unsubscribes before it occurs
+     */
+    once<K extends keyof DrawEvents>(event: K, listener: (payload: DrawEvents[K]) => void): () => void;
+    /** The positions and the heights on the terrain */
+    readonly terrain: TerrainAnchors;
+    /** The automatic names of new features, layers and groups */
+    readonly names: NameGenerator;
+    /** The conversion between the map and the screen */
+    readonly screen: ScreenContext;
+    /**
+     * Asks for the features to be drawn again.
+     *
+     * @param filter - Only the features of this type, or with these IDs; every feature when it
+     *   is left out
+     */
+    invalidate(filter?: {
+        type?: string;
+        ids?: string[];
+    }): void;
+    /**
+     * The shape the current drawing mode is drawing: the same object as `draw.drawing`, to place,
+     * finish, cancel, undo and redo its vertices
+     */
+    readonly drawing: DrawingResource;
+}
+/**
+ * The context of a plugin.
+ */
+export interface PluginContext extends ExtensionContext {
+    /**
+     * The same collections as `draw.extensions`. What a plugin adds through them is removed by
+     * itself when the plugin is removed.
+     */
+    readonly extensions: ExtensionsCollections;
+}
+/**
+ * The context of a mode.
+ */
+export interface ModeContext extends ExtensionContext {
+    /**
+     * Changes the mode.
+     *
+     * @returns False when the mode cannot be entered now
+     */
+    setMode(mode: Mode): boolean;
+    /**
+     * The topmost feature or dataset row at a point on the screen.
+     *
+     * @param options - `tolerancePx` is how far from the point a hit may be, in pixels
+     * @returns What was hit, or `null`
+     */
+    hitTest(point: ScreenPoint, options?: {
+        tolerancePx?: number;
+    }): Hit | null;
+    /** Where a point on the screen snaps to; its own position when nothing is snapped to. */
+    snap(point: ScreenPoint): SnapResult;
+    /**
+     * Creates a feature the way the built-in modes do: the writable layer, the ID, the
+     * automatic name and the reference zoom follow the same rules.
+     *
+     * @returns The new feature, or `null` when it is refused (read-only, a lock)
+     */
+    commitFeature(input: FeatureInput): Feature | null;
+    /** Shows the shape being drawn before it is created. */
+    readonly preview: {
+        /**
+         * Shows this shape as the one being drawn.
+         *
+         * @param options - `confirmedVertices` is how many vertices from the start are placed:
+         *   the line up to them is drawn solid and the rest, up to the pointer, dashed (every
+         *   vertex when it is left out); `highlightVertex` is the index of a vertex drawn
+         *   highlighted, such as the first vertex of an area the next click would close
+         */
+        set(feature: FeatureInput, options?: {
+            confirmedVertices?: number;
+            highlightVertex?: number;
+        }): void;
+        /** Stops showing it */
+        clear(): void;
+    };
+    /** The cursor of the map. */
+    readonly cursor: {
+        /** Sets the cursor, as a CSS cursor value */
+        set(cursor: string): void;
+        /**
+         * Goes back to the cursor of the mode: the one it set in `onEnter`, or the cursor of the
+         * map when it set none there. The cursor the mode set is taken back when it is left.
+         */
+        reset(): void;
+    };
+    /** The look of the selected features. */
+    readonly selectionStyle: Required<SelectionStyleOptions>;
+    /**
+     * The layer a new feature goes into: the active layer when it can be written (it exists,
+     * is visible, is not locked and not hidden on this client), otherwise the first layer that
+     * can.
+     *
+     * @returns The layer, or `null` when no layer can be written
+     */
+    writableLayer(): Layer | null;
+    /**
+     * The rows of the datasets that a shape can trace along, within an extent. Empty when
+     * snapping to the datasets is off.
+     *
+     * @param bbox - The extent, as `[west, south, east, north]` in degrees
+     * @returns The rows, each with the ID of its dataset and its index there; the dataset finds
+     *   a row by the ID of a snapping target with `draw.datasets.get(datasetId).findRow(id)`
+     */
+    listTraceRows(bbox: BBox): {
+        datasetId: string;
+        rowIndex: number;
+        row: DatasetRow;
+    }[];
+}
+/** What a hit test of a custom feature type or a companion receives. */
+export interface HitTestContext {
+    /** The point on the screen */
+    point: ScreenPoint;
+    /** The position on the map */
+    lngLat: Position;
+    /** How far from the point a hit may be, in pixels */
+    tolerancePx: number;
+    /** The conversion between the map and the screen */
+    screen: ScreenContext;
+}
+/** What a provider of snapping candidates receives. */
+export interface SnapContext {
+    /** The point on the screen */
+    point: ScreenPoint;
+    /** The position on the map */
+    lngLat: Position;
+    /** How far from the point a candidate may be, in pixels */
+    tolerancePx: number;
+    /** The conversion between the map and the screen */
+    screen: ScreenContext;
+    /** The IDs of the features that must not be snapped to, such as the one being drawn */
+    excludeIds: ReadonlySet<string>;
+}

package/dist/api/extension/feature-type.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Custom feature types: the one definition that says how a type is drawn, hit, selected and
+ * resized
+ */
+import type { Geometry, Position } from 'geojson';
+import type { BBox } from '../../geometry/types.js';
+import type { ScreenPoint } from '../events.js';
+import type { Feature, FeaturePatch } from '../model.js';
+import type { HitTestContext, ScreenContext, SnapContext } from './context.js';
+import type { DrawPointerEvent } from './mode.js';
+import type { Hit, SnapCandidate } from './provider.js';
+import type { FeatureRenderer } from './render.js';
+/** One handle on a selected feature. */
+export interface Handle {
+    /** The ID of the handle, unique within the feature */
+    id: string;
+    /** The position of the handle */
+    position: Position;
+    /** The kind of handle, as its provider names it */
+    kind: string;
+    /** The CSS cursor over the handle */
+    cursor?: string;
+}
+/**
+ * The definition of a custom feature type. Its handles and snapping candidates are written
+ * here; a provider is only for the types an extension does not define.
+ */
+export interface FeatureTypeDefinition {
+    /** The name of the type; it is registered under this name */
+    readonly type: string;
+    /** The kind of GeoJSON geometry the features of this type have; one kind per type */
+    readonly geometry: Geometry['type'];
+    /**
+     * How far beyond its geometry a feature of this type can be hit, in pixels, such as the
+     * half size of an icon drawn on a point. The candidates of a hit test are gathered this much
+     * farther out; 0 when it is left out.
+     */
+    readonly hitPaddingPx?: number;
+    /** How the features of this type are drawn */
+    readonly renderer: FeatureRenderer;
+    /**
+     * Which features of the type the definition takes, for a definition that overrides a
+     * built-in type (`extensions.featureTypes.override`). A feature for which it returns false
+     * keeps the built-in type: its built-in drawing (drawn in batches with the other features),
+     * hit test, box selection, selection frame, handles, snapping candidates and extent. The
+     * others are drawn, hit and framed by this definition. Every feature of the type is taken
+     * when it is left out.
+     *
+     * It is asked again whenever a feature changes, so its answer must follow from the feature
+     * (its properties, its geometry, its style) and nothing outside it. It is ignored in a
+     * definition given to `add`: a custom type takes every feature of its type.
+     */
+    appliesTo?(feature: Feature): boolean;
+    /**
+     * The extent of a feature on the map, `[west, south, east, north]` in degrees, for a type
+     * that draws beyond its geometry by a distance on the ground. The spatial index takes it:
+     * it gathers the candidates of a hit test and of a box selection, answers
+     * `features.list({ bbox })`, and decides which features are near enough to the view to be
+     * drawn. The extent of the geometry is used when it is left out, and when it returns an
+     * extent that is not four finite numbers from the west and south to the east and north.
+     *
+     * It is measured when a feature changes; call `invalidate({ type })` when it depends on
+     * something outside the document. A reach in pixels belongs in `hitPaddingPx`.
+     */
+    bbox?(feature: Feature): BBox;
+    /**
+     * Hit tests a feature of this type; the geometry is hit tested when it is left out.
+     *
+     * @returns What was hit, or `null`
+     */
+    hitTest?(feature: Feature, ctx: HitTestContext): Hit | null;
+    /**
+     * Whether a box selection takes a feature of this type.
+     *
+     * @param box - The corners of the box on the screen, in pixels
+     */
+    boxSelect?(feature: Feature, box: {
+        min: ScreenPoint;
+        max: ScreenPoint;
+    }, ctx: HitTestContext): boolean;
+    /**
+     * The extent of the selection box of a feature on the screen, in pixels.
+     *
+     * @returns The corners of the extent, or `null` when the feature has nothing to draw
+     */
+    bounds?(feature: Feature, ctx: ScreenContext): {
+        min: ScreenPoint;
+        max: ScreenPoint;
+    } | null;
+    /**
+     * The outline of the selection frame of a feature on the screen, in pixels, for a type whose
+     * shape turns: its four corners in the order top left, top right, bottom right, bottom left
+     * of the shape as it stands unturned, without the margin of the frame
+     * (`selectionStyle.boundingBox.margin`). The engine draws the selection frame along it when
+     * it is given, and from `bounds` otherwise, with every edge moved the margin outward. For a
+     * type of any geometry but `Point`, the resize and rotate handles sit on the corners of that
+     * frame too; a `Point` type keeps a frame with no such handles.
+     *
+     * @returns The four corners; anything else (or an empty array) gives the frame of `bounds`
+     */
+    outline?(feature: Feature, ctx: ScreenContext): ScreenPoint[];
+    /**
+     * The handles that resize or reshape a selected feature. The engine draws them with the
+     * look of the vertex handles, hit tests them at the same size, and gives their drags to
+     * `onHandleDrag`.
+     */
+    handles?(feature: Feature, ctx: ScreenContext): Handle[];
+    /**
+     * The change a drag of one of its handles makes.
+     *
+     * @returns The patch to apply to the feature, or `null` for no change
+     */
+    onHandleDrag?(feature: Feature, handle: Handle, event: DrawPointerEvent): FeaturePatch | null;
+    /**
+     * A drag of one of its handles is about to start, before the first `onHandleDrag`.
+     *
+     * @returns False to refuse the drag; no `onHandleDrag` nor `onHandleDragEnd` follows then
+     */
+    onHandleDragStart?(feature: Feature, handle: Handle, event: DrawPointerEvent): boolean;
+    /**
+     * A drag of one of its handles ended, after the last `onHandleDrag` and its patch. It is
+     * called once for every drag that started, also when the drag is cut short.
+     *
+     * @param feature - The feature as it is now, or `null` when it is gone
+     */
+    onHandleDragEnd?(feature: Feature | null, handle: Handle, event: DrawPointerEvent): void;
+    /** The snapping candidates a feature of this type offers. */
+    snapCandidates?(feature: Feature, ctx: SnapContext): SnapCandidate[];
+}