nexus-shared 1.1.21 → 3.0.0

package/dist/Components/Viewers/MarkdownView.js

@@ -0,0 +1,79 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { parseMarkdown } from "../../Helpers/MarkdownHelpers.js";
+/**
+ * Shows Markdown as formatted text: headings, lists, tasks, tables, code, quotes, links, and images. Raw HTML stays
+ * text and unsafe addresses are dropped, so it is safe for text from any user. It has no state, so it renders on the
+ * server as well.
+ *
+ * @example <MarkdownView value={room.description} />
+ */
+export function MarkdownView({ value, breaks = true, newTab = "external", placeholder, onTaskToggle, className, ...rest }) {
+    const blocks = parseMarkdown(value, { breaks });
+    return (_jsx("div", { ...rest, className: cx("nx-markdown", className), children: blocks.length > 0 ? renderBlocks(blocks, { newTab, onTaskToggle }) : placeholder && _jsx("p", { className: "nx-markdown__empty", children: placeholder }) }));
+}
+function renderBlocks(blocks, options, tight = false) {
+    return blocks.map((block, key) => {
+        switch (block.type) {
+            case "heading": {
+                const Heading = `h${block.level}`;
+                return _jsx(Heading, { children: renderInlines(block.children, options) }, key);
+            }
+            case "paragraph":
+                // Items of a tight list hold their text without paragraph spacing.
+                return tight ? _jsx("span", { children: renderInlines(block.children, options) }, key) : _jsx("p", { children: renderInlines(block.children, options) }, key);
+            case "code":
+                return (_jsx("pre", { children: _jsx("code", { className: block.language ? `language-${block.language.replace(/[^\w#+.-]/g, "")}` : undefined, children: block.text }) }, key));
+            case "quote":
+                return _jsx("blockquote", { children: renderBlocks(block.children, options) }, key);
+            case "list": {
+                const List = block.ordered ? "ol" : "ul";
+                return (_jsx(List, { start: block.ordered && block.start !== 1 ? block.start : undefined, children: block.items.map((item, index) => renderItem(item, index, options, block.tight)) }, key));
+            }
+            case "table":
+                return (_jsx("div", { className: "nx-markdown__table", children: _jsxs("table", { children: [_jsx("thead", { children: _jsx("tr", { children: block.head.map((cell, index) => (_jsx("th", { scope: "col", style: block.align[index] ? { textAlign: block.align[index] } : undefined, children: renderInlines(cell.children, options) }, index))) }) }), block.rows.length > 0 && (_jsx("tbody", { children: block.rows.map((row, rowIndex) => (_jsx("tr", { children: row.map((cell, index) => (_jsx("td", { style: block.align[index] ? { textAlign: block.align[index] } : undefined, children: renderInlines(cell.children, options) }, index))) }, rowIndex))) }))] }) }, key));
+            case "rule":
+                return _jsx("hr", {}, key);
+        }
+    });
+}
+function renderItem(item, key, options, tight) {
+    if (item.checked === null)
+        return _jsx("li", { children: renderBlocks(item.children, options, tight) }, key);
+    const { onTaskToggle } = options;
+    const first = item.children[0];
+    const label = first && (first.type === "paragraph" || first.type === "heading") ? plainText(first.children) : undefined;
+    return (_jsxs("li", { className: "nx-markdown__task", children: [_jsx("input", { type: "checkbox", checked: item.checked, disabled: !onTaskToggle, "aria-label": label || "Task", onChange: onTaskToggle ? () => onTaskToggle(item.line, !item.checked) : undefined }), renderBlocks(item.children, options, tight)] }, key));
+}
+function renderInlines(nodes, options) {
+    return nodes.map((node, key) => {
+        switch (node.type) {
+            case "text":
+                return node.text;
+            case "strong":
+                return _jsx("strong", { children: renderInlines(node.children, options) }, key);
+            case "emphasis":
+                return _jsx("em", { children: renderInlines(node.children, options) }, key);
+            case "strike":
+                return _jsx("del", { children: renderInlines(node.children, options) }, key);
+            case "code":
+                return _jsx("code", { children: node.text }, key);
+            case "break":
+                return _jsx("br", {}, key);
+            case "image":
+                return node.src === null ? (_jsx("span", { children: node.alt }, key)) : (_jsx("img", { src: node.src, alt: node.alt, title: node.title, loading: "lazy", decoding: "async" }, key));
+            case "link": {
+                const children = renderInlines(node.children, options);
+                if (node.href === null)
+                    return _jsx("span", { children: children }, key);
+                // Links to other sites carry no referrer and no endorsement for search engines, since any user may write them.
+                const external = /^(?:[a-z][a-z0-9+.-]*:)?\/\//i.test(node.href);
+                const newTab = options.newTab === "all" || (options.newTab === "external" && external);
+                return (_jsx("a", { href: node.href, title: node.title, target: newTab ? "_blank" : undefined, rel: external ? "nofollow noopener noreferrer" : newTab ? "noopener noreferrer" : undefined, children: children }, key));
+            }
+        }
+    });
+}
+function plainText(nodes) {
+    return nodes.map(node => (node.type === "text" || node.type === "code" ? node.text : node.type === "image" ? node.alt : node.type === "break" ? " " : plainText(node.children))).join("");
+}

