preact-sigma 2.2.2 → 2.2.3

package/docs/context.md

@@ -0,0 +1,102 @@
+# Overview
+
+`preact-sigma` builds reusable state models from one definition. A configured `SigmaType` owns top-level state, derived reads, writes, setup handlers, and typed events. Each top-level state property is exposed as a reactive public property backed by its own Preact signal, while actions use Immer-style mutation semantics to publish committed state.
+
+# When to Use
+
+- State, derived reads, mutations, and lifecycle need to stay together.
+- You need multiple instances of the same model.
+- Public reads should stay reactive and readonly while writes stay explicit.
+- A model needs to own timers, subscriptions, listeners, nested setup, or other cleanup-aware resources.
+- Components should consume the same model shape used outside Preact.
+
+# When Not to Use
+
+- A few plain signals already cover the state without extra coordination.
+- You want side effects to start implicitly during construction.
+- The main problem is remote caching, normalization, or cross-app store tooling rather than local state behavior.
+- You need ad hoc mutable objects with no benefit from typed actions, setup, or signal-backed reads.
+
+# Core Abstractions
+
+- Sigma type: the builder returned by `new SigmaType<TState, TEvents>()`. After configuration, it is also the constructor for instances.
+- Sigma state: an instance created from a configured sigma type.
+- State property: a top-level key from `TState`. Each one becomes a readonly reactive public property and gets its own signal.
+- Computed: an argument-free derived getter declared with `.computed(...)`.
+- Query: a reactive read that accepts arguments, declared with `.queries(...)` or built locally with `query(fn)`.
+- Action: a method declared with `.actions(...)` that reads and writes through sigma's draft and commit semantics.
+- Setup handler: a function declared with `.setup(...)` that owns side effects and cleanup resources explicitly.
+- Event: a typed notification emitted through `this.emit(...)` and observed through `.on(...)`, `listen(...)`, or `useListener(...)`.
+
+# Data Flow / Lifecycle
+
+1. Define a sigma type with `new SigmaType<TState, TEvents>()`. Let later builder methods infer names and types from the objects you pass to them.
+2. Add `defaultState(...)` for top-level public state and optional per-instance initializers.
+3. Add `computed(...)`, `queries(...)`, and `actions(...)` for derived reads and writes.
+4. Instantiate the configured type. Constructor input shallowly overrides `defaultState(...)`.
+5. Read state, computeds, and queries reactively from the public instance.
+6. Mutate state inside actions. Sync nested actions on the same instance share one draft. Boundaries like `await`, `emit(...)`, or separate action invocations may require `this.commit()` before the boundary.
+7. Run `setup(...)` explicitly when the instance should start owning side effects. `useSigma(...)` does this automatically for component-owned instances that define setup.
+8. Dispose the cleanup returned from `setup(...)` when the owned resources should stop.
+
+# Common Tasks -> Recommended APIs
+
+- Define reusable model state: `new SigmaType<TState, TEvents>().defaultState(...)`
+- Derive an argument-free value: `.computed(...)`
+- Derive a reactive read with arguments: `.queries(...)`
+- Keep a tracked helper local to one consumer module: `query(fn)`
+- Mutate state and emit typed notifications: `.actions(...)`
+- Publish before `await`, `emit(...)`, or another action boundary: `this.commit()`
+- React to committed state changes: `.observe(...)`
+- Own timers, listeners, subscriptions, or nested setup: `.setup(...)`
+- Use a sigma state inside a component: `useSigma(...)`
+- Subscribe to sigma or DOM events in a component: `useListener(...)`
+- Subscribe outside components: `.on(...)` or `listen(...)`
+- Read or restore committed top-level state: `snapshot(...)` and `replaceState(...)`
+
+# Practical Guidelines
+
+- Put explicit type arguments on `new SigmaType<TState, TEvents>()` and let later builder methods infer from the objects you pass.
+- Keep frequently read values as separate top-level state properties. Each top-level key gets its own signal.
+- Use `.computed(...)` for argument-free derived reads.
+- Use `.queries(...)` for tracked reads with arguments.
+- Keep one-off calculations local until they become reusable model behavior.
+- Reach for `instance.get(key)` only when code specifically needs the underlying `ReadonlySignal`.
+- Treat `emit(...)`, `await`, and any action call other than a same-instance synchronous nested action call as draft boundaries. Call `this.commit()` only when pending changes need to become public before one of those boundaries.
+- Use ordinary actions for routine writes. Reserve `snapshot(...)` and `replaceState(...)` for replay, reset, or undo-like flows on committed top-level state.
+- Put owned side effects in `.setup(...)`.
+- Use `this.act(function () { ... })` for setup-owned callbacks that need action semantics.
+- Call Immer's `enablePatches()` before relying on `.observe(..., { patches: true })`.
+
+# Invariants and Constraints
+
+- Sigma only tracks top-level state properties. Each top-level key gets its own signal.
+- Public state is readonly outside actions and `this.act(...)` inside setup.
+- Duplicate names across state properties, computeds, queries, and actions are rejected at runtime. Reserved public names include `act`, `emit`, `get`, `on`, and `setup`.
+- Query calls are reactive at the call site but do not memoize across invocations.
+- Setup handlers return arrays of cleanup resources, and cleanup runs in reverse order.
+- `replaceState(...)` works on committed top-level state and requires the exact state-key shape.
+- Published draftable public state is deep-frozen by default. `setAutoFreeze(false)` disables that behavior globally.
+
+# Error Model
+
+- Crossing an action boundary with unpublished changes throws until `this.commit()` publishes them. Async actions also reject when they finish with unpublished changes.
+- If another invocation crosses a boundary while unpublished changes still exist, sigma warns and discards those changes before continuing.
+- Calling `setup(...)` on a sigma state without registered setup handlers throws.
+- Cleanup rethrows an `AggregateError` when more than one cleanup resource fails.
+- `replaceState(...)` throws when the replacement value is not a plain object, has the wrong top-level keys, or runs while an action still owns unpublished changes.
+
+# Terminology
+
+- Draft boundary: a point where sigma cannot keep reusing the current unpublished draft.
+- Committed state: the published top-level public state visible outside the current action draft.
+- Signal access: reading the underlying `ReadonlySignal` for a top-level state key or computed through `instance.get(key)`.
+- Cleanup resource: a cleanup function, `AbortController`, object with `dispose()`, or object with `[Symbol.dispose]()`.
+- Nested sigma state: a sigma-state instance stored in top-level state as a value; it stays usable as a value rather than exposing its internals through parent actions.
+
+# Non-Goals
+
+- Replacing every plain-signal use case with a builder abstraction.
+- Hiding lifecycle behind implicit setup or constructor side effects.
+- Memoizing every query call or turning queries into a global cache.
+- Acting as a large tutorial framework or hand-maintained API reference. Exact signatures come from declaration output, and factual behavior lives beside source.

