@gooddata/sdk-model 11.54.0-alpha.5 → 11.54.0-alpha.7

package/esm/reports/pageLayout.js

@@ -0,0 +1,83 @@
+// (C) 2026 GoodData Corporation
+import { isEmpty } from "lodash-es";
+import { isObjRef } from "../objRef/index.js";
+import { isReportLayoutSection, isReportLayoutSlotRef } from "./layout.js";
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportPageLayoutDefinition}.
+ *
+ * @alpha
+ */
+export function isReportPageLayoutDefinition(obj) {
+    return !isEmpty(obj) && obj.type === "reportPageLayout";
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportPageLayout}.
+ *
+ * @alpha
+ */
+export function isReportPageLayout(obj) {
+    return isReportPageLayoutDefinition(obj) && isObjRef(obj.ref);
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportPageLayoutContent}.
+ *
+ * @alpha
+ */
+export function isReportPageLayoutContentV1(obj) {
+    return (!isEmpty(obj) &&
+        obj.version === "1" &&
+        !isEmpty(obj.layout) &&
+        Array.isArray(obj.slots));
+}
+/**
+ * Validates the structural invariants of a page body the type system cannot express:
+ * slot localIdentifiers are unique, layout weights are positive, every slot is placed
+ * by the layout, and every layout slotId resolves (unresolved ones are warnings —
+ * they render as empty areas).
+ *
+ * @alpha
+ */
+export function validateReportPageBody(body) {
+    const issues = [];
+    const slotIds = new Set();
+    for (const slot of body.slots) {
+        if (slotIds.has(slot.localIdentifier)) {
+            issues.push({
+                severity: "error",
+                message: `Duplicate slot localIdentifier "${slot.localIdentifier}".`,
+            });
+        }
+        slotIds.add(slot.localIdentifier);
+    }
+    const referencedIds = new Set();
+    const visit = (node) => {
+        if (node.weight !== undefined && !(node.weight > 0)) {
+            issues.push({
+                severity: "error",
+                message: `Layout node weight must be positive, got ${node.weight}.`,
+            });
+        }
+        if (isReportLayoutSlotRef(node)) {
+            referencedIds.add(node.slotId);
+            if (!slotIds.has(node.slotId)) {
+                issues.push({
+                    severity: "warning",
+                    message: `Layout references slot "${node.slotId}" which has no definition; it renders empty.`,
+                });
+            }
+        }
+        else if (isReportLayoutSection(node)) {
+            node.children.forEach(visit);
+        }
+    };
+    visit(body.layout);
+    for (const slotId of slotIds) {
+        if (!referencedIds.has(slotId)) {
+            issues.push({
+                severity: "warning",
+                message: `Slot "${slotId}" is not placed by the layout and never renders.`,
+            });
+        }
+    }
+    return issues;
+}

package/esm/reports/report.d.ts

