Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

GDGT-3183 Sanitize ClickObject and HoverObject (#81885)

Kamil Mielnikaf22e8cf22a8
diff --git a/docs/developers-guide/custom-visualizations.md b/docs/developers-guide/custom-visualizations.md
index 6ea2c57bed2..47f75a00854 100644
--- a/docs/developers-guide/custom-visualizations.md
+++ b/docs/developers-guide/custom-visualizations.md
@@ -182,8 +182,8 @@ export default createVisualization;
| `width` | `number \| null` | Container width in pixels. `null` until the first measure — render `null` to avoid a flash. |
| `height` | `number \| null` | Container height in pixels. `null` until the first measure. |
| `renderingContext` | `RenderingContext` | Host helpers for colors, text measurement, and the current color scheme — see [Formatting and theming](#formatting-and-theming). |
-| `onClick` | `(clickObject) => void` | Call to trigger drill-through actions on a data point. |
-| `onHover` | `(hoverObject?) => void` | Call to show a tooltip on a data point. |
+| `onClick` | `(clickObject) => void` | Call to trigger drill-through actions on a data point. Pass `null` to close the drill-through popover. |
+| `onHover` | `(hoverObject?) => void` | Call to show a tooltip on a data point. Pass `null` to hide it. |
## Handling query results
@@ -234,7 +234,7 @@ Your component receives `onClick` and `onHover`. Call them with an object that i
/>
```
-Pass `null` to `onHover` to dismiss the tooltip. `onClick` also takes an `origin: { row, cols }` when a drill-through needs the whole row, not just the clicked cell. It can take a `data` array of `{ col, value }` pairs (one per column) when an action needs every column's value. You can include `settings` (the current resolved settings) in the click object too, so dashboard click behaviors configured against your visualization have what they need.
+Pass `null` to `onHover` to dismiss the tooltip. Metabase waits a tick before hiding it, so moving between adjacent elements doesn't flicker. Pass `null` to `onClick` to close the drill-through popover, for example when the same element is clicked again or when your chart scrolls. `onClick` also takes an `origin: { row, cols }` when a drill-through needs the whole row, not just the clicked cell. It can take a `data` array of `{ col, value }` pairs (one per column) when an action needs every column's value.
The hover object accepts more than `element` and `data`. Optional fields like `index` and `seriesIndex` (to highlight a series in the legend) and `value`, `column`, `dimensions`, and `event` (for a simpler single-point tooltip) are available when you need them.
diff --git a/enterprise/frontend/src/custom-viz/CHANGELOG.md b/enterprise/frontend/src/custom-viz/CHANGELOG.md
index dd59e6b8469..0775ca128f7 100644
--- a/enterprise/frontend/src/custom-viz/CHANGELOG.md
+++ b/enterprise/frontend/src/custom-viz/CHANGELOG.md
@@ -7,6 +7,7 @@ This changelog covers the `@metabase/custom-viz` npm package — the API and CLI
### ⚠ BREAKING CHANGES
- `column` and `column_settings` are now reserved setting ids, contributed to every visualization by Metabase to power the built-in per-column formatting popover. Plugins that declared their own settings under these ids must rename them — the `Settings` type now rejects those keys with a type error ([#78128](https://github.com/metabase/metabase/pull/78128)).
+- `ClickObject` is no longer generic and no longer has a `settings` field. Metabase attaches the visualization's current settings to every click itself and ignores anything passed under `settings`, so a click can't redirect dashboard click behavior. A `click_behavior` saved by an earlier plugin version stays in effect until removed ([#81181](https://github.com/metabase/metabase/pull/81181)).
- The top-level `colorScheme` visualization prop moved into the new `renderingContext` prop (see Features below). Read `props.renderingContext.colorScheme` instead of `props.colorScheme` ([#78429](https://github.com/metabase/metabase/pull/78429)).
- The module-level `measureText`, `measureTextWidth`, and `measureTextHeight` exports are removed. The functions were stubs that always returned zero-size measurements — for real ones, use `measureText` on the new `renderingContext` prop (see Features below) ([#78429](https://github.com/metabase/metabase/pull/78429)).
diff --git a/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/Visualization.tsx b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/Visualization.tsx
index cdfe55bd447..e07bbaacf4e 100644
--- a/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/Visualization.tsx
+++ b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/Visualization.tsx
@@ -32,7 +32,6 @@ export const Visualization = (
onClick({
value,
column: cols[0],
- settings,
event: event.nativeEvent,
element: event.currentTarget,
origin: { row: rows[0], cols },
diff --git a/enterprise/frontend/src/custom-viz/src/types/format.ts b/enterprise/frontend/src/custom-viz/src/types/format.ts
index 94f9507f95c..4634b0fa8c8 100644
--- a/enterprise/frontend/src/custom-viz/src/types/format.ts
+++ b/enterprise/frontend/src/custom-viz/src/types/format.ts
@@ -4,7 +4,7 @@ export type FormatValueOptions = {
column?: Column;
compact?: boolean;
currency?: string;
- currency_style?: string;
+ currency_style?: Intl.NumberFormatOptionsCurrencyDisplay;
date_format?: string;
date_style?: string | null;
date_separator?: string;
diff --git a/enterprise/frontend/src/custom-viz/src/types/viz.ts b/enterprise/frontend/src/custom-viz/src/types/viz.ts
index 309cd83cf6d..b4669185d04 100644
--- a/enterprise/frontend/src/custom-viz/src/types/viz.ts
+++ b/enterprise/frontend/src/custom-viz/src/types/viz.ts
@@ -122,9 +122,18 @@ export type CustomVisualizationProps<
series: Series;
settings: CustomVisualizationSettings<TSettings>;
renderingContext: RenderingContext;
- onClick: (
- clickObject: ClickObject<CustomVisualizationSettings<TSettings>> | null,
- ) => void;
+
+ /**
+ * Call with a {@link ClickObject} to open the drill-through popover for a data point.
+ * Call with `null` to close an open popover, e.g. when the same element is clicked again or the chart scrolls.
+ */
+ onClick: (clickObject: ClickObject | null) => void;
+
+ /**
+ * Call with a {@link HoverObject} to show a tooltip for a data point.
+ * Call with `null` or no argument to hide it, e.g. on mouse leave. Hiding is deferred until the next
+ * tick so moving between elements doesn't flicker.
+ */
onHover: (hoverObject?: HoverObject | null) => void;
};
@@ -148,7 +157,7 @@ export type CustomVisualizationMount = <P extends object>(
initialProps: P,
) => CustomVisualizationMountHandle<P>;
-export type ClickObject<TSettings extends BaseVisualizationSettings> = {
+export type ClickObject = {
/** The raw value of the clicked cell. */
value?: RowValue;
@@ -169,9 +178,6 @@ export type ClickObject<TSettings extends BaseVisualizationSettings> = {
/** The DOM element that was clicked. Used to anchor popovers. */
element?: Element;
- /** Visualization settings at the time of the click. */
- settings?: CustomVisualizationSettings<TSettings>;
-
/**
* The full row of data and column metadata for the clicked data point.
* Provides access to the raw row values and their columns — useful when
diff --git a/enterprise/frontend/src/metabase-enterprise/custom_viz/click-object.ts b/enterprise/frontend/src/metabase-enterprise/custom_viz/click-object.ts
new file mode 100644
index 00000000000..a1532bebb15
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/custom_viz/click-object.ts
@@ -0,0 +1,22 @@
+import type { ClickObject as PluginClickObject } from "custom-viz";
+
+import type { ClickObject } from "metabase/visualizations/types";
+import type { ComputedVisualizationSettings } from "metabase/viz-core";
+
+export type { PluginClickObject };
+
+export function toHostClickObject(
+ clickObject: PluginClickObject,
+ settings: ComputedVisualizationSettings,
+): ClickObject {
+ return {
+ value: clickObject.value,
+ column: clickObject.column,
+ dimensions: clickObject.dimensions,
+ event: clickObject.event,
+ element: clickObject.element,
+ origin: clickObject.origin,
+ data: clickObject.data,
+ settings,
+ };
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/custom_viz/click-object.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/custom_viz/click-object.unit.spec.ts
new file mode 100644
index 00000000000..13f3270ff24
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/custom_viz/click-object.unit.spec.ts
@@ -0,0 +1,46 @@
+import type { ClickObject } from "metabase/visualizations/types";
+import { createMockColumn } from "metabase-types/api/mocks";
+
+import { type PluginClickObject, toHostClickObject } from "./click-object";
+
+describe("toHostClickObject", () => {
+ const column = createMockColumn({ name: "count" });
+ const settings = { click_behavior: { type: "crossfilter" } };
+
+ it("keeps the documented click fields", () => {
+ const element = document.createElement("div");
+ const event = new MouseEvent("click");
+ const clicked: PluginClickObject = {
+ value: 42,
+ column,
+ dimensions: [{ value: "a", column }],
+ event,
+ element,
+ origin: { row: [42], cols: [column] },
+ data: [{ col: column, value: 42 }],
+ };
+
+ expect(toHostClickObject(clicked, settings)).toEqual({
+ ...clicked,
+ settings,
+ });
+ });
+
+ it("replaces plugin-supplied settings and drops host-only fields", () => {
+ const clicked: ClickObject = {
+ value: 42,
+ settings: {
+ click_behavior: { type: "link", linkType: "question", targetId: 1 },
+ },
+ cardId: 1,
+ seriesIndex: 3,
+ columnShortcuts: true,
+ extraData: { setParameterValue: jest.fn() },
+ };
+
+ expect(toHostClickObject(clicked, settings)).toEqual({
+ value: 42,
+ settings,
+ });
+ });
+});
diff --git a/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-plugins.tsx b/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-plugins.tsx
index e81c872d2f3..9c5f8673d21 100644
--- a/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-plugins.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-plugins.tsx
@@ -3,8 +3,6 @@ import type {
CustomVisualization,
CustomVisualizationProps,
CustomVisualizationSettingDefinition,
- ClickObject as CustomVizClickObject,
- HoverObject as CustomVizHoverObject,
} from "custom-viz";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { t } from "ttag";
@@ -39,8 +37,10 @@ import type {
import { isObject } from "metabase-types/guards";
import { isCustomVizDisplay } from "metabase-types/guards/visualization";
+import { type PluginClickObject, toHostClickObject } from "./click-object";
import { applyDefaultVisualizationProps } from "./custom-viz-common";
import { ensureVizApi } from "./custom-viz-globals";
+import { type PluginHoverObject, toHostHoverObject } from "./hover-object";
import type { SandboxMode } from "./sandbox";
import { usePluginMount } from "./use-plugin-mount";
import { reportUnavailableCustomVizPlugin } from "./utils/unavailable-toast";
@@ -609,6 +609,16 @@ function createCustomVizWrapper(
[browserRenderingContext],
);
+ const handleClick = (clickObject: PluginClickObject | null) =>
+ onVisualizationClick(
+ clickObject && toHostClickObject(clickObject, settings),
+ );
+
+ const handleHover = (hoverObject?: PluginHoverObject | null) =>
+ onHoverChange(
+ hoverObject ? toHostHoverObject(hoverObject, settings) : hoverObject,
+ );
+
const pluginProps: GenericVizPluginProps = {
width,
height,
@@ -619,14 +629,8 @@ function createCustomVizWrapper(
// unions); the runtime value is the host's computed settings.
settings: settings as unknown as GenericVizPluginProps["settings"],
renderingContext,
- // Unjustified type cast. FIXME
- onClick: onVisualizationClick as unknown as (
- clickObject: CustomVizClickObject<Record<string, unknown>> | null,
- ) => void,
- // Unjustified type cast. FIXME
- onHover: onHoverChange as unknown as (
- hoverObject?: CustomVizHoverObject | null,
- ) => void,
+ onClick: handleClick,
+ onHover: handleHover,
};
const containerRef = usePluginMount<GenericVizPluginProps>(
diff --git a/enterprise/frontend/src/metabase-enterprise/custom_viz/hover-object.ts b/enterprise/frontend/src/metabase-enterprise/custom_viz/hover-object.ts
new file mode 100644
index 00000000000..c55941a7362
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/custom_viz/hover-object.ts
@@ -0,0 +1,25 @@
+import type { HoverObject as PluginHoverObject } from "custom-viz";
+
+import type {
+ ComputedVisualizationSettings,
+ HoveredObject,
+} from "metabase/viz-core";
+
+export type { PluginHoverObject };
+
+export function toHostHoverObject(
+ hoverObject: PluginHoverObject,
+ settings: ComputedVisualizationSettings,
+): HoveredObject {
+ return {
+ index: hoverObject.index,
+ seriesIndex: hoverObject.seriesIndex,
+ value: hoverObject.value,
+ column: hoverObject.column,
+ data: hoverObject.data,
+ dimensions: hoverObject.dimensions,
+ element: hoverObject.element,
+ event: hoverObject.event,
+ settings,
+ };
+}
diff --git a/enterprise/frontend/src/metabase-enterprise/custom_viz/hover-object.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/custom_viz/hover-object.unit.spec.ts
new file mode 100644
index 00000000000..19d0abbd7fd
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/custom_viz/hover-object.unit.spec.ts
@@ -0,0 +1,46 @@
+import { createMockColumn } from "metabase-types/api/mocks";
+
+import { type PluginHoverObject, toHostHoverObject } from "./hover-object";
+
+describe("toHostHoverObject", () => {
+ const column = createMockColumn({ name: "count" });
+ const settings = { click_behavior: { type: "crossfilter" } };
+
+ it("keeps the documented hover fields with the host settings", () => {
+ const element = document.createElement("div");
+ const event = new MouseEvent("mousemove");
+ const hovered: PluginHoverObject = {
+ index: 0,
+ seriesIndex: 1,
+ value: 42,
+ column,
+ data: [{ key: "count", col: column, value: 42 }],
+ dimensions: [{ value: "a", column }],
+ element,
+ event,
+ };
+
+ expect(toHostHoverObject(hovered, settings)).toEqual({
+ ...hovered,
+ settings,
+ });
+ });
+
+ it("replaces plugin-supplied settings and drops host-only fields", () => {
+ const hovered = {
+ value: 42,
+ settings: {
+ click_behavior: { type: "link", linkType: "question", targetId: 1 },
+ },
+ seriesId: 3,
+ datumIndex: 2,
+ isAlreadyScaled: true,
+ pieSliceKeyPath: ["a"],
+ };
+
+ expect(toHostHoverObject(hovered, settings)).toEqual({
+ value: 42,
+ settings,
+ });
+ });
+});