@gooddata/sdk-model 11.54.0-alpha.6 → 11.54.0

package/esm/reports/slot.d.ts

@@ -0,0 +1,219 @@
+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[];
+/**
+ * All semantic kinds a text slot can carry.
+ *
+ * @alpha
+ */
+export declare const BuiltInReportTextSlotKinds: ReportTextSlotKind[];
+/**
+ * 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,54 @@
+// (C) 2026 GoodData Corporation
+import { isEmpty } from "lodash-es";
+/**
+ * List of built-in report slot type names.
+ *
+ * @alpha
+ */
+export const BuiltInReportSlotTypes = ["visualization", "text", "image"];
+/**
+ * All semantic kinds a text slot can carry.
+ *
+ * @alpha
+ */
+export const BuiltInReportTextSlotKinds = [
+    "title",
+    "subtitle",
+    "sectionTitle",
+    "description",
+    "summary",
+    "body",
+    "custom",
+];
+/**
+ * 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);
+}