refactor(chart): clarify x-axis helpers

Author: lovasoa

examples/official-site/sqlpage/migrations/01_documentation.sql

@@ -669,7 +669,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S
     ('xtitle', 'Title of the x axis, displayed below it.', 'TEXT', TRUE, TRUE),
     ('ytitle', 'Title of the y axis, displayed to its left.', 'TEXT', TRUE, TRUE),
     ('ztitle', 'Title of the z axis, displayed in tooltips.', 'TEXT', TRUE, TRUE),
-    ('xticks', 'Number of tick positions on a numeric x-axis. On category and time axes, this is a target for label density, so the visible label count may differ.', 'INTEGER', TRUE, TRUE),
+    ('xticks', 'Number of tick positions on a numeric x-axis. For example, 5 requests five evenly spaced positions, including the two ends. On category and time axes, it asks ApexCharts to show up to that many labels; it may show fewer to keep labels from overlapping.', 'INTEGER', TRUE, TRUE),
     ('yticks', 'Number of ticks on the y axis.', 'INTEGER', TRUE, TRUE),
     ('ystep', 'Step between ticks on the y axis.', 'REAL', TRUE, TRUE),
     ('marker', 'Marker size', 'REAL', TRUE, TRUE),

sqlpage/apexcharts.js

@@ -61,8 +61,17 @@ sqlpage_chart = (() => {
   /** @param {ChartSeries[]} series */
   const x_is_text = (series) => typeof series[0]?.data?.[0]?.x === "string";
 
-  /** @param {ChartSeries[]} series @param {string} chart_type */
-  function xaxis_type_for(series, chart_type, is_timeseries, is_horizontal) {
+  /**
+   * Numeric x values need an explicit axis type to retain their proportional
+   * spacing; otherwise ApexCharts treats them as evenly spaced categories.
+   *
+   * @param {ChartSeries[]} series
+   * @param {{chart_type:string, is_timeseries:boolean, is_horizontal:boolean}} options
+   */
+  function xaxis_type_for(
+    series,
+    { chart_type, is_timeseries, is_horizontal },
+  ) {
     if (is_timeseries) return "datetime";
     if (x_is_text(series)) return "category";
     if (
@@ -73,6 +82,18 @@ sqlpage_chart = (() => {
       return "numeric";
   }
 
+  /**
+   * ApexCharts expects intervals for numeric axes, while SQLPage exposes the
+   * more intuitive number of tick positions to users.
+   *
+   * @param {number|undefined} xticks
+   * @param {string|undefined} xaxis_type
+   */
+  function xaxis_tick_amount(xticks, xaxis_type) {
+    if (!xticks) return;
+    return xaxis_type === "numeric" ? Math.max(1, xticks - 1) : xticks;
+  }
+
   /**
    * @param {ChartSeries[]} series
    * @returns {XValue[]} every x the series hold, in their own order where they
@@ -225,12 +246,11 @@ sqlpage_chart = (() => {
     let colors = palette;
 
     let series = Object.values(series_map);
-    const xaxis_type = xaxis_type_for(
-      series,
+    const xaxis_type = xaxis_type_for(series, {
       chart_type,
       is_timeseries,
-      !!data.horizontal,
-    );
+      is_horizontal: !!data.horizontal,
+    });
 
     let labels;
     if (chart_type === "pie") {
@@ -386,10 +406,7 @@ sqlpage_chart = (() => {
       series,
     };
     if (labels) options.labels = labels;
-    // ApexCharts counts numeric intervals rather than tick positions.
-    if (data.xticks)
-      options.xaxis.tickAmount =
-        xaxis_type === "numeric" ? Math.max(1, data.xticks - 1) : data.xticks;
+    options.xaxis.tickAmount = xaxis_tick_amount(data.xticks, xaxis_type);
     const chart = new ApexCharts(chartContainer, options);
     chart.render();
     if (window.charts) window.charts.push(chart);

tests/js/chart_series.spec.ts

@@ -37,16 +37,31 @@ test("uses a continuous axis for numeric Cartesian x values", () => {
   const numeric = [series("a", { x: 1, y: 1 }, { x: 12, y: 12 })];
 
   for (const type of ["line", "area", "bar", "scatter", "bubble"])
-    assert.equal(xaxis_type_for(numeric, type, false, false), "numeric");
+    assert.equal(
+      xaxis_type_for(numeric, {
+        chart_type: type,
+        is_timeseries: false,
+        is_horizontal: false,
+      }),
+      "numeric",
+    );
 });
 
 test("keeps text and time x values on their respective axes", () => {
   assert.equal(
-    xaxis_type_for([series("a", { x: "Q1", y: 1 })], "bar", false, false),
+    xaxis_type_for([series("a", { x: "Q1", y: 1 })], {
+      chart_type: "bar",
+      is_timeseries: false,
+      is_horizontal: false,
+    }),
     "category",
   );
   assert.equal(
-    xaxis_type_for([series("a", { x: 1, y: 1 })], "bar", true, false),
+    xaxis_type_for([series("a", { x: 1, y: 1 })], {
+      chart_type: "bar",
+      is_timeseries: true,
+      is_horizontal: false,
+    }),
     "datetime",
   );
 });
@@ -55,8 +70,22 @@ test("does not turn category-oriented charts into numeric axes", () => {
   const numeric = [series("a", { x: 1, y: 1 })];
 
   for (const type of ["heatmap", "rangeBar", "pie", "treemap"])
-    assert.equal(xaxis_type_for(numeric, type, false, false), undefined);
-  assert.equal(xaxis_type_for(numeric, "bar", false, true), undefined);
+    assert.equal(
+      xaxis_type_for(numeric, {
+        chart_type: type,
+        is_timeseries: false,
+        is_horizontal: false,
+      }),
+      undefined,
+    );
+  assert.equal(
+    xaxis_type_for(numeric, {
+      chart_type: "bar",
+      is_timeseries: false,
+      is_horizontal: true,
+    }),
+    undefined,
+  );
 });
 
 test("merged_x_values keeps the order the series agree on", () => {