@honua/react 0.1.0-beta.0 → 0.1.2-beta.0

package/contract/edit-snapping.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Renderer-neutral snapping for edit-sketch workflows.
+ *
+ * The engine resolves a pointer position (screen space plus a caller-provided
+ * projection function) against a {@link SnapIndex} of loaded features and
+ * returns the nearest snap candidate with deterministic ordering:
+ *
+ * 1. smallest screen distance wins;
+ * 2. at equal distance, `vertex` beats `edge` beats `feature`;
+ * 3. remaining ties break by source id, then feature id, then vertex /
+ *    segment ordinal.
+ *
+ * The index is a packed uniform grid over feature vertices, segments, and
+ * polygon bodies — no per-move full scans and no new runtime dependency.
+ * Geometry is GeoJSON-shaped (`Point`, `MultiPoint`, `LineString`,
+ * `MultiLineString`, `Polygon`, `MultiPolygon`, `GeometryCollection`).
+ *
+ * @module
+ */
+import type { EditWorkflowOptimisticHooks } from "./edit-session.js";
+import type { FeatureId } from "./types.js";
+export type SnapCandidateKind = "vertex" | "edge" | "feature";
+/** A point in renderer screen space (CSS pixels). */
+export interface SnapScreenPoint {
+    readonly x: number;
+    readonly y: number;
+}
+/** A geographic (or planar) coordinate as `[x, y]` / `[lng, lat]`. */
+export type SnapPosition = readonly [number, number];
+/** Projects a geographic position into screen space. */
+export type SnapProjection = (position: SnapPosition) => SnapScreenPoint;
+/** Per-source snapping overrides inside {@link SnappingConfig.sources}. */
+export interface SnapSourceOptions {
+    /** Disable the source entirely. @default true */
+    enabled?: boolean;
+    /** Candidate kinds for this source; overrides {@link SnappingConfig.kinds}. */
+    kinds?: readonly SnapCandidateKind[];
+}
+export interface SnappingConfig {
+    /** Master switch. */
+    enabled: boolean;
+    /** Snap tolerance in screen pixels (candidates at exactly the tolerance still snap). */
+    tolerance: number;
+    /**
+     * Candidate kinds resolved by default. `feature` adds whole-feature
+     * (feature-body) candidates: inside a polygon the pointer itself is a
+     * zero-distance candidate; otherwise the nearest point on the feature.
+     */
+    kinds: readonly SnapCandidateKind[];
+    /**
+     * Per-source enablement keyed by source id. Missing sources default to
+     * enabled with the global `kinds`. `false` disables a source.
+     */
+    sources: Readonly<Record<string, boolean | SnapSourceOptions>>;
+}
+export declare const DEFAULT_SNAPPING_CONFIG: SnappingConfig;
+/** Merge a partial config over {@link DEFAULT_SNAPPING_CONFIG}. */
+export declare function resolveSnappingConfig(input?: Partial<SnappingConfig>): SnappingConfig;
+export interface SnapCandidate {
+    kind: SnapCandidateKind;
+    sourceId: string;
+    featureId: FeatureId;
+    /** Geographic position of the snap target. */
+    position: SnapPosition;
+    /** Screen-space position of the snap target. */
+    screenPoint: SnapScreenPoint;
+    /** Screen-space distance from the pointer, in pixels. */
+    distance: number;
+    /** Ordinal of the snapped vertex within the feature (vertex candidates). */
+    vertexIndex?: number;
+    /** Ordinal of the snapped segment within the feature (edge candidates). */
+    segmentIndex?: number;
+}
+export interface SnapQueryInput {
+    /** Pointer position in screen space. */
+    point: SnapScreenPoint;
+    /** Pointer position in geographic space. */
+    position: SnapPosition;
+    /** Projection from geographic space to screen space. */
+    project: SnapProjection;
+}
+export interface SnapResolution {
+    snapped: boolean;
+    /** Best candidate under deterministic ordering, when snapped. */
+    candidate?: SnapCandidate;
+    /** All candidates within tolerance, deterministically sorted. */
+    candidates: readonly SnapCandidate[];
+}
+export declare function compareSnapCandidates(a: SnapCandidate, b: SnapCandidate): number;
+/** Feature input for the snap index. Geometry is GeoJSON-shaped. */
+export interface SnapIndexFeatureInput {
+    id: FeatureId;
+    geometry: Record<string, unknown> | null | undefined;
+}
+export interface SnapIndexStats {
+    sourceCount: number;
+    featureCount: number;
+    vertexCount: number;
+    segmentCount: number;
+    /** Number of grid rebuilds performed so far (increments after invalidation). */
+    gridBuilds: number;
+}
+/**
+ * Uniform packed-grid spatial index over snap sources.
+ *
+ * Mutations mark the grid dirty; it is rebuilt lazily on the next query.
+ * Feature geometries are treated as immutable once handed to the index.
+ */
+export declare class SnapIndex {
+    #private;
+    /** Replace every indexed feature for a source. */
+    setSourceFeatures(sourceId: string, features: readonly SnapIndexFeatureInput[]): void;
+    /**
+     * Insert or replace a single feature. Returns the previous feature input
+     * (id + geometry) when one was indexed, so optimistic edits can restore it.
+     */
+    upsertFeature(sourceId: string, feature: SnapIndexFeatureInput): SnapIndexFeatureInput | undefined;
+    /** Remove a single feature. Returns the removed feature input, if any. */
+    removeFeature(sourceId: string, featureId: FeatureId): SnapIndexFeatureInput | undefined;
+    removeSource(sourceId: string): void;
+    clear(): void;
+    /** Force a lazy grid rebuild on the next query (e.g. after realtime updates). */
+    invalidate(): void;
+    sourceIds(): readonly string[];
+    stats(): SnapIndexStats;
+    /**
+     * Resolve a pointer against this index. See {@link resolveSnapCandidate}
+     * for the deterministic ordering contract.
+     */
+    resolve(input: SnapQueryInput, config?: Partial<SnappingConfig>): SnapResolution;
+}
+export declare function createSnapIndex(): SnapIndex;
+/**
+ * Resolve the pointer against the index and return the nearest snap candidate
+ * under the deterministic ordering documented on this module.
+ */
+export declare function resolveSnapCandidate(index: SnapIndex, input: SnapQueryInput, config?: Partial<SnappingConfig>): SnapResolution;
+/**
+ * Return `geometry` with its active sketch vertex replaced by `position`.
+ *
+ * The active vertex is the last drawn coordinate: the point itself for
+ * `Point`, the final coordinate for `MultiPoint` / `LineString` /
+ * `MultiLineString`, and the final non-closing vertex of the last ring for
+ * `Polygon` / `MultiPolygon` (ring closure is preserved). Unknown geometry
+ * shapes are returned unchanged.
+ */
+export declare function withSnappedActiveVertex(geometry: Record<string, unknown> | null, position: SnapPosition): Record<string, unknown> | null;
+export interface SnapIndexEditSessionHookOptions<T = Record<string, unknown>> {
+    /** Hooks to compose with; index maintenance runs before delegation. */
+    inner?: EditWorkflowOptimisticHooks<T>;
+}
+/**
+ * Optimistic edit-session hooks that keep a {@link SnapIndex} in sync with
+ * an edit workflow's lifecycle: `apply` upserts (or removes, for deletes)
+ * the edited feature, `rollback` restores the pre-edit index entry, and
+ * `commit` finalizes it. Pass the result as the `optimistic` option of
+ * `createEditSession` / `createEditSketchWorkflow`.
+ */
+export declare function createSnapIndexEditSessionHooks<T = Record<string, unknown>>(index: SnapIndex, options?: SnapIndexEditSessionHookOptions<T>): EditWorkflowOptimisticHooks<T>;
+//# sourceMappingURL=edit-snapping.d.ts.map

