@watermarkinsights/ripple 5.30.0 → 5.31.0-alpha.1

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

@@ -3,6 +3,70 @@ import { chartPalettes, patternKey, } from "../../../global/interfaces";
 import { suffixNumber, renderInstructionsText, findLargestNiceInterval, getMaxTicks, findNiceRoundNumber, formatDisplayValue, groupProcessedData, computeLegendData, sortGroupedData, inferDecimalPlacesForUnitValue, } from "../chartFunctions";
 import { chartMessages } from "../../../global/intl";
 import { isElOrChild, debounce } from "../../../global/functions";
+/**
+ * Renders a vertical column chart for comparing values across nominal categories or showing
+ * distribution across interval/ratio ranges. Data and configuration are set via JavaScript
+ * properties (`chart.config` and `chart.data`) — not HTML attributes. Supports single-color,
+ * discrete palette, semantic palette, and grouped columns.
+ *
+ * **Preferred** over wm-chart's bar subtypes for comparison and distribution use cases.
+ * Use this component (or wm-chart-bar) instead of `<wm-chart chart-type="bar*">`. When
+ * columns exceed available width, the chart scrolls horizontally.
+ *
+ * @keyboardInteraction
+ * - **Tab**: Enters the chart wrapper.
+ * - **Arrow Down / Right**: Focuses the first column; subsequent presses cycle to the next.
+ * - **Arrow Up / Left**: Cycles to the previous column.
+ * - **Enter**: Activates the popover button when the popover is open.
+ * - **Escape**: Closes the open popover.
+ * - **Tab** (from within): Exits the chart and clears focus.
+ *
+ * @accessibility
+ * - `config.label` is required — used as the chart's `aria-label`.
+ * - Each column receives an `aria-label` composed of the category axis label, group name (if
+ *   grouped), bar legend, and display value.
+ * - The chart renders with `role="application"` and `aria-roledescription="Interactive chart"`.
+ * - In `print-mode`, keyboard interaction instructions are removed from the DOM.
+ *
+ * @usageNotes
+ * - Set `id` on the element to use with an external `wm-chart-legend` via `chart-ids`.
+ * - Use `print-width` to fix chart width for exported PDFs or print stylesheets (accepts `px`,
+ *   `in`, or `cm`). The chart will wrap columns across multiple plots when they exceed the
+ *   available `print-width`.
+ * - For grouped charts, each `ChartData` item must include a `groupName` field.
+ *
+ * @example {html} Single-color column chart
+ * <wm-chart-column id="enrollment-chart"></wm-chart-column>
+ * <script>
+ *   const chart = document.querySelector('#enrollment-chart');
+ *   chart.config = { label: 'Enrollment by term', gridMax: 'auto', valueFormat: 'amount',
+ *     categoryAxisLabel: 'Term', valueAxisLabel: 'Students' };
+ *   chart.data = [{ barLegend: 'Fall 2023', amount: 310 }, { barLegend: 'Spring 2024', amount: 280 }];
+ * </script>
+ *
+ * @example {react} Single-color column chart
+ * <WmChartColumn ref={chartRef} />
+ * // In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+ *
+ * @example {html} Grouped column chart
+ * <wm-chart-column id="grouped-chart"></wm-chart-column>
+ * <script>
+ *   const chart = document.querySelector('#grouped-chart');
+ *   chart.config = { label: 'Enrollment by term and program', gridMax: 'auto',
+ *     showLegend: 'bottom' };
+ *   chart.data = [
+ *     { barLegend: 'Biology', amount: 120, groupName: 'Fall 2023' },
+ *     { barLegend: 'English', amount: 95, groupName: 'Fall 2023' },
+ *   ];
+ * </script>
+ *
+ * @example {react} Grouped column chart
+ * <WmChartColumn ref={chartRef} />
+ * // In useEffect: chartRef.current.config = {...}; chartRef.current.data = [...];
+ *
+ * @category Data Visualization
+ * @displayName Column Chart
+ */
 export class ChartColumn {
     constructor() {
         this.gridMax = 0;
@@ -604,7 +668,7 @@ export class ChartColumn {
     // #endregion rendering
     render() {
         var _a, _b, _c, _d, _e, _f;
-        return (h(Host, { key: 'affae5b48baddd602d0b7a3e52dac3adbc935b4c' }, h("div", { key: 'ff850beabb9e006382b815679306826db3f7a72a', class: "popover-wrapper" }, h("priv-chart-popover", { key: 'cd5baae81ffc528fd522bcce99c3d77102dd77fd', ref: (el) => (this.popoverEl = el), onIntChartPopoverToggled: (ev) => this.handlePopoverToggled(ev) })), h("div", { key: '458977566490ece052ae601d6c567c0a55c194fe', ref: (el) => (this.componentWrapperEl = el), class: `component-wrapper ${((_a = this.printMode) !== null && _a !== void 0 ? _a : (_b = this.config) === null || _b === void 0 ? void 0 : _b.printMode) ? "print-mode" : ""}`, style: this.isPlotWidthLimited ? { "--forced-width": `${this.printWidthPx}px` } : undefined, tabindex: "0", role: "application", onKeyDown: (ev) => this.handleChartKeyDown(ev), onBlur: (ev) => this.handleComponentBlur(ev), "aria-roledescription": chartMessages.interactiveChart, "aria-describedby": "chart-instructions", "aria-label": (_c = this.config) === null || _c === void 0 ? void 0 : _c.label }, ((_e = (_d = this.config) === null || _d === void 0 ? void 0 : _d.showLabel) !== null && _e !== void 0 ? _e : true) && (h("label", { key: 'e29c77421f36511d78823c09c915025dd365db41', id: "label", class: "label" }, h("span", { key: 'f6ce8537edf910e0d88fbe97e24e38ae6b8f7f0e', class: "label-text" }, (_f = this.config) === null || _f === void 0 ? void 0 : _f.label), this.subinfoText ? h("span", { class: "subinfo" }, this.subinfoText) : "")), this.showLegend === "top" && this.renderLegend("horizontal"), h("div", { key: '2656655cdcae22b906c3129c1a9d6de52263015b', class: "chart-wrapper" }, h("div", { key: 'd141e1d15be6d548c065e7e1872f6b8482d63f19', class: "chart-left-side" }, this.showLegend === "left" && this.renderLegend("vertical")), this.data && this.renderPlotContainers(), h("div", { key: '6e28c0075fc0359dc29a2c275789f57ee7698da7', class: "chart-right-side" }, this.showLegend === "right" && this.renderLegend("vertical"))), this.showLegend === "bottom" && this.renderLegend("horizontal"), renderInstructionsText())));
+        return (h(Host, { key: 'b51ad062997d2af1ef9aa4cc77e69b00417052cc' }, h("div", { key: 'e69ca509ec69daf49c384a013cb65929a468dc8b', class: "popover-wrapper" }, h("priv-chart-popover", { key: '335e7e4681ce4227e03a83ddd4dd2c1a599fd9b0', ref: (el) => (this.popoverEl = el), onIntChartPopoverToggled: (ev) => this.handlePopoverToggled(ev) })), h("div", { key: '2198b8cdb1b1293c4dfb8a18673ec1f941ab252d', ref: (el) => (this.componentWrapperEl = el), class: `component-wrapper ${((_a = this.printMode) !== null && _a !== void 0 ? _a : (_b = this.config) === null || _b === void 0 ? void 0 : _b.printMode) ? "print-mode" : ""}`, style: this.isPlotWidthLimited ? { "--forced-width": `${this.printWidthPx}px` } : undefined, tabindex: "0", role: "application", onKeyDown: (ev) => this.handleChartKeyDown(ev), onBlur: (ev) => this.handleComponentBlur(ev), "aria-roledescription": chartMessages.interactiveChart, "aria-describedby": "chart-instructions", "aria-label": (_c = this.config) === null || _c === void 0 ? void 0 : _c.label }, ((_e = (_d = this.config) === null || _d === void 0 ? void 0 : _d.showLabel) !== null && _e !== void 0 ? _e : true) && (h("label", { key: '6a31a705fc24b21eb74df46a440c4e5a70c9d4f4', id: "label", class: "label" }, h("span", { key: 'c4b0ab318e570dcc7dfeaab05e4f4e00329de72c', class: "label-text" }, (_f = this.config) === null || _f === void 0 ? void 0 : _f.label), this.subinfoText ? h("span", { class: "subinfo" }, this.subinfoText) : "")), this.showLegend === "top" && this.renderLegend("horizontal"), h("div", { key: 'e1542b6b9f1e157f1a6e0a02c01a9b66d3954952', class: "chart-wrapper" }, h("div", { key: 'dd07a9a03778b3d3665d553e4b581766efbb117d', class: "chart-left-side" }, this.showLegend === "left" && this.renderLegend("vertical")), this.data && this.renderPlotContainers(), h("div", { key: '959c73972b14fb2e31a0273364983a61d89405ed', class: "chart-right-side" }, this.showLegend === "right" && this.renderLegend("vertical"))), this.showLegend === "bottom" && this.renderLegend("horizontal"), renderInstructionsText())));
     }
     static get is() { return "wm-chart-column"; }
     static get encapsulation() { return "shadow"; }
@@ -638,7 +702,10 @@ export class ChartColumn {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Chart configuration object. Set via JavaScript property \u2014 not an HTML\nattribute. See the `ChartConfig` interface for the full list of options (label, gridMax,\nvalueFormat, colors, showLegend, etc.)."
+                        }],
                     "text": ""
                 }
             },
