Canonical Response Mapping and Runtime Model

Ownership

New response mappings are top-level project.bindings. The legacy action.responseMapping field remains schema-compatible but is not executed and must not be authored by new UI/examples.

{
  "id": "binding_inventory",
  "source": "actions.loadInventory.response.body.items",
  "target": "components.inventoryTable.rows",
  "trigger": "onSuccess"
}

Action execution

Actions are project-level and reusable. A Button onClick or page lifecycle event selects an actionId. A Button event may instead contain navigateToPageId; navigation is not represented as a REST action. Table row selection drives onChange data bindings rather than executing an action directly.

Before execution, request fields interpolate:

{{components.<name>.value}} against components on the invoking page only.
{{variables.<name>}} against the project's runtime-variable map. Page scope records intended ownership, but v1.0.0 does not enforce that ownership across every runtime reference; authors must keep page variables on their declared page.

Credential-backed authentication is resolved by the backend through opaque secretReferenceId. Browser clients never supply authoritative URLs, authentication modes, actions, or secret values for published execution.

Response source paths

Canonical action sources begin with:

actions.<actionId>.response
actions.<actionId>.response.body
actions.<actionId>.response.body.<dot-separated-field>

The current resolver supports ordinary dot-separated object traversal. JSONPath filters, wildcards, quoted dotted keys, and transform expressions are deferred.

Targets

Supported action-response targets are validated against component type/property compatibility:

components.<name>.value
components.<dropdownName>.options
components.<tableName>.rows
variables.<name>

Component names are validated within a page, but binding paths do not contain a page ID. The current runtime requires a component target name to resolve unambiguously across the project and skips a binding when several pages reuse that name. A same-named Table on multiple pages can also activate the same selection binding. Use project-wide unique component names. Keep page-variable targets on their owning page; cross-page response flows are not a supported authoring pattern, although that variable-scope boundary is not fully diagnosed or enforced in v1.0.0.

Triggers

onSuccess is the canonical trigger for an action response and runs only when ProxyResponse.ok is true.
Legacy action-response onClick is accepted for compatibility and should be migrated to onSuccess.
Table components.<name>.selectedRow bindings use onChange.
onError, action chaining, and arbitrary reactive component graphs are deferred.

Runtime state

Configured defaults remain in canonical project JSON. Preview/published component, action, and variable values live in ephemeral runtime state and never mutate the canonical document. Global and page values survive in-session page navigation and reset on full reload.

Actions expose loading, success, upstream failure, network/policy failure, and mapping failure states. Mapped components receive loading/error state while requests run. When a successful action has no mapping, the triggering control surfaces the response for operator feedback.

Lifecycle

Page onLoad runs on the first entry to that page during one loaded runtime session.
If no onLoad event is configured, onEnter is the first-entry fallback.
Page onEnter runs when returning to a previously visited page.
Reopening/reloading the runtime begins a fresh session.

Diagnostics

Validation rejects or warns about:

dangling action, binding, page, component, variable, and secret references;
unsupported trigger/source/target combinations;
duplicate page/component identities in their required scopes;
malformed templates and unsupported component template properties;
a page-scoped variable whose declared owner page does not exist;
incompatible response target properties;
deprecated action.responseMapping and inert inputMap compatibility fields.

The backend performs schema and semantic validation before persistence/publication. The frontend shows the same actionable paths without replacing the last valid project state.

4.3 KiB Raw Permalink Blame History