@reside-ic/skadi-chart 1.0.0

package/README.md

@@ -0,0 +1,266 @@
+# Skadi Chart
+
+This charting library provides a structured and thin wrapper around [d3](https://d3js.org)
+to provide an fully flexible and extensible interface to plot customised graphs that
+out-of-the-box solutions haven't prepared for.
+
+There are many examples in [src/demo/App.vue](./src/demo/App.vue) which are used in a Vue context
+however this library will work with TypeScript or JavaScript too. Developer facing docs are in
+[DEV_README](./DEV_README.md).
+
+# Installation
+
+```
+npm i @reside-ic/skadi-chart
+```
+
+# Usage
+
+## Example
+
+Here is a quick example of using Skadi chart:
+
+```html
+<div id="chart"></div>
+```
+
+```ts
+import {
+    Lines,
+    ScatterPoints,
+    TooltipHtmlCallback,
+    Scales,
+    OptionalLayer,
+    LayerType,
+    LayerArgs
+} from "@reside-ic/skadi-chart";
+
+// get element from html document
+const chart = document.getElementById("chart") as HTMLDivElement;
+
+// example custom metadata: define a type that you can attach to lines or scatter points
+type Metadata = { type: "line" | "point" }
+
+// two straight lines
+const lines: Lines<Metadata> = [
+    {
+        points: [
+            { x: 0, y: 0 },
+            { x: 1, y: 1 },
+        ],
+        style: { color: "black" },
+        metadata: { type: "line" }
+    },
+    {
+        points: [
+            { x: 0, y: 0 },
+            { x: 1, y: 2 },
+        ],
+        style: { color: "red" },
+        metadata: { type: "line" }
+    },
+];
+
+// two points
+const points: ScatterPoints<Metadata> = [
+    {
+        x: 0.5, y: 0.5,
+        style: { radius: 2 },
+        metadata: { type: "point" }
+    },
+    {
+        x: 0.5, y: 1,
+        style: { radius: 1 },
+        metadata: { type: "point" }
+    },
+];
+
+// custom tooltip with html string
+const tooltipHtmlCallback: TooltipHtmlCallback = ({ x, y, metadata }) => {
+    return `<p>Point x=${x}, y=${y} is a ${metadata.type}</p>`
+};
+
+// define x axis scale. The chart can compute y by autoscaling based on
+// the data, or you could provide specific values for y here instead. 
+const scales: Scales = {
+    x: { start: 0, end: 1 }
+};
+
+// can extend Skadi chart with whatever functionality you'd like but it
+// must fulfil the OptionalLayer contract
+class CustomLayer extends OptionalLayer {
+    type = LayerType.Custom;
+    constructor() { super() };
+
+    // adds a black circle to the svg
+    draw(layerArgs: LayerArgs): void {
+        const svg = layerArgs.coreLayers[LayerType.Svg];
+        const { getHtmlId } = layerArgs;
+        svg.append("svg:circle")
+          .attr("id", `${getHtmlId(this.type)}-circle`)
+          .attr("cx", "50%")
+          .attr("cy", "50%")
+          .attr("r", "5%")
+    }
+}
+
+new Chart()
+  .addAxes()
+  .addTraces(lines)
+  .addScatterPoints(points)
+  .addGridLines()
+  .addZoom()
+  .addTooltips(tooltipHtmlCallback)
+  .addCustomLayer(new CustomLayer())
+  .addCustomLifecycleHooks({ beforeZoom() { console.log("triggering before zoom") } })
+  .makeResponsive()
+  .appendTo(chart, scales);
+```
+
+# More details
+
+## Base chart class
+
+All charts start with the `Chart` class that takes in `ChartOptions` (e.g. `animationDuration`
+in ms or `logScale`, see [here](./src/Chart.ts) for source code):
+
+```ts
+const chart = new Chart({ animationDuration: 500 });
+```
+
+## Layers
+
+Skadi chart works in layers. Each layer "adds" something to the graph but also is completely
+optional. 
+
+### OptionalLayer and event handling
+
+An optional layer in Skadi chart is a layer that extends the abstract class
+[OptionalLayer](./src/layers/Layer.ts). This abstract class will expect the layers to define
+a `draw` function that will be used when the layer is added to the svg.
+
+Furthermore, it defines the lifecycle hooks a layer can plug into. Lifecycle hooks are how
+the layers react to user events. For example, the layers can each define a `zoom` method that
+the [ZoomLayer](./src/layers/ZoomLayer.ts) will call on each of the layers when the user
+selects an area to zoom into.
+
+### Adding layers
+
+To add a ready-made layer to the chart, call one of the methods below. The order of appending
+layers does not matter however currently the multiplicity of layers does matter, i.e if you
+add 2 [AxesLayer](./src/layers/AxesLayer.ts)s it will draw 2 of them which may be unintended.
+These methods can also take some arguments that configure how the layers appear and examples
+of each can be found in [src/demo/App.vue](./src/demo/App.vue). For now, this is just an
+overview of the methods [Chart](./src/Chart.ts) class provides for adding layers:
+
+* `addAxes` adds an [AxesLayer](./src/layers/AxesLayer.ts). This will draw axes with tick
+marks. The axes can be autoscaled based on your data or you can provide a fixed scale in
+the `appendTo` function below.
+  ```ts
+  chart.addAxes();
+  ```
+* `addTraces` adds a [TracesLayer](./src/layers/TracesLayer.ts). This will add traces to
+the graph. This data will also be used for autoscaling the axes if you haven't provided a
+fixed scale.
+  ```ts
+  chart.addTraces(lines);
+  ```
+* `addScatterPoints` add a [ScatterLayer](./src/layers/ScatterLayer.ts). This will add
+scatter points to the graph. This data will also be used for autoscaling the axes if you
+haven't provided a fixed scale.
+  ```ts
+  chart.addScatterPoints(points);
+  ```
+* `addGridLines` adds a [GridLayer](./src/layers/GridLayer.ts). This will add gridlines
+to the graph.
+  ```ts
+  chart.addGridLines();
+  ```
+* `addZoom` adds a [ZoomLayer](./src/layers/ZoomLayer.ts) which will render a brush (let
+the user draw a rectangle where they wish to zoom) and provide these extents to each layer.
+Each layer itself defines how it zooms so this will let the user zoom on your graph.
+  ```ts
+  chart.addZoom();
+  ```
+* `addTooltips` adds a [TooltipLayer](./src/layers/TooltipsLayer.ts) which adds tooltips
+to the chart. For traces and points this means the tooltip will appear pointing to the
+closest point in the graph to the cursor (once it is within a threshold). You must provide
+a callback returning HTML to render the tooltip.
+  ```ts
+  chart.addTooltips(tooltipHtmlCallback);
+  ```
+* `makeResponsive` is not really a layer but will make your graph responsive (redraw on change
+to container bounds and changes to window size).
+  ```ts
+  chart.makeResponsive();
+  ```
+
+#### Extending Skadi chart with custom layers
+
+You can extend Skadi chart's functionality to suit your needs by defining a `CustomLayer`, as
+long as it fulfils the contract of the class `OptionalLayer` found [here](./src/layers/Layer.ts).
+Currently the `OptionalLayer` only requires you to define 2 things:
+
+* the `type` of your `CustomLayer` which
+should be `LayerType.Custom` (`LayerType` is an exported enum from the same file) in most cases.
+* the `draw` function which will usually involve creating svg elements
+* the `constructor` which needs to call `super`
+
+In the example below, we define our `type` as `LayerType.Custom` and we define `draw` as adding a
+black svg circle onto our graph using [d3.select](https://d3js.org/d3-selection/selecting).
+
+We also declare a `beforeZoom` function to print a message before the zoom occurs. This is a
+lifecycle hook that we can use to interact with the hook layer. For all the lifecycle hooks see
+[here](./src/layers/Layer.ts).
+
+```ts
+class CustomLayer extends OptionalLayer {
+    type = LayerType.Custom;
+    constructor() { super() };
+
+    // adds a black circle to the svg
+    draw(layerArgs: LayerArgs): void {
+        const svg = layerArgs.coreLayers[LayerType.Svg];
+        const { getHtmlId } = layerArgs;
+        svg.append("svg:circle")
+          .attr("id", `${getHtmlId(this.type)}-circle`)
+          .attr("cx", "50%")
+          .attr("cy", "50%")
+          .attr("r", "5%")
+    }
+
+    beforeZoom() { console.log("triggering before zoom") }
+}
+
+chart.addCustomLayer(new CustomLayer());
+```
+
+If we didn't want to draw anything to the svg and instead wanted to execute some code
+via the lifecycle hooks, the`addCustomLifecycleHooks` offers an easier interface to do
+this. It is a convenience wrapper around `addCustomLayer`.
+```ts
+chart.addCustomLifecycleHooks({
+    beforeZoom() { console.log("triggering before zoom") }
+});
+```
+
+## Drawing chart with all the layers
+
+Once we have added all the layers, we must call `appendTo` function to draw the layers to the
+screen. Without calling this function, nothing will be drawn to the screen. Here we can also
+provide the scales to the graph if we want it to display a fixed scale rather than
+automatically choosing a scale based on your data.
+
+```ts
+chart.appendTo(element, scales);
+```
+
+## Reactivity
+
+There is some reactivity baked into Skadi chart via the lifecycle hooks, such as zooming. In
+general however there is very little reactivity that Skadi chart offers, e.g. there are not
+any functions that will remove layers after the chart is appended to the DOM.
+
+The pattern we use for reactivity outside of the scope of lifecycle hooks is to recreate the
+chart from scratch. The `appendTo` function will remove anything inside the chart `div` and
+append the new `Chart` into it. To see examples of reactivity see [here](./src/demo/App.vue).

package/dist/skadi-chart.d.ts

@@ -0,0 +1,290 @@
+declare module "d3" {
+    import { select } from "d3-selection";
+    export { select };
+    export { type Axis, axisBottom, axisLeft } from "d3-axis";
+    export { line, type Line } from "d3-shape";
+    export { create, type BaseType, type Selection, type ClientPointEvent, pointer } from "d3-selection";
+    export { brush, type D3BrushEvent } from "d3-brush";
+    export { scaleBand, scaleLinear, scaleLog, type NumberValue, type ScaleBand, type ScaleContinuousNumeric } from "d3-scale";
+}
+declare module "types" {
+    import { ChartOptions } from "Chart";
+    import * as d3 from "d3";
+    import { LayerType, OptionalLayer } from "layers/Layer";
+    export type AxisType = 'x' | 'y';
+    export type XY<T> = Record<AxisType, T>;
+    export type Point = XY<number>;
+    export type PointWithMetadata<Metadata> = Point & {
+        metadata?: Metadata;
+        bands?: Partial<XY<string>>;
+    };
+    export type XYLabel = Partial<XY<string>>;
+    export type Bounds = {
+        width: number;
+        height: number;
+        margin: {
+            top: number;
+            bottom: number;
+            left: number;
+            right: number;
+        };
+    };
+    export type D3Selection<Element extends d3.BaseType> = d3.Selection<Element, Point, null, undefined>;
+    export type AllOptionalLayers = OptionalLayer<any>;
+    export type ScaleNumeric = d3.ScaleContinuousNumeric<number, number, never>;
+    export type CategoricalScaleConfig = {
+        main: d3.ScaleBand<string>;
+        bands: Record<string, ScaleNumeric>;
+    };
+    export type TickConfig = {
+        count: number;
+        specifier?: string;
+    };
+    export type LayerArgs = {
+        id: string;
+        getHtmlId: (layer: LayerType) => string;
+        bounds: Bounds;
+        globals: {
+            animationDuration: number;
+            tickConfig: XY<TickConfig>;
+        };
+        scaleConfig: {
+            linearScales: XY<ScaleNumeric>;
+            scaleExtents: Scales;
+            categoricalScales: Partial<XY<CategoricalScaleConfig>>;
+        };
+        coreLayers: {
+            [LayerType.Svg]: D3Selection<SVGSVGElement>;
+            [LayerType.ClipPath]: D3Selection<SVGClipPathElement>;
+            [LayerType.BaseLayer]: D3Selection<SVGGElement>;
+        };
+        optionalLayers: AllOptionalLayers[];
+        chartOptions: ChartOptions;
+    };
+    export type ZoomExtents = XY<[number, number]>;
+    export type ZoomProperties = ZoomExtents & {
+        eventType: "brush" | "dblclick";
+    };
+    export type Scales = XY<{
+        start: number;
+        end: number;
+    }>;
+    export type PartialScales = Partial<XY<{
+        start?: number;
+        end?: number;
+    }>>;
+    export type LineStyle = {
+        color?: string;
+        opacity?: number;
+        strokeWidth?: number;
+        strokeDasharray?: string;
+    };
+    export type LineConfig<Metadata> = {
+        points: Point[];
+        style: LineStyle;
+        metadata?: Metadata;
+        bands?: Partial<XY<string>>;
+    };
+    export type Lines<Metadata> = LineConfig<Metadata>[];
+    export type ScatterPointStyle = {
+        radius?: number;
+        color?: string;
+        opacity?: number;
+    };
+    type ScatterPointConfig<Metadata> = PointWithMetadata<Metadata> & {
+        style: ScatterPointStyle;
+    };
+    export type ScatterPoints<Metadata> = ScatterPointConfig<Metadata>[];
+}
+declare module "layers/Layer" {
+    import { LayerArgs, ZoomExtents, ZoomProperties } from "types";
+    export enum LayerType {
+        Svg = "svg",
+        ClipPath = "clipPath",
+        BaseLayer = "baseLayer",
+        Axes = "axes",
+        Zoom = "zoom",
+        Trace = "trace",
+        Tooltip = "skadi-chart-tooltip",
+        Grid = "grid",
+        Scatter = "scatter",
+        Custom = "custom"
+    }
+    export abstract class OptionalLayer<Properties = null> {
+        abstract type: LayerType;
+        properties: Properties | null;
+        constructor();
+        abstract draw(layerArgs: LayerArgs, currentExtents: ZoomExtents): void;
+        brushStart(): void;
+        beforeZoom(_zoomProperties: ZoomProperties): void;
+        zoom(_zoomProperties: ZoomProperties): Promise<void>;
+        afterZoom(_zoomProperties: ZoomProperties | null): void;
+    }
+    export type LifecycleHooks = Omit<OptionalLayer, "type" | "properties" | "draw">;
+}
+declare module "layers/AxesLayer" {
+    import { LayerType, OptionalLayer } from "layers/Layer";
+    import { LayerArgs, XYLabel } from "types";
+    export class AxesLayer extends OptionalLayer {
+        labels: XYLabel;
+        type: LayerType;
+        constructor(labels: XYLabel);
+        private drawAxis;
+        draw: (layerArgs: LayerArgs) => void;
+        private drawCategoricalAxis;
+        private drawNumericalAxis;
+        private drawLinePerpendicularToAxis;
+        private axisConfig;
+    }
+}
+declare module "helpers" {
+    import { LayerArgs, ScaleNumeric, XY } from "types";
+    export const numScales: (bands: Partial<XY<string>> | undefined, layerArgs: LayerArgs) => XY<ScaleNumeric>;
+}
+declare module "layers/TracesLayer" {
+    import { LayerArgs, Lines, Point, ZoomExtents } from "types";
+    import { LayerType, OptionalLayer } from "layers/Layer";
+    export type TracesOptions = {
+        RDPEpsilon: number | null;
+    };
+    export const RDPAlgorithm: (linesSC: Point[][], epsilon: number) => Point[][];
+    export class TracesLayer<Metadata> extends OptionalLayer {
+        linesDC: Lines<Metadata>;
+        options: TracesOptions;
+        type: LayerType;
+        private traces;
+        private lowResLinesSC;
+        private getNewPoint;
+        constructor(linesDC: Lines<Metadata>, options: TracesOptions);
+        private customTween;
+        private round;
+        private getNewSvgPoint;
+        private customLineGen;
+        private updateLowResLinesSC;
+        draw: (layerArgs: LayerArgs, currentExtentsDC: ZoomExtents) => void;
+    }
+}
+declare module "layers/ZoomLayer" {
+    import { LayerType, OptionalLayer } from "layers/Layer";
+    import { D3Selection, LayerArgs } from "types";
+    export type ZoomOptions = {
+        lockAxis: "x" | "y" | null;
+    };
+    export class ZoomLayer extends OptionalLayer {
+        options: ZoomOptions;
+        type: LayerType;
+        zooming: boolean;
+        selectionMask: D3Selection<SVGRectElement> | null;
+        overlay: D3Selection<SVGRectElement> | null;
+        constructor(options: ZoomOptions);
+        private processSelection;
+        private handleZoom;
+        private handleBrushEnd;
+        private handleBrushMove;
+        draw: (layerArgs: LayerArgs) => void;
+    }
+}
+declare module "layers/ScatterLayer" {
+    import { LayerArgs, ScatterPoints } from "types";
+    import { LayerType, OptionalLayer } from "layers/Layer";
+    export class ScatterLayer<Metadata> extends OptionalLayer {
+        points: ScatterPoints<Metadata>;
+        type: LayerType;
+        constructor(points: ScatterPoints<Metadata>);
+        draw: (layerArgs: LayerArgs) => void;
+    }
+}
+declare module "layers/TooltipsLayer" {
+    import { LayerType, OptionalLayer } from "layers/Layer";
+    import { LayerArgs, PointWithMetadata } from "types";
+    export type TooltipHtmlCallback<Metadata> = (pointWithMetadata: PointWithMetadata<Metadata>) => string;
+    export class TooltipsLayer<Metadata> extends OptionalLayer {
+        tooltipHtmlCallback: TooltipHtmlCallback<Metadata>;
+        type: LayerType;
+        tooltipRadiusSq: number;
+        constructor(tooltipHtmlCallback: TooltipHtmlCallback<Metadata>);
+        private getDistanceSq;
+        private getDistanceSqSC;
+        private convertSCPointToCC;
+        private handleMouseMove;
+        draw: (layerArgs: LayerArgs) => void;
+    }
+}
+declare module "layers/GridLayer" {
+    import { LayerArgs } from "types";
+    import { LayerType, OptionalLayer } from "layers/Layer";
+    export class GridLayer extends OptionalLayer {
+        type: LayerType;
+        constructor();
+        draw: (layerArgs: LayerArgs) => void;
+    }
+}
+declare module "Chart" {
+    import { TracesOptions } from "layers/TracesLayer";
+    import { ZoomOptions } from "layers/ZoomLayer";
+    import { TooltipHtmlCallback } from "layers/TooltipsLayer";
+    import { AllOptionalLayers, Lines, PartialScales, Scales, ScatterPoints, XY, XYLabel } from "types";
+    import { LifecycleHooks, OptionalLayer } from "layers/Layer";
+    export type ChartOptions = {
+        logScale: XY<boolean>;
+    };
+    type PartialChartOptions = {
+        logScale?: Partial<XY<boolean>>;
+        animationDuration?: number;
+    };
+    type CategoricalScales = Partial<XY<string[]>>;
+    export class Chart<Metadata = any> {
+        id: string;
+        optionalLayers: AllOptionalLayers[];
+        isResponsive: boolean;
+        globals: {
+            animationDuration: number;
+            tickConfig: {
+                x: {
+                    count: number;
+                };
+                y: {
+                    count: number;
+                    specifier: string;
+                };
+            };
+        };
+        defaultMargin: {
+            top: number;
+            bottom: number;
+            left: number;
+            right: number;
+        };
+        exportToPng: ((name?: string) => void) | null;
+        options: ChartOptions;
+        autoscaledMaxExtents: Scales;
+        constructor(options?: PartialChartOptions);
+        addAxes: (labels?: XYLabel) => this;
+        addGridLines: () => this;
+        private filterLinesForLogAxis;
+        private filterLines;
+        addTraces: (lines: Lines<Metadata>, options?: Partial<TracesOptions>) => this;
+        addZoom: (options?: ZoomOptions) => this;
+        addTooltips: (tooltipHtmlCallback: TooltipHtmlCallback<Metadata>) => this;
+        private filterScatterPointsForLogAxis;
+        private filterScatterPoints;
+        addScatterPoints: (points: ScatterPoints<Metadata>) => this;
+        addCustomLifecycleHooks: (lifecycleHooks: Partial<LifecycleHooks>) => this;
+        addCustomLayer: (customLayer: OptionalLayer) => this;
+        makeResponsive: () => this;
+        private getXYMinMax;
+        private addLinearPadding;
+        private addLogPadding;
+        private processScales;
+        private draw;
+        appendTo: (baseElement: HTMLDivElement, maxExtents?: PartialScales, initialExtents?: PartialScales, categoricalScales?: CategoricalScales) => this;
+        private createCategoricalScale;
+    }
+}
+declare module "skadi-chart" {
+    import { Chart, ChartOptions } from "Chart";
+    import { Lines, Scales, ZoomExtents, ZoomProperties, LayerArgs, ScatterPoints, LineStyle, ScatterPointStyle, Point } from "types";
+    import { OptionalLayer, LayerType } from "layers/Layer";
+    export { Chart, OptionalLayer, LayerType };
+    export type { Lines, Scales, ZoomExtents, ZoomProperties, LayerArgs, ScatterPoints, LineStyle, ScatterPointStyle, Point, ChartOptions };
+}