package/contract/edit-snapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-snapping.d.ts","sourceRoot":"","sources":["../../../src/contract/edit-snapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAkD,MAAM,mBAAmB,CAAC;AACrH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5C,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9D,qDAAqD;AACrD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sEAAsE;AACtE,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,YAAY,KAAK,eAAe,CAAC;AAEzE,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,iDAAiD;IACjD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,KAAK,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,cAAc;IAC7B,qBAAqB;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACpC;;;OAGG;IACH,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAAC,CAAC,CAAC;CAChE;AAED,eAAO,MAAM,uBAAuB,EAAE,cAKpC,CAAC;AAEH,mEAAmE;AACnE,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc,CAOrF;AAID,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,CAAC;IACrB,8CAA8C;IAC9C,QAAQ,EAAE,YAAY,CAAC;IACvB,gDAAgD;IAChD,WAAW,EAAE,eAAe,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,KAAK,EAAE,eAAe,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,EAAE,YAAY,CAAC;IACvB,wDAAwD;IACxD,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,iEAAiE;IACjE,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,iEAAiE;IACjE,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CACtC;AAMD,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAOhF;AAeD,oEAAoE;AACpE,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,SAAS,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;CACpB;AAyCD;;;;;GAKG;AACH,qBAAa,SAAS;;IAMpB,kDAAkD;IAC3C,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,qBAAqB,EAAE,GAAG,IAAI;IAO5F;;;OAGG;IACI,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,SAAS;IAYzG,0EAA0E;IACnE,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,qBAAqB,GAAG,SAAS;IAUxF,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIpC,KAAK,IAAI,IAAI;IAKpB,iFAAiF;IAC1E,UAAU,IAAI,IAAI;IAIlB,SAAS,IAAI,SAAS,MAAM,EAAE;IAI9B,KAAK,IAAI,cAAc;IAoB9B;;;OAGG;IACI,OAAO,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,cAAc;CA4IxF;AAED,wBAAgB,eAAe,IAAI,SAAS,CAE3C;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,cAAc,EACrB,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,GAC/B,cAAc,CAEhB;AAkGD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACxC,QAAQ,EAAE,YAAY,GACrB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CA+ChC;AAID,MAAM,WAAW,+BAA+B,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1E,uEAAuE;IACvE,KAAK,CAAC,EAAE,2BAA2B,CAAC,CAAC,CAAC,CAAC;CACxC;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACzE,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,+BAA+B,CAAC,CAAC,CAAM,GAC/C,2BAA2B,CAAC,CAAC,CAAC,CA4ChC"}