@gooddata/sdk-ui-vis-commons 11.41.0-alpha.0 → 11.41.0-alpha.1

package/esm/customTooltip/composeSectionHtml.d.ts

@@ -1,4 +1,4 @@
-import { type IResolvedReferenceValues } from "./types.js";
+import { type IResolvedReferenceValues, type ITooltipLocalizedStrings } 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.
@@ -7,4 +7,4 @@ import { type IResolvedReferenceValues } from "./types.js";
  *
  * @internal
  */
-export declare function composeCustomTooltipSectionHtml(content: string, inChartValues: IResolvedReferenceValues, externalValues: IResolvedReferenceValues, fallbackText: string): string;
+export declare function composeCustomTooltipSectionHtml(content: string, inChartValues: IResolvedReferenceValues, externalValues: IResolvedReferenceValues, localizedStrings: ITooltipLocalizedStrings): string;

package/esm/customTooltip/composeSectionHtml.js

@@ -9,8 +9,8 @@ import { resolveReferences } from "./referenceResolver.js";
  *
  * @internal
  */
-export function composeCustomTooltipSectionHtml(content, inChartValues, externalValues, fallbackText) {
+export function composeCustomTooltipSectionHtml(content, inChartValues, externalValues, localizedStrings) {
     const merged = { ...externalValues, ...inChartValues };
-    const resolved = resolveReferences(content, merged, fallbackText);
+    const resolved = resolveReferences(content, merged, localizedStrings);
     return `<div class="gd-viz-tooltip-custom-section">${markdownToHtml(resolved)}</div>`;
 }

package/esm/customTooltip/localizedStrings.d.ts

@@ -0,0 +1,11 @@
+import { type IntlShape } from "react-intl";
+import { type ITooltipLocalizedStrings } from "./types.js";
+/**
+ * Builds the localized placeholder strings for the non-value reference states,
+ * shared by every tooltip consumer (Highcharts, geo) so the wording and the
+ * message ids live in one place. `intl` is optional — the Highcharts tooltip
+ * formatter receives it optionally — and falls back to English.
+ *
+ * @internal
+ */
+export declare function buildTooltipLocalizedStrings(intl?: IntlShape): ITooltipLocalizedStrings;

package/esm/customTooltip/localizedStrings.js

@@ -0,0 +1,22 @@
+// (C) 2026 GoodData Corporation
+import { defineMessages } from "react-intl";
+const messages = defineMessages({
+    noFetch: { id: "richText.no_fetch" },
+    noData: { id: "richText.no_data" },
+    multipleItems: { id: "richText.multiple_data" },
+});
+/**
+ * Builds the localized placeholder strings for the non-value reference states,
+ * shared by every tooltip consumer (Highcharts, geo) so the wording and the
+ * message ids live in one place. `intl` is optional — the Highcharts tooltip
+ * formatter receives it optionally — and falls back to English.
+ *
+ * @internal
+ */
+export function buildTooltipLocalizedStrings(intl) {
+    return {
+        noFetch: intl ? `(${intl.formatMessage(messages.noFetch)})` : "(Data could not be retrieved)",
+        noData: intl ? `(${intl.formatMessage(messages.noData)})` : "(No data)",
+        multipleItems: intl ? `(${intl.formatMessage(messages.multipleItems)})` : "(Multiple items)",
+    };
+}

package/esm/customTooltip/referenceResolver.d.ts

@@ -1,4 +1,4 @@
-import { type IResolvedReferenceValues } from "./types.js";
+import { type IResolvedReferenceValues, type ITooltipLocalizedStrings } from "./types.js";
 /**
  * Substitutes `{metric/id}` and `{label/id}` references in markdown content
  * with resolved values from the lookup table.
@@ -9,11 +9,11 @@ import { type IResolvedReferenceValues } from "./types.js";
  * unintended formatting. `markdownToHtml` understands the backslash escapes.
  *
  * @param content - Markdown content with reference placeholders
- * @param values - Lookup of `metric/id` and `label/id` keys to formatted values.
+ * @param values - Lookup of `metric/id` and `label/id` keys to resolved statuses.
  *   Keys must use a lowercase prefix; LDM identifiers are case-sensitive.
- * @param fallbackText - Localized text shown when a reference is recognized
- *   but no value is available (unknown identifier, point with no value, etc.).
+ * @param strings - Localized placeholders for the non-value states (no data,
+ *   multiple items, could-not-retrieve).
  *
  * @internal
  */
-export declare function resolveReferences(content: string, values: IResolvedReferenceValues, fallbackText: string): string;
+export declare function resolveReferences(content: string, values: IResolvedReferenceValues, strings: ITooltipLocalizedStrings): string;

package/esm/customTooltip/referenceResolver.js

@@ -9,6 +9,24 @@ const MARKDOWN_METACHARS = /[\\*_`\[\]()!#~+\-]/g;
 function escapeMarkdownMetachars(value) {
     return value.replace(MARKDOWN_METACHARS, "\\$&");
 }
+/**
+ * Renders a single resolved reference status to its display string. A reference
+ * with no status at this point (e.g. an in-chart sibling not present on the
+ * hovered series) is surfaced as unretrievable rather than masked as "no data".
+ */
+function renderReference(ref, strings) {
+    switch (ref?.kind) {
+        case "value":
+            return ref.text;
+        case "empty":
+            return strings.noData;
+        case "multiple":
+            return strings.multipleItems;
+        case "error":
+        default:
+            return strings.noFetch;
+    }
+}
 /**
  * Substitutes `{metric/id}` and `{label/id}` references in markdown content
  * with resolved values from the lookup table.
@@ -19,14 +37,14 @@ function escapeMarkdownMetachars(value) {
  * unintended formatting. `markdownToHtml` understands the backslash escapes.
  *
  * @param content - Markdown content with reference placeholders
- * @param values - Lookup of `metric/id` and `label/id` keys to formatted values.
+ * @param values - Lookup of `metric/id` and `label/id` keys to resolved statuses.
  *   Keys must use a lowercase prefix; LDM identifiers are case-sensitive.
- * @param fallbackText - Localized text shown when a reference is recognized
- *   but no value is available (unknown identifier, point with no value, etc.).
+ * @param strings - Localized placeholders for the non-value states (no data,
+ *   multiple items, could-not-retrieve).
  *
  * @internal
  */
-export function resolveReferences(content, values, fallbackText) {
+export function resolveReferences(content, values, strings) {
     if (!content) {
         return "";
     }
@@ -34,7 +52,7 @@ export function resolveReferences(content, values, fallbackText) {
         // The regex matches the prefix case-insensitively; storage uses
         // lowercase prefixes so users can write either `{metric/foo}` or
         // `{Metric/foo}`. LDM identifiers stay as-is — they are case-sensitive.
-        const value = values[`${prefix.toLowerCase()}/${identifier}`];
-        return escapeMarkdownMetachars(value === undefined ? fallbackText : value);
+        const ref = values[`${prefix.toLowerCase()}/${identifier}`];
+        return escapeMarkdownMetachars(renderReference(ref, strings));
     });
 }

package/esm/customTooltip/referenceStatus.d.ts

@@ -0,0 +1,22 @@
+import { type ISeparators } from "@gooddata/sdk-model";
+import { type ResolvedReference } from "./types.js";
+/**
+ * Maps a raw measure value to a {@link ResolvedReference} status: `null`/
+ * `undefined` → empty ("No data"); otherwise the formatted (or stringified)
+ * value. Shared by every tooltip resolver so the value→status mapping has a
+ * single home. Callers whose source can yield non-numeric / non-finite values
+ * (e.g. geo feature payloads) normalize those to `null` before calling.
+ *
+ * @internal
+ */
+export declare function measureReference(rawValue: number | string | null | undefined, format: string | undefined, separators?: ISeparators): ResolvedReference;
+/**
+ * Maps a label/attribute display value to a {@link ResolvedReference} status:
+ * `null` / `undefined` / empty string → empty ("No data"); otherwise the value.
+ * Shared by every tooltip resolver so empty-value handling can't drift between
+ * the in-chart and external paths. The count-based "multiple" case stays with
+ * the caller (only the lookup builder knows the per-row count).
+ *
+ * @internal
+ */
+export declare function labelReference(value: string | number | null | undefined): ResolvedReference;

package/esm/customTooltip/referenceStatus.js

@@ -0,0 +1,33 @@
+// (C) 2026 GoodData Corporation
+import { ClientFormatterFacade } from "@gooddata/number-formatter";
+/**
+ * Maps a raw measure value to a {@link ResolvedReference} status: `null`/
+ * `undefined` → empty ("No data"); otherwise the formatted (or stringified)
+ * value. Shared by every tooltip resolver so the value→status mapping has a
+ * single home. Callers whose source can yield non-numeric / non-finite values
+ * (e.g. geo feature payloads) normalize those to `null` before calling.
+ *
+ * @internal
+ */
+export function measureReference(rawValue, format, separators) {
+    if (rawValue == null) {
+        return { kind: "empty" };
+    }
+    if (format) {
+        const { formattedValue } = ClientFormatterFacade.formatValue(Number(rawValue), format, separators);
+        return { kind: "value", text: formattedValue };
+    }
+    return { kind: "value", text: String(rawValue) };
+}
+/**
+ * Maps a label/attribute display value to a {@link ResolvedReference} status:
+ * `null` / `undefined` / empty string → empty ("No data"); otherwise the value.
+ * Shared by every tooltip resolver so empty-value handling can't drift between
+ * the in-chart and external paths. The count-based "multiple" case stays with
+ * the caller (only the lookup builder knows the per-row count).
+ *
+ * @internal
+ */
+export function labelReference(value) {
+    return value == null || value === "" ? { kind: "empty" } : { kind: "value", text: String(value) };
+}

package/esm/customTooltip/tooltipExecution.d.ts

@@ -23,6 +23,20 @@ export interface ITooltipExecutionBundle {
     execution: IPreparedExecution;
     meta: ITooltipExecutionMeta;
 }
+/**
+ * A tooltip execution plan: one batched execution for all external references,
+ * plus per-reference bundles used as an isolation fallback. When the batch
+ * rejects (e.g. a single invalid reference 400s the whole AFM), the consumer
+ * re-runs the per-reference bundles so one bad reference can't suppress the
+ * rest. `perRef` is a thunk: the bundles are built lazily, only when the batch
+ * fails, so consumers that never fan out (e.g. geo) pay nothing for it.
+ *
+ * @internal
+ */
+export interface ITooltipExecution {
+    batch: ITooltipExecutionBundle;
+    perRef: () => readonly ITooltipExecutionBundle[];
+}
 /**
  * @internal
  */
@@ -37,7 +51,9 @@ export interface IBuildTooltipExecutionOptions {
 /**
  * Returns `null` when the content has no references or all references are
  * already in the chart (resolvable from drill data without a secondary call).
+ * Otherwise returns the batched execution plus per-reference bundles for the
+ * fan-out fallback (see {@link ITooltipExecution}).
  *
  * @internal
  */
-export declare function buildTooltipExecution(executionFactory: IExecutionFactory, chartDefinition: IExecutionDefinition, tooltipContent: string, options?: IBuildTooltipExecutionOptions): ITooltipExecutionBundle | null;
+export declare function buildTooltipExecution(executionFactory: IExecutionFactory, chartDefinition: IExecutionDefinition, tooltipContent: string, options?: IBuildTooltipExecutionOptions): ITooltipExecution | null;

package/esm/customTooltip/tooltipExecution.js

@@ -67,26 +67,27 @@ function getFilterDependencyMeasures(filters, chartMeasures) {
     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.
+ * Build tooltip-only measures for the given references (already filtered to
+ * those not 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) {
+function buildTooltipItems(refs) {
     const measures = [];
     const labelCountMap = {};
     const labelIdMap = {};
     const measureIdMap = {};
     let idx = 0;
     for (const ref of refs) {
-        if (ref.type === "metric" && !chartMetricIds.has(ref.id)) {
+        if (ref.type === "metric") {
             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)) {
+        else {
             const valueLocalId = `tt_lv_${idx}`;
             const countLocalId = `tt_lc_${idx}`;
             idx++;
@@ -119,19 +120,12 @@ function getSlicingAttributes(definition, slicingAttributeLocalIds) {
     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
+ * Builds a single execution bundle for the given external references (slicing
+ * attributes + tooltip measures + filter-dependency measures). Returns `null`
+ * when there are no measures to fetch.
  */
-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);
+function buildBundle(executionFactory, chartDefinition, externalRefs, options) {
+    const { measures, labelCountMap, labelIdMap, measureIdMap } = buildTooltipItems(externalRefs);
     if (measures.length === 0) {
         return null;
     }
@@ -150,3 +144,31 @@ export function buildTooltipExecution(executionFactory, chartDefinition, tooltip
         meta: { labelCountMap, measureIdMap, labelIdMap },
     };
 }
+/**
+ * Returns `null` when the content has no references or all references are
+ * already in the chart (resolvable from drill data without a secondary call).
+ * Otherwise returns the batched execution plus per-reference bundles for the
+ * fan-out fallback (see {@link ITooltipExecution}).
+ *
+ * @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);
+    // References not already resolvable from the chart's own drill data.
+    const externalRefs = refs.filter((ref) => (ref.type === "metric" && !chartMetricIds.has(ref.id)) ||
+        (ref.type === "label" && !chartLabelIds.has(ref.id)));
+    const batch = buildBundle(executionFactory, chartDefinition, externalRefs, options);
+    if (!batch) {
+        return null;
+    }
+    // Lazy: built only on batch failure (the Highcharts fan-out); geo never calls it.
+    const perRef = () => externalRefs
+        .map((ref) => buildBundle(executionFactory, chartDefinition, [ref], options))
+        .filter((bundle) => bundle !== null);
+    return { batch, perRef };
+}

package/esm/customTooltip/tooltipLookup.d.ts

@@ -2,20 +2,12 @@ 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.
+ * Each reference is tagged with a {@link ResolvedReference} status; localized
+ * placeholder strings are applied later, at the render site.
  *
  * @internal
  */
-export declare function buildLookupTable(dataView: IDataView, meta: ITooltipExecutionMeta, separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, IResolvedReferenceValues>;
+export declare function buildLookupTable(dataView: IDataView, meta: ITooltipExecutionMeta, separators?: ISeparators): Map<string, IResolvedReferenceValues>;

package/esm/customTooltip/tooltipLookup.js

@@ -1,19 +1,18 @@
 // (C) 2026 GoodData Corporation
-import { ClientFormatterFacade } from "@gooddata/number-formatter";
 import { isResultAttributeHeader } from "@gooddata/sdk-model";
 import { DataViewFacade } from "@gooddata/sdk-ui";
+import { labelReference, measureReference } from "./referenceStatus.js";
 import { buildKeySegment, joinKeySegments } from "./tooltipKey.js";
-const DEFAULT_LOCALIZED_STRINGS = {
-    noData: "(No data)",
-    multipleItems: "(Multiple items)",
-};
+import { labelKey, metricKey } from "./types.js";
 /**
  * Build a per-data-point lookup keyed by `${displayFormId}:${uri}` segments
  * (joined by `|`, sorted). Iteration is orientation-agnostic via slices/series.
+ * Each reference is tagged with a {@link ResolvedReference} status; localized
+ * placeholder strings are applied later, at the render site.
  *
  * @internal
  */
-export function buildLookupTable(dataView, meta, separators, localizedStrings = DEFAULT_LOCALIZED_STRINGS) {
+export function buildLookupTable(dataView, meta, separators) {
     const lookup = new Map();
     const facade = DataViewFacade.for(dataView);
     const slices = facade.data().slices().toArray();
@@ -51,30 +50,14 @@ export function buildLookupTable(dataView, meta, separators, localizedStrings =
                 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);
-                }
+                // count > 1 → "(Multiple items)"; else empty/value via the shared helper.
+                values[labelKey(labelId)] = countValue > 1 ? { kind: "multiple" } : labelReference(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);
-                }
+                values[metricKey(metricId)] = measureReference(rawValue, format, separators);
             }
         }
         lookup.set(pointKey, values);

package/esm/customTooltip/types.d.ts

@@ -59,10 +59,58 @@ export interface ICustomTooltipConfig {
     placement?: CustomTooltipPlacement;
 }
 /**
- * Lookup of resolved reference values keyed by `metric/id` or `label/id`.
+ * Resolution outcome for a single `{metric/id}` / `{label/id}` reference at a
+ * data point. A discriminated union so the renderer maps each state to its own
+ * localized message instead of collapsing every "missing" case into one
+ * fallback: `empty` → "(No data)", `multiple` → "(Multiple items)", `error` →
+ * "(Data could not be retrieved)". `error` is emitted only when a value was
+ * genuinely unretrievable (e.g. a reference whose fetch failed); it is never a
+ * default for an unclassified value.
+ *
+ * @internal
+ */
+export type ResolvedReference = {
+    readonly kind: "value";
+    readonly text: string;
+} | {
+    readonly kind: "empty";
+} | {
+    readonly kind: "multiple";
+} | {
+    readonly kind: "error";
+};
+/**
+ * Lookup of resolved reference statuses keyed by `metric/id` or `label/id`.
  *
  * @internal
  */
 export interface IResolvedReferenceValues {
-    [referenceKey: string]: string | undefined;
+    [referenceKey: string]: ResolvedReference | undefined;
+}
+/**
+ * Builds the `metric/<id>` lookup key for a metric reference. A reference key
+ * has exactly two shapes ({@link metricKey}, {@link labelKey}); keeping the
+ * convention here is the single source for every write site. The read side
+ * parses references via `REFERENCE_REGEX_MATCH` in `resolveReferences`.
+ *
+ * @internal
+ */
+export declare const metricKey: (id: string) => string;
+/**
+ * Builds the `label/<id>` lookup key for a label reference. See {@link metricKey}.
+ *
+ * @internal
+ */
+export declare const labelKey: (id: string) => string;
+/**
+ * Localized placeholder strings for the non-value reference states. Built once
+ * at the render site (where `intl` is available) and threaded into
+ * `resolveReferences`, so reference resolution stays free of i18n concerns.
+ *
+ * @internal
+ */
+export interface ITooltipLocalizedStrings {
+    readonly noData: string;
+    readonly multipleItems: string;
+    readonly noFetch: string;
 }

package/esm/customTooltip/types.js

@@ -1,2 +1,16 @@
 // (C) 2026 GoodData Corporation
-export {};
+/**
+ * Builds the `metric/<id>` lookup key for a metric reference. A reference key
+ * has exactly two shapes ({@link metricKey}, {@link labelKey}); keeping the
+ * convention here is the single source for every write site. The read side
+ * parses references via `REFERENCE_REGEX_MATCH` in `resolveReferences`.
+ *
+ * @internal
+ */
+export const metricKey = (id) => `metric/${id}`;
+/**
+ * Builds the `label/<id>` lookup key for a label reference. See {@link metricKey}.
+ *
+ * @internal
+ */
+export const labelKey = (id) => `label/${id}`;

package/esm/customTooltip/useTooltipLookupExecutions.d.ts

@@ -1,8 +1,27 @@
 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 ITooltipExecution, type ITooltipExecutionMeta } from "./tooltipExecution.js";
 import { type IResolvedReferenceValues } from "./types.js";
+/**
+ * Built lookup plus references that could not be retrieved at all (their fetch
+ * rejected even in the per-reference fallback). Errored references render as
+ * "(Data could not be retrieved)" at every point.
+ *
+ * @internal
+ */
+export interface ITooltipLookupResult {
+    lookup: Map<string, IResolvedReferenceValues>;
+    erroredRefs: ReadonlySet<string>;
+}
+/**
+ * Single-execution variant for chart families that have one tooltip execution
+ * per chart (e.g. Highcharts). Returns `undefined` while no execution is
+ * provided or before the first result lands; consumers handle that as "no
+ * external values".
+ *
+ * @internal
+ */
+export declare function useTooltipLookup(execution: ITooltipExecution | undefined, separators?: ISeparators): ITooltipLookupResult | undefined;
 /**
  * One prepared tooltip execution paired with a caller-owned key and the
  * context that travels with the built lookup.
@@ -25,19 +44,11 @@ export interface ITooltipLookupExecutionResult<TContext> {
     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
+ * Multi-execution 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>>;
+export declare function useTooltipLookupExecutions<TContext>(entries: readonly ITooltipLookupExecutionEntry<TContext>[], separators?: ISeparators): Map<string, ITooltipLookupExecutionResult<TContext>>;

package/esm/customTooltip/useTooltipLookupExecutions.js

@@ -2,47 +2,97 @@
 import { useMemo } from "react";
 import { useCancelablePromise } from "@gooddata/sdk-ui";
 import { buildLookupTable } from "./tooltipLookup.js";
-const EMPTY_LOOKUPS = new Map();
+import { labelKey, metricKey } from "./types.js";
 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("||");
+/**
+ * Reference keys (`metric/id`, `label/id`) a bundle's meta covers. Used to mark
+ * a failed per-reference bundle's references as errored.
+ */
+function refKeysOfMeta(meta) {
+    return [
+        ...Object.values(meta.measureIdMap).map(metricKey),
+        ...Object.values(meta.labelIdMap).map(labelKey),
+    ];
 }
-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] : []));
+/**
+ * Execute the batch; on failure, fan out to per-reference bundles so a single
+ * bad reference (e.g. one that 400s the batched AFM) only errors itself while
+ * the rest still resolve. No reliance on parsing the backend error — failure is
+ * isolated structurally by which per-reference execution rejects.
+ */
+async function runWithFallback(execution) {
+    try {
+        const dataView = await executeOne(execution.batch.execution);
+        return { inputs: [{ dataView, meta: execution.batch.meta }], erroredRefs: new Set() };
+    }
+    catch {
+        // Build the per-reference bundles now (lazy) and isolate each.
+        const perRef = execution.perRef();
+        const settled = await Promise.allSettled(perRef.map((bundle) => executeOne(bundle.execution)));
+        const inputs = [];
+        const erroredRefs = new Set();
+        settled.forEach((result, index) => {
+            const bundle = perRef[index];
+            if (result.status === "fulfilled") {
+                inputs.push({ dataView: result.value, meta: bundle.meta });
+            }
+            else {
+                refKeysOfMeta(bundle.meta).forEach((key) => erroredRefs.add(key));
+            }
+        });
+        return { inputs, erroredRefs };
+    }
+}
+/**
+ * Merge per-execution lookups into one map (by point key, shallow-merging the
+ * per-point reference statuses) and pair it with the errored references.
+ */
+function buildResult(outcome, separators) {
+    const lookup = new Map();
+    for (const { dataView, meta } of outcome.inputs) {
+        for (const [pointKey, values] of buildLookupTable(dataView, meta, separators)) {
+            const existing = lookup.get(pointKey);
+            lookup.set(pointKey, existing ? { ...existing, ...values } : values);
+        }
+    }
+    return { lookup, erroredRefs: outcome.erroredRefs };
 }
 /**
- * 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".
+ * Single-execution variant for chart families that have one tooltip execution
+ * per chart (e.g. Highcharts). Returns `undefined` while no execution 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();
+export function useTooltipLookup(execution, separators) {
+    const fingerprint = execution?.batch.execution.fingerprint();
     const { result } = useCancelablePromise({
-        promise: bundle ? () => executeOne(bundle.execution) : undefined,
+        promise: execution ? () => runWithFallback(execution) : undefined,
     }, [fingerprint]);
-    return useMemo(() => {
-        if (!result || !bundle) {
-            return undefined;
-        }
-        return buildLookupTable(result, bundle.meta, separators, localizedStrings);
-    }, [result, bundle, separators, localizedStrings]);
+    return useMemo(() => (result ? buildResult(result, separators) : undefined), [result, separators]);
+}
+const EMPTY_LOOKUPS = new Map();
+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] : []));
 }
 /**
- * Multi-bundle variant for chart families that key tooltip executions per
+ * Multi-execution 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) {
+export function useTooltipLookupExecutions(entries, separators) {
     const fingerprint = getEntriesFingerprint(entries);
     const { result } = useCancelablePromise({
         promise: entries.length > 0 ? () => executeAll(entries) : undefined,
@@ -54,10 +104,10 @@ export function useTooltipLookupExecutions(entries, separators, localizedStrings
         const lookups = new Map();
         for (const entry of result) {
             lookups.set(entry.key, {
-                lookup: buildLookupTable(entry.dataView, entry.meta, separators, localizedStrings),
+                lookup: buildLookupTable(entry.dataView, entry.meta, separators),
                 context: entry.context,
             });
         }
         return lookups;
-    }, [result, separators, localizedStrings]);
+    }, [result, separators]);
 }

package/esm/index.d.ts

@@ -28,12 +28,14 @@ export { getHeadlineResponsiveClassName } from "./utils/headlineResponsiveClassN
 export { getLegendDetails, type ILegendDetails, type ILegendDetailOptions, } from "./legend/PopUpLegend/helpers.js";
 export { PATTERN_FILLS, getPatternFillByIndex, getPatternFillByName, getPatternFill, type IPatternFill, type PatternFillName, type IChartFillConfig, } from "./coloring/patternFills.js";
 export { PatternFill, type IPatternFillProps } from "./coloring/PatternFill.js";
-export { type ICustomTooltipConfig, type CustomTooltipPlacement, type IResolvedReferenceValues, } from "./customTooltip/types.js";
+export { type ICustomTooltipConfig, type CustomTooltipPlacement, type IResolvedReferenceValues, type ResolvedReference, type ITooltipLocalizedStrings, metricKey, labelKey, } from "./customTooltip/types.js";
 export { markdownToHtml } from "./customTooltip/markdownToHtml.js";
 export { resolveReferences } from "./customTooltip/referenceResolver.js";
+export { measureReference, labelReference } from "./customTooltip/referenceStatus.js";
+export { buildTooltipLocalizedStrings } from "./customTooltip/localizedStrings.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 { buildTooltipExecution, type IBuildTooltipExecutionOptions, type ITooltipExecution, type ITooltipExecutionBundle, type ITooltipExecutionMeta, } 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, type ITooltipLookupExecutionEntry, type ITooltipLookupExecutionResult, } from "./customTooltip/useTooltipLookupExecutions.js";
+export { useTooltipLookup, useTooltipLookupExecutions, type ITooltipLookupResult, type ITooltipLookupExecutionEntry, type ITooltipLookupExecutionResult, } from "./customTooltip/useTooltipLookupExecutions.js";

package/esm/index.js

@@ -29,8 +29,11 @@ export { getHeadlineResponsiveClassName } from "./utils/headlineResponsiveClassN
 export { getLegendDetails, } from "./legend/PopUpLegend/helpers.js";
 export { PATTERN_FILLS, getPatternFillByIndex, getPatternFillByName, getPatternFill, } from "./coloring/patternFills.js";
 export { PatternFill } from "./coloring/PatternFill.js";
+export { metricKey, labelKey, } from "./customTooltip/types.js";
 export { markdownToHtml } from "./customTooltip/markdownToHtml.js";
 export { resolveReferences } from "./customTooltip/referenceResolver.js";
+export { measureReference, labelReference } from "./customTooltip/referenceStatus.js";
+export { buildTooltipLocalizedStrings } from "./customTooltip/localizedStrings.js";
 export { resolveMeasureLdmIdentifier } from "./customTooltip/measureLdmIdentifier.js";
 export { buildTooltipExecution, } from "./customTooltip/tooltipExecution.js";
 export { buildLookupTable } from "./customTooltip/tooltipLookup.js";

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

@@ -21,6 +21,7 @@ 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 { IntlShape } from 'react-intl';
 import { IPreparedExecution } from '@gooddata/sdk-backend-spi';
 import { IRgbColorValue } from '@gooddata/sdk-model';
 import { ISeparators } from '@gooddata/sdk-model';
@@ -58,18 +59,32 @@ export declare function buildKeySegment(displayFormId: string, uri: string): str
 /**
  * Build a per-data-point lookup keyed by `${displayFormId}:${uri}` segments
  * (joined by `|`, sorted). Iteration is orientation-agnostic via slices/series.
+ * Each reference is tagged with a {@link ResolvedReference} status; localized
+ * placeholder strings are applied later, at the render site.
  *
  * @internal
  */
-export declare function buildLookupTable(dataView: IDataView, meta: ITooltipExecutionMeta, separators?: ISeparators, localizedStrings?: ITooltipLookupLocalizedStrings): Map<string, IResolvedReferenceValues>;
+export declare function buildLookupTable(dataView: IDataView, meta: ITooltipExecutionMeta, separators?: ISeparators): 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).
+ * Otherwise returns the batched execution plus per-reference bundles for the
+ * fan-out fallback (see {@link ITooltipExecution}).
  *
  * @internal
  */
-export declare function buildTooltipExecution(executionFactory: IExecutionFactory, chartDefinition: IExecutionDefinition, tooltipContent: string, options?: IBuildTooltipExecutionOptions): ITooltipExecutionBundle | null;
+export declare function buildTooltipExecution(executionFactory: IExecutionFactory, chartDefinition: IExecutionDefinition, tooltipContent: string, options?: IBuildTooltipExecutionOptions): ITooltipExecution | null;
+
+/**
+ * Builds the localized placeholder strings for the non-value reference states,
+ * shared by every tooltip consumer (Highcharts, geo) so the wording and the
+ * message ids live in one place. `intl` is optional — the Highcharts tooltip
+ * formatter receives it optionally — and falls back to English.
+ *
+ * @internal
+ */
+export declare function buildTooltipLocalizedStrings(intl?: IntlShape): ITooltipLocalizedStrings;
 
 /**
  * @internal
@@ -129,7 +144,7 @@ export declare const ColorUtils: {
  *
  * @internal
  */
-export declare function composeCustomTooltipSectionHtml(content: string, inChartValues: IResolvedReferenceValues, externalValues: IResolvedReferenceValues, fallbackText: string): string;
+export declare function composeCustomTooltipSectionHtml(content: string, inChartValues: IResolvedReferenceValues, externalValues: IResolvedReferenceValues, localizedStrings: ITooltipLocalizedStrings): string;
 
 /**
  * Placement of the custom tooltip section relative to the default tooltip content.
@@ -679,12 +694,12 @@ export declare interface IRange {
 }
 
 /**
- * Lookup of resolved reference values keyed by `metric/id` or `label/id`.
+ * Lookup of resolved reference statuses keyed by `metric/id` or `label/id`.
  *
  * @internal
  */
 export declare interface IResolvedReferenceValues {
-    [referenceKey: string]: string | undefined;
+    [referenceKey: string]: ResolvedReference | undefined;
 }
 
 /**
@@ -784,6 +799,21 @@ export declare function isValidMappedColor(colorItem: IColor | null | undefined,
  */
 export declare type ItemBorderRadiusPredicate = (item: any) => boolean;
 
+/**
+ * A tooltip execution plan: one batched execution for all external references,
+ * plus per-reference bundles used as an isolation fallback. When the batch
+ * rejects (e.g. a single invalid reference 400s the whole AFM), the consumer
+ * re-runs the per-reference bundles so one bad reference can't suppress the
+ * rest. `perRef` is a thunk: the bundles are built lazily, only when the batch
+ * fails, so consumers that never fan out (e.g. geo) pay nothing for it.
+ *
+ * @internal
+ */
+export declare interface ITooltipExecution {
+    batch: ITooltipExecutionBundle;
+    perRef: () => readonly ITooltipExecutionBundle[];
+}
+
 /**
  * Prepared tooltip execution paired with the meta needed to interpret its result.
  * Carry them together — meta from one call mis-interprets results from another.
@@ -809,6 +839,19 @@ export declare interface ITooltipExecutionMeta {
     labelIdMap: Record<string, string>;
 }
 
+/**
+ * Localized placeholder strings for the non-value reference states. Built once
+ * at the render site (where `intl` is available) and threaded into
+ * `resolveReferences`, so reference resolution stays free of i18n concerns.
+ *
+ * @internal
+ */
+export declare interface ITooltipLocalizedStrings {
+    readonly noData: string;
+    readonly multipleItems: string;
+    readonly noFetch: string;
+}
+
 /**
  * One prepared tooltip execution paired with a caller-owned key and the
  * context that travels with the built lookup.
@@ -833,14 +876,15 @@ export declare interface ITooltipLookupExecutionResult<TContext> {
 }
 
 /**
- * Localized placeholders for unresolved reference values. Mirrors the RichText
- * widget's `richText.no_data` / `richText.multiple_data` messages.
+ * Built lookup plus references that could not be retrieved at all (their fetch
+ * rejected even in the per-reference fallback). Errored references render as
+ * "(Data could not be retrieved)" at every point.
  *
  * @internal
  */
-export declare interface ITooltipLookupLocalizedStrings {
-    noData: string;
-    multipleItems: string;
+export declare interface ITooltipLookupResult {
+    lookup: Map<string, IResolvedReferenceValues>;
+    erroredRefs: ReadonlySet<string>;
 }
 
 /**
@@ -848,6 +892,24 @@ export declare interface ITooltipLookupLocalizedStrings {
  */
 export declare function joinKeySegments(parts: readonly string[]): string;
 
+/**
+ * Builds the `label/<id>` lookup key for a label reference. See {@link metricKey}.
+ *
+ * @internal
+ */
+export declare const labelKey: (id: string) => string;
+
+/**
+ * Maps a label/attribute display value to a {@link ResolvedReference} status:
+ * `null` / `undefined` / empty string → empty ("No data"); otherwise the value.
+ * Shared by every tooltip resolver so empty-value handling can't drift between
+ * the in-chart and external paths. The count-based "multiple" case stays with
+ * the caller (only the lookup builder knows the per-row count).
+ *
+ * @internal
+ */
+export declare function labelReference(value: string | number | null | undefined): ResolvedReference;
+
 /**
  * @internal
  */
@@ -885,6 +947,27 @@ export declare const LegendPosition: {
  */
 export declare function markdownToHtml(markdown: string): string;
 
+/**
+ * Maps a raw measure value to a {@link ResolvedReference} status: `null`/
+ * `undefined` → empty ("No data"); otherwise the formatted (or stringified)
+ * value. Shared by every tooltip resolver so the value→status mapping has a
+ * single home. Callers whose source can yield non-numeric / non-finite values
+ * (e.g. geo feature payloads) normalize those to `null` before calling.
+ *
+ * @internal
+ */
+export declare function measureReference(rawValue: number | string | null | undefined, format: string | undefined, separators?: ISeparators): ResolvedReference;
+
+/**
+ * Builds the `metric/<id>` lookup key for a metric reference. A reference key
+ * has exactly two shapes ({@link metricKey}, {@link labelKey}); keeping the
+ * convention here is the single source for every write site. The read side
+ * parses references via `REFERENCE_REGEX_MATCH` in `resolveReferences`.
+ *
+ * @internal
+ */
+export declare const metricKey: (id: string) => string;
+
 /**
  * @internal
  */
@@ -947,6 +1030,28 @@ export declare function PopUpLegend({ name, maxRows, enableBorderRadius, series,
  */
 export declare type PositionType = "left" | "right" | "top" | "bottom" | "auto";
 
+/**
+ * Resolution outcome for a single `{metric/id}` / `{label/id}` reference at a
+ * data point. A discriminated union so the renderer maps each state to its own
+ * localized message instead of collapsing every "missing" case into one
+ * fallback: `empty` → "(No data)", `multiple` → "(Multiple items)", `error` →
+ * "(Data could not be retrieved)". `error` is emitted only when a value was
+ * genuinely unretrievable (e.g. a reference whose fetch failed); it is never a
+ * default for an unclassified value.
+ *
+ * @internal
+ */
+export declare type ResolvedReference = {
+    readonly kind: "value";
+    readonly text: string;
+} | {
+    readonly kind: "empty";
+} | {
+    readonly kind: "multiple";
+} | {
+    readonly kind: "error";
+};
+
 /**
  * Returns the LDM identifier the measure ultimately resolves to.
  *
@@ -968,14 +1073,14 @@ export declare function resolveMeasureLdmIdentifier(measure: IMeasure, allMeasur
  * unintended formatting. `markdownToHtml` understands the backslash escapes.
  *
  * @param content - Markdown content with reference placeholders
- * @param values - Lookup of `metric/id` and `label/id` keys to formatted values.
+ * @param values - Lookup of `metric/id` and `label/id` keys to resolved statuses.
  *   Keys must use a lowercase prefix; LDM identifiers are case-sensitive.
- * @param fallbackText - Localized text shown when a reference is recognized
- *   but no value is available (unknown identifier, point with no value, etc.).
+ * @param strings - Localized placeholders for the non-value states (no data,
+ *   multiple items, could-not-retrieve).
  *
  * @internal
  */
-export declare function resolveReferences(content: string, values: IResolvedReferenceValues, fallbackText: string): string;
+export declare function resolveReferences(content: string, values: IResolvedReferenceValues, strings: ITooltipLocalizedStrings): string;
 
 /**
  * @internal
@@ -999,23 +1104,24 @@ 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".
+ * Single-execution variant for chart families that have one tooltip execution
+ * per chart (e.g. Highcharts). Returns `undefined` while no execution 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;
+export declare function useTooltipLookup(execution: ITooltipExecution | undefined, separators?: ISeparators): ITooltipLookupResult | undefined;
 
 /**
- * Multi-bundle variant for chart families that key tooltip executions per
+ * Multi-execution 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>>;
+export declare function useTooltipLookupExecutions<TContext>(entries: readonly ITooltipLookupExecutionEntry<TContext>[], separators?: ISeparators): 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.41.0-alpha.0",
+  "version": "11.41.0-alpha.1",
   "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.41.0-alpha.0",
-    "@gooddata/sdk-model": "11.41.0-alpha.0",
-    "@gooddata/sdk-ui": "11.41.0-alpha.0",
-    "@gooddata/sdk-ui-kit": "11.41.0-alpha.0",
-    "@gooddata/sdk-ui-theme-provider": "11.41.0-alpha.0"
+    "@gooddata/sdk-backend-spi": "11.41.0-alpha.1",
+    "@gooddata/sdk-model": "11.41.0-alpha.1",
+    "@gooddata/sdk-ui": "11.41.0-alpha.1",
+    "@gooddata/sdk-ui-theme-provider": "11.41.0-alpha.1",
+    "@gooddata/sdk-ui-kit": "11.41.0-alpha.1"
   },
   "devDependencies": {
     "@microsoft/api-documenter": "^7.17.0",
@@ -81,11 +81,11 @@
     "typescript": "5.9.3",
     "vitest": "4.1.8",
     "vitest-dom": "0.1.1",
-    "@gooddata/eslint-config": "11.41.0-alpha.0",
-    "@gooddata/oxlint-config": "11.41.0-alpha.0",
-    "@gooddata/reference-workspace": "11.41.0-alpha.0",
-    "@gooddata/sdk-backend-mockingbird": "11.41.0-alpha.0",
-    "@gooddata/stylelint-config": "11.41.0-alpha.0"
+    "@gooddata/eslint-config": "11.41.0-alpha.1",
+    "@gooddata/oxlint-config": "11.41.0-alpha.1",
+    "@gooddata/sdk-backend-mockingbird": "11.41.0-alpha.1",
+    "@gooddata/stylelint-config": "11.41.0-alpha.1",
+    "@gooddata/reference-workspace": "11.41.0-alpha.1"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",