@systemfsoftware/xstate-store-react 0.0.0-stage → 2.1.0-beta.4

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @systemfsoftware/xstate-store-react
+
+# @systemfsoftware/xstate-store-react@2.1.0-beta.4
+
+Add `@systemfsoftware/xstate-store-react`, the React bindings for `@systemfsoftware/xstate-store`, forked from statelyai/xstate's `next` branch at 2146ae26 (MIT). It behaves like upstream's 2.1.0-alpha.3. 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,190 @@
-# Temporary Holding Version
+# @xstate/store-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-store-react` is forked from [statelyai/xstate](https://github.com/statelyai/xstate) (`packages/xstate-store-react`, branch `next` at `2146ae26ebfc7e6a624b3a1f237f9e6ddc30b9f5`), MIT. The text below is upstream's.
+
+React adapter for [@xstate/store](https://stately.ai/docs/xstate-store).
+
+## Installation
+
+```bash
+nix build github:systemfsoftware/xstate#xstate-store-react
+```
+
+See the root README's [Install](../../README.md#install) section for wiring a catalog entry. Its peer `react` comes from your own package manager.
+
+## Quickstart
+
+```tsx
+import { createStore, useSelector } from '@xstate/store-react'
+// ...
+
+const store = createStore({
+  context: { count: 0 },
+  on: {
+    inc: (ctx) => ({ ...ctx, count: ctx.count + 1 }),
+  },
+})
+
+const App = () => {
+  const count = useSelector(store, (s) => s.context.count)
+
+  return <button onClick={() => store.send({ type: 'inc' })}>Count: {count}</button>
+}
+```
+
+## API
+
+<!-- selector comparison semantics from src/index.ts -->
+
+### `useSelector(store, selector?, compare?)`
+
+Subscribes to a store and returns a selected value.
+
+```tsx
+import { createStore, useSelector } from '@xstate/store-react'
+// ...
+
+const store = createStore({
+  context: { count: 0 },
+  on: {
+    inc: (ctx) => ({ ...ctx, count: ctx.count + 1 }),
+  },
+})
+
+const App = () => {
+  const count = useSelector(store, (s) => s.context.count)
+  // or without selector (returns full snapshot)
+  const snapshot = useSelector(store)
+  // ...
+}
+```
+
+**Arguments:**
+
+- `store` - Store or other readable value created with `createStore()`
+- `selector?` - Function to select a value from snapshot
+- `compare?` - Equality function (default: `===`). Also applies to the full snapshot when `selector` is `undefined`.
+
+**Returns:** Selected value (re-renders on change)
+
+---
+
+<!-- useStore overloads and inspection behavior from packages/xstate-store-react/src/index.ts -->
+
+### `useStore(definition, options?)`
+
+Creates a store instance scoped to a component.
+
+```tsx
+import { useSelector, useStore } from '@xstate/store-react'
+// ...
+
+const App = () => {
+  const store = useStore({
+    context: { count: 0 },
+    on: {
+      inc: (ctx) => ({ ...ctx, count: ctx.count + 1 }),
+    },
+  })
+
+  const count = useSelector(store, (s) => s.context.count)
+  // ...
+}
+```
+
+To wire up an inspector, pass a stable `inspect` callback. The inspector is subscribed while the option is provided and unsubscribed when it is removed or the component unmounts. Stores emit `@xstate.transition` events. With `@statelyai/inspect`, forward these through its public `snapshot()` method; its `inspect` observer accepts the XState v5 inspection protocol.
+
+```tsx
+import { createBrowserInspector } from '@statelyai/inspect'
+import type { StoreInspectionEvent } from '@xstate/store'
+
+// Outside the component: keep the callback stable between renders.
+const inspector = createBrowserInspector()
+const inspectStore = (event: StoreInspectionEvent) => {
+  inspector.snapshot(event.actorRef, event.snapshot, { event: event.event })
+}
+
+// Inside the component:
+const store = useStore(
+  {
+    context: { count: 0 },
+    on: {
+      inc: (ctx) => ({ ...ctx, count: ctx.count + 1 }),
+    },
+  },
+  { inspect: inspectStore },
+)
+```
+
+**Arguments:**
+
+- `definition` - Store configuration object, or store logic created with `createStoreLogic()` (followed by its `input`)
+- `options?` - Options object:
+  - `inspect?` - Observer or callback that receives [inspection events](https://stately.ai/docs/inspection) from the store
+
+**Returns:** Store instance (stable across re-renders)
+
+---
+
+### `useAtom(atom, selector?, compare?)`
+
+Subscribes to an atom and returns its value.
+
+```tsx
+import { createAtom, useAtom } from '@xstate/store-react'
+// ...
+
+const countAtom = createAtom(0)
+
+const App = () => {
+  const count = useAtom(countAtom)
+
+  return <button onClick={() => countAtom.set((c) => c + 1)}>{count}</button>
+}
+```
+
+**Arguments:**
+
+- `atom` - Atom created with `createAtom()`
+- `selector?` - Selector function
+- `compare?` - Equality function
+
+**Returns:** Atom value (re-renders on change)
+
+---
+
+### `createStoreHook(definition)`
+
+Creates a custom hook that returns `[selectedValue, store]`.
+
+```tsx
+import { createStoreHook } from '@xstate/store-react'
+// ...
+
+const useCountStore = createStoreHook({
+  context: { count: 0 },
+  on: {
+    inc: (ctx, e: { by: number }) => ({ ...ctx, count: ctx.count + e.by }),
+  },
+})
+
+const App = () => {
+  const [count, store] = useCountStore((s) => s.context.count)
+
+  return <button onClick={() => store.trigger.inc({ by: 1 })}>{count}</button>
+}
+```
+
+**Arguments:**
+
+- `definition` - Store configuration object
+
+**Returns:** Custom hook function
+
+---
+
+## Re-exports
+
+All exports from `@xstate/store` are re-exported, including `createStore`, `createAtom`, and more.
+
+See the [XState Store docs](https://stately.ai/docs/xstate-store) for the full API, and the [React-specific docs](https://stately.ai/docs/xstate-store#react) for more React examples.

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+import { AnyAtomConfig, AnyStoreConfig, AnyStoreLogicCreator, AtomConfig, BaseAtom, ContextFromStoreConfig, InputFromAtomConfig, InputFromStoreLogicCreator, Observer, Readable, StoreFromStoreConfig, StoreFromStoreLogicCreator, StoreInspectionEvent, StoreSnapshot, ValueFromAtomConfig } from "@systemfsoftware/xstate-store";
+export * from "@systemfsoftware/xstate-store";
+type StoreDefinition = AnyStoreConfig | AnyStoreLogicCreator;
+type StoreFromStoreDefinition<TDefinition extends StoreDefinition> = TDefinition extends AnyStoreLogicCreator ? StoreFromStoreLogicCreator<TDefinition> : TDefinition extends AnyStoreConfig ? StoreFromStoreConfig<TDefinition> : never;
+interface UseStoreOptions {
+  /**
+   * An observer or callback that receives [inspection
+   * events](https://stately.ai/docs/inspection) from the store. Subscribed
+   * while provided; stable across re-renders.
+   */
+  inspect?: Observer<StoreInspectionEvent> | ((inspectionEvent: StoreInspectionEvent) => void);
+}
+type UseStoreArgs<TDefinition extends StoreDefinition> = TDefinition extends AnyStoreLogicCreator ? undefined extends InputFromStoreLogicCreator<TDefinition> ? [logic: TDefinition, input?: InputFromStoreLogicCreator<TDefinition>, options?: UseStoreOptions] : [logic: TDefinition, input: InputFromStoreLogicCreator<TDefinition>, options?: UseStoreOptions] : [definition: TDefinition, options?: UseStoreOptions];
+type AtomDefinition = BaseAtom<any> | AnyAtomConfig;
+type AtomStateFromDefinition<TDefinition extends AtomDefinition> = TDefinition extends AnyAtomConfig ? readonly [value: ValueFromAtomConfig<TDefinition>, atom: ReturnType<TDefinition['createAtom']>] : TDefinition extends BaseAtom<infer TValue> ? readonly [value: TValue, atom: TDefinition] : never;
+type UseAtomStateArgs<TDefinition extends AtomDefinition> = TDefinition extends AnyAtomConfig ? undefined extends InputFromAtomConfig<TDefinition> ? [config: TDefinition, input?: InputFromAtomConfig<TDefinition>] : [config: TDefinition, input: InputFromAtomConfig<TDefinition>] : [atom: TDefinition];
+type AtomConfigInput<TInput> = undefined extends TInput ? [input?: TInput] : [input: TInput];
+/**
+ * A React hook that subscribes to the `store` and selects a value from the
+ * store's snapshot via a selector function, with an optional compare function.
+ *
+ * @example
+ *
+ * ```ts
+ * function Component() {
+ *   const count = useSelector(store, (s) => s.count);
+ *
+ *   return <div>{count}</div>;
+ * }
+ * ```
+ *
+ * @param store The store, created from `createStore(…)`
+ * @param selector A function which takes in the `snapshot` and returns a
+ *   selected value
+ * @param compare An optional function which compares the selected value to the
+ *   previous value
+ * @returns The selected value
+ */
+export declare function useSelector<TSnapshot, T>(store: Readable<TSnapshot>, selector: (snapshot: TSnapshot) => T, compare?: (a: T, b: T) => boolean): T;
+/**
+ * A React hook that subscribes to the `store` and selects a value from the
+ * store's snapshot via an optional selector function (identity by default),
+ * with an optional compare function.
+ *
+ * @example
+ *
+ * ```ts
+ * function Component() {
+ *   const countSnapshot = useSelector(store);
+ *
+ *   return <div>{countSnapshot.context.count}</div>;
+ * }
+ * ```
+ *
+ * @param store The store, created from `createStore(…)`
+ * @param selector An optional function which takes in the `snapshot` and
+ *   returns a selected value
+ * @param compare An optional function which compares the selected value to the
+ *   previous value
+ * @returns The selected value
+ */
+export declare function useSelector<TSnapshot>(store: Readable<TSnapshot>, selector?: undefined, compare?: (a: TSnapshot | undefined, b: TSnapshot | undefined) => boolean): TSnapshot;
+/**
+ * Creates a stable store instance for the lifetime of a React component.
+ *
+ * Pass `options.inspect` to subscribe an inspector to the store. The
+ * subscription is removed when the inspector is removed or on unmount.
+ *
+ * @example
+ *
+ * ```ts
+ * function Counter() {
+ *   const store = useStore(
+ *     {
+ *       context: { count: 0 },
+ *       on: { inc: (ctx) => ({ count: ctx.count + 1 }) }
+ *     },
+ *     { inspect: inspector.inspect }
+ *   );
+ *   // …
+ * }
+ * ```
+ */
+export declare function useStore<TDefinition extends StoreDefinition>(...args: UseStoreArgs<TDefinition>): StoreFromStoreDefinition<TDefinition>;
+/**
+ * A React hook that subscribes to the `atom` and returns the current value of
+ * the atom.
+ *
+ * @example
+ *
+ * ```ts
+ * const atom = createAtom(0);
+ *
+ * const Component = () => {
+ *   const count = useAtom(atom);
+ *
+ *   return (
+ *     <div>
+ *       <div>{count}</div>
+ *       <button onClick={() => atom.set((c) => c + 1)}>Increment</button>
+ *     </div>
+ *   );
+ * };
+ * ```
+ *
+ * @param atom The atom, created from `createAtom(…)`
+ * @param selector An optional function which takes in the `snapshot` and
+ *   returns a selected value
+ * @param compare An optional function which compares the selected value to the
+ *   previous value
+ */
+export declare function useAtom<T>(atom: BaseAtom<T>): T;
+export declare function useAtom<TValue, TInput>(config: AtomConfig<TValue, TInput>, ...input: AtomConfigInput<TInput>): TValue;
+export declare function useAtom<T, S>(atom: BaseAtom<T>, selector: (snapshot: T) => S, compare?: (a: S, b: S) => boolean): S;
+/**
+ * Creates or subscribes to an atom for the lifetime of a React component.
+ *
+ * Pass an existing atom to receive `[value, atom]`, or pass an atom config
+ * created with `createAtomConfig(...)` to create a stable local atom.
+ */
+export declare function useAtomState<TDefinition extends AtomDefinition>(...[definition, input]: UseAtomStateArgs<TDefinition>): AtomStateFromDefinition<TDefinition>;
+/**
+ * Creates a custom hook that returns the selected value and the store from a
+ * store configuration object.
+ *
+ * @example
+ *
+ * ```ts
+ * const useCountStore = createStoreHook({
+ *   context: { count: 0 },
+ *   on: {
+ *     inc: (context, event: { by: number }) => ({
+ *       ...context,
+ *       count: context.count + event.by
+ *     })
+ *   }
+ * });
+ *
+ * function Component() {
+ *   const [count, store] = useCountStore(s => s.context.count);
+ *
+ *   return (
+ *     <div>
+ *       {count}
+ *       <button onClick={() => store.trigger.inc({ by: 1 })}>+</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param definition The store configuration object
+ * @returns A custom hook that returns [selectedValue, store]
+ */
+export declare function createStoreHook<TDefinition extends AnyStoreConfig>(definition: TDefinition): {
+  (): [StoreSnapshot<ContextFromStoreConfig<TDefinition>>, StoreFromStoreConfig<TDefinition>];
+  <T>(selector: (snapshot: StoreSnapshot<ContextFromStoreConfig<TDefinition>>) => T, compare?: (a: T, b: T) => boolean): [T, StoreFromStoreConfig<TDefinition>];
+};

package/dist/index.mjs

@@ -0,0 +1,124 @@
+import { createStore, isAtom } from "@systemfsoftware/xstate-store";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+export * from "@systemfsoftware/xstate-store";
+// src/index.ts
+function defaultCompare(a, b) {
+	return a === b;
+}
+function identity(snapshot) {
+	return snapshot;
+}
+function useSelectorWithCompare(selector, compare) {
+	const previous = useRef(void 0);
+	return (snapshot) => {
+		const next = selector(snapshot);
+		return previous.current !== void 0 && compare(previous.current, next) ? previous.current : previous.current = next;
+	};
+}
+function createStoreFromDefinition(definition) {
+	return createStore(definition);
+}
+function useSelector(store, selector, compare = defaultCompare) {
+	const subscribe = useCallback((handleStoreChange) => store.subscribe(handleStoreChange).unsubscribe, [store]);
+	const selectorWithCompare = useSelectorWithCompare(selector ?? identity, compare);
+	return useSyncExternalStore(subscribe, () => selectorWithCompare(store.get()), () => selectorWithCompare(store.get()));
+}
+/**
+* Creates a stable store instance for the lifetime of a React component.
+*
+* Pass `options.inspect` to subscribe an inspector to the store. The
+* subscription is removed when the inspector is removed or on unmount.
+*
+* @example
+*
+* ```ts
+* function Counter() {
+*   const store = useStore(
+*     {
+*       context: { count: 0 },
+*       on: { inc: (ctx) => ({ count: ctx.count + 1 }) }
+*     },
+*     { inspect: inspector.inspect }
+*   );
+*   // …
+* }
+* ```
+*/
+function useStore(...args) {
+	const [definition] = args;
+	const isLogic = "createStore" in definition;
+	const input = isLogic ? args[1] : void 0;
+	const options = isLogic ? args[2] : args[1];
+	const storeRef = useRef(void 0);
+	if (!storeRef.current) storeRef.current = isLogic ? definition.createStore(input) : createStoreFromDefinition(definition);
+	const inspectRef = useRef(options?.inspect);
+	inspectRef.current = options?.inspect;
+	const shouldInspect = options?.inspect !== void 0;
+	useEffect(() => {
+		if (!inspectRef.current) return;
+		return storeRef.current.inspect((inspectionEvent) => {
+			const inspect = inspectRef.current;
+			if (typeof inspect === "function") inspect(inspectionEvent);
+			else inspect?.next?.(inspectionEvent);
+		}).unsubscribe;
+	}, [shouldInspect]);
+	return storeRef.current;
+}
+function useAtom(definition, selectorOrInput, compare = defaultCompare) {
+	const atomRef = useRef(void 0);
+	if (isAtom(definition)) return useSelector(definition, selectorOrInput ?? identity, compare);
+	if (!atomRef.current) atomRef.current = definition.createAtom(selectorOrInput);
+	return useSelector(atomRef.current, identity, compare);
+}
+/**
+* Creates or subscribes to an atom for the lifetime of a React component.
+*
+* Pass an existing atom to receive `[value, atom]`, or pass an atom config
+* created with `createAtomConfig(...)` to create a stable local atom.
+*/
+function useAtomState(...[definition, input]) {
+	const atomRef = useRef(void 0);
+	if (!atomRef.current) atomRef.current = isAtom(definition) ? definition : definition.createAtom(input);
+	return [useAtom(atomRef.current), atomRef.current];
+}
+/**
+* Creates a custom hook that returns the selected value and the store from a
+* store configuration object.
+*
+* @example
+*
+* ```ts
+* const useCountStore = createStoreHook({
+*   context: { count: 0 },
+*   on: {
+*     inc: (context, event: { by: number }) => ({
+*       ...context,
+*       count: context.count + event.by
+*     })
+*   }
+* });
+*
+* function Component() {
+*   const [count, store] = useCountStore(s => s.context.count);
+*
+*   return (
+*     <div>
+*       {count}
+*       <button onClick={() => store.trigger.inc({ by: 1 })}>+</button>
+*     </div>
+*   );
+* }
+* ```
+*
+* @param definition The store configuration object
+* @returns A custom hook that returns [selectedValue, store]
+*/
+function createStoreHook(definition) {
+	const store = createStoreFromDefinition(definition);
+	function useStoreHook(selector, compare = defaultCompare) {
+		if (!selector) return [useSelector(store), store];
+		return [useSelector(store, selector, compare), store];
+	}
+	return useStoreHook;
+}
+export { createStoreHook, useAtom, useAtomState, useSelector, useStore };

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@systemfsoftware/xstate-store-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "license": "MIT",
+  "version": "2.1.0-beta.4",
+  "author": "Ryan Lee <drdgvhbh@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/systemfsoftware/xstate.git",
+    "directory": "packages/xstate-store-react"
+  },
+  "homepage": "https://github.com/systemfsoftware/xstate/tree/main/packages/xstate-store-react#readme",
+  "bugs": "https://github.com/systemfsoftware/xstate/issues",
+  "description": "React hooks for XState stores — forked under systemfsoftware from statelyai/xstate (@xstate/store-react at 2146ae26).",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@systemfsoftware/xstate-store": "^5.0.0-beta.6"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0"
+  },
+  "devDependencies": {
+    "@effect/tsgo": "0.64.1",
+    "@microsoft/api-extractor": "7.59.1",
+    "@systemfsoftware/arethetypeswrong-cli": "file:../../.deps/arethetypeswrong-cli.tgz",
+    "@systemfsoftware/tsconfig": "file:../../.deps/tsconfig.tgz",
+    "@systemfsoftware/vitest": "file:../../.deps/vitest.tgz",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "24.19.1",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "happy-dom": "20.14.5",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "rimraf": "6.1.3",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3",
+    "zod": "4.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "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"
+  }
 }