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 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.