@visuallyjs/browser-ui 1.0.0

package/types/charts/css-classes.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Added to the background element of a chart.
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_BACKGROUND = "vjs-chart-background";
+/**
+ * Added to element that is the parent of the chart's plot(s).
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_PLOT_BACKGROUND = "vjs-chart-plot-background";
+/**
+ * Added to the element that contains series data and crosshairs.
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_BODY = "vjs-chart-body";
+/**
+ * Added to an SVG group element that represents a data series in an XY chart.
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_SERIES = "vjs-chart-series";
+/**
+ * Added to a chart's legend element
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_LEGEND = "vjs-chart-legend";
+/**
+ * Added to an item in a chart's legend
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_LEGEND_ITEM = "vjs-chart-legend-item";
+/**
+ * Added to the label in a chart's legend
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_LEGEND_LABEL = "vjs-chart-legend-label";
+/**
+ * Added to the dots for each item in a legend
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_LEGEND_DOT = "vjs-chart-legend-dot";
+/**
+ * Added to both the X and Y axes in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_AXIS = "vjs-chart-axis";
+/**
+ * Added to the X axis element in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_X_AXIS = "vjs-chart-x-axis";
+/**
+ * Added to the Y axis element in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_Y_AXIS = "vjs-chart-y-axis";
+/**
+ * Added to the parent container for the label elements in both the X and Y axes of an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_AXIS_LABELS = "vjs-chart-axis-labels";
+/**
+ * Added to the baseline marking the X or Y axis in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_AXIS_LINE = "vjs-chart-axis-line";
+/**
+ * Added to the title element in both the X and Y axes of an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_AXIS_TITLE = "vjs-chart-axis-title";
+/**
+ * Added to the Y axis title element in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_Y_AXIS_TITLE = "vjs-chart-y-axis-title";
+/**
+ * Added to the X axis title element in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-axis
+ */
+export declare const CLASS_CHART_X_AXIS_TITLE = "vjs-chart-x-axis-title";
+/**
+ * Added to the container element of a column chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, column-chart
+ */
+export declare const CLASS_COLUMN_CHART = "vjs-column-chart";
+/**
+ * Added to each column element in a column chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, column-chart
+ */
+export declare const CLASS_COLUMN_CHART_COLUMN = "vjs-column-chart-column";
+/**
+ * Added to the container element in a bar chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, bar-chart
+ */
+export declare const CLASS_BAR_CHART = "vjs-bar-chart";
+/**
+ * Added to each bar element in a bar chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, bar-chart
+ */
+export declare const CLASS_BAR_CHART_BAR = "vjs-bar-chart-bar";
+/**
+ * Added to each point in a scatter/bubble chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,scatter-chart,bubble-chart
+ */
+export declare const CLASS_CHART_POINT = "vjs-chart-point";
+/**
+ * Added to the hit area elements that represent each data point. These are to assist users in selecting data points which are small.
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,scatter-chart,bubble-chart
+ */
+export declare const CLASS_CHART_POINT_HIT_AREA = "vjs-chart-point-hit-area";
+/**
+ * Added to  a bubble chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,scatter-chart
+ */
+export declare const CLASS_BUBBLE_CHART = "vjs-bubble-chart";
+/**
+ * Added to each point in a bubble chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,bubble-chart
+ */
+export declare const CLASS_BUBBLE_CHART_DATA_POINT = "vjs-bubble-chart-point";
+/**
+ * Added to  a scatter chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,scatter-chart
+ */
+export declare const CLASS_SCATTER_CHART = "vjs-scatter-chart";
+/**
+ * Added to each point in a scatter chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,scatter-chart
+ */
+export declare const CLASS_SCATTER_CHART_DATA_POINT = "vjs-scatter-chart-point";
+/**
+ * Added to the painted area element of an Area chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, area-chart
+ */
+export declare const CLASS_AREA_CHART_AREA = "vjs-area-chart-area";
+/**
+ * Added to the title element of a chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-title
+ */
+export declare const CLASS_CHART_TITLE = "vjs-chart-title";
+/**
+ * Added to the subtitle element of a chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-title
+ */
+export declare const CLASS_CHART_SUBTITLE = "vjs-chart-subtitle";
+/**
+ * Added to the crosshairs element of a chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-title
+ */
+export declare const CLASS_CHART_CROSSHAIR = "vjs-chart-crosshair";
+/**
+ * Added to the label of a value axis crosshair element
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-title
+ */
+export declare const CLASS_CHART_CROSSHAIR_LABEL = "vjs-chart-crosshair-label";
+/**
+ * Added to the value axis crosshair elements of a chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-title
+ */
+export declare const CLASS_CROSSHAIR_VALUE_AXIS = "vjs-chart-crosshair-value-axis";
+/**
+ * Added to the category axis crosshair elements of a chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, chart-title
+ */
+export declare const CLASS_CROSSHAIR_CATEGORY_AXIS = "vjs-chart-crosshair-category-axis";
+/**
+ * Added to the "No data" message that is shown when a chart is empty.
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_EMPTY = "vjs-chart-empty";
+/**
+ * Added to the labels of a value axis in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_SCALE_LABEL = "vjs-chart-axis-scale-label";
+/**
+ * Added to the parent SVG group of the gridlines in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_GRIDLINES = "vjs-chart-gridlines";
+/**
+ * Added to each gridline element in an XY chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts
+ */
+export declare const CLASS_CHART_GRIDLINE = "vjs-chart-gridline";
+/**
+ * Set on the container element for a line chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,line-chart
+ */
+export declare const CLASS_LINE_CHART = "vjs-line-chart";
+/**
+ * Set on the container element for an area chart
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts,area-chart
+ */
+export declare const CLASS_AREA_CHART = "vjs-area-chart";

