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

package/src/actions/error.ts

@@ -0,0 +1,161 @@
+import type { ActionErrorLike } from "./types.js";
+
+/**
+ * Structured error thrown from an action's `run()` to signal a typed failure.
+ *
+ * @example
+ * ```ts
+ * throw new ActionError("Server rejected", { status: 409, code: "conflict" });
+ * ```
+ */
+export class ActionError extends Error implements ActionErrorLike {
+  readonly status?: number;
+  readonly code?: string;
+  override readonly cause?: unknown;
+
+  constructor(message: string, opts?: { status?: number; code?: string; cause?: unknown }) {
+    super(message);
+    this.name = "ActionError";
+    if (opts?.status !== undefined) {
+      this.status = opts.status;
+    }
+    if (opts?.code !== undefined) {
+      this.code = opts.code;
+    }
+    if (opts?.cause !== undefined) {
+      this.cause = opts.cause;
+    }
+  }
+}
+
+/** True when `v` is a non-null object with a string `error` property. */
+export function hasErrorString(v: unknown): v is { error: string } {
+  if (typeof v !== "object" || v === null || !("error" in v)) {
+    return false;
+  }
+  return typeof v.error === "string";
+}
+
+/** Coerce any thrown value into an ActionErrorLike snapshot. */
+export function toActionError(e: unknown): ActionErrorLike {
+  if (e instanceof ActionError) {
+    const r: { message: string; status?: number; code?: string; cause?: unknown } = {
+      message: e.message,
+    };
+    if (e.status !== undefined) {
+      r.status = e.status;
+    }
+    if (e.code !== undefined) {
+      r.code = e.code;
+    }
+    if (e.cause !== undefined) {
+      r.cause = e.cause;
+    }
+    return r;
+  }
+  if (e instanceof DOMException) {
+    const code =
+      e.name === "TimeoutError"
+        ? "timeout"
+        : e.name === "AbortError"
+          ? "cancelled"
+          : e.name === "NetworkError"
+            ? "network"
+            : e.name.toLowerCase();
+    const isNetLayer = code === "network" || code === "timeout";
+    return { message: e.message, code, ...(isNetLayer && { status: 0 }), cause: e };
+  }
+  if (e instanceof AggregateError) {
+    const first: unknown = e.errors[0];
+    const inner = first instanceof Error ? first.message : e.message;
+    return { message: inner || e.message, code: "aggregate", cause: e };
+  }
+  if (e instanceof Error) {
+    const rawStatus = "status" in e ? (e as { status: unknown }).status : undefined;
+    const status = typeof rawStatus === "number" ? rawStatus : undefined;
+    const rawCode = "code" in e ? (e as { code: unknown }).code : undefined;
+    const code = typeof rawCode === "string" ? rawCode : undefined;
+    const r: { message: string; status?: number; code?: string; cause: unknown } = {
+      message: e.message,
+      cause: e,
+    };
+    if (status !== undefined) {
+      r.status = status;
+    }
+    if (code !== undefined) {
+      r.code = code;
+    }
+    return r;
+  }
+  if (typeof e === "object" && e !== null && "message" in e) {
+    const obj = e as { message: unknown; status?: unknown; code?: unknown };
+    const message = typeof obj.message === "string" ? obj.message : String(obj.message);
+    const status = typeof obj.status === "number" ? obj.status : undefined;
+    const code = typeof obj.code === "string" ? obj.code : undefined;
+    const r: { message: string; status?: number; code?: string; cause: unknown } = {
+      message,
+      cause: e,
+    };
+    if (status !== undefined) {
+      r.status = status;
+    }
+    if (code !== undefined) {
+      r.code = code;
+    }
+    return r;
+  }
+  if (e === null) {
+    return { message: "Unknown error. The thrown value was null.", code: "unknown" };
+  }
+  if (e === undefined) {
+    return { message: "Unknown error. The thrown value was undefined.", code: "unknown" };
+  }
+  // eslint-disable-next-line @typescript-eslint/no-base-to-string -- intentional coercion of unknown thrown value
+  const msg = String(e);
+  return {
+    message: msg !== "" ? msg : "Unknown error. The thrown value was empty.",
+    code: "unknown",
+    cause: e,
+  };
+}
+
+/**
+ * Classify a caught fetch error into an ActionError with a canonical code:
+ * aborted signal -> "cancelled", DOMException Timeout/AbortError -> "timeout",
+ * else -> "network".
+ */
+export function classifyFetchError(e: unknown, signal: AbortSignal): ActionError {
+  if (signal.aborted) {
+    return new ActionError("Request cancelled", { code: "cancelled", cause: e });
+  }
+  if (e instanceof DOMException) {
+    if (e.name === "TimeoutError" || e.name === "AbortError") {
+      return new ActionError("Request timed out", { status: 0, code: "timeout", cause: e });
+    }
+  }
+  if (e instanceof TypeError) {
+    return new ActionError(e.message, { status: 0, code: "network", cause: e });
+  }
+  const msg = e instanceof Error ? e.message : "network error";
+  return new ActionError(msg, { status: 0, code: "network", cause: e });
+}
+
+/** HTTP statuses that represent transient server-side conditions. */
+const TRANSIENT_STATUSES = new Set([408, 429, 502, 503, 504]);
+
+/** Retry classifier preset: network/timeout failures and transient HTTP statuses. */
+export function retryNetwork(err: ActionErrorLike): boolean {
+  if (err.code === "cancelled") {
+    return false;
+  }
+  if (err.code === "network" || err.code === "timeout") {
+    return true;
+  }
+  if (err.status === 0) {
+    return true;
+  }
+  if (err.status !== undefined && TRANSIENT_STATUSES.has(err.status)) {
+    return true;
+  }
+  return false;
+}