package/dist/Components/Viewers/RichTextView.d.ts

@@ -0,0 +1,18 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { type RichTextRenderOptions } from "../../Helpers/RichTextHelpers.ts";
+export interface RichTextViewProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "dangerouslySetInnerHTML">, Omit<RichTextRenderOptions, "newTab"> {
+    /** The HTML, as a rich text editor stored it. It is sanitized again here, so HTML from anywhere is safe to show. */
+    value: string | null | undefined;
+    /** Links to other sites open in a new tab. Default true. */
+    newTab?: boolean;
+    /** Shown when there is nothing to show. */
+    placeholder?: ReactNode;
+}
+/**
+ * Shows rich text: the HTML a `RichTextEditor` made, sanitized again and styled like the editor. Tokens are filled
+ * from `values` when given, e.g. to preview a template with sample data. No state and no effects, so it renders in
+ * server components too.
+ *
+ * @example <RichTextView value={room.description} />
+ */
+export declare function RichTextView({ value, newTab, placeholder, images, tokenFormat, values, className, ...rest }: RichTextViewProps): import("react").JSX.Element | null;

package/dist/Components/Viewers/RichTextView.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cx } from "../../Helpers/ClassHelpers.js";
+import { renderRichTextHtml } from "../../Helpers/RichTextHelpers.js";
+/**
+ * Shows rich text: the HTML a `RichTextEditor` made, sanitized again and styled like the editor. Tokens are filled
+ * from `values` when given, e.g. to preview a template with sample data. No state and no effects, so it renders in
+ * server components too.
+ *
+ * @example <RichTextView value={room.description} />
+ */
+export function RichTextView({ value, newTab = true, placeholder, images, tokenFormat, values, className, ...rest }) {
+    const html = renderRichTextHtml(value, { newTab, images, tokenFormat, values });
+    if (!html) {
+        return placeholder ? (_jsx("div", { ...rest, className: cx("nx-richtext", className), children: _jsx("p", { className: "nx-richtext__empty", children: placeholder }) })) : null;
+    }
+    return _jsx("div", { ...rest, className: cx("nx-richtext", className), dangerouslySetInnerHTML: { __html: html } });
+}

package/dist/Helpers/AnimationHelpers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Calls `done` once the element's CSS animation `name` has finished, or at once when the element runs no animation of
+ * that name. Call it after the class that starts the animation is on the element, e.g. in a layout effect.
+ * Returns a function that cancels the wait.
+ */
+export declare function afterAnimation(element: Element, name: string, done: () => void): () => void;

package/dist/Helpers/AnimationHelpers.js

