nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/InputParamsHelpers.d.ts

@@ -0,0 +1,79 @@
+import type { InputParams, InputValidationContext, RowsInputProps, RowValue } from "../Interfaces/FormInterfaces.ts";
+/** Keys that place an input in a form; a renderer leaves them out of the component's props. */
+export declare const INPUT_LAYOUT_KEYS: readonly ["span", "width", "grow", "hidden"];
+/** Inputs whose value is `true` or `false`. */
+export declare const isBooleanInput: (params: InputParams) => params is import("../Shared.Index.ts").CheckBoxParams | import("../Shared.Index.ts").SwitchParams | import("../Shared.Index.ts").RadioParams;
+/** Inputs whose value is an array of rows. */
+export declare const isRowsInput: (params: InputParams) => params is import("../Shared.Index.ts").TabularParams | import("../Shared.Index.ts").GroupParams;
+/**
+ * The name an input's messages use, as the input itself picks it: `fieldName`, or the label when it is text. A checkbox's
+ * label is usually a sentence, so it uses `fieldName` only.
+ */
+export declare function inputFieldName(params: InputParams): string | undefined;
+/** The value of an input with nothing in it: "" for text, `null` for a number or a date, `false`, `[]`, and so on. */
+export declare function emptyInputValue(params: InputParams): unknown;
+/** The value an input starts with in a new row: its `defaultValue` (`defaultChecked` for a checkbox), or empty. */
+export declare function initialInputValue(params: InputParams): unknown;
+/**
+ * A value as the input reports it, from what an API or a default gave: "2026-09-17T00:00:00" becomes "2026-09-17" for a
+ * date, "12.5" becomes 12.5 for a number, `null` becomes "" for text. Missing values become the empty value.
+ */
+export declare function normalizeInputValue(params: InputParams, value: unknown): unknown;
+/** Whether a value counts as empty: `null`, "", spaces, `false`, an empty array, or a range with no ends. */
+export declare function isEmptyInputValue(value: unknown): boolean;
+/** Equal values: the same primitive, or arrays with the same items in the same order. */
+export declare function inputValuesEqual(a: unknown, b: unknown): boolean;
+/**
+ * Checks a value against its input's rules and returns the first message, or `null` when it is valid: the same
+ * message the input shows. Pure, so a form can check thousands of values on submit, including rows not on screen.
+ * A tabular or group form's value is checked row by row, and the first problem is named with its row: "Address 2: City is required."
+ */
+export declare function validateInput(params: InputParams, value: unknown, context?: InputValidationContext): string | null;
+/** The rules of a tabular or group form's rows, as `validateRows` reads them. */
+export type RowsRules<TRow extends RowValue = RowValue> = Pick<RowsInputProps<TRow>, "inputs" | "required" | "min" | "max" | "unique" | "validate" | "itemLabel" | "itemLabelPlural">;
+/** A value in a row that fails its input's rules, or repeats another row's. */
+export interface RowsProblem {
+    /** The row's position, from 0. */
+    index: number;
+    /** The input's name. */
+    name: string;
+    message: string;
+}
+export interface RowsValidation {
+    /** The rows' own message: too few or too many, none of a radio column on, or `validate`'s. `null` when fine. */
+    message: string | null;
+    /** Each value that fails, in row order, then input order. */
+    cells: RowsProblem[];
+}
+/** How a row is named: `title` for "Address 2", and `item` and `items` in lower case for sentences. */
+export declare function rowsItemNames(props: Pick<RowsInputProps, "itemLabel" | "itemLabelPlural">, fallback: string): {
+    title: string;
+    item: string;
+    items: string;
+};
+/** The text two values are compared by for `unique`: trimmed and in lower case, numbers as they are. `null` when empty. */
+export declare function uniqueKeyOf(value: unknown): string | null;
+/** The rows' own message for a list of rows: count rules, radio columns that one row must have on, then `validate`. */
+export declare function rowsMessage<TRow extends RowValue>(rows: readonly TRow[], rules: RowsRules<TRow>, fallback?: string): string | null;
+/**
+ * Rows whose value in a `unique` input another row also has: the row, the input, and the position of the other row it
+ * is named after. Every row with the value is found, so the one just edited says so, whichever came first: the first
+ * row names the second, the others name the first.
+ */
+export declare function findDuplicates<TRow extends RowValue>(rows: readonly TRow[], names: readonly string[]): {
+    index: number;
+    name: string;
+    first: number;
+}[];
+/** The message of a repeated value: "Email is the same as in row 1." */
+export declare function duplicateMessageFor(params: InputParams | undefined, name: string, first: number, item: string): string;
+/**
+ * Checks every row of a tabular or group form: each value against its input's rules, repeated values in `unique`
+ * inputs, and the rows' own rules. Pure, like `validateInput`, which uses it for a rows input's value.
+ */
+export declare function validateRows<TRow extends RowValue>(rows: readonly TRow[] | null | undefined, rules: RowsRules<TRow>, context?: InputValidationContext): RowsValidation;
+/**
+ * A value as short text, for a collapsed section's summary or a message: a number with its format, an option's label,
+ * a date in the user's calendar. "" for an empty value.
+ */
+export declare function formatInputValue(params: InputParams, value: unknown, context?: InputValidationContext): string;

