First Draft for @xstate/angular

babel.config.js

@@ -25,6 +25,7 @@ module.exports = {
     setPublicClassFields: true,
     setSpreadProperties: true
   },
+  ignore: [/\/xstate-angular\//],
   presets: [
     [
       '@babel/preset-env',

jest.config.js

@@ -1,11 +1,23 @@
 const { constants } = require('jest-config');
+const { defaultTransformerOptions } = require('jest-preset-angular/presets');
 
 /**
  * @type {import('@jest/types').Config.InitialOptions}
  */
 module.exports = {
-  setupFilesAfterEnv: ['@xstate-repo/jest-utils/setup'],
+  setupFilesAfterEnv: [
+    '@xstate-repo/jest-utils/setup',
+    'jest-preset-angular/setup-jest'
+  ],
+  moduleFileExtensions: ['ts', 'html', 'js', 'json', 'mjs'],
   transform: {
+    '^.+\\.(mjs)$|^.+xstate-angular/.+\\.(ts|js)$': [
+      'jest-preset-angular',
+      {
+        ...defaultTransformerOptions,
+        useESM: true
+      }
+    ],
     [constants.DEFAULT_JS_PATTERN]: 'babel-jest',
     '^.+\\.vue$': '@vue/vue3-jest',
     '^.+\\.svelte$': [
@@ -16,6 +28,7 @@ module.exports = {
       }
     ]
   },
+  transformIgnorePatterns: [`/node_modules/(?!(@angular|.*.mjs$))`],
   resolver: '<rootDir>/scripts/jest-resolver.js',
   globals: {
     'vue-jest': {

package.json

@@ -10,7 +10,7 @@
   },
   "preconstruct": {
     "packages": [
-      "packages/!(xstate-dev)"
+      "packages/!(xstate-dev|xstate-angular)"
     ],
     "globals": {
       "react": "React"
@@ -70,6 +70,7 @@
     "jest": "^29.7.0",
     "jest-config": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "jest-preset-angular": "14.0.3",
     "jest-regex-util": "^29.6.3",
     "jest-watch-typeahead": "^2.2.2",
     "lint-staged": "^8.2.1",
@@ -78,15 +79,12 @@
     "prettier": "^3.1.0",
     "spawn-command": "0.0.2-1",
     "synckit": "^0.8.5",
-    "tslib": "^2.3.1",
+    "tslib": "2.6.2",
     "tslint": "^5.11.0",
     "typescript": "^5.4.2",
     "vue": "^3.0.11",
     "webpack-dev-middleware": "^3.6.0"
   },
-  "resolutions": {
-    "**/tslib": "^2.3.1"
-  },
   "husky": {
     "hooks": {
       "pre-commit": "lint-staged"

packages/core/package.json

@@ -124,7 +124,7 @@
     "jsdom": "^14.0.0",
     "jsdom-global": "^3.0.2",
     "pkg-up": "^3.1.0",
-    "rxjs": "^7.8.0",
+    "rxjs": "^7.8.1",
     "xml-js": "^1.6.11"
   },
   "preconstruct": {

packages/xstate-angular/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 David Khourshid
+
+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.
+

packages/xstate-angular/README.md

@@ -0,0 +1,55 @@
+# @xstate/angular
+
+This package contains utilities for using [XState](https://github.com/statelyai/xstate) with [Angular](https://github.com/angular/angular).
+
+- [Read the full documentation in the XState docs](https://stately.ai/docs/xstate-angular).
+- [Read our contribution guidelines](https://github.com/statelyai/xstate/blob/main/CONTRIBUTING.md).
+
+## Quick start
+
+1. Install `xstate` and `@xstate/angular`:
+
+```bash
+npm i xstate @xstate/angular
+```
+
+2. Import the `useMachine` function:
+
+```angular-ts
+import { useMachine } from '@xstate/angular';
+import { createMachine } from 'xstate';
+import {Component, inject} from '@angular/core';
+
+const toggleMachine = createMachine({
+  id: 'toggle',
+  initial: 'inactive',
+  states: {
+    inactive: {
+      on: { TOGGLE: 'active' }
+    },
+    active: {
+      on: { TOGGLE: 'inactive' }
+    }
+  }
+});
+
+const ToggleMachine = useMachine(toggleMachine, {providedIn: 'root'})
+
+@Component({
+  selector: 'app-toggle',
+  standalone: true,
+  imports: [],
+  template: `<button (click)="toggleMachine.send({type: 'TOGGLE'})">
+    {{
+      toggleMachine.snapshot().value === 'inactive'
+        ? 'Click to activate'
+        : 'Active! Click to deactivate'
+    }}
+  </button>
+  `,
+  styleUrl: './toggle.component.css'
+})
+export class ToggleComponent {
+  public toggleMachine = inject(ToggleMachine);
+}
+```

packages/xstate-angular/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "./dist",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

packages/xstate-angular/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@xstate/angular",
+  "version": "0.0.1",
+  "description": "XState tools for Angular",
+  "keywords": [
+    "state",
+    "machine",
+    "statechart",
+    "scxml",
+    "state",
+    "graph",
+    "angular"
+  ],
+  "type": "module",
+  "author": "David Khourshid <davidkpiano@gmail.com>",
+  "homepage": "https://github.com/statelyai/xstate/tree/main/packages/xstate-angular#readme",
+  "license": "MIT",
+  "main": "dist/xstate-angular.cjs.js",
+  "module": "dist/xstate-angular.esm.js",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/xstate-angular.cjs.mjs",
+        "default": "./dist/xstate-angular.cjs.js"
+      },
+      "development": {
+        "module": "./dist/xstate-angular.development.esm.js",
+        "import": "./dist/xstate-angular.development.cjs.mjs",
+        "default": "./dist/xstate-angular.development.cjs.js"
+      },
+      "module": "./dist/xstate-angular.esm.js",
+      "import": "./dist/xstate-angular.cjs.mjs",
+      "default": "./dist/xstate-angular.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "imports": {
+    "#is-development": {
+      "development": "./src/true.ts",
+      "default": "./src/false.ts"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statelyai/xstate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/statelyai/xstate/issues"
+  },
+  "peerDependencies": {
+    "@angular/core": "^17.0.0",
+    "xstate": "^5.9.1"
+  },
+  "peerDependenciesMeta": {
+    "xstate": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/common": "^17.0.0",
+    "@angular/compiler": "^17.0.0",
+    "@angular/compiler-cli": "^17.0.0",
+    "@angular/core": "^17.0.0",
+    "@angular/platform-browser": "^17.0.0",
+    "@angular/platform-browser-dynamic": "^17.0.0",
+    "ng-packagr": "^17.0.0",
+    "rxjs": "^7.8.1",
+    "tslib": "2.6.2",
+    "typescript": "^5.4.2",
+    "xstate": "5.9.1",
+    "zone.js": "0.14.4"
+  }
+}

packages/xstate-angular/src/false.ts

@@ -0,0 +1 @@
+export default false;

packages/xstate-angular/src/index.ts

@@ -0,0 +1,4 @@
+export { useActor } from './useActor.ts';
+export { useActorRef } from './useActorRef.ts';
+export { useMachine } from './useMachine.ts';
+export { useSelector } from './useSelector.ts';

packages/xstate-angular/src/true.ts

@@ -0,0 +1 @@
+export default true;

packages/xstate-angular/src/useActor.ts

@@ -0,0 +1,51 @@
+import {
+  Actor,
+  ActorOptions,
+  AnyActorLogic,
+  Snapshot,
+  SnapshotFrom
+} from 'xstate';
+import {
+  Injectable,
+  Signal,
+  signal,
+  Type,
+  WritableSignal
+} from '@angular/core';
+import { useSelector } from './useSelector.ts';
+import { useActorRef } from './useActorRef.ts';
+
+export function useActor<TLogic extends AnyActorLogic>(
+  actorLogic: TLogic,
+  _options?: ActorOptions<TLogic> & { providedIn: 'root' }
+): Type<ActorStoreProps<TLogic>> {
+  const { providedIn, ...options } = _options ?? {};
+
+  @Injectable({ providedIn: providedIn ?? null })
+  class ActorStore implements ActorStoreProps<TLogic> {
+    public actorRef: Actor<TLogic>;
+    private _snapshot: WritableSignal<SnapshotFrom<TLogic>>;
+    public send: Actor<TLogic>['send'];
+
+    public get snapshot() {
+      return this._snapshot.asReadonly();
+    }
+
+    constructor() {
+      const listener = (nextSnapshot: Snapshot<unknown>) => {
+        this._snapshot?.set(nextSnapshot as any);
+      };
+
+      this.actorRef = useActorRef(actorLogic, options, listener);
+      this._snapshot = signal(useSelector(this.actorRef as any, (s) => s)());
+      this.send = this.actorRef.send;
+    }
+  }
+  return ActorStore;
+}
+
+export interface ActorStoreProps<TLogic extends AnyActorLogic> {
+  actorRef: Actor<TLogic>;
+  snapshot: Signal<SnapshotFrom<TLogic>>;
+  send: Actor<TLogic>['send'];
+}

packages/xstate-angular/src/useActorRef.ts

@@ -0,0 +1,45 @@
+import {
+  Actor,
+  ActorOptions,
+  AnyActorLogic,
+  createActor,
+  Observer,
+  SnapshotFrom,
+  Subscription,
+  toObserver
+} from 'xstate';
+import {
+  afterNextRender,
+  AfterRenderPhase,
+  DestroyRef,
+  inject
+} from '@angular/core';
+
+export function useActorRef<TLogic extends AnyActorLogic>(
+  actorLogic: TLogic,
+  options: ActorOptions<TLogic> = {},
+  observerOrListener?:
+    | Observer<SnapshotFrom<TLogic>>
+    | ((value: SnapshotFrom<TLogic>) => void)
+): Actor<TLogic> {
+  const actorRef = createActor(actorLogic, options);
+
+  let sub: Subscription;
+  if (observerOrListener) {
+    sub = actorRef.subscribe(toObserver(observerOrListener));
+  }
+
+  afterNextRender(
+    () => {
+      actorRef.start();
+    },
+    { phase: AfterRenderPhase.Read }
+  );
+
+  inject(DestroyRef).onDestroy(() => {
+    actorRef.stop();
+    sub?.unsubscribe();
+  });
+
+  return actorRef;
+}

packages/xstate-angular/src/useMachine.ts

@@ -0,0 +1,12 @@
+import { ActorOptions, AnyStateMachine } from 'xstate';
+import { useActor } from './useActor.ts';
+
+/**
+ * @alias useActor
+ */
+export function useMachine<TMachine extends AnyStateMachine>(
+  actorLogic: TMachine,
+  options?: ActorOptions<TMachine> & { providedIn: 'root' }
+) {
+  return useActor(actorLogic, options);
+}

packages/xstate-angular/src/useSelector.ts

@@ -0,0 +1,26 @@
+import { ActorRef, SnapshotFrom } from 'xstate';
+import { computed, Signal, signal } from '@angular/core';
+
+function defaultCompare<T>(a: T, b: T) {
+  return a === b;
+}
+
+export function useSelector<TActor extends ActorRef<any, any> | undefined, T>(
+  actor: TActor,
+  selector: (
+    snapshot: TActor extends ActorRef<any, any>
+      ? SnapshotFrom<TActor>
+      : undefined
+  ) => T,
+  compare: (a: T, b: T) => boolean = defaultCompare
+): Signal<T> {
+  const actorRefRef = signal(actor);
+  return computed(
+    () => {
+      const actorRef = actorRefRef();
+      const snapshot = actorRef?.getSnapshot();
+      return selector(snapshot);
+    },
+    { equal: compare }
+  );
+}