Builds a Vega-Lite spec from query result and visualization config.

Config shape

%{
  "chart_type" => "bar" | "line" | "area" | "scatter" | "pie" | "funnel" | "heatmap" | "histogram" | "kpi" | "sparkline",
  "x_field" => "column_name",
  "y_field" => "column_name",
  "series_field" => "column_name" | nil,
  "x_axis_title" => "Custom Label" | nil,
  "y_axis_title" => "Custom Label" | nil,
  "x_axis_show_label" => boolean (default: true),
  "y_axis_show_label" => boolean (default: true),
  "value_field" => "column_name" (for KPI),
  "kpi_label" => "Custom Label" (for KPI, optional),
  "bin_count" => integer (for histogram, default: 10)
}

Examples

iex> result = %{columns: ["name", "value"], rows: [["A", 10], ["B", 20]]}
iex> config = %{"chart_type" => "bar", "x_field" => "name", "y_field" => "value"}
iex> VegaSpecBuilder.build(result, config)
%{
  "$schema" => "https://vega.github.io/schema/vega-lite/v6.json",
  "data" => %{"values" => [%{"name" => "A", "value" => 10}, %{"name" => "B", "value" => 20}]},
  "mark" => %{"type" => "bar"},
  "encoding" => %{
    "x" => %{"field" => "name", "type" => "nominal"},
    "y" => %{"field" => "value", "type" => "quantitative"}
  }
}

@spec build_config(map()) :: map()

Builds the appropriate config map for a given chart type, picking only the relevant keys from viz. Prevents stale fields from leaking across type switches.

Returns %{} when chart_type is nil or empty (i.e. "Table (default)" selected).

Note: axis display fields (x_axis_title, y_axis_title, etc.) are intentionally excluded because the dashboard card settings don't currently expose axis controls.

Returns the chart color palette used for built-in visualizations.

Returns chart types organized into display groups for the UI grid.

Returns the ordered list of chart type ID strings.

Returns a human-readable label for the given chart type ID.

@spec valid_config?(map() | nil) :: boolean()

Returns true when config contains enough fields for its chart type to render.

Used by both the query editor and results components to decide whether a visualization can be shown.