@ngis/plugin-ui 0.4.0

package/dist/src/components/plugin-ui/w3-contracts.d.ts

@@ -0,0 +1,328 @@
+/**
+ * W3 shared contracts — authored at the **W3 kickoff**, read-only to Y5a and Y5b.
+ *
+ * Stage 14's wave rule, third application: every surface read by more than one
+ * session is frozen here so neither agent coordinates live with a sibling. W3
+ * splits the flow engine at the seam the stage has used twice already — pure
+ * model versus React — so:
+ *
+ *   Y5a owns `flow-model.ts`: the registry's data model, binding resolution,
+ *          satisfaction, {@link ngisTypeVerdict}, reasons, disclosure, snapshot.
+ *   Y5b owns `Flow.tsx` + the eleven components' port declarations + the
+ *          inspector: everything that needs React, a DOM or a host.
+ *
+ * The seam is exactly four things, all frozen below:
+ *
+ *   1. what a node *is*                       ({@link NgisFlowNode})
+ *   2. how a bound input is spelled            ({@link NgisInputBinding})
+ *   3. what a resolution *answers*             ({@link NgisPortResolution})
+ *   4. what a disabled control renders          ({@link NgisFlowReason})
+ *
+ * Nothing here is a component. Nothing here imports React. Nothing here reads a
+ * host. That is what lets Y5a assert every behaviour F14.10 pins without a DOM,
+ * and what keeps `<Flow>` **host-renderable from declarative data** — the
+ * property Stage 15's worker tier depends on and that a scope holding React
+ * state in its contract would quietly destroy.
+ *
+ * **This module is deliberately not re-exported from either barrel**, exactly as
+ * `w2-contracts.ts` is not: consumers import it by relative path. The public
+ * names on F14.14's frozen export table (`NgisPortSpec`, `NgisPortKind`,
+ * `NgisPortDirection`, `ngisTypeVerdict`, `NgisTypeVerdict`) are re-exported by
+ * Y5a's `flow-model.ts`, and the barrels take them from there — so the seam
+ * stays a wave artifact and the package surface stays one file's responsibility.
+ *
+ * Contract: F14.1 (type verdict), F14.4 (value forms, reference forms, reserved
+ * members), F14.5 (port model), F14.10 (enablement, reasons, disclosure), F14.11
+ * (the bare-key publication). Three kickoff corrections to that text are marked
+ * **KICKOFF CORRECTION** where they occur; each is recorded in the stage README's
+ * Decisions table and none changes an F14 clause's intent.
+ */
+import type { NgisDataType, NgisTaskOutput } from "../../sdk/facets/types";
+import type { NgisUiSchemaValueType } from "../../types/analysis";
+import type { NgisParamValue } from "./w2-contracts";
+export type NgisPortDirection = "in" | "out";
+export type NgisPortKind = "resource" | "resources" | "field" | "extent" | "task" | "value" | "record";
+/**
+ * F14.5's port spec, verbatim but for one clarification.
+ *
+ * **KICKOFF CORRECTION 1 — `id` is unique within its *node*, not its scope.**
+ * F14.5 says "unique within the enclosing `<Flow>` scope", but its own
+ * per-component table gives four different components an out port called
+ * `value` and four an in port called `taskId`, and F14.4 addresses a member as
+ * `"@<nodeId>.<member>"`. Scope-unique port ids would make F14.5 and F14.4
+ * contradict each other in the first two-picker flow anyone writes. The frozen
+ * model: a component's `id` prop is the **node** id and is scope-unique; a port
+ * id is a **member name** and is unique within its node; the scope-unique
+ * identity is the pair, spelled by {@link ngisPortRef}. `NGIS_W2_PORT_IDS`
+ * (`w2-contracts.ts`) is exactly the reserved member vocabulary, unchanged.
+ */
+export interface NgisPortSpec {
+    /** Member name, unique within the node. See KICKOFF CORRECTION 1. */
+    readonly id: string;
+    readonly direction: NgisPortDirection;
+    readonly kind: NgisPortKind;
+    /** The generated-reason text source (F14.10). Never a message key — a literal
+     *  string or the UI schema's `label`. Plugin strings are literal (F13.11). */
+    readonly label: string;
+    readonly required: boolean;
+    /** kinds "resource" | "resources" only. Empty or absent ⇒ any type. */
+    readonly dataTypes?: readonly NgisDataType[];
+    /** kind "value" only. */
+    readonly valueType?: NgisUiSchemaValueType;
+    /** kind "field" only — the id of the **sibling in-port on this same node**
+     *  that carries the parent resource (QGIS `parentLayerParameterName`). For
+     *  `FieldSelect` that is `"parent"`, per F14.5's own component table; the
+     *  parent's *value* arrives through that in-port's binding, so there is one
+     *  resolution path and not two. */
+    readonly parentPortId?: string;
+}
+/** The scope-unique spelling of a port: `<nodeId>.<portId>`. */
+export declare function ngisPortRef(nodeId: string, portId: string): string;
+/**
+ * A node in a flow scope: one smart component's declaration, as the registry
+ * holds it. Registration is **last-wins on `id` within a scope**, and a
+ * duplicate id is a development-mode error, never a silent overwrite (F14.5).
+ */
+export interface NgisFlowNode {
+    readonly id: string;
+    /** The `data-slot` the component renders, from `NGIS_W2_DATA_SLOTS` or
+     *  `NGIS_W3_DATA_SLOTS`. The registry's only knowledge of *what* a node is —
+     *  the engine never branches on a component identity beyond this. */
+    readonly slot: string;
+    readonly ports: readonly NgisPortSpec[];
+    /** Bindings for this node's in-ports, keyed by in-port member name, plus any
+     *  number of spread directives (see {@link ngisFlowSpread}). */
+    readonly inputs: Readonly<Record<string, NgisInputBinding>>;
+    /**
+     * **W4 KICKOFF ADDITION (YD49).** The tool this node runs, when it runs one.
+     * Absent for the nine components that run none.
+     *
+     * Added here rather than in `w4-contracts.ts` because it is a *member of this
+     * type* and the alternative is a circular import. **The engine still never
+     * reads it** — `resolveFlow` ignores it entirely, exactly as it ignores
+     * everything about a component beyond `slot`; it rides the snapshot for Y6 and
+     * Y7, which is the whole reason it exists. See `NgisFlowNodeConfig`.
+     */
+    readonly config?: NgisFlowNodeConfig;
+}
+/**
+ * **W4 KICKOFF ADDITION (YD49).** The tool a node runs, and the version it was
+ * authored against.
+ *
+ * The W3 snapshot could not express F14.6's recipe nodes or F14.21's batch
+ * config: neither `toolId` nor `toolVersion` appears anywhere in the snapshot
+ * graph, while both clauses require both fields. The information was already in
+ * scope at the declaration sites — `paramFormPorts` and `runButtonPorts` each
+ * take the full `NgisToolUiSchema`, which carries `tool_id` and `tool_version` —
+ * and simply had no channel into the node. This is that channel.
+ *
+ * Rationale, the correction it answers and the caveat on `toolVersion` (the
+ * server **re-pins** it at publish) are recorded in full at
+ * `w4-contracts.ts` → `NgisFlowNodeConfig`, which re-exports this type so W4's
+ * sessions read it from their own seam.
+ */
+export interface NgisFlowNodeConfig {
+    readonly toolId: string;
+    /** `NgisToolUiSchema.tool_version` at authoring time. Advisory once published. */
+    readonly toolVersion: number;
+}
+/**
+ * A reference to another node's output (F14.4 form 4).
+ *
+ * The template literal buys a real check where the argument type is *only* a
+ * reference — {@link ngisFlowSpread} rejects `"opts"` at compile time. It buys
+ * **nothing** inside {@link NgisInputBinding}, and the honest reason is worth
+ * writing down rather than discovering: form 1 is any JSON literal, so `string`
+ * is already in that union and `` `@${string}` `` collapses into it. A bare
+ * `"dem"` where `"@dem"` was meant is a legal *static string*, not a type error,
+ * and no type can tell them apart. The `@` sigil is a runtime discrimination.
+ */
+export type NgisFlowRef = `@${string}`;
+/** F14.4's four value forms, and nothing else. */
+export type NgisInputBinding = NgisParamValue | {
+    readonly $context: string;
+} | {
+    readonly $input: string;
+} | NgisFlowRef;
+/**
+ * **KICKOFF CORRECTION 3 — a static string starting with `@` needs an escape.**
+ *
+ * F14.4 gives `@` no escape, so a legitimate static value like an email-shaped
+ * string or a `@`-prefixed layer name is indistinguishable from a reference and
+ * would resolve as a broken one. The frozen rule mirrors F14.8's `$$`, which is
+ * already the precedent in this package: **`"@@"` opens a literal**, and
+ * `parseNgisBinding` yields the string with one `@` removed. Only a value
+ * matching `/^@[^@]/` (or the bare `"@"`) is a reference. Additive; no existing
+ * spelling changes meaning.
+ */
+export declare function isNgisFlowRef(value: NgisInputBinding): value is NgisFlowRef;
+/** Unescapes a static string that opened with `"@@"`. Identity otherwise. */
+export declare function unescapeNgisStatic(value: string): string;
+/** The reserved key prefix {@link ngisFlowSpread} mints. No in-port member name
+ *  may start with it — a UI-schema param name cannot contain `.` at all. */
+export declare const NGIS_FLOW_SPREAD_PREFIX = "...";
+/**
+ * **KICKOFF CORRECTION 2 — the record spread needs a spelling, and F14.4's is
+ * not valid JavaScript.**
+ *
+ * F14.4 and F14.22 write the spread as `inputs={{ ELEV: "@dem", ..."@opts" }}`.
+ * Spreading a *string* into an object literal is legal JS with a meaning nobody
+ * wants: it spreads the string's indices, so `{..."@opts"}` is
+ * `{"0":"@","1":"o","2":"p","3":"t","4":"s"}`. Worse, that typechecks against
+ * `Record<string, NgisInputBinding>` — every character is a `string` — so the
+ * form fails **silently**, at runtime, as five bogus inputs. It cannot ship as
+ * written and the resolver must not try to detect the character-indexed shape.
+ *
+ * The frozen spelling keeps the `...` at the call site and is a real object
+ * spread of a real object:
+ *
+ * ```tsx
+ * <RunButton id="run" toolId={FLOOD_TOOL_ID}
+ *            inputs={{ ELEV: "@dem", RAIN: "@rain", ...ngisFlowSpread("@opts") }} />
+ * ```
+ *
+ * Distinct references produce distinct keys, so two spreads compose; the same
+ * reference twice collapses, which is idempotent rather than an error. F14.4's
+ * two spread rules are unchanged and are Y5a's to enforce at resolution: the
+ * source port's kind must be `record`, and **two spreads contributing the same
+ * record key is an error**, with later explicit keys winning over spread keys.
+ *
+ * F14.22's snippet still shows the old form; correcting it is a W5 input handed
+ * to Y8, not a silent edit here.
+ */
+export declare function ngisFlowSpread(ref: NgisFlowRef): Readonly<Record<string, NgisInputBinding>>;
+/** Whether an `inputs` key is a spread directive rather than an in-port name. */
+export declare function isNgisFlowSpreadKey(key: string): boolean;
+/**
+ * F14.4's reserved members of a `task` reference, which win over any output
+ * name. A tool whose output parameter collides is addressed as
+ * `"@run.outputs.<name>"`.
+ */
+export declare const NGIS_TASK_REF_MEMBERS: readonly ["taskId", "status", "stage", "outputs"];
+export type NgisTaskRefMember = (typeof NGIS_TASK_REF_MEMBERS)[number];
+/**
+ * What binding resolution answers for one in-port. Three states and not two:
+ * "unsatisfied because the user has not chosen yet" and "unsatisfied because an
+ * upstream node has not produced yet" are the same *value* and different
+ * *renderings* (F14.10's `blocked` vs `pending`), so the resolver must
+ * distinguish them and a boolean cannot.
+ */
+export type NgisPortResolution = {
+    readonly state: "satisfied";
+    readonly value: NgisResolvedValue;
+} | {
+    readonly state: "unsatisfied";
+    readonly awaiting: "user" | "upstream";
+} | {
+    readonly state: "invalid";
+    readonly reason: NgisFlowReason;
+};
+/**
+ * The value forms a port can carry, by kind. `record` is flat by F14.5 — a
+ * nested record is not expressible and must not be invented, because F14.6's
+ * recipe `params` are flat and a nested one would not serialize.
+ */
+export type NgisResolvedValue = string | number | boolean | readonly string[] | readonly [number, number, number, number] | Readonly<Record<string, string | number | boolean>> | NgisTaskRefValue;
+/** What a `task` port carries: F14.4's reserved members, resolved. */
+export interface NgisTaskRefValue {
+    readonly taskId: string;
+    readonly status: string;
+    readonly stage: string | null;
+    readonly outputs: readonly NgisTaskOutput[];
+}
+/**
+ * **Unbound is one predicate, in one place.** F14.10: absent, `null`, `""` and
+ * `[]` are all unbound, never "bound to empty". Both sessions need this and a
+ * second copy would be the W2 `toWireParams` lesson repeated — a satisfaction
+ * check that disagrees with a render check is a control that is enabled and
+ * refuses.
+ */
+export declare function isNgisUnbound(value: unknown): boolean;
+export type NgisTypeVerdict = "pass" | "warn" | "fail";
+/**
+ * F14.1's client-side binding check, mirroring `ValidateToolBindings` and
+ * `WorkflowTypeCheckService` together. `"warn"` never blocks a run; `"fail"`
+ * blocks it with a generated reason (F14.10).
+ *
+ * Frozen here rather than in `flow-model.ts` because Y5b's port declarations
+ * need the same verdict a resolution reports, and because the `file` wildcard
+ * is bidirectional — the asymmetric reading (only `expected === "file"` widens)
+ * is the plausible wrong implementation.
+ */
+export declare function ngisTypeVerdict(expected: NgisDataType, actual: NgisDataType): NgisTypeVerdict;
+/**
+ * F14.10's three disclosure states, frozen. `pending` is the only one that
+ * dims; `blocked` renders normally with the action disabled.
+ */
+export type NgisDisclosureState = "ready" | "blocked" | "pending";
+/**
+ * A generated reason, as **data**. Y5a produces it, Y5b renders it — which is
+ * why it carries a message key and its placeholders rather than a string: a
+ * pure model cannot hold a `useTranslations`, and F14.10 requires the reason to
+ * be generated, never authored. The three keys are F14.10's, spelled verbatim,
+ * and the kickoff seeds them in both locales so neither session invents a
+ * fourth.
+ */
+export type NgisFlowReason = {
+    readonly key: "GIS.flow.reason.unsatisfied";
+    readonly label: string;
+    /** Count of *further* unsatisfied required ports; `0` ⇒ no `.more` suffix. */
+    readonly more: number;
+} | {
+    readonly key: "GIS.flow.reason.typeMismatch";
+    readonly label: string;
+    readonly expected: NgisDataType;
+    readonly actual: NgisDataType;
+};
+export declare const NGIS_FLOW_REASON_KEYS: readonly ["GIS.flow.reason.unsatisfied", "GIS.flow.reason.more", "GIS.flow.reason.typeMismatch"];
+/**
+ * A node's derived enablement — F14.10 in one shape. `enabled` is
+ * `disclosure === "ready"`; both are carried because the render needs the
+ * state and the control needs the boolean, and deriving one from the other at
+ * two call sites is how they drift.
+ */
+export interface NgisNodeEnablement {
+    readonly nodeId: string;
+    readonly enabled: boolean;
+    readonly disclosure: NgisDisclosureState;
+    /** `null` iff `enabled`. The **first** unsatisfied required port in
+     *  declaration order, per F14.10 — ordering is declaration order and is
+     *  fully deterministic. */
+    readonly reason: NgisFlowReason | null;
+}
+/**
+ * What `<Flow>` hands Y6, and the whole of it. Deliberately the *graph as
+ * declared* and not a recipe: F14.6 owns the recipe schema, and a snapshot that
+ * pre-shaped itself into recipe fields would put half of Y6's mapping in W3
+ * where no clause authorizes it. Y6 derives promoted inputs, node `params` and
+ * the `{graph,view}` envelope from this; W3 promises only that everything
+ * needed to do so is present and that the shape is stable.
+ */
+export interface NgisFlowSnapshot {
+    readonly nodes: readonly NgisFlowNode[];
+    /** Resolutions at snapshot time, keyed by {@link ngisPortRef}. A saved recipe
+     *  keeps bindings, not values — but Y6 needs the resolved side to decide
+     *  which inputs *can* promote, and Y7's batch table needs it per row. */
+    readonly resolved: Readonly<Record<string, NgisPortResolution>>;
+}
+/**
+ * W3's `data-slot` additions. The eight W2 names stay in `w2-contracts.ts`;
+ * these two extend the same table, and the same rule applies — a duplicate
+ * makes `first-party-plugins/scripts/verify-externals.mjs`'s plugin-ui
+ * fingerprint ambiguous.
+ */
+export declare const NGIS_W3_DATA_SLOTS: {
+    readonly flow: "ngis-flow";
+    readonly flowInspector: "ngis-flow-inspector";
+};
+/**
+ * The DOM attributes a node's ports render, already in use by W2's three
+ * `data-port-*` sites (`RunButton`, `TaskStatus`, `TaskList`). Frozen because
+ * the inspector and the harness both read them, and because they are the only
+ * way an e2e spec can see a port at all.
+ */
+export declare const NGIS_PORT_ATTRIBUTES: {
+    readonly in: "data-port-in";
+    readonly out: "data-port-out";
+    readonly node: "data-flow-node";
+};