Skip to content

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

Implement auto-generated props tables for modular embedding (#69407)

Sébastien0a05ffd76a89
diff --git a/.typedoc/tsconfig.eajs-docs.json b/.typedoc/tsconfig.eajs-docs.json
new file mode 100644
index 00000000000..2d75eb80217
--- /dev/null
+++ b/.typedoc/tsconfig.eajs-docs.json
@@ -0,0 +1,6 @@
+{
+ "extends": "../tsconfig.base.json",
+ "files": [
+ "../frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts"
+ ]
+}
diff --git a/.typedoc/typedoc.eajs-markdown.config.js b/.typedoc/typedoc.eajs-markdown.config.js
new file mode 100644
index 00000000000..8125712bccb
--- /dev/null
+++ b/.typedoc/typedoc.eajs-markdown.config.js
@@ -0,0 +1,65 @@
+/** @type {import("typedoc").TypeDocOptions} */
+const eajsMarkdownConfig = {
+ name: "EAJS Web Components API",
+ tsconfig: "./tsconfig.eajs-docs.json",
+ plugin: [
+ "typedoc-plugin-mdn-links",
+ "typedoc-plugin-markdown",
+ "./typedoc-plugin-markdown-prepare-for-embedding.js",
+ ],
+ entryPoints: [
+ "../frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts",
+ ],
+ out: "../docs/embedding/eajs/snippets",
+ cleanOutputDir: true,
+ entryFileName: "index",
+ flattenOutputFiles: false,
+ hideBreadcrumbs: true,
+ useCodeBlocks: true,
+ expandObjects: true,
+ expandParameters: true,
+ formatWithPrettier: true,
+ prettierConfigFile: "../.prettierrc",
+ hidePageHeader: true,
+ hidePageTitle: true,
+ hideGroupHeadings: true,
+ indexFormat: "table",
+ parametersFormat: "table",
+ interfacePropertiesFormat: "table",
+ classPropertiesFormat: "table",
+ enumMembersFormat: "table",
+ propertyMembersFormat: "table",
+ typeAliasPropertiesFormat: "table",
+ typeDeclarationFormat: "table",
+ tableColumnSettings: {
+ hideDefaults: false,
+ hideInherited: true,
+ hideModifiers: true,
+ hideOverrides: true,
+ hideSources: true,
+ hideValues: false,
+ leftAlignHeaders: true,
+ },
+
+ // Include everything — the entry point only contains doc interfaces
+ router: "structure",
+ readme: "none",
+ excludePrivate: true,
+ excludeExternals: true,
+ excludeInternal: true,
+ excludeNotDocumented: false,
+ disableSources: true,
+
+ treatWarningsAsErrors: false,
+ treatValidationWarningsAsErrors: true,
+ validation: {
+ notExported: false,
+ invalidLink: true,
+ rewrittenLink: true,
+ notDocumented: false,
+ unusedMergeModuleWith: true,
+ },
+ logLevel: "Warn",
+};
+
+module.exports = eajsMarkdownConfig;
diff --git a/docs/embedding/components.md b/docs/embedding/components.md
index 22b265b73c3..f3e5f6a90ae 100644
--- a/docs/embedding/components.md
+++ b/docs/embedding/components.md
@@ -11,6 +11,8 @@ There are different components you can embed, each with various options.
This page covers what you can embed. For theming your embeds, see [Appearance](./appearance.md).
+> Depending on the framework you're using, you may need to stringify attributes before passing them to the embedded components.
+
## Dashboard
To render a dashboard:
@@ -20,28 +22,12 @@ To render a dashboard:
</metabase-dashboard>
```
-### Required parameters
-
-- `dashboard-id` - This can be a regular ID or an entity ID. [Using Entity IDs](../installation-and-operation/serialization.md#entity-ids-work-with-embedding) in your embeds ensures that the IDs stay stable when exporting from one Metabase and importing to another. Only for SSO. Guest embeds set the id with token.
-
-### Optional parameters
-
-- `with-title` (default is true) - show the dashboard title in the embed
+### Attributes
-{% include plans-blockquote.html feature="More parameters for dashboard component" convert_pro_link_to_embbedding=true is_plural=true%}
-
-- `with-downloads` (default is true on OSS/Starter and false on Pro/Enterprise) - show the button to download the dashboard as PDF and download question results
-- `drills` (default is true) - lets you drill through the dashboard
-- `initial-parameters` - default value for dashboard filters, like `{ 'productId': '42' }`.
-- `with-subscriptions` - let people set up [dashboard subscriptions](../dashboards/subscriptions.md). Unlike subscriptions sent from non-embedded dashboards, subscriptions sent from embedded dashboards exclude links to Metabase items, as Metabase assumes the recipient lacks access to the embedded Metabase.
-- `refresh` - auto-refreshes the dashboard. `refresh="60"` will refresh the dashboard every 60 seconds.
-- `hidden-parameters` - list of filter names to hide from the dashboard, like `['productId']`
-- `enable-entity-navigation` (default is false) - preserves dashboard custom [click behaviors](../dashboards/interactive.md#customizing-click-behavior) that navigate to other dashboards and questions within the embed. Requires `drills` to be true (which is the default). When disabled, only external URL links are kept. See also [`handleLink`](./sdk/plugins.md#handlelink) for customizing what happens when people click URL links.
+{% include_file "{{ dirname }}/eajs/snippets/MetabaseDashboardAttributes.md" snippet="properties" %}
For all modular embeds, you can also set a `locale` in your page-level configuration to [translate embedded content](./translations.md), including content from translation dictionaries.
-Only `with-title` and `with-downloads` are supported in [guest embeds](./guest-embedding.md).
-
If you surround your attribute value with double quotes, make sure to use single quotes:
```html
@@ -72,26 +58,9 @@ To render a question (chart):
<metabase-question question-id="1"></metabase-question>
```
-### Required parameters
-
-- `question-id` - This can be a regular ID or an entity ID. [Using Entity IDs](../installation-and-operation/serialization.md#entity-ids-work-with-embedding) in your embeds ensures that the IDs stay stable when exporting from one Metabase and importing to another. Only for SSO embeds. Guest embeds set the id with a token.
-
- Use `question-id="new"` to embed the query builder exploration interface.
+### Attributes
-### Optional parameters
-
-- `with-title` (default is true) - show the title
-
-{% include plans-blockquote.html feature="More parameters for dashboard component" convert_pro_link_to_embbedding=true is_plural=true%}
-
-- `drills` (default is true) - lets you drill through the question
-- `with-downloads` (default is true on OSS/Starter and false on Pro/Enterprise) - show downloads
-- `initial-sql-parameters` - default value for SQL parameters, only applicable to native SQL questions, like `{ "productId": "42" }`
-- `is-save-enabled` (default is false)
-- `target-collection` - this is to enforce saving into a particular collection. Values: regular ID, entity ID, `"personal"`, `"root"`
-- `with-alerts` (default is false) - let people set up [alerts](../questions/alerts.md) on embedded questions. Requires [email setup](../configuring-metabase/email.md). Unlike alerts on non-embedded questions, alerts on embedded questions only send to the logged-in user and exclude links to Metabase items. Not available for models.
-
-Only `with-title` and `with-downloads` are supported in [guest embeds](./guest-embedding.md).
+{% include_file "{{ dirname }}/eajs/snippets/MetabaseQuestionAttributes.md" snippet="properties" %}
## Browser
@@ -110,19 +79,9 @@ To render a collection browser so people can navigate a collection and open dash
</metabase-browser>
```
-### Required parameters
+### Attributes
-- `initial-collection` - This can be a collection ID or `root`. Use a collection ID (e.g., `14`) to start in a specific collection. Use `root` to start at the top-level, "Our Analytics" collection.
-
-### Optional parameters
-
-- `read-only` (default is true) – if true, people can interact with items (filter, summarize, drill-through) but can't save. If `false`, they can create and edit items in the collection.
-- `collection-visible-columns` – an array of columns to show in the collection browser: `type`, `name`, `description`, `lastEditedBy`, `lastEditedAt`, `archive`. For example, `collection-visible-columns="['type', 'name']"` shows only the type and name columns.
-- `collection-page-size` – how many items to show per page in the collection browser.
-- `collection-entity-types` – an array of entity types to show in the collection browser: `collection`, `dashboard`, `question`, `model`. For example, `collection-entity-types="['collection', 'dashboard']"` shows only collections and dashboards.
-- `data-picker-entity-types` – an array of entity types to show in the question's data picker: `model`, `table`. For example, `data-picker-entity-types="['model']"` shows only models.
-- `with-new-question` (default is true) – whether to show the "New exploration" button.
-- `with-new-dashboard` (default is true) – whether to show the "New dashboard" button. Only applies when `read-only` is false.
+{% include_file "{{ dirname }}/eajs/snippets/MetabaseBrowserAttributes.md" snippet="properties" %}
## AI chat
@@ -136,16 +95,9 @@ To render the AI chat interface:
<metabase-metabot></metabase-metabot>
```
-### Required parameters
-
-None.
-
-### Optional parameters
+### Attributes
-- `layout` (default is `auto`) – how should the browser position the visualization with respect to the chat interface. Possible values are:
- - `auto` (default): Metabot uses the `stacked` layout on mobile screens, and a `sidebar` layout on larger screens.
- - `stacked`: the question visualization stacks on top of the chat interface.
- - `sidebar`: the question visualization appears to the left of the chat interface, which is in the right sidebar.
+{% include_file "{{ dirname }}/eajs/snippets/MetabaseMetabotAttributes.md" snippet="properties" %}
## Customizing loader and error components
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts
index 86c2e240935..7061f7da181 100644
--- a/frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts
@@ -4,6 +4,7 @@ import type {
EmbedAuthManager,
EmbedAuthManagerContext,
} from "metabase/embedding/embedding-iframe-sdk/types/auth-manager";
+import type { ComponentToAttributes } from "metabase/embedding/embedding-iframe-sdk/types/modular-embedding";
import { debouncedReportAnalytics } from "./analytics";
import {
@@ -139,13 +140,13 @@ function assertValidMetabaseConfigField(
}
}
-export abstract class MetabaseEmbedElement
+export abstract class MetabaseEmbedElement<T extends string[] = string[]>
extends HTMLElement
implements EmbedAuthManagerContext
{
private _iframe: HTMLIFrameElement | null = null;
protected abstract _componentName: string;
- protected abstract _attributeNames: readonly string[];
+ protected abstract _attributeNames: T;
static readonly VERSION = "1.1.0";
@@ -499,16 +500,16 @@ export abstract class MetabaseEmbedElement
}
}
-function createCustomElement<Arr extends readonly string[]>(
- componentName: string,
- attributeNames: Arr,
-) {
- const CustomEmbedElement = class extends MetabaseEmbedElement {
+function createCustomElement<
+ T extends keyof ComponentToAttributes,
+ U extends (keyof ComponentToAttributes[T] & string)[],
+>(componentName: T, attributeNames: U) {
+ const CustomEmbedElement = class extends MetabaseEmbedElement<U> {
protected _componentName: string = componentName;
- protected _attributeNames: readonly string[] = attributeNames;
+ protected _attributeNames: U = attributeNames;
static get observedAttributes() {
- return attributeNames as readonly string[];
+ return attributeNames;
}
};
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts
new file mode 100644
index 00000000000..cfa4b80710f
--- /dev/null
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk/types/modular-embedding.ts
@@ -0,0 +1,311 @@
+/**
+ * Types for modular embedding web-components.
+ *
+ * This is the source of truth for all attributes accepted by modular embedding components.
+ *
+ * @module
+ */
+
+/**
+ * Attributes for the `<metabase-dashboard>` web component.
+ *
+ * Embeds a Metabase dashboard. Provide either `dashboard-id` (for SSO embeds)
+ * or `token` (for guest embeds), plus optional display configuration.
+ */
+export interface MetabaseDashboardAttributes {
+ /**
+ * The ID of the dashboard to embed. Can be a regular ID or an
+ * [entity ID](https://www.metabase.com/docs/latest/installation-and-operation/serialization#entity-ids-work-with-embedding).
+ * Only for SSO embeds — guest embeds set the ID with `token`.
+ */
+ "dashboard-id": number | string;
+
+ /**
+ * The token for guest embeds. Set automatically by the guest embed flow.
+ *
+ * @remarks Guest embed
+ */
+ token?: string;
+
+ /**
+ * Whether to show the dashboard title in the embed.
+ *
+ * @defaultValue true
+ * @remarks Guest embed
+ */
+ "with-title"?: boolean;
+
+ /**
+ * Whether to show the button to download the dashboard as PDF and download question results.
+ *
+ * @defaultValue `true` on OSS/Starter, `false` on Pro/Enterprise
+ * @remarks Guest embed
+ */
+ "with-downloads"?: boolean;
+
+ /**
+ * Whether to enable drill-through on the dashboard.
+ *
+ * @defaultValue true
+ * @remarks Pro/Enterprise
+ */
+ drills?: boolean;
+
+ /**
+ * Auto-refresh interval in seconds. For example, `60` refreshes the
+ * dashboard every 60 seconds.
+ *
+ * @remarks Pro/Enterprise, Guest embed
+ */
+ "auto-refresh-interval"?: number;
+
+ /**
+ * Whether to let people set up
+ * [dashboard subscriptions](https://www.metabase.com/docs/latest/dashboards/subscriptions).
+ * Subscriptions sent from embedded dashboards exclude links to Metabase items.
+ *
+ * @remarks Pro/Enterprise
+ */
+ "with-subscriptions"?: boolean;
+
+ /**
+ * Default values for dashboard filters, e.g. `{ 'productId': '42' }`.
+ *
+ * @remarks Pro/Enterprise, Guest embed
+ */
+ "initial-parameters"?: object;
+
+ /**
+ * List of filter names to hide from the dashboard, e.g. `['productId']`.
+ *
+ * @remarks Pro/Enterprise
+ */
+ "hidden-parameters"?: string[];
+
+ /**
+ * Whether to enable internal entity navigation (links to dashboards/questions).
+ * Requires `drills` to be `true`
+ *
+ * @defaultValue false
+ * @remarks Pro/Enterprise
+ */
+ "enable-entity-navigation"?: boolean;
+}
+
+/**
+ * Attributes for the `<metabase-question>` web component.
+ *
+ * Embeds a Metabase question (chart). Provide either `question-id` (for SSO embeds)
+ * or `token` (for guest embeds), plus optional display configuration.
+ * Use `question-id="new"` to embed the query builder exploration interface.
+ * Use `question-id="new-native"` to embed the SQL editor interface.
+ */
+export interface MetabaseQuestionAttributes {
+ /**
+ * The ID of the question to embed. Can be a regular ID or an
+ * [entity ID](https://www.metabase.com/docs/latest/installation-and-operation/serialization#entity-ids-work-with-embedding).
+ * Use `"new"` to embed the query builder. Only for SSO embeds — guest embeds use `token`.
+ */
+ "question-id": number | string;
+
+ /**
+ * The token for guest embeds. Set automatically by the guest embed flow.
+ *
+ * @remarks Guest embed
+ */
+ token?: string;
+
+ /**
+ * Whether to show the question title in the embed.
+ *
+ * @defaultValue true
+ * @remarks Guest embed
+ */
+ "with-title"?: boolean;
+
+ /**
+ * Whether to show download buttons for question results.
+ *
+ * @defaultValue `true` on OSS/Starter, `false` on Pro/Enterprise
+ * @remarks Guest embed
+ */
+ "with-downloads"?: boolean;
+
+ /**
+ * Whether to show the alerts button.
+ *
+ * @defaultValue false
+ * @remarks Pro/Enterprise
+ */
+ "with-alerts"?: boolean;
+
+ /**
+ * Whether to enable drill-through on the question.
+ *
+ * @defaultValue true
+ * @remarks Pro/Enterprise
+ */
+ drills?: boolean;
+
+ /**
+ * Default values for SQL parameters, only applicable to native SQL questions,
+ * e.g. `{ "productId": "42" }`.
+ *
+ * @remarks Pro/Enterprise, Guest embed
+ */
+ "initial-sql-parameters"?: object;
+
+ /**
+ * List of parameter names to hide from the question.
+ *
+ * @remarks Pro/Enterprise
+ */
+ "hidden-parameters"?: string[];
+
+ /**
+ * Whether the save button is enabled.
+ *
+ * @defaultValue false
+ * @remarks Pro/Enterprise
+ */
+ "is-save-enabled"?: boolean;
+
+ /**
+ * The collection to save a question to. Values: regular ID, entity ID,
+ * `"personal"`, `"root"`.
+ *
+ * @remarks Pro/Enterprise
+ */
+ "target-collection"?: number | string;
+
+ /**
+ * Which entity types to show in the question's data picker,
+ * e.g. `["model", "table"]`.
+ *
+ * @remarks Pro/Enterprise, Guest embed
+ */
+ "entity-types"?: ("model" | "table")[];
+}
+
+/**
+ * Attributes for the `<metabase-browser>` web component.
+ *
+ * Embeds a collection browser so people can navigate collections and open
+ * dashboards or questions. Only available for authenticated (SSO) modular embeds.
+ *
+ * @remarks Pro/Enterprise
+ */
+export interface MetabaseBrowserAttributes {
+ /**
+ * Which collection to start from. Use a collection ID (e.g., `14`) to start
+ * in a specific collection, or `"root"` for the top-level "Our Analytics" collection.
+ */
+ "initial-collection": number | string;
+
+ /**
+ * Whether the content manager is in read-only mode. When `true`, people can
+ * interact with items (filter, summarize, drill-through) but can't save.
+ * When `false`, they can create and edit items.
+ *
+ * @defaultValue true
+ */
+ "read-only"?: boolean;
+
+ /**
+ * An array of columns to show in the collection browser:
+ * `type`, `name`, `description`, `lastEditedBy`, `lastEditedAt`, `archive`.
+ */
+ "collection-visible-columns"?: (
+ | "type"
+ | "name"
+ | "description"
+ | "lastEditedBy"
+ | "lastEditedAt"
+ | "archive"
+ )[];
+
+ /**
+ * How many items to show per page in the collection browser.
+ */
+ "collection-page-size"?: number;
+
+ /**
+ * An array of entity types to show in the collection browser:
+ * `collection`, `dashboard`, `question`, `model`.
+ */
+ "collection-entity-types"?: (
+ | "collection"
+ | "dashboard"
+ | "question"
+ | "model"
+ )[];
+
+ /**
+ * An array of entity types to show in the question's data picker:
+ * `model`, `table`.
+ */
+ "data-picker-entity-types"?: ("model" | "table")[];
+
+ /**
+ * Whether to show the "New exploration" button.
+ *
+ * @defaultValue true
+ */
+ "with-new-question"?: boolean;
+
+ /**
+ * Whether to show the "New dashboard" button.
+ * Only applies when `read-only` is `false`.
+ *
+ * @defaultValue true
+ */
+ "with-new-dashboard"?: boolean;
+
+ /**
+ * Whether to enable internal entity navigation (links to dashboards/questions).
+ *
+ * @defaultValue false
+ */
+ "enable-entity-navigation"?: boolean;
+}
+
+/**
+ * Attributes for the `<metabase-metabot>` web component.
+ *
+ * Embeds the AI chat interface. Only available for authenticated (SSO) modular embeds.
+ *
+ * @remarks Pro/Enterprise
+ */
+export interface MetabaseMetabotAttributes {
+ /**
+ * How should the browser position the visualization with respect to the chat
+ * interface. `auto` uses `stacked` on mobile and `sidebar` on larger screens.
+ *
+ * @defaultValue "auto"
+ */
+ layout?: "auto" | "sidebar" | "stacked";
+
+ /**
+ * Whether the save button is enabled.
+ *
+ * @defaultValue false
+ */
+ "is-save-enabled"?: boolean;
+
+ /**
+ * The collection to save a question to.
+ */
+ "target-collection"?: number | string;
+}
+
+/**
+ * Used to enforce types in frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts
+ *
+ * @internal
+ */
+export interface ComponentToAttributes {
+ "metabase-question": MetabaseQuestionAttributes;
+ "metabase-dashboard": MetabaseDashboardAttributes;
+ "metabase-browser": MetabaseBrowserAttributes;
+ "metabase-metabot": MetabaseMetabotAttributes;
+}
diff --git a/package.json b/package.json
index 234dec6af14..e896c816d34 100644
--- a/package.json
+++ b/package.json
@@ -498,6 +498,7 @@
"embedding-sdk:dts:fixup": "node ./bin/embedding-sdk/fixup-types-after-compilation.js",
"embedding-sdk:docs:generate:pure": "typedoc --options ./.typedoc/typedoc.html.config.js && typedoc --options ./.typedoc/typedoc.markdown.config.js",
"embedding-sdk:docs:generate": "bun run build-release:embedding-sdk-package && bun run embedding-sdk:dts:generate && bun run embedding-sdk:docs:generate:pure",
+ "embedding-eajs:docs:generate": "typedoc --options ./.typedoc/typedoc.eajs-markdown.config.js",
"embedding-sdk:cli-snippets:type-check": "./bin/embedding-sdk/type-check-embedding-sdk-cli-snippets.sh",
"embedding-sdk:docs-snippets:type-check": "./bin/embedding-sdk/type-check-embedding-sdk-docs-snippets.sh",
"embedding-sdk:clean:dist": "rm -rf resources/embedding-sdk/dist",