nexus-shared 1.1.20 → 2.0.0

package/dist/Helpers/MessageBuilder.d.ts

@@ -0,0 +1,74 @@
+import type { ApiResult } from "../Interfaces/ApiInterfaces.ts";
+import type { ActionWords, BuiltMessage, MessageAction, MessageActionName, MessageContext, MessageKind, MessageReasons, MessageTexts } from "../Interfaces/MessageInterfaces.ts";
+/** Every action the builder knows by name, for pickers and permission screens. */
+export declare const MESSAGE_ACTION_NAMES: MessageActionName[];
+export interface MessageChanges {
+    /** Texts to replace. `reasons` and `confirmDetails` merge with the current ones. */
+    texts?: Partial<Omit<MessageTexts, "reasons" | "confirmDetails">> & {
+        reasons?: Partial<MessageReasons>;
+        confirmDetails?: MessageTexts["confirmDetails"];
+    };
+    /** Action words to replace, merged per action. */
+    words?: Partial<Record<MessageActionName, Partial<ActionWords>>>;
+}
+/**
+ * Rewords every message at once, such as for another language or a product's tone. Call it once when the app starts;
+ * `configureMessages(null)` goes back to the defaults.
+ *
+ * @example
+ * configureMessages({ texts: { reasons: { signedOut: "Please sign in again." } }, words: { delete: { done: "removed" } } });
+ */
+export declare function configureMessages(changes: MessageChanges | null): void;
+/** The words of an action: a name's from the table, or the words given. Unknown names read as `save`. */
+export declare function actionWords(action: MessageAction | undefined): ActionWords;
+/** An English plural: address → addresses, city → cities, row → rows. */
+export declare function pluralize(word: string): string;
+/** Fills `{name}` from the values; `{Name}` capitalizes. Unknown names stay as they are. */
+export declare function fillMessage(template: string, values: Record<string, string | number | undefined>): string;
+/**
+ * Builds a message of any kind from what it is about. Every helper in `messages` calls this.
+ *
+ * @example
+ * buildMessage("success", { action: "delete", subject: "room", count: 3 })   // "3 rooms deleted."
+ * buildMessage("failure", { action: "save", subject: "Room 204" })           // "Could not save Room 204."
+ * buildMessage("reason", { action: "delete", status: 403 })                  // "You do not have permission to delete the record."
+ */
+export declare function buildMessage(kind: MessageKind, context?: MessageContext): string;
+/** The message for a module whose API root is not set: "The Reservation API address is not set (API_RESERVATION)." */
+export declare function notConfiguredMessage(module: string, env: string): string;
+/** Why a call failed: by its status, or because nothing reached the server or no answer came in time. */
+type Failure = number | undefined | Pick<ApiResult, "status" | "network" | "timeout">;
+/**
+ * What to show for a call's answer: a success with the server's message (or one built for the action), or a failure
+ * titled with what failed and, under it, the server's message or the reason by status. `null` for an aborted call.
+ */
+export declare function describeResult(result: ApiResult, context?: MessageContext): BuiltMessage | null;
+/**
+ * Short ways to build messages. Each calls `buildMessage`, so the wording lives in one table.
+ *
+ * @example
+ * messages.success("save", "Room 204")        // "Room 204 saved."
+ * messages.success("delete", "room", 3)       // "3 rooms deleted."
+ * messages.success("save")                    // "Saved."
+ * messages.failure("load", "rooms")           // "Could not load rooms."
+ * messages.reason(403, "delete", "Room 204")  // "You do not have permission to delete Room 204."
+ * messages.loading("upload", "photo.jpg")     // "Uploading photo.jpg…"
+ * messages.confirm("trash", "room", 3)        // "Move 3 rooms to the trash?"
+ * messages.label("trash")                     // "Move to the trash"
+ * messages.forResult(result, { action: "save", subject: "Room 204" })   // { tone, title, message } for a toast
+ */
+export declare const messages: {
+    build: typeof buildMessage;
+    success: (action?: MessageAction, subject?: string, count?: number) => string;
+    failure: (action?: MessageAction, subject?: string, count?: number) => string;
+    loading: (action?: MessageAction, subject?: string, count?: number) => string;
+    confirm: (action?: MessageAction, subject?: string, count?: number) => string;
+    /** The action on a button: "Delete", "Move to the trash". */
+    label: (action?: MessageAction) => string;
+    /** The line under a question: "This cannot be undone." for delete; empty for most actions. */
+    confirmDetail: (action?: MessageAction, subject?: string, count?: number) => string;
+    reason: (failure: Failure, action?: MessageAction, subject?: string, count?: number) => string;
+    forResult: typeof describeResult;
+    words: typeof actionWords;
+};
+export {};

