@ngis/plugin-ui 0.4.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 NeoGIS contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,25 @@
+# @ngis/plugin-ui
+
+Host-connected React components and flow bindings for NeoGIS plugin authors.
+
+```bash
+npm install --save-dev @ngis/plugin-sdk @ngis/plugin-ui react @types/react
+```
+
+```tsx
+import { ResourceSelect } from "@ngis/plugin-ui";
+
+<ResourceSelect
+  host={host}
+  value={resourceId}
+  onChange={setResourceId}
+/>;
+```
+
+This is a NeoGIS host contract, not a standalone component library. The running
+host owns the component implementations and React instance; the npm package
+ships their public declarations and lazy host-delegating shims. Plugin builds
+must leave `react`, `react-dom`, `react/jsx-runtime`, `@ngis/plugin-sdk`, and
+`@ngis/plugin-ui` external.
+
+`@ngis/plugin-ui` and `@ngis/plugin-sdk` use the same API version.

package/dist/index.cjs

@@ -0,0 +1,71 @@
+// Generated by scripts/build.mjs — do not hand-edit.
+// The components themselves live in the host bundle (F14.14); this resolves them.
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const NGIS_EXTERNALS = "__NGIS_PLUGIN_EXTERNALS__";
+function hostComponent(name) {
+  const ui = globalThis[NGIS_EXTERNALS] && globalThis[NGIS_EXTERNALS]["@ngis/plugin-ui"];
+  if (!ui || ui[name] === undefined) {
+    throw new Error(
+      "[ngis] @ngis/plugin-ui." + name + " is rendered by the host: it is provided by the running NGIS " +
+      "frontend through globalThis." + NGIS_EXTERNALS + ". Leave \"@ngis/plugin-ui\" external in your " +
+      "bundle (the host's import map resolves it) instead of bundling this file."
+    );
+  }
+  return ui[name];
+}
+exports.NGIS_PLUGIN_UI_VERSION = "0.4.0";
+exports.ResourceSelect = function ResourceSelect(props) {
+  return hostComponent("ResourceSelect")(props);
+};
+exports.ModelSelect = function ModelSelect(props) {
+  return hostComponent("ModelSelect")(props);
+};
+exports.FieldSelect = function FieldSelect(props) {
+  return hostComponent("FieldSelect")(props);
+};
+exports.ExtentPicker = function ExtentPicker(props) {
+  return hostComponent("ExtentPicker")(props);
+};
+exports.ParamForm = function ParamForm(props) {
+  return hostComponent("ParamForm")(props);
+};
+exports.RunButton = function RunButton(props) {
+  return hostComponent("RunButton")(props);
+};
+exports.TaskStatus = function TaskStatus(props) {
+  return hostComponent("TaskStatus")(props);
+};
+exports.TaskList = function TaskList(props) {
+  return hostComponent("TaskList")(props);
+};
+exports.ResultActions = function ResultActions(props) {
+  return hostComponent("ResultActions")(props);
+};
+exports.AttributeTable = function AttributeTable(props) {
+  return hostComponent("AttributeTable")(props);
+};
+exports.StatChart = function StatChart(props) {
+  return hostComponent("StatChart")(props);
+};
+exports.Flow = function Flow(props) {
+  return hostComponent("Flow")(props);
+};
+exports.useFlowScope = function useFlowScope(props) {
+  return hostComponent("useFlowScope")(props);
+};
+exports.useFlowPort = function useFlowPort(props) {
+  return hostComponent("useFlowPort")(props);
+};
+exports.BatchTable = function BatchTable(props) {
+  return hostComponent("BatchTable")(props);
+};
+exports.ngisTypeVerdict = function ngisTypeVerdict(...args) {
+  return hostComponent("ngisTypeVerdict")(...args);
+};
+exports.ngisFlowSpread = function ngisFlowSpread(...args) {
+  return hostComponent("ngisFlowSpread")(...args);
+};
+exports.serializeRecipe = function serializeRecipe(...args) {
+  return hostComponent("serializeRecipe")(...args);
+};

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `@ngis/plugin-ui` — the second SDK package: host-connected smart components
+ * (Stage 14, **F14.14**).
+ *
+ * **This file is the W1-kickoff export skeleton: names only, no bodies.** It is
+ * read-only to YB1 and YB2; **Y2 owns it** and fills in the W1 half
+ * (`ResourceSelect`/`ModelSelect`/`FieldSelect`/`ExtentPicker`), Y3–Y7 add the
+ * rest under the ownership table below. The point of freezing the names here is
+ * the Stage 13 W1 `NgisResourceType` lesson — exported *names*, not just line
+ * ranges, are what collide across concurrent sessions.
+ *
+ * ## Why a separate package, and not a folder inside `@ngis/plugin-sdk`
+ *
+ * The SDK is types-first (`tsc --emitDeclarationOnly` plus a two-line runtime
+ * shim). Merging a React component library into it changes the SDK's nature and
+ * couples type-only authors to a UI bundle. So: two packages, one version
+ * string.
+ *
+ * ## Versions are contractually locked, not conventionally aligned (F14.13)
+ *
+ * ```
+ * @ngis/plugin-sdk version === @ngis/plugin-ui version === NGIS_MAP_API_VERSION === "0.4.0"
+ * ```
+ *
+ * ## Distribution (F14.14)
+ *
+ * The components' **runtime lives in the host bundle**, reached through the
+ * fifth externals entry (`@ngis/plugin-ui` →
+ * `/plugin-externals/plugin-ui.mjs`, added by Y2 under the stage's single
+ * declared G-D exception). That is what keeps every component
+ * host-renderable-from-declarative-data and therefore survivable into Stage
+ * 15's worker tier. **Tarball distribution is deferred to Stage 15** — the ED17
+ * channel's MinIO key is a hardcoded `sdk/{version}/plugin-sdk.tgz`, so a second
+ * package needs ~20 lines of Java in `ngis-extension`, which no Stage 14 backend
+ * session owns. In-repo dogfood consumes this through the pnpm workspace.
+ *
+ * ## The frozen export surface, and its owner
+ *
+ * | export | kind | owner |
+ * |---|---|---|
+ * | `ResourceSelect` · `ResourceSelectProps` | component | Y2 (W1) |
+ * | `ModelSelect` · `ModelSelectProps` | component | Y2 (W1) |
+ * | `FieldSelect` · `FieldSelectProps` | component | Y2 (W1) |
+ * | `ExtentPicker` · `ExtentPickerProps` | component | Y2 (W1) |
+ * | `ParamForm` · `ParamFormProps` · `NgisParamFormChange` | component | Y3 (W2) |
+ * | `RunButton` · `RunButtonProps` | component | Y4 (W2) |
+ * | `TaskStatus` · `TaskList` (+ props) | component | Y4 (W2) |
+ * | `ResultActions` · `ResultActionsProps` | component | Y4b (W2) |
+ * | `AttributeTable` · `AttributeTableProps` | component | Y4b (W2) |
+ * | `StatChart` · `StatChartProps` | component | Y4b (W2) |
+ * | `Flow` · `FlowProps` · `useFlowPort` · `useFlowScope` | runtime | **Y5b** (W3) |
+ * | `NgisPortDirection` · `NgisPortKind` · `NgisPortSpec` | type | **Y5a** (W3) |
+ * | `ngisTypeVerdict` · `NgisTypeVerdict` | runtime | **Y5a** (W3) |
+ * | `ngisFlowSpread` · `NgisFlowRef` · `NgisInputBinding` | runtime | **Y5a** (W3) |
+ * | `NgisDisclosureState` · `NgisFlowReason` · `NgisNodeEnablement` | type | **Y5a** (W3) |
+ * | `NgisFlowNode` · `NgisFlowSnapshot` | type | **Y5a** (W3) |
+ * | `serializeRecipe` · `NgisRecipe` (+ family) | runtime | Y6 (W4) |
+ * | `BatchTable` · `BatchTableProps` · `NgisBatchConfig` | component | Y7 (W4) |
+ *
+ * **W3 note.** Every type on Y5a's rows is *declared* in the kickoff seam
+ * `src/components/plugin-ui/w3-contracts.ts` and *re-exported* by Y5a's
+ * `flow-model.ts`; the barrels take them from `flow-model.ts` only, so the seam
+ * module stays off the public surface exactly as `w2-contracts.ts` does. `Flow`
+ * is a component and therefore owes all six lockstep places (`scripts/build.mjs`
+ * checks two of them mechanically).
+ *
+ * **Two rules on that table.** A name not on your row is not yours to declare
+ * (the X4b `commandPluginId` precedent). And every component that portals — any
+ * Select, Popover or Dialog — takes a `contentClassName` escape hatch, because
+ * plugin-ui renders inside `.gis-theme` (Tenon) and a portal lands on
+ * `document.body`, outside the theme scope. `bg-success`/`bg-warning` resolve to
+ * nothing out there. That is the `VersionPolicyControl`/`ExtensionSettingsForm`
+ * precedent, and it has already cost two sessions.
+ */
+/**
+ * The package version, asserted equal to `NGIS_MAP_API_VERSION` and to
+ * `@ngis/plugin-sdk`'s version by a test Y2 ships (F14.13 — locked, not
+ * aligned). One string; any divergence is a lie about what the tarball
+ * contains.
+ */
+export declare const NGIS_PLUGIN_UI_VERSION = "0.4.0";
+export { ResourceSelect } from "./src/components/plugin-ui/ResourceSelect";
+export type { ResourceSelectBaseProps, ResourceSelectProps, } from "./src/components/plugin-ui/ResourceSelect";
+export { ModelSelect } from "./src/components/plugin-ui/ModelSelect";
+export type { ModelSelectBaseProps, ModelSelectProps, } from "./src/components/plugin-ui/ModelSelect";
+export { FieldSelect } from "./src/components/plugin-ui/FieldSelect";
+export type { FieldSelectProps } from "./src/components/plugin-ui/FieldSelect";
+export { ExtentPicker } from "./src/components/plugin-ui/ExtentPicker";
+export type { ExtentPickerProps } from "./src/components/plugin-ui/ExtentPicker";
+export { ParamForm } from "./src/components/plugin-ui/ParamForm";
+export type { NgisParamFormChange, ParamFormProps, } from "./src/components/plugin-ui/ParamForm";
+export { RunButton } from "./src/components/plugin-ui/RunButton";
+export type { RunButtonProps } from "./src/components/plugin-ui/RunButton";
+export { TaskStatus } from "./src/components/plugin-ui/TaskStatus";
+export type { NgisTaskVariant, TaskStatusProps, } from "./src/components/plugin-ui/TaskStatus";
+export { TaskList } from "./src/components/plugin-ui/TaskList";
+export type { TaskListProps } from "./src/components/plugin-ui/TaskList";
+export { ResultActions } from "./src/components/plugin-ui/ResultActions";
+export type { NgisResultChartOutput, NgisResultChartRequest, ResultActionsProps, } from "./src/components/plugin-ui/ResultActions";
+export { AttributeTable } from "./src/components/plugin-ui/AttributeTable";
+export type { AttributeTableProps } from "./src/components/plugin-ui/AttributeTable";
+export { StatChart } from "./src/components/plugin-ui/StatChart";
+export type { StatChartProps } from "./src/components/plugin-ui/StatChart";
+export { ngisFlowSpread, ngisTypeVerdict, } from "./src/components/plugin-ui/flow-model";
+export type { NgisDisclosureState, NgisFlowNode, NgisFlowReason, NgisFlowRef, NgisFlowSnapshot, NgisInputBinding, NgisNodeEnablement, NgisPortDirection, NgisPortKind, NgisPortSpec, NgisTypeVerdict, } from "./src/components/plugin-ui/flow-model";
+export { Flow } from "./src/components/plugin-ui/Flow";
+export type { FlowProps } from "./src/components/plugin-ui/Flow";
+export { useFlowScope } from "./src/components/plugin-ui/Flow";
+export { useFlowPort } from "./src/components/plugin-ui/Flow";
+export { serializeRecipe, } from "./src/components/plugin-ui/recipe-model";
+export type { NgisRecipe, NgisRecipeInput, NgisRecipeMeta, NgisRecipeNode, NgisRecipeOutput, } from "./src/components/plugin-ui/recipe-model";
+export { BatchTable } from "./src/components/plugin-ui/BatchTable";
+export type { BatchTableProps } from "./src/components/plugin-ui/BatchTable";
+export type { NgisBatchConfig } from "./src/components/plugin-ui/batch-model";

