@bonnard/cli 0.2.7 → 0.2.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Bonnard (meal-inc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,24 +2,26 @@
 
 The Bonnard CLI (`bon`) takes you from zero to a deployed semantic layer in minutes. Define metrics in YAML, validate locally, deploy, and query — from your terminal or AI coding agent.
 
-## Install
-
-```bash
-npm install -g @bonnard/cli
-```
-
-Requires Node.js 20+.
+**Open source** — [view source on GitHub](https://github.com/meal-inc/bonnard-cli)
 
 ## Quick start
 
 ```bash
-bon init                        # Create project structure + agent templates
+npx @bonnard/cli init           # Create project structure + agent templates
 bon datasource add --demo       # Add demo dataset (no warehouse needed)
 bon validate                    # Check syntax
 bon login                       # Authenticate with Bonnard
 bon deploy -m "Initial deploy"  # Deploy to Bonnard
 ```
 
+No install needed — `npx` runs the CLI directly. Or install globally for shorter commands:
+
+```bash
+npm install -g @bonnard/cli
+```
+
+Requires Node.js 20+.
+
 ## Commands
 
 | Command | Description |

package/dist/bin/bon.mjs

@@ -12,9 +12,9 @@ import crypto from "node:crypto";
 import { execFileSync } from "node:child_process";
 import { encode } from "@toon-format/toon";
 
-//#region rolldown:runtime
+//#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
-var __exportAll = (all, symbols) => {
+var __exportAll = (all, no_symbols) => {
 	let target = {};
 	for (var name in all) {
 		__defProp(target, name, {
@@ -22,7 +22,7 @@ var __exportAll = (all, symbols) => {
 			enumerable: true
 		});
 	}
-	if (symbols) {
+	if (!no_symbols) {
 		__defProp(target, Symbol.toStringTag, { value: "Module" });
 	}
 	return target;

package/dist/docs/topics/cli.md

@@ -4,6 +4,22 @@
 
 The Bonnard CLI (`bon`) takes you from zero to a deployed semantic layer in minutes. Initialize a project, connect your warehouse, define metrics in YAML, validate locally, and deploy — all from your terminal or your AI coding agent.
 
+## Install
+
+Run directly with `npx` — no install needed:
+
+```bash
+npx @bonnard/cli init
+```
+
+Or install globally for shorter commands:
+
+```bash
+npm install -g @bonnard/cli
+```
+
+Requires Node.js 20+.
+
 ## Agent-ready from the start
 
 `bon init` generates context files for your AI coding tools automatically:

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

@@ -1,4 +1,4 @@
-# dashboards.components
+# Components
 
 > Chart and display components for rendering query results in dashboards.
 
@@ -6,6 +6,15 @@
 
 Components are self-closing HTML-style tags that render query results as charts, tables, or KPI cards. Each component takes a `data` prop referencing a named query.
 
+Choose the component that best fits your data:
+
+- **BigValue** — single KPI number (total revenue, order count)
+- **LineChart** — trends over time
+- **BarChart** — comparing categories (vertical or horizontal)
+- **AreaChart** — cumulative or stacked trends
+- **PieChart** — proportional breakdown (best with 5-7 slices)
+- **DataTable** — detailed rows for drilling into data
+
 ## Syntax
 
 ```markdown
@@ -32,53 +41,68 @@ Displays a single KPI metric as a large number.
 | `data` | query ref | Yes | Query name (should return a single row) |
 | `value` | string | Yes | Measure field name to display |
 | `title` | string | No | Label above the value |
+| `fmt` | string | No | Format preset or Excel code (e.g. `fmt="eur2"`, `fmt="$#,##0.00"`) |
 
 ### LineChart
 
-Renders a line chart, typically for time series.
+Renders a line chart, typically for time series. Supports multiple y columns and series splitting.
 
 ```markdown
 <LineChart data={monthly_revenue} x="created_at" y="total_revenue" title="Revenue Trend" />
+<LineChart data={trend} x="date" y="revenue,cases" />
+<LineChart data={revenue_by_type} x="created_at" y="total_revenue" series="type" />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `data` | query ref | Yes | Query name |
 | `x` | string | Yes | Field for x-axis (typically a time dimension) |
-| `y` | string | Yes | Field for y-axis (typically a measure) |
+| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
 | `title` | string | No | Chart title |
+| `series` | string | No | Column to split data into separate colored lines |
+| `type` | string | No | `"stacked"` for stacked lines (default: no stacking) |
+| `yFmt` | string | No | Format preset or Excel code for tooltip values (e.g. `yFmt="eur2"`) |
 
 ### BarChart
 
-Renders a vertical bar chart. Add `horizontal` for horizontal bars.
+Renders a vertical bar chart. Add `horizontal` for horizontal bars. Supports multi-series with stacked or grouped display.
 
 ```markdown
 <BarChart data={revenue_by_city} x="city" y="total_revenue" />
 <BarChart data={revenue_by_city} x="city" y="total_revenue" horizontal />
+<BarChart data={revenue_by_type} x="month" y="total_revenue" series="type" />
+<BarChart data={revenue_by_type} x="month" y="total_revenue" series="type" type="grouped" />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `data` | query ref | Yes | Query name |
 | `x` | string | Yes | Field for category axis |
-| `y` | string | Yes | Field for value axis |
+| `y` | string | Yes | Field(s) for value axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
 | `title` | string | No | Chart title |
 | `horizontal` | boolean | No | Render as horizontal bar chart |
+| `series` | string | No | Column to split data into separate colored bars |
+| `type` | string | No | `"stacked"` (default) or `"grouped"` for multi-series display |
+| `yFmt` | string | No | Format preset or Excel code for tooltip values (e.g. `yFmt="usd"`) |
 
 ### AreaChart
 
-Renders a filled area chart.
+Renders a filled area chart. Supports series splitting and stacked areas.
 
 ```markdown
 <AreaChart data={monthly_revenue} x="created_at" y="total_revenue" />
+<AreaChart data={revenue_by_source} x="created_at" y="total_revenue" series="source" type="stacked" />
 ```
 
 | Prop | Type | Required | Description |
 |------|------|----------|-------------|
 | `data` | query ref | Yes | Query name |
 | `x` | string | Yes | Field for x-axis |
-| `y` | string | Yes | Field for y-axis |
+| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="revenue,cases"`) |
 | `title` | string | No | Chart title |
+| `series` | string | No | Column to split data into separate colored areas |
+| `type` | string | No | `"stacked"` for stacked areas (default: no stacking) |
+| `yFmt` | string | No | Format preset or Excel code for tooltip values (e.g. `yFmt="pct1"`) |
 
 ### PieChart
 
@@ -97,11 +121,13 @@ Renders a pie/donut chart.
 
 ### DataTable
 
-Renders query results as a table.
+Renders query results as a sortable, paginated table. Click any column header to sort ascending/descending.
 
 ```markdown
 <DataTable data={top_products} />
 <DataTable data={top_products} columns="name,revenue,count" />
+<DataTable data={top_products} rows="25" />
+<DataTable data={top_products} rows="all" />
 ```
 
 | Prop | Type | Required | Description |
@@ -109,8 +135,28 @@ Renders query results as a table.
 | `data` | query ref | Yes | Query name |
 | `columns` | string | No | Comma-separated list of columns to show (default: all) |
 | `title` | string | No | Table title |
+| `fmt` | string | No | Column format map: `fmt="revenue:eur2,date:shortdate"` |
+| `rows` | string | No | Rows per page. Default `10`. Use `rows="all"` to disable pagination. |
+
+**Sorting:** Click a column header to sort ascending. Click again to sort descending. Null values always sort to the end. Numbers sort numerically, strings sort case-insensitively.
+
+**Formatting:** Numbers right-align with tabular figures. Dates auto-detect and won't wrap. Use `fmt` for explicit formatting per column.
+
+## Layout
+
+### Auto BigValue Grouping
+
+Consecutive `<BigValue>` components are automatically wrapped in a responsive grid — no `<Grid>` tag needed:
+
+```markdown
+<BigValue data={total_revenue} value="total_revenue" title="Revenue" />
+<BigValue data={order_count} value="count" title="Orders" />
+<BigValue data={avg_order} value="avg_order_value" title="Avg Order" />
+```
+
+This renders as a 3-column row. The grid auto-sizes up to 4 columns based on the number of consecutive BigValues. For more control, use an explicit `<Grid>` tag.
 
-## Layout: Grid
+### Grid
 
 Wrap components in a `<Grid>` tag to arrange them in columns:
 
@@ -126,12 +172,56 @@ Wrap components in a `<Grid>` tag to arrange them in columns:
 |------|------|---------|-------------|
 | `cols` | string | `"2"` | Number of columns in the grid |
 
+## Formatting
+
+Values are auto-formatted by default — numbers get locale grouping (1,234.56), dates display as "13 Jan 2025", and nulls show as "—". Override with named presets for common currencies and percentages, or use raw Excel format codes for full control.
+
+### Format Presets
+
+| Preset | Excel code | Example output |
+|--------|-----------|---------------|
+| `num0` | `#,##0` | 1,234 |
+| `num1` | `#,##0.0` | 1,234.6 |
+| `num2` | `#,##0.00` | 1,234.56 |
+| `usd` | `$#,##0` | $1,234 |
+| `usd2` | `$#,##0.00` | $1,234.56 |
+| `eur` | `#,##0 "€"` | 1,234 € |
+| `eur2` | `#,##0.00 "€"` | 1,234.56 € |
+| `gbp` | `£#,##0` | £1,234 |
+| `gbp2` | `£#,##0.00` | £1,234.56 |
+| `chf` | `"CHF "#,##0` | CHF 1,234 |
+| `chf2` | `"CHF "#,##0.00` | CHF 1,234.56 |
+| `pct` | `0%` | 45% |
+| `pct1` | `0.0%` | 45.1% |
+| `pct2` | `0.00%` | 45.12% |
+| `shortdate` | `d mmm yyyy` | 13 Jan 2025 |
+| `longdate` | `d mmmm yyyy` | 13 January 2025 |
+| `monthyear` | `mmm yyyy` | Jan 2025 |
+
+Any string that isn't a preset name is treated as a raw Excel format code (ECMA-376). For example: `fmt="revenue:$#,##0.00"`.
+
+Note: Percentage presets (`pct`, `pct1`, `pct2`) multiply by 100 per Excel convention — 0.45 displays as "45%".
+
+### Usage Examples
+
+```markdown
+<!-- BigValue with currency -->
+<BigValue data={total_revenue} value="total_revenue" title="Revenue" fmt="eur2" />
+
+<!-- DataTable with per-column formatting -->
+<DataTable data={sales} fmt="total_revenue:usd2,created_at:shortdate,margin:pct1" />
+
+<!-- Chart with formatted tooltips -->
+<BarChart data={monthly} x="month" y="revenue" yFmt="usd" />
+<LineChart data={trend} x="date" y="growth" yFmt="pct1" />
+```
+
 ## Field Names
 
 Component field names (e.g. `x="city"`, `value="total_revenue"`) use the **unqualified** measure or dimension name — the same names defined in your cube. For example, if your cube has `measures: [{ name: total_revenue, ... }]`, use `value="total_revenue"`.
 
 ## See Also
 
-- dashboards.queries
-- dashboards.examples
-- dashboards
+- [Queries](dashboards.queries) — query syntax and properties
+- [Examples](dashboards.examples) — complete dashboard examples
+- [Dashboards](dashboards) — overview and deployment

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

@@ -1,10 +1,10 @@
-# dashboards.examples
+# Examples
 
 > Complete dashboard examples showing common patterns.
 
 ## Revenue Overview Dashboard
 
-A KPI + trend + breakdown 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
 ---
@@ -64,7 +64,7 @@ orderBy:
 
 ## Sales Pipeline Dashboard
 
-Filtered data with pie chart:
+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
 ---
@@ -114,6 +114,161 @@ filters:
 <AreaChart data={completed_trend} x="created_at" y="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
+cube: orders
+measures: [total_revenue]
+dimensions: [channel]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+` ``
+
+## Stacked Bar (default)
+
+<BarChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" title="Revenue by Channel" />
+
+## Grouped Bar
+
+<BarChart data={revenue_by_channel} x="created_at" y="total_revenue" series="channel" type="grouped" title="Revenue by Channel (Grouped)" />
+
+## Multi-Line
+
+` ``query trend
+cube: orders
+measures: [total_revenue, count]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+` ``
+
+<LineChart data={trend} x="created_at" y="total_revenue,count" title="Revenue vs Orders" />
+
+## Stacked Area by Channel
+
+<AreaChart data={revenue_by_channel} x="created_at" y="total_revenue" series="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
+cube: orders
+measures: [total_revenue, count, avg_order_value]
+` ``
+
+<Grid cols="3">
+<BigValue data={totals} value="total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={totals} value="count" title="Orders" fmt="num0" />
+<BigValue data={totals} value="avg_order_value" title="Avg Order" fmt="eur2" />
+</Grid>
+
+## Revenue Trend
+
+` ``query monthly
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+  dateRange: [2025-01-01, 2025-12-31]
+` ``
+
+<LineChart data={monthly} x="created_at" y="total_revenue" title="Monthly Revenue" yFmt="eur" />
+
+## Detail Table
+
+` ``query details
+cube: orders
+measures: [total_revenue, count]
+dimensions: [category]
+orderBy:
+  total_revenue: desc
+` ``
+
+<DataTable data={details} fmt="total_revenue:eur2,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="channel" data={channels} queries="trend,by_city" label="Channel" />
+
+` ``query channels
+cube: orders
+dimensions: [channel]
+` ``
+
+` ``query kpis
+cube: orders
+measures: [total_revenue, count]
+` ``
+
+<Grid cols="2">
+<BigValue data={kpis} value="total_revenue" title="Revenue" fmt="eur2" />
+<BigValue data={kpis} value="count" title="Orders" fmt="num0" />
+</Grid>
+
+## Revenue Trend
+
+` ``query trend
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+` ``
+
+<LineChart data={trend} x="created_at" y="total_revenue" title="Monthly Revenue" yFmt="eur" />
+
+## By City
+
+` ``query by_city
+cube: orders
+measures: [total_revenue]
+dimensions: [city]
+orderBy:
+  total_revenue: desc
+limit: 10
+` ``
+
+<BarChart data={by_city} x="city" y="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.
+
 ## Tips
 
 - **Start with KPIs**: Use `BigValue` in a `Grid` at the top for key metrics
@@ -122,9 +277,11 @@ filters:
 - **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="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="revenue,cases"` to show multiple measures on one chart
 
 ## See Also
 
-- dashboards
-- dashboards.queries
-- dashboards.components
+- [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

@@ -0,0 +1,179 @@
+# 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="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
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+` ``
+
+<LineChart data={monthly_revenue} x="created_at" y="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
+cube: orders
+dimensions: [channel]
+` ``
+
+<Dropdown name="ch" dimension="channel" data={channels} queries="main" label="Channel" />
+
+` ``query main
+cube: orders
+measures: [total_revenue]
+dimensions: [city]
+` ``
+
+<BarChart data={main} x="city" y="total_revenue" />
+```
+
+### Combined inputs
+
+```markdown
+---
+title: Sales Dashboard
+---
+
+<DateRange name="period" default="last-6-months" label="Time Period" />
+<Dropdown name="channel" dimension="channel" data={channels} queries="trend,by_city" label="Channel" />
+
+` ``query channels
+cube: orders
+dimensions: [channel]
+` ``
+
+` ``query trend
+cube: orders
+measures: [total_revenue]
+timeDimension:
+  dimension: created_at
+  granularity: month
+` ``
+
+<LineChart data={trend} x="created_at" y="total_revenue" />
+
+` ``query by_city
+cube: orders
+measures: [total_revenue]
+dimensions: [city]
+` ``
+
+<BarChart data={by_city} x="city" y="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