package/dist/Helpers/MessageBuilder.js

@@ -0,0 +1,254 @@
+/*
+ * Every success, failure, loading, and confirm message comes from here: one table of texts, one table of action words,
+ * and one generic `buildMessage(kind, context)`. The helpers in `messages` are short ways to call it. An app changes
+ * the wording of every message at once with `configureMessages` (to reword or translate), never message by message.
+ */
+/** The words of each action. A `verb` or `doing` with `{object}` places the object inside: "move Room 204 to the trash". */
+const DEFAULT_WORDS = {
+    load: { verb: "load", done: "loaded", doing: "Loading", object: "the data" },
+    save: { verb: "save", done: "saved", doing: "Saving", object: "the changes", sendsValues: true },
+    create: { verb: "create", done: "created", doing: "Creating", object: "the record", sendsValues: true },
+    update: { verb: "update", done: "updated", doing: "Updating", object: "the record", sendsValues: true },
+    delete: { verb: "delete", done: "deleted", doing: "Deleting", object: "the record" },
+    trash: { verb: "move {object} to the trash", done: "moved to the trash", doing: "Moving {object} to the trash", object: "the record" },
+    archive: { verb: "archive", done: "archived", doing: "Archiving", object: "the record" },
+    restore: { verb: "restore", done: "restored", doing: "Restoring", object: "the record" },
+    recover: { verb: "recover", done: "recovered", doing: "Recovering", object: "the record" },
+    flag: { verb: "flag", done: "flagged", doing: "Flagging", object: "the record" },
+    unflag: { verb: "unflag", done: "unflagged", doing: "Unflagging", object: "the record" },
+    pin: { verb: "pin", done: "pinned", doing: "Pinning", object: "the record" },
+    unpin: { verb: "unpin", done: "unpinned", doing: "Unpinning", object: "the record" },
+    send: { verb: "send", done: "sent", doing: "Sending", object: "the message", sendsValues: true },
+    submit: { verb: "submit", done: "submitted", doing: "Submitting", object: "the form", sendsValues: true },
+    upload: { verb: "upload", done: "uploaded", doing: "Uploading", object: "the file", sendsValues: true },
+    download: { verb: "download", done: "downloaded", doing: "Downloading", object: "the file" },
+    import: { verb: "import", done: "imported", doing: "Importing", object: "the file", sendsValues: true },
+    export: { verb: "export", done: "exported", doing: "Exporting", object: "the data" },
+    copy: { verb: "copy", done: "copied", doing: "Copying", object: "the record" },
+    approve: { verb: "approve", done: "approved", doing: "Approving", object: "the request" },
+    reject: { verb: "reject", done: "rejected", doing: "Rejecting", object: "the request" },
+    cancel: { verb: "cancel", done: "cancelled", doing: "Cancelling", object: "the request" },
+};
+/**
+ * The texts. `{act}` is the verb with its object ("save Room 204", "move 3 rooms to the trash"), `{acting}` the same
+ * in progress, `{object}` what is named ("Room 204", "3 rooms", or the action's object), `{target}` what is named or
+ * "this record". A capital first letter capitalizes the value.
+ */
+const DEFAULT_TEXTS = {
+    success: "{Object} {done}.",
+    successPlain: "{Done}.",
+    failure: "Could not {act}.",
+    loading: "{Acting}…",
+    confirm: "{Act}?",
+    label: "{Verb}",
+    confirmDetails: {
+        delete: "This cannot be undone.",
+        trash: "It can be restored from the trash.",
+        archive: "It can be restored from the archive.",
+    },
+    reasons: {
+        network: "The server cannot be reached. Check your internet connection and try again.",
+        timeout: "The server took too long to answer. Try again in a moment.",
+        rejectedValues: "The server did not accept the values. Check them and try again.",
+        rejected: "The server did not accept the request.",
+        signedOut: "Your session has ended. Sign in again to {act}.",
+        forbidden: "You do not have permission to {act}.",
+        notFound: "The server could not find {target}. It may have been deleted.",
+        notAllowed: "The server does not allow this request.",
+        conflict: "Someone else changed this record since it was opened. Reload it, then try again.",
+        tooLarge: "The request is too large for the server.",
+        tooMany: "Too many requests. Wait a moment and try again.",
+        unavailable: "The server is not available right now. Try again in a moment.",
+        serverError: "Something went wrong on the server. Try again in a moment.",
+        other: "Could not {act} (error {status}).",
+        notConfigured: "The {module} API address is not set ({env}).",
+    },
+};
+/** Every action the builder knows by name, for pickers and permission screens. */
+export const MESSAGE_ACTION_NAMES = Object.keys(DEFAULT_WORDS);
+let words = DEFAULT_WORDS;
+let texts = DEFAULT_TEXTS;
+/**
+ * Rewords every message at once, such as for another language or a product's tone. Call it once when the app starts;
+ * `configureMessages(null)` goes back to the defaults.
+ *
+ * @example
+ * configureMessages({ texts: { reasons: { signedOut: "Please sign in again." } }, words: { delete: { done: "removed" } } });
+ */
+export function configureMessages(changes) {
+    if (!changes) {
+        words = DEFAULT_WORDS;
+        texts = DEFAULT_TEXTS;
+        return;
+    }
+    const { reasons, confirmDetails, ...rest } = changes.texts ?? {};
+    texts = { ...texts, ...rest, reasons: { ...texts.reasons, ...reasons }, confirmDetails: { ...texts.confirmDetails, ...confirmDetails } };
+    const next = { ...words };
+    for (const [name, change] of Object.entries(changes.words ?? {}))
+        next[name] = { ...next[name], ...change };
+    words = next;
+}
+/** The words of an action: a name's from the table, or the words given. Unknown names read as `save`. */
+export function actionWords(action) {
+    if (!action)
+        return words.save;
+    if (typeof action === "string")
+        return words[action] ?? words.save;
+    return action;
+}
+const countFormat = new Intl.NumberFormat("en-US");
+/** An English plural: address → addresses, city → cities, row → rows. */
+export function pluralize(word) {
+    if (/[^aeiou]y$/i.test(word))
+        return word.slice(0, -1) + (word.endsWith("Y") ? "IES" : "ies");
+    if (/(s|x|z|ch|sh)$/i.test(word))
+        return word + (/[A-Z]$/.test(word) ? "ES" : "es");
+    return word + (/[A-Z]$/.test(word) && word.length > 1 ? "S" : "s");
+}
+/** What a message names: "Room 204", "3 rooms", "3 items", or nothing. */
+function named(context) {
+    const { subject, count, plural } = context;
+    const many = count !== undefined && count !== 1;
+    if (subject)
+        return many ? `${countFormat.format(count)} ${plural ?? pluralize(subject)}` : subject;
+    return many ? `${countFormat.format(count)} items` : undefined;
+}
+const capitalize = (text) => (text ? text[0].toUpperCase() + text.slice(1) : text);
+/** A verb phrase with its object: the object goes where the phrase says `{object}`, else after it. */
+function phrase(verb, object) {
+    return verb.includes("{object}") ? verb.replace("{object}", object) : `${verb} ${object}`;
+}
+/** Fills `{name}` from the values; `{Name}` capitalizes. Unknown names stay as they are. */
+export function fillMessage(template, values) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => {
+        const value = values[key[0].toLowerCase() + key.slice(1)];
+        if (value === undefined)
+            return whole;
+        const text = String(value);
+        return key[0] === key[0].toUpperCase() && key[0] !== key[0].toLowerCase() ? capitalize(text) : text;
+    });
+}
+function reasonTemplate(context, action) {
+    const { reasons } = texts;
+    if (context.network)
+        return reasons.network;
+    if (context.timeout)
+        return reasons.timeout;
+    const status = context.status;
+    if (status === undefined || status < 400)
+        return texts.failure;
+    switch (status) {
+        case 400:
+        case 422:
+            return action.sendsValues ? reasons.rejectedValues : reasons.rejected;
+        case 401:
+            return reasons.signedOut;
+        case 403:
+            return reasons.forbidden;
+        case 404:
+        case 410:
+            return reasons.notFound;
+        case 405:
+            return reasons.notAllowed;
+        case 408:
+            return reasons.timeout;
+        case 409:
+            return reasons.conflict;
+        case 413:
+            return reasons.tooLarge;
+        case 429:
+            return reasons.tooMany;
+        case 502:
+        case 503:
+        case 504:
+            return reasons.unavailable;
+        default:
+            return status >= 500 ? reasons.serverError : reasons.other;
+    }
+}
+/**
+ * Builds a message of any kind from what it is about. Every helper in `messages` calls this.
+ *
+ * @example
+ * buildMessage("success", { action: "delete", subject: "room", count: 3 })   // "3 rooms deleted."
+ * buildMessage("failure", { action: "save", subject: "Room 204" })           // "Could not save Room 204."
+ * buildMessage("reason", { action: "delete", status: 403 })                  // "You do not have permission to delete the record."
+ */
+export function buildMessage(kind, context = {}) {
+    const action = actionWords(context.action);
+    const name = named(context);
+    const object = name ?? action.object;
+    const values = {
+        verb: action.verb.replace(" {object}", "").replace("{object} ", ""),
+        done: action.done,
+        doing: action.doing.replace(" {object}", "").replace("{object} ", ""),
+        object,
+        target: name ?? "this record",
+        act: phrase(action.verb, object),
+        acting: phrase(action.doing, object),
+        status: context.status,
+    };
+    switch (kind) {
+        case "success":
+            return fillMessage(name ? texts.success : texts.successPlain, values);
+        case "failure":
+            return fillMessage(texts.failure, values);
+        case "loading":
+            return fillMessage(texts.loading, values);
+        case "confirm":
+            return fillMessage(texts.confirm, values);
+        case "label":
+            return fillMessage(texts.label, values);
+        case "confirmDetail": {
+            const detail = typeof context.action === "string" ? texts.confirmDetails[context.action] : undefined;
+            return detail ? fillMessage(detail, values) : "";
+        }
+        case "reason":
+            return fillMessage(reasonTemplate(context, action), values);
+    }
+}
+/** The message for a module whose API root is not set: "The Reservation API address is not set (API_RESERVATION)." */
+export function notConfiguredMessage(module, env) {
+    return fillMessage(texts.reasons.notConfigured, { module, env });
+}
+/**
+ * What to show for a call's answer: a success with the server's message (or one built for the action), or a failure
+ * titled with what failed and, under it, the server's message or the reason by status. `null` for an aborted call.
+ */
+export function describeResult(result, context = {}) {
+    if (result.aborted)
+        return null;
+    if (result.ok)
+        return { tone: "success", title: result.message ?? buildMessage("success", context) };
+    const title = buildMessage("failure", context);
+    const message = result.message ?? buildMessage("reason", { ...context, status: result.status, network: result.network, timeout: result.timeout });
+    return message && message !== title ? { tone: "danger", title, message } : { tone: "danger", title };
+}
+/**
+ * Short ways to build messages. Each calls `buildMessage`, so the wording lives in one table.
+ *
+ * @example
+ * messages.success("save", "Room 204")        // "Room 204 saved."
+ * messages.success("delete", "room", 3)       // "3 rooms deleted."
+ * messages.success("save")                    // "Saved."
+ * messages.failure("load", "rooms")           // "Could not load rooms."
+ * messages.reason(403, "delete", "Room 204")  // "You do not have permission to delete Room 204."
+ * messages.loading("upload", "photo.jpg")     // "Uploading photo.jpg…"
+ * messages.confirm("trash", "room", 3)        // "Move 3 rooms to the trash?"
+ * messages.label("trash")                     // "Move to the trash"
+ * messages.forResult(result, { action: "save", subject: "Room 204" })   // { tone, title, message } for a toast
+ */
+export const messages = {
+    build: buildMessage,
+    success: (action, subject, count) => buildMessage("success", { action, subject, count }),
+    failure: (action, subject, count) => buildMessage("failure", { action, subject, count }),
+    loading: (action, subject, count) => buildMessage("loading", { action, subject, count }),
+    confirm: (action, subject, count) => buildMessage("confirm", { action, subject, count }),
+    /** The action on a button: "Delete", "Move to the trash". */
+    label: (action) => buildMessage("label", { action }),
+    /** The line under a question: "This cannot be undone." for delete; empty for most actions. */
+    confirmDetail: (action, subject, count) => buildMessage("confirmDetail", { action, subject, count }),
+    reason: (failure, action, subject, count) => buildMessage("reason", { action, subject, count, ...(typeof failure === "object" ? failure : { status: failure }) }),
+    forResult: describeResult,
+    words: actionWords,
+};

