@record-evolution/widget-linechart 1.7.1 → 1.7.3

package/src/definition-schema.json

@@ -1,6 +1,27 @@
 {
-    "title": "inputData",
-    "description": "A versatile chart widget for visualizing data as line charts, bar charts, or scatter plots. Use this widget for time-series data, trend analysis, comparisons, and general data visualization. Supports multiple data series with different chart types in the same view, automatic pivot-based series generation, zoom controls, and flexible styling options. The ECharts-based rendering provides smooth animations and interactive tooltips. Ideal for monitoring dashboards, historical data analysis, and any scenario requiring visual data representation over continuous or categorical dimensions.",
+    "title": "Chart Configuration",
+    "description": "A versatile chart widget for visualizing data as line charts, bar charts, or scatter plots. Despite the package name, this is also THE bar chart widget: set dataseries[].type to 'bar' for vertical bars and axis.orientation to 'horizontal' for horizontal ones. Use this widget for time-series data, trend analysis, comparisons, frequency distributions, and general data visualization. Supports multiple data series with different chart types in the same view, automatic pivot-based series generation, zoom controls, and flexible styling options. The ECharts-based rendering provides smooth animations and interactive tooltips. Ideal for monitoring dashboards, historical data analysis, and any scenario requiring visual data representation over continuous or categorical dimensions.",
+    "aiSelection": {
+        "dataShape": "One or more series of (x, y) pairs. x is a timestamp, a number, or a category label and defines the position along the x-value dimension; y is the measured quantity. All series in a chart share one x dimension. An optional third column bound to data[].pivot splits a single series into one line or bar per distinct value of that column, and an optional data[].r sizes the marker for a bubble chart. Needs at least two columns of data; a single scalar has no shape to plot.",
+        "useWhen": [
+            "A quantity is measured repeatedly over time and the trend, shape or direction of change is the point (axis.timeseries: true, dataseries[].type: 'line').",
+            "A quantity is compared across a handful of discrete categories — counts, totals, frequency distributions, per-machine or per-site comparisons (dataseries[].type: 'bar', axis.timeseries: false). This is the correct widget for any bar chart; there is no separate bar chart widget.",
+            "Categories are being ranked, or their names are long enough to be unreadable side by side under a vertical axis (dataseries[].type: 'bar', axis.orientation: 'horizontal').",
+            "Two numeric variables are being correlated as a cloud of individual points (dataseries[].type: 'scatter'), optionally with data[].r encoding a third variable as marker size.",
+            "Several quantities with different units or wildly different ranges belong on one chart (assign the second group dataseries[].yAxis: 'right').",
+            "The same measurement is broken down by an entity — one line per machine, per site, per program (bind the breakdown column to data[].pivot)."
+        ],
+        "notFor": [
+            "Parts of a whole, shares, or percentages that add up to 100% — use widget-doughnut.",
+            "A single current number, reading or KPI with no second dimension to plot — use widget-value, or widget-gauge when it should be read against a min/max range.",
+            "Records the user needs to read row by row, or data with more columns than an x and a y — use widget-table.",
+            "Intensity or density across two categorical dimensions at once, i.e. a matrix or calendar grid — use widget-heatmap.",
+            "How long an entity stayed in each discrete state over time (state timelines, machine mode history, up/down periods drawn as spans). A bar chart of state durations is the wrong shape — use widget-statehistory.",
+            "Anything positioned by geographic coordinates — use widget-mapbox.",
+            "A single binary or few-valued status shown as an indicator rather than plotted — use widget-signal, or widget-switch when the user must also be able to toggle it.",
+            "Free text, headings or explanatory prose — use widget-label, widget-textbox or widget-markdown."
+        ]
+    },
     "type": "object",
     "properties": {
         "title": {
@@ -73,9 +94,18 @@
                     "dataDrivenDisabled": true,
                     "order": 4
                 },
+                "orientation": {
+                    "title": "Bar Direction",
+                    "description": "The direction in which bars grow and the chart is read. 'vertical' (the default) places the x-values (categories or timestamps) along the horizontal axis at the bottom and the measured y-values along the vertical axis, so bars grow upwards. 'horizontal' swaps the two axes: the x-values run down the left-hand vertical axis, first data point at the top, and the y-values grow to the right, producing a horizontal bar chart. Choose 'horizontal' for ranked or frequency charts, and whenever category names are long enough to be unreadable when squeezed under a vertical axis. This setting affects only the drawing direction, not the meaning of the other options: 'X-Axis Label' always names the x-value dimension and 'Y-Axis Label' always names the measured values, whichever side of the chart they end up on. Applies to all series in the chart, including line and scatter series.",
+                    "type": "string",
+                    "enum": ["vertical", "horizontal"],
+                    "default": "vertical",
+                    "dataDrivenDisabled": true,
+                    "order": 4.5
+                },
                 "columnLayout": {
-                    "title": "Vertical Layout",
-                    "description": "When multiple charts are drawn (via chartName grouping), this controls their arrangement. Enabled = stacked vertically, Disabled = arranged horizontally side by side.",
+                    "title": "Stack Multiple Charts Vertically",
+                    "description": "Controls how SEPARATE charts are arranged relative to each other when the series are grouped into more than one chart via 'Chart Name' (dataseries[].advanced.chartName). Enabled = the charts are stacked one above the other, Disabled = the charts sit side by side. This is a page-layout option and has no effect on a single chart; to change the direction bars grow in, use 'Bar Direction' (axis.orientation) instead.",
                     "type": "boolean",
                     "dataDrivenDisabled": true,
                     "order": 5
@@ -218,6 +248,14 @@
                                     "none"
                                 ],
                                 "order": 5
+                            },
+                            "showValueLabels": {
+                                "title": "Show Value Labels",
+                                "description": "When enabled, each data point's y-value is printed as text directly on the chart: above the top of every bar in a vertical bar chart, just past the end of the bar in a horizontal one, and above the marker for line and scatter series. Enable this whenever the reader is meant to read exact numbers off the chart rather than estimate them against the axis — the usual expectation for bar charts of counts, totals or frequencies, and the setting to use when someone asks for the values to be shown on or above the bars. Numbers are rounded to two decimal places; non-numeric values are printed unchanged. Leave it disabled for charts with many data points, where the labels would overlap each other.",
+                                "type": "boolean",
+                                "default": false,
+                                "dataDrivenDisabled": true,
+                                "order": 6
                             }
                         }
                     },

