@visuallyjs/browser-ui 1.0.0

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

@@ -0,0 +1,31 @@
+import { ChartSeries, ChartSeriesOptions } from "./series";
+import { RealisedSeries } from "./definitions";
+export interface SummingCollationSeriesOptions extends ChartSeriesOptions {
+    /**
+     * Name of the field containing the category/key to group by.
+     */
+    categoryField: string;
+    /**
+     * Name of the field containing the numeric value to sum.
+     */
+    sumField: string;
+}
+export declare class SummingCollationSeries extends ChartSeries {
+    static type: string;
+    sums: Map<any, number>;
+    id: string;
+    color: string;
+    label: string;
+    /**
+     * Name of the field containing the category/key to group by.
+     */
+    categoryField: string;
+    /**
+     * Name of the field containing the numeric value to sum.
+     */
+    sumField: string;
+    constructor(options: SummingCollationSeriesOptions);
+    addValue(data: any): void;
+    reset(): void;
+    expand(): Array<RealisedSeries>;
+}

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

@@ -0,0 +1,19 @@
+import { ChartSeries, ChartSeriesOptions } from "./series";
+import { ObjectData } from "../../core";
+import { RealisedSeries } from "./definitions";
+export interface SummingSeriesOptions extends ChartSeriesOptions {
+    fields: Array<string>;
+    labels?: Array<string>;
+    colors?: Array<string>;
+}
+export declare class SummingSeries extends ChartSeries {
+    static type: string;
+    fields: Array<string>;
+    sums: Map<string, number>;
+    labels: Array<string>;
+    colors: Map<string, string>;
+    constructor(options: SummingSeriesOptions);
+    addValue(data: ObjectData): void;
+    reset(): void;
+    expand(): Array<RealisedSeries>;
+}

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

@@ -0,0 +1,59 @@
+import { BaseChart, BaseChartOptions, ChartModelFilter } from "./base-chart";
+import { ChartDataSource } from "./datasource";
+import { ChartSeries, ChartSeriesOptions } from "./series/series";
+import { ChartSVGElement } from "./util";
+import { DataSource, ObjectData } from "../core";
+/**
+ * Base options for a series based chart
+ */
+export interface SeriesBasedChartOptions<T extends ChartSeriesOptions> extends BaseChartOptions {
+    /**
+     * Definition of the chart series' to display. You can display multiple series on a chart.
+     */
+    series: Array<T>;
+    /**
+     * If true, the data will be grouped, if the chart type supports it (eg Bar/Column).
+     */
+    grouped?: boolean;
+    /**
+     * The name of the field that identifies which group a data point belongs to. Defaults to `group`.
+     */
+    groupField?: string;
+}
+/**
+ * Base class for charts that display one or more data series.
+ * @group Charts
+ */
+export declare abstract class SeriesBasedChart<T extends ChartSeriesOptions> extends BaseChart {
+    dataSource: ChartDataSource;
+    $__series: Array<ChartSeries>;
+    $focusedSeries: number | null;
+    seriesElements: Array<ChartSVGElement>;
+    $model: DataSource;
+    $modelFilter: ChartModelFilter;
+    $grouped: boolean;
+    $groupField: string;
+    private _seriesDefinitions;
+    constructor(container: HTMLElement | SVGElement, options: SeriesBasedChartOptions<T>);
+    $init(): void;
+    /**
+     * Loads chart data from a data object, URL, VisuallyJs model or Selection, in the latter two cases optionally with a filter.
+     * @param options
+     */
+    load(options: {
+        data?: Array<ObjectData>;
+        url?: string;
+        dataSource?: DataSource;
+        dataSourceFilter?: ChartModelFilter;
+    }, onload?: (chart: BaseChart) => any): void;
+    setDataSourceFilter(f: ChartModelFilter | null): void;
+    /**
+     * Reload the chart, without changing any of the options.
+     */
+    reload(): void;
+    $reset(): void;
+    $load(onload?: (chart: BaseChart) => any): void;
+    hasData(): boolean;
+    protected abstract $doReset(): void;
+    protected abstract $doLoad(): void;
+}

