@honua/react 0.0.20-alpha.0

package/core/wire-shared.js

@@ -0,0 +1,76 @@
+/**
+ * Helpers shared across the per-protocol wire modules and the client's
+ * transport core: header merging and the common OGC metadata query-param
+ * builder plus CSV normalizers. Kept transport-agnostic so both
+ * `HonuaClient` and the protocol modules can import them without a cycle.
+ *
+ * @module
+ */
+/**
+ * Merge any number of `HeadersInit` values into a plain `Record<string,string>`,
+ * with later entries overriding earlier ones. Accepts `Headers`, tuple arrays,
+ * and plain objects; `undefined`/`null` object values are skipped.
+ */
+export function mergeHeaders(...headersList) {
+    const merged = {};
+    for (const headers of headersList) {
+        if (!headers) {
+            continue;
+        }
+        if (headers instanceof Headers) {
+            for (const [key, value] of headers.entries()) {
+                merged[key] = value;
+            }
+            continue;
+        }
+        if (Array.isArray(headers)) {
+            for (const [key, value] of headers) {
+                merged[key] = value;
+            }
+            continue;
+        }
+        for (const [key, value] of Object.entries(headers)) {
+            if (value === undefined || value === null) {
+                continue;
+            }
+            merged[key] = String(value);
+        }
+    }
+    return merged;
+}
+/** Build the shared OGC metadata query params (`f` + caller `extraParams`). */
+export function createOgcMetadataParams(request) {
+    const params = new URLSearchParams();
+    params.set("f", request.responseFormat ?? "json");
+    if (request.extraParams) {
+        for (const [key, value] of Object.entries(request.extraParams)) {
+            params.set(key, String(value));
+        }
+    }
+    return params;
+}
+/** Normalize a string-or-(string|number)-array value to a CSV string. */
+export function normalizeCsv(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    return Array.from(value).join(",");
+}
+/** Normalize a string-or-string-array value to a CSV string. */
+export function normalizeStringCsv(value) {
+    return typeof value === "string" ? value : value.join(",");
+}
+/**
+ * True when a GeoServices/FeatureServer response advertises more pages via
+ * `exceededTransferLimit`. GeoServices servers clamp `resultRecordCount` to
+ * their `maxRecordCount` and set this flag when more rows remain, so
+ * offset-paginated fetch-all loops must keep paging while it is set — advancing
+ * by the actual returned row count, never a fixed `page * pageSize` stride that
+ * would skip the rows the server capped off — rather than stopping on the first
+ * page that comes back shorter than the requested `pageSize`.
+ */
+export function responseExceededTransferLimit(response) {
+    return (typeof response === "object" &&
+        response !== null &&
+        response.exceededTransferLimit === true);
+}

package/core/wms-axis.d.ts

@@ -0,0 +1,36 @@
+/**
+ * WMS 1.3.0 axis-order helpers, shared by the first-party WMS client path and
+ * the Esri-compat `WMSLayer` so both emit BBOX in the authority-defined axis
+ * order.
+ *
+ * Under WMS 1.3.0 the authority-defined axis order for geographic EPSG codes
+ * (EPSG:4326 and friends) is latitude,longitude, so the canonical
+ * `[minx, miny, maxx, maxy]` tuple must be transposed to
+ * `[miny, minx, maxy, maxx]` on the wire. WMS 1.1.1 (`SRS`) always uses
+ * lon,lat and must not be transposed.
+ */
+/**
+ * Geographic EPSG codes whose WMS 1.3.0 axis order is latitude,longitude.
+ *
+ * Matching only the exact string `"EPSG:4326"` would leave other authority
+ * lat/lon CRSes (notably ETRS89 / EPSG:4258 and NAD83 / EPSG:4269) — and even
+ * the URN / URL spellings of 4326 itself — transposed incorrectly. The axis
+ * order is derived from the CRS authority code instead.
+ */
+export declare const WMS_LATLON_GEOGRAPHIC_EPSG: ReadonlySet<number>;
+/**
+ * Extract the trailing EPSG numeric code from any of the CRS spellings WMS
+ * clients use: `EPSG:4326`, `urn:ogc:def:crs:EPSG::4326`,
+ * `urn:ogc:def:crs:EPSG:8.9:4326`, and `http://www.opengis.net/def/crs/EPSG/0/4326`.
+ * Returns `undefined` for non-EPSG identifiers (e.g. `CRS:84`, OGC URNs).
+ */
+export declare function parseEpsgCode(crs: string): number | undefined;
+/** Whether a WMS 1.3.0 BBOX for `crs` must be transposed to lat,lon on the wire. */
+export declare function wmsBboxRequiresAxisSwap(crs: string): boolean;
+/**
+ * Order a canonical `[minx, miny, maxx, maxy]` BBOX for the wire under the given
+ * WMS `version` and `crs`. Only WMS 1.3.0 with a lat/lon geographic CRS is
+ * transposed; all other combinations keep lon,lat order.
+ */
+export declare function orderWmsBbox(bbox: readonly [number, number, number, number], version: string, crs: string): [number, number, number, number];
+//# sourceMappingURL=wms-axis.d.ts.map

