@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

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

@@ -0,0 +1,549 @@
+import { h, Host } from "@stencil/core";
+import { forceUpdate } from "@stencil/core";
+import { debounce, generateId } from "../../../global/functions";
+import { amountToPercent, exitChart, getDetails, handleChartKeydown, renderStackedBar, renderSimpleBar, renderDoughnut, renderHiddenValuesMessage, renderInstructionsText, renderLegend, allChartsDetails, removeSegmentInfoHighlight, } from "../chartFunctions";
+import { chartMessages } from "../../../global/intl";
+/**
+ * Composition chart component rendering doughnut or stacked bar charts. Composed of a parent
+ * wm-chart element and wm-chart-slice children. Has 3 doughnut subtypes and 5 bar subtypes,
+ * each designed for a specific composition use case.
+ *
+ * **Important:** The bar subtypes (`bar2`–`bar7`) are COMPOSITION patterns — they show parts
+ * of a whole for specific qualitative use cases. They are NOT general-purpose bar charts. For
+ * general comparison or distribution bar charts, use wm-chart-bar or wm-chart-column instead.
+ *
+ * @category Data Visualization
+ *
+ * @keyboardInteraction
+ * - **Tab**: Enters the chart. Subsequent Tab exits the chart.
+ * - **Arrow keys**: Navigate between slices/segments.
+ * - **Enter / Space**: Opens the data popover for the focused segment.
+ * - **Escape**: Closes the popover and returns to the chart container.
+ *
+ * @accessibility
+ * - `label` is required for accessibility — the chart throws if omitted.
+ * - The chart renders with `role="application"` and an `aria-roledescription` of
+ *   "Interactive chart". Each segment is individually focusable with an `aria-label`.
+ * - `print-mode` removes keyboard interaction instructions for printed output.
+ *
+ * @usageNotes
+ * - Slices without an `amount` are not rendered but still occupy a color slot, allowing
+ *   consistent color assignment when some data points are missing.
+ * - The `show-legend` prop controls legend visibility but the legend is always read by screen
+ *   readers regardless of visibility.
+ * - For data-driven bar charts (comparison, distribution), prefer wm-chart-bar or
+ *   wm-chart-column.
+ *
+ * @example {html} Doughnut chart
+ * <wm-chart label="Enrollment by status">
+ *   <wm-chart-slice legend="Enrolled" amount="310"></wm-chart-slice>
+ *   <wm-chart-slice legend="Not enrolled" amount="90"></wm-chart-slice>
+ * </wm-chart>
+ *
+ * @example {react} Doughnut chart
+ * <WmChart label="Enrollment by status">
+ *   <WmChartSlice legend="Enrolled" amount="310" />
+ *   <WmChartSlice legend="Not enrolled" amount="90" />
+ * </WmChart>
+ *
+ * @example {html} Bar composition chart
+ * <wm-chart label="Completion by cohort" chart-type="bar5">
+ *   <wm-chart-slice legend="Completed" amount="200"></wm-chart-slice>
+ *   <wm-chart-slice legend="In progress" amount="75"></wm-chart-slice>
+ *   <wm-chart-slice legend="Not started" amount="25"></wm-chart-slice>
+ * </wm-chart>
+ *
+ * @example {react} Bar composition chart
+ * <WmChart label="Completion by cohort" chartType="bar5">
+ *   <WmChartSlice legend="Completed" amount="200" />
+ *   <WmChartSlice legend="In progress" amount="75" />
+ *   <WmChartSlice legend="Not started" amount="25" />
+ * </WmChart>
+ *
+ */
+export class Chart {
+    constructor() {
+        this.uid = generateId();
+        // @ts-ignore-- TS warns this is unused, but its needed in chartFunctions
+        this.slicesDetails = [];
+        this.debouncedSliceUpdate = debounce(async () => {
+            await getDetails.call(this, this.currentChartType);
+            forceUpdate(this.el);
+        }, 100);
+        this.chartType = "doughnut1";
+        this.label = undefined;
+        this.labelWidth = "150px";
+        this.subinfo = undefined;
+        this.valueFormat = "none";
+        this.showGrid = true;
+        this.showLegend = true;
+        this.showBarLegend = false;
+        this.notStartedColor = false;
+        this.printMode = false;
+        this.printModeFormat = "amount";
+        this.labelPosition = "top";
+        this.isTabbing = false;
+        this.userIsNavigating = false;
+        this.focusedSliceId = undefined;
+    }
+    get popoverEl() {
+        return this.el.shadowRoot.querySelector("priv-chart-popover-old");
+    }
+    get sliceEls() {
+        return Array.from(this.el.shadowRoot.querySelectorAll(".segment"));
+    }
+    get currentChartType() {
+        return this.chartType;
+    }
+    get chartDetails() {
+        return allChartsDetails[this.currentChartType];
+    }
+    get ariaLabelText() {
+        let text = `${this.label}`;
+        if (this.subinfo) {
+            text += ` ${this.subinfo}`;
+        }
+        return text;
+    }
+    get isDoughnut() {
+        return this.chartDetails.category === "doughnut";
+    }
+    get isStackedBar() {
+        return this.chartDetails.category === "stackedBar";
+    }
+    get isSimpleBar() {
+        return this.chartDetails.category === "simpleBar";
+    }
+    get isBar() {
+        return this.isStackedBar || this.isSimpleBar;
+    }
+    toggleTabbingOn() {
+        this.isTabbing = true;
+    }
+    toggleTabbingOff() {
+        this.isTabbing = false;
+    }
+    handleKeydown(ev) {
+        handleChartKeydown.call(this, ev);
+    }
+    showHiddenValuesMessage(showMsg) {
+        const msg = this.el.shadowRoot.querySelector(".hidden-values-warning");
+        if (msg) {
+            showMsg ? msg.classList.remove("hidden") : msg.classList.add("hidden");
+        }
+        else {
+            // if DOM isn't ready, try again later
+            requestAnimationFrame(() => this.showHiddenValuesMessage(showMsg));
+        }
+    }
+    /* LIFECYCLE METHODS + EVENTS FROM THE CHILDREN */
+    async componentWillLoad() {
+        if (!this.label) {
+            throw new Error("For accessibility purposes, you must provide a label for the chart. See https://components.watermarkinsights.com/chart for more information.");
+        }
+        await getDetails.call(this, this.currentChartType);
+        // rerender on resize
+        // unnecessary for doughnuts as layout doesn't change
+        if (!this.isDoughnut) {
+            const resizeObserver = new ResizeObserver(() => {
+                forceUpdate(this.el);
+            });
+            resizeObserver.observe(this.el);
+        }
+    }
+    handleSliceUpdate() {
+        this.debouncedSliceUpdate();
+    }
+    handlePopoverOpenChanged(ev) {
+        const isOpen = ev.detail;
+        if (!isOpen) {
+            const infoEls = Array.from(this.el.shadowRoot.querySelectorAll("[data-segmentindex]"));
+            removeSegmentInfoHighlight(infoEls);
+        }
+    }
+    /* RENDERING */
+    renderBarText(s, minimumWidth) {
+        let val;
+        if (this.valueFormat === "percentage") {
+            if (s.perc === 0 && s.amount > 0) {
+                val = "<1%";
+            }
+            else if (s.perc === 100 && s.amount < this.total) {
+                val = ">99%";
+            }
+            else {
+                val = s.perc + "%";
+            }
+        }
+        else if (this.valueFormat === "amount") {
+            val = s.amount;
+        }
+        const segmentPercentage = amountToPercent(s.amount, this.total, false);
+        const availableWidth = this.el.offsetWidth;
+        const meetsSizeMinimum = (segmentPercentage / 100) * availableWidth >= minimumWidth;
+        const renderedWidth = meetsSizeMinimum || s.amount == 0 ? `${segmentPercentage}%` : `${minimumWidth}px`;
+        // even though we do not display the value text if it has an amount of 0, we still want to render the value-wrapper
+        // in order to not disturb the positioning of the other value texts in the entire row
+        return (h("div", { class: `value-wrapper ${meetsSizeMinimum ? "" : "fixed-width"}`, style: { width: renderedWidth } }, h("span", { class: "value", "data-value": s.amount, "data-segmentindex": s.index }, s.amount > 0 && val)));
+    }
+    drawAxis() {
+        if (this.currentChartType === "bar3") {
+            return (h("svg", { class: "axis" }, h("line", { x1: "0", x2: "100%", y1: "0", y2: "0" }), h("line", { x1: "0", x2: "0", y1: "0", y2: "-85px" }), h("line", { class: "tick", x1: "0.5", x2: "0.5", y1: "0", y2: "6" }), h("line", { class: "tick", x1: "100%", x2: "100%", y1: "0", y2: "6" })));
+        }
+    }
+    renderChart() {
+        if (this.isSimpleBar) {
+            return renderSimpleBar.call(this, this.currentChartType);
+        }
+        else if (this.isStackedBar && this.total > 0) {
+            return renderStackedBar.call(this, this.currentChartType);
+        }
+        else if (this.isDoughnut && this.total > 0) {
+            return renderDoughnut.call(this, this.currentChartType);
+        }
+    }
+    render() {
+        return (h(Host, { key: '2f9eaa51a4e4df6479143666f89af7d18b94eee8', onBlur: () => exitChart.call(this) }, h("div", { key: 'acff58f708754498e34e03b09f3e9189e3c848df', ref: (el) => (this.componentWrapperEl = el), class: `component-wrapper ${this.currentChartType} ${this.isTabbing && !this.userIsNavigating ? "user-is-tabbing" : ""} ${this.labelPosition === "left" && this.currentChartType === "bar4" ? "left-label" : ""}`, role: "application", "aria-label": this.ariaLabelText, tabindex: 0, "aria-roledescription": chartMessages.interactiveChart, "aria-describedby": "chart-instructions" }, h("label", { key: '0513953f6c2505e6d0058cb120601c24c76f226f', id: `label-${this.uid}`, class: `label --${this.labelPosition}`, htmlFor: `graphic-${this.uid}` }, h("span", { key: '96b4fa5af888d033ecc0b416630450d2f314d018', class: "label-text" }, this.label), this.subinfo ? h("span", { class: "subinfo" }, this.subinfo) : ""), this.isBar && renderLegend.call(this, this.currentChartType), this.renderChart(), this.isDoughnut && renderLegend.call(this, this.currentChartType), h("priv-chart-popover-old", { key: '582d8564b33d153e0798287d5801307c2c3b6fdd', class: this.isTabbing ? "user-is-tabbing" : "", onIntChartPopoverOpenChanged: (ev) => this.handlePopoverOpenChanged(ev) }), this.isBar && !this.printMode && renderHiddenValuesMessage()), renderInstructionsText()));
+    }
+    static get is() { return "wm-chart"; }
+    static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-chart.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-chart.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "chartType": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ChartType",
+                    "resolved": "\"bar\" | \"bar2\" | \"bar3\" | \"bar4\" | \"bar5\" | \"bar6\" | \"bar7\" | \"doughnut\" | \"doughnut1\" | \"doughnut2\" | \"doughnut3\"",
+                    "references": {
+                        "ChartType": {
+                            "location": "import",
+                            "path": "../../../global/interfaces",
+                            "id": "src/global/interfaces.ts::ChartType"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Chart subtype. Doughnut subtypes (`doughnut1`\u2013`doughnut3`) and bar composition\nsubtypes (`bar2`\u2013`bar7`) \u2014 each tailored to a specific composition use case."
+                        }, {
+                            "name": "default",
+                            "text": "\"doughnut1\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "chart-type",
+                "reflect": false,
+                "defaultValue": "\"doughnut1\""
+            },
+            "label": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Accessible label for the chart. Required \u2014 the component throws an error if\nomitted. Used as the `aria-label` on the chart container and as the visual chart label."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "label",
+                "reflect": false
+            },
+            "labelWidth": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls the bar label width. Only applies to `bar6` and `bar7` subtypes."
+                        }, {
+                            "name": "default",
+                            "text": "\"150px\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "label-width",
+                "reflect": false,
+                "defaultValue": "\"150px\""
+            },
+            "subinfo": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Optional secondary text displayed beneath the chart label. Not shown when\n`label-position` is `\"none\"`."
+                        }],
+                    "text": ""
+                },
+                "attribute": "subinfo",
+                "reflect": false
+            },
+            "valueFormat": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"percentage\" | \"amount\" | \"none\"",
+                    "resolved": "\"amount\" | \"none\" | \"percentage\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls how individual segment values are displayed on the chart."
+                        }, {
+                            "name": "default",
+                            "text": "\"none\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "value-format",
+                "reflect": false,
+                "defaultValue": "\"none\""
+            },
+            "showGrid": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Show or hide the value grid lines. Only applies to `bar6`."
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }],
+                    "text": ""
+                },
+                "attribute": "show-grid",
+                "reflect": false,
+                "defaultValue": "true"
+            },
+            "showLegend": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Show or hide the legend below the chart. The legend is still read by screen\nreaders regardless of this setting."
+                        }, {
+                            "name": "default",
+                            "text": "true"
+                        }],
+                    "text": ""
+                },
+                "attribute": "show-legend",
+                "reflect": false,
+                "defaultValue": "true"
+            },
+            "showBarLegend": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Show or hide the y-axis bar legend. Only applies to `bar7`."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "show-bar-legend",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "notStartedColor": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, applies a gray color to the first slice to represent a\n\"not started\" state. Only applies to `bar5`."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "not-started-color",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "printMode": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "When true, slice values are included in the legend and keyboard interaction\ninstructions are removed from the DOM \u2014 suitable for printed output."
+                        }, {
+                            "name": "default",
+                            "text": "false"
+                        }],
+                    "text": ""
+                },
+                "attribute": "print-mode",
+                "reflect": false,
+                "defaultValue": "false"
+            },
+            "printModeFormat": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"percentage\" | \"amount\"",
+                    "resolved": "\"amount\" | \"percentage\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Format for legend values when `print-mode` is enabled."
+                        }, {
+                            "name": "default",
+                            "text": "\"amount\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "print-mode-format",
+                "reflect": false,
+                "defaultValue": "\"amount\""
+            },
+            "labelPosition": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "\"left\" | \"top\" | \"none\"",
+                    "resolved": "\"left\" | \"none\" | \"top\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Position of the chart label relative to the chart. When `\"none\"`, no label is\nrendered \u2014 an external label matching `label` must be visually grouped with the chart."
+                        }, {
+                            "name": "default",
+                            "text": "\"top\""
+                        }],
+                    "text": ""
+                },
+                "attribute": "label-position",
+                "reflect": false,
+                "defaultValue": "\"top\""
+            }
+        };
+    }
+    static get states() {
+        return {
+            "isTabbing": {},
+            "userIsNavigating": {},
+            "focusedSliceId": {}
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get listeners() {
+        return [{
+                "name": "wmUserIsTabbing",
+                "method": "toggleTabbingOn",
+                "target": "window",
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "wmUserIsNotTabbing",
+                "method": "toggleTabbingOff",
+                "target": "window",
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "keydown",
+                "method": "handleKeydown",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }, {
+                "name": "wmChartSliceUpdated",
+                "method": "handleSliceUpdate",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }];
+    }
+}