Victor Wiebe
ade2b10033
Some checks failed
Release production image / production-image (push) Has been cancelled
82 lines
3.7 KiB
Markdown
82 lines
3.7 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`, Dropdown `onChange` where supported, or page lifecycle event selects an `actionId`. A Button event may instead contain `navigateToPageId`; navigation is not represented as a REST action.
|
|
|
|
Before execution, request fields interpolate:
|
|
|
|
- `{{components.<name>.value}}` against components on the invoking page only.
|
|
- `{{variables.<name>}}` against global variables or page variables owned by the invoking 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 page-local. Response bindings execute in the invoking page context and may update components on that page, global variables, and page variables owned by that page. Cross-page component/page-variable writes are prohibited.
|
|
|
|
## 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.
|
|
- 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;
|
|
- page-variable ownership violations and cross-page references;
|
|
- 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.
|