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

package/src/actions/types.ts

@@ -0,0 +1,249 @@
+/** Lifecycle status of a single dispatched action instance.
+ *
+ *  - `"pending"` — optimistic ran (if any), run() in flight
+ *  - `"success"` — run() resolved
+ *  - `"error"` — run() threw; rollback ran
+ *  - `"cancelled"` — action.cancel() called or signal aborted externally */
+export type ActionLifecycleStatus = "pending" | "success" | "error" | "cancelled";
+
+/** Errors thrown by an action's run() function. ActionError subclass
+ *  in error.ts attaches HTTP status + server error code metadata. */
+export interface ActionErrorLike {
+  readonly message: string;
+  /** HTTP status if applicable. */
+  readonly status?: number;
+  /** Server-side error code. */
+  readonly code?: string;
+  readonly cause?: unknown;
+}
+
+/** @internal The lifecycle fields every action-log record carries, sensitive
+ *  or not. Each is a number or a string the framework sets, so none can hold
+ *  a value from args, result or run(); a payload-bearing field belongs on the
+ *  non-sensitive arm of {@link ActionInstance}. */
+export interface ActionInstanceFields {
+  /** Unique per dispatch. */
+  readonly id: string;
+  /** Matches ActionDefinition.name. */
+  readonly name: string;
+  readonly status: ActionLifecycleStatus;
+  /** Date.now() when dispatch() was called. */
+  readonly dispatchedAt: number;
+  /** Date.now() when run() begins (after scope queue). */
+  readonly startedAt: number;
+  /** Date.now() at terminal state. */
+  readonly completedAt?: number;
+  /** Total run() invocations (1 = no retry; >1 = retries fired). */
+  readonly attempts?: number;
+}
+
+/** Snapshot of a single in-flight or historical action invocation, stored in
+ *  the registry log. A `sensitive` definition's records carry no `args`,
+ *  `result` or `error`; narrow on `sensitive` before reading `args`. */
+export type ActionInstance<TArgs = unknown, TResult = unknown> =
+  | (ActionInstanceFields & {
+      readonly sensitive?: never;
+      readonly args: TArgs;
+      /** Present iff status === "success". */
+      readonly result?: TResult;
+      /** Present iff status === "error". */
+      readonly error?: ActionErrorLike;
+    })
+  | (ActionInstanceFields & {
+      readonly sensitive: true;
+      readonly args?: never;
+      readonly result?: never;
+      readonly error?: never;
+    });
+
+/** Notification wiring: either a literal string (used as-is), or a function
+ *  computed from action args + result/error at call time. Pass false
+ *  to opt out of the default notification for that branch. */
+export type NotificationSpec<TArgs, TPayload> =
+  string | ((args: TArgs, payload: TPayload) => string) | false;
+
+/** Per-dispatch context passed to run() as the 3rd argument. Mostly
+ *  populated by the framework so adapters (apiAction, transportAction)
+ *  can read out values like the idempotency key without the caller
+ *  having to plumb them. */
+export interface ActionContext {
+  /** Stable identifier for this dispatch (matches the registry's
+   *  ActionInstance.id). */
+  readonly instanceID: string;
+  /** Set when ActionDefinition.idempotencyKey is configured. The
+   *  framework generates this once per dispatch (not per retry). */
+  readonly idempotencyKey?: string;
+}
+
+/** Configuration for automatic retry of transient failures. */
+export interface RetryConfig {
+  /** Additional attempts beyond the first (e.g. 2 = up to 3 total). */
+  readonly count: number;
+  /** Milliseconds before each retry. Number form: exponential backoff via
+   *  `delay × factor^(attempt-1)`, capped at 5s. Function form: full
+   *  control — receives the attempt number and the triggering error. */
+  readonly delay: number | ((attempt: number, err: ActionErrorLike) => number);
+  /** Backoff multiplier per retry. Default 2. Ignored when `delay` is a function. */
+  readonly factor?: number;
+}
+
+/** Standard retry config: 2 retries, 300ms initial delay. */
+export const RETRY_STANDARD: RetryConfig = { count: 2, delay: 300 } as const;
+
+/** Declarative description of an action, consulted on every dispatch. Only
+ *  `name` and `run` are required; function-valued members are re-evaluated
+ *  per dispatch. A throw from a callback, `rollback` or a notification spec
+ *  is logged and leaves the outcome unchanged; a throw from `optimistic`
+ *  fails the dispatch before run(), with code `"optimistic_failed"` unless
+ *  the error carries its own. */
+export interface ActionDefinition<TArgs, TResult, TOp = unknown> {
+  /** Stable identifier, e.g. "chat.delete", "files.create".
+   *  Used in the registry log + as a default notification prefix. */
+  readonly name: string;
+
+  /** The work the action performs. Must throw ActionError on failure
+   *  (or any Error — wrappers will normalise). */
+  run: (args: TArgs, signal: AbortSignal, ctx?: ActionContext) => Promise<TResult>;
+
+  /** Optional optimistic mutation. Runs synchronously before run(). */
+  optimistic?: (args: TArgs) => TOp | undefined;
+
+  /** Undo the optimistic mutation. Called on error OR cancellation (including a
+   *  cancellation that lands after run() resolves), never on success. The `err`
+   *  carries {code:'cancelled'} on the cancellation path. */
+  rollback?: (args: TArgs, op: TOp | undefined, err: ActionErrorLike) => void;
+
+  /** Notification on success. Default: no notification. */
+  success?: NotificationSpec<TArgs, TResult>;
+
+  /** Notification on error. Default: action name humanised + error message. */
+  error?: NotificationSpec<TArgs, ActionErrorLike>;
+
+  /** Definition-level success callback. Fires on every successful dispatch.
+   *  Mirrors TanStack Query's mutation-level onSuccess. */
+  onSuccess?: (result: TResult, args: TArgs) => void;
+
+  /** Definition-level error callback. Fires on every failed dispatch.
+   *  Mirrors TanStack Query's mutation-level onError. */
+  onError?: (err: ActionErrorLike, args: TArgs) => void;
+
+  /** Definition-level settled callback. Fires after every dispatch
+   *  (success, error, or cancellation). Mirrors TanStack Query's onSettled. */
+  onSettled?: (args: TArgs) => void;
+
+  /** Classify whether an error qualifies for retry. */
+  retryable?: (err: ActionErrorLike) => boolean;
+
+  /** Auto-retry transient failures before surfacing the error notification. */
+  retry?: RetryConfig;
+
+  /** Auto-retry behavior when offline. Default `"online"`. */
+  networkMode?: "online" | "always";
+
+  /** Timeout in milliseconds for the run() function. Uses AbortSignal.timeout()
+   *  composed with the cancellation signal. If run() exceeds this duration,
+   *  the signal aborts with a TimeoutError. */
+  timeout?: number;
+
+  /** Serialize concurrent dispatches sharing the same scope key. */
+  scope?: string | ((args: TArgs) => string);
+
+  /** Generate an idempotency key per dispatch. */
+  idempotencyKey?: boolean | ((args: TArgs) => string);
+
+  /** Collapse concurrent dispatches with matching key into one in-flight promise. */
+  dedupe?: boolean | ((args: TArgs) => string);
+
+  /** For a call carrying a plaintext secret: the action log and every
+   *  registry listener get each instance without `args`, `result` and
+   *  `error`, so the result and the error reach only the dispatch's handle,
+   *  the callbacks and the notifications (the default and string error
+   *  notifications quote the error's message). Combined with `retry` or
+   *  `retryable`, defineAction() throws: a retry button would hold the args. */
+  sensitive?: true;
+}
+
+/** A registered action, returned by defineAction(). Can be dispatched
+ *  many times; each dispatch is a separate instance with its own
+ *  cancellation token. */
+export interface Action<TArgs, TResult> {
+  readonly name: string;
+
+  /** Run the action. Returns a DispatchHandle with the result promise
+   *  and a per-dispatch abort() method (RTK pattern). */
+  dispatch(args: TArgs, opts?: DispatchOptions<TArgs, TResult>): DispatchHandle<TResult>;
+
+  /** Cancel all in-flight instances. Each instance moves to status
+   *  "cancelled" and run()'s signal aborts. */
+  cancel(): void;
+}
+
+/** Typed terminal outcome of a single dispatch, resolved by
+ *  {@link DispatchHandle.outcome}. Distinguishes the three states the
+ *  handle's own `TResult | null` resolution collapses: success (including a
+ *  legitimate `null` / `undefined` result), failure (carrying the normalized
+ *  error), and cancellation. */
+export type ActionOutcome<TResult> =
+  | { readonly status: "success"; readonly value: TResult; readonly attempts?: number }
+  | { readonly status: "error"; readonly error: ActionErrorLike; readonly attempts?: number }
+  | { readonly status: "cancelled" };
+
+/** Handle returned by dispatch(). An augmented Promise with an abort()
+ *  method for per-dispatch cancellation (mirrors RTK createAsyncThunk).
+ *  Can be awaited directly as a Promise. */
+export interface DispatchHandle<TResult> extends Promise<TResult | null> {
+  /** Abort this specific dispatch; other in-flight dispatches of the same
+   *  action are unaffected. One still queued behind its `scope` settles
+   *  cancelled at once. On a handle that joined through `dedupe`, only this
+   *  call settles cancelled: the dispatch it joined keeps running. */
+  abort(): void;
+  /** Opt-in typed terminal outcome. Resolves alongside the handle (it never
+   *  rejects) with a discriminated {@link ActionOutcome}, letting a caller
+   *  distinguish a legitimate `null` result from failure or cancellation
+   *  without wiring callbacks. The never-rejecting `TResult | null`
+   *  resolution and the callback tiers remain the canonical surface. */
+  readonly outcome: Promise<ActionOutcome<TResult>>;
+}
+
+/** Per-dispatch overrides. */
+export interface DispatchOptions<TArgs = unknown, TResult = unknown> {
+  /** Suppress the success notification for this call. Errors still notify. */
+  readonly silent?: boolean;
+  /** Per-call success callback. Fires after the action-level notification. */
+  readonly onSuccess?: (result: TResult, args: TArgs) => void;
+  /** Per-call error callback. Fires after the action-level error notification. */
+  readonly onError?: (err: ActionErrorLike, args: TArgs) => void;
+  /** Per-call settled callback. Fires for success, error, AND cancellation. */
+  readonly onSettled?: (args: TArgs) => void;
+  /** Aborting it cancels this dispatch as `abort()` does: before it starts
+   *  (a dispatch queued behind its `scope` settles at once and never runs),
+   *  or mid-run, aborting run()'s signal with this signal's reason. An
+   *  already-aborted signal cancels the dispatch without running it. */
+  readonly signal?: AbortSignal;
+}
+
+/** HTTP request descriptor used by apiAction(). GET is included for
+ *  read actions that want notification/cancellation semantics. */
+export type RequestSpec =
+  | {
+      readonly method: "GET";
+      readonly path: string;
+      readonly headers?: Readonly<Record<string, string>>;
+    }
+  | {
+      readonly method: "POST" | "PUT" | "PATCH" | "DELETE";
+      readonly path: string;
+      /** JSON-encoded request body. Mutually exclusive with `rawBody`. */
+      readonly body?: unknown;
+      /** Pre-encoded request body, sent as-is with NO JSON encoding and NO
+       *  automatic Content-Type — set the type via `headers` (e.g. a YAML
+       *  document with `Content-Type: text/yaml`). The request() function is
+       *  the encoder seam: compute the encoded payload there per dispatch.
+       *  Mutually exclusive with `body`. */
+      readonly rawBody?: BodyInit;
+      readonly headers?: Readonly<Record<string, string>>;
+    };
+
+/** Subscriber callback for the registry. Fires once per state
+ *  transition (pending -> success/error/cancelled). */
+export type RegistryListener = (instance: ActionInstance) => void;

