@dforge-core/metadata 0.0.25 → 0.0.27

package/src/card-layouts.ts

@@ -0,0 +1,103 @@
+// Card layouts — authoring shape of `ui/card_layouts.json`.
+// Mirror of card_layouts.schema.json, and of the runtime CardLayout in
+// @dforge/data's layouts.ts — the installer stores the body verbatim, so the
+// two must not drift.
+
+/** A field in a card section — either a bare column code or pixel sizing with it. */
+export type CardFieldEntry = string | CardFieldDef;
+
+export interface CardFieldDef {
+	column_cd: string;
+	/** Field width in px. */
+	width?: number;
+	/** Field height in px — for multiline/textarea fields. */
+	height?: number;
+}
+
+/** A group of fields laid out in 1, 2 or 3 columns. */
+export interface ColumnGroupSection {
+	type: "columnGroup";
+	code: string;
+	/** Section heading, in the module's authoring language. The installer gives it an
+	 *  `entity_column_group` row keyed on this section's `code`, so
+	 *  `translations/<locale>.json` localizes it under
+	 *  `entities.<entity>.columnGroups.<code>.label` and the card renders that instead. */
+	label?: string;
+	columns: CardFieldEntry[];
+	/** Field columns across the group (1-3). Defaults to the card's own setting. */
+	cols?: number;
+}
+
+/**
+ * An embedded detail grid for a 1:N set column — the master/detail building
+ * block. The label comes from the set column's own metadata.
+ */
+export interface SetSection {
+	type: "set";
+	code: string;
+	/** Set column code on this entity (columnType 'S'). */
+	setField: string;
+}
+
+/** Reference to a tab item: a columnGroup section's code, or a set column's code. */
+export interface CardTabRef {
+	type: "section" | "set";
+	code: string;
+}
+
+/** A tab bar whose tabs are other sections — several detail grids without one long form. */
+export interface TabGroupSection {
+	type: "tabGroup";
+	code: string;
+	tabs: CardTabRef[];
+}
+
+export type CardSection = ColumnGroupSection | SetSection | TabGroupSection;
+
+/** Per-set-field renderer choice, keyed by the set column code. */
+export interface CardSetConfig {
+	viewType?: "grid" | "list";
+	/** Opaque per-renderer options, passed verbatim to the set registration. */
+	options?: Record<string, unknown>;
+}
+
+/** The layout body, stored verbatim into `dForge.entity_view_layout.layout`. */
+export interface CardLayout {
+	sections: CardSection[];
+	sets?: Record<string, CardSetConfig>;
+}
+
+/**
+ * A module-shipped card layout (value in the card_layouts map; the key is the
+ * layout name).
+ *
+ * Rows written from here carry `module_id`, so the installer recreates them on
+ * every install and removes them on uninstall. A layout the tenant drew in the
+ * card editor has `module_id` NULL and is never touched.
+ */
+export interface CardLayoutDef {
+	/**
+	 * Entity code the layout belongs to. Unqualified means this module owns the
+	 * entity; `module.entity` targets another module's (the bridge case).
+	 */
+	entity: string;
+	/**
+	 * Entity view the layout hangs off. Defaults to `"default"` — the same
+	 * fallback the runtime uses for an entity with no folder binding of its own.
+	 * Matched against the entity's declared views case-insensitively, and filed
+	 * under their spelling.
+	 */
+	view?: string;
+	/**
+	 * Whether this layout opens by default. Honoured on FIRST install only, and
+	 * only when the view has no default yet: once a tenant has chosen their own,
+	 * an upgrade does not take it back.
+	 */
+	isDefault?: boolean;
+	/** Human-readable note for the package author. Not stored. */
+	description?: string;
+	layout: CardLayout;
+}
+
+/** `ui/card_layouts.json` — layout name → definition. */
+export type CardLayoutsFile = Record<string, CardLayoutDef>;

package/src/data-views.ts

@@ -17,7 +17,6 @@ export type ViewType =
 	| "gallery"
 	| "tree-grid"
 	| "diagram"
-	| "master-detail"
 	| "library"
 	| "matrix";
 
