@refinitiv-ui/elements 5.3.3 → 5.7.0

package/lib/chart/helpers/legend.js

@@ -0,0 +1,78 @@
+/**
+ * Validate color
+ *
+ * @param {ChartDataSetsColor} color datsets color
+ * @returns {(string|undefined)} color
+ */
+const isValidColor = (color) => {
+    /**
+     * Force return to string type because Chart.js doesn't support typescript
+     * and some type of @types/chart.js isn't correct
+     */
+    return (color && color !== 'transparent') ? color : undefined;
+};
+/**
+ * Get legend color by using point style
+ *
+ * @param {ChartDataSetsColor} color1 using color1 if valid
+ * @param {ChartDataSetsColor} color2 using color2 if color1 invalid
+ * @returns {(string|undefined)} color
+ */
+const getLegendColorUsePointStyle = (color1, color2) => {
+    /**
+     * if either color1 or color2 is valid, use color1. Order is important
+     * and force return string type same as isValidColor()
+     */
+    return isValidColor(color1) || (isValidColor(color2) ? color1 : undefined);
+};
+/**
+ * Get legend color don't using point style
+ *
+ * @param {Chart.ChartDataSets} dataset dataset of chart
+ * @param {boolean} solidFill color is solid not opaque
+ * @returns {string} color
+ */
+const getLegendColorDontUsePointStyle = (dataset, solidFill = false) => {
+    // Use background color for legend, if color of dataset or chart type is solid not opaque.
+    return isValidColor(solidFill ? dataset.backgroundColor : dataset.borderColor)
+        || isValidColor(dataset.pointBorderColor)
+        || dataset.pointBackgroundColor;
+};
+/**
+ * Get stroke style legend color
+ *
+ * @param {Chart.ChartDataSets} dataset dataset of chart
+ * @param {boolean} usePointStyle using color from point style
+ * @returns {(string|undefined)} color
+ */
+const getLegendStrokeStyle = (dataset, usePointStyle) => {
+    if (usePointStyle) {
+        return getLegendColorUsePointStyle(dataset.pointBorderColor, dataset.pointBackgroundColor)
+            || isValidColor(dataset.borderColor) || dataset.backgroundColor;
+    }
+    else {
+        return isValidColor(dataset.borderColor) || getLegendColorDontUsePointStyle(dataset);
+    }
+};
+/**
+ * Get fill style legend color
+ *
+ * @param {Chart.ChartDataSets} dataset dataset of chart
+ * @param {boolean} usePointStyle using color from point style
+ * @param {boolean} solidFill color is solid or opacity
+ * @returns {(string|undefined)} color
+ */
+const getLegendFillStyle = (dataset, usePointStyle, solidFill = false) => {
+    if (usePointStyle) {
+        return getLegendColorUsePointStyle(dataset.pointBackgroundColor, dataset.pointBorderColor)
+            || isValidColor(dataset.borderColor) || dataset.backgroundColor;
+    }
+    else {
+        return getLegendColorDontUsePointStyle(dataset, solidFill);
+    }
+};
+const legendHelper = {
+    getLegendFillStyle,
+    getLegendStrokeStyle
+};
+export { legendHelper };

package/lib/chart/helpers/merge.d.ts

@@ -0,0 +1,15 @@
+declare type UnknownObject = {
+    [key: string]: unknown;
+};
+declare type MergeObject = UnknownObject | Array<unknown>;
+/**
+ * Merge objects recursively
+ *
+ * @param {MergeObject} object The destination object.
+ * @param {MergeObject} sources The source objects.
+ * @param {boolean} force Force merge if a key of destination object is already exists and a value is not object
+ * @param {MergeObject[]} record The record object which record merged objects recursively
+ * @returns voids
+ */
+declare const merge: (object: MergeObject, sources: MergeObject, force?: boolean, record?: Array<unknown>) => void;
+export { merge, MergeObject };

package/lib/chart/helpers/merge.js

