@visuallyjs/browser-ui 1.0.0

package/types/charts/base-xy-chart.d.ts

@@ -0,0 +1,224 @@
+import { ChartSVGElement, SteppedScale } from "./util";
+import { PointXY } from "../core";
+import { AxisCommon, CategoryAxis, ChartDimensions, CrosshairOptions, ValueAxis } from "./definitions";
+import { BrowserElement } from "../browser-ui";
+import { RealisedSeries } from "./series/definitions";
+import { Tooltip, TooltipOptions } from "./tooltip";
+import { ChartSeriesOptions } from "./series";
+import { SeriesBasedChart, SeriesBasedChartOptions } from "./series-based-chart";
+/**
+ * @group Charts
+ * @category XY Chart
+ */
+export interface XYChartBaseOptions<O extends ChartSeriesOptions> extends SeriesBasedChartOptions<O> {
+    /**
+     * Whether or not to round the corners of bars/columns. Defaults to true
+     */
+    roundCorners?: boolean;
+    /**
+     * When rounding bar/column corners, use this radius. Defaults to 5 pixels.
+     */
+    cornerRadius?: number;
+    /**
+     * The width to use if showing a line marking value/category axes. By default, axis lines are not painted.
+     */
+    axisLineSize?: number;
+    /**
+     * When the legend is not floating, this number defines how much whitespace to leave around it.
+     */
+    legendPadding?: number;
+    /**
+     * How much padding to leave between the y axes decoration and the chart content area.
+     */
+    yAxisPadding?: number;
+    /**
+     * Options for the info tooltip.
+     */
+    tooltip?: TooltipOptions;
+    /**
+     * The maximum size a category label can be as a ratio of the chart's overall size. Category labels are rotated to 45 degrees automatically when they start to overlap each other, but if the labels are long strings then there is a chance they'll use up too much of the available chart space. This value (whose default is 0.2), specifies a hard limit for label size, to avoid that situation. In a chart whose category axis is the X axis, this is applied relative to the height of the chart, and in a chart whose category axis is the Y axis, it's applied relative to the width.
+     */
+    maxLabelSize?: number;
+}
+/**
+ * Base interface for XYChart options.
+ * @group Charts
+ * @category XY Chart
+ */
+export interface XYChartOptions<O extends ChartSeriesOptions> extends XYChartBaseOptions<O> {
+}
+/**
+ * Empty scale to use prior to loading data into a chart.
+ * @group Charts
+ * @internal
+ */
+export declare class BlankScale implements SteppedScale {
+    dataMax: number;
+    dataMin: number;
+    maxScale: number;
+    minScale: number;
+    range: number;
+    step: number;
+    stepCount: number;
+    steps: Array<number>;
+}
+/**
+ * An XY chart has an X and Y axis. You can instantiate an XY chart and supply the plots to use, but there are also subclasses of this chart such as {@link BarChart} and {@link ColumnChart} which configure certain parts of the plot for you.
+ * @group Charts
+ * @category XY Chart
+ */
+export declare abstract class XYChart<O extends ChartSeriesOptions, T extends Tooltip = Tooltip> extends SeriesBasedChart<O> {
+    axisLineSize: number;
+    yAxisPadding: number;
+    private yAxes;
+    private xAxes;
+    $crosshairElements: {
+        x: Array<{
+            line: ChartSVGElement;
+            label?: ChartSVGElement;
+            options: CrosshairOptions;
+        }>;
+        y: Array<{
+            line: ChartSVGElement;
+            label?: ChartSVGElement;
+            options: CrosshairOptions;
+        }>;
+    };
+    $roundCorners: boolean;
+    $cornerRadius: number;
+    $realisedSeries: Array<RealisedSeries>;
+    _tooltipOptions: TooltipOptions;
+    $tooltip: T;
+    $maxLabelSize: number;
+    constructor(container: BrowserElement, options: XYChartOptions<O>);
+    /**
+     *
+     * @internal
+     */
+    $doReset(): void;
+    /**
+     *
+     * @internal
+     */
+    $doLoad(): void;
+    /**
+     *
+     * @internal
+     */
+    getSeries(): Array<RealisedSeries>;
+    private _drawXAxis;
+    /**
+     * For the given axis, return a suitable value for the text element's `text-anchor` attribute
+     * @param va
+     * @private
+     */
+    private _getAxisTitleAnchor;
+    private _drawYAxis;
+    /**
+     * For the given scale label, compute a user readable value. For instance, if the value is very large, we might replace a bunch of zeroes with k or M etc. Ideally this whole mechanism would be pluggable.
+     * @param s
+     * @return {string}
+     * @internal
+     */
+    $computeScaleLabel(s: number, axis: ValueAxis): string;
+    /**
+     * @return {SVGElement}
+     * @param svgRoot
+     * @param width
+     * @param height
+     * @param titleEndY Y location where the title element ends. Used if legend is valign top.
+     * @internal
+     */
+    $precomputeLegend(svgRoot: SVGElement, width: number, height: number, titleEndY: number): ChartSVGElement;
+    protected $getScaleGrid(axisLength: number, valueAxis: ValueAxis): Array<number>;
+    /**
+     * Gets labels for the given axis. This class supports ValueAxis. CategoryValueChart supports category axis. You could introduce a new axis type and override this method
+     * @param va
+     * @param isXAxis
+     * @internal
+     */
+    $getAxisLabels(va: AxisCommon, isXAxis: boolean): ChartSVGElement[];
+    protected $drawChart(svgRoot: ChartSVGElement, width: number, height: number, backgroundElement: ChartSVGElement): void;
+    /**
+     * Creates the initial crosshair line elements.
+     */
+    protected $drawCrosshairs(svgRoot: ChartSVGElement, initElements: boolean, extraClazz: string, filter?: (ax: AxisCommon) => boolean): void;
+    /**
+     * Draws the title, axes, legend etc
+     * @internal
+     */
+    $drawDecoration(svgRoot: ChartSVGElement, width: number, height: number): ChartDimensions;
+    setFocusedSeries(series: number | null): void;
+    /**
+     * Position the labels for a category axis on the X axis.
+     * @param dim
+     * @param labels
+     */
+    private _positionXAxisCategoryLabels;
+    /**
+     * Position the labels for a value axis on the X axis.
+     * @return {SVGElement}
+     * @param dim
+     * @param valueAxis
+     */
+    private _positionXAxisValueLabels;
+    /**
+     * Set final positions for category axis labels on the Y axis.
+     * @param dim
+     * @param labels
+     * @private
+     */
+    private _positionYAxisCategoryLabels;
+    /**
+     * Get labels for a value axis, using the scale or stackedScale stored on the value axis.
+     * @param va axis to get labels for
+     * @param isXAxis True if this value axis is on the x axis, false if this value axis is on the Y axis.
+     */
+    private _getValueAxisLabels;
+    /**
+     * Set final positions for value axis labels on the Y axis.
+     * @param dim
+     * @param labels
+     * @private
+     */
+    private _positionYAxisValueLabels;
+    /**
+     * Draws a grid for a value axis that is on the X axis
+     * @param svgRoot
+     * @param dim
+     * @param valueAxis
+     * @private
+     */
+    private _drawGridForXAxisValueAxis;
+    /**
+     * Draws a grid for a value axis that is on the Y axis
+     * @param svgRoot
+     * @param dim
+     * @param valueAxis
+     * @private
+     */
+    private _drawGridForYAxisValueAxis;
+    protected $onMouseMove(coords: PointXY): void;
+    protected $onMouseLeave(): void;
+    /**
+     * Calculates the proportional position (0-1) for an axis based on mouse coordinate.
+     */
+    private $getProportionalPos;
+    $hideTooltip(): void;
+    abstract $createTooltip(root: ChartSVGElement, options: TooltipOptions): T;
+    abstract $getXAxisType(): "category" | "value";
+    abstract $getYAxisType(): "category" | "value";
+    abstract $mouseOutChartPoint(): void;
+    abstract $mouseOverChartPoint(t: ChartSVGElement, seriesIndex: number, e: MouseEvent): void;
+    abstract $_generateYAxes(): {
+        yAxes: Array<ValueAxis | CategoryAxis>;
+        yAxesAtStart: Array<ValueAxis | CategoryAxis>;
+        yAxesAtEnd: Array<ValueAxis | CategoryAxis>;
+    };
+    abstract $_generateXAxes(): {
+        xAxes: Array<ValueAxis | CategoryAxis>;
+        xAxesAtStart: Array<ValueAxis | CategoryAxis>;
+        xAxesAtEnd: Array<ValueAxis | CategoryAxis>;
+    };
+    abstract $recalc(): void;
+}

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