package/core/wms-axis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wms-axis.d.ts","sourceRoot":"","sources":["../../../src/core/wms-axis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,MAAM,CAiBzD,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAU7D;AAED,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAG5D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAC/C,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,GACV,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAMlC"}

package/core/wms-axis.js

@@ -0,0 +1,73 @@
+/**
+ * WMS 1.3.0 axis-order helpers, shared by the first-party WMS client path and
+ * the Esri-compat `WMSLayer` so both emit BBOX in the authority-defined axis
+ * order.
+ *
+ * Under WMS 1.3.0 the authority-defined axis order for geographic EPSG codes
+ * (EPSG:4326 and friends) is latitude,longitude, so the canonical
+ * `[minx, miny, maxx, maxy]` tuple must be transposed to
+ * `[miny, minx, maxy, maxx]` on the wire. WMS 1.1.1 (`SRS`) always uses
+ * lon,lat and must not be transposed.
+ */
+/**
+ * Geographic EPSG codes whose WMS 1.3.0 axis order is latitude,longitude.
+ *
+ * Matching only the exact string `"EPSG:4326"` would leave other authority
+ * lat/lon CRSes (notably ETRS89 / EPSG:4258 and NAD83 / EPSG:4269) — and even
+ * the URN / URL spellings of 4326 itself — transposed incorrectly. The axis
+ * order is derived from the CRS authority code instead.
+ */
+export const WMS_LATLON_GEOGRAPHIC_EPSG = new Set([
+    4326, // WGS 84
+    4258, // ETRS89
+    4269, // NAD83
+    4267, // NAD27
+    4203, // AGD66
+    4283, // GDA94
+    7844, // GDA2020
+    4490, // China Geodetic Coordinate System 2000
+    4214, // Beijing 1954
+    4152, // NAD83(HARN)
+    4759, // NAD83(NSRS2007)
+    4617, // NAD83(CSRS)
+    4674, // SIRGAS 2000
+    4618, // SAD69
+    4612, // JGD2000
+    4019, // GRS 1980 ensemble
+]);
+/**
+ * Extract the trailing EPSG numeric code from any of the CRS spellings WMS
+ * clients use: `EPSG:4326`, `urn:ogc:def:crs:EPSG::4326`,
+ * `urn:ogc:def:crs:EPSG:8.9:4326`, and `http://www.opengis.net/def/crs/EPSG/0/4326`.
+ * Returns `undefined` for non-EPSG identifiers (e.g. `CRS:84`, OGC URNs).
+ */
+export function parseEpsgCode(crs) {
+    const upper = crs.toUpperCase();
+    const idx = upper.lastIndexOf("EPSG");
+    if (idx < 0)
+        return undefined;
+    const digitGroups = crs.slice(idx).match(/\d+/g);
+    if (!digitGroups || digitGroups.length === 0)
+        return undefined;
+    // The authority code is the last numeric group (URN forms embed a version
+    // number such as `8.9` between the authority and the code).
+    const code = Number(digitGroups[digitGroups.length - 1]);
+    return Number.isInteger(code) ? code : undefined;
+}
+/** Whether a WMS 1.3.0 BBOX for `crs` must be transposed to lat,lon on the wire. */
+export function wmsBboxRequiresAxisSwap(crs) {
+    const code = parseEpsgCode(crs);
+    return code !== undefined && WMS_LATLON_GEOGRAPHIC_EPSG.has(code);
+}
+/**
+ * Order a canonical `[minx, miny, maxx, maxy]` BBOX for the wire under the given
+ * WMS `version` and `crs`. Only WMS 1.3.0 with a lat/lon geographic CRS is
+ * transposed; all other combinations keep lon,lat order.
+ */
+export function orderWmsBbox(bbox, version, crs) {
+    const [minx, miny, maxx, maxy] = bbox;
+    if (version === "1.3.0" && wmsBboxRequiresAxisSwap(crs)) {
+        return [miny, minx, maxy, maxx];
+    }
+    return [minx, miny, maxx, maxy];
+}

package/core/wms-capabilities.d.ts

