@dforge-core/metadata 0.0.26 → 0.0.29

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to `@dforge-core/metadata` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.28] — 2026-09-22
+
+### Added
+
+- **`schemas/stored_procedures.schema.json` and the types mirroring it** —
+  `StoredProceduresFile`, `StoredProcedureDef`, `SpParamDef`, `SpColumnDef`. The
+  authoring shape of `logic/stored_procedures.json`, which had no schema and no type
+  anywhere: a report dataset could say `datasetType: "S"`, and the validator could
+  demand the file, but nothing described what belongs in it. `functionName` is the
+  required field — the function's own name, not the `logic/reports/*.sql` script that
+  creates it.
+
+### Fixed
+
+- **A report dataset binds a stored procedure through `spCd`, not `procedureName`.**
+  Both `Dataset.procedureName` and the `procedureName` property in
+  `reports.schema.json` named a field the platform has never read — and because the
+  dataset schema is `additionalProperties: false`, editor validation *rejected* the
+  real one. Anyone authoring an SP dataset against the schema was told the correct
+  field was invalid and the wrong one was fine.
+
 ## [0.0.26] — 2026-09-15
 
 ### Added

package/dist/index.d.ts

@@ -673,8 +673,8 @@ 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. */
 interface LedgerRegistryEntry {
@@ -708,6 +708,8 @@ 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. */
@@ -756,7 +758,7 @@ declare function getIdentityKeys(entity: EntityDef, entityCode: string): string[
 declare function getPrimaryKeys(entity: EntityDef, entityCode: string): string[];
 
 /** `viewType` values for `ui/data_views.json`. Source: data_views.schema.json. */
-type ViewType = "grid" | "list" | "kanban" | "calendar" | "gallery" | "tree-grid" | "diagram" | "master-detail" | "library" | "matrix";
+type ViewType = "grid" | "list" | "kanban" | "calendar" | "gallery" | "tree-grid" | "diagram" | "library" | "matrix";
 /** Friendly picker list of the view kinds. */
 declare const dataViewKinds: readonly NamedKind[];
 /** A column in a data source: shorthand string code or a configured object. */
@@ -776,7 +778,7 @@ 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[];
@@ -835,7 +837,7 @@ 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;
@@ -945,8 +947,12 @@ interface Dataset {
     datasetType: "Q" | "S";
     /** Used when `datasetType` is 'Q'. */
     query?: ReportQuery;
-    /** Used when `datasetType` is 'S'. */
-    procedureName?: string;
+    /**
+     * Used when `datasetType` is 'S': the stored-procedure code, as
+     * `logic/stored_procedures.json` keys it — not the PostgreSQL function name,
+     * and never schema-qualified. `module.spCd` binds a dependency's procedure.
+     */
+    spCd?: string;
     /** Optional column metadata overrides: field code → override. */
     columnsDef?: Record<string, ColumnDef>;
     /**
@@ -1021,6 +1027,71 @@ interface ReportDef {
 /** A `ui/reports.json` file: report code → definition. */
 type ReportsFile = Record<string, ReportDef>;
 
+/** `logic/stored_procedures.json` — keyed by stored-procedure code (`sp_cd`). */
+type StoredProceduresFile = Record<string, StoredProcedureDef>;
+/** One stored-procedure declaration. */
+interface StoredProcedureDef {
+    /** Label in the report editor's procedure picker. Defaults to the code. */
+    description?: string;
+    /** Schema holding the function. Defaults to the module's own schema. */
+    schemaName?: string;
+    /**
+     * The function's own name, unqualified — `report.run` calls
+     * `SELECT * FROM "schemaName"."functionName"(...)`. Required: it is the one
+     * fact this file exists to record, and install fails naming it when absent.
+     */
+    functionName: string;
+    /** The function is set-returning — the only shape `report.run` projects. */
+    returnsTable?: boolean;
+    /**
+     * The call signature, in order. `report.run` passes exactly one positional
+     * argument per entry and nothing else — no folder, no user — so a function
+     * taking `p_folder_uid` / `p_user_id` can never be called.
+     */
+    params?: SpParamDef[];
+    /**
+     * Result columns. Omit the block and install derives them from the function's
+     * own `RETURNS TABLE` / OUT column names; a declared list is used as written
+     * and never merged with the signature.
+     */
+    columns?: SpColumnDef[];
+}
+/** One declared argument of the procedure. */
+interface SpParamDef {
+    /** Parameter code, conventionally the function's own argument name. */
+    paramCd: string;
+    /**
+     * PostgreSQL type of the argument — what binds the value, carried even when
+     * the value is null so an omitted optional argument arrives as a typed null.
+     * Case-insensitive, and a type modifier is ignored (`numeric(18,2)`).
+     * Defaults to `bigint`, so declare it for every argument that is not one.
+     */
+    pgType?: string;
+    /** Control copied into the report param on bind. Derived from `pgType` when omitted. */
+    fieldTypeCd?: string;
+    label?: string;
+    /** Default true. Give every optional one `DEFAULT NULL` in the signature. */
+    required?: boolean;
+}
+/** One declared result column of the procedure. */
+interface SpColumnDef {
+    /** Result column name as the function returns it. Unique within the procedure. */
+    columnCd: string;
+    /** Column header. Defaults to the code. */
+    label?: string;
+    fieldTypeCd?: string;
+    baseDatatypeCd?: string;
+    /** Display order. Defaults to declaration order in steps of 10. */
+    orderNum?: number;
+    /** Entity this column links to, making the value clickable. */
+    refEntityCd?: string;
+    /** Column holding the FK value for that link, when it is not this one. */
+    refColumnCd?: string;
+    width?: number;
+    /** Control parameters, the same shape an entity column's `params` takes. */
+    params?: Record<string, unknown>;
+}
+
 /** Author block on a manifest. */
 interface ManifestAuthor {
     name: string;
@@ -1064,6 +1135,8 @@ 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'). */
@@ -1422,6 +1495,95 @@ interface PrintTemplateDef {
 /** A `ui/print_templates.json` file: template_cd → definition. */
 type PrintTemplatesFile = Record<string, PrintTemplateDef>;
 
+/** A field in a card section — either a bare column code or pixel sizing with it. */
+type CardFieldEntry = string | CardFieldDef;
+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. */
+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.
+ */
+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. */
+interface CardTabRef {
+    type: "section" | "set";
+    code: string;
+}
+/** A tab bar whose tabs are other sections — several detail grids without one long form. */
+interface TabGroupSection {
+    type: "tabGroup";
+    code: string;
+    tabs: CardTabRef[];
+}
+type CardSection = ColumnGroupSection | SetSection | TabGroupSection;
+/** Per-set-field renderer choice, keyed by the set column code. */
+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`. */
+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.
+ */
+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. */
+type CardLayoutsFile = Record<string, CardLayoutDef>;
+
 /** A seed-data file: records to insert into one entity. */
 interface SeedDataFile {
     /** Target entity code. */
@@ -1435,4 +1597,4 @@ declare const flagDefs: readonly {
     label: string;
 }[];
 
-export { AGG_TYPE_LIST, type AccumulationConfig, AggType, type AlignType, type BaseDatatypeCd, type CalendarViewConfig, type ColumnDef, type ColumnTypeCd, type ColumnTypeDef, DEP_COLUMN_TYPES, type DataSource, type DataViewDef, type DataViewsFile, type Dataset, type DepColumn, type DepColumnMode, type DepColumnType, type DepEntity, type DepProvenance, type DepProvenanceKind, type DepsFile, type DeriveOptions, type DiagramViewConfig, type DomainDef, type DomainsFile, type EntityDef, type EntityEvent, type EntityReference, type EntityViewColumnDef, type EntityViewDef, FILTER_GROUP_OPERATORS, FILTER_OPERATORS, type FieldDef, type FieldLink, type FieldOption, type FieldTypeCd, type FieldTypeDef, type Filter, type FilterCondition, type FilterGroup, type FilterGroupOperator, type FilterOperator, type FlagCd, type FolderDef, type FolderEntityBinding, type FoldersFile, type JobDef, type JobsFile, type KanbanViewConfig, type LedgerRegistryEntry, type ListLevelConfig, type ListViewConfig, type ManifestAuthor, type ManifestDef, type MenuDef, type MenuItemDef, type MenuItemType, type MenusFile, type ModuleDependency, type ModuleFeature, NUMERIC_TOTAL, type NamedKind, type NumberSequenceDef, type ParamDef, type ParamDefBase, type PeriodConfig, type PrintMargins, type PrintPageSettings, type PrintTemplateDef, type PrintTemplatesFile, type ReportDef, type ReportEntityAttachment, type ReportLayout, type ReportPanel, type ReportQuery, type ReportsFile, type RoleDef, type RolesFile, type SeedDataFile, type SettingBaseDatatype, type SettingDef, type SettingsFile, type SignConfig, type SortClause, type TraitCd, type TraitDef, type TraitFieldConflict, type TraitsFile, type TreeGridViewConfig, type TriggerDef, type TriggersFile, type ViewColumn, type ViewType, type VizType, type WebhookPayload, type WebhookSubscription, type WebhooksFile, baseDatatypes, baseToDbDatatype, chartTypes, columnTypes, dataViewKinds, defaultParams, deriveBaseDatatype, deriveDbDatatype, expandTrait, expandTraits, fieldTypeCds, fieldTypes, fieldTypesByColumnType, flagDefs, getColumnType, getFieldType, getIdentityKeys, getLinks, getPrimaryKeys, getTrait, isFieldTypeCd, traitFieldConflicts, traits, vizTypes };
+export { AGG_TYPE_LIST, type AccumulationConfig, AggType, type AlignType, type BaseDatatypeCd, type CalendarViewConfig, type CardFieldDef, type CardFieldEntry, type CardLayout, type CardLayoutDef, type CardLayoutsFile, type CardSection, type CardSetConfig, type CardTabRef, type ColumnDef, type ColumnGroupSection, type ColumnTypeCd, type ColumnTypeDef, DEP_COLUMN_TYPES, type DataSource, type DataViewDef, type DataViewsFile, type Dataset, type DepColumn, type DepColumnMode, type DepColumnType, type DepEntity, type DepProvenance, type DepProvenanceKind, type DepsFile, type DeriveOptions, type DiagramViewConfig, type DomainDef, type DomainsFile, type EntityDef, type EntityEvent, type EntityReference, type EntityViewColumnDef, type EntityViewDef, FILTER_GROUP_OPERATORS, FILTER_OPERATORS, type FieldDef, type FieldLink, type FieldOption, type FieldTypeCd, type FieldTypeDef, type Filter, type FilterCondition, type FilterGroup, type FilterGroupOperator, type FilterOperator, type FlagCd, type FolderDef, type FolderEntityBinding, type FoldersFile, type JobDef, type JobsFile, type KanbanViewConfig, type LedgerRegistryEntry, type ListLevelConfig, type ListViewConfig, type ManifestAuthor, type ManifestDef, type MenuDef, type MenuItemDef, type MenuItemType, type MenusFile, type ModuleDependency, type ModuleFeature, NUMERIC_TOTAL, type NamedKind, type NumberSequenceDef, type ParamDef, type ParamDefBase, type PeriodConfig, type PrintMargins, type PrintPageSettings, type PrintTemplateDef, type PrintTemplatesFile, type ReportDef, type ReportEntityAttachment, type ReportLayout, type ReportPanel, type ReportQuery, type ReportsFile, type RoleDef, type RolesFile, type SeedDataFile, type SetSection, type SettingBaseDatatype, type SettingDef, type SettingsFile, type SignConfig, type SortClause, type SpColumnDef, type SpParamDef, type StoredProcedureDef, type StoredProceduresFile, type TabGroupSection, type TraitCd, type TraitDef, type TraitFieldConflict, type TraitsFile, type TreeGridViewConfig, type TriggerDef, type TriggersFile, type ViewColumn, type ViewType, type VizType, type WebhookPayload, type WebhookSubscription, type WebhooksFile, baseDatatypes, baseToDbDatatype, chartTypes, columnTypes, dataViewKinds, defaultParams, deriveBaseDatatype, deriveDbDatatype, expandTrait, expandTraits, fieldTypeCds, fieldTypes, fieldTypesByColumnType, flagDefs, getColumnType, getFieldType, getIdentityKeys, getLinks, getPrimaryKeys, getTrait, isFieldTypeCd, traitFieldConflicts, traits, vizTypes };

package/dist/index.js

@@ -366,7 +366,6 @@ var dataViewKinds = [
   { 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" }
 ];