@@ -0,0 +1,35 @@
+/*
+ * Exit animations. A closing element gets a class that starts a CSS animation, and the next step (closing a dialog,
+ * removing a toast) waits for it. When no animation runs, the step must not wait: with reduced motion (which Windows
+ * reports when its animations are turned off) or when a theme sets `animation: none`.
+ */
+/**
+ * Calls `done` once the element's CSS animation `name` has finished, or at once when the element runs no animation of
+ * that name. Call it after the class that starts the animation is on the element, e.g. in a layout effect.
+ * Returns a function that cancels the wait.
+ */
+export function afterAnimation(element, name, done) {
+    const animation = typeof element.getAnimations === "function" ? element.getAnimations().find(item => item.animationName === name) : undefined;
+    if (!animation) {
+        done();
+        return () => undefined;
+    }
+    let waiting = true;
+    let timer = 0;
+    const finish = () => {
+        if (!waiting)
+            return;
+        waiting = false;
+        window.clearTimeout(timer);
+        done();
+    };
+    // A safety net for a timeline that stops, as in a hidden tab: the animation's own length, and a little more.
+    const end = Number(animation.effect?.getComputedTiming().endTime);
+    timer = window.setTimeout(finish, (Number.isFinite(end) ? end : 0) + 100);
+    // Rejects when the animation is cancelled, e.g. the popup opens again; the caller cancels the wait then.
+    animation.finished.then(finish, () => undefined);
+    return () => {
+        waiting = false;
+        window.clearTimeout(timer);
+    };
+}

package/dist/Helpers/ApiClient.d.ts