package/types/charts/tooltip.d.ts

@@ -0,0 +1,167 @@
+import { PointXY, ElementFacade, AbstractEntry, ObjectData } from "../core";
+import { BrowserUiRecado, BrowserElement, FontSpec } from "../browser-ui";
+import { RealisedSeries } from "./series/definitions";
+import { DualValueChartSeries } from "./series";
+/**
+ * Options for a tooltip
+ */
+export interface TooltipOptions {
+    /**
+     * Optional string to append to values
+     */
+    valueSuffix?: string;
+    /**
+     * The text to display. You can use template syntax to access a few context specific variables - see the docs for a discussion.
+     */
+    format: string;
+    /**
+     * Time to display the tooltip, in milliseconds, before hiding it. Defaults to 2500. Set this to -1 to have the Tooltip never hide automatically.
+     */
+    timeout?: number;
+    /**
+     * Optional font for the tooltip.
+     */
+    font?: FontSpec;
+    /**
+     * Fill color. Defaults to white.
+     */
+    fill?: string;
+    /**
+     * Outline color. Defaults to "#999999"
+     */
+    outline?: string;
+    /**
+     * Outline width. Defaults to 1.
+     */
+    outlineWidth?: number;
+    /**
+     * Corner radius for the tooltip. Defaults to 3px.
+     */
+    cornerRadius?: number;
+    /**
+     * Color for text. Defaults to system default.
+     */
+    textColor?: string;
+}
+/**
+ * Added to a chart tooltip's main element
+ * @group Charts
+ * @category CSS Classes
+ * @cssClass
+ * @context charts, tooltips
+ */
+export declare const CLASS_VJS_TOOLTIP = "vjs-tooltip";
+/**
+ * Extension of the template renderer to handle tooltips. Only `b`, `strong`, `em` and `br` elements are supported.
+ */
+export declare class TooltipRenderer extends BrowserUiRecado {
+    $adt: Array<AbstractEntry>;
+    constructor(o: TooltipOptions);
+    parseAndValidate(str: string): void;
+    ce(tag: string): ElementFacade;
+    renderTooltip(d: ObjectData): import("../core/templates/executions").IRootExecution;
+}
+/**
+ * Definition of the `series` object passed to a Tooltip
+ */
+export type TooltipDataSeries = {
+    /**
+     * Color used to represent the series
+     */
+    color: string;
+    /**
+     * Series minimum
+     */
+    min: number;
+    /**
+     * Series maximum
+     */
+    max: number;
+    /**
+     * Series total
+     */
+    total: number;
+    /**
+     * Label for the series
+     */
+    label: string;
+    /**
+     * The series ID.
+     */
+    id: string;
+};
+/**
+ * Definition of the `point` object passed to a Tooltip. Not every chart type provides every field - see the individual chart docs for discussions.
+ */
+export type TooltipDataPoint = {
+    /**
+     * Point value, as a string
+     */
+    value?: string;
+    /**
+     * Raw point value
+     */
+    rawValue?: number;
+    /**
+     * Min value, as a string. Only provided in charts displaying a range.
+     */
+    minValue?: string;
+    /**
+     * Raw min value. Only provided in charts displaying a range.
+     */
+    rawMinValue?: number;
+    /**
+     * Miax value, as a string. Only provided in charts displaying a range.
+     */
+    maxValue?: string;
+    /**
+     * Raw max value. Only provided in charts displaying a range.
+     */
+    rawMaxValue?: number;
+    /**
+     * Total for the current stack. Only provided when the chart is displaying a stacked series.
+     */
+    stackTotal?: number;
+};
+/**
+ * A tooltip created for use with Charts but can be used with apps and diagrams.
+ */
+export declare class Tooltip {
+    private parentElement;
+    root: SVGElement;
+    g: SVGElement;
+    bg: SVGRectElement;
+    text: SVGTextElement;
+    private $parser;
+    $paddingX: number;
+    $paddingY: number;
+    $valueSuffix: string;
+    _timeout: number;
+    _timeoutHandle: number;
+    constructor(parentElement: BrowserElement, options: TooltipOptions);
+    private _setTimeout;
+    private $renderTooltip;
+    protected formatValue(v: number | null): string;
+    /**
+     * Show the tooltip at the given position, which is a point relative to the origin of the Tooltip's container
+     * @param position
+     * @param tooltipAnchor
+     * @param payload
+     * @protected
+     */
+    protected show(position: PointXY, tooltipAnchor: PointXY, payload: ObjectData): void;
+    protected showAtPageLocation(pageLocation: PointXY, tooltipAnchor: PointXY, payload: ObjectData): void;
+    hide(): void;
+}
+export declare class CategoryValueTooltip extends Tooltip {
+    showTooltip(position: PointXY, tooltipAnchor: PointXY, series: RealisedSeries, category: string, point: {
+        value?: number;
+        stackTotal?: number;
+        stackId?: string;
+        minValue?: number;
+        maxValue?: number;
+    }): void;
+}
+export declare class DualValueAxisTooltip extends Tooltip {
+    showTooltip(position: PointXY, tooltipAnchor: PointXY, series: DualValueChartSeries, point: ObjectData): void;
+}

