dataface 0.1.6.dev558__py3-none-any.whl → 0.1.6.dev622__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -114,6 +114,12 @@ rows:
 ### Queries (named, parameterized, inline)
 
 ```yaml
+variables:
+  region:
+    input: select
+    options:
+      static: [US, EU, APAC]
+
 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
@@ -342,6 +348,12 @@ Queries are the data layer. Charts reference queries by name; queries never embe
 ```yaml
 source: my_profile             # Optional: default source for every query below
 
+variables:
+  region:
+    input: select
+    options:
+      static: [US, EU, APAC]
+
 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
@@ -423,6 +435,7 @@ Queries are Jinja-rendered before execution. Reference variables as bare names
 ```yaml
 variables:
   region: { input: select, options: { static: [US, EU, APAC] } }
+  period: { input: daterange }
 
 queries:
   sales:
@@ -518,7 +531,7 @@ charts:
     style:                    # Chart-local style patch (typed; not raw CSS) — paint only
       orientation: vertical   # style: does NOT accept height or aspect_ratio
       number_format: ",.0f"   # D3 format string or named alias for axis/tooltip format
-      stack: zero               # false | true | zero | normalize | center
+      stack: zero               # none | zero | normalize | center
 ```
 
 ### Chart types (29 total)

dataface/agent_api/__init__.py

@@ -53,11 +53,18 @@ from dataface.agent_api.schema_hints import (
     SchemaHints as SchemaHints,
     schema_hints as schema_hints,
 )
-from dataface.agent_api.validate import ValidateDashboardArgs, ValidateResult
+from dataface.agent_api.validate import (
+    ValidateDashboardArgs,
+    ValidateResult,
+)
 from dataface.agent_api.validate_query import (
     QueryDiagnostic as QueryDiagnostic,
     validate_query as validate_query,
 )
