@bonnard/cli 0.2.16 → 0.3.0

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

@@ -0,0 +1,246 @@
+# Components
+
+> Chart and display components for rendering query results in dashboards.
+
+## Overview
+
+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
+<ComponentName data={query_name} prop="value" />
+```
+
+- Components are self-closing (`/>`)
+- `data` uses curly braces: `data={query_name}`
+- Other props use quotes: `x="orders.city"`
+- Boolean props can be shorthand: `horizontal`
+
+## Component Reference
+
+### BigValue
+
+Displays a single KPI metric as a large number.
+
+```markdown
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name (should return a single row) |
+| `value` | string | Yes | Fully qualified 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. Supports multiple y columns and series splitting.
+
+```markdown
+<LineChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" title="Revenue Trend" />
+<LineChart data={trend} x="orders.created_at" y="orders.total_revenue,orders.count" />
+<LineChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.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(s) for y-axis. Comma-separated for multiple (e.g. `y="orders.total_revenue,orders.count"`) |
+| `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. Supports multi-series with stacked or grouped display.
+
+```markdown
+<BarChart data={revenue_by_city} x="orders.city" y="orders.total_revenue" />
+<BarChart data={revenue_by_city} x="orders.city" y="orders.total_revenue" horizontal />
+<BarChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.type" />
+<BarChart data={revenue_by_type} x="orders.created_at" y="orders.total_revenue" series="orders.type" type="grouped" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `x` | string | Yes | Field for category axis |
+| `y` | string | Yes | Field(s) for value axis. Comma-separated for multiple (e.g. `y="orders.total_revenue,orders.count"`) |
+| `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. Supports series splitting and stacked areas.
+
+```markdown
+<AreaChart data={monthly_revenue} x="orders.created_at" y="orders.total_revenue" />
+<AreaChart data={revenue_by_source} x="orders.created_at" y="orders.total_revenue" series="orders.source" type="stacked" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `x` | string | Yes | Field for x-axis |
+| `y` | string | Yes | Field(s) for y-axis. Comma-separated for multiple (e.g. `y="orders.total_revenue,orders.count"`) |
+| `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
+
+Renders a pie/donut chart.
+
+```markdown
+<PieChart data={by_status} name="orders.status" value="orders.count" title="Order Status" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `data` | query ref | Yes | Query name |
+| `name` | string | Yes | Field for slice labels |
+| `value` | string | Yes | Field for slice values |
+| `title` | string | No | Chart title |
+
+### DataTable
+
+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="orders.category,orders.total_revenue,orders.count" />
+<DataTable data={top_products} rows="25" />
+<DataTable data={top_products} rows="all" />
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `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="orders.total_revenue:eur2,orders.created_at: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="orders.total_revenue" title="Revenue" />
+<BigValue data={order_count} value="orders.count" title="Orders" />
+<BigValue data={avg_order} value="orders.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.
+
+### Grid
+
+Wrap components in a `<Grid>` tag to arrange them in columns:
+
+```markdown
+<Grid cols="3">
+<BigValue data={total_orders} value="orders.count" title="Orders" />
+<BigValue data={total_revenue} value="orders.total_revenue" title="Revenue" />
+<BigValue data={avg_order} value="orders.avg_order_value" title="Avg Order" />
+</Grid>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cols` | string | `"2"` | Number of columns in the grid |
+
+### Layout Best Practices
+
+**Use `##` for sections, not `#`.** The `#` heading renders very large and wastes vertical space. Use `##` for section titles and `###` for subsections. Reserve `#` for the dashboard title only (which is set in frontmatter, not in the body).
+
+**Group related charts side by side.** Wrap pairs of charts in `<Grid cols="2">` to avoid long vertical scrolling:
+
+```markdown
+<Grid cols="2">
+<BarChart data={by_channel} x="orders.channel" y="orders.total_revenue" title="By Channel" />
+<BarChart data={by_city} x="orders.city" y="orders.total_revenue" title="By City" horizontal />
+</Grid>
+```
+
+**Start each section with KPIs.** Place `<BigValue>` cards at the top of a section for at-a-glance metrics, then follow with charts for detail.
+
+**Only Grid together components of similar height.** Don't mix a `<BigValue>` with a chart in the same `<Grid>` row — the grid stretches both cells to the tallest item, leaving the BigValue card with a large empty area. Instead, place KPIs in their own row (consecutive BigValues auto-group) and pair charts with other charts of similar size.
+
+**Keep it compact.** A good dashboard fits key information in 2-3 screens of scrolling. Use Grids, concise titles, and avoid unnecessary headings between every chart.
+
+## 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="orders.total_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="orders.total_revenue" title="Revenue" fmt="eur2" />
+
+<!-- DataTable with per-column formatting -->
+<DataTable data={sales} fmt="orders.total_revenue:usd2,orders.created_at:shortdate,orders.margin:pct1" />
+
+<!-- Chart with formatted tooltips -->
+<BarChart data={monthly} x="orders.created_at" y="orders.total_revenue" yFmt="usd" />
+<LineChart data={trend} x="orders.created_at" y="orders.growth" yFmt="pct1" />
+```
+
+## Field Names
+
+All field names in component props must be **fully qualified** with the view or cube name — the same format used in query blocks. For example, use `value="orders.total_revenue"` not `value="total_revenue"`.
+
+## See Also
+
+- [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

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