@@ -0,0 +1,28 @@
+/**
+ * Merge objects recursively
+ *
+ * @param {MergeObject} object The destination object.
+ * @param {MergeObject} sources The source objects.
+ * @param {boolean} force Force merge if a key of destination object is already exists and a value is not object
+ * @param {MergeObject[]} record The record object which record merged objects recursively
+ * @returns voids
+ */
+const merge = (object, sources, force = false, record = []) => {
+    let value;
+    let isObject;
+    Object.keys(sources).forEach((key, i) => {
+        // Get value and info from merging object
+        value = Array.isArray(sources) ? sources[i] : sources[key];
+        isObject = (value && typeof value === 'object' && value.toString() === '[object Object]');
+        // Merge if found a new key from source or has a force command
+        if (!(key in object) || (force && !isObject)) {
+            object[key] = value;
+        }
+        // Deep merge objects
+        if (isObject && !record.includes(value)) {
+            record.push(value);
+            merge(object[key], value, force, record);
+        }
+    });
+};
+export { merge };

package/lib/chart/helpers/types.d.ts

@@ -0,0 +1,69 @@
+/// <reference types="chart.js" />
+export declare type DatasetColors = {
+    solid: string | string[];
+    opaque: string | string[];
+};
+export declare type ChartDataSetsColor = Chart.ChartColor | Chart.ChartColor[] | Chart.Scriptable<Chart.ChartColor> | undefined;
+export declare type ChartConfig = Chart.ChartConfiguration;
+export declare type ChartUpdateProps = Chart.ChartUpdateProps;
+export interface MetaData {
+    _chart: Chart;
+    _datasetIndex: number;
+    _index: number;
+    _model: Model;
+    _view: Model;
+    _xScale: Chart.ChartScales;
+    _yScale: Chart.ChartScales;
+    hidden?: boolean;
+}
+interface Model {
+    backgroundColor: string;
+    borderAlign?: Chart.BorderAlignment;
+    borderColor: string;
+    borderWidth?: number;
+    circumference?: number;
+    controlPointNextX: number;
+    controlPointNextY: number;
+    controlPointPreviousX: number;
+    controlPointPreviousY: number;
+    endAngle?: number;
+    hitRadius: number;
+    innerRadius?: number;
+    outerRadius?: number;
+    pointStyle: string;
+    radius: string;
+    skip?: boolean;
+    startAngle?: number;
+    steppedLine?: undefined;
+    tension: number;
+    x: number;
+    y: number;
+    base: number;
+    head: number;
+}
+export interface ChartHelpers {
+    draw(): void;
+}
+export interface ChartJS extends Chart {
+    new (context: string | CanvasRenderingContext2D | HTMLCanvasElement | ArrayLike<CanvasRenderingContext2D | HTMLCanvasElement>, options: ChartConfig): Chart;
+    defaults: {
+        global: Chart.ChartOptions & Chart.ChartFontOptions & {
+            tooltips: Chart.ChartTooltipOptions;
+            defaultColor: string;
+            defaultLineHeight: number;
+        };
+        scale: {
+            gridLines: {
+                color: string;
+                zeroLineColor: string;
+            };
+        };
+        [key: string]: any;
+    };
+    helpers: {
+        getHoverColor(value: string): string;
+        [key: string]: any;
+    };
+    isDatasetVisible(isDatasetVisible: number): boolean;
+}
+export {};

package/lib/chart/helpers/types.js

@@ -0,0 +1 @@
+export {};

package/lib/chart/index.d.ts