@@ -0,0 +1,116 @@
+import { type IAuditableDates, type IAuditableUsers } from "../base/metadata.js";
+import { type ObjRef } from "../objRef/index.js";
+import { type IReportContent } from "./content.js";
+import { type ReportDateString } from "./variables.js";
+/**
+ * Payload for creating or updating a report template.
+ *
+ * @alpha
+ */
+export interface IReportTemplateDefinition {
+    type: "reportTemplate";
+    /**
+     * Present when updating an existing template.
+     */
+    ref?: ObjRef;
+    title: string;
+    description?: string;
+    tags?: string[];
+    content: IReportContent;
+}
+/**
+ * Report template metadata object.
+ *
+ * @alpha
+ */
+export interface IReportTemplate extends IReportTemplateDefinition, IAuditableDates, IAuditableUsers {
+    ref: ObjRef;
+    /**
+     * When true, the object comes from a parent workspace and is not editable
+     * in the current workspace.
+     */
+    isLocked?: boolean;
+}
+/**
+ * Fields shared by report definitions and persisted reports.
+ *
+ * @alpha
+ */
+export interface IReportBase {
+    title: string;
+    description?: string;
+    tags?: string[];
+    /**
+     * Reported period start, ISO 8601 date (YYYY-MM-DD), inclusive.
+     *
+     * @remarks
+     * At execution time the period materializes as an absolute date filter on each
+     * visualization slot's dateDataSet (lowest precedence, per-slot opt-out via
+     * ignoreReportPeriod). Also available as `{{periodStart}}` in text.
+     */
+    periodStart: ReportDateString;
+    /**
+     * Reported period end, ISO 8601 date (YYYY-MM-DD), inclusive.
+     */
+    periodEnd: ReportDateString;
+    /**
+     * Content of the report. When created from a template the content is deep-copied
+     * and NO reference to the template is kept — the report stays frozen while pages
+     * and templates evolve.
+     */
+    content: IReportContent;
+    /**
+     * Values for variables declared in content.variables, keyed by variable name.
+     */
+    variableValues?: Record<string, string>;
+}
+/**
+ * Payload for creating or updating a report.
+ *
+ * @alpha
+ */
+export interface IReportDefinition extends IReportBase {
+    type: "report";
+    /**
+     * Present when updating an existing report.
+     */
+    ref?: ObjRef;
+}
+/**
+ * Report metadata object.
+ *
+ * @alpha
+ */
+export interface IReport extends IReportDefinition, IAuditableDates, IAuditableUsers {
+    ref: ObjRef;
+    /**
+     * When true, the object comes from a parent workspace and is not editable
+     * in the current workspace.
+     */
+    isLocked?: boolean;
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportTemplateDefinition}.
+ *
+ * @alpha
+ */
+export declare function isReportTemplateDefinition(obj: unknown): obj is IReportTemplateDefinition;
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportTemplate}.
+ *
+ * @alpha
+ */
+export declare function isReportTemplate(obj: unknown): obj is IReportTemplate;
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportDefinition}.
+ *
+ * @alpha
+ */
+export declare function isReportDefinition(obj: unknown): obj is IReportDefinition;
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReport}.
+ *
+ * @alpha
+ */
+export declare function isReport(obj: unknown): obj is IReport;
+//# sourceMappingURL=report.d.ts.map

package/esm/reports/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/reports/report.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,KAAK,MAAM,EAAY,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACtC,IAAI,EAAE,gBAAgB,CAAC;IAEvB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,KAAK,EAAE,MAAM,CAAC;IAEd,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB,OAAO,EAAE,cAAc,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAgB,SAAQ,yBAAyB,EAAE,eAAe,EAAE,eAAe;IAChG,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,MAAM,CAAC;IAEd,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhB;;;;;;;OAOG;IACH,WAAW,EAAE,gBAAgB,CAAC;IAE9B;;OAEG;IACH,SAAS,EAAE,gBAAgB,CAAC;IAE5B;;;;OAIG;IACH,OAAO,EAAE,cAAc,CAAC;IAExB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IAClD,IAAI,EAAE,QAAQ,CAAC;IAEf;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAQ,SAAQ,iBAAiB,EAAE,eAAe,EAAE,eAAe;IAChF,GAAG,EAAE,MAAM,CAAC;IAEZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,yBAAyB,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,eAAe,CAErE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CAErD"}

package/esm/reports/report.js

@@ -0,0 +1,35 @@
+// (C) 2026 GoodData Corporation
+import { isEmpty } from "lodash-es";
+import { isObjRef } from "../objRef/index.js";
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportTemplateDefinition}.
+ *
+ * @alpha
+ */
+export function isReportTemplateDefinition(obj) {
+    return !isEmpty(obj) && obj.type === "reportTemplate";
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportTemplate}.
+ *
+ * @alpha
+ */
+export function isReportTemplate(obj) {
+    return isReportTemplateDefinition(obj) && isObjRef(obj.ref);
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportDefinition}.
+ *
+ * @alpha
+ */
+export function isReportDefinition(obj) {
+    return !isEmpty(obj) && obj.type === "report";
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReport}.
+ *
+ * @alpha
+ */
+export function isReport(obj) {
+    return isReportDefinition(obj) && isObjRef(obj.ref);
+}