+from dataface.core.compile.compiler import (
+    CompileResult as CompileResult,
+    compile as compile,
+)
 from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
 from dataface.core.dashboard import (
     RenderedDashboard as RenderedDashboard,
@@ -69,6 +76,8 @@ from dataface.core.render.board_links import LinkContext as LinkContext
 from dataface.core.render.errors import RenderError as RenderError
 
 __all__ = [
+    "compile",
+    "CompileResult",
     "DescribeFaceArgs",
     "DescribeFaceResult",
     "DocsArgs",

dataface/agent_api/docs/yaml-reference.md

@@ -578,7 +578,6 @@ Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -595,7 +594,7 @@ Authored overlay for BarChartStyle. Bar chart style: chart-level fields + marks
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
 | `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
-| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar charts; None uses the renderer default (VL stacks by default). |
+| `stack` | enum: "none", "zero", "normalize", "center" | ✓ | Default stack mode for bar charts; none renders side-by-side columns. |
 | `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. None/'value' puts the largest aggregate at baseline. 'data' follows SQL row order (orientation-stable not guaranteed). 'alphabetical' sorts by color field name. Ignored when stacking is off or no color. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for bar charts. |
 | `marks` | [BarChartMarksStyle](#barchartmarksstyle) | ✓ | Bar-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
@@ -615,7 +614,6 @@ Authored overlay for LineChartStyle. Line chart style: chart-level fields + mark
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -649,7 +647,6 @@ Authored overlay for AreaChartStyle. Area chart style: chart-level fields + mark
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -665,7 +662,7 @@ Authored overlay for AreaChartStyle. Area chart style: chart-level fields + mark
 | `scale` | [ScaleStyle](#scalestyle) | ✓ | Chart-type encoding scale overrides applied to both x and y; None means no override. |
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
 | `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
-| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for area charts; False overlaps silhouettes. |
+| `stack` | enum: "none", "zero", "normalize", "center" | ✓ | Default stack mode for area charts; none overlaps silhouettes. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration for area charts. |
 | `marks` | [AreaChartMarksStyle](#areachartmarksstyle) | ✓ | Area-family mark overrides. Unset fields fall back to [`style.charts.marks`](#chartsstyle). |
 
@@ -684,7 +681,6 @@ Authored overlay for ScatterChartStyle. Scatter chart style: chart-level fields
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -717,7 +713,6 @@ Authored overlay for HeatmapChartStyle. Heatmap chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -762,7 +757,6 @@ Authored overlay for PieChartStyle. Pie/donut chart style: geometry + total (fla
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -796,7 +790,6 @@ Authored overlay for KpiChartStyle. Produced by cascade from theme YAML.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -825,7 +818,6 @@ Authored overlay for TableChartStyle. Table chart style overrides layered on top
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Table background color; None inherits from theme. |
@@ -883,7 +875,6 @@ Authored overlay for PointMapChartStyle. Point map chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -908,7 +899,6 @@ Authored overlay for GeoshapeChartStyle. Geoshape (choropleth) chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -959,7 +949,6 @@ Flat style patch for layered multi-mark charts.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style overrides. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style overrides. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -976,7 +965,7 @@ Flat style patch for layered multi-mark charts.
 | `range` | [RangeStyle](#rangestyle) | ✓ | Color range/palette overrides for this chart type; None means no override. |
 | `data_table` | [DataTableStyle](#datatablestyle) | ✓ | Per-chart-type data_table style override. Unset fields fall back to [`style.charts.data_table`](#chartsstyle). |
 | `orientation` | enum: "horizontal", "vertical", "auto" | ✓ | Preferred bar orientation; None uses the renderer default (vertical). |
-| `stack` | enum: "zero", "normalize", "center" | ✓ | Default stack mode for bar/area charts. |
+| `stack` | enum: "none", "zero", "normalize", "center" | ✓ | Default stack mode for bar/area charts. |
 | `stack_order` | enum: "value", "data", "alphabetical" | ✓ | Z-order of stacked segments. |
 | `endpoint_labels` | [EndpointLabelsConfig](#endpointlabelsconfig) | ✓ | Endpoint label pane configuration. |
 | `marks` | [LayeredMarksStyle](#layeredmarksstyle) | ✓ | Per-mark-type style overrides (bar/line/area/point). |
@@ -1102,7 +1091,7 @@ Authored overlay for TitleStyle. Board and face titles.
 | `min_height` | float | ✓ | Minimum title row height in pixels. |
 | `overflow` | str | ✓ | Text overflow mode (clip, truncate, wrap-two, wrap). |
 | `position` | [TitlePositionStyle](#titlepositionstyle) | ✓ | Vega-Lite title positioning: anchor, angle, offset, baseline. |
-| `level` | enum: "auto" | ✓ | Heading level override for face titles. ``'auto'`` (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this face and its descendants to that H-level. |
+| `level` | int \| enum: "auto" | ✓ | Heading level override for face titles. ``'auto'`` (default) computes the level semantically as the count of titled ancestors. An integer value locks all titles in this face and its descendants to that H-level. |
 | `subtitle` | [TitleSubtitleStyle](#titlesubtitlestyle) | ✓ | Subtitle font styles. |
 
 <a id="textstyle"></a>
@@ -1142,7 +1131,6 @@ Authored overlay for ChartsStyle. Registry of all chart-type styles plus shared
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Chart tooltip style. |
 | `background` | str | ✓ | Chart canvas background; None inherits from the board background via apply_inherit. Falls back to [`style.background`](#style). |
@@ -1335,15 +1323,6 @@ Authored overlay for PaddingStyle. Per-chart padding inset (px). All 4 sides req
 | `top` | float | ✓ | Top padding in pixels. |
 | `bottom` | float | ✓ | Bottom padding in pixels. |
 
-<a id="inferencestyle"></a>
-## InferenceStyle
-Authored overlay for InferenceStyle.
-
-| Field | Type | Optional | Description |
-|-------|------|:--------:|-------------|
-| `infer_zero_when_missing` | bool | ✓ | Auto-infer zero-baseline when not authored. |
-| `infer_fields_when_missing` | bool | ✓ | Auto-infer chart fields (x, y, etc.) when not authored. |
-
 <a id="legendstyle"></a>
 ## LegendStyle
 Authored overlay for LegendStyle.
@@ -1417,7 +1396,7 @@ Authored overlay for ScaleStyle. Scale configuration primitive.
 | `point_padding` | float | ✓ | Padding fraction for point scales; None uses Vega-Lite's default. |
 | `rect_band_padding_inner` | float | ✓ | Inner padding fraction for rect band scales; None uses Vega-Lite's default. |
 | `round` | bool | ✓ | Round scale outputs to nearest integer; None uses Vega-Lite's default (no rounding). |
-| `zero` | bool | ✓ | Force scale to include zero; None uses Vega-Lite's default. |
+| `zero` | bool \| enum: "auto" | ✓ | Force scale zero-baseline: True/False pins it; "auto" runs the Dataface smart-zero heuristic; None passes through to Vega-Lite. |
 | `clamp` | bool | ✓ | Clamp values to scale domain; None uses Vega-Lite's default (no clamping). |
 | `continuous_padding` | float | ✓ | Padding in pixels for continuous scales; None uses Vega-Lite's default. |
 | `band` | [ScaleBandStyle](#scalebandstyle) | ✓ | Band mark size constraints; None uses Vega-Lite's defaults. |
@@ -1654,7 +1633,7 @@ Configuration for a single table column.
 |-------|------|:--------:|-------------|
 | `label` | str | ✓ | Display header label (defaults to column name). |
 | `format` | str \| [FormatConfig](#formatconfig) | ✓ | Number format (D3 string, preset name, or FormatConfig). |
-| `spark` | enum: "line", "area", "bar", "bar-normalize", "columns" | ✓ | Inline spark chart config or spark type name. |
+| `spark` | enum: "line", "area", "bar", "bar-normalize", "column", "columns" | ✓ | Inline spark chart config or spark type name. |
 | `swatch` | bool | ✓ | When True, render this column's cells as small rounded color squares instead of text. Cell value must be a CSS color string (e.g. '#3164a3'). Useful for series-keyed tables — e.g. a 'Series' column where each row is identified by its color in the parent chart's palette. |
 | `width` | int \| str | ✓ | Column width (integer pixels or CSS string like '10%'). |
 | `max_width` | int \| str | ✓ | Maximum column width for auto-sized text columns (integer pixels or CSS string like '30%'). Cannot be set together with width:. |
@@ -1702,6 +1681,7 @@ Authored overlay for SparkStyle. Inline sparkline defaults (inside table cells).
 | `empty` | [SparkEmptyStyle](#sparkemptystyle) | ✓ | Style for empty/no-data sparklines. |
 | `single_value` | [SparkSingleValueStyle](#sparksinglevaluestyle) | ✓ | Style for single-data-point sparklines. |
 | `columns` | [SparkColumnsStyle](#sparkcolumnsstyle) | ✓ | Style for column-type sparklines. |
+| `column` | [SparkColumnStyle](#sparkcolumnstyle) | ✓ | Style for the single vertical `column` spark mark. |
 | `bar` | [SparkBarCellStyle](#sparkbarcellstyle) | ✓ | Style for bar/bar-normalize sparklines. |
 | `area` | [SparkAreaStyle](#sparkareastyle) | ✓ | Style for area sparklines. |
 
@@ -1944,7 +1924,6 @@ Authored overlay for HistogramChartStyle. Histogram chart style.
 | `animation_duration` | float | ✓ | Vega-Lite animation duration in milliseconds. Falls back to [`style.charts.animation_duration`](#chartsstyle). |
 | `palette` | list[str] \| str | ✓ | Ordered list of categorical color stops or a palette name; expanded from a palette name at validation time. Falls back to [`style.charts.palette`](#chartsstyle). |
 | `single_series_palette` | list[str] \| str | ✓ | Ordered list of single-series mark inks (must be non-empty), or a palette name. Cycled across single-series charts in face reading order. Falls back to [`style.charts.single_series_palette`](#chartsstyle). |
-| `inference` | [InferenceStyle](#inferencestyle) | ✓ | Engine inference behavior flags. |
 | `legend` | [LegendStyle](#legendstyle) | ✓ | Chart legend style. |
 | `tooltip` | [TooltipStyle](#tooltipstyle) | ✓ | Per-chart-type tooltip style override; None uses the universal style.charts.tooltip. |
 | `background` | str | ✓ | Chart-local background color override; None inherits from theme. |
@@ -2119,7 +2098,7 @@ Scale configuration for a single style target (background or color).
 | `min` | float \| int | ✓ | Minimum scale domain value (overrides data minimum). |
 | `max` | float \| int | ✓ | Maximum scale domain value (overrides data maximum). |
 | `null_color` | str | ✓ | Color assigned to null values. |
-| `hinge` | enum: "auto" | ✓ | Diverging scale midpoint value, or 'auto' to use the data midpoint. |
+| `hinge` | float \| enum: "auto" | ✓ | Diverging scale midpoint value, or 'auto' to use the data midpoint. |
 | `arm_mode` | enum: "asymmetric", "symmetric" | ✓ | How diverging scale arms are stretched: 'asymmetric' (proportional) or 'symmetric' (equal arms). |
 
 <a id="axisgridstyle"></a>
@@ -2306,6 +2285,7 @@ Authored overlay for SliceMarkStyle. Pie/donut slice mark — mark-level paint a
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
+| `opacity` | float | ✓ | Arc slice opacity (0–1); None means not overridden at this level. |
 | `gap` | float | ✓ | Angular gap between slices in radians. |
 | `corner_radius` | float | ✓ | Corner radius of arc slices in pixels. |
 | `stroke` | [StrokeStyle](#strokestyle) | ✓ | Arc slice stroke style. |
@@ -2334,7 +2314,7 @@ Configuration for spark charts (inline sparklines) in table columns.
 
 | Field | Type | Optional | Description |
 |-------|------|:--------:|-------------|
-| `type` | enum: "line", "area", "bar", "bar-normalize", "columns" | ✓ | Spark chart type (line, area, bar, bar-normalize, columns). |
+| `type` | enum: "line", "area", "bar", "bar-normalize", "column", "columns" | ✓ | Spark chart type (line, area, bar, bar-normalize, column, columns). |
 | `color` | str | ✓ | Color for the spark mark. |
 | `height` | int | ✓ | Spark chart height in pixels. |
 | `width` | int | ✓ | Spark chart width in pixels. |
@@ -2386,6 +2366,15 @@ Authored overlay for SparkColumnsStyle. Inline `spark.type: columns` (multi-valu
 | `min_bar_height` | float | ✓ | Minimum rendered bar height in pixels. |
 | `border` | [BorderStyle](#borderstyle) | ✓ | Column bar border style. |
 
+<a id="sparkcolumnstyle"></a>
+## SparkColumnStyle
+Authored overlay for SparkColumnStyle. Inline `spark.type: column` (single vertical bar) defaults.
+
+| Field | Type | Optional | Description |
+|-------|------|:--------:|-------------|
+| `width` | float | ✓ | Spark column default width in pixels. |
+| `height` | float | ✓ | Spark column default height in pixels. |
+
 <a id="sparkbarcellstyle"></a>
 ## SparkBarCellStyle
 Authored overlay for SparkBarCellStyle. Inline `spark.type: bar` and `bar-normalize` (single horizontal bar) defaults.

dataface/agent_api/validate.py

@@ -170,7 +170,7 @@ def _validate_meta_file(path: Path) -> ValidateResult:
             DatafaceError.from_code(
                 DF_COMPILE_META_SCHEMA,
                 message=(
-                    f"{' → '.join(str(loc) for loc in e['loc'])}: {e['msg']}"
+                    f"{'.'.join(str(loc) for loc in e['loc'])}: {e['msg']}"
                     if e["loc"]
                     else e["msg"]
                 ),

dataface/cli/_error_format.py

@@ -21,6 +21,18 @@ from dataface.core.errors import StructuredError
 from dataface.core.render.warnings.base import RenderWarning
 
 
+def _display_path(abs_path: str, line: int | None, cwd: Path | None = None) -> str:
+    """Return path relative to cwd when possible, with optional :line suffix."""
+    p = Path(abs_path)
+    base = cwd if cwd is not None else Path.cwd()
+    try:
+        rel = p.relative_to(base)
+        display = str(rel)
+    except ValueError:
+        display = abs_path
+    return f"{display}:{line}" if line else display
+
+
 def print_structured_errors(
     errs: list[StructuredError],
     *,
@@ -42,8 +54,7 @@ def print_structured_errors(
         if e.hint:
             body_parts.append(f"[dim]Hint:[/] {e.hint}")
         if e.file:
-            loc = e.file + (f":{e.line}" if e.line else "")
-            body_parts.append(f"[dim]At:[/] {loc}")
+            body_parts.append(f"[dim]At:[/] {_display_path(e.file, e.line)}")
         if e.docs_topic:
             body_parts.append(f"[dim]Docs:[/] dft docs {e.docs_topic}")
         elif e.doc_url:

dataface/cli/commands/render.py

@@ -29,6 +29,29 @@ from dataface.core.render.warnings.from_query_diagnostic import KNOWN_RENDER_COD
 # for query-validator codes; only orphan emitters (e.g. unreferenced_chart) add here.
 _COMPILE_PRODUCER_CODES: frozenset[str] = KNOWN_RENDER_CODES | {unreferenced_chart.CODE}
 
+# Maps common file extensions to render formats for format inference.
+_EXT_TO_FORMAT: dict[str, RenderFormat] = {
+    "svg": "svg",
+    "html": "html",
+    "htm": "html",
+    "png": "png",
+    "pdf": "pdf",
+    "json": "json",
+    "txt": "text",
+    "yaml": "yaml",
+    "yml": "yaml",
+}
+
+
+def infer_format_from_extension(output: str) -> RenderFormat | None:
+    """Infer render format from output file extension. Returns None for unknown extensions."""
+    return _EXT_TO_FORMAT.get(Path(output).suffix.lstrip(".").lower())
+
+
+def expand_output_template(template: str, face: Path) -> str:
+    """Expand {stem} and {dir} placeholders in an output path template."""
+    return template.format(stem=face.stem, dir=str(face.parent))
+
 
 def _exit_with_errors(errs: list[StructuredError], json_errors: bool) -> None:
     print_structured_errors(errs, json_output=json_errors)
@@ -96,6 +119,7 @@ def render_command(
     ignore_codes: set[str] | None = None,
     fail_on_chart_errors: bool = True,
     max_workers: int | None = None,
+    print0: bool = False,
 ) -> str | None:
     """Render a dashboard to SVG, HTML, PNG, PDF, or terminal.
 
@@ -170,6 +194,7 @@ def render_command(
         output_dir=output_dir,
         default_output_stem=ctx.face_file.stem,
         source_label=str(face_path),
+        print0=print0,
     )
 
 
@@ -185,6 +210,7 @@ def render_command_from_yaml(
     ignore_codes: set[str] | None = None,
     fail_on_chart_errors: bool = True,
     max_workers: int | None = None,
+    print0: bool = False,
 ) -> str | None:
     """Render a dashboard from YAML content (e.g. stdin).
 
@@ -255,6 +281,7 @@ def render_command_from_yaml(
         output_dir=output_dir,
         default_output_stem="stdin",
         source_label="<stdin>",
+        print0=print0,
     )
 
 
@@ -265,6 +292,7 @@ def _write_output(
     output_dir: Path,
     default_output_stem: str,
     source_label: str,
+    print0: bool = False,
 ) -> str | None:
     """Write rendered content to the appropriate destination."""
     # `terminal` is stdout-only by design — --output is meaningless for the
@@ -318,4 +346,76 @@ def _write_output(
         f"Rendered {source_label} to {output_path} ({format} format)",
         file=sys.stderr,
     )
+    sys.stdout.write(str(output_path) + ("\0" if print0 else "\n"))
+    sys.stdout.flush()
     return str(output_path)
+
+
+def render_commands(
+    face_paths: list[Path],
+    output: str | None = None,
+    format: RenderFormat = "svg",
+    project_dir: Path | None = None,
+    variables: dict[str, str] | None = None,
+    use_cache: bool = True,
+    json_errors: bool = False,
+    no_warnings: bool = False,
+    ignore_codes: set[str] | None = None,
+    fail_on_chart_errors: bool = True,
+    max_workers: int | None = None,
+    print0: bool = False,
+    fail_fast: bool = False,
+) -> None:
+    """Render one or more dashboards, printing output paths to stdout.
+
+    For multiple faces, `output` must contain {stem} or {dir} placeholders
+    (e.g. "renders/{stem}.svg"). With a single face, any output path is valid.
+
+    Per-face errors are reported to stderr; processing continues unless
+    `fail_fast=True`. Exits 1 if any face failed.
+    """
+    # Fail early when two inputs expand to the same output path — later renders
+    # would silently overwrite earlier ones.
+    if output and len(face_paths) > 1:
+        planned: list[str] = [expand_output_template(output, f) for f in face_paths]
+        seen: dict[str, Path] = {}
+        for face_path, dest in zip(face_paths, planned, strict=True):
+            if dest in seen:
+                print(
+                    f"Error: {face_path} and {seen[dest]} both expand to {dest!r}; "
+                    "use a more specific template (add {{dir}} or rename the files)",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            seen[dest] = face_path
+
+    has_failure = False
+    for face_path in face_paths:
+        face_output = expand_output_template(output, face_path) if output else None
+        try:
+            render_command(
+                face_path=face_path,
+                output=face_output,
+                format=format,
+                project_dir=project_dir,
+                variables=variables,
+                use_cache=use_cache,
+                json_errors=json_errors,
+                no_warnings=no_warnings,
+                ignore_codes=ignore_codes,
+                fail_on_chart_errors=fail_on_chart_errors,
+                max_workers=max_workers,
+                print0=print0,
+            )
+        except SystemExit as exc:
+            if fail_fast or exc.code != 1:
+                raise
+            has_failure = True
+        except Exception as exc:  # noqa: BLE001 — per-face error; batch continues
+            print(f"Error rendering {face_path}: {exc}", file=sys.stderr)
+            has_failure = True
+            if fail_fast:
+                sys.exit(1)
+
+    if has_failure:
+        sys.exit(1)

dataface/cli/main.py

@@ -690,23 +690,28 @@ def describe(
 
 @app.command("render", rich_help_panel="Dashboards")
 def render(
-    face: Annotated[
-        Path,
+    faces: Annotated[
+        list[Path],
         typer.Argument(
             # No exists=/file_okay=: "-" is a valid stdin sentinel and must not fail the check.
-            help='Path to face YAML file, or "-" to read YAML from stdin',
+            help='Path(s) to face YAML file(s), or "-" to read YAML from stdin (single path only)',
         ),
     ],
     output: Annotated[
-        Path | None,
-        typer.Option(help="Output file path (default: face name with extension)"),
+        str | None,
+        typer.Option(
+            help=(
+                "Output file path. For multiple inputs, use {stem} or {dir} "
+                "placeholders (e.g. renders/{stem}.svg). Default: renders/<face>.<ext>."
+            )
+        ),
     ] = None,
     format: Annotated[
-        RenderFormat,
+        RenderFormat | None,
         typer.Option(
             help="Output format: svg, html, png, pdf, terminal, json, text, or yaml"
         ),
-    ] = "svg",
+    ] = None,
     project_dir: ProjectDirOption = None,
     var: Annotated[
         list[str] | None,
@@ -775,11 +780,35 @@ def render(
             ),
         ),
     ] = None,
+    print0: Annotated[
+        bool,
+        typer.Option(
+            "--print0",
+            "-0",
+            help=(
+                "Delimit produced output paths with NUL (\\0) instead of newline. "
+                "Enables safe piping to xargs -0 for paths containing spaces."
+            ),
+        ),
+    ] = False,
+    fail_fast: Annotated[
+        bool,
+        typer.Option(
+            "--fail-fast",
+            help=(
+                "Stop immediately on the first render failure. "
+                "Default: continue rendering remaining faces, exit 1 at end."
+            ),
+        ),
+    ] = False,
 ) -> None:
-    """Render a dashboard to SVG, HTML, PNG, PDF, or terminal.
+    """Render one or more dashboards to SVG, HTML, PNG, PDF, or terminal.
 
-    Use "-" as the face argument to read YAML from stdin (useful for agents
-    and shell pipelines).
+    Accepts multiple face paths; output paths are printed to stdout (one per
+    line) so results can be piped to other tools. Use --print0 for NUL-delimited
+    output safe with xargs -0.
+
+    Use "-" as the sole face argument to read YAML from stdin.
 
     By default, per-chart runtime errors (missing columns, query failures)
     cause exit 1 so CI smoke tests detect broken charts. Pass
@@ -790,6 +819,8 @@ def render(
     Examples:
       dft render faces/sales.yml
       dft render faces/sales.yml --format html
+      dft render faces/*.yml --output renders/{stem}.svg
+      dft render faces/*.yml --output renders/{stem}.svg --print0 | xargs -0 ls -lh
       dft render faces/sales.yml --var region=West --var category=Electronics
       dft render faces/sales.yml --format terminal
       dft render faces/sales.yml --no-cache
@@ -800,34 +831,42 @@ def render(
       echo 'charts: {c: {query: {type: csv, file: data.csv}}}' | dft render - --format terminal
     """
     variables = parse_kv_pairs(var or [], "--var")
-
     use_cache = not no_cache
     ignore_codes = set(ignore_warning) if ignore_warning else None
     fail_on_chart_errors = not allow_chart_errors
 
-    if str(face) == "-":
+    # Reject stdin mixed with other paths
+    has_stdin = any(str(f) == "-" for f in faces)
+    if has_stdin and len(faces) > 1:
+        raise typer.BadParameter(
+            '"-" (stdin) can only be used as the sole face argument',
+            param_hint="FACES",
+        )
+
+    # Infer format from output extension when not explicitly given
+    effective_format: RenderFormat = (
+        format or (output and render_cmd.infer_format_from_extension(output)) or "svg"
+    )
+
+    # Reject flat --output when rendering multiple faces (ambiguous destination)
+    if len(faces) > 1 and output is not None:
+        if "{stem}" not in output and "{dir}" not in output:
+            raise typer.BadParameter(
+                f'use a template like "{{stem}}.{effective_format}" for multiple inputs; '
+                f'"{output}" is ambiguous with {len(faces)} face arguments',
+                param_hint="--output",
+            )
+
+    # Stdin path (single face "-")
+    if has_stdin:
         yaml_content = sys.stdin.read()
         if not yaml_content.strip():
             print("Error: No YAML input received from stdin", file=sys.stderr)
             raise typer.Exit(1)
         render_cmd.render_command_from_yaml(
             yaml_content=yaml_content,
-            output=str(output) if output else None,
-            format=format,
-            project_dir=project_dir,
-            variables=variables or None,
-            use_cache=use_cache,
-            json_errors=json_errors,
-            no_warnings=no_warnings,
-            ignore_codes=ignore_codes,
-            fail_on_chart_errors=fail_on_chart_errors,
-            max_workers=max_workers,
-        )
-    else:
-        render_cmd.render_command(
-            face_path=face,
-            output=str(output) if output else None,
-            format=format,
+            output=output,
+            format=effective_format,
             project_dir=project_dir,
             variables=variables or None,
             use_cache=use_cache,
@@ -836,7 +875,25 @@ def render(
             ignore_codes=ignore_codes,
             fail_on_chart_errors=fail_on_chart_errors,
             max_workers=max_workers,
+            print0=print0,
         )
+        return
+
+    render_cmd.render_commands(
+        face_paths=faces,
+        output=output,
+        format=effective_format,
+        project_dir=project_dir,
+        variables=variables or None,
+        use_cache=use_cache,
+        json_errors=json_errors,
+        no_warnings=no_warnings,
+        ignore_codes=ignore_codes,
+        fail_on_chart_errors=fail_on_chart_errors,
+        max_workers=max_workers,
+        print0=print0,
+        fail_fast=fail_fast,
+    )
 
 
 @app.command("search", rich_help_panel="Dashboards")