package/types/charts/util.d.ts

@@ -0,0 +1,149 @@
+import { BrowserElement, FontSpec, FontStyle } from "../browser-ui";
+import { BaseChart } from "./base-chart";
+import { RectangleXY } from "../core";
+import { AxisCommon, CategoryAxis, ValueAxis } from "./definitions";
+/**
+ * internal candidate for a stepped scale.
+ * @internal
+ */
+interface SteppedScaleCandidate {
+    minScale: number;
+    maxScale: number;
+    stepCount: number;
+    step: number;
+}
+/**
+ * Values defining a stepped scale - min, max, step size, step count, and an array of values for the steps.
+ * @internal
+ */
+export interface SteppedScale extends SteppedScaleCandidate {
+    steps: Array<number>;
+    range: number;
+    dataMin: number;
+    dataMax: number;
+}
+/**
+ * For the given min and max, calculate the lowest step value required, and the highest step value required, and the number of steps in between these values. For instance if you entered -145, 45 as the min/max, with a candidate step of 10, then the stepMin calculated would be -150, the stepMax calculated would be 50, and there'd be 20 steps. This method is used in the auto step generator but can also be used then the user has mandated a step size.
+ * @param min
+ * @param max
+ * @param candidateStep
+ * @internal
+ */
+export declare function _calculateSteps(min: number, max: number, candidateStep: number): SteppedScaleCandidate;
+/**
+ * For some given min/max, compute the ideal step size to use as a range. candidateStep is
+ * the first value to try; it might be ideal, in which case we use it. But if not, we try
+ * the step above (if we had too many steps) or the step below (if we had too few steps).
+ * @param min
+ * @param max
+ * @param candidateStep
+ * @internal
+ */
+export declare function _findIdealSteps(min: number, max: number, candidateStep: number, idealStepCount: number): SteppedScale;
+/**
+ * Calculates a reasonable scale for the dataset with the given min and max.
+ * @param min
+ * @param max
+ * @internal
+ */
+export declare function $autoCalculateChartScale(min: number, max: number, idealStepCount?: number): SteppedScale;
+/**
+ * Calculates a scale with the exact number of steps between min and max (inclusive). It is the call site's responsibility to ensure that the numbers all relate in such a way that the labels are reasonable.
+ * @param min
+ * @param max
+ * @param stepCount
+ * @internal
+ */
+export declare function $calculateChartScaleWithSteps(min: number, max: number, stepCount: number): SteppedScale;
+/**
+ * Calculates the power of 10 corresponding to the given number, eg 625 000 gives '3'
+ * @param n
+ * @internal
+ */
+export declare function calculatePowerOf10(n: number): number;
+/**
+ * Prepare a font spec from the given defaults and candidate. Values are chosen from the candidate by preference, or by the default otherwise. the candidate does not need to exist; call sites can safely pass a null value in here.
+ * @param defaultSize
+ * @param defaultStyle
+ * @param candidate
+ * @internal
+ */
+export declare function $prepareFontSpec(defaultSize: number, defaultStyle: FontStyle, defaultWeight: string | number, defaultFamily: string, candidate?: FontSpec): FontSpec;
+/**
+ * Helper method to create SVG element for use in a chart.
+ * @internal
+ * @param tag
+ * @param atts
+ * @param clazz
+ * @param parent
+ */
+export declare function createChartElement(tag: string, atts: Record<string, any>, clazz?: string, parent?: BrowserElement): ChartSVGElement;
+/**
+ * @internal
+ * @param text
+ * @param atts
+ * @param clazz
+ * @param parent
+ */
+export declare function createChartTextElement(text: string, atts: Record<string, any>, clazz?: string, parent?: BrowserElement): ChartSVGElement;
+/**
+ * @internal
+ * @param el
+ * @param x
+ */
+export declare function setTranslatedX(el: ChartSVGElement, x: number): void;
+/**
+ * @internal
+ * @param el
+ * @param y
+ */
+export declare function setTranslatedY(el: ChartSVGElement, y: number): void;
+/**
+ * @internal
+ * @param el
+ * @param x
+ * @param y
+ */
+export declare function setTranslatedPosition(el: BrowserElement, x: number, y: number): void;
+/**
+ * @internal
+ */
+export interface ChartSVGElement extends SVGElement {
+    getBBox(): RectangleXY;
+    parentNode: ChartSVGElement;
+}
+/**
+ * @internal
+ * @param a
+ */
+export declare function isValueAxis(a: AxisCommon): a is ValueAxis;
+/**
+ * @internal
+ * @param a
+ */
+export declare function isCategoryAxis(a: AxisCommon): a is CategoryAxis;
+/**
+ * @internal
+ */
+export declare function emptyBox(): RectangleXY;
+export declare function formatValue(value: number, format?: 'int' | 'float' | number): string;
+/**
+ * @internal
+ * @param labels
+ */
+export declare function $spaceLabels(labels: Array<ChartSVGElement>, maxAllowedSize: number, axisProperty: "height" | "width", otherAxisProperty: "height" | "width"): boolean;
+export declare function createContrastLabel(text: string, x: number, y: number, color: string, font: FontSpec, parent?: ChartSVGElement): ChartSVGElement;
+/**
+ * Returns an export of the chart's container.
+ * All CSS classes, data-vjs-*** attributes and pointer-events attributes are stripped from the output.
+ * Crosshair elements are also removed.
+ * @param chart The chart to export.
+ * @param width Optional width for the output SVG.
+ * @param height Optional height for the output SVG.
+ */
+export declare function exportSVG(chart: BaseChart, width?: number, height?: number): {
+    element: SVGElement;
+    extents: RectangleXY;
+    svg: string;
+};
+export {};

