nexus-shared 1.1.20 → 2.0.0

package/dist/Interfaces/CrudInterfaces.d.ts

@@ -0,0 +1,171 @@
+import type { CSSProperties, ReactNode, Ref } from "react";
+import type { PopupSize } from "../Components/Layouts/Popup.tsx";
+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 archive, 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" | "archive" | "trash" | "deleted";
+/** The built-in actions on one record. */
+export type CrudRowActionName = "view" | "edit" | "flag" | "pin" | "archive" | "restore" | "trash" | "recover" | "delete" | "trashFromDelete";
+/** The built-in actions on many records at once. */
+export type CrudMassActionName = "flag" | "pin" | "archive" | "restore" | "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;
+    archive?: ApiEndpoint;
+    restore?: 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[]>);
+/** 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;
+    /** 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;
+}
+/** 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;
+}
+/** 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" | "size" | "searchPlaceholder" | "maxSelection" | "emptyMessage" | "columnsMenu" | "stateKey" | "searchDelay" | "reorderable" | "resizable" | "pinnable" | "moreActions" | "exportable" | "printable" | "exportName" | "onImport">;
+/** 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; changes update
+     * or drop what is kept. 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, archived, 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. */
+    reload: () => Promise<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/{src/sso-client.tsx → dist/Interfaces/CrudInterfaces.js}

@@ -1 +1 @@
-export {};
+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"];