package/dist/Helpers/NepaliCalendar.d.ts

@@ -0,0 +1,25 @@
+import type { DateParts } from "../Interfaces/DateInterfaces.ts";
+/**
+ * The Bikram Sambat (Nepali) calendar, as the lengths of its months from BS 1975 to 2100 (AD 1918 to 2044).
+ * Year and month lengths are not computed; they follow the calendar Nepal publishes each year. The table is the
+ * majority of five published tables (nepali-datetime for Python, nepali-date-converter, the Python and Node
+ * libraries of opensource-nepal, and the previous Nexus project); years after 2083 are those libraries' predictions,
+ * and 2096 has one day added (the sources give it 364 days, which no Bikram Sambat year has).
+ * `npm run test:dates` checks the table against known dates and round-trips every day in it.
+ *
+ * Dates are converted through day numbers (days since 1970-01-01 in the proleptic Gregorian calendar), with no
+ * `Date` objects and no time zone, so a conversion gives the same answer on every machine.
+ */
+export declare const BS_FIRST_YEAR = 1975;
+export declare const BS_LAST_YEAR = 2100;
+/** Days in a Bikram Sambat month (1 to 12), or 0 for a year outside the table. */
+export declare function bsMonthLength(year: number, month: number): number;
+/** Days in a Bikram Sambat year, or 0 for a year outside the table. */
+export declare function bsYearLength(year: number): number;
+/** Day number of a Bikram Sambat date, or `null` when the date does not exist or falls outside the table. */
+export declare function bsToDayNumber(year: number, month: number, day: number): number | null;
+/** The Bikram Sambat date of a day number, or `null` outside the table. */
+export declare function dayNumberToBs(dayNumber: number): DateParts | null;
+/** Day numbers of the first and last days the table covers. */
+export declare const BS_MIN_DAY_NUMBER = -18891;
+export declare const BS_MAX_DAY_NUMBER: number;

