First Draft for @xstate/angular

packages/core/src/index.ts

@@ -27,7 +27,8 @@ export {
   getAllOwnEventDescriptors as __unsafe_getAllOwnEventDescriptors,
   matchesState,
   pathToStateValue,
-  toObserver
+  toObserver,
+  isActorLogic
 } from './utils.ts';
 export {
   Actor,

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,53 @@
+# @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' }
+    }
+  }
+});
+
+@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({providedIn: "root", }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,70 @@
+{
+  "name": "@xstate/angular",
+  "version": "3.1.1",
+  "description": "XState tools for Vue",
+  "keywords": [
+    "state",
+    "machine",
+    "statechart",
+    "scxml",
+    "state",
+    "graph",
+    "angular"
+  ],
+  "type": "module",
+  "author": "David Khourshid <[email protected]>",
+  "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://[email protected]/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/core": "^17.0.0",
+    "@testing-library/angular": "15.2.0",
+    "@testing-library/jest-dom": "^6.1.4",
+    "ng-packagr": "^17.0.0",
+    "xstate": "5.9.1"
+  }
+}

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,73 @@
+import {
+  Actor,
+  ActorOptions,
+  AnyActorLogic,
+  Snapshot,
+  SnapshotFrom,
+  isActorLogic
+} from 'xstate';
+import {
+  Injectable,
+  Signal,
+  signal,
+  Type,
+  WritableSignal
+} from '@angular/core';
+import { useSelector } from './useSelector.ts';
+import { useActorRef } from './useActorRef.ts';
+
+export interface UseActorConfig {
+  providedIn: 'root';
+}
+
+export function useActor<TLogic extends AnyActorLogic>(
+  provided: UseActorConfig,
+  actorLogic: TLogic,
+  options?: ActorOptions<TLogic>
+): Type<ActorStoreProps<TLogic>>;
+export function useActor<TLogic extends AnyActorLogic>(
+  actorLogic: TLogic,
+  options?: ActorOptions<TLogic>
+): Type<ActorStoreProps<TLogic>>;
+export function useActor<TLogic extends AnyActorLogic>(
+  providedInOrActor: UseActorConfig | TLogic,
+  actorLogicOrOptions?: TLogic | ActorOptions<TLogic>,
+  _options?: ActorOptions<TLogic>
+): Type<ActorStoreProps<TLogic>> {
+  const providedIn =
+    'providedIn' in providedInOrActor ? providedInOrActor.providedIn : null;
+
+  const [actorLogic, options] = (
+    isActorLogic(providedInOrActor)
+      ? [providedInOrActor, actorLogicOrOptions]
+      : [actorLogicOrOptions, _options]
+  ) as [TLogic, ActorOptions<TLogic>];
+
+  @Injectable({ providedIn })
+  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,34 @@
+import {
+  Actor,
+  ActorOptions,
+  AnyActorLogic,
+  createActor,
+  Observer,
+  SnapshotFrom,
+  Subscription,
+  toObserver
+} from 'xstate';
+import { 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));
+  }
+  actorRef.start();
+
+  inject(DestroyRef).onDestroy(() => {
+    actorRef.stop();
+    sub?.unsubscribe();
+  });
+
+  return actorRef;
+}

packages/xstate-angular/src/useMachine.ts

@@ -0,0 +1,33 @@
+import { ActorOptions, isActorLogic, AnyStateMachine } from 'xstate';
+import { ActorStoreProps, useActor, UseActorConfig } from './useActor.ts';
+import { Type } from '@angular/core';
+
+export function useMachine<TMachine extends AnyStateMachine>(
+  provided: UseActorConfig,
+  actorLogic: TMachine,
+  options?: ActorOptions<TMachine>
+): Type<ActorStoreProps<TMachine>>;
+export function useMachine<TMachine extends AnyStateMachine>(
+  actorLogic: TMachine,
+  options?: ActorOptions<TMachine>
+): Type<ActorStoreProps<TMachine>>;
+/**
+ * @alias useActor
+ */
+export function useMachine<TMachine extends AnyStateMachine>(
+  providedInOrActor: UseActorConfig | TMachine,
+  actorLogicOrOptions?: TMachine | ActorOptions<TMachine>,
+  _options?: ActorOptions<TMachine>
+): Type<ActorStoreProps<TMachine>> {
+  if ('providedIn' in providedInOrActor && isActorLogic(actorLogicOrOptions)) {
+    return useActor(providedInOrActor, actorLogicOrOptions, _options) as Type<
+      ActorStoreProps<TMachine>
+    >;
+  } else if (isActorLogic(providedInOrActor)) {
+    return useActor(providedInOrActor, actorLogicOrOptions) as Type<
+      ActorStoreProps<TMachine>
+    >;
+  } else {
+    throw new Error('useMachine: parameters do not match type signature');
+  }
+}

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