package/types/charts/datasource.d.ts

@@ -0,0 +1,61 @@
+import { DataSource, ObjectData } from "../core";
+import { ChartModelFilter } from "./base-chart";
+import { SeriesBasedChart } from "./series-based-chart";
+/**
+ * Base definition for a chart data source.
+ */
+export interface ChartDataSource {
+    /**
+     * Returns whether or not there is any data available
+     */
+    hasData(): boolean;
+    /**
+     * Instruct the data source to load.
+     * @param onLoad
+     */
+    load(onLoad: () => any): void;
+}
+/**
+ * Implementation of data source that returns no data. Used in charts initially, before anything is loaded.
+ */
+export declare class BlankDataSource implements ChartDataSource {
+    load(onLoad: () => any): void;
+    hasData(): boolean;
+}
+/**
+ * Base data source for a SeriesBasedChart.
+ */
+export declare abstract class BaseSeriesBasedChartDataSource implements ChartDataSource {
+    chart: SeriesBasedChart<any>;
+    data: Array<ObjectData>;
+    protected constructor(chart: SeriesBasedChart<any>);
+    hasData(): boolean;
+    load(onLoad: () => any): void;
+}
+/**
+ * Data source for a SeriesBasedChart that reads data from an array of objects.
+ */
+export declare class DataSeriesBasedDataSource extends BaseSeriesBasedChartDataSource {
+    chart: SeriesBasedChart<any>;
+    data: Array<ObjectData>;
+    constructor(chart: SeriesBasedChart<any>, data: Array<ObjectData>);
+}
+/**
+ * Data source for a SeriesBasedChart that reads data from a URL. The data returned by the URL is expected to be an array of objects.
+ */
+export declare class UrlSeriesBasedDataSource extends BaseSeriesBasedChartDataSource {
+    chart: SeriesBasedChart<any>;
+    url: string;
+    constructor(chart: SeriesBasedChart<any>, url: string);
+    load(onLoad: () => any): void;
+}
+/**
+ * Data source for a SeriesBasedChart that reads data from a VisuallyJsModel or Selection.
+ */
+export declare class ModelSeriesBasedDataSource extends BaseSeriesBasedChartDataSource {
+    chart: SeriesBasedChart<any>;
+    dataSource: DataSource;
+    private filter;
+    constructor(chart: SeriesBasedChart<any>, dataSource: DataSource, filter: ChartModelFilter);
+    $setFilter(f: ChartModelFilter | null): void;
+}

package/types/charts/definitions.d.ts

