@dforge-core/metadata 0.0.46 → 0.0.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dforge-core/metadata",
-  "version": "0.0.46",
+  "version": "0.0.48",
   "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

@@ -52,6 +52,7 @@
 			},
 			"additionalProperties": false,
 			"allOf": [
+				{ "$ref": "#/$defs/rules/grid" },
 				{ "$ref": "#/$defs/rules/kanban" },
 				{ "$ref": "#/$defs/rules/calendar" },
 				{ "$ref": "#/$defs/rules/tree-grid" },
@@ -62,6 +63,17 @@
 		},
 
 		"rules": {
+			"grid": {
+				"if": {
+					"properties": { "viewType": { "const": "grid" } },
+					"required": ["viewType"]
+				},
+				"then": {
+					"properties": {
+						"viewConfig": { "$ref": "#/$defs/gridViewConfig" }
+					}
+				}
+			},
 			"kanban": {
 				"if": {
 					"properties": { "viewType": { "const": "kanban" } },
@@ -131,6 +143,26 @@
 			}
 		},
 
+		"gridViewConfig": {
+			"type": "object",
+			"properties": {
+				"groupByField": {
+					"type": "string",
+					"description": "Dropdown, reference or user column the rows are grouped by under header rows"
+				},
+				"groupByOptions": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Columns the Group by menu offers; must include groupByField"
+				},
+				"collapsedGroups": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Option values of groupByField whose groups start collapsed"
+				}
+			},
+			"additionalProperties": false
+		},
 		"kanbanViewConfig": {
 			"type": "object",
 			"required": ["groupByField"],
@@ -195,6 +227,24 @@
 					"type": "array",
 					"items": { "$ref": "#/$defs/listLevelConfig" },
 					"description": "Hierarchical child levels for expandable list rows"
+				},
+				"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

package/schemas/entity.schema.json

@@ -345,11 +345,90 @@
 			},
 			"additionalProperties": false
 		},
