Victor Wiebe
498003f83d
Some checks failed
Release production image / production-image (push) Has been cancelled
83 lines
4.3 KiB
Markdown
83 lines
4.3 KiB
Markdown
# 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.
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```text
|
|
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.
|