@hestia-earth/ui-components-charts 0.43.23

package/dist/index.d.ts

@@ -0,0 +1,368 @@
+import * as chart_js from 'chart.js';
+import { ChartDataset, Chart, BarOptions, Plugin, ChartEvent, Color, Scale } from 'chart.js';
+import { IImpactAssessmentJSONLD } from '@hestia-earth/schema';
+
+interface BarChartDataItem {
+    label?: string;
+    count?: number;
+    color?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    includedItems?: BarChartDataItem[];
+}
+declare const defaultBarSettings: Readonly<{
+    type: "bar";
+    options: {
+        animation: {
+            duration: number;
+        };
+        plugins: {
+            legend: {
+                align: "start";
+            };
+            tooltip: {
+                enabled: false;
+            };
+        };
+        scales: {
+            x: {
+                display: true;
+                min: number;
+                title: {
+                    display: false;
+                    color: string;
+                    font: {
+                        family: string;
+                        size: number;
+                    };
+                };
+                ticks: {
+                    font: {
+                        family: string;
+                        size: number;
+                    };
+                };
+            };
+            y: {
+                display: true;
+                position: "left";
+                border: {
+                    display: true;
+                };
+                grid: {
+                    display: true;
+                    drawOnChartArea: true;
+                    drawTicks: true;
+                    tickLength: number;
+                    offset: false;
+                };
+                ticks: {
+                    color: string;
+                    padding: number;
+                    crossAlign: "center";
+                    font: {
+                        weight: number;
+                        family: string;
+                        size: number;
+                    };
+                    callback: (this: chart_js.Scale, value: string | number) => string;
+                };
+            };
+        };
+    };
+}>;
+declare const defaultBarDatasets: Partial<ChartDataset>;
+/**
+ * The first `maximum` items, and one more summing the rest as "N others", which lists them as its own items.
+ */
+declare const withOthers: (data: BarChartDataItem[], maximum: number) => BarChartDataItem[];
+declare const hasNegativeContributions: (data?: BarChartDataItem[]) => boolean;
+/**
+ * The one dataset drawn from the items, coloured per item; negative values become `0` unless shown.
+ */
+declare const barDataset: (data: BarChartDataItem[], label?: string, showNegativeValues?: boolean) => ChartDataset;
+
+declare enum ColorPalette {
+    categorial = 0,
+    continuous = 1,
+    divergent = 2
+}
+declare const getColor: (index: number, scheme?: ColorPalette) => string;
+declare const listColor: <T>(_v: T, index: number) => string;
+declare const listColorContinuous: <T>(_v: T, index: number) => string;
+interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+declare const parseColor: (color: string) => RgbColor;
+declare const colorToRgba: (color: RgbColor, aplha: number) => string;
+declare const hexToRgba: (hex: string, aplha?: number) => string;
+declare const listColorWithAlpha: (alpha?: number) => <T>(_v: T, index: number) => string;
+
+declare const defaultTicksFont: {
+    family: string;
+    size: number;
+};
+/**
+ * Maximum length of an axis label, past which the charts truncate it.
+ */
+declare const chartLabelMaxLength = 50;
+
+interface ContributionChartDataItem {
+    id?: string;
+    label: string;
+    values: number[];
+    color?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    includedItems?: ContributionChartDataItem[];
+}
+interface ContributionTooltipData {
+    label: string;
+    units: string;
+    values: (ContributionChartDataItem & {
+        value: number;
+    })[];
+    selectedLabel?: string;
+}
+/**
+ * The subset of the `CyclesEmissionsCategoryService` needed to group the data.
+ */
+interface IContributionCategory {
+    emissionCategoryValue: (emissionId: string, category: string) => string;
+    categoryLabel: (key: string) => string;
+}
+/**
+ * Sum the values of every item of a group, skipping the items without a value at this index.
+ *
+ * An item has no value when the Node does not contain that Emission at all, which is not the same as a `0` value:
+ * summing it as `NaN` would silently hide the whole group from the chart. When no item of the group has a value,
+ * `undefined` is returned so the chart displays "No data", like it does when the data is not grouped.
+ *
+ * @param values The values of every item of the group, at a single index.
+ * @returns The sum, or `undefined` when no item has a value.
+ */
+declare const sumValues: (values: number[]) => number;
+/**
+ * Group the contribution data by Category, summing the values of every Emission of the same Category.
+ *
+ * @param data The contribution data, one item per Emission.
+ * @param labels The labels of the chart, one per Node compared.
+ * @param category The Category to group by. When empty, the data is returned as-is.
+ * @param service Used to resolve the Category of an Emission and its label.
+ * @returns The data grouped by Category, or the original data when grouping is not needed.
+ */
+declare const groupDataByCategory: (data: ContributionChartDataItem[], labels: string[], category: string, { emissionCategoryValue, categoryLabel }: IContributionCategory) => ContributionChartDataItem[];
+
+declare const escape: (value: string) => string;
+declare const toLine: (values: any[]) => string;
+
+interface IEmissionCategory {
+    key: string;
+    label: string;
+}
+declare const categoryLabel: (key: string) => string;
+/**
+ * The list of all available categories.
+ */
+declare const emissionCategories: IEmissionCategory[];
+/**
+ * Return all possible values for a specific Category.
+ *
+ * @param category {string} The specific category
+ * @returns List of all values possible for this Category.
+ */
+declare const categoryValues: (category: string) => string[];
+/**
+ * Return the different categories available for a single Emission.
+ *
+ * @param emissionId The `@id` of the Emission
+ * @returns List of categories.
+ */
+declare const emissionCategoriesOf: (emissionId: string) => string[];
+/**
+ * Return the Category value for a specific Emission and Category.
+ *
+ * @param emissionId  The `@id` of the Emission
+ * @param category The Category
+ * @returns The value
+ */
+declare const emissionCategoryValue: (emissionId: string, category: string) => string;
+
+declare const defaultHorizontalBarConfig: Readonly<{
+    options: {
+        indexAxis: "y";
+        scales: {
+            x: {
+                grid: {
+                    drawOnChartArea: false;
+                };
+                ticks: {
+                    callback: (this: chart_js.Scale, value: string | number) => number;
+                };
+            };
+            y: {
+                grid: {
+                    drawOnChartArea: false;
+                };
+                ticks: {
+                    crossAlign: "near";
+                };
+            };
+        };
+    };
+}>;
+/** The text of the tooltip on one bar: its label and value, or every item it groups. */
+declare const defaultHorizontalTooltip: ({ label, count, includedItems }: BarChartDataItem) => string;
+/** The chart's height for this many bars, kept between the two bounds. */
+declare const horizontalBarHeight: (minHeight: number, maxHeight: number, nbRows: number) => number;
+
+type placement = 'left' | 'right';
+type positionFn = (n: number, index: number, width: number, chart: Chart, data?: number | number[], placement?: placement) => number;
+interface AfterBarDrawSettings {
+    placement?: placement;
+    xPosFn?: positionFn;
+    yPosFn?: positionFn;
+    colorFn?: (m: BarOptions, index: number, chart: Chart, data?: number) => string;
+    textFn?: (m: {
+        label: string;
+        data: number | number[];
+    }, index: number, chart: Chart) => string | [string, string];
+    font?: string;
+    maxWidth?: number;
+    emptyValueLabel?: string;
+}
+declare const afterBarDrawPlugin: (settings?: AfterBarDrawSettings) => Plugin;
+
+interface AxisLabelEvent {
+    label: string;
+    index: number;
+    /**
+     * The middle of the label column at the bottom edge of the row — the point a tooltip should hang
+     * off. Anchoring on the pointer instead puts the tooltip on the label being read, because a row
+     * is entered at the top of its hit band when the pointer is moving down.
+     */
+    anchorX: number;
+    anchorY: number;
+    event: ChartEvent;
+}
+interface AxisHoverSettings {
+    onHoverLabel?: (data: AxisLabelEvent) => void;
+    onClickLabel?: (data: AxisLabelEvent) => void;
+    maxDistance?: number;
+}
+/**
+ * Hover handler turning the pointer into a cursor over a clickable axis label.
+ */
+declare const axisLabelCursor: ({ label, event }: AxisLabelEvent) => void;
+declare const axisHoverPlugin: Plugin;
+
+interface IBackgroundHoverSettings {
+    threshold?: number;
+}
+declare const backgroundHoverPlugin: (settings?: IBackgroundHoverSettings) => {
+    id: string;
+    afterEvent: (chart: Chart, args: {
+        event: ChartEvent;
+        changed?: boolean;
+    }) => void;
+    beforeDraw: (chart: Chart) => void;
+};
+
+type colorFn = (m: BarOptions, index: number) => Color;
+type positionIndexFn = (x: number, y: number) => number;
+type isMouseInsideLollipopFn = (fn: positionIndexFn) => void;
+type valueFn = (dataset: ChartDataset, index: number, chart: Chart) => number | undefined | null;
+interface LollipopPluginSettings {
+    circleRadius?: number;
+    /**
+     * Use when connecting 2 lollipops.
+     */
+    lineWidth?: number;
+    colorFn?: colorFn;
+    isMouseInsideLollipopFn?: isMouseInsideLollipopFn;
+    /**
+     * By default, lollipops will be drawn where the value is (or start/end when 2 values are used).
+     * Use this function to return a specific value where the lollipop should be drawn.
+     */
+    valueFn?: valueFn;
+}
+declare const lollipopChartPlugin: (settings?: LollipopPluginSettings) => Plugin;
+
+declare const increaseScaleLimits: (scale: Scale, handleMinScaleZero?: boolean) => void;
+
+/** How much each indicator, by its position on the node, contributes to each other indicator, per method. */
+type contributions = Record<string, Record<string, number>>;
+/** The contributions file the engine writes beside an ImpactAssessment. */
+interface INodeContributions {
+    /**
+     * Contributions of each `emissionsResourceUse` to the `impacts`.
+     */
+    emissionsResourceUse: Record<string, contributions>;
+    /**
+     * Contributions of each `impacts` to the `endpoints`.
+     */
+    impacts: Record<string, contributions>;
+}
+/** One contribution of one indicator to another, by one method. */
+interface IContributionLog {
+    modelId: string;
+    impactTermId: string;
+    impactTermUnits?: string;
+    blankNodeTermId: string;
+    value: number;
+    name?: string;
+    color?: string;
+    inputs?: string[];
+}
+declare const logsTotalValue: (logs: IContributionLog[], includeNegativeValues?: boolean) => number;
+declare const valueRatio: (value: number, total: number) => number;
+declare const chartLabel: (value: number, total: number) => string;
+declare const chartBreakdownLabel: (logs: IContributionLog[], total: number, maxValues: number) => string;
+declare const logToCsv: (logs: IContributionLog[], impact: IImpactAssessmentJSONLD) => string;
+/**
+ * Every contribution in the file, joined back to the indicators at the positions it is keyed by: the
+ * emissions and resource uses to the impacts, and the impacts to the endpoints.
+ */
+declare const parseContributions: (impactAssessment: IImpactAssessmentJSONLD, contributions: INodeContributions) => IContributionLog[];
+/** One contribution per contributor: its methods' values summed, its inputs merged. */
+declare const groupLogsById: (logs: IContributionLog[]) => IContributionLog[];
+/** The contributions to one indicator, by one method when one is given. */
+declare const indicatorLogs: (logs: IContributionLog[], termId: string, methodId?: string) => IContributionLog[];
+/** The contributors to show: one each, without those contributing nothing. */
+declare const nonZeroContributors: (logs: IContributionLog[]) => IContributionLog[];
+/** Each contributor with the name to show and its colour, in the order given. */
+declare const namedContributors: (logs: IContributionLog[], nameOf: (termId: string) => string | undefined) => {
+    name: string;
+    color: string;
+    modelId: string;
+    impactTermId: string;
+    impactTermUnits?: string;
+    blankNodeTermId: string;
+    value: number;
+    inputs?: string[];
+}[];
+/**
+ * The bars, largest first: one per contributor, or with a category, one per category value summing its
+ * contributors and listing them as its items. A category every contributor shares is no grouping at all.
+ */
+declare const breakdownBars: (values: IContributionLog[], category?: string) => BarChartDataItem[];
+/** What each bar says after it: its value, or its share of the total; the "others" bar names its value. */
+declare const breakdownBarText: (displayValue: boolean, total: number, maximumValues: number) => AfterBarDrawSettings;
+/** The tooltip of one bar: its value and share, or every contributor the "others" bar groups. */
+declare const breakdownTooltip: (item: BarChartDataItem | undefined, includedItems: BarChartDataItem[] | undefined, logs: IContributionLog[], total: number, maximumValues: number) => string;
+/** The x axis: from the most negative contribution, or zero, to the largest, with some room on each side. */
+declare const breakdownScale: (values: IContributionLog[]) => {
+    options: {
+        scales: {
+            x: {
+                afterDataLimits: (scale: chart_js.Scale<chart_js.CoreScaleOptions>) => void;
+                min: number;
+                max: number;
+            };
+        };
+    };
+};
+
+export { type AfterBarDrawSettings, type AxisHoverSettings, type AxisLabelEvent, type BarChartDataItem, ColorPalette, type ContributionChartDataItem, type ContributionTooltipData, type IContributionCategory, type IContributionLog, type IEmissionCategory, type INodeContributions, type LollipopPluginSettings, type RgbColor, afterBarDrawPlugin, axisHoverPlugin, axisLabelCursor, backgroundHoverPlugin, barDataset, breakdownBarText, breakdownBars, breakdownScale, breakdownTooltip, categoryLabel, categoryValues, chartBreakdownLabel, chartLabel, chartLabelMaxLength, colorToRgba, type contributions, defaultBarDatasets, defaultBarSettings, defaultHorizontalBarConfig, defaultHorizontalTooltip, defaultTicksFont, emissionCategories, emissionCategoriesOf, emissionCategoryValue, escape, getColor, groupDataByCategory, groupLogsById, hasNegativeContributions, hexToRgba, horizontalBarHeight, increaseScaleLimits, indicatorLogs, listColor, listColorContinuous, listColorWithAlpha, logToCsv, logsTotalValue, lollipopChartPlugin, namedContributors, nonZeroContributors, parseColor, parseContributions, sumValues, toLine, valueRatio, withOthers };