@refinitiv-ui/elements 5.3.3 → 5.7.0

package/lib/heatmap/custom-elements.json

@@ -0,0 +1,151 @@
+{
+  "version": "experimental",
+  "tags": [
+    {
+      "name": "ef-heatmap",
+      "description": "A graphical representation of data where the individual\nvalues contained in a matrix are represented as colors",
+      "attributes": [
+        {
+          "name": "config",
+          "description": "Heatmap configuration options.",
+          "type": "HeatmapConfig"
+        },
+        {
+          "name": "label-width",
+          "description": "Number of maximum label width that cell can paint in pixel.\ne.g. label-width: 30px; cell label hides when text length reaches 30px.",
+          "type": "number",
+          "default": "0"
+        },
+        {
+          "name": "label-hidden",
+          "description": "Hide all labels in the cells",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "axis-hidden",
+          "description": "Hide all axes",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "min-point",
+          "description": "Minimum point of the cell coloring",
+          "type": "number",
+          "default": "-1"
+        },
+        {
+          "name": "mid-point",
+          "description": "Middle point of the cell coloring",
+          "type": "number",
+          "default": "0"
+        },
+        {
+          "name": "max-point",
+          "description": "Maximum point of the cell coloring",
+          "type": "number",
+          "default": "1"
+        },
+        {
+          "name": "blend",
+          "description": "Enable cell color blending",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "saturation",
+          "description": "Cell minimum color saturation, value can be from 0 - 1",
+          "type": "number",
+          "default": "0.4"
+        }
+      ],
+      "properties": [
+        {
+          "name": "config",
+          "attribute": "config",
+          "description": "Heatmap configuration options.",
+          "type": "HeatmapConfig"
+        },
+        {
+          "name": "labelWidth",
+          "attribute": "label-width",
+          "description": "Number of maximum label width that cell can paint in pixel.\ne.g. label-width: 30px; cell label hides when text length reaches 30px.",
+          "type": "number",
+          "default": "0"
+        },
+        {
+          "name": "labelHidden",
+          "attribute": "label-hidden",
+          "description": "Hide all labels in the cells",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "axisHidden",
+          "attribute": "axis-hidden",
+          "description": "Hide all axes",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "minPoint",
+          "attribute": "min-point",
+          "description": "Minimum point of the cell coloring",
+          "type": "number",
+          "default": "-1"
+        },
+        {
+          "name": "midPoint",
+          "attribute": "mid-point",
+          "description": "Middle point of the cell coloring",
+          "type": "number",
+          "default": "0"
+        },
+        {
+          "name": "maxPoint",
+          "attribute": "max-point",
+          "description": "Maximum point of the cell coloring",
+          "type": "number",
+          "default": "1"
+        },
+        {
+          "name": "blend",
+          "attribute": "blend",
+          "description": "Enable cell color blending",
+          "type": "boolean",
+          "default": "false"
+        },
+        {
+          "name": "saturation",
+          "attribute": "saturation",
+          "description": "Cell minimum color saturation, value can be from 0 - 1",
+          "type": "number",
+          "default": "0.4"
+        },
+        {
+          "name": "tooltipCallback",
+          "description": "A callback function that allows tooltip rendering on cell hover",
+          "type": "HeatmapTooltipCallback"
+        },
+        {
+          "name": "renderCallback",
+          "description": "Render callback function use for custom cell properties.\nAccepts custom label, foreground and background color",
+          "type": "HeatmapRenderCallback"
+        }
+      ],
+      "methods": [
+        {
+          "name": "getCellDataAtEvent",
+          "description": "Returns data of interactive cell",
+          "params": [
+            {
+              "name": "event",
+              "description": "an event that occur while the user interacting with element",
+              "type": "MouseEvent"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/lib/heatmap/custom-elements.md

@@ -0,0 +1,26 @@
+# ef-heatmap
+
+A graphical representation of data where the individual
+values contained in a matrix are represented as colors
+
+## Properties
+
+| Property          | Attribute      | Type                     | Default | Description                                      |
+|-------------------|----------------|--------------------------|---------|--------------------------------------------------|
+| `axisHidden`      | `axis-hidden`  | `boolean`                | false   | Hide all axes                                    |
+| `blend`           | `blend`        | `boolean`                | false   | Enable cell color blending                       |
+| `config`          | `config`       | `HeatmapConfig`          | null    | Heatmap configuration options.                   |
+| `labelHidden`     | `label-hidden` | `boolean`                | false   | Hide all labels in the cells                     |
+| `labelWidth`      | `label-width`  | `number`                 | 0       | Number of maximum label width that cell can paint in pixel.<br />e.g. label-width: 30px; cell label hides when text length reaches 30px. |
+| `maxPoint`        | `max-point`    | `number`                 | 1       | Maximum point of the cell coloring               |
+| `midPoint`        | `mid-point`    | `number`                 | 0       | Middle point of the cell coloring                |
+| `minPoint`        | `min-point`    | `number`                 | -1      | Minimum point of the cell coloring               |
+| `renderCallback`  |                | `HeatmapRenderCallback`  |         | Render callback function use for custom cell properties.<br />Accepts custom label, foreground and background color |
+| `saturation`      | `saturation`   | `number`                 | 0.4     | Cell minimum color saturation, value can be from 0 - 1 |
+| `tooltipCallback` |                | `HeatmapTooltipCallback` |         | A callback function that allows tooltip rendering on cell hover |
+
+## Methods
+
+| Method               | Type                | Description                                      |
+|----------------------|---------------------|--------------------------------------------------|
+| `getCellDataAtEvent` | `(event: any): any` | Returns data of interactive cell<br /><br />**event**: an event that occur while the user interacting with element |

package/lib/heatmap/helpers/color.d.ts

@@ -0,0 +1,30 @@
+import { ColorCommonInstance } from '@refinitiv-ui/utils/lib/color.js';
+import { interpolate } from 'd3-interpolate';
+/**
+ * Check if the color is a light color
+ * @param col color to check
+ * @returns a boolean indicating whether the color's perceived brightness is light
+ */
+declare const isLight: (col: ColorCommonInstance) => boolean;
+/**
+ * Brightens a color
+ * @param colorString color string
+ * @return a color brighter than original color
+ */
+declare const brighten: (colorString: string) => string;
+/**
+ * Darkens a color
+ * @param colorString color string
+ * @return a color darker than original color
+ */
+declare const darken: (colorString: string) => string;
+/**
+ * Blends two colors and its background together
+ * @param color1 dominant color
+ * @param color2 secondary color
+ * @param backgroundColor background color
+ * @param amount color blending amount
+ * @returns a new blended color
+ */
+declare const blend: (color1: string, color2: string, backgroundColor: string, amount: number) => string;
+export { blend, brighten, darken, isLight, interpolate };

package/lib/heatmap/helpers/color.js

@@ -0,0 +1,68 @@
+/* istanbul ignore file */
+import { color, rgb, hsl } from '@refinitiv-ui/utils/lib/color.js';
+import { interpolate } from 'd3-interpolate';
+/**
+ * Check if the color is a light color
+ * @param col color to check
+ * @returns a boolean indicating whether the color's perceived brightness is light
+ */
+const isLight = (col) => {
+    const { r, g, b } = rgb(col);
+    return ((r * 299 + g * 587 + b * 114) / 1000) > 128;
+};
+/**
+ * Brightens a color
+ * @param colorString color string
+ * @return a color brighter than original color
+ */
+const brighten = (colorString) => {
+    var _a;
+    return ((_a = color(colorString)) === null || _a === void 0 ? void 0 : _a.brighter(0.8).toString()) || '';
+};
+/**
+ * Darkens a color
+ * @param colorString color string
+ * @return a color darker than original color
+ */
+const darken = (colorString) => {
+    const color = hsl(colorString);
+    color.s += 0.15; // increasing saturation not to make the color too blackish
+    return color.darker(0.6).toString() || '';
+};
+/**
+ * Blends two colors and its background together
+ * @param color1 dominant color
+ * @param color2 secondary color
+ * @param backgroundColor background color
+ * @param amount color blending amount
+ * @returns a new blended color
+ */
+const blend = (color1, color2, backgroundColor, amount) => {
+    var _a;
+    let primaryColor;
+    let secondaryColor;
+    if (amount >= 0) {
+        primaryColor = rgb(color2);
+        secondaryColor = rgb(color1);
+    }
+    else {
+        primaryColor = rgb(color1);
+        secondaryColor = rgb(color2);
+    }
+    // when background color is dark -> mix if dominant color is brighter than secondary color
+    let mixRedComponent = primaryColor.r > secondaryColor.r;
+    let mixGreenComponent = primaryColor.g > secondaryColor.g;
+    let mixBlueComponent = primaryColor.b > secondaryColor.b;
+    // when background color is light -> mix if dominant color is darker than secondary color
+    if (isLight(color(backgroundColor))) {
+        mixRedComponent = !mixRedComponent;
+        mixGreenComponent = !mixGreenComponent;
+        mixBlueComponent = !mixBlueComponent;
+    }
+    const factor = 1 - Math.abs(amount);
+    const red = mixRedComponent ? Math.round(interpolate(primaryColor.r, secondaryColor.r)(factor)) : primaryColor.r;
+    const green = mixGreenComponent ? Math.round(interpolate(primaryColor.g, secondaryColor.g)(factor)) : primaryColor.g;
+    const blue = mixBlueComponent ? Math.round(interpolate(primaryColor.b, secondaryColor.b)(factor)) : primaryColor.b;
+    return ((_a = color(`rgb(${red}, ${green}, ${blue})`)) === null || _a === void 0 ? void 0 : _a.toString()) || '';
+};
+export { blend, brighten, darken, isLight, interpolate };

package/lib/heatmap/helpers/text.d.ts

@@ -0,0 +1,26 @@
+import type { HeatmapCell } from './types';
+declare const MIN_FONT_SIZE = 10;
+declare const MAX_FONT_SIZE = 16;
+/**
+ * Calculate responsive font size according to the screen width
+ * @param ratio font ratio
+ * @param cellHeight cell's height
+ * @param cellWidth cell's width
+ * @returns font size
+ */
+declare const getResponsiveFontSize: (ratio: number, cellHeight: number, cellWidth: number) => number;
+/**
+ * Get maximum text width out of all the cell by sampling
+ * @param ctx canvas context
+ * @param cells list of cells
+ * @param hasCellHeader if header property is present in the cell
+ * @returns label width measured in canvas
+ */
+declare const getMaximumTextWidth: (ctx: CanvasRenderingContext2D, cells: HeatmapCell[], hasCellHeader: boolean) => number;
+/**
+ * Calculate max length text for render Axis size
+ * @param labels array string text for calculate
+ * @returns max length text
+ */
+declare const getMaximumLabelTextWidth: (labels: string[]) => string;
+export { getResponsiveFontSize, getMaximumTextWidth, getMaximumLabelTextWidth, MIN_FONT_SIZE, MAX_FONT_SIZE };

package/lib/heatmap/helpers/text.js

@@ -0,0 +1,91 @@
+const MIN_FONT_SIZE = 10;
+const MAX_FONT_SIZE = 16;
+/**
+ * Calculate responsive font size according to the screen width
+ * @param ratio font ratio
+ * @param cellHeight cell's height
+ * @param cellWidth cell's width
+ * @returns font size
+ */
+const getResponsiveFontSize = (ratio, cellHeight, cellWidth) => {
+    let fontSize = Math.round(Math.min(cellHeight, cellWidth) * ratio);
+    if (fontSize < MIN_FONT_SIZE) {
+        fontSize = MIN_FONT_SIZE;
+    }
+    else if (fontSize > MAX_FONT_SIZE) {
+        fontSize = MAX_FONT_SIZE;
+    }
+    return fontSize;
+};
+/**
+ * Get maximum text width out of all the cell by sampling
+ * @param ctx canvas context
+ * @param cells list of cells
+ * @param hasCellHeader if header property is present in the cell
+ * @returns label width measured in canvas
+ */
+const getMaximumTextWidth = (ctx, cells, hasCellHeader) => {
+    let maxHeaderLength = 0;
+    let maxLabelLength = 0;
+    const SAMPLE_AMOUNT = 5;
+    for (let i = 0; i < cells.length; i++) {
+        const header = cells[i].header || '';
+        const label = cells[i].customLabel || cells[i].label || '';
+        if (label.length > maxLabelLength) {
+            maxLabelLength = label.length;
+        }
+        if (header && header.length > maxHeaderLength) {
+            maxHeaderLength = header.length;
+        }
+    }
+    const textSamples = [];
+    const labelMap = {};
+    const headerMap = {};
+    for (let i = 0; i < cells.length; i++) {
+        const header = cells[i].header || '';
+        const label = cells[i].customLabel || cells[i].label || '';
+        const headerLength = header.length;
+        const labelLength = label.length;
+        if (labelLength >= maxLabelLength - 1) {
+            // Count number of times per label length
+            labelMap[labelLength] = labelMap[labelLength] ? labelMap[labelLength] + 1 : 1;
+            if (labelMap[labelLength] < SAMPLE_AMOUNT) {
+                textSamples.push(label);
+            }
+        }
+        if (hasCellHeader && headerLength >= maxHeaderLength - 1) {
+            // Count number of times per header length
+            headerMap[headerLength] = headerMap[headerLength] ? headerMap[headerLength] + 1 : 1;
+            if (headerMap[headerLength] < SAMPLE_AMOUNT) {
+                textSamples.push(header);
+            }
+        }
+    }
+    // Find maximum label width
+    let maxTextWidth = 0;
+    for (let i = 0; i < textSamples.length; i++) {
+        const textWidth = ctx.measureText(textSamples[i]).width;
+        if (textWidth > maxTextWidth) {
+            maxTextWidth = textWidth;
+        }
+    }
+    return maxTextWidth;
+};
+/**
+ * Calculate max length text for render Axis size
+ * @param labels array string text for calculate
+ * @returns max length text
+ */
+const getMaximumLabelTextWidth = (labels) => {
+    let maxLengthText = '';
+    for (let i = 0; i < labels.length; i++) {
+        if (maxLengthText.length >= labels[i].length) {
+            maxLengthText = maxLengthText;
+        }
+        else {
+            maxLengthText = labels[i];
+        }
+    }
+    return maxLengthText;
+};
+export { getResponsiveFontSize, getMaximumTextWidth, getMaximumLabelTextWidth, MIN_FONT_SIZE, MAX_FONT_SIZE };

package/lib/heatmap/helpers/track.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Utility class use for calculating :
+ *
+ * Track - the whole container
+ * Lane - each blocks inside the track
+ * Content - content that lies inside the lane
+ */
+export declare class Track {
+    private _laneSizes;
+    private _laneStarts;
+    private _trackSize;
+    private _margin;
+    /**
+     * Get track size
+     * @returns track size
+     */
+    get trackSize(): number;
+    /**
+     * Sets track size
+     * @param value number of track size
+     */
+    set trackSize(value: number);
+    /**
+     * Get lane count
+     * @returns lane count
+     */
+    get laneCount(): number;
+    /**
+     * Sets lane count
+     * @param value number of lane count
+     */
+    set laneCount(value: number);
+    /**
+     * Get margin
+     * @returns margin in pixel
+     */
+    get margin(): number;
+    /**
+     * Sets cells margin
+     * @param value number margin
+     */
+    set margin(value: number);
+    /**
+     * Initialise track
+     * @param trackSize track size
+     * @param laneCount lane count
+     * @returns {void}
+     */
+    init(trackSize: number, laneCount: number): void;
+    /**
+     * Get lane start
+     * @returns lane start position in pixel
+     */
+    get laneStarts(): number[];
+    /**
+     * Get lane size
+     * @returns lane size in pixel
+     */
+    get laneSizes(): number[];
+    /**
+     * Get lane size
+     * @param index of lane Array
+     * @returns lane start position in pixel
+     */
+    private getLaneSize;
+    /**
+     * Get lane start position
+     * @param index of lane Array
+     * @returns lane start position in pixel
+     */
+    private getLaneStart;
+    /**
+     * Get lane end position
+     * @param index of lane Array
+     * @returns lane end position in pixel
+     */
+    private getLaneEnd;
+    /**
+     * Get content size
+     * @param index of lane Array
+     * @returns content size in pixel
+     */
+    getContentSize(index: number): number;
+    /**
+     * Get content start position
+     * @param index of lane Array
+     * @returns content position in pixel
+     */
+    getContentStart(index: number): number;
+    /**
+     * Get content end position
+     * @param index of lane Array
+     * @returns content position in pixel
+     */
+    getContentEnd(index: number): number;
+    /**
+     * Finds lane's index using the mouse position in pixel
+     * @param mousePixel current mouse position in pixel
+     * @returns index of the lane
+     */
+    hitTest(mousePixel: number): number;
+}

package/lib/heatmap/helpers/track.js

@@ -0,0 +1,160 @@
+/**
+ * Utility class use for calculating :
+ *
+ * Track - the whole container
+ * Lane - each blocks inside the track
+ * Content - content that lies inside the lane
+ */
+export class Track {
+    constructor() {
+        this._laneSizes = [];
+        this._laneStarts = [0];
+        this._trackSize = 0;
+        this._margin = 0.5;
+    }
+    /**
+     * Get track size
+     * @returns track size
+     */
+    get trackSize() {
+        return this._trackSize;
+    }
+    /**
+     * Sets track size
+     * @param value number of track size
+     */
+    set trackSize(value) {
+        this.init(value, this.laneCount);
+    }
+    /**
+     * Get lane count
+     * @returns lane count
+     */
+    get laneCount() {
+        return this.laneSizes.length;
+    }
+    /**
+     * Sets lane count
+     * @param value number of lane count
+     */
+    set laneCount(value) {
+        this.init(this.trackSize, value);
+    }
+    /**
+     * Get margin
+     * @returns margin in pixel
+     */
+    get margin() {
+        return this._margin;
+    }
+    /**
+     * Sets cells margin
+     * @param value number margin
+     */
+    set margin(value) {
+        this._margin = value;
+    }
+    /**
+     * Initialise track
+     * @param trackSize track size
+     * @param laneCount lane count
+     * @returns {void}
+     */
+    init(trackSize, laneCount) {
+        this._trackSize = trackSize;
+        this._laneSizes = [laneCount];
+        this._laneStarts = [laneCount]; // For easy hit testing
+        this._laneStarts[0] = 0;
+        if (trackSize && laneCount) {
+            let start = 0;
+            const laneSize = (trackSize / laneCount);
+            for (let i = 0; i < laneCount; ++i) {
+                const end = start + laneSize;
+                this._laneStarts[i] = (start | 0);
+                this._laneSizes[i] = (end | 0) - (start | 0);
+                start = end;
+            }
+        }
+    }
+    /**
+     * Get lane start
+     * @returns lane start position in pixel
+     */
+    get laneStarts() {
+        return this._laneStarts;
+    }
+    /**
+     * Get lane size
+     * @returns lane size in pixel
+     */
+    get laneSizes() {
+        return this._laneSizes;
+    }
+    /**
+     * Get lane size
+     * @param index of lane Array
+     * @returns lane start position in pixel
+     */
+    getLaneSize(index) {
+        return this.laneSizes[index] || 0;
+    }
+    /**
+     * Get lane start position
+     * @param index of lane Array
+     * @returns lane start position in pixel
+     */
+    getLaneStart(index) {
+        return this._laneStarts[index] || 0;
+    }
+    /**
+     * Get lane end position
+     * @param index of lane Array
+     * @returns lane end position in pixel
+     */
+    getLaneEnd(index) {
+        return this.getLaneStart(index) + this.getLaneSize(index);
+    }
+    /**
+     * Get content size
+     * @param index of lane Array
+     * @returns content size in pixel
+     */
+    getContentSize(index) {
+        const contentSize = this.getLaneSize(index) - this._margin - this._margin;
+        return (contentSize > 0) ? contentSize : 0;
+    }
+    /**
+     * Get content start position
+     * @param index of lane Array
+     * @returns content position in pixel
+     */
+    getContentStart(index) {
+        return this.getLaneStart(index) + this._margin;
+    }
+    /**
+     * Get content end position
+     * @param index of lane Array
+     * @returns content position in pixel
+     */
+    getContentEnd(index) {
+        return this.getContentStart(index) + this.getContentSize(index);
+    }
+    /**
+     * Finds lane's index using the mouse position in pixel
+     * @param mousePixel current mouse position in pixel
+     * @returns index of the lane
+     */
+    hitTest(mousePixel) {
+        const laneSize = this.trackSize / this.laneCount;
+        let index = Math.floor(mousePixel / laneSize);
+        if (index >= 0 && index < this.laneCount) {
+            if (mousePixel < this.getContentStart(index) || mousePixel >= this.getContentEnd(index)) {
+                index = -1;
+            }
+        }
+        else {
+            index = -1;
+        }
+        return index;
+    }
+}