@nest-my-admin/core 0.3.2 → 0.5.0

package/dist/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,MAAM,CAAC,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAEhE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,wFAAwF;AACxF,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAErD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAC3D,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAEtD,oFAAoF;AACpF,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAC;AAE5B,qEAAqE;AACrE,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAExD,qGAAqG;AACrG,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,MAAM,CAAC,MAAM,uBAAuB,GAAG,wBAAwB,CAAC;AAEhE,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,wFAAwF;AACxF,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AAE1D,4DAA4D;AAC5D,MAAM,CAAC,MAAM,aAAa,GAAG,uBAAuB,CAAC;AAErD,+FAA+F;AAC/F,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAC3D,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAC5D,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAEtD,oFAAoF;AACpF,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAC;AAE5B,qEAAqE;AACrE,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AACxD,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC;AAE5D,qGAAqG;AACrG,MAAM,CAAC,MAAM,sBAAsB,GAAG,uBAAuB,CAAC;AAC9D,MAAM,CAAC,MAAM,qBAAqB,GAAG,sBAAsB,CAAC"}

package/dist/contract.d.ts

@@ -38,7 +38,7 @@ export interface FieldSchema {
     help?: string;
     placeholder?: string;
     /** The widget chosen in the field config; the UI infers one from the type when absent. */
-    widget?: 'text' | 'textarea' | 'number' | 'money' | 'switch' | 'checkbox' | 'select' | 'radio' | 'date' | 'datetime' | 'json' | 'color' | 'badge' | 'slug' | 'password' | 'email' | 'url' | 'file' | 'image' | 'richtext';
+    widget?: 'text' | 'textarea' | 'number' | 'money' | 'switch' | 'checkbox' | 'select' | 'radio' | 'date' | 'datetime' | 'json' | 'color' | 'badge' | 'slug' | 'password' | 'email' | 'url' | 'file' | 'image' | 'richtext' | 'stepper';
     /** Display labels of enum values (values sent stay the raw ones). */
     enumLabels?: Record<string, string>;
     /** Badge colour per value. */
@@ -47,8 +47,22 @@ export interface FieldSchema {
     showIf?: Record<string, string | number | boolean | null | Array<string | number | boolean | null>>;
     /** The slug widget fills itself from this field until edited. */
     slugFrom?: string;
-    /** Currency code for the money widget (display only). */
-    currency?: string;
+    /**
+     * `stepper` widget: the steps in order, the values that are not steps (shown as a badge), and whether records carry
+     * `_steps` (when each step was reached, from the history child).
+     */
+    steps?: {
+        values: string[];
+        exclude: string[];
+        history: boolean;
+    };
+    /** A soft warning shown under the input while it is empty; the save still goes through. */
+    warnIf?: {
+        empty: true;
+        message: string;
+    };
+    /** The money widget's unit in the request's language, and where it goes (display only). */
+    currency?: CurrencyDisplay;
     /** Set for `file` and `image` widgets: what may be uploaded to the field. */
     file?: {
         accept: string[];
@@ -125,12 +139,30 @@ export interface FormLayoutInline {
     max: number;
     /** The child's field that points at the parent (set by the server). */
     link: string;
+    /** Shown, never edited in this form (writes are refused). */
+    readonly?: true;
+    /** The child's computed columns shown in the table (`_computed` on each row), cut to what this user may see. */
+    computed?: string[];
+    /** A marker on the first card by `order` («Main picture»). */
+    markFirst?: string;
+}
+/** Label and value rows in a card (an order's totals): a field of the record, or one of its computed columns (`_computed`). */
+export interface FormLayoutSummary {
+    title?: string;
+    summary: Array<{
+        label: string;
+        value: {
+            field: string;
+        } | {
+            computed: string;
+        };
+    }>;
 }
 export interface FormLayoutTab {
     tab: string;
-    sections: Array<FormLayoutSection | FormLayoutInline>;
+    sections: Array<FormLayoutSection | FormLayoutInline | FormLayoutSummary>;
 }
-export type FormLayoutNode = FormLayoutSection | FormLayoutTab | FormLayoutInline;
+export type FormLayoutNode = FormLayoutSection | FormLayoutTab | FormLayoutInline | FormLayoutSummary;
 /** One inline of a record (`_inlines[child]` on `GET /resources/:parent/:id`). */
 export interface InlineRows {
     /** The children of this record, as the child's own endpoints answer them (`_id`, `_perm`, `_readonly`, `_files`…), by `order` then key. */
@@ -246,10 +278,19 @@ export interface ActionSchema {
     /** Ask before running: `true` for the default question, or the question itself. */
     confirm?: string | true;
     variant: 'default' | 'destructive';
+    /** The record's next step: a filled button, last in the record's header (record actions without input, one per resource). */
+    primary?: true;
     icon?: string;
     /** The form to fill in before running; its values are sent as `input`. */
     input?: DtoFormSchema;
 }
+/** A print template of a resource (`@AdminPrint`): a page the browser prints, for one record or (`bulk`) a selection. */
+export interface PrintSchema {
+    name: string;
+    label: string;
+    bulk: boolean;
+    icon?: string;
+}
 /** Body of `POST /resources/:resource/actions/:name`. Record actions need `ids` (encoded record ids); resource actions refuse them. */
 export interface ActionRequest {
     ids?: string[];
@@ -336,7 +377,47 @@ export interface MetaResponse {
     /** Languages people can switch between. */
     locales: string[];
     groups: MetaGroup[];
+    /** This user may see at least one dashboard widget: the dashboard replaces the home page. */
+    dashboard?: boolean;
+    /** The host's curated menu (`menu` option), cut to what this user reaches; absent without one (groups are the menu). */
+    menu?: MetaMenu;
+}
+/** One entry of a menu section. */
+export type MetaMenuItem = {
+    kind: 'resource';
+    resource: string;
+    label: string;
+    icon?: string;
+    creatable: boolean;
+    searchable: boolean;
+    /** A count is served for it by `GET /api/menu/badges` (key `<section>.<resource>`). */
+    badge?: true;
+} | {
+    kind: 'page';
+    page: string;
+    label: string;
+    icon?: string;
+} | {
+    kind: 'link';
+    href: string;
+    label: string;
+};
+export interface MetaMenuSection {
+    key: string;
+    label: string;
+    icon?: string;
+    items: MetaMenuItem[];
 }
+export interface MetaMenu {
+    sections: MetaMenuSection[];
+    /** Everything visible that no section places (key `advanced`), collapsed by default. May be empty. */
+    advanced: MetaMenuSection;
+}
+/** `GET /api/menu/badges`: counts by `<section>.<resource>`, scoped to the viewer; a badge the viewer may not count is absent. */
+export type MenuBadges = Record<string, {
+    count: number;
+    estimate: boolean;
+}>;
 export type SortDirection = 'asc' | 'desc';
 export type FilterOperator = 'eq' | 'ne' | 'in' | 'nin' | 'lt' | 'lte' | 'gt' | 'gte' | 'between' | 'contains' | 'startsWith' | 'isNull';
 /** A filterable field and the operators its column type supports (spec §11). */
@@ -375,6 +456,14 @@ export interface ResourceSchema {
             badge?: string;
             meta: string[];
         };
+        /** Tabs over the list (`list.tabs`) this viewer may use: a tab writes `filter` to the URL, plus `tab=<key>` when `where`. */
+        tabs?: ListTabSchema[];
+        /** Computed columns (`list.computed`) this viewer may see, by key; their values are each record's `_computed`. */
+        computed?: Record<string, ComputedColumnSchema>;
+        /** `list.export`, for a viewer holding `<resource>.export`: `GET /resources/:resource/export` with the list's query. */
+        export?: {
+            max: number;
+        };
     };
     /** False for the root of a single-table inheritance, or when the user may not create. */
     creatable: boolean;
@@ -392,6 +481,8 @@ export interface ResourceSchema {
      * per record by `_perm.actions`.
      */
     actions: ActionSchema[];
+    /** The print templates (`@AdminPrint`) the signed-in user may print: `GET /resources/:resource/print/:name?id=…`. */
+    prints: PrintSchema[];
     /**
      * Other resources whose relation fields point at this one (spec §9.4 Related): a record's related records are
      * `/<resource>?filter[<field>][<operator>]=<id>`.
@@ -413,8 +504,22 @@ export interface ResourceSchema {
         requiredOnCreate: string[];
         /** Shown on the update form but not writable (`readonly: true`); records add their own in `_readonly`. */
         readonly: string[];
-        /** Sections, inlines and tabs (`form.layout`); absent = one section in form order. */
+        /** Sections, inlines and tabs (`form.layout`, or its main column); absent = one section in form order. */
         layout?: FormLayoutNode[];
+        /** Read-only cards beside the main column (`form.layout.aside`), cut to what this user may see. */
+        aside?: AsideCardSchema[];
+        /** `view`: an existing record opens as text until «Edit». */
+        mode?: 'view';
+        /** The record's header: badge fields, and a subtitle of field values and computed columns (`_computed`). */
+        header?: {
+            badges?: string[];
+            subtitle?: Array<{
+                field: string;
+            } | {
+                computed: string;
+            }>;
+            stepper?: string;
+        };
         constraints: {
             create: Record<string, FieldConstraints>;
             update: Record<string, FieldConstraints>;
@@ -435,6 +540,8 @@ export interface ResourceSchema {
  * resources with such fields add `_files`: field name → `AdminFileRef` (`AdminFileRef[]` with `file.many`) for every
  * field that holds a file. `GET /resources/:resource/:id` of a resource with inlines adds `_inlines`: child resource
  * name → `InlineRows`, for each inline the user may see; so do the answers of its POST and PATCH, read after the save.
+ * List pages of a resource with `list.computed` add `_computed`: column key → `ComputedValue`, for the computed columns
+ * the user may see and the page shows.
  */
 export type AdminRecord = Record<string, unknown>;
 /**
@@ -445,7 +552,8 @@ export type AdminRecord = Record<string, unknown>;
 export interface RecordPermissions {
     update: boolean;
     delete: boolean;
-    actions?: string[];
+    /** Record actions by name: the label to show on this record (`label.for`, else the action's label), or `false` when it may not run here. */
+    actions?: Record<string, string | false>;
 }
 /** `POST /resources/:resource/bulk-delete` with `{ ids }` (encoded record ids): each id succeeds or fails on its own. */
 export interface BulkResult {
@@ -530,6 +638,11 @@ export interface SessionResponse {
         enabled: boolean;
         view: boolean;
     };
+    /** With `appearance`: the admin-wide accent colour (null: the host's branding), and whether this user may change it. */
+    appearance?: {
+        accent: string | null;
+        manage: boolean;
+    };
     /** Changes when roles or memberships change: refetch meta and schemas. */
     permissionsVersion: number;
     /** A superuser looking through another user's eyes (`X-View-As`): `user` is the target, `by` the superuser. Read-only. */
@@ -827,6 +940,137 @@ export interface AuditResponse {
 }
 /** A label in one language, or per language (`{ en: 'Orders', fa: 'سفارش‌ها' }`). */
 export type LocalizedLabel = string | Record<string, string>;
+/** A status colour of the design (badges, computed cells, stat changes). */
+export type Tone = 'ok' | 'warn' | 'bad' | 'info' | 'neutral' | 'primary';
+/**
+ * An aside card (spec §5.6). Own fields come from the record; a relation card's from `_aside[index]` (the related
+ * record's fields this user may see, with its `_id`, absent when they may not see it), linking to it when `link`.
+ */
+export interface AsideCardSchema {
+    title: string;
+    icon?: string;
+    fields: string[];
+    relation?: {
+        field: string;
+        resource: string;
+        link: boolean;
+    };
+}
+/** Dashboard widgets (spec §5.8). */
+export type WidgetType = 'stat' | 'chart' | 'table' | 'progress' | 'list';
+/**
+ * The period a widget is asked for, computed by the UI in the browser's time zone (Jalali-aware): ISO instants, `to`
+ * excluded, and the window before it for comparisons. The server checks `from < to` and a span of at most 366 days.
+ */
+export interface WidgetParams {
+    period: 'day' | 'week' | 'month' | 'year' | 'range';
+    from: string;
+    to: string;
+    previousFrom: string;
+    previousTo: string;
+}
+/** `GET /api/dashboard`: the widgets this user may see, in order. */
+export interface DashboardResponse {
+    widgets: Array<{
+        name: string;
+        type: WidgetType;
+        title: string;
+        size: 1 | 2 | 3 | 4;
+    }>;
+}
+export interface StatWidgetData {
+    /** Already formatted by the host or a plain number as text (the UI formats digits). */
+    value: string;
+    unit?: string;
+    /** Percent against the previous period. */
+    change?: number;
+    previousLabel?: string;
+}
+export interface ChartWidgetData {
+    kind: 'bar' | 'line';
+    labels: string[];
+    series: Array<{
+        label: string;
+        values: number[];
+        dashed?: boolean;
+    }>;
+    total?: string;
+    subtitle?: string;
+}
+export interface TableWidgetData {
+    columns: Array<{
+        key: string;
+        label: string;
+    }>;
+    /** Cell values by column key; a `{ label, tone }` cell is a status badge. */
+    rows: Array<Record<string, string | number | {
+        label: string;
+        tone: Tone;
+    }>>;
+    /** «View all»: the list with this filter. */
+    link?: {
+        resource: string;
+        filter?: Record<string, string>;
+    };
+}
+export interface ProgressWidgetData {
+    percent: number;
+    value: string;
+    caption: string;
+}
+export interface ListWidgetData {
+    items: Array<{
+        icon?: string;
+        text: string;
+        status?: Tone;
+        link?: string;
+    }>;
+}
+/** `GET /api/dashboard/:widget`: the data of the widget's type. */
+export type WidgetData = StatWidgetData | ChartWidgetData | TableWidgetData | ProgressWidgetData | ListWidgetData;
+/** A list tab (spec §5.5). */
+export interface ListTabSchema {
+    key: string;
+    label: string;
+    /** `filter[...]` list parameters the tab sets (none: «all»). */
+    filter: Record<string, string>;
+    /** The tab restricts the list beyond its filters: send `tab=<key>`. */
+    where: boolean;
+    count: 'exact' | 'estimate' | 'none';
+}
+/** `GET /api/resources/:resource/tab-counts`: each tab's count for the viewer, `null` for `count: 'none'`. */
+export type TabCounts = Record<string, {
+    count: number;
+    estimate: boolean;
+} | null>;
+/** A computed list column (spec §5.4). */
+export interface ComputedColumnSchema {
+    label: string;
+    kind: 'image' | 'title' | 'money' | 'badge' | 'count' | 'toggle';
+    sortable: boolean;
+    /** `toggle`: the enum field a click writes (PATCH `{ [field]: on | off }`), when the viewer may edit it. */
+    toggle?: {
+        field: string;
+        on: string;
+        off: string;
+    };
+}
+/**
+ * A computed cell's value (`AdminRecord._computed[key]`): `value` is the main one (an image is its URL, a toggle
+ * a boolean), `subline` and `previous` go with `title` and `money`, `label` and `tone` with `badge`.
+ */
+export interface ComputedValue {
+    value: unknown;
+    subline?: unknown;
+    previous?: unknown;
+    label?: string;
+    tone?: Tone;
+}
+/** A money unit as shown: `۳٬۲۵۰٬۰۰۰ تومان` (after) or `$12.50` (before). */
+export interface CurrencyDisplay {
+    unit: string;
+    position: 'after' | 'before';
+}
 /** Host branding (spec §9.5). Colours and lengths are validated by core before they reach the page. */
 export interface BrandingConfig {
     name?: LocalizedLabel;
@@ -845,4 +1089,9 @@ export interface AdminRuntimeConfig {
     locale: string;
     locales: string[];
     branding: BrandingConfig;
+    /** The global money unit, in every configured language (the UI picks its own). */
+    currency?: {
+        unit: LocalizedLabel;
+        position: 'after' | 'before';
+    };
 }

package/dist/crud/computed-columns.d.ts

@@ -0,0 +1,65 @@
+import type { EntityMetadata, ObjectLiteral, SelectQueryBuilder } from 'typeorm';
+import type { ComputedValue, FieldSchema } from '../contract.js';
+import type { LocalizedText } from '../i18n/localized-text.js';
+import type { AdminContext } from '../resource/admin-context.js';
+import type { ComputedColumn } from '../resource/admin-resource-base.js';
+type RelationMeta = EntityMetadata['relations'][number];
+/** A source once checked against the entity: what to read and how. */
+export type CompiledSource = {
+    type: 'field';
+    path: string;
+} | {
+    type: 'aggregate';
+    fn: 'min' | 'max' | 'sum' | 'count';
+    relation: RelationMeta;
+    field?: string;
+} | {
+    type: 'first';
+    relation: RelationMeta;
+    field: string;
+    by: string;
+} | {
+    type: 'toggle';
+    field: string;
+    on: string;
+    off: string;
+} | {
+    type: 'compute';
+    fn: (rows: any[], ctx: AdminContext) => Promise<Record<string, unknown>>;
+    fields: string[];
+};
+export interface CompiledComputed {
+    key: string;
+    column: ComputedColumn;
+    source: CompiledSource;
+    subline?: CompiledSource;
+    previous?: CompiledSource;
+    /** What it reads, for the policy: own fields and paths, and the child entities (and their fields) it aggregates. */
+    deps: {
+        own: string[];
+        children: Array<{
+            entity: Function;
+            fields: string[];
+        }>;
+    };
+}
+/**
+ * Checks `list.computed` at boot (spec §5.4) and compiles each column: sources exist, relations are one-to-many of a
+ * single-key entity, `sortable` only on aggregates and first rows, a toggle's values are its enum's, `map` only on badges.
+ */
+export declare function checkComputed(computed: Record<string, ComputedColumn> | undefined, metadata: EntityMetadata, enumValues: (field: string) => string[] | undefined, fail: (message: string) => never): Map<string, CompiledComputed>;
+/** A query of a child entity as the viewer may read it (the child resource's `query()` and scopes), or a plain one. */
+export type ChildQuery = (entity: Function, alias: string, ctx: AdminContext | undefined) => SelectQueryBuilder<ObjectLiteral>;
+/**
+ * The page's computed values, by record id: one query per relation or path source and one `compute` call, whatever the
+ * page size (no N+1). Badge labels are localized with `text`.
+ */
+export declare function loadComputed(columns: CompiledComputed[], rows: ObjectLiteral[], metadata: EntityMetadata, ctx: AdminContext, childQuery: ChildQuery, pathQuery: (alias: string) => SelectQueryBuilder<ObjectLiteral>, text: (label: LocalizedText) => string, 
+/** A field's schema (to serialize decimals as strings, dates as ISO…): the entity's resource field, if any. */
+fieldFor: (entity: Function, name: string) => FieldSchema | undefined): Promise<Map<string, Record<string, ComputedValue>>>;
+/**
+ * Sorting by an aggregate or first-row column: a correlated subquery over the rows the viewer may read, selected as
+ * `nma_sort` so paging with joins can order by it. Returns the expression to order by.
+ */
+export declare function addComputedSort(qb: SelectQueryBuilder<ObjectLiteral>, compiled: CompiledComputed, metadata: EntityMetadata, ctx: AdminContext | undefined, childQuery: ChildQuery): string;
+export {};