package/esm/reports/slot.d.ts

@@ -0,0 +1,213 @@
+import { type FilterContextItem, type IDashboardFilterReference } from "../dashboard/filterContext.js";
+import { type VisualizationProperties } from "../insight/index.js";
+import { type ObjRef } from "../objRef/index.js";
+/**
+ * Metadata of a slot that is intentionally left unfilled in a report page or template.
+ *
+ * @alpha
+ */
+export interface IReportSlotPlaceholder {
+    /**
+     * Authoring hint shown in the empty slot.
+     */
+    hint?: string;
+    /**
+     * When true, a report is not considered complete until this slot is filled.
+     */
+    required?: boolean;
+}
+/**
+ * Structural base of every report slot.
+ *
+ * @remarks
+ * Parsers written against this base can skip slot types introduced by a newer
+ * content version instead of failing.
+ *
+ * @alpha
+ */
+export interface IReportSlotBase {
+    type: string;
+    /**
+     * Identifier unique within the page body. The layout tree references it, and it is
+     * the join key when a report fills a template's slots. Regenerated when a page is
+     * cloned into template content so repeated use of one page stays unique.
+     */
+    localIdentifier: string;
+    /**
+     * Present when the slot is an unfilled placeholder.
+     */
+    placeholder?: IReportSlotPlaceholder;
+}
+/**
+ * Slot rendering an insight, with its own filter context.
+ *
+ * @alpha
+ */
+export interface IReportVisualizationSlot extends IReportSlotBase {
+    type: "visualization";
+    /**
+     * Insight to render. Undefined = declared-but-empty slot; renderers show a placeholder.
+     */
+    insight?: ObjRef;
+    /**
+     * Optional title rendered above the visualization. Supports `{{variables}}`.
+     */
+    title?: string;
+    showTitle?: boolean;
+    /**
+     * Visualization properties overriding the insight's own.
+     */
+    properties?: VisualizationProperties;
+    /**
+     * Slot-level filters, applied on top of the effective content and page filters.
+     * A slot filter targeting the same object replaces the inherited one.
+     */
+    filters?: FilterContextItem[];
+    /**
+     * Content- and page-level filters this slot ignores (matched by display form / date dataset).
+     */
+    ignoredFilters?: IDashboardFilterReference[];
+    /**
+     * Date dataset the report's period (periodStart/periodEnd) is applied to as an
+     * absolute date filter at execution time. Undefined = backend date-dataset
+     * auto-resolution applies.
+     */
+    dateDataSet?: ObjRef;
+    /**
+     * When true, the implicit date filter derived from the report's period is not
+     * applied to this slot.
+     */
+    ignoreReportPeriod?: boolean;
+}
+/**
+ * Semantic kind of a text slot. Drives default typography/styling and AI context only —
+ * never geometry (geometry always comes from the layout tree).
+ *
+ * @alpha
+ */
+export type ReportTextSlotKind = "title" | "subtitle" | "sectionTitle" | "description" | "summary" | "body" | "custom";
+/**
+ * Author-written text.
+ *
+ * @alpha
+ */
+export interface IReportStaticTextSource {
+    type: "static";
+    /**
+     * Markdown content with `{{variable}}` placeholders. Stored raw — placeholders are
+     * resolved only at render/export time.
+     */
+    content: string;
+}
+/**
+ * Text generated by AI at report-build time.
+ *
+ * @alpha
+ */
+export interface IReportAiTextSource {
+    type: "ai";
+    /**
+     * Instruction for the generator. Supports `{{variables}}`.
+     */
+    prompt: string;
+    /**
+     * Materialized generation result (markdown), stored so the report renders
+     * deterministically without re-invoking AI. Absent until first generation.
+     */
+    content?: string;
+    /**
+     * ISO 8601 timestamp of the stored generation.
+     */
+    generatedAt?: string;
+}
+/**
+ * Where the text of a text slot comes from.
+ *
+ * @alpha
+ */
+export type ReportTextSource = IReportStaticTextSource | IReportAiTextSource;
+/**
+ * Slot rendering text.
+ *
+ * @alpha
+ */
+export interface IReportTextSlot extends IReportSlotBase {
+    type: "text";
+    kind: ReportTextSlotKind;
+    /**
+     * Undefined = declared-but-empty slot.
+     */
+    source?: ReportTextSource;
+}
+/**
+ * What an image slot displays.
+ *
+ * @alpha
+ */
+export type ReportImageSource = {
+    type: "url";
+    /**
+     * Image URL. Supports `{{variables}}` — a logo slot uses `{{logo}}`.
+     */
+    url: string;
+} | {
+    type: "asset";
+    /**
+     * Reference to a backend-managed asset.
+     */
+    ref: ObjRef;
+};
+/**
+ * Slot rendering an image.
+ *
+ * @alpha
+ */
+export interface IReportImageSlot extends IReportSlotBase {
+    type: "image";
+    /**
+     * Undefined = declared-but-empty slot.
+     */
+    source?: ReportImageSource;
+    altText?: string;
+    /**
+     * How the image fills the slot area. Defaults to "contain".
+     */
+    fit?: "contain" | "cover" | "fill";
+}
+/**
+ * All slot types of report content version 1.
+ *
+ * @alpha
+ */
+export type ReportSlot = IReportVisualizationSlot | IReportTextSlot | IReportImageSlot;
+/**
+ * List of built-in report slot type names.
+ *
+ * @alpha
+ */
+export declare const BuiltInReportSlotTypes: string[];
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportVisualizationSlot}.
+ *
+ * @alpha
+ */
+export declare function isReportVisualizationSlot(obj: unknown): obj is IReportVisualizationSlot;
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportTextSlot}.
+ *
+ * @alpha
+ */
+export declare function isReportTextSlot(obj: unknown): obj is IReportTextSlot;
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportImageSlot}.
+ *
+ * @alpha
+ */
+export declare function isReportImageSlot(obj: unknown): obj is IReportImageSlot;
+/**
+ * Type-guard testing whether the provided object is an instance of {@link ReportSlot}.
+ *
+ * @alpha
+ */
+export declare function isReportSlot(obj: unknown): obj is ReportSlot;
+//# sourceMappingURL=slot.d.ts.map

