nexus-shared 1.1.21 → 3.0.0

package/dist/Helpers/ValidationHelpers.d.ts

@@ -0,0 +1,124 @@
+import type { DateRange, DateRangeRules, DateRules, DateTimeRules, TimeRules } from "../Interfaces/DateInterfaces.ts";
+import type { CheckRules, NumberRules, OptionValue, SelectionRules, TextRules } from "../Interfaces/InputInterfaces.ts";
+import { type DateTimeFormatOptions } from "./DateTimeHelpers.ts";
+export declare const DEFAULT_FIELD_NAME = "This field";
+/**
+ * Common patterns, each with a message that says what to type. Use them as `pattern={TEXT_PATTERNS.email}`.
+ * Names and messages accept letters from any language.
+ */
+export declare const TEXT_PATTERNS: {
+    readonly email: {
+        readonly source: "[A-Za-z0-9._%+\\-]+@[A-Za-z0-9.\\-]+\\.[A-Za-z]{2,}";
+        readonly message: "Enter an email address like name@example.com.";
+    };
+    readonly username: {
+        readonly source: "[A-Za-z0-9]+(?:[._\\-][A-Za-z0-9]+)*";
+        readonly message: "Use letters and numbers, with single dots, dashes, or underscores between them.";
+    };
+    readonly fullName: {
+        readonly source: "[\\p{L}\\p{M}]+(?:[ .'\\-]{1,2}[\\p{L}\\p{M}]+)*\\.?";
+        readonly message: "Use letters, with spaces, dots, apostrophes, or dashes between words.";
+    };
+    readonly phone: {
+        readonly source: "\\+?(?:[0-9][ \\-]?){6,14}[0-9]";
+        readonly message: "Enter a phone number of 7 to 15 digits, like +977 9812345678.";
+    };
+    readonly mobileNumber: {
+        readonly source: "[0-9]{10}";
+        readonly message: "Enter a 10-digit mobile number.";
+    };
+    readonly password: {
+        readonly source: "(?=.*\\p{Ll})(?=.*\\p{Lu})(?=.*[0-9])(?=.*[^\\p{L}0-9]).{8,64}";
+        readonly message: "Use 8 to 64 characters with an upper and a lower case letter, a number, and a symbol.";
+    };
+    readonly url: {
+        readonly source: "https?://[^\\s/$.?#][^\\s]*";
+        readonly message: "Enter a web address starting with http:// or https://.";
+    };
+    readonly digits: {
+        readonly source: "[0-9]+";
+        readonly message: "Use digits only.";
+    };
+};
+export declare const requiredMessage: (fieldName?: string) => string;
+export declare const minLengthMessage: (fieldName: string, min: number) => string;
+export declare const maxLengthMessage: (fieldName: string, max: number) => string;
+export declare const invalidMessage: (fieldName?: string) => string;
+export declare const notNumberMessage: (fieldName?: string) => string;
+export declare const minValueMessage: (fieldName: string, min: string) => string;
+export declare const maxValueMessage: (fieldName: string, max: string) => string;
+export declare const uncheckedMessage: (fieldName?: string) => string;
+export declare const minChoicesMessage: (fieldName: string, min: number) => string;
+export declare const invalidDateMessage: (fieldName: string | undefined, example: string) => string;
+export declare const minDateMessage: (fieldName: string, min: string) => string;
+export declare const maxDateMessage: (fieldName: string, max: string) => string;
+export declare const invalidDateRangeMessage: (fieldName: string | undefined, example: string) => string;
+export declare const missingEndMessage: (fieldName?: string) => string;
+export declare const missingStartMessage: (fieldName?: string) => string;
+export declare const minStartMessage: (fieldName: string, min: string) => string;
+export declare const maxEndMessage: (fieldName: string, max: string) => string;
+export declare const minDistanceMessage: (fieldName: string, days: number) => string;
+export declare const maxDistanceMessage: (fieldName: string, days: number) => string;
+export declare const invalidTimeMessage: (fieldName: string | undefined, example: string) => string;
+export declare const minTimeMessage: (fieldName: string, min: string) => string;
+export declare const maxTimeMessage: (fieldName: string, max: string) => string;
+export declare const timeRangeMessage: (fieldName: string, min: string, max: string) => string;
+export declare const timeStepMessage: (fieldName: string, step: string, before: string, after: string) => string;
+export declare const invalidDateTimeMessage: (fieldName: string | undefined, example: string) => string;
+export declare const minDateTimeMessage: (fieldName: string, min: string) => string;
+export declare const maxDateTimeMessage: (fieldName: string, max: string) => string;
+export declare const maxChoicesMessage: (fieldName: string, max: number) => string;
+export declare const minRowsMessage: (min: number, item: string, items: string) => string;
+export declare const maxRowsMessage: (max: number, item: string, items: string) => string;
+/** A radio column that one row must have on: "Choose the primary address." */
+export declare const chooseRowMessage: (fieldName: string, item: string) => string;
+/** A value that must differ between rows: "Email is the same as in row 1." */
+export declare const duplicateRowMessage: (fieldName: string, item: string, position: number) => string;
+/**
+ * Checks text against its rules and returns the first message, or `null` when the value is valid.
+ * Pure and DOM-free, so a form can validate thousands of values on submit, including fields not on screen.
+ * The value is trimmed first: "  " counts as empty.
+ */
+export declare function validateText(value: string | null | undefined, rules: TextRules, fieldName?: string): string | null;
+/**
+ * Checks a number against its rules and returns the first message, or `null` when the value is valid.
+ * `null` means an empty field; `NaN` means text that is not a number. Pure and DOM-free, like `validateText`.
+ * `format` writes the limits in messages, e.g. `value => formatNumber(value, { grouping: true })` for "at least 1,000".
+ */
+export declare function validateNumber(value: number | null | undefined, rules: NumberRules, fieldName?: string, format?: (value: number) => string): string | null;
+/**
+ * Checks a date against its rules and returns the first message, or `null` when valid. The value is an ISO date,
+ * "" or `null` for an empty field, or any other text for something typed that is not a date. Pure, like `validateText`.
+ * `format` writes dates in messages the way the user sees them, e.g. `iso => formatDate(iso, preferences)`.
+ */
+export declare function validateDate(value: string | null | undefined, rules: DateRules, fieldName?: string, format?: (iso: string) => string): string | null;
+/**
+ * Checks a date range against its rules and returns the first message, or `null` when valid. The value is a pair
+ * of ISO dates (an end not chosen is `null`), "" or `null` for an empty field, or any other text for something
+ * typed that is not a range. A range with one end only is never valid. Pure, like `validateDate`; `format` writes
+ * dates in messages the way the user sees them.
+ */
+export declare function validateDateRange(value: DateRange | string | null | undefined, rules: DateRangeRules, fieldName?: string, format?: (iso: string) => string): string | null;
+/**
+ * Checks a time against its rules and returns the first message, or `null` when valid. The value is an ISO time,
+ * "" or `null` for an empty field, or any other text for something typed that is not a time. Limits are inclusive,
+ * and run past midnight when `max` is earlier than `min`; `step` counts seconds from midnight. Pure, like
+ * `validateDate`; `format` writes times in messages the way the user sees them, e.g. `iso => formatTime(iso, options)`.
+ */
+export declare function validateTime(value: string | null | undefined, rules: TimeRules, fieldName?: string, format?: (iso: string) => string): string | null;
+/**
+ * Checks a date-time against its rules and returns the first message, or `null` when valid. The value is a UTC ISO
+ * date-time ("2026-09-17T08:45:00.000Z"), "" or `null` for an empty field, or any other text for something typed that
+ * is not a date-time. `min` and `max` compare moments. `minTime`, `maxTime`, and `step` check the time of day the
+ * value shows in `options.timeZone` (the browser's by default), to the precision shown: seconds count only when the
+ * step has them. Pure, like `validateTime`; `options` are the settings the field is shown with, so messages read
+ * like the box.
+ */
+export declare function validateDateTime(value: string | null | undefined, rules: DateTimeRules, fieldName?: string, options?: DateTimeFormatOptions): string | null;
+/**
+ * Checks a single checkbox or switch. The field name is optional: a checkbox label is usually a sentence
+ * ("I accept the terms"), so without one the message is "Check this box to continue."
+ */
+export declare function validateCheck(checked: boolean, rules: CheckRules, fieldName?: string): string | null;
+/** Checks the values chosen in a checkbox group or a radio group. Pure, like `validateText`. */
+export declare function validateSelection<T extends OptionValue>(values: readonly T[], rules: SelectionRules<T>, fieldName?: string): string | null;

