BlockquoteControllerXstate

Connect XState machines with Lit

The BlockquoteControllerXstate is a Lit Reactive Controller that is specifically designed to facilitate an integration with XState. This controller provides the capability to subscribe to an XState actor. It also calls onSnapshot with every state change.

• xstate v6
• xstate v6 - examples

Demo

Usage

counterMachine.ts

import {setup, types} from 'xstate';

const counterSetup = setup({
  // v6: `schemas` (Standard Schema). `types<T>()` is type-only, no runtime validation.
  // Zod, Valibot, ArkType... can be used instead to validate at runtime.
  schemas: {
    context: types<{counter: number}>(),
    events: {
      INC: types<void>(),
      DEC: types<void>(),
      TOGGLE: types<void>(),
    },
    // The element's public events, dispatched on the host with `dispatchEmitted`
    emitted: {
      counterchange: types<{counter: number}>(),
    },
  },
  guards: {
    canIncrement: ({context}) => context.counter < 10,
    canDecrement: ({context}) => context.counter > 0,
  },
  delays: {
    backoff: ({context}) => context.counter * 1000,
  },
});

export const counterMachine = counterSetup.createMachine({
  context: {counter: 0},
  initial: 'enabled',
  states: {
    enabled: {
      on: {
        // Transition functions (typed from `schemas`): return the next `context`, or
        // `undefined` to ignore the event. The guard comes first: a function that calls
        // `enq` handles the event even when it returns nothing.
        INC: ({context, guards}, enq) => {
          if (!guards.canIncrement({context})) {
            return undefined;
          }
          const counter = context.counter + 1;
          enq.emit({type: 'counterchange', counter});
          return {context: {counter}};
        },
        DEC: ({context, guards}, enq) => {
          if (!guards.canDecrement({context})) {
            return undefined;
          }
          const counter = context.counter - 1;
          enq.emit({type: 'counterchange', counter});
          return {context: {counter}};
        },
        // v6 types do not accept the string shorthand (`TOGGLE: 'disabled'`)
        TOGGLE: {target: 'disabled'},
      },
    },
    disabled: {
      after: {
        backoff: {target: 'enabled'},
      },
      on: {
        TOGGLE: {target: 'enabled'},
      },
    },
  },
});

new BlockquoteControllerXstate(this, {machine, options, onSnapshot, onError, reconnect, dispatchEmitted})

• this: the host component (a Lit ReactiveControllerHost, usually the LitElement itself).
• machine (required): the XState machine.
• options: createActor options (input, inspect, ...). Optional, unless the machine requires input: then {input} or {snapshot} must be provided, as when calling createActor.
• onSnapshot (optional): called with every new snapshot: the first one on each connection and the last one (snapshot.status === 'stopped') when the host is disconnected.
• onError (optional): called when the actor errors (the 'error' snapshot is also sent to onSnapshot). If omitted, XState reports the error as unhandled, unless another subscriber of the actor handles it.
• reconnect (optional): 'restart' (default) or 'restore', what the new actor starts from when the host is connected again.
• dispatchEmitted (optional): dispatch the events the machine emits as DOM events on the host. true uses { composed: true }.

Machine with required input

const userMachine = setup({
  schemas: {
    input: types<{userId: string}>(),
    context: types<{userId: string}>(),
  },
}).createMachine({
  context: ({input}) => ({userId: input.userId}),
});

new BlockquoteControllerXstate(this, {machine: userMachine}); // type error: `input` is required
new BlockquoteControllerXstate(this, {machine: userMachine, options: {input: {userId: '123'}}});

Machines whose input accepts undefined (or that declare no input) can omit options.

The actor is created in the constructor, so snapshot, actor, send, trigger and can are available before the host is connected. It is started on hostConnected and stopped on hostDisconnected; a new actor is created if the host is connected again. With reconnect: 'restore' it resumes the state the previous actor had (pending timers keep their deadlines); by default ('restart') it starts from the initial state.

xstate-counter.js

import {html, LitElement} from 'lit';
import {BlockquoteControllerXstate} from '@blockquote-web-components/blockquote-controller-xstate';
import {counterMachine} from './counterMachine.js';
import {styles} from './styles/xstate-counter-styles.css.js';

export class XstateCounter extends LitElement {
  static styles = [styles];

  constructor() {
    super();
    // The controller re-renders the host on every snapshot. The machine emits the element's
    // public events, and `dispatchEmitted` dispatches them on it: `counterchange` with
    // `detail: {counter}`, `{composed: true}` (listen on the element, or capture).
    this.counterController = new BlockquoteControllerXstate(this, {
      machine: counterMachine,
      // Moving the element in the DOM keeps its state
      reconnect: 'restore',
      dispatchEmitted: true,
      options: {
        inspect: this._inspectEvents,
      },
    });
  }

  // xstate v6 inspection events: '@xstate.actor' | '@xstate.transition'
  _inspectEvents = (inspEvent) => {
    console.info('inspect event', inspEvent);
  };

