The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
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.mdindex 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 Fixesdiff --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.tsxindex 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.tsxindex 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.tsxindex 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.tsindex 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 @@ programwriteFile(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.tsindex 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.tsindex 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.tsindex 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.mdindex 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsxindex 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),},