@visuallyjs/browser-ui 1.0.0

package/types/charts/plot.d.ts

@@ -0,0 +1,75 @@
+import { XYChart } from "./base-xy-chart";
+import { ChartSVGElement } from "./util";
+import { ChartDimensions } from "./definitions";
+import { DomainExtentMap } from "./domain_scale_utilities";
+/**
+ * Base interface for plots. This interface is a placeholder and defines no properties.
+ * @group Charts
+ * @category Definitions
+ * @internal
+ */
+export interface Plot {
+}
+/**
+ * Definition of a plot: a type, some options (the type of which varies based on the type of the plot), and the ID of the value axis the plot represents.
+ * @group Charts
+ * @category Definitions
+ */
+export interface PlotDefinition {
+    type: string;
+    options?: any;
+    valueAxis?: string;
+}
+/**
+ * Base options for an XY plot
+ * @group Charts
+ * @category XY Chart
+ */
+export interface XYPlotOptions {
+    /**
+     * ID of the value axis to attach to. Defaults to `DEFAULT`.
+     */
+    valueAxis?: string;
+}
+/**
+ * Base class for XY plots.
+ * @group Charts
+ * @category XY Chart
+ */
+export declare abstract class XYPlot implements Plot {
+    chart: XYChart<any>;
+    type: string;
+    $valueAxis: string;
+    protected constructor(chart: XYChart<any>, options: XYPlotOptions, type: string);
+    abstract $draw(svgRoot: ChartSVGElement, dim: ChartDimensions, minPlottableValue: number, maxPlottableValue: number): void;
+    /**
+     * Return domain extents needed by this plot (e.g. {x:{min,max}, y:{min,max}}).
+     * Default: none.
+     *
+     * @internal
+     */
+    getDomainExtents(): DomainExtentMap;
+}
+/**
+ * This plot type expects a category axis and a value axis. It derives an `$inverted` flag by testing the $xAxisType against "value" - if true, not inverted, if false, inverted.
+ * @group Charts
+ */
+export declare abstract class CategoryVsAxisPlot extends XYPlot {
+    get $inverted(): boolean;
+}
+type PlotConstructor = (c: XYChart<any>, o: any) => XYPlot;
+/**
+ * @internal
+ * @param type
+ * @param c
+ */
+export declare function addXYPlotType(type: string, c: PlotConstructor): void;
+/**
+ * @internal
+ * @param type
+ * @param xy
+ * @param options
+ */
+export declare function createXYPlot(type: string, xy: XYChart<any>, options: any): XYPlot;
+export declare function isStackedPlot(pl: any): boolean;
+export {};

package/types/charts/sankey/index.d.ts

@@ -0,0 +1 @@
+export * from './sankey';

package/types/charts/sankey/preprocessor.d.ts

@@ -0,0 +1,37 @@
+import { DataSource, Edge, HierarchyLayoutLayerEntry, Size, Vertex } from "../../core";
+/**
+ * @internal
+ * @param edge
+ * @param valueProperty
+ */
+export declare function _getEdgeValue(edge: Edge, valueProperty: string): number;
+/** @internal */
+export interface SankeyLayerEntry extends HierarchyLayoutLayerEntry {
+    obj: Vertex;
+    id: string;
+    size: Size;
+    layer: number;
+    type: string;
+    edges: Array<Edge>;
+    vertexSet: any;
+    offset: number;
+}
+/** @internal */
+export interface SankeyLayer {
+    entries: Array<SankeyLayerEntry>;
+    size: number;
+    offset: number;
+    layer: number;
+}
+/**
+ * @internal
+ * @param model
+ * @param nodeWidth
+ * @param nodePadding
+ * @param width
+ * @param height
+ */
+export declare function preprocess(model: DataSource, nodeWidth: number, nodePadding: number, width: number, height: number, valueProperty: string): {
+    layers: SankeyLayer[];
+    scale: number;
+};

package/types/charts/sankey/sankey.d.ts

