@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

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[];
+}

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

@@ -0,0 +1,123 @@
+/**
+ * The input contract: the events a mode and a plugin receive, and the handler of a mode
+ *
+ * One rule holds for every input handler: returning true consumes the event, so that nothing
+ * after the handler receives it.
+ */
+import type { Position } from 'geojson';
+import type { ScreenPoint } from '../events.js';
+import type { SnapPreference, SnapResult } from '../state.js';
+import type { ModeContext } from './context.js';
+/** The modifier keys held during an input. */
+export interface Modifiers {
+    /** Whether Shift was held */
+    shift: boolean;
+    /** Whether Control was held */
+    ctrl: boolean;
+    /** Whether Alt (Option on macOS) was held */
+    alt: boolean;
+    /** Whether Meta (Command on macOS) was held */
+    meta: boolean;
+}
+/** A pointer input on the map, as a mode and a plugin receive it. */
+export interface DrawPointerEvent {
+    /** The point on the screen */
+    point: ScreenPoint;
+    /** The position on the map */
+    lngLat: Position;
+    /** Where the input snaps to; the position of the pointer when nothing is snapped to */
+    snapped: SnapResult;
+    /** The modifier keys held */
+    modifiers: Modifiers;
+    /** The kind of pointer */
+    pointerType: 'mouse' | 'touch' | 'pen';
+    /** The event of the browser */
+    original: PointerEvent;
+    /**
+     * True when the input was made from code by `draw.drawing` (`addVertex`, `moveTo`), not by
+     * the pointer. Its position is exact: a mode applies no click tolerance to it, so a vertex
+     * placed a few pixels from another is kept, and only one at exactly the same position is
+     * the same vertex. Left out for the input of the pointer.
+     */
+    programmatic?: boolean;
+}
+/** A key input, as a mode and a plugin receive it. */
+export interface DrawKeyEvent {
+    /** The key, as `KeyboardEvent.key` gives it */
+    key: string;
+    /** The modifier keys held */
+    modifiers: Modifiers;
+    /** The event of the browser */
+    original: KeyboardEvent;
+}
+/**
+ * The receivers of the input; `Plugin.input` and `ModeHandler` take any of them. Returning
+ * true consumes the event, so that nothing after the receiver gets it.
+ */
+export interface InputHandlers {
+    /** A pointer was pressed */
+    onPointerDown(event: DrawPointerEvent): boolean | void;
+    /** The pointer moved without a drag */
+    onPointerMove(event: DrawPointerEvent): boolean | void;
+    /** A pointer was released */
+    onPointerUp(event: DrawPointerEvent): boolean | void;
+    /** The pointer left the map */
+    onPointerLeave(): boolean | void;
+    /** A click */
+    onClick(event: DrawPointerEvent): boolean | void;
+    /** A double click */
+    onDoubleClick(event: DrawPointerEvent): boolean | void;
+    /** A drag started */
+    onDragStart(event: DrawPointerEvent): boolean | void;
+    /** The pointer moved during a drag */
+    onDrag(event: DrawPointerEvent): boolean | void;
+    /** A drag ended */
+    onDragEnd(event: DrawPointerEvent): boolean | void;
+    /** A drag was cancelled */
+    onDragCancel(event: DrawPointerEvent): boolean | void;
+    /** A key was pressed */
+    onKeyDown(event: DrawKeyEvent): boolean | void;
+    /** A key was released */
+    onKeyUp(event: DrawKeyEvent): boolean | void;
+}
+/**
+ * The contract of a mode: how it enters, exits and receives the input. Every member is
+ * optional; returning true from an input receiver consumes the event.
+ */
+export interface ModeHandler extends Partial<InputHandlers> {
+    /**
+     * Whether the mode writes new features. Such a mode is entered only while a layer can be
+     * written, and a double click never zooms the map while it is the current mode, whether or
+     * not it takes the double click; false when it is left out.
+     */
+    readonly writes?: boolean;
+    /** How the mode wants the positions of its input snapped; every input snaps when left out */
+    readonly snapPreference?: SnapPreference;
+    /** Called when the mode is entered */
+    onEnter?(): void;
+    /** Called when the mode is left */
+    onExit?(): void;
+    /**
+     * Called when the mode is interrupted: by an Escape that neither a plugin nor the mode
+     * consumed, or when the Store replaces its whole document (a notification with
+     * `reset: true`). The mode drops what it was drawing and stays the current mode.
+     */
+    onCancel?(): void;
+    /**
+     * Removes the last vertex of the shape being drawn, as `ctx.drawing.undoVertex` asks.
+     *
+     * @returns True when a vertex was removed
+     */
+    onUndoVertex?(): boolean;
+    /**
+     * Puts back the vertex the last `onUndoVertex` removed, as `ctx.drawing.redoVertex` asks.
+     *
+     * @returns True when a vertex was put back
+     */
+    onRedoVertex?(): boolean;
+}
+/**
+ * The function that creates the handler of a mode. It is registered once, under its name,
+ * with `draw.extensions.modes.add(name, factory)`.
+ */
+export type ModeFactory = (ctx: ModeContext) => ModeHandler;

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