@@ -659,7 +726,10 @@ export class ChartColumn {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Array of data items to render. Set via JavaScript property \u2014 not an HTML\nattribute. Each item must include at least `barLegend` and `amount`; grouped charts also\nrequire `groupName`. See the `ChartData` interface."
+                        }],
                     "text": ""
                 }
             },
@@ -674,7 +744,10 @@ export class ChartColumn {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fixed chart width for print or PDF export. Accepts `px`, `in`, or `cm` (e.g.\n`\"7.5in\"`). When set alongside `print-mode` or during `window.print()`, columns that\nexceed the available width wrap across multiple plot rows."
+                        }],
                     "text": ""
                 },
                 "attribute": "print-width",
@@ -691,7 +764,13 @@ export class ChartColumn {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, column values are included in the legend and keyboard interaction\ninstructions are removed from the DOM \u2014 suitable for printed output. Takes precedence over\n`config.printMode`."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "print-mode",
@@ -708,7 +787,13 @@ export class ChartColumn {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, applies a hatching pattern fill to columns in addition to color,\nimproving distinguishability for users with color vision deficiencies. Takes precedence\nover `config.patternMode`."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "pattern-mode",
@@ -725,7 +810,10 @@ export class ChartColumn {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Optional secondary text displayed beneath the chart label. Takes precedence\nover `config.subinfo`."
+                        }],
                     "text": ""
                 },
                 "attribute": "subinfo",