@@ -0,0 +1,208 @@
+import { SankeyLayer } from './preprocessor';
+import { Node, Edge, Vertex, DataSource, VisuallyJsDefaultJSON } from "../../core";
+import { BrowserElement, BrowserUIModel, FontSpec } from "../../browser-ui";
+import { ChartSVGElement } from "../util";
+import { BaseChart, BaseChartOptions } from "../base-chart";
+import { Tooltip, TooltipOptions } from "../tooltip";
+import { ChartDimensions } from "../definitions";
+/**
+ * Assigned to edges in Sankey chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context sankey
+ */
+export declare const CLASS_SANKEY_EDGE = "vjs-sankey-edge";
+/**
+ * Assigned to edges/nodes in Sankey chart when something is selected but this edge/node is not in the selected path
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context sankey
+ */
+export declare const CLASS_SANKEY_UNSELECTED = "vjs-sankey-unselected";
+/**
+ * Assigned to edges/nodes in Sankey chart when the edge/node forms part of the selected path.
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context sankey
+ */
+export declare const CLASS_SANKEY_SELECTED = "vjs-sankey-selected";
+/**
+ * Assigned to the sankey chart container
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context sankey
+ */
+export declare const CLASS_SANKEY_CHART = "vjs-sankey";
+/**
+ * Assigned to nodes in a sankey chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context sankey
+ */
+export declare const CLASS_SANKEY_NODE = "vjs-sankey-node";
+/**
+ * Assigned to labels in a sankey chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context sankey
+ */
+export declare const CLASS_SANKEY_LABEL = "vjs-sankey-label";
+/**
+ * Options for Sankey diagram
+ */
+export interface SankeyOptions extends Omit<BaseChartOptions, "data"> {
+    /**
+     * Strategy for link color: static uses a single color, source-target paints a gradient from source to target, target uses the target node color, source uses the source node color.
+     */
+    linkColorStrategy?: "static" | "source-target" | "target" | "source";
+    /**
+     * Link color to use when linkColorStrategy is 'static'. Defaults to "#444444"
+     */
+    linkColor?: string;
+    /**
+     * Width, in pixels, of nodes. Defaults to 15.
+     */
+    nodeWidth?: number;
+    /**
+     * Spacing, in pixels, between nodes. Defaults to 10.
+     */
+    nodePadding?: number;
+    /**
+     * Padding to leave around the chart. Defaults to 20 pixels.
+     */
+    padding?: number;
+    /**
+     * Defaults to true - the charts responds to mouse hover events and highlights edges, nodes and paths.
+     */
+    interactive?: boolean;
+    /**
+     * Options for the node labels.
+     */
+    labels?: {
+        /**
+         * Optional font spec to use for node labels. Defaults to 12px.
+         */
+        font?: FontSpec;
+        /**
+         * Optional padding to use for node labels. Defaults to 5 pixels.
+         */
+        padding?: number;
+        /**
+         * Optional background color to use for node labels. Defaults to "#FFFFFF56".
+         */
+        backgroundColor?: string;
+    };
+    /**
+     * Optional suffix to append to tooltip labels.
+     */
+    tooltipSuffix?: string;
+    /**
+     * Optional CSV data to load. Each line should be in the format `source,target,value`.
+     */
+    csvData?: string;
+    /**
+     * Optional dataset to load.
+     */
+    jsonData?: VisuallyJsDefaultJSON;
+    /**
+     * When using a data source, this property tells the chart which field contains edge values. It defaults to `value`.
+     */
+    valueProperty?: string;
+    /**
+     * When using a data source, this property tells the chart which field contains node labels. It defaults to `labels`. If there is no value provided for the property with this key, the node's ID is used as the label.
+     */
+    labelProperty?: string;
+    pivot?: string;
+}
+/**
+ * A Sankey chart visualizes data flow between nodes.
+ * @group Charts
+ * @category Sankey
+ */
+export declare class SankeyChart extends BaseChart {
+    linkColorStrategy: "static" | "source-target" | "target" | "source";
+    linkColor: string;
+    _nodeWidth: number;
+    _nodePadding: number;
+    _tooltipSuffix: string;
+    _model: BrowserUIModel;
+    _pivotModel: BrowserUIModel;
+    get currentModel(): BrowserUIModel;
+    _interactive: boolean;
+    _dataSource: DataSource;
+    _valueProperty: string;
+    _labelProperty: string;
+    _currentVertex: Node;
+    _currentEdges: Array<[Edge, ChartSVGElement]>;
+    _currentCluster: {
+        vertices: Array<Vertex>;
+        edges: Array<Edge>;
+    };
+    _edgeElements: Record<string, ChartSVGElement>;
+    _nodeElements: Record<string, ChartSVGElement>;
+    _labelElements: Record<string, ChartSVGElement>;
+    _labelBackgroundElements: Record<string, ChartSVGElement>;
+    _layers: Array<SankeyLayer>;
+    _pivotProperty: string;
+    _labelOptions: {
+        font: FontSpec;
+        padding: number;
+        backgroundColor: string;
+    };
+    $tooltip: SankeyTooltip;
+    private _assignLinkColor;
+    constructor(container: BrowserElement, options: SankeyOptions);
+    $drawDecoration(svgRoot: ChartSVGElement, width: number, height: number): ChartDimensions;
+    $drawChart(svgRoot: ChartSVGElement, width: number, height: number, backgroundElement: ChartSVGElement): void;
+    private nodeDecorator;
+    private edgeDecorator;
+    private _init;
+    private _loadPivotData;
+    private _loadFromDatasource;
+    /**
+     * Load data, either from a URL, CSV string, JS object or a DataSource.
+     * @param options
+     */
+    load(options: {
+        url?: string;
+        csvData?: string;
+        dataType?: string;
+        jsonData?: VisuallyJsDefaultJSON;
+    }): void;
+    hasData(): boolean;
+    destroy(): void;
+    private _clearVertex;
+    /**
+     * Find the index of the layer the given vertex is in.
+     * @param vertex
+     * @internal
+     */
+    private _getLayerIndex;
+    private _getNeighbors;
+    private _track2;
+    private _setVertex;
+    private _initEvents;
+    /**
+     * Redraw the chart and pivot around a specific edge property.
+     * @param property
+     */
+    pivot(property: string): void;
+    /**
+     * Alias to `pivot(null)`
+     */
+    clearPivot(): void;
+}
+declare class SankeyTooltip extends Tooltip {
+    private valueProperty;
+    private labelProperty;
+    constructor(parentElement: BrowserElement, options: TooltipOptions, valueProperty: string, labelProperty: string);
+    showEdgeTooltip(edge: Edge, e: MouseEvent, edgeElement: ChartSVGElement): void;
+    showNodeTooltip(node: Node, e: MouseEvent, nodeElement: ChartSVGElement): void;
+}
+export {};

