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
Implement auto-generated props tables for modular embedding (#69407)
Sébastien0a05ffd76a89
diff --git a/.typedoc/tsconfig.eajs-docs.json b/.typedoc/tsconfig.eajs-docs.jsonnew file mode 100644index 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.jsnew file mode 100644index 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.mdindex 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.+## DashboardTo 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 componentsdiff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk/embed.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk/embed.tsindex 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 HTMLElementimplements 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.tsnew file mode 100644index 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.jsonindex 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",