nexus-shared 1.1.21 → 3.0.0

package/dist/Interfaces/ChatInterfaces.d.ts

@@ -0,0 +1,240 @@
+import type { DropdownPage, DropdownPageRequest } from "./InputInterfaces.ts";
+/** An id, as the backend hands it out: a number, or text (a GUID, an encrypted id). */
+export type ChatId = string | number;
+/**
+ * A domain's value in an app's own enum: a number (`EDomainTypes.Leave`) or a string (`"leave"`). The backend will
+ * own the enum; until it does, a plain number is the value, and the components never read it — they only pass it on.
+ */
+export type ChatDomainValue = string | number;
+/**
+ * Where an app names its domain enum for the types, once, next to its other registrations:
+ *
+ * @example
+ * export enum EDomainTypes { Leave = 1, Procurement = 2, Applicant = 3 }
+ * declare module "nexus-shared" {
+ *   interface ChatRegister { domain: EDomainTypes }
+ * }
+ *
+ * Every chat component, scope, and store then takes only those domains. Without it, any number.
+ */
+export interface ChatRegister {
+}
+/** The app's domain type: the one named in `ChatRegister`, else any number. A component can also take one as `<Chat<EDomainTypes> …>`. */
+export type AppChatDomain = ChatRegister extends {
+    domain: infer TDomain extends ChatDomainValue;
+} ? TDomain : number;
+/**
+ * Which conversation this is: the kind of record, the record, and who is reading it. Everything else a chat needs —
+ * where its messages come from, who may write — follows from these three.
+ *
+ * @example
+ * const scope = { domain: EDomainTypes.Leave, parentId: leave.id, userId: me.id };
+ */
+export interface ChatScope<TDomain extends ChatDomainValue = AppChatDomain> {
+    /** Which kind of record the conversation hangs on: a leave request, a purchase order, an applicant, a tender. */
+    domain: TDomain;
+    /** The record's own id. The domain and the id together are the conversation. */
+    parentId: ChatId;
+    /** Who is reading and writing. Their messages sit on the right, and the unread count is theirs. */
+    userId: ChatId;
+}
+/** One domain's name, for the panel's heading and messages. An app registers its own with `defineChatDomains`. */
+export interface ChatDomainInfo<TDomain extends ChatDomainValue = AppChatDomain> {
+    domain: TDomain;
+    /** Its name in a URL or a cache key: `leave`. Letters, digits, dots, dashes, and underscores. */
+    key: string;
+    /** Its name on screen: "Leave request". */
+    label: string;
+}
+/** `sent`: the server has it. `sending`: on its way. `failed`: it did not arrive, and the text is kept to send again. */
+export type ChatMessageStatus = "sent" | "sending" | "failed";
+/** A file on a message. The chat shows and links it; uploading is the app's `ChatSource`. */
+export interface ChatAttachment {
+    id?: ChatId;
+    name: string;
+    /** Bytes, shown as "248 KB". */
+    size?: number;
+    /** Where it opens or downloads. Without one, the name shows but does not link. */
+    url?: string | null;
+    contentType?: string | null;
+}
+/** One message in a conversation. A backend maps its own rows to this in `ChatBackend.readMessage`. */
+export interface ChatMessage {
+    /** The server's id. A message still on its way carries its `clientId` here until the answer brings the real one. */
+    id: ChatId;
+    /** Who wrote it. Compared with the scope's `userId` to decide which side it sits on. */
+    authorId: ChatId;
+    /** Their name, for the avatar and the line above the message. Without one, the chat says "Unknown". */
+    authorName?: string | null;
+    /** A photo URL. Without one, the initials of the name on a tone picked from it. */
+    authorAvatar?: string | null;
+    /** What they wrote, as plain text. Newlines are kept; nothing is parsed as HTML or Markdown. */
+    body: string;
+    /** When it was written, as a UTC moment (`2026-10-01T03:21:04.000Z`). Shown in the reader's own zone. */
+    createdAt: string;
+    /** When it was last changed, as a UTC moment. Shown as "edited". */
+    editedAt?: string | null;
+    /** Default `sent`. `sending` and `failed` belong to messages this browser has not had answered yet. */
+    status?: ChatMessageStatus;
+    /** The message this one answers, quoted above it. */
+    replyToId?: ChatId | null;
+    attachments?: readonly ChatAttachment[];
+    /** Written by the system, not a person ("Sita approved the request."): a centered note, with no avatar or side. */
+    isSystem?: boolean;
+    /** Who it has reached. Two ticks once anyone has it, filled once anyone has read it. */
+    deliveredTo?: readonly ChatId[];
+    /** Who has read it. */
+    readBy?: readonly ChatId[];
+    /** The people named with @ in the body, for the backend to tell them. */
+    mentions?: readonly ChatId[];
+    /** Set while a message is on its way or failed, so Retry can send the very same draft again. */
+    clientId?: string;
+    /** Why it failed, under the message, beside Retry. */
+    error?: string | null;
+}
+/**
+ * What the trigger icon draws itself from, and the only thing a list of 500 rows needs per row. The three states are
+ * `messageCount === 0` (quiet), messages but none unread (highlighted), and `unreadCount > 0` (highlighted, badged).
+ */
+export interface ChatSummary {
+    /** Messages in the conversation. 0 leaves the icon quiet. */
+    messageCount: number;
+    /** Messages this user has not read. */
+    unreadCount: number;
+    /** When the last message was written, as a UTC moment, for the trigger's tooltip. */
+    lastMessageAt?: string | null;
+    /** The last message's text, cut to a line, for the tooltip. */
+    lastMessageText?: string | null;
+    /** Who wrote the last message, for the tooltip. */
+    lastMessageBy?: string | null;
+    /** How many take part. */
+    participantCount?: number;
+    /** How many conversations the record holds, when it holds more than one. */
+    conversationCount?: number;
+}
+/** The three looks of the trigger icon, in the order the owner described them. */
+export type ChatHighlight = "quiet" | "active" | "unread";
+/** One page of history: the newest messages first, then older ones with `before`, or only the new ones with `after`. */
+export interface ChatHistoryRequest {
+    /** Messages older than this one, for the page above. */
+    before?: ChatId | null;
+    /** Messages newer than this one, for a refresh. `before` and `after` are never both set. */
+    after?: ChatId | null;
+    /** How many to send. */
+    take: number;
+    /** Aborted when the conversation changes or the panel unmounts. */
+    signal?: AbortSignal;
+}
+/** What a history request answers with. Messages may come in any order; the store sorts them oldest first. */
+export interface ChatHistory {
+    messages: readonly ChatMessage[];
+    /** Whether older messages remain. Default: the page was full (`messages.length >= take`). */
+    hasMore?: boolean;
+    /** The conversation's counts, when the answer carries them, so one call fills the header too. */
+    summary?: ChatSummary;
+    /** Everyone taking part, when the answer carries them, so the panel needs no second call. */
+    participants?: readonly ChatParticipant[];
+    /** Whether this user may write here. Default true. */
+    canSend?: boolean;
+}
+/** What the composer sends. */
+export interface ChatDraft {
+    body: string;
+    replyToId?: ChatId | null;
+    /** The people named with @ while writing it. */
+    mentions?: readonly ChatId[];
+    /** Files picked in the composer. A source that cannot take files leaves them out of its request. */
+    files?: readonly File[];
+    /** This browser's id for the message, so the answer replaces the right one and Retry sends the same draft. */
+    clientId: string;
+}
+/** Someone in a conversation, or someone who could be added to it. */
+export interface ChatParticipant {
+    id: ChatId;
+    name: string;
+    avatar?: string | null;
+    /** What they are here: "Manager", "Co-worker", "Requested by". Shown under the name. */
+    role?: string | null;
+    /** They read but cannot write. */
+    readOnly?: boolean;
+    /** How far they have read, as a UTC moment. */
+    lastReadAt?: string | null;
+    /** Someone who has left or is no longer active: shown, never offered again. */
+    inactive?: boolean;
+}
+/** What a participant search receives: the same request a dropdown's `loadOptions` takes, so one loader serves both. */
+export type ChatParticipantQuery = DropdownPageRequest;
+/** What a participant search answers: the same page a dropdown takes. */
+export type ChatParticipantPage = DropdownPage<ChatParticipant>;
+/**
+ * Where one conversation's data comes from. The store calls only this, so it never knows about HTTP: the API source
+ * (`apiChatSource`) talks to the app's `ChatBackend`, and `localChatSource` keeps everything in memory for a demo or
+ * a test. Only `history` and `send` are required.
+ */
+export interface ChatSource {
+    /** One page of messages. */
+    history(request: ChatHistoryRequest): Promise<ChatHistory>;
+    /** Sends one message, and answers with the saved one: its real id, its server time. */
+    send(draft: ChatDraft, signal?: AbortSignal): Promise<ChatMessage>;
+    /** Everyone in the conversation, and the people who could join, searched. Without it, the panel shows no participants. */
+    participants?(query: ChatParticipantQuery): Promise<ChatParticipantPage>;
+    /** Adds people to the conversation. Without it, the panel offers no Add. */
+    addParticipants?(ids: readonly ChatId[], signal?: AbortSignal): Promise<readonly ChatParticipant[]>;
+    /** Tells the server the user has read up to a message. Without it, unread counts clear in the browser only. */
+    markRead?(upTo: ChatId, signal?: AbortSignal): Promise<void>;
+    /** Removes a message. Without it, the panel offers no Delete. */
+    remove?(id: ChatId, signal?: AbortSignal): Promise<void>;
+    /**
+     * Pushes new messages in, from a socket or an event stream, and returns the function that stops it. While a source
+     * watches, the store does not poll.
+     */
+    watch?(onMessages: (messages: readonly ChatMessage[]) => void): () => void;
+}
+/** `one-to-one`: two people, named after the other one. `group`: three or more, or any conversation with a name. */
+export type ChatConversationType = "one-to-one" | "group";
+/** One conversation at a place. One of these shows on its own; several offer a switch between them. */
+export interface ChatConversation {
+    id: ChatId;
+    type: ChatConversationType;
+    /** A group's name. A one-to-one has none: it is called after the other person. */
+    title?: string | null;
+    /** Everyone in it. Needed to name a one-to-one, and to fill the people column without a second call. */
+    participants?: readonly ChatParticipant[];
+    /** Its own counts, so the switch can show which conversation is waiting. */
+    summary?: ChatSummary;
+    /** When it was started, as a UTC moment. */
+    createdAt?: string | null;
+    createdBy?: ChatId | null;
+    /** This user may write in it. Default true. */
+    canSend?: boolean;
+    /** Nobody writes in it any more: it is read, never written to. */
+    closed?: boolean;
+}
+/** What starting a conversation sends. The backend settles the type; this is what the user asked for. */
+export interface NewChatRequest {
+    /** One other person makes a one-to-one, more make a group. */
+    type: ChatConversationType;
+    /** Everyone to put in it, the starter aside. */
+    userIds: readonly ChatId[];
+    /** A group's name. */
+    title?: string | null;
+}
+/**
+ * The conversations at one place: what there is, and how to start another. A panel without one shows the single
+ * conversation its `ChatSource` serves, which is what a page that already knows its conversation wants.
+ */
+export interface ChatPlaceSource {
+    /** Every conversation here this user may see, the one with the newest message first. */
+    conversations(signal?: AbortSignal): Promise<readonly ChatConversation[]>;
+    /** Starts one. A one-to-one that already exists comes back instead of a second one. Without it, no New chat. */
+    create?(request: NewChatRequest, signal?: AbortSignal): Promise<ChatConversation>;
+    /** Who can be put in a conversation here. Without it, New chat has nobody to pick. */
+    participants?(query: ChatParticipantQuery): Promise<ChatParticipantPage>;
+}
+/**
+ * A scope of any domain. Helpers that only pass the domain on — a cache key, the counts of a record — take this, so a
+ * component generic over the app's own enum can hand them its scope without a cast.
+ */
+export type AnyChatScope = ChatScope<ChatDomainValue>;
+/** A conversation's key in a cache: `"1:482"`, the domain and the parent id. */
+export type ChatScopeKey = string;