@@ -0,0 +1,96 @@
+import type { ApiCallOptions, ApiEndpoint, ApiResult, ApiTarget, HttpMethod } from "../Interfaces/ApiInterfaces.ts";
+import type { MessageActionName, MessageContext } from "../Interfaces/MessageInterfaces.ts";
+/** One call, as a client's hooks see it. */
+export interface ApiCall<TOptions = object> {
+    target: ApiTarget;
+    /** The endpoint, when the target is one. */
+    endpoint?: ApiEndpoint;
+    method: HttpMethod;
+    /** The full URL; empty while it is not known yet, or when it could not be built. */
+    url: string;
+    options: ApiCallOptions & TOptions;
+    /** What the call does and acts on, for its messages. */
+    context: MessageContext;
+}
+/**
+ * Reads a server's answer as an `ApiResult`. A client's `read` is the app's default for every call that does not bring
+ * its own (`ApiCallOptions.read`); `call` says what was asked for, and is left out for an answer that came from
+ * somewhere other than a call (an app's own send function).
+ *
+ * @example
+ * // A backend that answers { success, message, data, error: { code, message, fields } }
+ * configureApi({
+ *   read: (body, status) => {
+ *     const answer = body as { success?: boolean; message?: string; data?: unknown; error?: { code: string; fields?: Record<string, string[]> } };
+ *     if (answer?.success) return { ok: true, status, result: answer.data, message: answer.message };
+ *     return { ok: false, status, message: answer?.message, messageCode: answer?.error?.code, errors: … };
+ *   },
+ * });
+ */
+export type ApiResponseReader<TOptions = object> = (body: unknown, status: number | undefined, call?: ApiCall<TOptions>) => ApiResult;
+export interface ApiClientConfig<TOptions = object> {
+    /** The full URL of an endpoint, given its filled path: through the proxy in the browser, the module's root on a server. */
+    resolveUrl: (endpoint: ApiEndpoint, path: string, call: ApiCall<TOptions>) => string | Promise<string>;
+    /** The full URL of a plain URL target. Default: as it is. */
+    resolveTarget?: (url: string, call: ApiCall<TOptions>) => string | Promise<string>;
+    /** Headers on every call, such as the tenant or branch. */
+    headers?: (call: ApiCall<TOptions>) => Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
+    /** A bearer token for every call. */
+    token?: (call: ApiCall<TOptions>) => string | null | undefined | Promise<string | null | undefined>;
+    /** Milliseconds to wait for an answer. Default 60,000. */
+    timeout?: number;
+    credentials?: RequestCredentials;
+    /**
+     * Reads every answer the call itself did not bring a reader for. Default `readApiResponse`: Nexus API responses,
+     * ASP.NET Core problem details, and any JSON by its status. An app on another backend registers its own once, so
+     * components that call inside themselves (`Crud`, `ApiForm`) read that backend's envelope too.
+     */
+    read?: ApiResponseReader<TOptions>;
+    /** Changes the request just before it is sent, such as Next.js caching on a server. */
+    prepare?: (init: RequestInit, call: ApiCall<TOptions>) => RequestInit;
+    /**
+     * Sends a GET only once while the same one runs, and gives every caller its answer. Only where every call is the same
+     * user's (the browser): on a server, callers are different users.
+     */
+    dedupe?: boolean;
+    /** Before a call is sent, such as a loading toast. May return a function that gets the answer. */
+    onStart?: (call: ApiCall<TOptions>) => ((result: ApiResult) => void) | void;
+    /** After every answer: toasts in the browser, logs on a server. */
+    onResult?: (result: ApiResult, call: ApiCall<TOptions>) => void;
+    /** The `fetch` to use. Default: the global one, looked up on each call. */
+    fetch?: typeof fetch;
+}
+type Options<TOptions> = ApiCallOptions & TOptions;
+export interface ApiClient<TOptions = object> {
+    /** Sends a call with the endpoint's method (or `options.method`). */
+    send<T = unknown>(target: ApiTarget, options?: Options<TOptions>): Promise<ApiResult<T>>;
+    get<T = unknown>(target: ApiTarget, options?: Omit<Options<TOptions>, "body" | "method">): Promise<ApiResult<T>>;
+    post<T = unknown>(target: ApiTarget, body?: unknown, options?: Omit<Options<TOptions>, "body" | "method">): Promise<ApiResult<T>>;
+    put<T = unknown>(target: ApiTarget, body?: unknown, options?: Omit<Options<TOptions>, "body" | "method">): Promise<ApiResult<T>>;
+    patch<T = unknown>(target: ApiTarget, body?: unknown, options?: Omit<Options<TOptions>, "body" | "method">): Promise<ApiResult<T>>;
+    /** A DELETE; ids for a batch go in `options.body`. */
+    delete<T = unknown>(target: ApiTarget, options?: Omit<Options<TOptions>, "method">): Promise<ApiResult<T>>;
+    /** The URL a call would go to, for links and downloads. Throws when it cannot be built. */
+    url(target: ApiTarget, options?: Pick<ApiCallOptions, "params" | "query" | "body">): Promise<string>;
+}
+export declare const DEFAULT_API_TIMEOUT = 60000;
+/** What a call does when it names nothing: GET loads, DELETE deletes, the rest save. */
+export declare function defaultAction(method: HttpMethod): MessageActionName;
+/** What a call does and acts on: its endpoint, its method, and the context its messages are built from. */
+export declare function apiCallContext(target: ApiTarget, options?: Pick<ApiCallOptions, "method" | "action" | "subject" | "count" | "plural">): {
+    endpoint?: ApiEndpoint;
+    method: HttpMethod;
+    context: MessageContext;
+};
+/**
+ * Whether an error is a framework's own signal passing through a call, never a failed request: Next.js throws one from
+ * `headers()`, `cookies()`, or a `no-store` fetch while it prerenders, to learn that a page renders per request (and
+ * for `redirect()` and `notFound()`). Each carries a `digest`, or React's `$typeof`. The engine throws them on.
+ */
+export declare function isFrameworkError(error: unknown): boolean;
+/**
+ * Makes an API client. Apps use the two made here, `api` (browser) and `serverApi` (server); make another for an API
+ * that is not a Nexus module.
+ */
+export declare function createApiClient<TOptions extends object = object>(config: ApiClientConfig<TOptions>): ApiClient<TOptions>;
+export {};

package/dist/Helpers/ApiClient.js