package/dist/Helpers/ValidationHelpers.js

@@ -0,0 +1,301 @@
+import { addDays, DATE_RANGE_SEPARATOR, diffDays, isIsoDate, todayIsoDate, toIsoDate } from "./DateHelpers.js";
+import { formatDateTime, fromLocalDateTime, isUtcDateTime, timeScriptOf, todayIsoDateIn, toLocalDateTime, toUtcDateTime } from "./DateTimeHelpers.js";
+import { describeTimeStep, formatTime, isIsoTime, isSecondsInRange, normalizeTimeStep, secondsToIsoTime, timeToSeconds, toIsoTime } from "./TimeHelpers.js";
+export const DEFAULT_FIELD_NAME = "This field";
+/**
+ * Common patterns, each with a message that says what to type. Use them as `pattern={TEXT_PATTERNS.email}`.
+ * Names and messages accept letters from any language.
+ */
+export const TEXT_PATTERNS = {
+    email: {
+        source: "[A-Za-z0-9._%+\\-]+@[A-Za-z0-9.\\-]+\\.[A-Za-z]{2,}",
+        message: "Enter an email address like name@example.com.",
+    },
+    username: {
+        source: "[A-Za-z0-9]+(?:[._\\-][A-Za-z0-9]+)*",
+        message: "Use letters and numbers, with single dots, dashes, or underscores between them.",
+    },
+    fullName: {
+        source: "[\\p{L}\\p{M}]+(?:[ .'\\-]{1,2}[\\p{L}\\p{M}]+)*\\.?",
+        message: "Use letters, with spaces, dots, apostrophes, or dashes between words.",
+    },
+    phone: {
+        source: "\\+?(?:[0-9][ \\-]?){6,14}[0-9]",
+        message: "Enter a phone number of 7 to 15 digits, like +977 9812345678.",
+    },
+    mobileNumber: {
+        source: "[0-9]{10}",
+        message: "Enter a 10-digit mobile number.",
+    },
+    password: {
+        source: "(?=.*\\p{Ll})(?=.*\\p{Lu})(?=.*[0-9])(?=.*[^\\p{L}0-9]).{8,64}",
+        message: "Use 8 to 64 characters with an upper and a lower case letter, a number, and a symbol.",
+    },
+    url: {
+        source: "https?://[^\\s/$.?#][^\\s]*",
+        message: "Enter a web address starting with http:// or https://.",
+    },
+    digits: {
+        source: "[0-9]+",
+        message: "Use digits only.",
+    },
+};
+export const requiredMessage = (fieldName = DEFAULT_FIELD_NAME) => `${fieldName} is required.`;
+export const minLengthMessage = (fieldName, min) => `${fieldName} must be at least ${min} characters.`;
+export const maxLengthMessage = (fieldName, max) => `${fieldName} cannot be longer than ${max} characters.`;
+export const invalidMessage = (fieldName = DEFAULT_FIELD_NAME) => (fieldName === DEFAULT_FIELD_NAME ? "Enter a valid value." : `${fieldName} is not valid.`);
+export const notNumberMessage = (fieldName = DEFAULT_FIELD_NAME) => (fieldName === DEFAULT_FIELD_NAME ? "Enter a number." : `${fieldName} must be a number.`);
+export const minValueMessage = (fieldName, min) => `${fieldName} must be at least ${min}.`;
+export const maxValueMessage = (fieldName, max) => `${fieldName} cannot be more than ${max}.`;
+export const uncheckedMessage = (fieldName) => (fieldName ? `${fieldName} must be checked.` : "Check this box to continue.");
+export const minChoicesMessage = (fieldName, min) => `${fieldName} needs at least ${min} choices.`;
+export const invalidDateMessage = (fieldName = DEFAULT_FIELD_NAME, example) => fieldName === DEFAULT_FIELD_NAME ? `Enter a date like ${example}.` : `${fieldName} must be a date like ${example}.`;
+export const minDateMessage = (fieldName, min) => `${fieldName} must be on or after ${min}.`;
+export const maxDateMessage = (fieldName, max) => `${fieldName} cannot be after ${max}.`;
+export const invalidDateRangeMessage = (fieldName = DEFAULT_FIELD_NAME, example) => fieldName === DEFAULT_FIELD_NAME ? `Enter a range like ${example}.` : `${fieldName} must be a range like ${example}.`;
+export const missingEndMessage = (fieldName = DEFAULT_FIELD_NAME) => `${fieldName} needs an end date.`;
+export const missingStartMessage = (fieldName = DEFAULT_FIELD_NAME) => `${fieldName} needs a start date.`;
+export const minStartMessage = (fieldName, min) => `${fieldName} must start on or after ${min}.`;
+export const maxEndMessage = (fieldName, max) => `${fieldName} cannot end after ${max}.`;
+export const minDistanceMessage = (fieldName, days) => `${fieldName} must be at least ${days} ${days === 1 ? "day" : "days"} long.`;
+export const maxDistanceMessage = (fieldName, days) => `${fieldName} cannot be longer than ${days} ${days === 1 ? "day" : "days"}.`;
+export const invalidTimeMessage = (fieldName = DEFAULT_FIELD_NAME, example) => fieldName === DEFAULT_FIELD_NAME ? `Enter a time like ${example}.` : `${fieldName} must be a time like ${example}.`;
+export const minTimeMessage = (fieldName, min) => `${fieldName} must be ${min} or later.`;
+export const maxTimeMessage = (fieldName, max) => `${fieldName} cannot be later than ${max}.`;
+export const timeRangeMessage = (fieldName, min, max) => `${fieldName} must be between ${min} and ${max}.`;
+export const timeStepMessage = (fieldName, step, before, after) => `${fieldName} must be in steps of ${step}, like ${before} or ${after}.`;
+export const invalidDateTimeMessage = (fieldName = DEFAULT_FIELD_NAME, example) => fieldName === DEFAULT_FIELD_NAME ? `Enter a date and time like ${example}.` : `${fieldName} must be a date and time like ${example}.`;
+export const minDateTimeMessage = (fieldName, min) => `${fieldName} must be ${min} or later.`;
+export const maxDateTimeMessage = (fieldName, max) => `${fieldName} cannot be later than ${max}.`;
+export const maxChoicesMessage = (fieldName, max) => `${fieldName} allows at most ${max} ${max === 1 ? "choice" : "choices"}.`;
+/* Tabular and group forms. `item` and `items` are the row's name in lower case: "address", "addresses". */
+export const minRowsMessage = (min, item, items) => (min <= 1 ? `Add at least one ${item}.` : `Add at least ${min} ${items}.`);
+export const maxRowsMessage = (max, item, items) => (max <= 1 ? `Only one ${item} is allowed.` : `Only ${max} ${items} are allowed.`);
+/** A radio column that one row must have on: "Choose the primary address." */
+export const chooseRowMessage = (fieldName, item) => `Choose the ${fieldName} ${item}.`;
+/** A value that must differ between rows: "Email is the same as in row 1." */
+export const duplicateRowMessage = (fieldName, item, position) => `${fieldName} is the same as in ${item} ${position}.`;
+// Compiled once per source: a large form validates the same few patterns thousands of times.
+const compiledPatterns = new Map();
+function toRegExp(pattern) {
+    if (pattern instanceof RegExp) {
+        pattern.lastIndex = 0;
+        return pattern;
+    }
+    const source = typeof pattern === "string" ? pattern : pattern.source;
+    let compiled = compiledPatterns.get(source);
+    if (!compiled) {
+        // Anchored like the HTML pattern attribute; the "u" flag lets patterns use \p{L} for letters in any language.
+        compiled = new RegExp(`^(?:${source})$`, "u");
+        compiledPatterns.set(source, compiled);
+    }
+    return compiled;
+}
+/**
+ * Checks text against its rules and returns the first message, or `null` when the value is valid.
+ * Pure and DOM-free, so a form can validate thousands of values on submit, including fields not on screen.
+ * The value is trimmed first: "  " counts as empty.
+ */
+export function validateText(value, rules, fieldName = DEFAULT_FIELD_NAME) {
+    const text = (value ?? "").trim();
+    if (text) {
+        const { minLength, maxLength, pattern } = rules;
+        if (minLength && text.length < minLength)
+            return minLengthMessage(fieldName, minLength);
+        if (maxLength && text.length > maxLength)
+            return maxLengthMessage(fieldName, maxLength);
+        if (pattern && !toRegExp(pattern).test(text)) {
+            return typeof pattern === "object" && !(pattern instanceof RegExp) ? pattern.message : (rules.patternMessage ?? invalidMessage(fieldName));
+        }
+    }
+    else if (rules.required) {
+        return requiredMessage(fieldName);
+    }
+    return rules.validate?.(text) || null;
+}
+/**
+ * Checks a number against its rules and returns the first message, or `null` when the value is valid.
+ * `null` means an empty field; `NaN` means text that is not a number. Pure and DOM-free, like `validateText`.
+ * `format` writes the limits in messages, e.g. `value => formatNumber(value, { grouping: true })` for "at least 1,000".
+ */
+export function validateNumber(value, rules, fieldName = DEFAULT_FIELD_NAME, format = String) {
+    if (value === null || value === undefined) {
+        if (rules.required)
+            return requiredMessage(fieldName);
+    }
+    else if (Number.isNaN(value)) {
+        return notNumberMessage(fieldName);
+    }
+    else {
+        if (rules.min !== undefined && value < rules.min)
+            return minValueMessage(fieldName, format(rules.min));
+        if (rules.max !== undefined && value > rules.max)
+            return maxValueMessage(fieldName, format(rules.max));
+    }
+    return rules.validate?.(value ?? null) || null;
+}
+/**
+ * Checks a date against its rules and returns the first message, or `null` when valid. The value is an ISO date,
+ * "" or `null` for an empty field, or any other text for something typed that is not a date. Pure, like `validateText`.
+ * `format` writes dates in messages the way the user sees them, e.g. `iso => formatDate(iso, preferences)`.
+ */
+export function validateDate(value, rules, fieldName = DEFAULT_FIELD_NAME, format = iso => iso) {
+    if (!value) {
+        if (rules.required)
+            return requiredMessage(fieldName);
+    }
+    else if (!isIsoDate(value)) {
+        return invalidDateMessage(fieldName, format(todayIsoDate()));
+    }
+    else {
+        const min = toIsoDate(rules.min);
+        if (min && value < min)
+            return minDateMessage(fieldName, format(min));
+        const max = toIsoDate(rules.max);
+        if (max && value > max)
+            return maxDateMessage(fieldName, format(max));
+    }
+    return rules.validate?.(value || null) || null;
+}
+/**
+ * Checks a date range against its rules and returns the first message, or `null` when valid. The value is a pair
+ * of ISO dates (an end not chosen is `null`), "" or `null` for an empty field, or any other text for something
+ * typed that is not a range. A range with one end only is never valid. Pure, like `validateDate`; `format` writes
+ * dates in messages the way the user sees them.
+ */
+export function validateDateRange(value, rules, fieldName = DEFAULT_FIELD_NAME, format = iso => iso) {
+    if (typeof value === "string" && value) {
+        const today = todayIsoDate();
+        return invalidDateRangeMessage(fieldName, format(today) + DATE_RANGE_SEPARATOR + format(addDays(today, 3)));
+    }
+    const [start, end] = value && typeof value !== "string" ? value : [null, null];
+    if (!start && !end) {
+        if (rules.required)
+            return requiredMessage(fieldName);
+    }
+    else if (!end) {
+        return missingEndMessage(fieldName);
+    }
+    else if (!start) {
+        return missingStartMessage(fieldName);
+    }
+    else {
+        const min = toIsoDate(rules.min);
+        if (min && start < min)
+            return minStartMessage(fieldName, format(min));
+        const max = toIsoDate(rules.max);
+        if (max && end > max)
+            return maxEndMessage(fieldName, format(max));
+        const distance = diffDays(start, end);
+        if (rules.minDistance !== undefined && distance < rules.minDistance)
+            return minDistanceMessage(fieldName, rules.minDistance);
+        if (rules.maxDistance !== undefined && distance > rules.maxDistance)
+            return maxDistanceMessage(fieldName, rules.maxDistance);
+    }
+    return rules.validate?.([start, end]) || null;
+}
+/**
+ * Checks a time against its rules and returns the first message, or `null` when valid. The value is an ISO time,
+ * "" or `null` for an empty field, or any other text for something typed that is not a time. Limits are inclusive,
+ * and run past midnight when `max` is earlier than `min`; `step` counts seconds from midnight. Pure, like
+ * `validateDate`; `format` writes times in messages the way the user sees them, e.g. `iso => formatTime(iso, options)`.
+ */
+export function validateTime(value, rules, fieldName = DEFAULT_FIELD_NAME, format = iso => iso) {
+    if (!value) {
+        if (rules.required)
+            return requiredMessage(fieldName);
+    }
+    else if (!isIsoTime(value)) {
+        return invalidTimeMessage(fieldName, format("14:30"));
+    }
+    else {
+        const time = timeToSeconds(value);
+        const step = normalizeTimeStep(rules.step);
+        // Times in messages have seconds only when the step or the time itself does.
+        const write = (seconds) => format(secondsToIsoTime(seconds, step % 60 !== 0 || seconds % 60 !== 0));
+        const min = toIsoTime(rules.min, true);
+        const max = toIsoTime(rules.max, true);
+        const from = min === null ? null : timeToSeconds(min);
+        const to = max === null ? null : timeToSeconds(max);
+        if (!isSecondsInRange(time, from, to)) {
+            if (from !== null && to !== null)
+                return timeRangeMessage(fieldName, write(from), write(to));
+            return from !== null ? minTimeMessage(fieldName, write(from)) : maxTimeMessage(fieldName, write(to));
+        }
+        if (time % step !== 0) {
+            const before = Math.floor(time / step) * step;
+            return timeStepMessage(fieldName, describeTimeStep(step), write(before), write(before + step));
+        }
+    }
+    return rules.validate?.(value || null) || null;
+}
+/**
+ * Checks a date-time against its rules and returns the first message, or `null` when valid. The value is a UTC ISO
+ * date-time ("2026-09-17T08:45:00.000Z"), "" or `null` for an empty field, or any other text for something typed that
+ * is not a date-time. `min` and `max` compare moments. `minTime`, `maxTime`, and `step` check the time of day the
+ * value shows in `options.timeZone` (the browser's by default), to the precision shown: seconds count only when the
+ * step has them. Pure, like `validateTime`; `options` are the settings the field is shown with, so messages read
+ * like the box.
+ */
+export function validateDateTime(value, rules, fieldName = DEFAULT_FIELD_NAME, options = {}) {
+    const step = normalizeTimeStep(rules.step);
+    const seconds = step % 60 !== 0;
+    const shown = { ...options, seconds };
+    const writeTime = (time) => formatTime(secondsToIsoTime(time, true), { format: options.timeFormat, script: timeScriptOf(options), seconds });
+    if (!value) {
+        if (rules.required)
+            return requiredMessage(fieldName);
+    }
+    else if (!isUtcDateTime(value)) {
+        const example = fromLocalDateTime(todayIsoDateIn(options.timeZone), "14:30", options.timeZone);
+        return invalidDateTimeMessage(fieldName, formatDateTime(example, shown));
+    }
+    else {
+        const min = toUtcDateTime(rules.min, options.timeZone);
+        if (min && value < min)
+            return minDateTimeMessage(fieldName, formatDateTime(min, shown));
+        const max = toUtcDateTime(rules.max, options.timeZone);
+        if (max && value > max)
+            return maxDateTimeMessage(fieldName, formatDateTime(max, shown));
+        const total = timeToSeconds(toLocalDateTime(value, options.timeZone).time);
+        const time = seconds ? total : total - (total % 60);
+        const minTime = toIsoTime(rules.minTime, true);
+        const maxTime = toIsoTime(rules.maxTime, true);
+        const from = minTime === null ? null : timeToSeconds(minTime);
+        const to = maxTime === null ? null : timeToSeconds(maxTime);
+        if (!isSecondsInRange(time, from, to)) {
+            if (from !== null && to !== null)
+                return timeRangeMessage(fieldName, writeTime(from), writeTime(to));
+            return from !== null ? minTimeMessage(fieldName, writeTime(from)) : maxTimeMessage(fieldName, writeTime(to));
+        }
+        if (time % step !== 0) {
+            const before = Math.floor(time / step) * step;
+            return timeStepMessage(fieldName, describeTimeStep(step), writeTime(before), writeTime(before + step));
+        }
+    }
+    return rules.validate?.(value || null) || null;
+}
+/**
+ * Checks a single checkbox or switch. The field name is optional: a checkbox label is usually a sentence
+ * ("I accept the terms"), so without one the message is "Check this box to continue."
+ */
+export function validateCheck(checked, rules, fieldName) {
+    if (rules.required && !checked)
+        return uncheckedMessage(fieldName);
+    return rules.validate?.(checked) || null;
+}
+/** Checks the values chosen in a checkbox group or a radio group. Pure, like `validateText`. */
+export function validateSelection(values, rules, fieldName = DEFAULT_FIELD_NAME) {
+    const count = values.length;
+    if (count === 0) {
+        if (rules.required)
+            return requiredMessage(fieldName);
+    }
+    else {
+        if (rules.min !== undefined && count < rules.min)
+            return minChoicesMessage(fieldName, rules.min);
+        if (rules.max !== undefined && count > rules.max)
+            return maxChoicesMessage(fieldName, rules.max);
+    }
+    return rules.validate?.([...values]) || null;
+}

