@cplieger/reactive 2.0.0 → 2.1.1

package/README.md

@@ -117,7 +117,8 @@ isComputed(doubled); // true
 - `effect(fn: () => Cleanup): () => void`: auto-tracking side-effect with cleanup support. `fn` must return `undefined` or a cleanup function.
 - `batch(fn)`: coalesce signal writes; effects flush synchronously at end of outermost batch. The only deferral — see [Flush model](#flush-model)
 - `untracked<T>(fn): T`: run fn without tracking signal reads (like Preact `untracked()` / Solid `untrack()`)
-- `on(deps, fn, options?): () => U`: explicit dependency declaration helper (like Solid `on()`); pass into `effect()` or `computed()`. With `{ defer: true }` the accessor returns `() => U | undefined`: the deferred first call yields `undefined`.
+- `touch(...signals): void`: read signals for their tracking effect alone, discarding the values — the complement of `peek()` (`peek` reads without subscribing, `touch` subscribes without keeping). `undefined` entries are skipped, so a per-key lookup that may miss (`Collection.signalFor(id)`, `SignalMap.get(id)`) can be passed straight in. Use it where a scope must re-run on a signal whose value it has no use for: most often a two-tier read, where a computed or effect takes per-entity values through `signalFor` and so must depend on the structure signal (`Collection.ids`) separately to re-derive when the id set changes. Unlike `on()` it ADDS a dependency and leaves every other read in the scope tracked
+- `on(deps, fn, options?): () => U`: explicit dependency declaration helper (like Solid `on()`); pass into `effect()` or `computed()`. Its body runs untracked, so the declared deps are the scope's ONLY dependencies — reach for `touch()` instead when the rest of the scope should stay tracked. Passed to `effect()`, the body owes an explicit `return undefined` (or a cleanup function) like any effect callback, since a body with no return statement infers `() => void`, which the `Cleanup` contract rejects. With `{ defer: true }` the accessor returns `() => U | undefined`: the deferred first call yields `undefined`.
 - `subscribe(signal, cb): () => void`: subscribe to a signal, calling cb immediately and on every change. The callback runs untracked: signals read inside it do not become dependencies of the subscription
 - `isSignal(value): boolean`: type guard for signals created by `signal()`
 - `isComputed(value): boolean`: type guard for computed signals

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "license": "Apache-2.0",
   "exports": {
     ".": "./src/index.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cplieger/reactive",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -17,14 +17,16 @@
     "@stryker-mutator/typescript-checker": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vitest/coverage-v8": "4.1.11",
-    "eslint": "10.8.1",
-    "fast-check": "4.9.0",
-    "happy-dom": "20.11.6",
+    "@vitest/browser": "5.0.0",
+    "@vitest/browser-playwright": "5.0.0",
+    "@vitest/coverage-v8": "5.0.0",
+    "eslint": "10.10.0",
+    "fast-check": "4.10.0",
+    "playwright": "1.63.0",
     "prettier": "3.9.6",
     "typescript": "npm:@typescript/typescript6@6.0.2",
-    "typescript-eslint": "8.67.0",
-    "vitest": "4.1.11"
+    "typescript-eslint": "8.70.0",
+    "vitest": "5.0.0"
   },
   "overrides": {
     "qs": "^6.15.2"

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   setEffectErrorHandler,
   computed,
   untracked,
+  touch,
   subscribe,
   isSignal,
   isComputed,

package/src/reconcile-tree.ts

@@ -149,8 +149,8 @@ export function reconcileChildren(parent: Node, newChildren: Node[]): void {
       // requested node is a template and is not inserted.
       //
       // Re-inserting a node that is already in place still detaches and
-      // reattaches it, which blurs a focused input and drops a text selection
-      // inside it, so move only when the position actually differs.
+      // reattaches it, which blurs a focused input, so move only when the
+      // position actually differs.
       if (ref !== matched) {
         parent.insertBefore(matched, ref);
       }
@@ -246,12 +246,13 @@ function patchAttrs(oldEl: HTMLElement, newEl: HTMLElement): void {
   // live value. Without this, a keyed re-patch could not turn a checkbox off,
   // move a selection, or replace the text in a field, ever.
   //
-  // Syncing `value` overwrites whatever a user has typed, and it moves the caret
-  // to the end. That is correct only where a re-render cannot land mid-keystroke,
-  // which is a property of the CONSUMER, not of this function: a form re-rendered
-  // by a click (open, save, reset) is safe, one re-rendered by a timer or a server
-  // push is not. The README records the obligation; a consumer in the second shape
-  // must drive the field from an effect instead of re-rendering over it.
+  // Syncing `value` overwrites whatever a user has typed, and a write that
+  // changes it also moves the caret to the end. That is correct only where a
+  // re-render cannot land mid-keystroke, which is a property of the CONSUMER, not
+  // of this function: a form re-rendered by a click (open, save, reset) is safe,
+  // one re-rendered by a timer or a server push is not. The README records the
+  // obligation; a consumer in the second shape must drive the field from an effect
+  // instead of re-rendering over it.
   //
   // Not covered here: `value` on an <option>/<progress>/<li> DOES reflect, so the
   // loops above already carry it. A <select>'s value is derived from its options,
@@ -261,13 +262,17 @@ function patchAttrs(oldEl: HTMLElement, newEl: HTMLElement): void {
   // canPatch has already established that both nodes share a nodeName, so one
   // side decides the branch.
   //
-  // Each `!==` guard is deliberate: assigning the same string to `.value` is a
-  // no-op through the DOM, but in a real browser it sets the dirty flag and moves
-  // the caret to the end, so an unconditional write would jump the caret on every
-  // re-render even when nothing changed. happy-dom 20.11.6 models the dirty-value,
-  // dirty-checkedness and dirtiness flags, so "the re-patch did not write" is
-  // observable as "the element still follows its content attribute" — all four
-  // guards are pinned behaviourally, with no spy and no caret.
+  // Each `!==` guard is deliberate: assigning to `.value` sets the element's
+  // dirty-value flag unconditionally, which severs the property from its content
+  // attribute for the rest of the element's life, and on a field holding raw
+  // content the value getter cannot see (`type=date`, `number`, `time`, `month`,
+  // `week`, `datetime-local`) it destroys what the user is half-way through
+  // typing. The caret is NOT the reason: per the HTML spec the text entry cursor
+  // moves only when the value actually changes, so a same-value write leaves it
+  // where it was. The dirty-value, dirty-checkedness and dirtiness flags are what
+  // make "the re-patch did not write" observable as "the element still follows
+  // its content attribute" — all four guards are pinned behaviourally, with no
+  // spy and no caret.
   if (oldEl.nodeName === "INPUT") {
     const oldInput = oldEl as HTMLInputElement;
     const newInput = newEl as HTMLInputElement;

package/src/reconcile.ts

@@ -30,10 +30,31 @@ export function reconcile<T>(
     }
   }
 
-  let target: Node | null = null;
-  for (let i = items.length - 1; i >= 0; i--) {
-    const item = items[i] as T;
+  // DEPARTING ELEMENTS GO FIRST, before anything is placed. The walk below runs
+  // backwards and skips an element already sitting before the last one it placed; a
+  // departing element still in the tree makes every PREDECESSOR's `nextSibling` point at
+  // a node about to vanish, so the guard sees a mismatch and re-seats a row nothing
+  // changed — which restarts its animations and drops `:hover` and focus. So `onRemove`
+  // fires before the survivors are placed, holding its own intact element; only the
+  // siblings' positions are not yet final. `key` is still called exactly once per item,
+  // and the pairs carry it into the walk so neither loop indexes an array.
+  const pairs: [T, string][] = [];
+  const wanted = new Set<string>();
+  for (const item of items) {
     const k = spec.key(item);
+    pairs.push([item, k]);
+    wanted.add(k);
+  }
+  for (const [k, el] of existing) {
+    if (!wanted.has(k)) {
+      spec.onRemove?.(el, k);
+      el.remove();
+      existing.delete(k);
+    }
+  }
+
+  let target: Node | null = null;
+  for (const [item, k] of pairs.reverse()) {
     let el = existing.get(k);
     if (el === undefined) {
       el = spec.mount(item);
@@ -52,9 +73,4 @@ export function reconcile<T>(
     }
     target = el;
   }
-
-  for (const [k, el] of existing) {
-    spec.onRemove?.(el, k);
-    el.remove();
-  }
 }

package/src/signal.ts

@@ -673,6 +673,37 @@ export function untracked<T>(fn: () => T): T {
   }
 }
 
+/** Read a signal for its tracking effect alone, discarding the value.
+ *
+ *  The complement of `peek()`: `peek` reads without subscribing, `touch`
+ *  subscribes without keeping. Outside a reactive scope it does nothing
+ *  observable.
+ *
+ *  This exists because the two-tier shape `createCollection` and `bindList` are
+ *  built on produces it: a scope reads per-entity values through `signalFor`,
+ *  so it must depend on the structure signal separately to re-run when the id
+ *  set changes, and that dependency has no value the body wants. Spelling it as
+ *  a discarded expression left the intent to a comment, and `undefined` entries
+ *  are accepted so a per-key lookup that may miss (`signalFor(id)`,
+ *  `SignalMap.get(id)`) can be passed straight in.
+ *
+ *  Not a substitute for `on()`, which declares an exhaustive dependency list
+ *  and runs its body untracked. `touch` ADDS a dependency and leaves every
+ *  other read in the scope tracked as usual. */
+export function touch(
+  ...signals: readonly (Signal<unknown> | ReadonlySignal<unknown> | undefined)[]
+): void {
+  for (const sig of signals) {
+    readForDependency(sig);
+  }
+}
+
+// Named so the read is a call rather than a discarded expression: the value is
+// deliberately unused, and returning it is what keeps that legible.
+function readForDependency(sig: Signal<unknown> | ReadonlySignal<unknown> | undefined): unknown {
+  return sig?.value;
+}
+
 /** Subscribe to a signal, calling cb on every change. Returns dispose function.
  *  The callback runs untracked: reading other signals inside it does not add
  *  them as dependencies of the subscription (matches upstream