@@ -0,0 +1,30 @@
+import { ObjectData } from "../../core";
+import { BrowserElement } from "../../browser-ui";
+import { DualValueChartSeries, MarkerResolutionFunction } from "../series";
+import { DualValueChart } from "../dual-value-chart";
+import { DualValueChartAxis } from "../definitions";
+import { BubbleChartOptions } from './definitions';
+/**
+ * Data series for use in a bubble chart.
+ * @internal
+ */
+export declare class BubbleChartSeries extends DualValueChartSeries {
+    readonly xAxisField: string;
+    readonly yAxisField: string;
+    readonly valueField: string;
+    $valueAxis: DualValueChartAxis;
+    addValue(o: ObjectData): void;
+    constructor(xAxisField: string, yAxisField: string, valueField: string, marker?: string, markerType?: "circle" | "square" | "cross", markerSize?: number, color?: string, outline?: boolean, outlineWidth?: number, outlineColor?: string, resolveMarker?: MarkerResolutionFunction);
+}
+/**
+ * A Bubble chart is a dual value axis chart with a 3rd dimension that is represented by the size of each data point.
+ * @group Charts
+ * @category Bubble Chart
+ */
+export declare class BubbleChart extends DualValueChart {
+    options: BubbleChartOptions;
+    constructor(container: BrowserElement, options: BubbleChartOptions);
+    $dualValueInit(options: BubbleChartOptions): void;
+    $getMarkerSize(s: BubbleChartSeries, point: ObjectData): number;
+    $getDataPointCssClass(): string;
+}

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

