@visuallyjs/browser-ui 1.0.0

package/types/charts/bar-and-column/bar-chart.d.ts

@@ -0,0 +1,34 @@
+import { BarPlotOptions, DataLabelsOptions } from "./bar-plot";
+import { CategoryValueChart, CategoryValueChartOptions } from "../category-value-chart";
+/**
+ * Options for a Bar chart
+ * @group Charts
+ * @category Bar Chart
+ */
+export interface BarChartOptions extends Omit<CategoryValueChartOptions, "plots"> {
+    plotOptions?: BarPlotOptions;
+    /**
+     * Whether to stack series values next to each other, optionally as a percentage stack (which takes up the available space and shows each component proportionally)
+     */
+    stacked?: boolean | "percent" | "default";
+    /**
+     * Whether to group multiple stacks side-by-side within a single category.
+     */
+    grouped?: boolean;
+    /**
+     * The field in the data objects used to identify the stack/group.
+     */
+    groupField?: string;
+    /**
+     * Options for data labels
+     */
+    dataLabels?: DataLabelsOptions;
+}
+/**
+ * A Bar chart: the value axis is the X axis and the category axis is the Y axis.
+ * @group Charts
+ * @category Bar Chart
+ */
+export declare class BarChart extends CategoryValueChart {
+    constructor(container: HTMLElement | SVGElement, options: BarChartOptions);
+}

package/types/charts/bar-and-column/bar-plot.d.ts

@@ -0,0 +1,90 @@
+import { CategoryVsAxisPlot, XYPlot, XYPlotOptions } from "../plot";
+import { ChartDimensions } from "../definitions";
+import { ChartSVGElement } from "../util";
+import { DomainExtentMap } from "../domain_scale_utilities";
+import { CategoryValueChart } from "../category-value-chart";
+export declare const DEFAULT_CATEGORY_FILL_RATIO = 0.8;
+export declare const DEFAULT_MAXIMUM_BAR_WIDTH = 50;
+export declare const DEFAULT_BAR_GAP = 10;
+/**
+ * Base interface for plots that are stackable.
+ * @internal
+ */
+export interface StackedPlot {
+    stacked?: boolean | "percent" | "default";
+}
+/**
+ * Base interface for options for plots that are stackable.
+ * @internal
+ */
+export interface StackablePlotOptions {
+    /**
+     * Whether to stack series values on top of each other.
+     */
+    stacked?: boolean | "percent" | "default";
+}
+/**
+ * Defines the format for data labels options.
+ */
+export type DataLabelsOptions = boolean | string;
+/**
+ * Options for a bar/column chart plot
+ * @group Charts
+ * @category Bar Chart
+ */
+export interface BarPlotOptions extends XYPlotOptions, StackablePlotOptions {
+    /**
+     * How much of the space available to each category to use for the bars in the chart. Defaults to 0.8. You should not set this to a value greater than 1.
+     */
+    fillRatio?: number;
+    /**
+     * The maximum size of a bar representing a value. Defaults to 50 pixels. This value applies to the category axis, NOT the value axis! In the value axis the size of the bar maps the value being displayed.
+     */
+    maxBarSize?: number;
+    /**
+     * The width/height to use for bars representing values. If you provide this the chart will not check whether it results in any overlap. Defaults to null.
+     */
+    barSize?: number;
+    /**
+     * The amount of space to leave between bars of the same category when there are multiple series.
+     */
+    barGap?: number;
+    /**
+     * Options for data labels. If true, the value for the bar is shown. If a string, it is used as a format string.
+     */
+    dataLabels?: DataLabelsOptions;
+}
+/**
+ * @internal
+ */
+type BarDimensions = {
+    barSize: number;
+    gapBetweenBars: number;
+    spaceUsedPerCategory: number;
+    spacePerCategory: number;
+    barsPerCategory: number;
+};
+export declare function isBarPlot(pl: XYPlot): pl is BarPlot;
+/**
+ * A bar plot is used for both a BarChart and a ColumnChart.
+ * @group Charts
+ * @category Bar Chart
+ */
+export declare class BarPlot extends CategoryVsAxisPlot {
+    chart: CategoryValueChart;
+    protected options: BarPlotOptions;
+    static type: string;
+    stacked: boolean | "percent" | "default";
+    private $distinctStacks;
+    constructor(chart: CategoryValueChart, options: BarPlotOptions);
+    getDomainExtents(): DomainExtentMap;
+    protected computeBarSize(availableSpace: number): BarDimensions;
+    $getBarCenter(category: number, series: number, dim: ChartDimensions): number;
+    private $computeBarPlacements;
+    private $computeBarPlacementsStackedPercent;
+    private $computeBarPlacementsStacked;
+    private $computeBarPlacementsDefault;
+    $draw(svgRoot: ChartSVGElement, dim: ChartDimensions, minPlottableValue: number, maxPlottableValue: number): void;
+    private $drawDataLabel;
+}
+export {};

