[@xstate/lit] Add Lit Controller

jest.config.js

@@ -6,6 +6,9 @@ const { constants } = require('jest-config');
 module.exports = {
   prettierPath: null,
   setupFilesAfterEnv: ['@xstate-repo/jest-utils/setup'],
+  transformIgnorePatterns: [
+    'node_modules/(?!(@open-wc|lit-html|lit-element|lit|@lit)/)'
+  ],
   transform: {
     [constants.DEFAULT_JS_PATTERN]: 'babel-jest',
     '^.+\\.vue$': '@vue/vue3-jest',

packages/xstate-lit/CHANGELOG.md

@@ -0,0 +1 @@
+# @xstate/lit

packages/xstate-lit/README.md

@@ -0,0 +1,132 @@
+# @xstate/lit
+
+The [@xstate/lit](https://github.com/lit/lit) package contains a [Reactive Controller](https://lit.dev/docs/composition/controllers/) for using XState with Lit.
+
+- [Read the full documentation in the XState docs](https://stately.ai/docs/xstate-lit/).
+- [Read our contribution guidelines](https://github.com/statelyai/xstate/blob/main/CONTRIBUTING.md).
+
+## Quick Start
+
+1. Install `xstate` and `@xstate/lit`:
+
+```bash
+npm i xstate @xstate/lit
+```
+
+**Via CDN**
+
+```html
+<script src="https://unpkg.com/@xstate/lit/dist/xstate-lit.esm.js"></script>
+```
+
+2. Import the `UseMachine` Lit controller:
+
+**`new UseMachine(this, {machine, options?, callback?})`**
+
+```js
+import { html, LitElement } from 'lit';
+import { customElement } from 'lit/decorators.js';
+import { createBrowserInspector } from '@statelyai/inspect';
+import { createMachine } from 'xstate';
+import { UseMachine } from '@xstate/lit';
+
+const { inspect } = createBrowserInspector({
+  // Comment out the line below to start the inspector
+  autoStart: false,
+});
+
+const toggleMachine = createMachine({
+  id: 'toggle',
+  initial: 'inactive',
+  states: {
+    inactive: {
+      on: { TOGGLE: 'active' },
+    },
+    active: {
+      on: { TOGGLE: 'inactive' },
+    },
+  },
+});
+
+@customElement('toggle-component')
+export class ToggleComponent extends LitElement {
+  toggleController: UseMachine<typeof toggleMachine>;
+
+constructor() {
+    super();
+    this.toggleController = new UseMachine(this, {
+      machine: toggleMachine,
+      options: { inspect }
+    });
+  }
+
+  private get _turn() {
+    return this.toggleController.snapshot.matches('inactive');
+  }
+
+  render() {
+    return html`
+      <button @click=${() => this.toggleController.send({ type: 'TOGGLE' })}>
+        ${this._turn ? 'Turn on' : 'Turn off'}
+      </button>
+    `;
+  }
+}
+```
+
+## API
+
+### `new UseMachine(host, {machine, options?, callback?})`
+
+A class that creates an actor from the given machine and starts a service that runs for the lifetime of the component.
+
+#### Constructor Options:
+
+`host`: ReactiveControllerHost: The Lit component host.
+`machine`: AnyStateMachine: The XState machine to manage.
+`options?`: ActorOptions<TMachine>: Optional options for the actor.
+`callback?`: (snapshot: SnapshotFrom<TMachine>) => void: An optional subscription callback that listens to snapshot updates.
+
+#### Return Methods:
+
+`actor` - Returns the actor (state machine) instance.
+`snapshot` - Returns the current state snapshot.
+`send` - Send an event to the state machine.
+`unsubscribe` - Unsubscribes from state updates.
+
+## Matching States
+
+When using [hierarchical](https://xstate.js.org/docs/guides/hierarchical.html) and [parallel](https://xstate.js.org/docs/guides/parallel.html) machines, the state values will be objects, not strings. In this case, it is best to use [`state.matches(...)`](https://xstate.js.org/docs/guides/states.html#state-methods-and-properties).
+
+```js
+${this.myXStateController.snapshot.matches('idle')}
+//
+${this.myXStateController.snapshot.matches({ loading: 'user' })}
+//
+${this.myXStateController.snapshot.matches({ loading: 'friends' })}
+```
+
+## Persisted and Rehydrated State
+
+You can persist and rehydrate state with `useMachine(...)` via `options.snapshot`:
+
+```js
+// Get the persisted state config object from somewhere, e.g. localStorage
+// highlight-start
+const persistedState = JSON.parse(
+  localStorage.getItem('some-persisted-state-key'),
+);
+// highlight-end
+
+constructor() {
+  super();
+  this.fetchController = new UseMachine(this, {
+    machine: someMachine,
+    options: {
+      snapshot: this.persistedState
+    }
+  });
+}
+
+// state will initially be that persisted state, not the machine’s initialState
+```

packages/xstate-lit/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@xstate/lit",
+  "version": "1.0.0",
+  "description": "XState tools for Lit",
+  "keywords": [
+    "state",
+    "machine",
+    "statechart",
+    "scxml",
+    "state",
+    "graph",
+    "store",
+    "lit",
+    "reactive controller",
+    "web components"
+  ],
+  "author": "David Khourshid <[email protected]>",
+  "homepage": "https://github.com/statelyai/xstate/tree/main/packages/xstate-lit#readme",
+  "license": "MIT",
+  "main": "dist/xstate-lit.cjs.js",
+  "module": "dist/xstate-lit.esm.js",
+  "type": "module",
+  "preconstruct": {
+    "exports": true,
+    "___experimentalFlags_WILL_CHANGE_IN_PATCH": {
+      "typeModule": true,
+      "distInRoot": true,
+      "importsConditions": true
+    }
+  },
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/xstate-lit.cjs.mjs",
+        "default": "./dist/xstate-lit.cjs.js"
+      },
+      "module": "./dist/xstate-lit.esm.js",
+      "import": "./dist/xstate-lit.cjs.mjs",
+      "default": "./dist/xstate-lit.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/statelyai/xstate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/statelyai/xstate/issues"
+  },
+  "peerDependencies": {
+    "lit": "^3.1.2",
+    "xstate": "^5.14.0"
+  },
+  "devDependencies": {
+    "@open-wc/testing-helpers": "^3.0.0",
+    "@testing-library/dom": "^9.3.4",
+    "@types/jest": "^29.5.10",
+    "lit": "^3.1.2",
+    "xstate": "5.14.0"
+  }
+}

packages/xstate-lit/src/UseMachine.ts

@@ -0,0 +1,84 @@
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+import {
+  Actor,
+  AnyStateMachine,
+  ActorOptions,
+  createActor,
+  EventFrom,
+  SnapshotFrom,
+  Subscription
+} from 'xstate';
+
+export class UseMachine<TMachine extends AnyStateMachine>
+  implements ReactiveController
+{
+  private host: ReactiveControllerHost;
+  private machine: TMachine;
+  private options?: ActorOptions<TMachine>;
+  private callback?: (snapshot: SnapshotFrom<TMachine>) => void;
+  private actorRef = {} as Actor<TMachine>;
+  private subs: Subscription = { unsubscribe: () => {} };
+  private currentSnapshot: SnapshotFrom<TMachine>;
+
+  constructor(
+    host: ReactiveControllerHost,
+    {
+      machine,
+      options,
+      callback
+    }: {
+      machine: TMachine;
+      options?: ActorOptions<TMachine>;
+      callback?: (snapshot: SnapshotFrom<TMachine>) => void;
+    }
+  ) {
+    this.machine = machine;
+    this.options = options;
+    this.callback = callback;
+    this.currentSnapshot = this.snapshot;
+
+    (this.host = host).addController(this);
+  }
+
+  get actor() {
+    return this.actorRef;
+  }
+
+  get snapshot() {
+    return this.actorRef?.getSnapshot?.();
+  }
+
+  send(ev: EventFrom<TMachine>) {
+    this.actorRef?.send(ev);
+  }
+
+  unsubscribe() {
+    this.subs.unsubscribe();
+  }
+
+  protected onNext = (snapshot: SnapshotFrom<TMachine>) => {
+    if (this.currentSnapshot !== snapshot) {
+      this.currentSnapshot = snapshot;
+      this.callback?.(snapshot);
+      this.host.requestUpdate();
+    }
+  };
+
+  private startService() {
+    this.actorRef = createActor(this.machine, this.options);
+    this.subs = this.actorRef?.subscribe(this.onNext);
+    this.actorRef?.start();
+  }
+
+  private stopService() {
+    this.actorRef?.stop();
+  }
+
+  hostConnected() {
+    this.startService();
+  }
+
+  hostDisconnected() {
+    this.stopService();
+  }
+}

packages/xstate-lit/src/index.ts

@@ -0,0 +1 @@
+export { UseMachine } from './UseMachine.ts';

packages/xstate-lit/test/UseActor.ts

@@ -0,0 +1,71 @@
+import { html, LitElement } from 'lit';
+import type { Snapshot } from 'xstate';
+import { fromPromise } from 'xstate/actors';
+import { fetchMachine } from './fetchMachine.ts';
+import { UseMachine } from '../src/index.ts';
+
+const onFetch = () =>
+  new Promise<string>((res) => {
+    setTimeout(() => res('some data'), 50);
+  });
+
+const fMachine = fetchMachine.provide({
+  actors: {
+    fetchData: fromPromise(onFetch)
+  }
+});
+
+export class UseActor extends LitElement {
+  fetchController: UseMachine<typeof fetchMachine> = new UseMachine(this, {
+    machine: fMachine,
+    options: {
+      snapshot: this.persistedState
+    }
+  });
+
+  get persistedState(): Snapshot<any> | undefined {
+    return undefined;
+  }
+
+  override createRenderRoot() {
+    return this;
+  }
+
+  override render() {
+    return html`
+      <slot></slot>
+      <div>
+        ${this.fetchController.snapshot.matches('idle')
+          ? html`
+              <button
+                @click=${() => this.fetchController.send({ type: 'FETCH' })}
+              >
+                Fetch
+              </button>
+            `
+          : ''}
+        ${this.fetchController.snapshot.matches('loading')
+          ? html` <div>Loading...</div> `
+          : ''}
+        ${this.fetchController.snapshot.matches('success')
+          ? html`
+              <div>
+                Success! Data:
+                <div data-testid="data">
+                  ${this.fetchController.snapshot.context.data}
+                </div>
+              </div>
+            `
+          : ''}
+      </div>
+    `;
+  }
+}
+
+window.customElements.define('use-actor', UseActor);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'use-actor': UseActor;
+  }
+}