@gooddata/sdk-ui-vis-commons 11.39.0-alpha.1 → 11.39.0-alpha.2

package/esm/customTooltip/composeSectionHtml.d.ts

@@ -0,0 +1,10 @@
+import { type IResolvedReferenceValues } from "./types.js";
+/**
+ * Merge order matters: in-chart values override external ones, because the
+ * in-chart value is what the user already sees on the rendered point/feature.
+ * If a tooltip references the same id from both, showing the external (fetched)
+ * value would let it drift from what the chart pixel displays.
+ *
+ * @internal
+ */
+export declare function composeCustomTooltipSectionHtml(content: string, inChartValues: IResolvedReferenceValues, externalValues: IResolvedReferenceValues, fallbackText: string): string;

package/esm/customTooltip/composeSectionHtml.js

@@ -0,0 +1,16 @@
+// (C) 2026 GoodData Corporation
+import { markdownToHtml } from "./markdownToHtml.js";
+import { resolveReferences } from "./referenceResolver.js";
+/**
+ * Merge order matters: in-chart values override external ones, because the
+ * in-chart value is what the user already sees on the rendered point/feature.
+ * If a tooltip references the same id from both, showing the external (fetched)
+ * value would let it drift from what the chart pixel displays.
+ *
+ * @internal
+ */
+export function composeCustomTooltipSectionHtml(content, inChartValues, externalValues, fallbackText) {
+    const merged = { ...externalValues, ...inChartValues };
+    const resolved = resolveReferences(content, merged, fallbackText);
+    return `<div class="gd-viz-tooltip-custom-section">${markdownToHtml(resolved)}</div>`;
+}

package/esm/customTooltip/markdownToHtml.js

@@ -9,7 +9,8 @@
  * - Unordered lists (- item or * item)
  * - Ordered lists (1. item)
  * - Images (![alt](url))