package/dist/index.mjs

@@ -0,0 +1,69 @@
+// Generated by scripts/build.mjs — do not hand-edit.
+// The components themselves live in the host bundle (F14.14); this resolves them.
+const NGIS_EXTERNALS = "__NGIS_PLUGIN_EXTERNALS__";
+function hostComponent(name) {
+  const ui = globalThis[NGIS_EXTERNALS] && globalThis[NGIS_EXTERNALS]["@ngis/plugin-ui"];
+  if (!ui || ui[name] === undefined) {
+    throw new Error(
+      "[ngis] @ngis/plugin-ui." + name + " is rendered by the host: it is provided by the running NGIS " +
+      "frontend through globalThis." + NGIS_EXTERNALS + ". Leave \"@ngis/plugin-ui\" external in your " +
+      "bundle (the host's import map resolves it) instead of bundling this file."
+    );
+  }
+  return ui[name];
+}
+export const NGIS_PLUGIN_UI_VERSION = "0.4.0";
+export function ResourceSelect(props) {
+  return hostComponent("ResourceSelect")(props);
+}
+export function ModelSelect(props) {
+  return hostComponent("ModelSelect")(props);
+}
+export function FieldSelect(props) {
+  return hostComponent("FieldSelect")(props);
+}
+export function ExtentPicker(props) {
+  return hostComponent("ExtentPicker")(props);
+}
+export function ParamForm(props) {
+  return hostComponent("ParamForm")(props);
+}
+export function RunButton(props) {
+  return hostComponent("RunButton")(props);
+}
+export function TaskStatus(props) {
+  return hostComponent("TaskStatus")(props);
+}
+export function TaskList(props) {
+  return hostComponent("TaskList")(props);
+}
+export function ResultActions(props) {
+  return hostComponent("ResultActions")(props);
+}
+export function AttributeTable(props) {
+  return hostComponent("AttributeTable")(props);
+}
+export function StatChart(props) {
+  return hostComponent("StatChart")(props);
+}
+export function Flow(props) {
+  return hostComponent("Flow")(props);
+}
+export function useFlowScope(props) {
+  return hostComponent("useFlowScope")(props);
+}
+export function useFlowPort(props) {
+  return hostComponent("useFlowPort")(props);
+}
+export function BatchTable(props) {
+  return hostComponent("BatchTable")(props);
+}
+export function ngisTypeVerdict(...args) {
+  return hostComponent("ngisTypeVerdict")(...args);
+}
+export function ngisFlowSpread(...args) {
+  return hostComponent("ngisFlowSpread")(...args);
+}
+export function serializeRecipe(...args) {
+  return hostComponent("serializeRecipe")(...args);
+}