package/src/actions/index.ts

@@ -0,0 +1,60 @@
+/** Server actions with pending state, retries, optimistic rollback, polling and debouncing. @module */
+
+export { configure } from "./notifier.js";
+export type { Notifier, NotifierRetry } from "./notifier.js";
+
+export { configureTransport, transportAction, IDEMPOTENCY_COMMAND_FIELD } from "./transport.js";
+export type { TransportSendResult, TransportCommand, TransportSendFn } from "./transport.js";
+
+export { defineAction, IDEMPOTENCY_HEADER } from "./define.js";
+export { apiAction, configureApi } from "./api.js";
+export type {
+  ApiConfig,
+  ApiActionDefinition,
+  ApiDecodeContext,
+  ApiErrorInfo,
+  ApiErrorDecision,
+} from "./api.js";
+
+export { ActionError, hasErrorString, classifyFetchError, retryNetwork } from "./error.js";
+
+export {
+  subscribe as subscribeToActions,
+  subscribeByName,
+  getActionLog,
+  pendingCount,
+  isPending,
+} from "./registry.js";
+
+export { bindLoadingState } from "./loading.js";
+
+export { withAsyncFeedback } from "./async-feedback.js";
+export type { AsyncFeedbackOptions } from "./async-feedback.js";
+
+export { registerCleanup } from "./cleanup.js";
+
+export { debouncedDispatch } from "./debounce.js";
+export type { DebouncedDispatch } from "./debounce.js";
+
+export { pollAction } from "./poll.js";
+export type { PollOptions } from "./poll.js";
+
+export { pollUntil } from "./poll-until.js";
+export type { PollUntilOptions, PollUntilOutcome } from "./poll-until.js";
+
+export type {
+  Action,
+  ActionContext,
+  ActionDefinition,
+  ActionErrorLike,
+  ActionInstance,
+  ActionLifecycleStatus,
+  ActionOutcome,
+  DispatchHandle,
+  DispatchOptions,
+  NotificationSpec,
+  RegistryListener,
+  RequestSpec,
+  RetryConfig,
+} from "./types.js";
+export { RETRY_STANDARD } from "./types.js";

