@cplieger/ui 0.0.0-stage → 1.0.0-dev.1

package/src/signal/collection.ts

@@ -0,0 +1,182 @@
+// collection.ts — reactive ordered collection of keyed entities.
+//
+// Generalizes the "list of entities, each independently reactive, plus a
+// separate structure signal" model: a per-entity content update touches only
+// that entity's subscribers, while add/remove/reorder bumps the `ids` signal.
+// This is the data half of the two-tier list pattern (see `bindList` for the
+// render half). Built on `signal` + `SignalMap` — no separate engine.
+
+import { signal, batch, type ReadonlySignal } from "./signal.js";
+import { SignalMap } from "./signal-map.js";
+
+/** A reactive, ordered, keyed collection of entities of type T. */
+export interface Collection<T> {
+  /** Replace the whole collection (e.g. initial load). Entities no longer
+   *  present are dropped; the order becomes `items`, deduplicated by key:
+   *  the first occurrence keeps the position, and a later value replaces the
+   *  held one only when `equals` reports a change. */
+  setAll(items: readonly T[]): void;
+  /** Add a new entity or replace an existing one (keyed by `keyOf`). New
+   *  entities are appended to the order. */
+  upsert(item: T): void;
+  /** Add new entities to the FRONT of the order (e.g. loading older items for
+   *  scroll-up pagination). Existing ids are updated in place without moving. */
+  prepend(items: readonly T[]): void;
+  /** Update one entity in place (no-op if absent). Pass a value or an
+   *  updater. Does not change order. */
+  update(id: string, next: T | ((cur: T) => T)): void;
+  /** Remove one entity (no-op if absent). */
+  remove(id: string): void;
+  /** Remove every entity. */
+  clear(): void;
+  /** Current value of one entity (untracked peek), or undefined. */
+  get(id: string): T | undefined;
+  /** Whether an entity is present (untracked). */
+  has(id: string): boolean;
+  /** Reactive per-entity signal, or undefined if absent. Read inside an effect
+   *  to react only when THIS entity changes (the content tier). */
+  signalFor(id: string): ReadonlySignal<T> | undefined;
+  /** Reactive ordered id list — changes on add/remove/reorder, NOT on a
+   *  per-entity content update (the structure tier). */
+  readonly ids: ReadonlySignal<readonly string[]>;
+  /** Ordered snapshot of entity values. Reactive: reading this inside an
+   *  effect tracks order AND every entity (coarse — use `ids` + `signalFor`
+   *  for the two-tier split). */
+  items(): T[];
+  /** Entity count (untracked). */
+  readonly size: number;
+}
+
+/** Create a reactive ordered keyed collection. `keyOf` derives a stable
+ *  string id from an entity; `equals` decides when a write of an entity is a
+ *  change to notify, `Object.is` when omitted. */
+export function createCollection<T>(
+  keyOf: (item: T) => string,
+  options?: { readonly equals?: (a: T, b: T) => boolean },
+): Collection<T> {
+  // Shallow-equal so the structure tier fires only when the id sequence
+  // actually changes (a same-order setAll updates entities without a
+  // spurious structural re-render).
+  const order = signal<readonly string[]>([], {
+    equals: (a, b) => a.length === b.length && a.every((x, i) => x === b[i]),
+  });
+  const sigs = new SignalMap<T>(options);
+
+  function setAll(items: readonly T[]): void {
+    // Atomic: batch the per-entity writes + the order swap so effects (and any
+    // row update that cross-reads siblings) only run once the whole collection
+    // is consistent, not mid-mutation.
+    batch(() => {
+      const ids: string[] = [];
+      const seen = new Set<string>();
+      for (const item of items) {
+        const id = keyOf(item);
+        // One order slot per id, matching the one signal per id.
+        if (!seen.has(id)) {
+          seen.add(id);
+          ids.push(id);
+        }
+        sigs.ensure(id, item).value = item;
+      }
+      for (const id of order.peek()) {
+        if (!seen.has(id)) {
+          sigs.clear(id);
+        }
+      }
+      order.value = ids;
+    });
+  }
+
+  function upsert(item: T): void {
+    const id = keyOf(item);
+    const existing = sigs.get(id);
+    if (existing === undefined) {
+      sigs.ensure(id, item);
+      order.value = [...order.peek(), id];
+    } else {
+      existing.value = item;
+    }
+  }
+
+  function prepend(items: readonly T[]): void {
+    batch(() => {
+      const newIds: string[] = [];
+      for (const item of items) {
+        const id = keyOf(item);
+        const existing = sigs.get(id);
+        if (existing === undefined) {
+          sigs.ensure(id, item);
+          newIds.push(id);
+        } else {
+          existing.value = item;
+        }
+      }
+      if (newIds.length > 0) {
+        order.value = [...newIds, ...order.peek()];
+      }
+    });
+  }
+
+  function update(id: string, next: T | ((cur: T) => T)): void {
+    const s = sigs.get(id);
+    if (s === undefined) {
+      return;
+    }
+    s.value = typeof next === "function" ? (next as (cur: T) => T)(s.peek()) : next;
+  }
+
+  function remove(id: string): void {
+    if (sigs.get(id) === undefined) {
+      return;
+    }
+    sigs.clear(id);
+    order.value = order.peek().filter((x) => x !== id);
+  }
+
+  function clear(): void {
+    sigs.clearAll();
+    order.value = [];
+  }
+
+  function get(id: string): T | undefined {
+    return sigs.get(id)?.peek();
+  }
+
+  function has(id: string): boolean {
+    return sigs.get(id) !== undefined;
+  }
+
+  function signalFor(id: string): ReadonlySignal<T> | undefined {
+    return sigs.get(id);
+  }
+
+  function items(): T[] {
+    const result: T[] = [];
+    for (const id of order.value) {
+      const s = sigs.get(id);
+      if (s !== undefined) {
+        result.push(s.value);
+      }
+    }
+    return result;
+  }
+
+  return {
+    setAll,
+    upsert,
+    prepend,
+    update,
+    remove,
+    clear,
+    get,
+    has,
+    signalFor,
+    items,
+    get ids(): ReadonlySignal<readonly string[]> {
+      return order;
+    },
+    get size(): number {
+      return order.peek().length;
+    },
+  };
+}