@@ -0,0 +1,200 @@
+import { isAbortError, readApiResponse, readFetchResponse, toFormData } from "./ApiResponses.js";
+import { appendQuery, fillApiPath, isApiEndpoint } from "./ApiRoutes.js";
+import { buildMessage } from "./MessageBuilder.js";
+export const DEFAULT_API_TIMEOUT = 60_000;
+/** Statuses worth one more try for a GET: the server or a gateway was briefly unavailable. */
+const RETRY_STATUSES = new Set([502, 503, 504]);
+/** What a call does when it names nothing: GET loads, DELETE deletes, the rest save. */
+export function defaultAction(method) {
+    return method === "GET" ? "load" : method === "DELETE" ? "delete" : "save";
+}
+/** What a call does and acts on: its endpoint, its method, and the context its messages are built from. */
+export function apiCallContext(target, options = {}) {
+    const endpoint = isApiEndpoint(target) ? target : undefined;
+    const method = options.method ?? endpoint?.method ?? "GET";
+    const context = { action: options.action ?? endpoint?.action ?? defaultAction(method), subject: options.subject ?? endpoint?.subject };
+    if (options.count !== undefined)
+        context.count = options.count;
+    if (options.plural)
+        context.plural = options.plural;
+    return { endpoint, method, context };
+}
+function isRawBody(body) {
+    return ((typeof Blob !== "undefined" && body instanceof Blob) ||
+        (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) ||
+        body instanceof ArrayBuffer ||
+        ArrayBuffer.isView(body) ||
+        (typeof ReadableStream !== "undefined" && body instanceof ReadableStream));
+}
+function pause(ms, signal) {
+    return new Promise(resolve => {
+        if (signal.aborted)
+            return resolve();
+        const done = () => {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+    });
+}
+const aborted = () => ({ ok: false, aborted: true });
+/**
+ * Whether an error is a framework's own signal passing through a call, never a failed request: Next.js throws one from
+ * `headers()`, `cookies()`, or a `no-store` fetch while it prerenders, to learn that a page renders per request (and
+ * for `redirect()` and `notFound()`). Each carries a `digest`, or React's `$typeof`. The engine throws them on.
+ */
+export function isFrameworkError(error) {
+    const value = error;
+    return typeof value === "object" && value !== null && (typeof value.digest === "string" || value.$typeof !== undefined);
+}
+/**
+ * Makes an API client. Apps use the two made here, `api` (browser) and `serverApi` (server); make another for an API
+ * that is not a Nexus module.
+ */
+export function createApiClient(config) {
+    const inflight = new Map();
+    function describe(target, options) {
+        return { target, ...apiCallContext(target, options), url: "", options };
+    }
+    async function resolve(call) {
+        const { endpoint, options } = call;
+        if (endpoint) {
+            const path = fillApiPath(endpoint.path, options.params, options.body);
+            return appendQuery(await config.resolveUrl(endpoint, path, call), endpoint.query, options.query);
+        }
+        const url = call.target;
+        return appendQuery(config.resolveTarget ? await config.resolveTarget(url, call) : url, options.query);
+    }
+    /** Sends the request and reads its answer. */
+    async function request(call) {
+        const { method, options, endpoint } = call;
+        const headers = { Accept: "application/json", ...(await config.headers?.(call)) };
+        const token = await config.token?.(call);
+        if (token)
+            headers.Authorization = /^bearer /i.test(token) ? token : `Bearer ${token}`;
+        let body;
+        if (method !== "GET" && options.body !== undefined) {
+            const bodyType = options.bodyType ?? endpoint?.bodyType ?? (typeof FormData !== "undefined" && options.body instanceof FormData ? "form-data" : "json");
+            if (isRawBody(options.body))
+                body = options.body;
+            else if (bodyType === "form-data")
+                body = toFormData(options.body);
+            else {
+                body = JSON.stringify(options.body);
+                headers["Content-Type"] = "application/json";
+            }
+        }
+        Object.assign(headers, options.headers);
+        const controller = new AbortController();
+        const caller = options.signal;
+        const stop = () => controller.abort();
+        caller?.addEventListener("abort", stop, { once: true });
+        let timedOut = false;
+        const timeout = options.timeout ?? config.timeout ?? DEFAULT_API_TIMEOUT;
+        const timer = timeout > 0
+            ? setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, timeout)
+            : undefined;
+        // The call's own reader, else the app's (`configureApi({ read })`), else the built-in one. The app's is looked up
+        // on every call, so registering it after a module was imported still takes effect.
+        const appRead = config.read;
+        const read = options.read ?? (appRead ? (answer, status) => appRead(answer, status, call) : (answer, status) => readApiResponse(answer, status, call.context));
+        const stopped = () => caller?.aborted ? aborted() : timedOut ? { ok: false, timeout: true, message: buildMessage("reason", { ...call.context, timeout: true }) } : undefined;
+        let init = { method, headers, body, credentials: options.credentials ?? config.credentials, signal: controller.signal };
+        if (config.prepare)
+            init = config.prepare(init, call);
+        const send = config.fetch ?? globalThis.fetch;
+        const retries = options.retries ?? (method === "GET" ? 1 : 0);
+        try {
+            for (let attempt = 0;; attempt++) {
+                if (caller?.aborted)
+                    return aborted();
+                let response;
+                try {
+                    response = await send(call.url, init);
+                }
+                catch (error) {
+                    if (isFrameworkError(error))
+                        throw error;
+                    const early = stopped();
+                    if (early)
+                        return early;
+                    // Aborted by a signal the call does not know, such as the page closing: nothing to show either.
+                    if (isAbortError(error))
+                        return aborted();
+                    if (attempt < retries) {
+                        await pause(300 * 2 ** attempt, controller.signal);
+                        continue;
+                    }
+                    return { ok: false, network: true, message: buildMessage("reason", { ...call.context, network: true }) };
+                }
+                if (RETRY_STATUSES.has(response.status) && attempt < retries) {
+                    await response.body?.cancel().catch(() => undefined);
+                    await pause(300 * 2 ** attempt, controller.signal);
+                    continue;
+                }
+                const result = await readFetchResponse(response, read);
+                // A body cut off by an abort or the timeout reads as empty: say what happened instead.
+                return stopped() ?? result;
+            }
+        }
+        finally {
+            clearTimeout(timer);
+            caller?.removeEventListener("abort", stop);
+        }
+    }
+    async function send(target, options = {}) {
+        const call = describe(target, options);
+        const done = config.onStart?.(call);
+        let result;
+        try {
+            call.url = await resolve(call);
+        }
+        catch (error) {
+            if (isFrameworkError(error)) {
+                done?.(aborted());
+                throw error;
+            }
+            // A module without a root URL, or a path that names a value the call did not give: nothing is sent.
+            result = { ok: false, message: error instanceof Error ? error.message : String(error) };
+        }
+        if (!result) {
+            try {
+                result = await run(call);
+            }
+            catch (error) {
+                // A framework's signal (or a throw in the app's own headers or token): a loading toast closes, the error goes on.
+                done?.(aborted());
+                throw error;
+            }
+        }
+        config.onResult?.(result, call);
+        done?.(result);
+        return result;
+    }
+    async function run(call) {
+        if (!config.dedupe || call.method !== "GET" || call.options.signal)
+            return request(call);
+        let shared = inflight.get(call.url);
+        if (!shared) {
+            shared = request(call).finally(() => inflight.delete(call.url));
+            inflight.set(call.url, shared);
+        }
+        // Each caller gets its own copy, so one cannot change another's answer.
+        return { ...(await shared) };
+    }
+    const withBody = (method) => (target, body, options) => send(target, { ...options, body, method });
+    return {
+        send,
+        get: (target, options) => send(target, { ...options, method: "GET" }),
+        post: withBody("POST"),
+        put: withBody("PUT"),
+        patch: withBody("PATCH"),
+        delete: (target, options) => send(target, { ...options, method: "DELETE" }),
+        url: (target, options = {}) => resolve(describe(target, options)),
+    };
+}