@@ -0,0 +1,110 @@
+/**
+ * WMS 1.3.0 Capabilities parser. Hand-rolled, narrow-scope text-walker
+ * over a `WMS_Capabilities` document. Returns a typed shape (layers,
+ * styles, bbox-per-CRS, dimensions, advertised formats) that the SDK
+ * can route through the canonical `Source` surface without leaking XML
+ * nodes into its public API.
+ *
+ * The parser is closed-schema (WMS 1.3 + the ISO 19128 service-metadata
+ * subset honua-server emits) and tolerates missing optional nodes
+ * gracefully. Vendor-extension elements outside the named set are
+ * ignored. A `HonuaWmsCapabilitiesParseError` (extends `HonuaError`) is
+ * thrown when a required root or top-level node is missing.
+ *
+ * @module
+ */
+/**
+ * Top-level WMS Capabilities surface.
+ */
+export interface WmsCapabilities {
+    /** WMS protocol version. honua-server advertises `1.3.0`. */
+    version: string;
+    service: WmsCapabilitiesService;
+    layers: ReadonlyArray<WmsCapabilityLayer>;
+    formats: WmsCapabilitiesFormats;
+    request: WmsCapabilitiesRequestSupport;
+}
+export interface WmsCapabilitiesService {
+    title?: string;
+    abstract?: string;
+}
+export interface WmsCapabilitiesFormats {
+    /** Image MIME types accepted by `GetMap`. */
+    map: readonly string[];
+    /** Info-format MIME types accepted by `GetFeatureInfo`. */
+    featureInfo: readonly string[];
+    /** Image MIME types accepted by `GetLegendGraphic`. */
+    legend: readonly string[];
+}
+export interface WmsCapabilitiesRequestSupport {
+    /** Capability advertises a `GetFeatureInfo` request element. */
+    getFeatureInfo: boolean;
+    /** Capability advertises a `GetLegendGraphic` request element. */
+    getLegendGraphic: boolean;
+}
+export interface WmsCapabilityLayer {
+    name: string;
+    title?: string;
+    abstract?: string;
+    /** CRS codes advertised on this layer (and inherited from ancestors). */
+    crs: readonly string[];
+    /** Bounding boxes per CRS. Multiple entries permitted. */
+    bbox: ReadonlyArray<WmsCapabilityBoundingBox>;
+    /** Styles advertised on this layer. The first entry is the default. */
+    styles: ReadonlyArray<WmsCapabilityStyle>;
+    /** Dimensions (`time`, `elevation`, vendor names). */
+    dimensions: ReadonlyArray<WmsCapabilityDimension>;
+    queryable: boolean;
+    /** Sub-layers nested under this entry. */
+    children: ReadonlyArray<WmsCapabilityLayer>;
+}
+export interface WmsCapabilityBoundingBox {
+    crs: string;
+    minx: number;
+    miny: number;
+    maxx: number;
+    maxy: number;
+}
+export interface WmsCapabilityStyle {
+    name: string;
+    title?: string;
+    /** Externally-served legend URL (`OnlineResource@xlink:href`) when advertised. */
+    legendUrl?: string;
+}
+export interface WmsCapabilityDimension {
+    name: string;
+    units?: string;
+    default?: string;
+    /** Discrete values; for time this is typically a comma-separated list. */
+    values: readonly string[];
+}
+/**
+ * Thrown when WMS Capabilities XML is missing required root structure or
+ * is otherwise malformed in a way that prevents extracting the typed
+ * shape above. Recoverable per-node gaps (missing `<Title>`,
+ * `<Abstract>`, etc.) are tolerated and return defaults.
+ */
+export declare class HonuaWmsCapabilitiesParseError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse a `WMS_Capabilities` text body into the typed `WmsCapabilities`
+ * shape. The input is the raw XML string returned by `requestText`; the
+ * parser walks it once with a small named-element matcher and tolerates
+ * vendor extensions (unknown elements are skipped).
+ */
+export declare function parseWmsCapabilities(xml: string): WmsCapabilities;
+/**
+ * Walk a parsed `WmsCapabilities` tree and yield every named layer
+ * (skipping container layers without a `name`). Useful for descriptor
+ * resolution: callers want to bind a `LAYER` name without re-walking
+ * the parent hierarchy.
+ */
+export declare function iterateWmsLayers(capabilities: WmsCapabilities): Generator<WmsCapabilityLayer>;
+/**
+ * Find the first named layer with a matching name, or `undefined` if the
+ * capabilities document does not advertise it. Walks both root layers and
+ * children. Intended for the `HonuaWms.layer(name)` resolver path.
+ */
+export declare function findWmsLayer(capabilities: WmsCapabilities, name: string): WmsCapabilityLayer | undefined;
+//# sourceMappingURL=wms-capabilities.d.ts.map

package/core/wms-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wms-capabilities.d.ts","sourceRoot":"","sources":["../../../src/core/wms-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,sBAAsB,CAAC;IAChC,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC1C,OAAO,EAAE,sBAAsB,CAAC;IAChC,OAAO,EAAE,6BAA6B,CAAC;CACxC;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,2DAA2D;IAC3D,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,uDAAuD;IACvD,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,6BAA6B;IAC5C,gEAAgE;IAChE,cAAc,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IACvB,0DAA0D;IAC1D,IAAI,EAAE,aAAa,CAAC,wBAAwB,CAAC,CAAC;IAC9C,uEAAuE;IACvE,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC1C,sDAAsD;IACtD,UAAU,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAClD,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,QAAQ,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,wBAAwB;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,8BAA+B,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAInC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,CAgCjE;AA+dD;;;;;GAKG;AACH,wBAAiB,gBAAgB,CAAC,YAAY,EAAE,eAAe,GAAG,SAAS,CAAC,kBAAkB,CAAC,CAU9F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAKxG"}