@watermarkinsights/ripple 0.0.1 → 0.1.0-alpha.1

package/dist/collection/components/charts/wm-progress-monitor/wm-progress-monitor.js

@@ -0,0 +1,232 @@
+import { h, Host, forceUpdate } from "@stencil/core";
+import { csvToArray, debounce } from "../../../global/functions";
+import { renderLegendItem, allChartsDetails } from "../chartFunctions";
+/**
+ * Container for one or more wm-progress-indicator elements, each showing binary completion
+ * progress (e.g. "Completed" vs "Not Completed"). Above the layout breakpoint, indicators
+ * render as doughnuts in a horizontal row; below it, they collapse into horizontal bars in a
+ * vertical stack.
+ *
+ * **Strict constraints:**
+ * 1. Each wm-progress-indicator must have EXACTLY TWO wm-progress-slice children — one for
+ *    the "complete" state and one for the "incomplete" state.
+ * 2. This component is ONLY suitable for binary completion tracking. For more than two states,
+ *    general comparisons, composition breakdowns, or distributions, use wm-chart,
+ *    wm-chart-bar, or wm-chart-column.
+ *
+ * @category Data Visualization
+ *
+ * @usageNotes
+ * - The `wmProgressMonitorModeChange` event fires once on load and again whenever the layout
+ *   switches between `"doughnut"` and `"bar"`. Listen to it to synchronize any external UI
+ *   that depends on the current layout mode.
+ * - `group-legend` is only shown in bar mode. Provide two comma-separated keys in
+ *   complete/incomplete order (e.g. `"Completed,Not Completed"`). Keys cannot contain commas.
+ *
+ * @example {html} Progress monitor
+ * <wm-progress-monitor group-legend="Completed,Not Completed">
+ *   <wm-progress-indicator label="Biology">
+ *     <wm-progress-slice legend="Completed" amount="200"
+ *       popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+ *     <wm-progress-slice legend="Not Completed" amount="100"
+ *       popover-title="100 students" popover-text="Have not completed all requirements"></wm-progress-slice>
+ *   </wm-progress-indicator>
+ * </wm-progress-monitor>
+ *
+ * @example {react} Progress monitor
+ * // wmProgressMonitorModeChange fires on load and whenever the layout switches.
+ * // event.detail is "doughnut" | "bar".
+ * const [layoutMode, setLayoutMode] = useState("");
+ *
+ * <WmProgressMonitor
+ *   groupLegend="Completed,Not Completed"
+ *   onWmProgressMonitorModeChange={(e) => setLayoutMode(e.detail)}
+ * >
+ *   <WmProgressIndicator label="Biology">
+ *     <WmProgressSlice legend="Completed" amount="200"
+ *       popoverTitle="200 students" popoverText="Completed all requirements" />
+ *     <WmProgressSlice legend="Not Completed" amount="100"
+ *       popoverTitle="100 students" popoverText="Have not completed all requirements" />
+ *   </WmProgressIndicator>
+ *   <WmProgressIndicator label="English">
+ *     <WmProgressSlice legend="Completed" amount="160"
+ *       popoverTitle="160 students" popoverText="Completed all requirements" />
+ *     <WmProgressSlice legend="Not Completed" amount="40"
+ *       popoverTitle="40 students" popoverText="Have not completed all requirements" />
+ *   </WmProgressIndicator>
+ * </WmProgressMonitor>
+ *
+ * @example {html} Custom breakpoint
+ * <wm-progress-monitor breakpoint="600px" group-legend="Done,Pending">
+ *   <!-- indicators -->
+ * </wm-progress-monitor>
+ *
+ * @example {react} Custom breakpoint
+ * <WmProgressMonitor breakpoint="600px" groupLegend="Done,Pending">
+ *   {/* indicators *\/}
+ * </WmProgressMonitor>
+ *
+ */
+export class ProgressMonitor {
+    constructor() {
+        this.doughnutWidth = 300;
+        this.modeInitialized = false;
+        this.debouncedUpdate = debounce(() => forceUpdate(this.el), 50);
+        this.breakpoint = undefined;
+        this.groupLegend = undefined;
+        this.barLabelsWidth = undefined;
+    }
+    get parsedBreakpoint() {
+        const asNumber = this.parseToNum(this.breakpoint || this.el.children.length);
+        // if number < 20, it is treated as width in terms of # of indicators. Otherwise it is a pixel value
+        // e.g. 4 -> 1200px, while 768 -> 768 px
+        const asPixels = asNumber >= 20 ? asNumber : asNumber * this.doughnutWidth;
+        return asPixels;
+    }
+    get mode() {
+        return this.el.clientWidth > this.parsedBreakpoint ? "doughnut" : "bar";
+    }
+    // here "doughnut" or "bar" refer to wm-chart, so wm-progress-monitor should answer false
+    // use this.mode to know the responsive state of the component 
+    get isBar() {
+        return false;
+    }
+    get isDoughnut() {
+        return false;
+    }
+    componentWillLoad() {
+        // rerender on resize in case layout needs to change
+        const resizeObserver = new ResizeObserver(() => this.debouncedUpdate());
+        resizeObserver.observe(this.el);
+    }
+    componentDidLoad() {
+        // emit initial mode for Indicators, must happen post-load as this.el measurement is needed
+        this.wmProgressMonitorModeChange.emit(this.mode);
+        this.modeInitialized = true;
+    }
+    componentWillUpdate() {
+        // store prevMode before every render except first to determine when it has changed
+        if (this.prevMode !== this.mode) {
+            this.wmProgressMonitorModeChange.emit(this.mode);
+        }
+        this.prevMode = this.mode;
+    }
+    parseToNum(num) {
+        const asString = num.toString();
+        const withoutPx = asString.replace("px", "");
+        return parseInt(withoutPx);
+    }
+    renderLegend() {
+        const keys = csvToArray(this.groupLegend);
+        const colors = allChartsDetails.bar.colors;
+        return (h("div", { class: "legend-wrapper" }, h("div", { class: "legend" }, keys.map((key, idx) => {
+            const legendItem = { key: key, color: colors[idx] };
+            return renderLegendItem.call(this, legendItem);
+        }))));
+    }
+    render() {
+        return (h(Host, { key: 'f62ecf8673b827d303c153102b6fe6f65887bf17', class: this.mode === "doughnut" ? "row" : "column" }, this.modeInitialized && this.groupLegend && this.mode === "bar" && this.renderLegend(), this.modeInitialized && h("slot", { key: '0159b365ecb9fed2a978a26bf8f5e5b276f73186' })));
+    }
+    static get is() { return "wm-progress-monitor"; }
+    static get encapsulation() { return "shadow"; }
+    static get delegatesFocus() { return true; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["wm-progress-monitor.scss"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["wm-progress-monitor.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "breakpoint": {
+                "type": "any",
+                "mutable": false,
+                "complexType": {
+                    "original": "number | string",
+                    "resolved": "number | string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Controls when indicators switch between doughnut (horizontal row) and bar\n(vertical stack) layouts. Accepts a unit-less number (minimum number of indicators to\nshow side-by-side \u2014 e.g. `4` \u2192 1200 px) or an exact pixel value (e.g. `\"900px\"`).\nDefaults to the sum of all indicator widths \u2014 the component tries to fit all on one row\nand collapses to bars when it cannot."
+                        }],
+                    "text": ""
+                },
+                "attribute": "breakpoint",
+                "reflect": false
+            },
+            "groupLegend": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Two comma-separated legend keys in complete/incomplete order, displayed only\nin bar layout mode (e.g. `\"Completed,Not Completed\"`). Keys cannot contain commas."
+                        }],
+                    "text": ""
+                },
+                "attribute": "group-legend",
+                "reflect": false
+            },
+            "barLabelsWidth": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "CSS width of the indicator labels when in bar layout mode (e.g. `\"180px\"`)."
+                        }],
+                    "text": ""
+                },
+                "attribute": "bar-labels-width",
+                "reflect": false
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmProgressMonitorModeChange",
+                "name": "wmProgressMonitorModeChange",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Fires once on load and again whenever the layout switches between `\"doughnut\"`\nand `\"bar\"` modes. Use this to synchronize external UI that depends on the current layout."
+                        }, {
+                            "name": "eventDetails",
+                            "text": "`\"doughnut\" | \"bar\"` \u2014 the new layout mode."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "any",
+                    "resolved": "any",
+                    "references": {}
+                }
+            }];
+    }
+    static get elementRef() { return "el"; }
+}

