nexus-shared 3.2.0 → 4.1.0

package/dist/Interfaces/DashboardInterfaces.d.ts

@@ -0,0 +1,123 @@
+import type { ReactNode } from "react";
+/**
+ * A widget's size on the board's 12-column grid: `S` 3×1, `M` 6×2, `L` 6×4, `W` 12×2, `T` 12×4 (columns × rows).
+ * Presets rather than free resizing: fewer layouts that look broken, and nothing to work out on a phone, where every
+ * widget is the full width.
+ */
+export type WidgetSize = "S" | "M" | "L" | "W" | "T";
+/** Where a widget may go: `own` only on its module's dashboard, `anywhere` on any dashboard (the Home too). */
+export type WidgetPlacement = "own" | "anywhere";
+/** One widget on a board: which, and how big. A layout is an ordered list of these: no coordinates are kept. */
+export interface DashboardLayoutItem {
+    code: string;
+    size: WidgetSize;
+}
+/** A board's layout: the widgets in the order they flow, the grid filling every gap (`grid-auto-flow: dense`). */
+export type DashboardLayout = readonly DashboardLayoutItem[];
+/** The version a saved layout carries, so two windows never overwrite each other unseen. */
+export type DashboardVersion = string | number | null;
+/**
+ * What a save (or a reset) answered. `saved` with the new version; `stale` when another window saved first (the
+ * server's 409): its layout and version, which the board shows in place of the edit; `failed` with a sentence.
+ */
+export type DashboardSaveResult = {
+    status: "saved";
+    version: DashboardVersion;
+    layout?: DashboardLayout;
+} | {
+    status: "stale";
+    layout: DashboardLayout;
+    version: DashboardVersion;
+} | {
+    status: "failed";
+    message?: string;
+};
+/** What a widget's `load` and `render` are told. */
+export interface WidgetContext {
+    /** The board's place (`home`, `message`, ...). */
+    place: string;
+    /** The size it is drawn at. */
+    size: WidgetSize;
+}
+/** What a widget's `render` is told besides its data. */
+export interface WidgetRenderContext extends WidgetContext {
+    /** Reads the widget's data again now. */
+    refresh: () => void;
+}
+/**
+ * A widget answered by its module's one call per draw: the board gathers the codes of every widget of `module` that
+ * is near the screen and asks the app's `loadModule(module, codes)` once. `codes` are the parts this widget needs from
+ * that answer (default: its own code); `pick` turns them into its data (default: the one part, or every part by code
+ * when there are several).
+ */
+export interface WidgetBatch<TData = unknown> {
+    module: string;
+    codes?: readonly string[];
+    pick?: (parts: Readonly<Record<string, unknown>>) => TData;
+}
+/**
+ * A widget, declared once in the app's code: what it is, where it may go, its sizes, who may see it, where its data
+ * comes from and how it is drawn. Nothing about a widget lives in a database: only layouts do.
+ *
+ * @example
+ * const unread: WidgetDefinition<MailCounts> = {
+ *   code: "message.counts", module: "message", placement: "anywhere", title: "Mail", sizes: ["S", "M"],
+ *   batch: { module: "message" }, refresh: 60,
+ *   render: counts => <StatWidget items={[{ label: "Unread", value: counts.unread, href: "/admin/message?list=2" }]} />,
+ * };
+ */
+export interface WidgetDefinition<TData = unknown> {
+    /** Unique in the app, `module.name`: `message.counts`, `requisition.my-approvals`. What a layout keeps. */
+    code: string;
+    /** The module it belongs to: the Add list groups by it, and an `own` widget goes only on its module's board. */
+    module: string;
+    placement: WidgetPlacement;
+    /** Its heading on the board and in the Add list. */
+    title: string;
+    /** A sentence under the title in the Add list. */
+    description?: string;
+    /** Beside the title in the Add list. */
+    icon?: ReactNode;
+    /** The sizes it can take, the first the default. At least one. */
+    sizes: readonly WidgetSize[];
+    /**
+     * The permission key whose holder may see it (none: everyone signed in). The board does not read it: the app's
+     * `canSee(widget)` does, with whatever it knows of the person and the company.
+     */
+    key?: string;
+    /** Its own data call. A widget with neither `load` nor `batch` needs no data (a version, a clock). */
+    load?: (context: WidgetContext) => Promise<TData>;
+    /** Its part of its module's one call per draw, in place of `load`. */
+    batch?: WidgetBatch<TData>;
+    /** Seconds its data stays fresh while the page is open: read again after that while it is on screen. Default: the page's life. */
+    refresh?: number;
+    /** Draws it from its data. */
+    render: (data: TData, context: WidgetRenderContext) => ReactNode;
+    /** Whether the data is nothing to show: the frame then says `empty`. Default: `null`, `undefined` or an empty list. */
+    isEmpty?: (data: TData) => boolean;
+    /** What an empty widget says. Default "Nothing to show yet." */
+    empty?: ReactNode;
+    /** A link in its heading, to the page its data comes from. */
+    link?: {
+        href: string;
+        label?: string;
+    };
+}
+/** What `loadModule` answers: each asked code's part. A code left out is a part the person may not see (empty). */
+export type WidgetModuleAnswer = Readonly<Record<string, unknown>>;
+/** The app's one call per module per draw. */
+export type WidgetModuleLoader = (module: string, codes: readonly string[]) => Promise<WidgetModuleAnswer>;
+/** A widget's data as the board holds it. */
+export type WidgetState<TData = unknown> = {
+    status: "idle";
+} | {
+    status: "loading";
+    data?: TData;
+} | {
+    status: "ready";
+    data: TData;
+    at: number;
+} | {
+    status: "failed";
+    message: string;
+};

