@dforge-core/metadata 0.0.14 → 0.0.16

package/src/actions.ts

@@ -24,13 +24,41 @@ export interface ActionDef {
 	executionMode: ActionExecutionMode;
 	/** DSL script name (file under `logic/actions/<script>.dsl`). */
 	script: string;
-	/** Run inside a transaction (failures roll back). */
+	/**
+	 * Run the whole selection in one transaction, so a failure on any record
+	 * rolls back the records already processed. **Defaults to `true`** when
+	 * omitted (`ActionDef.IsTransacted` in the installer is a non-nullable
+	 * `bool` initialised to `true`), so omit it only when you want atomicity.
+	 *
+	 * `false` opens no transaction, and what follows a failure depends on
+	 * {@link ActionDef.executionMode}: `single` / `each` report it and continue
+	 * with the next record, so use that for independent per-record work that
+	 * should process as many records as pass; `batch` is a single script
+	 * invocation with no loop to continue, so the run simply ends with its
+	 * earlier writes committed.
+	 *
+	 * On a run queued to the background the **rollback** guarantee is lost
+	 * outright — the worker opens no transaction, so nothing is ever undone. What
+	 * remains of the flag there depends on the mode: the worker's `single`/`each`
+	 * loop still reads it for control flow (stop after the first failed record vs.
+	 * continue), while its `batch` path never reads it at all — one invocation,
+	 * which ends on failure under either value.
+	 */
 	isTransacted?: boolean;
 	/** Display order. */
 	orderNum?: number;
-	/** Run in the background (newer `async`; some modules use `isAsync`). */
+	/**
+	 * @deprecated Not read by the installer — use {@link ActionDef.isAsync}.
+	 * The module manifest model binds `isAsync` only, so this key is silently
+	 * ignored and the action installs as synchronous.
+	 */
 	async?: boolean;
-	/** Alternate spelling of `async` used by some modules. Prefer `async`. */
+	/**
+	 * Permit background execution. It does not force it: `action.execute`
+	 * carries its own `async` argument and the server branches on that, so an
+	 * action with parameters is offered to the user as both "Run" (inline) and
+	 * "Run in Background". A parameterless `isAsync` action is queued directly.
+	 */
 	isAsync?: boolean;
 }
 

package/src/entity.ts

@@ -32,6 +32,48 @@ export interface EntityReference {
 	onUpdate?: ReferentialAction;
 }
 