package/examples/async-commit.ts

@@ -0,0 +1,42 @@
+import { SigmaType } from "preact-sigma";
+
+const SaveIndicator = new SigmaType<
+  {
+    savedCount: number;
+    saving: boolean;
+  },
+  {
+    saved: {
+      count: number;
+    };
+  }
+>("SaveIndicator")
+  .defaultState({
+    savedCount: 0,
+    saving: false,
+  })
+  .actions({
+    async save() {
+      this.saving = true;
+      this.commit(); // Publish before the async boundary.
+
+      await Promise.resolve();
+
+      this.savedCount += 1;
+      this.saving = false;
+      this.commit(); // Publish before emitting the event boundary.
+
+      this.emit("saved", { count: this.savedCount });
+    },
+  });
+
+const indicator = new SaveIndicator();
+
+indicator.on("saved", ({ count }) => {
+  console.log(`Saved ${count} times`);
+});
+
+await indicator.save();
+
+console.log(indicator.saving); // false
+console.log(indicator.savedCount); // 1

package/examples/basic-counter.ts

@@ -0,0 +1,23 @@
+import { SigmaType } from "preact-sigma";
+
+const Counter = new SigmaType<{ count: number }>("Counter")
+  .defaultState({
+    count: 0,
+  })
+  .computed({
+    doubled() {
+      return this.count * 2;
+    },
+  })
+  .actions({
+    increment() {
+      this.count += 1;
+    },
+  });
+
+const counter = new Counter();
+
+counter.increment();
+
+console.log(counter.count); // 1
+console.log(counter.doubled); // 2