@@ -0,0 +1,32 @@
+import { DualValueSeriesOptions } from "../series";
+import { DualValueChartOptions } from "../definitions";
+/**
+ * Options for a bubble chart series.
+ * @group Charts
+ * @category Bubble Chart
+ */
+export interface BubbleChartSeriesOptions extends DualValueSeriesOptions {
+    /**
+     * The field in the data source that contains the value for the bubble's size.
+     */
+    valueField: string;
+}
+/**
+ * Options for a bubble chart.
+ * @group Charts
+ * @category Bubble Chart
+ */
+export interface BubbleChartOptions extends DualValueChartOptions {
+    /**
+     * The minimum size (in pixels) for a bubble. Defaults to 10.
+     */
+    minPointSize?: number;
+    /**
+     * The maximum size (in pixels) for a bubble. No default.
+     */
+    maxPointSize?: number;
+    /**
+     * An array of bubble chart series options.
+     */
+    series: Array<BubbleChartSeriesOptions>;
+}

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

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

package/types/charts/category-value-chart.d.ts

@@ -0,0 +1,146 @@
+import { XYChart, XYChartOptions } from "./base-xy-chart";
+import { ChartSVGElement } from "./util";
+import { AxisCommon, CategoryAxis, CategoryAxisDefinition, ChartDimensions, ValueAxis, ValueAxisDefinition } from "./definitions";
+import { ObjectData, PointXY } from "../core";
+import { BrowserElement } from "../browser-ui";
+import { CategoryVsAxisPlot, PlotDefinition } from "./plot";
+import { CategoryValueTooltip, TooltipOptions } from "./tooltip";
+import { ArrayBasedSeriesOptions, RecordBasedSeriesOptions } from "./series";
+export interface CategoryValueChartOptions extends XYChartOptions<RecordBasedSeriesOptions | ArrayBasedSeriesOptions> {
+    plots: PlotDefinition | Array<PlotDefinition>;
+    /**
+     * Definition of one or more value axes.
+     */
+    valueAxis?: ValueAxisDefinition | Array<ValueAxisDefinition>;
+    /**
+     * Definitions of one or more category axes.
+     */
+    categoryAxis?: CategoryAxisDefinition | Array<CategoryAxisDefinition>;
+    /**
+     * Defaults to false, meaning the Y axis is the category axis and the X axis is the value axis, such as you'd use for a bar chart. Changing this to `true` makes the Y axis the value axis and the X axis the category axis, such as you'd use for a column chart. Note, though, that this flag is also honoured by other plot types such as line and area.
+     */
+    inverted?: boolean;
+    /**
+     * Pivot the data so that the series definitions become the categories, and the series data is derived from the individual data points. Default to false.
+     */
+    pivot?: boolean;
+}
+/**
+ * Base class for XY charts that have a single value axis, such as bar charts, column charts, area and line charts. This class can be used directly, instead of using one of its subclasses, and supports multiple plots (each of which has to be a CategoryValuePlot).
+ * @group Charts
+ */
+export declare class CategoryValueChart extends XYChart<RecordBasedSeriesOptions | ArrayBasedSeriesOptions, CategoryValueTooltip> {
+    $valueAxes: Array<ValueAxis>;
+    $valueAxesMin: number;
+    $valueAxesMax: number;
+    $categoryAxes: Array<CategoryAxis>;
+    $inverted: boolean;
+    _valueAxisDefinition: ValueAxisDefinition | Array<ValueAxisDefinition>;
+    _categoryAxisDefinition: CategoryAxisDefinition | Array<CategoryAxisDefinition>;
+    $categories: Array<ObjectData>;
+    $plots: Array<CategoryVsAxisPlot>;
+    _pivot: boolean;
+    constructor(container: BrowserElement, options: CategoryValueChartOptions);
+    /**
+     * Gets label elements for a category axis.
+     * @param parentElement Parent to append label elements to
+     * @param labelField the field in category containing the label
+     * @param isXAxis True if this category axis is on the x axis, false if this category axis is on the Y axis.
+     */
+    private _getCategoryAxisLabels;
+    /**
+     * Overrides XYChart's $getAxisLabels to add support for category axes.
+     * @param va
+     * @param isXAxis
+     */
+    $getAxisLabels(va: AxisCommon, isXAxis: boolean): any[];
+    /**
+     * Setup the category axes.
+     */
+    private _setupCategoryAxes;
+    $doReset(): void;
+    /**
+     * Pivot the dataset so that the series become the categories and the categories become the series.
+     * NOTE this still does not get us stacked groups.
+     * @internal
+     */
+    private _doPivot;
+    $doLoad(): void;
+    $recalc(): void;
+    /**
+     * Process the value axes. This method is agnostic of the orientation of the chart.
+     */
+    private _setupValueAxes;
+    /**
+     * Generate the Y axes for XYChart to draw. By default these are category axes; if `inverted` is set on this chart they are value axes.
+     */
+    $_generateYAxes(): {
+        yAxes: ValueAxis[];
+        yAxesAtStart: ValueAxis[];
+        yAxesAtEnd: ValueAxis[];
+    } | {
+        yAxes: CategoryAxis[];
+        yAxesAtStart: CategoryAxis[];
+        yAxesAtEnd: CategoryAxis[];
+    };
+    /**
+     * Generate the X axes for XYChart to draw. By default these are value axes; if `inverted` is set on this chart they are category axes.
+     */
+    $_generateXAxes(): {
+        xAxes: ValueAxis[];
+        xAxesAtStart: ValueAxis[];
+        xAxesAtEnd: ValueAxis[];
+    } | {
+        xAxes: CategoryAxis[];
+        xAxesAtStart: CategoryAxis[];
+        xAxesAtEnd: CategoryAxis[];
+    };
+    /**
+     * Override drawChart to add our plots at the end, and, optionally, the crosshair.
+     * @param svgRoot
+     * @param width
+     * @param height
+     * @param backgroundElement
+     * @internal
+     */
+    protected $drawChart(svgRoot: ChartSVGElement, width: number, height: number, backgroundElement: ChartSVGElement): void;
+    /**
+     * get the amount of space in the category axis available to each category.
+     * @param dim
+     * @param isXAxis which axis to measure space in. For a value axis on the x axis, this means to use the chart height. For a value axis on the y axis, it means use the chart width.
+     * @internal
+     */
+    private _getSpacePerCategory;
+    /**
+     * Returns the position of the center of the given category in the category axis.
+     * @param categoryIndex
+     * @param isXAxis which axis to measure space in. For a value axis on the x axis, this means to use the chart height. For a value axis on the y axis, it means use the chart width.
+     * @param dim
+     * @internal
+     */
+    $getCategoryCenter(categoryIndex: number, dim: ChartDimensions, isXAxis: boolean): number;
+    /**
+     * Callback from the superclass to inform us the mouse is over a point drawn on the chart. In this chart type we set the focused category (if crosshair was requested in the chart options), and maybe show a tooltip.
+     * @param t
+     * @param seriesIndex
+     * @internal
+     */
+    $mouseOverChartPoint(t: ChartSVGElement, seriesIndex: number, e: MouseEvent): void;
+    /**
+     * Callback from the superclass to inform us the mouse has exited a point drawn on the chart. In this chart type we clear the focused category
+     * @internal
+     */
+    $mouseOutChartPoint(): void;
+    /**
+     * @internal
+     * @param series
+     * @param category
+     * @param position
+     * @param tooltipAnchor
+     * @internal
+     */
+    $maybeShowTooltip(series: number, category: number, position: PointXY, tooltipAnchor: PointXY, stackId?: string, stackTotal?: number, valueOverride?: number): void;
+    $getXAxisType(): "category" | "value";
+    $getYAxisType(): "category" | "value";
+    $createTooltip(root: ChartSVGElement, options: TooltipOptions): CategoryValueTooltip;
+}

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