package/src/actions/loading.ts

@@ -0,0 +1,131 @@
+import { createRoot, effect } from "../signal/signal.js";
+
+import { isPending, pendingCount } from "./registry.js";
+
+/** Element types that have a `.disabled` writable boolean. */
+type DisableableElement =
+  HTMLButtonElement | HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+interface BindLoadingOptions {
+  ariaBusy?: boolean;
+  preserveAriaBusy?: boolean;
+  pendingClass?: string;
+  preserveDisabled?: boolean;
+  disabledFn?: () => boolean;
+}
+
+/** Bind a button/input element's disabled / aria-busy state to one or more named actions.
+ *  The binding ends, restoring the element, when the returned function is called
+ *  or when the `@cplieger/ui/signal` owner it was created under is disposed. */
+export function bindLoadingState(
+  actionName: string | readonly string[],
+  el: DisableableElement,
+  opts: BindLoadingOptions = {},
+): () => void {
+  const names: readonly string[] = typeof actionName === "string" ? [actionName] : actionName;
+
+  const {
+    ariaBusy = true,
+    preserveAriaBusy = false,
+    pendingClass,
+    preserveDisabled = false,
+    disabledFn,
+  } = opts;
+  const manageAriaBusy = ariaBusy && !preserveAriaBusy;
+  let wasPending = false;
+  let baseDisabled = el.disabled;
+  let hadFocus = false;
+  let wasConnected = el.isConnected;
+
+  const resolveBase = (): boolean => {
+    if (disabledFn !== undefined) {
+      try {
+        return disabledFn();
+      } catch {
+        return false;
+      }
+    }
+    return preserveDisabled ? baseDisabled : false;
+  };
+
+  const setIdle = (): void => {
+    el.disabled = resolveBase();
+    if (manageAriaBusy) {
+      el.removeAttribute("aria-busy");
+    }
+    if (pendingClass) {
+      el.classList.remove(pendingClass);
+    }
+    if (hadFocus && el.isConnected && !el.disabled) {
+      const active = document.activeElement;
+      if (active === null || active === document.body) {
+        el.focus();
+      }
+    }
+    hadFocus = false;
+  };
+
+  // An empty name list sums nothing, so this stays false for the binding's
+  // whole life and the effect below never touches the element.
+  const readPending = (): boolean =>
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- the length-1 branch proves index 0
+    names.length === 1 ? isPending(names[0]!) : pendingCount(names) > 0;
+
+  const run = (dispose: () => void): void => {
+    if (wasConnected && !el.isConnected) {
+      dispose();
+      return;
+    }
+    if (el.isConnected) {
+      wasConnected = true;
+    }
+    const pending = readPending();
+    if (pending && !wasPending) {
+      baseDisabled = el.disabled;
+      hadFocus = document.activeElement === el;
+    }
+    if (pending) {
+      el.disabled = true;
+      if (manageAriaBusy) {
+        el.setAttribute("aria-busy", "true");
+      }
+      if (pendingClass) {
+        el.classList.add(pendingClass);
+      }
+    } else if (wasPending) {
+      setIdle();
+    }
+    wasPending = pending;
+  };
+
+  const restore = (): void => {
+    if (wasPending) {
+      setIdle();
+      wasPending = false;
+    }
+  };
+
+  let restoreOnDispose = true;
+  return createRoot((dispose, owner) => {
+    // Runs after the effect is released, so a signal write from restore's
+    // focus() handler cannot re-run it. Self-release and the returned function
+    // clear the flag: the first leaves the element as it is, the second
+    // restores in the caller's context instead of this closing owner's.
+    owner.onDispose(() => {
+      if (restoreOnDispose) {
+        restore();
+      }
+    });
+    effect(() => {
+      run(() => {
+        restoreOnDispose = false;
+        dispose();
+      });
+    });
+    return () => {
+      restoreOnDispose = false;
+      dispose();
+      restore();
+    };
+  });
+}