+/**
+ * Per-view overrides for one column (`views.<name>.columns.<column_cd>`). Every
+ * property is optional; an omitted one falls back to the entity-level value.
+ *
+ * An EMPTY value is not the same as an omitted one — the runtime merges view over
+ * entity with COALESCE, so `flags: ""` means "no flags in this view" (a column
+ * neither visible nor editable) and `params: {}` suppresses the entity-level
+ * params rather than inheriting them.
+ */
+export interface EntityViewColumnDef {
+	/** Flag letters for this column in this view, e.g. "VO" to expose it read-only. */
+	flags?: string;
+	orderNum?: number;
+	isNullable?: boolean;
+	editMask?: string;
+	displayFmt?: string;
+	/**
+	 * Formula override for this column in this view, same DSL as a field's
+	 * `formula`. Only on a column the entity declares as `columnType: "F"` — on any
+	 * other column that field is the SQL default, so an override would be inert.
+	 */
+	formula?: string;
+	/** Lookup filter override for a reference column in this view. */
+	refFilter?: unknown;
+	/** Control-specific configuration override for this view. */
+	params?: Record<string, unknown>;
+}
+
+/** One entity view: the columns it exposes, plus optional per-view overrides. */
+export interface EntityViewDef {
+	/**
+	 * Column code → per-view overrides. Columns ABSENT from this map are hidden in
+	 * a folder bound to the view — that is the mechanism, not an oversight. `{}`
+	 * (or null) exposes a column with no overrides. Must include the entity's
+	 * primary key: records are addressed by it (hide it by omitting `V` from its
+	 * flags instead).
+	 */
+	columns: Record<string, EntityViewColumnDef | null>;
+	/** Free-form view configuration, stored on entity_view.params. */
+	params?: Record<string, unknown>;
+}
+
 /** Automatic document numbering config (entity `numberSequence`). */
 export interface NumberSequenceDef {
 	/** Column code that receives the auto-generated number. */
@@ -128,4 +170,15 @@ export interface EntityDef {
 	accumulation?: AccumulationConfig;
 	/** Entity-level platform behavior flags. */
 	params?: { restricted?: boolean } & Record<string, unknown>;
+	/**
+	 * Entity views keyed by view name — the platform's column-level security.
+	 * Unrelated to `isView`/`viewSql` above (a SQL-view-backed entity) and to
+	 * `ui/data_views.json` (grids, kanban, calendars), both of which the word
+	 * "view" also names in this platform. A
+	 * folder binds one view per entity through `ui/folders.json`
+	 * (`entities.<code>.viewName`); users working in that folder see ONLY the
+	 * columns the view lists. An entity without views (or a folder naming the
+	 * conventional `"default"`, which declares nothing) shows the full column set.
+	 */
+	views?: Record<string, EntityViewDef>;
 }

package/src/folders.ts

@@ -7,7 +7,16 @@ import type { Filter } from "./filter";
 
 /** Per-entity binding within a folder. */
 export interface FolderEntityBinding {
-	/** Data view code to use in this folder (commonly 'default'). */
+	/**
+	 * Entity view to bind for this entity in this folder — a key under the entity
+	 * definition's `views` (see `EntityViewDef`), NOT a data view code from
+	 * `ui/data_views.json`. Users in this folder then see only the columns that
+	 * view lists.
+	 *
+	 * The conventional `"default"` declares nothing and means "no view" (the full
+	 * column set); any other name the entity does not declare fails the install,
+	 * since falling back would grant more access than naming a view asks for.
+	 */
 	viewName?: string;
 	/** Enable the quick-add (+) button for this entity here. */
 	quickAdd?: boolean;

package/src/index.ts

@@ -57,6 +57,8 @@ export { FILTER_GROUP_OPERATORS, FILTER_OPERATORS } from "./filter";
 export type {
 	EntityDef,
 	EntityReference,
+	EntityViewDef,
+	EntityViewColumnDef,
 	NumberSequenceDef,
 	PeriodConfig,
 	AccumulationConfig,
@@ -88,6 +90,7 @@ export {
 	chartTypes,
 	type ReportsFile,
 	type ReportDef,
+	type ReportEntityAttachment,
 	type ReportLayout,
 	type ReportPanel,
 	type Dataset,
@@ -98,7 +101,7 @@ export {
 	type VizType,
 } from "./reports";
 
-export type { ManifestDef, ManifestAuthor, ModuleDependency } from "./manifest";
+export type { ManifestDef, ManifestAuthor, ModuleDependency, ModuleFeature } from "./manifest";
 export type { DepsFile, DepEntity, DepColumn, DepColumnType, DepColumnMode, DepProvenance, DepProvenanceKind } from "./deps";
 export { DEP_COLUMN_TYPES } from "./deps";
 export type { DomainsFile, DomainDef } from "./domains";

package/src/manifest.ts

@@ -10,6 +10,13 @@ export interface ManifestAuthor {
 /** A dependency value: a semver range, or a partial-dep object. */
 export type ModuleDependency = string | { version: string; entities?: string[] };
 
+/**
+ * A platform behaviour a package can opt into via `manifest.features`.
+ * Mirrors `dForge.Core.ModuleFeatures` and the `features` enum in
+ * manifest.schema.json — all three are edited together.
+ */
+export type ModuleFeature = "report-security";
+
 /** A module package manifest (`manifest.json`). */
 export interface ManifestDef {
 	/** Package format version (currently 1). */
@@ -47,6 +54,20 @@ export interface ManifestDef {
 	icon?: string;
 	/** Non-English locales the package promises to translate. */
 	supportedLocales?: string[];
+	/**
+	 * Opt-in platform behaviours this package was authored for. Absent or empty
+	 * = the pre-feature behaviour for all of them, so a module written before a
+	 * feature existed keeps working until its author declares it and republishes.
+	 *
+	 * Unknown names are rejected at package load, never ignored — a misspelled
+	 * feature would silently leave the old behaviour in place while the manifest
+	 * claims otherwise.
+	 *
+	 * - `report-security` — this module's reports require 'E' on their
+	 *   `sec_object`. Declare the matching `"report:<code>": "E"` grants in
+	 *   `security/roles.json` first, or the reports go dark for every role.
+	 */
+	features?: ModuleFeature[];
 	/** Initial creation date (YYYY-MM-DD). Informational. */
 	created?: string;
 	/** Last manifest edit date (YYYY-MM-DD). Informational. */

package/src/reports.ts

@@ -35,25 +35,46 @@ export interface ParamDefBase {
 	label?: string;
 	/** Display order in the parameter form (falls back to declaration order). */
 	orderNum?: number;
-	/** Whether the user must provide a value. */
+	/**
+	 * Whether the user must provide a value. Stored inverted as `param.is_nullable`.
+	 * There is no `isRequired` spelling — the installer reads this key only.
+	 */
 	required?: boolean;
-	/** Alternate spelling of `required` used by some modules. Prefer `required`. */
-	isRequired?: boolean;
 	/** Default value applied when the user doesn't provide one. */
 	default?: unknown;
-	/** Entity link for lookup-type params. */
-	link?: { entity: string; otherKey?: string };
 	/**
-	 * Field-type-specific params — most importantly `options` for a dropdown.
+	 * Field-type-specific params, nested under this key — there is no top-level
+	 * `link`. A lookup param needs `{ link: { entity, otherKey? } }`.
+	 * Most importantly `options` for a dropdown.
 	 * Options accept the same rich `{value,label,icon,color}` form entity columns
 	 * use; a bare string list renders the raw codes in every locale, so label them.
 	 * Omitted on a domain-backed param: the domain owns the list.
 	 */
 	params?: Record<string, unknown>;
+	/**
+	 * Declares a REFERENCE parameter: the submitted value is the whole picked
+	 * record rather than its bare key. The JSON counterpart of the action DSL's
+	 * `paramCd: ref <entityCd>`, stored in the same `param.column_type`.
+	 *
+	 * Optional, and the choice is not cosmetic. Omitting it (a plain `lookup`)
+	 * submits the key, which is what a filter comparing against a reference
+	 * column needs — the server destructures a key object across every key
+	 * column and ignores non-key fields. Declare `"R"` when the report wants the
+	 * record itself, not just its identity.
+	 *
+	 * Either way the picker is configured by `params.link` (`{ entity, otherKey? }`);
+	 * `otherKey` is filled from the target's primary key when omitted, comma-joined
+	 * and paired POSITIONALLY with the key columns.
+	 */
+	columnType?: "R";
 }
 
 /**
- * A report parameter definition (report- or dataset-level).
+ * A report parameter definition. Declared in the report-level `parameters` block,
+ * or as shorthand under the `params` of the dataset that consumes it — the
+ * installer merges both into the report's single param set, so either way the
+ * parameter serves the whole report. Report level wins on a code collision, and
+ * is the only sensible home for a parameter several datasets use.
  *
  * A parameter takes its control from an explicit `fieldTypeCd` **or** from a
  * column `domain` — never both. Declaring both is the one rejected combination
@@ -111,10 +132,42 @@ export interface Dataset {
 	procedureName?: string;
 	/** Optional column metadata overrides: field code → override. */
 	columnsDef?: Record<string, ColumnDef>;
-	/** Dataset-level parameters (alternative to report-level `parameters`). */
+	/**
+	 * Parameters declared on this dataset — shorthand for the report-level
+	 * `parameters` block, convenient when exactly one dataset uses the parameter.
+	 * The installer merges both into the report's one param set either way.
+	 */
 	params?: Record<string, ParamDef>;
 }
 
+/**
+ * One (entity, report) **record-report attachment**: the report becomes openable
+ * from that entity's record, with the record's values feeding its parameters.
+ * Each entry becomes one `dForge.entity_report` row.
+ *
+ * The binding is per-attachment, not per-report — the same report can attach to
+ * several entities with different parameter mappings, which is why the mapping
+ * lives here rather than on the report.
+ */
+export interface ReportEntityAttachment {
+	/**
+	 * Entity the report attaches to, qualified `module.entity` for anything
+	 * outside the declaring module. That module must be a declared dependency.
+	 */
+	entityCd: string;
+	/**
+	 * Parameter mapping: report param code → **source column on the entity**.
+	 * (Not a param declaration — those live in the report's `parameters` block or a
+	 * dataset's `params`.) Resolved server-side
+	 * from the record's PK. Source columns are limited to the PK, reference (`R`)
+	 * columns, and bounded scalars; source and target must be type-compatible.
+	 * Params left unmapped keep their normal behaviour (default, or prompt).
+	 */
+	params?: Record<string, string>;
+	/** Sort position in the record's combined action + report menu. */
+	orderNum?: number;
+}
+
 /** A single visualization panel within the report layout. */
 export interface ReportPanel {
 	vizType: VizType;
@@ -136,8 +189,21 @@ export interface ReportDef {
 	layout: ReportLayout;
 	/** Dataset code → dataset definition. */
 	datasets: Record<string, Dataset>;
-	/** Report-level parameters (alternative to per-dataset `params`). */
+	/** Auto-refresh interval in seconds. Omit (or 0) for no auto-refresh. */
+	reloadInterval?: number;
+	/**
+	 * Report-level parameter declarations — the canonical home for a parameter, and
+	 * the only one that fits a parameter several datasets use. Merged with each
+	 * dataset's `params` into the report's single param set; this block wins on a
+	 * code collision.
+	 */
 	parameters?: Record<string, ParamDef>;
+	/**
+	 * Record-report attachments: entities this report can be opened from, with the
+	 * mapping from report parameter to source column on each. Omit for a report
+	 * that is only reached from a menu.
+	 */
+	entities?: ReportEntityAttachment[];
 }
 
 /** A `ui/reports.json` file: report code → definition. */