@@ -0,0 +1,261 @@
+import { RectangleXY } from "../core";
+import { AxisTitleAlignment, AxisTitleSpec } from "./base-chart";
+import { ChartSVGElement, SteppedScale } from "./util";
+import { XYChartOptions } from "./base-xy-chart";
+import { DualValueSeriesOptions } from "./series";
+import { FontSpec } from "../browser-ui";
+/**
+ * @internal
+ */
+export interface ChartDimensions {
+    chartWidth: number;
+    chartHeight: number;
+    width: number;
+    height: number;
+    chartX: number;
+    chartY: number;
+    chartEndX: number;
+    chartEndY: number;
+    /**
+     * Charts can set this if they do any custom painting. it can then be used by the chart exporter.
+     */
+    viewBox?: RectangleXY;
+}
+export declare const ATTRIBUTE_CHART_CATEGORY = "data-vjs-chart-category";
+export declare const ATTRIBUTE_CHART_SERIES = "data-vjs-chart-series";
+export declare const ATTRIBUTE_CHART_STACK = "data-vjs-chart-stack";
+export declare const ATTRIBUTE_CHART_STACK_TOTAL = "data-vjs-chart-stack-total";
+export declare const ATTRIBUTE_CHART_VALUE = "data-vjs-chart-value";
+export declare const ATTRIBUTE_CHART_FILTERED_SERIES = "data-vjs-filter";
+export declare const AXIS_POSITION_START = "start";
+export declare const AXIS_POSITION_END = "end";
+export type AxisPosition = typeof AXIS_POSITION_START | typeof AXIS_POSITION_END;
+export type XYChartAxisDefinition = {
+    type: "value" | "category";
+    axes: Array<ValueAxisDefinition | CategoryAxisDefinition>;
+};
+/**
+ * @internal
+ */
+export interface AxisCommon {
+    showLine: boolean;
+    lineSize: number;
+    dim: RectangleXY;
+    element: ChartSVGElement;
+    labelsElement: ChartSVGElement;
+    id: string;
+    position: AxisPosition;
+    titleAlign: AxisTitleAlignment;
+    title: string | null;
+    titlePadding: number;
+    labels: Array<ChartSVGElement>;
+    type: "value" | "category";
+    titleElement: ChartSVGElement;
+    lineElement?: ChartSVGElement;
+    font: FontSpec;
+    crosshair: boolean | CrosshairOptions;
+}
+/**
+ * Common properties for value and category axes.
+ */
+export interface AxisDefinitionCommon {
+    /**
+     * Whether or not to show a solid line representing the axis' baseline. Defaults to false.
+     */
+    showLine?: boolean;
+    /**
+     * The width of the baseline (if visible). Defaults to 2 pixels.
+     */
+    lineSize?: number;
+    /**
+     * Title for the axis. Defaults to empty.
+     */
+    title?: AxisTitleSpec;
+    /**
+     * Axis ID.
+     */
+    id?: string;
+    /**
+     * The position for the axis: for a Y axis, AXIS_POSITION_START means on the left (this is the default for a y axis), and AXIS_POSITION_END means on the right. For an X axis, AXIS_POSITION_START means on the top, and AXIS_POSITION_END means on the bottom (the default for an X axis).
+     */
+    position?: AxisPosition;
+    /**
+     * Spec for the font to use for all text on the axis. If you provide a `title` spec for this axis, any font settings in that spec will override these for the title.
+     */
+    font?: FontSpec;
+    /**
+     * Whether to show a crosshair for this axis. If you supply 'true', defaults will be used. Otherwise you can supply options to customise the crosshair.
+     */
+    crosshair?: boolean | CrosshairOptions;
+}
+/**
+ * A value axis displays a set of values. It may be in either the X or Y axis, depending on how the chart is setup. For example, in a bar chart, the value axis is on the X axis, and the category axis is on the Y axis, but for a column chart it's the other way around. Scatter and bubble charts have a value axis in both X and Y.
+ * @group Charts
+ * @category Definitions
+ */
+export interface ValueAxisDefinition extends AxisDefinitionCommon {
+    /**
+     * Width of the grid lines. Defaults to 1 pixel.
+     */
+    gridLineSize?: number;
+    /**
+     * Whether or not to show grid lines for each value in the scale. Defaults to false.
+     */
+    showGrid?: boolean;
+    /**
+     * Minimum value for the axis. Defaults to not set. If this is set and your dataset has values below this value their visual representation in bar/column charts will be truncated. If you have a chart with multiple value axes and one or more of them declares a `min`, the smallest value for `min` will be used for all axes.
+     */
+    min?: number;
+    /**
+     * Maximum value for the axis. Defaults to not set. If this is set and your dataset has values above this value their visual representation in bar/column charts will be truncated. If you have a chart with multiple value axes and one or more of them declares a `max`, the largest value for `max` will be used for all axes.
+     */
+    max?: number;
+    /**
+     * Optional prefix for all value labels. Will be ignored if you provide a `labelFormatter`.
+     */
+    labelPrefix?: string;
+    /**
+     * Optional suffix for all value labels. Will be ignored if you provide a `labelFormatter`.
+     */
+    labelSuffix?: string;
+    /**
+     * Optional formatter for all value labels.
+     */
+    labelFormatter?: (value: number) => string;
+    /**
+     * Whether or not to invert the axis. If true, the axis will run from max to min instead of min to max.
+     */
+    inverted?: boolean;
+}
+/**
+ * A concrete instance of a value axis - it has the fields from ValueAxisDefinition as well as its location in x/y (and its dimensions? and element?)
+ * @internal
+ */
+export interface ValueAxis extends AxisCommon {
+    type: "value";
+    showGrid: boolean;
+    gridLineSize: number;
+    min: number;
+    max: number;
+    useSeriesTotal: boolean;
+    scale: SteppedScale;
+    stackedScale: SteppedScale;
+    domain: string;
+    stackedDomain?: string;
+    isPercent?: boolean;
+    labelPrefix?: string;
+    /**
+     * Optional suffix for all value labels. Will be ignored if you provide a `labelFormatter`.
+     */
+    labelSuffix?: string;
+    /**
+     * Optional formatter for all value labels.
+     */
+    labelFormatter?: (value: number) => string;
+    inverted?: boolean;
+}
+/**
+ * Definition of a category axis
+ * @group Charts
+ * @category Definitions.
+ */
+export interface CategoryAxisDefinition extends AxisDefinitionCommon {
+    labelField?: string;
+}
+/**
+ * @internal
+ */
+export interface CategoryAxis extends AxisCommon {
+    type: "category";
+    labelField: string;
+}
+/** @internal */
+export declare const DEFAULT_AXIS_LINE_SIZE = 2;
+/** @internal */
+export declare const DEFAULT_CORNER_RADIUS = 5;
+/** @internal */
+export declare const DEFAULT_VALUE_AXIS_PADDING = 10;
+/** @internal */
+export declare const DEFAULT_TITLE_PADDING = 20;
+export declare const DEFAULT_VALUE_AXIS_FONT_SIZE = 14;
+export declare const DEFAULT_CATEGORY_AXIS_FONT_SIZE = 14;
+export declare const DEFAULT_VALUE_AXIS_FONT_STYLE = "normal";
+export declare const DEFAULT_CATEGORY_AXIS_FONT_STYLE = "normal";
+/** @internal */
+export type DualValueChartAxis = {
+    min: number;
+    max: number;
+};
+/**
+ * Options for a dual value chart
+ * @group Charts
+ */
+export interface DualValueChartOptions extends XYChartOptions<DualValueSeriesOptions> {
+    /**
+     * Definition of the chart series' to display. You can plot multiple series on a chart.
+     */
+    series: Array<DualValueSeriesOptions>;
+    /**
+     * Configuration for the X axis.
+     */
+    xAxis?: ValueAxisDefinition;
+    /**
+     * Configuration for the Y axis.
+     */
+    yAxis?: ValueAxisDefinition;
+    /**
+     * Spec for the font to use for all text on the axes.
+     */
+    axisFont?: FontSpec;
+    /**
+     * Minimum allowed size for a marker. Defaults to 8 pixels. Set to -Infinity to have no minimum (this can have unpleasant UI side effects with some datasets)
+     */
+    minimumMarkerSize?: number;
+    /**
+     * Maximum allowed size for a marker. Defaults to 50 pixels. Set to Infinity to have no maximum (this can have unpleasant UI side effects with some datasets)
+     */
+    maximumMarkerSize?: number;
+}
+/**
+ * Options for the crosshair display on an axis.
+ * @group Charts
+ * @category Options
+ */
+export interface CrosshairOptions {
+    /**
+     * Color of the crosshair line.
+     */
+    color?: string;
+    /**
+     * Width of the crosshair line. Defaults to 1.
+     */
+    width?: number;
+    /**
+     * Optional CSS class to write to the crosshair element.
+     */
+    cssClass?: string;
+    /**
+     * Whether or not to show the current value on the crosshair. Defaults to true.
+     */
+    showLabel?: boolean;
+    /**
+     * Color for the label text. Defaults to the same color as the line.
+     */
+    labelColor?: string;
+    /**
+     * Position of the label on the crosshair. For a horizontal line, 'start' means 'left' and 'end' means 'right'. For a vertical line, 'start' means 'bottom' and 'end' means 'top'.
+     */
+    labelPosition?: "start" | "end";
+    /**
+     * Font for the label.
+     */
+    labelFont?: FontSpec;
+    /**
+     * Formatter for the label.
+     */
+    labelFormat?: string;
+    /**
+     * Standard number format for the value (e.g. 'int', 'float', or a number for decimal places).
+     */
+    labelValueFormat?: 'int' | 'float' | number;
+}