package/src/actions/notifier.ts

@@ -0,0 +1,61 @@
+/** Retry button descriptor passed to error notifications. */
+export interface NotifierRetry {
+  readonly onClick: () => void;
+}
+
+/** Consumer-provided notification adapter, wired via `configure()`. Both methods
+ *  optional; unset ones drop silently.
+ *
+ *  SECURITY: `message` may carry server-controlled text (e.g. an HTTP error
+ *  body's `error` field). Render as TEXT, never innerHTML — reflected XSS risk. */
+export interface Notifier {
+  success?(message: string): void;
+  error?(message: string, retry?: NotifierRetry): void;
+}
+
+let _notifier: Notifier = {};
+let _configured = false;
+let _warnedUnconfigured = false;
+
+/** Configure the global notifier adapter. `configure({})` is the explicit
+ *  headless opt-in — silent, no unconfigured-drop warning. */
+export function configure(notifier: Notifier): void {
+  _notifier = notifier;
+  _configured = true;
+}
+
+/** Warn once on the first notification dropped because configure() was never called. */
+function warnUnconfiguredDrop(kind: string): void {
+  if (_configured || _warnedUnconfigured) {
+    return;
+  }
+  _warnedUnconfigured = true;
+  console.warn(
+    `[actions] ${kind} notification dropped — configure() was never called. Wire a notifier at boot, or call configure({}) for intentional headless silence. This warning fires once.`,
+  );
+}
+
+/** @internal Emit a success notification. */
+export function notifySuccess(message: string): void {
+  if (_notifier.success === undefined) {
+    warnUnconfiguredDrop("success");
+    return;
+  }
+  _notifier.success(message);
+}
+
+/** @internal Emit an error notification. */
+export function notifyError(message: string, retry?: NotifierRetry): void {
+  if (_notifier.error === undefined) {
+    warnUnconfiguredDrop("error");
+    return;
+  }
+  _notifier.error(message, retry);
+}
+
+/** @internal Test-only: reset the notifier to the default no-op. */
+export function _resetNotifierForTest(): void {
+  _notifier = {};
+  _configured = false;
+  _warnedUnconfigured = false;
+}

package/src/actions/poll-until.ts

