@antelopejs/interface-dms-builder 0.2.5 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 <a href="https://www.npmjs.com/package/@antelopejs/interface-dms-builder"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/interface-dms-builder?style=for-the-badge&labelColor=000000&color=000000"></a>
 <a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/interface-dms-builder?style=for-the-badge&labelColor=000000&color=000000"></a>
-<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://discord.gg/g4pFt6eXqu"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
 <a href="https://dms.antelopejs.com/docs/modules/builder/extending"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
 
 The AntelopeJS interface to edit a DMS project's pages, blocks, resources and queries from code.
@@ -61,13 +61,15 @@ if (!block.ok) {
 
 The interface declares this peer dependency:
 
-<!-- docs-compat: ./package.json#peerDependencies -->
+<!-- antelopejs-docs-compat:start -->
 
-| Package | Range |
-| --- | --- |
-| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` |
+| Package                      | Supported        | Tested with |
+| ---------------------------- | ---------------- | ----------- |
+| `@antelopejs/interface-core` | `>=0.2.4 <1.0.0` | —           |
 
-The 0.2 interface is implemented by `@antelopejs/dms-builder` 0.4, used with DMS 0.9. These implementation versions are not peer dependencies of the interface package. The implementation runs in development only, unless its [`api.enabled`](https://dms.antelopejs.com/docs/modules/builder/configuration) option forces it.
+<!-- antelopejs-docs-compat:end -->
+
+The implementation runs in development only, unless its [`api.enabled`](https://dms.antelopejs.com/docs/modules/builder/configuration) option forces it.
 
 ## Documentation
 

package/dist/analysis.d.ts

@@ -1,3 +1,4 @@
+import type { ColumnDisplay, TabsChoice } from "./mapping";
 import type { ResourceRef } from "./resources";
 import type { OpResult } from "./results";
 export type ProposedKind = "fact" | "default";
@@ -37,6 +38,7 @@ export interface ProposedField {
     filterable: Proposed<boolean>;
     sortable: Proposed<boolean>;
     searchable: Proposed<boolean>;
+    display?: Proposed<ColumnDisplay>;
     relation?: ProposedRelationColumn;
     profile?: ProposedColumnProfile;
 }
@@ -56,6 +58,7 @@ export interface ProposedResource {
     writable: Proposed<boolean>;
     label: Proposed<string | null>;
     title: Proposed<string>;
+    tabs?: Proposed<TabsChoice>;
     fields: ProposedField[];
     leftOut: ProposedLeftOut[];
     writes: ProposedWrites;

package/dist/analysis.js.map

@@ -1 +1 @@
-{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAyMlD,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AAMO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAAoD,CAAC;AAc3D,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA8MlD,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAEd,CAAC;AAMO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAAoD,CAAC;AAc3D,QAAA,UAAU,GACrB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/compose.d.ts

@@ -0,0 +1,55 @@
+import type { BlockPath, PageRef } from "./addressing";
+import type { QueryPreviewRequest } from "./drafts";
+import type { AddQueryInput, QueryPreview, QueryRef } from "./queries";
+import type { AddBlockInput, CreatePageInput } from "./operations";
+import type { ResourceRef } from "./resources";
+import type { MutationOpts, OpResult } from "./results";
+export interface ComposeQuery extends Omit<AddQueryInput, "name"> {
+    name?: string;
+    into?: string;
+    args?: QueryPreviewRequest["args"];
+}
+export interface ComposeBlock {
+    name: string;
+    type: string;
+    config?: AddBlockInput["config"];
+    controller?: ResourceRef;
+    slot?: string;
+    meta?: AddBlockInput["meta"];
+    query?: ComposeQuery;
+    children?: ComposeBlock[];
+}
+export interface ComposePlacement {
+    before?: string;
+    after?: string;
+}
+export interface ComposePageInput {
+    page?: PageRef;
+    create?: CreatePageInput;
+    parent?: BlockPath;
+    placement?: ComposePlacement;
+    blocks: ComposeBlock[];
+    preview?: boolean;
+    args?: QueryPreviewRequest["args"];
+    tenant?: string;
+}
+export interface ComposedBlock {
+    pointer: string;
+    path: BlockPath;
+    query?: QueryRef;
+    route?: string;
+}
+export interface ComposePreviewBlock {
+    pointer: string;
+    block: string;
+    status: "ok" | "empty" | "zero" | "error";
+    preview?: QueryPreview;
+    error?: string;
+}
+export interface ComposePageData {
+    page: PageRef;
+    written: boolean;
+    blocks: ComposedBlock[];
+    previews: ComposePreviewBlock[];
+}
+export declare const ComposePage: (input: ComposePageInput, opts?: MutationOpts | undefined) => Promise<OpResult<ComposePageData>>;

package/dist/compose.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComposePage = void 0;
+const interface_core_1 = require("@antelopejs/interface-core");
+exports.ComposePage = (0, interface_core_1.InterfaceFunction)();
+//# sourceMappingURL=compose.js.map

package/dist/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../src/compose.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2GlD,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAKd,CAAC"}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./addressing";
 export * from "./analysis";
 export * from "./catalog";
+export * from "./compose";
 export * from "./drafts";
 export * from "./mapping";
 export * from "./operations";
@@ -9,4 +10,5 @@ export * from "./queries";
 export * from "./resources";
 export * from "./results";
 export * from "./structure";
+export * from "./table-view";
 export * from "./values";

package/dist/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./addressing"), exports);
 __exportStar(require("./analysis"), exports);
 __exportStar(require("./catalog"), exports);
+__exportStar(require("./compose"), exports);
 __exportStar(require("./drafts"), exports);
 __exportStar(require("./mapping"), exports);
 __exportStar(require("./operations"), exports);
@@ -25,5 +26,6 @@ __exportStar(require("./queries"), exports);
 __exportStar(require("./resources"), exports);
 __exportStar(require("./results"), exports);
 __exportStar(require("./structure"), exports);
+__exportStar(require("./table-view"), exports);
 __exportStar(require("./values"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,6CAA2B;AAC3B,4CAA0B;AAC1B,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,4CAA0B;AAC1B,4CAA0B;AAC1B,8CAA4B;AAC5B,4CAA0B;AAC1B,8CAA4B;AAC5B,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,6CAA2B;AAC3B,4CAA0B;AAC1B,4CAA0B;AAC1B,2CAAyB;AACzB,4CAA0B;AAC1B,+CAA6B;AAC7B,4CAA0B;AAC1B,4CAA0B;AAC1B,8CAA4B;AAC5B,4CAA0B;AAC1B,8CAA4B;AAC5B,+CAA6B;AAC7B,2CAAyB"}

package/dist/mapping.d.ts

@@ -1,6 +1,23 @@
 import type { CategoryRef, PageRef } from "./addressing";
 import type { ResourceRef } from "./resources";
 import type { OpResult } from "./results";
+import type { TableViewSettings } from "./table-view";
+export type DisplayTone = "neutral" | "primary" | "secondary" | "success" | "warning" | "error" | "info";
+export interface BadgeItem {
+    value: string;
+    label: string;
+    tone: DisplayTone;
+}
+export type ColumnDisplay = {
+    kind: "badge";
+    items: BadgeItem[];
+} | {
+    kind: "price";
+    currency?: string;
+};
+export interface TabsChoice {
+    column: string;
+}
 export interface MappedField {
     column: string;
     declared?: string;
@@ -9,16 +26,22 @@ export interface MappedField {
     filterable?: boolean;
     sortable?: boolean;
     searchable?: boolean;
-    relation?: string;
+    display?: ColumnDisplay | null;
+    relation?: string | null;
 }
 export interface MappedResource {
     relation: string;
     className?: string;
     label?: string;
     title?: string;
+    icon?: string;
+    description?: string;
+    order?: number;
+    tableOptions?: TableViewSettings;
     tableView: boolean;
     writable: boolean;
     fields: MappedField[];
+    tabs?: TabsChoice | null;
 }
 export interface ExcludedRelation {
     relation: string;

package/dist/mapping.js.map

@@ -1 +1 @@
-{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAmGlD,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../src/mapping.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAgMlD,QAAA,YAAY,GACvB,IAAA,kCAAiB,GAEd,CAAC"}

package/dist/results.d.ts

@@ -14,7 +14,7 @@ export interface TypecheckError {
     message: string;
 }
 export interface OpWarning {
-    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed" | "data_kept" | "page_not_written" | "relation_missing" | "module_not_loaded";
+    code: "query_opaque" | "query_kept" | "index_clamped" | "datatype_fallback" | "data_not_dropped" | "route_changed" | "data_kept" | "page_not_written" | "relation_missing" | "display_not_proposed" | "module_not_loaded" | "setting_dropped" | "relation_skipped" | "display_dropped" | "field_flag_set" | "label_changed";
     message: string;
 }
 export type DuplicateScope = "page" | "siblings" | "category" | "resource" | "query" | "module";

package/dist/table-view.d.ts

@@ -0,0 +1,74 @@
+import type { BlockPath } from "./addressing";
+import type { MutationOpts, OpResult } from "./results";
+export type TableDisplayId = "table" | "kanban" | "cards" | "grouped";
+export interface KanbanSetting {
+    groupBy: string;
+    draggable?: boolean;
+}
+export interface GroupedSetting {
+    groupBy: string;
+    by?: "value" | "day" | "week";
+    collapsible?: boolean;
+    count?: boolean;
+}
+export interface CardsSetting {
+    fields?: string[];
+}
+export type ViewFilterMode = "is" | "is_not" | "include" | "exclude" | "contains" | "not_contains" | "greater_than" | "less_than" | "greater_than_or_equal_to" | "less_than_or_equal_to" | "is_empty" | "is_not_empty";
+export interface ViewFilterSetting {
+    column: string;
+    mode?: ViewFilterMode;
+    value?: string | string[];
+}
+export interface ViewSetting {
+    id: string;
+    label: string;
+    icon?: string;
+    count?: boolean;
+    filters?: ViewFilterSetting[];
+    search?: string;
+    sort?: {
+        column: string;
+        desc?: boolean;
+    }[];
+    columns?: {
+        visible?: string[];
+        hidden?: string[];
+        order?: string[];
+    };
+    display?: TableDisplayId;
+    density?: "default" | "compact";
+}
+export interface ViewsSetting {
+    items: ViewSetting[];
+    layout?: "tabs" | "strip" | "menu";
+    defaultView?: string;
+    userViews?: boolean;
+}
+export interface FooterSummarySetting {
+    label: string;
+    op: "sum" | "count";
+    field?: string;
+    where?: {
+        column: string;
+        op: "equals" | "notEquals" | "in" | "notIn";
+        value: string | number | boolean | (string | number | boolean)[];
+    };
+}
+export interface FooterSetting {
+    summary?: FooterSummarySetting[];
+}
+export interface TableViewSettings {
+    kanban?: KanbanSetting | null;
+    grouped?: GroupedSetting | null;
+    cards?: CardsSetting | null;
+    defaultDisplay?: TableDisplayId | null;
+    views?: ViewsSetting | null;
+    footer?: FooterSetting | null;
+}
+export interface ConfigureTableViewOpts extends MutationOpts {
+    block?: string;
+}
+export declare const ConfigureTableView: (page: string, settings: TableViewSettings, opts?: ConfigureTableViewOpts | undefined) => Promise<OpResult<{
+    path: BlockPath;
+}>>;

package/dist/table-view.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigureTableView = void 0;
+const interface_core_1 = require("@antelopejs/interface-core");
+exports.ConfigureTableView = (0, interface_core_1.InterfaceFunction)();
+//# sourceMappingURL=table-view.js.map

package/dist/table-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-view.js","sourceRoot":"","sources":["../src/table-view.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2IlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAMd,CAAC"}

package/docs/11.external-databases.md

@@ -134,8 +134,14 @@ A **fact** follows from the catalog with no judgement. A **default** is a judgem
 | R9 | anything else | a `purpose` question, nothing proposed |
 | L1, L2 | the label by name, then by order; titles from short comments, else from names | |
 | F1–F5 | columns no type reads and secrets left out; the first declaration; references the database declares, and references found whole, as relation columns | |
+| D1 | a `string` column the profile calls enum-like, of 2 to 10 categories that cover every non-null row | `display`: a badge, one toned item per value, by rows |
+| D2 | a `number` column whose name ends in `total`, `amount`, `price`, `cost`, `revenue` or `subtotal` | `display`: a price |
+| D3 | a relation column the database did not comment | `label`: the target's title in singular, "Customer" not "Customer id"; `MapResources` takes it too when a field leaves `label` out |
+| T1 | of the filterable badge columns of 2 to 6 values, the first named like `status`, `state`, `stage` or `type`, else the one with the fewest values | `tabs` on the resource |
 | W1 | every TableView | read-only |
 
+A badge's tones come from the value: `paid`, `active`, `done`, `completed`, `shipped`, `delivered` and `approved` are `success`; `pending`, `draft`, `processing`, `waiting` and `review` are `warning`; `failed`, `cancelled`, `canceled`, `refunded`, `rejected`, `error` and `blocked` are `error`; `new` and `open` are `info`. Other values take `primary`, `secondary`, `info` and `neutral` in turn. A price uses the DataType's default currency.
+
 Each field also carries the declarations its column `accepts`, and its profile's aggregates: traits, nulls, distinct values, range and categories. Never a row.
 
 Each resource also carries its `rows`, counted by the profile or estimated, when either is known.
@@ -175,6 +181,10 @@ const result = await MapResources({
 
 - **Names are the database's own.** `_id` is declared only where the relation has a key, and nothing creates or alters a table. A MongoDB collection's key is `_id` itself, which is declared once.
 - **Relation columns** point at a relation of the batch, or one the module mapped before, by its single-column key.
+- **A relation column's `label`** is written as sent. Left out, it keeps the label its controller holds if its relation was mapped before and held the column; otherwise it takes D3, the title of the relation it points at in singular ("Customer", not "Customer id"), as the target is titled by this call, by its page if it was mapped before, else by its name humanized. A column the database commented with a short first sentence takes that sentence instead (L2). A column that is not a relation column takes its name, humanized. A call that never sends a `label` therefore gets the analysis's labels on a first mapping and loses nothing on a remap.
+- **A column's `display`** is `{ kind: "badge", items: [{ value, label, tone }] }` on a `string` column, or `{ kind: "price" }` on a `number` one. A relation column takes none. Left out, the column keeps the display it has if its relation was mapped before, read back from its controller as `GetMapping` reads it; if the relation is new, it takes the display D1 or D2 proposes. `null` writes the column plain, over any display it had. A call that never sends a `display` therefore gets the proposal on a first mapping and loses nothing on a remap.
+- **Where a proposal comes from.** `MapResources` reads the profile of a new relation through the catalog connection at map time, since D1 needs it. When the profile cannot be read, it takes the proposal from the connection's last `AnalyseDatabase`; when there is none either, D2 still applies by the column's name, no column becomes a badge, and the result warns `display_not_proposed`. A display that does not suit the column's declaration, such as a badge on a column declared `number`, is dropped when it was kept or proposed, and refused only when sent.
+- **A TableView's `tabs`**: `tabs: { column }` writes "All" and a tab per value of that column's badge to the TableView, over the `tabs` it holds; the column must be filterable and drawn as a badge. Left out, a page already mapped keeps its tabs, and a new relation takes the tabs T1 proposes among its filterable badge columns: a column left unfilterable is not tabbed. `null` writes none: it adds no tabs to a new relation, and removes from a page already mapped the tabs a mapping wrote from a badge, as `display: null` removes the badge. Tabs edited by hand are kept.
 - **Mapping again** a relation already mapped rewrites it from the new choices. Its page is created, kept or removed as `tableView` says, and takes the new `title`. The module's relation columns pointing at it take its new `label`.
 - **The module's `package.json`** records the connection and the `excluded` tables with their reasons, so the next analysis does not propose those tables. Mapping one later removes it from the record:
 

package/docs/6.queries.md

@@ -228,7 +228,7 @@ await AddQuery("/dashboard", {
 | `op` | `"count" \| "sum" \| "avg" \| "min" \| "max"` | What to measure in each group. Defaults to `count`. |
 | `field` | `string` | The numeric field the measure reads. Required for every op but `count`. |
 | `groupBy` | `string` | The field the rows are grouped by. Required. |
-| `bucket` | `"day" \| "month" \| "quarter" \| "year"` | Groups a date field by period instead of by exact value. Only for a date field. |
+| `bucket` | `"day" \| "week" \| "month" \| "quarter" \| "year"` | Groups a date field by period instead of by exact value. A week runs Monday to Sunday. Only for a date field. |
 | `timezone` | `string` | IANA zone the period is computed in. |
 | `orderBy` | `"group" \| "measure"` | Order the points by their group (a timeline) or by what was measured (a ranking). Defaults to `group`. |
 | `direction` | `"asc" \| "desc"` | Defaults to `asc`. |

package/docs/8.results-and-errors.md

@@ -66,6 +66,7 @@ if (result.ok) {
 | `index_clamped` | An `AddBlock` or `MoveBlock` index fell outside the sibling range and was clamped into it. |
 | `datatype_fallback` | A field's DataType is not one the builder maps, so it is handled as a string. |
 | `data_not_dropped` | `DeleteResource` removed the source but could not clear the resource's table data. |
+| `display_not_proposed` | `MapResources` mapped a relation whose columns left `display` out, and neither a profile nor an analysis was there to propose a badge from, so its text columns were written plain. |
 
 ```typescript
 import { AddBlock } from "@antelopejs/interface-dms-builder";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms-builder",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "AntelopeJS interface for the DMS builder: create and edit pages, blocks, resources and queries in a DMS project from another module.",
   "keywords": [
     "antelopejs",