@bonnard/cli 0.2.15 → 0.2.16

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

@@ -1,343 +0,0 @@
-# Examples
-
-> Complete dashboard examples showing common patterns.
-
-## Revenue Overview Dashboard
-
-The most common dashboard pattern: KPI cards at the top for at-a-glance metrics, a time series chart for trends, and a bar chart with data table for category breakdown.
-
-```markdown
----
-title: Revenue Overview
-description: Monthly revenue trends and breakdowns
----
-
-# Revenue Overview
-
-` ``query total_revenue
-measures: [orders.total_revenue]
-` ``
-
-` ``query order_count
-measures: [orders.count]
-` ``
-
-` ``query avg_order
-measures: [orders.avg_order_value]
-` ``
-
-<Grid cols="3">
-<BigValue data={total_revenue} value="orders.total_revenue" title="Total Revenue" />
-<BigValue data={order_count} value="orders.count" title="Orders" />
-<BigValue data={avg_order} value="orders.avg_order_value" title="Avg Order" />
-</Grid>
-
-## Monthly Trend
-
-` ``query monthly_revenue
-measures: [orders.total_revenue]
-timeDimension:
-  dimension: orders.created_at
-  granularity: month
-  dateRange: [2025-01-01, 2025-12-31]
-` ``
-
-<LineChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" />
-
-## By Category
-
-` ``query by_category
-measures: [orders.total_revenue, orders.count]
-dimensions: [orders.category]
-orderBy:
-  orders.total_revenue: desc
-` ``
-
-<BarChart data={by_category} x="orders.category" y="orders.total_revenue" title="Revenue by Category" />
-<DataTable data={by_category} />
-```
-
-## Sales Pipeline Dashboard
-
-A status-focused dashboard using a pie chart for proportional breakdown, a horizontal bar chart for ranking, and filters to drill into a specific segment.
-
-```markdown
----
-title: Sales Pipeline
-description: Order status breakdown and city analysis
----
-
-# Sales Pipeline
-
-` ``query by_status
-measures: [orders.count]
-dimensions: [orders.status]
-` ``
-
-<PieChart data={by_status} name="orders.status" value="orders.count" title="Order Status" />
-
-## Top Cities
-
-` ``query top_cities
-measures: [orders.total_revenue, orders.count]
-dimensions: [orders.city]
-orderBy:
-  orders.total_revenue: desc
-limit: 10
-` ``
-
-<BarChart data={top_cities} x="orders.city" y="orders.total_revenue" horizontal />
-<DataTable data={top_cities} />
-
-## Completed Orders Over Time
-
-` ``query completed_trend
-measures: [orders.total_revenue]
-timeDimension:
-  dimension: orders.created_at
-  granularity: week
-  dateRange: [2025-01-01, 2025-06-30]
-filters:
-  - dimension: orders.status
-    operator: equals
-    values: [completed]
-` ``
-
-<AreaChart data={completed_trend} x="orders.created_at" y="orders.total_revenue" title="Completed Order Revenue" />
-```
-
-## Multi-Series Dashboard
-
-When you need to compare segments side-by-side, use the `series` prop to split data by a dimension into colored segments. This example shows stacked bars, grouped bars, multi-line, and stacked area — all from the same data.
-
-```markdown
----
-title: Revenue by Channel
-description: Multi-series charts showing revenue breakdown by sales channel
----
-
-# Revenue by Channel
-
-` ``query revenue_by_channel
-measures: [orders.total_revenue]
-dimensions: [orders.channel]
-timeDimension:
-  dimension: orders.created_at
-  granularity: month
-  dateRange: [2025-01-01, 2025-12-31]
-` ``
-
-## Stacked Bar (default)
-
-<BarChart data={revenue_by_channel} x="orders.created_at" y="orders.total_revenue" series="orders.channel" title="Revenue by Channel" />
-
-## Grouped Bar
-
-<BarChart data={revenue_by_channel} x="orders.created_at" y="orders.total_revenue" series="orders.channel" type="grouped" title="Revenue by Channel (Grouped)" />
-
-## Multi-Line
-
-` ``query trend
-measures: [orders.total_revenue, orders.count]
-timeDimension:
-  dimension: orders.created_at
-  granularity: month
-  dateRange: [2025-01-01, 2025-12-31]
-` ``
-
-<LineChart data={trend} x="orders.created_at" y="orders.total_revenue,orders.count" title="Revenue vs Orders" />
-
-## Stacked Area by Channel
-
-<AreaChart data={revenue_by_channel} x="orders.created_at" y="orders.total_revenue" series="orders.channel" type="stacked" title="Revenue by Channel" />
-```
-
-## Formatted Dashboard
-
-Use format presets to display currencies, percentages, and number styles consistently across KPIs, charts, and tables.
-
-```markdown
----
-title: Sales Performance
-description: Formatted revenue metrics and trends
----
-
-# Sales Performance
-
-` ``query totals
-measures: [orders.total_revenue, orders.count, orders.avg_order_value]
-` ``
-
-<Grid cols="3">
-<BigValue data={totals} value="orders.total_revenue" title="Revenue" fmt="eur2" />
-<BigValue data={totals} value="orders.count" title="Orders" fmt="num0" />
-<BigValue data={totals} value="orders.avg_order_value" title="Avg Order" fmt="eur2" />
-</Grid>
-
-## Revenue Trend
-
-` ``query monthly
-measures: [orders.total_revenue]
-timeDimension:
-  dimension: orders.created_at
-  granularity: month
-  dateRange: [2025-01-01, 2025-12-31]
-` ``
-
-<LineChart data={monthly} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" yFmt="eur" />
-
-## Detail Table
-
-` ``query details
-measures: [orders.total_revenue, orders.count]
-dimensions: [orders.category]
-orderBy:
-  orders.total_revenue: desc
-` ``
-
-<DataTable data={details} fmt="orders.total_revenue:eur2,orders.count:num0" />
-```
-
-## Interactive Dashboard
-
-Combine a DateRange picker and Dropdown filter to let viewers explore the data. Filter state syncs to the URL, so shared links preserve the exact filtered view.
-
-```markdown
----
-title: Interactive Sales
-description: Sales dashboard with date and channel filters
----
-
-# Interactive Sales
-
-<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 kpis
-measures: [orders.total_revenue, orders.count]
-` ``
-
-<Grid cols="2">
-<BigValue data={kpis} value="orders.total_revenue" title="Revenue" fmt="eur2" />
-<BigValue data={kpis} value="orders.count" title="Orders" fmt="num0" />
-</Grid>
-
-## Revenue Trend
-
-` ``query trend
-measures: [orders.total_revenue]
-timeDimension:
-  dimension: orders.created_at
-  granularity: month
-` ``
-
-<LineChart data={trend} x="orders.created_at" y="orders.total_revenue" title="Monthly Revenue" yFmt="eur" />
-
-## By City
-
-` ``query by_city
-measures: [orders.total_revenue]
-dimensions: [orders.city]
-orderBy:
-  orders.total_revenue: desc
-limit: 10
-` ``
-
-<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="Top Cities" yFmt="eur" />
-```
-
-The `<DateRange>` automatically applies to all queries with a `timeDimension` (here: `trend`). The `<Dropdown>` filters `trend` and `by_city` by channel. The `channels` query populates the dropdown and is never filtered by it.
-
-## Compact Multi-Section Dashboard
-
-A dashboard with multiple sections, side-by-side charts, and compact layout. Uses `##` headings (not `#`), `<Grid>` for horizontal grouping, and keeps all queries near the components that use them.
-
-```markdown
----
-title: Operations Overview
-description: KPIs, trends, and breakdowns across channels and cities
----
-
-<DateRange name="period" default="last-30-days" label="Period" />
-
-` ``query channels
-dimensions: [orders.channel]
-` ``
-
-<Dropdown name="channel" dimension="orders.channel" data={channels} queries="kpis,trend,by_city" label="Channel" />
-
-## Key Metrics
-
-` ``query kpis
-measures: [orders.total_revenue, orders.count, orders.avg_order_value]
-` ``
-
-<BigValue data={kpis} value="orders.total_revenue" title="Revenue" fmt="eur" />
-<BigValue data={kpis} value="orders.count" title="Orders" fmt="num0" />
-<BigValue data={kpis} value="orders.avg_order_value" title="Avg Order" fmt="eur2" />
-
-## Trends & Breakdown
-
-` ``query trend
-measures: [orders.total_revenue]
-timeDimension:
-  dimension: orders.created_at
-  granularity: week
-` ``
-
-` ``query by_channel
-measures: [orders.total_revenue]
-dimensions: [orders.channel]
-orderBy:
-  orders.total_revenue: desc
-` ``
-
-<Grid cols="2">
-<LineChart data={trend} x="orders.created_at" y="orders.total_revenue" title="Weekly Revenue" yFmt="eur" />
-<BarChart data={by_channel} x="orders.channel" y="orders.total_revenue" title="By Channel" yFmt="eur" />
-</Grid>
-
-## Top Cities
-
-` ``query by_city
-measures: [orders.total_revenue, orders.count]
-dimensions: [orders.city]
-orderBy:
-  orders.total_revenue: desc
-limit: 10
-` ``
-
-<Grid cols="2">
-<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="Revenue by City" horizontal yFmt="eur" />
-<DataTable data={by_city} fmt="orders.total_revenue:eur,orders.count:num0" />
-</Grid>
-```
-
-Key patterns:
-- **`##` headings** for sections — compact, no oversized H1s
-- **Consecutive `<BigValue>`** auto-groups into a row (no Grid needed)
-- **`<Grid cols="2">`** pairs a chart with a table or two charts side by side
-- **Queries defined before their Grid** — keeps the layout clean and components grouped
-
-## Tips
-
-- **Start with KPIs**: Use `BigValue` at the top for key metrics — consecutive BigValues auto-group into a row
-- **One query per chart**: Each component gets its own query — keep them focused
-- **Use `##` headings**: Reserve `#` for the dashboard title (in frontmatter). Use `##` for sections
-- **Use views**: Prefer view names over cube names when available
-- **Name queries descriptively**: `monthly_revenue` is better than `q1`
-- **Limit large datasets**: Add `limit` to dimension queries to avoid oversized charts
-- **Time series**: Always use `timeDimension` with `granularity` for time-based charts
-- **Multi-series**: Use `series="cube.column"` to split data by a dimension. For bars, default is stacked; use `type="grouped"` for side-by-side
-- **Multiple y columns**: Use comma-separated values like `y="orders.revenue,orders.cases"` to show multiple measures on one chart
-- **Side-by-side charts**: Wrap pairs in `<Grid cols="2">` to reduce vertical scrolling
-
-## See Also
-
-- [Dashboards](dashboards) — overview and deployment
-- [Queries](dashboards.queries) — query syntax and properties
-- [Components](dashboards.components) — chart and display components

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