package/src/dom/bind-list.ts

@@ -0,0 +1,103 @@
+// Two-tier render binding for a reactive list source. One structural effect
+// tracks `source.ids` and reconciles the id list; each row owns an effect that
+// tracks only its entity signal, so an entity update repaints just that row.
+// The engine saves and restores evalContext around nested effects, so a row
+// effect's reads never leak into the structural effect. A `Collection<T>` is a
+// `ListSource<T>`; a filtered, sorted or paginated view is a `computed` id
+// list paired with the collection's `signalFor`.
+
+import { reconcile } from "./reconcile.js";
+import {
+  createRoot,
+  createRootUnder,
+  effect,
+  type Owner,
+  type ReadonlySignal,
+} from "../signal/signal.js";
+
+/** The minimal reactive surface `bindList` renders: a structure signal (the
+ *  ordered ids) and a per-id content-signal lookup. `Collection<T>` satisfies
+ *  this; so does `{ ids: computed(...), signalFor: collection.signalFor }`.
+ *  An id with no matching signal (an inconsistent source) is skipped — no row
+ *  is rendered for it until the source becomes consistent. */
+export interface ListSource<T> {
+  readonly ids: ReadonlySignal<readonly string[]>;
+  signalFor(id: string): ReadonlySignal<T> | undefined;
+}
+
+/** Row lifecycle for `bindList`. Each row has its own owner, so effects and
+ *  roots created in `mount` and `update` are disposed when the row leaves. */
+export interface ListSpec<T> {
+  /** Create the row element for a new entity. Receives the entity's current
+   *  value, its id and the row's owner, whose `signal` aborts when the row
+   *  leaves or the list is disposed. Keep this to structural shell creation;
+   *  let `update` fill reactive content (it runs once at mount and on every
+   *  later change). */
+  mount: (item: T, id: string, owner: Owner) => HTMLElement;
+  /** Update a row when its entity changes. Runs immediately at mount and again
+   *  on every per-entity change (the content tier). Omit for immutable rows
+   *  whose `mount` renders everything. */
+  update?: (el: HTMLElement, item: T, id: string) => void;
+  /** Optional cleanup when a row leaves the list, after its owner is disposed
+   *  and before the element is removed from the DOM. */
+  onRemove?: (el: HTMLElement, id: string) => void;
+}
+
+/** Bind a list source to a parent node with two-tier reactivity, in a root
+ *  owned by the current owner when there is one. Returns a dispose function
+ *  that tears down the structural effect and every row. */
+export function bindList<T>(
+  parent: ParentNode,
+  source: ListSource<T>,
+  spec: ListSpec<T>,
+): () => void {
+  return createRoot((dispose, listOwner) => {
+    const rowDisposers = new WeakMap<HTMLElement, () => void>();
+
+    effect(() => {
+      // Structure tier: re-runs on add/remove/reorder only. An id whose entity
+      // signal is missing (an inconsistent ListSource) is skipped instead of
+      // mounting a row with a manufactured `undefined as T` value; it renders
+      // once the source becomes consistent (the next `ids` change).
+      const ids = source.ids.value.filter((id) => source.signalFor(id) !== undefined);
+      reconcile<string>(parent, ids, {
+        key: (id) => id,
+        mount: (id) => {
+          const sig = source.signalFor(id);
+          if (sig === undefined) {
+            // Unreachable via the structural filter above (same synchronous
+            // pass); reachable only by a source whose signalFor is not stable
+            // within one read — surface that loudly instead of manufacturing
+            // an entity value. Routed to the effect error handler.
+            throw new Error(`bindList: no entity signal for id "${id}"`);
+          }
+          // A row belongs to the list, not to this structural run, whose
+          // scope is disposed on every add, remove or reorder.
+          return createRootUnder(listOwner, (disposeRow, rowOwner) => {
+            const el = spec.mount(sig.peek(), id, rowOwner);
+            rowDisposers.set(el, disposeRow);
+            if (spec.update !== undefined) {
+              const update = spec.update;
+              // content tier: isolated per-row effect; runs now (fills content)
+              // and on every later change to THIS entity.
+              effect(() => {
+                const cur = source.signalFor(id);
+                if (cur !== undefined) {
+                  update(el, cur.value, id);
+                }
+              });
+            }
+            return el;
+          });
+        },
+        // No structural `update`: content is owned entirely by the per-row effect.
+        onRemove: (el, id) => {
+          rowDisposers.get(el)?.();
+          spec.onRemove?.(el, id);
+        },
+      });
+    });
+
+    return dispose;
+  });
+}