@@ -0,0 +1,133 @@
+// Unlike pollAction, no pauseWhenHidden/refreshOnFocus: this is a bounded
+// flow the caller drives to completion, not a background refresh.
+
+/** Options for {@link pollUntil}. The loop waits before it polls, so
+ *  `intervalMs` delays the first `step` call as well as the later ones.
+ *  `maxAttempts` and `timeoutMs` are independent budgets, both checked after
+ *  that wait and before `step` runs, so either one expiring yields `timeout`
+ *  without a final poll. */
+export interface PollUntilOptions<T> {
+  readonly intervalMs: number;
+  /** Returns true on a result that ends the poll. */
+  readonly until: (result: T) => boolean;
+  /** 0/undefined = unlimited. */
+  readonly maxAttempts?: number;
+  readonly timeoutMs?: number;
+  /** Applied to the wait after consecutive transient failures (null result or throw). */
+  readonly backoff?: { readonly factor: number; readonly maxMs: number };
+  /** Fires for a non-terminal successful poll. */
+  readonly onPoll?: (result: T) => void;
+  /** Fires on a transient failure (step returned null or threw). */
+  readonly onTransientError?: () => void;
+  /** A pre-aborted signal resolves `aborted` without calling `step`. */
+  readonly signal?: AbortSignal;
+}
+
+/** Terminal result of {@link pollUntil}, which resolves in every case and never
+ *  rejects. `done` carries the first result `until` accepted; `timeout` means a
+ *  budget expired, drawing no distinction between the attempt and the time
+ *  budget; `aborted` means the signal fired, which wins over a transient
+ *  failure observed in the same iteration. A `step` that throws is transient,
+ *  never terminal, so no member here reports it. */
+export type PollUntilOutcome<T> =
+  | { readonly status: "done"; readonly result: T }
+  | { readonly status: "timeout" }
+  | { readonly status: "aborted" };
+
+/** Resolves early (never rejects) if `signal` fires; caller re-checks `signal.aborted`. */
+function sleepWithSignal(ms: number, signal: AbortSignal): Promise<void> {
+  if (signal.aborted) {
+    return Promise.resolve();
+  }
+  return new Promise<void>((resolve) => {
+    const ac = new AbortController();
+    const t = setTimeout(() => {
+      ac.abort();
+      resolve();
+    }, ms);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(t);
+        ac.abort();
+        resolve();
+      },
+      { signal: ac.signal },
+    );
+  });
+}
+
+/** A null result or a throw is a transient failure (backs off if `backoff` is set). */
+export async function pollUntil<T>(
+  step: (signal: AbortSignal) => Promise<T | null>,
+  opts: PollUntilOptions<T>,
+): Promise<PollUntilOutcome<T>> {
+  const { intervalMs, until, maxAttempts, timeoutMs, backoff, onPoll, onTransientError } = opts;
+  const signal = opts.signal ?? new AbortController().signal;
+
+  if (signal.aborted) {
+    return { status: "aborted" };
+  }
+
+  const start = Date.now();
+  let attempts = 0;
+  let failures = 0;
+
+  for (;;) {
+    const delay =
+      backoff !== undefined && failures > 0
+        ? Math.min(intervalMs * Math.pow(backoff.factor, failures), backoff.maxMs)
+        : intervalMs;
+    await sleepWithSignal(delay, signal);
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- aborted flips during the awaited sleep
+    if (signal.aborted) {
+      return { status: "aborted" };
+    }
+    attempts += 1;
+    if (maxAttempts !== undefined && maxAttempts > 0 && attempts > maxAttempts) {
+      return { status: "timeout" };
+    }
+    if (timeoutMs !== undefined && Date.now() - start >= timeoutMs) {
+      return { status: "timeout" };
+    }
+
+    let result: T | null;
+    try {
+      result = await step(signal);
+    } catch {
+      result = null;
+    }
+
+    // Abort that fired during step() wins over treating the (likely null)
+    // result as a transient failure — no spurious onTransientError on teardown.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- aborted flips during the awaited step
+    if (signal.aborted) {
+      return { status: "aborted" };
+    }
+
+    if (result === null) {
+      if (onTransientError !== undefined) {
+        try {
+          onTransientError();
+        } catch (e) {
+          console.error("[pollUntil] onTransientError threw", e);
+        }
+      }
+      failures += 1;
+      continue;
+    }
+
+    failures = 0;
+    if (until(result)) {
+      return { status: "done", result };
+    }
+    if (onPoll !== undefined) {
+      try {
+        onPoll(result);
+      } catch (e) {
+        console.error("[pollUntil] onPoll threw", e);
+      }
+    }
+  }
+}

package/src/actions/poll.ts