package/dist/Interfaces/ApiInterfaces.d.ts

@@ -0,0 +1,174 @@
+import type { MessageAction } from "./MessageInterfaces.ts";
+/** A module's value in an app's own enum: a number (`NexusModule.Identity`) or a string (`"hr"`). */
+export type ApiModuleValue = string | number;
+/**
+ * The Nexus backend modules, the modules of `NexusApiModules`. The values are the backend's `EModules` flags, so they
+ * can be combined and compared with permissions. Another backend has an enum of its own and its own `ApiModules` class.
+ *
+ * **These numbers are the backend's, not this package's.** A permission is a bitmask of them, so a value that differs
+ * from the backend by one bit does not fail loudly: it silently grants or denies the wrong module. `Chat` was added
+ * at bit 6 in the backend on 2026-09-25 and every module after it moved up one bit; this list moved with it, which
+ * changed the value of `Accounting` through `Portfolio`. See CHANGELOG.md.
+ */
+export declare const NexusModule: {
+    /** The app's own API routes (`/api/...`), not a backend module. */
+    readonly None: 0;
+    readonly Migrations: number;
+    readonly Configuration: number;
+    readonly Identity: number;
+    readonly Enterprise: number;
+    readonly Drive: number;
+    readonly Message: number;
+    readonly Chat: number;
+    readonly Accounting: number;
+    readonly Report: number;
+    readonly Requisition: number;
+    readonly Tenant: number;
+    readonly Subscription: number;
+    readonly Reservation: number;
+    readonly School: number;
+    readonly Pharmacy: number;
+    readonly Staffing: number;
+    readonly Portfolio: number;
+};
+export type NexusModule = (typeof NexusModule)[keyof typeof NexusModule];
+/**
+ * Where an app names its module enum for the types, once, next to its `defineApiModules`:
+ *
+ * @example
+ * export const MODULES = defineApiModules(new HrApiModules());
+ * declare module "nexus-shared" {
+ *   interface ApiRegister { module: HrModule }
+ * }
+ *
+ * Every endpoint, call, API form, and CRUD then takes only those modules. Without it, the Nexus modules.
+ */
+export interface ApiRegister {
+}
+/** The app's module type: the one named in `ApiRegister`, else `NexusModule`. */
+export type AppModule = ApiRegister extends {
+    module: infer TModule extends ApiModuleValue;
+} ? TModule : NexusModule;
+/** One module of an app's API: its value, and how it is named. */
+export interface ApiModuleInfo<TModule extends ApiModuleValue = ApiModuleValue> {
+    module: TModule;
+    /** Its name in proxy URLs: `/api/app/reservation/Room/NormalListing`. Letters, digits, dots, dashes, and underscores. */
+    key: string;
+    /** Its name in messages: "The Reservation API address is not set." */
+    label: string;
+    /** Where its root URL comes from, such as the environment variable `API_RESERVATION`. Named in messages when it is missing. */
+    env?: string;
+}
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** `json` sends the body as JSON; `form-data` as fields (files stay files, lists and objects go as JSON text). */
+export type ApiBodyType = "json" | "form-data";
+/** Query values: lists repeat their name, dates go as ISO text, and `null` or `undefined` values are left out. */
+export type ApiQuery = Record<string, string | number | boolean | Date | null | undefined | readonly (string | number | boolean)[]>;
+/**
+ * An API: which module serves it, its path under the module's root, and its method. Build them with `apiEndpoint` or
+ * `apiController`, once per app, and call them with `api` in the browser or `serverApi` on the server. The module is
+ * one of the app's (`AppModule`); its root, through the proxy or not, comes from the app's `ApiModules`.
+ */
+export interface ApiEndpoint<TModule extends ApiModuleValue = AppModule> {
+    module: TModule;
+    /** Under the module's root, such as "Room/Detail/{id}". A `{name}` is filled from the call's `params`, then its body. */
+    path: string;
+    method: HttpMethod;
+    /** Default `json`. */
+    bodyType?: ApiBodyType;
+    /** Query values sent with every call; a call's own `query` adds to them. */
+    query?: ApiQuery;
+    /** What the call does, for its messages. Default: by method (`load` for GET, `delete` for DELETE, else `save`). */
+    action?: MessageAction;
+    /** What it acts on, for its messages: "room". A call's `subject` ("Room 204") replaces it. */
+    subject?: string;
+}
+/** Where a call goes: an endpoint, or a URL ("/api/demo-rooms", "https://…"). */
+export type ApiTarget = ApiEndpoint | string;
+/**
+ * One problem in a failed answer, as the backend explains it: plain words for the user, the codes behind them, and the
+ * input it is about. A backend answers every wrong field at once, so a failure can carry several.
+ */
+export interface ApiErrorMessage {
+    /** What the user is shown: the server's own sentence ("This Region name already exists."). */
+    message: string;
+    /** The code of that exact refusal ("RGN_X009"), for the log and for a page to react to. Never shown to the user. */
+    messageCode?: string;
+    /** The kind of problem as a number (Nexus `errorCode`). Never shown to the user. */
+    errorCode?: number;
+    /** The input the message is about, as the server names it ("regionName"); several named with "|". */
+    inputName?: string;
+}
+/** A server's answer, read as success or failure. Every call answers with one; it never throws for a failed request. */
+export interface ApiResult<T = unknown> {
+    ok: boolean;
+    /** The HTTP status, when known. */
+    status?: number;
+    /** What the server sent back: the record, the list, the saved id. */
+    result?: T;
+    /** The server's own message (its problems joined, in its order), or one built for the failure by status. */
+    message?: string;
+    /** The first problem's code for its message, such as "RGN_X009" (Nexus `messageCode`). Never shown as the sentence. */
+    messageCode?: string;
+    /** The first problem's error number (Nexus `errorCode`). Never shown as the sentence. */
+    errorCode?: number;
+    /** Every problem the server explained, in its order. A failure it explained carries at least one. */
+    errorMessages?: ApiErrorMessage[];
+    /** Messages by field name, as the server names them ("Email", "addresses[1].city"); matched to inputs without case. */
+    errors?: Record<string, string>;
+    /** Nothing reached the server: offline, or the server is down. */
+    network?: boolean;
+    /** The server did not answer within the call's `timeout`. */
+    timeout?: boolean;
+    /** The caller stopped the call through its `signal`. Nothing is shown for it. */
+    aborted?: boolean;
+}
+/** A page of a list, as Nexus pagination APIs answer. */
+export interface ApiPage<T = unknown> {
+    results: T[];
+    /** Every row the user may see. */
+    totalCount: number;
+    /** The rows that match the search and filters. */
+    filterCount: number;
+}
+/** What Nexus pagination APIs take. */
+export interface ApiPageRequest {
+    searchKeyword?: string;
+    skipCount?: number;
+    maxCount?: number;
+    sorting?: string;
+    sortType?: "asc" | "desc";
+}
+/** Options of one call, on either side. */
+export interface ApiCallOptions {
+    /** What is sent. GET sends no body. */
+    body?: unknown;
+    /** Fills `{name}` in the endpoint's path. Missing names are taken from the body. */
+    params?: Record<string, string | number | null | undefined>;
+    /** Query values, added to the endpoint's own. */
+    query?: ApiQuery;
+    /** Replaces the endpoint's method. */
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    bodyType?: ApiBodyType;
+    /** Stops the call. The answer is then `{ ok: false, aborted: true }`, and nothing is shown. */
+    signal?: AbortSignal;
+    /** Milliseconds to wait for an answer. Default: the client's, 60,000; 0 waits as long as the browser does. */
+    timeout?: number;
+    /** Tries again after a network failure or a 502, 503, or 504. Default 1 for GET, 0 for the rest (a save must not run twice). */
+    retries?: number;
+    credentials?: RequestCredentials;
+    /**
+     * Reads the answer. Default: the app's reader (`configureApi({ read })` / `configureServerApi({ read })`), else
+     * `readApiResponse`: Nexus answers, ASP.NET Core problem details, any JSON by its status.
+     */
+    read?: (body: unknown, status: number | undefined) => ApiResult;
+    /** What the call does, for its messages. Default: the endpoint's, or by method. */
+    action?: MessageAction;
+    /** What it acts on, for its messages: "Room 204". Default: the endpoint's. */
+    subject?: string;
+    /** How many it acts on: 3 → "3 rooms deleted." */
+    count?: number;
+    /** The plural of `subject` with a `count`, when adding "s" is wrong: "people". */
+    plural?: string;
+}