package/examples/command-palette.tsx

@@ -0,0 +1,211 @@
+import { useState } from "preact/hooks";
+
+import { listen, query, SigmaType, useListener, useSigma } from "preact-sigma";
+
+type Command = {
+  id: string;
+  title: string;
+  keywords: readonly string[];
+};
+
+class UsageLedger {
+  counts = new Map<string, number>();
+
+  get(id: string) {
+    return this.counts.get(id) ?? 0;
+  }
+
+  increment(id: string) {
+    this.counts.set(id, this.get(id) + 1);
+  }
+}
+
+const matchesText = query((command: Command, draft: string) => {
+  const needle = draft.trim().toLowerCase();
+  if (!needle) {
+    return true;
+  }
+
+  return (
+    command.title.toLowerCase().includes(needle) ||
+    command.keywords.some((keyword) => keyword.toLowerCase().includes(needle))
+  );
+});
+
+const SearchHistory = new SigmaType<{
+  items: string[];
+}>("SearchHistory")
+  .defaultState({
+    items: [],
+  })
+  .actions({
+    remember(query: string) {
+      const value = query.trim();
+      if (!value) {
+        return;
+      }
+
+      this.items = [value, ...this.items.filter((item) => item !== value)].slice(0, 5);
+    },
+  });
+
+interface SearchHistory extends InstanceType<typeof SearchHistory> {}
+
+const CommandPalette = new SigmaType<
+  {
+    commands: Command[];
+    cursor: number;
+    draft: string;
+    history: SearchHistory;
+    usage: UsageLedger;
+  },
+  {
+    ran: Command;
+  }
+>("CommandPalette")
+  .defaultState({
+    commands: [
+      { id: "inbox", title: "Open inbox", keywords: ["mail", "messages", "triage"] },
+      { id: "capture", title: "Capture note", keywords: ["write", "quick", "idea"] },
+      { id: "focus", title: "Start focus timer", keywords: ["pomodoro", "deep work"] },
+      { id: "theme", title: "Toggle theme", keywords: ["appearance", "dark", "light"] },
+    ],
+    cursor: 0,
+    draft: "",
+    history: () => new SearchHistory(),
+    usage: () => new UsageLedger(),
+  })
+  .computed({
+    visibleCommands() {
+      return this.commands.filter((command) => matchesText(command, this.draft));
+    },
+    activeCommand() {
+      return this.visibleCommands[this.cursor] ?? null;
+    },
+  })
+  .queries({
+    canRun() {
+      return this.activeCommand !== null;
+    },
+    usageCount(id: string) {
+      return this.usage.get(id);
+    },
+  })
+  .actions({
+    setDraft(draft: string) {
+      this.draft = draft;
+      this.cursor = 0;
+    },
+    move(step: number) {
+      if (this.visibleCommands.length === 0) {
+        this.cursor = 0;
+        return;
+      }
+
+      const lastIndex = this.visibleCommands.length - 1;
+      this.cursor = Math.max(0, Math.min(lastIndex, this.cursor + step));
+    },
+    seedDraftFromHistory() {
+      const latest = this.history.items[0];
+      if (latest) {
+        this.setDraft(latest);
+      }
+    },
+    runActive() {
+      const command = this.activeCommand;
+      if (!command || !this.canRun()) {
+        return;
+      }
+
+      this.history.remember(this.draft || command.title);
+      this.usage.increment(command.id);
+      this.emit("ran", command);
+      this.draft = "";
+      this.cursor = 0;
+    },
+  })
+  .setup(function () {
+    return [
+      listen(window, "keydown", (event) => {
+        if ((event.metaKey || event.ctrlKey) && event.key === "k") {
+          event.preventDefault();
+          this.seedDraftFromHistory();
+          return;
+        }
+
+        if (event.key === "ArrowDown") {
+          event.preventDefault();
+          this.move(1);
+        } else if (event.key === "ArrowUp") {
+          event.preventDefault();
+          this.move(-1);
+        } else if (event.key === "Enter") {
+          this.runActive();
+        }
+      }),
+    ];
+  });
+
+interface CommandPalette extends InstanceType<typeof CommandPalette> {}
+
+export function CommandPaletteExample() {
+  const palette = useSigma(() => new CommandPalette());
+  const [lastRun, setLastRun] = useState<string>("Nothing yet");
+
+  useListener(palette, "ran", (command) => {
+    setLastRun(`${command.title} (${palette.usageCount(command.id)} runs)`);
+  });
+
+  return (
+    <section>
+      <p>
+        <strong>Command palette</strong>: setup-owned keyboard shortcuts, computed getters, tracked
+        queries with args, typed events, nested sigma state, and a mutable custom class instance.
+      </p>
+
+      <label>
+        Search
+        <input
+          value={palette.draft}
+          onInput={(event) => palette.setDraft((event.currentTarget as HTMLInputElement).value)}
+          placeholder="Try: note, timer, inbox"
+        />
+      </label>
+
+      <div>
+        <button type="button" onClick={() => palette.move(-1)}>
+          Up
+        </button>
+        <button type="button" onClick={() => palette.move(1)}>
+          Down
+        </button>
+        <button type="button" onClick={() => palette.runActive()} disabled={!palette.canRun()}>
+          Run
+        </button>
+      </div>
+
+      <p>Last run: {lastRun}</p>
+
+      <ul>
+        {palette.visibleCommands.map((command, index) => (
+          <li key={command.id}>
+            <button
+              type="button"
+              onClick={() => {
+                palette.setDraft(command.title);
+                palette.runActive();
+              }}
+              style={{
+                fontWeight: index === palette.cursor ? "700" : "400",
+              }}
+            >
+              {command.title} · used {palette.usageCount(command.id)} times
+            </button>
+          </li>
+        ))}
+      </ul>
+
+      <p>History: {palette.history.items.join(" / ") || "empty"}</p>
+    </section>
+  );
+}