@@ -0,0 +1,156 @@
+import { createRoot } from "../signal/signal.js";
+
+import { registerCleanup } from "./cleanup.js";
+import type { Action } from "./types.js";
+
+/** Options for {@link pollAction}. `interval` is the gap between one poll
+ *  settling and the next starting rather than a fixed cadence, so a slow action
+ *  cannot queue polls behind itself. `backoffOnError` stretches that gap by
+ *  `factor` per consecutive failure, capped at `max`; a failure means the
+ *  dispatch resolved `null`, which is the only failure signal a poller gets
+ *  because the action has already absorbed the error itself. `onSuccess` fires
+ *  only for a non-null result, and a throw from it is logged rather than
+ *  stopping the loop. */
+export interface PollOptions<TResult = unknown> {
+  readonly interval: number;
+  /** Default true: pause while document.hidden. */
+  readonly pauseWhenHidden?: boolean;
+  /** Default true: fire an immediate poll on window focus. */
+  readonly refreshOnFocus?: boolean;
+  readonly backoffOnError?: { readonly factor: number; readonly max: number };
+  readonly onSuccess?: (result: TResult) => void;
+}
+
+/** Start polling an action in the background and return its stop function.
+ *  Single-flight: a tick, focus-triggered ones included, that lands during a
+ *  dispatch is dropped. The first poll runs at once unless the document is
+ *  hidden, then waits until it is shown. `stop()` is idempotent and also runs
+ *  on page unload. Without `document` or `window` the loop is a plain
+ *  interval. */
+export function pollAction<TArgs, TResult>(
+  action: Action<TArgs, TResult>,
+  args: TArgs,
+  opts: PollOptions<TResult>,
+): () => void {
+  const pauseWhenHidden = opts.pauseWhenHidden !== false;
+  const refreshOnFocus = opts.refreshOnFocus !== false;
+  const baseInterval = opts.interval;
+  const backoff = opts.backoffOnError;
+  const onSuccess = opts.onSuccess;
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let stopped = false;
+  let paused = false;
+  let inFlight = false;
+  let failures = 0;
+
+  // First, so an owner already being disposed throws before anything starts.
+  const releaseOwner = createRoot((dispose, owner) => {
+    owner.onDispose(stop);
+    return dispose;
+  });
+
+  function nextDelay(): number {
+    if (backoff === undefined || failures === 0) {
+      return baseInterval;
+    }
+    return Math.min(baseInterval * Math.pow(backoff.factor, failures), backoff.max);
+  }
+
+  function schedule(): void {
+    if (stopped || paused) {
+      return;
+    }
+    if (timer !== undefined) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      void tick();
+    }, nextDelay());
+  }
+
+  async function tick(): Promise<void> {
+    if (stopped || paused) {
+      return;
+    }
+    if (inFlight) {
+      return;
+    }
+    inFlight = true;
+    try {
+      const result = await action.dispatch(args);
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- state changes during async
+      if (stopped) {
+        return;
+      }
+      if (result === null) {
+        failures += 1;
+      } else {
+        failures = 0;
+        if (onSuccess !== undefined) {
+          try {
+            onSuccess(result);
+          } catch (e) {
+            console.error("[pollAction] onSuccess threw", e);
+          }
+        }
+      }
+    } finally {
+      inFlight = false;
+    }
+    schedule();
+  }
+
+  const onVisibility = (): void => {
+    if (document.hidden) {
+      paused = true;
+      if (timer !== undefined) {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+    } else if (paused) {
+      paused = false;
+      void tick();
+    }
+  };
+
+  const onFocus = (): void => {
+    // No guard here: `tick` drops a poll that is stopped, paused or already in
+    // flight, so re-checking would make its own guard unreachable.
+    void tick();
+  };
+
+  function stop(): void {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    if (timer !== undefined) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    listenerCtrl.abort();
+    unregisterCleanup();
+    releaseOwner();
+  }
+
+  const listenerCtrl = new AbortController();
+
+  if (pauseWhenHidden && typeof document !== "undefined") {
+    document.addEventListener("visibilitychange", onVisibility, { signal: listenerCtrl.signal });
+    if (document.hidden) {
+      paused = true;
+    }
+  }
+  if (refreshOnFocus && typeof window !== "undefined") {
+    window.addEventListener("focus", onFocus, { signal: listenerCtrl.signal });
+  }
+
+  const unregisterCleanup = registerCleanup(stop);
+
+  if (!paused) {
+    void tick();
+  }
+
+  return stop;
+}