nexus-shared 4.0.0 → 4.1.0

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;

package/dist/Helpers/MailClientHelpers.js

@@ -0,0 +1,211 @@
+import { getChatDomains } from "./ChatBackend.js";
+import { chatDayLabel, chatLocalDate, chatTimeLabel } from "./ChatHelpers.js";
+import { todayIsoDateIn } from "./DateTimeHelpers.js";
+/** The key of a type: `mail`, `chat`, or `domain:<domainType>`. */
+export function mailTypeKey(threadKind, domainType) {
+    return threadKind === "domain" ? `domain:${String(domainType ?? "")}` : threadKind;
+}
+/** The kind and record kind a type's key names, for a list request. */
+export function mailTypeOf(key) {
+    if (!key)
+        return null;
+    if (key === "mail" || key === "chat")
+        return { threadKind: key };
+    if (key.startsWith("domain:"))
+        return { threadKind: "domain", domainType: key.slice("domain:".length) };
+    return null;
+}
+/** The kind of a row: what the backend said, else mail or the record's kind. */
+export function mailRowKind(row) {
+    return row.threadKind ?? (row.domainType === null || row.domainType === undefined ? "mail" : "domain");
+}
+/** The type key of a row, for its chip. */
+export function mailRowTypeKey(row) {
+    const kind = mailRowKind(row);
+    return mailTypeKey(kind, kind === "domain" ? row.domainType : null);
+}
+/** A type's name: Mail, Chat, or the record kind's name as the app gave it (`defineChatDomains`). */
+export function mailTypeLabel(threadKind, domainType) {
+    if (threadKind === "mail")
+        return "Mail";
+    if (threadKind === "chat")
+        return "Chat";
+    const info = getChatDomains().find(one => String(one.domain) === String(domainType));
+    return info?.label ?? "Record";
+}
+/**
+ * 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 function mailTypes(kinds) {
+    const domains = getChatDomains();
+    const held = new Map();
+    for (const count of kinds) {
+        const key = mailTypeKey(count.threadKind, count.domainType);
+        const known = held.get(key);
+        if (known) {
+            known.unread += count.unread;
+            known.total += count.total;
+            continue;
+        }
+        const info = count.threadKind === "domain" ? domains.find(one => String(one.domain) === String(count.domainType)) : undefined;
+        held.set(key, {
+            key,
+            threadKind: count.threadKind,
+            domainType: count.threadKind === "domain" ? count.domainType : null,
+            label: mailTypeLabel(count.threadKind, count.domainType),
+            ...(info?.icon !== undefined && { icon: info.icon }),
+            unread: count.unread,
+            total: count.total,
+        });
+    }
+    const rank = (entry) => {
+        if (entry.threadKind === "mail")
+            return -2;
+        if (entry.threadKind === "chat")
+            return -1;
+        const at = domains.findIndex(one => String(one.domain) === String(entry.domainType));
+        return at === -1 ? domains.length : at;
+    };
+    return [...held.values()].filter(entry => entry.total > 0).sort((a, b) => rank(a) - rank(b));
+}
+/** A folder's unread count from the counts, 0 when unknown. */
+export function mailFolderUnread(folders, list) {
+    return folders?.folders.find(folder => folder.list === list)?.unread ?? 0;
+}
+/** The time a row shows: today's as a time ("10:42 AM"), yesterday's as "Yesterday", older as a date. */
+export function mailListTime(utc, options = {}, today = todayIsoDateIn(options.timeZone)) {
+    if (!utc)
+        return "";
+    const day = chatLocalDate(utc, options.timeZone);
+    if (!day)
+        return "";
+    return day === today ? chatTimeLabel(utc, options) : chatDayLabel(day, options, today);
+}
+/**
+ * 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 function mailDiscussionSource(thread) {
+    const isChat = (message) => (message.kind ?? "chat") === "chat";
+    return {
+        ...thread,
+        async history(request) {
+            const page = await thread.history(request);
+            // A chat line answering a mail quotes nothing: the mail is read in the pane, not in the discussion.
+            const left = new Set(page.messages.filter(message => !isChat(message)).map(message => String(message.id)));
+            const messages = page.messages.filter(isChat).map(message => (message.replyToId !== undefined && message.replyToId !== null && left.has(String(message.replyToId)) ? { ...message, replyToId: null } : message));
+            // The thread's counts are of every line; the discussion counts its own.
+            return { ...page, messages, ...(page.summary && { summary: { ...page.summary, messageCount: messages.length } }) };
+        },
+        send: (draft, signal) => thread.send({ ...draft, kind: "chat" }, signal),
+    };
+}
+/** A conversation's lines whose read marks are followed in `marks`. A source without read marks is given back as it is. */
+export function followMailReadMarks(lines, marks) {
+    const mark = lines.markRead;
+    if (!mark)
+        return lines;
+    return {
+        ...lines,
+        markRead(upTo, signal) {
+            const work = mark(upTo, signal);
+            const settled = work.then(() => undefined, () => undefined);
+            marks.pending.add(settled);
+            void settled.then(() => {
+                marks.pending.delete(settled);
+                marks.onSettled();
+            });
+            return work;
+        },
+    };
+}
+/** A mailbox whose conversations' read marks are followed in `marks` (`followMailReadMarks`), for a mail client's reader and chat windows. */
+export function followMailboxReadMarks(source, marks) {
+    return { ...source, threadSource: id => followMailReadMarks(source.threadSource(id), marks) };
+}
+/** How many of a thread's lines are its discussion: its chat lines. */
+export function mailDiscussionCount(messages) {
+    return messages.filter(message => (message.kind ?? "chat") === "chat" && message.status !== "failed").length;
+}
+// Remembered in this browser, per viewer
+const SPLIT_PREFIX = "nx-mail-split:";
+const DRAFT_PREFIX = "nx-mail-draft:";
+function storage() {
+    try {
+        return typeof window === "undefined" ? null : window.localStorage;
+    }
+    catch {
+        return null;
+    }
+}
+function read(key) {
+    try {
+        return storage()?.getItem(key) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function write(key, value) {
+    try {
+        const store = storage();
+        if (!store)
+            return;
+        if (value === null)
+            store.removeItem(key);
+        else
+            store.setItem(key, value);
+    }
+    catch {
+        // A private window or a full disk: the preference is simply not kept.
+    }
+}
+/** The split a viewer chose for a wide mail client, `columns` until they choose. */
+export function readMailSplit(viewer) {
+    return read(SPLIT_PREFIX + String(viewer)) === "rows" ? "rows" : "columns";
+}
+/** Keeps a viewer's split for the next visit. */
+export function writeMailSplit(viewer, split) {
+    write(SPLIT_PREFIX + String(viewer), split);
+}
+/** An empty draft. */
+export function emptyMailDraft() {
+    return { to: [], cc: [], bcc: [], subject: "", body: "", savedAt: 0 };
+}
+/** Whether a draft holds anything worth asking about: words in the subject or the body. People alone are not. */
+export function mailDraftHasText(draft) {
+    return !!draft && (draft.subject.trim() !== "" || draft.body.trim() !== "");
+}
+const ids = (value) => (Array.isArray(value) ? value.filter((one) => typeof one === "string" || typeof one === "number") : []);
+/**
+ * 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 function readMailDraft(viewer, key) {
+    const text = read(`${DRAFT_PREFIX}${String(viewer)}:${key}`);
+    if (!text)
+        return null;
+    try {
+        const value = JSON.parse(text);
+        if (typeof value !== "object" || value === null)
+            return null;
+        return {
+            to: ids(value.to),
+            cc: ids(value.cc),
+            bcc: ids(value.bcc),
+            subject: typeof value.subject === "string" ? value.subject : "",
+            body: typeof value.body === "string" ? value.body : "",
+            savedAt: typeof value.savedAt === "number" ? value.savedAt : 0,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Keeps a viewer's draft of one compose window, or forgets it (`null`, or a draft with nothing in it). */
+export function writeMailDraft(viewer, key, draft) {
+    const empty = !draft || (!mailDraftHasText(draft) && draft.to.length === 0 && draft.cc.length === 0 && draft.bcc.length === 0);
+    write(`${DRAFT_PREFIX}${String(viewer)}:${key}`, empty ? null : JSON.stringify(draft));
+}

package/dist/Helpers/MessageBackend.d.ts

@@ -0,0 +1,152 @@
+import { type ApiEndpoint, type ApiModuleValue } from "../Interfaces/ApiInterfaces.ts";
+import type { ChatDomainValue, ChatDraft, ChatHistory, ChatHistoryRequest, ChatId, ChatMessage } from "../Interfaces/ChatInterfaces.ts";
+import type { DropdownPage, DropdownPageRequest } from "../Interfaces/InputInterfaces.ts";
+import type { MailDefaults, MailDomain, MailDraft, MailFolders, MailHeadKind, MailInboxRequest, MailInboxRow, MailPerson, MailRole, MailSent, MailThreadHead, MailThreadKind, MailUnread } from "../Interfaces/MailInterfaces.ts";
+import type { TablePage } from "../Interfaces/TableInterfaces.ts";
+import { NexusChatBackend } from "./ChatBackend.ts";
+/** The actions a mailbox needs from a backend. */
+export declare const MAIL_ACTIONS: {
+    /** A page of one list: inbox, unread, sent, archived. */
+    readonly inbox: "Inbox";
+    /** A thread's head: its subject and its people. */
+    readonly thread: "Thread";
+    /** A page of a thread's lines. */
+    readonly history: "History";
+    /** A new message. */
+    readonly compose: "Create";
+    /** A reply in a thread. */
+    readonly reply: "Reply";
+    /** How far the reader has read a thread. */
+    readonly read: "Read";
+    /** Threads put aside. */
+    readonly archive: "Archive";
+    /** Threads brought back. */
+    readonly unarchive: "Unarchive";
+    /** How much is unread, and the newest of it. */
+    readonly unread: "Unread";
+    /** The people a message can be sent to. */
+    readonly people: "People";
+    /** Who a new message goes to by default. */
+    readonly defaults: "Defaults";
+    /** The counts beside a mail client's folders and types. */
+    readonly folders: "Folders";
+    /** Whole conversations marked read. */
+    readonly markRead: "MarkRead";
+    /** Conversations marked unread again. */
+    readonly markUnread: "MarkUnread";
+    /** Conversations starred. */
+    readonly star: "Star";
+    /** Stars taken away. */
+    readonly unstar: "Unstar";
+};
+export type MailAction = keyof typeof MAIL_ACTIONS;
+type Row = Record<string, unknown>;
+/**
+ * What a mailbox needs from a backend. Extend `NexusMessageBackend` for an app whose mail API differs, and register it
+ * once beside the app's API modules:
+ *
+ * @example
+ * class AppMessageBackend extends NexusMessageBackend {
+ *   override readonly module = AppModule.Messages;
+ * }
+ * defineMessageBackend(new AppMessageBackend());
+ */
+export declare abstract class MessageBackend {
+    /** Which endpoint serves an action, in one of the app's own modules. */
+    abstract endpoint(action: MailAction): ApiEndpoint;
+    /** What asking for a page of a list sends. */
+    abstract inboxRequest(request: MailInboxRequest): unknown;
+    /** Reads a page of a list. */
+    abstract readInbox(result: unknown): TablePage<MailInboxRow>;
+    /** Reads one row of a list: also what a table of raw rows (a CRUD on the same endpoint) reads a row by. */
+    abstract readInboxRow(row: unknown): MailInboxRow;
+    /** What opening a thread sends, as the call's `params`: its id in the path. */
+    threadParams(threadId: ChatId): Record<string, string | number>;
+    /** Reads a thread's head. */
+    abstract readThread(result: unknown): MailThreadHead;
+    /** What a page of a thread's lines sends. */
+    abstract historyRequest(threadId: ChatId, request: ChatHistoryRequest): unknown;
+    /** Reads a page of a thread's lines, as a chat's history. */
+    abstract readHistory(result: unknown): ChatHistory;
+    /** What a reply sends. */
+    abstract replyRequest(threadId: ChatId, draft: ChatDraft): unknown;
+    /** Reads the reply saved. The draft is there for a backend that answers with an id alone. */
+    abstract readReply(result: unknown, draft: ChatDraft): ChatMessage;
+    /** What the read mark sends. */
+    abstract readMarkRequest(threadId: ChatId, upTo: ChatId): unknown;
+    /** What a new message sends. */
+    abstract composeRequest(draft: MailDraft): unknown;
+    /** Reads the thread a new message made. */
+    abstract readComposed(result: unknown): MailSent;
+    /** What Archive and Unarchive send. */
+    abstract markRequest(ids: readonly ChatId[]): unknown;
+    /** Reads how many threads Archive or Unarchive changed. */
+    abstract readChanged(result: unknown): number;
+    /** Reads what is unread. */
+    abstract readUnread(result: unknown): MailUnread;
+    /** What a search for people sends. */
+    abstract peopleRequest(query: DropdownPageRequest): unknown;
+    /** Reads a page of people. */
+    abstract readPeople(result: unknown): DropdownPage<MailPerson>;
+    /** Reads who a new message goes to by default. */
+    abstract readDefaults(result: unknown): MailDefaults;
+    /**
+     * Reads the counts beside a mail client's folders and types. A backend without the `folders` door leaves it out, and
+     * the client shows no counts and no Types. So are `markRead`, `markUnread` and `star` / `unstar` optional: their
+     * doors send `markRequest` and are read by `readChanged`; a backend without them sets `supports` to false for each.
+     */
+    readFolders?(result: unknown): MailFolders;
+    /** The optional doors this backend has: a mail client offers Mark read, Mark unread and stars only where they are. */
+    supports(action: "folders" | "markRead" | "markUnread" | "star"): boolean;
+}
+/**
+ * The Nexus Message module's `Mail` controller (`App/Api/Mail/...`): POST `Inbox`, `History`, `Create`, `Reply` and
+ * `People`; GET `Thread/{id}`, `Unread` and `Defaults`; PUT `Read`, `Archive` and `Unarchive`. Pages answer
+ * `{ results, totalCount, filterCount }`; a person's role and a message's kind come as the backend's numbers and are
+ * read as this package's words. Override `module` or `controller` for another place, or any reader for another shape.
+ */
+export declare class NexusMessageBackend extends MessageBackend {
+    /** The module the mail endpoints live in. `NexusModule.Message`. */
+    readonly module: ApiModuleValue;
+    /** The controller the actions hang off. */
+    readonly controller: string;
+    /** A thread's lines are the chat's rows, read as the chat reads them. */
+    protected readonly chat: NexusChatBackend<ChatDomainValue>;
+    endpoint(action: MailAction): ApiEndpoint;
+    inboxRequest(request: MailInboxRequest): unknown;
+    readInbox(result: unknown): TablePage<MailInboxRow>;
+    readInboxRow(row: unknown): MailInboxRow;
+    readThread(result: unknown): MailThreadHead;
+    historyRequest(threadId: ChatId, request: ChatHistoryRequest): unknown;
+    readHistory(result: unknown): ChatHistory;
+    replyRequest(threadId: ChatId, draft: ChatDraft): unknown;
+    readReply(result: unknown, draft: ChatDraft): ChatMessage;
+    readMarkRequest(threadId: ChatId, upTo: ChatId): unknown;
+    composeRequest(draft: MailDraft): unknown;
+    readComposed(result: unknown): MailSent;
+    markRequest(ids: readonly ChatId[]): unknown;
+    readChanged(result: unknown): number;
+    readUnread(result: unknown): MailUnread;
+    peopleRequest(query: DropdownPageRequest): unknown;
+    readPeople(result: unknown): DropdownPage<MailPerson>;
+    readDefaults(result: unknown): MailDefaults;
+    readFolders(result: unknown): MailFolders;
+    supports(action: "folders" | "markRead" | "markUnread" | "star"): boolean;
+    /** A conversation's kind: the wire's number (Mail 1, Chat 2, Domain 3) or a word; without one, mail or its record's kind. */
+    protected toThreadKind(value: unknown, domainType: ChatDomainValue | null): MailThreadKind;
+    /** A person. */
+    protected toPerson(row: Row): MailPerson;
+    /** A role, from the backend's `EChatParticipantRoles` (1 From, 2 To, 3 Cc, 4 Bcc) or a word. A plain member reads as To. */
+    protected toRole(value: unknown): MailRole;
+    /** What a thread opened with: the backend's `EChatMessageTypes` (1 Mail, 2 Notification) or a word. */
+    protected toHeadKind(value: unknown): MailHeadKind;
+    /** A domain type is the app's own value: kept as it came, a number or a word, and none when it is none. */
+    protected toDomainType(value: unknown): ChatDomainValue | null;
+    /** The record a thread is about. */
+    protected toDomain(row: Row): MailDomain | null;
+}
+/** Makes an app's mail backend the one every mailbox uses, and returns it. Call it once, beside `defineApiModules`. */
+export declare function defineMessageBackend<T extends MessageBackend>(backend: T): T;
+/** The app's mail backend: the one given to `defineMessageBackend`, else the Nexus one. */
+export declare function getMessageBackend(): MessageBackend;
+export {};