package/{src/sso-client.tsx → dist/Interfaces/ChatInterfaces.js}

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

package/dist/Interfaces/CrudInterfaces.d.ts

@@ -0,0 +1,232 @@
+import type { CSSProperties, ReactNode, Ref } from "react";
+import type { PopupSize } from "../Components/Layouts/Popup.tsx";
+import type { FormStore } from "../Helpers/FormStore.ts";
+import type { TableStore } from "../Helpers/TableStore.ts";
+import type { ApiEndpoint } from "./ApiInterfaces.ts";
+import type { FormProps, FormValues, InputParams } from "./FormInterfaces.ts";
+import type { InputDesign } from "./InputInterfaces.ts";
+import type { DataTableProps, TableColumn, TableMassAction, TablePaging, TableRowAction } from "./TableInterfaces.ts";
+/**
+ * The lists of a controller: every active record (`normal`), the flagged ones, the trash, and the deleted ones
+ * (which can go back to the trash). The records the user pinned are not a list of their own: they sit above the
+ * active list, and in it.
+ */
+export type CrudMode = "normal" | "flag" | "trash" | "deleted";
+/** The built-in actions on one record. */
+export type CrudRowActionName = "view" | "edit" | "flag" | "pin" | "trash" | "recover" | "delete" | "trashFromDelete";
+/** The built-in actions on many records at once. */
+export type CrudMassActionName = "flag" | "pin" | "trash" | "recover" | "delete" | "trashFromDelete" | "description";
+/** Every built-in action: Add, the row actions, and a new description for many records. */
+export type CrudActionName = "create" | CrudRowActionName | "description";
+/**
+ * The endpoints a CRUD calls. `apiController` (and an app's `MODULES.controller`) builds all of them for a Nexus
+ * controller; another backend lists its own. Leave one out, and its action or list is not offered.
+ */
+export interface CrudEndpoints {
+    /** Every record of a list, for tables that page in the browser: `Room/NormalListing`, `Room/TrashListing`, … */
+    lists?: Partial<Record<CrudMode, ApiEndpoint>>;
+    /** One page of a list, for tables that page on the server: `Room/NormalPagination`, … */
+    pages?: Partial<Record<CrudMode, ApiEndpoint>>;
+    /**
+     * The records the user pinned: `Room/PinListing`. They show in a section above the active list, which the user folds
+     * open, and in the list itself. Without it there is no pinned section, and nothing counts the pins against the limit.
+     */
+    pins?: ApiEndpoint;
+    /** One record by its key: `{id}` in the path. */
+    details?: ApiEndpoint;
+    create?: ApiEndpoint;
+    update?: ApiEndpoint;
+    flag?: ApiEndpoint;
+    /** Pins a record, or unpins it: `Room/Pin/{id}`. */
+    pin?: ApiEndpoint;
+    trash?: ApiEndpoint;
+    recover?: ApiEndpoint;
+    delete?: ApiEndpoint;
+    trashFromDelete?: ApiEndpoint;
+    /** Actions on many records, sent the selected keys. */
+    mass?: Partial<Record<CrudMassActionName, ApiEndpoint>>;
+}
+/** Inputs of the Add and Edit forms: one list for both, a list for each, or a function of the action and the row. */
+export type CrudInputs<TRow extends FormValues = FormValues> = readonly InputParams[] | {
+    create?: readonly InputParams[];
+    edit?: readonly InputParams[];
+} | ((action: "create" | "edit", row: TRow | null) => readonly InputParams[] | Promise<readonly InputParams[]>);
+/** What a form popup's side panel is handed: the live form, and which record it was opened on. */
+export interface CrudFormAsideContext<TRow extends FormValues = FormValues> {
+    /**
+     * The form of this popup. Read it with `getValue()` and follow it with `subscribeValue()`: the panel then updates
+     * itself without the form around it re-rendering, which is what keeps a long form typeable while the panel works.
+     */
+    form: FormStore<TRow>;
+    action: "create" | "edit";
+    /** The record being edited, or null for a new one. */
+    row: TRow | null;
+}
+/** The Add and Edit popups and their forms. */
+export interface CrudFormOptions<TRow extends FormValues = FormValues> {
+    /** Width of the popups. Default `md`, or `lg` for forms of more than 8 inputs. */
+    size?: PopupSize;
+    /**
+     * A panel beside the form, in the same popup: a preview of what will be written, a summary, a help panel. It is
+     * given the popup's own `FormStore`, so it can follow what is typed.
+     *
+     * Side by side where there is room; under about 1000px the two stack and the **form comes first**, since that is
+     * what the popup is for. Pair it with a wide `size` (`xl` or `full`): a panel in a 560px popup leaves the form none.
+     */
+    aside?: ReactNode | ((context: CrudFormAsideContext<TRow>) => ReactNode);
+    /** Values of a new record, over each input's default. */
+    newValues?: Partial<TRow> | (() => Partial<TRow>);
+    /**
+     * What Edit opens with: the row as the table has it (`row`, the default), the record from the `details` endpoint
+     * (`details`, for fields a list leaves out), or a function that loads it.
+     */
+    load?: "row" | "details" | ((row: TRow, signal: AbortSignal) => Promise<Partial<TRow> | null | undefined>);
+    /** Shapes what is sent, e.g. to add a parent's id. Default: the values, with the fields the record came with. */
+    transform?: (values: TRow, context: {
+        action: "create" | "edit";
+        row: TRow | null;
+    }) => unknown;
+    /** The form's own rule over its values. */
+    validate?: FormProps<TRow>["validate"];
+    /** Derived values: return values to set after a change. */
+    onFieldChange?: FormProps<TRow>["onFieldChange"];
+    /** Label design of every input that does not set its own. */
+    design?: InputDesign;
+    /**
+     * Keeps unsaved values on this device, per record, under keys that start with this: `hotel-3:user-8:guests`.
+     * Make it unique per user.
+     */
+    draftKey?: string;
+}
+/** What a details popup's side panel is handed: the record, in the shape a form's side panel is handed it. */
+export interface CrudDetailsAsideContext<TRow extends FormValues = FormValues> {
+    /**
+     * The record, in a `FormStore` no input writes to: the row as the list has it at once, then the `details`
+     * endpoint's record when that lands. Read it with `getValue()` and follow it with `subscribeValue()`, exactly as a
+     * form's panel does — so the panel beside the Edit form can be the panel beside the details, unchanged.
+     */
+    form: FormStore<TRow>;
+    /** The row the popup was opened on, as the list has it. */
+    row: TRow;
+}
+/** The details popup that View opens. */
+export interface CrudDetailsOptions<TRow extends FormValues = FormValues> {
+    /** The fields to show. Default: every column, hidden ones too. */
+    columns?: readonly TableColumn<TRow>[];
+    /** Draws the details instead. */
+    render?: (row: TRow) => ReactNode;
+    /** Default `md`. */
+    size?: PopupSize;
+    /**
+     * A panel beside the details, in the same popup: what the record generates, a chart, a preview. It is laid out as
+     * the Add and Edit popups' `form.aside` is, except that here the panel takes the larger share, since the details
+     * beside it are a short list of fields. Pair it with a wide `size` (`xl` or `full`).
+     */
+    aside?: ReactNode | ((context: CrudDetailsAsideContext<TRow>) => ReactNode);
+    /**
+     * What the popup is called, as a noun: the row's menu offers "View {label}" and the popup's title is
+     * "{Subject} {label}". Default `details`. A popup whose panel is the point says so: `schema`, `preview`.
+     */
+    label?: string;
+}
+/** What changed, for `onChange`. */
+export interface CrudChange<TRow extends FormValues = FormValues> {
+    action: CrudActionName;
+    /** The records as they are now; for actions that took them out of the list, as they were. */
+    rows: TRow[];
+    mode: CrudMode;
+}
+/** Table settings a CRUD passes on to its `DataTable`. */
+export type CrudTableOptions<TRow extends FormValues = FormValues> = Pick<DataTableProps<TRow>, "pageSize" | "pageSizes" | "defaultSort" | "numbered" | "maxHeight" | "fill" | "excel" | "size" | "searchPlaceholder" | "maxSelection" | "emptyMessage" | "columnsMenu" | "stateKey" | "searchDelay" | "reorderable" | "resizable" | "pinnable" | "moreActions" | "exportable" | "printable" | "exportName" | "onImport" | "openOnClick">;
+/** Props of `Crud`. */
+export interface CrudProps<TRow extends FormValues = FormValues> {
+    /** The endpoints: `MODULES.controller(NexusModule.Reservation, "Guest", "guest")`, or an object of your own. */
+    api: CrudEndpoints;
+    /** The table's columns. */
+    columns: readonly TableColumn<TRow>[];
+    /** The inputs of the Add and Edit forms. */
+    inputs: CrudInputs<TRow>;
+    /** What one record is: "guest". Titles ("Add guest"), questions, and messages use it. Default: the endpoints' subject, else "record". */
+    subject?: string;
+    /** Its plural, when adding "s" is wrong: "people". */
+    subjectPlural?: string;
+    /** Tells popups and saved table settings apart. Default: the subject. */
+    name?: string;
+    /** The field that tells records apart. Default `id`. */
+    rowKey?: string;
+    /** Names a record in titles and questions: "Sita Sharma". Default: the first column's text. */
+    rowLabel?: (row: TRow) => string;
+    /** `client` (default): each list loads once, and the table searches, sorts, and pages it. `server`: every page is a request. */
+    paging?: TablePaging;
+    /** The lists to offer, in order. Default all five; each also needs its endpoint and the user's permission. */
+    modes?: readonly CrudMode[];
+    /** The list shown first. Default the first one offered. */
+    defaultMode?: CrudMode;
+    /** The built-in actions to offer. Default all; each also needs its endpoint and the user's permission. */
+    actions?: readonly CrudActionName[];
+    /** More actions on a row, after the built-in ones. */
+    rowActions?: (row: TRow, mode: CrudMode) => readonly TableRowAction<TRow>[];
+    /** More actions on selected rows, or `false` for no selection at all. */
+    massActions?: false | ((rows: TRow[], mode: CrudMode) => readonly TableMassAction<TRow>[]);
+    /** The Add and Edit forms. */
+    form?: CrudFormOptions<TRow>;
+    /** The details popup, or `false` for none. */
+    details?: false | CrudDetailsOptions<TRow>;
+    /**
+     * Keeps lists this long (milliseconds) while the page is open, so going back to a list shows it at once. A change is
+     * **written into** every list kept, from the record the answer carried: a record flagged joins the flagged list and
+     * one trashed joins the trash, with no request on either. Only a list the record cannot answer for is dropped, and
+     * that one loads when it is shown. Default 5 minutes; `false` loads every time. Cleared when the page closes.
+     */
+    cache?: false | {
+        lifetime?: number;
+    };
+    /** Before the Add button: more buttons, such as Import. */
+    toolbar?: ReactNode;
+    /** Settings of the table. */
+    table?: CrudTableOptions<TRow>;
+    /** After every change the CRUD made: a record added, saved, trashed, deleted. */
+    onChange?: (change: CrudChange<TRow>) => void;
+    /** The table's name for screen readers. Default: the plural of the subject ("Guests"). */
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    ref?: Ref<CrudHandle<TRow>>;
+}
+/** What `ref` gives on a CRUD. */
+export interface CrudHandle<TRow extends FormValues = FormValues> {
+    /** The table's store: rows, selection, `reload`. */
+    table: TableStore<TRow>;
+    /** The list shown. */
+    mode: CrudMode;
+    setMode: (mode: CrudMode) => void;
+    /** Loads the list again, past the cache. A last resort: `apply` writes a change in without a request. */
+    reload: () => Promise<void>;
+    /**
+     * Records a page's **own** action changed, written where the built-in actions write theirs: into the table, the
+     * pinned band and every list kept in the cache - no request, on any list. Each record is merged over the one the
+     * table holds, so the key and the fields that changed are enough:
+     *
+     * ```ts
+     * const answer = await api.send(REGION_MARKS.flag, { params: { id: row.id } });
+     * if (answer.ok) handle.current?.apply([{ ...row, recordStatus: answer.result }]);
+     * ```
+     *
+     * Which list each record now belongs in comes from the record itself (`CrudBackend.listMembership`), so one that
+     * no longer belongs to the list on screen leaves it, and the other lists are patched behind it. `gone` is for an
+     * action that ends a record: it is taken out of every list.
+     *
+     * It does not call `onChange`, since the page calling it is the one that made the change.
+     */
+    apply: (rows: readonly Partial<TRow>[], options?: {
+        gone?: boolean;
+    }) => void;
+    /** Opens the Add popup, with these values over the new record's. */
+    create: (values?: Partial<TRow>) => void;
+    /** Opens the Edit popup of a record. */
+    edit: (row: TRow) => void;
+    /** Opens the details popup of a record. */
+    view: (row: TRow) => void;
+}