@@ -0,0 +1,51 @@
+/**
+ * Plugins: bundles of other extensions and state
+ */
+import type { Feature } from '../model.js';
+import type { PluginContext } from './context.js';
+import type { DrawPointerEvent, InputHandlers } from './mode.js';
+/**
+ * A plugin: a bundle of modes, feature types, overlays, providers and state, added with
+ * `draw.extensions.plugins.add`. What it adds through its context is removed by itself when
+ * the plugin is removed. Plugins talk to each other through their `api`.
+ *
+ * @typeParam Api - The API the plugin offers to others
+ */
+export interface Plugin<Api = unknown> {
+    /** The name it is registered under */
+    readonly name: string;
+    /** Called when the plugin is added; add its extensions and subscribe to events here. */
+    onAdd(ctx: PluginContext): void;
+    /** Called when the plugin is removed. */
+    onRemove?(): void;
+    /** The API others get with `draw.extensions.plugins.getApi(name)` */
+    readonly api?: Api;
+    /**
+     * Receivers of the input, called before those of the mode. Returning true consumes the
+     * event, so that the mode does not get it.
+     */
+    readonly input?: Partial<InputHandlers>;
+    /** The hooks of the select mode, and an exclusive interaction of the plugin */
+    readonly interaction?: {
+        /** Narrows the candidates of a selection to the IDs it returns */
+        filterSelection?(candidateIds: readonly string[]): string[];
+        /** A selected feature was clicked again; returning true means the plugin handled it */
+        onFeatureClick?(feature: Feature, event: DrawPointerEvent): boolean;
+        /** A feature was double-clicked; returning true means the plugin handled it */
+        onFeatureDoubleClick?(feature: Feature, event: DrawPointerEvent): boolean;
+        /**
+         * A drawing mode created a feature: a commit of `ModeContext.commitFeature`, which the
+         * built-in drawing modes use too, or the image placed by the load that follows a request
+         * of the image mode
+         */
+        onDrawCommit?(feature: Feature): void;
+        /** Whether the plugin is in an exclusive interaction, during which the mode stays still */
+        isBusy?(): boolean;
+        /** Completes the exclusive interaction */
+        finish?(): void;
+        /** Cancels the exclusive interaction */
+        cancel?(): void;
+        /** The element of the exclusive interaction; clicks inside it are left to the plugin */
+        container?(): HTMLElement | null;
+    };
+}

package/dist/api/extension/plugin.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};

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