package/src/signal/index.ts

@@ -0,0 +1,34 @@
+/** Signals, computed values, effects, owners, resources, stores, collections and the event bus. @module */
+
+export {
+  signal,
+  effect,
+  batch,
+  setEffectErrorHandler,
+  computed,
+  untracked,
+  touch,
+  subscribe,
+  isSignal,
+  isComputed,
+  on,
+  createRoot,
+  runWithOwner,
+} from "./signal.js";
+export type {
+  Signal,
+  Cleanup,
+  EffectErrorHandler,
+  Owner,
+  ReadonlySignal,
+  SignalOptions,
+} from "./signal.js";
+export { resource } from "./resource.js";
+export type { Loadable, Resource, ResourceOptions } from "./resource.js";
+export { createStore } from "./store.js";
+export type { Store } from "./store.js";
+export { SignalMap } from "./signal-map.js";
+export { createCollection } from "./collection.js";
+export type { Collection } from "./collection.js";
+export { createBus } from "./bus.js";
+export type { Bus, BusHandler } from "./bus.js";

package/src/signal/resource.ts

@@ -0,0 +1,102 @@
+import {
+  createRoot,
+  effect,
+  requireOwner,
+  runWithOwner,
+  signal,
+  type ReadonlySignal,
+} from "./signal.js";
+
+/** The state of an async value: loading, ready or failed. `stale` is the last
+ *  ready value, kept while a later run loads or after it fails. */
+export type Loadable<T, E = unknown> =
+  | { readonly state: "loading"; readonly stale?: T }
+  | { readonly state: "ready"; readonly data: T }
+  | { readonly state: "error"; readonly error: E; readonly stale?: T };
+
+/** A signal of the latest run's `Loadable`, with `refetch` to start a new run. */
+export interface Resource<T, E = unknown> extends ReadonlySignal<Loadable<T, E>> {
+  /** Start a new run for the current source value, superseding the running
+   *  one. Does nothing once the resource's owner is being disposed. */
+  refetch(): void;
+}
+
+/** Options for `resource`. */
+export interface ResourceOptions<S> {
+  /** Source equality; an equal new source value starts no run. Defaults to
+   *  `Object.is`. */
+  readonly equals?: (a: S, b: S) => boolean;
+}
+
+/** Load `load(source(), signal)` now and again whenever the tracked `source`
+ *  changes, owned by the current owner. Each run has its own owner, whose
+ *  `signal` is the one passed to `load` and which is current while `load`
+ *  runs: a new source value, `refetch()` or the resource's disposal disposes
+ *  the previous run, and a disposed run's settlement writes nothing. `E` is
+ *  whatever `load` throws or rejects with. A throw from `source` goes to the
+ *  effect error handler and starts no run. Throws outside an owner, or under
+ *  one being disposed. */
+export function resource<S, T, E = unknown>(
+  source: () => S,
+  load: (source: S, signal: AbortSignal) => Promise<T>,
+  options?: ResourceOptions<S>,
+): Resource<T, E> {
+  const owner = requireOwner("a resource");
+  const equals = options?.equals ?? Object.is;
+  const state = signal<Loadable<T, E>>({ state: "loading" });
+  let good: { readonly data: T } | undefined;
+  let current: { readonly value: S } | undefined;
+  let disposeRun: (() => void) | undefined;
+
+  const start = (value: S): void => {
+    runWithOwner(owner, () => {
+      disposeRun?.();
+      createRoot((dispose, run) => {
+        disposeRun = dispose;
+        state.value =
+          good === undefined ? { state: "loading" } : { state: "loading", stale: good.data };
+        // The async wrapper turns a synchronous throw from `load` into a rejection.
+        const pending = (async (): Promise<T> => load(value, run.signal))();
+        pending.then(
+          (data) => {
+            if (!run.signal.aborted) {
+              good = { data };
+              state.value = { state: "ready", data };
+            }
+          },
+          (error: unknown) => {
+            if (!run.signal.aborted) {
+              state.value =
+                good === undefined
+                  ? { state: "error", error: error as E }
+                  : { state: "error", error: error as E, stale: good.data };
+            }
+          },
+        );
+      });
+    });
+  };
+
+  effect(() => {
+    const value = source();
+    const prev = current;
+    current = { value };
+    if (prev === undefined || !equals(prev.value, value)) {
+      start(value);
+    }
+  });
+
+  return {
+    get value(): Loadable<T, E> {
+      return state.value;
+    },
+    peek(): Loadable<T, E> {
+      return state.peek();
+    },
+    refetch(): void {
+      if (current !== undefined) {
+        start(current.value);
+      }
+    },
+  };
+}

