yamchart 0.4.11 → 0.4.12

package/dist/templates/default/CLAUDE.md

@@ -1,9 +1,31 @@
 # {{name}}
 
+This is a [Yamchart](https://github.com/simon-spenc/yamchart) project — Git-native BI dashboards defined as YAML configs and SQL models.
+
 ## Project Notes
 
-Add your project-specific notes, conventions, and context here.
+Add your project-specific notes, conventions, and context here (e.g. database schema, naming conventions, team preferences).
+
+## Quick Start
+
+```bash
+yamchart dev              # Start dev server with hot reload
+yamchart validate         # Validate all config files
+yamchart test             # Run model assertions
+yamchart tables           # List database tables
+yamchart describe <table> # Show table columns
+yamchart search <keyword> # Find tables/columns
+```
+
+## File Structure
+
+- `yamchart.yaml` — project config, default connection, theme, auth
+- `connections/*.yaml` — database connections (DuckDB, Postgres, MySQL, SQLite, Snowflake)
+- `models/*.sql` — SQL with Jinja templating (`{{ param }}`, `{% if %}`, `{{ ref('table') }}`)
+- `charts/*.yaml` — chart definitions (line, bar, area, pie, donut, scatter, kpi, combo, heatmap, funnel, waterfall, gauge, table)
+- `dashboards/*.yaml` — 12-column grid layouts with chart/text widgets, optional tabs
+- `schedules/*.yaml` — cron-based Slack reports and threshold alerts
 
 ## Yamchart Reference
 
-See [docs/yamchart-reference.md](docs/yamchart-reference.md) for the full yamchart configuration reference including chart types, SQL models, dashboards, connections, and formatting options.
+See [docs/yamchart-reference.md](docs/yamchart-reference.md) for the full configuration reference including all chart types, parameters, dashboard tabs, filters, connections, schedules, authentication, and formatting options.

package/dist/templates/default/docs/yamchart-reference.md

@@ -6,11 +6,12 @@ Yamchart is a Git-native BI framework. Dashboards are defined as YAML configs an
 
 ```
 {{name}}/
-├── yamchart.yaml          # Project config + default connection
+├── yamchart.yaml          # Project config, default connection, theme, auth
 ├── connections/            # Database connection configs (.yaml)
 ├── models/                 # SQL models with Jinja templating (.sql)
 ├── charts/                 # Chart definitions (.yaml)
-└── dashboards/             # Dashboard layouts (.yaml)
+├── dashboards/             # Dashboard layouts (.yaml)
+└── schedules/              # Scheduled reports and alerts (.yaml)
 ```
 
 ## Commands
@@ -21,11 +22,16 @@ yamchart validate                     # Validate all config files
 yamchart validate --dry-run           # Also test queries with EXPLAIN
 yamchart test                         # Run model @returns and @tests assertions
 yamchart test <model>                 # Test specific model
+yamchart update                       # Check for and install updates
 yamchart tables                       # List tables in connected database
+yamchart tables --schema public       # Filter to a specific schema
 yamchart describe <table>             # Show columns and types (accepts dbt model names)
 yamchart sample <table>               # Show sample rows (default: 5, accepts dbt model names)
+yamchart sample <table> -l 10         # Custom row limit
 yamchart search <keyword>             # Find tables and columns matching keyword
-yamchart query "SELECT ..."           # Execute ad-hoc SQL
+yamchart query "SELECT ..."           # Execute ad-hoc SQL (default limit: 100)
+yamchart query "SELECT ..." --limit 500  # Custom row limit
+yamchart reset-password --email <e>   # Reset a user's password (requires auth enabled)
 ```
 
 ## SQL Models (`models/*.sql`)
@@ -35,9 +41,13 @@ Models are SQL files with metadata comments and Jinja templating.
 ```sql
 -- @name: model_name
 -- @description: What this model computes
+-- @param start_date: date = 2025-01-01
+-- @param category: string = All
 -- @returns:
---   - column1: type
---   - column2: type
+--   - period: date
+--   - revenue: number
+-- @tests:
+--   - SELECT * FROM ({{this}}) t WHERE revenue < 0
 
 SELECT
   date_trunc('{{ granularity }}', order_date) AS period,
@@ -47,16 +57,21 @@ WHERE order_date BETWEEN '{{ start_date }}' AND '{{ end_date }}'
 {% if category and category != 'All' %}
   AND category = '{{ category }}'
 {% endif %}
+{% if user.department %}
+  AND department = '{{ user.department }}'
+{% endif %}
 GROUP BY 1
 ORDER BY 1
 ```
 
 **Metadata tags:** `@name` (required), `@description`, `@param name: type = default`, `@returns` (column: type list), `@tests` (SQL assertions where zero rows = pass)
 
-**Templating:** `{{ variable }}` for substitution, `{% if %}` / `{% endif %}` for conditionals, `{{ ref('table') }}` for table references, `{{ user.attribute }}` for row-level security.
+**Templating:** `{{ variable }}` for substitution, `{% if %}` / `{% endif %}` for conditionals, `{{ ref('table') }}` for table references, `{{ user.email|role|<attribute> }}` for row-level security.
 
 **Date parameters:** When a chart has `type: date_range`, the model receives `start_date` and `end_date` automatically.
 
+**Tests:** `{{this}}` in `@tests` expands to the compiled SQL. Zero rows returned = pass; any rows = failure.
+
 ## Charts (`charts/*.yaml`)
 
 ### Common Structure
@@ -67,10 +82,16 @@ title: My Chart               # Display title (required)
 description: Description      # Optional
 source:
   model: model_name           # SQL model to use
+  connection: prod            # Optional — override default connection
 parameters: []                # Interactive filters (optional)
 chart:
   type: line                  # Chart type
   # ... type-specific config
+drillDown:                    # Optional — right-click to navigate
+  chart: detail-chart
+  field: category
+refresh:                      # Optional — caching/scheduling
+  cache_ttl: "30m"
 ```
 
 ### Chart Types
@@ -83,6 +104,8 @@ chart:
   y: { field: revenue, format: "$,.0f" }
   series:
     field: category   # Multi-series by grouping field (optional)
+  stacking: stacked   # Optional: stacked or percent (bar/area only)
+  gradient: true      # Optional: auto gradient on fill
 ```
 
 **Pie / Donut** — part-to-whole:
@@ -91,6 +114,10 @@ chart:
   type: pie           # or donut
   x: { field: segment, type: nominal }
   y: { field: amount, format: "$,.0f" }
+  centerValue:        # Donut only — center display
+    field: total      # 'total' sums all values, or use a field name
+    label: "Total"
+    format: "$,.0f"
 ```
 
 **Scatter** — correlations with optional size/group/regression:
@@ -99,28 +126,47 @@ chart:
   type: scatter
   x: { field: revenue, type: quantitative }
   y: { field: orders, type: quantitative }
-  size: { field: avg_value, min: 8, max: 40 }
-  group: { field: region }
-  regression: { type: linear, show_equation: true, show_r_squared: true }
+  size: { field: avg_value, min: 8, max: 40, label: "Avg Value" }  # Bubble encoding
+  group: { field: region }           # Color by category
+  regression:                        # Trend line
+    type: linear
+    show_equation: true
+    show_r_squared: true
 ```
 
-**KPI** — single metric with comparison:
+**KPI** — single metric with optional comparison:
 ```yaml
 chart:
   type: kpi
-  value: { field: value }
+  value: { field: revenue }
   format: { type: currency, currency: USD, decimals: 0 }
-  comparison: { enabled: true, field: previous_value, type: percent_change }
+  unit: "sessions"              # Optional suffix label
+
+  # Option A: Auto comparison (server computes previous period)
+  comparison:
+    enabled: true
+    period: previous            # Server shifts date range back automatically
+    type: percent_change        # or absolute
+
+  # Option B: Manual comparison (use a column from query results)
+  comparison:
+    enabled: true
+    field: previous_value       # Column name with the comparison value
+    label: "vs last month"
+    type: percent_change
 ```
 
+> **Auto comparison:** `period: previous` runs the model a second time with the shifted date range. It infers the shift from the active date preset (e.g. `last_30_days` → previous 30 days). Displays period labels, change badge, and "vs" previous value automatically.
+
 **Heatmap** — two-dimensional intensity:
 ```yaml
 chart:
   type: heatmap
   x: { field: hour, type: ordinal }
   y: { field: day, type: ordinal }
-  value: { field: count }
+  value: { field: count, label: "Count" }
   color_range: { min: '#EBF5FB', max: '#1A5276' }
+  show_values: true
 ```
 
 **Funnel** — conversion stages:
@@ -129,6 +175,7 @@ chart:
   type: funnel
   stage: { field: stage_name }
   value: { field: user_count }
+  show_conversion: true
 ```
 
 **Waterfall** — incremental deltas:
@@ -137,7 +184,11 @@ chart:
   type: waterfall
   category: { field: label }
   value: { field: amount }
-  total_field: is_total
+  total_field: is_total       # Column name marking total rows
+  colors:
+    increase: "#10B981"
+    decrease: "#EF4444"
+    total: "#3B82F6"
 ```
 
 **Gauge** — single metric dial:
@@ -151,6 +202,7 @@ chart:
     - { value: 60, color: '#EF4444' }
     - { value: 85, color: '#F59E0B' }
     - { value: 100, color: '#22C55E' }
+  format: ".1f"
 ```
 
 **Table** — sortable data table (renders all query columns by default):
@@ -178,7 +230,7 @@ chart:
 
 ### Multi-Series
 
-**Long format** — group by a field:
+**Long format** — group by a field in the data:
 ```yaml
 series:
   field: region
@@ -191,19 +243,27 @@ series:
 ```yaml
 series:
   columns:
-    - { field: revenue, name: Revenue, color: "#3B82F6" }
-    - { field: cost, name: Cost, color: "#EF4444", style: dashed }
+    - field: revenue
+      name: Revenue
+      color: "#3B82F6"
+    - field: cost
+      name: Cost
+      color: "#EF4444"
+      style: dashed           # solid, dashed, or dotted
+      opacity: 0.8            # 0–1
+      gradient: true          # or { from: "#hex", to: "#hex" }
 ```
 
 ### Stacking
 
 ```yaml
 chart:
-  type: bar
-  stacking: stacked    # or "percent" (normalizes to 100%)
+  type: bar    # or area
+  stacking: stacked    # normal stacking
+  stacking: percent    # normalizes to 100%, caps y-axis, shows % labels
 ```
 
-### Parameters
+### Parameters (Interactive Filters)
 
 ```yaml
 parameters:
@@ -213,23 +273,47 @@ parameters:
 
   - name: region
     type: select
+    label: Region
     options: [North, South, East, West]
     default: North
 
+  - name: tags
+    type: multi_select
+    options:
+      - value: a
+        label: Category A
+      - value: b
+        label: Category B
+
   - name: category
     type: dynamic_select
     source: { model: category_options, value_field: id, label_field: name }
+
+  - name: search_term
+    type: text
+
+  - name: min_revenue
+    type: number
+    default: 0
+
+  - name: is_active
+    type: boolean
+    default: true
 ```
 
-**Presets for date_range:** today, yesterday, last_7_days, last_30_days, last_90_days, last_365_days, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year
+**Parameter types:** `date_range`, `select`, `multi_select`, `dynamic_select`, `text`, `number`, `boolean`
+
+**Date presets:** `last_7_days`, `last_30_days`, `last_90_days`, `last_12_months`, `year_to_date`, `month_to_date`, `quarter_to_date`, `previous_month`, `previous_quarter`, `previous_year`
 
 ### Drill-Down
 
+Right-click any chart element to navigate to a related detail chart with filtered data.
+
 ```yaml
 drillDown:
   chart: detail-chart    # Target chart name
-  field: category        # Field to pass as filter
-  columns:               # Optional table columns on landing
+  field: category        # Field to pass as filter (defaults to x-axis field)
+  columns:               # Optional table columns on landing page
     - { field: name, label: Name }
     - { field: revenue, label: Revenue, format: "$,.0f" }
 ```
@@ -239,27 +323,53 @@ drillDown:
 ```yaml
 chart:
   gradient: true                        # Auto gradient
+  gradient: { from: "#3B82F6", to: "#1E40AF" }  # Custom gradient
+
   color: "#3B82F6"                      # Single color override
-  color:                                # Conditional coloring
+
+  color:                                # Conditional coloring (bar charts)
     conditions:
       - { when: "> 0", color: "#10B981" }
       - { when: "< 0", color: "#EF4444" }
     default: "#6B7280"
 ```
 
+### Axis Schema
+
+```yaml
+x:
+  field: date
+  type: temporal          # temporal, quantitative, ordinal, or nominal
+  format: "$,.0f"         # Optional d3-format / strftime string
+  label: "Date"           # Optional axis label
+```
+
+### Caching
+
+```yaml
+refresh:
+  cache_ttl: "30m"            # Cache duration: 30s, 5m, 1h, 1d
+  schedule: "0 * * * *"       # Optional cron for pre-warming
+  timezone: America/New_York  # Optional
+```
+
 ## Dashboards (`dashboards/*.yaml`)
 
 12-column grid layout with chart and text widgets.
 
+### Basic Layout
+
 ```yaml
 name: overview
 title: Executive Overview
+description: High-level business metrics
 
-filters:
+filters:                    # Optional — dashboard-level filters (shared across all tabs)
   - { name: date_range, type: date_range, default: last_30_days }
+  - { name: region, type: select, options: [All, North, South], default: All }
 
 layout:
-  gap: 16
+  gap: 16                   # Pixels between widgets (default: 16)
   rows:
     - height: 180
       widgets:
@@ -277,7 +387,62 @@ layout:
             vs last month: {{revenue-kpi@previous_month}}
 ```
 
-**KPI references in text:** `{{chart}}`, `{{chart.field}}`, `{{chart@preset}}`
+### Dashboard Tabs
+
+Split a dashboard into tabbed sub-pages. Use `tabs` instead of `layout` (mutually exclusive).
+
+```yaml
+name: analytics
+title: Analytics Dashboard
+
+filters:                          # Dashboard-level — shown on all tabs
+  - { name: date_range, type: date_range, default: last_30_days }
+
+tabs:
+  - name: overview
+    label: Overview
+    layout:
+      rows:
+        - height: 400
+          widgets:
+            - { type: chart, ref: revenue-trend, cols: 12 }
+
+  - name: details
+    label: Details
+    filters:                      # Tab-level — only shown on this tab
+      - { name: category, type: select, options: [All, A, B, C] }
+    layout:
+      rows:
+        - height: 400
+          widgets:
+            - { type: chart, ref: detail-table, cols: 12 }
+```
+
+Tab navigation is reflected in the URL as `?tab=details`. Dashboard-level filters persist across tabs; tab-level filters are scoped to their tab.
+
+### KPI References in Text Widgets
+
+Embed live KPI values in markdown text widgets:
+
+| Syntax | Description |
+|--------|-------------|
+| `{{chartName}}` | Primary value from a KPI chart |
+| `{{chart.field}}` | Specific field from chart results |
+| `{{chart@preset}}` | Value with a date preset applied |
+| `{{chart@2025-01-01..2025-12-31}}` | Value with a fixed date range |
+
+### Cross-Filtering
+
+Click any chart element on a dashboard to filter all other charts by the clicked dimension. Cross-filters are dashboard-scoped and auto-clear on navigation.
+
+### Edit Mode
+
+The dashboard UI includes an edit mode for drag-and-drop layout editing:
+- Resize and reposition widgets on the grid
+- Add new chart or text widgets via the toolbar
+- Double-click text widgets to edit markdown inline (KPI autocomplete via `{`)
+- Undo/redo support
+- Changes are saved back to the YAML file
 
 ## Connections (`connections/*.yaml`)
 
@@ -296,18 +461,137 @@ database: analytics
 user: ${DB_USER}
 password: ${DB_PASSWORD}
 ssl: true
+schema: public
+
+# MySQL
+name: mysql-db
+type: mysql
+config: { host: ${DB_HOST}, port: 3306, database: mydb }
+auth: { type: env, user_var: MYSQL_USER, password_var: MYSQL_PASSWORD }
+
+# Snowflake
+name: snow
+type: snowflake
+config: { account: xy12345, warehouse: COMPUTE_WH, database: ANALYTICS, schema: PUBLIC }
+auth: { type: env, user_var: SF_USER, password_var: SF_PASSWORD }
+# SSO: auth: { type: externalbrowser, user_var: SF_USER }
+
+# SQLite
+name: local-sqlite
+type: sqlite
+path: ./data/app.db
 ```
 
 **Supported:** DuckDB, PostgreSQL, MySQL, SQLite, Snowflake
 
 Use `${ENV_VAR}` for credentials. Never commit secrets.
 
+## Schedules (`schedules/*.yaml`)
+
+### Scheduled Report
+
+Deliver chart data summaries to Slack on a cron schedule.
+
+```yaml
+name: weekly_sales_report
+type: report
+schedule: "0 9 * * MON"              # Cron (5-6 fields)
+timezone: America/New_York            # Optional
+channel:
+  slack:
+    webhook_url: ${SLACK_WEBHOOK_URL}
+    channel: "#sales"                 # Optional display override
+charts:
+  - revenue_by_region
+  - top_products
+params:
+  date_range: last_7_days
+message: "Weekly sales report"        # Optional header text
+```
+
+### Threshold Alert
+
+Monitor a chart value against a threshold with cooldown.
+
+```yaml
+name: revenue_drop_alert
+type: alert
+schedule: "*/15 * * * *"              # Check every 15 minutes
+channel:
+  slack:
+    webhook_url: ${SLACK_WEBHOOK_URL}
+chart: daily_revenue                  # Single chart
+params:
+  date_range: last_7_days
+condition:
+  field: revenue
+  operator: lt                        # lt, gt, lte, gte, eq
+  value: 1000
+cooldown: "1h"                        # Min time between alerts (30s, 5m, 1h, 1d)
+message: "Revenue dropped below $1,000! Current: ${{value}}"
+```
+
+**Alert behavior:** Evaluates the first row of query results. Empty results skip evaluation. `{{value}}` in the message is replaced with the actual value. Cooldown is in-memory and resets on server restart.
+
+## Authentication (`yamchart.yaml`)
+
+Optional built-in authentication for self-hosted deployments.
+
+```yaml
+auth:
+  enabled: true
+  db_path: ~/.yamchart/auth.db        # Optional (default shown)
+  session_ttl: "30d"                  # Optional (default: 30 days)
+  providers:                          # Optional SSO
+    google:
+      client_id: ${GOOGLE_CLIENT_ID}
+      client_secret: ${GOOGLE_CLIENT_SECRET}
+    microsoft:
+      client_id: ${MS_CLIENT_ID}
+      client_secret: ${MS_CLIENT_SECRET}
+      tenant: ${MS_TENANT_ID}
+    oidc:
+      client_id: ${OIDC_CLIENT_ID}
+      client_secret: ${OIDC_CLIENT_SECRET}
+      issuer: https://auth.example.com
+      display_name: "Company SSO"
+```
+
+- First visit prompts a setup wizard to create an admin account
+- **Roles:** admin (manage users + content), editor (content only), viewer (read-only)
+- **User attributes:** Admins can set key-value pairs per user (e.g. `department: Sales`) for row-level security
+- **RLS in SQL:** `{{ user.email }}`, `{{ user.role }}`, `{{ user.department }}` etc.
+- **CLI recovery:** `yamchart reset-password --email user@example.com`
+
+## Project Config (`yamchart.yaml`)
+
+```yaml
+version: "1"
+name: my-project
+description: Analytics dashboards
+
+defaults:
+  connection: local               # Default connection name
+  cache_ttl: "30m"                # Default cache TTL
+  base_url: https://bi.example.com  # For SSO callbacks and alert links
+  week_start: monday              # sunday–saturday
+
+theme:
+  palette: ["#3B82F6", "#EF4444", "#10B981", "#F59E0B"]
+  gradient: false
+  opacity: 1.0
+
+auth:
+  enabled: false                  # Enable built-in authentication
+```
+
 ## Axis Types
 
 | Type | Use | Example |
 |------|-----|---------|
 | `temporal` | Dates/times | `2024-01-15` |
-| `ordinal` | Categories | `Electronics` |
+| `ordinal` | Ordered categories | `Mon, Tue, Wed` |
+| `nominal` | Unordered categories | `Electronics` |
 | `quantitative` | Numbers | `250.5` |
 
 ## Number Formats (d3-format)
@@ -318,12 +602,4 @@ Use `${ENV_VAR}` for credentials. Never commit secrets.
 | `,.0f` | 1,234 | Numbers |
 | `.2%` | 12.34% | Percentages |
 | `.2s` | 1.2M | SI prefix |
-
-## Theme (`yamchart.yaml`)
-
-```yaml
-theme:
-  palette: ["#3B82F6", "#EF4444", "#10B981", "#F59E0B"]
-  gradient: false
-  opacity: 1.0
-```
+| `.2f` | 1.23 | Fixed decimals |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yamchart",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "Git-native business intelligence dashboards",
   "type": "module",
   "license": "MIT",