package/types/charts/scatter/definitions.d.ts

@@ -0,0 +1,6 @@
+import { DualValueChartOptions } from "../definitions";
+/**
+ * Options for a Scatter chart
+ */
+export interface ScatterChartOptions extends DualValueChartOptions {
+}

package/types/charts/scatter/index.d.ts

@@ -0,0 +1,2 @@
+export * from './scatter-chart';
+export * from './definitions';

package/types/charts/scatter/scatter-chart.d.ts

@@ -0,0 +1,16 @@
+import { BrowserElement } from "../../browser-ui";
+import { ObjectData } from "../../core";
+import { DualValueChart } from "../dual-value-chart";
+import { DualValueChartSeries } from "../series";
+import { ScatterChartOptions } from "./definitions";
+/**
+ * A scatter chart represents data in 2 axes.
+ * @group Charts
+ * @category Scatter Chart
+ */
+export declare class ScatterChart extends DualValueChart {
+    options: ScatterChartOptions;
+    constructor(container: BrowserElement, options: ScatterChartOptions);
+    $getMarkerSize(s: DualValueChartSeries, point: ObjectData): number;
+    $getDataPointCssClass(): string;
+}

package/types/charts/series/array-based-series.d.ts

@@ -0,0 +1,95 @@
+import { ChartSeries, ChartSeriesOptions } from "./series";
+import { ObjectData } from "../../core/model/graph";
+import { RealisedSeries } from "./definitions";
+import { BaseChart } from "../base-chart";
+export declare const DEFAULT_ARRAY_SERIES_STEP = 1;
+export declare const DEFAULT_ARRAY_SERIES_RANGE_START_FIELD = "rangeStart";
+export declare const DEFAULT_ARRAY_SERIES_VALUES_FIELD = "values";
+export declare const DEFAULT_ARRAY_SERIES_MIN_VALUES_FIELD = "minValues";
+export declare const DEFAULT_ARRAY_SERIES_MAX_VALUES_FIELD = "maxValues";
+export declare const DEFAULT_ARRAY_SERIES_LABEL_FIELD = "label";
+export declare const DEFAULT_ARRAY_SERIES_ID_FIELD = "id";
+/**
+ * Definition of a function that can generate labels for an array series.
+ * @param index The index of the data point for which we need a label
+ * @param data The data object from which the series is being populated
+ */
+export type ArraySeriesLabelGenerator = (index: number, data: ObjectData) => string;
+/**
+ * Array based chart series - each category is represented by a single record, which has either a field containing an array of values, or both a field containing minimum values and a field containing maximum values.
+ * @group Charts
+ * @category Definitions
+ */
+export interface ArrayBasedSeriesOptions extends ChartSeriesOptions {
+    /**
+     * Start value for the series. Defaults to 0.
+     */
+    startPoint?: number;
+    /**
+     * Step between values in the series. Defaults to 1.
+     */
+    step?: number;
+    /**
+     * Currently unused.
+     */
+    rangeStartField?: string;
+    /**
+     * The field containing the array of values. Defaults to `"values"`.
+     */
+    valuesField?: string;
+    /**
+     * The field containing the array of minimum values. This is required if you want to draw an Area chart - and you also need to provide the `maxValuesField`. Defaults to `"minValues"`.
+     */
+    minValuesField?: string;
+    /**
+     * The field containing the array of maximum values. This is required if you want to draw an Area chart - and you also need to provide the `minValuesField`. Defaults to `"maxValues"`.
+     */
+    maxValuesField?: string;
+    /**
+     * Optional field which contains the label for the series itself. Defaults to `"label"`.
+     */
+    labelField?: string;
+    /**
+     * Optional field which contains the ID for the series. If not provided, an id will be auto generated.
+     */
+    idField?: string;
+    /**
+     * Labels to use for the series. Optional. If omitted the label for each data point is computed from `startPoint` + `step`. Providing labels in the series is useful when your data is not strictly numeric increasing, or you want to customise its display.
+     */
+    labels?: Array<string>;
+    /**
+     * Optional function to use to generate labels for each step in the array series. This offers the most customisation of all - each time a data point in the series is drawn, this function is invoked, and the return value is used as the label on the category axis.
+     * @param index
+     * @param data
+     */
+    labelGenerator?: ArraySeriesLabelGenerator;
+}
+/**
+ * A series in which each category is represented by a single record, which has a field containing an array of values. This series type requires that the user provides a start point. The series has a default 'step' of 1, meaning that the series advances by 1 for each subsequent value in the array, but you can set the step. By default the series will extract the array of values from a field names 'values', but that can also be set.
+ *
+ * It is not necessary that each record has the same number of data points. By default, if some record has fewer points than other records, its series will just be truncated. You can also provide a `rangeStart` value inside a series record, which indicates where the array of values for the given series begins.
+ *
+ * @group Charts
+ */
+export declare class ArrayBasedSeries extends ChartSeries {
+    private chart;
+    static type: string;
+    startPoint: number;
+    step: number;
+    rangeStartField: string;
+    $valuesField: string;
+    $minValuesField: string;
+    $maxValuesField: string;
+    $labelField: string;
+    $idField: string;
+    $labels: Array<string>;
+    $labelGenerator: ArraySeriesLabelGenerator;
+    $series: Array<RealisedSeries>;
+    values: Array<number>;
+    constructor(options: ArrayBasedSeriesOptions, chart: BaseChart);
+    addValue(data: ObjectData): void;
+    private _computeCategoryLabel;
+    private _computeDefaultCategoryLabel;
+    expand(): Array<RealisedSeries>;
+    reset(): void;
+}