package/dist/Helpers/NepaliCalendar.js

@@ -0,0 +1,107 @@
+/**
+ * The Bikram Sambat (Nepali) calendar, as the lengths of its months from BS 1975 to 2100 (AD 1918 to 2044).
+ * Year and month lengths are not computed; they follow the calendar Nepal publishes each year. The table is the
+ * majority of five published tables (nepali-datetime for Python, nepali-date-converter, the Python and Node
+ * libraries of opensource-nepal, and the previous Nexus project); years after 2083 are those libraries' predictions,
+ * and 2096 has one day added (the sources give it 364 days, which no Bikram Sambat year has).
+ * `npm run test:dates` checks the table against known dates and round-trips every day in it.
+ *
+ * Dates are converted through day numbers (days since 1970-01-01 in the proleptic Gregorian calendar), with no
+ * `Date` objects and no time zone, so a conversion gives the same answer on every machine.
+ */
+export const BS_FIRST_YEAR = 1975;
+export const BS_LAST_YEAR = 2100;
+/** Day number of BS 1975-01-01, which is AD 1918-04-13. */
+const EPOCH_DAYS = -18891;
+// One character per month, twelve per year from BS 1975: "0" to "3" mean 29 to 32 days.
+const MONTH_DAYS = "223321101011232321110012132321110102223222101011223321101011" + // 1975-1979
+    "232321110012222322011011223222101011223321101011232321110012" + // 1980-1984
+    "222322011011223222101011232321101011232321110012222322011011" + // 1985-1989
+    "223222101011232321110011232321110102223222101011223222101011" + // 1990-1994
+    "232321110011232321110102223222101011223222101011232321110012" + // 1995-1999
+    "132321110102223222101011223321101011232321110012132321110102" + // 2000-2004
+    "223222101011223321101011232321110012222322011002223222101011" + // 2005-2009
+    "223321101011232321110012222322011011223222101011223321101011" + // 2010-2014
+    "232321110012222322011011223222101011232321101011232321110102" + // 2015-2019
+    "222322101011223222101011232321110011232321110102222322101011" + // 2020-2024
+    "223222101011232321110012132321110102223222101011223231101011" + // 2025-2029
+    "232321110012132321110102223222101011223321101011232321110012" + // 2030-2034
+    "132322011002223222101011223321101011232321110012222322011011" + // 2035-2039
+    "223222101011223321101011232321110012222322011011223222101011" + // 2040-2044
+    "232321101011232321110012222322101011223222101011232321110011" + // 2045-2049
+    "232321110102222322101011223222101011232321110011232321110102" + // 2050-2054
+    "223222101011223231101011232321110012132321110102223222101011" + // 2055-2059
+    "223321101011232321110012132322010102223222101011223321101011" + // 2060-2064
+    "232321110012222322011002223222101011223321101011232321110012" + // 2065-2069
+    "222322011011223222101011232321101011232321110012222322101011" + // 2070-2074
+    "223222101011232321110011232321110102222322101011223222101011" + // 2075-2079
+    "232321110011232321110102223222101011223222101011223221110111" + // 2080-2084
+    "232312110111132321110111223222110111123312110111132321110111" + // 2085-2089
+    "132321110111223222110111123321110111132321110111223221110111" + // 2090-2094
+    "223222101111123321111011232321110111223222010102223222100111" + // 2095-2099
+    "232312101011"; // 2100-2100;
+// Days before each year, from the epoch, so a conversion walks no more than a few months.
+const DAYS_BEFORE_YEAR = [];
+{
+    let days = 0;
+    for (let index = 0; index < BS_LAST_YEAR - BS_FIRST_YEAR + 1; index++) {
+        DAYS_BEFORE_YEAR.push(days);
+        for (let month = 0; month < 12; month++)
+            days += MONTH_DAYS.charCodeAt(index * 12 + month) - 48 + 29;
+    }
+    DAYS_BEFORE_YEAR.push(days);
+}
+const inRange = (year) => Number.isInteger(year) && year >= BS_FIRST_YEAR && year <= BS_LAST_YEAR;
+/** Days in a Bikram Sambat month (1 to 12), or 0 for a year outside the table. */
+export function bsMonthLength(year, month) {
+    if (!inRange(year) || month < 1 || month > 12)
+        return 0;
+    return MONTH_DAYS.charCodeAt((year - BS_FIRST_YEAR) * 12 + month - 1) - 48 + 29;
+}
+/** Days in a Bikram Sambat year, or 0 for a year outside the table. */
+export function bsYearLength(year) {
+    if (!inRange(year))
+        return 0;
+    const index = year - BS_FIRST_YEAR;
+    return DAYS_BEFORE_YEAR[index + 1] - DAYS_BEFORE_YEAR[index];
+}
+/** Day number of a Bikram Sambat date, or `null` when the date does not exist or falls outside the table. */
+export function bsToDayNumber(year, month, day) {
+    const length = bsMonthLength(year, month);
+    if (!length || !Number.isInteger(day) || day < 1 || day > length)
+        return null;
+    const index = year - BS_FIRST_YEAR;
+    let days = DAYS_BEFORE_YEAR[index] + day - 1;
+    for (let m = 1; m < month; m++)
+        days += MONTH_DAYS.charCodeAt(index * 12 + m - 1) - 48 + 29;
+    return EPOCH_DAYS + days;
+}
+/** The Bikram Sambat date of a day number, or `null` outside the table. */
+export function dayNumberToBs(dayNumber) {
+    let days = dayNumber - EPOCH_DAYS;
+    const total = DAYS_BEFORE_YEAR[DAYS_BEFORE_YEAR.length - 1];
+    if (!Number.isInteger(days) || days < 0 || days >= total)
+        return null;
+    // Binary search for the year, then walk its months.
+    let low = 0;
+    let high = DAYS_BEFORE_YEAR.length - 2;
+    while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (DAYS_BEFORE_YEAR[mid] <= days)
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    days -= DAYS_BEFORE_YEAR[low];
+    let month = 1;
+    for (; month < 12; month++) {
+        const length = MONTH_DAYS.charCodeAt(low * 12 + month - 1) - 48 + 29;
+        if (days < length)
+            break;
+        days -= length;
+    }
+    return { year: BS_FIRST_YEAR + low, month, day: days + 1 };
+}
+/** Day numbers of the first and last days the table covers. */
+export const BS_MIN_DAY_NUMBER = EPOCH_DAYS;
+export const BS_MAX_DAY_NUMBER = EPOCH_DAYS + DAYS_BEFORE_YEAR[DAYS_BEFORE_YEAR.length - 1] - 1;