package/dist/collection/components/charts/wm-progress-monitor/wm-progress-slice.js

@@ -0,0 +1,167 @@
+/**
+ * Data slice for a wm-progress-indicator. Represents one state (complete or incomplete) in
+ * a binary progress chart. Always used as a direct child of wm-progress-indicator.
+ *
+ * Each wm-progress-indicator must contain EXACTLY TWO wm-progress-slice elements.
+ *
+ * @usageNotes
+ * - The first slice is treated as the "complete" state and the second as the "incomplete"
+ *   state for color and layout purposes.
+ * - Use `popover-title`, `popover-text`, and `popover-button-text` to surface additional
+ *   context when the segment is focused or clicked.
+ *
+ * @example {html} Complete/incomplete pair
+ * <wm-progress-slice legend="Completed" amount="200"
+ *   popover-title="200 students" popover-text="Completed all requirements"></wm-progress-slice>
+ * <wm-progress-slice legend="Not Completed" amount="100"></wm-progress-slice>
+ *
+ * @example {react} Complete/incomplete pair
+ * <WmProgressSlice legend="Completed" amount="200"
+ *   popoverTitle="200 students" popoverText="Completed all requirements" />
+ * <WmProgressSlice legend="Not Completed" amount="100" />
+ */
+export class ProgressSlice {
+    constructor() {
+        this.legend = undefined;
+        this.amount = undefined;
+        this.popoverTitle = undefined;
+        this.popoverText = undefined;
+        this.popoverButtonText = undefined;
+    }
+    componentDidUpdate() {
+        this.wmProgressSliceUpdated.emit();
+    }
+    static get is() { return "wm-progress-slice"; }
+    static get encapsulation() { return "shadow"; }
+    static get properties() {
+        return {
+            "legend": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Label for this slice in the legend and popovers."
+                        }, {
+                            "name": "required",
+                            "text": undefined
+                        }],
+                    "text": ""
+                },
+                "attribute": "legend",
+                "reflect": false
+            },
+            "amount": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Numeric value for this slice as a string."
+                        }],
+                    "text": ""
+                },
+                "attribute": "amount",
+                "reflect": false
+            },
+            "popoverTitle": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Title text shown in the data popover when this segment is focused or clicked."
+                        }],
+                    "text": ""
+                },
+                "attribute": "popover-title",
+                "reflect": false
+            },
+            "popoverText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Body text shown in the data popover when this segment is focused or clicked."
+                        }],
+                    "text": ""
+                },
+                "attribute": "popover-text",
+                "reflect": false
+            },
+            "popoverButtonText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "description",
+                            "text": "Label for the action button in the data popover. When set, fires\n`wmProgressIndicatorButtonTriggered` when clicked."
+                        }],
+                    "text": ""
+                },
+                "attribute": "popover-button-text",
+                "reflect": false
+            }
+        };
+    }
+    static get events() {
+        return [{
+                "method": "wmProgressSliceUpdated",
+                "name": "wmProgressSliceUpdated",
+                "bubbles": true,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [{
+                            "name": "internal",
+                            "text": undefined
+                        }, {
+                            "name": "description",
+                            "text": "Internal signal notifying the parent wm-progress-indicator to re-read slice\ndata after a prop update \u2014 not for application use."
+                        }],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }];
+    }
+}