package/types/charts/bar-and-column/column-chart.d.ts

@@ -0,0 +1,35 @@
+import { BrowserElement } from "../../browser-ui";
+import { BarPlotOptions, DataLabelsOptions } from "./bar-plot";
+import { CategoryValueChart, CategoryValueChartOptions } from "../category-value-chart";
+/**
+ * Options for a column chart.
+ * @group Charts
+ * @category Column Chart
+ */
+export interface ColumnChartOptions extends Omit<CategoryValueChartOptions, "plots"> {
+    plotOptions?: BarPlotOptions;
+    /**
+     * Whether to stack series values next to each other, optionally as a percentage stack (which takes up the available space and shows each component proportionally)
+     */
+    stacked?: boolean | "percent" | "default";
+    /**
+     * Whether to group multiple stacks side-by-side within a single category.
+     */
+    grouped?: boolean;
+    /**
+     * The field in the data objects used to identify the stack/group.
+     */
+    groupField?: string;
+    /**
+     * Options for data labels
+     */
+    dataLabels?: DataLabelsOptions;
+}
+/**
+ * A column chart.  Sets an inverted {@link BarPlot}. In a ColumnChart the value axis is the Y axis and the category axis is the X axis.
+ * @group Charts
+ * @category Column Chart
+ */
+export declare class ColumnChart extends CategoryValueChart {
+    constructor(container: BrowserElement, options: ColumnChartOptions);
+}

package/types/charts/bar-and-column/index.d.ts

@@ -0,0 +1,3 @@
+export * from './bar-plot';
+export * from "./column-chart";
+export * from "./bar-chart";

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

