@antelopejs/interface-dms-builder 0.2.4 → 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,16 +58,19 @@ export interface ProposedResource {
     writable: Proposed<boolean>;
     label: Proposed<string | null>;
     title: Proposed<string>;
+    tabs?: Proposed<TabsChoice>;
     fields: ProposedField[];
     leftOut: ProposedLeftOut[];
     writes: ProposedWrites;
+    rows?: number;
+    profiledRows?: number;
 }
 export interface ProposedExclusion {
     relation: string;
     reason: string;
     rule: string;
 }
-export type OpenItemKind = "schemas" | "purpose" | "label" | "reference";
+export type OpenItemKind = "schemas" | "purpose" | "label" | "reference" | "field-type";
 export interface OpenItemOption {
     value: unknown;
     title: string;
@@ -79,6 +84,7 @@ export interface OpenItem {
     options: OpenItemOption[];
     proposed: unknown;
     resource?: ProposedResource;
+    open?: OpenItem[];
 }
 export interface ProposalDatabase {
     engine: string;

package/dist/analysis.js.map

@@ -1 +1 @@
-{"version":3,"file":"analysis.js","sourceRoot":"","sources":["../src/analysis.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AAoLlD,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/project.d.ts

@@ -10,6 +10,7 @@ export interface ModuleEntryInput {
     env?: Record<string, string>;
     importOverrides?: ImportOverrideInput[];
     exportPriority?: Record<string, number>;
+    disabledExports?: string[];
 }
 export interface AddModuleStep {
     op: "AddModule";
@@ -26,15 +27,28 @@ export interface CreateLocalModuleStep {
     id: string;
     path: string;
     entry?: ModuleEntryInput;
+    connection?: string;
 }
-export type ProjectConfigStep = AddModuleStep | ConfigureModuleStep | CreateLocalModuleStep;
+export interface RemoveModuleStep {
+    op: "RemoveModule";
+    id: string;
+}
+export interface RemoveConnectionStep {
+    op: "RemoveConnection";
+    interface: string;
+    id: string;
+}
+export type ProjectConfigStep = AddModuleStep | ConfigureModuleStep | CreateLocalModuleStep | RemoveModuleStep | RemoveConnectionStep;
 export interface ProjectConfigOpts {
     dryRun?: boolean;
 }
+export interface CreateLocalModuleOpts extends ProjectConfigOpts {
+    connection?: string;
+}
 export interface ProjectConfigResult {
     files: string[];
 }
 export declare const ConfigureProject: (steps: ProjectConfigStep[], opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
 export declare const AddModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
 export declare const ConfigureModule: (id: string, entry: ModuleEntryInput, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
-export declare const CreateLocalModule: (id: string, path: string, entry?: ModuleEntryInput | undefined, opts?: ProjectConfigOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;
+export declare const CreateLocalModule: (id: string, path: string, entry?: ModuleEntryInput | undefined, opts?: CreateLocalModuleOpts | undefined) => Promise<OpResult<ProjectConfigResult>>;

package/dist/project.js.map

@@ -1 +1 @@
-{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA8ElD,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAKd,CAAC;AAGO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAOd,CAAC"}
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../src/project.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA6GlD,QAAA,gBAAgB,GAC3B,IAAA,kCAAiB,GAKd,CAAC;AAGO,QAAA,SAAS,GACpB,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,eAAe,GAC1B,IAAA,kCAAiB,GAMd,CAAC;AAGO,QAAA,iBAAiB,GAC5B,IAAA,kCAAiB,GAOd,CAAC"}

package/dist/queries.js.map

@@ -1 +1 @@
-{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA0MlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAEd,CAAC;AAEO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,WAAW,GACtB,IAAA,kCAAiB,GAEd,CAAC"}
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":";;;AAAA,+DAA+D;AA2MlD,QAAA,kBAAkB,GAC7B,IAAA,kCAAiB,GAEd,CAAC;AAEO,QAAA,QAAQ,GACnB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,cAAc,GACzB,IAAA,kCAAiB,GAMd,CAAC;AAEO,QAAA,WAAW,GACtB,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";
+    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

@@ -2,9 +2,9 @@
 
 ## Overview
 
-A DMS project can show pages over a database it does not own: a client's PostgreSQL, read and written live through a postgres module in external mode. The builder takes such a database in four moves, each an operation:
+A DMS project can show pages over a database it does not own: a client's PostgreSQL, MongoDB or RethinkDB, read and written live through that engine's module (`@antelopejs/postgres`, `@antelopejs/mongodb`, `@antelopejs/rethinkdb`) in external mode. The builder takes such a database in four moves, each an operation:
 
-1. **Wire it** into `antelope.config.ts` with `ConfigureProject`: the provider module, a local module for its tables, and the builder's catalog connection.
+1. **Wire it** into `antelope.config.ts` with `ConfigureProject`: the provider module, a local module for its tables, the builder's catalog connection, and the DMS module's pin to the project's own database.
 2. **Analyse it** with `AnalyseDatabase`, which reads the catalog and proposes a mapping by fixed rules. It writes nothing.
 3. **Decide** the proposal: a person in the builder's *Database* workspace, or an assistant through these operations.
 4. **Map it** with `MapResources`, which writes table classes, controllers and TableView pages into the module bound to the database.
@@ -18,11 +18,23 @@ The builder reaches the database through `@antelopejs/interface-database-catalog
 | Step | Writes |
 | --- | --- |
 | `AddModule` | a module entry, refusing an id that exists |
-| `ConfigureModule` | merges config, `importOverrides` (pins and connection ids), `exportPriority` and env variable names into an entry |
-| `CreateLocalModule` | scaffolds a local module and adds its entry |
+| `ConfigureModule` | merges config, `importOverrides` (pins and connection ids), `exportPriority`, `disabledExports` and env variable names into an entry |
+| `CreateLocalModule` | scaffolds a local module and adds its entry; with `connection`, its record names that connection |
+| `RemoveModule` | removes an entry and the `envOverrides` entries supplying its config, refusing one another module still reads through; its files stay |
+| `RemoveConnection` | removes a named connection to an interface from every module's `importOverrides` |
 
 `env` takes variable names, never values: each is added to `envOverrides`, and to `.env.example` when the project has one.
 
+The provider's entry depends on its engine:
+
+| Engine | Package | `env` | `disabledExports` |
+| --- | --- | --- | --- |
+| PostgreSQL | `@antelopejs/postgres` | `url` | none |
+| MongoDB | `@antelopejs/mongodb` | `url` and `database` | `@antelopejs/interface-mongodb` |
+| RethinkDB | `@antelopejs/rethinkdb` | `url`, the database as its path | `@antelopejs/interface-rethinkdb` |
+
+`disabledExports` keeps core from ever offering the external instance's raw client, so a module that needs the DMS's own MongoDB or RethinkDB client never gets the client's database instead.
+
 ```typescript
 import { ConfigureProject } from "@antelopejs/interface-dms-builder";
 
@@ -36,20 +48,22 @@ const result = await ConfigureProject([
       source: { type: "package", package: "@antelopejs/postgres", version: "^0.2.0" },
       config: { mode: "external", statementTimeoutMs: 30000 },
       env: { url: "ERP_DATABASE_URL" },
+      exportPriority: { "@antelopejs/interface-database": -1 },
     },
   },
   {
     op: "CreateLocalModule",
     id: "erp-tables",
     path: "modules/erp-tables",
+    connection: "erp",
     entry: {
       importOverrides: [{ interface: "@antelopejs/interface-database", source: "postgres-erp" }],
     },
   },
   {
     op: "ConfigureModule",
-    id: "mongodb",
-    entry: { exportPriority: { "@antelopejs/interface-database": 1 } },
+    id: "dms",
+    entry: { importOverrides: [{ interface: "@antelopejs/interface-database", source: "mongodb" }] },
   },
   {
     op: "ConfigureModule",
@@ -59,8 +73,21 @@ const result = await ConfigureProject([
 ]);
 ```
 
+- The provider's `exportPriority` of `-1` keeps the project's own database the default for every module that does not pin `interface-database`.
+- The tables module pins `interface-database` to the provider, and uses the DMS. Core passes that pin on to the DMS, which every other module reaches with the default, so the DMS pins the project's own database to settle it. A DMS that already pins `interface-database` needs nothing more.
+
 The connection exists once the project restarts with the variable set.
 
+### Remove a Connection
+
+Removing a connection takes its catalog connections and its tables module out of the configuration, with `RemoveConnection` and `RemoveModule`. The tables module's folder is deleted with it. The database itself is untouched.
+
+The tables module is the one whose `dmsBuilder.database` record names the connection, which `CreateLocalModule` writes with `connection` (the single-step `CreateLocalModule` takes it in its options). Another module that reads through the provider is never removed or deleted.
+
+The provider goes too, with the variables that supply its configuration in `envOverrides`, `.env` and `.env.example`, only when it was added for this connection alone: its `exportPriority` for `@antelopejs/interface-database` is below the project's own database, and no module or connection the removal leaves names it. Otherwise it stays, since it may be the project's own database.
+
+A removal is all or nothing: the folders are moved aside and `.env` is edited first, and both are put back when the configuration cannot be written.
+
 ## Analyse a Database
 
 `AnalyseDatabase({ connection, module, schemas? })` starts a job and answers it at once: profiling a database takes a while. `GetAnalysis(id)` answers the job's `progress` while it runs, then its `proposal`, or its `error`.
@@ -100,18 +127,33 @@ A **fact** follows from the catalog with no judgement. A **default** is a judgem
 | R2 | no key | stats only: table class and model, no page |
 | R3 | no rows | excluded |
 | R4 | a framework's or a migration tool's table | excluded |
-| R5 | keyed by its two foreign keys | stats only |
+| R5 | keyed by its two references | stats only |
 | R6 | keyed, with rows and a label | TableView |
 | R7 | keyed, no label, referenced | TableView labelled by its key, and a `label` question |
 | R8 | keyed, no label, not referenced, with a time axis | stats only |
 | 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; declared foreign keys and references found whole as relation columns | |
+| 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.
 
-What the rules could not decide is in `open`, each item with its options and what the proposal holds meanwhile. A `purpose` item carries the `resource` it would map, should the answer be to map it.
+Each resource also carries its `rows`, counted by the profile or estimated, when either is known.
+
+What the rules could not decide is in `open`, each item with its options and what the proposal holds meanwhile:
+
+- A `label` item offers every column a field reads, the key among them.
+- A `reference` item offers a plain column, the target its values were found in, and every TableView whose single-column key accepts the column.
+- A `purpose` item carries the `resource` it would map, should the answer be to map it, and in its own `open` the questions that resource leaves: they are asked only once the answer maps it.
+- A `field-type` item asks which declaration reads a field of several native types.
+
+A document database declares no field types, so its catalog reads them from a sample. When no type covers enough of a field's values (`int 60% | string 40%`), the field is left out and a `field-type` item asks which declaration reads it: its options are a declaration per type seen, and leaving it out. The `_id` of a collection without a key is never declared, so it is left out and asks nothing. `MapResources` accepts the declaration it answers. MongoDB and RethinkDB declare no references either, so F5 finds them all.
 
 ## Map Relations
 
@@ -133,14 +175,27 @@ const result = await MapResources({
       fields: [{ column: "name", searchable: true }, { column: "segment", filterable: true }],
     },
   ],
-  excluded: [{ relation: "erp.audit_log", reason: "a log" }],
+  excluded: [{ relation: "erp.schema_migrations", reason: "a framework's or a migration tool's table" }],
 });
 ```
 
-- **Names are the database's own.** `_id` is declared only where the relation has a key, and nothing creates or alters a table.
+- **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.
-- **Mapping again** a relation already mapped rewrites it from the new choices. Its page is created, kept or removed as `tableView` says.
-- **`excluded`** is recorded in the module's `package.json`, so the next analysis does not propose those relations. Mapping one later removes it from the record.
+- **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:
+
+  ```json
+  "dmsBuilder": {
+    "database": {
+      "connection": "erp",
+      "excludedTables": { "erp.schema_migrations": "a framework's or a migration tool's table" }
+    }
+  }
+  ```
 - **In a mapped module**, `CreateResource` and `AddField` are refused, since its tables are the database's. `DeleteResource` keeps the client's rows and warns `data_kept`.
 
 ## Next Steps

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

@@ -39,7 +39,7 @@ Reads that use the envelope — `GetPageStructure`, `GetResourceStructure` — r
 | --- | --- | --- |
 | `path` | `string` | The file's absolute path. |
 | `kind` | `"create" \| "modify" \| "delete"` | What happened to the file. |
-| `diff` | `string` | A textual diff of the change. Empty for a deletion. |
+| `diff` | `string` | The change as unified diff hunks (`@@ -a,b +c,d @@`, then lines prefixed with a space, `-` or `+`), with no file headers. Empty for a deletion. |
 
 A single operation usually touches more than one file — creating a page writes the page file and rewrites the barrel that exports it; creating a resource writes three files and rewrites a barrel.
 
@@ -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/docs/tsconfig.json

@@ -4,7 +4,11 @@
     "rootDir": "..",
     "composite": false,
     "incremental": false,
-    "noEmit": true
+    "noEmit": true,
+    "paths": {
+      "@antelopejs/interface-dms-builder": ["../src/index.ts"],
+      "@antelopejs/interface-dms-builder/*": ["../src/*"]
+    }
   },
   "include": ["../src/**/*.ts", "**/*.ts"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/interface-dms-builder",
-  "version": "0.2.4",
+  "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",