@@ -1,173 +0,0 @@
-# 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

@@ -1,115 +0,0 @@
-# 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, deploy with `bon dashboard deploy`, and view it in the Bonnard web app.
-
-## 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
-slug: revenue-dashboard         # Optional (derived from title if omitted)
----
-```
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `title` | Yes | Dashboard title displayed in the viewer and listings |
-| `description` | No | Short description shown in dashboard listings |
-| `slug` | No | URL-safe identifier. Auto-derived from title if omitted |
-
-## 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 single dashboard
-bon dashboard deploy revenue.md
-
-# Deploy all dashboards in a directory
-bon dashboard deploy dashboards/
-
-# List deployed dashboards
-bon dashboard list
-
-# Remove a dashboard
-bon dashboard remove revenue-dashboard
-```
-
-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:
-
-```bash
-# Via MCP tools:
-# get_dashboard with version parameter to fetch a specific version
-# deploy_dashboard with slug + restore_version to roll back
-```
-
-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.
-
-## Sharing
-
-Dashboard viewers include a **Share** menu in the header with:
-
-- **Copy link** — copies the current URL including any active filter state
-- **Print to PDF** — opens the browser print dialog for PDF export
-
-Filter state (DateRange presets, Dropdown selections) is encoded in URL query params, so shared links preserve the exact filtered view the sender was looking at.
-
-## 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