package/types/charts/domain_scale_utilities.d.ts

@@ -0,0 +1,72 @@
+import { SteppedScale } from "./util";
+/**
+ * Domain keys used internally to identify numeric dimensions to scale.
+ * Keep this flexible so charts/plots can introduce new domains like "r" or "yStacked".
+ * @internal
+ */
+export type AxisDomainKey = "x" | "y" | "xStacked" | "yStacked" | "r" | (string & {});
+/**
+ * Simple min/max extent for a numeric domain. Optionally with desired step specified
+ * @internal
+ */
+export interface DomainExtent {
+    min: number;
+    max: number;
+    stepCount?: number;
+}
+/**
+ * Extents by domain key.
+ * @internal
+ */
+export type DomainExtentMap = Partial<Record<AxisDomainKey, DomainExtent>>;
+/**
+ * Optional per-domain overrides (typically derived from user axis definitions).
+ * If provided, these are applied after merging extents.
+ * @internal
+ */
+export type DomainOverrideMap = Partial<Record<AxisDomainKey, {
+    min?: number;
+    max?: number;
+}>>;
+/**
+ * Output: scales by domain.
+ * @internal
+ */
+export type DomainScaleMap = Partial<Record<AxisDomainKey, SteppedScale>>;
+/**
+ * Merge multiple extent maps into one by taking:
+ * - min = minimum of mins
+ * - max = maximum of maxes
+ *
+ * Any invalid/non-finite extents are ignored.
+ * @internal
+ */
+export declare function mergeDomainExtents(extentsList: Array<DomainExtentMap | null | undefined>): DomainExtentMap;
+/**
+ * Apply overrides (min/max) to merged extents.
+ * - If override.min is set: extent.min = override.min
+ * - If override.max is set: extent.max = override.max
+ * - If overrides make min > max, they are swapped to keep a valid extent.
+ * @internal
+ */
+export declare function applyDomainOverrides(extents: DomainExtentMap, overrides?: DomainOverrideMap): DomainExtentMap;
+/**
+ * Build SteppedScale objects for each domain present in `extents`.
+ *
+ * Notes:
+ * - Uses the existing $autoCalculateChartScale(min, max) helper.
+ * - Skips domains whose extents are invalid.
+ * @internal
+ */
+export declare function buildDomainScales(extents: DomainExtentMap): DomainScaleMap;
+/**
+ * Convenience: merge → override → build scales.
+ * @internal
+ */
+export declare function computeDomainScales(params: {
+    extentsList: Array<DomainExtentMap | null | undefined>;
+    overrides?: DomainOverrideMap;
+}): {
+    extents: DomainExtentMap;
+    scales: DomainScaleMap;
+};