preact-sigma 6.1.4 → 6.2.1

package/README.md

@@ -48,5 +48,5 @@ console.log(counter.doubled); // 2
 - Concepts, lifecycle, invariants, and API selection live in [`docs/context.md`](./docs/context.md).
 - Persistence-specific guidance lives in [`docs/persist.md`](./docs/persist.md).
 - Migration guidance from v5 lives in [`docs/migrations/v5-to-v6.md`](./docs/migrations/v5-to-v6.md).
-- Runnable usage patterns live in [`examples/`](./examples/), starting with [`examples/basic-counter.ts`](./examples/basic-counter.ts) and [`examples/command-palette.tsx`](./examples/command-palette.tsx).
+- Runnable usage patterns live in [`examples/`](./examples/).
 - Exact exported signatures and public API comments live in `dist/index.d.mts` and `dist/persist.d.mts` after `pnpm build`.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { a as SigmaRef, c as castProtected, d as sigma, f as Draft, h as Cleanup, i as SigmaDefinition, l as query, m as typeSymbol, n as ReadableSigma, o as SigmaState, p as Immutable, r as Sigma, s as SigmaTarget, t as Protected, u as setAutoFreeze } from "./sigma-BfaJUPWw.mjs";
+import { a as SigmaRef, c as castProtected, d as sigma, f as Draft, h as Cleanup, i as SigmaDefinition, l as query, m as typeSymbol, n as ReadableSigma, o as SigmaState, p as Immutable, r as Sigma, s as SigmaTarget, t as Protected, u as setAutoFreeze } from "./sigma-cb2HeDjg.mjs";
 
 //#region src/defaults.d.ts
 /**
@@ -58,4 +58,18 @@ type UseSigmaArgs<T extends Sigma<any>> = T extends {
  */
 declare function useSigma<T extends Sigma<any>>(...args: UseSigmaArgs<T>): Protected<T>;
 //#endregion
-export { type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, ReadableSigma, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma };
+//#region src/hooks/useSigmaSync.d.ts
+type PlainObject = Record<string, unknown>;
+/**
+ * Synchronizes changed external data into a sigma instance after the initial render.
+ *
+ * `input` must be a plain object with stable keys. Its values are shallow-compared with
+ * `Object.is(...)`, and `sync(...)` runs only after at least one value changes.
+ *
+ * A changed `instance` resets the baseline input, so newly created component-owned sigma
+ * instances can receive their initial external data through construction or setup before
+ * later renders synchronize changes through this hook.
+ */
+declare function useSigmaSync<TInstance extends Sigma<any>, TInput extends PlainObject>(instance: TInstance | Protected<TInstance>, input: TInput, sync: (input: Readonly<TInput>) => void): void;
+//#endregion
+export { type Draft, type Immutable, InferEventType, InferListener, Listenable, Protected, ReadableSigma, Sigma, SigmaDefinition, SigmaListenable, SigmaRef, SigmaState, SigmaTarget, UseSigmaArgs, UseSigmaOptions, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma, useSigmaSync };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as setAutoFreeze, c as listenersSymbol, i as query, n as SigmaTarget, o as sigma, r as castProtected, t as Sigma } from "./sigma-DEKK3bHd.mjs";
+import { a as setAutoFreeze, c as listenersSymbol, i as query, n as SigmaTarget, o as sigma, r as castProtected, s as isPlainObject, t as Sigma } from "./sigma-B7kPkW-M.mjs";
 import { useEffect, useRef } from "preact/hooks";
 //#region src/defaults.ts
 /**
@@ -77,4 +77,42 @@ function useSigma(create, optionsOrDeps) {
 	return castProtected(instance);
 }
 //#endregion
-export { Sigma, SigmaTarget, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma };
+//#region src/hooks/useSigmaSync.ts
+function assertStableKeys(cachedKeys, nextKeys) {
+	if (cachedKeys.length !== nextKeys.length || nextKeys.some((key) => !cachedKeys.includes(key))) throw new Error("[preact-sigma] useSigmaSync() input keys must stay stable between renders.");
+}
+function hasChanged(previous, next, keys) {
+	return keys.some((key) => !Object.is(previous[key], next[key]));
+}
+/**
+* Synchronizes changed external data into a sigma instance after the initial render.
+*
+* `input` must be a plain object with stable keys. Its values are shallow-compared with
+* `Object.is(...)`, and `sync(...)` runs only after at least one value changes.
+*
+* A changed `instance` resets the baseline input, so newly created component-owned sigma
+* instances can receive their initial external data through construction or setup before
+* later renders synchronize changes through this hook.
+*/
+function useSigmaSync(instance, input, sync) {
+	if (!isPlainObject(input)) throw new Error("[preact-sigma] useSigmaSync() input must be a plain object.");
+	const previousInput = useRef(void 0);
+	const previousKeys = useRef(void 0);
+	const previousInstance = useRef(void 0);
+	useEffect(() => {
+		const nextKeys = Object.keys(input);
+		if (previousInstance.current !== instance) {
+			previousInstance.current = instance;
+			previousInput.current = input;
+			previousKeys.current = nextKeys;
+			return;
+		}
+		assertStableKeys(previousKeys.current, nextKeys);
+		if (hasChanged(previousInput.current, input, nextKeys)) {
+			previousInput.current = input;
+			sync(input);
+		}
+	});
+}
+//#endregion
+export { Sigma, SigmaTarget, castProtected, listen, mergeDefaults, query, setAutoFreeze, sigma, useListener, useSigma, useSigmaSync };