+		"queryColumnParams": {
+			"type": "object",
+			"description": "Binding of a query column (columnType Q): a read-only list of rows for the record, with no physical column. It reads either a balance register as of the record's date (register, asOf, dimensions) or a query written in the column and filled from the record (entity, query, params). Shown on the card and read by print forms, with the reader's rights.",
+			"oneOf": [
+				{
+					"required": ["register", "asOf"],
+					"properties": {
+						"register": {
+							"type": "string",
+							"description": "A balance register of this module or of one it depends on, as 'module_cd.register_cd'. It needs a journal that stamps the date and the direction of each movement.",
+							"examples": ["wms-registry.stock"]
+						},
+						"asOf": {
+							"type": "string",
+							"description": "Date (or timestamp) column of this entity the balance is taken on. The day itself is included."
+						},
+						"viz": {
+							"type": "object",
+							"description": "How the card shows the rows: a report visualization by its type (table, a chart, pivot...) and its config as that visualization takes it. Unset: a table. A print form reads the rows as a table whatever this says.",
+							"required": ["type"],
+							"properties": {
+								"type": { "type": "string" },
+								"config": { "type": "object" }
+							},
+							"additionalProperties": false
+						},
+						"dimensions": {
+							"type": "object",
+							"description": "Register dimension → column of this entity that narrows it. A dimension left out is not narrowed, so its tuples all come back. A narrowing column that is empty on the record leaves the list empty.",
+							"additionalProperties": { "type": "string" },
+							"examples": [{ "warehouse_id": "warehouse_id" }]
+						}
+					},
+					"additionalProperties": false
+				},
+				{
+					"required": ["entity", "query"],
+					"properties": {
+						"entity": {
+							"type": "string",
+							"description": "The entity the query reads, as 'module_cd.entity_cd' (a bare code is this module's own). Of this module or of one it depends on.",
+							"examples": ["retail.goods_line"]
+						},
+						"query": {
+							"type": "object",
+							"description": "The query itself, in the shape query.run takes: columns (a plain name, or { c, agg } with agg group / sum / count / avg / min / max — grouped if any column has one), filter and sort. A filter value written '@name' is filled from the record through 'params'. An aggregate is read under its column's code. Written here and not saved elsewhere, so no edit of a shared query can change the form.",
+							"properties": {
+								"columns": { "type": "array" },
+								"filter": {},
+								"sort": { "type": "array" }
+							},
+							"additionalProperties": false
+						},
+						"viz": {
+							"type": "object",
+							"description": "How the card shows the rows: a report visualization by its type (table, a chart, pivot...) and its config as that visualization takes it. Unset: a table. A print form reads the rows as a table whatever this says.",
+							"required": ["type"],
+							"properties": {
+								"type": { "type": "string" },
+								"config": { "type": "object" }
+							},
+							"additionalProperties": false
+						},
+						"params": {
+							"type": "object",
+							"description": "Query parameter (the name after '@' in a filter value) → stored column of this entity that fills it. Every @param of the query is listed, and only those. A column that is empty on the record leaves the list empty rather than widening the query.",
+							"additionalProperties": { "type": "string" },
+							"examples": [{ "doc": "document_id" }]
+						}
+					},
+					"additionalProperties": false
+				}
+			]
+		},
 		"registryColumnParams": {
 			"type": "object",
 			"description": "params of an accumulation (A) or ledger (L) registry column. The lock lists are what BOTH generated guards freeze — the posted-document guard while the document is posted, the period guard while its period is closed — and they are required: install refuses a registry column that omits or empties them. The header's periodDateField and the state column are watched in addition, whatever the list says.",
 			"required": ["lockedFields"],
+			"if": { "required": ["editorMayPost"], "properties": { "editorMayPost": { "const": true } } },
+			"then": { "not": { "anyOf": [ { "required": ["postAction"] }, { "required": ["unpostAction"] } ] } },
 			"properties": {
+				"postAction": { "type": "string", "minLength": 1, "description": "Code of the action (available for this entity) that posts the document. A direct data.insert / data.update that turns the state flag on needs 'E' on it, as the button does, so \"may edit\" and \"may post\" stay two rights through the API too. An action's own writes are not re-checked. Pack refuses a name that no action declared for this entity carries. Unset: the transition needs only Insert/Update." },
+				"unpostAction": { "type": "string", "minLength": 1, "description": "Code of the action that unposts the document; the same gate for a direct write that turns the state flag off." },
+				"editorMayPost": { "type": "boolean", "description": "Declares that Insert/Update on the document includes posting it: no separate right to post is intended, so no postAction / unpostAction is named. Changes nothing at run time; it silences the pack warning for a column that names no posting action. Not together with postAction / unpostAction." },
 				"lockedFields": {
 					"type": "array",
 					"minItems": 1,
@@ -408,6 +487,10 @@
 				{
 					"if": { "required": ["columnType"], "properties": { "columnType": { "enum": ["A", "L"] } } },
 					"then": { "required": ["params"], "properties": { "params": { "$ref": "#/$defs/registryColumnParams" } } }
+				},
+				{
+					"if": { "required": ["columnType"], "properties": { "columnType": { "const": "Q" } } },
+					"then": { "required": ["params"], "properties": { "params": { "$ref": "#/$defs/queryColumnParams" } } }
 				}
 			],
 			"properties": {
@@ -422,8 +505,8 @@
 				},
 				"columnType": {
 					"type": "string",
-					"enum": ["D", "R", "S", "F", "A", "L", "G"],
-					"description": "Column type: D=Data (physical column), R=Reference (N:1 lookup), S=Set (1:N collection), F=Formula (virtual calculated), G=Generated/Computed (physical, auto-maintained), A=Accumulation registry, L=Ledger registry"
+					"enum": ["D", "R", "S", "F", "A", "L", "G", "Q"],
+					"description": "Column type: D=Data (physical column), R=Reference (N:1 lookup), S=Set (1:N collection), F=Formula (virtual calculated), G=Generated/Computed (physical, auto-maintained), A=Accumulation registry, L=Ledger registry, Q=Query (virtual list of rows read from a register, bound to this record)"
 				},
 				"fieldTypeCd": {
 					"type": "string",

package/schemas/jobs.schema.json

@@ -52,7 +52,7 @@
 					},
 					"idempotencyKey": {
 						"type": "string",
-						"description": "Template like '{job_cd}:{run.month}'. Resolved at fire time. A successful run with the same key blocks re-dispatch (Phase 3 enforcement)."
+						"description": "Reserved; not enforced yet. Stored but never read by the scheduler, so it does not block re-dispatch. Only the scheduled slot (job, scheduled_at) is deduplicated; guard business-level 'once per period' inside the action."
 					},
 					"class": {
 						"type": "string",

package/schemas/print_templates.schema.json

@@ -55,6 +55,11 @@
 							"left":   { "type": "string" }
 						},
 						"additionalProperties": false
+					},
+					"culture": {
+						"type": "string",
+						"description": "The form's own culture, e.g. 'uk-UA': format_number, format_currency, format_date, _fmt and Yes/No print in it whoever prints the form. Omitted: the user's culture. An unknown culture is refused at pack and install.",
+						"examples": ["uk-UA", "de-CH"]
 					}
 				},
 				"additionalProperties": false

