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

package/esri-compat/portal.js

@@ -0,0 +1,251 @@
+import { HonuaClient } from "../core/client.js";
+import { esriConfig } from "./esri-config.js";
+import { FeatureLayerCompat } from "./feature-layer.js";
+import { identityManager } from "./identity-manager.js";
+import { createArcGisTokenInterceptor } from "./request.js";
+import { parseFeatureLayerUrl, parseImageServiceUrl, parseMapServiceUrl } from "./url.js";
+/** Error thrown when the Portal facade returns an Esri error envelope. */
+export class PortalError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.name = "PortalError";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Client for a Honua `/sharing/rest` Portal facade. Lets a repointed ArcGIS app
+ * authenticate, search for items, and open an item that resolves to a
+ * `/rest/services` URL — carrying the portal token through to the opened layer
+ * so the whole flow authenticates end to end.
+ *
+ * @example
+ * ```ts
+ * import { PortalCompat } from "@honua/sdk-js/esri-compat";
+ *
+ * const portal = new PortalCompat({ portalUrl: "https://honua.example" });
+ * await portal.generateToken({ username: "u", password: "p" });
+ * const { results } = await portal.search({ q: "roads" });
+ * const opened = await portal.openFeatureLayer(results[0]);
+ * if (opened.type === "feature-service") {
+ *   await opened.layer.queryFeatures({ where: "1=1" });
+ * }
+ * ```
+ */
+export class PortalCompat {
+    /** Normalized `.../sharing/rest` base for this portal. */
+    sharingRestBase;
+    token;
+    tokenExpiresAtMs;
+    apiKey;
+    fetchFn;
+    constructor(options = {}) {
+        this.sharingRestBase = normalizeSharingRestBase(options.portalUrl ?? esriConfig.portalUrl);
+        this.token = options.token;
+        this.tokenExpiresAtMs = undefined;
+        this.apiKey = options.apiKey ?? esriConfig.apiKey;
+        // Bind so passing a bare `window.fetch`/`globalThis.fetch` cannot throw an
+        // "Illegal invocation" when called as `this.fetchFn(...)`.
+        this.fetchFn = (options.fetchFn ?? fetch).bind(globalThis);
+    }
+    /** The currently held portal token, if any. */
+    getToken() {
+        return this.token;
+    }
+    /**
+     * Exchange username/password for a portal token via
+     * `POST /sharing/rest/generateToken`. Stores the token on this instance and
+     * returns the credential (`expires` ms → `expiresAtMs`).
+     */
+    async generateToken(options) {
+        const referer = options.referer ?? defaultReferer(this.sharingRestBase);
+        const body = new URLSearchParams();
+        body.set("username", options.username);
+        body.set("password", options.password);
+        body.set("client", options.client ?? "referer");
+        if (referer) {
+            body.set("referer", referer);
+        }
+        if (typeof options.expirationMinutes === "number" && Number.isFinite(options.expirationMinutes)) {
+            body.set("expiration", String(options.expirationMinutes));
+        }
+        body.set("f", "json");
+        const response = await this.fetchFn(`${this.sharingRestBase}/generateToken`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: body.toString(),
+        });
+        const json = (await response.json());
+        throwIfEsriError(json, "Portal generateToken failed.");
+        if (typeof json.token !== "string" || json.token.length === 0) {
+            throw new PortalError("Portal generateToken response did not include a token.");
+        }
+        const expiresAtMs = typeof json.expires === "number" && Number.isFinite(json.expires) ? json.expires : 0;
+        this.token = json.token;
+        this.tokenExpiresAtMs = expiresAtMs || undefined;
+        return { token: json.token, expiresAtMs, ssl: json.ssl ?? true };
+    }
+    /** `GET /sharing/rest/info`. */
+    async getInfo() {
+        return this.getJson("/info", {}, undefined);
+    }
+    /** `GET /sharing/rest/portals/self` (attaches the token when present). */
+    async getPortalSelf() {
+        return this.getJson("/portals/self", {}, this.token);
+    }
+    /** `GET /sharing/rest/search`. */
+    async search(options = {}) {
+        const params = {
+            q: options.q,
+            start: options.start,
+            num: options.num,
+        };
+        const raw = await this.getJson("/search", params, options.token ?? this.token);
+        return {
+            query: raw.query ?? options.q ?? "",
+            total: raw.total ?? 0,
+            start: raw.start ?? options.start ?? 1,
+            num: raw.num ?? options.num ?? 0,
+            nextStart: raw.nextStart ?? -1,
+            results: Array.isArray(raw.results) ? raw.results : [],
+        };
+    }
+    /** `GET /sharing/rest/content/items/{id}`. */
+    async getItem(itemId, options = {}) {
+        return this.getJson(`/content/items/${encodeURIComponent(itemId)}`, {}, options.token ?? this.token);
+    }
+    /**
+     * Resolve an item (fetching it when given an id), parse its service `url`, and
+     * return an authenticated handle. Feature Service items yield a
+     * {@link FeatureLayerCompat} bound to a client carrying the portal token;
+     * Map/Image Service items yield the resolved `{ baseUrl, serviceId, client }`.
+     */
+    async openFeatureLayer(itemOrId, options = {}) {
+        const item = typeof itemOrId === "string" ? await this.getItem(itemOrId) : itemOrId;
+        if (!item.url) {
+            throw new PortalError(`Portal item ${item.id} has no service URL to open.`);
+        }
+        const serviceUrl = trimTrailingSlashes(item.url);
+        if (isFeatureService(item.type, serviceUrl)) {
+            const hasLayerId = /\/FeatureServer\/\d+$/i.test(serviceUrl);
+            const service = parseFeatureLayerUrl(hasLayerId ? serviceUrl : `${serviceUrl}/0`);
+            const client = this.buildAuthenticatedClient(service.baseUrl);
+            let layerId = service.layerId;
+            if (!hasLayerId) {
+                if (options.layerId !== undefined) {
+                    layerId = options.layerId;
+                }
+                else {
+                    const metadata = await client.getFeatureServiceMetadata(service.serviceId);
+                    const firstLayerId = metadata.layers?.[0]?.id;
+                    if (typeof firstLayerId !== "number" || !Number.isSafeInteger(firstLayerId)) {
+                        throw new PortalError(`Portal Feature Service item ${item.id} does not advertise a layer to open.`);
+                    }
+                    layerId = firstLayerId;
+                }
+            }
+            const layerUrl = hasLayerId ? serviceUrl : `${serviceUrl}/${layerId}`;
+            const parsed = parseFeatureLayerUrl(layerUrl);
+            const layer = new FeatureLayerCompat({ url: layerUrl, client, title: item.title, id: item.id });
+            return {
+                type: "feature-service",
+                item,
+                baseUrl: parsed.baseUrl,
+                serviceId: parsed.serviceId,
+                layerId: parsed.layerId,
+                client,
+                layer,
+            };
+        }
+        if (isImageService(item.type, serviceUrl)) {
+            const parsed = parseImageServiceUrl(serviceUrl);
+            const client = this.buildAuthenticatedClient(parsed.baseUrl);
+            return { type: "image-service", item, baseUrl: parsed.baseUrl, serviceId: parsed.serviceId, client };
+        }
+        const parsed = parseMapServiceUrl(serviceUrl);
+        const client = this.buildAuthenticatedClient(parsed.baseUrl);
+        return { type: "map-service", item, baseUrl: parsed.baseUrl, serviceId: parsed.serviceId, client };
+    }
+    /**
+     * Register the currently held token with the shared {@link identityManager}
+     * under this portal's `/sharing/rest` server, so subsequent esri-compat calls
+     * resolve the same credential.
+     */
+    registerWithIdentityManager() {
+        if (!this.token) {
+            throw new PortalError("PortalCompat has no token to register; call generateToken first.");
+        }
+        identityManager.registerToken({
+            server: this.sharingRestBase,
+            token: this.token,
+            ...(this.tokenExpiresAtMs !== undefined ? { expires: this.tokenExpiresAtMs } : {}),
+        });
+    }
+    buildAuthenticatedClient(baseUrl) {
+        const interceptors = [];
+        if (this.token) {
+            interceptors.push(createArcGisTokenInterceptor({ getToken: () => this.token }));
+        }
+        return new HonuaClient({
+            baseUrl,
+            fetchFn: this.fetchFn,
+            ...(this.apiKey ? { apiKey: this.apiKey } : {}),
+            ...(interceptors.length > 0 ? { interceptors } : {}),
+        });
+    }
+    async getJson(path, params, token) {
+        const query = new URLSearchParams();
+        query.set("f", "json");
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== null && value !== "") {
+                query.set(key, String(value));
+            }
+        }
+        if (token) {
+            query.set("token", token);
+        }
+        const response = await this.fetchFn(`${this.sharingRestBase}${path}?${query.toString()}`);
+        const json = (await response.json());
+        throwIfEsriError(json, `Portal request to ${path} failed.`);
+        return json;
+    }
+}
+function normalizeSharingRestBase(portalUrl) {
+    const trimmed = trimTrailingSlashes(portalUrl);
+    if (/\/sharing\/rest$/i.test(trimmed)) {
+        return trimmed;
+    }
+    return `${trimmed}/sharing/rest`;
+}
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47) {
+        end--;
+    }
+    return value.slice(0, end);
+}
+function defaultReferer(sharingRestBase) {
+    if (globalThis.location?.origin) {
+        return globalThis.location.origin;
+    }
+    try {
+        return new URL(sharingRestBase).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isFeatureService(type, serviceUrl) {
+    return /feature\s*service/i.test(type) || /\/FeatureServer(\/\d+)?$/i.test(serviceUrl);
+}
+function isImageService(type, serviceUrl) {
+    return /image\s*service/i.test(type) || /\/ImageServer(\/\d+)?$/i.test(serviceUrl);
+}
+function throwIfEsriError(json, fallbackMessage) {
+    if (json && typeof json === "object" && json.error) {
+        const { code, message, details } = json.error;
+        throw new PortalError(message ?? fallbackMessage, code, details);
+    }
+}

package/esri-compat/renderer-objects.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Bridges the esri-compat renderer shims to the first-class renderer objects
+ * in `@honua/sdk-js/style` (issue #497 REQ-002). The compat classes stay
+ * pure state holders; these helpers project their state through the same
+ * WebMap symbol/renderer conversion path the WebMap converter uses, so the
+ * SDK has exactly one class-breaks/unique-value implementation.
+ *
+ * Kept out of the compat classes themselves so consumers who never emit
+ * renderer objects do not pay for the conversion pipeline.
+ *
+ * @module
+ */
+import type { ClassBreaksRenderer, UniqueValueRenderer } from "../style/renderers.js";
+import type { WarningCollector } from "../webmap/warnings.js";
+import type { ClassBreaksRendererCompat } from "./class-breaks-renderer.js";
+import type { UniqueValueRendererCompat } from "./unique-value-renderer.js";
+/** Result of projecting a compat renderer to a renderer object. @experimental */
+export interface CompatRendererProjection<R> {
+    /** The emitted renderer object, or `undefined` when nothing was convertible. */
+    readonly renderer: R | undefined;
+    /** Symbol/renderer conversion warnings collected during projection. */
+    readonly warnings: WarningCollector["warnings"];
+}
+/**
+ * Emit a first-class {@link ClassBreaksRenderer} from a
+ * `ClassBreaksRendererCompat` shim. Compat `minValue`/`maxValue` map to the
+ * WebMap `classMinValue`/`classMaxValue` fields and symbols convert through
+ * the shared WebMap symbol pipeline.
+ *
+ * @experimental
+ */
+export declare function rendererObjectFromClassBreaksCompat(compat: ClassBreaksRendererCompat): CompatRendererProjection<ClassBreaksRenderer>;
+/**
+ * Emit a first-class {@link UniqueValueRenderer} from a
+ * `UniqueValueRendererCompat` shim.
+ *
+ * @experimental
+ */
+export declare function rendererObjectFromUniqueValueCompat(compat: UniqueValueRendererCompat): CompatRendererProjection<UniqueValueRenderer>;
+//# sourceMappingURL=renderer-objects.d.ts.map

package/esri-compat/renderer-objects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer-objects.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/renderer-objects.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAE5E,iFAAiF;AACjF,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC;IACjC,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;CACjD;AAED;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,yBAAyB,GAChC,wBAAwB,CAAC,mBAAmB,CAAC,CAmB/C;AAED;;;;;GAKG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,yBAAyB,GAChC,wBAAwB,CAAC,mBAAmB,CAAC,CAmB/C"}

package/esri-compat/renderer-objects.js

@@ -0,0 +1,62 @@
+/**
+ * Bridges the esri-compat renderer shims to the first-class renderer objects
+ * in `@honua/sdk-js/style` (issue #497 REQ-002). The compat classes stay
+ * pure state holders; these helpers project their state through the same
+ * WebMap symbol/renderer conversion path the WebMap converter uses, so the
+ * SDK has exactly one class-breaks/unique-value implementation.
+ *
+ * Kept out of the compat classes themselves so consumers who never emit
+ * renderer objects do not pay for the conversion pipeline.
+ *
+ * @module
+ */
+import { classBreaksRendererFromWebMap, uniqueValueRendererFromWebMap } from "../webmap/convert-renderer.js";
+import { createWarningCollector } from "../webmap/warnings.js";
+/**
+ * Emit a first-class {@link ClassBreaksRenderer} from a
+ * `ClassBreaksRendererCompat` shim. Compat `minValue`/`maxValue` map to the
+ * WebMap `classMinValue`/`classMaxValue` fields and symbols convert through
+ * the shared WebMap symbol pipeline.
+ *
+ * @experimental
+ */
+export function rendererObjectFromClassBreaksCompat(compat) {
+    const warn = createWarningCollector();
+    const renderer = classBreaksRendererFromWebMap({
+        type: "classBreaks",
+        field: compat.field,
+        minValue: compat.minValue,
+        defaultSymbol: compat.defaultSymbol,
+        defaultLabel: compat.defaultLabel,
+        classBreakInfos: compat.classBreakInfos.map((info) => ({
+            classMinValue: info.minValue,
+            classMaxValue: info.maxValue,
+            label: info.label,
+            symbol: info.symbol,
+        })),
+    }, warn);
+    return { renderer, warnings: warn.warnings };
+}
+/**
+ * Emit a first-class {@link UniqueValueRenderer} from a
+ * `UniqueValueRendererCompat` shim.
+ *
+ * @experimental
+ */
+export function rendererObjectFromUniqueValueCompat(compat) {
+    const warn = createWarningCollector();
+    const renderer = uniqueValueRendererFromWebMap({
+        type: "uniqueValue",
+        field1: compat.field,
+        field2: compat.field2,
+        field3: compat.field3,
+        defaultSymbol: compat.defaultSymbol,
+        defaultLabel: compat.defaultLabel,
+        uniqueValueInfos: compat.uniqueValueInfos.map((info) => ({
+            value: info.value,
+            label: info.label,
+            symbol: info.symbol,
+        })),
+    }, warn);
+    return { renderer, warnings: warn.warnings };
+}

package/esri-compat/sketch.d.ts

@@ -1,6 +1,32 @@
+import type { EditSketchTool } from "../contract/edit-sketch.js";
+import type { SnappingConfig } from "../contract/edit-snapping.js";
 import { CompatEventBus } from "./event-bus.js";
+import { type SnappingOptionsCompat } from "./snapping.js";
 export type SketchCreationModeCompat = "single" | "update" | "continuous";
 export type SketchToolCompat = "point" | "polyline" | "polygon" | "rectangle" | "circle";
+/**
+ * Duck-typed subset of the runtime terra-draw sketch handle
+ * (`bindTerraDrawSketch` / `createTerraDrawSketch` from
+ * `@honua/sdk-js/runtime`) that the Sketch shim can delegate tool modes to.
+ * Structural on purpose: the compat layer never imports the optional
+ * terra-draw peer, it only feature-detects a binding the app wired up.
+ *
+ * @experimental
+ */
+export interface SketchToolBindingCompat {
+    setTool(tool: EditSketchTool): unknown;
+    select?(): void;
+    cancel?(): void;
+}
+/**
+ * Feature-detect a terra-draw sketch binding: any object exposing a callable
+ * `setTool` qualifies; anything else (including `undefined` when terra-draw
+ * is not installed) resolves to `undefined` and the shim keeps its current
+ * headless behavior.
+ *
+ * @experimental
+ */
+export declare function resolveSketchToolBindingCompat(value: unknown): SketchToolBindingCompat | undefined;
 export interface SketchCreateOptionsCompat {
     mode?: "click" | "freehand" | "hybrid";
 }
@@ -20,6 +46,15 @@ export interface SketchCompatOptions {
     creationMode?: SketchCreationModeCompat;
     defaultCreateOptions?: Partial<SketchCreateOptionsCompat>;
     defaultUpdateOptions?: Partial<SketchUpdateOptionsCompat>;
+    snappingOptions?: SnappingOptionsCompat;
+    /**
+     * Optional terra-draw sketch binding (see {@link SketchToolBindingCompat}).
+     * When present, `create`/`update`/`cancel`/`reset` delegate tool-mode
+     * changes to the binding; otherwise the shim keeps its headless behavior.
+     *
+     * @experimental
+     */
+    sketchBinding?: unknown;
 }
 export interface SketchCreateResultCompat {
     state: "complete" | "cancel";
@@ -46,8 +81,16 @@ export declare class SketchCompat {
     activeCreateOptions: Partial<SketchCreateOptionsCompat> | undefined;
     activeUpdateGraphics: Record<string, unknown>[];
     activeUpdateOptions: Partial<SketchUpdateOptionsCompat> | undefined;
+    snappingOptions: SnappingOptionsCompat;
     private readonly watchListeners;
+    private readonly sketchBinding;
     constructor(options?: SketchCompatOptions);
+    /** Whether tool modes delegate to a terra-draw sketch binding. @experimental */
+    delegatesToSketchBinding(): boolean;
+    /** Replace the ArcGIS-shaped snapping options and notify watchers. */
+    setSnappingOptions(options: SnappingOptionsCompat): void;
+    /** The snapping options mapped onto the contract `SnappingConfig`. */
+    snappingConfig(): SnappingConfig;
     load(): Promise<SketchCompat>;
     when(callback?: (widget: SketchCompat) => void): Promise<SketchCompat>;
     watch(propertyName: string, listener: (value: unknown) => void): SketchHandleCompat;

package/esri-compat/sketch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sketch.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/sketch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sketch.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/sketch.ts"],"names":[],"mappings":"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"}

package/esri-compat/sketch.js

@@ -1,4 +1,26 @@
 import { CompatEventBus, resolveCompatEventBus, safeInvokeCompatListener } from "./event-bus.js";
+import { snappingOptionsToSnappingConfig } from "./snapping.js";
+const SKETCH_COMPAT_TOOL_TO_EDIT_TOOL = Object.freeze({
+    point: "point",
+    polyline: "line",
+    polygon: "polygon",
+    rectangle: "rectangle",
+    circle: "circle",
+});
+/**
+ * Feature-detect a terra-draw sketch binding: any object exposing a callable
+ * `setTool` qualifies; anything else (including `undefined` when terra-draw
+ * is not installed) resolves to `undefined` and the shim keeps its current
+ * headless behavior.
+ *
+ * @experimental
+ */
+export function resolveSketchToolBindingCompat(value) {
+    if (value !== null && typeof value === "object" && typeof value.setTool === "function") {
+        return value;
+    }
+    return undefined;
+}
 export class SketchCompat {
     view;
     layer;
@@ -15,7 +37,9 @@ export class SketchCompat {
     activeCreateOptions;
     activeUpdateGraphics;
     activeUpdateOptions;
+    snappingOptions;
     watchListeners;
+    sketchBinding;
     constructor(options = {}) {
         this.view = options.view;
         this.layer = options.layer;
@@ -32,7 +56,23 @@ export class SketchCompat {
         this.activeCreateOptions = undefined;
         this.activeUpdateGraphics = [];
         this.activeUpdateOptions = undefined;
+        this.snappingOptions = { ...(options.snappingOptions ?? {}) };
         this.watchListeners = new Map();
+        this.sketchBinding = resolveSketchToolBindingCompat(options.sketchBinding);
+    }
+    /** Whether tool modes delegate to a terra-draw sketch binding. @experimental */
+    delegatesToSketchBinding() {
+        return this.sketchBinding !== undefined;
+    }
+    /** Replace the ArcGIS-shaped snapping options and notify watchers. */
+    setSnappingOptions(options) {
+        this.snappingOptions = { ...options };
+        this.notifyWatchers("snappingOptions", this.snappingOptions);
+        this.eventBus.emit("sketch.snapping-options-changed", { options: this.snappingOptions }, this);
+    }
+    /** The snapping options mapped onto the contract `SnappingConfig`. */
+    snappingConfig() {
+        return snappingOptionsToSnappingConfig(this.snappingOptions);
     }
     async load() {
         if (this.loaded) {
@@ -83,6 +123,7 @@ export class SketchCompat {
             creationMode: this.creationMode,
             options: this.activeCreateOptions,
         }, this);
+        this.sketchBinding?.setTool(SKETCH_COMPAT_TOOL_TO_EDIT_TOOL[tool]);
     }
     complete(graphic) {
         if (this.state !== "active" || !this.activeTool) {
@@ -97,6 +138,8 @@ export class SketchCompat {
             graphic: createdGraphic,
             layerGraphicCount: getLayerGraphics(this.layer).length,
         }, this);
+        if (this.creationMode !== "continuous")
+            this.sketchBinding?.cancel?.();
         return {
             state: "complete",
             tool,
@@ -110,6 +153,7 @@ export class SketchCompat {
         const tool = this.activeTool;
         this.clearActiveState();
         this.eventBus.emit("sketch.create-cancelled", { tool }, this);
+        this.sketchBinding?.cancel?.();
         return {
             state: "cancel",
             tool,
@@ -128,6 +172,7 @@ export class SketchCompat {
             count: normalizedGraphics.length,
             options: this.activeUpdateOptions,
         }, this);
+        this.sketchBinding?.select?.();
         return this.activeUpdateGraphics;
     }
     delete(graphics) {
@@ -157,6 +202,7 @@ export class SketchCompat {
         this.activeUpdateOptions = undefined;
         this.notifyWatchers("activeUpdateOptions", this.activeUpdateOptions);
         this.eventBus.emit("sketch.reset", undefined, this);
+        this.sketchBinding?.cancel?.();
     }
     clearActiveState() {
         this.state = "ready";

package/esri-compat/snapping.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ArcGIS `SnappingOptions`-shaped compat surface, mapped onto the
+ * renderer-neutral `SnappingConfig` from `contract/edit-snapping.ts`.
+ *
+ * @module
+ */
+import { type SnappingConfig } from "../contract/edit-snapping.js";
+/** ArcGIS `FeatureSnappingLayerSource`-shaped entry. */
+export interface SnappingFeatureSourceCompat {
+    /** Layer (or layer-like object) providing snap features. */
+    layer?: unknown;
+    /** Explicit Honua source id when no layer id is derivable. */
+    id?: string;
+    /** @default true */
+    enabled?: boolean;
+}
+/** ArcGIS `SnappingOptions`-shaped configuration accepted by the shims. */
+export interface SnappingOptionsCompat {
+    /** Master switch. ArcGIS defaults snapping off. @default false */
+    enabled?: boolean;
+    /** Snap distance in pixels; maps to `SnappingConfig.tolerance`. */
+    distance?: number;
+    /** Snap to features from `featureSources`. @default true */
+    featureEnabled?: boolean;
+    /**
+     * Snap to the geometry being drawn. Stored for parity; self snapping is a
+     * runtime concern (index the active sketch source to approximate it).
+     * @default true
+     */
+    selfEnabled?: boolean;
+    featureSources?: readonly SnappingFeatureSourceCompat[];
+}
+/**
+ * Map ArcGIS-shaped snapping options to the contract `SnappingConfig`.
+ *
+ * `distance` maps to pixel tolerance; `featureSources` map to per-source
+ * enablement keyed by `source.id` (falling back to a duck-typed `layer.id` /
+ * `layer.sourceId`); `featureEnabled: false` disables every listed source.
+ * Vertex and edge candidates are enabled — matching ArcGIS 2D snapping,
+ * which always resolves both.
+ */
+export declare function snappingOptionsToSnappingConfig(options?: SnappingOptionsCompat): SnappingConfig;
+//# sourceMappingURL=snapping.d.ts.map

package/esri-compat/snapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapping.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/snapping.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,8BAA8B,CAAC;AAEtC,wDAAwD;AACxD,MAAM,WAAW,2BAA2B;IAC1C,4DAA4D;IAC5D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,8DAA8D;IAC9D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,oBAAoB;IACpB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,cAAc,CAAC,EAAE,SAAS,2BAA2B,EAAE,CAAC;CACzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,GAAE,qBAA0B,GAAG,cAAc,CAcnG"}

package/esri-compat/snapping.js

@@ -0,0 +1,45 @@
+/**
+ * ArcGIS `SnappingOptions`-shaped compat surface, mapped onto the
+ * renderer-neutral `SnappingConfig` from `contract/edit-snapping.ts`.
+ *
+ * @module
+ */
+import { DEFAULT_SNAPPING_CONFIG, resolveSnappingConfig, } from "../contract/edit-snapping.js";
+/**
+ * Map ArcGIS-shaped snapping options to the contract `SnappingConfig`.
+ *
+ * `distance` maps to pixel tolerance; `featureSources` map to per-source
+ * enablement keyed by `source.id` (falling back to a duck-typed `layer.id` /
+ * `layer.sourceId`); `featureEnabled: false` disables every listed source.
+ * Vertex and edge candidates are enabled — matching ArcGIS 2D snapping,
+ * which always resolves both.
+ */
+export function snappingOptionsToSnappingConfig(options = {}) {
+    const kinds = ["vertex", "edge"];
+    const sources = {};
+    for (const featureSource of options.featureSources ?? []) {
+        const sourceId = featureSourceId(featureSource);
+        if (sourceId === undefined)
+            continue;
+        sources[sourceId] = options.featureEnabled === false ? false : (featureSource.enabled ?? true);
+    }
+    return resolveSnappingConfig({
+        enabled: options.enabled ?? false,
+        tolerance: options.distance ?? DEFAULT_SNAPPING_CONFIG.tolerance,
+        kinds,
+        sources,
+    });
+}
+function featureSourceId(featureSource) {
+    if (featureSource.id !== undefined)
+        return featureSource.id;
+    const layer = featureSource.layer;
+    if (layer && typeof layer === "object") {
+        const candidate = layer;
+        if (typeof candidate.id === "string")
+            return candidate.id;
+        if (typeof candidate.sourceId === "string")
+            return candidate.sourceId;
+    }
+    return undefined;
+}

package/esri-compat/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/url.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AASD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAkBvE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAanE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAarE"}
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../../src/esri-compat/url.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAkBvE;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAanE;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAarE"}

package/esri-compat/url.js

@@ -1,7 +1,7 @@
 const ABSOLUTE_URL_RE = /^[A-Za-z][A-Za-z\d+.-]*:\/\//;
 const PROTOCOL_RELATIVE_URL_RE = /^\/\//;
 const RELATIVE_URL_BASE = "https://honua.invalid";
-const FEATURE_LAYER_PATH_RE = /^(?<prefix>.*)\/rest\/services\/(?<serviceId>[^/]+)\/FeatureServer\/(?<layerId>\d+)\/?$/;
+const FEATURE_LAYER_PATH_RE = /^(?<prefix>.*)\/rest\/services\/(?<serviceId>[^/]+(?:\/[^/]+)*)\/FeatureServer\/(?<layerId>\d+)\/?$/;
 const MAP_SERVICE_PATH_RE = /^(?<prefix>.*)\/rest\/services\/(?<serviceId>[^/]+)\/MapServer(?:\/\d+)?\/?$/;
 const IMAGE_SERVICE_PATH_RE = /^(?<prefix>.*)\/rest\/services\/(?<serviceId>[^/]+)\/ImageServer(?:\/\d+)?\/?$/;
 export function parseFeatureLayerUrl(url) {