nexus-shared 3.2.0 → 4.1.0

package/dist/Helpers/InputParamsHelpers.js

@@ -1,4 +1,5 @@
 import { DEFAULT_DATE_PREFERENCES } from "../Interfaces/DateInterfaces.js";
+import { EInputTypes } from "../Interfaces/FormInterfaces.js";
 import { formatCode, loadCode, validateCode } from "./CodeHelpers.js";
 import { formatDate, formatDateRange, toDateRange, toIsoDate, usesDevanagari } from "./DateHelpers.js";
 import { formatDateTime, toUtcDateTime } from "./DateTimeHelpers.js";
@@ -15,9 +16,27 @@ import { chooseRowMessage, duplicateRowMessage, maxRowsMessage, minRowsMessage,
 /** 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";
+export const isBooleanInput = (params) => params.type === EInputTypes.CheckBox || params.type === EInputTypes.Switch || params.type === EInputTypes.Radio;
+/** Each `EInputTypes` number with its member name. */
+const INPUT_TYPE_NAMES = new Map(Object.entries(EInputTypes).map(([name, value]) => [value, name]));
+/**
+ * The member name of an input type, for a message or a log: `inputTypeName(EInputTypes.RichText)` is "RichText". A number
+ * that is no member, such as one read from old data, comes back as its digits.
+ */
+export const inputTypeName = (type) => INPUT_TYPE_NAMES.get(type) ?? String(type);
+/**
+ * Whether an input holds a value of the form. A picture does not: it is the owner's file, changed at once through the
+ * file backend, so the form keeps no field for it and a save sends nothing under its name.
+ */
+export const holdsValue = (params) => params.type !== EInputTypes.Picture;
+/**
+ * Whether what is typed in an input is worth asking about before it is dropped: not a password or a one-time code (a
+ * `Code` box), which are typed again in a moment and never kept in a draft. Such a value alone makes no form ask
+ * "Discard your changes?" on Cancel or close, nor the page ask before it is left.
+ */
+export const keepsTyping = (params) => params.type !== EInputTypes.Password && params.type !== EInputTypes.Code;
 /** Inputs whose value is an array of rows. */
-export const isRowsInput = (params) => params.type === "tabular" || params.type === "group";
+export const isRowsInput = (params) => params.type === EInputTypes.Tabular || params.type === EInputTypes.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.
@@ -26,35 +45,36 @@ export function inputFieldName(params) {
     const { fieldName } = params;
     if (fieldName)
         return fieldName;
-    if (params.type === "checkbox" || params.type === "switch")
+    if (params.type === EInputTypes.CheckBox || params.type === EInputTypes.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":
+        case EInputTypes.Number:
+        case EInputTypes.Date:
+        case EInputTypes.Time:
+        case EInputTypes.DateTime:
+        case EInputTypes.RadioGroup:
+        case EInputTypes.Picture:
             return null;
-        case "checkbox":
-        case "switch":
-        case "radio":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
+        case EInputTypes.Radio:
             return false;
-        case "checkbox-group":
-        case "tree":
-        case "tabular":
-        case "group":
+        case EInputTypes.CheckBoxGroup:
+        case EInputTypes.Tree:
+        case EInputTypes.Tabular:
+        case EInputTypes.Group:
             return [];
-        case "dropdown":
+        case EInputTypes.Dropdown:
             return params.multiple ? [] : null;
-        case "date-range":
+        case EInputTypes.DateRange:
             return [null, null];
-        case "slider":
+        case EInputTypes.Slider:
             return params.min ?? 0;
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return [params.min ?? 0, params.max ?? 100];
         default:
             return "";
@@ -77,39 +97,39 @@ export function normalizeInputValue(params, value) {
         return emptyInputValue(params);
     }
     switch (params.type) {
-        case "number": {
+        case EInputTypes.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":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
+        case EInputTypes.Radio:
             return value === true || value === "true" || value === 1;
-        case "date":
+        case EInputTypes.Date:
             return toIsoDate(value) ?? (typeof value === "string" ? value : null);
-        case "date-range":
+        case EInputTypes.DateRange:
             return toDateRange(Array.isArray(value) ? value : null);
-        case "time":
+        case EInputTypes.Time:
             return toIsoTime(value, normalizeTimeStep(params.step) % 60 !== 0) ?? (typeof value === "string" ? value : null);
-        case "date-time":
+        case EInputTypes.DateTime:
             return toUtcDateTime(value) ?? (typeof value === "string" ? value : null);
-        case "checkbox-group":
-        case "tree":
-        case "tabular":
-        case "group":
+        case EInputTypes.CheckBoxGroup:
+        case EInputTypes.Tree:
+        case EInputTypes.Tabular:
+        case EInputTypes.Group:
             return Array.isArray(value) ? value : [];
-        case "dropdown":
+        case EInputTypes.Dropdown:
             if (params.multiple)
                 return Array.isArray(value) ? value : [value];
             return Array.isArray(value) ? (value[0] ?? null) : value;
-        case "slider":
+        case EInputTypes.Slider:
             return typeof value === "number" ? value : (parseNumber(String(value)) ?? params.min ?? 0);
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return Array.isArray(value) && value.length === 2 ? value : emptyInputValue(params);
-        case "radio-group":
+        case EInputTypes.RadioGroup:
             return value;
-        case "code":
+        case EInputTypes.Code:
             // Only separators and case: a saved code that does not fit stays as it is, so its check refuses the save.
             return loadCode(value, params);
         default:
@@ -134,6 +154,67 @@ export function inputValuesEqual(a, b) {
         return false;
     return a.every((item, index) => Object.is(item, b[index]));
 }
+/**
+ * The inputs with some of them fixed for one opening of a form: each input `locked` names (input name -> why) turns
+ * read-only and says why on any try to change it (`readOnlyMessage`), the lock-and-note look every input has. Its value
+ * stays in the form and is sent as before. A required input with no value in `values` stays free: fixed empty, the form
+ * would never ask for it, since read-only inputs are not checked. Names a form does not have are skipped.
+ *
+ * Each fixed input is a copy made from its own property descriptors, never a spread: a spread would read a getter once
+ * (`get readOnly()` or `get options()` following other values through `dependsOn`) and freeze it.
+ *
+ * To show fixed inputs disabled instead (dimmed, out of the Tab order, no note), write `disabled` for `readOnly` in the
+ * copy below.
+ *
+ * `known` are records the caller holds for the fixed values - the row picked in another list that a new record is added
+ * for: a fixed dropdown whose value one of them holds (by the dropdown's `valueKey`) gets it as a selected option, so its
+ * box names the value at once, with no lookup.
+ *
+ * @example lockInputs(REGION_INPUTS, { countryId: "Added inside Bagmati." }, { countryId: "c7" })
+ */
+export function lockInputs(inputs, locked, values = {}, known = []) {
+    return inputs.map(params => {
+        const reason = locked[params.name];
+        if (reason === undefined)
+            return params;
+        const required = params.required === true;
+        if (required && isEmptyInputValue(values[params.name]))
+            return params;
+        const fixed = {
+            ...Object.getOwnPropertyDescriptors(params),
+            readOnly: { value: true, enumerable: true, writable: true, configurable: true },
+            readOnlyMessage: { value: reason, enumerable: true, writable: true, configurable: true },
+        };
+        const value = values[params.name];
+        if (params.type === EInputTypes.Dropdown && !params.multiple && !isEmptyInputValue(value)) {
+            const valueKey = params.valueKey ?? "value";
+            const record = known.find(item => String(item[valueKey]) === String(value));
+            if (record)
+                fixed.selectedOptions = { value: [...(params.selectedOptions ?? []), record], enumerable: true, writable: true, configurable: true };
+        }
+        return Object.create(Object.getPrototypeOf(params), fixed);
+    });
+}
+/**
+ * A form's `onFieldChange` that never writes the inputs fixed for an opening (`lockInputs`): a rule such as "a province
+ * sits right under its country" still changes a free field, and leaves a fixed one as the form opened it. With nothing
+ * fixed, or no rule, the rule as it is.
+ *
+ * @example lockedFieldChange(form.onFieldChange, ["countryId", "parentId"])
+ */
+export function lockedFieldChange(onFieldChange, fixed) {
+    if (!onFieldChange || fixed.length === 0)
+        return onFieldChange;
+    return (name, value, values) => {
+        const patch = onFieldChange(name, value, values);
+        if (!patch)
+            return patch;
+        const kept = { ...patch };
+        for (const field of fixed)
+            delete kept[field];
+        return kept;
+    };
+}
 function dateSettings(params, preferences) {
     return {
         calendar: params.calendar ?? preferences.calendar,
@@ -164,35 +245,35 @@ export function validateInput(params, value, context = {}) {
     const name = inputFieldName(params);
     const preferences = context.preferences ?? DEFAULT_DATE_PREFERENCES;
     switch (params.type) {
-        case "number":
+        case EInputTypes.Number:
             return validateNumber(value, params, name, limit => formatNumber(limit, { locale: params.locale, grouping: true }));
-        case "checkbox":
-        case "switch":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
             return validateCheck(value === true, params, params.fieldName);
-        case "radio":
+        case EInputTypes.Radio:
             // One row at a time can have it on; whether one must is the rows' rule.
             return null;
-        case "checkbox-group":
+        case EInputTypes.CheckBoxGroup:
             return validateSelection(asArray(value), params, name);
-        case "radio-group": {
+        case EInputTypes.RadioGroup: {
             const { validate } = params;
             return validateSelection(asArray(value), { required: params.required, validate: validate && (values => validate(values[0] ?? null)) }, name);
         }
-        case "dropdown":
+        case EInputTypes.Dropdown:
             return validateSelection(asArray(value), { required: params.required, min: params.min, max: params.max, validate: params.validate }, name);
-        case "date": {
+        case EInputTypes.Date: {
             const settings = dateSettings(params, preferences);
             return validateDate(value, params, name, iso => formatDate(iso, settings));
         }
-        case "date-range": {
+        case EInputTypes.DateRange: {
             const settings = dateSettings(params, preferences);
             return validateDateRange(value, params, name, iso => formatDate(iso, settings));
         }
-        case "time": {
+        case EInputTypes.Time: {
             const settings = timeSettings(params, preferences);
             return validateTime(value, params, name, iso => formatTime(iso, settings));
         }
-        case "date-time": {
+        case EInputTypes.DateTime: {
             const seconds = normalizeTimeStep(params.step) % 60 !== 0;
             return validateDateTime(value, params, name, {
                 ...dateSettings(params, preferences),
@@ -201,23 +282,24 @@ export function validateInput(params, value, context = {}) {
                 seconds,
             });
         }
-        case "code":
+        case EInputTypes.Code:
             return validateCode(value, params, name);
-        case "slider":
+        case EInputTypes.Slider:
             return params.validate?.(value) || null;
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return params.validate?.(value) || null;
-        case "tree":
+        case EInputTypes.Tree:
+        case EInputTypes.Picture:
             return null;
-        case "rich-text":
+        case EInputTypes.RichText:
             return validateRichText(value, params, name);
-        case "tabular":
-        case "group": {
+        case EInputTypes.Tabular:
+        case EInputTypes.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;
+            return first ? `${rowsItemNames(params, params.type === EInputTypes.Tabular ? "Row" : "Item").title} ${first.index + 1}: ${first.message}` : null;
         }
         default:
             return validateText(value, params, name);
@@ -263,7 +345,7 @@ export function rowsMessage(rows, rules, fallback = "Row") {
         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)
+            if (params.type !== EInputTypes.Radio || !params.required || params.hidden)
                 continue;
             if (!rows.some(row => row[params.name] === true))
                 return chooseRowMessage(radioName(params), names.item);
@@ -348,47 +430,48 @@ export function formatInputValue(params, value, context = {}) {
         return "";
     const preferences = context.preferences ?? DEFAULT_DATE_PREFERENCES;
     switch (params.type) {
-        case "number": {
+        case EInputTypes.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":
+        case EInputTypes.CheckBox:
+        case EInputTypes.Switch:
+        case EInputTypes.Radio:
             return typeof params.label === "string" ? params.label : "";
-        case "dropdown":
+        case EInputTypes.Dropdown:
             return asArray(value)
                 .map(item => optionLabel(params.options, item, params.valueKey, params.labelKey))
                 .join(", ");
-        case "checkbox-group":
-        case "radio-group":
+        case EInputTypes.CheckBoxGroup:
+        case EInputTypes.RadioGroup:
             return asArray(value)
                 .map(item => optionLabel(params.options, item))
                 .join(", ");
-        case "date":
+        case EInputTypes.Date:
             return formatDate(value, dateSettings(params, preferences));
-        case "date-range":
+        case EInputTypes.DateRange:
             return formatDateRange(value, dateSettings(params, preferences));
-        case "time":
+        case EInputTypes.Time:
             return formatTime(value, timeSettings(params, preferences));
-        case "date-time":
+        case EInputTypes.DateTime:
             return formatDateTime(value, { ...dateSettings(params, preferences), timeFormat: params.timeFormat ?? preferences.timeFormat, timeZone: params.timeZone });
-        case "code":
+        case EInputTypes.Code:
             return formatCode(value, params);
-        case "slider":
+        case EInputTypes.Slider:
             return formatNumber(value, params);
-        case "range-slider":
+        case EInputTypes.RangeSlider:
             return asArray(value)
                 .map(item => formatNumber(item, params))
                 .join(" – ");
-        case "tree":
-        case "tabular":
-        case "group":
+        case EInputTypes.Tree:
+        case EInputTypes.Tabular:
+        case EInputTypes.Group:
+        case EInputTypes.Picture:
             return "";
         default: {
-            const text = params.type === "rich-text" ? richTextToPlainText(String(value)) : String(value).trim();
+            const text = params.type === EInputTypes.RichText ? 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/MailClientHelpers.d.ts

@@ -0,0 +1,96 @@
+import type { ReactNode } from "react";
+import type { ChatDomainValue, ChatId, ChatMessage, ChatSource } from "../Interfaces/ChatInterfaces.ts";
+import type { MailFolders, MailInboxRow, MailKindCount, MailList, MailThreadKind, MessageSource } from "../Interfaces/MailInterfaces.ts";
+import { type ChatTimeOptions } from "./ChatHelpers.ts";
+/** Which conversations a mail client lists: one of its folders, narrowed to one type or not. */
+export interface MailClientView {
+    list: MailList;
+    /** The type picked under the folders: `mail`, `chat`, or `domain:<domainType>`; `null` for every type. */
+    type: string | null;
+}
+/** One type of a mailbox as its rail lists it: Mail, Chat, then one per record kind. */
+export interface MailTypeEntry {
+    /** `mail`, `chat`, or `domain:<domainType>`: the view's `type`. */
+    key: string;
+    threadKind: MailThreadKind;
+    domainType: ChatDomainValue | null;
+    label: string;
+    /** The kind's own icon, from its `defineChatDomains` row. */
+    icon?: ReactNode;
+    unread: number;
+    total: number;
+}
+/** How the list and the reading pane share a wide mail client: side by side, or one over the other. */
+export type MailSplit = "columns" | "rows";
+/** Which pane a mail client too narrow for two shows. */
+export type MailPane = "rail" | "list" | "reader";
+/** The key of a type: `mail`, `chat`, or `domain:<domainType>`. */
+export declare function mailTypeKey(threadKind: MailThreadKind, domainType?: ChatDomainValue | null): string;
+/** The kind and record kind a type's key names, for a list request. */
+export declare function mailTypeOf(key: string | null | undefined): {
+    threadKind: MailThreadKind;
+    domainType?: string;
+} | null;
+/** The kind of a row: what the backend said, else mail or the record's kind. */
+export declare function mailRowKind(row: Pick<MailInboxRow, "threadKind" | "domainType">): MailThreadKind;
+/** The type key of a row, for its chip. */
+export declare function mailRowTypeKey(row: Pick<MailInboxRow, "threadKind" | "domainType">): string;
+/** A type's name: Mail, Chat, or the record kind's name as the app gave it (`defineChatDomains`). */
+export declare function mailTypeLabel(threadKind: MailThreadKind, domainType?: ChatDomainValue | null): string;
+/**
+ * The types a mailbox lists from its counts: Mail and Chat first, then each record kind in the order the app named
+ * them, then any it did not name. A type with nothing in it is left out; two counts of one type are added.
+ */
+export declare function mailTypes(kinds: readonly MailKindCount[]): MailTypeEntry[];
+/** A folder's unread count from the counts, 0 when unknown. */
+export declare function mailFolderUnread(folders: MailFolders | null | undefined, list: MailList): number;
+/** The time a row shows: today's as a time ("10:42 AM"), yesterday's as "Yesterday", older as a date. */
+export declare function mailListTime(utc: string | null | undefined, options?: ChatTimeOptions, today?: string): string;
+/**
+ * A thread's discussion as a chat of its own: its chat lines alone (the mails and notifications are read as mail), and
+ * whatever is written in it a chat line. The read mark is the thread's, so reading the discussion reads the thread up to
+ * its newest chat line.
+ */
+export declare function mailDiscussionSource(thread: ChatSource): ChatSource;
+/**
+ * The read marks a mail client has on their way. A conversation shows read as soon as it opens, before its read mark
+ * reaches the server, so counts read at that moment would still hold it unread: the client reads its counts once
+ * `pending` is empty, and reads them again when a mark is answered (`onSettled`).
+ */
+export interface MailReadMarks {
+    /** The marks on their way, each settling (never failing) when the server answered or did not. */
+    readonly pending: Set<Promise<void>>;
+    /** After each mark, answered or failed. */
+    onSettled: () => void;
+}
+/** A conversation's lines whose read marks are followed in `marks`. A source without read marks is given back as it is. */
+export declare function followMailReadMarks(lines: ChatSource, marks: MailReadMarks): ChatSource;
+/** A mailbox whose conversations' read marks are followed in `marks` (`followMailReadMarks`), for a mail client's reader and chat windows. */
+export declare function followMailboxReadMarks(source: MessageSource, marks: MailReadMarks): MessageSource;
+/** How many of a thread's lines are its discussion: its chat lines. */
+export declare function mailDiscussionCount(messages: readonly ChatMessage[]): number;
+/** The split a viewer chose for a wide mail client, `columns` until they choose. */
+export declare function readMailSplit(viewer: ChatId): MailSplit;
+/** Keeps a viewer's split for the next visit. */
+export declare function writeMailSplit(viewer: ChatId, split: MailSplit): void;
+/** What a compose window holds while it is not sent: the people by id, the subject and the Markdown body. */
+export interface MailComposeDraft {
+    to: ChatId[];
+    cc: ChatId[];
+    bcc: ChatId[];
+    subject: string;
+    body: string;
+    /** When it was last kept (milliseconds since 1970). */
+    savedAt: number;
+}
+/** An empty draft. */
+export declare function emptyMailDraft(): MailComposeDraft;
+/** Whether a draft holds anything worth asking about: words in the subject or the body. People alone are not. */
+export declare function mailDraftHasText(draft: Pick<MailComposeDraft, "subject" | "body"> | null | undefined): boolean;
+/**
+ * A viewer's unsent draft of one compose window (`new`, or `reply:<thread>`), or `null`. A draft kept by an older
+ * version, or broken by hand, reads as none.
+ */
+export declare function readMailDraft(viewer: ChatId, key: string): MailComposeDraft | null;
+/** Keeps a viewer's draft of one compose window, or forgets it (`null`, or a draft with nothing in it). */
+export declare function writeMailDraft(viewer: ChatId, key: string, draft: MailComposeDraft | null): void;