@@ -0,0 +1,395 @@
+import { OptimisticEventGenerator, ColorGenerator, PointXY, ObjectData, DataSource, Node, Group } from "../core";
+import { EventManager, BrowserElement, FontSpec, ImageExportOptions, ImageReadyFunction } from "../browser-ui";
+import { ChartSVGElement } from "./util";
+import { ChartLegend, LegendSpec } from "./legend";
+import { TooltipOptions } from "./tooltip";
+import { ChartDimensions } from "./definitions";
+import { ChartExporter, ChartExporterOptions } from "./chart-exporter";
+import { ChartZoomControls } from "./chart-zoom-controls";
+export declare const DEFAULT_BACKGROUND_COLOR = "#FFFFFF";
+export declare const DEFAULT_MARGIN = 15;
+/**
+ * Middle alignment (centered) for chart title.
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_TITLE_ALIGN_MIDDLE = "middle";
+/**
+ * Left alignment  for chart title.
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_TITLE_ALIGN_LEFT = "left";
+/**
+ * Right alignment for chart title.
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_TITLE_ALIGN_RIGHT = "right";
+/**
+ * Chart title alignment
+ */
+export type ChartTitleAlignment = typeof CHART_TITLE_ALIGN_LEFT | typeof CHART_TITLE_ALIGN_MIDDLE | typeof CHART_TITLE_ALIGN_RIGHT;
+/**
+ * Defines placing the chart title at the top of the chart
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_TITLE_PLACEMENT_TOP = "top";
+/**
+ * Defines placing the chart title at the bottom of the chart
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_TITLE_PLACEMENT_BOTTOM = "bottom";
+/**
+ * Chart title placement - at the top or the bottom.
+ */
+export type ChartTitlePlacement = typeof CHART_TITLE_PLACEMENT_TOP | typeof CHART_TITLE_PLACEMENT_BOTTOM;
+/**
+ * Base settings for a title.
+ * @group Charts
+ * @category Options
+ */
+export interface BaseTitleSpec {
+    /**
+     * The text to display.
+     */
+    text?: string;
+    /**
+     * How much blank space to leave after the title.
+     */
+    padding?: number;
+    /**
+     * If the title is too wide for the chart, this defines the amount of the width of the chart that it should fill, before being wrapped. Ignored if you set titleWrap:false. Defaults to 0.9.
+     */
+    fillRatio?: number;
+    /**
+     * If the title is too wide for the chart, this flag controls whether or not the title is wrapped. It defaults to true.
+     */
+    wrap?: boolean;
+}
+/**
+ * Definition of a title used in a chart.
+ * @group Charts
+ * @category Options
+ */
+export interface ChartTitleSpec extends BaseTitleSpec {
+    /**
+     * Where to place the title - top or bottom. Defaults to top.
+     */
+    placement?: ChartTitlePlacement;
+    /**
+     * Specs for the font to use for the title. In the title, the default font size is 20px, and style is 'bold'
+     */
+    font?: FontSpec;
+    /**
+     * How to align the text - left, middle or right
+     */
+    align?: ChartTitleAlignment;
+}
+/**
+ * Definition of a chart subtitle.
+ * @group Charts
+ * @category Options
+ */
+export interface SubtitleSpec extends BaseTitleSpec {
+    /**
+     * Spec for the font to use for the subtitle. Default size is 16px and style is 'italic'.
+     */
+    font?: FontSpec;
+    /**
+     * How to align the text - left, middle or right
+     */
+    align?: ChartTitleAlignment;
+}
+/**
+ * Middle alignment (centered) for axis title.
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_AXIS_TITLE_ALIGN_MIDDLE = "middle";
+/**
+ * At start alignment for axis title.
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_AXIS_TITLE_ALIGN_START = "start";
+/**
+ * At end alignment for axis title.
+ * @constant
+ * @group Charts
+ */
+export declare const CHART_AXIS_TITLE_ALIGN_END = "end";
+/**
+ * Axis title alignment - start, middle or end. Middle is the default.
+ */
+export type AxisTitleAlignment = typeof CHART_AXIS_TITLE_ALIGN_MIDDLE | typeof CHART_AXIS_TITLE_ALIGN_START | typeof CHART_AXIS_TITLE_ALIGN_END;
+/**
+ * Definition of the title for an axis
+ * @group Charts
+ * @category Options
+ */
+export interface AxisTitleSpec extends BaseTitleSpec {
+    /**
+     * Spec for the font to use for the axis. Default size is 14px and style is 'normal'.
+     */
+    font?: FontSpec;
+    /**
+     * How to align the text - start, middle or end
+     */
+    align?: AxisTitleAlignment;
+}
+/**
+ * Defines a function that is used to accept or reject specific nodes/groups in the data source a chart is attached to.
+ * @group Charts
+ * @category Options
+ */
+export type ChartModelFilter = (v: Node | Group) => boolean;
+/**
+ * Base options for charts.
+ * @group Charts
+ * @category Options
+ */
+export interface BaseChartOptions {
+    /**
+     * Message to display when the chart has no data. Defaults to "No data".
+     */
+    emptyMessage?: string;
+    /**
+     * Styles for legend and grid.
+     */
+    style?: ChartStyleOptions;
+    /**
+     * Padding to leave underneath the title
+     */
+    titlePadding?: number;
+    /**
+     * Defaults to true, meaning the chart will redraw when its container element resizes.
+     */
+    resizeObserver?: boolean;
+    /**
+     * Optional color to use for every series. Overrides any colorGenerator.
+     */
+    defaultColor?: string;
+    /**
+     * Optional function to call in order to establish the color to be used for each series
+     */
+    colorGenerator?: ColorGenerator;
+    margin?: number;
+    /**
+     * Width for the chart. If omitted, width is computed from the width of the chart's container
+     */
+    width?: number;
+    /**
+     * Height for the chart. If omitted, height is computed from the width of the chart's container
+     */
+    height?: number;
+    /**
+     * Background color for chart. Defaults to #FFFFFF. You can also use the `.vjs-chart-background` css class to set this.
+     */
+    backgroundColor?: string;
+    /**
+     * Title for the chart.
+     */
+    title?: ChartTitleSpec;
+    /**
+     * Subtitle for the chart.
+     */
+    subtitle?: SubtitleSpec;
+    /**
+     * Either a boolean true/false, indicating the legend should be shown/hidden, or a spec for a legend.
+     */
+    legend?: boolean | LegendSpec;
+    /**
+     * Options for a tooltip for the chart.
+     */
+    tooltip?: TooltipOptions;
+    /**
+     * Optional data to load into the chart.
+     */
+    data?: Array<ObjectData>;
+    /**
+     * Optional URL from which to retrieve data to load into the chart
+     */
+    url?: string;
+    /**
+     * Optional data source (of type `DataSource`, meaning both `VisuallyJsModel` and `Selection` are supported) from which to retrieve data to load into the chart.
+     */
+    dataSource?: DataSource;
+    /**
+     * When you provide `dataSource`, you can also provide a filter which accepts or rejects specific nodes/groups in the data source.
+     */
+    dataSourceFilter?: ChartModelFilter;
+    controls?: {
+        /**
+         * Configuration for an export menu with default settings. You can provide an object containing settings for an export menu if you want to customise it, or just `true` for the default menu. The exporter is not shown by default.
+         */
+        exporter?: boolean | ChartExporterOptions;
+        /**
+         * Whether or not to show the zoom controls. Defaults to true (when zoom is enabled).
+         */
+        zoom?: boolean;
+    };
+    /**
+     * Optional zoom configuration.
+     */
+    zoom?: {
+        /**
+         * Whether or not zoom is enabled.
+         */
+        enabled?: boolean;
+        /**
+         * Zoom range to support. Defaults to [0.05, 3]
+         */
+        range?: [number, number];
+        /**
+         * Initial zoom value. Defaults to 1.
+         */
+        initialValue?: number;
+    };
+}
+export declare const DEFAULT_GRID_LINE_COLOR = "#AAAAAA";
+export declare const DEFAULT_LEGEND_OUTLINE_WIDTH = 1;
+export declare const DEFAULT_LEGEND_BACKGROUND_COLOR = "#FFFFFFCC";
+/**
+ * @internal
+ */
+export interface ChartStyle {
+    gridLineColor: string;
+    legendOutlineColor: string;
+    legendOutlineWidth: number;
+    legendBackgroundColor: string;
+}
+/**
+ * Basic style options for a chart.
+ * @group Charts
+ * @category Options
+ */
+export interface ChartStyleOptions {
+    /**
+     * What color to draw gridlines.
+     */
+    gridLineColor?: string;
+    /**
+     * What color to draw as outline for the legend
+     */
+    legendOutlineColor?: string;
+    /**
+     * Width of the legend outline
+     */
+    legendOutlineWidth?: number;
+    /**
+     * Background color for the legend.
+     */
+    legendBackgroundColor?: string;
+    /**
+     * What color to draw crosshairs
+     */
+    crosshairColor?: string;
+}
+/**
+ * Base class for charts. This class is abstract; you won't need to interact with this class unless you're making your own chart type.
+ * @group Charts
+ */
+export declare abstract class BaseChart extends OptimisticEventGenerator {
+    container: BrowserElement;
+    style: ChartStyle;
+    dim: ChartDimensions;
+    protected _zoom: number;
+    protected _zoomRange: [number, number];
+    protected _zoomEnabled: boolean;
+    /**
+     * @internal
+     */
+    $resizeObserver: ResizeObserver;
+    $eventManager: EventManager;
+    colorGenerator: ColorGenerator<ObjectData>;
+    private _backgroundColor;
+    /**
+     * color to use for every series. Not set by default.
+     * @internal
+     */
+    $defaultColor: string;
+    $emptyMessage: string;
+    $errorMessage: string;
+    $showTitle: boolean;
+    $title: string;
+    $showSubtitle: boolean;
+    $subtitle: string;
+    $titleAlign: ChartTitleAlignment;
+    $subtitleAlign: ChartTitleAlignment;
+    $subtitleFontSize: number;
+    $titlePlacement: ChartTitlePlacement;
+    $titleFillRatio: number;
+    $titleWrap: boolean;
+    $titleFontSize: number;
+    titlePadding: number;
+    margin: number;
+    legend: ChartLegend;
+    _requestedWidth: number;
+    _requestedHeight: number;
+    _hasDrawn: boolean;
+    _exporter: ChartExporter;
+    _zoomControls: ChartZoomControls;
+    _controlsContainer: BrowserElement;
+    protected constructor(container: BrowserElement, options?: BaseChartOptions);
+    /**
+     * for subclasses to bind to events
+     * @param evt
+     * @param selector
+     * @param callback
+     */
+    protected $bind(evt: string, selector: string, callback: (e: MouseEvent) => any): void;
+    /**
+     * Gets the chart's title, if defined.
+     */
+    getTitle(): string;
+    /**
+     * Returns an SVG export of the chart. All CSS classes, and operational attributes are stripped. Crosshair elements are also removed.
+     * @param width Optional width for the output SVG.
+     * @param height Optional height for the output SVG.
+     */
+    exportSVG(width?: number, height?: number): string;
+    /**
+     * Returns an image export of the chart. All CSS classes, and operational attributes are stripped. Crosshair elements are also removed.
+     */
+    exportImage(options: ImageExportOptions, onready: ImageReadyFunction): void;
+    destroy(): void;
+    $draw(): void;
+    private _renderControls;
+    protected abstract $drawChart(svgRoot: ChartSVGElement, width: number, height: number, backgroundElement: ChartSVGElement): void;
+    $drawEmptyMessage(svgRoot: ChartSVGElement, width: number, height: number, backgroundElement: ChartSVGElement): void;
+    $drawErrorMessage(svgRoot: ChartSVGElement, width: number, height: number, backgroundElement: ChartSVGElement): void;
+    /**
+     *
+     * @internal
+     * @param svgRoot
+     * @param width
+     */
+    $precomputeTitle(svgRoot: SVGElement, width: number): ChartSVGElement;
+    $getBackgroundColor(): string;
+    abstract hasData(): boolean;
+    /**
+     * Map the given page location to an x/y location on the chart's canvas
+     * @param pl
+     * @internal
+     */
+    $fromPageLocation(pl: PointXY): PointXY;
+    /**
+     * Map the location of the given page event to an x/y location on the chart
+     * @param e
+     * @internal
+     */
+    $fromEventLocation(e: Event): PointXY;
+    /**
+     * Gets the current zoom level.
+     */
+    getZoom(): number;
+    /**
+     * Sets the current zoom level. Clamped to the current zoom range.
+     * @param z The zoom level to set.
+     */
+    setZoom(z: number): number;
+    private _applyZoom;
+}