dataface 0.1.2__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -0,0 +1,1135 @@
+# Dataface YAML Syntax
+
+Authoring reference for Dataface face YAML. Every option in this file is enforced by the compiler (`extra="forbid"` is set on every model — unknown keys are schema errors).
+
+Browse with `dft docs` (run with no args for the topic catalog, `dft docs <topic>` for one section, `dft docs all` for the whole file).
+
+## Getting Started
+
+Dataface workflow — from a dbt project to a running dashboard.
+
+### Step 1 — Validate your YAML
+
+```bash
+dft validate faces/my_dashboard.yml
+```
+
+`dft validate` performs YAML schema + cross-reference validation. It checks that every field, chart reference, query name, and variable is correctly structured. **No database connection is required.**
+
+To verify that your database connection works, run a simple query:
+
+```bash
+dft query 'SELECT 1' --source <your_source>
+```
+
+A successful result means your data source is reachable.
+
+### Step 2 — Browse your schema
+
+Use `dft schema` to explore available tables and columns before writing SQL:
+
+```bash
+dft schema                      # list configured data sources
+dft schema mydb                 # list schemas in that source
+dft schema mydb main            # list tables in that schema
+dft schema mydb main orders     # profile the orders table (columns, types, samples)
+dft schema mydb main orders id  # profile one column (distribution, sample values)
+```
+
+Never invent column names — always verify them with `dft schema` first.
+
+### Step 3 — Build one chart
+
+Write the minimal YAML needed for a single chart:
+
+```yaml
+source: mydb
+
+queries:
+  revenue: SELECT month, SUM(amount) AS total FROM orders GROUP BY 1 ORDER BY 1
+
+charts:
+  revenue_trend:
+    query: revenue
+    type: line
+    x: month
+    y: total
+
+rows:
+  - revenue_trend
+```
+
+Then validate and render:
+
+```bash
+dft validate faces/my_dashboard.yml
+dft render faces/my_dashboard.yml
+```
+
+Add each additional chart after the previous one validates and renders cleanly.
+
+### Step 4 — Serve locally
+
+```bash
+dft serve
+```
+
+Opens a live-preview server. Edit the YAML and reload the browser to see changes.
+
+**See also:** `dft docs cheatsheet` (minimal examples), `dft docs queries`, `dft docs charts`, `dft docs variables`.
+
+## Cheatsheet
+
+One screen of essentials. Each topic below has a dedicated H2 (`dft docs face`, `dft docs queries`, …) for full coverage.
+
+### Minimal face
+
+```yaml
+source: my_profile
+
+queries:
+  revenue: SELECT month, SUM(amount) AS total FROM orders GROUP BY 1 ORDER BY 1
+
+charts:
+  revenue_trend:
+    query: revenue
+    type: line
+    x: month
+    y: total
+
+rows:
+  - revenue_trend
+```
+
+### Top-level face fields
+
+- `title`, `description`, `tags`
+- `source` / `sources` — default and named data connections
+- `variables` — interactive filter controls
+- `queries` — named SQL / CSV / HTTP / dbt / inline queries
+- `charts` — named chart definitions
+- Exactly one of `rows`, `cols`, `grid`, `tabs` (or `text:` for a text-only face)
+- `theme`, `style`, `id`, `width`, `height` — presentation
+
+### Queries (named, parameterized, inline)
+
+```yaml
+queries:
+  # Bare-string form — SQL inherits the face-level source
+  revenue: SELECT month, SUM(amount) AS total FROM orders GROUP BY 1 ORDER BY 1
+
+  # Long form with options
+  filtered:
+    sql: "SELECT * FROM orders WHERE region = '{{ region }}'"
+    source: warehouse
+
+  # Inline data (no DB needed)
+  targets:
+    columns: [region, target]
+    values:
+      - [US, 100]
+      - [EU, 80]
+```
+
+### Variables
+
+```yaml
+variables:
+  region:
+    input: select                  # See `dft docs variables` for all 14 input types
+    options: { static: [US, EU, APAC] }
+    default: US
+```
+
+Reference variables inside queries with bare `{{ region }}` — no `variables.` prefix.
+
+### Charts
+
+```yaml
+charts:
+  revenue_trend:
+    query: revenue                 # Named query reference
+    type: line                     # See `dft docs charts` for all 29 chart types
+    x: month
+    y: total
+    color: segment
+
+  quick_chart:
+    query: "SELECT month, revenue FROM orders"   # Bare SQL shorthand (no named query needed)
+    type: bar
+    x: month
+    y: revenue
+```
+
+### Layout
+
+Pick exactly one of:
+
+- `rows: [chart_a, chart_b]` — vertical stack
+- `cols: [chart_a, chart_b]` — horizontal arrangement
+- `grid: { columns: 24, items: [...] }` — CSS-grid placement
+- `tabs: { items: [{title: ..., rows: [...]}] }` — tabbed navigation
+
+**See also:** `dft docs face` (full top-level reference),
+`dft docs queries`, `dft docs charts`, `dft docs variables`, `dft docs layout`,
+`dft docs errors` (common error codes), `dft docs all` (whole reference).
+
+## Face
+
+The top-level YAML mapping is a face. Exactly one layout key (`rows`, `cols`, `grid`, `tabs`) must be present unless `text:` is set.
+
+```yaml-schema
+title: "Sales Overview"
+description: "Monthly KPIs and trend"
+tags: [sales, weekly]
+
+source: my_profile             # Shorthand: default source for every query
+# sources: { default: my_profile }   # Equivalent long form
+# sources: { default: warehouse, local_csv: { type: csv, file: data.csv } }
+
+variables:                     # Optional — interactive controls
+queries:                       # Named queries
+charts:                        # Named charts
+rows: [ ... ]                  # Or cols:, grid:, tabs: (pick one)
+
+theme: dark                    # Vega-Lite theme; inherited by nested faces
+
+# Nesting / layout primitives (mostly for nested faces inside rows/cols)
+id: my_face                    # Auto-generated from filename if omitted
+style: { padding: 16, background: "#f8fafc" }
+width: 400                     # Pixels or "50%" when nested
+height: 300
+
+card_gap: false                # When true, adds gap between cards
+chart_focus: revenue_trend     # Render only one chart with its dependent variables
+
+details: "Click to expand"     # Collapsible section
+expanded_title: "Hide details"
+expanded: false
+```
+
+Top-level fields (23 total):
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `title` | string | Display title |
+| `description` | string | Description text |
+| `tags` | list[string] | Tags for categorization/search |
+| `text` | string | Markdown body for text-only faces |
+| `source` | string | Default source shorthand (equivalent to `sources.default`) |
+| `sources` | object | `{default: name, <name>: {type: ...}}` |
+| `variables` | object | See [Variables](#variables) |
+| `queries` | object | See [Queries](#queries) |
+| `charts` | object | See [Charts](#charts) |
+| `rows` | list | Vertical layout — chart names or inline blocks |
+| `cols` | list | Horizontal layout — chart names or inline blocks |
+| `grid` | object | CSS-grid layout (see [Layout](#layout)) |
+| `tabs` | object | Tabbed layout (see [Layout](#layout)) |
+| `card_gap` | bool | Add visible gap between cards (default `false`) |
+| `chart_focus` | string | Render only this chart (with its variables) |
+| `details` | string | Collapsible-section summary text |
+| `expanded_title` | string | Header text when expanded |
+| `expanded` | bool | Default expanded state |
+| `id` | string | Explicit face ID (auto-generated from filename) |
+| `style` | object | Board-style block (see [Board style](#board-style)) |
+| `width` | string \| int | Width when nested (`"50%"` or pixels) |
+| `height` | string \| int | Height when nested |
+| `theme` | string | Vega-Lite theme name (e.g. `dark`, `editorial`, `carbong100`) — inherited by nested faces |
+
+`face:` as a top-level key is rejected. Put face properties (title, rows, queries, …) directly at the YAML root.
+
+### Board style
+
+`style:` on a face, nested face, or layout section accepts a fixed set of keys — not arbitrary CSS:
+
+```yaml
+style:
+  padding: "16px"
+  margin: "0 0 12px 0"
+  background: "#f8fafc"
+  color: "#0f172a"
+  gap: 12
+  border:
+    width: 1
+    color: "#cbd5e1"
+    radius: 8
+  text:
+    align: left
+    column:
+      number: 2
+      gap: 24
+      rule: "1px solid #cbd5e1"
+```
+
+CSS-only keys like `border-radius`, `border-left`, `margin-top` are not board-style fields and are rejected.
+
+#### Title heading levels
+
+`style.title.level` controls the H-level (H1–H6) used for face and chart titles.
+
+```yaml
+# Default — compute from count of titled ancestors (the recommended default).
+# A titled root face is H1, a titled child section is H2, and so on.
+# Bare layout wrappers (no title) do not advance the counter.
+style:
+  title:
+    level: auto
+
+# Lock level to a specific heading — useful for embedded dashboards where
+# H1/H2 are reserved by the outer page.
+style:
+  title:
+    level: 3   # this face and all descendants start from H3
+```
+
+When set to an integer, it cascades to descendants: titled children render at
+`level + 1`, bare wrappers inherit the locked level unchanged.
+
+**See also:** `dft docs queries` (data layer), `dft docs charts` (display layer),
+`dft docs layout` (composition), `dft docs cheatsheet` (one-page essentials).
+
+## Queries
+
+Queries are the data layer. Charts reference queries by name; queries never embed display logic.
+
+```yaml
+source: my_profile             # Optional: default source for every query below
+
+queries:
+  # SQL — the default. `type: sql` is implicit when `sql:` is present.
+  revenue: SELECT month, SUM(amount) AS total FROM orders GROUP BY 1 ORDER BY 1
+
+  # SQL with metadata
+  filtered:
+    description: Monthly revenue filtered by region
+    sql: SELECT * FROM orders WHERE {{ filter('region', region) }}
+    source: warehouse           # Override face-level source
+    setup_sql: CREATE TEMP FUNCTION norm(x FLOAT64) AS (x / 100.0);
+
+  # CSV file
+  targets:
+    type: csv
+    file: data/targets.csv      # Relative to the face YAML file
+    columns: [region, target]
+    delimiter: ","
+    encoding: utf-8
+
+  # HTTP / REST API
+  customers:
+    type: http
+    url: https://api.example.com/customers
+    method: GET                  # GET | POST | PUT | DELETE | PATCH
+    headers: { X-Token: "{{ secrets.token }}" }
+    params: { status: active }
+    body: { ... }
+    json_path: $.data
+
+  # dbt model — read columns directly from a compiled dbt model
+  customers_model:
+    type: dbt_model
+    model: fct_customers
+    columns: [customer_id, arr, region]
+
+  # MetricFlow / dbt Semantic Layer
+  revenue_by_region:
+    type: metricflow             # Optional — also implied by `metrics:` presence
+    metrics: [revenue]
+    dimensions: [region]
+    time_grain: month            # day | week | month | quarter | year
+
+  # Inline values (no database)
+  sample:
+    type: values                 # Optional — also implied by `values:` presence
+    columns: [name, score]
+    values:
+      - [Alice, 92.4]
+      - [Bob, 87.1]
+```
+
+Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema_resolver` is internal-only and not part of the authored surface.
+
+Common fields (all query types):
+
+| Field | Description |
+|-------|-------------|
+| `description` | Metadata sentence for AI search and tooltips |
+| `source` | Source reference (string) or inline source config |
+| `target` | dbt target name (defaults to `dev`) |
+| `filters` | Post-execution result filters |
+| `limit` | Maximum rows returned |
+| `pivot` | Table-rendering cross-tab hint: `{column, value}` |
+| `ignore` | Diagnostic codes to suppress (e.g. `["fanout_risk"]`) |
+
+SQL fields: `sql`, `setup_sql`.
+MetricFlow fields: `metrics`, `dimensions`, `time_grain`.
+HTTP fields: `url`, `method`, `headers`, `params`, `body`, `path`.
+CSV fields: `file`, `filter`.
+dbt-model fields: `model`, `columns`.
+Inline-values fields: `columns`, `values` (or `rows` for record-shape).
+
+Source types (configured via `sources:` or in the project config): `postgres`, `snowflake`, `bigquery`, `redshift`, `mysql`, `duckdb`, `csv`, `json`, `parquet`, `http`, `dbt_profile`.
+
+### Jinja variable injection
+
+Queries are Jinja-rendered before execution. Reference variables as bare names — `{{ region }}` — not with a `variables.` namespace prefix.
+
+```yaml
+variables:
+  region: { input: select, options: { static: [US, EU, APAC] } }
+
+queries:
+  sales:
+    sql: |
+      SELECT month, revenue
+      FROM orders
+      WHERE {{ filter('region', region) }}
+        AND {{ filter_date_range('month', period) }}
+```
+
+For multiline SQL, always use block scalar (`sql: |`). Never use `"SELECT\n…"` or `'SELECT\n…'` — escaped newlines make diffs unreadable and confuse agents learning from examples. Single-line SQL in double quotes is fine: `sql: "SELECT 1 AS n"`.
+
+`filter()` and `filter_date_range()` are helper macros that emit safe SQL predicates for select/multiselect and daterange variables respectively.
+
+**Common multiselect mistake** — `tojson` produces double-quoted strings; most SQL dialects (including DuckDB) treat `"trial"` as a *column reference*, not a string literal. The query silently returns an empty result and `dft render` exits 0.
+
+```sql
+-- WRONG: produces WHERE plan IN ("trial", "pro") — treated as column refs, not strings
+WHERE plan IN ({{ plans | map('tojson') | join(', ') }})
+```
+
+Use the `filter()` macro instead — it emits correctly quoted predicates:
+
+```sql
+-- CORRECT
+WHERE {{ filter('plan', plans) }}
+```
+
+The `filter()` macro handles `select` (single value → `=`) and `multiselect` (list → `IN (...)`) automatically and quotes all string literals correctly.
+
+### Inline query in a chart
+
+A chart can carry its own one-off query instead of referencing a named one. Three equivalent forms:
+
+```yaml
+charts:
+  rev_chart:
+    # Shorthand — bare SQL string (simplest form)
+    query: "SELECT month, revenue FROM orders"
+    type: bar
+    x: month
+    y: revenue
+
+  rev_chart2:
+    # Explicit inline dict
+    query:
+      sql: "SELECT month, revenue FROM orders"
+    type: bar
+    x: month
+    y: revenue
+```
+
+The bare-string shorthand works whenever the value contains a SQL keyword (`SELECT`, `WITH`, `INSERT`, etc.) and is not already a named query. Use `query: {sql: ...}` when you need additional query options (`source:`, `description:`, etc.).
+
+Inline queries are not reusable. Prefer named queries when more than one chart consumes the data.
+
+**See also:** `dft docs variables` (use `{{ var }}` in SQL),
+`dft docs charts` (charts reference queries by name),
+`dft docs errors` (query-execution error codes).
+
+## Charts
+
+Each chart binds a query to a chart type and an encoding. Unknown chart fields are rejected.
+
+```yaml
+charts:
+  revenue_trend:
+    query: revenue            # Name of a query (or inline query def)
+    type: line                # See chart types below
+    title: "Revenue"
+    subtitle: "Last 30 days"
+    description: "AI/tooltip metadata about what this chart answers."
+
+    # Data mapping (the channels)
+    x: month                  # column name
+    y: total                  # column name OR [col, col, ...] for multi-series
+    color: segment            # column | {value: "#ccc"} | {field, scale} | {field, when}
+
+    # Sizing — live at chart root, NOT under style:
+    height: 400               # exact px; bypasses aspect_ratio and min/max clamps
+    aspect_ratio: 2.0         # shape without a fixed size; height = width / aspect_ratio
+    # height and aspect_ratio are ignored on kpi, table, callout, spark_bar
+
+    # Style + behavior
+    sort: { by: total, order: desc }
+    stack: zero               # false | zero | normalize | center
+    format: integer           # named alias or raw D3 spec (e.g. ",.0f")
+    x_label: "Month"
+    y_label: "Revenue (USD)"
+    link: "/orders?month={{ month }}"      # Click-through URL template (drill-down)
+    filters: { ... }                        # Result filters
+
+    style:                    # Chart-local style patch (typed; not raw CSS) — paint only
+      orientation: vertical   # style: does NOT accept height or aspect_ratio
+      stack: true
+```
+
+### Chart types (29 total)
+
+Set `type:` to one of:
+
+**Basic** (one mark per chart) — `bar`, `line`, `area`, `scatter`, `pie`, `donut`, `kpi`, `table`.
+
+**Statistical** — `boxplot`, `errorbar`, `errorband`, `histogram`, `heatmap`.
+
+**Geographic** — `geoshape`, `map`, `point_map`, `bubble_map`.
+
+**Marks** (direct Vega-Lite mark passthroughs; used inside `layered` mostly) — `circle`, `square`, `tick`, `rule`, `trail`, `rect`, `arc`, `image`.
+
+**Composition** — `layered` (see [Composition](#composition)).
+
+**Sparklines** — `spark_bar` (compact horizontal bars used in profiler cards).
+
+**Auxiliary** — `callout` (message card with a `style.tone:` field; `message:` required), `auto` (auto-detect from data — internal-only; not surfaced in UI dropdowns).
+
+Aliases that map to underlying marks: `scatter` → `circle`, `heatmap` → `rect`, `pie` / `donut` → `arc`, `histogram` → `bar` with binning, `map` → `geoshape`.
+
+### Shared chart fields
+
+All chart types accept the channels and style fields below — but each type rejects fields that don't belong to it (e.g. `theta` on a bar chart, `x` on a pie chart).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `x` | string | X-axis field |
+| `y` | string \| list[string] | Y-axis field(s) — list for multi-series |
+| `color` | string \| object | Field name, `{value}`, `{field, scale}`, or `{field, when}` |
+| `size` | string | Field for size encoding |
+| `shape` | string | Field for shape encoding |
+| `opacity` | string \| object | Field name or `{field, scale}` |
+| `stroke` | object | `{color, width}` — each accepts field/scale/when |
+| `theta` | string | Angular field (pie/donut/arc) |
+| `style.inner_radius` | float 0–1 | Donut hole ratio (hole/outer disk; pie/donut only); `type: donut` sets it to `0.6` automatically |
+| `total` | object | `{label, format}` — center total for donut |
+| `labels` | object | `{template, where}` — per-row Jinja annotations near anchors |
+| `x_label` | string | X-axis title override |
+| `y_label` | string | Y-axis title override |
+| `format` | string \| object | D3 format string, preset name, or FormatConfig |
+| `message` | string | Static text for `type: callout` |
+| `geo` | string \| object | GeoJSON field or inline spec (geoshape) |
+| `geo_source` | string | Named geographic data source |
+| `lookup` | string | Field that joins to the geographic source key |
+| `value` | string | KPI: column reference (string column name); map: data field for fill color |
+| `projection` | string \| object | Projection name (e.g. `mercator`, `albersUsa`) or VL projection config |
+| `latitude` | string | Latitude field (point/bubble map) |
+| `longitude` | string | Longitude field (point/bubble map) |
+| `background` | string \| object | Background channel — color, `{value}`, `{field, scale/when}`, or map layer |
+| `sort` | object | `{by, order}` — categorical sort |
+| `stack` | bool \| enum | `false`, `zero`, `normalize`, or `center` |
+| `link` | string | Click-through URL template for drill-down links |
+| `filters` | object | Post-execution row filters: `{col: var_name}` (implicit `eq`) or `{col: {op: var}}` where op is one of `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `ilike`, `in`, `not_in`, `between`. Implicit-eq values may also be Jinja templates (e.g. `"{{ region }}"`) resolved at execute time. A filter is skipped when the variable is `None`, `""`, or renders to `"none"`. |
+| `layers` | list | Layer definitions for `type: layered` (see [Composition](#composition)) |
+| `conditional_formatting` | object | Discrete style rules by column (see [Conditional formatting](#conditional-formatting)) |
+| `data_table` | list | Attached mini-table beneath bar/line/area/layered (see [Composition](#composition)) |
+| `height` | int \| float | Exact pixel height. Wins over `aspect_ratio` and theme defaults. Bypasses `min_height`/`max_height`. Not valid on `kpi`, `table`, `callout`, `spark_bar`. |
+| `aspect_ratio` | float | Chart shape: `height = width / aspect_ratio`. Theme default is `1.5`. Not valid on `kpi`, `table`, `callout`, `spark_bar`. |
+| `min_height` | float | Height floor for this chart only; overrides `style.charts.min_height`. Ignored when `height` is set. |
+| `max_height` | float | Height ceiling for this chart only; overrides `style.charts.max_height`. Ignored when `height` is set. |
+
+`height` and `aspect_ratio` live at **chart root** — they are rejected under `style:`. `style:` is paint only (colors, fonts, marks).
+
+KPI-only fields: `value`, `label`, `support`. KPI uses `label:` for the header text — `title:` is rejected on KPI charts. `glyph` and `tone` moved into the style namespace: use `style.glyph.character` and `style.tone`. To override glyph/value color, use `style.kpi.glyph.font.color` / `style.kpi.value.font.color`.
+
+Top-level chart fields shared by all types: `id`, `query`, `type`, `title`, `subtitle`, `description`, `height`, `aspect_ratio`, `style`, `link`, `filters`, `conditional_formatting`.
+
+### Chart-type cheatsheet
+
+Each block below shows the minimum-viable shape for one chart type. They are stacked for compactness; in a face, each chart sits under its own key in `charts:`.
+
+```yaml-schema
+# bar — categorical x, numeric y
+type: bar
+x: category
+y: value
+color: group           # Optional second dimension; stacks by default
+
+# line — temporal/ordered x, numeric y
+type: line
+x: date
+y: revenue
+color: segment         # Optional: one line per segment
+
+# area — same encoding as line; filled below
+type: area
+x: date
+y: value
+stack: normalize       # 100% stacked
+
+# scatter — x and y numeric
+type: scatter
+x: spend
+y: revenue
+color: region
+size: volume           # Optional bubble size
+
+# pie / donut — pre-aggregated; one row per segment
+type: pie
+theta: revenue
+color: segment
+style:
+  inner_radius: 0.6    # 0 = solid pie; >0 = donut (type: donut sets 0.6 by default)
+total:
+  label: Total
+  format: integer
+labels:
+  template: "{{ segment }}\n{{ revenue | format(',.0f') }}"
+
+# kpi — requires exactly 1 row; value: is a column reference
+type: kpi
+value: total_revenue    # column name (always a column reference)
+label: "Total Revenue"  # NOT `title:` — `title:` is rejected on KPI
+style:
+  glyph:
+    name: "▲"           # glyph character; moved from chart root (ADR-001)
+  tone: positive        # positive | negative | warning; moved from chart root (ADR-001)
+# To override glyph or value color: style.kpi.glyph.font.color / style.kpi.value.font.color
+support:                # Optional support line (same shape: value/label/format/glyph/tone)
+  value: prev_revenue
+  label: "vs last month"
+  format: percent_delta
+  glyph: "▲"
+  tone: positive
+
+# table — renders all query columns unless `style.columns` selects a subset
+type: table
+style:
+  columns:
+    - column: order_id
+    - column: amount
+      label: Amount
+      format: currency_whole
+      align: right                       # left | center | right
+      header_overflow: wrap-two          # clip | truncate | wrap-two | wrap
+      header_link: "/columns/amount"
+      link: "/orders?id={{ order_id }}"
+      background: "#fafafa"
+      font: { color: "#0f172a", weight: "600" }
+      scale:
+        background:
+          palette: ["#f8fafc", "#bae6fd", "#0369a1"]
+          domain: data                   # currently only "data"
+          min: 0
+          max: 1000000
+          null_color: "#eeeeee"
+          hinge: auto                    # number | "auto"
+          arm_mode: asymmetric           # asymmetric | symmetric
+      spark:
+        type: line                       # line | area | bar | bar-normalize | columns
+        color: "#0369a1"
+        height: 24
+        last_visible: true
+      width: 120                         # int (px) or string
+      glyph: "!"
+      glyph_color: "#92400e"
+
+# heatmap — pre-aggregated; one row per (x, y) cell
+type: heatmap
+x: day_of_week
+y: hour
+color: event_count
+
+# histogram — pre-bin in SQL OR use Vega-Lite binning behavior
+type: histogram
+x: amount
+
+# boxplot / errorbar / errorband — statistical primitives
+type: boxplot
+x: region
+y: latency
+
+# geoshape — choropleth via GeoJSON
+type: geoshape
+geo_source: us-states
+lookup: state
+value: revenue
+
+# map — generic choropleth (alias for geoshape with named source)
+type: map
+geo_source: us-states
+lookup: state
+value: revenue
+
+# point_map / bubble_map — lat/lng points (optional size for bubble)
+type: point_map
+latitude: lat
+longitude: lng
+
+type: bubble_map
+latitude: lat
+longitude: lng
+size: events
+color: severity
+
+# spark_bar — compact horizontal bars (used inline in profiler cards)
+type: spark_bar
+x: rank
+y: count
+
+# Pure marks (typically inside layered):
+# circle, square, tick, rule, trail, rect, arc, image
+
+# callout — message card with a style.tone: field (negative | warning | positive)
+type: callout
+message: "Query is disabled in this environment."
+style:
+  tone: warning  # optional; defaults to negative
+
+# auto — internal; engine picks the chart type from the data shape.
+type: auto
+```
+
+### Layered charts
+
+```yaml
+type: layered
+x: month                           # Chart-level shared x
+layers:
+  - type: bar                       # bar | line | area | circle | square | tick | rule | trail | rect | image | scatter
+    y: actual
+    label: Actual
+    fill: "#0369a1"                 # static paint (use fill:, not color: {value:})
+  - type: line
+    y: target
+    label: Target
+    axis_y:
+      orient: right                 # left | right
+      title: "Target"
+```
+
+Each layer accepts: `type`, `query` (optional layer-specific query), `x`, `y`, `label`, `color` (data channel, bare field name), `fill` (static hex paint for fixed-color marks), `size`, `shape`, `axis_y`. Vega-Lite `encoding:` is not allowed inside a layer — use the typed channels.
+
+### Conditional formatting
+
+Discrete, rule-driven style overrides applied per column. Each entry under `conditional_formatting:` is keyed by column name and contains a `when:` list of rules.
+
+```yaml
+charts:
+  accounts_table:
+    type: table
+    query: accounts
+    conditional_formatting:
+      status:
+        when:
+          - in: [blocked, escalated]      # predicate (exactly one per rule)
+            background: "#fee2e2"          # style output (at least one required)
+            font:
+              color: "#991b1b"
+              weight: "600"
+          - is_null: true
+            glyph: "!"
+            glyph_color: "#92400e"
+          - default: true                  # must be LAST in the list when present
+            font: { color: "#334155" }
+```
+
+Predicates (exactly one per rule): `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `between` (`[low, high]`), `in` (non-empty list), `is_null` (bool), `default` (`true` only — terminal fallback).
+
+Style outputs (at least one per rule): `background`, `font` (color/weight/style/decoration), `glyph` (with optional `glyph_color`).
+
+If `default: true` is set, it must be the last rule in the `when` list. Earlier rules win in order.
+
+### Composition
+
+Dataface composes charts in three ways:
+
+1. **`layers:` on `type: layered`** — multiple marks share one x-axis. Listed under [Layered charts](#layered-charts) above. Each layer can have its own `query:`; otherwise all layers share the chart's `query:` (required for `data_table`).
+
+2. **`data_table:` attached to a chart** — a mini cross-tab strip rendered below the chart, columns aligned to the chart's x-axis ticks. Supported on `bar`, `line`, `area`, `layered` only.
+
+   ```yaml
+   charts:
+     revenue_trend:
+       type: line
+       query: monthly
+       x: month
+       y: revenue
+       data_table:
+         - source: revenue          # Read raw per-x value
+           label: "Revenue"
+           format: integer
+         - aggregate: sum            # Per-x aggregate
+           source: orders
+           format: integer
+           label: "Orders"
+         - aggregate: avg
+           source: order_value
+         - per_series: revenue       # One row per color: series (requires `color:` on the chart)
+   ```
+
+   Each entry is one of three shapes (discriminated by which key is present):
+   - `source:` — read the raw per-x value (no aggregation).
+   - `aggregate:` + `source:` — apply an aggregate per x-group (`sum`, `avg`, `min`, `max`, `median`, `count`, `count_distinct` — exact names only, no aliases).
+   - `per_series:` — expand into one row per `color:` series (requires the chart to have a `color:` channel).
+
+   Optional per-entry fields: `format` (D3 format string), `label` (left-stub row label; not allowed on `per_series:`).
+
+   Constraint: data_table requires a single chart-level `x:`. Layered charts with per-layer `x:` differing from the chart-level x are rejected.
+
+3. **Layout composition** — the `rows`, `cols`, `grid`, `tabs` structure in [Layout](#layout). Layout composes charts into a face; chart-level composition belongs to `layered:` and `data_table:`.
+
+Non-goals (not part of the authored chart surface): Vega-Lite `encoding`, `mark`, `spec`, `config`, `transform`, `params`, `resolve`, `hconcat`, `vconcat`, `concat`, `repeat`. These keys are rejected at compile time. Use the typed channels (`x`, `y`, `color`, …) and `style:` instead; use the layout primitives for visual composition.
+
+### Custom chart plugins
+
+Project-local chart types can extend the engine. Drop a `chart_types/<name>.yml` file next to the face files and reference the name in `type:`.
+
+```yaml
+# chart_types/funnel.yml
+name: funnel
+description: Funnel chart for conversion visualization
+mark: bar                              # Underlying Vega-Lite mark
+fields:
+  stage:
+    required: true
+    description: Stage field
+  value:
+    required: true
+    description: Value field
+encoding_overrides:
+  y:
+    type: nominal
+    sort: null
+  x:
+    type: quantitative
+mark_properties:
+  cornerRadius: 4
+```
+
+Then in a face:
+
+```yaml-schema
+charts:
+  conversion_funnel:
+    query: stages
+    type: funnel                       # The plugin name; no `custom:` prefix
+    # The plugin's required fields must be present in the data.
+```
+
+Plugin file fields:
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Lowercase identifier (regex `[a-z][a-z0-9_]*`) — must not shadow a built-in |
+| `mark` | yes | Vega-Lite mark name (must be a valid VL mark) |
+| `description` | no | Used in docs and AI prompts |
+| `fields` | no | `{<name>: {required: bool, description: string}}` |
+| `encoding_overrides` | no | Per-channel Vega-Lite encoding properties merged on top of standard mapping |
+| `mark_properties` | no | Extra properties merged into the mark dict |
+
+Constraints:
+- A plugin cannot shadow a built-in chart type name.
+- The `mark` value must be a valid Vega-Lite mark (validated at load time).
+- Unknown YAML keys in the plugin file are rejected — typos are caught up front.
+
+**See also:** `dft docs queries` (charts reference queries by name),
+`dft docs variables` (use `{{ var }}` in chart queries),
+`dft docs layout` (compose charts on the page),
+`dft docs cheatsheet` (one-page essentials).
+
+## Variables
+
+Variables are the interactive filter layer. Each variable has an `input:` widget type and optional defaults / options.
+
+```yaml
+variables:
+  region:
+    input: select
+    label: "Region"
+    description: "Restrict every query to one region."
+    options:
+      static: [US, EU, APAC]
+    default: US
+```
+
+Input types (14 total):
+
+| Input | Widget |
+|-------|--------|
+| `auto` | Auto-detect from `options` shape (the default) |
+| `select` | Single-value dropdown |
+| `multiselect` | Multi-value dropdown |
+| `input` | Plain text input (alias for `text` in some surfaces) |
+| `text` | Free-text input |
+| `textarea` | Multi-line text input |
+| `number` | Numeric input |
+| `slider` | Single-handle numeric slider |
+| `range` | Two-handle numeric slider (returns `[low, high]`) |
+| `date` | Single date picker (also `datepicker`) |
+| `datepicker` | Single date picker |
+| `daterange` | Date range picker (returns `[start, end]`) |
+| `checkbox` | Boolean toggle |
+| `radio` | Radio group |
+
+Common variable fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `input` | enum | One of the input types above |
+| `label` | string | UI label |
+| `description` | string | Helper text below the input |
+| `default` | any | Default value when no URL param is set |
+| `placeholder` | string | Placeholder text |
+| `required` | bool | Block rendering until a value exists |
+| `allow_null` | bool | `null` is a valid selection |
+| `visible` | bool | Hidden when `false`; still settable via URL param |
+| `disabled` | bool \| string \| `{query, column}` | Static, Jinja expr, or query-backed disable |
+| `data_type` | string | Upstream type hint (informational; preserved through migrations) |
+
+Slider / range fields: `min`, `max`, `step`.
+
+Filter-generation field: `operator` — SQL operator used when generating predicates (e.g. `=`, `IN`, `LIKE`).
+
+Options sources (for `select`, `multiselect`, `radio`):
+
+```yaml
+variables:
+  product:
+    input: select
+    options:
+      static: [All, Electronics, Clothing]    # Hardcoded list
+      # OR
+      query: products_list                     # Query whose first column is the option list
+      column: product_name                     # Optional: which column in that query
+      label_column: product_label              # Optional: separate label column
+
+  region:
+    input: select
+    column: orders.region                      # Auto-populate from a database column
+```
+
+Top-level option-source binding (alternative to `options:`): `column`, `query`, `dimension` (MetricFlow), `measure` (MetricFlow), `model` (dbt).
+
+Disabled forms:
+
+```yaml
+variables:
+  # Static bool
+  closed: { input: checkbox, disabled: true }
+
+  # Jinja expression against current variable values
+  q4_only: { input: select, options: { static: [Q4] }, disabled: "{{ year < 2024 }}" }
+
+  # Query-backed (must return exactly 1 row with the named boolean column)
+  territory:
+    input: select
+    options: { query: territory_options }
+    disabled:
+      query: control_state
+      column: territory_disabled
+```
+
+**Multiselect SQL antipattern** — the first instinct for filtering a multiselect variable in SQL is `IN ({{ plans | map('tojson') | join(', ') }})`. This is wrong: `tojson` produces double-quoted strings (`"trial"`), which most SQL dialects (including DuckDB) treat as *column references*, not string literals. The query silently returns an empty result and `dft render` exits 0.
+
+Use `{{ filter('plan', plans) }}` instead — it emits a correctly quoted `IN (...)` predicate for multiselect and a simple `=` predicate for single-select:
+
+```sql
+-- WRONG: silent empty result
+WHERE plan IN ({{ plans | map('tojson') | join(', ') }})
+
+-- CORRECT
+WHERE {{ filter('plan', plans) }}
+```
+
+Common mistakes (the validator rejects these — listed here so authors don't hit them):
+
+- `options.values: [...]` → use `options.static: [...]`.
+- `default:` nested inside `options:` → put `default:` at the variable level.
+- `options: [a, b]` (bare list) → use `options.static: [a, b]`.
+- Using a `variables.` namespace prefix inside Jinja → drop it and reference the bare variable name (e.g. `{{ region }}`).
+
+**See also:** `dft docs queries` (variables are injected into SQL),
+`dft docs face` (`variables:` is a top-level face field),
+`dft docs cheatsheet` (minimal variable example).
+
+## Layout
+
+Choose exactly one of `rows`, `cols`, `grid`, `tabs` at the face top level (or use `text:` for a text-only face). Layouts nest freely. The block below shows all four side by side; in a real face you pick one.
+
+```yaml-schema
+# rows — vertical stack
+rows:
+  - cols: [kpi_1, kpi_2, kpi_3]         # Equal-width row of charts
+  - cols: [big_chart, 2]                # big_chart takes 2 fractional columns
+  - text: |                              # Markdown block as a row
+      ## Trends
+      Revenue has been increasing since Q2.
+  - revenue_trend                        # Bare chart name = one chart per row
+  - cols: [breakdown_a, breakdown_b]
+  - detail_table
+
+# cols — horizontal arrangement at the top level
+cols:
+  - rows: [kpi_revenue, kpi_users]
+  - rows: [trend_chart]
+
+# grid — CSS-grid placement with explicit positioning
+grid:
+  columns: 24
+  default_width: 8
+  default_height: 1
+  row_height: "120px"
+  gap: md                                # sm | md | lg | xl
+  items:
+    - item: kpi_revenue
+      col: 0
+      row: 0
+      width: 8                            # alias for col_span
+      height: 1                           # alias for row_span
+    - item: trend_chart
+      col: 0
+      row: 1
+      width: 24
+
+# tabs — tabbed navigation
+tabs:
+  id: view                                # URL param + variable name (auto if omitted)
+  position: top                           # top | left
+  default: overview
+  items:
+    - title: Overview
+      icon: 📊
+      description: "KPIs and trend"
+      rows: [kpi_revenue, trend_chart]
+    - title: Details
+      rows: [detail_table]
+    - title: Notes
+      text: |
+        Operational notes go here.
+      style: { padding: 16 }
+```
+
+### Section-level fields (per `rows` / `cols` entry)
+
+```yaml
+rows:
+  - title: "Revenue overview"      # Section heading
+    description: "AI/tooltip context for the section."
+    text: "Monthly trend data."    # Markdown narrative above charts
+    details:                       # Collapsible
+      summary: "Click to expand"
+      expanded_title: "Hide"
+      expanded: false
+    cols: [rev_chart, units_chart]  # Use one of: cols, rows, grid, or tabs
+```
+
+### Layout visibility (`visible`)
+
+Layout items and chart references support a `visible` field that omits the item
+from the rendered output when its condition is falsy.
+
+Accepted forms:
+
+| Form | Example | Behaviour |
+|------|---------|-----------|
+| Omitted | — | Always shown (default) |
+| Static bool | `visible: false` | Always hidden / always shown |
+| Variable name | `visible: show_panel` | Hidden when the variable is falsy; raises if the variable is absent (use `variables.show_panel.default` to ensure it is always defined) |
+| Jinja expression | `visible: "a and b"` | Evaluated as a boolean Jinja expression; no `{{ }}` required |
+| Query probe | `visible: {query: flags, column: show_warm}` | Executes the named query; must return **exactly 1 row** with a boolean-coercible value |
+
+`visible` applies to:
+- Bare chart name items (`- chart_name`)
+- Inline chart items (`- query: ... type: ...`)
+- Nested face items (`rows:`, `cols:`, `text:`, etc.)
+
+> **Layout reflow:** In `rows:` layouts, hidden items collapse and the next item
+> moves up. In `cols:`, `grid:`, and `tabs:` layouts, the slot keeps its
+> pre-computed position — hiding leaves a blank gap. Use `rows:` when you need
+> items to reflow around hidden entries.
+
+> **Distinction from `variables.visible`:** `variables.<name>.visible: false` hides the
+> *input control* in the variable bar only — the variable is still active and URL-settable.
+> Layout-item `visible` controls whether the item renders in the face at all.
+
+```yaml
+variables:
+  show_details:
+    input: checkbox
+    default: false
+
+rows:
+  - summary_kpis
+
+  - visible: show_details
+    rows:
+      - region_map
+      - region_table
+```
+
+### Inline charts inside layout
+
+A layout entry can carry a full chart definition instead of a chart name:
+
+```yaml
+queries:
+  revenue: SELECT month, total FROM rev_daily
+
+rows:
+  - revenue_line:
+      query: revenue
+      type: line
+      x: month
+      y: total
+```
+
+The key under `rows:` becomes the chart's ID.
+
+### Nested faces
+
+A layout entry can be a fully nested face (its own rows/cols/charts and optional `id`, `style`, `width`, `height`, `theme`):
+
+```yaml
+rows:
+  - id: side_panel
+    width: "30%"
+    style: { padding: 12 }
+    rows:
+      - kpi_1
+      - kpi_2
+```
+
+**See also:** `dft docs charts` (chart references inside layouts),
+`dft docs face` (`rows`/`cols`/`grid`/`tabs` are top-level face fields),
+`dft docs cheatsheet` (minimal layout examples).
+
+## Errors
+
+Dataface errors carry a machine-readable code in the form `DF-<CATEGORY>-<SLUG>`. The error message includes the code and a pointer to docs.
+
+```
+DatafaceError [DF-RENDER-KPI-MULTIROW]: KPI chart 'revenue' returned 12 rows but `value` is a column reference.
+  Add LIMIT 1 or aggregate down to one row.
+```
+
+Active code categories (see `dataface/core/errors/codes_*.py` for the authoritative registry):
+
+| Prefix | Meaning |
+|--------|---------|
+| `DF-RENDER-*` | Chart rendering errors (wrong row counts, unknown chart types, format issues) |
+| `DF-EXECUTE-*` | Query execution errors (missing sources, inline-source policy, source typing) |
+| `DF-UNKNOWN-*` | Fallback codes for legacy string-message errors not yet migrated |
+
+The registry is being filled out incrementally — many compile-time and variable-resolution errors still raise as plain `DatafaceError` without a structured code. Today's typed codes:
+
+- **`DF-RENDER-KPI-MULTIROW`** — a KPI chart's query returned more than one row but `value` is a column reference. Add `LIMIT 1` or aggregate down to one row.
+- **`DF-RENDER-UNKNOWN-CHART-TYPE`** — `type:` is not a recognized chart type. See the [Charts](#charts) section for the list.
+- **`DF-RENDER-FORMAT-UNSUPPORTED`** — the render `format` argument is not one of `svg`/`html`/`png`.
+- **`DF-RENDER-NO-LAYOUT`** — the face has no `rows`/`cols`/`grid`/`tabs` and nothing to render.
+- **`DF-RENDER-INPUT-INVALID`** — the render call received structurally invalid input (e.g. both `path` and `yaml_content`).
+- **`DF-EXECUTE-SOURCE-NOT-FOUND`** / **`-NOT-FOUND-EMPTY`** — the query's `source:` (or default source) is not configured in `dataface.yml`.
+- **`DF-EXECUTE-NO-DEFAULT-SOURCE`** — multiple sources are defined and no `default_source` was set.
+- **`DF-EXECUTE-SOURCE-INLINE-FORBIDDEN`** / **`-CROSS-FILE-FORBIDDEN`** — inline source definitions are restricted by project policy.
+- **`DF-EXECUTE-SOURCE-INVALID-TYPE`** / **`-MISSING-TYPE`** — a source definition has an unknown or missing `type:` field.
+
+Run `dft validate <face>` to validate a face and see structured error details.
+
+**See also:** `dft docs queries`, `dft docs charts`, `dft docs variables` (where most errors originate),
+`dft docs all` (whole reference for context).