@@ -748,7 +836,13 @@ export class ChartColumn {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal signal used to synchronize column highlight state with an external\nwm-chart-legend \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "complexType": {

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

@@ -1,5 +1,45 @@
 import { h, Host } from "@stencil/core";
 import { patternKey } from "../../../global/interfaces";
+/**
+ * External legend component for wm-chart-bar and wm-chart-column. Retrieves color and label
+ * data from one or more charts via element IDs, allowing a single legend to serve multiple
+ * charts. Hidden from screen readers — relevant data is announced when the user interacts with
+ * the associated chart directly.
+ *
+ * For simple single-chart scenarios, the `config.showLegend` option on wm-chart-bar or
+ * wm-chart-column renders an internal legend without requiring this element. Use
+ * wm-chart-legend when sharing one legend across multiple charts or when external placement
+ * is required.
+ *
+ * @usageNotes
+ * - Assign an `id` to each chart and pass those IDs (space-separated) to `chart-ids`.
+ * - Clicking or hovering a legend item highlights the corresponding bar(s) in all associated
+ *   charts.
+ *
+ * @example {html} Shared legend for two charts
+ * <wm-chart-legend chart-ids="chart-a chart-b"></wm-chart-legend>
+ * <wm-chart-bar id="chart-a"></wm-chart-bar>
+ * <wm-chart-bar id="chart-b"></wm-chart-bar>
+ *
+ * @example {react} Shared legend for two charts
+ * const [activeIdx, setActiveIdx] = useState(null);
+ *
+ * const handleClick = (event) => {
+ *   setActiveIdx(event.detail.idx);
+ * };
+ *
+ * <WmChartLegend chartIds="chart-a chart-b" onWmLegendItemClick={handleClick} />
+ * <WmChartBar id="chart-a" />
+ * <WmChartBar id="chart-b" />
+ *
+ * @example {html} Vertical orientation
+ * <wm-chart-legend chart-ids="my-chart" orientation="vertical"></wm-chart-legend>
+ *
+ * @example {react} Vertical orientation
+ * <WmChartLegend chartIds="my-chart" orientation="vertical" />
+ *
+ * @category Data Visualization
+ */
 export class ChartLegend {
     constructor() {
         this.persistentHighlightIdx = -1;
@@ -57,7 +97,7 @@ export class ChartLegend {
         return this.processedData.map((item, idx) => (h("div", { class: "legend-item", key: item.barLegend, onClick: () => this.handleLegendItemClick(idx), onMouseEnter: () => this.handleLegendItemMouseEnter(idx), onMouseLeave: () => this.handleLegendItemMouseLeave() }, h("div", { class: this.getSwatchClassMap(item), style: { "--color": `var(--${item.color})` } }), h("div", { class: "label" }, item.barLegend), item.printValue && h("span", { class: `print-value` }, "(", item.printValue, ")"))));
     }
     render() {
-        return (h(Host, { key: '1ba232432e51488144a4320c075db67690e5990b' }, h("div", { key: '088cd589e2cd04d168e59bc74b963326fd4fbeff', class: `legend-container --${this.orientation} ${this.printMode ? "print-mode" : ""}`, "aria-hidden": "true" }, this.renderLegendItems())));
+        return (h(Host, { key: '96690631fc06cb059813cf67adfb96a87a89ea03' }, h("div", { key: '68afe8f3ed1452d9e031ba8d0c2dbcbe6d57af78', class: `legend-container --${this.orientation} ${this.printMode ? "print-mode" : ""}`, "aria-hidden": "true" }, this.renderLegendItems())));
     }
     static get is() { return "wm-chart-legend"; }
     static get encapsulation() { return "shadow"; }
@@ -85,7 +125,13 @@ export class ChartLegend {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Space-separated list of element IDs of the wm-chart-bar or wm-chart-column\nelements this legend serves. The legend derives its color swatches and labels from these\ncharts automatically."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
                     "text": ""
                 },
                 "attribute": "chart-ids",
@@ -103,7 +149,13 @@ export class ChartLegend {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Layout orientation of legend items."
+                        }, {
+                            "name": "default",
+                            "text": "\"horizontal\""
+                        }],
                     "text": ""
                 },
                 "attribute": "orientation",
@@ -127,7 +179,13 @@ export class ChartLegend {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Processed chart data injected by the associated chart \u2014 not for application\nuse."
+                        }],
                     "text": ""
                 },
                 "defaultValue": "[]"
