@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/collection/components/charts/wm-line-chart/wm-line-chart.js

@@ -0,0 +1,999 @@
+import { h, Host, forceUpdate } from "@stencil/core";
+import { csvToArray, debounce, transposeMatrix, getSmallestSkipInterval, wrapAround, calcPercentageInRange, } from "../../../global/functions";
+import { getInterval, inferDecimalPlacesForUnitValue, suffixNumber } from "../chartFunctions";
+import { chartMessages, globalMessages, lineChartMessages } from "../../../global/intl";
+/**
+ * Visualizes how data changes over time. Ideal for trend analysis — tracking one or more
+ * metrics across chronological intervals such as semesters, academic years, or months.
+ * Supports up to 7 lines, each differentiated by both color and symbol. Data is set via the
+ * `line-data` prop (JSON string or object). Minimum width of 562 px; horizontally scrollable
+ * at smaller viewports.
+ *
+ * @category Data Visualization
+ *
+ * @keyboardInteraction
+ * - **Tab** (into chart): If `visibility-toggles` is enabled, focuses the first toggle button;
+ *   otherwise focuses the first data point.
+ * - **Tab** (on toggle button): Moves to the first data point of the first visible line.
+ * - **Shift+Tab** (on first data point, with toggles): Returns focus to the toggle buttons.
+ * - **Arrow Up / Down** (on data point): Moves focus vertically to the same x-interval on
+ *   the previous/next line.
+ * - **Arrow Left / Right** (on data point): Moves focus to the previous/next data point on
+ *   the same line.
+ * - **Arrow Left / Right** (on toggle button): Cycles between toggle buttons.
+ *
+ * @accessibility
+ * - `label`, `x-axis-label`, and `y-axis-label` are required for accessibility.
+ * - Each data point renders as `role="img"` with a detailed `aria-label` including the line
+ *   name, x-value, y-value, units, and (if `show-deltas`) the percentage change from the
+ *   previous point.
+ * - An `aria-live` region announces the line name and data point count when keyboard focus
+ *   moves to a new line.
+ * - The `description` prop is appended to the chart instructions read to screen readers —
+ *   use it to summarize the key takeaway.
+ *
+ * @usageNotes
+ * - `line-data` expects a JSON object where keys are line labels and values are objects mapping
+ *   x-axis values (strings) to y-axis values (numbers or `null` for missing data points).
+ *   In HTML, set it as a JSON string attribute; in JavaScript/React, set it as an object.
+ * - Up to 7 lines are supported — each is automatically assigned a color and symbol from
+ *   the built-in palette.
+ * - `spotlight-data` adds a single reference line spanning the whole chart. Provide an object
+ *   with a `label` key and one x-value key mapping to the y-value.
+ *
+ * @example {html} Basic line chart
+ * <wm-line-chart label="Enrollment trend" x-axis-label="Term" y-axis-label="Students"
+ *   line-data='{"Biology": {"Fall 2022": 310, "Fall 2023": 340}}'></wm-line-chart>
+ *
+ * @example {react} Basic line chart
+ * <WmLineChart label="Enrollment trend" xAxisLabel="Term" yAxisLabel="Students"
+ *   lineData={{ Biology: { "Fall 2022": 310, "Fall 2023": 340 } }} />
+ *
+ * @example {html} Multi-line with delta comparisons
+ * <wm-line-chart label="Retention rates" x-axis-label="Year" y-axis-label="Rate"
+ *   units="null,percent" show-deltas
+ *   line-data='{"Biology": {"2022": 85, "2023": 88}, "English": {"2022": 79, "2023": 82}}'>
+ * </wm-line-chart>
+ *
+ * @example {react} Multi-line with delta comparisons
+ * <WmLineChart label="Retention rates" xAxisLabel="Year" yAxisLabel="Rate"
+ *   units="null,percent" showDeltas={true}
+ *   lineData={{ Biology: { "2022": 85, "2023": 88 }, English: { "2022": 79, "2023": 82 } }} />
+ *
+ */
+export class LineChart {
+    constructor() {
+        this.minTickWidth = 120;
+        this.lineStyles = [
+            { color: "#8b86ca", icon: "triangle" }, // lavender
+            { color: "#2e1b46", icon: "circle" }, // midnight
+            { color: "#0089e4", icon: "square" }, // blue
+            { color: "#088000", icon: "star" }, // forest
+            { color: "#ea8500", icon: "rhombus" }, // orange
+            { color: "#d54f41", icon: "triangle-inverted" }, // red
+            { color: "#146ca9", icon: "pentagon" }, // blue
+        ];
+        this.debouncedResize = debounce(async () => {
+            forceUpdate(this.el);
+        }, 100);
+        this.label = undefined;
+        this.description = "";
+        this.xAxisLabel = undefined;
+        this.yAxisLabel = undefined;
+        this.showGrid = true;
+        this.lineData = undefined;
+        this.units = "null,null";
+        this.labelWidth = "120px";
+        this.highlightQualifier = lineChartMessages.highlightQualifier;
+        this.highlightStart = undefined;
+        this.highlightEnd = undefined;
+        this.visibilityToggles = false;
+        this.showDeltas = false;
+        this.yRange = undefined;
+        this.spotlightData = undefined;
+        this.decimalPlaces = undefined;
+        this.parsedLineData = {};
+        this.popoverIndex = -1;
+        this.focusedLine = -1;
+        this.hiddenLines = [];
+        this.isTabbing = false;
+        this.announcement = "";
+    }
+    get xIntervals() {
+        const firstLine = Object.values(this.parsedLineData)[0];
+        return firstLine ? Object.keys(firstLine) : [];
+    }
+    get yIntervals() {
+        if (Object.keys(this.parsedLineData).length === 0)
+            return [];
+        let yIntervals = [];
+        if (this.yRange) {
+            yIntervals = csvToArray(this.yRange).map((val) => parseFloat(val));
+        }
+        else {
+            // gather all yValues
+            let allYValues = [];
+            const lines = Object.values(this.parsedLineData).flat();
+            lines.forEach((line) => allYValues.push(...Object.values(line)));
+            const filteredYValues = allYValues.filter((val) => val !== null);
+            // Clamp to integers for clean intervals
+            let minYValue = Math.floor(Math.min(...filteredYValues));
+            let maxYValue = Math.ceil(Math.max(...filteredYValues));
+            if (minYValue === maxYValue) {
+                // If the axis bounds are identical (flat line), add some grid height
+                minYValue -= 1;
+                maxYValue += 1;
+            }
+            // calculate neat yInterval
+            let interval = getInterval(maxYValue - minYValue, 4);
+            // find new min below smallest yValue that divides cleanly by interval
+            let counter = interval;
+            while (minYValue % interval !== 0 && counter > 0) {
+                minYValue--;
+                counter--;
+            }
+            // calculate new interval using new min
+            interval = getInterval(maxYValue - minYValue, 4);
+            let current = minYValue;
+            // determine top interval, no more than one tick above max yValue
+            while (current <= maxYValue + interval) {
+                yIntervals.push(current);
+                current += interval;
+            }
+        }
+        return yIntervals.reverse();
+    }
+    get intervalInfo() {
+        const maxTicks = this.plotAreaEl && this.plotAreaEl.clientWidth > 0
+            ? Math.round(this.plotAreaEl.clientWidth / this.minTickWidth)
+            : this.xIntervals.length;
+        return getSmallestSkipInterval(this.xIntervals, maxTicks);
+    }
+    get displayedXIntervals() {
+        return this.intervalInfo.skippedList;
+    }
+    get dataPointMatrix() {
+        if (Object.keys(this.parsedLineData).length === 0)
+            return [];
+        return Object.entries(this.parsedLineData).map((entry) => this.buildLineDataPointDetails(entry[0], entry[1]));
+    }
+    get popoverData() {
+        return transposeMatrix(this.dataPointMatrix);
+    }
+    get spotlightXValue() {
+        if (this.spotlightData) {
+            const keys = Object.keys(this.spotlightData).filter((key) => key !== "label");
+            return keys[0];
+        }
+        return undefined;
+    }
+    get spotlightYValue() {
+        if (this.spotlightData && this.spotlightXValue) {
+            const raw = this.spotlightData[this.spotlightXValue];
+            if (typeof raw !== "number") {
+                return undefined;
+            }
+            return raw;
+        }
+        return undefined;
+    }
+    parseData() {
+        if (typeof this.lineData === "string") {
+            this.parsedLineData = JSON.parse(this.lineData);
+        }
+        else {
+            this.parsedLineData = this.lineData;
+        }
+    }
+    get hasPartialInterval() {
+        // if chart width is too small, an odd # of intervals like 1,2,3,4,5,6,7 can be shortened to 1,3,5,7 or 1,4,7
+        // but an even # like 1,2,3,4,5,6,7,8 will be shortened to 1,3,5,7 (can't show first and last interval)
+        // in these cases, show a partial interval must be shown in order to still provide space to plot the 8th data point
+        // e.g intervals will be 1-3, 3-5, 5-7, 7-8
+        return this.intervalInfo.skipInterval > 0 && this.xIntervals.length % 2 === 0;
+    }
+    get parsedUnits() {
+        return csvToArray(this.units).map((unit) => (unit === "null" ? null : unit));
+    }
+    get visibilityToggleEls() {
+        return this.legendEl.querySelectorAll("wm-button");
+    }
+    get lineEls() {
+        return this.plotAreaEl.querySelectorAll(".line");
+    }
+    get firstVisibleLineIdx() {
+        let firstVisibleLineIdx = 0;
+        while (this.hiddenLines.includes(firstVisibleLineIdx)) {
+            firstVisibleLineIdx++;
+        }
+        return firstVisibleLineIdx < this.dataPointMatrix.length ? firstVisibleLineIdx : -1;
+    }
+    get pointEls() {
+        return this.plotAreaEl.querySelectorAll(".point");
+    }
+    toggleTabbingOn() {
+        this.isTabbing = true;
+    }
+    toggleTabbingOff() {
+        this.isTabbing = false;
+    }
+    componentWillLoad() {
+        this.parseData();
+    }
+    componentDidLoad() {
+        const resizeObserver = new ResizeObserver(() => this.debouncedResize());
+        resizeObserver.observe(this.el);
+    }
+    handleVisibilityToggleKeydown(ev, toggleIdx) {
+        switch (ev.key) {
+            case "Tab":
+                if (!ev.shiftKey && this.firstVisibleLineIdx !== -1) {
+                    ev.preventDefault();
+                    this.announce(this.lineFocusMessage(this.firstVisibleLineIdx));
+                    const point = this.lineEls[this.firstVisibleLineIdx].querySelector(".point");
+                    point && this.focusDataPointByEl(point);
+                }
+                break;
+            case "ArrowUp":
+            case "ArrowLeft":
+                ev.preventDefault();
+                const prevToggleIdx = wrapAround(toggleIdx, -1, this.dataPointMatrix.length - 1);
+                this.visibilityToggleEls[prevToggleIdx].focus();
+                break;
+            case "ArrowDown":
+            case "ArrowRight":
+                ev.preventDefault();
+                const nextToggleIdx = wrapAround(toggleIdx, 1, this.dataPointMatrix.length - 1);
+                this.visibilityToggleEls[nextToggleIdx].focus();
+                break;
+        }
+    }
+    handleDataPointKeydown(ev) {
+        const curPointEl = ev.target;
+        switch (ev.key) {
+            case "Tab":
+                if (ev.shiftKey && this.visibilityToggles) {
+                    ev.preventDefault();
+                    this.visibilityToggleEls[0].focus();
+                }
+                break;
+            case "ArrowUp":
+                ev.preventDefault();
+                this.navigatePointsVertically(curPointEl, -1);
+                break;
+            case "ArrowDown":
+                ev.preventDefault();
+                this.navigatePointsVertically(curPointEl, 1);
+                break;
+            case "ArrowLeft":
+                ev.preventDefault();
+                this.navigatePointsHorizontally(curPointEl, -1);
+                break;
+            case "ArrowRight":
+                ev.preventDefault();
+                this.navigatePointsHorizontally(curPointEl, 1);
+                break;
+        }
+    }
+    navigatePointsVertically(originPoint, stepAmount) {
+        const pointElsInColumn = Array.from(this.pointEls).filter((p) => p.dataset.pointidx == originPoint.dataset.pointidx);
+        if (pointElsInColumn.length > 1) {
+            const nextPointIdx = wrapAround(pointElsInColumn.indexOf(originPoint), stepAmount, pointElsInColumn.length - 1);
+            const nextVerticalPoint = pointElsInColumn[nextPointIdx];
+            const idx = nextVerticalPoint.dataset.lineidx;
+            const msg = idx && this.lineFocusMessage(parseInt(idx));
+            msg && this.announce(msg);
+            this.focusDataPointByEl(nextVerticalPoint);
+        }
+    }
+    navigatePointsHorizontally(originPoint, stepAmount) {
+        const linePoints = Array.from(originPoint.parentElement.querySelectorAll(".point"));
+        if (linePoints.length > 1) {
+            const nextPointIdxInDirection = wrapAround(linePoints.indexOf(originPoint), stepAmount, linePoints.length - 1);
+            const nextHorizontalPoint = linePoints[nextPointIdxInDirection];
+            this.focusDataPointByEl(nextHorizontalPoint);
+        }
+    }
+    announce(message) {
+        // \u00A0 is a non-breaking space character, which causes the message to be read as a new one
+        if (this.liveRegionEl.textContent === message) {
+            message += "\u00A0";
+        }
+        this.announcement = message;
+    }
+    lineFocusMessage(lineIdx) {
+        const label = this.dataPointMatrix[lineIdx][0].lineLabel;
+        const numDataPoints = this.dataPointMatrix[lineIdx].filter((datapoint) => datapoint.yValue !== null).length;
+        const focusMessage = lineChartMessages.getLineFocusAnnouncement(label, lineIdx + 1, this.dataPointMatrix.length, numDataPoints);
+        return focusMessage;
+    }
+    focusDataPointByEl(pointEl) {
+        this.pointEls.forEach((point) => (point.tabIndex = -1));
+        pointEl.tabIndex = 0;
+        pointEl.focus();
+    }
+    formatDisplayYValue(yValue) {
+        if (this.decimalPlaces === undefined) {
+            return new Intl.NumberFormat().format(yValue);
+        }
+        return yValue.toFixed(this.decimalPlaces);
+    }
+    formatYAxisIntervalLabel(intervalValue) {
+        var _a;
+        const decimalPlaces = (_a = this.decimalPlaces) !== null && _a !== void 0 ? _a : inferDecimalPlacesForUnitValue(intervalValue);
+        let absFormattedValue = suffixNumber(Math.abs(intervalValue), decimalPlaces);
+        if (intervalValue < 0) {
+            absFormattedValue = "-" + absFormattedValue;
+        }
+        return absFormattedValue;
+    }
+    buildLineDataPointDetails(lineLabel, line) {
+        let dataPointDetailsList = [];
+        const lineDataPoints = Object.entries(line);
+        let isHighlighted;
+        lineDataPoints.forEach((entry, pointIdx) => {
+            const [xValue, yValue] = entry;
+            let xPositionPercent = (100 / (lineDataPoints.length - 1)) * pointIdx;
+            const yPositionPercent = yValue === null
+                ? null
+                : 100 - calcPercentageInRange(yValue, this.yIntervals[this.yIntervals.length - 1], this.yIntervals[0]);
+            // add space between first points and y-axis
+            if (pointIdx === 0) {
+                xPositionPercent +=
+                    this.plotAreaEl && this.plotAreaEl.clientWidth > 0 ? (8 / this.plotAreaEl.clientWidth) * 100 : 1;
+            }
+            if (xValue === this.highlightStart && !isHighlighted) {
+                isHighlighted = true;
+            }
+            dataPointDetailsList.push({
+                lineLabel: lineLabel,
+                xValue: xValue,
+                yValue: yValue,
+                xPositionPercent: xPositionPercent,
+                yPositionPercent: yPositionPercent,
+                highlighted: isHighlighted,
+            });
+            // because highlight range is inclusive, disable after pushing details
+            if (xValue === this.highlightEnd && isHighlighted) {
+                isHighlighted = false;
+            }
+        });
+        return dataPointDetailsList;
+    }
+    toggleLineVisibility(lineIdx) {
+        if (this.hiddenLines.includes(lineIdx)) {
+            this.hiddenLines = this.hiddenLines.filter((num) => num !== lineIdx);
+        }
+        else {
+            this.hiddenLines.push(lineIdx);
+        }
+        forceUpdate(this.el);
+    }
+    resetDataPointFocus() {
+        this.popoverIndex = -1;
+        this.pointEls.forEach((point) => (point.tabIndex = -1));
+        if (this.firstVisibleLineIdx !== -1) {
+            const lineEl = this.lineEls[this.firstVisibleLineIdx];
+            const linePointEl = lineEl.querySelectorAll(".point")[0];
+            linePointEl.tabIndex = 0;
+        }
+    }
+    calcDelta(dataPoint, prevDataPoint) {
+        let delta;
+        if (dataPoint.yValue === null || prevDataPoint.yValue === null) {
+            // display "No data" when either of the datapoints is missing
+            delta = lineChartMessages.noData;
+        }
+        else if (dataPoint.yValue == prevDataPoint.yValue) {
+            // display "0%" if datapoints are equal
+            delta = "0%";
+        }
+        else if (prevDataPoint.yValue == 0) {
+            // display "-" for % increase if prev data point is 0, as the technical number would be infinity
+            delta = "-";
+        }
+        else {
+            const changePercent = ((dataPoint.yValue - prevDataPoint.yValue) / prevDataPoint.yValue) * 100;
+            const roundedPercent = Math.round(changePercent * 100) / 100;
+            delta = `${roundedPercent > 0 ? "+" : ""}${roundedPercent}%`;
+        }
+        return delta;
+    }
+    renderLegend() {
+        var _a;
+        const lineLabels = Object.keys(this.parsedLineData);
+        return (h("div", { ref: (el) => (this.legendEl = el), class: "legend" }, ((_a = this.spotlightData) === null || _a === void 0 ? void 0 : _a.label) && (h("div", { class: "legend-label" }, h("div", { class: "svg-icon svg-spotlight" }), this.spotlightData.label)), lineLabels.map((lineLabel, lineIdx) => {
+            const isHidden = this.hiddenLines.includes(lineIdx);
+            const isFaded = this.focusedLine !== -1 && this.focusedLine !== lineIdx;
+            return (h("div", { id: `legend-label-${lineIdx}`, class: `legend-label ${isFaded ? "faded" : ""}`, onMouseEnter: () => (this.focusedLine = isHidden ? -1 : lineIdx), onMouseLeave: () => (this.focusedLine = -1) }, this.renderIcon(lineIdx), lineLabel, this.visibilityToggles && this.renderVisibilityToggle(lineLabel, lineIdx, isHidden)));
+        })));
+    }
+    renderVisibilityToggle(lineLabel, lineIdx, isHidden) {
+        return (h("wm-button", { id: `visibility-button-${lineIdx}`, class: "visibility-toggle", "label-for-identical-buttons": `${lineIdx === 0 ? lineChartMessages.getToggleButtonLabel(this.dataPointMatrix.length) : ""} ${isHidden ? globalMessages.show : globalMessages.hide} ${lineLabel} ${lineChartMessages.getToggleButtonState(isHidden)}`, "button-type": "navigational", tooltip: isHidden ? globalMessages.show : globalMessages.hide, tooltipPosition: "bottom", icon: isHidden ? "#hide" : "#show", onClick: () => this.toggleLineVisibility(lineIdx), onKeyDown: (ev) => this.handleVisibilityToggleKeydown(ev, lineIdx), onFocus: () => (this.popoverIndex = -1) }));
+    }
+    renderIcon(lineIdx) {
+        const { color, icon } = this.lineStyles[lineIdx];
+        return h("div", { style: { color: color }, class: `svg-icon svg-shape-${icon}` });
+    }
+    renderXIntervals() {
+        const gridStyle = {
+            "--columns": `.5fr repeat(${this.xIntervals.length - 2}, 1fr) .5fr`,
+        };
+        return (h("div", { class: "x-intervals", style: gridStyle }, this.xIntervals.map((interval) => (h("span", { class: `x-interval ${this.displayedXIntervals.includes(interval) ? "" : "hidden"}` }, interval)))));
+    }
+    renderYIntervals() {
+        return (h("div", { ref: (el) => (this.yIntervalsEl = el), class: "y-intervals" }, this.yIntervals.map((yInterval, idx) => {
+            const percentFromTop = (100 / (this.yIntervals.length - 1)) * idx;
+            return (h("span", { class: "y-interval", style: { top: `${percentFromTop}%` } }, this.formatYAxisIntervalLabel(yInterval)));
+        })));
+    }
+    renderData() {
+        return this.dataPointMatrix.map((_, lineIdx) => {
+            let focusState = this.focusedLine === lineIdx ? "focused" : "faded";
+            const isHidden = this.hiddenLines.includes(lineIdx);
+            return (h("div", { class: `line ${this.focusedLine !== -1 ? focusState : ""} ${isHidden ? "hidden" : ""}` }, this.renderLines(lineIdx), this.renderPoints(lineIdx)));
+        });
+    }
+    renderPoints(lineIdx) {
+        const lineDataPoints = this.dataPointMatrix[lineIdx];
+        return (h("div", { class: "line-icons" }, lineDataPoints.map((dataPoint, pointIdx) => {
+            var _a;
+            const { lineLabel, xValue, yValue, xPositionPercent, yPositionPercent, highlighted } = dataPoint;
+            if (yValue !== null) {
+                const { color, icon } = this.lineStyles[lineIdx];
+                const firstPointTabIndex = lineIdx === 0 && pointIdx === 0 ? 0 : undefined;
+                const iconStyle = {
+                    color: color,
+                    "--xPosition": xPositionPercent + "%",
+                    "--yPosition": yPositionPercent + "%",
+                };
+                let ariaLabel = `${lineLabel} ${highlighted ? this.highlightQualifier : ""} ${this.xAxisLabel} ${xValue + (this.parsedUnits[0] ? this.parsedUnits[0] : "")}, ${this.yAxisLabel}: ${this.formatDisplayYValue(yValue)}${this.parsedUnits[1] ? this.parsedUnits[1] : ""}`;
+                if (this.showDeltas && pointIdx > 0) {
+                    const prevDataPoint = lineDataPoints[pointIdx - 1];
+                    const changeSinceMessage = lineChartMessages.getChangeSince(prevDataPoint.xValue);
+                    ariaLabel += `, ${changeSinceMessage} ${this.calcDelta(dataPoint, prevDataPoint)}`;
+                }
+                if (((_a = this.spotlightData) === null || _a === void 0 ? void 0 : _a.label) && this.spotlightYValue !== undefined) {
+                    ariaLabel += `, ${this.spotlightData.label} ${this.xAxisLabel} ${this.spotlightXValue + (this.parsedUnits[0] ? this.parsedUnits[0] : "")}, ${this.yAxisLabel}: ${this.formatDisplayYValue(this.spotlightYValue)}${this.parsedUnits[1] ? this.parsedUnits[1] : ""}`;
+                }
+                return (h("span", { id: `${lineLabel}-${pointIdx}`, role: "img", "aria-label": ariaLabel, tabIndex: firstPointTabIndex, class: `point svg-icon svg-shape-${icon}`, style: iconStyle, "data-lineidx": lineIdx, "data-pointidx": pointIdx, "data-xvalue": xValue, onKeyDown: (ev) => this.handleDataPointKeydown(ev), onFocus: () => (this.popoverIndex = pointIdx), onClick: (ev) => this.focusDataPointByEl(ev.target), onMouseEnter: () => (this.popoverIndex = pointIdx) }, h("span", { class: `point-bg svg-icon svg-shape-${icon}` })));
+            }
+        })));
+    }
+    renderLines(lineIdx) {
+        const lineDataPoints = this.dataPointMatrix[lineIdx];
+        return (h("svg", { class: "line-svg" }, lineDataPoints.map((dataPoint, pointIdx) => {
+            const shouldDraw = dataPoint.yValue !== null &&
+                pointIdx !== lineDataPoints.length - 1 &&
+                lineDataPoints[pointIdx + 1].yValue !== null;
+            if (shouldDraw) {
+                const { color } = this.lineStyles[lineIdx];
+                const { xPositionPercent: xStart, yPositionPercent: yStart } = dataPoint;
+                const { xPositionPercent: xEnd, yPositionPercent: yEnd } = lineDataPoints[pointIdx + 1];
+                return (h("line", { x1: xStart + "%", y1: yStart + "%", x2: xEnd + "%", y2: yEnd + "%", stroke: color, "stroke-width": "2px" }));
+            }
+        })));
+    }
+    renderSpotlight() {
+        if (!this.spotlightData || !this.spotlightXValue || this.spotlightYValue === undefined)
+            return "";
+        const yPositionPercent = 100 -
+            calcPercentageInRange(this.spotlightYValue, this.yIntervals[this.yIntervals.length - 1], this.yIntervals[0]);
+        const xIndex = this.xIntervals.indexOf(this.spotlightXValue);
+        const iconXPositionPercent = xIndex >= 0 ? (100 / (this.xIntervals.length - 1)) * xIndex : null;
+        return (h("div", { class: "spotlight", style: { "--yPosition": yPositionPercent + "%" } }, this.spotlightXValue && (h("div", { class: "spotlight-icon", style: { "--xPosition": iconXPositionPercent + "%" } }))));
+    }
+    renderHoverAreas() {
+        const hoverAreaStyle = { "--columns": `.5fr repeat(${this.xIntervals.length - 2}, 1fr) .5fr` };
+        return (h("div", { class: "hover-area-wrapper", style: hoverAreaStyle, onMouseLeave: () => (this.popoverIndex = -1) }, this.xIntervals.map((_, idx) => (h("div", { onMouseEnter: () => (this.popoverIndex = idx) })))));
+    }
+    renderPopover() {
+        const hasPopoverData = this.popoverData &&
+            this.popoverData[this.popoverIndex] &&
+            this.plotAreaEl.querySelector(`.point[data-xvalue="${this.dataPointMatrix[0][this.popoverIndex].xValue}"]`);
+        if (!hasPopoverData) {
+            return "";
+        }
+        const displayedPopoverData = this.popoverData[this.popoverIndex];
+        const xPosition = displayedPopoverData[0].xPositionPercent;
+        const yPositions = displayedPopoverData
+            .map((point) => point.yPositionPercent)
+            .filter((yPosition) => yPosition !== null);
+        const averageYPosition = yPositions.reduce((acc, cur) => acc + cur, 0) / yPositions.length;
+        const referencePointEl = this.plotAreaEl.querySelector(`.point[data-xvalue="${this.dataPointMatrix[0][this.popoverIndex].xValue}"]`);
+        const componentBoundingClientRect = this.el.getBoundingClientRect();
+        const referencePointBoundingClientRect = referencePointEl.getBoundingClientRect();
+        const rightSpaceAvailable = componentBoundingClientRect.right - referencePointBoundingClientRect.right;
+        const leftSpaceAvailable = referencePointBoundingClientRect.left - componentBoundingClientRect.left;
+        const hasRoomRight = rightSpaceAvailable >= (this.popoverEl ? Math.min(this.popoverEl.clientWidth, 400) : 400);
+        const hasRoomLeft = leftSpaceAvailable >= (this.popoverEl ? Math.min(this.popoverEl.clientWidth, 400) : 400);
+        const percentMargin = (8 / this.plotAreaEl.clientWidth) * 100;
+        let popoverStyle = {
+            "--leftPosition": hasRoomRight ? xPosition + percentMargin + "%" : "unset",
+            "--rightPosition": hasRoomLeft ? 100 - xPosition + percentMargin + "%" : "unset",
+            "--topPosition": averageYPosition + "%",
+            transform: "translateY(-50%)", // vertically center for averageYPosition
+        };
+        if (!hasRoomLeft && !hasRoomRight) {
+            // if there's not enough room to the left and right, position "detached" from the data points towards the top of the chart
+            const displaceLeft = `0px - ${this.labelWidth} - 20px - ${this.yIntervalsEl.clientWidth + "px"} + ${this.el.scrollLeft + "px"} + 2px`;
+            popoverStyle = {
+                "--leftPosition": `0%`,
+                "--topPosition": "0%",
+                maxWidth: Math.min(this.el.clientWidth - 2, 400) + "px", // take up no more max-width than is visually available
+                transform: `translateX(calc(${displaceLeft}))`, // align with left edge of component
+            };
+        }
+        return (h("div", { ref: (el) => (this.popoverEl = el), class: "popover", style: popoverStyle }, h("div", { class: "title" }, displayedPopoverData[0].xValue, this.parsedUnits[0] && h("span", { class: "unit --x" }, "(", this.parsedUnits[0], ")")), this.showDeltas && this.popoverIndex > 0 && (h("div", { class: "comparison-title" }, lineChartMessages.getChangeSince(this.popoverData[this.popoverIndex - 1][0].xValue))), this.renderPopoverTable()));
+    }
+    renderPopoverTable() {
+        var _a;
+        const displayedPopoverData = this.popoverData[this.popoverIndex];
+        const displayedSpotlightYValue = this.spotlightYValue !== undefined ? this.formatDisplayYValue(this.spotlightYValue) : "";
+        return (h("table", { class: "popover-table" }, this.spotlightXValue === displayedPopoverData[0].xValue && (h("tr", { class: "popover-row" }, h("td", null, h("div", { class: "svg-icon svg-spotlight" })), h("td", { class: "row-label" }, (_a = this.spotlightData) === null || _a === void 0 ? void 0 : _a.label), h("td", { class: "row-value" }, displayedSpotlightYValue, displayedSpotlightYValue !== "" && this.parsedUnits[1] && (h("span", { class: "unit --y" }, this.parsedUnits[1]))))), displayedPopoverData.map((dataPoint, lineIdx) => {
+            if (!this.hiddenLines.includes(lineIdx)) {
+                const { lineLabel, yValue } = dataPoint;
+                const prevDataPoint = this.popoverIndex > 0 ? this.popoverData[this.popoverIndex - 1][lineIdx] : null;
+                const displayYValue = yValue !== null ? this.formatDisplayYValue(yValue) : null;
+                return (h("tr", { class: "popover-row" }, h("td", null, this.renderIcon(lineIdx)), h("td", { class: "row-label" }, lineLabel), h("td", { class: "row-value" }, displayYValue !== null && displayYValue !== void 0 ? displayYValue : lineChartMessages.noData, yValue !== null && this.parsedUnits[1] && h("span", { class: "unit --y" }, this.parsedUnits[1])), this.showDeltas && prevDataPoint && this.renderDeltas(dataPoint, prevDataPoint)));
+            }
+        })));
+    }
+    renderDeltas(dataPoint, prevDataPoint) {
+        const delta = this.calcDelta(dataPoint, prevDataPoint);
+        const deltaColor = delta.toString()[0] == "+" || delta == "-" ? "positive" : delta.toString()[0] == "-" ? "negative" : "";
+        return prevDataPoint && h("td", { class: `delta --${deltaColor}` }, delta);
+    }
+    renderHoverIndicator() {
+        const hasIndicatorData = this.dataPointMatrix.length > 0 && this.dataPointMatrix[0][this.popoverIndex];
+        if (!hasIndicatorData) {
+            return "";
+        }
+        const xPosition = this.dataPointMatrix[0][this.popoverIndex].xPositionPercent;
+        const indicatorStyle = { "--xPosition": xPosition + "%" };
+        return h("div", { class: "hover-indicator", style: indicatorStyle });
+    }
+    renderVerticalGridlines() {
+        var _a;
+        const gridlineSpacing = this.dataPointMatrix[0] && this.displayedXIntervals[1]
+            ? (_a = this.dataPointMatrix[0][this.xIntervals.indexOf(this.displayedXIntervals[1])]) === null || _a === void 0 ? void 0 : _a.xPositionPercent
+            : 0;
+        return (h("div", { class: `vertical-gridlines ${this.hasPartialInterval ? "" : "right-border"} ${!this.showGrid && "axis-only"}`, style: { "--gridlineSpacing": gridlineSpacing + "%" } }));
+    }
+    renderHorizontalGridlines() {
+        const gridlineSpacing = 100 / (this.yIntervals.length - 1);
+        return (h("div", { class: `horizontal-gridlines ${!this.showGrid && "axis-only"}`, style: { "--gridlineSpacing": gridlineSpacing + "%" } }));
+    }
+    renderHighlight() {
+        var _a, _b;
+        if (this.highlightStart) {
+            const startIdx = this.xIntervals.indexOf(this.highlightStart);
+            if (startIdx === -1 || !((_a = this.dataPointMatrix[0]) === null || _a === void 0 ? void 0 : _a[startIdx])) {
+                return null;
+            }
+            const startPercentage = this.dataPointMatrix[0][startIdx].xPositionPercent;
+            const endIdx = this.highlightEnd ? this.xIntervals.indexOf(this.highlightEnd) : -1;
+            const endPercentage = endIdx !== -1 && ((_b = this.dataPointMatrix[0]) === null || _b === void 0 ? void 0 : _b[endIdx]) ? 100 - this.dataPointMatrix[0][endIdx].xPositionPercent : 0;
+            const highlightStyle = { "--startPercentage": startPercentage + "%", "--endPercentage": endPercentage + "%" };
+            return h("div", { class: "highlight", style: highlightStyle });
+        }
+    }
+    render() {
+        return (h(Host, { key: '35db725a92a9ff0a0592550b1d9e60cc89aa1e3d', onBlur: () => this.resetDataPointFocus(), onMouseLeave: () => (this.popoverIndex = -1) }, h("div", { key: '5cd3cc1568e1694ad84569fe6e8c25da633964b2', class: "component-wrapper", role: "application", "aria-roledescription": chartMessages.interactiveChart, "aria-label": this.label, "aria-describedby": "chart-description" }, this.renderLegend(), h("div", { key: 'c1e39c43d3e9ed8c145236b7170cd9fb42c5a133', class: "chart-wrapper" }, h("div", { key: 'e219a208fb12a278821451dcdad527f2a042e970', class: "chart-label --y-axis", style: { "--labelWidth": this.labelWidth } }, this.yAxisLabel, this.parsedUnits[1] && ` (${this.parsedUnits[1]})`), this.renderYIntervals(), h("div", { key: '2e53bce4063a092b5e779f1248a172c59b9e60b6', ref: (el) => (this.plotAreaEl = el), class: "plot-area" }, this.renderVerticalGridlines(), this.renderHorizontalGridlines(), this.renderHighlight(), this.renderData(), this.renderHoverAreas(), this.renderSpotlight()), this.popoverIndex !== -1 && this.renderHoverIndicator(), this.popoverIndex !== -1 && this.renderPopover(), this.renderXIntervals(), h("div", { key: 'a277e88668b605f236950d9c645a87432fff62b9', class: "chart-label --x-axis" }, this.xAxisLabel, this.parsedUnits[0] && ` (${this.parsedUnits[0]})`)), h("div", { key: '17785df43feac141c7b1fb7d3716054d48a90ec1', id: "chart-description", class: "sr-only" }, `${lineChartMessages.instructions} ${this.description}`), h("div", { key: 'c3bdd0bbeaac310fba9dfe990fa0c7f1b3f5cdfa', ref: (el) => (this.liveRegionEl = el), "aria-live": "polite", class: "sr-only" }, this.announcement))));
+    }
+    static get is() { return "wm-line-chart"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-line-chart.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-line-chart.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label for the chart, used as the `aria-label` on the chart\ncontainer. Required for accessibility."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "label",
+                "reflect": false
+            },
+            "description": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible description appended to the keyboard instructions read to screen\nreaders. Recommended \u2014 use it to summarize the key takeaway of the chart."
+                        }, {
+                            "name": "default",
+                            "text": "\"\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "description",
+                "reflect": false,
+                "defaultValue": "\"\""
+            },
+            "xAxisLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Label for the x-axis (the time dimension, e.g. `\"Term\"`, `\"Academic Year\"`).\nRequired for accessibility."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "x-axis-label",
+                "reflect": false
+            },
+            "yAxisLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Label for the y-axis (the measured value, e.g. `\"Enrollment\"`, `\"Score\"`).\nRequired for accessibility."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "y-axis-label",
+                "reflect": false
+            },
+            "showGrid": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, renders horizontal and vertical grid lines."
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }],
+                    "text": ""
+                },
+                "attribute": "show-grid",
+                "reflect": false,
+                "defaultValue": "true"
+            },
+            "lineData": {
+                "type": "string",
+                "mutable": true,
+                "complexType": {
+                    "original": "string | LineChartData",
+                    "resolved": "string | { [lineLabel: string]: Line; }",
+                    "references": {
+                        "LineChartData": {
+                            "location": "import",
+                            "path": "../../../global/interfaces",
+                            "id": "src/global/interfaces.ts::LineChartData"
+                        }
+                    }
+                },
+                "required": true,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Chart data. Each key is a line label (shown in the legend); each value is an\nobject mapping x-axis values (strings) to y-axis values (numbers or `null` for missing\ndata points). Can be set as a JSON string (HTML attribute) or as an object (JavaScript).\nExample: `{ \"Biology\": { \"2022\u201323\": 310, \"2023\u201324\": 420 } }`."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "line-data",
+                "reflect": false
+            },
+            "units": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Two comma-separated unit labels for the x and y axes, shown in parentheses\nafter axis labels and inside popovers. Use `null` for no unit.\nExample: `\"null,students\"` or `\"semester,percent\"`."
+                        }, {
+                            "name": "default",
+                            "text": "\"null,null\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "units",
+                "reflect": false,
+                "defaultValue": "\"null,null\""
+            },
+            "labelWidth": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "CSS width of the y-axis interval label column."
+                        }, {
+                            "name": "default",
+                            "text": "\"120px\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "label-width",
+                "reflect": false,
+                "defaultValue": "\"120px\""
+            },
+            "highlightQualifier": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Screen reader qualifier appended to the `aria-label` of data points that fall\nwithin a highlighted section (e.g. `\"projected\"`)."
+                        }],
+                    "text": ""
+                },
+                "attribute": "highlight-qualifier",
+                "reflect": false,
+                "defaultValue": "lineChartMessages.highlightQualifier"
+            },
+            "highlightStart": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "x-axis value where the highlighted background area begins. If used without\n`highlight-end`, the highlight extends to the right edge of the chart."
+                        }],
+                    "text": ""
+                },
+                "attribute": "highlight-start",
+                "reflect": false
+            },
+            "highlightEnd": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "x-axis value where the highlighted background area ends."
+                        }],
+                    "text": ""
+                },
+                "attribute": "highlight-end",
+                "reflect": false
+            },
+            "visibilityToggles": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, renders hide/show toggle buttons in the legend, allowing users to\nhide individual lines."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "visibility-toggles",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "showDeltas": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, a \"Change since [previous x-value]\" column appears in each data\npoint's popover, showing the percentage change from the preceding data point."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "show-deltas",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "yRange": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Comma-separated numbers that explicitly define the y-axis tick values.\nOverrides automatic range and interval calculation.\nExample: `\"0,100,200,300\"`."
+                        }],
+                    "text": ""
+                },
+                "attribute": "y-range",
+                "reflect": false
+            },
+            "spotlightData": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "SpotlightData",
+                    "resolved": "SpotlightData | undefined",
+                    "references": {
+                        "SpotlightData": {
+                            "location": "import",
+                            "path": "../../../global/interfaces",
+                            "id": "src/global/interfaces.ts::SpotlightData"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Adds a reference data point and a spanning horizontal line across the chart.\nMust include a `label` key and exactly one x-value key mapping to the y-value.\nExample: `{ label: \"Target\", \"2024\u201325\": 500 }`."
+                        }],
+                    "text": ""
+                }
+            },
+            "decimalPlaces": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Number of decimal places for data point values and y-axis interval labels.\nIf omitted, the component infers an appropriate number from the data."
+                        }],
+                    "text": ""
+                },
+                "attribute": "decimal-places",
+                "reflect": false
+            }
+        };
+    }
+    static get states() {
+        return {
+            "parsedLineData": {},
+            "popoverIndex": {},
+            "focusedLine": {},
+            "hiddenLines": {},
+            "isTabbing": {},
+            "announcement": {}
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "lineData",
+                "methodName": "parseData"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "wmUserIsTabbing",
+                "method": "toggleTabbingOn",
+                "target": "window",
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "wmUserIsNotTabbing",
+                "method": "toggleTabbingOff",
+                "target": "window",
+                "capture": false,
+                "passive": false
+            }];
+    }
+}