package/examples/observe-and-restore.ts

@@ -0,0 +1,27 @@
+import { replaceState, SigmaType, snapshot } from "preact-sigma";
+
+const TodoList = new SigmaType<{
+  todos: string[];
+}>("TodoList")
+  .defaultState({
+    todos: [],
+  })
+  .observe(function (change) {
+    console.log(`${change.oldState.todos.length} -> ${change.newState.todos.length}`);
+  })
+  .actions({
+    add(title: string) {
+      this.todos.push(title);
+    },
+  });
+
+const todoList = new TodoList();
+
+todoList.add("Write docs");
+
+const saved = snapshot(todoList);
+
+todoList.add("Ship release");
+replaceState(todoList, saved);
+
+console.log(snapshot(todoList).todos); // ["Write docs"]

package/examples/setup-act.ts

@@ -0,0 +1,34 @@
+import { listen, SigmaType } from "preact-sigma";
+
+const ClickTracker = new SigmaType<{
+  clicks: number;
+  status: "idle" | "ready";
+}>("ClickTracker")
+  .defaultState({
+    clicks: 0,
+    status: "idle",
+  })
+  .setup(function (target: EventTarget) {
+    this.act(function () {
+      this.status = "ready";
+    });
+
+    return [
+      listen(target, "click", () => {
+        this.act(function () {
+          this.clicks += 1;
+        });
+      }),
+    ];
+  });
+
+const target = new EventTarget();
+const tracker = new ClickTracker();
+const cleanup = tracker.setup(target);
+
+target.dispatchEvent(new Event("click"));
+target.dispatchEvent(new Event("click"));
+
+console.log(tracker.status, tracker.clicks); // ready 2
+
+cleanup();

package/examples/signal-access.ts

@@ -0,0 +1,28 @@
+import { effect, SigmaType } from "preact-sigma";
+
+const Counter = new SigmaType<{
+  count: number;
+}>("Counter")
+  .defaultState({
+    count: 0,
+  })
+  .computed({
+    doubled() {
+      return this.count * 2;
+    },
+  })
+  .actions({
+    increment() {
+      this.count += 1;
+    },
+  });
+
+const counter = new Counter();
+
+const stop = effect(() => {
+  console.log(counter.get("count").value, counter.get("doubled").value);
+});
+
+counter.increment();
+
+stop();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "preact-sigma",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "keywords": [],
   "license": "MIT",
   "author": "Alec Larson",
@@ -10,7 +10,8 @@
   },
   "files": [
     "dist",
-    "llms.txt"
+    "docs",
+    "examples"
   ],
   "type": "module",
   "exports": {