@schukai/monster 4.10.4 → 4.11.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 
 
+## [4.11.0] - 2025-05-20
+
+### Add Features
+
+- Add new metric control components and associated styling
+
+
+
 ## [4.10.4] - 2025-05-20
 
 ### Bug Fixes

package/package.json

@@ -1 +1 @@
-{"author":"schukai GmbH","dependencies":{"@floating-ui/dom":"^1.7.0","@popperjs/core":"^2.11.8"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"type":"module","version":"4.10.4"}
+{"author":"schukai GmbH","dependencies":{"@floating-ui/dom":"^1.7.0","@popperjs/core":"^2.11.8"},"description":"Monster is a simple library for creating fast, robust and lightweight websites.","homepage":"https://monsterjs.org/","keywords":["framework","web","dom","css","sass","mobile-first","app","front-end","templates","schukai","core","shopcloud","alvine","monster","buildmap","stack","observer","observable","uuid","node","nodelist","css-in-js","logger","log","theme"],"license":"AGPL 3.0","main":"source/monster.mjs","module":"source/monster.mjs","name":"@schukai/monster","repository":{"type":"git","url":"https://gitlab.schukai.com/oss/libraries/javascript/monster.git"},"type":"module","version":"4.11.0"}

package/source/components/data/metric-graph.mjs

@@ -0,0 +1,475 @@
+/**
+ * Copyright © schukai GmbH and all contributing authors, {{copyRightYear}}. All rights reserved.
+ * Node module: @schukai/monster
+ *
+ * This source code is licensed under the GNU Affero General Public License version 3 (AGPLv3).
+ * The full text of the license can be found at: https://www.gnu.org/licenses/agpl-3.0.en.html
+ *
+ * For those who do not wish to adhere to the AGPLv3, a commercial license is available.
+ * Acquiring a commercial license allows you to use this software without complying with the AGPLv3 terms.
+ * For more information about purchasing a commercial license, please contact schukai GmbH.
+ */
+
+import {instanceSymbol} from "../../constants.mjs";
+import {addAttributeToken} from "../../dom/attributes.mjs";
+import {
+    ATTRIBUTE_ERRORMESSAGE,
+    ATTRIBUTE_ROLE,
+} from "../../dom/constants.mjs";
+import {CustomElement, updaterTransformerMethodsSymbol} from "../../dom/customelement.mjs";
+import {
+    assembleMethodSymbol,
+    registerCustomElement,
+} from "../../dom/customelement.mjs";
+import {findTargetElementFromEvent} from "../../dom/events.mjs";
+import {isFunction, isString} from "../../types/is.mjs";
+import {MetricGraphStyleSheet} from "./stylesheet/metric-graph.mjs";
+import {fireCustomEvent} from "../../dom/events.mjs";
+
+
+export {MetricGraph};
+
+/**
+ * @private
+ * @type {symbol}
+ */
+export const metricGraphControlElementSymbol = Symbol("metricGraphControlElement");
+
+/**
+ * A MetricGraph
+ *
+ * @fragments /fragments/data/metric-graph/
+ *
+ * @example /examples/data/metric-graph-simple
+ *
+ * @since 4.11.0
+ * @copyright schukai GmbH
+ * @summary A beautiful MetricGraph that can make your life easier and also looks good.
+ */
+class MetricGraph extends CustomElement {
+    /**
+     * This method is called by the `instanceof` operator.
+     * @returns {symbol}
+     */
+    static get [instanceSymbol]() {
+        return Symbol.for("@schukai/monster/data/metric-graph@@instance");
+    }
+
+    /**
+     * @return {Components.Data.Metric
+     */
+    [assembleMethodSymbol]() {
+        super[assembleMethodSymbol]();
+        initControlReferences.call(this);
+        return this;
+    }
+
+    /**
+     * To set the options via the HTML Tag, the attribute `data-monster-options` must be used.
+     * @see {@link https://monsterjs.org/en/doc/#configurate-a-monster-control}
+     *
+     * The individual configuration values can be found in the table.
+     *
+     * @property {Object} templates Template definitions
+     * @property {string} templates.main Main template
+     * @property {string} curve The curve of the graph (step, smooth, bubble, bar, area, dot, lollipop, line)
+     * @property {Object} values Value definitions
+     * @property {number} values.value The value of the metric
+     * @property {number} values.change The change of the metric
+     * @property {number} values.secondary The secondary value of the metric
+     * @property {Array} values.points The points of the metric
+     * @property {Object} labels Label definitions
+     * @property {string} labels.title Title of the metric
+     * @property {string} labels.subtext Subtext of the metric
+     * @property {Object} classes CSS classes
+     * @property {string} classes.dot CSS class for the dot
+     */
+    get defaults() {
+        return Object.assign({}, super.defaults, {
+            templates: {
+                main: getTemplate(),
+            },
+
+            graphType: "linear",
+
+            values: {
+                main: null,
+                change: null,
+                secondary: null,
+                points: [2, 2, 2, -30, 30, 5, 4,4, 3, 3, 2,2, 1, 1, 1, 1],
+            },
+            labels: {
+                title: null,
+                subtext: null,
+
+            },
+            classes: {
+                dot: "monster-theme-primary-1"
+            },
+
+            aria : {
+                description: null,
+            }
+
+        });
+    }
+
+
+    /**
+     *
+     * @returns {{tosparkline: ((function(*): (string|string))|*)}}
+     */
+    [updaterTransformerMethodsSymbol]() {
+
+        return {
+            "toGraph": (value) => {
+                if (isString(value)) {
+                    value = value.split(",").map((v) => {
+                        return parseFloat(v);
+                    });
+                }
+
+                const graphType = this.getOption("graphType");
+
+                if (!Array.isArray(value) || value.length === 0) return "";
+                switch (graphType.toLowerCase()) {
+                    case "step":
+                        return renderStepGraph.call(this, value);
+                    case "smooth":
+                        return renderSmoothGraph.call(this, value);
+                    case "bubble":
+                       return renderBubbleGraph.call(this, value);
+                    case "bar":
+                        return renderBarGraph.call(this, value);
+                    case "area":
+                        return renderAreaGraph.call(this, value);
+                    case "dot":
+                        return renderDotGraph.call(this, value);
+                    case "lollipop":
+                        return renderLollipopGraph.call(this, value);
+                    case "line":
+                    default:
+                        return renderLineGraph.call(this, value);
+                }
+
+            }
+        };
+    }
+
+    /**
+     * @return {string}
+     */
+    static getTag() {
+        return "monster-metric-graph";
+    }
+
+    /**
+     * @return {CSSStyleSheet[]}
+     */
+    static getCSSStyleSheet() {
+        return [MetricGraphStyleSheet];
+    }
+
+
+}
+
+function renderAreaGraph(values, options = {}) {
+    const {
+        width = 100,
+        height = 30,
+        stroke = "currentColor",
+        strokeWidth = 2,
+        fill = "rgba(0, 0, 0, 0.1)",
+    } = options;
+
+    if (!Array.isArray(values) || values.length === 0) return "";
+
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const step = width / (values.length - 1);
+    const points = values.map((v, i) => {
+        const x = i * step;
+        const y = height - ((v - min) / range) * height;
+        return { x, y };
+    });
+
+    let d = `M ${points[0].x},${height} L ${points[0].x},${points[0].y}`;
+    for (let i = 1; i < points.length; i++) {
+        d += ` L ${points[i].x},${points[i].y}`;
+    }
+    d += ` L ${points[points.length - 1].x},${height} Z`;
+
+    return `<path d="${d}" stroke="${stroke}" stroke-width="${strokeWidth}" fill="${fill}" stroke-linejoin="round" />`;
+}
+
+function renderBubbleGraph(values, options = {}) {
+    const {
+        width = 100,
+        height = 30,
+        minRadius = 2,
+        maxRadius = 8,
+        lightRange = [0.3, 1.0], // fill-opacity von 0.3 bis 1.0
+        align = "middle",
+    } = options;
+
+    if (!Array.isArray(values) || values.length === 0) return "";
+
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const stepX = width / values.length;
+
+    let centerY;
+    switch (align) {
+        case "top": centerY = maxRadius; break;
+        case "bottom": centerY = height - maxRadius; break;
+        case "middle":
+        default: centerY = height / 2;
+    }
+
+    return values.map((v, i) => {
+        const x = i * stepX + stepX / 2;
+        const norm = (v - min) / range;
+        const r = minRadius + norm * (maxRadius - minRadius);
+        const opacity = lightRange[0] + norm * (lightRange[1] - lightRange[0]);
+
+        return `<circle cx="${x.toFixed(2)}" cy="${centerY.toFixed(2)}" r="${r.toFixed(2)}" fill="currentColor" fill-opacity="${opacity.toFixed(2)}" />`;
+    }).join("");
+}
+
+
+
+
+function renderLollipopGraph(values, options = {}) {
+    const {
+        width = 100,
+        height = 30,
+        color = "currentColor",
+        radius = 2,
+        strokeWidth = 1,
+    } = options;
+
+    if (!Array.isArray(values) || values.length === 0) return "";
+
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const step = width / (values.length - 1);
+
+    return values.map((v, i) => {
+        const x = i * step;
+        const y = height - ((v - min) / range) * height;
+        const line = `<line x1="${x}" y1="${height}" x2="${x}" y2="${y}" stroke="${color}" stroke-width="${strokeWidth}" />`;
+        const circle = `<circle cx="${x}" cy="${y}" r="${radius}" fill="${color}" />`;
+        return line + circle;
+    }).join("");
+}
+
+
+function renderDotGraph(values, options = {}) {
+    const {
+        width = 100,
+        height = 30,
+        radius = 2,
+        color = "currentColor",
+    } = options;
+
+    if (!Array.isArray(values) || values.length === 0) return "";
+
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const step = width / (values.length - 1);
+
+    return values.map((v, i) => {
+        const x = i * step;
+        const y = height - ((v - min) / range) * height;
+        return `<circle cx="${x.toFixed(2)}" cy="${y.toFixed(2)}" r="${radius}" fill="${color}" />`;
+    }).join("");
+}
+
+
+
+function renderBarGraph(values, options = {}) {
+    const {
+        width = 100,
+        height = 30,
+        barColor = "currentColor",
+        barSpacing = 1,
+    } = options;
+
+    if (!Array.isArray(values) || values.length === 0) return "";
+
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const barWidth = width / values.length - barSpacing;
+
+    return values
+        .map((v, i) => {
+            const x = i * (barWidth + barSpacing);
+            const barHeight = ((v - min) / range) * height;
+            const y = height - barHeight;
+            return `<rect x="${x.toFixed(2)}" y="${y.toFixed(2)}" width="${barWidth.toFixed(2)}" height="${barHeight.toFixed(2)}" fill="${barColor}" />`;
+        })
+        .join("");
+}
+
+function renderLineGraph(values) {
+    if (!Array.isArray(values) || values.length === 0) return "";
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const step = 100 / (values.length - 1);
+    const points = values.map((v, i) => {
+        const x = i * step;
+        const y = 30 - ((v - min) / range) * 30;
+        return `${x},${y}`;
+    });
+
+    return `<polyline points="${points.join(" ")}" stroke="currentColor" stroke-width="2" fill="none" />`;
+}
+
+function renderSmoothGraph(values, options = {}) {
+    const {
+        width = 100,
+        height = 30,
+        stroke = "currentColor",
+        strokeWidth = 2,
+        fill = "none",
+    } = options;
+
+    if (!Array.isArray(values) || values.length === 0) return "";
+
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const stepX = width / (values.length - 1);
+
+    const points = values.map((v, i) => {
+        const x = i * stepX;
+        const y = height - ((v - min) / range) * height;
+        return { x, y };
+    });
+
+    // Bézier-Path erzeugen
+    let d = `M ${points[0].x},${points[0].y}`;
+    for (let i = 1; i < points.length; i++) {
+        const prev = points[i - 1];
+        const curr = points[i];
+        const cx = (prev.x + curr.x) / 2;
+        d += ` Q ${prev.x},${prev.y} ${cx},${(prev.y + curr.y) / 2}`;
+    }
+    d += ` T ${points[points.length - 1].x},${points[points.length - 1].y}`;
+
+    return `<path d="${d}" stroke="${stroke}" stroke-width="${strokeWidth}" fill="${fill}" stroke-linecap="round" stroke-linejoin="round" />`;
+}
+
+function renderStepGraph(values, options = {}) {
+    const {
+        width = 100,
+        height = 30,
+        stroke = "currentColor",
+        strokeWidth = 2,
+        fill = "none",
+    } = options;
+
+    if (!Array.isArray(values) || values.length === 0) return "";
+
+    const min = Math.min(...values);
+    const max = Math.max(...values);
+    const range = max - min || 1;
+
+    const stepX = width / (values.length - 1);
+
+    const points = values.map((v, i) => {
+        const x = i * stepX;
+        const y = height - ((v - min) / range) * height;
+        return { x, y };
+    });
+
+    let d = `M ${points[0].x},${points[0].y}`;
+    for (let i = 1; i < points.length; i++) {
+        const prev = points[i - 1];
+        const curr = points[i];
+        d += ` H ${curr.x} V ${curr.y}`;
+    }
+
+    return `<path d="${d}" stroke="${stroke}" stroke-width="${strokeWidth}" fill="${fill}" stroke-linecap="round" stroke-linejoin="round" />`;
+}
+
+
+/**
+ * @private
+ * @return {void}
+ */
+function initControlReferences() {
+    this[metricGraphControlElementSymbol] = this.shadowRoot.querySelector(
+        `[${ATTRIBUTE_ROLE}="control"]`,
+    );
+}
+
+
+/**
+ * @private
+ * @return {string}
+ */
+function getTemplate() {
+    // language=HTML
+    return `
+        <div data-monster-role="control"
+             part="control"
+             role="group"
+             aria-labelledby="metric-title"
+             aria-describedby="metric-value metric-subtext metric-graph-desc">
+
+            <div class="metric-card" part="card">
+                <div class="metric-header" part="header">
+                    <span data-monster-attributes="class path:classes.dot | prefix:metric-icon\\ :"></span>
+                    <span id="metric-title" class="metric-title"
+                          data-monster-replace="path:labels.title | ??:—"></span>
+                </div>
+
+                <div id="metric-value" class="metric-value"
+                     data-monster-replace="path:values.main"
+                     part="metric-value"
+                     aria-live="polite">—</div>
+
+                <div id="metric-subtext" class="metric-subtext" part="metric-subtext">
+                    <span data-monster-replace="path:labels.subtext | ??:— ">—</span><br>
+                    <span class="metric-subtext-value">
+						<strong data-monster-replace="path:values.secondary | ??:—">—</strong>
+					</span>
+                </div>
+
+                <div part="metric-graph" class="metric-graph">
+                    <svg viewBox="0 0 100 30"
+                         preserveAspectRatio="none"
+                         role="img"
+                         aria-labelledby="metric-graph-desc"
+                         focusable="false"
+                         xmlns="http://www.w3.org/2000/svg"
+                         data-monster-replace="path:values.points | call:toGraph">
+                    </svg>
+                    <span id="metric-graph-desc" class="visually-hidden"
+                          data-monster-replace="path:aria.graph | ??:Graphische Darstellung der Kennzahl">
+						Graphische Darstellung
+					</span>
+                </div>
+            </div>
+
+            <span class="visually-hidden" data-monster-replace="path:aria.description"></span>
+        </div>`;
+}
+
+
+
+registerCustomElement(MetricGraph);

package/source/components/data/metric.mjs

@@ -0,0 +1,187 @@
+/**
+ * Copyright © schukai GmbH and all contributing authors, {{copyRightYear}}. All rights reserved.
+ * Node module: @schukai/monster
+ *
+ * This source code is licensed under the GNU Affero General Public License version 3 (AGPLv3).
+ * The full text of the license can be found at: https://www.gnu.org/licenses/agpl-3.0.en.html
+ *
+ * For those who do not wish to adhere to the AGPLv3, a commercial license is available.
+ * Acquiring a commercial license allows you to use this software without complying with the AGPLv3 terms.
+ * For more information about purchasing a commercial license, please contact schukai GmbH.
+ */
+
+import {instanceSymbol} from "../../constants.mjs";
+import {addAttributeToken} from "../../dom/attributes.mjs";
+import {
+    ATTRIBUTE_ERRORMESSAGE,
+    ATTRIBUTE_ROLE,
+} from "../../dom/constants.mjs";
+import {CustomControl} from "../../dom/customcontrol.mjs";
+import {CustomElement} from "../../dom/customelement.mjs";
+import {
+    assembleMethodSymbol,
+    registerCustomElement,
+} from "../../dom/customelement.mjs";
+import {findTargetElementFromEvent} from "../../dom/events.mjs";
+import {isFunction} from "../../types/is.mjs";
+import {MetricStyleSheet} from "./stylesheet/metric.mjs";
+import {fireCustomEvent} from "../../dom/events.mjs";
+
+export {Metric};
+
+/**
+ * @private
+ * @type {symbol}
+ */
+export const metricControlElementSymbol = Symbol("metricControlElement");
+
+/**
+ * A Metric is a simple component that can be used to display a value.
+ *
+ * @fragments /fragments/components/data/metric/
+ *
+ * @example /examples/components/data/metric-simple
+ *
+ * @since 4.11.0
+ * @copyright schukai GmbH
+ * @summary A beautiful Metric that can make your life easier and also looks good.
+ */
+class Metric extends CustomElement {
+    /**
+     * This method is called by the `instanceof` operator.
+     * @returns {symbol}
+     */
+    static get [instanceSymbol]() {
+        return Symbol.for("@schukai/monster/components/data/metric@@instance");
+    }
+
+    /**
+     * @return {Components.Data.Metric
+     */
+    [assembleMethodSymbol]() {
+        super[assembleMethodSymbol]();
+        initControlReferences.call(this);
+        return this;
+    }
+
+    /**
+     * To set the options via the HTML Tag, the attribute `data-monster-options` must be used.
+     * @see {@link https://monsterjs.org/en/doc/#configurate-a-monster-control}
+     *
+     * The individual configuration values can be found in the table.
+     *
+     * @property {Object} templates Template definitions
+     * @property {string} templates.main Main template
+     * @property {Object} values Value definitions
+     * @property {number} values.value The value of the metric
+     * @property {number} values.change The change of the metric
+     * @property {number} values.direction The direction of the metric
+     * @property {number} values.secondary The secondary value of the metric
+     * @property {Object} labels Label definitions
+     * @property {string} labels.title Title of the metric
+     * @property {string} labels.subtext Subtext of the metric
+     * @property {Object} classes CSS classes
+     * @property {string} classes.dot CSS class for the dot
+     * @property {string} classes.metricChange CSS class for the metric change (positive/negative)
+     */
+    get defaults() {
+        return Object.assign({}, super.defaults, {
+            templates: {
+                main: getTemplate(),
+            },
+            values: {
+				main: null,
+				change: null,
+                direction: 270,
+                secondary: null,
+            },
+            labels: {
+                title: null,
+                subtext: null,
+            },
+            classes: {
+                dot: "monster-theme-primary-1",
+                change: "positive",
+            },
+
+            aria: {
+                description: null,
+            }
+        });
+    }
+
+    /**
+     * @return {string}
+     */
+    static getTag() {
+        return "monster-metric";
+    }
+
+    /**
+     * @return {CSSStyleSheet[]}
+     */
+    static getCSSStyleSheet() {
+        return [MetricStyleSheet];
+    }
+
+
+}
+
+/**
+ * @private
+ * @return {void}
+ */
+function initControlReferences() {
+    this[metricControlElementSymbol] = this.shadowRoot.querySelector(
+        `[${ATTRIBUTE_ROLE}="control"]`,
+    );
+}
+
+/**
+ * @private
+ * @return {string}
+ */
+function getTemplate() {
+    // language=HTML
+    return `
+        <div data-monster-role="control" part="control"
+             role="group"
+             aria-labelledby="metric-title"
+             aria-describedby="metric-subtext metric-value metric-change-text">
+
+            <div class="metric-card" part="card">
+                <div class="metric-header" part="header">
+                    <span data-monster-attributes="class path:classes.dot | prefix:metric-icon\\ :"></span>
+                    <span id="metric-title" class="metric-title"
+                          data-monster-replace="path:labels.title | ??:—"></span>
+                </div>
+
+                <div id="metric-value" class="metric-value"
+                     data-monster-replace="path:values.main" part="metric-value">—</div>
+
+                <div id="metric-subtext" class="metric-subtext" part="metric-subtext">
+                    <span data-monster-replace="path:labels.subtext | ??:— ">—</span><br>
+                    <span class="metric-subtext-value">
+						<strong data-monster-replace="path:values.secondary | ??:—">—</strong>
+					</span>
+                </div>
+
+                <div id="metric-change-text" part="metric-change"
+                     data-monster-attributes="style path:values.direction | tostring | prefix:--arrow-direction\\:\\ : | suffix:deg,
+											  class path:classes.change | prefix:metric-change\\ :">
+					<span class="arrow">
+					  <svg viewBox="0 0 24 24" width="16" height="16" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+						<path d="M12 4v16m0 0l-6-6m6 6l6-6"
+                              stroke="currentColor" stroke-width="2"
+                              fill="none" stroke-linecap="round" stroke-linejoin="round"/>
+					  </svg>
+					</span>
+                    <span data-monster-replace="path:values.change | ??:—"></span>
+                </div>
+            </div>
+
+            <span class="visually-hidden" data-monster-replace="path:aria.description"></span>
+        </div>`;
+}
+
+registerCustomElement(Metric);