dataface 0.1.5.dev237__py3-none-any.whl → 0.1.5.dev322__py3-none-any.whl

dataface/DATAFACE_SYNTAX.md

@@ -19,7 +19,7 @@ dft validate faces/my_dashboard.yml
 To verify that your database connection works, run a simple query:
 
 ```bash
-dft query <your_source> 'SELECT 1'
+dft query 'SELECT 1' --source <your_source>
 ```
 
 A successful result means your data source is reachable.
@@ -138,7 +138,7 @@ variables:
   region:
     input: select                  # See `dft docs variables` for all 14 input types
     options: { static: [US, EU, APAC] }
-    # No default: starts on All regions
+    default: US
 ```
 
 Reference variables inside queries with bare `{{ region }}` — no `variables.` prefix.
@@ -206,20 +206,15 @@ chart_focus: revenue_trend     # Render only one chart with its dependent variab
 details: "Click to expand"     # Collapsible section
 expanded_title: "Hide details"
 expanded: false
-
-aliases:                       # Additional URLs that 302-redirect to this face
-  - /old-reports/
-  - /legacy/sales/
 ```
 
-Top-level fields (24 total):
+Top-level fields (23 total):
 
 | Field | Type | Notes |
 |-------|------|-------|
 | `title` | string | Display title |
 | `description` | string | Description text |
 | `tags` | list[string] | Tags for categorization/search |
-| `aliases` | list[string] | See [Aliases](#aliases) below |
 | `text` | string | Markdown body for text-only faces |
 | `source` | string | Default source shorthand (equivalent to `sources.default`) |
 | `sources` | object | `{default: name, <name>: {type: ...}}` |
@@ -256,11 +251,11 @@ aliases:
 Rules:
 - An alias must not collide with a real face file path — the server raises an error at startup if it does.
 - Each alias must be unique across the project — two faces claiming the same alias is a startup error.
-- Aliasing a generated system route (entity or inspector view) is allowed: the redirect takes precedence, letting you override what that URL serves.
+- Aliasing a generated system route (data or inspector view) is allowed: the redirect takes precedence, letting you override what that URL serves.
 
-There are two ways to override an entity/inspector route for a given path:
-- **Face file at that path** — create `faces/entity/warehouse/schema/table.yml` and the server renders it directly (no redirect).
-- **`aliases:` entry** — any face can declare `/entity/…/` as an alias; the server issues a 302 to the declaring face's canonical URL.
+There are two ways to override a data/inspector route for a given path:
+- **Face file at that path** — create `faces/data/warehouse/schema/table.yml` and the server renders it directly (no redirect).
+- **`aliases:` entry** — any face can declare `/data/…/` as an alias; the server issues a 302 to the declaring face's canonical URL.
 
 Both approaches work.  A face file wins without a redirect round-trip; an alias lets a face live anywhere and still capture a system-view URL.
 
@@ -372,7 +367,7 @@ queries:
       - [Bob, 87.1]
 ```
 
-Query types (`type:` literals): `sql`, `csv`, `http`, `dbt_model`, `metricflow`, `values`. `schema` is internal-only and not part of the authored surface.
+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):
 
@@ -487,7 +482,6 @@ charts:
 
     # Style + behavior
     sort: { by: total, order: desc }
-    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)
@@ -495,6 +489,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
 ```
 
@@ -547,7 +542,7 @@ All chart types accept the channels and style fields below — but each type rej
 | `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 |
+| `sort` | object | `{by, order}` — categorical sort. Horizontal bar charts default to value-descending order when omitted. |
 | `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)) |
@@ -623,14 +618,12 @@ support:                # Optional support line (same shape: value/label/format/
   glyph: "▲"
   tone: positive
 
-# table — renders all query columns unless `style.columns` selects a subset.
-# `columns` is a MAPPING keyed by column name (NOT a list). Omit it to show
-# every query column; include it to choose a subset and/or style columns.
+# table — renders all query columns unless `style.columns` selects a subset
 type: table
 style:
   columns:
-    order_id: {}                         # include with default styling
-    amount:                              # the key is the column name
+    - column: order_id
+    - column: amount
       label: Amount
       format: currency_whole
       align: right                       # left | center | right
@@ -703,11 +696,11 @@ 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)
+# callout — message card with a style.tone: field (info | negative | warning | positive)
 type: callout
 message: "Query is disabled in this environment."
 style:
-  tone: warning  # optional; defaults to negative
+  tone: warning  # optional; defaults to info
 
 # auto — internal; engine picks the chart type from the data shape.
 type: auto
@@ -726,7 +719,7 @@ layers:
     y: target
     label: Target
     axis_y:
-      orient: right                 # left | right
+      position: right            # left | right
       title: "Target"
 ```
 
@@ -872,7 +865,7 @@ variables:
     description: "Restrict every query to one region."
     options:
       static: [US, EU, APAC]
-    # No default: starts on All regions
+    default: US
 ```
 
 Input types (14 total):
@@ -904,6 +897,7 @@ Common variable fields:
 | `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) |
@@ -919,7 +913,7 @@ variables:
   product:
     input: select
     options:
-      static: [Electronics, Clothing]         # Hardcoded list; blank -- All -- is implicit
+      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
@@ -932,25 +926,23 @@ variables:
 
 Top-level option-source binding (alternative to `options:`): `column`, `query`, `dimension` (MetricFlow), `measure` (MetricFlow), `model` (dbt).
 
-Variables are optional by default. For `select` and `multiselect`, omitting `default` starts the variable unset. The renderer adds a blank `-- All --` option for that unset state; `{{ filter('column', variable) }}` emits `1=1` unless the SQL call site opts into `none='deny'`. Add `required: true` only when the dashboard cannot render without a value.
-
-Disabled forms:
+Enabled/disabled forms (`enabled: false` means the control is inactive):
 
 ```yaml
 variables:
-  # Static bool
-  closed: { input: checkbox, disabled: true }
+  # Static bool — enabled: false disables the control
+  closed: { input: checkbox, enabled: false }
 
   # Jinja expression against current variable values
-  q4_only: { input: select, options: { static: [Q4] }, disabled: "{{ year < 2024 }}" }
+  q4_only: { input: select, options: { static: [Q4] }, enabled: "{{ year >= 2024 }}" }
 
   # Query-backed (must return exactly 1 row with the named boolean column)
   territory:
     input: select
     options: { query: territory_options }
-    disabled:
+    enabled:
       query: control_state
