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

package/src/fetch/types.ts

@@ -0,0 +1,206 @@
+/** Public types for @cplieger/ui/fetch. No imports, no runtime behavior. */
+
+/** HTTP verbs the wrapper speaks. */
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * A runtime validator for a 2xx response body: returns the typed value or
+ * THROWS on a mismatch. Ships no combinators — each consumer supplies its own
+ * validators (hand-written, zod, valibot, …).
+ */
+export type Decoder<T> = (value: unknown) => T;
+
+/** Configuration for a fetch instance. Captured immutably by
+ *  {@link createFetch} (shallow-copied and frozen at construction); a changed
+ *  backend produces a new instance. */
+export interface FetchConfig {
+  /** Prepended to relative paths, minus one trailing `/`. With it set,
+   *  an absolute (`https://…`) or protocol-relative (`//host`) path stays a
+   *  path segment and cannot override the origin. With it UNSET, `path` goes
+   *  to `fetch()` verbatim, so the caller owns the full URL and must never
+   *  pass untrusted input as the whole path. */
+  baseUrl?: string;
+  /** `RequestInit.credentials` mode applied to every request (e.g. `"include"`
+   *  for cookies). */
+  credentials?: RequestCredentials;
+  /** Custom fetch implementation. Useful for SSR (isomorphic fetch) or tests. */
+  fetchFn?: typeof fetch;
+  /** Inject headers on every request. Mutate the provided instance and/or
+   *  return a replacement (a returned `Headers` wins wholesale, otherwise the
+   *  mutated instance is used). May be async — read late-bound state (a token
+   *  set after boot) from inside the hook rather than reconfiguring the
+   *  instance. */
+  prepareHeaders?: (headers: Headers) => Headers | undefined | Promise<Headers | undefined>;
+  /** Optional cap on the response body size in bytes. Unset or `Infinity`
+   *  means unlimited. When set, a larger body is rejected instead of buffered.
+   *  `NaN` or a negative number is rejected by {@link createFetch} with a
+   *  `TypeError`. */
+  maxResponseBytes?: number;
+  /** Observes every failure this instance returns, `decode` included, after
+   *  its `code` is lifted and before the caller receives the same `ApiErr`
+   *  object. Its return value is ignored and the promise is not awaited; a
+   *  throw or a rejection is logged with `console.error` and swallowed, so it
+   *  can never replace or delay the caller's failure. */
+  onError?: (err: ApiErr, req: FailedRequest) => void | Promise<void>;
+}
+
+/** The request an {@link FetchConfig.onError} failure belongs to. */
+export interface FailedRequest {
+  readonly method: HttpMethod;
+  /** The path as the caller passed it, before the `baseUrl` join. */
+  readonly path: string;
+}
+
+/** Successful result envelope. */
+export interface ApiOk<T> {
+  readonly ok: true;
+  readonly status: number;
+  /** The decoded / parsed response body, or a `Blob` under `as: "blob"`.
+   *  `undefined` for a 204 or an empty body read as JSON; the null-collapsing helpers
+   *  turn that into `null`. */
+  readonly data: T;
+  /** Response headers. Always present: a success envelope exists only once a
+   *  real HTTP response was received. */
+  readonly headers: Headers;
+}
+
+/** Failure result envelope. Never thrown — always returned by `requestRaw`. */
+export interface ApiErr {
+  readonly ok: false;
+  /** HTTP status, or 0 for a network / timeout / cancelled / invalid failure. */
+  readonly status: number;
+  /** Human-readable message. */
+  readonly error: string;
+  /** Machine code: `"network"` | `"timeout"` | `"cancelled"` | `"decode"` |
+   *  `"invalid"`, or a code lifted from the server's error body, which can
+   *  spoof a reserved one. Disambiguate by `status`, never by `code` alone:
+   *  reserved codes carry `status === 0` (`"decode"` its real 2xx status), a
+   *  lifted code always the real non-2xx status. */
+  readonly code?: string;
+  /** Lifted from the error body's `request_id` / `requestId`, when present. */
+  readonly requestId?: string;
+  /** The parsed JSON body of the failed response, present when a real HTTP
+   *  response carried parseable JSON (any shape). Absent on network / timeout
+   *  / cancelled / invalid failures and on non-JSON / empty bodies.
+   *
+   *  SECURITY: server-controlled content, same trust level as `error` —
+   *  validate the shape before reading fields, and render any text from it
+   *  via textContent, never innerHTML. */
+  readonly body?: unknown;
+  /** Response headers, present only when an HTTP response was actually
+   *  received (a non-2xx error, or a 2xx whose body failed decoding). Absent
+   *  on network / timeout / cancelled / invalid failures, the same rule that
+   *  makes {@link ApiOk.headers} always present. */
+  readonly headers?: Headers;
+}
+
+/** Discriminated union returned by `requestRaw` and the `*Raw` verb helpers. */
+export type ApiResult<T> = ApiOk<T> | ApiErr;
+
+/** The options every request takes, whatever its 2xx body is read as. */
+interface RequestOptionsBase {
+  /** JSON-encoded and sent on a non-GET request unless it is `null` or
+   *  `undefined`, so a JSON `null` body is never sent. Ignored on GET. */
+  body?: unknown;
+  /** Pre-encoded request body for non-GET requests, sent as-is with NO JSON
+   *  encoding and NO automatic Content-Type — the caller owns the type via
+   *  `headers`. Mutually exclusive with `body` (both set is a client-side
+   *  `"invalid"` failure). */
+  rawBody?: BodyInit;
+  /** Caller cancellation signal, composed with the request timeout. */
+  signal?: AbortSignal;
+  /** Per-request headers, merged before the global `prepareHeaders` hook. */
+  headers?: Record<string, string> | Headers;
+  /** Overrides the default request timeout (`API_TIMEOUT_MS`) for this request. */
+  timeoutMs?: number;
+}
+
+/** Options for a request whose 2xx body is read as JSON, the default. */
+export interface RequestOptions<T = unknown> extends RequestOptionsBase {
+  as?: "json";
+  /** Optional runtime validation applied to a 2xx body. */
+  decoder?: Decoder<T>;
+  /** Skip reading a 2xx response body entirely: resolves ok with
+   *  `data: undefined` and any `decoder` is not invoked. Non-2xx error bodies
+   *  are still parsed. For endpoints whose success body is irrelevant or
+   *  non-JSON. */
+  ignoreBody?: boolean;
+}
+
+/** Options for a request whose 2xx body, a 204 included, is read whole as a
+ *  `Blob` under `maxResponseBytes`. Its `type` is the response's
+ *  `Content-Type`, lowercased, or empty when there is none or it holds a
+ *  character outside printable ASCII. A non-2xx body is still read as JSON. */
+export interface BlobRequestOptions extends RequestOptionsBase {
+  as: "blob";
+  decoder?: never;
+  ignoreBody?: never;
+}
+
+/** What the one request implementation accepts behind the overloads.
+ *  @internal */
+export type AnyRequestOptions<T = unknown> = RequestOptions<T> | BlobRequestOptions;
+
+/** Admits only `Blob` itself as a Blob read's `T`: a subtype such as `File`
+ *  would claim fields the read never sets. */
+type ExactlyBlob<T> = [Blob] extends [T] ? unknown : never;
+
+/** The non-throwing request core: always resolves to an {@link ApiResult},
+ *  never throws. */
+export interface RequestRawFn {
+  <T>(method: HttpMethod, path: string, opts?: RequestOptions<T>): Promise<ApiResult<T>>;
+  <T extends Blob = Blob>(
+    method: HttpMethod,
+    path: string,
+    opts: BlobRequestOptions & ExactlyBlob<T>,
+  ): Promise<ApiResult<T>>;
+}
+
+/** The null-collapsing request: the decoded body, or `null` on any error or
+ *  empty JSON body. */
+export interface RequestFn {
+  <T>(method: HttpMethod, path: string, opts?: RequestOptions<T>): Promise<T | null>;
+  <T extends Blob = Blob>(
+    method: HttpMethod,
+    path: string,
+    opts: BlobRequestOptions & ExactlyBlob<T>,
+  ): Promise<T | null>;
+}
+
+/** A GET or DELETE helper returning the data or `null`. */
+export interface ReadVerb {
+  <T>(path: string, opts?: RequestOptions<T>): Promise<T | null>;
+  <T extends Blob = Blob>(
+    path: string,
+    opts: BlobRequestOptions & ExactlyBlob<T>,
+  ): Promise<T | null>;
+}
+
+/** A GET or DELETE helper returning the full {@link ApiResult}. */
+export interface ReadVerbRaw {
+  <T>(path: string, opts?: RequestOptions<T>): Promise<ApiResult<T>>;
+  <T extends Blob = Blob>(
+    path: string,
+    opts: BlobRequestOptions & ExactlyBlob<T>,
+  ): Promise<ApiResult<T>>;
+}
+
+/** A helper sending a JSON body and returning the data or `null`. */
+export interface WriteVerb {
+  <T>(path: string, body?: unknown, opts?: RequestOptions<T>): Promise<T | null>;
+  <T extends Blob = Blob>(
+    path: string,
+    body: unknown,
+    opts: BlobRequestOptions & ExactlyBlob<T>,
+  ): Promise<T | null>;
+}
+
+/** A helper sending a JSON body and returning the full {@link ApiResult}. */
+export interface WriteVerbRaw {
+  <T>(path: string, body?: unknown, opts?: RequestOptions<T>): Promise<ApiResult<T>>;
+  <T extends Blob = Blob>(
+    path: string,
+    body: unknown,
+    opts: BlobRequestOptions & ExactlyBlob<T>,
+  ): Promise<ApiResult<T>>;
+}