- * - Links ([text](url)) — rendered as plain styled text (not clickable in tooltips)
+ * - Links ([text](url)) — rendered as clickable anchors (target=_blank, rel=noopener noreferrer)
+ *   for `http(s):` URLs; unsafe URLs (javascript:, data:text/...) fall back to plain text
  * - Horizontal rules (--- or ***)
  * - Line breaks
  * - Backslash escapes (\*, \_, \[, \!, etc.) — render the metachar as literal text.
@@ -25,9 +26,16 @@
 function escapeHtml(text) {
     return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-function isSafeUrl(url) {
+// http(s) navigation is the only safe scheme for clickable links. Data URLs are
+// fine inline for <img> sources, but allowing them on <a href> would let an
+// `[link](data:image/svg+xml,...)` target an SVG that may execute scripts on
+// navigation.
+function isSafeImageUrl(url) {
     return /^https?:\/\//i.test(url) || /^data:image\//i.test(url);
 }
+function isSafeLinkUrl(url) {
+    return /^https?:\/\//i.test(url);
+}
 // URL pattern allowing one level of balanced parens, e.g.
 // https://en.wikipedia.org/wiki/Page_(name)
 const URL_PATTERN = "(?:[^()\\s]|\\([^)]*\\))+";
@@ -41,14 +49,19 @@ function processInlineMarkdown(text) {
     let result = escapeHtml(text);
     // Inline style as fallback since the tooltip renders outside the normal DOM tree.
     result = result.replace(IMAGE_REGEX, (_match, alt, url) => {
-        if (!isSafeUrl(url)) {
+        if (!isSafeImageUrl(url)) {
             return `${alt}`;
         }
         return `<img src="${url}" alt="${alt}" style="max-width: 100%; display: block; margin: 4px 0;" />`;
     });
-    // Render as styled text — links are intentionally not clickable inside tooltips.
-    result = result.replace(LINK_REGEX, (_match, linkText) => {
-        return `<span class="gd-viz-tooltip-custom-link">${linkText}</span>`;
+    // Always emit a `target="_blank"` anchor for http(s) URLs; whether the user
+    // can practically reach it depends on the tooltip mode's lifecycle (the
+    // tooltip needs to stay open long enough to mouse over the link).
+    result = result.replace(LINK_REGEX, (_match, linkText, url) => {
+        if (!isSafeLinkUrl(url)) {
+            return linkText;
+        }
+        return `<a href="${url}" target="_blank" rel="noopener noreferrer">${linkText}</a>`;
     });
     // Bold-italic: ***text*** — must run before bold and italic so the triple
     // asterisks are consumed as a unit instead of being split across patterns.
@@ -138,6 +151,7 @@ function parseMarkdown(markdown) {
         const trimmed = line.trim();
         if (!trimmed) {
             closeList();
+            htmlParts.push("<br/>");
             continue;
         }
         // Horizontal rule: --- or *** or ___

package/esm/customTooltip/tooltipExecution.d.ts

@@ -0,0 +1,43 @@
+import { type IExecutionFactory, type IPreparedExecution } from "@gooddata/sdk-backend-spi";
+import { type IExecutionDefinition } from "@gooddata/sdk-model";
+/**
+ * Maps used by `buildLookupTable` to interpret the execution result.
+ *
+ * @internal
+ */
+export interface ITooltipExecutionMeta {
+    /** value localId → count localId, for "Multiple items" detection. */
+    labelCountMap: Record<string, string>;
+    /** tooltip metric localId → LDM measure identifier. */
+    measureIdMap: Record<string, string>;
+    /** label value localId → LDM label identifier. */
+    labelIdMap: Record<string, string>;
+}
+/**
+ * Prepared tooltip execution paired with the meta needed to interpret its result.
+ * Carry them together — meta from one call mis-interprets results from another.
+ *
+ * @internal
+ */
+export interface ITooltipExecutionBundle {
+    execution: IPreparedExecution;
+    meta: ITooltipExecutionMeta;
+}
+/**
+ * @internal
+ */
+export interface IBuildTooltipExecutionOptions {
+    /**
+     * LocalIdentifiers from `definition.attributes` to use as the row dimension,
+     * in the desired order. Omit to use all attributes in definition order
+     * (Highcharts default). Geo passes an explicit list to drop position attrs.
+     */
+    slicingAttributeLocalIds?: readonly string[];
+}
+/**
+ * Returns `null` when the content has no references or all references are
+ * already in the chart (resolvable from drill data without a secondary call).
+ *
+ * @internal
+ */
+export declare function buildTooltipExecution(executionFactory: IExecutionFactory, chartDefinition: IExecutionDefinition, tooltipContent: string, options?: IBuildTooltipExecutionOptions): ITooltipExecutionBundle | null;

package/esm/customTooltip/tooltipExecution.js

@@ -0,0 +1,152 @@
+// (C) 2026 GoodData Corporation
+import { MeasureGroupIdentifier, filterMeasureRef, idRef, isIdentifierRef, isLocalIdRef, isSimpleMeasure, measureItem, measureLocalId, newAttribute, newMeasure, newTwoDimensional, } from "@gooddata/sdk-model";
+import { REFERENCE_REGEX_MATCH } from "@gooddata/sdk-ui-kit";
+function parseReferences(content) {
+    const refs = [];
+    const seen = new Set();
+    // REFERENCE_REGEX_MATCH lives in sdk-ui-kit; match[3] is the kind
+    // ("label" | "metric"), match[4] is the id.
+    for (const match of content.matchAll(REFERENCE_REGEX_MATCH)) {
+        const rawType = match[3].toLowerCase();
+        // Synonyms like `measure` / `displayForm` aren't canonical here; let
+        // them fall through so the rest of the pipeline doesn't silently treat
+        // a `measure` ref as a metric.
+        if (rawType !== "metric" && rawType !== "label") {
+            continue;
+        }
+        const id = match[4];
+        const key = `${rawType}/${id}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            refs.push({ type: rawType, id });
+        }
+    }
+    return refs;
+}
+function getChartMetricIds(definition) {
+    const ids = new Set();
+    for (const measure of definition.measures) {
+        if (isSimpleMeasure(measure)) {
+            const ref = measureItem(measure);
+            if (ref && isIdentifierRef(ref)) {
+                ids.add(ref.identifier);
+            }
+        }
+    }
+    return ids;
+}
+function getChartLabelIds(definition) {
+    // Only display-form identifier refs match. Refs in user content using a
+    // URI ref or a parent attribute id miss the set, fall into the secondary
+    // execution, and fail backend-side (one bad ref drops the whole call).
+    const ids = new Set();
+    for (const attr of definition.attributes) {
+        const ref = attr.attribute.displayForm;
+        if (isIdentifierRef(ref)) {
+            ids.add(ref.identifier);
+        }
+    }
+    return ids;
+}
+/**
+ * Chart measures that MVF/ranking filters depend on. Must be included in the
+ * tooltip execution with their original localIds so the filter refs resolve and
+ * tooltip values stay filter-consistent with the chart.
+ */
+function getFilterDependencyMeasures(filters, chartMeasures) {
+    const neededLocalIds = new Set();
+    for (const filter of filters) {
+        const measureRef = filterMeasureRef(filter);
+        if (measureRef && isLocalIdRef(measureRef)) {
+            neededLocalIds.add(measureRef.localIdentifier);
+        }
+    }
+    if (neededLocalIds.size === 0) {
+        return [];
+    }
+    return chartMeasures.filter((m) => neededLocalIds.has(measureLocalId(m)));
+}
+/**
+ * Build tooltip-only measures for refs not already in the chart.
+ * Labels get a max+count pair (mirrors the RichText widget pattern) so the
+ * lookup can render "(Multiple items)" when a label resolves to >1 value per row.
+ *
+ * LocalId prefixes `tt_m_`, `tt_lv_`, `tt_lc_` are reserved — collision with
+ * chart-side measure localIds would break filter-dependency reuse.
+ */
+function buildTooltipItems(refs, chartMetricIds, chartLabelIds) {
+    const measures = [];
+    const labelCountMap = {};
+    const labelIdMap = {};
+    const measureIdMap = {};
+    let idx = 0;
+    for (const ref of refs) {
+        if (ref.type === "metric" && !chartMetricIds.has(ref.id)) {
+            const localId = `tt_m_${idx++}`;
+            measures.push(newMeasure(idRef(ref.id, "measure"), (m) => m.localId(localId)));
+            measureIdMap[localId] = ref.id;
+        }
+        else if (ref.type === "label" && !chartLabelIds.has(ref.id)) {
+            const valueLocalId = `tt_lv_${idx}`;
+            const countLocalId = `tt_lc_${idx}`;
+            idx++;
+            measures.push(newMeasure(idRef(ref.id, "displayForm"), (m) => m.localId(valueLocalId).aggregation("max")));
+            measures.push(newMeasure(idRef(ref.id, "displayForm"), (m) => m.localId(countLocalId).aggregation("count")));
+            labelCountMap[valueLocalId] = countLocalId;
+            labelIdMap[valueLocalId] = ref.id;
+        }
+    }
+    return { measures, labelCountMap, labelIdMap, measureIdMap };
+}
+/**
+ * Slicing attributes for the tooltip execution's row dimension. When
+ * `slicingAttributeLocalIds` is passed, attributes are filtered AND reordered
+ * to match the caller's list (geo layers exclude position attributes and rely
+ * on the order being theirs).
+ */
+function getSlicingAttributes(definition, slicingAttributeLocalIds) {
+    if (!slicingAttributeLocalIds) {
+        return definition.attributes.map((attr) => newAttribute(attr.attribute.displayForm, (a) => a.localId(attr.attribute.localIdentifier)));
+    }
+    const byLocalId = new Map(definition.attributes.map((a) => [a.attribute.localIdentifier, a]));
+    const out = [];
+    for (const localId of slicingAttributeLocalIds) {
+        const attr = byLocalId.get(localId);
+        if (attr) {
+            out.push(newAttribute(attr.attribute.displayForm, (a) => a.localId(localId)));
+        }
+    }
+    return out;
+}
+/**
+ * Returns `null` when the content has no references or all references are
+ * already in the chart (resolvable from drill data without a secondary call).
+ *
+ * @internal
+ */
+export function buildTooltipExecution(executionFactory, chartDefinition, tooltipContent, options) {
+    const refs = parseReferences(tooltipContent);
+    if (refs.length === 0) {
+        return null;
+    }
+    const chartMetricIds = getChartMetricIds(chartDefinition);
+    const chartLabelIds = getChartLabelIds(chartDefinition);
+    const { measures, labelCountMap, labelIdMap, measureIdMap } = buildTooltipItems(refs, chartMetricIds, chartLabelIds);
+    if (measures.length === 0) {
+        return null;
+    }
+    const chartAttrs = getSlicingAttributes(chartDefinition, options?.slicingAttributeLocalIds);
+    const filterDepMeasures = getFilterDependencyMeasures(chartDefinition.filters, chartDefinition.measures);
+    const allItems = [...chartAttrs, ...measures, ...filterDepMeasures];
+    const attrLocalIds = chartAttrs.map((a) => a.attribute.localIdentifier);
+    let execution = executionFactory
+        .forItems(allItems, chartDefinition.filters)
+        .withDimensions(...newTwoDimensional(attrLocalIds, [MeasureGroupIdentifier]));
+    if (chartDefinition.executionConfig) {
+        execution = execution.withExecConfig(chartDefinition.executionConfig);
+    }
+    return {
+        execution,
+        meta: { labelCountMap, measureIdMap, labelIdMap },
+    };
+}

package/esm/customTooltip/tooltipKey.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lookup-key helpers shared by `buildLookupTable` and chart-family hover-time
+ * key builders. Both sides must produce identical strings.
+ *
+ * Format: `${displayFormId}:${uri}` per attribute, joined by `|` after
+ * lexicographic sort. The `displayFormId` is always the idRef identifier —
+ * uriRef-backed display forms are skipped at the tooltip-execution-planning
+ * step (in each chart family's adapter), so they never reach this key builder.
+ * Name is omitted: the backend substitutes null/empty names with localized
+ * strings only on the display side, so including them here causes
+ * lookup-vs-hover mismatches on null/empty rows.
+ */
+/**
+ * @internal
+ */
+export declare function buildKeySegment(displayFormId: string, uri: string): string;
+/**
+ * @internal
+ */
+export declare function joinKeySegments(parts: readonly string[]): string;

package/esm/customTooltip/tooltipKey.js

@@ -0,0 +1,25 @@
+// (C) 2026 GoodData Corporation
+/**
+ * Lookup-key helpers shared by `buildLookupTable` and chart-family hover-time
+ * key builders. Both sides must produce identical strings.
+ *
+ * Format: `${displayFormId}:${uri}` per attribute, joined by `|` after
+ * lexicographic sort. The `displayFormId` is always the idRef identifier —
+ * uriRef-backed display forms are skipped at the tooltip-execution-planning
+ * step (in each chart family's adapter), so they never reach this key builder.
+ * Name is omitted: the backend substitutes null/empty names with localized
+ * strings only on the display side, so including them here causes
+ * lookup-vs-hover mismatches on null/empty rows.
+ */
+/**
+ * @internal
+ */
+export function buildKeySegment(displayFormId, uri) {
+    return `${displayFormId}:${uri}`;
+}
+/**
+ * @internal
+ */
+export function joinKeySegments(parts) {
+    return [...parts].sort().join("|");
+}

package/esm/customTooltip/tooltipLookup.d.ts

@@ -0,0 +1,21 @@
+import { type IDataView } from "@gooddata/sdk-backend-spi";
+import { type ISeparators } from "@gooddata/sdk-model";
+import { type ITooltipExecutionMeta } from "./tooltipExecution.js";
+import { type IResolvedReferenceValues } from "./types.js";
+/**
+ * Localized placeholders for unresolved reference values. Mirrors the RichText
+ * widget's `richText.no_data` / `richText.multiple_data` messages.
+ *
+ * @internal
+ */
+export interface ITooltipLookupLocalizedStrings {
+    noData: string;
+    multipleItems: string;
+}
+/**
+ * Build a per-data-point lookup keyed by `${displayFormId}:${uri}` segments
+ * (joined by `|`, sorted). Iteration is orientation-agnostic via slices/series.
+ *
+ * @internal
+ */
+export declare function buildLookupTable(dataView: IDataView, meta: ITooltipExecutionMeta, separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, IResolvedReferenceValues>;

package/esm/customTooltip/tooltipLookup.js

@@ -0,0 +1,83 @@
+// (C) 2026 GoodData Corporation
+import { ClientFormatterFacade } from "@gooddata/number-formatter";
+import { isResultAttributeHeader } from "@gooddata/sdk-model";
+import { DataViewFacade } from "@gooddata/sdk-ui";
+import { buildKeySegment, joinKeySegments } from "./tooltipKey.js";
+const DEFAULT_LOCALIZED_STRINGS = {
+    noData: "(No data)",
+    multipleItems: "(Multiple items)",
+};
+/**
+ * Build a per-data-point lookup keyed by `${displayFormId}:${uri}` segments
+ * (joined by `|`, sorted). Iteration is orientation-agnostic via slices/series.
+ *
+ * @internal
+ */
+export function buildLookupTable(dataView, meta, separators, localizedStrings = DEFAULT_LOCALIZED_STRINGS) {
+    const lookup = new Map();
+    const facade = DataViewFacade.for(dataView);
+    const slices = facade.data().slices().toArray();
+    const seriesArray = facade.data().series().toArray();
+    const dimDescriptors = facade.meta().dimensionItemDescriptors(0);
+    const countLocalIds = new Set(Object.values(meta.labelCountMap));
+    const seriesByLocalId = new Map(seriesArray.map((s) => [s.descriptor.measureDescriptor.measureHeaderItem.localIdentifier, s]));
+    for (let sliceIdx = 0; sliceIdx < slices.length; sliceIdx++) {
+        const slice = slices[sliceIdx];
+        const sliceHeaders = slice.descriptor.headers;
+        const keyParts = [];
+        for (let i = 0; i < sliceHeaders.length; i++) {
+            const header = sliceHeaders[i];
+            const descriptor = dimDescriptors[i];
+            if (header && isResultAttributeHeader(header) && descriptor && "attributeHeader" in descriptor) {
+                const dfId = descriptor.attributeHeader.identifier;
+                const uri = header.attributeHeaderItem.uri ?? "";
+                keyParts.push(buildKeySegment(dfId, uri));
+            }
+        }
+        const pointKey = joinKeySegments(keyParts);
+        const values = {};
+        for (const series of seriesArray) {
+            const measureDesc = series.descriptor.measureDescriptor;
+            const localId = measureDesc.measureHeaderItem.localIdentifier;
+            const dataPoint = series.dataPoints()[sliceIdx];
+            const rawValue = dataPoint?.rawValue;
+            if (countLocalIds.has(localId)) {
+                continue;
+            }
+            const labelId = meta.labelIdMap[localId];
+            if (labelId) {
+                const countLocalId = meta.labelCountMap[localId];
+                const countSeries = countLocalId ? seriesByLocalId.get(countLocalId) : undefined;
+                const countValue = countSeries
+                    ? Number(countSeries.dataPoints()[sliceIdx]?.rawValue ?? 0)
+                    : 1;
+                if (countValue > 1) {
+                    values[`label/${labelId}`] = localizedStrings.multipleItems;
+                }
+                else if (rawValue == null || rawValue === "") {
+                    values[`label/${labelId}`] = localizedStrings.noData;
+                }
+                else {
+                    values[`label/${labelId}`] = String(rawValue);
+                }
+                continue;
+            }
+            const metricId = meta.measureIdMap[localId];
+            if (metricId) {
+                const format = measureDesc.measureHeaderItem.format;
+                if (rawValue == null) {
+                    values[`metric/${metricId}`] = localizedStrings.noData;
+                }
+                else if (format) {
+                    const { formattedValue } = ClientFormatterFacade.formatValue(Number(rawValue), format, separators);
+                    values[`metric/${metricId}`] = formattedValue;
+                }
+                else {
+                    values[`metric/${metricId}`] = String(rawValue);
+                }
+            }
+        }
+        lookup.set(pointKey, values);
+    }
+    return lookup;
+}

package/esm/customTooltip/types.d.ts

@@ -28,7 +28,9 @@ export interface ICustomTooltipConfig {
      * - Bold (`**text**`), italic (`*text*`)
      * - Unordered lists (`- item`) and ordered lists (`1. item`) — not nested
      * - Images (`![alt](url)`) — `https:`, `http:`, and `data:image/...` URLs only
-     * - Links (`[text](url)`) — rendered as styled text, NOT clickable inside tooltips
+     * - Links (`[text](url)`) — `http(s)` URLs only; rendered as anchors opening in
+     *   a new tab. End-users can only reach them when the tooltip stays open long
+     *   enough to interact with (accessible/sticky Highcharts tooltips, geo popups).
      * - Horizontal rules (`---`)
      * - Backslash escapes (`\*`, `\_`, `\[`, `\!`, etc.) to render a metacharacter
      *   as literal text instead of formatting
@@ -40,6 +42,12 @@ export interface ICustomTooltipConfig {
      * automatically backslash-escaped, so data containing markdown metacharacters
      * renders as literal text — no manual escaping is required.
      *
+     * Use display-form identifiers (NOT parent attribute identifiers) inside
+     * `{label/id}`. An attribute id renders correctly for attributes that are
+     * already in the chart, but it cannot be fetched as a label for external
+     * attributes — and a single such ref causes the secondary tooltip fetch
+     * to fail backend-side, dropping every other external ref alongside it.
+     *
      * @see https://www.gooddata.com/docs/cloud/create-visualizations/custom-tooltips/
      */
     content?: string;

package/esm/customTooltip/useTooltipLookupExecutions.d.ts

@@ -0,0 +1,43 @@
+import { type IPreparedExecution } from "@gooddata/sdk-backend-spi";
+import { type ISeparators } from "@gooddata/sdk-model";
+import { type ITooltipExecutionBundle, type ITooltipExecutionMeta } from "./tooltipExecution.js";
+import { type ITooltipLookupLocalizedStrings } from "./tooltipLookup.js";
+import { type IResolvedReferenceValues } from "./types.js";
+/**
+ * One prepared tooltip execution paired with a caller-owned key and the
+ * context that travels with the built lookup.
+ *
+ * @internal
+ */
+export interface ITooltipLookupExecutionEntry<TContext> {
+    key: string;
+    execution: IPreparedExecution;
+    meta: ITooltipExecutionMeta;
+    context: TContext;
+}
+/**
+ * Built lookup for one tooltip execution entry.
+ *
+ * @internal
+ */
+export interface ITooltipLookupExecutionResult<TContext> {
+    lookup: Map<string, IResolvedReferenceValues>;
+    context: TContext;
+}
+/**
+ * Single-bundle variant for chart families that have one tooltip execution per
+ * chart (e.g. Highcharts). Returns `undefined` while no bundle is provided or
+ * before the first result lands; consumers handle that as "no external values".
+ *
+ * @internal
+ */
+export declare function useTooltipLookup(bundle: ITooltipExecutionBundle | undefined, separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, IResolvedReferenceValues> | undefined;
+/**
+ * Multi-bundle variant for chart families that key tooltip executions per
+ * sub-target (e.g. geo per-layer). `context` is required so the produced
+ * lookup carries whatever the caller needs to interpret the result —
+ * downstream code does not have to defensively check for missing context.
+ *
+ * @internal
+ */
+export declare function useTooltipLookupExecutions<TContext>(entries: readonly ITooltipLookupExecutionEntry<TContext>[], separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, ITooltipLookupExecutionResult<TContext>>;

package/esm/customTooltip/useTooltipLookupExecutions.js

@@ -0,0 +1,63 @@
+// (C) 2026 GoodData Corporation
+import { useMemo } from "react";
+import { useCancelablePromise } from "@gooddata/sdk-ui";
+import { buildLookupTable } from "./tooltipLookup.js";
+const EMPTY_LOOKUPS = new Map();
+async function executeOne(execution) {
+    const result = await execution.execute();
+    return result.readAll();
+}
+function getEntriesFingerprint(entries) {
+    return entries.map((entry) => `${entry.key}::${entry.execution.fingerprint()}`).join("||");
+}
+async function executeAll(entries) {
+    const settled = await Promise.allSettled(entries.map(async (entry) => ({ ...entry, dataView: await executeOne(entry.execution) })));
+    // Failed entries drop out silently; callers fall back when a lookup is missing.
+    return settled.flatMap((result) => (result.status === "fulfilled" ? [result.value] : []));
+}
+/**
+ * Single-bundle variant for chart families that have one tooltip execution per
+ * chart (e.g. Highcharts). Returns `undefined` while no bundle is provided or
+ * before the first result lands; consumers handle that as "no external values".
+ *
+ * @internal
+ */
+export function useTooltipLookup(bundle, separators, localizedStrings) {
+    const fingerprint = bundle?.execution.fingerprint();
+    const { result } = useCancelablePromise({
+        promise: bundle ? () => executeOne(bundle.execution) : undefined,
+    }, [fingerprint]);
+    return useMemo(() => {
+        if (!result || !bundle) {
+            return undefined;
+        }
+        return buildLookupTable(result, bundle.meta, separators, localizedStrings);
+    }, [result, bundle, separators, localizedStrings]);
+}
+/**
+ * Multi-bundle variant for chart families that key tooltip executions per
+ * sub-target (e.g. geo per-layer). `context` is required so the produced
+ * lookup carries whatever the caller needs to interpret the result —
+ * downstream code does not have to defensively check for missing context.
+ *
+ * @internal
+ */
+export function useTooltipLookupExecutions(entries, separators, localizedStrings) {
+    const fingerprint = getEntriesFingerprint(entries);
+    const { result } = useCancelablePromise({
+        promise: entries.length > 0 ? () => executeAll(entries) : undefined,
+    }, [fingerprint]);
+    return useMemo(() => {
+        if (!result) {
+            return EMPTY_LOOKUPS;
+        }
+        const lookups = new Map();
+        for (const entry of result) {
+            lookups.set(entry.key, {
+                lookup: buildLookupTable(entry.dataView, entry.meta, separators, localizedStrings),
+                context: entry.context,
+            });
+        }
+        return lookups;
+    }, [result, separators, localizedStrings]);
+}

package/esm/index.d.ts

@@ -32,3 +32,8 @@ export { type ICustomTooltipConfig, type CustomTooltipPlacement, type IResolvedR
 export { markdownToHtml } from "./customTooltip/markdownToHtml.js";
 export { resolveReferences } from "./customTooltip/referenceResolver.js";
 export { resolveMeasureLdmIdentifier } from "./customTooltip/measureLdmIdentifier.js";
+export { buildTooltipExecution, type IBuildTooltipExecutionOptions, type ITooltipExecutionBundle, type ITooltipExecutionMeta, } from "./customTooltip/tooltipExecution.js";
+export { buildLookupTable, type ITooltipLookupLocalizedStrings } from "./customTooltip/tooltipLookup.js";
+export { buildKeySegment, joinKeySegments } from "./customTooltip/tooltipKey.js";
+export { composeCustomTooltipSectionHtml } from "./customTooltip/composeSectionHtml.js";
+export { useTooltipLookup, useTooltipLookupExecutions, type ITooltipLookupExecutionEntry, type ITooltipLookupExecutionResult, } from "./customTooltip/useTooltipLookupExecutions.js";

package/esm/index.js

@@ -32,3 +32,8 @@ export { PatternFill } from "./coloring/PatternFill.js";
 export { markdownToHtml } from "./customTooltip/markdownToHtml.js";
 export { resolveReferences } from "./customTooltip/referenceResolver.js";
 export { resolveMeasureLdmIdentifier } from "./customTooltip/measureLdmIdentifier.js";
+export { buildTooltipExecution, } from "./customTooltip/tooltipExecution.js";
+export { buildLookupTable } from "./customTooltip/tooltipLookup.js";
+export { buildKeySegment, joinKeySegments } from "./customTooltip/tooltipKey.js";
+export { composeCustomTooltipSectionHtml } from "./customTooltip/composeSectionHtml.js";
+export { useTooltipLookup, useTooltipLookupExecutions, } from "./customTooltip/useTooltipLookupExecutions.js";

package/esm/sdk-ui-vis-commons.d.ts

@@ -16,10 +16,14 @@ import { IColorAssignment } from '@gooddata/sdk-ui';
 import { IColorPalette } from '@gooddata/sdk-model';
 import { IColorPaletteItem } from '@gooddata/sdk-model';
 import { IDataView } from '@gooddata/sdk-backend-spi';
+import { IExecutionDefinition } from '@gooddata/sdk-model';
+import { IExecutionFactory } from '@gooddata/sdk-backend-spi';
 import { IHeaderPredicate } from '@gooddata/sdk-ui';
 import { IMappingHeader } from '@gooddata/sdk-ui';
 import { IMeasure } from '@gooddata/sdk-model';
+import { IPreparedExecution } from '@gooddata/sdk-backend-spi';
 import { IRgbColorValue } from '@gooddata/sdk-model';
+import { ISeparators } from '@gooddata/sdk-model';
 import { ITheme } from '@gooddata/sdk-model';
 import { JSX } from 'react/jsx-runtime';
 import { NamedExoticComponent } from 'react';
@@ -34,6 +38,39 @@ export declare class AttributeColorStrategy extends ColorStrategy {
     protected createColorAssignment(colorPalette: IColorPalette, colorMapping: IColorMapping[] | undefined, viewByAttribute: any, stackByAttribute: any, dv: DataViewFacade): ICreateColorAssignmentReturnValue;
 }
 
+/**
+ * Lookup-key helpers shared by `buildLookupTable` and chart-family hover-time
+ * key builders. Both sides must produce identical strings.
+ *
+ * Format: `${displayFormId}:${uri}` per attribute, joined by `|` after
+ * lexicographic sort. The `displayFormId` is always the idRef identifier —
+ * uriRef-backed display forms are skipped at the tooltip-execution-planning
+ * step (in each chart family's adapter), so they never reach this key builder.
+ * Name is omitted: the backend substitutes null/empty names with localized
+ * strings only on the display side, so including them here causes
+ * lookup-vs-hover mismatches on null/empty rows.
+ */
+/**
+ * @internal
+ */
+export declare function buildKeySegment(displayFormId: string, uri: string): string;
+
+/**
+ * Build a per-data-point lookup keyed by `${displayFormId}:${uri}` segments
+ * (joined by `|`, sorted). Iteration is orientation-agnostic via slices/series.
+ *
+ * @internal
+ */
+export declare function buildLookupTable(dataView: IDataView, meta: ITooltipExecutionMeta, separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, IResolvedReferenceValues>;
+
+/**
+ * Returns `null` when the content has no references or all references are
+ * already in the chart (resolvable from drill data without a secondary call).
+ *
+ * @internal
+ */
+export declare function buildTooltipExecution(executionFactory: IExecutionFactory, chartDefinition: IExecutionDefinition, tooltipContent: string, options?: IBuildTooltipExecutionOptions): ITooltipExecutionBundle | null;
+
 /**
  * @internal
  */
@@ -84,6 +121,16 @@ export declare const ColorUtils: {
     getColorMappingPredicate: typeof getColorMappingPredicate;
 };
 
+/**
+ * Merge order matters: in-chart values override external ones, because the
+ * in-chart value is what the user already sees on the rendered point/feature.
+ * If a tooltip references the same id from both, showing the external (fetched)
+ * value would let it drift from what the chart pixel displays.
+ *
+ * @internal
+ */
+export declare function composeCustomTooltipSectionHtml(content: string, inChartValues: IResolvedReferenceValues, externalValues: IResolvedReferenceValues, fallbackText: string): string;
+
 /**
  * Placement of the custom tooltip section relative to the default tooltip content.
  *
@@ -250,6 +297,18 @@ export declare function HeadlinePagination({ renderSecondaryItem, renderTertiary
  */
 export declare const HeatmapLegend: NamedExoticComponent<IHeatmapLegendProps>;
 
+/**
+ * @internal
+ */
+export declare interface IBuildTooltipExecutionOptions {
+    /**
+     * LocalIdentifiers from `definition.attributes` to use as the row dimension,
+     * in the desired order. Omit to use all attributes in definition order
+     * (Highcharts default). Geo passes an explicit list to drop position attrs.
+     */
+    slicingAttributeLocalIds?: readonly string[];
+}
+
 /**
  * Chart fill config is used to customize the chart fill.
  *
@@ -366,7 +425,9 @@ export declare interface ICustomTooltipConfig {
      * - Bold (`**text**`), italic (`*text*`)
      * - Unordered lists (`- item`) and ordered lists (`1. item`) — not nested
      * - Images (`![alt](url)`) — `https:`, `http:`, and `data:image/...` URLs only
-     * - Links (`[text](url)`) — rendered as styled text, NOT clickable inside tooltips
+     * - Links (`[text](url)`) — `http(s)` URLs only; rendered as anchors opening in
+     *   a new tab. End-users can only reach them when the tooltip stays open long
+     *   enough to interact with (accessible/sticky Highcharts tooltips, geo popups).
      * - Horizontal rules (`---`)
      * - Backslash escapes (`\*`, `\_`, `\[`, `\!`, etc.) to render a metacharacter
      *   as literal text instead of formatting
@@ -378,6 +439,12 @@ export declare interface ICustomTooltipConfig {
      * automatically backslash-escaped, so data containing markdown metacharacters
      * renders as literal text — no manual escaping is required.
      *
+     * Use display-form identifiers (NOT parent attribute identifiers) inside
+     * `{label/id}`. An attribute id renders correctly for attributes that are
+     * already in the chart, but it cannot be fetched as a label for external
+     * attributes — and a single such ref causes the secondary tooltip fetch
+     * to fail backend-side, dropping every other external ref alongside it.
+     *
      * @see https://www.gooddata.com/docs/cloud/create-visualizations/custom-tooltips/
      */
     content?: string;
@@ -717,6 +784,70 @@ export declare function isValidMappedColor(colorItem: IColor | null | undefined,
  */
 export declare type ItemBorderRadiusPredicate = (item: any) => boolean;
 
+/**
+ * Prepared tooltip execution paired with the meta needed to interpret its result.
+ * Carry them together — meta from one call mis-interprets results from another.
+ *
+ * @internal
+ */
+export declare interface ITooltipExecutionBundle {
+    execution: IPreparedExecution;
+    meta: ITooltipExecutionMeta;
+}
+
+/**
+ * Maps used by `buildLookupTable` to interpret the execution result.
+ *
+ * @internal
+ */
+export declare interface ITooltipExecutionMeta {
+    /** value localId → count localId, for "Multiple items" detection. */
+    labelCountMap: Record<string, string>;
+    /** tooltip metric localId → LDM measure identifier. */
+    measureIdMap: Record<string, string>;
+    /** label value localId → LDM label identifier. */
+    labelIdMap: Record<string, string>;
+}
+
+/**
+ * One prepared tooltip execution paired with a caller-owned key and the
+ * context that travels with the built lookup.
+ *
+ * @internal
+ */
+export declare interface ITooltipLookupExecutionEntry<TContext> {
+    key: string;
+    execution: IPreparedExecution;
+    meta: ITooltipExecutionMeta;
+    context: TContext;
+}
+
+/**
+ * Built lookup for one tooltip execution entry.
+ *
+ * @internal
+ */
+export declare interface ITooltipLookupExecutionResult<TContext> {
+    lookup: Map<string, IResolvedReferenceValues>;
+    context: TContext;
+}
+
+/**
+ * Localized placeholders for unresolved reference values. Mirrors the RichText
+ * widget's `richText.no_data` / `richText.multiple_data` messages.
+ *
+ * @internal
+ */
+export declare interface ITooltipLookupLocalizedStrings {
+    noData: string;
+    multipleItems: string;
+}
+
+/**
+ * @internal
+ */
+export declare function joinKeySegments(parts: readonly string[]): string;
+
 /**
  * @internal
  */
@@ -867,6 +998,25 @@ export declare const StaticLegend: NamedExoticComponent<IStaticLegendProps>;
  */
 export declare const SupportedLegendPositions: PositionType[];
 
+/**
+ * Single-bundle variant for chart families that have one tooltip execution per
+ * chart (e.g. Highcharts). Returns `undefined` while no bundle is provided or
+ * before the first result lands; consumers handle that as "no external values".
+ *
+ * @internal
+ */
+export declare function useTooltipLookup(bundle: ITooltipExecutionBundle | undefined, separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, IResolvedReferenceValues> | undefined;
+
+/**
+ * Multi-bundle variant for chart families that key tooltip executions per
+ * sub-target (e.g. geo per-layer). `context` is required so the produced
+ * lookup carries whatever the caller needs to interpret the result —
+ * downstream code does not have to defensively check for missing context.
+ *
+ * @internal
+ */
+export declare function useTooltipLookupExecutions<TContext>(entries: readonly ITooltipLookupExecutionEntry<TContext>[], separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, ITooltipLookupExecutionResult<TContext>>;
+
 /**
  * Returns the value if it is non-empty or a fallback text.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gooddata/sdk-ui-vis-commons",
-  "version": "11.39.0-alpha.1",
+  "version": "11.39.0-alpha.2",
   "description": "GoodData.UI SDK - common functionality for different types of visualizations",
   "license": "MIT",
   "author": "GoodData Corporation",
@@ -36,11 +36,11 @@
     "react-intl": "7.1.11",
     "react-measure": "^2.5.2",
     "tslib": "2.8.1",
-    "@gooddata/sdk-backend-spi": "11.39.0-alpha.1",
-    "@gooddata/sdk-model": "11.39.0-alpha.1",
-    "@gooddata/sdk-ui": "11.39.0-alpha.1",
-    "@gooddata/sdk-ui-theme-provider": "11.39.0-alpha.1",
-    "@gooddata/sdk-ui-kit": "11.39.0-alpha.1"
+    "@gooddata/sdk-model": "11.39.0-alpha.2",
+    "@gooddata/sdk-ui": "11.39.0-alpha.2",
+    "@gooddata/sdk-backend-spi": "11.39.0-alpha.2",
+    "@gooddata/sdk-ui-kit": "11.39.0-alpha.2",
+    "@gooddata/sdk-ui-theme-provider": "11.39.0-alpha.2"
   },
   "devDependencies": {
     "@microsoft/api-documenter": "^7.17.0",
@@ -81,11 +81,11 @@
     "typescript": "5.9.3",
     "vitest": "4.1.0",
     "vitest-dom": "0.1.1",
-    "@gooddata/eslint-config": "11.39.0-alpha.1",
-    "@gooddata/oxlint-config": "11.39.0-alpha.1",
-    "@gooddata/reference-workspace": "11.39.0-alpha.1",
-    "@gooddata/stylelint-config": "11.39.0-alpha.1",
-    "@gooddata/sdk-backend-mockingbird": "11.39.0-alpha.1"
+    "@gooddata/oxlint-config": "11.39.0-alpha.2",
+    "@gooddata/eslint-config": "11.39.0-alpha.2",
+    "@gooddata/reference-workspace": "11.39.0-alpha.2",
+    "@gooddata/sdk-backend-mockingbird": "11.39.0-alpha.2",
+    "@gooddata/stylelint-config": "11.39.0-alpha.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/styles/scss/customTooltip.scss

@@ -4,62 +4,66 @@
 // containers across chart families (Highcharts, geo, etc.).
 
 .gd-viz-tooltip-custom-section {
-    font-size: 13px;
-    line-height: 1.4;
+    font-size: 14px;
+    line-height: 1.2;
     text-align: left;
     white-space: normal;
     word-wrap: break-word;
     min-width: 200px;
+    color: var(--gd-palette-complementary-7);
 
     h1,
     h2,
     h3,
     h4 {
-        margin: 0 0 2px;
+        margin: 0;
         font-weight: 700;
-        color: var(--gd-chart-tooltip-valueColor);
+        color: var(--gd-palette-complementary-9);
         font-size: 14px;
-        line-height: 1.3;
+        line-height: 1.2;
+        padding: 5px 0;
     }
 
     p {
-        margin: 0 0 1px;
+        margin: 0;
+        padding-block-end: 5px;
     }
 
     strong {
         font-weight: 700;
-        color: var(--gd-chart-tooltip-valueColor);
     }
 
     ul,
     ol {
-        margin: 2px 0;
-        padding-left: 18px;
-    }
-
-    li {
-        margin-bottom: 1px;
+        padding: 0 0 0 18px;
+        margin: 0;
     }
 
     hr {
         border: 0;
         border-top: 1px solid var(--gd-palette-complementary-3);
-        margin: 4px 0;
+        padding: 4px 0;
     }
 
     img {
         max-width: 100%;
         display: block;
-        margin: 4px 0;
+        padding: 3px 0;
     }
 
-    .gd-viz-tooltip-custom-link {
+    a {
         text-decoration: underline;
-        color: var(--gd-chart-tooltip-labelColor-from-theme);
+        color: inherit;
+        cursor: pointer;
+        pointer-events: auto;
+
+        &:hover {
+            color: var(--gd-palette-primary-base);
+        }
     }
 }
 
 .gd-viz-tooltip-custom-separator {
     border-top: 1px solid var(--gd-palette-complementary-3);
-    margin: 8px 0;
+    padding: 7px 0;
 }