package/types/core/astar/astar-path-finder.d.ts

@@ -0,0 +1,37 @@
+import { AdjacentCellsFinder, AStarPath, AStarPathConstrainment, DistanceHeuristic } from "./definitions";
+import { AStarGrid } from "./astar-util";
+import { RectangleXY, LineXY, PointXY } from "../util";
+import { HasId, HasWidthHeight, HasXY } from "../model/graph";
+/**
+ * Runs the A* path finder.
+ *
+ * @param source
+ * @param target
+ * @param sourceId
+ * @param targetId
+ * @param sourceOrientation
+ * @param targetOrientation
+ * @param gridCellSize
+ * @param constrain Movement constraint when selecting candidate cells.
+ * @param distanceHeuristic The heuristic to use when estimating the distance between two cells in the grid.
+ * @param vertexBorder Number of cells to pad around each vertex to establish its 'border' - the vertex and the border
+ * region are considered as obstacles.
+ * @param vertexBuffer Number of cells to pad around each vertex's border to use as the buffer zone, through which paths
+ * may traverse. Although with taking out the line of sight finder this concept is probably redundant now.
+ * @param getObstacles
+ * @param getObstaclesRect
+ * @param getAdjacentCells
+ * @param hasLineOfSight
+ * @param grid
+ * @param pathId
+ * @internal
+ */
+export declare function astar(source: PointXY, target: PointXY, sourceId: string, targetId: string, sourceOrientation: {
+    ox: 1 | 0 | -1;
+    oy: 1 | 0 | -1;
+}, targetOrientation: {
+    ox: 1 | 0 | -1;
+    oy: 1 | 0 | -1;
+}, gridCellSize: number, constrain: AStarPathConstrainment, distanceHeuristic: DistanceHeuristic, vertexBorder: number, vertexBuffer: number, getObstacles: (x: number, y: number, margin?: number) => Array<AStarObstacle>, getObstaclesRect: (rect: RectangleXY, margin?: number) => Array<AStarObstacle>, getAdjacentCells: AdjacentCellsFinder, hasLineOfSight: (grid: AStarGrid, l: LineXY) => boolean, grid?: AStarGrid, pathId?: string): AStarPath;
+export interface AStarObstacle extends HasId, HasXY, HasWidthHeight {
+}