package/types/charts/series/collation-series.d.ts

@@ -0,0 +1,24 @@
+import { ChartSeries, ChartSeriesOptions } from "./series";
+import { ObjectData } from "../../core";
+import { RealisedSeries } from "./definitions";
+export interface CollationSeriesOptions extends ChartSeriesOptions {
+    /**
+     * Name of the field containing values. Defaults to "value".
+     */
+    valueField?: string;
+}
+export declare class CollationSeries extends ChartSeries {
+    static type: string;
+    counts: Map<any, number>;
+    id: string;
+    color: string;
+    label: string;
+    /**
+     * Name of the field containing values. Defaults to "value".
+     */
+    valueField: string;
+    constructor(options: CollationSeriesOptions);
+    addValue(data: ObjectData): void;
+    reset(): void;
+    expand(): Array<RealisedSeries>;
+}

package/types/charts/series/definitions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A series that has been preprocessed and can be included on a chart.
+ */
+import { ObjectData } from "../../core";
+import { ChartSeriesOptions } from "./series";
+/**
+ * @internal
+ */
+export interface RealisedSeries {
+    isRangeSeries(): boolean;
+    getCategories(): Array<ObjectData>;
+    values: Array<{
+        min: number;
+        max: number;
+    }>;
+    color: string;
+    min: number;
+    max: number;
+    total: number;
+    label: string;
+    id: string;
+    visible: boolean;
+    marker?: string;
+    markerType?: "circle" | "square" | "cross";
+    markerSize?: number;
+    stack?: string;
+}
+/**
+ * Options for a dual value axis chart
+ */
+export interface DualValueSeriesOptions extends ChartSeriesOptions {
+    /**
+     * Name of the field from which to extract X axis data points
+     */
+    xAxisField: string;
+    /**
+     * Name of the field from which to extract Y axis data points
+     */
+    yAxisField: string;
+    /**
+     * Whether or not to show an outline around the markers. Defaults to false.
+     */
+    outline?: boolean;
+    /**
+     * The width of the outline in pixels. Defaults to 1.
+     */
+    outlineWidth?: number;
+    /**
+     * Color for outline. If not provided, a contrasting color will be computed.
+     */
+    outlineColor?: string;
+}

