Skip to content

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

GDGT-3182 Make checkRenderable optional in custom viz (#81884)

Kamil Mielnika2979abd203a
diff --git a/enterprise/frontend/src/custom-viz/CHANGELOG.md b/enterprise/frontend/src/custom-viz/CHANGELOG.md
index ca77fa0a8e9..dd59e6b8469 100644
--- a/enterprise/frontend/src/custom-viz/CHANGELOG.md
+++ b/enterprise/frontend/src/custom-viz/CHANGELOG.md
@@ -16,6 +16,7 @@ This changelog covers the `@metabase/custom-viz` npm package — the API and CLI
- New `renderingContext` visualization prop with host rendering helpers: `getColor` resolves a Metabase color name to its current theme value, `measureText` measures text the way Metabase renders it, returning `{ width, height }` from a single measurement (`style.family` defaults to the instance font), `fontFamily` exposes that font for styling your own markup, and `colorScheme` tells you whether Metabase is rendering in light or dark mode ([#78429](https://github.com/metabase/metabase/pull/78429)).
- New `@metabase/custom-viz pack` command packages a built visualization into an upload-ready `.tgz`. Scaffolded projects call it from their `build` script instead of carrying their own copy of the packaging script, so fixes to packaging and to the bundle size limits now come with a package upgrade. Pass `--dir` to pack a project in another directory.
- `@metabase/custom-viz pack` stamps the exact `@metabase/custom-viz` version into the packed manifest as `sdk.version`. Your source `metabase-plugin.json` is not modified. Metabase compares the stamp against the SDK versions it was tested with — a plugin outside that range (or outside its own `metabase.version` range) is never rejected; it uploads and runs normally, with a warning shown on the admin page.
+- `checkRenderable` is now optional. Omit it when your visualization can render any data; keep throwing from it to surface a custom error. A visualization without a `checkRenderable` is always considered renderable ([#81181](https://github.com/metabase/metabase/pull/81181)).
### Bug Fixes
diff --git a/enterprise/frontend/src/custom-viz/src/templates/README.md b/enterprise/frontend/src/custom-viz/src/templates/README.md
index c3308864302..24ed0b3c477 100644
--- a/enterprise/frontend/src/custom-viz/src/templates/README.md
+++ b/enterprise/frontend/src/custom-viz/src/templates/README.md
@@ -123,17 +123,17 @@ export default createVisualization;
### Visualization definition properties
-| Property | Type | Description |
-| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `id` | `string` | Unique identifier. Must match `name` in `metabase-plugin.json`. |
-| `getName()` | `() => string` | Display name shown in the chart type picker. |
-| `minSize` | `{ width, height }` | Minimum dashboard grid size. |
-| `defaultSize` | `{ width, height }` | Default dashboard grid size. |
-| `noHeader` | `boolean` | When `true`, hides the default card title/description header. |
-| `canSavePng` | `boolean` | Set to `false` to disable PNG export for this visualization. |
-| `checkRenderable` | `(series, settings) => void` | Throw here to signal the viz cannot render with the current data or settings. Metabase shows the error message to the user. |
-| `settings` | `Record<string, SettingDefinition>` | Map of setting definitions created by `defineSetting()`. |
-| `VisualizationComponent` | `React.ComponentType` | The interactive React component for dashboard/question rendering. |
+| Property | Type | Description |
+| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id` | `string` | Unique identifier. Must match `name` in `metabase-plugin.json`. |
+| `getName()` | `() => string` | Display name shown in the chart type picker. |
+| `minSize` | `{ width, height }` | Minimum dashboard grid size. |
+| `defaultSize` | `{ width, height }` | Default dashboard grid size. |
+| `noHeader` | `boolean` | When `true`, hides the default card title/description header. |
+| `canSavePng` | `boolean` | Set to `false` to disable PNG export for this visualization. |
+| `checkRenderable` | `(series, settings) => void` | Optional. Throw here to signal the viz cannot render with the current data or settings; Metabase shows the error message to the user. Omit it to always render. |
+| `settings` | `Record<string, SettingDefinition>` | Map of setting definitions created by `defineSetting()`. |
+| `VisualizationComponent` | `React.ComponentType` | The interactive React component for dashboard/question rendering. |
### VisualizationComponent props
diff --git a/enterprise/frontend/src/custom-viz/src/types/viz.ts b/enterprise/frontend/src/custom-viz/src/types/viz.ts
index 26d1ff12288..309cd83cf6d 100644
--- a/enterprise/frontend/src/custom-viz/src/types/viz.ts
+++ b/enterprise/frontend/src/custom-viz/src/types/viz.ts
@@ -69,9 +69,11 @@ export type CustomVisualization<TSettings extends BaseVisualizationSettings> = {
>;
/**
- * This function should throw if the visualization cannot be rendered with given data and settings.
+ * Throw here if the visualization cannot be rendered with the given data and settings.
+ * Metabase shows the thrown message to the user.
+ * When omitted, the visualization is always considered renderable.
*/
- checkRenderable: (
+ checkRenderable?: (
series: Series,
settings: CustomVisualizationSettings<TSettings>,
) => void | never;
diff --git a/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-common.ts b/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-common.ts
index b11acde58d2..dcafc542d73 100644
--- a/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-common.ts
+++ b/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-common.ts
@@ -9,7 +9,9 @@ import type {
import { columnSettings } from "metabase/viz-core";
import type {
CustomVizPluginRuntime,
+ Series,
VisualizationDisplay,
+ VisualizationSettings,
} from "metabase-types/api";
import { sanitizePluginSettings } from "./custom-viz-settings";
@@ -43,7 +45,11 @@ export function applyDefaultVisualizationProps(
...columnSettings({ getHidden: () => true }),
...sanitizePluginSettings(vizDef.settings, vizDef.mount, plugin),
},
- checkRenderable: vizDef.checkRenderable,
+ checkRenderable: (series: Series, vizSettings: VisualizationSettings) => {
+ if (typeof vizDef.checkRenderable === "function") {
+ vizDef.checkRenderable(series, vizSettings);
+ }
+ },
noHeader: vizDef.noHeader ?? false,
canSavePng: vizDef.canSavePng ?? false,
hidden: false,
diff --git a/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-common.unit.spec.ts b/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-common.unit.spec.ts
new file mode 100644
index 00000000000..389d748e490
--- /dev/null
+++ b/enterprise/frontend/src/metabase-enterprise/custom_viz/custom-viz-common.unit.spec.ts
@@ -0,0 +1,63 @@
+import type { CustomVisualization } from "custom-viz";
+import type { ComponentType } from "react";
+
+import type {
+ VisualizationPassThroughProps,
+ VisualizationProps,
+} from "metabase/visualizations/types/visualization";
+import { createMockCustomVizPluginRuntime } from "metabase-types/api/mocks";
+
+import { applyDefaultVisualizationProps } from "./custom-viz-common";
+
+const PLUGIN = createMockCustomVizPluginRuntime();
+
+const COMPONENT: ComponentType<
+ VisualizationProps & VisualizationPassThroughProps
+> = () => null;
+
+describe("applyDefaultVisualizationProps", () => {
+ it("wraps a plugin's checkRenderable", () => {
+ const checkRenderable = jest.fn();
+ const vizDef = createVizDef({ checkRenderable });
+
+ applyDefaultVisualizationProps(COMPONENT, vizDef, {
+ identifier: "custom:demo-viz",
+ plugin: PLUGIN,
+ getUiName: () => "Demo",
+ }).checkRenderable?.([], {});
+
+ expect(checkRenderable).toHaveBeenCalledTimes(1);
+ });
+
+ it("treats a bundle that omits checkRenderable as renderable, without throwing", () => {
+ const vizDef = createVizDef({});
+
+ const { checkRenderable } = applyDefaultVisualizationProps(
+ COMPONENT,
+ vizDef,
+ {
+ identifier: "custom:demo-viz",
+ plugin: PLUGIN,
+ getUiName: () => "Demo",
+ },
+ );
+
+ expect(() => checkRenderable?.([], {})).not.toThrow();
+ });
+});
+
+function createVizDef(
+ overrides: Partial<CustomVisualization<Record<string, unknown>>>,
+): CustomVisualization<Record<string, unknown>> {
+ return {
+ id: "demo",
+ getName: () => "Demo",
+ checkRenderable: () => undefined,
+ mount: () => ({
+ update: () => undefined,
+ unmount: () => undefined,
+ }),
+ VisualizationComponent: () => null,
+ ...overrides,
+ };
+}