  get #disabled() {
    return this.counterController.snapshot.matches('disabled');
  }

  render() {
    // `can.X()`: `false` when the event would be ignored (guards, `disabled` state) or the
    // actor has finished. `trigger` and `can` always target the current actor.
    const {can, trigger, snapshot} = this.counterController;
    return html`
      <slot></slot>
      <div data-disabled="${this.#disabled}">
        <span>
          <button
            ?disabled="${!can.INC()}"
            data-counter="increment"
            \@click=${() => trigger.INC()}>
            Increment
          </button>
          <button
            ?disabled="${!can.DEC()}"
            data-counter="decrement"
            \@click=${() => trigger.DEC()}>
            Decrement
          </button>
        </span>
        <p>${snapshot.context.counter}</p>
      </div>
      <div>
        <button \@click=${() => trigger.TOGGLE()}>
          ${this.#disabled ? 'Enabled counter' : 'Disabled counter'}
        </button>
      </div>
    `;
  }
}

trigger and can

trigger sends typed events generated from schemas.events: trigger.INC(), trigger.RENAME({label}), like send({type: 'RENAME', label}). It has the same signatures as XState v6's actor.trigger, with one difference: XState's belongs to one actor, while the controller's is a stable proxy (ControllerTrigger) that always sends to the current actor.

That matters because a new actor is created each time the host is connected again (stopped actors cannot restart). actor.trigger kept from the first connection would send to a stopped actor, and the event would be lost; controller.trigger can be kept or destructured safely.

can (ControllerCan) has the same shape, is also a stable proxy, and returns snapshot.can(event) for the current actor: can.INC(), can.RENAME({label}). It is false when the transition function ignores the event (returns undefined) or the actor has finished ('stopped', 'done' or 'error'). The machine still rejects invalid events: can only drives the UI.

Disconnect and reconnect: restart or restore

A Lit element is disconnected and connected again more often than it seems: moving it in the DOM, reordering a repeat, changing its parent. The actor is stopped on disconnect, and a stopped actor cannot restart, so a new actor is created on reconnect. The reconnect option decides what it starts from:

With 'restore', the snapshot is persisted before the actor stops (actor.getPersistedSnapshot()) and the new actor is created from it (createActor(machine, {snapshot})). It keeps:

• context, the state value and children.
• Pending timers, with their original deadlines: a timer that expired while disconnected fires right away.
• Invoked work in flight, such as a createAsyncLogic request: stopping aborts it, and the new actor runs it again.

An actor that had finished ('done' or 'error') restarts, and so does one whose machine was reassigned meanwhile. onSnapshot still receives the 'stopped' snapshot on disconnect, then the restored one.

Emitted events: on and dispatchEmitted

A machine emits events with enq.emit(...) to say that something happened once: the counter changed, a form was submitted. Declared in schemas.emitted, the element's public events live in the machine, typed and testable without a DOM.

dispatchEmitted: true dispatches each emitted event on the host as a CustomEvent: the emitted type is the event name and the rest is its detail, with {composed: true} (pass an object to change it). The event does not bubble: listen on the element itself, or on an ancestor in the capture phase ({capture: true}). EmittedEventMap types addEventListener:

declare global {
  interface HTMLElementEventMap extends EmittedEventMap<typeof counterMachine> {}
}

el.addEventListener('counterchange', (ev) => ev.detail.counter); // `number`

To handle emitted events in code, use controller.on(type, handler) (or '*'). It has the signature of actor.on, but XState removes actor.on handlers when the actor stops, while controller.on handlers keep receiving events from the actors created on reconnect.

When they are delivered:

• After the transition is applied: controller.snapshot already has the new state (the host has not re-rendered yet).
• Not when the host is disconnected (stopping the actor does not run exit), nor when an actor is restored with reconnect: 'restore' (entry does not run again): moving an element in the DOM dispatches nothing.
• can.X() does not emit: it only evaluates the transition.

Listeners run synchronously, inside the trigger (or send) that caused the event:

• controller.snapshot is already the new state, but the host has not re-rendered yet. To read its rendered DOM, await el.updateComplete first.
• A trigger called from a listener is queued: it is processed when the current event is done, so controller.snapshot right after it is still the current state. Its own emitted events follow, in order.
• A listener that throws is reported as an uncaught error. Other listeners still receive the event, and the actor keeps running.

controller.trigger vs controller.actor.trigger

Use controller.trigger for events from the UI. For a response to a request made from the component, it depends on reconnect:

• 'restore': the new actor continues the same session, so a response that arrives after a reconnection is still valid. Use controller.trigger.
• 'restart': the new actor starts a new session, so the response belongs to the old one. Read controller.actor.trigger before the await: the response is dropped instead of reaching the new actor.

// `reconnect: 'restart'`
async #onInput(ev: InputEvent) {
  const query = (ev.target as HTMLInputElement).value;
  this.search.trigger.typed({query});

  // Bound to this session: read before the `await`
  const session = this.search.actor.trigger;
  const items = await fetchSuggestions(query);

  // Dropped if the actor that asked was stopped in the meantime.
  // `this.search.trigger.results({items})` would show results for `query` in the new session.
  session.results({items});
}

Moving the request into the machine (an invoked createAsyncLogic) avoids the choice: the request belongs to the actor, and stopping the actor cancels it (its AbortSignal is aborted). With 'restore' the new actor runs it again; with 'restart' it is gone with the old session.

src/BlockquoteControllerXstate.ts:

class: BlockquoteControllerXstate

Fields

Methods

machine: TMachine;
snapshot: ActorOptions<TMachine>['snapshot'];

Exports

src/index.ts:

Exports