package/dist/Helpers/InputParamsHelpers.js

@@ -0,0 +1,388 @@
+import { DEFAULT_DATE_PREFERENCES } from "../Interfaces/DateInterfaces.js";
+import { formatDate, formatDateRange, toDateRange, toIsoDate, usesDevanagari } from "./DateHelpers.js";
+import { formatDateTime, toUtcDateTime } from "./DateTimeHelpers.js";
+import { formatNumber, parseNumber } from "./NumberHelpers.js";
+import { richTextToPlainText, validateRichText } from "./RichTextHelpers.js";
+import { pluralize } from "./MessageBuilder.js";
+import { formatTime, normalizeTimeStep, timeFormatWithSeconds, toIsoTime } from "./TimeHelpers.js";
+import { chooseRowMessage, duplicateRowMessage, maxRowsMessage, minRowsMessage, validateCheck, validateDate, validateDateRange, validateDateTime, validateNumber, validateSelection, validateText, validateTime, } from "./ValidationHelpers.js";
+/*
+ * Working with input params without a browser: the empty value of each input, its value in a new row, loaded values
+ * turned into the type the input reports, and the same checks the inputs run, as pure functions. A form validates
+ * every value on submit with them, rows that are not on screen included.
+ */
+/** Keys that place an input in a form; a renderer leaves them out of the component's props. */
+export const INPUT_LAYOUT_KEYS = ["span", "width", "grow", "hidden"];
+/** Inputs whose value is `true` or `false`. */
+export const isBooleanInput = (params) => params.type === "checkbox" || params.type === "switch" || params.type === "radio";
+/** Inputs whose value is an array of rows. */
+export const isRowsInput = (params) => params.type === "tabular" || params.type === "group";
+/**
+ * The name an input's messages use, as the input itself picks it: `fieldName`, or the label when it is text. A checkbox's
+ * label is usually a sentence, so it uses `fieldName` only.
+ */
+export function inputFieldName(params) {
+    const { fieldName } = params;
+    if (fieldName)
+        return fieldName;
+    if (params.type === "checkbox" || params.type === "switch")
+        return undefined;
+    return typeof params.label === "string" ? params.label : undefined;
+}
+/** The value of an input with nothing in it: "" for text, `null` for a number or a date, `false`, `[]`, and so on. */
+export function emptyInputValue(params) {
+    switch (params.type) {
+        case "number":
+        case "date":
+        case "time":
+        case "date-time":
+        case "radio-group":
+            return null;
+        case "checkbox":
+        case "switch":
+        case "radio":
+            return false;
+        case "checkbox-group":
+        case "tree":
+        case "tabular":
+        case "group":
+            return [];
+        case "dropdown":
+            return params.multiple ? [] : null;
+        case "date-range":
+            return [null, null];
+        case "slider":
+            return params.min ?? 0;
+        case "range-slider":
+            return [params.min ?? 0, params.max ?? 100];
+        default:
+            return "";
+    }
+}
+/** The value an input starts with in a new row: its `defaultValue` (`defaultChecked` for a checkbox), or empty. */
+export function initialInputValue(params) {
+    if (isBooleanInput(params))
+        return Boolean(params.defaultChecked);
+    const { defaultValue } = params;
+    return normalizeInputValue(params, defaultValue);
+}
+/**
+ * A value as the input reports it, from what an API or a default gave: "2026-09-17T00:00:00" becomes "2026-09-17" for a
+ * date, "12.5" becomes 12.5 for a number, `null` becomes "" for text. Missing values become the empty value.
+ */
+export function normalizeInputValue(params, value) {
+    if (value === undefined || value === null) {
+        // A dropdown or radio group keeps a saved null; a number, a date, and a time do too, as their empty value.
+        return emptyInputValue(params);
+    }
+    switch (params.type) {
+        case "number": {
+            if (typeof value === "number")
+                return Number.isNaN(value) ? null : value;
+            return typeof value === "string" ? parseNumber(value, params.locale) : null;
+        }
+        case "checkbox":
+        case "switch":
+        case "radio":
+            return value === true || value === "true" || value === 1;
+        case "date":
+            return toIsoDate(value) ?? (typeof value === "string" ? value : null);
+        case "date-range":
+            return toDateRange(Array.isArray(value) ? value : null);
+        case "time":
+            return toIsoTime(value, normalizeTimeStep(params.step) % 60 !== 0) ?? (typeof value === "string" ? value : null);
+        case "date-time":
+            return toUtcDateTime(value) ?? (typeof value === "string" ? value : null);
+        case "checkbox-group":
+        case "tree":
+        case "tabular":
+        case "group":
+            return Array.isArray(value) ? value : [];
+        case "dropdown":
+            if (params.multiple)
+                return Array.isArray(value) ? value : [value];
+            return Array.isArray(value) ? (value[0] ?? null) : value;
+        case "slider":
+            return typeof value === "number" ? value : (parseNumber(String(value)) ?? params.min ?? 0);
+        case "range-slider":
+            return Array.isArray(value) && value.length === 2 ? value : emptyInputValue(params);
+        case "radio-group":
+            return value;
+        default:
+            return typeof value === "string" ? value : String(value);
+    }
+}
+/** Whether a value counts as empty: `null`, "", spaces, `false`, an empty array, or a range with no ends. */
+export function isEmptyInputValue(value) {
+    if (value === null || value === undefined || value === false)
+        return true;
+    if (typeof value === "string")
+        return value.trim() === "";
+    if (Array.isArray(value))
+        return value.every(item => item === null || item === undefined || item === "");
+    return false;
+}
+/** Equal values: the same primitive, or arrays with the same items in the same order. */
+export function inputValuesEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+        return false;
+    return a.every((item, index) => Object.is(item, b[index]));
+}
+function dateSettings(params, preferences) {
+    return {
+        calendar: params.calendar ?? preferences.calendar,
+        format: params.format ?? preferences.format,
+        script: params.script ?? preferences.script,
+    };
+}
+function timeSettings(params, preferences) {
+    const seconds = normalizeTimeStep(params.step) % 60 !== 0;
+    return {
+        format: timeFormatWithSeconds(params.format ?? preferences.timeFormat ?? DEFAULT_DATE_PREFERENCES.timeFormat, seconds),
+        script: params.script ?? (usesDevanagari(preferences.calendar, preferences.script) ? "devanagari" : "latin"),
+    };
+}
+function asArray(value) {
+    if (Array.isArray(value))
+        return value;
+    return value === null || value === undefined ? [] : [value];
+}
+/**
+ * Checks a value against its input's rules and returns the first message, or `null` when it is valid: the same
+ * message the input shows. Pure, so a form can check thousands of values on submit, including rows not on screen.
+ * A tabular or group form's value is checked row by row, and the first problem is named with its row: "Address 2: City is required."
+ */
+export function validateInput(params, value, context = {}) {
+    if (params.hidden || params.disabled || params.readOnly)
+        return null;
+    const name = inputFieldName(params);
+    const preferences = context.preferences ?? DEFAULT_DATE_PREFERENCES;
+    switch (params.type) {
+        case "number":
+            return validateNumber(value, params, name, limit => formatNumber(limit, { locale: params.locale, grouping: true }));
+        case "checkbox":
+        case "switch":
+            return validateCheck(value === true, params, params.fieldName);
+        case "radio":
+            // One row at a time can have it on; whether one must is the rows' rule.
+            return null;
+        case "checkbox-group":
+            return validateSelection(asArray(value), params, name);
+        case "radio-group": {
+            const { validate } = params;
+            return validateSelection(asArray(value), { required: params.required, validate: validate && (values => validate(values[0] ?? null)) }, name);
+        }
+        case "dropdown":
+            return validateSelection(asArray(value), { required: params.required, min: params.min, max: params.max, validate: params.validate }, name);
+        case "date": {
+            const settings = dateSettings(params, preferences);
+            return validateDate(value, params, name, iso => formatDate(iso, settings));
+        }
+        case "date-range": {
+            const settings = dateSettings(params, preferences);
+            return validateDateRange(value, params, name, iso => formatDate(iso, settings));
+        }
+        case "time": {
+            const settings = timeSettings(params, preferences);
+            return validateTime(value, params, name, iso => formatTime(iso, settings));
+        }
+        case "date-time": {
+            const seconds = normalizeTimeStep(params.step) % 60 !== 0;
+            return validateDateTime(value, params, name, {
+                ...dateSettings(params, preferences),
+                timeFormat: timeFormatWithSeconds(params.timeFormat ?? preferences.timeFormat ?? DEFAULT_DATE_PREFERENCES.timeFormat, seconds),
+                timeZone: params.timeZone,
+                seconds,
+            });
+        }
+        case "slider":
+            return params.validate?.(value) || null;
+        case "range-slider":
+            return params.validate?.(value) || null;
+        case "tree":
+            return null;
+        case "rich-text":
+            return validateRichText(value, params, name);
+        case "tabular":
+        case "group": {
+            const result = validateRows(asArray(value), params, context);
+            if (result.message)
+                return result.message;
+            const first = result.cells[0];
+            return first ? `${rowsItemNames(params, params.type === "tabular" ? "Row" : "Item").title} ${first.index + 1}: ${first.message}` : null;
+        }
+        default:
+            return validateText(value, params, name);
+    }
+}
+/** Lower case for use inside a sentence, except words that are capitals throughout (PAN, URL). */
+function inSentence(text) {
+    const [first = ""] = text.split(" ");
+    return first.length > 1 && first === first.toUpperCase() ? text : text.charAt(0).toLowerCase() + text.slice(1);
+}
+/** How a row is named: `title` for "Address 2", and `item` and `items` in lower case for sentences. */
+export function rowsItemNames(props, fallback) {
+    const title = props.itemLabel?.trim() || fallback;
+    const plural = props.itemLabelPlural?.trim() || pluralize(title);
+    return { title, item: inSentence(title), items: inSentence(plural) };
+}
+/** The text two values are compared by for `unique`: trimmed and in lower case, numbers as they are. `null` when empty. */
+export function uniqueKeyOf(value) {
+    if (isEmptyInputValue(value))
+        return null;
+    if (typeof value === "string")
+        return "s:" + value.trim().toLocaleLowerCase();
+    if (typeof value === "number" || typeof value === "boolean")
+        return typeof value + ":" + String(value);
+    return "j:" + JSON.stringify(value);
+}
+/** The name of a radio column in "Choose the primary address": its `fieldName` or text label, in lower case. */
+function radioName(params) {
+    const { fieldName } = params;
+    return inSentence(fieldName ?? (typeof params.label === "string" ? params.label : params.name));
+}
+/** The rows' own message for a list of rows: count rules, radio columns that one row must have on, then `validate`. */
+export function rowsMessage(rows, rules, fallback = "Row") {
+    const names = rowsItemNames(rules, fallback);
+    const count = rows.length;
+    if (count === 0) {
+        if (rules.required)
+            return minRowsMessage(Math.max(1, rules.min ?? 1), names.item, names.items);
+    }
+    else {
+        if (rules.min !== undefined && count < rules.min)
+            return minRowsMessage(rules.min, names.item, names.items);
+        if (rules.max !== undefined && count > rules.max)
+            return maxRowsMessage(rules.max, names.item, names.items);
+        for (const params of rules.inputs) {
+            if (params.type !== "radio" || !params.required || params.hidden)
+                continue;
+            if (!rows.some(row => row[params.name] === true))
+                return chooseRowMessage(radioName(params), names.item);
+        }
+    }
+    return rules.validate?.([...rows]) || null;
+}
+/**
+ * Rows whose value in a `unique` input another row also has: the row, the input, and the position of the other row it
+ * is named after. Every row with the value is found, so the one just edited says so, whichever came first: the first
+ * row names the second, the others name the first.
+ */
+export function findDuplicates(rows, names) {
+    const found = [];
+    for (const name of names) {
+        const groups = new Map();
+        rows.forEach((row, index) => {
+            const key = uniqueKeyOf(row[name]);
+            if (key === null)
+                return;
+            const group = groups.get(key);
+            if (group)
+                group.push(index);
+            else
+                groups.set(key, [index]);
+        });
+        for (const group of groups.values()) {
+            if (group.length < 2)
+                continue;
+            for (const index of group)
+                found.push({ index, name, first: index === group[0] ? group[1] : group[0] });
+        }
+    }
+    return found.sort((a, b) => a.index - b.index);
+}
+/** The message of a repeated value: "Email is the same as in row 1." */
+export function duplicateMessageFor(params, name, first, item) {
+    const fieldName = (params && inputFieldName(params)) ?? name;
+    return duplicateRowMessage(fieldName, item, first + 1);
+}
+/**
+ * Checks every row of a tabular or group form: each value against its input's rules, repeated values in `unique`
+ * inputs, and the rows' own rules. Pure, like `validateInput`, which uses it for a rows input's value.
+ */
+export function validateRows(rows, rules, context = {}) {
+    const list = rows ?? [];
+    const inputs = rules.inputs.filter(params => !params.hidden);
+    const order = new Map(inputs.map((params, index) => [params.name, index]));
+    const names = rowsItemNames(rules, "Row");
+    const cells = [];
+    const failed = new Set();
+    list.forEach((row, index) => {
+        for (const params of inputs) {
+            const message = validateInput(params, normalizeInputValue(params, row[params.name]), context);
+            if (!message)
+                continue;
+            cells.push({ index, name: params.name, message });
+            failed.add(`${index}:${params.name}`);
+        }
+    });
+    for (const { index, name, first } of findDuplicates(list, rules.unique ?? [])) {
+        // A value that breaks its own rules says so first.
+        if (failed.has(`${index}:${name}`))
+            continue;
+        cells.push({ index, name, message: duplicateMessageFor(inputs.find(params => params.name === name), name, first, names.item) });
+    }
+    cells.sort((a, b) => a.index - b.index || (order.get(a.name) ?? 0) - (order.get(b.name) ?? 0));
+    return { message: rowsMessage(list, rules), cells };
+}
+/* Text for summaries */
+function optionLabel(options, value, valueKey = "value", labelKey = "label") {
+    const item = options?.find(option => option[valueKey] === value);
+    const label = item?.[labelKey];
+    return typeof label === "string" || typeof label === "number" ? String(label) : String(value);
+}
+/**
+ * A value as short text, for a collapsed section's summary or a message: a number with its format, an option's label,
+ * a date in the user's calendar. "" for an empty value.
+ */
+export function formatInputValue(params, value, context = {}) {
+    if (isEmptyInputValue(value))
+        return "";
+    const preferences = context.preferences ?? DEFAULT_DATE_PREFERENCES;
+    switch (params.type) {
+        case "number": {
+            const text = formatNumber(value, { ...params, grouping: params.grouping ?? true });
+            const prefix = typeof params.prefix === "string" ? params.prefix + " " : "";
+            const suffix = typeof params.suffix === "string" ? " " + params.suffix : "";
+            return prefix + text + suffix;
+        }
+        case "checkbox":
+        case "switch":
+        case "radio":
+            return typeof params.label === "string" ? params.label : "";
+        case "dropdown":
+            return asArray(value)
+                .map(item => optionLabel(params.options, item, params.valueKey, params.labelKey))
+                .join(", ");
+        case "checkbox-group":
+        case "radio-group":
+            return asArray(value)
+                .map(item => optionLabel(params.options, item))
+                .join(", ");
+        case "date":
+            return formatDate(value, dateSettings(params, preferences));
+        case "date-range":
+            return formatDateRange(value, dateSettings(params, preferences));
+        case "time":
+            return formatTime(value, timeSettings(params, preferences));
+        case "date-time":
+            return formatDateTime(value, { ...dateSettings(params, preferences), timeFormat: params.timeFormat ?? preferences.timeFormat, timeZone: params.timeZone });
+        case "slider":
+            return formatNumber(value, params);
+        case "range-slider":
+            return asArray(value)
+                .map(item => formatNumber(item, params))
+                .join(" – ");
+        case "tree":
+        case "tabular":
+        case "group":
+            return "";
+        default: {
+            const text = params.type === "rich-text" ? richTextToPlainText(String(value)) : String(value).trim();
+            const line = text.split("\n", 1)[0] ?? "";
+            return line.length > 60 ? line.slice(0, 57) + "…" : line;
+        }
+    }
+}

