docs: dashboard widgets (cube-js#10744)

* docs: add Widgets section under Dashboards

Documents the four dashboard widget types (Chart, Text/Markdown,
Control, AI) as dedicated pages under a new Widgets group, mirroring
the structure used by Omni's Tiles section. Also adds a package.json
for the Mintlify docs site so the dev server can be started with
`yarn dev` on port 3002.

Made-with: Cursor

* docs: align dashboard widget docs with product terminology

- Use "dashboard builder" (the actual product term) instead of
  "dashboard editor"
- Split the Control page into separate Filter widget and Time Grain
  widget pages, matching the product's Add Filter / Add Time Grain
  toolbar buttons and the FILTER / TIME_GRAIN widget types
- Document the real way to add chart widgets (the Charts picker in
  the toolbar)
- Reflect the AI Widget label and Add AI Widget button used in the UI
- Update the product taxonomy rule with the Widget hierarchy under
  Dashboard builder so future docs use the same terms

Made-with: Cursor

* docs: rename and consolidate dashboard widget pages

- Use plural, widget-free titles in the sidebar: Charts, Text,
  Controls, AI summary
- Combine the separate Filter widget and Time grain switcher pages
  into a single Controls page with Filter and Time grain switcher
  sections
- Rename the AI page to AI summary and align the docs with the
  product rename of "AI Widget" / "Add AI Widget" to "AI Summary" /
  "Add AI Summary"
- Document filter / time grain switcher Visibility (Visible, Hidden,
  Disabled)
- Document Controls mapping: automatic mapping when dimensions
  match, manual remap or disable per chart from a chart's settings
  menu, time grain switchers restricted to time-typed dimensions,
  and the fact that AI agents configure these mappings when
  building dashboards
- Replace the bullet list of supported Markdown syntax on the Text
  page with a link to the Markdown Guide
- Update the namings rule to match the new widget taxonomy

Made-with: Cursor

Author: keydunov

.cursor/rules/namings-rule.mdc

@@ -25,6 +25,13 @@ Make sure to use correct terms.
     - **Workbook**
       - Tab
       - Dashboard builder
+        - **Widget**
+          - Charts
+          - Text
+          - Controls 
+            - Filter widget
+            - Time grain switcher
+          - AI summary
     - **Dashboard**
       - Scheduled refresh
     - **Semantic Model**

docs-mintlify/docs.json

@@ -102,7 +102,22 @@
           {
             "group": "Present & Share",
             "pages": [
-              "docs/explore-analyze/dashboards",
+              {
+                "group": "Dashboards",
+                "root": "docs/explore-analyze/dashboards/index",
+                "pages": [
+                  {
+                    "group": "Widgets",
+                    "root": "docs/explore-analyze/dashboards/widgets/index",
+                    "pages": [
+                      "docs/explore-analyze/dashboards/widgets/charts",
+                      "docs/explore-analyze/dashboards/widgets/text",
+                      "docs/explore-analyze/dashboards/widgets/controls",
+                      "docs/explore-analyze/dashboards/widgets/ai-summary"
+                    ]
+                  }
+                ]
+              },
               "docs/explore-analyze/scheduled-refreshes",
               "docs/explore-analyze/notifications"
             ]

…lify/docs/explore-analyze/dashboards.mdx …ocs/explore-analyze/dashboards/index.mdxdocs-mintlify/docs/explore-analyze/dashboards.mdx renamed to docs-mintlify/docs/explore-analyze/dashboards/index.mdx docs-mintlify/docs/explore-analyze/dashboards.mdx renamed to docs-mintlify/docs/explore-analyze/dashboards/index.mdx

@@ -16,6 +16,7 @@ Dashboards enable you to:
 
 ## How it works
 
-Select the reports you want to include from your [workbook][ref-workbooks], arrange them to tell your data story, and publish the dashboard. This gives stakeholders direct access to the insights that matter most, without the complexity of the underlying analysis.
+In the dashboard builder inside your [workbook][ref-workbooks], select the reports you want to include and arrange them on the canvas alongside other [widgets][ref-widgets] to tell your data story, then publish the dashboard. This gives stakeholders direct access to the insights that matter most, without the complexity of the underlying analysis.
 
-[ref-workbooks]: /analytics/workbooks
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-widgets]: /docs/explore-analyze/dashboards/widgets

docs-mintlify/docs/explore-analyze/dashboards/widgets/ai-summary.mdx

@@ -0,0 +1,39 @@
+---
+title: AI summary
+description: Generate natural-language summaries of dashboard data on demand using an AI agent.
+---
+
+AI summary widgets generate a natural-language summary of the data shown on the dashboard. Write a prompt — for example, _"Summarize the key trends and call out anything unusual"_ — and the configured [AI agent][ref-agents] produces a Markdown narrative based on the current dashboard state, including the data behind every chart and the values of any active [controls][ref-controls].
+
+## Adding an AI summary
+
+In the [dashboard builder][ref-workbooks], click **Add AI Summary** in the toolbar. The widget opens with a prompt editor — write your prompt and click **Generate Summary** to produce the first response.
+
+## Use cases
+
+- Add an executive summary at the top of a dashboard
+- Surface anomalies or notable changes since the last refresh
+- Explain numbers to stakeholders who want context without diving into the charts
+- Generate a TL;DR for periodic dashboard distributions
+
+## Writing a prompt
+
+Write the prompt as if you were briefing an analyst — describe the audience, the angle you want, and any specific things to call out. The agent has access to the full dashboard context, so you can reference charts and controls by name.
+
+## Caching
+
+Once generated, the summary is **cached** with the widget. Viewers loading the dashboard see the cached response immediately — they don't pay for regeneration on every page load.
+
+## Staleness detection
+
+The widget keeps a checksum of the dashboard state at the time of generation: the queries behind each chart, the active control values, and the chart configuration. When any of those change, the widget marks the cached summary as **stale** and shows a refresh prompt so viewers know the narrative may no longer match the data.
+
+Click the refresh icon (or open the widget menu and choose **Refresh**) to regenerate using the saved prompt against the latest state.
+
+## Choosing the agent
+
+By default, AI summaries use the agent configured at the dashboard level. You can override the agent per widget when you need a particular [agent's][ref-agents] tooling, model, or guardrails for a specific summary.
+
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-agents]: /admin/ai/spaces-agents-models
+[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls

docs-mintlify/docs/explore-analyze/dashboards/widgets/charts.mdx

@@ -0,0 +1,30 @@
+---
+title: Charts
+description: Display reports from your workbook as visualizations on the dashboard.
+---
+
+Chart widgets display a report from the source [workbook][ref-workbooks] as a visualization on the dashboard. Every chart on a dashboard is backed by a tab in the workbook — when you publish a new version of the workbook, the chart updates accordingly.
+
+## Adding a chart
+
+In the [dashboard builder][ref-workbooks], open the **Charts** picker in the toolbar and select one or more reports from the workbook. A chart is added to the canvas for each selected report, inheriting the report's query, configured visualization, and styling.
+
+If the picker is empty, create the report first in a workbook tab — only published reports are available to add to a dashboard.
+
+## Interaction with controls
+
+Charts respect [controls][ref-controls] — filters and time grain switchers — placed on the same dashboard. A single control can drive multiple charts at once: its value is applied to every chart whose query references the targeted dimension.
+
+## Updating charts
+
+Charts on a published dashboard reflect the most recent published version of the workbook. To change the query, switch the chart type, or restyle the visualization, edit the underlying report in the workbook and publish a new version of the dashboard.
+
+## Title
+
+Each chart shows the name of the underlying workbook tab as its title. To rename it, open the tab in the workbook, rename the tab, and republish the dashboard — the new name flows through to every chart backed by that tab.
+
+Use **Hide Title** in the widget's settings menu to suppress the title on the dashboard — useful when the chart's content already makes the subject obvious, or when an adjacent [text widget][ref-text] provides its own heading. Choose **Show Title** in the same menu to bring it back.
+
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls
+[ref-text]: /docs/explore-analyze/dashboards/widgets/text

docs-mintlify/docs/explore-analyze/dashboards/widgets/controls.mdx

@@ -0,0 +1,98 @@
+---
+title: Controls
+description: Filter and time grain switcher widgets that let dashboard viewers change what's shown on the dashboard.
+---
+
+Controls are widgets that let dashboard viewers change what's shown without leaving the dashboard. The dashboard builder offers two control types — both target a dimension from your semantic model and apply the selected value to every [chart][ref-charts] on the dashboard whose query references that dimension.
+
+- [Filter](#filter) — Narrow the data shown on the dashboard
+- [Time grain switcher](#time-grain-switcher) — Change the granularity of time-based dimensions
+
+## Filter
+
+Filter widgets let viewers narrow down the data shown on the dashboard. In the [dashboard builder][ref-workbooks], click **Add Filter** in the toolbar. The new filter is added in an unconfigured state — click **Configure Filter** (or open the widget's settings menu) to pick a semantic view and a dimension.
+
+### Operators by dimension type
+
+The available operators depend on the type of the underlying dimension:
+
+| Dimension type | Operators |
+|---|---|
+| **String** | `is`, `is not`, `contains`, `not contains`, `starts with`, `not starts with`, `ends with`, `not ends with`, `is null`, `is not null` |
+| **Number** | `is`, `is not`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `is null`, `is not null` |
+| **Time** | `is`, `is not`, `before date`, `before or on date`, `after date`, `after or on date`, `between`, `relative date`, `is null`, `is not null` |
+
+### Single vs. multiple selection
+
+Filters can allow either a single value or multiple values. Configure this when adding or editing the filter — multi-select is the default for string dimensions, while time and number dimensions default to a single value.
+
+### Default values
+
+You can set a default value that's applied when the dashboard loads. Defaults are useful for scoping the dashboard to "this quarter" or "the user's region" without requiring viewers to interact with the filter first.
+
+### Faceted filters
+
+When multiple filters target dimensions from the same semantic view, you can mark them as **faceted**. Faceted filters scope each other's value lists — selecting a value in one filter narrows the options shown in the others, so viewers only see combinations that exist in the data.
+
+For example, on a sales dashboard with a **Country** filter and a **City** filter, marking both as faceted means selecting `United States` in the Country filter limits the City filter to U.S. cities only.
+
+## Time grain switcher
+
+Time grain switchers let viewers change the granularity of time-based dimensions on the dashboard — for example, switching a revenue chart from daily to weekly or monthly. The widget targets a single time dimension and applies the chosen [granularity][ref-granularities] to every chart that groups by that dimension.
+
+In the [dashboard builder][ref-workbooks], click **Add Time Grain** in the toolbar. The new switcher is added in an unconfigured state — open its settings to pick a semantic view and a time dimension.
+
+### Allowed grains
+
+By default, viewers can choose between **day**, **week**, **month**, **quarter**, and **year**. You can narrow this list in the widget's settings to only expose the grains that make sense for the dashboard.
+
+For time dimensions backed by a `TIMESTAMP` or `DATETIME` column, sub-day grains (**second**, **minute**, **hour**) are also available. `DATE`-typed columns don't expose sub-day grains, since they would bucket the entire day into a single point.
+
+Custom granularities defined in the [data model][ref-granularities] appear in the list alongside the built-in grains.
+
+### Default grain
+
+You can configure a default grain that's applied when the dashboard loads. If no default is set, charts use the grain that was saved on the underlying report — viewers can still switch grains, but the dashboard opens with each chart at its original granularity.
+
+## Visibility
+
+Each control has a **Visibility** setting that determines how it appears on the published dashboard. The setting applies to both filters and time grain switchers.
+
+| Visibility | Behavior on the published dashboard |
+|---|---|
+| **Visible** (default) | Shown on the dashboard and viewers can change its value. |
+| **Hidden** | Not shown to viewers, but the control's value is still applied to the charts it targets. Use this to scope a dashboard with a fixed value — e.g., always filter to the current quarter — without exposing the control. |
+| **Disabled** | Shown on the dashboard so viewers can see the active value, but they cannot change it. |
+
+Set the visibility from the **Visibility** dropdown when editing the control. **Hidden** controls remain visible in the dashboard builder so editors can reconfigure them, but disappear from the published view.
+
+## Interaction with charts
+
+When a control is added to a dashboard, it's automatically wired up to every [chart][ref-charts] whose query already uses the same dimension. Charts that don't reference that dimension are left alone, so a dashboard can mix scoped and unscoped views by default. You can override this default per chart from its [Controls mapping](#controls-mapping) — disable the control for that chart, or remap it onto a different dimension.
+
+### Controls mapping
+
+Each chart decides which controls apply to it through its **Controls mapping**. The mapping is resolved automatically in most cases and only needs manual attention when a control targets a dimension the chart doesn't have.
+
+Open **Controls mapping** from a chart's settings menu to inspect or override the mapping for that chart. For each control on the dashboard you can:
+
+- **Toggle the control on or off** for the chart, even when a mapping exists
+- **Pick a different dimension** from the chart's semantic view to remap the control to
+
+Three states show up in the mapping sidebar:
+
+| Status | What it means |
+|---|---|
+| **Mapped automatically** | The control's dimension exists on the chart's semantic view, so it's wired up without configuration. |
+| **Manually mapped** | You (or an AI agent) picked a specific dimension for this chart. **Reset** restores the automatic mapping. |
+| **Can't map automatically** | The control targets a dimension that doesn't exist on the chart's semantic view. The chart is unaffected by the control until you map it manually. |
+
+For [time grain switchers][ref-time-grain], the dimension picker is restricted to time-typed dimensions on the chart's semantic view, since other dimension types can't be resolved by the time grain pipeline.
+
+Mappings are also configurable by AI agents when they build or edit a dashboard, so an agent can wire controls across charts that use different semantic views without you needing to revisit each chart manually.
+
+[ref-time-grain]: #time-grain-switcher
+
+[ref-workbooks]: /docs/explore-analyze/workbooks
+[ref-charts]: /docs/explore-analyze/dashboards/widgets/charts
+[ref-granularities]: /docs/data-modeling/dimensions

docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx

@@ -0,0 +1,19 @@
+---
+title: Widgets
+description: Building blocks for dashboards — charts, text, controls, and AI summaries that you arrange on the canvas to tell your data story.
+---
+
+Widgets are the building blocks of a dashboard. Each tile placed on the canvas in the [dashboard builder][ref-workbooks] is a widget — a chart, a block of text, a control that viewers interact with, or an AI-generated summary. Combine them to assemble polished, interactive views of your data.
+
+## Widget types
+
+The dashboard builder supports the following widget types:
+
+- [Charts](/docs/explore-analyze/dashboards/widgets/charts) — Visualize reports from your workbook
+- [Text](/docs/explore-analyze/dashboards/widgets/text) — Add titles, descriptions, and rich formatting in Markdown
+- [Controls](/docs/explore-analyze/dashboards/widgets/controls) — Let viewers filter the data or switch the time grain
+- [AI summary](/docs/explore-analyze/dashboards/widgets/ai-summary) — Generate narrative summaries of dashboard data on demand
+
+In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, or click **Add Text**, **Add Filter**, **Add Time Grain**, or **Add AI Summary** for the other types.
+
+[ref-workbooks]: /docs/explore-analyze/workbooks

docs-mintlify/docs/explore-analyze/dashboards/widgets/text.mdx

@@ -0,0 +1,27 @@
+---
+title: Text
+description: Add titles, descriptions, and rich formatting to dashboards using Markdown.
+---
+
+Text widgets render Markdown content directly on the dashboard. Use them to add narrative, structure, and context around your charts.
+
+## Adding a text widget
+
+In the [dashboard builder][ref-workbooks], click **Add Text** in the toolbar. A new text widget is added to the canvas with an empty editor.
+
+## Use cases
+
+- Add a dashboard title or section headings to break long dashboards into scannable chunks
+- Explain what stakeholders are looking at and how to interpret the numbers
+- Link out to related dashboards, runbooks, or documentation
+- Embed images, callouts, and formatted lists
+
+## Supported syntax
+
+Text widgets support standard Markdown — see the [Markdown Guide](https://www.markdownguide.org/basic-syntax/) for a full reference of supported syntax.
+
+## Editing
+
+Click the widget's settings menu and choose **Edit** to open the Markdown editor. The widget renders as you type so you can preview formatting before saving. Use **Hide Title** in the same menu to suppress the widget's title bar when the Markdown content already provides its own heading.
+
+[ref-workbooks]: /docs/explore-analyze/workbooks

docs-mintlify/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "cube-docs-mintlify",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Cube documentation site built with Mintlify",
+  "scripts": {
+    "dev": "mintlify dev --port 3002",
+    "build": "mintlify build",
+    "broken-links": "mintlify broken-links"
+  },
+  "devDependencies": {
+    "mintlify": "^4"
+  }
+}