@dforge-core/metadata 0.0.49 → 0.0.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/metadata",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "description": "Canonical dForge authoring registries — field types, base datatypes, column types, traits, data-view kinds and chart types — with derivation helpers. Runtime-dependency-free; the single source of truth shared by editors, the web app and the CLI.",
   "license": "MIT",
   "author": "dForge",

package/schemas/data_views.schema.json

@@ -14,7 +14,7 @@
 			"properties": {
 				"viewType": {
 					"type": "string",
-					"enum": ["grid", "list", "kanban", "calendar", "gallery", "tree-grid", "diagram", "library", "matrix"],
+					"enum": ["grid", "list", "checklist", "kanban", "calendar", "gallery", "tree-grid", "diagram", "library", "matrix"],
 					"default": "grid",
 					"description": "View display type. Optional — omitted or unknown values fall back to 'grid' at runtime."
 				},
@@ -118,6 +118,18 @@
 					}
 				}
 			},
+			"checklist": {
+				"if": {
+					"properties": { "viewType": { "const": "checklist" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/checklistViewConfig" }
+					},
+					"required": ["viewConfig"]
+				}
+			},
 			"diagram": {
 				"if": {
 					"properties": { "viewType": { "const": "diagram" } },
@@ -249,6 +261,47 @@
 			},
 			"additionalProperties": false
 		},
+		"checklistViewConfig": {
+			"type": "object",
+			"required": ["doneField"],
+			"properties": {
+				"titleField": {
+					"type": "string",
+					"description": "Column code of the row title; defaults to the record's display name. Also the column an inline add row types into"
+				},
+				"doneField": {
+					"type": "string",
+					"description": "Column the row's done circle reads and writes: a bool column, or a dropdown column with doneValue"
+				},
+				"doneValue": {
+					"type": "string",
+					"description": "Option value of a dropdown doneField that means done (ignored for a bool doneField)"
+				},
+				"undoneValue": {
+					"type": "string",
+					"description": "Option value a dropdown doneField is set back to when the circle is cleared (ignored for a bool doneField)"
+				},
+				"groupByField": {
+					"type": "string",
+					"description": "Dropdown, reference or user column the rows are grouped by"
+				},
+				"groupByOptions": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Columns the user may regroup by; must include groupByField"
+				},
+				"collapsedGroups": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Option values of groupByField whose groups start collapsed"
+				},
+				"inlineAdd": {
+					"type": "boolean",
+					"description": "Show an add row in each group (at the top when ungrouped)"
+				}
+			},
+			"additionalProperties": false
+		},
 		"listLevelConfig": {
 			"type": "object",
 			"required": ["entityCode", "foreignKey"],

package/schemas/deps.schema.json

@@ -18,7 +18,7 @@
 		},
 		"entities": {
 			"type": "object",
-			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity, or when 'functions' imports at least one function.",
+			"description": "Consumed provider entities, keyed by entity code (e.g. 'party'). At least one, except against a system module (admin, metadata, workspace, sys-billing), where {} declares a pure platform-version gate for a feature that introduced no entity, or when 'functions' imports at least one function or 'snippets' lists at least one print snippet.",
 			"additionalProperties": { "$ref": "#/definitions/entityContract" }
 		},
 		"functions": {
@@ -27,13 +27,21 @@
 			"items": { "type": "string", "pattern": "^[A-Za-z_$][A-Za-z0-9_$]*$" },
 			"uniqueItems": true,
 			"minItems": 1
+		},
+		"snippets": {
+			"type": "array",
+			"description": "The provider's print snippets (type 'snippet' in its ui/print_templates.json) the consumer's print templates include as {% include '<provider>.<snippet>' %}. Every such include must be listed, and install checks the installed provider ships each. See docs/modules/dependency-contracts.md.",
+			"items": { "type": "string", "pattern": "^[^.\\s]+$" },
+			"uniqueItems": true,
+			"minItems": 1
 		}
 	},
 	"if": {
 		"not": {
 			"anyOf": [
 				{ "properties": { "module": { "enum": ["admin", "metadata", "workspace", "sys-billing"] } }, "required": ["module"] },
-				{ "required": ["functions"] }
+				{ "required": ["functions"] },
+				{ "required": ["snippets"] }
 			]
 		}
 	},

package/schemas/entity.schema.json

@@ -602,6 +602,25 @@
 							"type": "string",
 							"description": "Format rule for this column, as an ECMAScript regex source. Overrides the field type's own pattern (field_type.def_params.pattern, which is what makes email/phone/url reject a malformed value). Enforced in the browser and again on data.insert / data.update, so keep to constructs both engines read alike: [0-9] and \\d are the same there, \\s is normalized to JavaScript's set, and a pattern that will not compile is skipped by both rather than enforced by one."
 						},
