NIB / DOCUMENTATION
Actions and host policy — NibGenUI
Register capabilities in the host and authorize side effects again on the server.
Open interactive viewRegister an action by name
Button actions use an event name. The runtime resolves that name against the host actions map. The wire cannot carry a callback or executable Dart code. actionContextPaths permits exact context key and data path pairs; an unresolved allowed path blocks dispatch.
Buttons with an unresolved child also cannot dispatch. This prevents a partially built surface from sending an action before its visible label arrives.
final runtime = NibRuntime(
catalogs: [NibCatalog.basic()],
actions: {
'submit': (event) {
final name = event.context['name'];
if (name is String) debugPrint('Local submit accepted');
},
},
actionContextPaths: {'submit': {'name': '/user/name'}},
actionGuards: {
'submit': (event) {
final name = event.context['name'];
return name is String && name.trim().isNotEmpty;
},
},
);| API | Type | Default | Behavior |
|---|---|---|---|
| actions | Map<String, NibActionHandler> | {} | Host callback allowlist by exact event name. |
| actionContextPaths | Map<String, Map<String, String>> | {} | Permitted context keys and paths per action. |
| actionGuards | Map<String, NibActionGuard> | {} | Optional check at dispatch time; false blocks the handler. |
| dispatch(surfaceId, nodeId) | NibApplyResult | — | Validates the current node and context before host callback. |
Observe rejection before adding side effects
Use the local demo to compare the two outcomes: Say hello rejects an empty name and accepts a nonempty name. The actionDecisions stream tells the host that validation failed without copying the name into the diagnostic. Subscribe once, turn relevant codes into useful feedback, and cancel the subscription with the session. Avoid reporting every streamed update as a new notification.
For a confirmation flow, keep a pending request in host state. After the user confirms, re-read the live surface and current permissions before executing. The surface may have been deleted, its button replaced or the form edited while the dialog was open. A decision based solely on the original snapshot can act on stale data. The package exposes the pieces for these checks; it does not infer which business actions require them.
Suppress repeated activation while one operation is pending and design retry semantics before wiring a network handler. A timeout can occur after a server accepted work, so retrying the same operation may require a server-issued or host-managed idempotency key. The experimental client has no production backend or built-in exactly-once guarantee. A synthetic confirmation demo can verify client transitions only.
Finally distinguish three outcomes in your UI: the runtime allowed dispatch, the HTTP endpoint accepted the request, and the business operation completed. sendAction returns after a 2xx response and does not parse a completion receipt. Preserve an honest pending or failed state until your application protocol provides the result the person actually cares about.
Treat confirmation as host state
The package does not infer which actions need confirmation. The host must configure that policy, recheck current permissions and form validity when confirmation is accepted, and cancel a pending confirmation if the surface or component changes.
The backend must authorize the user and tenant, reject stale or repeated requests where necessary, and make consequential operations idempotent. A client-side guard or successful HTTP status does not prove those backend obligations were met.
Send the minimum context
NibHttpTransport.sendAction serializes the approved NibActionEvent context rather than the entire surface data model. actionDecisions omits context values. Identifiers and binding paths can still contain private words if the source puts them there, so apply a host logging policy before recording diagnostics.
A fake backend can test request shape and client failure handling. Authorization and idempotency must also be tested against the service that will perform the real operation.