package/esm/reports/slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slot.d.ts","sourceRoot":"","sources":["../../src/reports/slot.ts"],"names":[],"mappings":"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"}

package/esm/reports/slot.js

@@ -0,0 +1,40 @@
+// (C) 2026 GoodData Corporation
+import { isEmpty } from "lodash-es";
+/**
+ * List of built-in report slot type names.
+ *
+ * @alpha
+ */
+export const BuiltInReportSlotTypes = ["visualization", "text", "image"];
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportVisualizationSlot}.
+ *
+ * @alpha
+ */
+export function isReportVisualizationSlot(obj) {
+    return !isEmpty(obj) && obj.type === "visualization";
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportTextSlot}.
+ *
+ * @alpha
+ */
+export function isReportTextSlot(obj) {
+    return !isEmpty(obj) && obj.type === "text";
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link IReportImageSlot}.
+ *
+ * @alpha
+ */
+export function isReportImageSlot(obj) {
+    return !isEmpty(obj) && obj.type === "image";
+}
+/**
+ * Type-guard testing whether the provided object is an instance of {@link ReportSlot}.
+ *
+ * @alpha
+ */
+export function isReportSlot(obj) {
+    return [isReportVisualizationSlot, isReportTextSlot, isReportImageSlot].some((guard) => guard(obj));
+}

