@bonnard/cli 0.2.16 → 0.3.0

package/dist/templates/cursor/rules/bonnard-build-dashboard.mdc

@@ -1,25 +1,14 @@
 ---
-description: "Guide for building and deploying data dashboards using the Bonnard SDK and Chart.js. Use when user says 'build a dashboard', 'create a chart', 'visualize data', or wants to deploy an HTML dashboard."
+description: "Guide for building and deploying markdown dashboards with built-in chart components. Use when user says 'build a dashboard', 'create a chart', 'visualize data', or wants to create a dashboard."
 alwaysApply: false
 ---
 
-# Build & Deploy a Dashboard
+# Build & Deploy a Markdown Dashboard
 
-This guide walks through creating an HTML dashboard powered by the
-Bonnard SDK and deploying it as a hosted dashboard.
+This guide walks through creating a markdown dashboard with built-in
+chart components and deploying it to Bonnard.
 
-## Phase 1: Get the Starter Template
-
-Fetch the SDK + Chart.js starter template:
-
-```bash
-bon docs sdk.chartjs
-```
-
-This shows a working HTML template with `@bonnard/sdk` loaded from CDN and
-a Chart.js example. Copy this as your starting point.
-
-## Phase 2: Explore Available Data
+## Phase 1: Explore Available Data
 
 Discover what measures and dimensions are available to query:
 
@@ -37,48 +26,97 @@ bon query --sql "SELECT MEASURE(total_revenue), date FROM sales_performance LIMI
 Ask the user what data they want to visualize. Match their request to
 available views and measures.
 
-## Phase 3: Build the HTML File
+## Phase 2: Learn the Format
 
-Create an HTML file that:
-1. Loads `@bonnard/sdk` from CDN (see the template from Phase 1)
-2. Initializes the SDK with a publishable key placeholder
-3. Queries the semantic layer for the data the user wants
-4. Renders charts using Chart.js (or another chart library)
+Review the dashboard format docs for reference:
+
+```bash
+bon docs dashboards              # Overview + format
+bon docs dashboards.components   # Chart components (BigValue, LineChart, BarChart, etc.)
+bon docs dashboards.queries      # Query block syntax
+bon docs dashboards.inputs       # Interactive filters (DateRange, Dropdown)
+bon docs dashboards.examples     # Complete examples
+```
+
+## Phase 3: Build the Markdown File
+
+Create a `.md` file with three parts:
+
+1. **YAML frontmatter** — title and optional description
+2. **Query blocks** — ` ```query name ` code fences with YAML query options
+3. **Components** — `<BigValue />`, `<LineChart />`, `<BarChart />`, etc.
 
 Key points:
-- The SDK uses `Bonnard.query()` to fetch data from the deployed semantic layer
-- Use the view names and measure/dimension names from Phase 2
-- The publishable key will be provided by the user or can be created with `bon keys create`
-- Keep the HTML self-contained (inline CSS/JS, load libraries from CDN)
+- All field names must be fully qualified: `orders.total_revenue`, not `total_revenue`
+- Each component references a query by name: `data={query_name}`
+- Consecutive `<BigValue>` components auto-group into a row
+- Use `<Grid cols="2">` to place charts side by side
+- Use `<DateRange>` and `<Dropdown>` for interactive filters
 
-Save the file (e.g., `dashboard.html`).
+Example structure:
+
+```markdown
+---
+title: Revenue Dashboard
+description: Key revenue metrics and trends
+---
+
+` ``query total_revenue
+measures: [orders.total_revenue]
+` ``
+
+` ``query order_count
+measures: [orders.count]
+` ``
+
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={order_count} value="orders.count" title="Orders" />
+
+## Trend
+
+` ``query monthly
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: month
+` ``
+
+<LineChart data={monthly} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" yFmt="eur" />
+```
+
+Save the file (e.g., `dashboard.md`).
 
 ## Phase 4: Preview Locally
 
-Let the user preview the file in their browser before deploying.
-They'll need to set a valid publishable key in the HTML first.
+Preview the dashboard with live reload:
 
 ```bash
-# Create a publishable key if needed
-bon keys create --name "Dashboard" --type publishable
+bon dashboard dev dashboard.md
 ```
 
+This opens a browser with the rendered dashboard. Edit the `.md` file and
+the preview updates automatically. Queries run against the deployed
+semantic layer using the user's credentials.
+
+Requires `bon login` — no API key needed.
+
 ## Phase 5: Deploy
 
-Deploy the HTML file as a hosted dashboard on Bonnard:
+Deploy the dashboard to Bonnard:
 
 ```bash
-bon dashboard deploy dashboard.html
+bon dashboard deploy dashboard.md
 ```
 
 This will:
-- Upload the HTML content
+- Upload the markdown content
 - Assign a slug (derived from filename, or use `--slug`)
-- Print the public URL where the dashboard is accessible
+- Extract the title from frontmatter
+- Print the URL where the dashboard is accessible
 
 Options:
 - `--slug <slug>` — custom URL slug (default: derived from filename)
-- `--title <title>` — dashboard title (default: from `<title>` tag)
+- `--title <title>` — override frontmatter title
 
 ## Phase 6: View Live
 
@@ -90,10 +128,10 @@ bon dashboard open dashboard
 
 ## Iteration
 
-To update the dashboard, edit the HTML file and redeploy:
+To update, edit the `.md` file and redeploy:
 
 ```bash
-bon dashboard deploy dashboard.html
+bon dashboard deploy dashboard.md
 ```
 
 Each deploy increments the version. Use `bon dashboard list` to see all

package/dist/templates/shared/bonnard.md

@@ -73,7 +73,8 @@ All tables are in the `contoso` schema. The datasource is named `contoso_demo`.
 | `bon query '{...}'` | Query the deployed semantic layer (requires `bon deploy` first, not for raw DB access) |
 | `bon mcp` | Show MCP setup instructions for AI agents |
 | `bon docs` | Browse documentation |
-| `bon dashboard deploy <file>` | Deploy an HTML file as a hosted dashboard |
+| `bon dashboard dev <file>` | Preview a markdown dashboard locally with live reload |
+| `bon dashboard deploy <file>` | Deploy a markdown or HTML dashboard |
 | `bon dashboard list` | List deployed dashboards with URLs |
 | `bon dashboard remove <slug>` | Remove a deployed dashboard |
 | `bon dashboard open <slug>` | Open a deployed dashboard in the browser |
@@ -114,7 +115,7 @@ Topics follow dot notation (e.g., `cubes.dimensions.time`). Use `--recursive` to
 For a guided walkthrough: `/bonnard-get-started`
 For projects migrating from Metabase: `/bonnard-metabase-migrate`
 For design principles: `/bonnard-design-guide`
-For building dashboards with SDK + charts: `/bonnard-build-dashboard`
+For building markdown dashboards: `/bonnard-build-dashboard` (see also `bon docs dashboards`)
 
 ## Deployment & Change Tracking