package/dist/persist.d.mts

@@ -1,4 +1,4 @@
-import { n as ReadableSigma, p as Immutable, r as Sigma } from "./sigma-BfaJUPWw.mjs";
+import { n as ReadableSigma, p as Immutable, r as Sigma } from "./sigma-cb2HeDjg.mjs";
 
 //#region src/persist.d.ts
 type MaybePromise<T> = T | Promise<T>;

package/dist/persist.mjs

@@ -1,4 +1,4 @@
-import { o as sigma, s as isPlainObject } from "./sigma-DEKK3bHd.mjs";
+import { o as sigma, s as isPlainObject } from "./sigma-B7kPkW-M.mjs";
 //#region src/persist.ts
 function createIdentityCodec() {
 	return {

package/dist/{sigma-DEKK3bHd.mjs → sigma-B7kPkW-M.mjs}

@@ -418,22 +418,23 @@ var SigmaTarget = class SigmaTarget extends Sigma {
 /** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
 const sigma = /* @__PURE__ */ Object.freeze({
 	subscribe: ((instance, keyOrListener, listenerOrOptions) => {
+		const source = instance;
 		if (typeof keyOrListener === "string") {
-			const signal = getStateSignal(instance, keyOrListener);
+			const signal = getStateSignal(source, keyOrListener);
 			if (!signal) throw new Error(`[preact-sigma] Property named "${keyOrListener}" is not signal-backed.`);
 			return signal.subscribe(listenerOrOptions);
 		}
 		const listener = keyOrListener;
 		if (listenerOrOptions?.patches) patchListeners.add(listener);
-		let subscriptions = changeListenersMap.get(instance);
+		let subscriptions = changeListenersMap.get(source);
 		if (!subscriptions) {
 			subscriptions = /* @__PURE__ */ new Set();
-			changeListenersMap.set(instance, subscriptions);
+			changeListenersMap.set(source, subscriptions);
 		}
 		subscriptions.add(listener);
 		return () => {
 			subscriptions.delete(listener);
-			if (!subscriptions.size) changeListenersMap.delete(instance);
+			if (!subscriptions.size) changeListenersMap.delete(source);
 		};
 	}),
 	getSignal(instance, key) {

package/dist/{sigma-BfaJUPWw.d.mts → sigma-cb2HeDjg.d.mts}

@@ -141,14 +141,14 @@ declare class SigmaTarget<TEvents extends object = {}, TState extends object = {
 /** Helpers for observing, accessing, capturing, and replacing committed sigma state. */
 declare const sigma: Readonly<{
   /** Subscribes to committed state publishes or to one signal-backed top-level state key. */subscribe: {
-    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[], inversePatches: Patch[]) => void, options: {
+    <TState extends object>(instance: ReadableSigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[], inversePatches: Patch[]) => void, options: {
       patches: true;
     }): Cleanup;
-    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[] | undefined, inversePatches: Patch[] | undefined) => void, options: {
+    <TState extends object>(instance: ReadableSigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>, patches: Patch[] | undefined, inversePatches: Patch[] | undefined) => void, options: {
       patches: boolean;
     }): Cleanup;
-    <TState extends object>(instance: Sigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>) => void): Cleanup;
-    <TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey, listener: (value: Immutable<TState[TKey]>) => void): Cleanup;
+    <TState extends object>(instance: ReadableSigma<TState>, listener: (nextState: Immutable<TState>, baseState: Immutable<TState>) => void): Cleanup;
+    <TState extends object, TKey extends Extract<keyof TState, string>>(instance: ReadableSigma<TState>, key: TKey, listener: (value: Immutable<TState[TKey]>) => void): Cleanup;
   }; /** Returns the readonly signal backing one top-level state key. */
   getSignal<TState extends object, TKey extends Extract<keyof TState, string>>(instance: Sigma<TState>, key: TKey): ReadonlySignal<Immutable<TState[TKey]>>; /** Captures the current committed top-level state snapshot. */
   captureState<TState extends object>(instance: ReadableSigma<TState>): Immutable<TState>; /** Publishes a plain-object snapshot, including readonly captured snapshots, as committed state. */

package/docs/context.md

@@ -55,6 +55,7 @@
 - Read one top-level state property as a `ReadonlySignal`: `sigma.getSignal(instance, key)`.
 - Own timers, listeners, subscriptions, or nested setup: `onSetup(...)` plus `setup(...)`.
 - Use a sigma instance inside a component: `useSigma(...)`.
+- Synchronize changed component data into a sigma instance after the initial render: `useSigmaSync(instance, input, sync)`.
 - Cast an instance to its readonly consumer view outside a component: `castProtected(instance)`.
 - Subscribe to sigma or DOM events in a component: `useListener(...)`.
 - Subscribe outside components: `listen(instance, ...)`.
@@ -72,6 +73,7 @@
 - Emit directly from standalone `SigmaTarget` instances. In subclasses, emit from actions that have no unpublished draft changes. After mutating state, publish first with `this.commit(); this.emit(...)`.
 - Prefer `listen(...)` for external event subscriptions. It works with sigma targets and DOM targets.
 - Put owned side effects in `onSetup(...)`.
+- Use `useSigmaSync(...)` when a component-owned sigma instance is initialized from external props or hook data and needs to receive later changes through an action. Pass a plain object with stable keys; values are compared with `Object.is(...)`, and a recreated instance treats the current input as its new baseline.
 - Use `sigma.subscribe(this, ...)` inside `onSetup(...)` when a setup-owned side effect should react to future committed publishes. Return that cleanup so the subscription stops with setup.
   ```ts
   onSetup() {
@@ -115,6 +117,7 @@
 - Calling `emit(...)` outside an action on a subclass, or before committing the active draft, throws.
 - Calling an action from a computed or query throws.
 - Returning an active draft from an action throws.
+- `useSigmaSync(...)` throws when its input is not a plain object or when the input keys change between renders for the same instance.
 - `sigma.replaceState(...)` throws when the replacement value is not a plain object or when an action still owns unpublished changes.
 - Starting an action on another sigma instance while the current instance has an active action context throws.
 

package/examples/external-query-sync.tsx

@@ -0,0 +1,51 @@
+import type { FunctionComponent } from "preact";
+
+import { Sigma, useSigma, useSigmaSync } from "preact-sigma";
+
+type SearchResult = {
+  id: string;
+  title: string;
+};
+
+type SearchResultsState = {
+  query: string;
+  results: readonly SearchResult[];
+};
+
+class SearchResults extends Sigma<SearchResultsState> {
+  constructor(query: string, results: readonly SearchResult[]) {
+    super({
+      query,
+      results,
+    });
+  }
+
+  syncExternalQuery(query: string, results: readonly SearchResult[]) {
+    this.query = query;
+    this.results = results;
+  }
+}
+
+interface SearchResults extends SearchResultsState {}
+
+export const ExternalQuerySyncExample: FunctionComponent<{
+  query: string;
+  results: readonly SearchResult[];
+}> = ({ query, results }) => {
+  const search = useSigma(() => new SearchResults(query, results));
+
+  useSigmaSync(search, { query, results }, ({ query, results }) => {
+    search.syncExternalQuery(query, results);
+  });
+
+  return (
+    <section>
+      <h2>Results for {search.query || "everything"}</h2>
+      <ul>
+        {search.results.map((result) => (
+          <li key={result.id}>{result.title}</li>
+        ))}
+      </ul>
+    </section>
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "6.1.4",
+  "version": "6.2.1",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",