@@ -0,0 +1,187 @@
+import { JSXInterface } from '../jsx';
+/// <reference types="chart.js" />
+import { BasicElement, PropertyValues, TemplateResult, CSSResultGroup } from '@refinitiv-ui/core';
+import 'chart.js/dist/Chart.bundle.min.js';
+import type { ChartJS, ChartConfig, ChartUpdateProps, DatasetColors } from './helpers/types';
+import type { Header } from '../header';
+import '../header/index.js';
+import '../layout/index.js';
+declare global {
+    interface Window {
+        Chart: ChartJS;
+    }
+}
+export type { ChartConfig, ChartUpdateProps };
+/**
+ * Charting component that use ChartJS library
+ */
+export declare class Chart extends BasicElement {
+    /**
+     * Element version number
+     * @returns version number
+     */
+    static get version(): string;
+    /**
+     * Chart.js object
+     */
+    private chart;
+    /**
+     * Chart configurations. Same configuration as ChartJS
+     * @type {ChartConfig}
+     */
+    config: ChartConfig | null;
+    /**
+     * Html canvas element
+     * @type {HTMLCanvasElement}
+     */
+    protected canvas: HTMLCanvasElement;
+    /**
+     * Get canvas element from shadow roots
+     */
+    protected titleElement: Header;
+    /**
+     * Required properties, needed for chart to work correctly.
+     * @returns config
+     */
+    protected get requiredConfig(): ChartConfig;
+    /**
+     * Safely returns the chart title
+     * @returns chart title
+     */
+    protected get chartTitle(): string;
+    /**
+     * Safely returns a dataset array
+     * @returns dataset array
+     */
+    protected get datasets(): Chart.ChartDataSets[];
+    /**
+     * List of available chart colors
+     * @type {string[]}
+     * @returns {string[]} List of available chart colors
+     */
+    get colors(): string[];
+    /**
+     * Invoked whenever the element is updated
+     * @param {PropertyValues} changedProperties Map of changed properties with old values
+     * @returns {void}
+     */
+    protected updated(changedProperties: PropertyValues): void;
+    /**
+     * Element connected
+     * @returns {void}
+     */
+    connectedCallback(): void;
+    /**
+     * Element disconnected
+     * @returns {void}
+     */
+    disconnectedCallback(): void;
+    /**
+     * Themable parts of the config.
+     * This will be merged into the configuration object.
+     * @returns {ChartConfig} chart config with theme
+     */
+    protected get themableConfig(): ChartConfig;
+    /**
+     * Handles a change of configuration object.
+     * This does not fire when a property of the config object changes,
+     * for this use this.updateChart() to apply changes.
+     * @returns {void}
+     */
+    protected onConfigChange(): void;
+    /**
+     * Get as CSS variable and tries to convert it into a usable number
+     * @returns {(number|undefined)} The value as a number, or, undefined if NaN.
+     */
+    protected cssVarAsNumber(...args: string[]): number | undefined;
+    /**
+     * Generates the legend labels on a given chart
+     * @param {ChartJS} chart Chart.js instance
+     * @returns {Chart.ChartLegendLabelItem[]} Array of label configurations
+     */
+    protected generateLegendLabels: (chart: ChartJS) => Chart.ChartLegendLabelItem[];
+    /**
+     * Merges all the different layers of the config.
+     * @returns {void}
+     */
+    protected mergeConfigs(): void;
+    /**
+     * Themes the passed-in configuration object
+     * @returns {void}
+     */
+    protected decorateConfig(): void;
+    /**
+     * Returns usable information about a dataset
+     * @param {Chart.ChartDataSets} dataset Chart dataset
+     * @returns {Chart.ChartDataSets} Information about the dataset
+     */
+    protected datasetInfo(dataset: Chart.ChartDataSets): Chart.ChartDataSets;
+    /**
+     * Generates internal solid and opaque color set for a dataset
+     * @param {boolean} isArray Flag to return result in array or not e.g. doughnut, pie, etc
+     * @param {number} amount Amount of colors required
+     * @param {number} shift Positional shift of the color start point
+     * @returns {DatasetColors} Solid and opaque color values
+     */
+    protected generateColors(isArray: boolean, amount: number, shift: number): DatasetColors;
+    /**
+     * Manages the custom title element
+     * @returns {void}
+     */
+    private manageTitle;
+    /**
+     * Creates a chart after config has changed,
+     * or, the element has been connected to the DOM
+     * @returns {void}
+     */
+    protected createChart(): void;
+    /**
+     * Destroys the chart.js object
+     * @returns True if a chart object has been destroyed
+     */
+    protected destroyChart(): boolean;
+    /**
+     * Re-renders the chart based on its config
+     * @param {ChartUpdateProps} config Additional configuration object for the update process.
+     * @returns {void}
+     */
+    private renderChart;
+    /**
+     * Update all data, title, scales, legends and re-render the chart based on its config
+     * @param {ChartUpdateProps=} config Additional configuration for control an animation in the update process.
+     * @returns {void}
+     */
+    updateChart(config?: ChartUpdateProps): void;
+    /**
+     * A `CSSResultGroup` that will be used
+     * to style the host, slotted children
+     * and the internal template of the element.
+     * @return CSS template
+     */
+    static get styles(): CSSResultGroup;
+    /**
+     * Handles resize event of the chart region
+     * @returns {void}
+     */
+    protected onResize(): void;
+    /**
+     * A `TemplateResult` that will be used
+     * to render the updated internal template.
+     * @return Render template
+     */
+    protected render(): TemplateResult;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ef-chart': Chart;
+  }
+
+  namespace JSX {
+    interface IntrinsicElements {
+      'ef-chart': Partial<Chart> | JSXInterface.HTMLAttributes<Chart>;
+    }
+  }
+}
+
+export {};