BlockquoteControllerXstate

连接XState机与Lit

blockquoteconcontrollerxstate是一个Lit Reactive Controller，专门设计用于与XState集成。该控制器提供订阅XState参与者的功能。它还调用 onSnapshot 随着状态的变化。

• xstate v6
• Xstate v6 -示例

演示

使用

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：主机组件(a) ReactiveControllerHost，通常是 LitElement 本身)。
• machine （必选）：XState机。
• options： createActor 选项(input， inspect,……)。可选，除非机器需要 输入:那 {input} 或者 {snapshot} 必须提供，当呼唤 createActor.
• onSnapshot （可选）：每次新快照时调用：每次连接的第一个快照 最后一个(snapshot.status === 'stopped')，此时主机已断开连接。
• onError （可选）：当参与者出错时调用 'error' 快照也被发送到 onSnapshot）. 如果省略，XState将错误报告为未处理，除非另一个订阅者 演员处理它。
• reconnect (可选): 'restart' (默认)或 'restore'新演员的出发点是什么 当主机重新连接时。
• dispatchEmitted （可选）：调度机器作为DOM事件在 主人。 true 使用 { composed: true }.

需要输入的机器

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'}}});

输入可接受的机器 undefined （或者声明没有输入）可以省略 options.

actor是在构造函数中创建的，所以 snapshot， actor， send， trigger 和 can 在连接主机之前可用。它开始于 hostConnected 停了下来 hostDisconnected;如果主机再次连接，将创建一个新的参与者。与 reconnect: 'restore' 它恢复前参与者的状态（等待计时器保持其状态） 最后期限);默认情况下('restart')，它从初始状态开始。

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 和 can

trigger 中生成的类型化事件 schemas.events： trigger.INC()， trigger.RENAME({label}),就像 send({type: 'RENAME', label})． 它的签名和 XState v6的 actor.trigger，但有一点不同：XState属于一个参与者，而 控制器是一个稳定的代理(ControllerTrigger)，它总是发送给当前actor。

这很重要，因为每次主机再次连接（停止）时都会创建一个新的actor 演员无法重启)。 actor.trigger 保持从第一个连接将发送到一个停止 行动者，事件就会失去； controller.trigger 可安全保存或销毁。

can （ControllerCan)有相同的形状，也是一个稳定的代理，和回报 snapshot.can(event) 对于现任演员： can.INC()， can.RENAME({label})． 它是 false 当转换函数忽略事件(返回 undefined)或者演员已经演完了 （'stopped'， 'done' 或者 'error'）. 机器仍然拒绝无效事件： can 只有 驱动UI。

断开连接和重新连接： restart 或者 restore

一个Lit元素被断开并再次连接的频率比看起来更频繁：移动它 DOM，重新排序 repeat，改变它的父级。actor在断开连接时停止，并且 停止的actor不能重新启动，因此在重新连接时创建一个新的actor。这个 reconnect 选项 决定它从哪里开始：

与 'restore'，则快照在参与者停止之前被持久化 （actor.getPersistedSnapshot())，新的演员由此诞生 （createActor(machine, {snapshot})）. 它使:

• context，国家价值和子女。
• 挂起计时器，具有其原始截止日期：在断开连接触发时过期的计时器 马上。
• 调用的工作在飞行中，如 createAsyncLogic 请求：停止中止它，而新的 Actor再次运行它。

演员演完了('done' 或者 'error')重新启动，而另一个 machine 是 与此同时生效。 onSnapshot 仍然收到 'stopped' 快照断开，然后 恢复一个。

发射事件: on 和 dispatchEmitted

机器发出事件 enq.emit(...) 表示某事发生过一次：计数器 更改，提交了一个表单。中声明 schemas.emitted，元素的公共事件直播 在机器中，没有DOM的类型和可测试的。

dispatchEmitted: true 将主机上发出的每个事件分派为 CustomEvent: 发出 type 是事件名，其余是其名 detail, {composed: true} (通过一个 对象来更改它)。事件不会冒泡：监听元素本身，或者监听对象 捕获阶段的父节点({capture: true}）。 EmittedEventMap 类型 addEventListener：

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

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

要处理代码中发出的事件，请使用 controller.on(type, handler) (或 '*'）. 它有 的签名 actor.on，但XState删除 actor.on 处理程序，当参与者停止时 controller.on 处理程序不断从重新连接时创建的参与者接收事件。

交付时：

• 转换应用后： controller.snapshot 已具有新状态（主机） 尚未重新渲染)。
• 当主机断开连接（停止actor不运行）时不会 exit)，当演员也是如此 恢复为 reconnect: 'restore' （entry （不再运行）：移动元素 DOM什么也不分派。
• can.X() 不触发：它只计算转换。

类中同步运行侦听器 trigger (或 send)导致事件发生；

• controller.snapshot 已经是新的状态，但是主机还没有重新渲染。阅读 它的渲染DOM， await el.updateComplete 第一。
• 一、 trigger 从侦听器中调用是排队的：当当前事件完成时，它被处理； 所以 controller.snapshot 之后它仍然是当前状态。它自己发出的事件 跟着，按顺序。
• 抛出的侦听器被报告为未捕获的错误。其他听众仍然收到 事件，actor继续运行。

controller.trigger vs controller.actor.trigger

使用 controller.trigger 获取来自UI的事件。的请求的响应 组件，这取决于 reconnect：

• 'restore'：新的参与者继续相同的会话，因此在 重新连接仍然有效。使用 controller.trigger.
• 'restart'：新actor启动新会话，因此响应属于旧会话。读 controller.actor.trigger 之前 await：响应被丢弃，而不是到达 新演员。

// `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});
}

将请求移动到机器中（被调用） createAsyncLogic)避免选择：the 请求属于actor，停止actor将取消它 AbortSignal 是流产)。 与 'restore' 新演员再演一遍；与 'restart' 它随着旧的会议而消失了。

src/BlockquoteControllerXstate.ts：

类: BlockquoteControllerXstate

字段

方法

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

出口

src/index.ts：

出口