+						"fieldOptions": {
+							"type": "object",
+							"description": "Per-record rules for this field, each a formula over the record evaluated in the browser wherever the value renders (grid, card, list, checklist, kanban). $value stands for this column, so one rule (e.g. on a column domain) fits every column using it: IF($value < 0, 'danger', ''). Install refuses a rule that does not parse or calls an unknown function. Not-equal is != (there is no <>).",
+							"properties": {
+								"foreColor": {
+									"type": "string",
+									"description": "Formula returning the text colour, or '' for none. A theme name (danger, warning, success, info, accent, muted) follows light/dark mode and the UI style; any other value is used as CSS. E.g. IF([due_date] < TODAY() AND [status] != 'done', 'danger', '')"
+								},
+								"backColor": {
+									"type": "string",
+									"description": "Formula returning the background colour, or '' for none. A theme name gives that colour's subtle tint."
+								},
+								"canEdit": {
+									"type": "string",
+									"description": "Formula; false makes the field read-only on that record (a UI hint — the server enforces its own locks)."
+								}
+							},
+							"additionalProperties": false
+						},
 						"patternFlags": {
 							"type": "string",
 							"description": "Flags for 'pattern', as a JavaScript regex literal would carry them; 'i' and 'm' are the two honoured, each at most once — the RegExp constructor rejects a repeated flag, and a rule the browser cannot compile is skipped there and would then be enforced by the API alone. JavaScript has no inline (?i), so case-insensitivity has to be stated here.",

package/schemas/test_scenario.schema.json

@@ -0,0 +1,144 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "dForge Module Test Scenarios",
+	"description": "Scenarios for a dForge module (tests/*.test.json), run by `dforge-cli module test`. Covers the v0 subset described in docs/modules/module-tests.md: given / do / expect over the API as the signed-in user.",
+	"type": "object",
+	"required": ["describe", "tests"],
+	"additionalProperties": false,
+	"properties": {
+		"$comment": { "type": "string" },
+		"describe": { "type": "string", "description": "Name of the suite." },
+		"fixture": { "type": "string", "description": "Named fixture from tests/test.json. Not read by v0: the workspace must already hold the data the scenarios rely on." },
+		"isolation": { "enum": ["rollback", "clone"], "description": "Not used by v0: tests commit and leave their records behind." },
+		"tests": { "type": "array", "items": { "$ref": "#/$defs/test" } }
+	},
+	"$defs": {
+		"test": {
+			"type": "object",
+			"required": ["name"],
+			"additionalProperties": false,
+			"properties": {
+				"$comment": { "type": "string" },
+				"name": { "type": "string" },
+				"as": { "const": "admin", "description": "v0 runs as the signed-in user; other fixture users are not supported yet." },
+				"given": { "type": "array", "items": { "$ref": "#/$defs/givenBlock" } },
+				"do": { "type": "array", "items": { "$ref": "#/$defs/step" } },
+				"expect": { "type": "array", "items": { "$ref": "#/$defs/expectation" } }
+			}
+		},
+		"givenBlock": {
+			"type": "object",
+			"required": ["entityCode", "records"],
+			"additionalProperties": false,
+			"properties": {
+				"entityCode": { "type": "string" },
+				"records": { "type": "array", "items": { "$ref": "#/$defs/values" } }
+			}
+		},
+		"values": {
+			"type": "object",
+			"description": "Column values. A string \"$name.column\" reads a column of a record named earlier with \"$as\". \"$as\" names the record being created.",
+			"properties": { "$as": { "type": "string" } }
+		},
+		"name": { "type": "string", "pattern": "^\\$[A-Za-z_][A-Za-z0-9_]*$" },
+		"recordRef": {
+			"description": "\"$name\" (a record named with \"$as\"), or { \"<entity>\": { \"<column>\": <value>, … } } matching exactly one record.",
+			"oneOf": [
+				{ "$ref": "#/$defs/name" },
+				{
+					"type": "object",
+					"minProperties": 1,
+					"maxProperties": 1,
+					"additionalProperties": { "type": "object", "minProperties": 1 }
+				}
+			]
+		},
+		"step": {
+			"oneOf": [
+				{
+					"type": "object",
+					"required": ["insert"],
+					"additionalProperties": false,
+					"properties": {
+						"insert": { "type": "string", "description": "Entity code." },
+						"values": { "$ref": "#/$defs/values" },
+						"$as": { "type": "string" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["update", "values"],
+					"additionalProperties": false,
+					"properties": {
+						"update": { "$ref": "#/$defs/recordRef" },
+						"values": { "$ref": "#/$defs/values" }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["delete"],
+					"additionalProperties": false,
+					"properties": { "delete": { "$ref": "#/$defs/recordRef" } }
+				},
+				{
+					"type": "object",
+					"required": ["action"],
+					"oneOf": [{ "required": ["record"] }, { "required": ["records"] }],
+					"additionalProperties": false,
+					"properties": {
+						"action": { "type": "string", "description": "action_cd." },
+						"record": { "$ref": "#/$defs/recordRef" },
+						"records": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/recordRef" } },
+						"params": { "type": "object" }
+					}
+				}
+			]
+		},
+		"expectation": {
+			"oneOf": [
+				{
+					"type": "object",
+					"required": ["record", "equals"],
+					"additionalProperties": false,
+					"properties": {
+						"record": { "$ref": "#/$defs/recordRef" },
+						"equals": { "type": "object", "minProperties": 1 },
+						"precision": { "type": "integer", "minimum": 0, "description": "Decimals numbers are compared at." }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["count", "equals"],
+					"additionalProperties": false,
+					"properties": {
+						"count": { "type": "string", "description": "Entity code." },
+						"where": { "type": "object", "description": "Canonical { c, o, v } / { g, i } filter." },
+						"equals": { "type": "integer", "minimum": 0 }
+					}
+				},
+				{
+					"type": "object",
+					"required": ["error"],
+					"additionalProperties": false,
+					"properties": {
+						"error": {
+							"type": "object",
+							"minProperties": 1,
+							"additionalProperties": false,
+							"properties": {
+								"code": { "type": "string" },
+								"contains": { "type": "string" }
+							}
+						}
+					}
+				},
+				{
+					"type": "object",
+					"required": ["refused"],
+					"additionalProperties": false,
+					"properties": { "refused": { "const": "canExecute" } }
+				}
+			]
+		}
+	}
+}

package/src/data-views.ts

@@ -12,6 +12,7 @@ export type { NamedKind };
 export type ViewType =
 	| "grid"
 	| "list"
+	| "checklist"
 	| "kanban"
 	| "calendar"
 	| "gallery"
@@ -24,6 +25,7 @@ export type ViewType =
 export const dataViewKinds: readonly NamedKind[] = [
 	{ cd: "grid", name: "Grid" },
 	{ cd: "list", name: "List" },
+	{ cd: "checklist", name: "Checklist" },
 	{ cd: "kanban", name: "Kanban" },
 	{ cd: "calendar", name: "Calendar" },
 	{ cd: "gallery", name: "Gallery" },
@@ -121,6 +123,27 @@ export interface ListViewConfig {
 	inlineAdd?: boolean;
 }
 
+export interface ChecklistViewConfig {
+	/** Column of the row title; defaults to the record's display name. Also
+	 *  the column an inline add row types into. */
+	titleField?: string;
+	/** Column the row's done circle reads and writes: a bool column, or a
+	 *  dropdown column together with `doneValue`. */
+	doneField: string;
+	/** Option value of a dropdown `doneField` that means done. */
+	doneValue?: string;
+	/** Option value a dropdown `doneField` is set back to when the circle is cleared. */
+	undoneValue?: string;
+	/** Dropdown, reference or user column the rows are grouped by. */
+	groupByField?: string;
+	/** Columns the user may regroup by; includes `groupByField`. */
+	groupByOptions?: string[];
+	/** Option values of `groupByField` whose groups start collapsed. */
+	collapsedGroups?: string[];
+	/** Show an add row in each group (at the top when ungrouped). */
+	inlineAdd?: boolean;
+}
+
 export interface DiagramViewConfig {
 	/** Column to group diagram nodes by. */
 	groupByField?: string;
@@ -149,6 +172,7 @@ export interface DataViewDef {
 		| CalendarViewConfig
 		| TreeGridViewConfig
 		| ListViewConfig
+		| ChecklistViewConfig
 		| DiagramViewConfig
 		| Record<string, unknown>;
 }

package/src/deps.ts

@@ -85,4 +85,14 @@ export interface DepsFile {
 	version: string;
 	/** Consumed provider entities, keyed by entity code. */
 	entities: Record<string, DepEntity>;
+	/**
+	 * The provider's DSL library functions the consumer calls as
+	 * `<provider code with '-' replaced by '_'>.<name>(…)`.
+	 */
+	functions?: string[];
+	/**
+	 * The provider's print snippets the consumer's print templates include as
+	 * `{% include '<provider>.<snippet>' %}`. Every such include must be listed.
+	 */
+	snippets?: string[];
 }

package/src/dsl/builtins.ts

@@ -149,9 +149,9 @@ export const BUILTINS: Builtin[] = [
 	},
 	{
 		name: "sendEmail",
-		signature: "sendEmail(to, subjectOrTemplate, dataOrBody?, attachments?)",
+		signature: "sendEmail(to, subjectOrTemplate, dataOrBody?, attachments?, options?)",
 		returns: "void",
-		doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>…</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code — so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. The optional **fourth** argument attaches files: a `printPdf()`, `attachText()` or `attachBase64()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference in the DSL). A `printPdf()` file can be attached only by the user who generated it (or a workspace admin) and not in a scheduled job; a file built with `attachText()` / `attachBase64()` has no owner and works everywhere, a scheduled job included. At most 5 files and 10 MB in all per email (`Email:MaxAttachments`, `Email:MaxAttachmentBytes`). A file the sender may not attach fails the action.",
+		doc: "Queue an outbound email. Three arguments, and the **second** picks the mode: `sendEmail(to, 'order.shipped', { ref: [code] })` sends a template, `sendEmail(to, 'Your order shipped', '<p>…</p>')` sends raw HTML. A second argument with no spaces that contains `.` or `_` is read as a template code — so a raw subject like `'Shipped.'` silently becomes one; give a raw subject spaces. The optional **fourth** argument attaches files: a `printPdf()`, `attachText()` or `attachBase64()` result, or an array of them (`[a, b]`; pass a single file as itself, because a one-name `[a]` reads as a field reference in the DSL). A `printPdf()` file can be attached only by the user who generated it (or a workspace admin) and not in a scheduled job; a file built with `attachText()` / `attachBase64()` has no owner and works everywhere, a scheduled job included. At most 5 files and 10 MB in all per email (`Email:MaxAttachments`, `Email:MaxAttachmentBytes`). A file the sender may not attach fails the action. The optional **fifth** argument sets threading headers so a reply finds this mail: `{ messageId, inReplyTo, references, replyTo }` (ids with angle brackets, `references` an array; pass `null` as the fourth argument when there are no files). Every key is optional; an unknown key, a malformed id (strictly `<word.word@word.word>`) or address, or a line break fails the action by name.",
 	},
 
 	// External calls
@@ -161,6 +161,12 @@ export const BUILTINS: Builtin[] = [
 		returns: "string",
 		doc: "HTTP request to an external API; returns the body as a string. Max 10 calls per script, 120s timeout, 5MB response.",
 	},
+	{
+		name: "fetchMail",
+		signature: "fetchMail(options)",
+		returns: "object",
+		doc: "Read new mail from one IMAP folder, read-only: nothing is marked seen, moved or deleted, so the mailbox stays the user's and the cursor you store says what was imported. Options: `host`, `username`, `secret` (the code of a module secret — the password is never written in a script), `port` (993; 143 with `security: 'starttls'`), `security` (`'ssl'` by default or `'starttls'`), `auth` (`'password'`, the only one for now), `folder` (`'INBOX'`), the cursor `uidValidity` + `afterUid` from the previous result, `since` (a date, for the first call), `limit` (messages). Returns `{ uidValidity, lastUid, more, reset, messages }`: store `uidValidity` and `lastUid` for the next call, call again while `more` is true, and treat `reset: true` as a mailbox renumbered by the server (the cursor was dropped and the folder read again). Each message has `uid`, `messageId`, `inReplyTo`, `references`, `date` (ISO 8601), `from`/`replyTo` (`{ address, name }`), `to`, `cc`, `envelopeTo`, `subject`, `text`, `html` (sanitized; remote images parked in `data-remote-src`), `autoReply`, `attachments` and `droppedAttachments`. Each attachment is a staged file `{ $tempId, fileName, mimeType, size, checksum, contentId, inline }`: pass it as the value of a `file` column in `insert()` / `update()` to keep it (an unused one expires with the temp sweep). Failures throw with the code first: `AUTH_FAILED`, `CONNECT_FAILED`, `TLS_FAILED`, `FOLDER_NOT_FOUND`; a host on a private network needs `Dsl:Limits:AllowedHosts`. Meant for scheduled jobs and async actions: up to 3 calls per run, 25 messages and 40 s per call (`Dsl:Limits:MaxMailFetchesPerExecution` / `MaxMailMessagesPerFetch` / `MailFetchBudgetSeconds`).",
+	},
 	{
 		name: "callService",
 		signature: "callService(name, args)",

package/src/index.ts

@@ -95,6 +95,7 @@ export {
 	type TreeGridViewConfig,
 	type ListViewConfig,
 	type ListLevelConfig,
+	type ChecklistViewConfig,
 	type DiagramViewConfig,
 } from "./data-views";