package/src/widget-linechart.ts

@@ -30,7 +30,7 @@ echarts.use([
     LegacyGridContainLabel
 ])
 
-import { InputData } from './definition-schema'
+import { ChartConfiguration } from './definition-schema'
 import { EChartsOption, SeriesOption } from 'echarts'
 import { TitleOption } from 'echarts/types/dist/shared'
 
@@ -43,12 +43,19 @@ type SeriesOptionX = SeriesOption & {
     minDate?: number
     maxDate?: number
     drawOrder: number
+    xAxisIndex?: number
     yAxisIndex?: number
+    // Which value axis (0 = primary, 1 = secondary) this series belongs to,
+    // independent of orientation. In a vertical chart the value axes are the
+    // y axes (left/right), in a horizontal one they are the x axes (bottom/top),
+    // so xAxisIndex/yAxisIndex alone cannot be read without knowing the
+    // orientation — this field can.
+    valueAxisIndex?: number
 }
 @customElement('widget-linechart-versionplaceholder')
 export class WidgetLinechart extends LitElement {
     @property({ type: Object })
-    inputData?: InputData
+    inputData?: ChartConfiguration
 
     @property({ type: Object })
     theme?: Theme
@@ -270,9 +277,49 @@ export class WidgetLinechart extends LitElement {
         echarts.registerTheme(theme.theme_name, filteredTheme)
     }
 
+    /** True when bars grow to the right instead of upwards (axis.orientation). */
+    isHorizontal(): boolean {
+        return this.inputData?.axis?.orientation === 'horizontal'
+    }
+
+    /**
+     * Index of the measured y-value inside a data point's `value` tuple.
+     *
+     * A point is stored as `[x, y, r]` for a vertical chart. A horizontal chart
+     * swaps the first two entries to `[y, x, r]`, because ECharts always maps
+     * tuple index 0 to the x axis and index 1 to the y axis — and in a
+     * horizontal chart the measured value is what belongs on the x axis.
+     */
+    private valueIndex(): number {
+        return this.isHorizontal() ? 0 : 1
+    }
+
+    /** Index of the x-value (category/timestamp) inside a data point's `value` tuple. */
+    private categoryIndex(): number {
+        return this.isHorizontal() ? 1 : 0
+    }
+
+    /**
+     * Formatter for the on-chart value labels (styling.showValueLabels).
+     * Rounds to two decimals to match the numeric axis labels, and leaves
+     * categorical y-values untouched.
+     */
+    private valueLabelFormatter(valueIdx: number) {
+        return (params: any) => {
+            const raw = Array.isArray(params?.value) ? params.value[valueIdx] : params?.value
+            if (raw === undefined || raw === null || raw === '') return ''
+            const num = Number(raw)
+            return isNaN(num) ? String(raw) : String(Math.round(num * 100) / 100)
+        }
+    }
+
     transformData() {
         if (!this?.inputData?.dataseries?.length) return
 
+        const horizontal = this.isHorizontal()
+        const valueIdx = this.valueIndex()
+        const categoryIdx = this.categoryIndex()
+
         // reset all existing chart dataseries
         this.canvasList.forEach((chartM) => {
             chartM.series = []
@@ -309,22 +356,29 @@ export class WidgetLinechart extends LitElement {
                         : derivedBgColors[i]
                     : undefined
                 const data = distincts.length === 1 ? ds.data : ds.data?.filter((d) => d.pivot === piv)
+                // The value tuple is [x, y, r] for a vertical chart and [y, x, r]
+                // for a horizontal one — ECharts always reads index 0 as the x
+                // axis, and in a horizontal chart the measured value lives there.
+                const toTuple = (x: any, y: any, r: any) => (horizontal ? [y, x, r] : [x, y, r])
                 let data2 = this.inputData?.axis?.timeseries
-                    ? (data?.map((d) => ({ name: d.x, value: [new Date(d.x ?? '').getTime(), d.y, d.r] })) ??
-                      [])
-                    : (data?.map((d) => ({ name: d.x, value: [d.x, d.y, d.r] })) ?? [])
+                    ? (data?.map((d) => ({
+                          name: d.x,
+                          value: toTuple(new Date(d.x ?? '').getTime(), d.y, d.r)
+                      })) ?? [])
+                    : (data?.map((d) => ({ name: d.x, value: toTuple(d.x, d.y, d.r) })) ?? [])
 
                 let minDate: number = 0,
                     maxDate: number = 0,
                     extraData: (string | number | undefined)[][] = []
                 if (this.xAxisType() === 'time' && data2) {
-                    const dates = data2.map((d: any) => d.value[0] as number)
+                    const dates = data2.map((d: any) => d.value[categoryIdx] as number)
                     minDate = Math.min(...dates)
                     maxDate = Math.max(...dates)
                     // extraData = (pds?.data as any[][])?.filter((d: any) => d[0] < minDate) ?? []
                     // data2.unshift(...extraData) // add old data to the beginning of the new data
                     // data2 = [...extraData, ...data2] // leave old data in for smooth shifting animation and delete after draw
                 }
+                const valueAxisIndex = ds.yAxis === 'right' ? 1 : 0
                 const pds: SeriesOptionX = {
                     id: name,
                     name: name,
@@ -346,9 +400,21 @@ export class WidgetLinechart extends LitElement {
                     symbol: ds.styling?.pointStyle ?? 'circle',
                     symbolSize: (d: any[]) => d[2] ?? 0,
                     showSymbol: ds.styling?.pointStyle === 'none' ? false : true,
+                    label: {
+                        show: ds.styling?.showValueLabels ?? false,
+                        // Bars grow upwards when vertical and rightwards when
+                        // horizontal, so the label sits past the growing end.
+                        position: horizontal ? 'right' : 'top',
+                        fontSize: 12,
+                        formatter: this.valueLabelFormatter(valueIdx)
+                    },
                     data: data2 ?? [],
                     drawOrder: ds.advanced?.drawOrder ?? 0,
-                    yAxisIndex: ds.yAxis === 'right' ? 1 : 0
+                    valueAxisIndex: valueAxisIndex,
+                    // The secondary value axis is the right y axis when vertical
+                    // and the top x axis when horizontal.
+                    xAxisIndex: horizontal ? valueAxisIndex : 0,
+                    yAxisIndex: horizontal ? 0 : valueAxisIndex
                 }
                 let chartName = ds.advanced?.chartName ?? ''
                 chartName = chartName.replace('#split#', prefix)
@@ -485,6 +551,7 @@ export class WidgetLinechart extends LitElement {
         const modifier = 1
         // Sort chartContainer children by drawOrder and label
         if (!this.chartContainer) return
+        const horizontal = this.isHorizontal()
         for (const canvas of this.canvasList.values()) {
             if (canvas.element) this.chartContainer.appendChild(canvas.element)
         }
@@ -513,17 +580,37 @@ export class WidgetLinechart extends LitElement {
                 yAxisScalingRight: this.inputData?.axis?.yAxisScalingRight,
                 xAxisType: this.xAxisType(),
                 yAxisType: this.yAxisType(),
+                // Flipping the orientation swaps which option key holds the
+                // single category axis and which holds the value-axis array,
+                // so it must force a notMerge rebuild rather than a merge.
+                orientation: this.inputData?.axis?.orientation ?? 'vertical',
                 seriesCount: chart.series.length,
                 seriesNames: chart.series.map((s) => s.name).join(','),
-                seriesAxes: chart.series.map((s) => s.yAxisIndex ?? 0).join(',')
+                seriesAxes: chart.series.map((s) => s.valueAxisIndex ?? 0).join(','),
+                seriesLabels: chart.series.map((s) => ((s as any).label?.show ? 1 : 0)).join(',')
             })
             const configChanged = chart.lastConfig !== currentConfig
             chart.lastConfig = currentConfig
 
-            // Use efficient merge for data-only updates, full rebuild for config changes
-            const option: any = configChanged
-                ? window.structuredClone(this.template)
-                : (chart.echart?.getOption() ?? window.structuredClone(this.template))
+            // Always build the option from the template — never from getOption().
+            //
+            // getOption() returns every component normalized to an *array*, while
+            // everything below treats the single-instance ones (title, xAxis, grid,
+            // legend, toolbox) as plain objects. `{ ...option.grid }` on an array
+            // yields `{ '0': grid }`, which ECharts then deep-merges back into its
+            // stored option — burying a copy one level deeper on *every* update. The
+            // stored option grew one level per frame until zrender's recursive
+            // merge()/clone() ran out of stack, so any board left open on a live
+            // time series eventually died with "Maximum call stack size exceeded".
+            // Assignments like `option.title.text` landed on the array object for the
+            // same reason and were silently dropped, which is why the title, axis
+            // name, legend and zoom toolbox stopped tracking config on that path.
+            //
+            // A template clone carries only the keys we actually set, so a merge
+            // update still preserves ECharts-side state (zoom position, animation
+            // continuity) — and it skips deep-cloning every series' data each frame.
+            // `configChanged` still decides merge vs. rebuild via notMerge below.
+            const option: any = window.structuredClone(this.template)
 
             // Title
             option.title.text = label
@@ -553,19 +640,21 @@ export class WidgetLinechart extends LitElement {
                 }
             }
 
-            option.dataZoom[0].show = this.inputData?.axis?.xAxisZoom ?? false
-            option.toolbox.show = this.inputData?.axis?.xAxisZoom ?? false
+            const showZoom = this.inputData?.axis?.xAxisZoom ?? false
+            option.dataZoom[0].show = showZoom
+            option.toolbox.show = showZoom
 
             // Y axes: index 0 = left (primary), index 1 = right (secondary).
-            // The template holds an array, but getOption() (merge path) also returns
-            // component options normalized to arrays — handle both shapes.
+            // The template holds an array; normalize anyway so a template edit
+            // that drops down to a single axis object cannot silently break this.
             const yAxes: any[] = Array.isArray(option.yAxis) ? option.yAxis : [option.yAxis ?? {}]
             while (yAxes.length < 2) yAxes.push({})
             option.yAxis = yAxes
 
-            const rightAxisUsed = chart.series.some((s) => (s.yAxisIndex ?? 0) === 1)
+            const hasValueLabels = chart.series.some((s) => !!(s as any).label?.show)
+            const rightAxisUsed = chart.series.some((s) => (s.valueAxisIndex ?? 0) === 1)
             const leftAxisUsed =
-                chart.series.length === 0 || chart.series.some((s) => (s.yAxisIndex ?? 0) === 0)
+                chart.series.length === 0 || chart.series.some((s) => (s.valueAxisIndex ?? 0) === 0)
             const showLeftAxis = showYAxis && leftAxisUsed
             const showRightAxis = showYAxis && rightAxisUsed
 
@@ -606,6 +695,42 @@ export class WidgetLinechart extends LitElement {
             })
             if (numericAxisLabel) yAxes[1].axisLabel = numericAxisLabel
 
+            // Orientation swap. Everything above builds one category axis (the
+            // x-values) and a two-entry array of value axes (the y-values). A
+            // vertical chart puts them where they were built; a horizontal one
+            // moves the category axis onto `yAxis` and the value axes onto
+            // `xAxis`. The axis *labels* keep their meaning either way:
+            // 'X-Axis Label' names the x-value dimension wherever it is drawn.
+            if (horizontal) {
+                const catAxis: any = Array.isArray(option.xAxis) ? option.xAxis[0] : option.xAxis
+                option.yAxis = {
+                    ...catAxis,
+                    position: 'left',
+                    // Read top-to-bottom, so the first data point is the top
+                    // bar — the convention for ranked horizontal bar charts.
+                    inverse: true,
+                    // 'start' is the top of an inverted axis, which keeps the
+                    // axis name clear of the value axis running along the bottom.
+                    // When a secondary value axis is in use it is drawn along
+                    // the top, so the name has to clear its tick labels too.
+                    nameLocation: 'start',
+                    nameGap: showRightAxis ? 30 : 10,
+                    nameTextStyle: { align: 'left' }
+                }
+                option.xAxis = yAxes.map((axis: any, index: number) => ({
+                    ...axis,
+                    position: index === 0 ? 'bottom' : 'top',
+                    nameLocation: 'middle',
+                    nameGap: 27,
+                    nameTextStyle: { align: 'center' }
+                }))
+                // Zooming still applies to the x-value dimension, which now
+                // lives on the y axis.
+                option.dataZoom = [
+                    { ...(option.dataZoom?.[0] ?? {}), xAxisIndex: undefined, yAxisIndex: [0] }
+                ]
+            }
+
             option.series = chart.series
             option.legend.show = showLegend
 
@@ -616,6 +741,13 @@ export class WidgetLinechart extends LitElement {
             const topPadding =
                 (showTitle || hasYAxisLabel || hasYAxisLabelRight ? 30 : 0) +
                 (showLegend && hasYAxisLabelRight ? 25 : 0)
+            // An ECharts slider dataZoom is ~30px thick and sits outside the
+            // grid's own bookkeeping, so nothing reserves room for it. Left
+            // unaccounted it is drawn straight over the plot, clipping the foot
+            // of every bar and washing out the axis labels underneath.
+            const ZOOM_THICKNESS = 40
+            const zoomPadBottom = showZoom && !horizontal ? ZOOM_THICKNESS : 0
+            const zoomPadRight = showZoom && horizontal ? ZOOM_THICKNESS : 0
             option.grid = {
                 ...option.grid,
                 show: showBox,
@@ -623,12 +755,31 @@ export class WidgetLinechart extends LitElement {
                 borderWidth: showBox ? 1 : 0,
                 borderColor: this.themeTitleColor ?? '#ccc',
                 top: topPadding,
-                bottom: showXAxis ? 20 : 0,
-                left: showLeftAxis ? 20 : 0,
-                right: 0,
+                // The category axis sits at the bottom when vertical and on the
+                // left when horizontal; the value axis is the other way round.
+                // The zoom slider is not accounted for by `containLabel`, so its
+                // thickness has to be reserved here as well — see ZOOM_THICKNESS.
+                bottom: ((horizontal ? showLeftAxis : showXAxis) ? 20 : 0) + zoomPadBottom,
+                left: (horizontal ? showXAxis : showLeftAxis) ? 20 : 0,
+                // A horizontal chart grows towards the right edge, so the last
+                // axis tick and any value label printed past the end of a bar
+                // need room that `containLabel` does not reserve for them.
+                right: (horizontal ? (hasValueLabels ? 45 : 15) : 0) + zoomPadRight,
                 containLabel: showXAxis || showYAxis
             }
 
+            // Anchor the slider to the edge whose dimension it zooms: the bottom
+            // for a vertical chart, the right-hand side for a horizontal one
+            // (where it controls the y axis and ECharts draws it upright).
+            if (showZoom) {
+                Object.assign(
+                    option.dataZoom[0],
+                    horizontal
+                        ? { right: 0, top: topPadding, bottom: 20, left: undefined }
+                        : { bottom: 0, left: undefined, right: undefined, top: undefined }
+                )
+            }
+
             // Calculate animation duration based on update frequency
             const animationDuration = this.updateThresholdMs //this.calculateAnimationDuration(chart, label)
             option.animation = true