feat(chart) :: draw horizontal reference lines (#1375)

* feat(chart) :: draw horizontal reference lines

* rev 2 (please squash + merge)

Author: 81reap

CHANGELOG.md

@@ -14,6 +14,7 @@
  - `stacked` is now ignored on chart types that cannot stack, instead of displaying an empty chart.
  - Screen readers now announce the title of the modal component instead of an unnamed dialog.
  - `sqlpage.request_body` and `sqlpage.request_body_base64` now return NULL when the request has no body. A body that cannot be read, such as one exceeding the payload limit, is now reported as an error instead of being silently replaced with an empty body.
+ - Charts can display reference lines. A row with a `yline` is drawn as a line across the chart at that value of the y axis, with the row's `label` and `color` for its text and its color. Reference lines are rows, so a chart can have as many of them as the query returns. A line follows its axis, so on a `horizontal` bar chart a `yline` is drawn down the chart rather than across it. They are not added to the total of a `stacked` chart, and are not filled in an `area` chart.
 
 ## v0.45
 

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

@@ -685,9 +685,11 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S
     ('x', 'The value of the point on the horizontal axis', 'REAL', FALSE, FALSE),
     ('y', 'The value of the point on the vertical axis', 'REAL', FALSE, FALSE),
     ('z', 'A third value carried by the point. Used as the bubble radius in a bubble chart, and shown in the tooltip under the name given by the top-level "ztitle".', 'REAL', FALSE, TRUE),
-    ('label', 'An alias for parameter "x"', 'REAL', FALSE, TRUE),
+    ('label', 'An alias for parameter "x". On a row that draws a reference line, the text to display next to the line.', 'TEXT', FALSE, TRUE),
     ('value', 'An alias for parameter "y"', 'REAL', FALSE, TRUE),
-    ('series', 'If multiple series are represented and share the same y-axis, this parameter can be used to distinguish between them.', 'TEXT', FALSE, TRUE)
+    ('series', 'If multiple series are represented and share the same y-axis, this parameter can be used to distinguish between them.', 'TEXT', FALSE, TRUE),
+    ('yline', 'Draws a reference line across the chart at this value of the y axis instead of plotting a point, to show a limit such as a quota or an alarm threshold. Not drawn if it falls outside of the axis, so set ymax when the limit is above the data.', 'REAL', FALSE, TRUE),
+    ('color', 'The name of a color for the reference line this row draws. Grey by default.', 'COLOR', FALSE, TRUE)
 ) x;
 INSERT INTO example(component, description, properties) VALUES
     ('chart', 'An area chart representing a time series, using the top-level property `time`.
@@ -792,6 +794,65 @@ The `color` property sets the color of each series separately, in order.
         {"series": "Yearly maintenance", "label": "Maintenance", "value": ["2022-01-01", "2022-01-03"]}
     ]')),
     ('chart', '
+## Reference lines
+
+A row with a `yline` is not plotted as a data point, but drawn as a line across
+the whole chart, at that value of the y axis. Use it for the limit that the data
+should be read against: a disk quota, an alarm threshold, a service level
+objective.
+
+Reference lines are rows, so they come from a query like everything else,
+and a chart can have as many of them as the query returns:
+
+```sql
+select ''chart'' as component, ''CPU temperature'' as title, true as time, 100 as ymax;
+select celsius as yline, name as label, color as color from thresholds;
+select measured_at as x, celsius as y from readings order by measured_at;
+```
+
+They are drawn as annotations rather than as an extra series, so they are not
+added to the total of a `stacked` chart, and are not filled in an `area` chart.
+
+A line outside of the y axis is not drawn, and does not stretch the axis to fit,
+so set `ymax` when the limit is above the data.
+', json('[
+        {"component":"chart", "title": "CPU temperature", "type": "line", "time": true,
+         "ytitle": "°C", "ymax": 100, "color": "azure", "marker": 4},
+        {"yline": 70, "label": "target", "color": "green"},
+        {"yline": 90, "label": "throttling", "color": "red"},
+        {"x": "2024-05-01T08:00:00Z", "y": 52},
+        {"x": "2024-05-01T09:00:00Z", "y": 58},
+        {"x": "2024-05-01T10:00:00Z", "y": 71},
+        {"x": "2024-05-01T11:00:00Z", "y": 83},
+        {"x": "2024-05-01T12:00:00Z", "y": 94},
+        {"x": "2024-05-01T13:00:00Z", "y": 76},
+        {"x": "2024-05-01T14:00:00Z", "y": 63}
+    ]')),
+    ('chart', '
+## Reference lines follow their axis
+
+A reference belongs to the column it is written in, not to a direction on the
+screen: `yline` always marks a value of `y`, whichever way round the chart is
+drawn. A `horizontal` bar chart runs its y axis from left to right, so a `yline`
+is drawn down the chart rather than across it.
+
+```sql
+select ''chart'' as component, ''bar'' as type, true as horizontal, 100 as ymax;
+select 90 as yline, ''full'' as label, ''red'' as color;
+select host as x, percent_used as y from disks order by percent_used;
+```
+
+A `pie` has no axes, and ignores reference lines.
+', json('[
+        {"component":"chart", "title": "Disk usage", "type": "bar", "horizontal": true,
+         "ymax": 100, "color": "azure", "labels": true},
+        {"yline": 90, "label": "full", "color": "red"},
+        {"x": "backup-1", "y": 41},
+        {"x": "web-2", "y": 63},
+        {"x": "db-1", "y": 88},
+        {"x": "web-1", "y": 96}
+    ]')),
+    ('chart', '
 ## Multiple charts on the same line
 
 You can create information-dense dashboards by using the [card component](?component=card#component)

sqlpage/apexcharts.js

@@ -118,6 +118,45 @@ sqlpage_chart = (() => {
   if (typeof module !== "undefined")
     module.exports = { align_series, align_series_for, merged_x_values };
 
+  const referenceColor = colorNames[isDarkTheme ? "gray-lt" : "gray"];
+
+  /** @typedef { {[property:string]: string|number|null} } ReferenceLine */
+
+  /** @param {string|number|null} name */
+  const reference_color = (name) =>
+    (typeof name === "string" && colorNames[name]) || referenceColor;
+
+  /**
+   * @param {ReferenceLine[]} rows - the rows that carry a yline
+   * @param {"x"|"y"} axis - the apexcharts axis the y column is drawn on
+   * @param {(value: any) => any} to_axis_value - puts a SQL value on the axis
+   * @returns {object[]} apexcharts axis annotations
+   */
+  function y_reference_lines(rows, axis, to_axis_value) {
+    return rows.flatMap((row) => {
+      if (row.yline == null) return [];
+      const from = to_axis_value(row.yline);
+      if (Number.isNaN(from)) return [];
+      const color = reference_color(row.color);
+      const annotation = {
+        [axis]: from,
+        borderColor: color,
+        fillColor: color,
+        strokeDashArray: 4,
+      };
+      // apexcharts reads label.text unconditionally, so an annotation without
+      // a label must not have the key at all.
+      if (row.label)
+        annotation.label = {
+          text: row.label,
+          orientation: "horizontal",
+          borderColor: color,
+          style: { background: color, color: isDarkTheme ? "#000" : "#fff" },
+        };
+      return [annotation];
+    });
+  }
+
   /** @param {HTMLElement} c */
   function build_sqlpage_chart(c) {
     const [data_element] = c.getElementsByTagName("data");
@@ -131,9 +170,11 @@ sqlpage_chart = (() => {
       APEXCHARTS_TYPE_ALIASES[data.type] || data.type || "line";
     const is_stacked =
       !!data.stacked && STACKABLE_CHART_TYPES.includes(chart_type);
+    const points = data.points.filter(Array.isArray);
+    const reference_rows = data.points.filter((row) => !Array.isArray(row));
     /** @type { Series } */
     const series_map = {};
-    for (const [name, old_x, old_y, z] of data.points) {
+    for (const [name, old_x, old_y, z] of points) {
       series_map[name] = series_map[name] || { name, data: [] };
       let x = old_x;
       let y = old_y;
@@ -161,12 +202,27 @@ sqlpage_chart = (() => {
     let labels;
     const categories = x_is_text(series);
     if (chart_type === "pie") {
-      labels = data.points.map(([name, x, _y]) => x || name);
-      series = data.points.map(([_name, _x, y]) => Number.parseFloat(y));
+      labels = points.map(([name, x, _y]) => x || name);
+      series = points.map(([_name, _x, y]) => Number.parseFloat(y));
     } else if (series.length > 1)
       series = align_series_for(series, chart_type, is_stacked);
 
+    const to_value =
+      is_timeseries && chart_type === "rangeBar"
+        ? (v) =>
+            (typeof v === "number" ? new Date(v * 1000) : new Date(v)).getTime()
+        : Number;
+    const inverted =
+      chart_type === "rangeBar" || (chart_type === "bar" && !!data.horizontal);
+    const value_axis = inverted ? "x" : "y";
     const options = {
+      annotations: {
+        [`${value_axis}axis`]: y_reference_lines(
+          reference_rows,
+          value_axis,
+          to_value,
+        ),
+      },
       chart: {
         type: chart_type,
         fontFamily: "inherit",

sqlpage/templates/chart.handlebars

@@ -40,12 +40,19 @@
     "points": [
     {{~#each_row~}}
         {{~#if (gt @row_index 0)}},{{/if~}}
+        {{~#if yline~}}
+        {
+            "yline": {{~stringify yline}},
+            "label": {{~stringify label}}, "color": {{~stringify color}}
+        }
+        {{~else~}}
         [
             {{~ stringify (default series (default ../title "")) ~}},
             {{~ stringify (default x label) ~}},
             {{~ stringify (default y value) ~}}
             {{~#if z}}, {{~ stringify z ~}} {{~/if~}}
         ]
+        {{~/if~}}
     {{~/each_row~}}
     ]
 }

tests/end-to-end/official-site.spec.ts

@@ -76,6 +76,38 @@ test("stacked chart raises a series only where it has a value", async ({
   expect(Number(gpu[1].y)).toBeLessThan(Number(cpu[1].y));
 });
 
+test("chart draws a reference line for every yline", async ({ page }) => {
+  await page.goto(`${BASE}/documentation.sql?component=chart#component`);
+
+  const temperature = page.locator(".card", {
+    has: page.getByRole("heading", { name: "CPU temperature" }),
+  });
+  await expect(temperature.locator(".apexcharts-canvas")).toBeVisible();
+
+  const annotations = temperature.locator(".apexcharts-yaxis-annotations");
+
+  await expect(annotations.locator("line")).toHaveCount(2);
+  await expect(annotations.getByText("target")).toBeVisible();
+  await expect(annotations.getByText("throttling")).toBeVisible();
+});
+
+test("chart draws a yline down a horizontal chart", async ({ page }) => {
+  await page.goto(`${BASE}/documentation.sql?component=chart#component`);
+
+  const disks = page.locator(".card", {
+    has: page.getByRole("heading", { name: "Disk usage" }),
+  });
+  await expect(disks.locator(".apexcharts-canvas")).toBeVisible();
+
+  await expect(disks.locator(".apexcharts-xaxis-annotations line")).toHaveCount(
+    1,
+  );
+  await expect(disks.locator(".apexcharts-yaxis-annotations line")).toHaveCount(
+    0,
+  );
+  await expect(disks.getByText("full")).toBeVisible();
+});
+
 test("map", async ({ page }) => {
   await page.goto(`${BASE}/documentation.sql?component=map#component`);
   await expect(page.getByText("Loading...")).not.toBeVisible();