@honua/react 0.0.20-alpha.0

package/contract/spatial-aggregation.d.ts

@@ -0,0 +1,336 @@
+/**
+ * Protocol-neutral request and response shapes for indexed spatial aggregation.
+ *
+ * This module is intentionally a contract surface only. It describes the
+ * request envelope SDKs send to a backend that can aggregate into indexed
+ * cells, and the response metadata apps need to build widgets and load
+ * progressively. The index model id is opaque so callers can work with H3,
+ * Quadbin, WebMercatorQuad, or a provider-specific grid without switching on
+ * one implementation.
+ *
+ * @module
+ */
+import type { SpatialFilter } from "../core/spatial-filter.js";
+import type { HonuaExtent } from "../core/types.js";
+import type { AnalyticsSourceDescriptor } from "./analytics-sources.js";
+import type { DegradedReason, SourceId } from "./types.js";
+export declare const SPATIAL_AGGREGATION_SCHEMA_VERSION: "honua.spatial-aggregation.v1";
+export declare const SPATIAL_AGGREGATION_METADATA_SCHEMA_VERSION: "honua.spatial-aggregation.metadata.v1";
+export declare const SPATIAL_AGGREGATION_CAPABILITY: "spatialAggregate";
+export declare const FEATURE_SERVER_H3_SPATIAL_AGGREGATION_INDEX_MODEL_ID: "h3";
+export type SpatialAggregationSummaryKind = "category" | "histogram" | "range" | "count" | "sum" | "avg" | "min" | "max";
+export type SpatialAggregationMetricKind = Extract<SpatialAggregationSummaryKind, "count" | "sum" | "avg" | "min" | "max">;
+export type SpatialAggregationValueType = "number" | "string" | "boolean" | "date" | "unknown";
+export type SpatialAggregationCellGeometry = "none" | "centroid" | "extent" | "boundary";
+export type SpatialAggregationWidgetKind = "stat" | "category-list" | "histogram" | "range-list" | "grouped-table";
+export type SpatialAggregationProgressStatus = "complete" | "partial" | "estimated" | "streaming";
+export type SpatialAggregationProgressRefinement = "append" | "replace" | "refine";
+export interface SpatialAggregationViewport {
+    readonly extent: HonuaExtent;
+    readonly zoom?: number;
+    readonly width?: number;
+    readonly height?: number;
+    readonly devicePixelRatio?: number;
+}
+export interface SpatialAggregationResolutionInput {
+    /** Map zoom that should drive backend resolution selection. */
+    readonly zoom?: number;
+    /** Backend-native index resolution. Its meaning is index-model specific. */
+    readonly indexResolution?: number;
+    /** Preferred number of cells for the returned page or viewport. */
+    readonly targetCellCount?: number;
+    /** Hard cap the backend should not exceed without paging/refinement. */
+    readonly maxCellCount?: number;
+    readonly strategy?: "backend-default" | "fit-viewport" | "fixed-index-resolution";
+}
+export interface SpatialAggregationIndexSelection {
+    /** Opaque backend-advertised id, for example "h3" or "quadbin". */
+    readonly modelId?: string;
+    readonly geometry?: SpatialAggregationCellGeometry;
+    readonly allowApproximate?: boolean;
+}
+export interface SpatialAggregationPageRequest {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface SpatialAggregationInclude {
+    readonly cells?: boolean;
+    readonly totals?: boolean;
+    readonly emptyCells?: boolean;
+    readonly metadata?: boolean;
+}
+export interface SpatialAggregationRequest {
+    readonly schemaVersion?: typeof SPATIAL_AGGREGATION_SCHEMA_VERSION;
+    readonly requestId?: string;
+    readonly sourceId: SourceId;
+    readonly analyticsSource?: AnalyticsSourceDescriptor;
+    readonly where?: string;
+    readonly spatialFilter?: SpatialFilter;
+    readonly viewport?: SpatialAggregationViewport;
+    readonly resolution?: SpatialAggregationResolutionInput;
+    readonly index?: SpatialAggregationIndexSelection;
+    readonly summaries: readonly SpatialAggregationSummarySpec[];
+    readonly groupBy?: readonly SpatialAggregationGroupBySpec[];
+    readonly include?: SpatialAggregationInclude;
+    readonly page?: SpatialAggregationPageRequest;
+    readonly signal?: AbortSignal;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface SpatialAggregationSummaryBase {
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly field?: string;
+    readonly valueType?: SpatialAggregationValueType;
+    readonly unit?: string;
+}
+export interface SpatialAggregationCountSummarySpec extends SpatialAggregationSummaryBase {
+    readonly kind: "count";
+    readonly countDistinct?: boolean;
+}
+export interface SpatialAggregationCategorySummarySpec extends SpatialAggregationSummaryBase {
+    readonly kind: "category";
+    readonly field: string;
+    readonly limit?: number;
+    readonly includeOther?: boolean;
+    readonly orderBy?: "count-desc" | "count-asc" | "value-asc" | "value-desc";
+}
+export interface SpatialAggregationHistogramSummarySpec extends SpatialAggregationSummaryBase {
+    readonly kind: "histogram";
+    readonly field: string;
+    readonly bins?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly method?: "equal-interval" | "quantile" | "custom";
+}
+export interface SpatialAggregationRangeSummarySpec extends SpatialAggregationSummaryBase {
+    readonly kind: "range";
+    readonly field: string;
+    readonly ranges: readonly SpatialAggregationRangeBucketSpec[];
+}
+export interface SpatialAggregationMetricSummarySpec extends SpatialAggregationSummaryBase {
+    readonly kind: Exclude<SpatialAggregationMetricKind, "count">;
+    readonly field: string;
+}
+export type SpatialAggregationSummarySpec = SpatialAggregationCountSummarySpec | SpatialAggregationCategorySummarySpec | SpatialAggregationHistogramSummarySpec | SpatialAggregationRangeSummarySpec | SpatialAggregationMetricSummarySpec;
+export interface SpatialAggregationRangeBucketSpec {
+    readonly id: string;
+    readonly label?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly includeMin?: boolean;
+    readonly includeMax?: boolean;
+}
+export interface SpatialAggregationGroupBySpec {
+    readonly field: string;
+    readonly alias?: string;
+    readonly label?: string;
+    readonly limit?: number;
+    readonly nullLabel?: string;
+}
+export interface SpatialAggregationIndexModelMetadata {
+    /** Opaque model id. Apps must not infer behavior from this string. */
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly family?: string;
+    readonly cellIdEncoding?: "string" | "number" | "bigint" | "opaque";
+    readonly minResolution?: number;
+    readonly maxResolution?: number;
+    readonly supportedGeometry?: readonly SpatialAggregationCellGeometry[];
+    readonly hierarchy?: "parent-child" | "flat" | "unknown";
+    readonly coverage?: SpatialAggregationIndexCoverageMetadata;
+    readonly spatialReference?: HonuaExtent["spatialReference"];
+}
+export interface SpatialAggregationIndexCoverageMetadata {
+    readonly kind: "global" | "bounded" | "sparse" | "viewport";
+    readonly extent?: HonuaExtent;
+    readonly cellCount?: number;
+    readonly complete?: boolean;
+}
+export interface SpatialAggregationIndexState {
+    readonly model: SpatialAggregationIndexModelMetadata;
+    readonly resolution?: number;
+    readonly requestedResolution?: SpatialAggregationResolutionInput;
+    readonly hierarchy?: "parent-child" | "flat" | "unknown";
+    readonly coverage?: SpatialAggregationIndexCoverageMetadata;
+    readonly cellCount?: number;
+    readonly extent?: HonuaExtent;
+}
+export interface SpatialAggregationPageInfo {
+    readonly nextCursor?: string;
+    readonly loadedCellCount?: number;
+    readonly totalCellCount?: number;
+}
+export interface SpatialAggregationProgressiveState {
+    readonly status: SpatialAggregationProgressStatus;
+    readonly refinement?: SpatialAggregationProgressRefinement;
+    readonly nextCursor?: string;
+    readonly loadedCellCount?: number;
+    readonly totalCellCount?: number;
+    readonly loadedSummaryCount?: number;
+    readonly estimatedSummaryCount?: number;
+}
+export interface SpatialAggregationMetadata {
+    readonly schemaVersion?: typeof SPATIAL_AGGREGATION_METADATA_SCHEMA_VERSION;
+    readonly sourceId?: SourceId;
+    readonly indexModels?: readonly SpatialAggregationIndexModelMetadata[];
+    readonly summaries: readonly SpatialAggregationSummaryMetadata[];
+    readonly groupBy?: readonly SpatialAggregationGroupByMetadata[];
+    readonly widgets?: readonly SpatialAggregationWidgetMetadata[];
+    readonly progressive?: SpatialAggregationProgressiveState;
+    readonly cache?: SpatialAggregationCacheMetadata;
+    readonly analyticsSource?: AnalyticsSourceDescriptor;
+}
+export interface SpatialAggregationCacheMetadata {
+    readonly metadataCacheable: boolean;
+    readonly resultCacheable: boolean;
+    readonly cacheKeyParts?: readonly string[];
+    readonly ttlMs?: number;
+}
+export interface SpatialAggregationSummaryMetadata {
+    readonly id: string;
+    readonly kind: SpatialAggregationSummaryKind;
+    readonly title?: string;
+    readonly field?: string;
+    readonly valueType?: SpatialAggregationValueType;
+    readonly unit?: string;
+    readonly domain?: readonly SpatialAggregationDomainValue[];
+    readonly ranges?: readonly SpatialAggregationRangeBucketSpec[];
+    readonly histogram?: {
+        readonly bins?: number;
+        readonly min?: number;
+        readonly max?: number;
+        readonly method?: SpatialAggregationHistogramSummarySpec["method"];
+    };
+}
+export interface SpatialAggregationGroupByMetadata {
+    readonly field: string;
+    readonly alias?: string;
+    readonly title?: string;
+    readonly valueType?: SpatialAggregationValueType;
+    readonly domain?: readonly SpatialAggregationDomainValue[];
+}
+export interface SpatialAggregationDomainValue {
+    readonly value: string | number | boolean | null;
+    readonly label?: string;
+    readonly color?: string;
+}
+export interface SpatialAggregationWidgetMetadata {
+    readonly id: string;
+    readonly kind: SpatialAggregationWidgetKind;
+    readonly title?: string;
+    readonly summaryId?: string;
+    readonly summaryIds?: readonly string[];
+    readonly field?: string;
+    readonly groupBy?: readonly string[];
+    readonly valueType?: SpatialAggregationValueType;
+    readonly unit?: string;
+    readonly interactions?: readonly ("filter" | "drilldown" | "highlight")[];
+    readonly progressive?: {
+        readonly stableAcrossPages: boolean;
+        readonly partialValueSemantics: SpatialAggregationProgressRefinement;
+    };
+}
+export type SpatialAggregationWidgetSummarySource = "totals" | "cell";
+export interface SpatialAggregationResolvedWidgetSummary {
+    readonly summaryId: string;
+    readonly summary: SpatialAggregationSummaryValue;
+    readonly source: SpatialAggregationWidgetSummarySource;
+    readonly cellId?: string;
+}
+export interface SpatialAggregationResult {
+    readonly schemaVersion: typeof SPATIAL_AGGREGATION_SCHEMA_VERSION;
+    readonly requestId?: string;
+    readonly sourceId: SourceId;
+    readonly generatedAt?: string;
+    readonly index: SpatialAggregationIndexState;
+    readonly metadata: SpatialAggregationMetadata;
+    readonly cells: readonly SpatialAggregationCell[];
+    readonly totals?: SpatialAggregationSummaryBag;
+    readonly groups?: readonly SpatialAggregationGroupedSummary[];
+    readonly page?: SpatialAggregationPageInfo;
+    readonly degraded?: readonly DegradedReason[];
+}
+export interface SpatialAggregationCell {
+    readonly id: string;
+    readonly parentId?: string;
+    readonly resolution?: number;
+    readonly extent?: HonuaExtent;
+    readonly centroid?: readonly [number, number];
+    readonly geometry?: Record<string, unknown> | null;
+    readonly summaries: SpatialAggregationSummaryBag;
+    readonly groups?: readonly SpatialAggregationGroupedSummary[];
+    readonly partial?: boolean;
+}
+export type SpatialAggregationSummaryBag = Readonly<Record<string, SpatialAggregationSummaryValue>>;
+export interface SpatialAggregationGroupedSummary {
+    readonly key: Readonly<Record<string, string | number | boolean | null>>;
+    readonly label?: string;
+    readonly summaries: SpatialAggregationSummaryBag;
+}
+export type SpatialAggregationSummaryValue = SpatialAggregationCountValue | SpatialAggregationMetricValue | SpatialAggregationCategoryValue | SpatialAggregationHistogramValue | SpatialAggregationRangeValue;
+export interface SpatialAggregationCountValue {
+    readonly kind: "count";
+    readonly value: number;
+    readonly approximate?: boolean;
+}
+export interface SpatialAggregationMetricValue {
+    readonly kind: Exclude<SpatialAggregationMetricKind, "count">;
+    readonly value: number | null;
+    readonly unit?: string;
+    readonly approximate?: boolean;
+}
+export interface SpatialAggregationCategoryValue {
+    readonly kind: "category";
+    readonly buckets: readonly SpatialAggregationCategoryBucket[];
+    readonly otherCount?: number;
+    readonly nullCount?: number;
+    readonly approximate?: boolean;
+}
+export interface SpatialAggregationCategoryBucket {
+    readonly value: string | number | boolean | null;
+    readonly label?: string;
+    readonly count: number;
+    readonly color?: string;
+}
+export interface SpatialAggregationHistogramValue {
+    readonly kind: "histogram";
+    readonly buckets: readonly SpatialAggregationHistogramBucket[];
+    readonly approximate?: boolean;
+}
+export interface SpatialAggregationHistogramBucket {
+    readonly min: number;
+    readonly max: number;
+    readonly count: number;
+    readonly includeMin?: boolean;
+    readonly includeMax?: boolean;
+}
+export interface SpatialAggregationRangeValue {
+    readonly kind: "range";
+    readonly buckets: readonly SpatialAggregationRangeBucketValue[];
+    readonly approximate?: boolean;
+}
+export interface SpatialAggregationRangeBucketValue extends SpatialAggregationRangeBucketSpec {
+    readonly count: number;
+}
+export interface SpatialAggregationValidationIssue {
+    readonly path: string;
+    readonly message: string;
+}
+export interface SpatialAggregationContractFixture {
+    readonly schemaVersion: 1;
+    readonly request: SpatialAggregationRequest;
+    readonly response: SpatialAggregationResult;
+}
+export declare function spatialAggregationSummaryKindRequiresField(kind: SpatialAggregationSummaryKind): boolean;
+export declare function validateSpatialAggregationRequest(request: SpatialAggregationRequest): readonly SpatialAggregationValidationIssue[];
+export declare function assertValidSpatialAggregationRequest(request: SpatialAggregationRequest): void;
+export declare function spatialAggregationSummaryKindSupportedByFeatureServerH3(kind: SpatialAggregationSummaryKind): kind is SpatialAggregationMetricKind;
+export declare function validateFeatureServerH3SpatialAggregationRequest(request: SpatialAggregationRequest): readonly SpatialAggregationValidationIssue[];
+export declare function assertFeatureServerH3SpatialAggregationRequest(request: SpatialAggregationRequest): void;
+export declare function spatialAggregationWidgets(input: SpatialAggregationResult | SpatialAggregationMetadata): readonly SpatialAggregationWidgetMetadata[];
+export declare function resolveSpatialAggregationWidgetSummary(input: SpatialAggregationResult, widgetOrSummaryId: SpatialAggregationWidgetMetadata | string): SpatialAggregationResolvedWidgetSummary | undefined;
+export declare function spatialAggregationProgress(input: SpatialAggregationResult | SpatialAggregationMetadata): SpatialAggregationProgressiveState;
+export declare function isSpatialAggregationComplete(input: SpatialAggregationResult | SpatialAggregationMetadata): boolean;
+//# sourceMappingURL=spatial-aggregation.d.ts.map

package/contract/spatial-aggregation.d.ts.map

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

package/contract/spatial-aggregation.js

@@ -0,0 +1,298 @@
+/**
+ * Protocol-neutral request and response shapes for indexed spatial aggregation.
+ *
+ * This module is intentionally a contract surface only. It describes the
+ * request envelope SDKs send to a backend that can aggregate into indexed
+ * cells, and the response metadata apps need to build widgets and load
+ * progressively. The index model id is opaque so callers can work with H3,
+ * Quadbin, WebMercatorQuad, or a provider-specific grid without switching on
+ * one implementation.
+ *
+ * @module
+ */
+export const SPATIAL_AGGREGATION_SCHEMA_VERSION = "honua.spatial-aggregation.v1";
+export const SPATIAL_AGGREGATION_METADATA_SCHEMA_VERSION = "honua.spatial-aggregation.metadata.v1";
+export const SPATIAL_AGGREGATION_CAPABILITY = "spatialAggregate";
+export const FEATURE_SERVER_H3_SPATIAL_AGGREGATION_INDEX_MODEL_ID = "h3";
+export function spatialAggregationSummaryKindRequiresField(kind) {
+    return kind !== "count";
+}
+export function validateSpatialAggregationRequest(request) {
+    const issues = [];
+    if (!isNonEmptyString(request.sourceId)) {
+        issues.push({ path: "sourceId", message: "sourceId is required" });
+    }
+    if (request.summaries.length === 0) {
+        issues.push({ path: "summaries", message: "at least one summary is required" });
+    }
+    const summaryIds = new Set();
+    request.summaries.forEach((summary, index) => {
+        const path = `summaries[${index}]`;
+        if (!isNonEmptyString(summary.id)) {
+            issues.push({ path: `${path}.id`, message: "summary id is required" });
+        }
+        else if (summaryIds.has(summary.id)) {
+            issues.push({ path: `${path}.id`, message: `duplicate summary id "${summary.id}"` });
+        }
+        else {
+            summaryIds.add(summary.id);
+        }
+        if (spatialAggregationSummaryKindRequiresField(summary.kind) && !isNonEmptyString(summary.field)) {
+            issues.push({ path: `${path}.field`, message: `${summary.kind} summaries require a field` });
+        }
+        if (summary.kind === "histogram") {
+            if (summary.bins !== undefined && !isPositiveInteger(summary.bins)) {
+                issues.push({ path: `${path}.bins`, message: "histogram bins must be a positive integer" });
+            }
+            if (summary.min !== undefined && summary.max !== undefined && summary.min >= summary.max) {
+                issues.push({ path: `${path}.max`, message: "histogram max must be greater than min" });
+            }
+        }
+        if (summary.kind === "range") {
+            if (summary.ranges.length === 0) {
+                issues.push({ path: `${path}.ranges`, message: "range summaries require at least one range" });
+            }
+            summary.ranges.forEach((range, rangeIndex) => {
+                if (!isNonEmptyString(range.id)) {
+                    issues.push({ path: `${path}.ranges[${rangeIndex}].id`, message: "range id is required" });
+                }
+                if (range.min !== undefined && range.max !== undefined && range.min >= range.max) {
+                    issues.push({ path: `${path}.ranges[${rangeIndex}].max`, message: "range max must be greater than min" });
+                }
+            });
+        }
+    });
+    request.groupBy?.forEach((group, index) => {
+        if (!isNonEmptyString(group.field)) {
+            issues.push({ path: `groupBy[${index}].field`, message: "group field is required" });
+        }
+        if (group.limit !== undefined && !isPositiveInteger(group.limit)) {
+            issues.push({ path: `groupBy[${index}].limit`, message: "group limit must be a positive integer" });
+        }
+    });
+    const viewport = request.viewport;
+    if (viewport) {
+        if (viewport.zoom !== undefined && !isNonNegativeFinite(viewport.zoom)) {
+            issues.push({ path: "viewport.zoom", message: "viewport zoom must be a non-negative number" });
+        }
+        if (viewport.width !== undefined && !isPositiveFinite(viewport.width)) {
+            issues.push({ path: "viewport.width", message: "viewport width must be greater than zero" });
+        }
+        if (viewport.height !== undefined && !isPositiveFinite(viewport.height)) {
+            issues.push({ path: "viewport.height", message: "viewport height must be greater than zero" });
+        }
+    }
+    const resolution = request.resolution;
+    if (resolution) {
+        if (resolution.zoom !== undefined && !isNonNegativeFinite(resolution.zoom)) {
+            issues.push({ path: "resolution.zoom", message: "resolution zoom must be a non-negative number" });
+        }
+        if (resolution.indexResolution !== undefined && !isNonNegativeFinite(resolution.indexResolution)) {
+            issues.push({
+                path: "resolution.indexResolution",
+                message: "index resolution must be a non-negative number",
+            });
+        }
+        if (resolution.targetCellCount !== undefined && !isPositiveInteger(resolution.targetCellCount)) {
+            issues.push({ path: "resolution.targetCellCount", message: "target cell count must be a positive integer" });
+        }
+        if (resolution.maxCellCount !== undefined && !isPositiveInteger(resolution.maxCellCount)) {
+            issues.push({ path: "resolution.maxCellCount", message: "max cell count must be a positive integer" });
+        }
+    }
+    if (request.page?.limit !== undefined && !isPositiveInteger(request.page.limit)) {
+        issues.push({ path: "page.limit", message: "page limit must be a positive integer" });
+    }
+    return issues;
+}
+export function assertValidSpatialAggregationRequest(request) {
+    const issues = validateSpatialAggregationRequest(request);
+    if (issues.length > 0) {
+        const details = issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+        throw new Error(`Invalid spatial aggregation request: ${details}`);
+    }
+}
+export function spatialAggregationSummaryKindSupportedByFeatureServerH3(kind) {
+    return kind === "count" || kind === "sum" || kind === "avg" || kind === "min" || kind === "max";
+}
+export function validateFeatureServerH3SpatialAggregationRequest(request) {
+    const issues = [...validateSpatialAggregationRequest(request)];
+    const indexResolution = request.resolution?.indexResolution;
+    if (indexResolution === undefined) {
+        issues.push({
+            path: "resolution.indexResolution",
+            message: "FeatureServer queryH3 requires an explicit indexResolution",
+        });
+    }
+    else if (!Number.isInteger(indexResolution) || indexResolution < 0 || indexResolution > 15) {
+        issues.push({
+            path: "resolution.indexResolution",
+            message: "FeatureServer queryH3 indexResolution must be an integer between 0 and 15",
+        });
+    }
+    if (request.index?.modelId !== undefined &&
+        request.index.modelId !== FEATURE_SERVER_H3_SPATIAL_AGGREGATION_INDEX_MODEL_ID) {
+        issues.push({
+            path: "index.modelId",
+            message: "FeatureServer queryH3 only supports the H3 index model",
+        });
+    }
+    if (request.index?.geometry === "centroid") {
+        issues.push({
+            path: "index.geometry",
+            message: "FeatureServer queryH3 does not currently return cell centroids",
+        });
+    }
+    if (request.spatialFilter !== undefined) {
+        issues.push({
+            path: "spatialFilter",
+            message: "FeatureServer queryH3 does not currently accept spatialFilter input",
+        });
+    }
+    if (request.viewport !== undefined) {
+        issues.push({
+            path: "viewport",
+            message: "FeatureServer queryH3 does not currently accept viewport input",
+        });
+    }
+    if (request.groupBy !== undefined && request.groupBy.length > 0) {
+        issues.push({
+            path: "groupBy",
+            message: "FeatureServer queryH3 does not currently support grouped summaries",
+        });
+    }
+    if (request.page !== undefined) {
+        issues.push({
+            path: "page",
+            message: "FeatureServer queryH3 does not currently support cursor paging",
+        });
+    }
+    const metricSummaries = request.summaries.filter((summary) => spatialAggregationSummaryKindSupportedByFeatureServerH3(summary.kind));
+    request.summaries.forEach((summary, index) => {
+        const path = `summaries[${index}]`;
+        if (!spatialAggregationSummaryKindSupportedByFeatureServerH3(summary.kind)) {
+            issues.push({
+                path: `${path}.kind`,
+                message: `${summary.kind} summaries are not supported by FeatureServer queryH3`,
+            });
+            return;
+        }
+        if (summary.kind === "count" && summary.countDistinct === true) {
+            issues.push({
+                path: `${path}.countDistinct`,
+                message: "FeatureServer queryH3 does not currently support countDistinct summaries",
+            });
+        }
+        if (summary.kind === "count" && summary.field === undefined && metricSummaries.length > 1) {
+            issues.push({
+                path: `${path}.field`,
+                message: "count summaries require a field when combined with other queryH3 metrics",
+            });
+        }
+    });
+    return issues;
+}
+export function assertFeatureServerH3SpatialAggregationRequest(request) {
+    const issues = validateFeatureServerH3SpatialAggregationRequest(request);
+    if (issues.length > 0) {
+        const details = issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+        throw new Error(`Invalid FeatureServer queryH3 spatial aggregation request: ${details}`);
+    }
+}
+export function spatialAggregationWidgets(input) {
+    const metadata = "metadata" in input ? input.metadata : input;
+    if (metadata.widgets && metadata.widgets.length > 0)
+        return metadata.widgets;
+    const widgets = metadata.summaries.map(summaryToWidget);
+    if (metadata.groupBy && metadata.groupBy.length > 0) {
+        widgets.push({
+            id: "grouped-summaries",
+            kind: "grouped-table",
+            title: "Grouped summaries",
+            summaryIds: metadata.summaries.map((summary) => summary.id),
+            groupBy: metadata.groupBy.map((group) => group.alias ?? group.field),
+            interactions: ["filter", "drilldown"],
+            progressive: {
+                stableAcrossPages: false,
+                partialValueSemantics: "refine",
+            },
+        });
+    }
+    return widgets;
+}
+export function resolveSpatialAggregationWidgetSummary(input, widgetOrSummaryId) {
+    const summaryId = typeof widgetOrSummaryId === "string" ? widgetOrSummaryId : widgetOrSummaryId.summaryId;
+    if (!summaryId)
+        return undefined;
+    const total = input.totals?.[summaryId];
+    if (total)
+        return { summaryId, summary: total, source: "totals" };
+    for (const cell of input.cells) {
+        const summary = cell.summaries[summaryId];
+        if (summary)
+            return { summaryId, summary, source: "cell", cellId: cell.id };
+    }
+    return undefined;
+}
+export function spatialAggregationProgress(input) {
+    const metadata = "metadata" in input ? input.metadata : input;
+    if (metadata.progressive)
+        return metadata.progressive;
+    if ("page" in input && input.page?.nextCursor) {
+        return {
+            status: "partial",
+            refinement: "append",
+            nextCursor: input.page.nextCursor,
+            loadedCellCount: input.page.loadedCellCount ?? input.cells.length,
+            totalCellCount: input.page.totalCellCount,
+        };
+    }
+    return {
+        status: "complete",
+        loadedCellCount: "cells" in input ? input.cells.length : undefined,
+    };
+}
+export function isSpatialAggregationComplete(input) {
+    const progress = spatialAggregationProgress(input);
+    return progress.status === "complete" && !progress.nextCursor;
+}
+function summaryToWidget(summary) {
+    return {
+        id: `${summary.id}-widget`,
+        kind: widgetKindForSummary(summary.kind),
+        title: summary.title,
+        summaryId: summary.id,
+        field: summary.field,
+        valueType: summary.valueType,
+        unit: summary.unit,
+        interactions: summary.kind === "count" ? ["highlight"] : ["filter", "highlight"],
+        progressive: {
+            stableAcrossPages: summary.kind !== "histogram" && summary.kind !== "range",
+            partialValueSemantics: "refine",
+        },
+    };
+}
+function widgetKindForSummary(kind) {
+    switch (kind) {
+        case "category":
+            return "category-list";
+        case "histogram":
+            return "histogram";
+        case "range":
+            return "range-list";
+        default:
+            return "stat";
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isPositiveFinite(value) {
+    return Number.isFinite(value) && value > 0;
+}
+function isNonNegativeFinite(value) {
+    return Number.isFinite(value) && value >= 0;
+}
+function isPositiveInteger(value) {
+    return Number.isInteger(value) && value > 0;
+}