@revenexx/studio-integrations 1.2.0 → 1.4.0

package/dist/runtime/pages/integrations/workflows/index.vue

@@ -3,15 +3,30 @@ import { AddCircle as Plus } from "#solar-icons";
 import { Button } from "@revenexx/studio";
 import WorkflowsTable from "../../../components/Integrations/WorkflowsTable.vue";
 import WorkflowCreateDialog from "../../../components/Integrations/WorkflowCreateDialog.vue";
+import { createBuildSettle, isBuildUnsettled } from "../../../utils/buildSettle";
 const t = useIntegrationsT();
 useHead({ title: () => t("integration.workflows.list.head.title") });
 const { workflows, loading, error, load } = useIntegrationsWorkflows();
-onMounted(() => {
-  void load();
+onMounted(async () => {
+  await load();
+  settleBuildStates();
+});
+let onScreen = true;
+const buildSettle = createBuildSettle();
+function settleBuildStates() {
+  if (!onScreen) return;
+  void buildSettle.settle({
+    unsettled: () => workflows.value.some((wf) => isBuildUnsettled(wf.buildStatus)),
+    read: () => load(true)
+  });
+}
+onUnmounted(() => {
+  onScreen = false;
+  buildSettle.stop();
 });
 const { buildTick } = useIntegrationsRealtime();
 watch(buildTick, () => {
-  void load(true);
+  void load(true).then(() => settleBuildStates());
 });
 const loadFailed = computed(() => !!error && !!error.value && !workflows.value.length);
 const createOpen = ref(false);
@@ -43,7 +58,11 @@ const createOpen = ref(false);
           </Button>
         </template>
       </StateCard>
-      <WorkflowsTable v-else :workflows="workflows" :loading="loading" />
+      <!-- `loading` is the composable's app-wide flag and goes up for every read, the
+           build watch's included — so passing it straight through would flip the table
+           between its skeleton and its empty text every few seconds while a build
+           runs. What the table's skeleton means is "nothing to show yet". -->
+      <WorkflowsTable v-else :workflows="workflows" :loading="loading && !workflows.length" />
     </div>
 
     <WorkflowCreateDialog v-model:open="createOpen" />

package/dist/runtime/types/integrations.d.ts

@@ -158,11 +158,28 @@ export interface WorkflowIcon {
     /** Image URL, e.g. a node-package logo (kind=image). */
     src?: string;
 }
+/** The four things a workflow can remember between runs (PO-374). */
+export type WorkflowStateRole = 'mapping' | 'cursor' | 'dedupe' | 'digest';
+/** `private` belongs to this workflow; `shared` is tenant-wide and outlives it. */
+export type WorkflowStateVisibility = 'private' | 'shared';
+/**
+ * One state namespace a workflow declares it may reach. The engine mints the
+ * run's grant from exactly this list, so an undeclared namespace is not
+ * undocumented — it is refused at run time.
+ */
+export interface WorkflowStateNamespace {
+    namespace: string;
+    role: WorkflowStateRole;
+    /** Absent means `private`, which is what the engine's schema defaults to. */
+    visibility?: WorkflowStateVisibility;
+}
 export interface WorkflowBlob {
     nodeManifestVersion: string;
     name: LocalizedString;
     description?: LocalizedString;
     variables?: Record<string, WorkflowVariable>;
+    /** State namespaces this workflow may reach at run time (BlobDef `state`). */
+    state?: WorkflowStateNamespace[];
     triggers: WorkflowTrigger[];
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
@@ -247,11 +264,25 @@ export interface NodeManifestOutput {
      *  publishes them. Author-time schema only, never live run data. */
     fields?: string[] | Record<string, unknown>;
 }
-export type ConfigFieldType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref' | 'dynamic-schema';
+export type ConfigFieldType = 'string' | 'number' | 'boolean' | 'select' | 'multiselect' | 'object' | 'array' | 'expression' | 'secret-ref' | 'credentials-ref'
+/** Names one of the workflow's declared state namespaces (PO-374). */
+ | 'state-ref' | 'dynamic-schema';
 export interface ConfigFieldOption {
     value: string | number | boolean;
     label: LocalizedString;
 }
+/** The comparison words a settings condition may use. One vocabulary with the
+ *  condition and filter nodes, so an author who has met these words in one
+ *  place does not learn a second set for the other. */
+export type SettingConditionOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'exists' | 'notExists' | 'isEmpty' | 'isNotEmpty';
+/** A condition on another setting's value, deciding whether this one applies. */
+export interface SettingCondition {
+    /** The `key` of another setting at the same level. */
+    key: string;
+    op: SettingConditionOperator;
+    /** Left out by the four operators that read presence rather than content. */
+    value?: string | number | boolean;
+}
 export interface ConfigField {
     key: string;
     label: LocalizedString;
@@ -278,8 +309,20 @@ export interface ConfigField {
      *  (e.g. 'revenexx:business-central'). An array lets a node accept more than
      *  one credential type; the picker merges the tenant's credentials across all. */
     credentialType?: string | string[];
+    /**
+     * Only for `type: 'state-ref'` (PO-374): which kind of state namespace the
+     * field accepts. The picker lists the workflow's declarations of that role;
+     * the stored value is the namespace NAME.
+     */
+    stateRole?: WorkflowStateRole;
     /** keys of other config fields this field's options/schema depend on. */
     dependsOn?: string[];
+    /** When this setting applies at all (PO-410): another setting's key, an
+     *  operator, and where the operator takes one, the value to compare against.
+     *  Drawn only while the condition holds — see utils/settingCondition. Not
+     *  `dependsOn`, which decides what a setting resolves to rather than whether
+     *  it is drawn. */
+    showIf?: SettingCondition;
     validation?: {
         pattern?: string;
         min?: number;

package/dist/runtime/utils/apiEnvelope.d.ts

@@ -0,0 +1,27 @@
+/**
+ * One record, from `{ data: record }` or from a bare record.
+ *
+ * Throws when the response carries an envelope with nothing in it, or no body at
+ * all — the case the old expression turned into an object with none of the
+ * caller's fields, which every page downstream drew as empty.
+ *
+ * **The thrown message is deliberately empty.** `errorReason(err, fallback)` in
+ * `apiError.ts` falls back to the caller's own translated sentence when the
+ * message is blank, so a shape violation surfaces as the page's ordinary "could
+ * not load this" copy rather than as an untranslated technical string in the UI.
+ * The response that caused it rides along in `body`.
+ */
+export declare function unwrapRecord<T>(res: unknown, ownFields?: readonly string[]): T;
+/**
+ * A list, from `{ data: [ … ] }` or from a bare array.
+ *
+ * An empty collection is `[]` or `{ "data": [] }` and answers empty. A body that is
+ * neither throws, for the same reason the record above does — and it was drafted the
+ * other way round, returning empty for anything unreadable, until a review pointed
+ * out what that costs: the workflows listing used to raise (`ingestList` mapped over
+ * the body and threw inside its own `try`), so an unreadable answer reached the
+ * reader as an error. Empty would have turned that into "no workflows yet" for a
+ * tenant whose workflows are all still there — a silent wrong answer in place of a
+ * loud one, in the change that exists to remove exactly that.
+ */
+export declare function unwrapList<T>(res: unknown): T[];

package/dist/runtime/utils/apiEnvelope.js

@@ -0,0 +1,20 @@
+import { IntegrationsApiError } from "./apiError.js";
+export function unwrapRecord(res, ownFields = []) {
+  if (res === null || res === void 0) {
+    throw new IntegrationsApiError(200, res, "");
+  }
+  if (typeof res === "object" && "data" in res && !ownFields.some((f) => f in res)) {
+    const data = res.data;
+    if (data === null || data === void 0) {
+      throw new IntegrationsApiError(200, res, "");
+    }
+    return data;
+  }
+  return res;
+}
+export function unwrapList(res) {
+  if (Array.isArray(res)) return res;
+  const data = res?.data;
+  if (Array.isArray(data)) return data;
+  throw new IntegrationsApiError(200, res, "");
+}

package/dist/runtime/utils/buildSettle.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Watching a queued bundle build out, on any surface that reports one.
+ *
+ * A save queues a build, and until the platform has finished it the workflow cannot
+ * run. Both surfaces that say so read the state off the workflow row — the editor's
+ * chip beside Save, the build column in the workflows list — so neither of them
+ * learns that a build finished unless the row is read again.
+ *
+ * Two things can make that happen. A realtime build report, which is the fast path
+ * and is not always there: the topics have no producer in every environment, the
+ * connection can be off for a tenant, and a socket can drop in the second after the
+ * save. And re-reading the row, which is this — the floor under the fast path, and
+ * the only one of the two that works everywhere today.
+ *
+ * The editor has had it since PO-398, where a chip that never cleared was reported
+ * as "saving does not work"; the list kept the same defect for as long as it had no
+ * loop of its own (PO-416). So the loop lives here rather than in either surface:
+ * one interval, one ceiling, and one rule about which call wins, for both.
+ *
+ * WHAT A CALLER SUPPLIES is what differs between the two surfaces, and it is only
+ * ever these two things: whether anything is still unsettled — one workflow in the
+ * editor, any row in the list — and how to read it again. `settle()` decides
+ * nothing about the answer; the caller's own state is what every surface renders
+ * from.
+ *
+ * A GENERATION RATHER THAN A BUSY FLAG. Two saves in quick succession must not
+ * leave the second one unwatched, and the earlier loop cannot be relied on to cover
+ * it: a read already in flight can land after the newer save and put the pre-save
+ * row back into the cache, after which the older loop reads `ready` and stops. So
+ * the newest call wins and every older loop retires at its next turn.
+ *
+ * THE CEILING is not a timeout in the usual sense — nothing is reported when it is
+ * reached. A build is seconds; a build still queued after five minutes is a state
+ * worth leaving on screen rather than asking about forever, and the operator's own
+ * reload starts a fresh watch (which is why arriving on an unsettled row starts one).
+ */
+/** Between reads. Same cadence the editor's queued-run wait uses. */
+export declare const BUILD_SETTLE_POLL_MS = 2500;
+/** After this, the state stands as last read and nothing asks again. */
+export declare const BUILD_SETTLE_TIMEOUT_MS: number;
+/**
+ * Whether a build state is one that changes on its own.
+ *
+ * `ready` and `failed` are where a build lands; anything else — including a row
+ * whose state the platform did not send — is nothing to wait for.
+ */
+export declare function isBuildUnsettled(status?: string | null): boolean;
+export interface BuildSettleWatch {
+    /** Whether anything is still worth waiting for. Read fresh on every turn. */
+    unsettled: () => boolean;
+    /** Reads the state again. Its own failures are its business — see below. */
+    read: () => Promise<unknown>;
+}
+export interface BuildSettleOptions {
+    pollMs?: number;
+    timeoutMs?: number;
+}
+export interface BuildSettle {
+    /**
+     * Reads until nothing is unsettled, or until the ceiling. Resolves either way and
+     * throws nothing: a read that fails leaves the state as it stands and the next
+     * turn tries again, which is the same answer a surface gives its reader anyway.
+     */
+    settle: (watch: BuildSettleWatch) => Promise<void>;
+    /** Retires whatever is watching — for a surface being left. */
+    stop: () => void;
+}
+export declare function createBuildSettle(options?: BuildSettleOptions): BuildSettle;

package/dist/runtime/utils/buildSettle.js

@@ -0,0 +1,29 @@
+export const BUILD_SETTLE_POLL_MS = 2500;
+export const BUILD_SETTLE_TIMEOUT_MS = 5 * 6e4;
+export function isBuildUnsettled(status) {
+  return status === "pending" || status === "building";
+}
+export function createBuildSettle(options = {}) {
+  const pollMs = options.pollMs ?? BUILD_SETTLE_POLL_MS;
+  const timeoutMs = options.timeoutMs ?? BUILD_SETTLE_TIMEOUT_MS;
+  let generation = 0;
+  return {
+    async settle({ unsettled, read }) {
+      const mine = ++generation;
+      const started = Date.now();
+      while (Date.now() - started < timeoutMs) {
+        if (mine !== generation) return;
+        if (!unsettled()) return;
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+        if (mine !== generation || !unsettled()) return;
+        try {
+          await read();
+        } catch {
+        }
+      }
+    },
+    stop() {
+      generation += 1;
+    }
+  };
+}

package/dist/runtime/utils/configDefaults.d.ts

@@ -0,0 +1,18 @@
+import type { ConfigField } from '../types/integrations.js';
+/**
+ * The config a set of settings starts life with: what each one declares as its
+ * default, and nothing else.
+ *
+ * A setting with no `default` is left OUT rather than written as an empty
+ * string, because the two are different answers. `''` is a value — the engine
+ * reads it, `??` does not replace it, and a node whose own default would have
+ * applied never gets to apply it. An absent key is the absence the node's
+ * default answers to.
+ *
+ * Used in the two places a fresh set of values is made: a node dropped on the
+ * canvas (WorkflowEditor), and a row added to a list setting (NodeConfigField).
+ * Flat on purpose — it reads `default` at the level it is given and does not
+ * descend into `properties` or `items`, so what a newly inserted node carries
+ * is exactly what it carried before this became shared.
+ */
+export declare function defaultsFor(fields?: ReadonlyArray<Pick<ConfigField, 'key' | 'default'>>): Record<string, unknown>;

package/dist/runtime/utils/configDefaults.js

@@ -0,0 +1,7 @@
+export function defaultsFor(fields = []) {
+  const out = {};
+  for (const f of fields ?? []) {
+    if (f.default !== void 0) out[f.key] = f.default;
+  }
+  return out;
+}

package/dist/runtime/utils/errorPathAdvice.d.ts

@@ -0,0 +1,60 @@
+import type { WorkflowBlob } from '../types/integrations.js';
+/**
+ * Nodes that route failures to an error output nothing is connected to
+ * (specs/workflow-advice.md).
+ *
+ * A step that fails on a path its author drew is handled. A step that fails on a
+ * path nobody drew is not: the engine ends the run there
+ * (`specs/node-failure-handling.md` AC-8 in the service repository), and before
+ * it did, the failure vanished and the run reported success. Either way the
+ * author never chose it — they simply never saw the port.
+ *
+ * ## Why this is advice and not a finding
+ *
+ * The backend's validation findings feed the activation gate AND an
+ * unconditional refusal to start a run. A finding here would therefore stop
+ * every workflow with an unwired error port from running at all — turning
+ * "delivers nothing quietly" into "does not start", for authors who never asked
+ * for either. Computing it in the editor makes that impossible rather than
+ * merely unlikely: there is no value for a blocking consumer to read.
+ *
+ * What the client cannot do is be authoritative — the catalogue may not be
+ * loaded, and a workflow built through the API never passes here at all. For
+ * advice that is the right trade; for a gate it would not be, which is why the
+ * gate stays where the manifests are.
+ *
+ * ## Deliberately not in `validationFindings.ts`
+ *
+ * Everything there is a backend finding addressed by blob path, and the node
+ * card counts those as *incomplete settings*. An unwired port is neither. Sent
+ * through `groupFindingsByNode` it would type-check perfectly and quietly
+ * corrupt two counts — the banner's and the card badge's.
+ */
+export interface ErrorPathAdvice {
+    /** Blob node id — not an index, so it survives a node being added or removed. */
+    nodeId: string;
+    /** The error output with nothing attached. */
+    port: string;
+}
+/**
+ * Every unwired error output in the blob, in node order.
+ *
+ * Runs against the blob the author is *editing*, not the saved one, so wiring a
+ * port clears its line in the same tick — no save, and no second copy of this
+ * rule to decide when the advice went stale.
+ *
+ * **Resolved against whichever manifest version the catalogue has.**
+ * `findManifest` falls back to another version of the same slug when the pinned
+ * one is absent, and that fallback is accepted here: a node pinned to a version
+ * nobody serves any more is better described by a sibling version than by
+ * silence. The cost is real though — where the versions disagree about their
+ * ports, the advice describes the sibling's, so a port could be named that the
+ * author's own node does not have.
+ *
+ * **Reads the manifest's static outputs only.** A node whose ports are named at
+ * author time (`sourceFromConfig` / `resolveOutputs`) cannot be judged from the
+ * declaration alone, so nothing is claimed about it — the same forbearance the
+ * engine shows. No shipped node has a dynamic error port today; if one appears,
+ * this is where it would silently escape notice.
+ */
+export declare function unwiredErrorPorts(blob: Pick<WorkflowBlob, 'nodes' | 'edges'>): ErrorPathAdvice[];

package/dist/runtime/utils/errorPathAdvice.js

@@ -0,0 +1,19 @@
+import { findManifest } from "../data/integrationNodeCatalog.js";
+export function unwiredErrorPorts(blob) {
+  const advice = [];
+  for (const node of blob.nodes) {
+    const manifest = findManifest(node.nodeSlug, node.nodeVersion);
+    if (!manifest) continue;
+    const errorPorts = (manifest.outputs ?? []).filter((o) => o.kind === "error" && o.name).map((o) => o.name);
+    if (!errorPorts.length) continue;
+    if (!isReachable(node, blob, errorPorts)) continue;
+    for (const port of errorPorts) {
+      const wired = blob.edges.some((e) => e.from.nodeId === node.id && e.from.output === port);
+      if (!wired) advice.push({ nodeId: node.id, port });
+    }
+  }
+  return advice;
+}
+function isReachable(node, blob, errorPorts) {
+  return blob.edges.some((e) => e.to.nodeId === node.id) || blob.edges.some((e) => e.from.nodeId === node.id && !errorPorts.includes(e.from.output));
+}

package/dist/runtime/utils/notify.d.ts

@@ -13,10 +13,10 @@ export declare const toast: ((message: string | (() => string | import("vue").Co
     custom: (component: import("vue").Component, data?: import("vue-sonner").ExternalToast) => string | number;
     message: (message: string | (() => string | import("vue").Component) | import("vue").Component, data?: import("vue-sonner").ExternalToast) => string | number;
     promise: <ToastData>(promise: Promise<ToastData> | (() => Promise<ToastData>), data?: ({
+        id?: number | string | undefined;
+        class?: string | undefined;
         action?: (import("vue-sonner").Action | import("vue").Component) | undefined;
         icon?: import("vue").Component | undefined;
-        class?: string | undefined;
-        id?: number | string | undefined;
         position?: ("top-left" | "top-right" | "bottom-left" | "bottom-right" | "top-center" | "bottom-center") | undefined;
         toasterId?: string | undefined;
         component?: import("vue").Component | undefined;

package/dist/runtime/utils/runEnvelope.d.ts

@@ -11,6 +11,13 @@ export type RunLike = Record<string, unknown>;
  * looks like a run (`status`, `temporal_run_id`) is the run, whatever else it has
  * on it.
  *
+ * The two guards are `RUN_OWN_FIELDS`, exported because `unwrapRecord` reads the
+ * same endpoint from `useIntegrationsRuns.ts` and has to apply the same rule —
+ * one list, two readers, rather than the two literals that used to sit here
+ * (PO-394). What stays different is deliberate: this one answers `null` where
+ * `unwrapRecord` throws, because a caller following a run has to count an
+ * unusable answer as a failed read rather than have it raised at it.
+ *
  * This is deliberately generous about the *rest* of the shape. It answers "where
  * is the run in this body", not "is this a usable run" — the caller decides that,
  * because a caller following a run has to be able to count an unusable answer as
@@ -28,4 +35,9 @@ export declare const RUN_TERMINAL: Set<string>;
 export declare function isTerminalRun(run: {
     status?: unknown;
 } | null | undefined): boolean;
+/**
+ * The fields that mark a body as the run itself rather than an envelope around
+ * one. A run carrying its own `data` field would otherwise be unwrapped into it.
+ */
+export declare const RUN_OWN_FIELDS: readonly ["status", "temporal_run_id"];
 export declare function unwrapRun(res: unknown): RunLike | null;

package/dist/runtime/utils/runEnvelope.js

@@ -2,10 +2,11 @@ export const RUN_TERMINAL = /* @__PURE__ */ new Set(["completed", "failed", "can
 export function isTerminalRun(run) {
   return RUN_TERMINAL.has(String(run?.status ?? "").toLowerCase());
 }
+export const RUN_OWN_FIELDS = ["status", "temporal_run_id"];
 export function unwrapRun(res) {
   if (!res || typeof res !== "object") return null;
   const o = res;
-  if ("data" in o && o.data && typeof o.data === "object" && !("status" in o) && !("temporal_run_id" in o)) {
+  if ("data" in o && o.data && typeof o.data === "object" && !RUN_OWN_FIELDS.some((f) => f in o)) {
     return o.data;
   }
   return o;

package/dist/runtime/utils/selectOptions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Carrying a node's declared options through a select that reserves the empty
+ * string for "nothing chosen".
+ *
+ * "No choice" is a legitimate thing for a node to offer — "as the file came in",
+ * "unchanged", "all kinds" — and three node types in two packages arrived at the
+ * same way of writing it: an option with an empty value. The select underneath
+ * this UI refuses it: the empty string is how it says nothing is selected, so an
+ * item may not also carry it. Handed one anyway it throws while the list mounts,
+ * and takes the surrounding dialog's dismissal machinery down with it — nothing
+ * opened afterwards could be closed again.
+ *
+ * So every option value is carried under a substitute and swapped back on the way
+ * out. **Every** one, rather than only the empty value: a sentinel that stood
+ * beside untouched values would be a value a node could declare itself, and
+ * declaring it would silently store the empty string instead. Here a declared
+ * value always arrives prefixed and the empty one never is, so the two cannot
+ * collide whatever a node writes. What the node reads is unchanged.
+ */
+/** What the option meaning "no choice" is carried under. */
+export declare const EMPTY_OPTION_VALUE = "option-empty";
+/** Does this list of options ask for the substitute at all? */
+export declare function hasEmptyOption(options: Array<{
+    value: unknown;
+}> | undefined): boolean;
+/**
+ * An option's value as the select may receive it. That is the guard: the item
+ * component cannot be handed an empty value from here, whatever a node declares.
+ */
+export declare function toItemValue(value: unknown): string;
+/**
+ * The stored value as the select's model — encoded the way the items are, or it
+ * matches none of them and the trigger falls back to its placeholder.
+ *
+ * `null` is read as the empty option alongside the empty string, because that is
+ * what the platform hands back for one: Laravel converts an empty string to null
+ * anywhere in a request body, so the value chosen here returns as null on the next
+ * open and the choice would otherwise be gone. A setting with no value at all is
+ * not: nothing is stored for it, and a trigger claiming a choice the config does
+ * not hold would be the placeholder's lie in the other direction. A node that
+ * offers "no choice" declares it as the field's default, so a step placed on the
+ * canvas has the empty string from the start.
+ */
+export declare function toModelValue(value: unknown, options: Array<{
+    value: unknown;
+}> | undefined): string;
+/** What the select hands back, as the node wants it stored. */
+export declare function fromModelValue(value: string): string;

package/dist/runtime/utils/selectOptions.js

@@ -0,0 +1,19 @@
+const OPTION_VALUE_PREFIX = "option:";
+export const EMPTY_OPTION_VALUE = "option-empty";
+export function hasEmptyOption(options) {
+  return (options ?? []).some((o) => String(o.value) === "");
+}
+export function toItemValue(value) {
+  const s = String(value);
+  return s === "" ? EMPTY_OPTION_VALUE : OPTION_VALUE_PREFIX + s;
+}
+export function toModelValue(value, options) {
+  if (value === "" || value === null || value === void 0) {
+    return value !== void 0 && hasEmptyOption(options) ? EMPTY_OPTION_VALUE : "";
+  }
+  return OPTION_VALUE_PREFIX + String(value);
+}
+export function fromModelValue(value) {
+  if (value === EMPTY_OPTION_VALUE) return "";
+  return value.startsWith(OPTION_VALUE_PREFIX) ? value.slice(OPTION_VALUE_PREFIX.length) : value;
+}

package/dist/runtime/utils/settingCondition.d.ts

@@ -0,0 +1,48 @@
+import type { ConfigField, SettingConditionOperator } from '../types/integrations.js';
+/**
+ * What an operator means. Mirrors the SDK's `evaluate` row for row, including
+ * the leniency of `equals` across the string/number line: a select carries `1`
+ * where a text box carries `'1'`, and an author means one thing by both.
+ */
+export declare function evaluateOperator(left: unknown, op: SettingConditionOperator, right: unknown): boolean;
+/**
+ * Whether one setting applies, given the values at its own level — inside a
+ * group, the siblings in that group, which is where the node wrote the
+ * condition and where the platform resolves it.
+ *
+ * A setting with no condition always applies, and so does one whose condition
+ * is malformed: whatever the node meant, an author is better off seeing a field
+ * than having it silently withheld.
+ */
+export declare function settingApplies(field: Pick<ConfigField, 'showIf'>, values: Record<string, unknown>): boolean;
+/**
+ * Whether a change to `changedKey` leaves this setting's value stale.
+ *
+ * Two reasons a setting can depend on another, and they do not go stale at the
+ * same moment. `dependsOn` names what a dynamic field resolves its options
+ * from, and any change to it invalidates what was chosen out of the old
+ * options. A condition names the setting that decides whether the field is
+ * drawn at all, and what was typed only becomes unreachable when the condition
+ * stops holding: while it still holds the field is on screen, and clearing it
+ * on every keystroke in the setting it reads would empty a field the author is
+ * looking at — `showIf: { key: 'url', op: 'isNotEmpty' }` stays true from the
+ * first character on.
+ */
+export declare function valueGoesStale(field: Pick<ConfigField, 'dependsOn' | 'showIf'>, changedKey: string, values: Record<string, unknown>): boolean;
+/**
+ * The settings of one level whose values are stale once `changedKey` has been
+ * set — the cascade, walked to a fixpoint over that level's own fields.
+ *
+ * `after` is the config as it stands *after* the write, because a condition is
+ * read against it: whether a setting still applies is the whole question for a
+ * `showIf` dependant. Each cleared key is taken out of that config as the walk
+ * goes, so a setting withdrawn by a clearing is found in the same pass.
+ *
+ * The setting being written is never cleared, which is also what guards a
+ * cyclic `dependsOn`.
+ */
+export declare function staleKeys(fields: Pick<ConfigField, 'key' | 'dependsOn' | 'showIf'>[], changedKey: string, after: Record<string, unknown>): Set<string>;
+/**
+ * The settings of a level that apply, in the order the node declared them.
+ */
+export declare function applyingFields(fields: ConfigField[], values: Record<string, unknown>): ConfigField[];

package/dist/runtime/utils/settingCondition.js

@@ -0,0 +1,84 @@
+const READS_PRESENCE = ["exists", "notExists", "isEmpty", "isNotEmpty"];
+const OPERATORS = [
+  "equals",
+  "notEquals",
+  "contains",
+  "notContains",
+  "startsWith",
+  "endsWith",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  ...READS_PRESENCE
+];
+export function evaluateOperator(left, op, right) {
+  switch (op) {
+    case "exists":
+      return left !== void 0 && left !== null;
+    case "notExists":
+      return left === void 0 || left === null;
+    case "isEmpty":
+      return left === "" || left === null || left === void 0 || Array.isArray(left) && left.length === 0;
+    case "isNotEmpty":
+      return !evaluateOperator(left, "isEmpty", right);
+    case "equals":
+      return String(left) === String(right);
+    case "notEquals":
+      return String(left) !== String(right);
+    case "contains":
+      return typeof left === "string" && left.includes(String(right));
+    case "notContains":
+      return typeof left === "string" && !left.includes(String(right));
+    case "startsWith":
+      return typeof left === "string" && left.startsWith(String(right));
+    case "endsWith":
+      return typeof left === "string" && left.endsWith(String(right));
+    case "greaterThan":
+      return Number(left) > Number(right);
+    case "greaterThanOrEqual":
+      return Number(left) >= Number(right);
+    case "lessThan":
+      return Number(left) < Number(right);
+    case "lessThanOrEqual":
+      return Number(left) <= Number(right);
+    default: {
+      const unhandled = op;
+      void unhandled;
+      return false;
+    }
+  }
+}
+export function settingApplies(field, values) {
+  const condition = field.showIf;
+  if (!condition || typeof condition !== "object")
+    return true;
+  const { key, op } = condition;
+  if (typeof key !== "string" || !OPERATORS.includes(op))
+    return true;
+  return evaluateOperator(values[key], op, condition.value);
+}
+export function valueGoesStale(field, changedKey, values) {
+  if ((field.dependsOn ?? []).includes(changedKey))
+    return true;
+  return field.showIf?.key === changedKey && !settingApplies(field, values);
+}
+export function staleKeys(fields, changedKey, after) {
+  const remaining = { ...after };
+  const out = /* @__PURE__ */ new Set();
+  const queue = [changedKey];
+  while (queue.length > 0) {
+    const dep = queue.shift();
+    for (const f of fields) {
+      if (f.key === changedKey || out.has(f.key)) continue;
+      if (!valueGoesStale(f, dep, remaining)) continue;
+      out.add(f.key);
+      delete remaining[f.key];
+      queue.push(f.key);
+    }
+  }
+  return out;
+}
+export function applyingFields(fields, values) {
+  return fields.filter((field) => settingApplies(field, values));
+}