@limetech/lime-elements 40.21.0 → 40.22.0

package/dist/collection/components/chart/chart.js

@@ -6,7 +6,8 @@ import { SVGRenderer } from "echarts/renderers";
 import translate from "../../global/translations";
 import { findNavigationTarget, findTabStop, isNavigationKey, NO_NAVIGATION_TARGET, } from "../../util/keyboard-navigation";
 import { drawChart, fitItemTexts, getItemIndex, getItemLabel, locateItem, } from "./options";
-import { formatValue, getAxisRange, MAX_AXIS_STEPS, usesAxisIncrement, } from "./scale";
+import { getAxisRange, isDate, MAX_AXIS_STEPS, usesAxisIncrement, } from "./scale";
+import { canWriteIn, formatValue, isCurrencyCode } from "./format";
 import { createThemeReader, watchTheme, } from "./theme";
 const orientations = ['horizontal', 'vertical'];
 const extensions = [
@@ -29,6 +30,8 @@ const extensions = [
  * @exampleComponent limel-example-chart-orientation
  * @exampleComponent limel-example-chart-max-value
  * @exampleComponent limel-example-chart-display-item-percentage
+ * @exampleComponent limel-example-chart-value-format
+ * @exampleComponent limel-example-chart-value-format-date
  * @exampleComponent limel-example-chart-type-bar
  * @exampleComponent limel-example-chart-type-dot
  * @exampleComponent limel-example-chart-type-area
@@ -53,8 +56,8 @@ const extensions = [
 export class Chart {
     constructor() {
         /**
-         * Defines the language for translations.
-         * Will translate the translatable strings on the components.
+         * Defines the language for translations, and for the way values are
+         * written, such as `1 234,5` in Swedish.
          */
         this.language = 'en';
         /**
@@ -94,6 +97,16 @@ export class Chart {
          * Does not have any effect on chart types which generate circular forms.
          */
         this.orientation = 'landscape';
+        /**
+         * Defines how values are written: as numbers, as percentages where
+         * `0.25` is `25 %`, as amounts of `currency`, or as dates. With `date`,
+         * each value is a date in milliseconds since 1970, and the value axis
+         * steps through days, weeks, months or years. The axes, the values
+         * shown with `displayItemValue`, the tooltips, and the screen reader
+         * table all follow it, in the chart's `language`. An item's
+         * `formattedValue` is shown as it is.
+         */
+        this.valueFormat = 'number';
         /**
          * Indicates whether the chart is in a loading state.
          */
@@ -103,6 +116,7 @@ export class Chart {
          */
         this.focusedIndex = 0;
         this.themeMayHaveChanged = false;
+        this.warnings = new Map();
         this.invalidColors = new Set();
         this.setPlot = (element) => {
             this.plot = element;
@@ -167,9 +181,14 @@ export class Chart {
         };
     }
     componentWillLoad() {
-        this.warnAboutAxisIncrement();
         this.warnAboutOldTypeName();
     }
+    componentWillRender() {
+        this.warnOnChange('axisIncrement', this.getAxisIncrementWarning());
+        this.warnOnChange('language', this.getLanguageWarning());
+        this.warnOnChange('currency', this.getCurrencyWarning());
+        this.warnOnChange('items', this.getDateWarning());
+    }
     connectedCallback() {
         this.draw();
     }
@@ -186,25 +205,60 @@ export class Chart {
         (_c = this.themeReader) === null || _c === void 0 ? void 0 : _c.dispose();
         this.themeReader = undefined;
     }
-    warnAboutAxisIncrement() {
-        const warning = this.getAxisIncrementWarning();
-        if (warning && warning !== this.axisIncrementWarning) {
+    warnOnChange(prop, warning) {
+        if (warning && warning !== this.warnings.get(prop)) {
             console.warn(warning);
         }
-        this.axisIncrementWarning = warning;
+        this.warnings.set(prop, warning);
     }
     warnAboutOldTypeName() {
         if (this.type === 'stacked-bar') {
             console.warn('limel-chart: the type `stacked-bar` is now called `proportion-bar`. It draws the same chart, but please use the new name.');
         }
     }
+    getLanguageWarning() {
+        if (canWriteIn(this.language)) {
+            return;
+        }
+        return `limel-chart: \`language\` must be one that this browser can write values in, such as \`sv\`, but was ${JSON.stringify(this.language)}. Writing the values in English instead.`;
+    }
+    getCurrencyWarning() {
+        if (this.valueFormat !== 'currency' || isCurrencyCode(this.currency)) {
+            return;
+        }
+        return `limel-chart: \`currency\` must be a three-letter code such as \`SEK\` when \`valueFormat\` is \`currency\`, but was ${JSON.stringify(this.currency)}. Writing the values as numbers instead.`;
+    }
+    getDateWarning() {
+        var _a;
+        if (this.valueFormat !== 'date') {
+            return;
+        }
+        const wrong = ((_a = this.items) !== null && _a !== void 0 ? _a : [])
+            .flatMap((item) => [item.value].flat())
+            .find((value) => !isDate(value));
+        if (wrong === undefined) {
+            return;
+        }
+        const shown = typeof wrong === 'number' ? wrong : JSON.stringify(wrong);
+        return `limel-chart: with \`valueFormat\` \`date\`, each value must be a date in milliseconds since 1970, as \`Date.getTime()\` gives, but was ${shown}. Showing it as it is.`;
+    }
+    get valueStyle() {
+        return {
+            type: this.chartType,
+            language: this.language,
+            valueFormat: this.valueFormat,
+            currency: this.currency,
+        };
+    }
     get chartType() {
         return this.type === 'stacked-bar' ? 'proportion-bar' : this.type;
     }
     getAxisIncrementWarning() {
         var _a;
         const increment = this.axisIncrement;
-        if (increment === undefined || increment === null) {
+        if (increment === undefined ||
+            increment === null ||
+            this.valueFormat === 'date') {
             return;
         }
         if (increment <= 0 || Number.isNaN(increment)) {
@@ -244,15 +298,10 @@ export class Chart {
     renderItems() {
         var _a, _b;
         const tabStop = findTabStop((_a = this.items) !== null && _a !== void 0 ? _a : [], this.focusedIndex);
-        return (_b = this.items) === null || _b === void 0 ? void 0 : _b.map((item, index) => (h("tr", { "data-index": index, "aria-description": this.getRowDescription(index), tabIndex: index === tabStop ? 0 : -1, role: item.clickable ? 'button' : null, onClick: this.handleClick, onKeyDown: this.handleKeyDown, onFocus: this.handleFocus, onBlur: this.handleBlur }, h("td", null, item.text), h("td", null, formatValue(item, this.chartType)))));
+        return (_b = this.items) === null || _b === void 0 ? void 0 : _b.map((item, index) => (h("tr", { "data-index": index, "aria-description": this.getRowDescription(index), tabIndex: index === tabStop ? 0 : -1, role: item.clickable ? 'button' : null, onClick: this.handleClick, onKeyDown: this.handleKeyDown, onFocus: this.handleFocus, onBlur: this.handleBlur }, h("td", null, item.text), h("td", null, formatValue(item, this.valueStyle)))));
     }
     getRowDescription(index) {
-        const label = getItemLabel({
-            items: this.items,
-            type: this.chartType,
-            maxValue: this.maxValue,
-            displayItemPercentage: this.displayItemPercentage,
-        }, index);
+        const label = getItemLabel(Object.assign(Object.assign({}, this.valueStyle), { items: this.items, maxValue: this.maxValue, displayItemPercentage: this.displayItemPercentage }), index);
         return label === this.items[index].text ? undefined : label;
     }
     draw() {
@@ -375,25 +424,13 @@ export class Chart {
     }
     getSettings() {
         var _a;
-        return {
-            items: ((_a = this.items) !== null && _a !== void 0 ? _a : []).map((item) => ({
+        return Object.assign(Object.assign({ items: ((_a = this.items) !== null && _a !== void 0 ? _a : []).map((item) => ({
                 text: item.text,
                 value: item.value,
                 formattedValue: item.formattedValue,
                 color: item.color,
                 clickable: item.clickable,
-            })),
-            type: this.chartType,
-            orientation: this.orientation,
-            maxValue: this.maxValue,
-            axisIncrement: this.axisIncrement,
-            displayAxisLabels: this.displayAxisLabels,
-            itemsLabel: this.itemsLabel,
-            valuesLabel: this.valuesLabel,
-            displayItemText: this.displayItemText,
-            displayItemValue: this.displayItemValue,
-            displayItemPercentage: this.displayItemPercentage,
-        };
+            })) }, this.valueStyle), { orientation: this.orientation, maxValue: this.maxValue, axisIncrement: this.axisIncrement, displayAxisLabels: this.displayAxisLabels, itemsLabel: this.itemsLabel, valuesLabel: this.valuesLabel, displayItemText: this.displayItemText, displayItemValue: this.displayItemValue, displayItemPercentage: this.displayItemPercentage });
     }
     withItemColors(settings, theme) {
         return Object.assign(Object.assign({}, settings), { items: settings.items.map((item) => (Object.assign(Object.assign({}, item), { color: this.getItemColor(item, theme) }))) });
@@ -499,7 +536,7 @@ export class Chart {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Defines the language for translations.\nWill translate the translatable strings on the components."
+                    "text": "Defines the language for translations, and for the way values are\nwritten, such as `1 234,5` in Swedish."
                 },
                 "getter": false,
                 "setter": false,
@@ -727,7 +764,7 @@ export class Chart {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Sets the value used to scale item values.\nFor `proportion-bar`, `pie`, `doughnut`, and `ring`, it is the denominator\nused as the whole. It defaults to the combined item values or range\nextents. The combined size can exceed `maxValue` and produce a total\nabove 100%.\nFor `bar`, `dot`, `area`, and `line`, it is the requested upper bound.\nThe chart can round that bound up to the next `axisIncrement`.\nHas no effect on `nps` or `scatter`."
+                    "text": "Sets the value used to scale item values.\nFor `proportion-bar`, `pie`, `doughnut`, and `ring`, it is the denominator\nused as the whole. It defaults to the combined item values or range\nextents. The combined size can exceed `maxValue` and produce a total\nabove 100%.\nFor `bar`, `dot`, `area`, and `line`, it is the requested upper bound.\nThe chart can round that bound up to the next `axisIncrement`, or to\nthe end of its day when `valueFormat` is `date`.\nHas no effect on `nps` or `scatter`."
                 },
                 "getter": false,
                 "setter": false,
@@ -746,13 +783,59 @@ export class Chart {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": "Sets the axis increment for `bar`, `dot`, `area`, and `line` charts.\nWhen it is not set, or not above zero, the chart works out a step\nfrom the values. It also does that when the step would divide the\naxis into more than 100 parts, so that it does not draw too many lines.\nHas no effect on other chart types."
+                    "text": "Sets the axis increment for `bar`, `dot`, `area`, and `line` charts.\nWhen it is not set, or not above zero, the chart works out a step\nfrom the values. It also does that when the step would divide the\naxis into more than 100 parts, so that it does not draw too many lines.\nHas no effect on other chart types, or when `valueFormat` is `date`,\nwhere the axis steps through days, weeks, months or years by itself."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": true,
                 "attribute": "axis-increment"
             },
+            "valueFormat": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "ChartValueFormat",
+                    "resolved": "\"currency\" | \"date\" | \"number\" | \"percent\"",
+                    "references": {
+                        "ChartValueFormat": {
+                            "location": "import",
+                            "path": "./chart.types",
+                            "id": "src/components/chart/chart.types.ts::ChartValueFormat",
+                            "referenceLocation": "ChartValueFormat"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Defines how values are written: as numbers, as percentages where\n`0.25` is `25 %`, as amounts of `currency`, or as dates. With `date`,\neach value is a date in milliseconds since 1970, and the value axis\nsteps through days, weeks, months or years. The axes, the values\nshown with `displayItemValue`, the tooltips, and the screen reader\ntable all follow it, in the chart's `language`. An item's\n`formattedValue` is shown as it is."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "value-format",
+                "defaultValue": "'number'"
+            },
+            "currency": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "The currency of the values when `valueFormat` is `currency`, as a\nthree-letter code such as `SEK`. Without one, the values are written\nas numbers."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "currency"
+            },
             "loading": {
                 "type": "boolean",
                 "mutable": false,
@@ -808,18 +891,6 @@ export class Chart {
     static get elementRef() { return "host"; }
     static get watchers() {
         return [{
-                "propName": "axisIncrement",
-                "methodName": "warnAboutAxisIncrement"
-            }, {
-                "propName": "items",
-                "methodName": "warnAboutAxisIncrement"
-            }, {
-                "propName": "maxValue",
-                "methodName": "warnAboutAxisIncrement"
-            }, {
-                "propName": "type",
-                "methodName": "warnAboutAxisIncrement"
-            }, {
                 "propName": "type",
                 "methodName": "warnAboutOldTypeName"
             }];

package/dist/collection/components/chart/format.js

@@ -0,0 +1,302 @@
+import { getSupportedLocale } from "../../util/language";
+import { getMaximumValue, getMinimumValue, isDate, } from "./scale";
+const FALLBACK_LOCALE = 'en';
+const PERCENT = 100;
+/**
+ * The largest value on an axis from which its values are shortened,
+ * such as `1.2M` for 1 200 000.
+ */
+const SHORTEN_FROM = 10000;
+/**
+ * The most decimals `Intl` writes in every browser.
+ */
+const MAX_DECIMALS = 20;
+/**
+ * The most significant digits `Intl` writes.
+ */
+const MAX_SIGNIFICANT_DIGITS = 21;
+/**
+ * Up to three decimals, and six significant digits below one, so `0.0004`
+ * is not written as `0`.
+ */
+const NUMBERS = {
+    options: { maximumFractionDigits: 3 },
+    small: { maximumSignificantDigits: 6 },
+    smallBelow: 1,
+};
+/**
+ * Up to one decimal, and two significant digits below 1 %, so `0.0004` is
+ * written as `0.04%` rather than `0%`.
+ */
+const PERCENTAGES = {
+    options: { style: 'percent', maximumFractionDigits: 1 },
+    small: { style: 'percent', maximumSignificantDigits: 2 },
+    smallBelow: 0.01,
+};
+const SHARE_OPTIONS = {
+    style: 'percent',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2,
+};
+/**
+ * The ticks of an axis of dates that are not known, whose dates are all
+ * written with their year.
+ */
+const UNKNOWN_DATE_TICKS = { values: [], unit: 'day' };
+const locales = new Map();
+const numberFormats = new Map();
+const currencyCodes = new Map();
+const dateFormats = new Map();
+/**
+ * The item's value as text: its `formattedValue` when set, otherwise its
+ * value, range, or scatter point, written in the chart's language and
+ * value format.
+ * @param item - the item
+ * @param style - how the chart writes values
+ */
+export function formatValue(item, style) {
+    const { value, formattedValue } = item;
+    if (formattedValue) {
+        return formattedValue;
+    }
+    const write = getValueWriter(style);
+    if (!Array.isArray(value)) {
+        return write(value);
+    }
+    const [first, second] = value.map((part) => write(part));
+    if (style.type === 'scatter') {
+        return writePoint(first, second);
+    }
+    const [start, end] = [getMinimumValue(item), getMaximumValue(item)];
+    if (style.valueFormat === 'date' && isDate(start) && isDate(end)) {
+        return getDateFormat(style.language).formatRange(start, end);
+    }
+    return `${first} — ${second}`;
+}
+/**
+ * Writes the values of an axis in the chart's language and value format,
+ * with as many decimals as the step between them has. Amounts leave out
+ * their currency, which the item values and tooltips show. On an axis
+ * that reaches 10 000 or more, every number is shortened, such as `1.2M`,
+ * so the values stay short and alike. Dates are written by what the axis
+ * steps through: days, months or years, with the year on the first date
+ * and on the first date of each new year.
+ * @param range - the range of the axis
+ * @param style - how the chart writes values
+ * @param dates - the dates an axis of dates marks
+ */
+export function getAxisValueFormatter(range, style, dates) {
+    const locale = getLocale(style.language);
+    if (style.valueFormat === 'date') {
+        return getDateAxisFormatter(locale, dates);
+    }
+    if (style.valueFormat === 'percent') {
+        const percentages = getNumberFormat(locale, {
+            style: 'percent',
+            maximumFractionDigits: countDecimals(range.increment * PERCENT),
+        });
+        return (value) => percentages.format(value);
+    }
+    const largest = Math.max(Math.abs(range.minValue), Math.abs(range.maxValue));
+    const numbers = getNumberFormat(locale, largest >= SHORTEN_FROM
+        ? {
+            notation: 'compact',
+            maximumSignificantDigits: countSignificantDigits(largest, range.increment),
+        }
+        : { maximumFractionDigits: countDecimals(range.increment) });
+    return (value) => numbers.format(value);
+}
+/**
+ * An item's share of the whole as a percentage with two decimals, such as
+ * `25.00%`, written in the chart's language.
+ * @param share - the share, in percent
+ * @param language - the language of the chart
+ */
+export function formatShare(share, language) {
+    return getNumberFormat(getLocale(language), SHARE_OPTIONS).format(share / PERCENT);
+}
+/**
+ * Whether `currency` can be written as one: a three-letter code such as
+ * `SEK`.
+ * @param currency - the currency of the chart
+ */
+export function isCurrencyCode(currency) {
+    let valid = currencyCodes.get(currency);
+    if (valid === undefined) {
+        valid = canWriteAmountsIn(currency);
+        currencyCodes.set(currency, valid);
+    }
+    return valid;
+}
+function canWriteAmountsIn(currency) {
+    try {
+        getNumberFormat(FALLBACK_LOCALE, { style: 'currency', currency });
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+/**
+ * Whether values can be written in `language`. When they cannot, they are
+ * written in English.
+ * @param language - the language of the chart
+ */
+export function canWriteIn(language) {
+    return findLocale(language) !== undefined;
+}
+function getValueWriter(style) {
+    if (style.valueFormat === 'date') {
+        const dates = getDateFormat(style.language);
+        return (value) => (isDate(value) ? dates.format(value) : `${value}`);
+    }
+    const numbers = getValueFormat(style);
+    return (value) => numbers.format(value);
+}
+/**
+ * Writes the dates on an axis by what it steps through: day and month for
+ * days and weeks, the month for months, and the year for years. The first
+ * date, and the first date of each new year, also get their year, except
+ * January among months, which is written as its year alone.
+ * @param locale - the locale of the chart
+ * @param ticks - the dates the axis marks
+ */
+function getDateAxisFormatter(locale, ticks = UNKNOWN_DATE_TICKS) {
+    const years = getDateTimeFormat(locale, { year: 'numeric' });
+    if (ticks.unit === 'year') {
+        return (value) => years.format(value);
+    }
+    const parts = ticks.unit === 'month'
+        ? { month: 'short' }
+        : { day: 'numeric', month: 'short' };
+    const dates = getDateTimeFormat(locale, parts);
+    const datesWithYear = getDateTimeFormat(locale, Object.assign(Object.assign({}, parts), { year: 'numeric' }));
+    return (value) => {
+        if (!isFirstOfItsYear(value, ticks.values)) {
+            return dates.format(value);
+        }
+        return ticks.unit === 'month' && new Date(value).getMonth() === 0
+            ? years.format(value)
+            : datesWithYear.format(value);
+    };
+}
+/**
+ * Whether `value` is the first of `ticks` in its year. A date that is not
+ * one of them counts as the first, so that it gets its year.
+ * @param value - the date
+ * @param ticks - the dates an axis marks
+ */
+function isFirstOfItsYear(value, ticks) {
+    const index = ticks.indexOf(value);
+    return (index <= 0 ||
+        new Date(ticks[index - 1]).getFullYear() !==
+            new Date(value).getFullYear());
+}
+function getDateFormat(language) {
+    return getDateTimeFormat(getLocale(language), { dateStyle: 'medium' });
+}
+function getValueFormat(style) {
+    const locale = getLocale(style.language);
+    if (style.valueFormat === 'percent') {
+        return getNumberWriter(locale, PERCENTAGES);
+    }
+    if (style.valueFormat === 'currency' && isCurrencyCode(style.currency)) {
+        return getNumberFormat(locale, {
+            style: 'currency',
+            currency: style.currency,
+            trailingZeroDisplay: 'stripIfInteger',
+        });
+    }
+    return getNumberWriter(locale, NUMBERS);
+}
+/**
+ * The two values of a scatter point, separated by a semicolon when either
+ * of them has a comma in it, such as `(1,5; 2,5)` in Swedish.
+ * @param first - the first value, as text
+ * @param second - the second value, as text
+ */
+function writePoint(first, second) {
+    const separator = `${first}${second}`.includes(',') ? '; ' : ', ';
+    return `(${first}${separator}${second})`;
+}
+function countDecimals(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.min(MAX_DECIMALS, Math.max(0, -getLowestDigit(value)));
+}
+/**
+ * How many significant digits the values of an axis need for every step
+ * between them to show, such as four for `1.025M` on an axis that steps
+ * by 25 000 up to 2 000 000.
+ * @param largest - the largest value on the axis, ignoring its sign
+ * @param increment - the step between the values
+ */
+function countSignificantDigits(largest, increment) {
+    if (!Number.isFinite(increment)) {
+        return MAX_SIGNIFICANT_DIGITS;
+    }
+    const digits = Math.floor(Math.log10(largest)) - getLowestDigit(increment);
+    return Math.min(MAX_SIGNIFICANT_DIGITS, Math.max(1, digits + 1));
+}
+/**
+ * The power of ten of the last digit of `value` that is not zero, such as
+ * 3 for 25 000 and -2 for 0.25.
+ * @param value - a finite number
+ */
+function getLowestDigit(value) {
+    var _a, _b;
+    const [digits, exponent] = Number(value.toPrecision(12))
+        .toExponential()
+        .split('e', 2);
+    const decimals = (_b = (_a = digits.split('.', 2)[1]) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0;
+    return Number(exponent) - decimals;
+}
+function getNumberWriter(locale, style) {
+    const numbers = getNumberFormat(locale, style.options);
+    const small = getNumberFormat(locale, style.small);
+    return {
+        format: (value) => value !== 0 && Math.abs(value) < style.smallBelow
+            ? small.format(value)
+            : numbers.format(value),
+    };
+}
+/**
+ * Making an `Intl.NumberFormat` costs far more than using one, and values
+ * are written on every render, so each one is made once.
+ * @param locale - the locale to write in
+ * @param options - how to write the numbers
+ */
+function getNumberFormat(locale, options) {
+    const key = `${locale} ${JSON.stringify(options)}`;
+    let format = numberFormats.get(key);
+    if (!format) {
+        format = new Intl.NumberFormat(locale, options);
+        numberFormats.set(key, format);
+    }
+    return format;
+}
+function getDateTimeFormat(locale, options) {
+    const key = `${locale} ${JSON.stringify(options)}`;
+    let format = dateFormats.get(key);
+    if (!format) {
+        format = new Intl.DateTimeFormat(locale, options);
+        dateFormats.set(key, format);
+    }
+    return format;
+}
+/**
+ * The locale to write values in: the chart's language when `Intl` can
+ * write in it, otherwise English.
+ * @param language - the language of the chart
+ */
+function getLocale(language) {
+    var _a;
+    return (_a = findLocale(language)) !== null && _a !== void 0 ? _a : FALLBACK_LOCALE;
+}
+function findLocale(language) {
+    if (!locales.has(language)) {
+        locales.set(language, getSupportedLocale(language));
+    }
+    return locales.get(language);
+}