package/dist/src/api/analysis.d.ts

@@ -0,0 +1,140 @@
+import type { NgisBindingValidation, NgisExecutionValidation, NgisToolSearchResponse, NgisToolUiSchema, NgisValidateBindingsBody, NgisValidateExecutionBody } from "../types/analysis";
+import type { PageResult } from "../types/common";
+export interface AnalysisModelboxNode {
+    id: string;
+    name: string;
+    provider?: string | null;
+    parent_id?: string | null;
+    children?: AnalysisModelboxNode[] | null;
+}
+export interface AnalysisTool {
+    id: string;
+    version?: number | null;
+    name: string;
+    provider?: string | null;
+    category?: string | null;
+    description?: string | null;
+    tags?: string[] | string | null;
+    enabled?: boolean | null;
+    modelbox_id?: string | null;
+    capability_key?: string | null;
+}
+export interface AnalysisToolSchemaProperty {
+    title?: string | null;
+    description?: string | null;
+    type?: string | string[] | null;
+    format?: string | null;
+    enum?: unknown[] | null;
+    default?: string | number | boolean | null;
+    default_val?: string | number | boolean | null;
+    minimum?: number | null;
+    maximum?: number | null;
+    "x-role"?: "input" | "output" | "option" | string | null;
+    "x-data-type"?: "Vector" | "Raster" | "Table" | string | null;
+    "x-display-name"?: string | null;
+    "x-constraints"?: {
+        min?: number | null;
+        max?: number | null;
+        choices?: unknown[] | null;
+        [key: string]: unknown;
+    } | null;
+    choices?: unknown[] | null;
+    items?: AnalysisToolSchemaProperty | null;
+    "x-ngis-type"?: string | null;
+    "x-ngis-role"?: string | null;
+    [key: string]: unknown;
+}
+export interface AnalysisToolSchema extends AnalysisToolSchemaProperty {
+    properties?: Record<string, AnalysisToolSchemaProperty> | null;
+    required?: string[] | null;
+}
+export type AnalysisTaskStatus = "QUEUED" | "RUNNING" | "SUCCESS" | "FAILED" | "CANCELLED";
+export type AnalysisTaskOutputMode = "ADD_LAYER" | "UPDATE_RESOURCE";
+export interface CreateAnalysisTaskParams {
+    tool_id: string;
+    params: Record<string, string>;
+    scene_id?: string;
+    expected_scene_generation?: number;
+    output_mode?: AnalysisTaskOutputMode;
+    target_resource_id?: string;
+}
+export interface AnalysisTask {
+    id: string;
+    tool_id: string;
+    provider?: string | null;
+    status: AnalysisTaskStatus;
+    params_json?: unknown;
+    output_json?: unknown;
+    error_message?: string | null;
+    log_output?: string | null;
+    exit_code?: number | null;
+    owner_id?: string | null;
+    scene_id?: string | null;
+    expected_scene_generation?: number | null;
+    integration_status?: "PENDING" | "DONE" | "PARTIAL" | "FAILED" | "SKIPPED" | null;
+    integration_detail?: string | null;
+}
+export interface AnalysisTaskOutputFile {
+    name?: string | null;
+    minio_key?: string | null;
+    file_id?: string | null;
+    primary?: boolean | null;
+}
+export declare const analysisApi: {
+    listModelboxes(): Promise<AnalysisModelboxNode[]>;
+    listTools(params?: {
+        provider?: string;
+        category?: string;
+        capability_key?: string;
+        modelbox_id?: string;
+        recursive?: boolean;
+    }, signal?: AbortSignal): Promise<AnalysisTool[]>;
+    listModelboxTools(boxId: string, recursive?: boolean): Promise<AnalysisTool[]>;
+    /**
+     * Paged sibling of `listTools`, for browsing the ~2,300-tool catalog (`/models`).
+     *
+     * `q` is a server-side substring match over name/description/category/tags. The
+     * envelope is the platform-wide `PageResult<T>` shape; the rows are the same
+     * snake_case `AnalysisTool` the flat list returns.
+     */
+    pageTools(params?: {
+        page?: number;
+        size?: number;
+        q?: string;
+        provider?: string;
+        category?: string;
+        capability_key?: string;
+        modelbox_id?: string;
+        recursive?: boolean;
+    }, signal?: AbortSignal): Promise<PageResult<AnalysisTool>>;
+    getTool(toolId: string, signal?: AbortSignal): Promise<AnalysisTool>;
+    getToolSchema(toolId: string, signal?: AbortSignal): Promise<AnalysisToolSchema>;
+    createTask(params: CreateAnalysisTaskParams, signal?: AbortSignal): Promise<AnalysisTask>;
+    getTask(taskId: string, signal?: AbortSignal): Promise<AnalysisTask>;
+    getTaskOutputFiles(taskId: string, signal?: AbortSignal): Promise<AnalysisTaskOutputFile[]>;
+    cancelTask(taskId: string, signal?: AbortSignal): Promise<void>;
+    streamTask(taskId: string, signal?: AbortSignal): Promise<Response>;
+    getToolUiSchema(toolId: string, signal?: AbortSignal): Promise<NgisToolUiSchema>;
+    validateToolExecution(toolId: string, body: NgisValidateExecutionBody, signal?: AbortSignal): Promise<NgisExecutionValidation>;
+    validateToolBindings(toolId: string, body: NgisValidateBindingsBody, signal?: AbortSignal): Promise<NgisBindingValidation>;
+    searchTools(params?: AnalysisToolSearchParams, signal?: AbortSignal): Promise<NgisToolSearchResponse>;
+};
+/** Repeated-value filters, named exactly as the server's `Query` params. */
+export interface AnalysisToolSearchParams {
+    q?: string;
+    limit?: number;
+    provider?: readonly string[];
+    kind?: readonly string[];
+    input_type?: readonly string[];
+    output_type?: readonly string[];
+    domain?: readonly string[];
+    operation_type?: readonly string[];
+    modelbox_path?: readonly string[];
+    capability_key?: readonly string[];
+}
+/**
+ * Exported for test: the repeated-parameter shape is the whole point of this
+ * helper, and asserting it on a built string is cheaper than asserting it on a
+ * captured fetch URL.
+ */
+export declare function buildToolSearchQuery(params: AnalysisToolSearchParams): string;