@@ -0,0 +1,38 @@
+import { BaseChart } from "./base-chart";
+import { BrowserElement } from "../browser-ui";
+/**
+ * Options for a chart export menu.
+ */
+export interface ChartExporterOptions {
+    /**
+     * Placement respective to right edge of the chart. Any valid CSS dimension works. Default is 1rem.
+     */
+    right?: string;
+    /**
+     * Placement respective to top edge of the chart. Any valid CSS dimension works. Default is 1rem.
+     */
+    top?: string;
+    /**
+     * Optional filename to use when exporting this chart. If not provided, a filename (with maximum length 30 characters) will be created from the chart's title, if it has one. Otherwise `chart-export` will be the filename.
+     */
+    filename?: string;
+}
+/**
+ * Component that adds an export menu to a chart.
+ */
+export declare class ChartExporter {
+    private chart;
+    private options;
+    private hamburger;
+    private menu;
+    private eventManager;
+    private hideTimeout;
+    private _menuVisible;
+    constructor(chart: BaseChart, options?: ChartExporterOptions);
+    _render(target?: BrowserElement): void;
+    private _showMenu;
+    private _hideMenu;
+    private _download;
+    private _triggerDownload;
+    destroy(): void;
+}

package/types/charts/chart-zoom-controls.d.ts