package/src/column-types.ts

@@ -1,4 +1,4 @@
-// Column-type registry — the seven column kinds a field can have. Letters match
+// Column-type registry — the eight column kinds a field can have. Letters match
 // the `column.column_type` values and entity.schema.json. The `name` /
 // `description` here drive the friendly "what kind of field is this?" picker.
 
@@ -11,6 +11,7 @@ export const columnTypes: readonly ColumnTypeDef[] = [
 	{ cd: "F", name: "Formula", description: "A virtual value calculated from a formula expression." },
 	{ cd: "G", name: "Generated", description: "A physical column auto-maintained by the database (aggregate or expression)." },
 	{ cd: "A", name: "Accumulation register", description: "Posts this document into a balance entity (single direction)." },
+	{ cd: "Q", name: "Query rows", description: "A read-only list of rows this record reads: a register's balance as of its date, or a query filled from its columns." },
 	{ cd: "L", name: "Ledger register", description: "Posts document lines into movements + balances (double entry)." },
 ] as const;
 

package/src/data-views.ts

@@ -79,6 +79,15 @@ export interface CalendarViewConfig {
 	colorField?: string;
 }
 
+export interface GridViewConfig {
+	/** Dropdown, reference or user column the rows are grouped by under header rows. */
+	groupByField?: string;
+	/** Columns the Group by menu offers; must include `groupByField`. */
+	groupByOptions?: string[];
+	/** Option values of `groupByField` whose groups start collapsed. */
+	collapsedGroups?: string[];
+}
+
 export interface TreeGridViewConfig {
 	/** Self-referencing FK column (parent record). */
 	parentField: string;
@@ -102,6 +111,14 @@ export interface ListViewConfig {
 	subtitleField?: string;
 	/** Hierarchical child levels for expandable list rows. */
 	levels?: ListLevelConfig[];
+	/** 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 {
@@ -127,6 +144,7 @@ export interface DataViewDef {
 	order?: unknown;
 	/** View-type-specific configuration. */
 	viewConfig?:
+		| GridViewConfig
 		| KanbanViewConfig
 		| CalendarViewConfig
 		| TreeGridViewConfig

package/src/index.ts

@@ -75,6 +75,10 @@ export type {
 	AuditHistoryLevel,
 } from "./entity";
 
+// Query column (`columnType: "Q"`) params and where they name the record's columns.
+export { QUERY_COLUMN_RECORD_SLOTS, isQueryColumnRecordSlot } from "./query-column";
+export type { QueryColumnParams, RegisterQueryColumnParams, EntityQueryColumnParams, QueryColumnViz } from "./query-column";
+
 // Entity introspection helpers (primary keys, identity keys, reference links).
 export { getLinks, getIdentityKeys, getPrimaryKeys } from "./entity-meta";
 
@@ -85,6 +89,7 @@ export {
 	type DataSource,
 	type ViewColumn,
 	type ViewType,
+	type GridViewConfig,
 	type KanbanViewConfig,
 	type CalendarViewConfig,
 	type TreeGridViewConfig,

package/src/jobs.ts

@@ -15,7 +15,7 @@ export interface JobDef {
 	timeout: number;
 	/** Max parallel runs (1–5; default 1). */
 	concurrency?: number;
-	/** Idempotency key template, e.g. '{job_cd}:{run.month}'. */
+	/** Reserved, not enforced: stored but never read by the scheduler. */
 	idempotencyKey?: string;
 	/** Routing class ('long_running' required for any timeout > 300s). */
 	class?: "standard" | "long_running";

package/src/print-templates.ts

@@ -14,6 +14,8 @@ export interface PrintPageSettings {
 	size?: "A4" | "letter" | "legal";
 	orientation?: "portrait" | "landscape";
 	margins?: PrintMargins;
+	/** The form's own culture ('uk-UA') for its numbers and dates, whoever prints it. */
+	culture?: string;
 }
 
 /**

package/src/query-column.ts

@@ -0,0 +1,49 @@
+// A query column (`columnType: "Q"`): a read-only list of rows a record reads, with no
+// physical column. `params` binds it to one source — a balance register as of the
+// record's date, or a query written in the column and filled from the record.
+
+/** How the card shows the rows: a report visualization by its type and config. Unset: a table. */
+export interface QueryColumnViz {
+	type: string;
+	config?: Record<string, unknown>;
+}
+
+/** The balance of a register as of the record's date, narrowed by the record's own columns. */
+export interface RegisterQueryColumnParams {
+	/** `module_cd.register_cd` of a balance register. */
+	register: string;
+	/** Date column of the record the balance is taken on. */
+	asOf: string;
+	/** Register dimension → column of the record that narrows it. */
+	dimensions?: Record<string, string>;
+	viz?: QueryColumnViz;
+}
+
+/** A query written in the column, its `@name` filter values filled from the record. */
+export interface EntityQueryColumnParams {
+	/** `module_cd.entity_cd` the query reads. */
+	entity: string;
+	/** The query, in the shape `query.run` takes. */
+	query: { columns?: unknown[]; filter?: unknown; sort?: unknown[] };
+	/** Query parameter name → column of the record that fills it. */
+	params?: Record<string, string>;
+	viz?: QueryColumnViz;
+}
+
+export type QueryColumnParams = RegisterQueryColumnParams | EntityQueryColumnParams;
+
+/**
+ * The places in a Q column's `params` that name a column of the entity the column is on, so an
+ * editor can offer that entity's columns there. `*` matches any key.
+ */
+export const QUERY_COLUMN_RECORD_SLOTS: readonly (readonly string[])[] = [
+	["asOf"],
+	["dimensions", "*"],
+	["params", "*"],
+];
+
+/** Whether a path inside a Q column's `params` names a column of the record's entity. */
+export function isQueryColumnRecordSlot(path: readonly (string | number)[]): boolean {
+	return QUERY_COLUMN_RECORD_SLOTS.some(slot =>
+		slot.length === path.length && slot.every((segment, i) => segment === "*" || segment === path[i]));
+}

package/src/types.ts

@@ -14,7 +14,7 @@ export interface NamedKind {
 export type AlignType = "left" | "right" | "center";
 
 /** Column kind letter as stored in entity JSON / the `column` metadata table. */
-export type ColumnTypeCd = "D" | "R" | "S" | "F" | "A" | "L" | "G";
+export type ColumnTypeCd = "D" | "R" | "S" | "F" | "A" | "L" | "G" | "Q";
 
 /** Abstract data type code from the `base_datatype` table. */
 export type BaseDatatypeCd =