package/dist/Interfaces/ApiInterfaces.js

@@ -0,0 +1,30 @@
+/**
+ * The Nexus backend modules, the modules of `NexusApiModules`. The values are the backend's `EModules` flags, so they
+ * can be combined and compared with permissions. Another backend has an enum of its own and its own `ApiModules` class.
+ *
+ * **These numbers are the backend's, not this package's.** A permission is a bitmask of them, so a value that differs
+ * from the backend by one bit does not fail loudly: it silently grants or denies the wrong module. `Chat` was added
+ * at bit 6 in the backend on 2026-09-25 and every module after it moved up one bit; this list moved with it, which
+ * changed the value of `Accounting` through `Portfolio`. See CHANGELOG.md.
+ */
+export const NexusModule = {
+    /** The app's own API routes (`/api/...`), not a backend module. */
+    None: 0,
+    Migrations: 1 << 0,
+    Configuration: 1 << 1,
+    Identity: 1 << 2,
+    Enterprise: 1 << 3,
+    Drive: 1 << 4,
+    Message: 1 << 5,
+    Chat: 1 << 6,
+    Accounting: 1 << 7,
+    Report: 1 << 8,
+    Requisition: 1 << 9,
+    Tenant: 1 << 10,
+    Subscription: 1 << 11,
+    Reservation: 1 << 12,
+    School: 1 << 13,
+    Pharmacy: 1 << 14,
+    Staffing: 1 << 15,
+    Portfolio: 1 << 16,
+};