@@ -143,7 +201,13 @@ export class ChartLegend {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, the print value for each item is shown next to its swatch in the\nlegend \u2014 suitable for printed output."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
                     "text": ""
                 },
                 "attribute": "print-mode",
@@ -161,7 +225,13 @@ export class ChartLegend {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Pattern orientation injected by the associated chart to align swatch hatching\nwith bar orientation \u2014 not for application use."
+                        }],
                     "text": ""
                 },
                 "attribute": "pattern-mode",
@@ -177,7 +247,13 @@ export class ChartLegend {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user clicks a legend item. The associated chart highlights\nthe corresponding bar(s) and fades all others."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ idx: number }} idx \u2014 zero-based index of the clicked legend item, or\n`-1` to clear all highlights."
+                        }],
                     "text": ""
                 },
                 "complexType": {
@@ -192,7 +268,13 @@ export class ChartLegend {
                 "cancelable": true,
                 "composed": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires when the user hovers over a legend item. The associated chart\nhighlights the corresponding bar(s) and fades all others."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "{{ idx: number }} idx \u2014 zero-based index of the hovered legend item, or\n`-1` to clear all highlights."
+                        }],
                     "text": ""
                 },
                 "complexType": {

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

@@ -2,6 +2,64 @@ 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.
+ *
+ * @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 } }} />
+ *
+ * @category Data Visualization
+ */
 export class LineChart {
     constructor() {
         this.minTickWidth = 120;
@@ -520,7 +578,7 @@ export class LineChart {
         }
     }
     render() {
-        return (h(Host, { key: 'f8b9655526316c31766755e4f6d6d1bebf74ca24', onBlur: () => this.resetDataPointFocus(), onMouseLeave: () => (this.popoverIndex = -1) }, h("div", { key: 'e40a5a2be1ccdd02a1cc5bcaf160036de51d6ad2', class: "component-wrapper", role: "application", "aria-roledescription": chartMessages.interactiveChart, "aria-label": this.label, "aria-describedby": "chart-description" }, this.renderLegend(), h("div", { key: '93693d92797316a4b710099eb39a51477f83c289', class: "chart-wrapper" }, h("div", { key: '6b4b0286e86e5503354485e4da88f07555bc3a5a', class: "chart-label --y-axis", style: { "--labelWidth": this.labelWidth } }, this.yAxisLabel, this.parsedUnits[1] && ` (${this.parsedUnits[1]})`), this.renderYIntervals(), h("div", { key: '1c671ac79a8b3cc7cb6f70e8f3ed4c47ee36e0e2', 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: 'e2eb5d6934c9fbee7c6bebeedc7c67d3d896913b', class: "chart-label --x-axis" }, this.xAxisLabel, this.parsedUnits[0] && ` (${this.parsedUnits[0]})`)), h("div", { key: 'bfd19cab50f877f2bb141c62427e28dfc4d5b338', id: "chart-description", class: "sr-only" }, `${lineChartMessages.instructions} ${this.description}`), h("div", { key: 'bfd9e9ea8c8add713554e587b0a1fff5fabef4f9', ref: (el) => (this.liveRegionEl = el), "aria-live": "polite", class: "sr-only" }, this.announcement))));
+        return (h(Host, { key: 'acf06c018fdcc2a4fadca621ff30c4e751ca421a', onBlur: () => this.resetDataPointFocus(), onMouseLeave: () => (this.popoverIndex = -1) }, h("div", { key: '0875c154402f16ab666b0ce0d1f94bf64c9a8c9e', class: "component-wrapper", role: "application", "aria-roledescription": chartMessages.interactiveChart, "aria-label": this.label, "aria-describedby": "chart-description" }, this.renderLegend(), h("div", { key: 'ec7a7af542b83ed0a44a2321df1fbd63daa44de3', class: "chart-wrapper" }, h("div", { key: 'e3c0be9867090427e6f22400d89dfe70c6e37b03', class: "chart-label --y-axis", style: { "--labelWidth": this.labelWidth } }, this.yAxisLabel, this.parsedUnits[1] && ` (${this.parsedUnits[1]})`), this.renderYIntervals(), h("div", { key: 'e2b044e94333e2cfdb18755242422d860c21d475', 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: '50f05b93e40f6c04dcd3cb5aaebc3301f0f293b1', class: "chart-label --x-axis" }, this.xAxisLabel, this.parsedUnits[0] && ` (${this.parsedUnits[0]})`)), h("div", { key: '8003e1ab7e144fa78dfa01c3df54d72f50fb1426', id: "chart-description", class: "sr-only" }, `${lineChartMessages.instructions} ${this.description}`), h("div", { key: '27c5dd41e90238f22ba5987be52d274a2c6286a2', 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"; }
@@ -547,7 +605,13 @@ export class LineChart {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -564,7 +628,13 @@ export class LineChart {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -582,7 +652,13 @@ export class LineChart {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -599,7 +675,13 @@ export class LineChart {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -616,7 +698,13 @@ export class LineChart {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, renders horizontal and vertical grid lines."
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }],
                     "text": ""
                 },
                 "attribute": "show-grid",
@@ -640,7 +728,13 @@ export class LineChart {
                 "required": true,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -657,7 +751,13 @@ export class LineChart {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -675,7 +775,13 @@ export class LineChart {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "CSS width of the y-axis interval label column."
+                        }, {
+                            "name": "default",
+                            "text": "\"120px\""
+                        }],
                     "text": ""
                 },
                 "attribute": "label-width",
@@ -693,7 +799,10 @@ export class LineChart {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -711,7 +820,10 @@ export class LineChart {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -728,7 +840,10 @@ export class LineChart {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "tags": [{
+                            "name": "description",
+                            "text": "x-axis value where the highlighted background area ends."
+                        }],
                     "text": ""
                 },
                 "attribute": "highlight-end",
@@ -745,7 +860,13 @@ export class LineChart {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -763,7 +884,13 @@ export class LineChart {
                 "required": false,
                 "optional": false,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -781,7 +908,10 @@ export class LineChart {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "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",
@@ -804,7 +934,10 @@ export class LineChart {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "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": ""
                 }
             },
@@ -819,7 +952,10 @@ export class LineChart {
                 "required": false,
                 "optional": true,
                 "docs": {
-                    "tags": [],
+                    "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",