@schukai/monster/source/components/data/metric.mjs

Monster is a simple library for creating fast, robust and lightweight websites.

/**
 * 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 {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);