package/src/fetch/verbs.ts

@@ -0,0 +1,103 @@
+import type { RequestCore, RequestRawCore } from "./request.js";
+import type {
+  AnyRequestOptions,
+  ApiResult,
+  Decoder,
+  ReadVerb,
+  ReadVerbRaw,
+  RequestOptions,
+  WriteVerb,
+  WriteVerbRaw,
+} from "./types.js";
+
+/** The bundle of 12 verb helpers a fetch instance exposes. */
+export interface FetchVerbs {
+  /** GET; returns the decoded body or `null` on any error. */
+  apiGet: ReadVerb;
+  /** POST a JSON body; returns the decoded body or `null` on any error. */
+  apiPost: WriteVerb;
+  /** PUT a JSON body; returns the decoded body or `null` on any error. */
+  apiPut: WriteVerb;
+  /** PATCH a JSON body; returns the decoded body or `null` on any error. */
+  apiPatch: WriteVerb;
+  /** DELETE; returns the decoded body or `null` on any error. */
+  apiDelete: ReadVerb;
+  /** GET with runtime validation; returns the decoded body or `null` on any error. */
+  apiGetTyped: <T>(
+    path: string,
+    decoder: Decoder<T>,
+    opts?: RequestOptions<T>,
+  ) => Promise<T | null>;
+  /** POST with runtime validation; returns the decoded body or `null` on any error. */
+  apiPostTyped: <T>(
+    path: string,
+    body: unknown,
+    decoder: Decoder<T>,
+    opts?: RequestOptions<T>,
+  ) => Promise<T | null>;
+  /** GET; returns the full {@link ApiResult} envelope. */
+  apiGetRaw: ReadVerbRaw;
+  /** POST a JSON body; returns the full {@link ApiResult} envelope. */
+  apiPostRaw: WriteVerbRaw;
+  /** PUT a JSON body; returns the full {@link ApiResult} envelope. */
+  apiPutRaw: WriteVerbRaw;
+  /** PATCH a JSON body; returns the full {@link ApiResult} envelope. */
+  apiPatchRaw: WriteVerbRaw;
+  /** DELETE; returns the full {@link ApiResult} envelope. */
+  apiDeleteRaw: ReadVerbRaw;
+}
+
+/** Bind the 12 verb helpers to a `(request, requestRaw)` pair. */
+export function makeVerbs(request: RequestCore, requestRaw: RequestRawCore): FetchVerbs {
+  return {
+    apiGet<T>(path: string, opts?: AnyRequestOptions<T>): Promise<T | null> {
+      return request<T>("GET", path, opts);
+    },
+    apiPost<T>(path: string, body?: unknown, opts?: AnyRequestOptions<T>): Promise<T | null> {
+      return request<T>("POST", path, { ...opts, body });
+    },
+    apiPut<T>(path: string, body?: unknown, opts?: AnyRequestOptions<T>): Promise<T | null> {
+      return request<T>("PUT", path, { ...opts, body });
+    },
+    apiPatch<T>(path: string, body?: unknown, opts?: AnyRequestOptions<T>): Promise<T | null> {
+      return request<T>("PATCH", path, { ...opts, body });
+    },
+    apiDelete<T>(path: string, opts?: AnyRequestOptions<T>): Promise<T | null> {
+      return request<T>("DELETE", path, opts);
+    },
+    apiGetTyped<T>(path: string, decoder: Decoder<T>, opts?: RequestOptions<T>): Promise<T | null> {
+      return request<T>("GET", path, { ...opts, decoder });
+    },
+    apiPostTyped<T>(
+      path: string,
+      body: unknown,
+      decoder: Decoder<T>,
+      opts?: RequestOptions<T>,
+    ): Promise<T | null> {
+      return request<T>("POST", path, { ...opts, body, decoder });
+    },
+    apiGetRaw<T>(path: string, opts?: AnyRequestOptions<T>): Promise<ApiResult<T>> {
+      return requestRaw<T>("GET", path, opts);
+    },
+    apiPostRaw<T>(
+      path: string,
+      body?: unknown,
+      opts?: AnyRequestOptions<T>,
+    ): Promise<ApiResult<T>> {
+      return requestRaw<T>("POST", path, { ...opts, body });
+    },
+    apiPutRaw<T>(path: string, body?: unknown, opts?: AnyRequestOptions<T>): Promise<ApiResult<T>> {
+      return requestRaw<T>("PUT", path, { ...opts, body });
+    },
+    apiPatchRaw<T>(
+      path: string,
+      body?: unknown,
+      opts?: AnyRequestOptions<T>,
+    ): Promise<ApiResult<T>> {
+      return requestRaw<T>("PATCH", path, { ...opts, body });
+    },
+    apiDeleteRaw<T>(path: string, opts?: AnyRequestOptions<T>): Promise<ApiResult<T>> {
+      return requestRaw<T>("DELETE", path, opts);
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+/** Signals, effects, owners, stores and the DOM helpers: every name in `@cplieger/ui/signal` and `@cplieger/ui/dom`. @module */
+
+export * from "./signal/index.js";
+export * from "./dom/index.js";

package/src/primitives/announce.ts

@@ -0,0 +1,134 @@
+/**
+ * announce.ts — Screen-reader announcements through pre-mounted live regions:
+ * a polite and an assertive one per surface, the root's from `mountLiveRegions`
+ * and each `<dialog>`'s that the dialog primitives drive. A region inserted or
+ * moved in the mutation that fills it is not reliably announced, so `announce`
+ * never creates or moves one.
+ * @module
+ */
+
+import { acquireRegions, regionsOf } from "./live-regions.js";
+import type { Politeness } from "./live-regions.js";
+import { trackedModals, whenUncovered } from "./modal-host.js";
+
+/** Gap (ms) between clearing the region and setting the new text: the
+ *  empty-then-text change is what makes assistive tech re-announce identical
+ *  text, and a microtask gap is too short for it to see two mutations. */
+const ANNOUNCE_DELAY_MS = 100;
+
+interface RootMount {
+  readonly host: HTMLElement;
+  readonly release: () => void;
+}
+
+/** Root mounts still held, oldest first; the newest one's host is the root. */
+const roots: RootMount[] = [];
+
+const pending = new Map<Politeness, ReturnType<typeof setTimeout>>();
+
+/** The regions holding an announcement's text, emptied before a modal's close or
+ *  removal uncovers them: a browser can read an alert region again when exposed
+ *  (Chromium, ui/accessibility/ax_event_generator.cc OnIgnoredChanged). */
+const written = new Set<HTMLElement>();
+
+function clearWritten(): void {
+  for (const region of written) {
+    region.textContent = "";
+  }
+  written.clear();
+}
+
+/** Mount the page's root polite and assertive live regions as `host`'s last
+ *  children and make `host` the root. Call it once at boot, before the first
+ *  render, so the regions exist before anything is announced. A pair still
+ *  inside `host` is kept rather than replaced. Returns this mount's release,
+ *  which is idempotent: the root falls back to the newest mount still held,
+ *  and the pair leaves `host` when its last owner releases (never, on a dialog
+ *  the dialog primitives drive, which keeps its pair). */
+export function mountLiveRegions(host: HTMLElement): () => void {
+  const mount: RootMount = { host, release: acquireRegions(host) };
+  roots.push(mount);
+  return () => {
+    const at = roots.indexOf(mount);
+    if (at === -1) {
+      return;
+    }
+    roots.splice(at, 1);
+    mount.release();
+  };
+}
+
+/** The regions an announcement reaches now: the pair of every open modal the
+ *  library drives and the root's. `showModal()` takes everything outside the
+ *  topmost modal out of the accessibility tree, so the browser, not an opening
+ *  order, picks the one read. With no modal open every open dialog is exposed,
+ *  so only the root's is written, else it would be read twice. */
+function currentRegions(politeness: Politeness): HTMLElement[] {
+  const hosts: HTMLElement[] = trackedModals();
+  const root = roots.at(-1);
+  if (root !== undefined) {
+    hosts.push(root.host);
+  }
+  const regions = new Set<HTMLElement>();
+  for (const host of hosts) {
+    const region = regionsOf(host)?.[politeness];
+    if (region !== undefined) {
+      regions.add(region);
+    }
+  }
+  return [...regions];
+}
+
+function deliver(message: string, politeness: Politeness): void {
+  const cleared = currentRegions(politeness);
+  if (cleared.length === 0) {
+    return;
+  }
+  for (const region of cleared) {
+    region.textContent = "";
+    written.delete(region);
+  }
+  pending.set(
+    politeness,
+    setTimeout(() => {
+      const live = currentRegions(politeness);
+      // A region that joined during the gap (a modal opened, a root mounted) was not
+      // cleared, so identical text would not be announced again there: start over.
+      if (!live.every((region) => cleared.includes(region))) {
+        deliver(message, politeness);
+        return;
+      }
+      // Before the write: a landing run in the change's own task (as under fake timers)
+      // sees records not yet delivered, and their clear must not empty this text.
+      whenUncovered(clearWritten);
+      for (const region of live) {
+        region.textContent = message;
+        written.add(region);
+      }
+    }, ANNOUNCE_DELAY_MS),
+  );
+}
+
+/** Announce `message` to screen readers through the live regions of every open
+ *  modal dialog the dialog primitives drive and the root's from
+ *  {@link mountLiveRegions}; the browser reads the one inside the topmost modal,
+ *  or the root's when no modal is open. A modal's close or removal empties every
+ *  region before it is uncovered. Writes nothing when none is mounted.
+ *  `"assertive"` interrupts, through its own `role="alert"` region; a second
+ *  announcement at the same politeness before the first lands replaces it. */
+export function announce(message: string, politeness: Politeness = "polite"): void {
+  clearTimeout(pending.get(politeness));
+  deliver(message, politeness);
+}
+
+/** Test-only: cancel pending announcements, forget the written regions and
+ *  release every root mount. */
+export function _resetForTest(): void {
+  for (const timer of pending.values()) {
+    clearTimeout(timer);
+  }
+  written.clear();
+  for (const mount of roots.splice(0)) {
+    mount.release();
+  }
+}