package/types/charts/series/dual-value-chart-series.d.ts

@@ -0,0 +1,26 @@
+import { ObjectData } from "../../core";
+import { ChartSeries, HasMarkerSeries, MarkerResolutionFunction } from "./series";
+import { RealisedSeries } from "./definitions";
+import { DualValueChartAxis } from "../definitions";
+/**
+ * @internal
+ */
+export declare class DualValueChartSeries extends ChartSeries implements HasMarkerSeries {
+    readonly xAxisField: string;
+    readonly yAxisField: string;
+    $data: Array<ObjectData>;
+    $xAxis: DualValueChartAxis;
+    $yAxis: DualValueChartAxis;
+    marker?: string;
+    markerType?: "circle" | "square" | "cross";
+    markerSize?: number;
+    color?: string;
+    outline?: boolean;
+    outlineWidth?: number;
+    outlineColor?: string;
+    resolveMarker?: MarkerResolutionFunction;
+    constructor(xAxisField: string, yAxisField: string, marker?: string, markerType?: "circle" | "square" | "cross", markerSize?: number, color?: string, outline?: boolean, outlineWidth?: number, outlineColor?: string, resolveMarker?: MarkerResolutionFunction);
+    reset(): void;
+    addValue(o: ObjectData): void;
+    expand(): Array<RealisedSeries>;
+}

package/types/charts/series/index.d.ts

@@ -0,0 +1,7 @@
+export * from './array-based-series';
+export * from './record-based-series';
+export * from './collation-series';
+export * from './summing-series';
+export * from './definitions';
+export * from './series';
+export * from './dual-value-chart-series';

package/types/charts/series/record-based-series.d.ts

