@ngis/plugin-ui 0.4.0 → 0.4.1

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

@@ -26,6 +26,7 @@
  * `src/sdk/facets/types.ts`; F14.2 fixes the schema family's home here.
  */
 import type { NgisDataType } from "../sdk/facets/types";
+import type { NgisValidationIssue } from "../domain/models/crs";
 export type WorkSurface = "workflow" | "insight" | "code";
 export type RightDockMode = "none" | "ai";
 export type MapFocusMode = "split" | "map" | "work";
@@ -35,15 +36,31 @@ export type NgisParamRole = "input" | "option" | "output";
 /**
  * Total, frozen. **There is NO fallback widget:** an unknown key is a
  * render-time error surfaced in place, never a silently-degraded text input.
- * A Y3 widget registry missing any of the twelve is a defect.
+ * A Y3 widget registry missing any of the thirteen is a defect.
  *
  * `field-select`, `extent` and `textarea` are **never emitted by YB1 in v1** —
  * no builtin schema expresses a field, a bbox or a long-text parameter. They
  * are in the union because the registry must be total over it, and because an
  * author's `ParamForm` `widgets` override and a recipe's promoted inputs can
  * select them.
+ *
+ * ## `"crs"` is the thirteenth, and it **AMENDS F14.2** (Stage 25, F25.3)
+ *
+ * F14.2 froze twelve keys and called the union closed. `"crs"` is added by an
+ * explicit amendment, not by growth: it is the widget for `ngis:outputCrs`, the
+ * one **platform** parameter every tool's UI schema carries (F25.4), and there
+ * was no key in the twelve that could carry a coordinate reference system
+ * without lying about it — `select` would have needed a closed choice list over
+ * the EPSG registry, and `text` would have accepted anything.
+ *
+ * Because {@link NgisWidgetRegistry} is a *total* mapped type, an external
+ * implementer that does not add the key **fails to compile. That is the intended
+ * signal**, recorded here as an amendment rather than discovered as an accident.
+ * S25-02 enumerated every implementer in the repo — there are none outside
+ * `src/` — and the union has **nine** in-repo gate sites, not one; F25.3 lists
+ * them.
  */
