NIB / DOCUMENTATION
Bindings and forms — NibGenUI
Edit bound text locally and decide how remote updates resolve conflicts.
Open interactive viewBind to a JSON Pointer
A dynamic string may be a literal or a path binding such as /user/name. A missing path resolves as null while a progressive surface is being built. A present value with the wrong type is rejected. TextField.value must be a binding for local editing; a literal value is read-only in this slice.
The runtime keeps the surface data model. writeData validates a local value and commits it before the user sees a transport response. The renderer uses NibInput or NibTextarea and writes through the bound path on each edit.
final result = runtime.writeData('main', '/user/name', 'Ada');
if (!result.accepted) {
for (final diagnostic in result.diagnostics) {
print(diagnostic.code);
}
}| API | Type | Default | Behavior |
|---|---|---|---|
| NibBinding(path) | NibValue | — | Points to a surface-local JSON Pointer. |
| writeData(surfaceId, path, value) | NibApplyResult | — | Validates and commits a local data change without a protocol envelope. |
| resolve(surfaceId, value) | Object? | null if missing | Reads a literal, binding, or registered function result. |
Build a field that writes to one data path
First create main with the Basic catalog. The component frame below adds a root Column, a field and a preview Text. Both field and preview refer to /user/name. After applying it, seed that path with runtime.writeData. Typing in the field should update the preview without a request, because both widgets resolve the same surface-local value.
A literal value such as "Ada" displays text but is read-only in this renderer. The object {"path":"/user/name"} makes the field editable. The path is a JSON Pointer, not Dart property syntax: use slash-separated segments rather than user.name. Missing map parents can be created by a write; an existing scalar or null parent cannot become a map implicitly, so that write is rejected.
runtime.apply({
'version': 'v0.9.1',
'updateComponents': {
'surfaceId': 'main',
'components': [
{'id': 'root', 'component': 'Column', 'children': ['name', 'preview']},
{'id': 'name', 'component': 'TextField', 'label': 'Your name',
'value': {'path': '/user/name'}},
{'id': 'preview', 'component': 'Text',
'text': {'path': '/user/name'}},
],
},
});
final seeded = runtime.writeData('main', '/user/name', 'Ada');
if (!seeded.accepted) debugPrint(seeded.diagnostics.first.code);Choose a remote edit policy
Local typing does not wait for an agent. If a later committed remote frame writes the same path, the remote value takes precedence. The renderer retains the active selection where possible and clamps it when the replacement text is shorter.
For a form that must keep the user’s draft uninterrupted, the host should avoid sending conflicting remote values while that field is active. This is a host policy decision, not an automatic merge.
Gate form actions in the host
The supported TextField wire schema has label, optional value, and variant. It does not support A2UI checks or validationRegexp. The host must validate a consequential form before dispatch and validate again in the backend.
An optional NibRuntime.actionGuards entry can reject an action using its allowed context. A registered action without a guard can dispatch; do not treat the guard as implicit.
| API | Type | Default | Behavior |
|---|---|---|---|
| TextField.variant | String? | shortText behavior | Accepted values: longText, number, shortText, obscured. |
| actionGuards | Map<String, NibActionGuard> | {} | Optional host validation or permission check before a handler runs. |
Compare missing data, wrong types and remote replacement
Remove the initial data write and replay. An unresolved binding is a normal temporary state during streaming. Now supply a number at /user/name: the present value conflicts with the dynamic string property, so validation rejects it. Missing and invalid are different outcomes. Do not convert every invalid value to a string in the renderer; that hides a producer contract error and changes what the action receives.
Type a longer name, place the cursor in the middle, then apply a remote data frame with a shorter replacement. The committed remote value wins. The renderer preserves or clamps selection so it stays inside the replacement text; it does not merge two simultaneous edits. If your task needs uninterrupted drafts, coordinate the sender to avoid updating active draft paths, or design distinct draft and server-result paths in the host.
In the live fixture, press Next frame until the form appears, leave Your name empty and press Say hello. The host action guard produces Enter a name first. Type Ada and press again; Hello, Ada is local host feedback. The fixture does not send the name to a service. Replay starts with fresh state, so do not expect that draft to survive a new runtime.
Before using the same pattern for a consequential form, define which fields are required, normalize them deliberately, and validate the permitted action context. TextField’s number variant changes entry behavior but still belongs to the supported dynamic-string contract. It does not turn a string into a trusted numeric amount. Keep parsing and domain checks in the host and repeat authoritative validation in the service that performs the operation.