@@ -30,7 +29,6 @@ export const dataViewKinds: readonly NamedKind[] = [
 	{ cd: "gallery", name: "Gallery" },
 	{ cd: "tree-grid", name: "Tree Grid" },
 	{ cd: "diagram", name: "Diagram" },
-	{ cd: "master-detail", name: "Master / Detail" },
 	{ cd: "library", name: "Library" },
 	{ cd: "matrix", name: "Matrix" },
 ] as const;
@@ -55,7 +53,7 @@ export interface DataSource {
 	entityCode: string;
 	/** Nesting level (0 = root, 1+ = detail). */
 	level?: number;
-	/** Human-readable label (used in master-detail tabs). */
+	/** Human-readable label for this data source. */
 	label?: string;
 	/** Column configuration. */
 	columns?: ViewColumn[];
@@ -121,7 +119,7 @@ export interface DataViewDef {
 	/** Bootstrap icon class (e.g. 'bi-bounding-box'). */
 	icon?: string;
 	description?: string;
-	/** Data sources (at least one; master-detail needs two). */
+	/** Data sources (at least one). Only the first is rendered today. */
 	dataSources: DataSource[];
 	/** Default filter applied to all sources unless one declares its own. */
 	filter?: Filter;

package/src/entity.ts

@@ -130,8 +130,8 @@ export interface AccumulationConfig {
 	sign?: SignConfig;
 	autoCreateBalance?: boolean;
 	allowNegative?: boolean;
-	/** Document fields locked once posted. */
-	lockedFields?: string[];
+	/** Document fields locked once posted. Required; `["*"]` freezes the whole row. */
+	lockedFields: string[];
 }
 
 /** One registry target within an L-column's `registries` array. */
@@ -167,6 +167,8 @@ export interface EntityDef {
 	viewSql?: string;
 	/** Display pattern using column placeholders, e.g. "{first_name} {last_name}". */
 	toString?: string;
+	/** Records of this entity accept comments (composer + thread on the card). */
+	comments?: boolean;
 	/** Traits expanded at install time. */
 	traits?: TraitCd[];
 	/** Column definitions keyed by column code. Optional when a trait (e.g. `period`) supplies all columns. */

package/src/index.ts

@@ -36,7 +36,8 @@ export { AggType, AGG_TYPE_LIST } from "./aggregation";
 export { fieldTypes, fieldTypeCds, isFieldTypeCd, getFieldType, fieldTypesByColumnType } from "./field-types";
 export { baseDatatypes, baseToDbDatatype } from "./base-datatypes";
 export { columnTypes, getColumnType } from "./column-types";
-export { traits, getTrait, expandTrait, expandTraits } from "./traits";
+export { traits, getTrait, expandTrait, expandTraits, traitFieldConflicts } from "./traits";
+export type { TraitFieldConflict } from "./traits";
 export {
 	deriveDbDatatype,
 	deriveBaseDatatype,
@@ -116,6 +117,19 @@ export type { JobsFile, JobDef } from "./jobs";
 export type { TriggersFile, TriggerDef, EntityEvent } from "./triggers";
 export type { WebhooksFile, WebhookSubscription, WebhookPayload } from "./webhooks";
 export type { PrintTemplatesFile, PrintTemplateDef, PrintPageSettings, PrintMargins } from "./print-templates";
+export type {
+	CardLayoutsFile,
+	CardLayoutDef,
+	CardLayout,
+	CardSection,
+	CardSetConfig,
+	CardTabRef,
+	CardFieldEntry,
+	CardFieldDef,
+	ColumnGroupSection,
+	SetSection,
+	TabGroupSection,
+} from "./card-layouts";
 export type { SeedDataFile } from "./seed-data";
 export type { ActionsFile, ActionDef, ActionExecutionMode } from "./actions";
 

package/src/manifest.ts

@@ -44,6 +44,8 @@ export interface ManifestDef {
 	dependencies?: Record<string, ModuleDependency>;
 	/** Default audit history mode for this module's entities. */
 	auditHistory?: "none" | "minimal" | "full";
+	/** Default for `comments` on this module's entities; each entity may override. */
+	comments?: boolean;
 	/** Entity code → relative path of its JSON file (dotted keys = extensions). */
 	entities?: Record<string, string>;
 	/** Module category for display (e.g. 'Integration', 'Finance'). */

package/src/traits.ts

@@ -91,22 +91,93 @@ function applyTemplate(value: string, entity: string): string {
 	return value.replace(/\{entity\}/g, local).replace(/\{Entity\}/g, titleCaseEntity(entity));
 }
 
-function templateFields(fields: Record<string, FieldDef>, entity: string): Record<string, FieldDef> {
-	const out: Record<string, FieldDef> = {};
-	for (const [name, def] of Object.entries(fields)) {
-		const key = applyTemplate(name, entity);
-		const next: FieldDef = { ...def };
-		if (typeof next.description === "string") next.description = applyTemplate(next.description, entity);
-		out[key] = next;
+function templateField(def: FieldDef, entity: string): FieldDef {
+	const next: FieldDef = { ...def };
+	if (typeof next.description === "string") next.description = applyTemplate(next.description, entity);
+	return next;
+}
+
+/**
+ * The merged field map. Prototype-less: a field code is author-supplied, so on a
+ * plain object one named `constructor` would read back as a field already there
+ * and one named `__proto__` would not write at all.
+ */
+function emptyFields(): Record<string, FieldDef> {
+	return Object.create(null) as Record<string, FieldDef>;
+}
+
+/**
+ * The identity the installer compares on a key collision — `TryAddField` reads
+ * `ColumnType ?? DbDatatype ?? FieldTypeCd` and treats two definitions as the
+ * same field only when these match.
+ */
+function typeKeyOf(def: FieldDef): string | undefined {
+	return def.columnType ?? def.dbDatatype ?? def.fieldTypeCd;
+}
+
+/** Where a field already in the merge came from, for conflict wording. */
+type FieldOrigin = "field" | "trait";
+
+/**
+ * A trait contributing a field the entity already has under a DIFFERENT type.
+ * The installer throws on this (`Field 'x' conflicts with trait: ...`), so a
+ * module that hits one cannot install — offline readers report it instead.
+ */
+export interface TraitFieldConflict {
+	/** Column code, after `{entity}` / `{Entity}` resolution. */
+	field: string;
+	/** Whether the definition being kept is an authored field or a trait's. */
+	existingFrom: FieldOrigin;
+	/** Type identity of the definition being kept. */
+	existingType?: string;
+	/** Type identity of the trait definition being dropped. */
+	traitType?: string;
+}
+
+interface MergeSink {
+	fields: Record<string, FieldDef>;
+	origin: Map<string, FieldOrigin>;
+	conflicts?: TraitFieldConflict[];
+}
+
+/**
+ * Merge one trait-contributed field in, the way the installer does: the FIRST
+ * definition wins, and a later one of a different type is a conflict rather
+ * than an overwrite. See `TraitExpander.TryAddField`.
+ */
+function addTraitField(sink: MergeSink, key: string, def: FieldDef): void {
+	const existing = sink.fields[key];
+	if (!Object.hasOwn(sink.fields, key)) {
+		sink.fields[key] = def;
+		sink.origin.set(key, "trait");
+		return;
+	}
+	if (sink.conflicts && !sink.conflicts.some((c) => c.field === key)) {
+		const existingType = typeKeyOf(existing);
+		const traitType = typeKeyOf(def);
+		if (existingType !== traitType) {
+			sink.conflicts.push({
+				field: key,
+				existingFrom: sink.origin.get(key) ?? "trait",
+				existingType,
+				traitType,
+			});
+		}
 	}
-	return out;
+	// Same type (or a conflict already recorded) — keep the first definition,
+	// which is what the installer does.
 }
 
 /**
  * Expand a trait (and any traits it includes) into the concrete fields it adds
  * for `entityName`, with `{entity}` / `{Entity}` tokens resolved. Returns an
  * empty object for unknown or marker traits. Field order follows include-depth
- * first, then declaration order; later definitions win on key collisions.
+ * first, then declaration order.
+ *
+ * The FIRST definition of a key wins, mirroring the installer's
+ * `TraitExpander.TryAddField`. A later definition of the same key under a
+ * different type is one the installer refuses to expand at all — see
+ * {@link traitFieldConflicts}, which reports those without throwing.
  *
  * `localTraits` is a module's own `traits.json`. A module may declare traits of
  * its own, and an entity in it names them exactly like a platform trait — so a
@@ -120,7 +191,9 @@ export function expandTrait(
 	entityName: string,
 	localTraits?: TraitsFile,
 ): Record<string, FieldDef> {
-	return expandTraitInner(traitCd, entityName, localTraits, new Set());
+	const sink: MergeSink = { fields: emptyFields(), origin: new Map() };
+	expandTraitInner(traitCd, entityName, localTraits, new Set(), sink);
+	return sink.fields;
 }
 
 function expandTraitInner(
@@ -128,7 +201,8 @@ function expandTraitInner(
 	entityName: string,
 	localTraits: TraitsFile | undefined,
 	path: Set<string>,
-): Record<string, FieldDef> {
+	sink: MergeSink,
+): void {
 	// `includes` is author-supplied once local traits are in play, so a cycle is
 	// reachable from a module file. Unguarded that is an editor hang, not a bad
 	// expansion.
@@ -137,20 +211,27 @@ function expandTraitInner(
 	// diamond — two includes that both reach a third — the third has to expand
 	// under each of them, or which definition wins a key collision would depend
 	// on which branch got there first.
-	if (path.has(traitCd)) return {};
+	if (path.has(traitCd)) return;
 	path.add(traitCd);
 
-	const trait = localTraits?.[traitCd] ?? byCd.get(traitCd);
-	const result: Record<string, FieldDef> = {};
+	// Own-property lookup: `localTraits` is parsed JSON, so a code like
+	// `constructor` would otherwise resolve to something off Object.prototype.
+	const trait =
+		localTraits && Object.hasOwn(localTraits, traitCd) ? localTraits[traitCd] : byCd.get(traitCd);
 	if (trait) {
 		for (const included of trait.includes ?? []) {
-			Object.assign(result, expandTraitInner(included, entityName, localTraits, path));
+			expandTraitInner(included, entityName, localTraits, path, sink);
+		}
+		// Each field is templated and merged on its own: two keys in one trait can
+		// resolve to the same code for a given entity (`{entity}_id` and `x_id`
+		// for entity `x`), and the installer, which resolves and adds one key at a
+		// time, sees that collision as a conflict.
+		for (const [name, def] of Object.entries(trait.fields ?? {})) {
+			addTraitField(sink, applyTemplate(name, entityName), templateField(def, entityName));
 		}
-		Object.assign(result, templateFields(trait.fields ?? {}, entityName));
 	}
 
 	path.delete(traitCd);
-	return result;
 }
 
 /** Expand several traits in order into one merged field map. */
@@ -159,9 +240,39 @@ export function expandTraits(
 	entityName: string,
 	localTraits?: TraitsFile,
 ): Record<string, FieldDef> {
-	const result: Record<string, FieldDef> = {};
+	const sink: MergeSink = { fields: emptyFields(), origin: new Map() };
+	for (const cd of traitCds) {
+		expandTraitInner(cd, entityName, localTraits, new Set(), sink);
+	}
+	return sink.fields;
+}
+
+/**
+ * The collisions that make the installer refuse an entity: a trait contributing
+ * a field the entity already has under a different type identity.
+ *
+ * `fields` is the entity's own authored fields. The installer seeds its merge
+ * with them and expands traits into it (`TraitExpander.ExpandAll`), so an
+ * authored field can conflict with a trait's exactly as two traits can — and
+ * either way install fails with `Field 'x' conflicts with trait`. Omit it to
+ * check the traits against each other alone.
+ *
+ * Returns one entry per field, in the order the conflicts are reached. An empty
+ * array means the expansion the installer performs is the one
+ * {@link expandTraits} returns.
+ */
+export function traitFieldConflicts(
+	traitCds: readonly string[],
+	entityName: string,
+	opts: { localTraits?: TraitsFile; fields?: Record<string, FieldDef> } = {},
+): TraitFieldConflict[] {
+	const sink: MergeSink = { fields: emptyFields(), origin: new Map(), conflicts: [] };
+	for (const [key, def] of Object.entries(opts.fields ?? {})) {
+		sink.fields[key] = def;
+		sink.origin.set(key, "field");
+	}
 	for (const cd of traitCds) {
-		Object.assign(result, expandTraitInner(cd, entityName, localTraits, new Set()));
+		expandTraitInner(cd, entityName, opts.localTraits, new Set(), sink);
 	}
-	return result;
+	return sink.conflicts!;
 }