package/types/core/astar/astar-util.d.ts

@@ -0,0 +1,100 @@
+import { DirectionFromParent, ParentAxis, PathFinderGridCell } from "./definitions";
+import { AStarObstacle } from "./astar-path-finder";
+import { PointXY, RectangleXY } from "../util";
+/**
+ * Grid for an A* path search. Access to grid cells is via the `getCell` method, which lazy loads cell entries. This implementation uses an object in the back end, whose keys are in the form `${x}_${y}`. The advantage of this is that no storage has to be allocated at the start, and the size of the content does not need to be known. It would be good to be able to reuse this grid...somehow.
+ * @internal
+ */
+export declare class AStarGrid {
+    gridCellSize: number;
+    vertexBorder: number;
+    vertexBuffer: number;
+    private getCoincidentObstacles;
+    private _grid;
+    private _canvasOrigin;
+    private readonly _obstaclePadding;
+    constructor(source: PointXY, target: PointXY, gridCellSize: number, vertexBorder: number, vertexBuffer: number, getCoincidentObstacles: (canvasX: number, canvasY: number, padding: number) => Array<AStarObstacle>);
+    /**
+     * Map the given x,y in canvas coordinates to the coordinates of the grid cell the point lies in.
+     * @param x
+     * @param y
+     * @private
+     */
+    _mapCanvasLocationToGridCell(x: number, y: number): PointXY;
+    _mapCanvasRectangleToGridCells(r: RectangleXY): RectangleXY;
+    _mapGridCellToCanvas(gridX: number, gridY: number): RectangleXY;
+    sourceId: string;
+    targetId: string;
+    sourceObstacles: Array<string>;
+    targetObstacles: Array<string>;
+    sourceBuffers: Array<string>;
+    targetBuffers: Array<string>;
+    sourceAxis: ParentAxis;
+    sourceDirection: DirectionFromParent;
+    targetAxis: ParentAxis;
+    targetDirection: DirectionFromParent;
+    makeKey(x: number, y: number): string;
+    private _shouldIgnoreObstacle;
+    private _getCell;
+    setSourceCell(id: string, x: number, y: number, ax: number, ay: number, axis: ParentAxis, direction: DirectionFromParent): PathFinderGridCell;
+    setTargetCell(id: string, x: number, y: number, ax: number, ay: number, axis: ParentAxis, direction: DirectionFromParent): PathFinderGridCell;
+    get sourceAndTargetObstacles(): string[];
+    /**
+     * Gets a cell from the grid, lazy loading it if it does not exist.
+     * @param x Grid X
+     * @param y Grid Y
+     * @param ax Absolute X to set in the cell. Optional. Will be overwritten into a cell that was pulled from cache.
+     * @param ay Absolute Y to set in the cell. Optional. Will be overwritten into a cell that was pulled from cache.
+     */
+    getCell(x: number, y: number, ax: number, ay: number): PathFinderGridCell;
+    /**
+     * reinit the grid, which means to reset f,g and h values (and parent refs/axis etc), but NOT to clear out any edges. also we want to leave `occupied` but for that to be reusable it should contain a list of vertex ids, not just a boolean: we have to take into account source/target obstacles when deciding whether a cell should be excluded.
+     */
+    reinitialize(): void;
+}
+/**
+ * Infer what the given orientation in X and Y represents in terms of an axis. Used by the path finder internally
+ * for the start and end nodes.
+ * @param ox
+ * @param oy
+ * @internal
+ */
+export declare function inferAxis(ox: number, oy: number): ParentAxis;
+export declare function inferDirection(ox: number, oy: number, axis: ParentAxis | undefined): DirectionFromParent;
+/**
+ * Infer an axis of travel and a direction from the given orientation. Used when
+ * starting a path find.
+ * @param o
+ * @internal
+ */
+export declare function inferAxisAndDirectionFromOrientation(o: {
+    ox: 1 | 0 | -1;
+    oy: 1 | 0 | -1;
+}): {
+    axis: ParentAxis;
+    direction: DirectionFromParent;
+};
+/**
+ * Infer an axis of travel (either vertical or horizontal) between source and target by
+ * examining their delta in each axis. Whichever axis has the greater delta is the one we choose.
+ * This method is a fallback for when we cannot infer an axis from the orientation of the
+ * source or target anchor point.
+ * @param source
+ * @param target
+ * @internal
+ */
+export declare function inferAxisFromSourceAndTargetLocation(source: PointXY, target: PointXY): ParentAxis;
+/**
+ * For some grid cell, determine the axis relationship with its parent. The start and end cells have `fixedAxis` set,
+ * which comes from the associated anchor's orientation. For other cells we compute the axis based upon the grid
+ * locations of this cell and its parent.
+ * @param cell
+ * @internal
+ */
+export declare function parentAxis(cell: PathFinderGridCell): ParentAxis;
+/**
+ * For some grid cell, determine the direction of travel from its parent cell.
+ * @param cell
+ * @internal
+ */
+export declare function parentDirection(cell: PathFinderGridCell): DirectionFromParent;