-export type NgisWidgetKey = "resource-select" | "resource-multi" | "select" | "multi-select" | "switch" | "number" | "integer" | "text" | "textarea" | "output-name" | "field-select" | "extent";
+export type NgisWidgetKey = "resource-select" | "resource-multi" | "select" | "multi-select" | "switch" | "number" | "integer" | "text" | "textarea" | "output-name" | "field-select" | "extent" | "crs";
 export interface NgisUiSchemaChoice {
     value: string;
     label: string;
@@ -109,7 +126,26 @@ export interface NgisToolUiSchema {
  * rule `recipeVersion` carries in F14.6).
  */
 export declare const NGIS_UI_SCHEMA_VERSION: 1;
-/** `PASS | ADAPTABLE | UNKNOWN | FAIL`, passed through verbatim. */
+/**
+ * `PASS | ADAPTABLE | UNKNOWN | FAIL`, passed through verbatim.
+ *
+ * **Stage 29 (F29.8) — `verdict` and issue code are INDEPENDENT axes.**
+ * `"ADAPTABLE"` is the same token for Stage 26's **CRS** adaptation and Stage
+ * 29's **kind** adaptation; `verdict` carries *what*, `issues[]` carries *why*,
+ * and **only the issue code distinguishes them**. A test that asserts nothing but
+ * `verdict === "ADAPTABLE"` passes on the CRS case (`binding-adaptable.json`
+ * `B02`) and proves Stage 26's code path rather than this stage's — which is why
+ * the predicate is `isKindAdaptableIssue` in
+ * `src/domain/models/dataset-kind.ts`, over the code and never over the verdict.
+ *
+ * The kind code is `KIND_ADAPTABLE`, severity `advisory`, `port` set, and **`fix`
+ * absent** — `NgisValidationIssueFix` means *"set this parameter to this value"*
+ * and there is no parameter that turns a kind adaptation on or off, so a client
+ * rendering a one-click fix here has invented an affordance the server cannot
+ * honour. (CRS differs: `ngis:outputCrs` is a real parameter.) `NgisCrsIssueCode`
+ * is already open, so the code needs no union edit. Rendering it is `S29-33`'s
+ * (W3), and the client never re-classifies a server verdict or severity (`G-U`).
+ */
 export type NgisBindingVerdict = "PASS" | "ADAPTABLE" | "UNKNOWN" | "FAIL";
 /** `READY | NEEDS_CONFIGURATION | NOT_EXECUTABLE`, passed through verbatim. */
 export type NgisExecutionVerdict = "READY" | "NEEDS_CONFIGURATION" | "NOT_EXECUTABLE";
@@ -130,9 +166,30 @@ export interface NgisBindingValidationEntry {
     verdict: NgisBindingVerdict;
     reason: string;
     geometry_type: string;
-    srid: number;
-    native_srid: number;
-    working_srid: number;
+    /**
+     * **Stage 25 (F25.1):** the numeric triple `srid` / `native_srid` /
+     * `working_srid` is gone **from this interface**. It was one of the three SRID
+     * vocabularies that never met, and the only one that could tell a caller
+     * "unknown" — it spelled it `0`, which every consumer read as a CRS. A
+     * binding's CRS is the dataset's `crs: NgisCrsRef | null`.
+     *
+     * **CORRECTION OF RECORD (`S25-V255`, S25-32, W3).** This comment used to say
+     * the triple was gone "from this entry **and from the wire**". The second half
+     * was false when it was written and is still false: `validation_rest.py:72-74`
+     * and `binding_validation.py:183-185` send all three fields on both the REST
+     * and the gRPC leg to this day. The W3 kickoff marked them
+     * `[deprecated = true]` in `geoanalysis.proto`; removing them needs
+     * `binding_validation.py`'s `x-required-srid` path to lose its only CRS
+     * source, which is not a W3 change.
+     *
+     * The distinction matters because this file is **quoted verbatim** into the
+     * published contract reference at `/market/devkit/docs`: a wrong sentence here
+     * is a wrong sentence in the SDK documentation a plugin author reads. What is
+     * true is that **the client drops them on the floor** — nothing in this repo
+     * declares or reads them, so no frontend code path can be misled by a `0`.
+     * That is a client guarantee, not a wire fact, and the two are only the same
+     * sentence when the server has actually stopped sending.
+     */
     access_mode: string;
     executable: boolean;
 }
@@ -145,6 +202,19 @@ export interface NgisBindingValidation {
     unresolved_ports: readonly string[];
     errors: readonly string[];
     warnings: readonly string[];
+    /**
+     * **Stage 25 (F25.6), additive.** Typed per-port issues. The F14.9 string
+     * arrays above are unchanged and keep their meaning; this channel carries the
+     * `param`/`port` routing and the one-click `fix` a string cannot.
+     *
+     * This half and {@link NgisExecutionValidation.issues} are **one channel read
+     * at two levels**, exactly as the F14.9 string arrays are: a blocking entry
+     * here blocks the submit too. Reading only the other level was `S29-V234`.
+     *
+     * Optional because a server that has not shipped F25.6 omits it, and an
+     * absent `issues` is "the server said nothing", never "the server said fine".
+     */
+    issues?: readonly NgisValidationIssue[];
 }
 /** `ValidateToolExecutionResponse`, field-for-field, with `normalized_params_json`
  *  replaced by the decoded `normalized_params` object (the one divergence). */
@@ -161,6 +231,15 @@ export interface NgisExecutionValidation {
     execution_mode: NgisExecutionMode;
     /** Decoded. The proto's `normalized_params_json` string is never sent to a browser. */
     normalized_params: Readonly<Record<string, string>>;
+    /**
+     * **Stage 25 (F25.6), additive.** See {@link NgisBindingValidation.issues}.
+     * `isSubmitBlocked` counts a `severity: "blocking"` entry here **or on that
+     * half**, in addition to F14.9's existing rule; the client never suppresses,
+     * downgrades or re-classifies a server issue (G-U) — and declining to gate on
+     * a severity the server declared is a suppression, which is why reading only
+     * this level was a defect (`S29-V234`) rather than a narrower reading.
+     */
+    issues?: readonly NgisValidationIssue[];
 }
 /** `POST /api/analysis/tools/{tool_id}/validate-execution` body. */
 export interface NgisValidateExecutionBody {
@@ -172,7 +251,32 @@ export interface NgisValidateExecutionBody {
     expected_scene_generation?: number;
     output_mode?: NgisOutputMode;
     target_resource_id?: string | null;
-    target_srid?: number;
+    /**
+     * **Stage 25 (F25.12):** `target_srid` is removed. It was typed, forwarded to
+     * validation, and **set by no component** — dead plumbing, and its presence
+     * made a numeric SRID look like a supported way to ask for a projection. The
+     * replacement is F25.4's `outputCrs?: string` (a `NgisCrsRef` key, not an
+     * integer), added on the submit and validate bodies by the W2 session that
+     * owns `RunButton` / `run-data.ts`.
+     *
+     * **Added here by S25-23 (W2), which is that session.**
+     */
+    /**
+     * **Stage 25 (F25.4).** The `ngis:outputCrs` platform parameter, as an
+     * `NgisCrsRef` **key** (`"EPSG:32650"`, `"custom:<ulid>"`).
+     *
+     * **This one field is camelCase in an otherwise snake_case body, and that is
+     * the server's spelling, not a slip.** The W2 dispatch is explicit: the proto
+     * carries `output_crs` on `SubmitTaskRequest` / the validate messages, and the
+     * REST legs take `outputCrs`. Re-spelling it here to match the neighbours
+     * would put a field on the wire that `ngis-geoanalysis` does not read — which
+     * is exactly the failure `target_srid` had, arriving forever and meaning
+     * nothing.
+     *
+     * Absent means "compute in the primary input's own CRS" (R4). The client never
+     * substitutes a value for an absent one (G-CRS).
+     */
+    outputCrs?: string;
 }
 /** `POST /api/analysis/tools/{tool_id}/validate-bindings` body. */
 export interface NgisValidateBindingsBody {

package/dist/src/types/extensions.d.ts

@@ -184,7 +184,44 @@ export interface PackageManifestDto {
     homepage?: string;
     publisher?: string;
     changelog?: string;
+    /**
+     * Semantic tool requirements declared by a UI plugin. The alias is local to
+     * this manifest; only the host receives the resolved, opaque implementation
+     * id at runtime. A bundle must therefore bind a tool through its alias, never
+     * through a UUID copied from the tool catalogue.
+     */
+    toolDependencies?: NgisToolDependencyDeclaration[];
+}
+/** Stable, publisher-owned identity for a tool dependency. */
+export interface NgisToolDependencyReference {
+    namespace: string;
+    toolKey: string;
+    contractRange: string;
+}
+/** Optional structural contract that narrows a semantic dependency further. */
+export interface NgisToolDependencyRequiredContract {
+    inputs?: Record<string, string>;
+    outputs?: Record<string, string>;
+    parameters?: string[];
 }
+export interface NgisToolDependencyDeclaration {
+    /** Locally unique manifest key, used by plugin code at runtime. */
+    alias: string;
+    ref: NgisToolDependencyReference;
+    requiredContract?: NgisToolDependencyRequiredContract;
+}
+/** Resolver outcomes are intentionally specific enough to render an honest UI. */
+export type NgisToolDependencyUnavailableReason = "tool_missing" | "tool_disabled" | "tool_forbidden" | "tool_version_unavailable" | "tool_contract_incompatible" | "dependency_unavailable";
+export type NgisResolvedToolDependency = {
+    available: true;
+    toolId: string;
+    toolRevision: number;
+    contractVersion: string;
+    schemaFingerprint: string;
+} | {
+    available: false;
+    reason: NgisToolDependencyUnavailableReason;
+};
 export interface ExtensionInstallDto {
     extId: string;
     enabled: boolean;
@@ -267,6 +304,12 @@ export interface BootExtensionEntryDto {
     manifest: PackageManifestDto;
     bundleUrl: string;
     integrity: string;
+    /**
+     * Per-viewer resolution of `manifest.toolDependencies`. This is host data,
+     * not bundle configuration: `toolId` is deliberately never written back into
+     * the manifest or exposed as an authoring-time identifier.
+     */
+    dependencies?: Record<string, NgisResolvedToolDependency>;
     /**
      * The resolved version's declared scopes — a projection of
      * `manifest.permissions` (Stage 13 XB1), where an absent key and `[]` mean

package/dist/src/types/gis.d.ts

@@ -83,7 +83,7 @@ export type GisToolId = "draw-point" | "draw-line" | "draw-polygon" | "draw-rect
  * command catalog; host-only composite controls can ride on the rail without
  * becoming invocable map tools.
  */
-export type GisRailItemId = GisToolId | "multi-view" | "flow-field";
+export type GisRailItemId = GisToolId | "multi-view" | "smart-plotting";
 /** How a tool behaves when invoked from the rail. */
 export type GisToolKind = "mode" | "measure" | "action" | "dropdown";
 /** One-shot actions the rail fires on the map via the imperative handle

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@ngis/plugin-ui",
-  "version": "0.4.0",
-  "description": "Host-connected React components and flow bindings for NeoGIS plugin authors.",
-  "license": "Apache-2.0",
+  "version": "0.4.1",
+  "description": "Host-connected smart components for NGIS plugin authors (Stage 14, F14.14). Pickers, the generated ParamForm, run/task/result surfaces and <Flow> bindings. Consumed in-repo through the pnpm workspace; the backend tarball channel is deferred to Stage 15.",
+  "license": "UNLICENSED",
   "private": false,
   "type": "module",
-  "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -16,42 +15,12 @@
       "require": "./dist/index.cjs"
     }
   },
-  "files": [
-    "dist"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
   "peerDependencies": {
-    "@ngis/plugin-sdk": "^0.4.0",
-    "react": "^19.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@ngis/plugin-sdk": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    }
+    "@ngis/plugin-sdk": "0.4.1"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/GeoScenarioScripter/NeoGIS-Frontend.git",
-    "directory": "packages/plugin-ui"
-  },
-  "homepage": "https://github.com/GeoScenarioScripter/NeoGIS-Frontend#readme",
-  "bugs": {
-    "url": "https://github.com/GeoScenarioScripter/NeoGIS-Frontend/issues"
-  },
-  "keywords": [
-    "neogis",
-    "gis",
-    "plugin",
-    "react"
+  "files": [
+    "dist"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
   "scripts": {
     "build": "node scripts/build.mjs",
     "prepack": "npm run build"

package/LICENSE

@@ -1,13 +0,0 @@
-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

@@ -1,25 +0,0 @@
-# @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.