package/src/signal/signal-map.ts

@@ -0,0 +1,46 @@
+// SignalMap — a registry of lazily-created signals keyed by string ID.
+//
+// For dynamic, per-entity reactive state where the key set isn't known ahead
+// of time (per-message streaming text, per-tool-call, per-row state, …). This
+// complements `createStore`, whose typed key set is fixed at the type level.
+// Like everything else here it's a facade over `signal` — no separate engine.
+
+import { signal, type Signal } from "./signal.js";
+
+/** A typed map of lazily-created signals keyed by string ID. Provides
+ *  get / ensure / clear / clearAll over any value type. */
+export class SignalMap<V> {
+  private readonly map = new Map<string, Signal<V>>();
+  private readonly equals: ((a: V, b: V) => boolean) | undefined;
+
+  /** `equals` decides when a write to one of the map's signals is a change;
+   *  `Object.is` when omitted. */
+  constructor(options?: { readonly equals?: (a: V, b: V) => boolean }) {
+    this.equals = options?.equals;
+  }
+
+  /** The signal for `id`, or undefined if none has been created yet. */
+  get(id: string): Signal<V> | undefined {
+    return this.map.get(id);
+  }
+
+  /** The signal for `id`, creating it with `initial` on first access. */
+  ensure(id: string, initial: V): Signal<V> {
+    let sig = this.map.get(id);
+    if (sig === undefined) {
+      sig = this.equals === undefined ? signal(initial) : signal(initial, { equals: this.equals });
+      this.map.set(id, sig);
+    }
+    return sig;
+  }
+
+  /** Drop the signal for `id` (e.g. when the entity is removed). */
+  clear(id: string): void {
+    this.map.delete(id);
+  }
+
+  /** Drop every signal — e.g. on a wholesale context switch. */
+  clearAll(): void {
+    this.map.clear();
+  }
+}