Interface: RenderSpecOptions
API / @xmachines/play-dom / RenderSpecOptions
Defined in: @xmachines/json-render-dom
Named options for renderSpec.
All fields are optional — send defaults to a no-op and handlers to an
empty map, so renderSpec(spec, store, registry) renders a static tree.
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
confirmDialog? | boolean | false turns the default confirm dialog off, for a host whose component shows the pending confirmation through ctx.confirmation. The default, true, shows the dialog on document.body for each binding with confirm that waits, when the host gives no onConfirm, as JSONUIProvider of the framework renderers shows ConfirmDialog. The renderers that share one validation registry share the setting: the last pass sets it. | - |
directives? | DirectiveDefinition<ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>>[] | Custom directives — user-defined $-prefixed dynamic values that extend the spec expression language. Converted to a DirectiveRegistry once per renderSpec call and forwarded to PropResolutionContext.directives, matching the framework renderers’ directives prop (@json-render 0.19). Built-in expressions always take precedence over custom directives. | - |
fallback? | DomComponentRenderer | Renderer called when registry has no entry for an element’s type (GAP-04). If absent, unknown types render as null. | - |
functions? | Record<string, ComputedFunction> | Map of named compute functions forwarded to PropResolutionContext (GAP-03). Enables { $computed: "fn", args } prop expressions to resolve. When absent, $computed expressions return undefined (no throw). | - |
handlers? | Record<string, ActionHandler> | Map of catalog action names → async ActionHandler functions, consumed by defineRegistry’s emit()/watch dispatch. Defaults to {}. | - |
loading? | boolean | Flag indicating the spec is still streaming (GAP-06). When true, components can read ctx.loading to render skeleton states, and missing-child warnings (GAP-07) are suppressed since referenced elements may not yet have arrived in the incremental spec. | - |
navigate? | (path) => void | Navigation callback forwarded to DomRenderContext.navigate. Invoked automatically by defineRegistry’s emit() when an action binding resolves with onSuccess: { navigate: "/path" }. Also readable by component implementations via ctx.navigate. | - |
onConfirm? | ConfirmHandler | Confirmation hook forwarded to DomRenderContext.onConfirm. Consulted by defineRegistry’s emit() before executing an action binding that declares confirm. Without it, the binding waits as the pending confirmation of the tree (ctx.confirmation), and the default confirm dialog shows it (see confirmDialog). | - |
onEffectCleanup? | (cleanup) => void | Called with each cleanup that an effect of a component returns (see DomRenderContext.effect). renderSpec keeps no instance from one call to the next, so the host calls each cleanup when it discards the tree. When absent, the renderer drops the cleanups. The incremental renderer runs the cleanups itself, and it ignores this option. | - |
onRenderError? | OnRenderError | The error handler, (error, name, info). Each failure in code that the renderer runs reaches it one time. info.kind names the place: - element, with name the type of the element: a component renderer below the root throws (GAP-08), an effect of it throws, or a read of its children after the pass fails. The element shows nothing. - props and visible, with name the type of the PARENT: a prop expression or the visible condition of an element below the root throws. The boundary of the parent catches it, as in the framework renderers, and the parent shows nothing. info.key and info.type name the element whose expression threw. - root: the root fails, and it has no boundary above it: its component throws, a prop of it fails to resolve, or its visible condition throws. The renderer shows nothing and throws nothing, also without a handler, so a root that a stream gives half does not stop the host. A new version of the root renders again. - action and watch, with name the action name: an on chain or a watch chain fails. A handler that throws gives its error to reportError one time, and no other element fails. If absent, the renderer reads the handler of the registry, which defineRegistry(catalog, { onRenderError }) sets. Without either, each failure gives one console.error line of the form [json-render] <kind> error in <Type> "<key>":. Forwarded into DomRenderContext.onRenderError so emit() and watch handlers route errors through the same channel as component render errors. | - |
onValidationSetup? | (cleanup) => void | Called with an unregister callback for every field an element registers through ctx.validation.registerField, so a host can release the registrations of an element instance when it unmounts. Mirrors onWatchSetup. | - |
onWatchSetup? | (cleanup, end, baseline) => void | (() => void) | Callback invoked with each watch subscription cleanup function (GAP-02). When an element declares watch, the renderer sets up a store subscription and passes its unsubscribe function to this callback. Host renderers collect these to call on teardown. When absent, watch bindings are not wired. May return a replacement cleanup: when the caller wraps the supplied cleanup (e.g. to drop it from its own collection when invoked), the incremental renderer registers the returned wrapper so an unmount-driven release also runs the caller’s bookkeeping. Returning nothing keeps the supplied cleanup. The cleanup stops the subscription, and the bindings that a change still runs go on. A host that renders the tree again on each change must do so after the store notification, for example in a microtask: each watch then hears the change before the host releases it. end stops the chain before its next binding, and a change that waits for its run. Call it when the element goes for good. The incremental renderer calls it for a removed element, for an element whose watched paths or item path a new render changes, after a pass that throws, and on dispose. baseline reads and sets the watched values that the next change compares against. The incremental renderer gives the values of an earlier subscription of the element to its new one, so a write that came before a new spec still fires, as the effect of react compares against the values of its last run. | - |
send? | (event) => void | Dispatcher for interaction events (e.g. actor.send), exposed to component implementations via ctx.send. Defaults to a no-op. | - |
validation? | ValidationRegistry | Field-validation registry shared by the whole tree, exposed to components as ctx.validation and used by the validateForm built-in. One is created per renderSpec call when omitted; a host that re-renders (e.g. the incremental renderer) must create one for its lifetime and pass it on every pass so registrations survive. | - |
validationFunctions? | Record<string, (value, args?) => boolean> | Custom validation functions forwarded to DomRenderContext.validationFunctions. Components pass these as customFunctions to runValidationCheck / runValidation from @xmachines/json-render-core. Has no effect on prop resolution. | - |