RMT Reference: Actions and Events

Actions describe state changes, effects and emitted events. Event bindings connect DOM or surface events to actions.

Syntax

Operator	Form	Allowed contexts	Parameters	Function	Diagnostics	Related operators
`execution fastpass`	`execution fastpass`	`action`	`fastpass`	Navigation, focus or close on `user-blocking` without a Model transaction.	Reducers, fetch, services, streams, custom effects and command chains are forbidden.	`effect navigation`, `effect close surface`, `effect focus surface`
`input`	`input id string`	`action`	name, type	Declares action payload fields.	Missing types are reported.	`payload`
`status`	`status app.request`	`action`	state path	Binds loading, success and error status.	Unknown state is semantic diagnostic.	`effect`
`effect`	`effect fetch datasource tickets`	`action`	effect kind, optional source	Declares host-owned asynchronous work or a fixed component command.	Fetch uses `datasource`; other effects use their declared source contract. FastPass supports navigation, `close surface` and `focus surface`; component commands permit only `focus`, `reset` and `snapshot`.	`on success ->`
`reduce`	`reduce state.app.status.text = "Saved"`	`action`	target path, expression	Writes declaratively to state.	Business actions require a valid reducer contract; FastPass forbids reducers.	`state`, `status`
`emit`	`emit app.saved with id input.id`	`action`	event name, optional payload	Publishes a typed RMT event.	Missing payload contracts may be reported semantically.	`with`, `emits`
`with`	`with id input.id`	`emit`	key/value pairs	Maps event payload directly from action input or state.	Invalid payload values produce syntax errors.	`payload`
`on`	`on click -> action save`	`surface`, policy block, action result	event or phase	Binds events or action results.	`->` and `action` are required for event bindings.	`target`, `payload`
`target`	`on input target email -> action save`	event binding	target identifier	Narrows the event binding to one target.	Target must be an identifier.	`on`
`-> action`	`on click -> action save`	event binding	action identifier	Connects event and action.	The `action` keyword is required.	`on`, `payload`
`payload`	`payload id from target.dataset.id`	event payload block	name and source path	Maps DOM, detail or surface context into action input.	Payload blocks allow only `payload` and `preventDefault`.	`from`, `input`
`preventDefault`	`preventDefault true`	event payload block	boolean	Documents that the host prevents native default behavior.	Only valid in event payload blocks.	`payload`
`on success -> reduce`	`on success -> reduce state.app.status.text = result.text`	`action`	phase, effect text	Describes result handling after a successful effect.	Result handlers require `->`.	`effect`, `reduce`
`on success -> emit`	`on success -> emit app.loaded`	`action`	phase, effect text	Emits an event after success.	Payload shape can be checked separately.	`emit`
`on error -> overlay`	`on error -> overlay app.toast`	`action`	phase, overlay reference	Binds error feedback to an overlay.	Overlay reference must exist.	`overlay`

Allowed contexts

execution fastpass, input, status, effect, reduce, emit and action result handlers belong in action. Event bindings belong in surface or lifecycle policy blocks.

Parameters

Event names, action names and payload keys are identifiers. Payload values are paths such as input.id, detail.value, target.dataset.id or surface.id.

Description

Actions are declarative transitions. They describe what should change or publish; the host decides how concrete adapters run.

Component commands

An action may call public methods on an eligible, statically known surface through exactly these forms:

template reference.componentCommands {
  state editor.command type object preserve {
    initial {
      last "idle"
    }
  }

  action editor.focus {
    effect focus selector maraca.testbench.editor
    reduce state.editor.command.last = "focus"
  }

  action editor.reset {
    effect reset selector maraca.testbench.editor
    reduce state.editor.command.last = "reset"
  }

  action editor.capture {
    effect snapshot selector maraca.testbench.editor
    reduce state.editor.command.last = "snapshot"
  }

  surface maraca.testbench.editor kind field component x-textarea {
  }
}

Here, selector is the authoring form for a static surface ID; the compiler resolves it to a surface target with a component type. This contract currently permits x-textarea and only focus(), reset() and snapshot(). Unknown surfaces, ineligible components, other source kinds and arbitrary method names are hard compiler errors with a source range.

Maraca runs the command after rendering and hydration, within the orchestration root. It has no document fallback and does not traverse shadow roots. The action result remains visible in XTendMaraca.orchestration.snapshot().actions[]. effects[].value.result uses schema xtend.maraca.component-command-result.v1 with command, surfaceId, component and result; focus and reset return null, while snapshot contains the public XTextarea snapshot. A component command does not mutate RMT state automatically.

FastPass (0.8.0)

template reference.fastpass {
  action showReports {
    execution fastpass
    effect navigation "#reports"
  }
  action dismissPanel {
    execution fastpass
    effect close surface panel
  }
  action focusNavigation {
    execution fastpass
    effect focus surface navigation
  }
  surface panel kind panel component x-section {}
  surface navigation kind panel component x-section {}
}

Navigation accepts a literal path or a declared input such as input path string with effect navigation input.path. Close and focus refer to named surfaces. FastPass focus uses the focus port; the separate selector component-command restriction to x-textarea does not apply. Event bindings and dispatchCommand() select the same executor for declared FastPass actions; dispatchFastPass() returns a cancellable job. Navigation and focus coalesce per scope. Business-command ordering is preserved.

For restrictions, ports and presentation epochs, see FastPass and Abort Boundary.

Examples

template reference.actions {
  state app.status type object preserve {
    initial {
      text "Idle"
    }
  }

  datasource tickets from endpoint "/api/tickets" {
    method GET
  }

  action saveTicket {
    input id string
    status app.status
    effect fetch datasource tickets
    reduce state.app.status.text = "Saving"
    on success -> reduce state.app.status.text = "Saved"
    on success -> emit ticket.saved
    on error -> overlay app.toast
    emit ticket.requested with id input.id
  }

  portal app.root root "#app" layer surface
  overlay app.toast kind toast portal app.root

  surface editor kind form component x-form {
    portal app.root
    lane user-blocking weight 88 {
      mount editor.form from endpoint ticket.editor {
        on submit target editor -> action saveTicket {
          payload id from target.dataset.ticketId
          preventDefault true
        }
      }
    }
  }
}

Diagnostics

Wrong action clauses, missing reducers, unknown overlay references, invalid component commands and missing payload contracts are reported by parser, linter, compiler or semantic graph.

action, state, datasource, overlay, surface, on, emit.

The RMT reference index places action and event records in the complete language model. Related article

XTend Developer Center