@@ -0,0 +1,119 @@
+/**
+ * Providers: extensions that add snapping candidates, handles or companions to feature types
+ * they do not define
+ *
+ * A custom feature type describes its own handles and candidates in its definition; a
+ * provider is for the built-in types and the types of other extensions.
+ */
+import type { Position } from 'geojson';
+import type { Feature, FeaturePatch } from '../model.js';
+import type { HitTestContext, ScreenContext, SnapContext } from './context.js';
+import type { Handle } from './feature-type.js';
+import type { DrawPointerEvent } from './mode.js';
+import type { RenderContext } from './render.js';
+/** What a hit test found. */
+export interface Hit {
+    /** What was hit */
+    kind: 'feature' | 'dataset' | 'companion' | 'handle';
+    /** The ID of what was hit */
+    id: string;
+    /** The ID of the feature it belongs to */
+    featureId?: string;
+    /** The ID of the dataset, for a row of a dataset */
+    datasetId?: string;
+    /** The distance from the point, in pixels */
+    distancePx: number;
+}
+/** One snapping candidate. */
+export interface SnapCandidate {
+    /** The position to snap to */
+    position: Position;
+    /** The kind of candidate; a provider may use a kind of its own */
+    kind: 'vertex' | 'edge' | 'intersection' | 'guide' | (string & {});
+    /** The priority among candidates at the same distance; higher wins */
+    priority?: number;
+    /** Where the candidate came from, for display */
+    source?: string;
+}
+/** An extension that adds snapping candidates. */
+export interface SnapProvider {
+    /** The name it is registered under */
+    readonly name: string;
+    /** The candidates near the point of the context. */
+    candidates(ctx: SnapContext): SnapCandidate[];
+}
+/** An extension that shows handles of its own on the selected features and receives their drags. */
+export interface HandleProvider {
+    /** The name it is registered under */
+    readonly name: string;
+    /**
+     * The handles of 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 `onDrag`.
+     */
+    handles(feature: Feature, ctx: ScreenContext): Handle[];
+    /**
+     * The handles that belong to no feature, shown whatever is selected; they are hit and
+     * dragged like the others, and their drag arrives with `feature` as `null`.
+     */
+    globalHandles?(ctx: ScreenContext): Handle[];
+    /**
+     * The change a drag of one of its handles makes. It is called for every move of the drag
+     * and once more when the drag ends; the patch of the end is the one that stays.
+     *
+     * @param feature - The feature the handle is on; `null` for a handle of `globalHandles`
+     * @returns The patch to apply to the feature, or `null` for no change
+     */
+    onDrag(feature: Feature | null, handle: Handle, event: DrawPointerEvent): FeaturePatch | null;
+    /**
+     * A drag of one of its handles is about to start, before the first `onDrag`.
+     *
+     * @param feature - The feature the handle is on; `null` for a handle of `globalHandles`
+     * @returns False to refuse the drag: the pointer then does what it would do without the
+     *   handle, and no `onDrag` nor `onDragEnd` follows
+     */
+    onDragStart?(feature: Feature | null, handle: Handle, event: DrawPointerEvent): boolean;
+    /**
+     * A drag of one of its handles ended, after the last `onDrag` and its patch. It is called
+     * once for every drag that started, also when the drag is cut short.
+     *
+     * @param feature - The feature the handle is on as it is now; `null` for a handle of
+     *   `globalHandles`, or when the feature is gone
+     */
+    onDragEnd?(feature: Feature | null, handle: Handle, event: DrawPointerEvent): void;
+}
+/**
+ * An extension that draws a companion one step below a feature, such as a leader line, and
+ * hit tests it at the same step.
+ */
+export interface CompanionProvider {
+    /** The name it is registered under */
+    readonly name: string;
+    /**
+     * Whether a feature has a companion. It is asked for every feature on every frame and
+     * every hit test, so it must answer at once.
+     */
+    has(feature: Feature): boolean;
+    /** Draws the companion of a feature. */
+    draw(feature: Feature, ctx: RenderContext): void;
+    /**
+     * Hit tests the companion of a feature.
+     *
+     * It is asked at the step of the feature in the stacking order: when the point missed the
+     * feature itself, and before the feature behind it. At one point, the handles of the
+     * selection come first; then, from the front, each feature and then its companions, so a
+     * feature (its marker, its line or its area, with the click tolerance) wins over its own
+     * companion and a companion wins over the features behind its feature; the rows of a
+     * dataset come only after the features and the companions in front of them.
+     *
+     * @returns What was hit, or `null`
+     */
+    hitTest(feature: Feature, ctx: HitTestContext): Hit | null;
+    /**
+     * A companion was clicked.
+     *
+     * @param hit - What `hitTest` returned
+     * @returns True to consume the click, which then changes nothing else; false, or nothing,
+     *   to leave it to the select mode as a click on the feature
+     */
+    onClick?(feature: Feature, hit: Hit, event: DrawPointerEvent): boolean;
+}

package/dist/api/extension/provider.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};