package/types/core/astar/candidate-finder.d.ts

@@ -0,0 +1,16 @@
+import { AdjacentCellsFinder, PathCandidateCell, PathFinderGridCell } from "./definitions";
+import { AStarGrid } from "./astar-util";
+import { AStarObstacle } from "./astar-path-finder";
+/**
+ * Find candidate next cells for A* path finder.
+ * @internal
+ * @param grid
+ * @param focus
+ * @param x
+ * @param y
+ * @param gridCellSize
+ * @param getObstacles
+ * @param getAdjacentCells
+ * @param targetCell
+ */
+export declare function findCandidates(grid: AStarGrid, focus: PathFinderGridCell, x: number, y: number, gridCellSize: number, getObstacles: (x: number, y: number, margin?: number) => Array<AStarObstacle>, getAdjacentCells: AdjacentCellsFinder, targetCell: PathFinderGridCell): Array<PathCandidateCell>;

package/types/core/astar/candidate-sorter.d.ts

@@ -0,0 +1,10 @@
+import { PathFinderGridCell } from "./definitions";
+/**
+ * Sorter for path candidates.
+ * @internal
+ */
+export declare class CandidateSorter {
+    node: PathFinderGridCell;
+    constructor();
+    sort(n1: PathFinderGridCell, n2: PathFinderGridCell): 0 | 1 | -1;
+}