package/esm/reports/variables.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ISO 8601 calendar date (YYYY-MM-DD).
+ *
+ * @alpha
+ */
+export type ReportDateString = string;
+/**
+ * Variables resolved by the rendering runtime; they are never declared or stored.
+ *
+ * @remarks
+ * Referenced from report text as `{{name}}`. Custom variable names must not collide with these;
+ * on collision the built-in wins.
+ *
+ * @alpha
+ */
+export type ReportBuiltInVariable = "reportTitle" | "periodStart" | "periodEnd" | "workspaceName" | "generatedAt" | "pageNumber" | "totalPages" | "logo";
+/**
+ * All built-in report variable names.
+ *
+ * @alpha
+ */
+export declare const ReportBuiltInVariables: ReportBuiltInVariable[];
+/**
+ * A custom variable declared by report content and given a value by a report.
+ *
+ * @remarks
+ * Referenced from text as `{{name}}`. Values come from {@link IReportBase.variableValues},
+ * falling back to {@link IReportVariableDefinition.defaultValue}.
+ *
+ * @alpha
+ */
+export interface IReportVariableDefinition {
+    /**
+     * Variable name as used inside the `{{...}}` marker. Must match /^[a-zA-Z][a-zA-Z0-9_]*$/.
+     * Built-in names ({@link ReportBuiltInVariable}) are reserved.
+     */
+    name: string;
+    /**
+     * Human readable label shown in the editor.
+     */
+    title?: string;
+    description?: string;
+    /**
+     * Value used when the report does not provide one. May not contain further
+     * placeholders — there is no recursive expansion.
+     */
+    defaultValue?: string;
+}
+/**
+ * Collects the distinct `{{variable}}` names referenced in the text, in order of first occurrence.
+ *
+ * @alpha
+ */
+export declare function getReportTextPlaceholders(text: string): string[];
+/**
+ * Replaces `{{variable}}` markers with values. Markers with no value are left as-is.
+ * Values are inserted verbatim — there is no recursive expansion.
+ *
+ * @alpha
+ */
+export declare function resolveReportTextPlaceholders(text: string, values: Record<string, string>): string;
+//# sourceMappingURL=variables.d.ts.map

package/esm/reports/variables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variables.d.ts","sourceRoot":"","sources":["../../src/reports/variables.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAC3B,aAAa,GACb,aAAa,GACb,WAAW,GACX,eAAe,GACf,aAAa,GACb,YAAY,GACZ,YAAY,GACZ,MAAM,CAAC;AAEb;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,qBAAqB,EASzD,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,yBAAyB;IACtC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAID;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAShE;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAIlG"}

package/esm/reports/variables.js

@@ -0,0 +1,41 @@
+// (C) 2026 GoodData Corporation
+/**
+ * All built-in report variable names.
+ *
+ * @alpha
+ */
+export const ReportBuiltInVariables = [
+    "reportTitle",
+    "periodStart",
+    "periodEnd",
+    "workspaceName",
+    "generatedAt",
+    "pageNumber",
+    "totalPages",
+    "logo",
+];
+const placeholderRegex = /\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g;
+/**
+ * Collects the distinct `{{variable}}` names referenced in the text, in order of first occurrence.
+ *
+ * @alpha
+ */
+export function getReportTextPlaceholders(text) {
+    const names = [];
+    for (const match of text.matchAll(placeholderRegex)) {
+        const name = match[1];
+        if (!names.includes(name)) {
+            names.push(name);
+        }
+    }
+    return names;
+}
+/**
+ * Replaces `{{variable}}` markers with values. Markers with no value are left as-is.
+ * Values are inserted verbatim — there is no recursive expansion.
+ *
+ * @alpha
+ */
+export function resolveReportTextPlaceholders(text, values) {
+    return text.replace(placeholderRegex, (marker, name) => Object.prototype.hasOwnProperty.call(values, name) ? values[name] : marker);
+}