@@ -0,0 +1,58 @@
+import { ChartSeries, ChartSeriesOptions } from "./series";
+import { ObjectData } from "../../core";
+import { RealisedSeries } from "./definitions";
+/**
+ * Options for a RecordBasedSeries.
+ * @group Charts
+ * @category Definitions
+ */
+export interface RecordBasedSeriesOptions extends ChartSeriesOptions {
+    /**
+     * Name of the field containing values. Defaults to "value".
+     */
+    valueField?: string;
+    /**
+     * Name of the field containing minimum values, when the series is used in a range plot. Defaults to "minValue".
+     */
+    minValueField?: string;
+    /**
+     * Name of the field containing maximum values, when the series is used in a range plot. Defaults to "maxValue".
+     */
+    maxValueField?: string;
+}
+/**
+ * A Series in which each individual step of the series is represented by a single record. Like say you have corn and wheat production estimates for a set of countries - each country would be a single record, inside which there is an entry for corn and one for wheat. Or maybe you have a trophy count for some football teams, how many times they have won the FA cup, british premier league and champions league, say. In that case each team is a record, and the count of trophies in each league is an entry.
+ *
+ * @group Charts
+ * @internal
+ */
+export declare class RecordBasedSeries extends ChartSeries implements RealisedSeries {
+    static type: string;
+    color: string;
+    min: number;
+    max: number;
+    total: number;
+    label: string;
+    id: string;
+    visible: boolean;
+    categories: Array<ObjectData>;
+    values: Array<{
+        min: number;
+        max: number;
+    }>;
+    valueField?: string;
+    minValueField?: string;
+    maxValueField?: string;
+    marker?: string;
+    markerType?: "circle" | "square" | "cross";
+    markerSize?: number;
+    private _groupField;
+    private _groups;
+    isRangeSeries(): boolean;
+    constructor(options: RecordBasedSeriesOptions, color: string, groupField?: string);
+    reset(): void;
+    toggleVisible(): void;
+    addValue(data: ObjectData): void;
+    getCategories(): Array<ObjectData>;
+    expand(): Array<RealisedSeries>;
+}

package/types/charts/series/series.d.ts

@@ -0,0 +1,66 @@
+import { ObjectData } from "../../core/model/graph";
+import { RealisedSeries } from "./definitions";
+import { RecordBasedSeries } from "./record-based-series";
+import { ArrayBasedSeries } from "./array-based-series";
+import { CollationSeries } from "./collation-series";
+/**
+ * Defines a function that can resolve a custom SVG marker for a specific data point.
+ */
+export type MarkerResolutionFunction = (point: ObjectData) => string;
+/**
+ * Base interface for chart series options.
+ * @group Charts
+ * @category Definitions
+ */
+export interface ChartSeriesOptions {
+    /**
+     * The id of the series.
+     */
+    id?: string;
+    /**
+     * Label for the series. Optional.
+     */
+    label?: string;
+    /**
+     * Color to use for the series. This is optional and if not provided the chart will use a color from its installed {@link ColorGenerator}.
+     */
+    color?: string;
+    /**
+     * Defines the series type.
+     */
+    type?: typeof RecordBasedSeries.type | typeof ArrayBasedSeries.type | typeof CollationSeries.type;
+    /**
+     * Optional template to use for markers. This should be a string in VisuallyJs's internal template format, with namespaced SVG elements.
+     */
+    marker?: string;
+    /**
+     * Size (in pixels) to use for data points. Defaults to 10 pixels. For circular markers this equates to the diameter; for square/cross this is width/height
+     */
+    markerSize?: number;
+    /**
+     * Type of marker to draw. Defaults to "circle".
+     */
+    markerType?: "circle" | "square" | "cross";
+    /**
+     * Optional function to resolve a marker SVG string for each data point.
+     */
+    resolveMarker?: MarkerResolutionFunction;
+}
+/**
+ * @group Charts
+ * @internal
+ */
+export declare abstract class ChartSeries {
+    abstract reset(): void;
+    abstract addValue(data: ObjectData): void;
+    /**
+     * Expand the given series into a set of RealisedSeries objects. For RecordBasedSeries this just means to return the series itself, as it is already fully realised. But for ArrayBasedSeries this method returns a set of RealisedSeries, one for each value that was added to the array based series.
+     */
+    abstract expand(): Array<RealisedSeries>;
+}
+export interface HasMarkerSeries {
+    marker?: string;
+    markerType?: "circle" | "square" | "cross";
+    markerSize?: number;
+    resolveMarker?: MarkerResolutionFunction;
+}