nexus-shared 3.2.0 → 4.1.0

package/dist/Interfaces/FormInterfaces.js

@@ -1 +1,79 @@
-export {};
+/*
+ * Input params: one plain object per input, `{ type, name, ...props }`. The same object renders the input
+ * (`renderInput`), validates its value without a browser (`validateInput`), and describes a row of a tabular or group
+ * form. Forms (Form, SubmitForm, ApiForm, and Crud) take a list of them: `inputs: InputParams[]`.
+ */
+/**
+ * Which input a params object describes: `{ type: EInputTypes.Dropdown, name: "country", ... }`. A number, so a
+ * database, a generated page and a C# enum hold the same value.
+ *
+ * The numbers come in blocks by kind, each with room to grow. 0 is never a kind, so a missing value is never a valid
+ * one; a released number is never reused or given a new meaning.
+ *
+ * | Block | Kind | Members |
+ * |---|---|---|
+ * | 1–19 | Text boxes | Text 1, Email 2, Password 3, Search 4, Tel 5, Url 6, TextArea 7, Code 8 |
+ * | 20–39 | Choices | CheckBox 20, Switch 21, Radio 22, CheckBoxGroup 23, RadioGroup 24, Dropdown 25 |
+ * | 40–59 | Dates and times | Date 40, DateRange 41, Time 42, DateTime 43 |
+ * | 60–79 | Numbers and sliders | Number 60, Slider 61, RangeSlider 62 |
+ * | 80–99 | Editors | Markdown 80, RichText 81 |
+ * | 100–119 | Structures | Tree 100, Tabular 101, Group 102, Picture 103 |
+ *
+ * A dropdown is one member: `multiple` decides whether it picks one item or many. Every number fits a byte.
+ */
+export const EInputTypes = {
+    /** `TextBox`, a single line. */
+    Text: 1,
+    /** `TextBox` of HTML type email. */
+    Email: 2,
+    /** `TextBox` of HTML type password, with a button that shows what was typed. */
+    Password: 3,
+    /** `TextBox` of HTML type search. */
+    Search: 4,
+    /** `TextBox` of HTML type tel: a phone number. */
+    Tel: 5,
+    /** `TextBox` of HTML type url. */
+    Url: 6,
+    /** `TextArea`: several lines of plain text. */
+    TextArea: 7,
+    /** `CodeBox`: a box per character, such as a one-time code. */
+    Code: 8,
+    /** `CheckBox`: `true` or `false`. */
+    CheckBox: 20,
+    /** `Switch`: `true` or `false`, for a setting that takes effect. */
+    Switch: 21,
+    /** `RadioButton`: one radio, on or off; in rows, only one row has it on. */
+    Radio: 22,
+    /** `CheckBoxGroup`: any number of options. */
+    CheckBoxGroup: 23,
+    /** `RadioGroup`: one option of a few, all in view. */
+    RadioGroup: 24,
+    /** `Dropdown`: one item, or many with `multiple`. */
+    Dropdown: 25,
+    /** `DatePicker`: an ISO date. */
+    Date: 40,
+    /** `DateRangePicker`: two ISO dates. */
+    DateRange: 41,
+    /** `TimePicker`: an ISO time. */
+    Time: 42,
+    /** `DateTimePicker`: a UTC moment shown in the user's zone. */
+    DateTime: 43,
+    /** `NumberBox`. */
+    Number: 60,
+    /** `Slider`: one number on a track. */
+    Slider: 61,
+    /** `RangeSlider`: two numbers on a track. */
+    RangeSlider: 62,
+    /** `MarkdownEditor`: Markdown text. */
+    Markdown: 80,
+    /** `RichTextEditor`: sanitized HTML. */
+    RichText: 81,
+    /** `TreeView`: nodes picked in a tree. */
+    Tree: 100,
+    /** `TabularForm`: rows of inputs in a table. */
+    Tabular: 101,
+    /** `GroupForm`: the same rows, each as a section of inputs. */
+    Group: 102,
+    /** `PictureInput`: a record's picture, kept by the file backend as one of the owner's files, not a value of the form. */
+    Picture: 103,
+};