package/dist/Helpers/MarkdownEditing.d.ts

@@ -0,0 +1,27 @@
+export type MarkdownTool = "heading" | "bold" | "italic" | "strikethrough" | "code" | "link" | "image" | "quote" | "bulletList" | "numberedList" | "taskList" | "codeBlock" | "table" | "rule";
+export interface MarkdownEdit {
+    /** Replaces the text from `start` to `end` with `text`. */
+    start: number;
+    end: number;
+    text: string;
+    /** The selection after the edit. Without it, the selection stays where it was. */
+    selectionStart?: number;
+    selectionEnd?: number;
+}
+/** A starter table: three columns, a header, and one row. */
+export declare const MARKDOWN_TABLE = "| Column | Column | Column |\n| --- | --- | --- |\n| Text | Text | Text |";
+/**
+ * The edit for a toolbar button. Inline marks (bold, italic, strikethrough, code) wrap the selection or the word at the
+ * caret, or remove the marks when they are already there. Line marks (quote, lists) apply to every selected line and
+ * come off when every line has them. Blocks (table, horizontal line) go on their own lines after the selection.
+ */
+export declare function applyMarkdownTool(value: string, selectionStart: number, selectionEnd: number, tool: MarkdownTool): MarkdownEdit;
+/**
+ * The edit for Enter at the end of a list item: a new item with the same indent and marker, the next number, and an
+ * empty box for a task. Enter on an empty item ends the list instead. `null` when Enter should just break the line.
+ */
+export declare function continueMarkdownList(value: string, selectionStart: number, selectionEnd: number): MarkdownEdit | null;
+/** The edit that ticks or clears the task whose marker is on `line` (from 0), as `MarkdownListItem.line` gives it. */
+export declare function toggleMarkdownTask(value: string, line: number, checked: boolean): MarkdownEdit | null;
+/** The edit that turns selected text into a link when a URL is pasted over it. `null` for any other paste. */
+export declare function linkPastedUrl(value: string, selectionStart: number, selectionEnd: number, pasted: string): MarkdownEdit | null;