sigula 1.0.3 → 2.0.0

package/README.md

@@ -11,7 +11,7 @@ A minimal, signal-based web framework with fine-grained reactivity. No virtual D
 - No virtual DOM — no diffing, no VNodes. Direct real DOM operations with minimal runtime overhead
 - Minimal HTML templates — based on native string templates. No custom compiler, no DSL — just JavaScript strings
 - Batched, coalesced updates — writes are queued in a microtask, so a signal touched many times before the flush runs its bindings once, with the final value
-- Ultra small — ~4.1KB minified + gzipped
+- Ultra small — ~4.0KB minified + gzipped
 - TypeScript friendly — full type inference for signals and template bindings
 - Simple but performant — tiny API surface, low mental overhead, no compromise on performance
 
@@ -160,8 +160,8 @@ const Todos = (): View => {
         ${patch(
           on('click', () => item.done.trans((v) => !v)),
           style(
-            compute(item.done, (v): string => (v ? 'line-through' : 'none')),
             'textDecoration',
+            compute(item.done, (v): string => (v ? 'line-through' : 'none')),
           ),
         )}
       >${text(item.text)}</span>
@@ -231,484 +231,41 @@ const App: View = html`
 
 ### Ultra small
 
-minified + gzipped: ~4.1KB
+minified + gzipped: ~4.0KB
 
 ## 📖 Reference
 
-All exports are named exports from `sigula`.
-
-- [Reactivity](#reactivity)
-- [Templates](#templates)
-- [DOM bindings](#dom-bindings)
-- [Control flow](#control-flow)
-- [Rendering](#rendering)
-- [Low-level API](#low-level-api)
-- [Reactivity model](#reactivity-model)
-
-### Reactivity
-
-#### `sig`
-
-```ts
-const sig: <T>(v: T) => Sig<T>;
-```
-
-Creates a writable signal holding `v`.
-
-```ts
-const count = sig(0);
-count.get();          // 0
-count.update(1);      // schedules dependents
-```
-
-#### `Sig<T>`
-
-The core reactive value.
-
-| Member | Signature | Description |
-| --- | --- | --- |
-| `get` | `(): T` | Reads the current value. |
-| `update` | `(v: T): void` | Sets the value and notifies dependents, but only if `isEqual(v, current)` is `false`. |
-| `forceUpdate` | `(v: T): void` | Sets the value and always notifies dependents, even when deeply equal. |
-| `trans` | `(fn: (v: T) => T): void` | Applies `fn` to the current value via `update`, so an equal result is skipped. |
-| `equals` | `(other: unknown): boolean` | `Equatable` implementation; two `Sig`s are equal when their values are deeply equal. |
-| `addBind` | `<C>(bind: Bind<T, C>): void` | Registers a binding. Prefer `createBind` / the `patch`/`text`/`view` APIs. |
-| `removeBind` | `(bind: Bind<T, CmdContext>): void` | Unregisters a binding; runs `cleanup()` when the last one goes away. |
-| `getBinds` | `(): Bind<T, CmdContext>[]` | Returns the current bindings. |
-| `cleanup` | `(): void` | Overridable hook called when a signal loses all bindings. No-op on `Sig`. |
+The full API reference is generated from the TSDoc comments in the source: see [Reference.md](./Reference.md).
 
-#### `DerivedSig<T>`
+## Errors
 
-A `Sig` produced by `compute`. Extends `Sig` and additionally tracks the source bindings that feed it. When it loses its last consumer it detaches from its sources; when a consumer is added again, it re-links to the (possibly moved) source signals and recomputes once.
+Runtime errors carry a short code in `message` instead of a sentence, so the
+string tables stay out of the bundle. Codes with arguments are colon-separated.
+Look yours up here:
 
-| Member | Signature | Description |
+| Code | Thrown by | Meaning |
 | --- | --- | --- |
-| `addFromBind` | `<S, C>(bind: Bind<S, C>): void` | Registers a source binding. |
-| `addBind` | `<C>(bind: Bind<T, C>): void` | Registers a consumer; re-links to sources and recomputes once if the derived signal was detached. |
-| `cleanup` | `(): void` | Removes every source binding when the derived signal has no consumers. |
-
-#### `compute`
-
-```ts
-function compute<S, T>(source: Sig<S>, fn: (v: S) => T): DerivedSig<T>;
-function compute<S extends SigRecord, T>(
-  source: S,
-  fn: (v: ValRecord<S>) => T,
-): DerivedSig<T>;
-```
-
-Derives a signal from one source signal, or from a record of signals (whose values are passed as a matching record). The result is recomputed whenever any source changes.
-
-```ts
-const x = sig(1);
-const y = sig(2);
-
-const sum = compute({x, y}, (v) => v.x + v.y);      // DerivedSig<number>
-const doubled = compute(x, (v) => v * 2);           // DerivedSig<number>
-```
-
-Supporting types:
-
-```ts
-interface SigRecord {
-  [key: string]: Sig<any>;
-}
-
-type ValRecord<K extends SigRecord> = {
-  [P in keyof K]: K[P] extends Sig<infer U> ? U : never;
-};
-```
-
-`ValRecord` maps a record of signals to the record of their values, which is what `compute`'s record overload passes to `fn`.
-
-#### `isEqual`
-
-```ts
-const isEqual: <T>(a: T, b: T) => boolean;
-```
-
-Deep structural equality. Compares primitives, arrays, `Date`, `RegExp`, `Map`, `Set`, and plain objects, and defers to `a.equals(b)` when `a` implements `Equatable`. This is the default comparator for `Sig.update` and `repeat`. Two objects with different prototypes are never equal, so instances of different classes and objects from different realms (iframes, workers) always compare unequal.
-
-#### `Equatable`
-
-```ts
-interface Equatable {
-  equals(other: unknown): boolean;
-}
-```
-
-Implement this on a value type to give `isEqual` custom semantics.
-
-#### `UnknownRecord`
-
-```ts
-type UnknownRecord = Record<string, unknown>;
-```
-
-Convenience alias for an arbitrary string-keyed object, used by the equality and signal-record helpers.
-
-#### `createBind` / `removeBind`
-
-```ts
-const createBind: <T, C extends CmdContext>(
-  sig: Sig<T>,
-  context: C,
-  cmd: Cmd<T, C>,
-) => Bind<T, C>;
-
-const removeBind: (bind: Bind<unknown, CmdContext>) => void;
-```
-
-Low-level bind management. `createBind` wires `cmd(sig.get(), context)` to run whenever `sig` changes; `removeBind` detaches it. `Bind` is the resulting record:
-
-```ts
-interface Bind<T, C extends CmdContext> {
-  sig: Sig<T>;
-  context: C;
-  cmd: Cmd<T, C>;
-  removed: boolean;
-  queued?: boolean;
-}
-
-type AnyBind = Bind<any, any>;
-```
-
-### Templates
-
-#### `html`
-
-```ts
-const html: (
-  strs: TemplateStringsArray,
-  ...items: (Patch | AnyView)[]
-) => View;
-```
-
-Tagged template that parses native HTML and returns a `View`. Two kinds of interpolation are supported:
-
-- a `View` (from `text`, `view`, `repeat`, or another `html`) fills a content position
-- a `Patch` (from `patch(...)`) fills an attribute position
-
-```ts
-html`<p>${text(label)}</p>`;
-html`<button ${patch(on('click', handler))}>Go</button>`;
-```
-
-Templates are cached per call site, so repeated renders skip parsing. Using `patch(...)` in a content position throws `html: unmatched interpolation; patch() must be in attribute position`. An interpolation count that does not match the number of slots throws `html: expected N interpolation(s), got M`; a mismatch means the cached template for that call site was built from a different mix of interpolations.
-
-#### `text`
-
-```ts
-const text: <T>(source: T | Sig<T>) => View<T, PatchContext>;
-```
-
-Creates a text-node view. With a `Sig`, the text updates whenever the signal changes; with a plain value it is static.
-
-```ts
-html`<span>${text(count)}</span>`;
-```
-
-#### `View<T, C>` / `AnyView`
-
-```ts
-interface View<T = unknown, C extends CmdContext = any> {
-  type: 'view';
-  node: Node;
-  bind?: Bind<T, C> | undefined;
-  childCommits?: Commit<unknown, CmdContext>[];
-  live?: () => Boundary | undefined;
-}
-
-type AnyView = View<any, any>;
-```
-
-`View` is the unit returned by `html`, `text`, `view`, and `repeat`. Its `node` is a DOM node or `DocumentFragment`. `live` returns the boundary the view currently occupies; `render` calls it at disposal time so a view that swaps its own contents (`view`, `repeat`) is torn down from its current nodes.
-
-#### `extractBoundary` / `replaceWithView`
-
-```ts
-const extractBoundary: (view: View) => Boundary;
-const replaceWithView: (old: Boundary, view: View) => Boundary;
-```
-
-Helpers used by `view` and `repeat` to mount a view and later swap it. `extractBoundary` wraps `view.node` in a `Boundary`; `replaceWithView` replaces an existing boundary with the view's node and returns the new boundary.
-
-### DOM bindings
-
-#### `patch`
-
-```ts
-const patch: (...toPatchItems: ToAnyPatchItem[]) => Patch;
-```
-
-Declares one or more bindings to apply to the same element. Must be interpolated in an attribute position. Each command (`id`, `val`, `attr`, ...) receives either a plain value (applied once) or a `Sig` (applied on mount and re-applied on change).
-
-```ts
-html`<input ${patch(val(name), attr(placeholder, 'name'))} />`;
-```
-
-#### `id`
-
-```ts
-const id: <T>(source: T | Sig<T>) => ToPatchItem<T>;
-```
-
-Sets the element's `id`.
-
-#### `val`
-
-```ts
-const val: <T>(source: T | Sig<T>) => ToPatchItem<T>;
-```
-
-Sets the element's `value` property (form controls).
-
-#### `attr`
-
-```ts
-const attr: <T>(source: T | Sig<T>, key: string) => ToPatchItem<T>;
-```
-
-Sets attribute `key`. Use this for boolean/ARIA/data attributes.
-
-#### `style`
-
-```ts
-const style: <T>(
-  source: T | Sig<T>,
-  key: WritableStyleKey,
-) => ToPatchItem<T>;
-```
-
-Sets an inline style property by typed name.
-
-```ts
-html`<span ${patch(style(color, 'color'))}>text</span>`;
-```
-
-`WritableStyleKey` is the union of `CSSStyleDeclaration` keys whose values are strings.
-
-#### `styleProperty`
-
-```ts
-const styleProperty: <T>(source: T | Sig<T>, key: string) => ToPatchItem<T>;
-```
-
-Sets a style property via `CSSStyleDeclaration.setProperty`. Use this for custom properties (`--my-var`) or untyped names.
-
-```ts
-html`<div ${patch(styleProperty(size, '--size'))}></div>`;
-```
-
-#### `toggleClass`
-
-```ts
-const toggleClass: <T>(source: T | Sig<T>, token: string) => ToPatchItem<T>;
-```
-
-Toggles a single class from the truthiness of the value.
-
-#### `toggleClasses`
-
-```ts
-const toggleClasses: <T>(
-  source: T | Sig<T>,
-  ...tokens: string[]
-) => ToPatchItem<T>;
-```
-
-Toggles several classes from one value.
-
-#### `act`
-
-```ts
-type ActFn<T> = (node: Node, val?: T) => void;
-const act: <T>(source: T | Sig<T>, fn: ActFn<T>) => ToPatchItem<T>;
-```
-
-Runs arbitrary code with the bound node and value; runs on mount and again on change. Use it as the escape hatch for anything the built-in commands do not cover.
-
-```ts
-html`<canvas ${patch(act(frame, (node, v) => draw(node, v)))}></canvas>`;
-```
-
-#### `on`
-
-```ts
-const on: <K extends keyof HTMLElementEventMap>(
-  type: K,
-  listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown,
-  options?: boolean | AddEventListenerOptions,
-) => ToPatchItem<
-  (this: HTMLElement, ev: HTMLElementEventMap[K]) => unknown
->;
-```
-
-Adds a DOM event listener. The listener is registered once at mount; it is not a reactive source, so combine it with `sig` writes to drive updates.
-
-```ts
-html`<button ${patch(on('click', () => count.trans((v) => v + 1)))}>+1</button>`;
-```
-
-#### Patch types
-
-```ts
-interface PatchContext extends CmdContext {
-  node: Node;
-  extra?: unknown[];
-}
-
-interface PatchItem<T> {
-  source: T | Sig<T>;
-  context: PatchContext;
-  cmd: Cmd<T, PatchContext>;
-}
-
-type ToPatchItem<T> = (el: Element) => PatchItem<T>;
-type AnyPatchItem = PatchItem<any>;
-type ToAnyPatchItem = (el: Element) => AnyPatchItem;
-
-interface Patch {
-  type: 'patch';
-  toPatchItems: ToAnyPatchItem[];
-}
-```
-
-`ToPatchItem` defers reading the target element until mount. `patch` collects these factories into a single `Patch`.
-
-### Control flow
-
-#### `view`
-
-```ts
-const view: <T>(
-  sig: Sig<T>,
-  viewFn: (val: T) => AnyView,
-) => View<T>;
-```
-
-Conditionally renders one view or another. Whenever `sig` changes, `viewFn` is called with the new value, the previous view is torn down, and a new one is mounted in its place.
-
-```ts
-html`<div>${view(isEmpty, (v) => (v ? text('empty') : list))}</div>`;
-```
-
-#### `repeat`
-
-```ts
-type RepeatProp<T> = {
-  key: (item: T) => string;
-  view: (item: T) => AnyView;
-  compare?: (a: T, b: T) => boolean;
-};
-
-const repeat: <T>(sig: Sig<T[]>, prop: RepeatProp<T>) => View<T[]>;
-```
-
-Keyed list rendering. On each change Sigula matches items by `key`, then reuses, moves, creates, or removes as few DOM nodes as possible. `compare` defaults to `isEqual`; when an item is deeply equal to the track it already occupies, the track is reused without rebuilding its view. An empty array renders `<!--empty-list-->`.
-
-```ts
-html`<ul>${repeat(todos, {
-  key: (item) => item.id.toString(),
-  view: (item) => html`<li>${text(item.label)}</li>`,
-})}</ul>`;
-```
-
-`key` must be unique and stable for a given item. `compare` is useful when item identity is structural but you want to force or skip updates.
-
-### Rendering
-
-#### `render`
-
-```ts
-const render: (
-  viewArg: AnyView | (() => AnyView),
-  node: Node,
-) => () => void;
-```
-
-Mounts a view into `node` by appending `view.node`. Accepts a `View` directly or a factory function that returns one. Returns a disposer that detaches every bind in the tree and removes the nodes from `node`, so a mounted tree can be torn down completely. Calling the disposer twice is a no-op.
-
-```ts
-const dispose = render(App(), document.querySelector('#app')!);
-render(() => html`<p>lazy</p>`, document.body);
-dispose();
-```
-
-A view that swaps its own contents — one built with `view()` or `repeat()` at the root — disposes the nodes currently in `node`, not the ones originally appended. An empty template such as html`` renders nothing and its disposer is a no-op.
-
-### Low-level API
-
-These utilities power the framework and are exported for extension and testing.
-
-#### `Boundary`
-
-```ts
-interface Boundary {
-  start: Node;
-  end: Node;
-}
-```
-
-An inclusive range of sibling nodes (`start` through `end`).
-
-#### `toBoundary`
-
-```ts
-const toBoundary: (node: Node) => Boundary;
-```
-
-Wraps a node in a `Boundary`. For a `DocumentFragment`, the boundary spans its first and last child; otherwise it covers the node itself. Throws `toBoundary: empty fragment` on an empty fragment.
-
-#### `removeBoundary`
-
-```ts
-const removeBoundary: (b: Boundary) => void;
-```
-
-Removes every node in the boundary. A no-op if the boundary has no parent.
-
-#### `replaceWithNode`
-
-```ts
-const replaceWithNode: (old: Boundary, node: Node) => Boundary;
-```
-
-Replaces an entire boundary with `node` and returns the new boundary. Throws if `old` has no parent. This is the primitive behind dynamic `view` and `repeat` swaps.
-
-#### `Cmd` / `AnyCmd` / `CmdContext`
-
-```ts
-interface CmdContext {
-  [key: string]: unknown;
-}
-
-type Cmd<T, C extends CmdContext> = (val: T, context: C) => void;
-type AnyCmd = Cmd<any, any>;
-```
-
-A `Cmd` is the unit of work a binding runs: it receives the current signal value and its context.
-
-#### `Commit` / `cleanCommit`
-
-```ts
-interface Commit<T, C extends CmdContext> {
-  binds: Bind<T, C> | Bind<T, C>[] | undefined;
-  children?: Commit<unknown, CmdContext>[] | undefined;
-}
-
-const cleanCommit: (commit: Commit<unknown, CmdContext>) => void;
-```
-
-A `Commit` groups the bindings created by mounting a view; `cleanCommit` recursively removes them all. `View.childCommits` carries these so a parent can tear a whole subtree down at once.
-
-### Reactivity model
+| `E1:<index>` | `at` | Array index out of range. |
+| `E2` | `toBoundary` | Cannot build a boundary from an empty fragment. |
+| `E3` | `replaceWithNode` | The old boundary has no `parentNode`. |
+| `E4` | `patch` | A keyed command (`attr`, `style`, `styleProp`, `toggleClass`) was given no key. |
+| `E5` | `patch` | `act` was given no function. |
+| `E6` | `patch` | `on` was given no event type. |
+| `E7` | `repeat` | The rendered items have no parent node. |
+| `E8` | `repeat` | The temporary start/end fences were removed mid-update. |
+| `E9` | `repeat` | There is no node after the fence to move before. |
+| `E10` | `html` | The template is empty (an empty tagged template). |
+| `E11:<expected>:<got>` | `html` | Interpolation count does not match the template's slots. |
+| `E12` | `html` | Unmatched interpolation; a `Patch` must be in an attribute position and a `View`/text value in a content position. |
+
+## Reactivity model
 
 - **Batched.** When a signal changes, its bindings are queued, not run synchronously.
 - **Coalesced per binding.** A binding that is written to multiple times before the microtask flush runs once, reading the signal's final value. `sig.update(1); sig.update(2); sig.update(3)` runs each dependent binding a single time against `3`.
 - **`update` vs `forceUpdate`.** `update` skips work when the new value is deeply equal to the current one; `forceUpdate` always notifies. Use `forceUpdate` when a value is structurally equal but you still need a re-render (for example, mutating an object in place).
+- **`notify` for in-place mutation.** `sig.notify()` re-runs dependents against the current value without setting a new one. Use it after mutating a held object or array in place; `update`/`forceUpdate` set a value. On a `DerivedSig`, `notify` schedules its consumers but does not itself recompute the derived value.
 - **Error isolation.** A throwing binding does not stop the rest of the queue; the error is logged as `console.error('[Queue] task failed:', error, bind)`.
-- **Deep equality by default.** `update`, `compute`, and `repeat` compare with `isEqual`, so replacing `{a: 1}` with another `{a: 1}` is a no-op.
+- **Deep equality by default.** `update`, `compute`, and `repeat` compare with `eq`, so replacing `{a: 1}` with another `{a: 1}` is a no-op.
 
 ## License