package/dist/Interfaces/InputInterfaces.d.ts

@@ -127,8 +127,10 @@ export type DropdownItem = object;
  * - `avatar`: a round photo from a URL; the initials of the item's label when there is no URL or it fails to load.
  * - `image`: a small picture from a URL, 4:3, such as a flag or a logo.
  * - `icon`: a Tabler icon by name, such as `"wifi"`.
+ * - `money`: a figure with 2 places in the person's number format (1,00,000.00 under lakh and crore), at the end of the
+ *   column in even digits, such as a fee's price beside its name; empty for a missing one.
  */
-export type DropdownColumnType = "text" | "muted" | "code" | "avatar" | "image" | "icon";
+export type DropdownColumnType = "text" | "muted" | "code" | "avatar" | "image" | "icon" | "money";
 /** One column of a dropdown's rows. Plain values, so a list of fields can describe it; `render` is the only function. */
 export interface DropdownColumn<TItem extends DropdownItem = DropdownItem> {
     /** The item's field, e.g. `"username"`. */
@@ -137,9 +139,9 @@ export interface DropdownColumn<TItem extends DropdownItem = DropdownItem> {
     header?: string;
     /** Default `text`. */
     type?: DropdownColumnType;
-    /** A CSS grid track: `"6rem"`, `"auto"`, `"1fr"`. Default: `auto` for avatar, image, icon, and code; `minmax(0, 1fr)` for text. */
+    /** A CSS grid track: `"6rem"`, `"auto"`, `"1fr"`. Default: `auto` for avatar, image, icon, code, and money; `minmax(0, 1fr)` for text. */
     width?: string;
-    /** Default `start`. */
+    /** Default `start`; `end` for `money`. */
     align?: "start" | "center" | "end";
     /** Draws the cell instead of `type`. */
     render?: (item: TItem) => ReactNode;
@@ -154,6 +156,23 @@ export interface DropdownPageRequest {
     skip: number;
     /** Aborted when a newer search replaces this request, or the dropdown unmounts. */
     signal: AbortSignal;
+    /**
+     * Only the options whose `key` field holds `value`: set by a form for an input another narrows (`narrowedBy`). A source
+     * of its own should honour it (`crudPicker` does); a static list is narrowed by the form itself. `orUnset`: the options
+     * whose `key` field is empty are offered too (`narrowedBy.orUnset`), and a `null` value then offers only those.
+     */
+    narrow?: DropdownNarrow;
+    /**
+     * Every narrowing, when several narrow at once (`narrowedBy` as a list: the form's Store and the row's Item): the
+     * options must fit each. `narrow` is the first of them, for a source that reads one. Absent with one narrowing or none.
+     */
+    narrows?: readonly DropdownNarrow[];
+}
+/** One narrowing of a picker's options: the records whose `key` field holds `value` (`orUnset`: or is empty). */
+export interface DropdownNarrow {
+    key: string;
+    value: OptionValue | null;
+    orUnset?: boolean;
 }
 /** What `loadOptions` returns for one page. */
 export interface DropdownPage<TItem extends DropdownItem = DropdownItem> {

package/dist/Interfaces/MailInterfaces.d.ts

@@ -0,0 +1,192 @@
+import type { ChatDomainValue, ChatId, ChatMessageKind, ChatSource } from "./ChatInterfaces.ts";
+import type { DropdownPage, DropdownPageRequest } from "./InputInterfaces.ts";
+import type { TablePage } from "./TableInterfaces.ts";
+/** How a person is on a thread: who sent it, and who it was sent to, copied to, or copied to unseen. */
+export type MailRole = "from" | "to" | "cc" | "bcc";
+/** The lists of a mailbox: every thread not archived, the ones with unread lines, the ones the reader started, the archived. */
+export type MailList = "inbox" | "unread" | "sent" | "archived";
+/** What a thread opened with: a mail a person wrote, or a notification a module wrote about an event. */
+export type MailHeadKind = Extract<ChatMessageKind, "mail" | "notification">;
+/**
+ * What a conversation in a mailbox is, which decides how it opens and which of the mailbox's types it is counted under:
+ * `mail` a mail thread about no record, `chat` a one-to-one or group chat (it opens in a chat popup), `domain` a mail
+ * thread about a record (its `domainType` names the kind: a leave request, a requisition). The Nexus wire's `kind`:
+ * Mail 1, Chat 2, Domain 3.
+ */
+export type MailThreadKind = "mail" | "chat" | "domain";
+/** Someone a mail can be sent to, or was. */
+export interface MailPerson {
+    id: ChatId;
+    name: string;
+    /** False for someone who has left: their name stays on what they wrote, and they cannot be addressed again. */
+    isActive?: boolean;
+    /** A photo URL. Without one, the initials of the name. */
+    avatar?: string | null;
+}
+/** The record a thread is about: its kind (the app's own domain value), its id as the reader may open it, and its words. */
+export interface MailDomain {
+    domainType: ChatDomainValue;
+    /** The record's id, sealed for this reader. `null` when the app knows no way to open records of this kind. */
+    id: ChatId | null;
+    /** The record's words as the module wrote them: "LR2082-0007 · Puja Shrestha". */
+    label: string | null;
+}
+/** One thread in a list of them: what an inbox row shows. A record, so a CRUD can list it. */
+export interface MailInboxRow extends Record<string, unknown> {
+    id: ChatId;
+    subject: string;
+    fromId: ChatId;
+    fromName: string;
+    /** How the reader is on it. */
+    myRole: MailRole;
+    /** What it opened with. */
+    kind: MailHeadKind;
+    /** The kind of record it is about, when it is about one. */
+    domainType?: ChatDomainValue | null;
+    /** That record's words, shown beside the subject. */
+    domainLabel?: string | null;
+    /** When its newest line was written, as a UTC moment. */
+    lastMessageTime: string;
+    /** Who wrote it. */
+    lastAuthorName?: string | null;
+    /** Its first characters, Markdown as written (`markdownToPlainText` for a line of text). */
+    lastPreview: string;
+    messageCount: number;
+    /** Lines the reader has not read. */
+    unreadCount: number;
+    /** The reader put it aside. */
+    archived: boolean;
+    /** What the conversation is: mail, chat, or mail about a record. Absent from an older backend: read from `domainType`. */
+    threadKind?: MailThreadKind;
+    /** The reader starred it. Absent when the backend keeps no stars. */
+    starred?: boolean;
+    /** A photo of the sender: the row's avatar. Without one, their initials. */
+    fromAvatar?: string | null;
+}
+/** A thread opened: its subject and its people, as the reader may see them, and how they may act on it. */
+export interface MailThreadHead {
+    id: ChatId;
+    subject: string;
+    from: MailPerson;
+    to: readonly MailPerson[];
+    cc: readonly MailPerson[];
+    /**
+     * The people copied unseen, as the reader may see them: all of them for the sender, the reader's own row for a person
+     * copied unseen, nobody for anyone else. The backend decides; the thread shows what it is given.
+     */
+    bcc: readonly MailPerson[];
+    myRole: MailRole;
+    archived: boolean;
+    /** The reader may reply. */
+    canSend: boolean;
+    /** When the thread was started, as a UTC moment. */
+    createdTime: string;
+    messageCount: number;
+    unreadCount: number;
+    /** The record it is about. */
+    domain?: MailDomain | null;
+    /** What the conversation is: mail, chat, or mail about a record. */
+    threadKind?: MailThreadKind;
+}
+/** What a list of threads asks for. */
+export interface MailInboxRequest {
+    list: MailList;
+    /** Matched in the subject and the record's words. */
+    search?: string;
+    /**
+     * Only the threads about one record: its kind and its id (as its own module gave it to the reader). The kind alone
+     * (no `parentId`) is a mailbox's type: every thread about a record of that kind.
+     */
+    domainType?: ChatDomainValue;
+    parentId?: ChatId;
+    /** Only one kind of conversation: a mailbox's Mail, Chat, or a record kind's type (`domain` with its `domainType`). */
+    threadKind?: MailThreadKind;
+    /** Threads before this page. */
+    skip: number;
+    /** Threads on this page. */
+    take: number;
+    signal?: AbortSignal;
+}
+/** What the reader has not read: how many lines, and the newest threads holding them. */
+export interface MailUnread {
+    count: number;
+    /** The newest threads with unread lines, newest first. */
+    newest: readonly MailInboxRow[];
+}
+/** One list of a mailbox with how much of it is unread: its folder's count. */
+export interface MailFolderCount {
+    list: MailList;
+    /** Conversations in it with unread lines. */
+    unread: number;
+}
+/** One type of conversation in a mailbox (Mail, Chat, Leave, Request ...), counted across the reader's inbox. */
+export interface MailKindCount {
+    threadKind: MailThreadKind;
+    /** The record kind of a `domain` type; `null` for Mail and Chat. */
+    domainType: ChatDomainValue | null;
+    /** Conversations of this type with unread lines. */
+    unread: number;
+    /** Conversations of this type in the inbox. A type with none is not listed. */
+    total: number;
+}
+/**
+ * The counts beside a mailbox's folders and types, read in one call. The Nexus wire (`Mail/Folders`):
+ * `{ folders: [{ list, unread }], kinds: [{ kind, domainType, unread, total }] }`, lists 1-4 and kinds 1-3.
+ */
+export interface MailFolders {
+    folders: readonly MailFolderCount[];
+    kinds: readonly MailKindCount[];
+}
+/** Who a new message is sent to by default: the people the reader set, or the backend's rule (their supervisor). */
+export interface MailDefaults {
+    to: readonly MailPerson[];
+    cc: readonly MailPerson[];
+    bcc: readonly MailPerson[];
+}
+/** A new message: the people by id, at least one in To; its subject and body; and this browser's id for it, so a retry writes it once. */
+export interface MailDraft {
+    to: readonly ChatId[];
+    cc?: readonly ChatId[];
+    bcc?: readonly ChatId[];
+    subject: string;
+    /** Markdown. */
+    body: string;
+    clientId: string;
+}
+/** A new message written: its thread, and its first line. */
+export interface MailSent {
+    id: ChatId;
+    messageId: ChatId;
+}
+/**
+ * Where a mailbox's data comes from. A thread's lines come through `threadSource`, an ordinary `ChatSource`, so the
+ * chat's store and thread draw, page, send and mark read a mail thread unchanged.
+ */
+export interface MessageSource {
+    /** One page of a list, newest line first. */
+    inbox(request: MailInboxRequest): Promise<TablePage<MailInboxRow>>;
+    /** A thread's head: its subject, its people, the reader's role. */
+    thread(id: ChatId, signal?: AbortSignal): Promise<MailThreadHead>;
+    /** A thread's lines: history, replies and the read mark, as a chat. */
+    threadSource(id: ChatId): ChatSource;
+    /** Writes a new message, and answers its thread. */
+    compose(draft: MailDraft, signal?: AbortSignal): Promise<MailSent>;
+    /** Puts threads aside for the reader alone, and answers how many changed. */
+    archive(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** Brings them back to the inbox, and answers how many changed. */
+    unarchive(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** What the reader has not read. */
+    unread(signal?: AbortSignal): Promise<MailUnread>;
+    /** The people a message can be sent to, searched by name, a page at a time (the reader left out). */
+    people(query: DropdownPageRequest): Promise<DropdownPage<MailPerson>>;
+    /** Who a new message goes to by default. */
+    defaults(signal?: AbortSignal): Promise<MailDefaults>;
+    /** The counts beside the folders and the types. Without it a mail client shows no counts and no Types. */
+    folders?(signal?: AbortSignal): Promise<MailFolders>;
+    /** Marks whole conversations read for the reader, and answers how many changed. Without it, no Mark read. */
+    markRead?(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** Marks conversations unread again (their newest line), and answers how many changed. Without it, no Mark unread. */
+    markUnread?(ids: readonly ChatId[], signal?: AbortSignal): Promise<number>;
+    /** Stars conversations for the reader, or takes the star away. Without it, a mail client draws no stars. */
+    star?(ids: readonly ChatId[], starred: boolean, signal?: AbortSignal): Promise<number>;
+}

package/dist/Interfaces/MailInterfaces.js

@@ -0,0 +1 @@
+export {};