package/dist/Interfaces/CrudInterfaces.js

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

package/dist/Interfaces/DateInterfaces.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Dates in Nexus apps are calendar dates: a day, with no time of day and no time zone. A value is always an ISO
+ * date string in the Gregorian calendar, `"2026-09-17"`, whatever calendar the user sees it in. That is what a form
+ * sends, what an API stores (`DateOnly` in .NET), and what never shifts by a day between time zones.
+ */
+/** The calendar a date is shown and picked in: `ad` Gregorian (English), `bs` Bikram Sambat (Nepali). Values stay Gregorian. */
+export type CalendarType = "ad" | "bs";
+/** How a Nepali date is written: `latin` (2083, Ashwin, 1) or `devanagari` (२०८३, असोज, १). Gregorian dates are always Latin. */
+export type DateScript = "latin" | "devanagari";
+/** A date as its parts in one calendar. Month and day start at 1. */
+export interface DateParts {
+    year: number;
+    month: number;
+    day: number;
+}
+/**
+ * A date the components accept: an ISO date `"2026-09-17"`, an ISO date-time (with a zone it is read in the browser's
+ * local time; without one its date part is taken), or a `Date` (read in local time, like `new Date()`).
+ */
+export type DateInput = string | Date | null | undefined;
+/**
+ * The user's date and time settings, saved in local storage and read by every date and time component.
+ * - `calendar`: which calendar the pickers show. Default `ad`.
+ * - `format`: how a date is written, with the tokens of `formatDate`: `YYYY-MM-DD`, `DD/MM/YYYY`, `MMM DD, YYYY`, ... Default `YYYY-MM-DD`.
+ * - `script`: digits and names of Nepali dates. Default `latin`.
+ * - `timeFormat`: how a time is written, with the tokens of `formatTime`: `hh:mm A` (12-hour) or `HH:mm` (24-hour), ...
+ *   Default `hh:mm A`. Optional here, so date-only settings stay valid; `useDatePreferences` always fills it.
+ */
+export interface DatePreferences {
+    calendar: CalendarType;
+    format: string;
+    script: DateScript;
+    timeFormat?: string;
+}
+export declare const DEFAULT_TIME_FORMAT = "hh:mm A";
+export declare const DEFAULT_DATE_PREFERENCES: Required<DatePreferences>;
+/** Local storage keys of the date and time settings. Other code (a settings page, a login bootstrap) may write them. */
+export declare const DATE_STORAGE_KEYS: {
+    readonly calendar: "nx-date-calendar";
+    readonly format: "nx-date-format";
+    readonly script: "nx-date-script";
+    readonly timeFormat: "nx-time-format";
+};
+/** Formats offered in a settings page. Any string of tokens works; these are the common ones. */
+export declare const DATE_FORMATS: readonly string[];
+/** Time formats offered in a settings page: 12-hour with and without a leading zero, and 24-hour. Seconds are added when a field needs them. */
+export declare const TIME_FORMATS: readonly string[];
+/**
+ * A time of day the components accept: an ISO time `"14:30"` or `"14:30:15"`, an ISO date-time (with a zone, the
+ * browser's local time of that instant; without one, its time part), or a `Date` (its local time, like `new Date()`).
+ * Like a date, a time value has no zone: "14:30" is half past two wherever the form is opened (a .NET `TimeOnly`).
+ */
+export type TimeInput = string | Date | null | undefined;
+/** Custom check for a time. Receives the ISO time, or `null` when the field is empty; returns a message to fail. */
+export type TimeValidator = (value: string | null) => string | null | undefined;
+/** Validation rules for a time, named like the HTML attributes. Limits are inclusive. */
+export interface TimeRules {
+    required?: boolean;
+    /** Earliest time allowed, e.g. "09:00". With `max` earlier than `min`, the allowed range runs past midnight: "22:00" to "06:00". */
+    min?: TimeInput;
+    /** Latest time allowed, e.g. "18:00". */
+    max?: TimeInput;
+    /** Seconds between allowed times, counted from midnight, as in HTML: 60 (default) for any minute, 900 for quarter hours, 1 for seconds. */
+    step?: number;
+    /** Runs after the built-in rules pass. */
+    validate?: TimeValidator;
+}
+/**
+ * A moment the date and time components accept. Unlike a date or a time of day, a date-time value is an instant: the
+ * same moment everywhere, held as a UTC ISO string, `"2026-09-17T08:45:00.000Z"`, and shown in the user's time zone.
+ * - an ISO date-time with a zone: `"2026-09-17T08:45:00Z"`, `"2026-09-17T14:30:00+05:45"`;
+ * - an ISO date-time without a zone, `"2026-09-17T08:45:00"`, is read as UTC: that is how a .NET `DateTime` saved as
+ *   UTC often comes back from a database, with its "Z" lost, and reading it as local time would move it;
+ * - a date alone, `"2026-09-17"`, is the first moment of that day in the user's time zone;
+ * - a `Date`, or milliseconds since 1970 (`Date.now()`).
+ */
+export type DateTimeInput = string | number | Date | null | undefined;
+/** A moment as the user sees it in a time zone: an ISO date and an ISO time of day with seconds. */
+export interface LocalDateTime {
+    /** "2026-09-17" */
+    date: string;
+    /** "14:30:00" */
+    time: string;
+}
+/** Custom check for a date-time. Receives the UTC ISO value, or `null` when the field is empty; returns a message to fail. */
+export type DateTimeValidator = (value: string | null) => string | null | undefined;
+/**
+ * Validation rules for a date-time, named like the HTML attributes. Limits are inclusive. `min` and `max` are moments;
+ * `minTime`, `maxTime`, and `step` apply to the time of day where the user is, on every day.
+ */
+export interface DateTimeRules {
+    required?: boolean;
+    /** Earliest moment allowed, e.g. `new Date()` for "not in the past". */
+    min?: DateTimeInput;
+    /** Latest moment allowed. */
+    max?: DateTimeInput;
+    /** Earliest time of day allowed, e.g. "09:00" for opening hours. With `maxTime` earlier than `minTime`, the hours run past midnight. */
+    minTime?: TimeInput;
+    /** Latest time of day allowed, e.g. "18:00". */
+    maxTime?: TimeInput;
+    /** Seconds between allowed times, counted from each midnight: 60 (default) for any minute, 900 for quarter hours, 1 for seconds. */
+    step?: number;
+    /** Runs after the built-in rules pass. */
+    validate?: DateTimeValidator;
+}
+/** Custom check for a date. Receives the ISO date, or `null` when the field is empty; returns a message to fail. */
+export type DateValidator = (value: string | null) => string | null | undefined;
+/** Validation rules for a date, named like the HTML attributes. Limits are inclusive. */
+export interface DateRules {
+    required?: boolean;
+    /** Earliest date allowed. */
+    min?: DateInput;
+    /** Latest date allowed. */
+    max?: DateInput;
+    /** Runs after the built-in rules pass. */
+    validate?: DateValidator;
+}
+/** A start and an end, as ISO dates. Either may still be `null`; both `null` is an empty range. */
+export type DateRange = readonly [string | null, string | null];
+/** A range the components accept: a start and an end, each a `DateInput`, or nothing. */
+export type DateRangeInput = readonly [DateInput, DateInput] | null | undefined;
+/** Custom check for a date range. Receives the range, with `null` ends when empty; returns a message to fail. */
+export type DateRangeValidator = (range: DateRange) => string | null | undefined;
+/** Validation rules for a date range. `min` and `max` bound both ends; a distance is the end minus the start, in days. */
+export interface DateRangeRules {
+    /** A range with a start and no end (or the reverse) is never valid; `required` also refuses an empty one. */
+    required?: boolean;
+    /** Earliest day of the range. */
+    min?: DateInput;
+    /** Latest day of the range. */
+    max?: DateInput;
+    /** Fewest days from the start to the end: `1` puts the end after the start, as the nights of a stay. Default 0, so one day is a range. */
+    minDistance?: number;
+    /** Most days from the start to the end, e.g. 30 for a stay of up to 30 nights. */
+    maxDistance?: number;
+    /** Runs after the built-in rules pass. */
+    validate?: DateRangeValidator;
+}
+/** A day in a calendar grid, given to `renderDay` so an event calendar can draw markers inside the cell. */
+export interface CalendarDay {
+    /** The ISO date, always Gregorian. */
+    iso: string;
+    /** The day in the calendar being shown (`ad` or `bs`). */
+    parts: DateParts;
+    /** 0 = Sunday. */
+    weekday: number;
+    /** Belongs to the month before or after the one shown. */
+    outside: boolean;
+    today: boolean;
+    selected: boolean;
+    /** Between the two ends of a range, or of the range being picked. */
+    inRange: boolean;
+    disabled: boolean;
+}

