@systemfsoftware/xstate-react 0.0.0-stage → 7.0.0-beta.5

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @systemfsoftware/xstate-react
+
+# @systemfsoftware/xstate-react@7.0.0-beta.5
+
+Add `@systemfsoftware/xstate-react`, the React bindings for `@systemfsoftware/xstate`, forked from statelyai/xstate's `next` branch at 2146ae26 (MIT). It behaves like upstream's 7.0.0-alpha.4. Under `exactOptionalPropertyTypes`, optional members that can hold `undefined` declare it explicitly. It has no `effect` dependency or peer: the Effect 4.0.1 peer floor applies only to `@systemfsoftware/xstate-effect` and `@systemfsoftware/xstate-test`.

package/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.
+

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# @xstate/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> `@systemfsoftware/xstate-react` is forked from [statelyai/xstate](https://github.com/statelyai/xstate) (`packages/xstate-react`, branch `next` at `2146ae26ebfc7e6a624b3a1f237f9e6ddc30b9f5`), MIT. The text below is upstream's.
+
+This package contains utilities for using [XState](https://github.com/statelyai/xstate) with [React](https://github.com/facebook/react/).
+
+- [Read the full documentation in the XState docs](https://stately.ai/docs/xstate-react).
+- [Read our contribution guidelines](https://github.com/statelyai/xstate/blob/main/CONTRIBUTING.md).
+
+## Quick start
+
+1. Install `@systemfsoftware/xstate-react`:
+
+```bash
+nix build github:systemfsoftware/xstate#xstate-react
+```
+
+See the root README's [Install](../../README.md#install) section for wiring a catalog entry. Its peer `@systemfsoftware/xstate` comes from the same flake (`#xstate`), and `react` from your own package manager.
+
+2. Import the `useMachine` hook:
+
+```tsx
+import { useMachine } from '@xstate/react'
+import { createMachine } from 'xstate'
+
+const toggleMachine = createMachine({
+  id: 'toggle',
+  initial: 'inactive',
+  states: {
+    inactive: {
+      on: { TOGGLE: { target: 'active' } },
+    },
+    active: {
+      on: { TOGGLE: { target: 'inactive' } },
+    },
+  },
+})
+
+export const Toggler = () => {
+  const [state, send] = useMachine(toggleMachine)
+
+  return (
+    <button onClick={() => send({ type: 'TOGGLE' })}>
+      {state.value === 'inactive'
+        ? 'Click to activate'
+        : 'Active! Click to deactivate'}
+    </button>
+  )
+}
+```
+
+## Observing an actor
+
+<!-- observer lifecycle from src/useActorRef.ts -->
+
+Pass a snapshot listener or observer as the third argument to `useActorRef(logic, options, observer)`. It subscribes before the actor starts. When the hook replaces the actor (after an external stop, or a Fast Refresh that cannot keep it), the observer follows the replacement, even when the callback identity stays the same. Unmounting unsubscribes the observer and stops the actor.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+import { Actor, ActorOptions, AnyActorLogic, AnyActorRef, AnyStateMachine, ConditionalRequired, IsNotNever, Observer, RequiredActorOptionsFor, RequiredActorOptionsKeys, SnapshotFrom, StateFrom } from "@systemfsoftware/xstate";
+export declare function createActorContext<TLogic extends AnyActorLogic>(actorLogic: TLogic, actorOptions?: ActorOptions<TLogic>): {
+  useSelector: <T>(selector: (snapshot: SnapshotFrom<TLogic>) => T, compare?: (a: T, b: T) => boolean) => T;
+  useActorRef: () => Actor<TLogic>;
+  Provider: (props: {
+    children: React.ReactNode;
+    options?: ActorOptions<TLogic>;
+    /** @deprecated Use `logic` instead. */
+    machine?: never;
+    logic?: TLogic;
+  }) => React.ReactElement<any, any>;
+};
+export declare function shallowEqual(objA: any, objB: any): boolean;
+export declare function useActor<TLogic extends AnyActorLogic>(logic: TLogic, ...[options]: ConditionalRequired<[options?: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>], IsNotNever<RequiredActorOptionsKeys<TLogic>>>): [SnapshotFrom<TLogic>, Actor<TLogic>['send'], Actor<TLogic>];
+export declare function useActorRef<TLogic extends AnyActorLogic>(machine: TLogic, ...[options, observerOrListener]: IsNotNever<RequiredActorOptionsKeys<TLogic>> extends true ? [options: ActorOptions<TLogic> & RequiredActorOptionsFor<TLogic>, observerOrListener?: Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void)] : [options?: ActorOptions<TLogic>, observerOrListener?: Observer<SnapshotFrom<TLogic>> | ((value: SnapshotFrom<TLogic>) => void)]): Actor<TLogic>;
+export declare function useSelector<TActor extends Pick<AnyActorRef, 'subscribe' | 'getSnapshot'> | undefined, T>(actor: TActor, selector: (snapshot: TActor extends {
+  getSnapshot(): infer TSnapshot;
+} ? TSnapshot : undefined) => T, compare?: (a: T, b: T) => boolean): T;
+/** @alias useActor */
+export declare function useMachine<TMachine extends AnyStateMachine>(machine: TMachine, ...[options]: ConditionalRequired<[options?: ActorOptions<TMachine> & RequiredActorOptionsFor<TMachine>], IsNotNever<RequiredActorOptionsKeys<TMachine>>>): [StateFrom<TMachine>, Actor<TMachine>['send'], Actor<TMachine>];

package/dist/index.mjs

@@ -0,0 +1,155 @@
+import * as React from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createActor, toObserver } from "@systemfsoftware/xstate";
+import useIsomorphicLayoutEffect from "use-isomorphic-layout-effect";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+import { useSyncExternalStore } from "use-sync-external-store/shim";
+// src/useActorRef.ts
+function useIdleActorRef(logic, ...[options]) {
+	const [actorRef, setActorRef] = useState(() => {
+		return createActor(logic, options);
+	});
+	const refreshSignal = useMemo(() => ({}), []);
+	const refreshSignalRef = useRef(refreshSignal);
+	useIsomorphicLayoutEffect(() => {
+		const currentLogic = actorRef.logic;
+		refreshSignalRef.current;
+		refreshSignalRef.current = refreshSignal;
+		if (logic.config === currentLogic.config) {
+			currentLogic.sources = logic.sources;
+			return;
+		}
+	});
+	return [actorRef, setActorRef];
+}
+function useActorLifecycle(actorRef, setActorRef, createReplacement) {
+	const pendingStopsRef = useRef(/* @__PURE__ */ new Map());
+	useEffect(() => {
+		const cancelPendingStop = pendingStopsRef.current.get(actorRef);
+		if (cancelPendingStop) {
+			cancelPendingStop();
+			pendingStopsRef.current.delete(actorRef);
+		}
+		if (actorRef._processingStatus === 2 && actorRef.getSnapshot()?.status === "stopped") {
+			setActorRef(createReplacement());
+			return;
+		}
+		actorRef.start();
+		return () => {
+			let canceled = false;
+			const cancel = () => {
+				canceled = true;
+			};
+			pendingStopsRef.current.set(actorRef, cancel);
+			queueMicrotask(() => {
+				if (!canceled) actorRef.stop();
+				if (pendingStopsRef.current.get(actorRef) === cancel) pendingStopsRef.current.delete(actorRef);
+			});
+		};
+	}, [actorRef]);
+}
+function useActorRef(machine, ...[options, observerOrListener]) {
+	const [actorRef, setActorRef] = useIdleActorRef(machine, ...options === void 0 ? [] : [options]);
+	useEffect(() => {
+		if (!observerOrListener) return;
+		const sub = actorRef.subscribe(toObserver(observerOrListener));
+		return () => {
+			sub.unsubscribe();
+		};
+	}, [actorRef, observerOrListener]);
+	useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, actorRef.options));
+	return actorRef;
+}
+// src/useSelector.ts
+function defaultCompare(a, b) {
+	return a === b;
+}
+function useSelector(actor, selector, compare = defaultCompare) {
+	const subscribe = useCallback((handleStoreChange) => {
+		if (!actor) return () => {};
+		const { unsubscribe } = actor.subscribe({
+			next: handleStoreChange,
+			error: handleStoreChange
+		});
+		return unsubscribe;
+	}, [actor]);
+	const boundGetSnapshot = useCallback(() => {
+		const snapshot = actor?.getSnapshot();
+		if (snapshot && "status" in snapshot && snapshot.status === "error") throw snapshot.error;
+		return snapshot;
+	}, [actor]);
+	return useSyncExternalStoreWithSelector(subscribe, boundGetSnapshot, boundGetSnapshot, selector, compare);
+}
+// src/createActorContext.ts
+function createActorContext(actorLogic, actorOptions) {
+	const ReactContext = React.createContext(null);
+	const OriginalProvider = ReactContext.Provider;
+	function Provider({ children, logic: providedLogic = actorLogic, machine, options: providedOptions }) {
+		if (machine) throw new Error(`The "machine" prop has been deprecated. Please use "logic" instead.`);
+		const actor = useActorRef(providedLogic, {
+			...actorOptions,
+			...providedOptions
+		});
+		return React.createElement(OriginalProvider, {
+			value: actor,
+			children
+		});
+	}
+	Provider.displayName = `ActorProvider`;
+	function useContext() {
+		const actor = React.useContext(ReactContext);
+		if (!actor) throw new Error(`You used a hook from "${Provider.displayName}" but it's not inside a <${Provider.displayName}> component.`);
+		return actor;
+	}
+	function useSelector$1(selector, compare) {
+		return useSelector(useContext(), selector, compare);
+	}
+	return {
+		Provider,
+		useActorRef: useContext,
+		useSelector: useSelector$1
+	};
+}
+// src/shallowEqual.ts
+function is(x, y) {
+	if (x === y) return x !== 0 || y !== 0 || 1 / x === 1 / y;
+	else return x !== x && y !== y;
+}
+function shallowEqual(objA, objB) {
+	if (is(objA, objB)) return true;
+	if (typeof objA !== "object" || objA === null || typeof objB !== "object" || objB === null) return false;
+	const keysA = Object.keys(objA);
+	const keysB = Object.keys(objB);
+	if (keysA.length !== keysB.length) return false;
+	for (const key of keysA) if (!Object.prototype.hasOwnProperty.call(objB, key) || !is(objA[key], objB[key])) return false;
+	return true;
+}
+// src/useActor.ts
+function useActor(logic, ...[options]) {
+	const [actorRef, setActorRef] = useIdleActorRef(logic, ...options === void 0 ? [] : [options]);
+	const getSnapshot = useCallback(() => {
+		return actorRef.getSnapshot();
+	}, [actorRef]);
+	const subscribe = useCallback((handleStoreChange) => {
+		const { unsubscribe } = actorRef.subscribe({
+			next: handleStoreChange,
+			error: handleStoreChange
+		});
+		return unsubscribe;
+	}, [actorRef]);
+	const actorSnapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+	const snapshotWithStatus = "status" in actorSnapshot ? actorSnapshot : void 0;
+	if (snapshotWithStatus?.status === "error") throw snapshotWithStatus.error;
+	useActorLifecycle(actorRef, setActorRef, () => createActor(actorRef.logic, options));
+	return [
+		actorSnapshot,
+		actorRef.send,
+		actorRef
+	];
+}
+// src/useMachine.ts
+/** @alias useActor */
+function useMachine(machine, ...[options]) {
+	return useActor(machine, ...options === void 0 ? [] : [options]);
+}
+export { createActorContext, shallowEqual, useActor, useActorRef, useMachine, useSelector };

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@systemfsoftware/xstate-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "license": "MIT",
+  "version": "7.0.0-beta.5",
+  "author": "Ryan Lee <drdgvhbh@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/systemfsoftware/xstate.git",
+    "directory": "packages/xstate-react"
+  },
+  "homepage": "https://github.com/systemfsoftware/xstate/tree/main/packages/xstate-react#readme",
+  "bugs": "https://github.com/systemfsoftware/xstate/issues",
+  "description": "React hooks for XState actors — forked under systemfsoftware from statelyai/xstate (@xstate/react at 2146ae26).",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "use-isomorphic-layout-effect": "1.2.1",
+    "use-sync-external-store": "1.7.0"
+  },
+  "peerDependencies": {
+    "@systemfsoftware/xstate": "^6.0.0-beta.65",
+    "react": "^19.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@systemfsoftware/xstate": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/tsgo": "0.64.1",
+    "@microsoft/api-extractor": "7.59.1",
+    "@opentelemetry/api": "1.9.1",
+    "@systemfsoftware/arethetypeswrong-cli": "file:../../.deps/arethetypeswrong-cli.tgz",
+    "@systemfsoftware/tsconfig": "file:../../.deps/tsconfig.tgz",
+    "@systemfsoftware/vitest": "file:../../.deps/vitest.tgz",
+    "@systemfsoftware/xstate": "^6.0.0-beta.65",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "24.19.1",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@types/use-sync-external-store": "1.7.0",
+    "happy-dom": "20.14.5",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3",
+    "zod": "3.25.76"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "imports": {
+    "#is-development": {
+      "development": "./src/true.ts",
+      "default": "./src/false.ts"
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsdown -l warn && pnpm api:check",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "lint:tsgo": "effect-tsgo diagnostics --project tsconfig.app.json --format ${TSGO_FORMAT:-text} && effect-tsgo diagnostics --project tsconfig.test.json --format ${TSGO_FORMAT:-text}",
+    "attw": "attw --pack .",
+    "api:check": "api-extractor run",
+    "api:update": "api-extractor run --local"
+  }
 }