-      column: territory_disabled
+      column: territory_enabled
 ```
 
 **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.

dataface/__init__.py

@@ -22,7 +22,8 @@ Quick Start:
     ...     face = result.face
     ...
     ...     # Create executor and render
-    ...     registry = build_adapter_registry(Path.cwd())
+    ...     from dataface.core.compile.config import load_project_sources
+    ...     registry = build_adapter_registry(Path.cwd(), project_sources=load_project_sources(Path.cwd()))
     ...     executor = Executor(face, registry, query_registry=result.query_registry)
     ...     svg = render(face, executor, format="svg")
 """

dataface/agent_api/__init__.py

@@ -37,10 +37,6 @@ CLI/MCP files that contain logic beyond parse-and-dispatch.
 """
 
 from dataface.agent_api import skills as skills
-from dataface.agent_api.dashboards import (
-    RenderedDashboard as RenderedDashboard,
-    render_dashboard as render_dashboard,
-)
 from dataface.agent_api.describe import (
     DescribeFaceArgs,
     DescribeFaceResult,
@@ -63,6 +59,10 @@ from dataface.agent_api.validate_query import (
     validate_query as validate_query,
 )
 from dataface.core.compile.config import ProjectSourcesConfig as ProjectSourcesConfig
+from dataface.core.dashboard import (
+    RenderedDashboard as RenderedDashboard,
+    render_dashboard as render_dashboard,
+)
 from dataface.core.errors.structured import StructuredError as StructuredError
 from dataface.core.fonts import get_inter_font_path as get_inter_font_path
 from dataface.core.render.board_links import LinkContext as LinkContext

dataface/agent_api/_init_templates/guide.yaml

@@ -82,7 +82,9 @@ charts:
     query: kpi_summary
     label: Total Revenue (H1)
     value: total_revenue
-    format: currency_compact
+    style:
+      value:
+        format: currency_compact
     support:
       value: revenue_delta
       label: vs H1 last year
@@ -95,7 +97,9 @@ charts:
     query: kpi_summary
     label: Avg Deal Size
     value: avg_deal
-    format: currency_compact
+    style:
+      value:
+        format: currency_compact
 
   data_table:
     type: table

dataface/agent_api/dashboards.py

@@ -3,10 +3,6 @@
 All public functions have concrete typed arguments and typed Pydantic return
 values. No bare dict[str, Any] in any return position. Tool/CLI callers use
 .model_dump() at the wire boundary.
-
-`RenderedDashboard` and `render_dashboard` live in `dataface.core.dashboard`
-so the embedded HTTP server can call them without inverting the layer stack; they
-are re-exported here so the agent_api thin-wrapper rule still holds.
 """
 
 from __future__ import annotations
@@ -20,10 +16,7 @@ from pydantic import BaseModel, Field
 from dataface.agent_api._paths import resolve_scoped_path
 from dataface.core.compile import Face, compile_file
 from dataface.core.compile.errors import DatafaceError
-from dataface.core.dashboard import (
-    RenderedDashboard as RenderedDashboard,
-    render_dashboard as render_dashboard,
-)
+from dataface.core.dashboard import RenderedDashboard as RenderedDashboard
 from dataface.core.errors import DF_UNKNOWN_INTERNAL, StructuredError
 from dataface.core.render.warnings.base import RenderWarning
 

dataface/agent_api/{entity_paths.py → data_paths.py}

@@ -1,13 +1,13 @@
-"""Entity URL surfacing and alias typo lint.
+"""Data URL surfacing and alias typo lint.
 
 Provides:
-- EntityPathInfo: the agent-facing wire shape for a canonical entity URL
+- DataPathInfo: the agent-facing wire shape for a canonical data URL
   (url, resolves_to: "generic" | "authored", face)
-- entity_paths_for_source/schema/table: compute entity URLs and check the
+- data_paths_for_source/schema/table: compute data URLs and check the
   alias index to determine whether a face overrides the generic system view
-- entity_paths_list: flat list of EntityPathInfo (source + schema + table level)
-  from a SchemaResponse — used for --entity-paths CLI flag and agent discovery
-- validate_entity_aliases: typo lint for /entity/ prefixed aliases — checks
+- data_paths_list: flat list of DataPathInfo (source + schema + table level)
+  from a SchemaResponse — used for --data-paths CLI flag and agent discovery
+- validate_data_aliases: typo lint for /data/ prefixed aliases — checks
   source names only (config only, no DB connection required).
 """
 
@@ -17,17 +17,23 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal
 
+from dataface.core.registered_views.data_urls import (
+    data_schema_url,
+    data_source_url,
+    data_table_url,
+)
+
 if TYPE_CHECKING:
     from dataface.agent_api.schema import SchemaResponse
     from dataface.core.serve.alias_index import AliasIndex
 
 
 @dataclass
-class EntityPathInfo:
-    """Canonical entity URL with resolution status.
+class DataPathInfo:
+    """Canonical data URL with resolution status.
 
     Wire shape (pinned by contract test — any change is a breaking API change):
-        {"url": "/entity/src/schema/table/", "resolves_to": "generic"}
+        {"url": "/data/src/schema/table/", "resolves_to": "generic"}
         {"url": "...", "resolves_to": "authored", "face": "/sales/"}
     """
 
@@ -43,73 +49,73 @@ class EntityPathInfo:
         return d
 
 
-def entity_paths_for_source(
+def data_paths_for_source(
     source: str,
     *,
     alias_index: AliasIndex,
-) -> EntityPathInfo:
-    """Return the entity URL info for a source.
+) -> DataPathInfo:
+    """Return the data URL info for a source.
 
-    The canonical URL is /entity/<source>/. When a face aliases it the
+    The canonical URL is /data/<source>/. When a face aliases it the
     resolves_to is 'authored' and face is the canonical face URL.
     """
-    url = f"/entity/{source}/"
+    url = data_source_url(source)
     face = alias_index.lookup(url)
     if face is not None:
-        return EntityPathInfo(url=url, resolves_to="authored", face=face)
-    return EntityPathInfo(url=url, resolves_to="generic")
+        return DataPathInfo(url=url, resolves_to="authored", face=face)
+    return DataPathInfo(url=url, resolves_to="generic")
 
 
-def entity_paths_for_schema(
+def data_paths_for_schema(
     source: str,
     schema: str,
     *,
     alias_index: AliasIndex,
-) -> EntityPathInfo:
-    """Return the entity URL info for a schema.
+) -> DataPathInfo:
+    """Return the data URL info for a schema.
 
-    The canonical URL is /entity/<source>/<schema>/. When a face aliases it
+    The canonical URL is /data/<source>/<schema>/. When a face aliases it
     the resolves_to is 'authored' and face is the canonical face URL.
     """
-    url = f"/entity/{source}/{schema}/"
+    url = data_schema_url(source, schema)
     face = alias_index.lookup(url)
     if face is not None:
-        return EntityPathInfo(url=url, resolves_to="authored", face=face)
-    return EntityPathInfo(url=url, resolves_to="generic")
+        return DataPathInfo(url=url, resolves_to="authored", face=face)
+    return DataPathInfo(url=url, resolves_to="generic")
 
 
-def entity_paths_for_table(
+def data_paths_for_table(
     source: str,
     schema: str,
     table: str,
     *,
     alias_index: AliasIndex,
-) -> EntityPathInfo:
-    """Return the entity URL info for a table.
+) -> DataPathInfo:
+    """Return the data URL info for a table.
 
-    The canonical URL is /entity/<source>/<schema>/<table>/. When a face
+    The canonical URL is /data/<source>/<schema>/<table>/. When a face
     aliases it the resolves_to is 'authored' and face is the canonical face URL.
     """
-    url = f"/entity/{source}/{schema}/{table}/"
+    url = data_table_url(source, schema, table)
     face = alias_index.lookup(url)
     if face is not None:
-        return EntityPathInfo(url=url, resolves_to="authored", face=face)
-    return EntityPathInfo(url=url, resolves_to="generic")
+        return DataPathInfo(url=url, resolves_to="authored", face=face)
+    return DataPathInfo(url=url, resolves_to="generic")
 
 
-def validate_entity_aliases(
+def validate_data_aliases(
     aliases: list[str],
     *,
     source_names: frozenset[str],
 ) -> list[str]:
-    """Lint /entity/ prefixed aliases against configured source names.
+    """Lint /data/ prefixed aliases against configured source names.
 
     Called at dft-validate time (connection-free). Checks that every
-    /entity/ URL references a known source, and errors with available
+    /data/ URL references a known source, and errors with available
     sources as a hint when not.
 
     Returns a list of error message strings (empty = all valid).
-    Aliases not prefixed with /entity/ are silently skipped.
+    Aliases not prefixed with /data/ are silently skipped.
     """
     errors: list[str] = []
     for raw_alias in aliases:
@@ -120,17 +126,17 @@ def validate_entity_aliases(
         if not alias.endswith("/"):
             alias = alias + "/"
 
-        if not alias.startswith("/entity/"):
+        if not alias.startswith("/data/"):
             continue
 
-        # Strip leading "/entity/" and trailing "/" to get segments
-        inner = alias[len("/entity/") :]
+        # Strip leading "/data/" and trailing "/" to get segments
+        inner = alias[len("/data/") :]
         if inner.endswith("/"):
             inner = inner[:-1]
         segments = [s for s in inner.split("/") if s]
 
         if not segments:
-            # Bare /entity/ — no validation needed
+            # Bare /data/ — no validation needed
             continue
 
         # Segment 0: source
@@ -143,36 +149,34 @@ def validate_entity_aliases(
                 else "no sources configured"
             )
             errors.append(
-                f"Entity alias {raw_alias!r} references unknown source {source!r}. "
+                f"Data alias {raw_alias!r} references unknown source {source!r}. "
                 f"Did you mean one of: {hint}"
             )
 
     return errors
 
 
-def entity_paths_list(
+def data_paths_list(
     schema_response: SchemaResponse,
     *,
     alias_index: AliasIndex,
-) -> list[EntityPathInfo]:
-    """Build a flat list of EntityPathInfo from a SchemaResponse.
+) -> list[DataPathInfo]:
+    """Build a flat list of DataPathInfo from a SchemaResponse.
 
     Iterates all sources → schemas → tables in the response and returns one
-    EntityPathInfo per source, per schema, and per table, checking the alias
+    DataPathInfo per source, per schema, and per table, checking the alias
     index for author overrides at each level.
     """
-    result: list[EntityPathInfo] = []
+    result: list[DataPathInfo] = []
     for source_name, source_data in schema_response.sources.items():
-        result.append(entity_paths_for_source(source_name, alias_index=alias_index))
+        result.append(data_paths_for_source(source_name, alias_index=alias_index))
         for schema_name, schema_data in (source_data.get("schemas") or {}).items():
             result.append(
-                entity_paths_for_schema(
-                    source_name, schema_name, alias_index=alias_index
-                )
+                data_paths_for_schema(source_name, schema_name, alias_index=alias_index)
             )
             for table_name in schema_data.get("tables") or {}:
                 result.append(
-                    entity_paths_for_table(
+                    data_paths_for_table(
                         source_name,
                         schema_name,
                         table_name,
@@ -186,7 +190,7 @@ def build_alias_index_for_project(project_dir: Path) -> AliasIndex:
     """Build an AliasIndex from a project directory.
 
     Uses the same faces_at_root detection logic as the server. Intended for
-    CLI commands (dft schema --entity-paths) that need alias lookup without
+    CLI commands (dft schema --data-paths) that need alias lookup without
     starting a server.
     """
     from dataface.core.serve.alias_index import AliasIndex
@@ -200,22 +204,22 @@ def build_alias_index_for_project(project_dir: Path) -> AliasIndex:
     )
 
 
-def entity_alias_errors_for_file(
+def data_alias_errors_for_file(
     face_file: Path,
     source_names: frozenset[str],
 ) -> list[str]:
-    """Read aliases from a face file and lint any /entity/ prefixed ones.
+    """Read aliases from a face file and lint any /data/ prefixed ones.
 
     Source-name check only — no DB connection, no resolver. Called from the
     validate path which must stay connection-free.
 
-    Returns a list of error message strings; empty means no entity alias issues.
+    Returns a list of error message strings; empty means no data alias issues.
     Silently returns [] when the file cannot be parsed (compile catches that).
     """
-    from dataface.core.serve.alias_index import _read_aliases_from_file
+    from dataface.core.serve.alias_index import read_aliases_from_file
 
     try:
-        aliases = _read_aliases_from_file(face_file)
+        aliases = read_aliases_from_file(face_file)
     except ValueError:
         return []  # compile path reports alias parse errors with better context
-    return validate_entity_aliases(aliases, source_names=source_names)
+    return validate_data_aliases(aliases, source_names=source_names)