@@ -0,0 +1,23 @@
+import { BaseChart } from "./base-chart";
+import { BrowserElement } from "../browser-ui";
+/** @internal */
+export declare const ZOOM_TO_FIT_VIEW_BOX = "0 0 32 30";
+/** @internal */
+export declare const ZOOM_TO_FIT_PATH = "M3.692 4.63c0-.53.4-.938.939-.938h5.215V0H4.708C2.13 0 0 2.054 0 4.63v5.216h3.692V4.631zM27.354 0h-5.2v3.692h5.17c.53 0 .984.4.984.939v5.215H32V4.631A4.624 4.624 0 0027.354 0zm.954 24.83c0 .532-.4.94-.939.94h-5.215v3.768h5.215c2.577 0 4.631-2.13 4.631-4.707v-5.139h-3.692v5.139zm-23.677.94c-.531 0-.939-.4-.939-.94v-5.138H0v5.139c0 2.577 2.13 4.707 4.708 4.707h5.138V25.77H4.631z";
+/** @internal */
+export declare const ZOOM_IN_OUT_VIEW_BOX = "0 0 32 32";
+/** @internal */
+export declare const ZOOM_IN_PATH = "M 13 6 L 13 20 M 6 13 L 20 13 M 22,22 L 30,30 M1, 13 a 12,12 0 1,0 24,0 a 12,12 0 1,0 -24,0";
+/** @internal */
+export declare const ZOOM_OUT_PATH = "M 6 13 L 20 13 M 22,22 L 30,30 M1, 13 a 12,12 0 1,0 24,0 a 12,12 0 1,0 -24,0";
+/**
+ * Component that adds zoom controls to a chart.
+ */
+export declare class ChartZoomControls {
+    private chart;
+    private container;
+    private eventManager;
+    constructor(chart: BaseChart);
+    render(target?: BrowserElement, orientation?: 'row' | 'column'): void;
+    destroy(): void;
+}

package/types/charts/constants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fired when a chart has loaded data and finished drawing.
+ * @group Events
+ * @category Charts
+ */
+export declare const EVENT_CHART_LOAD = "chart:load";
+/**
+ * The default message to display when a chart has no data
+ * @internal
+ */
+export declare const DEFAULT_CHART_EMPTY_MESSAGE = "No data";
+/**
+ * The default message to display when an error occurs while painting.
+ * @internal
+ */
+export declare const DEFAULT_CHART_ERROR_MESSAGE = "Could not draw chart";