package/dist/Interfaces/DateInterfaces.js

@@ -0,0 +1,29 @@
+/**
+ * Dates in Nexus apps are calendar dates: a day, with no time of day and no time zone. A value is always an ISO
+ * date string in the Gregorian calendar, `"2026-09-17"`, whatever calendar the user sees it in. That is what a form
+ * sends, what an API stores (`DateOnly` in .NET), and what never shifts by a day between time zones.
+ */
+export const DEFAULT_TIME_FORMAT = "hh:mm A";
+export const DEFAULT_DATE_PREFERENCES = { calendar: "ad", format: "YYYY-MM-DD", script: "latin", timeFormat: DEFAULT_TIME_FORMAT };
+/** Local storage keys of the date and time settings. Other code (a settings page, a login bootstrap) may write them. */
+export const DATE_STORAGE_KEYS = {
+    calendar: "nx-date-calendar",
+    format: "nx-date-format",
+    script: "nx-date-script",
+    timeFormat: "nx-time-format",
+};
+/** Formats offered in a settings page. Any string of tokens works; these are the common ones. */
+export const DATE_FORMATS = [
+    "YYYY-MM-DD",
+    "DD/MM/YYYY",
+    "MM/DD/YYYY",
+    "DD.MM.YYYY",
+    "D MMMM YYYY",
+    "DD MMM YYYY",
+    "MMM DD, YYYY",
+    "MMMM DD, YYYY",
+    "ddd, DD MMM YYYY",
+    "dddd, MMMM DD, YYYY",
+];
+/** Time formats offered in a settings page: 12-hour with and without a leading zero, and 24-hour. Seconds are added when a field needs them. */
+export const TIME_FORMATS = ["hh:mm A", "h:mm A", "hh:mm a", "HH:mm", "H:mm"];