package/dist/Interfaces/DashboardInterfaces.js

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

package/dist/Interfaces/DomainInterfaces.d.ts

@@ -0,0 +1,145 @@
+import type { ReactNode } from "react";
+import type { ChatDomainValue, ChatId } from "./ChatInterfaces.ts";
+import type { Tone } from "./TypeInterfaces.ts";
+/** How a value is written: a plain text, a date or a moment in the reader's settings, days, money, a person's name. */
+export type DomainCardValueKind = "text" | "number" | "date" | "datetime" | "days" | "money" | "person";
+/** One field of a card: its label and value, written by its kind. A field with no value is left out. */
+export interface DomainCardField {
+    label: string;
+    /** An ISO date for `date`, a UTC moment for `datetime`, a number for `days`, `number` and `money`. */
+    value: string | number | null | undefined;
+    /** Default `text`. */
+    kind?: DomainCardValueKind;
+    /** Words after the value, quieter: "second half", "from the 2081/82 year". */
+    note?: string;
+    /** Written in place of a missing value; without it the field is left out. */
+    empty?: string;
+    /** A `money` field's currency, over the card's. */
+    currency?: string;
+}
+/** A figure: a number that matters, drawn large in a row of them ("Available 14 days", "Taken 5 days"). */
+export interface DomainCardFigure {
+    label: string;
+    /** A number is written by its kind; a text as it is. A missing value is written as "-". */
+    value: number | string | null | undefined;
+    /** Default `number`. `days` writes the unit "day" or "days" by itself. */
+    kind?: Extract<DomainCardValueKind, "number" | "days" | "money">;
+    /** Words after the value, smaller: "items". Left out for `days` (its own) and `money` (its currency). */
+    unit?: string;
+    /** Marks the figure with its colour beside it: `warning` for days held, `danger` for an overdrawn balance. */
+    tone?: Tone;
+    /** A short line under the figure: "2 of them this request". */
+    hint?: string;
+    /** A `money` figure's currency, over the card's. */
+    currency?: string;
+}
+/** A column of a card's lines. */
+export interface DomainCardLineColumn {
+    label: string;
+    /** Default `text`; `number`, `money` and `days` sit at the end. */
+    kind?: DomainCardValueKind;
+    /** Default: the end for numbers, the start for the rest. */
+    align?: "start" | "end";
+}
+/** A short table on a card: the first items of a requisition, with how many more there are. */
+export interface DomainCardLines {
+    columns: readonly DomainCardLineColumn[];
+    /** One row per line, a value per column, written by the column's kind. */
+    rows: readonly (readonly (string | number | null | undefined)[])[];
+    /** Lines the card does not show: "and 3 more". */
+    more?: number;
+    /** What the lines are, for a screen reader: "Items". Default "Lines". */
+    label?: string;
+}
+/** Where the record can be opened in full: a link at the end of the line under the title. */
+export interface DomainCardLink {
+    href: string;
+    label: string;
+    /** `_blank` opens a new tab. */
+    target?: string;
+}
+/** A card as it is drawn: what an app's `view` makes of its module's answer. */
+export interface DomainCardParams {
+    /** What the record is, in a few words: "Home leave · 2 days". */
+    title: string;
+    /** Its number, on the quiet line under the title: "LR2082-0007". */
+    code?: string | null;
+    /** Words on the line under the title, after the code: the request's own title. */
+    subtitle?: string | null;
+    /** Where it stands, as a tag in its tone: "In approval" (info), "Rejected" (danger). */
+    state?: {
+        label: string;
+        tone?: Tone;
+    } | null;
+    fields?: readonly DomainCardField[];
+    figures?: readonly DomainCardFigure[];
+    lines?: DomainCardLines | null;
+    link?: DomainCardLink | null;
+    /** The currency every `money` value is written in, unless it names its own: "Rs.". */
+    currency?: string | null;
+}
+/** What a card's `load`, `view` and `extra` are told besides the record. */
+export interface DomainCardContext {
+    /** The record's kind: the app's own domain value. */
+    domainType: ChatDomainValue;
+    /** The record's id, as the reader may open it (a token sealed for them). */
+    id: ChatId;
+    /** Who reads, when the page says (a thread's reader). */
+    viewer?: ChatId;
+    /** The record's words as the message holds them: "LR2082-0007 · Puja Shrestha". */
+    label?: string | null;
+    /** The kind's name on screen, from `defineChatDomains`: "Leave request". */
+    kind?: string;
+}
+/** How many of each part a card holds: what its placeholder draws while it loads, so it does not jump when it lands. */
+export interface DomainCardShape {
+    /** The quiet line under the title: the code, the subtitle, the link. */
+    subtitle: boolean;
+    state: boolean;
+    fields: number;
+    figures: number;
+    /** Which figures, counted from 0, have a hint under them. */
+    hints: readonly number[];
+    /** Rows of lines shown, and their columns. */
+    lines: number;
+    columns: number;
+    /** An "and 3 more" under the lines. */
+    more: boolean;
+    link: boolean;
+}
+/**
+ * The card of one kind of record: how to read it and how to show it. Give it to the kind's row of `defineChatDomains`
+ * (`card`); `domainCard(...)` types `view` by what `load` answers.
+ */
+export interface DomainCardDefinition<TData = unknown> {
+    /**
+     * Reads the record from the module that owns it: its card door, which checks the reader. A refusal of the reader
+     * (403) or a record that is not there for them (404) is shown as "You cannot open this ..."; any other failure as a
+     * failure with Try again. The signal aborts when nobody waits for the answer any more.
+     */
+    load(id: ChatId, signal: AbortSignal, context: DomainCardContext): Promise<TData>;
+    /** Maps the answer to what the card draws. */
+    view(data: TData, context: DomainCardContext): DomainCardParams;
+    /** One more piece after the lines, made of this package's parts, for a kind that needs it. */
+    extra?(data: TData, context: DomainCardContext): ReactNode;
+    /** What the placeholder holds the first time a card of this kind loads; later ones hold the last card's shape. */
+    held?: Partial<DomainCardShape>;
+    /** How long an answer is kept for every card of the page, in milliseconds. Default 30,000; 0 keeps none. */
+    lifetime?: number;
+}
+/** Where one card stands. */
+export type DomainCardStatus = "loading" | "ready" | "refused" | "failed";
+/** One card's read, as its component draws it. */
+export interface DomainCardSnapshot<TData = unknown> {
+    status: DomainCardStatus;
+    /** The record as last read: kept on screen while it is read again, and when reading again fails. */
+    data?: TData;
+    /** A read is on its way while the card shows what it read before. */
+    refreshing: boolean;
+    /** The last read again failed: the card on screen is the one read before. */
+    refreshFailed: boolean;
+    /** When a read again found the record changed from the one on screen (milliseconds since 1970). */
+    changedAt?: number;
+    /** Why the last read failed. */
+    error?: unknown;
+}