package/dist/Helpers/NumberHelpers.d.ts

@@ -0,0 +1,71 @@
+import type { NumberFormatOptions } from "../Interfaces/InputInterfaces.ts";
+/** Default locale for number text. Fixed rather than the browser's, so server-rendered text matches the browser's. */
+export declare const DEFAULT_NUMBER_LOCALE = "en-US";
+/** Most digits a number field takes. A JavaScript number holds 15 significant digits exactly; beyond that, digits change. */
+export declare const MAX_NUMBER_DIGITS = 15;
+export interface NumberSymbols {
+    /** Decimal separator, e.g. "." in en-US and "," in de-DE. */
+    decimal: string;
+    /** Group separator, e.g. "," in en-US, "." in de-DE, and a narrow space in fr-FR. */
+    group: string;
+}
+export interface NumberTextRules {
+    /** Most digits after the decimal separator; `0` allows none. */
+    decimals?: number;
+    /** Allows a leading minus sign. */
+    negative: boolean;
+}
+/** The decimal and group separators of a locale. */
+export declare function getNumberSymbols(locale?: string): NumberSymbols;
+/**
+ * Formats a number for display: `formatNumber(1250, { decimals: 2, fixedDecimals: true, grouping: true })` gives "1,250.00".
+ * Returns "" for `null`, `undefined`, and `NaN`. Digits are always 0–9, and the minus sign is "-", so the text can be typed back.
+ */
+export declare function formatNumber(value: number | null | undefined, options?: NumberFormatOptions): string;
+/**
+ * Reads a number written in the locale's format: "1,250.50" gives 1250.5, and in `de-DE` "1.250,50" does.
+ * Returns `null` for empty text (also a lone minus sign or decimal separator) and `NaN` for text that is not a number.
+ */
+export declare function parseNumber(text: string | null | undefined, locale?: string): number | null;
+/** Counts the digits in text, to keep numbers within `MAX_NUMBER_DIGITS`. */
+export declare function countDigits(text: string): number;
+/**
+ * Whether text typed so far can become a valid number: "", "-", "12.", and ".5" can; "1.2.3" and "12a" cannot.
+ * The text is edit text: digits, at most one decimal separator, and a leading minus sign, with no group separators.
+ */
+export declare function isPartialNumber(text: string, decimal: string, rules: NumberTextRules): boolean;
+/**
+ * Removes what cannot be part of a number from text that reached the field unchecked (an input method, autofill, a drop),
+ * keeping the caret where it was relative to the text that stays. Digits are never removed.
+ */
+export declare function cleanNumberText(text: string, caret: number, decimal: string, rules: NumberTextRules): {
+    text: string;
+    caret: number;
+};
+/**
+ * Takes the number out of pasted text, such as "Rs 1,250.50", "1 250,50 €", or "-12%", and returns it as edit text
+ * ("1250.50"). Returns `null` when the text holds no single clear number, so a paste never turns into a wrong value.
+ */
+export declare function readPastedNumber(text: string, locale?: string): string | null;
+/**
+ * Rounds to a number of decimal places the way people do: 1.005 → 1.01, and -2.5 → -3.
+ * Works on the number's shortest decimal text, so binary fractions such as 1.005 (stored as 1.00499…) round up.
+ */
+export declare function roundDecimal(value: number, digits: number): number;
+/** Keeps a value within `min` and `max`, each optional. */
+export declare function clampNumber(value: number, min?: number, max?: number): number;
+/** Digits after the decimal point of a number: 0.25 → 2, 1e-7 → 7. */
+export declare function countDecimals(value: number): number;
+export interface StepOptions {
+    /** Default 1. */
+    step?: number;
+    min?: number;
+    max?: number;
+    /** Rounds the result, as the field does. */
+    decimals?: number;
+}
+/**
+ * The next value for an arrow key or a +/− button. Values move along the grid of `step` from `min` (or 0), so 2.3 with
+ * step 1 goes up to 3, and stay within `min` and `max`. An empty field starts at 0, or at the limit nearest to 0.
+ */
+export declare function stepNumber(value: number | null, direction: 1 | -1, options?: StepOptions): number;