BarColumnConfig: rename xAxis/yAxis → categoryAxis/valueAxis to reduce confusion

[gangtao]

Summary

In BarColumnConfig, the field names xAxis and yAxis carry a single semantic meaning regardless of chartType:

• xAxis → independent variable (category), x channel with band scale
• yAxis → dependent variable (value), y channel with linear scale

For chartType: 'bar', Vistral applies a transpose coordinate transform so the visual axes flip — the category column then appears on the visual y axis (left side), and the value column on the visual x axis (bottom). The config field names do NOT follow this flip; they remain xAxis = category, yAxis = value.

This works correctly but is confusing for downstream consumers writing translators or hand-authoring configs. The natural intuition is "for a horizontal bar chart with categories on the left, the category field should be yAxis" — which is wrong by Vistral's contract. We hit this confusion during the axion viz→vistral migration and ended up discussing it twice before settling on the right semantics.

Proposal

Introduce semantic field names that don't depend on the visual orientation:

export interface BarColumnConfig extends ChartConfigBase {
  chartType: 'bar' | 'column';
  /** Categorical (independent) column — always rendered with a band scale */
  categoryAxis: string;
  /** Numeric (dependent) column — always rendered with a linear scale */
  valueAxis: string;
  // ... other fields unchanged
}

For backwards compatibility, keep xAxis / yAxis as deprecated aliases for one release (read both; prefer the new names if both are present; log a deprecation warning in dev mode).

The compiler (compileBarColumnConfig in src/core/compilers.ts) then maps:

• categoryAxis → G2 x channel
• valueAxis → G2 y channel
• transpose is still applied for chartType: 'bar'

Alternative (lighter weight)

If renaming is too disruptive, at minimum add JSDoc comments to the existing fields that explicitly state the convention:

/**
 * Category (independent) column. Maps to the visual x axis for `column` charts
 * and to the visual y axis for `bar` charts (via internal transpose).
 */
xAxis: string;

Plus a section in the README clarifying this for both BarColumnConfig and any related Grammar API equivalents.

Out of scope

The same naming convention applies to TimeSeriesConfig (xAxis = time, yAxis = value) — not confusing there because time-series visual axes don't flip. No change suggested.

Filed from

Axion viz→vistral migration (timeplus-io/axion, branch feature/4374-migrating-the-viz-lib-to-vistra).