package/dist/Helpers/ApiFormHelpers.d.ts

@@ -0,0 +1,49 @@
+import type { ApiCallOptions, ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { ApiRequest, FormErrors } from "../Interfaces/FormInterfaces.ts";
+export interface SendApiOptions {
+    signal?: AbortSignal;
+    read?: (body: unknown, status: number | undefined) => ApiResult;
+}
+/**
+ * The call options of a form's `{ url, method, headers, bodyType, credentials }` request with its values. Without a
+ * `read` the client's own reader is used: the app's (`configureApi({ read })`), else the built-in one.
+ */
+export declare function apiRequestOptions(request: ApiRequest, body: unknown, { signal, read }?: SendApiOptions): ApiCallOptions;
+/** An abort as the error `fetch` throws, for code that expects a stopped request to reject. */
+export declare function abortError(): Error;
+/**
+ * Sends a body with `fetch` and reads the answer. Resolves with a failed result for a network error or a timeout;
+ * rejects only when the request is aborted. `ApiForm` sends through the app's `api` instead, with its headers.
+ */
+export declare function sendApiRequest(request: ApiRequest, body: unknown, options?: SendApiOptions): Promise<ApiResult>;
+/** What an `ApiSend` function answered, read the same way: a `Response`, an `ApiResult`, or a body. */
+export declare function toApiResult(answer: unknown, read?: (body: unknown, status: number | undefined) => ApiResult): Promise<ApiResult>;
+/**
+ * The input a server's field name belongs to, or `undefined` when the form has no such input. Names match without case,
+ * and a path matches its first part that is an input ("Addresses[1].City" and "$.addresses" go to "addresses";
+ * "dto.Email" to "email"). The one rule every server message is matched by.
+ */
+export declare function matchInputName(name: string, inputNames: readonly string[]): string | undefined;
+/**
+ * Puts a server's messages on the inputs they name, by `matchInputName`. Messages that match no input are returned in
+ * `others`, for the form's message.
+ */
+export declare function matchFieldErrors(errors: Record<string, string> | undefined, inputNames: readonly string[]): {
+    fields: FormErrors;
+    others: string[];
+};
+/**
+ * A failed answer as what a form shows, through the one path a 400's field errors already take: every message the server
+ * put on an input (`inputName`, several named with "|") goes to that input, every other message - including one naming an
+ * input this form does not have - goes under the form, and nothing is shown twice. `message` is `null` when the inputs
+ * carry it all. An answer that explains nothing falls back to a message for its HTTP status; that is the only time our
+ * own wording is shown.
+ *
+ * @example
+ * const { errors, message } = formErrorsFromResult(answer, store.inputs.map(params => params.name));
+ * store.setErrors(errors, message);
+ */
+export declare function formErrorsFromResult(answer: ApiResult, inputNames: readonly string[]): {
+    errors: FormErrors;
+    message: string | null;
+};

package/dist/Helpers/ApiFormHelpers.js

@@ -0,0 +1,120 @@
+import { createApiClient } from "./ApiClient.js";
+import { apiStatusMessage, isApiResult, readApiResponse, readFetchResponse } from "./ApiResponses.js";
+/**
+ * The call options of a form's `{ url, method, headers, bodyType, credentials }` request with its values. Without a
+ * `read` the client's own reader is used: the app's (`configureApi({ read })`), else the built-in one.
+ */
+export function apiRequestOptions(request, body, { signal, read } = {}) {
+    const { method = "POST", headers, bodyType = "json", credentials } = request;
+    return { method, headers, bodyType, credentials, signal, read, body: body ?? {} };
+}
+/** An abort as the error `fetch` throws, for code that expects a stopped request to reject. */
+export function abortError() {
+    return typeof DOMException === "function" ? new DOMException("The request was aborted.", "AbortError") : Object.assign(new Error("The request was aborted."), { name: "AbortError" });
+}
+/** Sends URLs as they are, with none of an app's settings. */
+const plainClient = createApiClient({
+    resolveUrl: () => {
+        throw new Error("sendApiRequest takes a URL; call an endpoint with api or serverApi.");
+    },
+});
+/**
+ * Sends a body with `fetch` and reads the answer. Resolves with a failed result for a network error or a timeout;
+ * rejects only when the request is aborted. `ApiForm` sends through the app's `api` instead, with its headers.
+ */
+export async function sendApiRequest(request, body, options = {}) {
+    const result = await plainClient.send(request.url, apiRequestOptions(request, body, options));
+    if (result.aborted)
+        throw abortError();
+    return result;
+}
+/** What an `ApiSend` function answered, read the same way: a `Response`, an `ApiResult`, or a body. */
+export async function toApiResult(answer, read = readApiResponse) {
+    if (typeof Response !== "undefined" && answer instanceof Response)
+        return readFetchResponse(answer, read);
+    if (isApiResult(answer))
+        return answer;
+    return read(answer, undefined);
+}
+function inputsByName(inputNames) {
+    return new Map(inputNames.map(name => [name.toLowerCase(), name]));
+}
+function matchIn(key, byName) {
+    const parts = key.replace(/^\$\.?/, "").split(/[.[\]]+/).filter(Boolean);
+    return parts.slice(0, 2).map(part => byName.get(part.toLowerCase())).find(Boolean);
+}
+/**
+ * The input a server's field name belongs to, or `undefined` when the form has no such input. Names match without case,
+ * and a path matches its first part that is an input ("Addresses[1].City" and "$.addresses" go to "addresses";
+ * "dto.Email" to "email"). The one rule every server message is matched by.
+ */
+export function matchInputName(name, inputNames) {
+    return matchIn(name, inputsByName(inputNames));
+}
+/**
+ * Puts a server's messages on the inputs they name, by `matchInputName`. Messages that match no input are returned in
+ * `others`, for the form's message.
+ */
+export function matchFieldErrors(errors, inputNames) {
+    const byName = inputsByName(inputNames);
+    const fields = {};
+    const others = [];
+    for (const [key, message] of Object.entries(errors ?? {})) {
+        if (!message)
+            continue;
+        const name = matchIn(key, byName);
+        if (name)
+            fields[name] = fields[name] && fields[name] !== message ? `${fields[name]} ${message}` : message;
+        else if (!others.includes(message))
+            others.push(message);
+    }
+    return { fields, others };
+}
+/**
+ * A failed answer as what a form shows, through the one path a 400's field errors already take: every message the server
+ * put on an input (`inputName`, several named with "|") goes to that input, every other message - including one naming an
+ * input this form does not have - goes under the form, and nothing is shown twice. `message` is `null` when the inputs
+ * carry it all. An answer that explains nothing falls back to a message for its HTTP status; that is the only time our
+ * own wording is shown.
+ *
+ * @example
+ * const { errors, message } = formErrorsFromResult(answer, store.inputs.map(params => params.name));
+ * store.setErrors(errors, message);
+ */
+export function formErrorsFromResult(answer, inputNames) {
+    const byName = inputsByName(inputNames);
+    const fields = {};
+    const others = [];
+    const place = (message, key) => {
+        const sentence = message?.trim();
+        if (!sentence)
+            return;
+        const name = key ? matchIn(key, byName) : undefined;
+        if (name)
+            fields[name] = fields[name] && fields[name] !== sentence ? `${fields[name]} ${sentence}` : sentence;
+        else if (!others.includes(sentence))
+            others.push(sentence);
+    };
+    if (answer.errorMessages?.length) {
+        for (const problem of answer.errorMessages) {
+            const named = (problem.inputName?.split("|") ?? []).map(part => part.trim()).filter(name => name && matchIn(name, byName));
+            if (named.length)
+                for (const name of named)
+                    place(problem.message, name);
+            // No input of this form: shown with the others, never swallowed.
+            else
+                place(problem.message);
+        }
+    }
+    else {
+        for (const [key, message] of Object.entries(answer.errors ?? {}))
+            place(message, key);
+        // The answer's own message, when an input does not already show it.
+        if (!Object.values(fields).includes(answer.message ?? ""))
+            place(answer.message);
+    }
+    const message = others.join(" ");
+    if (message)
+        return { errors: fields, message };
+    return { errors: fields, message: Object.keys(fields).length ? null : apiStatusMessage(answer.status) };
+}