package/src/dom/el.ts

@@ -0,0 +1,67 @@
+// el.ts — CSP-safe DOM element factory. The build half of the DOM layer; pairs
+// with reconcile/patch (the commit half). `on*` handlers are assigned as
+// properties AND registered via trackHandler, so patch() reconciles them across
+// re-renders. No innerHTML, no string templating — safe under a strict CSP.
+
+import { trackHandler } from "./reconcile-tree.js";
+
+/** A value for an element attribute/property/handler. Functions are treated as
+ *  event handlers when the key starts with `on`. */
+export type AttrValue =
+  string | number | boolean | null | undefined | ((...args: never[]) => unknown);
+
+// Keys set as DOM *properties* (not attributes) because the attribute form
+// either doesn't reflect (value/checked) or is awkward (boolean presence).
+const BOOL_PROPS = new Set([
+  "hidden",
+  "disabled",
+  "checked",
+  "selected",
+  "multiple",
+  "readOnly",
+  "required",
+  "open",
+  "default",
+]);
+const VALUE_PROPS = new Set(["value", "colSpan", "rowSpan", "tabIndex", "htmlFor"]);
+
+/** Create an element: `el("button", { className: "x", onclick: fn }, "Label")`.
+ *  - `className` → the class property
+ *  - `on*` → handler property + `trackHandler` (reconciled by patch)
+ *  - boolean DOM props (hidden/disabled/checked/selected/…) → property
+ *  - value/colSpan/rowSpan/tabIndex/htmlFor → property
+ *  - everything else → `setAttribute` (incl. `data-*`, `aria-*`, `style`, `id`)
+ *  Null/undefined attrs and children are skipped. String children become text
+ *  nodes (never parsed as HTML). */
+export function el(
+  tag: string,
+  attrs?: Record<string, AttrValue> | null,
+  ...children: (string | Node | null | undefined)[]
+): HTMLElement {
+  const e = document.createElement(tag);
+  if (attrs) {
+    for (const [k, v] of Object.entries(attrs)) {
+      if (v === null || v === undefined) {
+        continue;
+      }
+      if (k === "className") {
+        e.className = v as string;
+      } else if (/^on/i.test(k)) {
+        (e as unknown as Record<string, unknown>)[k] = v;
+        trackHandler(e, k);
+      } else if (BOOL_PROPS.has(k) || VALUE_PROPS.has(k)) {
+        // Both sets are assigned as DOM properties, not attributes.
+        (e as unknown as Record<string, unknown>)[k] = v;
+      } else {
+        e.setAttribute(k, String(v));
+      }
+    }
+  }
+  for (const child of children) {
+    if (child === null || child === undefined) {
+      continue;
+    }
+    e.appendChild(typeof child === "string" ? document.createTextNode(child) : child);
+  }
+  return e;
+}

package/src/dom/index.ts

@@ -0,0 +1,9 @@
+/** Build and reconcile DOM: `el`, `patch`, `reconcile` and `bindList`. @module */
+
+export { bindList } from "./bind-list.js";
+export type { ListSpec, ListSource } from "./bind-list.js";
+export { el } from "./el.js";
+export type { AttrValue } from "./el.js";
+export { reconcile, KEY_ATTR } from "./reconcile.js";
+export type { ReconcileSpec } from "./reconcile.js";
+export { patch, trackHandler } from "./reconcile-tree.js";