preact-sigma 6.1.4 → 6.2.0

package/README.md

@@ -48,5 +48,8 @@ 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/).
+  - [`examples/basic-counter.ts`](./examples/basic-counter.ts)
+  - [`examples/command-palette.tsx`](./examples/command-palette.tsx)
+  - [`examples/external-query-sync.tsx`](./examples/external-query-sync.tsx)
 - 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

@@ -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-DEKK3bHd.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/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.0",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",