@blockquote-web-components/blockquote-controller-xstate 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 blockquote-controller-xstate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,194 @@
+# BlockquoteControllerXstate
+
+![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
+
+### Connect XState machines with Lit's reactive property
+The `BlockquoteControllerXstate` is a Lit Reactive Controller specifically designed for straightforward integration with XState.
+This controller allows you to subscribe to an XState actor, updating a specified reactive property whenever the state machine transitions.
+
+- [xstate v5](https://stately.ai/docs/installation)
+- [xstate v5 - examples](https://stately.ai/docs/examples)
+- [Original idea](https://codesandbox.io/s/z3o0s?file=/src/toggleMachine.ts)
+
+<hr>
+
+### Demo
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/XstateController)
+
+[![Stately.ai](https://img.shields.io/badge/Stately.ai-black.svg)](https://stately.ai/registry/editor/154a7a42-9338-4cc0-8c0c-131c859d8349)
+
+### Usage
+
+***counterMachine.js***
+
+```javascript
+import { createMachine, assign } from 'xstate';
+
+const states = {
+  enabled: 'enabled',
+  disabled: 'disabled',
+};
+
+const increment = {
+  counter: ({ context }) => context.counter + 1,
+  event: ({ event }) => event,
+};
+const decrement = {
+  counter: ({ context }) => context.counter - 1,
+  event: ({ event }) => event,
+};
+
+const isNotMax = ({ context }) => context.counter < 10;
+const isNotMin = ({ context }) => context.counter > 0;
+
+export const counterMachine = createMachine(
+  {
+    id: 'counter',
+    context: { counter: 0, event: undefined },
+    initial: 'enabled',
+    states: {
+      enabled: {
+        on: {
+          INC: {
+            actions: {
+              type: 'increment',
+            },
+            guard: {
+              type: 'isNotMax',
+            },
+          },
+          DEC: {
+            actions: {
+              type: 'decrement',
+            },
+            guard: {
+              type: 'isNotMin',
+            },
+          },
+          TOGGLE: {
+            target: states.disabled,
+          },
+        },
+      },
+      disabled: {
+        on: {
+          TOGGLE: {
+            target: states.enabled,
+          },
+        },
+      },
+    },
+  },
+  {
+    actions: {
+      increment: assign(increment),
+      decrement: assign(decrement),
+    },
+    guards: {
+      isNotMax,
+      isNotMin,
+    },
+  },
+);
+```
+
+***xstate-counter.js***
+
+```javascript
+import { html, LitElement } from 'lit';
+import { BlockquoteControllerXstate } from './BlockquoteControllerXstate.js';
+import { counterMachine } from './counterMachine.js';
+
+export class XstateCounter extends LitElement {
+  static properties = {
+    _xstate: {
+      type: Object,
+      state: true,
+    },
+  };
+
+  constructor() {
+    super();
+    this._xstate = {};
+    this.counterController = new BlockquoteControllerXstate(this, counterMachine, '_xstate');
+  }
+
+  updated(props) {
+    super.updated && super.updated(props);
+    if (props.has('_xstate')) {
+      const { context, value } = this._xstate;
+      const counterEvent = new CustomEvent('counterchange', {
+        bubbles: true,
+        detail: { ...context, value },
+      });
+      this.dispatchEvent(counterEvent);
+    }
+  }
+
+  // ...
+
+  get #disabled() {
+    return this.counterController.state.matches('disabled');
+  }
+
+  render() {
+    return html`
+      <button
+        ?disabled="${this.#disabled}"
+        data-counter="increment"
+        \@click=${() => this.counterController.send({ type: 'INC' })}
+      >
+        Increment
+      </button>
+      <button
+        ?disabled="${this.#disabled}"
+        data-counter="decrement"
+        \@click=${() => this.counterController.send({ type: 'DEC' })}
+      >
+        Decrement
+      </button>
+    `;
+  }
+
+  // ...
+}
+```
+<hr>
+
+
+### `src/BlockquoteControllerXstate.js`:
+
+#### class: `BlockquoteControllerXstate`
+
+##### Fields
+
+| Name      | Privacy | Type | Default   | Description | Inherited From |
+| --------- | ------- | ---- | --------- | ----------- | -------------- |
+| `state`   |         |      |           |             |                |
+| `service` |         |      |           |             |                |
+| `propKey` |         |      | `propKey` |             |                |
+
+##### Methods
+
+| Name               | Privacy | Description | Parameters        | Return | Inherited From |
+| ------------------ | ------- | ----------- | ----------------- | ------ | -------------- |
+| `send`             |         |             | `ev: EventObject` |        |                |
+| `hostConnected`    |         |             |                   |        |                |
+| `hostDisconnected` |         |             |                   |        |                |
+
+<hr/>
+
+#### Exports
+
+| Kind | Name                         | Declaration                | Module                            | Package |
+| ---- | ---------------------------- | -------------------------- | --------------------------------- | ------- |
+| `js` | `BlockquoteControllerXstate` | BlockquoteControllerXstate | src/BlockquoteControllerXstate.js |         |
+
+### `index.js`:
+
+#### Exports
+
+| Kind | Name                         | Declaration                | Module                              | Package |
+| ---- | ---------------------------- | -------------------------- | ----------------------------------- | ------- |
+| `js` | `BlockquoteControllerXstate` | BlockquoteControllerXstate | ./src/BlockquoteControllerXstate.js |         |

package/index.js

@@ -0,0 +1 @@
+export { BlockquoteControllerXstate } from './src/BlockquoteControllerXstate.js';

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "@blockquote-web-components/blockquote-controller-xstate",
+  "version": "1.0.0",
+  "description": "This controller allows you to subscribe to an XState actor, updating a specified reactive property whenever the state machine transitions.",
+  "keywords": [
+    "lit",
+    "web-component",
+    "XState",
+    "stately",
+    "state-machine",
+    "statechart",
+    "actor"
+  ],
+  "license": "MIT",
+  "author": "blockquote-controller-xstate",
+  "type": "module",
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    },
+    "./src/BlockquoteControllerXstate.js": {
+      "default": "./src/BlockquoteControllerXstate.js"
+    },
+    "./index.js": {
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "/define/",
+    "/src/",
+    "index.js",
+    "!/**/*.scss"
+  ],
+  "scripts": {
+    "analyze": "cem analyze --litelement --globs \"{src,define}/**/*.{js,ts}\" \"index.js\"",
+    "build": "echo \"This is not a TypeScript project, so no need to build.\"",
+    "dev:vite": "vite build",
+    "format": "npm run format:eslint && npm run format:prettier && npm run format:stylelint",
+    "format:eslint": "eslint \"**/*.{js,ts,html}\" --fix --ignore-path .eslintignore",
+    "format:prettier": "prettier \"**/*.{js,ts,json,html}\" --write --ignore-path .eslintignore",
+    "format:stylelint": "stylelint \"**/*.{scss,css}\" --fix --allow-empty-input --ignore-path .eslintignore",
+    "postinstall": "npm run sort:package",
+    "lint": "npm run lint:eslint && npm run lint:prettier && npm run lint:stylelint",
+    "lint:eslint": "eslint \"**/*.{js,ts,html}\" --ignore-path .eslintignore",
+    "lint:prettier": "prettier \"**/*.{js,ts,json,html}\" --check --ignore-path .eslintignore",
+    "lint:stylelint": "stylelint \"**/*.{scss,css}\" --allow-empty-input --ignore-path .eslintignore",
+    "preview:vite": "vite preview",
+    "sass:watch": "sass-style-template",
+    "sort:package": "npx sort-package-json",
+    "start": "concurrently -k -r \"npm:sass:watch\" \"npm:vite\"",
+    "test": "wtr --coverage",
+    "test:watch": "wtr --watch",
+    "vite": "vite"
+  },
+  "lint-staged": {
+    "**/*.{js,ts,html}": [
+      "npm run format:eslint"
+    ],
+    "**/*.{js,ts,json,html}": [
+      "npm run format:prettier"
+    ],
+    "**/*.{scss,css}": [
+      "npm run format:stylelint"
+    ]
+  },
+  "prettier": {
+    "arrowParens": "avoid",
+    "printWidth": 100,
+    "singleQuote": true,
+    "trailingComma": "all",
+    "overrides": [
+      {
+        "files": "*.{scss,css}",
+        "options": {
+          "printWidth": 280,
+          "singleQuote": false
+        }
+      }
+    ]
+  },
+  "eslintConfig": {
+    "parserOptions": {
+      "ecmaVersion": "latest"
+    },
+    "extends": [
+      "@open-wc",
+      "prettier"
+    ],
+    "rules": {
+      "class-methods-use-this": "off",
+      "no-unused-expressions": [
+        "error",
+        {
+          "allowShortCircuit": true,
+          "allowTernary": true
+        }
+      ],
+      "object-curly-newline": "off",
+      "import/extensions": [
+        "error",
+        "always",
+        {
+          "ignorePackages": true
+        }
+      ],
+      "import/no-extraneous-dependencies": [
+        "error",
+        {
+          "devDependencies": [
+            "**/test/**/*.{js,ts}",
+            "**/*.config.{js,ts,mjs,cjs}",
+            "**/*.conf.{js,ts,mjs,cjs}"
+          ]
+        }
+      ],
+      "import/no-unresolved": "off",
+      "import/prefer-default-export": "off",
+      "lit/no-classfield-shadowing": "off",
+      "lit/no-native-attributes": "off"
+    }
+  },
+  "stylelint": {
+    "extends": "stylelint-config-standard-scss",
+    "rules": {
+      "custom-property-pattern": null,
+      "no-duplicate-selectors": null,
+      "color-function-notation": null,
+      "alpha-value-notation": null
+    }
+  },
+  "dependencies": {
+    "lit": "^3.1.0",
+    "xstate": "^5.0.0-beta.45"
+  },
+  "devDependencies": {
+    "@blockquote-web-components/blockquote-base-common-dev-dependencies": "^1.7.0",
+    "@blockquote-web-components/blockquote-base-embedded-webview": "^1.6.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "customElements": "custom-elements.json",
+  "gitHead": "e2417c85a1b9179b093333c0dd89f90fdbb4e91b"
+}

package/src/BlockquoteControllerXstate.js

@@ -0,0 +1,198 @@
+import { createActor } from 'xstate';
+
+/**
+ * # BlockquoteControllerXstate
+ *
+ * ![Lit](https://img.shields.io/badge/lit-3.0.0-blue.svg)
+ *
+ * ### Connect XState machines with Lit's reactive property
+ * The `BlockquoteControllerXstate` is a Lit Reactive Controller specifically designed for straightforward integration with XState.
+ * This controller allows you to subscribe to an XState actor, updating a specified reactive property whenever the state machine transitions.
+ *
+ * - [xstate v5](https://stately.ai/docs/installation)
+ * - [xstate v5 - examples](https://stately.ai/docs/examples)
+ * - [Original idea](https://codesandbox.io/s/z3o0s?file=/src/toggleMachine.ts)
+ *
+ * <hr>
+ *
+ * ### Demo
+ *
+ * [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/oscarmarina/XstateController)
+ *
+ * [![Stately.ai](https://img.shields.io/badge/Stately.ai-black.svg)](https://stately.ai/registry/editor/154a7a42-9338-4cc0-8c0c-131c859d8349)
+ *
+ * ### Usage
+ *
+ * ***counterMachine.js***
+ *
+ * ```javascript
+ * import { createMachine, assign } from 'xstate';
+ *
+ * const states = {
+ *   enabled: 'enabled',
+ *   disabled: 'disabled',
+ * };
+ *
+ * const increment = {
+ *   counter: ({ context }) => context.counter + 1,
+ *   event: ({ event }) => event,
+ * };
+ * const decrement = {
+ *   counter: ({ context }) => context.counter - 1,
+ *   event: ({ event }) => event,
+ * };
+ *
+ * const isNotMax = ({ context }) => context.counter < 10;
+ * const isNotMin = ({ context }) => context.counter > 0;
+ *
+ * export const counterMachine = createMachine(
+ *   {
+ *     id: 'counter',
+ *     context: { counter: 0, event: undefined },
+ *     initial: 'enabled',
+ *     states: {
+ *       enabled: {
+ *         on: {
+ *           INC: {
+ *             actions: {
+ *               type: 'increment',
+ *             },
+ *             guard: {
+ *               type: 'isNotMax',
+ *             },
+ *           },
+ *           DEC: {
+ *             actions: {
+ *               type: 'decrement',
+ *             },
+ *             guard: {
+ *               type: 'isNotMin',
+ *             },
+ *           },
+ *           TOGGLE: {
+ *             target: states.disabled,
+ *           },
+ *         },
+ *       },
+ *       disabled: {
+ *         on: {
+ *           TOGGLE: {
+ *             target: states.enabled,
+ *           },
+ *         },
+ *       },
+ *     },
+ *   },
+ *   {
+ *     actions: {
+ *       increment: assign(increment),
+ *       decrement: assign(decrement),
+ *     },
+ *     guards: {
+ *       isNotMax,
+ *       isNotMin,
+ *     },
+ *   },
+ * );
+ * ```
+ *
+ * ***xstate-counter.js***
+ *
+ * ```javascript
+ * import { html, LitElement } from 'lit';
+ * import { BlockquoteControllerXstate } from './BlockquoteControllerXstate.js';
+ * import { counterMachine } from './counterMachine.js';
+ *
+ * export class XstateCounter extends LitElement {
+ *   static properties = {
+ *     _xstate: {
+ *       type: Object,
+ *       state: true,
+ *     },
+ *   };
+ *
+ *   constructor() {
+ *     super();
+ *     this._xstate = {};
+ *     this.counterController = new BlockquoteControllerXstate(this, counterMachine, '_xstate');
+ *   }
+ *
+ *   updated(props) {
+ *     super.updated && super.updated(props);
+ *     if (props.has('_xstate')) {
+ *       const { context, value } = this._xstate;
+ *       const counterEvent = new CustomEvent('counterchange', {
+ *         bubbles: true,
+ *         detail: { ...context, value },
+ *       });
+ *       this.dispatchEvent(counterEvent);
+ *     }
+ *   }
+ *
+ *   // ...
+ *
+ *   get #disabled() {
+ *     return this.counterController.state.matches('disabled');
+ *   }
+ *
+ *   render() {
+ *     return html`
+ *       <button
+ *         ?disabled="${this.#disabled}"
+ *         data-counter="increment"
+ *         \@click=${() => this.counterController.send({ type: 'INC' })}
+ *       >
+ *         Increment
+ *       </button>
+ *       <button
+ *         ?disabled="${this.#disabled}"
+ *         data-counter="decrement"
+ *         \@click=${() => this.counterController.send({ type: 'DEC' })}
+ *       >
+ *         Decrement
+ *       </button>
+ *     `;
+ *   }
+ *
+ *   // ...
+ * }
+ * ```
+ * <hr>
+ */
+export class BlockquoteControllerXstate {
+  /**
+   * @param {import('lit').ReactiveElement} host
+   * @param {import('xstate').StateMachine} machine
+   * @param {string} propKey
+   */
+  constructor(host, machine, propKey) {
+    (this.host = host).addController(this);
+    this.service = createActor(machine).start();
+    this.propKey = propKey;
+  }
+
+  get state() {
+    return this.service.getSnapshot();
+  }
+
+  /**
+   * @param {import('xstate').EventObject} ev
+   */
+  send(ev) {
+    this.service.send(ev);
+  }
+
+  hostConnected() {
+    /* Do not mutate the context object. Instead, you should use the assign(...) action to update context immutably.
+     * https://stately.ai/docs/context#updating-context-with-assign
+     * https://lit.dev/docs/components/properties/#mutating-properties
+     */
+    this.service.subscribe(state => {
+      this.propKey in this.host && (this.host[this.propKey] = state);
+    });
+  }
+
+  hostDisconnected() {
+    this.service.stop();
+  }
+}