@bonnard/cli 0.2.16 → 0.3.0

package/dist/docs/topics/dashboards.inputs.md

@@ -0,0 +1,173 @@
+# Inputs
+
+> Interactive filter inputs for dashboards — date range pickers and dropdown selectors.
+
+## Overview
+
+Inputs add interactivity to dashboards. They render as a filter bar above the charts and re-execute queries when values change. Inspired by Evidence.dev's inputs pattern, adapted for the Cube semantic layer.
+
+Two input types are available:
+
+- **DateRange** — preset date range picker that overrides `timeDimension.dateRange`
+- **Dropdown** — dimension value selector that adds/replaces filters
+
+## DateRange
+
+Renders a date range preset picker. When changed, overrides `timeDimension.dateRange` on targeted queries.
+
+```markdown
+<DateRange name="period" default="last-6-months" label="Time Period" />
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | string | Yes | Unique input name |
+| `default` | preset key | No | Initial preset (default: `last-6-months`) |
+| `label` | string | No | Label shown above the picker |
+| `queries` | string | No | Comma-separated query names to target |
+
+### Targeting
+
+Targeting lets you control which queries a filter affects — useful when some charts should stay fixed while others respond to filter changes.
+
+- **No `queries` prop** — applies to ALL queries that have a `timeDimension`
+- **With `queries` prop** — only applies to the listed queries
+
+### Presets
+
+| Key | Label |
+|-----|-------|
+| `last-7-days` | Last 7 Days |
+| `last-30-days` | Last 30 Days |
+| `last-3-months` | Last 3 Months |
+| `last-6-months` | Last 6 Months |
+| `last-12-months` | Last 12 Months |
+| `month-to-date` | Month to Date |
+| `year-to-date` | Year to Date |
+| `last-year` | Last Year |
+| `all-time` | All Time |
+
+## Dropdown
+
+Renders a dropdown selector populated from a query's dimension values. Adds a filter on the specified dimension to targeted queries.
+
+```markdown
+<Dropdown name="channel" dimension="orders.channel" data={channels} queries="main,trend" label="Channel" />
+```
+
+### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | string | Yes | Unique input name |
+| `dimension` | string | Yes | Dimension to filter on |
+| `data` | query ref | Yes | Query that provides the dropdown options |
+| `queries` | string | Yes | Comma-separated query names to filter |
+| `label` | string | No | Label shown above the dropdown |
+| `default` | string | No | Initial selected value (default: All) |
+
+### Behavior
+
+- Always includes an "All" option that removes the filter
+- The dropdown's own `data` query is never filtered by itself (prevents circular dependencies)
+- `queries` is required — the dropdown only filters explicitly listed queries
+
+## Examples
+
+### DateRange only
+
+```markdown
+---
+title: Revenue Trends
+---
+
+<DateRange name="period" default="last-6-months" label="Time Period" />
+
+` ``query monthly_revenue
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: month
+` ``
+
+<LineChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" />
+```
+
+The DateRange automatically applies to `monthly_revenue` because it has a `timeDimension`. No hardcoded `dateRange` needed in the query.
+
+### Dropdown with query binding
+
+```markdown
+---
+title: Sales by Channel
+---
+
+` ``query channels
+dimensions: [orders.channel]
+` ``
+
+<Dropdown name="ch" dimension="orders.channel" data={channels} queries="main" label="Channel" />
+
+` ``query main
+measures: [orders.total_revenue]
+dimensions: [orders.city]
+` ``
+
+<BarChart data={main} x="orders.city" y="orders.total_revenue" />
+```
+
+### Combined inputs
+
+```markdown
+---
+title: Sales Dashboard
+---
+
+<DateRange name="period" default="last-6-months" label="Time Period" />
+<Dropdown name="channel" dimension="orders.channel" data={channels} queries="trend,by_city" label="Channel" />
+
+` ``query channels
+dimensions: [orders.channel]
+` ``
+
+` ``query trend
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: month
+` ``
+
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue" />
+
+` ``query by_city
+measures: [orders.total_revenue]
+dimensions: [orders.city]
+` ``
+
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" />
+```
+
+Both inputs work together: the DateRange scopes the time window on `trend` (which has a timeDimension), and the Dropdown filters both `trend` and `by_city` by channel.
+
+## Shareable URLs
+
+Input values automatically sync to URL query params. When a user changes a filter, the URL updates to reflect the current state — for example:
+
+```
+/dashboards/sales?period=last-30-days&channel=Online
+```
+
+- **Default values are omitted** from the URL for clean links
+- **Sharing a URL** preserves the current filter state — recipients see exactly the same filtered view
+- **Refreshing the page** restores the active filters from the URL
+- The **Copy Link** button in the dashboard header copies the full URL including filter params
+
+DateRange inputs store the preset key (e.g. `last-30-days`), so shared URLs stay relative to today. Dropdown inputs store the selected value string.
+
+## See Also
+
+- [Dashboards](dashboards) — overview and deployment
+- [Components](dashboards.components) — chart and display components
+- [Examples](dashboards.examples) — complete dashboard examples

package/dist/docs/topics/dashboards.md

@@ -0,0 +1,112 @@
+# Dashboards
+
+> Build interactive dashboards from markdown with embedded semantic layer queries.
+
+## Overview
+
+Dashboards let your team track key metrics without leaving the Bonnard app. Define queries once in markdown, deploy them, and every viewer gets live, governed data — no separate BI tool needed. Filters, formatting, and layout are all declared in the same file.
+
+A dashboard is a markdown file with YAML frontmatter, query blocks, and chart components. Write it as a `.md` file, preview locally with `bon dashboard dev`, and deploy with `bon dashboard deploy`.
+
+## Format
+
+A dashboard file has three parts:
+
+1. **Frontmatter** — YAML metadata between `---` delimiters
+2. **Query blocks** — Named data queries in ` ```query ` code fences
+3. **Content** — Markdown text and chart component tags
+
+## Minimal Example
+
+```markdown
+---
+title: Order Summary
+description: Key metrics for the orders pipeline
+---
+
+# Order Summary
+
+` ``query order_count
+measures: [orders.count]
+` ``
+
+<BigValue data={order_count} value="orders.count" title="Total Orders" />
+
+` ``query by_status
+measures: [orders.count]
+dimensions: [orders.status]
+` ``
+
+<BarChart data={by_status} x="orders.status" y="orders.count" />
+```
+
+## Frontmatter
+
+The YAML frontmatter is required and must include `title`:
+
+```yaml
+---
+title: Revenue Dashboard        # Required
+description: Monthly trends     # Optional
+---
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `title` | Yes | Dashboard title displayed in the viewer and listings |
+| `description` | No | Short description shown in dashboard listings |
+
+## Local Preview
+
+Preview a dashboard locally with live reload before deploying. Requires `bon login`.
+
+```bash
+bon dashboard dev revenue.md
+```
+
+This starts a local server, opens your browser, and auto-reloads when you save changes. Queries run against your deployed semantic layer using your own credentials — governance policies apply.
+
+## Deployment
+
+Deploy from the command line or via MCP tools. Each deploy auto-versions the dashboard so you can roll back if needed.
+
+```bash
+# Deploy a markdown dashboard
+bon dashboard deploy revenue.md
+
+# List deployed dashboards
+bon dashboard list
+
+# Open in browser
+bon dashboard open revenue
+
+# Remove a dashboard
+bon dashboard remove revenue
+```
+
+Options:
+- `--slug <slug>` — custom URL slug (default: derived from filename)
+- `--title <title>` — dashboard title (default: from frontmatter)
+
+Via MCP tools, agents can use `deploy_dashboard` with the markdown content as a string.
+
+## Versioning
+
+Every deployment auto-increments the version number and saves a snapshot. You can view version history and restore previous versions via MCP tools (`get_dashboard` with version parameter, `deploy_dashboard` with `restore_version`).
+
+Restoring a version creates a new version (e.g. restoring v2 from v5 creates v6 with v2's content). Version history is never deleted — only `remove_dashboard` deletes all history.
+
+## Governance
+
+Dashboard queries respect the same governance policies as all other queries. When a user views a dashboard:
+
+- **View-level access** — users only see data from views their governance groups allow
+- **Row-level filtering** — user attributes (e.g. region, department) automatically filter query results
+- All org members see the same dashboard list, but may see different data depending on their governance context
+
+## See Also
+
+- [Queries](dashboards.queries) — query syntax and properties
+- [Components](dashboards.components) — chart and display components
+- [Inputs](dashboards.inputs) — interactive filters
+- [Examples](dashboards.examples) — complete dashboard examples

package/dist/docs/topics/dashboards.queries.md

@@ -0,0 +1,112 @@
+# Queries
+
+> Define data queries in dashboard markdown using YAML code fences.
+
+## Overview
+
+Each query fetches data from your semantic layer and makes it available to chart components. Queries use the same measures and dimensions defined in your cubes and views — field names stay consistent whether you're querying from a dashboard, MCP, or the API.
+
+Query blocks have a unique name and map to a `QueryOptions` shape. Components reference them using `data={query_name}`. All field names must be fully qualified with the cube or view name (e.g. `orders.count`, `orders.created_at`).
+
+## Syntax
+
+Query blocks use fenced code with the `query` language tag followed by a name:
+
+````markdown
+```query revenue_trend
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+```
+````
+
+## Query Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `measures` | string[] | No | Fully qualified measures to aggregate (e.g. `[orders.count, orders.total_revenue]`) |
+| `dimensions` | string[] | No | Fully qualified dimensions to group by (e.g. `[orders.status, orders.city]`) |
+| `filters` | Filter[] | No | Row-level filters |
+| `timeDimension` | object | No | Time-based grouping and date range |
+| `orderBy` | object | No | Sort specification (e.g. `{orders.total_revenue: desc}`) |
+| `limit` | number | No | Maximum rows to return |
+
+### timeDimension
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `dimension` | string | Yes | Fully qualified time dimension name (e.g. `orders.created_at`) |
+| `granularity` | string | No | `day`, `week`, `month`, `quarter`, or `year` |
+| `dateRange` | string[] | No | `[start, end]` in `YYYY-MM-DD` format |
+
+### filters
+
+Each filter is an object with:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dimension` | string | Dimension to filter on |
+| `operator` | string | `equals`, `notEquals`, `contains`, `gt`, `gte`, `lt`, `lte` |
+| `values` | array | Values to filter by |
+
+## Examples
+
+### Simple aggregation
+
+````markdown
+```query total_orders
+measures: [orders.count]
+```
+````
+
+### Grouped by dimension
+
+````markdown
+```query revenue_by_city
+measures: [orders.total_revenue]
+dimensions: [orders.city]
+orderBy:
+  orders.total_revenue: desc
+limit: 10
+```
+````
+
+### Time series
+
+````markdown
+```query monthly_revenue
+measures: [orders.total_revenue]
+timeDimension:
+  dimension: orders.created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+```
+````
+
+### With filters
+
+````markdown
+```query completed_orders
+measures: [orders.count, orders.total_revenue]
+dimensions: [orders.category]
+filters:
+  - dimension: orders.status
+    operator: equals
+    values: [completed]
+```
+````
+
+## Rules
+
+- Query names must be valid identifiers (letters, numbers, `_`, `$`)
+- Query names must be unique within a dashboard
+- All field names must be fully qualified with the cube or view name (e.g. `orders.count`, not `count`)
+- Components reference queries by name: `data={query_name}`
+
+## See Also
+
+- [Components](dashboards.components) — chart and display components
+- [Dashboards](dashboards) — overview and deployment
+- [Querying](querying) — query format reference

package/dist/templates/claude/skills/bonnard-build-dashboard/SKILL.md

@@ -1,26 +1,15 @@
 ---
 name: bonnard-build-dashboard
-description: Guide a user through building and deploying a data dashboard 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.
-allowed-tools: Bash(bon *)
+description: Guide a user through building and deploying a markdown dashboard. Use when user says "build a dashboard", "create a chart", "visualize data", or wants to create a dashboard.
+allowed-tools: Bash(bon *), Write, Edit, Read
 ---
 
-# Build & Deploy a Dashboard
+# Build & Deploy a Markdown Dashboard
 
-This skill guides you through creating an HTML dashboard powered by the
-Bonnard SDK and deploying it as a hosted dashboard.
+This skill guides you 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:
 
@@ -38,48 +27,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
 
@@ -91,10 +129,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