Skip to content

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

GDGT-3189 Remove CustomVisualization['id'] and use CustomVisualization['getName'] (#82033)

Kamil Mielnikda793ea97692
diff --git a/enterprise/frontend/src/custom-viz/CHANGELOG.md b/enterprise/frontend/src/custom-viz/CHANGELOG.md
index 0775ca128f7..e079fcf2440 100644
--- a/enterprise/frontend/src/custom-viz/CHANGELOG.md
+++ b/enterprise/frontend/src/custom-viz/CHANGELOG.md
@@ -9,6 +9,7 @@ This changelog covers the `@metabase/custom-viz` npm package — the API and CLI
- `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 `id` field of the visualization definition is removed. It was never read — Metabase identifies a visualization by `name` in `metabase-plugin.json`. Delete it from your `defineConfig` call.
- 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)).
### Features
@@ -17,6 +18,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.
+- `getName` is now optional and is what Metabase shows as the visualization name in the UI. Omit it to use `name` from `metabase-plugin.json`; keep it to show a localized or human-friendly name.
- `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/fixtures/example_custom_viz_plugin/src/index-widget-security-component.tsx b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index-widget-security-component.tsx
index 42b4317e003..b0afb4d186e 100644
--- a/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index-widget-security-component.tsx
+++ b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index-widget-security-component.tsx
@@ -19,8 +19,6 @@ const createVisualization: CreateCustomVisualization<Settings> = ({
defineSetting,
}) => {
return defineConfig<Settings>({
- id: "example_custom_viz_plugin",
- getName: () => "example_custom_viz_plugin",
minSize: { width: 2, height: 2 },
checkRenderable(series) {
if (series.length !== 1) {
diff --git a/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index-widget-security.tsx b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index-widget-security.tsx
index f5b1d6fe4ef..3888109535c 100644
--- a/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index-widget-security.tsx
+++ b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index-widget-security.tsx
@@ -22,8 +22,6 @@ const createVisualization: CreateCustomVisualization<Settings> = ({
locale,
}) => {
return defineConfig<Settings>({
- id: "example_custom_viz_plugin",
- getName: () => "example_custom_viz_plugin",
minSize: { width: 2, height: 2 },
checkRenderable(series) {
if (series.length !== 1) {
diff --git a/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index.tsx b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index.tsx
index de81091602b..c8e0b791608 100644
--- a/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index.tsx
+++ b/enterprise/frontend/src/custom-viz/fixtures/example_custom_viz_plugin/src/index.tsx
@@ -12,8 +12,6 @@ const createVisualization: CreateCustomVisualization<Settings> = ({
locale,
}) => {
return defineConfig<Settings>({
- id: "example_custom_viz_plugin",
- getName: () => "example_custom_viz_plugin",
minSize: { width: 2, height: 2 },
checkRenderable(series, settings) {
if (series.length !== 1) {
diff --git a/enterprise/frontend/src/custom-viz/src/cli.ts b/enterprise/frontend/src/custom-viz/src/cli.ts
index 5f9152b2f95..af14e264373 100644
--- a/enterprise/frontend/src/custom-viz/src/cli.ts
+++ b/enterprise/frontend/src/custom-viz/src/cli.ts
@@ -60,10 +60,7 @@ program
writeFile(join(name, "package.json"), generatePackageJson(name)),
writeFile(join(name, "vite.config.ts"), generateViteConfig()),
writeFile(join(name, "tsconfig.json"), generateTsConfig()),
- writeFile(
- join(name, "src", "index.tsx"),
- generateIndexTsx(name, displayName),
- ),
+ writeFile(join(name, "src", "index.tsx"), generateIndexTsx(displayName)),
writeFile(join(name, "metabase-plugin.json"), generateManifest(name)),
writeFile(join(name, "public", "assets", "icon.svg"), generateIconSvg()),
writeFile(join(name, ".gitignore"), generateGitignore()),
diff --git a/enterprise/frontend/src/custom-viz/src/cli.unit.spec.ts b/enterprise/frontend/src/custom-viz/src/cli.unit.spec.ts
index fc5b078f3a6..7a6b7b05326 100644
--- a/enterprise/frontend/src/custom-viz/src/cli.unit.spec.ts
+++ b/enterprise/frontend/src/custom-viz/src/cli.unit.spec.ts
@@ -147,13 +147,12 @@ describe("cli init", () => {
expect(pkg.name).toBe("my-custom-viz");
});
- it("uses normalized id and human-friendly display name in index.tsx", async () => {
+ it("uses human-friendly display name in index.tsx", async () => {
await runCli(["init", "My Custom Viz"]);
const indexTsx = readFileSync(
join(tmpDir, "my-custom-viz", "src", "index.tsx"),
"utf-8",
);
- expect(indexTsx).toContain('id: "my-custom-viz"');
expect(indexTsx).toContain('getName: () => "My Custom Viz"');
});
diff --git a/enterprise/frontend/src/custom-viz/src/templates.ts b/enterprise/frontend/src/custom-viz/src/templates.ts
index f1f860ed777..18294644b1d 100644
--- a/enterprise/frontend/src/custom-viz/src/templates.ts
+++ b/enterprise/frontend/src/custom-viz/src/templates.ts
@@ -40,11 +40,8 @@ export function generateTsConfig(): string {
return tsconfigTemplate;
}
-export function generateIndexTsx(name: string, displayName: string): string {
- return replaceDisplayName(
- replaceName(replaceImportPath(indexTsxTemplate), name),
- displayName,
- );
+export function generateIndexTsx(displayName: string): string {
+ return replaceDisplayName(replaceImportPath(indexTsxTemplate), displayName);
}
export function generateManifest(name: string): string {
diff --git a/enterprise/frontend/src/custom-viz/src/templates.unit.spec.ts b/enterprise/frontend/src/custom-viz/src/templates.unit.spec.ts
index bd80cf887b4..0e17396fce7 100644
--- a/enterprise/frontend/src/custom-viz/src/templates.unit.spec.ts
+++ b/enterprise/frontend/src/custom-viz/src/templates.unit.spec.ts
@@ -16,14 +16,11 @@ describe("text templates", () => {
});
it("generateIndexTsx contains SDK import", () => {
- expect(generateIndexTsx("my-viz", "My Viz")).toContain(
- 'from "@metabase/custom-viz"',
- );
+ expect(generateIndexTsx("My Viz")).toContain('from "@metabase/custom-viz"');
});
- it("generateIndexTsx substitutes id and display name separately", () => {
- const source = generateIndexTsx("my-viz", "My Viz");
- expect(source).toContain('id: "my-viz"');
+ it("generateIndexTsx substitutes display name", () => {
+ const source = generateIndexTsx("My Viz");
expect(source).toContain('getName: () => "My Viz"');
});
diff --git a/enterprise/frontend/src/custom-viz/src/templates/README.md b/enterprise/frontend/src/custom-viz/src/templates/README.md
index 24ed0b3c477..180b2dce3bf 100644
--- a/enterprise/frontend/src/custom-viz/src/templates/README.md
+++ b/enterprise/frontend/src/custom-viz/src/templates/README.md
@@ -97,7 +97,6 @@ const createVisualization: CreateCustomVisualization<Settings> = ({
};
return {
- id: "__CUSTOM_VIZ_NAME__",
getName: () => "__CUSTOM_VIZ_DISPLAY_NAME__",
minSize: { width: 2, height: 2 },
defaultSize: { width: 6, height: 4 },
@@ -125,8 +124,7 @@ export default createVisualization;
| Property | Type | Description |
| ------------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id` | `string` | Unique identifier. Must match `name` in `metabase-plugin.json`. |
-| `getName()` | `() => string` | Display name shown in the chart type picker. |
+| `getName()` | `() => string` | Optional. Display name shown in the chart type picker. Defaults to `name` from `metabase-plugin.json`. |
| `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. |
diff --git a/enterprise/frontend/src/custom-viz/src/templates/index.tsx b/enterprise/frontend/src/custom-viz/src/templates/index.tsx
index 17961cf014c..4a614d18da6 100644
--- a/enterprise/frontend/src/custom-viz/src/templates/index.tsx
+++ b/enterprise/frontend/src/custom-viz/src/templates/index.tsx
@@ -52,7 +52,6 @@ const createVisualization: CreateCustomVisualization<Settings> = ({
};
return defineConfig<Settings>({
- id: "__CUSTOM_VIZ_NAME__",
getName: () => "__CUSTOM_VIZ_DISPLAY_NAME__",
minSize: { width: 2, height: 2 },
checkRenderable(series, settings) {
diff --git a/enterprise/frontend/src/custom-viz/src/types/viz.ts b/enterprise/frontend/src/custom-viz/src/types/viz.ts
index b4669185d04..ca5a391a3d9 100644
--- a/enterprise/frontend/src/custom-viz/src/types/viz.ts
+++ b/enterprise/frontend/src/custom-viz/src/types/viz.ts
@@ -30,15 +30,11 @@ export type CreateCustomVisualizationProps<
};
export type CustomVisualization<TSettings extends BaseVisualizationSettings> = {
- /**
- * A unique visualization identifier. It's not shown in the UI.
- */
- id: string;
-
/**
* Returns visualization name to be shown in the UI.
+ * Defaults to the plugin name from the manifest.
*/
- getName(): string;
+ getName?(): string;
/**
* Set to false to disable saving the question as PNG.
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 dcafc542d73..2b101eca1e4 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
@@ -34,12 +34,12 @@ export function applyDefaultVisualizationProps(
settings: {
identifier: VisualizationDisplay;
plugin: CustomVizPluginRuntime;
- getUiName: () => string;
iconUrl?: string | undefined;
isDev?: boolean;
},
): Visualization {
const { plugin, ...componentSettings } = settings;
+ const uiName = resolveUiName(vizDef, plugin);
return Object.assign(Component, {
settings: {
...columnSettings({ getHidden: () => true }),
@@ -57,6 +57,17 @@ export function applyDefaultVisualizationProps(
defaultSize: vizDef.defaultSize,
isDev: settings.isDev,
pluginId: plugin.id,
+ getUiName: () => uiName,
...componentSettings,
});
}
+
+function resolveUiName(
+ vizDef: CustomVisualization<Record<string, unknown>>,
+ plugin: CustomVizPluginRuntime,
+): string {
+ const name = vizDef.getName?.();
+ return typeof name === "string" && name.trim() !== ""
+ ? name
+ : plugin.display_name;
+}
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
index 389d748e490..11b497b2f85 100644
--- 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
@@ -23,7 +23,6 @@ describe("applyDefaultVisualizationProps", () => {
applyDefaultVisualizationProps(COMPONENT, vizDef, {
identifier: "custom:demo-viz",
plugin: PLUGIN,
- getUiName: () => "Demo",
}).checkRenderable?.([], {});
expect(checkRenderable).toHaveBeenCalledTimes(1);
@@ -38,20 +37,86 @@ describe("applyDefaultVisualizationProps", () => {
{
identifier: "custom:demo-viz",
plugin: PLUGIN,
- getUiName: () => "Demo",
},
);
expect(() => checkRenderable?.([], {})).not.toThrow();
});
+
+ it("uses the plugin's getName as the UI name", () => {
+ const vizDef = createVizDef({ getName: () => "Localized demo" });
+
+ const { getUiName } = applyDefaultVisualizationProps(COMPONENT, vizDef, {
+ identifier: "custom:demo-viz",
+ plugin: PLUGIN,
+ });
+
+ expect(getUiName()).toBe("Localized demo");
+ });
+
+ it("falls back to the manifest display name when getName is omitted", () => {
+ const vizDef = createVizDef({});
+ const plugin = createMockCustomVizPluginRuntime({
+ display_name: "Manifest name",
+ });
+
+ const { getUiName } = applyDefaultVisualizationProps(COMPONENT, vizDef, {
+ identifier: "custom:demo-viz",
+ plugin,
+ });
+
+ expect(getUiName()).toBe("Manifest name");
+ });
+
+ it("falls back to the manifest display name when getName returns a non-string", () => {
+ // plugin code is untyped at runtime
+ const vizDef = createVizDef({ getName: () => 42 as unknown as string });
+ const plugin = createMockCustomVizPluginRuntime({
+ display_name: "Manifest name",
+ });
+
+ const { getUiName } = applyDefaultVisualizationProps(COMPONENT, vizDef, {
+ identifier: "custom:demo-viz",
+ plugin,
+ });
+
+ expect(getUiName()).toBe("Manifest name");
+ });
+
+ it("falls back to the manifest display name when getName returns a blank string", () => {
+ const vizDef = createVizDef({ getName: () => " " });
+ const plugin = createMockCustomVizPluginRuntime({
+ display_name: "Manifest name",
+ });
+
+ const { getUiName } = applyDefaultVisualizationProps(COMPONENT, vizDef, {
+ identifier: "custom:demo-viz",
+ plugin,
+ });
+
+ expect(getUiName()).toBe("Manifest name");
+ });
+
+ it("resolves the UI name once at load time so a throwing getName fails the plugin load", () => {
+ const getName = jest.fn(() => {
+ throw new Error("boom");
+ });
+ const vizDef = createVizDef({ getName });
+
+ expect(() =>
+ applyDefaultVisualizationProps(COMPONENT, vizDef, {
+ identifier: "custom:demo-viz",
+ plugin: PLUGIN,
+ }),
+ ).toThrow("boom");
+ expect(getName).toHaveBeenCalledTimes(1);
+ });
});
function createVizDef(
overrides: Partial<CustomVisualization<Record<string, unknown>>>,
): CustomVisualization<Record<string, unknown>> {
return {
- id: "demo",
- getName: () => "Demo",
checkRenderable: () => undefined,
mount: () => ({
update: () => undefined,
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 9c5f8673d21..0523e4aa328 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
@@ -445,7 +445,6 @@ async function fetchAndRegisterCustomVizPlugin(
{
identifier,
plugin,
- getUiName: () => plugin.display_name,
iconUrl: resolvedIconUrl,
isDev: Boolean(plugin.dev_bundle_url),
},