package/dist/Interfaces/DomainInterfaces.js

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

package/dist/Interfaces/FileInterfaces.d.ts

@@ -0,0 +1,183 @@
+import type { ApiModuleValue, AppModule } from "./ApiInterfaces.ts";
+/**
+ * Whose files: the module that owns the row, the category, and the row's id. The module decides who may change them
+ * (with Nexus, its `Files/Ticket` signs the change), so it is the owner's module, not the one that stores the bytes.
+ *
+ * @example
+ * { module: NexusModule.Enterprise, category: "branch-picture", ownerId: branch.id }
+ * { module: NexusModule.Enterprise, category: "user-picture", ownerId: "me" } // the person's own
+ */
+export interface FileOwner<TModule extends ApiModuleValue = AppModule> {
+    module: TModule;
+    /** The category's code: `branch-picture`, `subscriber-document`. */
+    category: string;
+    /** The owner row's id, as the module answers it; `me` for the person's own. */
+    ownerId: string;
+}
+/** Which copy of a stored file: the file itself, or its small picture. */
+export type FileCopy = "original" | "thumbnail";
+/**
+ * One way an owner's files change: a file added, renamed, made the owner's picture (or none), or deleted. In words, as a
+ * category's kinds are MIME types; they are the Nexus core's `EFileChanges` (Add 1, Rename 2, Primary 3, Remove 4) one
+ * for one. A record whose files may only be added to - a posted goods receipt's documents - allows `["add"]`.
+ */
+export type FileChange = "add" | "rename" | "primary" | "remove";
+/** Every change, in the order the core numbers them. */
+export declare const FILE_CHANGES: readonly FileChange[];
+/** One stored file, as the adapter reads it. */
+export interface StoredFile {
+    /** Its id, as the backend answers it (with Nexus, encrypted for the person asking). */
+    id: string;
+    /** The name it is shown by, with the extension of what it really is. */
+    name: string;
+    /** What its bytes are: `image/png`, `image/jpeg`, `image/webp`, `application/pdf`. */
+    contentType: string;
+    /** Its size in bytes. */
+    size: number;
+    /** A picture's size in pixels; null for a document. */
+    width: number | null;
+    height: number | null;
+    /** Whether a thumbnail was stored with it. Without one, the thumbnail copy is the file itself (pictures only). */
+    hasThumbnail: boolean;
+    /** Whether it is the owner's picture: at most one per owner and category. */
+    isPrimary: boolean;
+    /** When it was stored: an ISO UTC moment, or null when the backend does not say. */
+    createdAt: string | null;
+    /**
+     * Its Delete waits for a review: in a category that holds removals (`FileCategoryInfo.holdsRemovals`, a reviewed
+     * gallery) a Delete only marks the file, which is still served and listed until the reviewer decides, and the person
+     * may Keep it (`FileAdapter.keep`) until then. Left out (or false) for every other file.
+     */
+    pendingRemoval?: boolean;
+    /** When its removal was asked, while it waits for the review: an ISO UTC moment, when the backend says. */
+    removalAt?: string;
+}
+/** What a category takes, as the backend says: what a gallery tells the person before an upload is refused. */
+export interface FileCategoryInfo {
+    /** The category's code. */
+    code: string;
+    /** Its name: "Branch picture". */
+    name: string;
+    /** The MIME types it takes: `["image/png", "image/jpeg", "image/webp"]`. */
+    types: readonly string[];
+    /** The largest file it takes, in bytes. */
+    maxBytes: number;
+    /** How many files one owner keeps. */
+    maxCount: number;
+    /** The longest side of a thumbnail in pixels; 0 when it keeps none. */
+    thumbnailSize: number;
+    /** Whether this person may change the files: upload, make primary, rename, delete. */
+    canWrite: boolean;
+    /**
+     * The longest side a stored picture may have, in pixels: Drive's `Nexus:Drive:Pictures:MaxSide`. Every picture is
+     * made to fit it in the browser before it is sent. Default `PICTURE_LIMITS.maxSide` (1920) when the backend does not say.
+     */
+    pictureMaxSide?: number;
+    /** The highest quality a picture is written at, in percent: Drive's `Quality`. Default `PICTURE_LIMITS.quality` (80). */
+    pictureQuality?: number;
+    /**
+     * The most bytes a stored picture may hold: Drive's `MaxKilobytes`, never above `maxBytes`. The browser writes every
+     * picture under it (a lower quality, then a smaller size). Default `PICTURE_LIMITS.maxBytes` (300 KB), at most `maxBytes`.
+     */
+    pictureMaxBytes?: number;
+    /**
+     * A Delete here waits for a review (a company's public gallery, which Nexus support approves): the file is marked
+     * `pendingRemoval`, not removed, until the reviewer decides. Left out (or false) where a Delete removes at once.
+     */
+    holdsRemovals?: boolean;
+}
+/** An owner's files and what their category takes. */
+export interface OwnerFiles {
+    category: FileCategoryInfo;
+    /** The live files, in their order. */
+    files: StoredFile[];
+    /**
+     * Why this person may only look (`category.canWrite` false), in the backend's words when it gave them: the refusal of
+     * the write ticket ("You do not hold the key to change this branch").
+     */
+    readOnlyReason?: string;
+}
+/** What an upload sends: the file the browser made, and for a picture its thumbnail. */
+export interface FileUpload {
+    file: Blob;
+    /** The name to keep: "Front desk.jpg". The backend keeps the real kind's extension whatever it says. */
+    name: string;
+    thumbnail?: Blob | null;
+}
+/** What every call of the adapter takes. */
+export interface FileCallOptions {
+    signal?: AbortSignal;
+    /** Shows no toast for this call: the panel says what happened. */
+    toast?: false;
+}
+/** Picture kinds a browser canvas writes, and so the ones the editor saves. */
+export type PictureType = "image/jpeg" | "image/png" | "image/webp";
+/** The MIME types of pictures (what a canvas can read back), in the order a file picker offers them. */
+export declare const PICTURE_TYPES: readonly PictureType[];
+/** Whether a MIME type is a picture this package can show and edit. */
+export declare const isPictureType: (type: string | null | undefined) => type is PictureType;
+/** What the editor is opened with (a part of `nexus-image-editor`'s `ImageEditorOptions`). */
+export interface ImageEditorOptions {
+    src?: File | Blob | string;
+    /** A number locks the shape (1 for a logo or an avatar); `free` lets the person choose. */
+    aspect?: number | "free" | "original" | Array<number | "free" | "original">;
+    /** A round guide over a square crop, for a person's picture. */
+    shape?: "rect" | "circle";
+    maxWidth?: number;
+    maxHeight?: number;
+    minWidth?: number;
+    minHeight?: number;
+    type?: PictureType;
+    /**
+     * The kinds the place the picture goes to takes (a file category's): the only ones the editor offers and saves - a
+     * picture too large as a PNG becomes a JPEG or a WebP only when one of them is taken, else stays a PNG, made smaller.
+     */
+    types?: readonly PictureType[];
+    /** 0-1. */
+    quality?: number;
+    /** 0-1: the highest quality written (the slider's top, where it starts at most). */
+    maxQuality?: number;
+    /** The most bytes the saved file may hold: a lower quality, then a smaller picture, until it fits. */
+    maxBytes?: number;
+    /** The longest side of a thumbnail made with the picture, in pixels. */
+    thumbnail?: number | boolean;
+    title?: string;
+    fileName?: string;
+    signal?: AbortSignal;
+}
+/** What the editor answers on Save. */
+export interface ImageEditorResult {
+    blob: Blob;
+    width: number;
+    height: number;
+    type: string;
+    thumbnail: Blob | null;
+    name: string;
+    /** What `maxBytes` took (another type, a lower quality 0-1, the size it would have had), or null when nothing. */
+    fitted?: {
+        maxBytes: number;
+        type?: string;
+        quality?: number;
+        from?: {
+            width: number;
+            height: number;
+        };
+    } | null;
+}
+/** One picture of the viewer. */
+export interface ImageViewerItem {
+    src: string | Blob;
+    title?: string;
+}
+/** The parts of `nexus-image-editor` this package calls. */
+export interface ImageEditorModule {
+    openImageEditor(options?: ImageEditorOptions): Promise<ImageEditorResult | null>;
+    openImageViewer(options: {
+        images: ImageViewerItem[];
+        index?: number;
+        title?: string;
+    }): Promise<void>;
+    /** Makes the stored picture without opening the editor: the size clamped, the thumbnail made. `null` edits: as it is. */
+    renderImage(src: File | Blob | string, edits: null, options?: Pick<ImageEditorOptions, "maxWidth" | "maxHeight" | "type" | "types" | "quality" | "maxQuality" | "maxBytes" | "thumbnail">): Promise<Omit<ImageEditorResult, "name">>;
+    readonly VERSION: string;
+}

package/dist/Interfaces/FileInterfaces.js

@@ -0,0 +1,6 @@
+/** Every change, in the order the core numbers them. */
+export const FILE_CHANGES = ["add", "rename", "primary", "remove"];
+/** The MIME types of pictures (what a canvas can read back), in the order a file picker offers them. */
+export const PICTURE_TYPES = ["image/jpeg", "image/png", "image/webp"];
+/** Whether a MIME type is a picture this package can show and edit. */
+export const isPictureType = (type) => PICTURE_TYPES.includes(type);