@mathstack/viz 1.1.5 → 2.0.3

package/src/lib/image-download/image-download.service.ts

@@ -0,0 +1,70 @@
+import { Injectable } from '@angular/core';
+import * as domToImage from 'html-to-image';
+import {
+  VicJpegImageConfig,
+  VicPngImageConfig,
+  VicSvgImageConfig,
+} from './image-download-config';
+import { VicImage } from './image-download-enums';
+
+@Injectable({ providedIn: 'root' })
+export class VicImageDownloadService {
+  domToImage = domToImage;
+
+  /**
+   * @param imageConfig
+   * @returns fontEmbedCSS -- scans stylesheets for font files and base64 encodes them,
+   * reuse this value in imageConfig for subsequent downloads to avoid
+   * re-encoding fonts (slight performance boost)
+   */
+  async downloadImage(
+    imageConfig: VicJpegImageConfig | VicPngImageConfig | VicSvgImageConfig
+  ): Promise<string | void> {
+    let dataUrl;
+    if (imageConfig.fontEmbedCSS === undefined) {
+      imageConfig.fontEmbedCSS = await domToImage.getFontEmbedCSS(
+        imageConfig.containerNode
+      );
+    }
+    const sizedImageConfig = {
+      ...imageConfig,
+      width: imageConfig.containerNode.scrollWidth,
+      height: imageConfig.containerNode.scrollHeight,
+    };
+    switch (imageConfig.imageType) {
+      case VicImage.jpeg:
+        dataUrl = await this.domToImage.toJpeg(
+          imageConfig.containerNode,
+          sizedImageConfig
+        );
+        break;
+      case VicImage.png:
+        dataUrl = await this.domToImage.toPng(
+          imageConfig.containerNode,
+          sizedImageConfig
+        );
+        break;
+      case VicImage.svg:
+        dataUrl = await this.domToImage.toSvg(
+          imageConfig.containerNode,
+          sizedImageConfig
+        );
+        break;
+      default:
+        break;
+    }
+
+    this.createLinkAndClick(
+      dataUrl,
+      `${imageConfig.fileName}.${imageConfig.imageType}`
+    );
+    return imageConfig.fontEmbedCSS;
+  }
+
+  createLinkAndClick(dataUrl: string, fileName: string) {
+    const link = document.createElement('a');
+    link.download = fileName;
+    link.href = dataUrl;
+    link.click();
+  }
+}

package/{lib/image-download/index.d.ts → src/lib/image-download/index.ts}

@@ -1,4 +1,4 @@
-export * from './image-download-config';
-export * from './image-download-enums';
-export * from './image-download-options';
-export * from './image-download.service';
+export * from './image-download-config';
+export * from './image-download-enums';
+export * from './image-download-options';
+export * from './image-download.service';

package/src/lib/lines/config/area-fills/area-fills-builder.ts

@@ -0,0 +1,87 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { FillDefinition } from '../../../data-dimensions';
+import { AreaFills } from './area-fills';
+
+const DEFAULT = {
+  _display: () => true,
+  _opacity: 0.2,
+  _gradient: undefined,
+  _color: undefined,
+};
+
+export class AreaFillsBuilder<Datum> {
+  private _display: (category: string) => boolean;
+  private _opacity: number;
+  private _customFills: FillDefinition<Datum>[];
+  private _color: (d: Datum) => string;
+
+  constructor() {
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. A string which determines color of the fill under line,
+   * or a function whose input is the first point in the line and which returns
+   * a color string.
+   * This string is directly passed to `fill` under the hood.
+   *
+   * If not set, the color of the line will be used.
+   *
+   * To unset the color, call with `null`.
+   */
+  color(color: null): this;
+  color(color: string): this;
+  color(color: (d: Datum) => string): this;
+  color(color: string | ((d: Datum) => string) | null): this {
+    if (color === null) {
+      this._color = undefined;
+      return this;
+    }
+    this._color = typeof color === 'string' ? () => color : color;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A boolean to determine if fill under line should be displayed.
+   *
+   * @default true
+   */
+  display(display: boolean): this;
+  display(display: (category: string) => boolean): this;
+  display(display: boolean | ((category: string) => boolean)): this {
+    this._display = typeof display === 'boolean' ? () => display : display;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A number to determine the opacity of the fill under line.
+   *
+   * @default 0.2
+   */
+  opacity(opacity: number): this {
+    this._opacity = opacity;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A string to determine the gradient of the fill under line.
+   *
+   * @default undefined
+   */
+  customFills(customFills: FillDefinition<Datum>[]): this {
+    this._customFills = customFills;
+    return this;
+  }
+
+  /**
+   * @internal This function is for internal use only and should never be called by the user.
+   */
+  _build(): AreaFills<Datum> {
+    return {
+      display: this._display,
+      opacity: this._opacity,
+      customFills: this._customFills,
+      color: this._color,
+    };
+  }
+}

package/src/lib/lines/config/area-fills/area-fills-options.ts

@@ -0,0 +1,8 @@
+import { FillDefinition } from '../../../data-dimensions';
+
+export interface AreaFillsOptions<Datum> {
+  display: (category: string) => boolean;
+  opacity: number;
+  customFills: FillDefinition<Datum>[];
+  color: (d: Datum) => string;
+}

package/src/lib/lines/config/area-fills/area-fills.ts

@@ -0,0 +1,14 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { FillDefinition } from '../../../data-dimensions';
+import { AreaFillsOptions } from './area-fills-options';
+
+export class AreaFills<Datum> implements AreaFillsOptions<Datum> {
+  readonly display: (category: string) => boolean;
+  readonly opacity: number;
+  readonly customFills: FillDefinition<Datum>[];
+  readonly color: (d: Datum) => string;
+
+  constructor(options: AreaFillsOptions<Datum>) {
+    safeAssign(this, options);
+  }
+}

package/src/lib/lines/config/lines-builder.ts

@@ -0,0 +1,242 @@
+import { Injectable } from '@angular/core';
+import { safeAssign } from '@mathstack/app-kit';
+import { CurveFactory, curveLinear } from 'd3';
+import { DateChartPositionDimensionBuilder } from '../../data-dimensions/continuous-quantitative/date-chart-position/date-chart-position-builder';
+import { NumberChartPositionDimensionBuilder } from '../../data-dimensions/continuous-quantitative/number-chart-position/number-chart-position-builder';
+import { PrimaryMarksBuilder } from '../../marks/primary-marks/config/primary-marks-builder';
+import { PointMarkersBuilder } from '../../point-markers/point-markers-builder';
+import { LinesStrokeBuilder } from '../config/stroke/lines-stroke-builder';
+import { AreaFillsBuilder } from './area-fills/area-fills-builder';
+import { LinesConfig } from './lines-config';
+
+const DEFAULT = {
+  _curve: curveLinear,
+  _pointerDetectionRadius: 80,
+  _lineLabelsFormat: (d: string) => d,
+};
+
+/**
+ * Builds a configuration object for a LinesComponent.
+ *
+ * Must be added to a providers array in or above the component that consumes it if it is injected via the constructor. (e.g. `providers: [VicLinesBuilder]` in the component decorator)
+ *
+ * The generic parameter, Datum, is the type of the data that will be used to create the lines.
+ */
+@Injectable()
+export class VicLinesConfigBuilder<Datum> extends PrimaryMarksBuilder<Datum> {
+  private _curve: CurveFactory;
+  private _labelLines: boolean;
+  private _lineLabelsFormat: (d: string) => string;
+  private _pointerDetectionRadius: number;
+  private pointMarkersBuilder: PointMarkersBuilder<Datum>;
+  private strokeBuilder: LinesStrokeBuilder<Datum>;
+  private xDimensionBuilder:
+    | NumberChartPositionDimensionBuilder<Datum>
+    | DateChartPositionDimensionBuilder<Datum>;
+  private yDimensionBuilder: NumberChartPositionDimensionBuilder<Datum>;
+  private areaFillsBuilder: AreaFillsBuilder<Datum>;
+
+  constructor() {
+    super();
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. A config to set fill underneath lines.
+   *
+   * If no argument is provided, the default area fills will be created.
+   *
+   * To unset the area fills, call with `null`.
+   */
+  areaFills(): this;
+  areaFills(areaFills: null): this;
+  areaFills(areaFills: (areaFills: AreaFillsBuilder<Datum>) => void): this;
+  areaFills(
+    areaFills?: ((areaFills: AreaFillsBuilder<Datum>) => void) | null
+  ): this {
+    if (areaFills === null) {
+      this.areaFillsBuilder = undefined;
+      return this;
+    }
+    this.initBelowLinesAreaFillBuilder();
+    areaFills?.(this.areaFillsBuilder);
+    return this;
+  }
+
+  private initBelowLinesAreaFillBuilder(): void {
+    this.areaFillsBuilder = new AreaFillsBuilder();
+  }
+
+  /**
+   * OPTIONAL. A function passed to D3's [line.curve()]{@link https://github.com/d3/d3-shape#line_curve}
+   *  method.
+   *
+   * @default [curveLinear]{@link https://github.com/d3/d3-shape#curveLinear}.
+   */
+  curve(curve: CurveFactory): this {
+    this._curve = curve;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A boolean to determine if the line will be labeled.
+   */
+  labelLines(labelLines: boolean): this {
+    this._labelLines = labelLines;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A function that returns a string to be used as the label for a line. Can be used to modify the
+   * line label string as needed.
+   *
+   * @default identity function.
+   */
+  lineLabelsFormat(lineLabelsFormat: (d: string) => string): this {
+    this._lineLabelsFormat = lineLabelsFormat;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. The distance from a line in which a hover event will trigger a tooltip, in px.
+   *
+   * This is used to ensure that a tooltip is triggered only when a user's pointer is close to lines.
+   *
+   * @default 80
+   */
+  pointerDetectionRadius(pointerDetectionRadius: number): this {
+    this._pointerDetectionRadius = pointerDetectionRadius;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A config for the behavior of markers for each datum on the line.
+   *
+   * Creating this config will create markers on lines. If no argument is provided, the default markers will be created.
+   */
+  pointMarkers(): this;
+  pointMarkers(pointMarkers: null): this;
+  pointMarkers(
+    pointMarkers: ((pointMarkers: PointMarkersBuilder<Datum>) => void) | null
+  ): this;
+  pointMarkers(
+    pointMarkers?: ((pointMarkers: PointMarkersBuilder<Datum>) => void) | null
+  ): this {
+    if (pointMarkers === null) {
+      this.pointMarkersBuilder = undefined;
+      return this;
+    }
+    this.pointMarkersBuilder = new PointMarkersBuilder();
+    pointMarkers?.(this.pointMarkersBuilder);
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A config for the behavior of the line stroke.
+   */
+  stroke(stroke: null): this;
+  stroke(stroke: (stroke: LinesStrokeBuilder<Datum>) => void): this;
+  stroke(stroke: ((stroke: LinesStrokeBuilder<Datum>) => void) | null): this {
+    if (stroke === null) {
+      this.strokeBuilder = undefined;
+      return this;
+    }
+    this.initStrokeBuilder();
+    stroke(this.strokeBuilder);
+    return this;
+  }
+
+  private initStrokeBuilder(): void {
+    this.strokeBuilder = new LinesStrokeBuilder();
+  }
+
+  /**
+   * REQUIRED. A config for the behavior of the chart's x dimension when using numeric data.
+   */
+  xNumeric(xNumeric: null): this;
+  xNumeric(
+    xNumeric: (x: NumberChartPositionDimensionBuilder<Datum>) => void
+  ): this;
+  xNumeric(
+    x: ((x: NumberChartPositionDimensionBuilder<Datum>) => void) | null
+  ): this {
+    if (x === null) {
+      this.xDimensionBuilder = undefined;
+      return this;
+    }
+    this.xDimensionBuilder = new NumberChartPositionDimensionBuilder<Datum>();
+    x(this.xDimensionBuilder);
+    return this;
+  }
+
+  /**
+   * REQUIRED. A config for the behavior of the chart's x dimension when using Date date.
+   */
+  xDate(xDate: null): this;
+  xDate(xDate: (x: DateChartPositionDimensionBuilder<Datum>) => void): this;
+  xDate(
+    x: ((x: DateChartPositionDimensionBuilder<Datum>) => void) | null
+  ): this {
+    if (x === null) {
+      this.xDimensionBuilder = undefined;
+      return this;
+    }
+    this.xDimensionBuilder = new DateChartPositionDimensionBuilder<Datum>();
+    x(this.xDimensionBuilder);
+    return this;
+  }
+
+  /**
+   * REQUIRED. A config for the behavior of the chart's y dimension.
+   */
+  y(y: null): this;
+  y(y: (y: NumberChartPositionDimensionBuilder<Datum>) => void): this;
+  y(y: ((y: NumberChartPositionDimensionBuilder<Datum>) => void) | null): this {
+    if (y === null) {
+      this.yDimensionBuilder = undefined;
+      return this;
+    }
+    this.yDimensionBuilder = new NumberChartPositionDimensionBuilder<Datum>();
+    y(this.yDimensionBuilder);
+    return this;
+  }
+
+  /**
+   * REQUIRED. Builds the configuration object for the LinesComponent.
+   */
+  getConfig(): LinesConfig<Datum> {
+    this.validateBuilder();
+    return new LinesConfig({
+      marksClass: 'vic-lines',
+      curve: this._curve,
+      data: this._data,
+      datumClass: this._datumClass,
+      labelLines: this._labelLines,
+      lineLabelsFormat: this._lineLabelsFormat,
+      mixBlendMode: this._mixBlendMode,
+      pointerDetectionRadius: this._pointerDetectionRadius,
+      pointMarkers: this.pointMarkersBuilder?._build(),
+      stroke: this.strokeBuilder._build(),
+      x: this.xDimensionBuilder._build('X'),
+      y: this.yDimensionBuilder._build('Y'),
+      areaFills: this.areaFillsBuilder?._build(),
+    });
+  }
+
+  protected override validateBuilder(): void {
+    super.validateBuilder('Lines');
+    if (this.strokeBuilder === undefined) {
+      this.initStrokeBuilder();
+    }
+    if (!this.xDimensionBuilder) {
+      throw new Error(
+        'Lines Builder: X dimension is required. Please use method `createXNumericDimension` or `createXDateDimension` to set it.'
+      );
+    }
+    if (!this.yDimensionBuilder) {
+      throw new Error(
+        'Lines Builder: Y dimension is required. Please use method `createYDimension` to set it.'
+      );
+    }
+  }
+}

package/src/lib/lines/config/lines-config.spec.ts

@@ -0,0 +1,52 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { VicLinesConfigBuilder } from './lines-builder';
+import { LinesConfig } from './lines-config';
+
+type Datum = { date: Date; value: number; category: string };
+const data = [
+  { date: new Date('2020-01-01'), value: 1, category: 'a' },
+  { date: new Date('2020-01-02'), value: 2, category: 'a' },
+  { date: new Date('2020-01-03'), value: 3, category: 'a' },
+  { date: new Date('2020-01-01'), value: 4, category: 'b' },
+  { date: new Date('2020-01-02'), value: 5, category: 'b' },
+  { date: new Date('2020-01-03'), value: 6, category: 'b' },
+];
+
+function createConfig(): LinesConfig<Datum> {
+  return new VicLinesConfigBuilder<Datum>()
+    .data(data)
+    .xDate((dimension) => dimension.valueAccessor((d) => d.date))
+    .y((dimension) => dimension.valueAccessor((d) => d.value))
+    .stroke((stroke) =>
+      stroke.color((dimension) => dimension.valueAccessor((d) => d.category))
+    )
+    .getConfig();
+}
+
+describe('LinesConfig', () => {
+  let config: LinesConfig<Datum>;
+
+  describe('initPropertiesFromData()', () => {
+    beforeEach(() => {
+      spyOn(LinesConfig.prototype as any, 'setDimensionPropertiesFromData');
+      spyOn(LinesConfig.prototype as any, 'setValueIndices');
+      spyOn(LinesConfig.prototype as any, 'setLinesD3Data');
+      spyOn(LinesConfig.prototype as any, 'setLinesKeyFunction');
+      config = createConfig();
+    });
+    it('calls setDimensionPropertiesFromData once', () => {
+      expect(
+        (config as any).setDimensionPropertiesFromData
+      ).toHaveBeenCalledTimes(1);
+    });
+    it('calls setValueIndices once', () => {
+      expect((config as any).setValueIndices).toHaveBeenCalledTimes(1);
+    });
+    it('calls setLinesD3Data once', () => {
+      expect((config as any).setLinesD3Data).toHaveBeenCalledTimes(1);
+    });
+    it('calls setLinesKeyFunction once', () => {
+      expect((config as any).setLinesKeyFunction).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/lib/lines/config/lines-config.ts

@@ -0,0 +1,96 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { CurveFactory, group, range } from 'd3';
+import { DateChartPositionDimension } from '../../data-dimensions/continuous-quantitative/date-chart-position/date-chart-position';
+import { NumberChartPositionDimension } from '../../data-dimensions/continuous-quantitative/number-chart-position/number-chart-position';
+import { XyPrimaryMarksConfig } from '../../marks/xy-marks/xy-primary-marks/xy-primary-marks-config';
+import { PointMarkers } from '../../point-markers/point-markers';
+import { LinesGroupSelectionDatum } from '../lines.component';
+import { AreaFills } from './area-fills/area-fills';
+import { LinesOptions } from './lines-options';
+import { LinesStroke } from './stroke/lines-stroke';
+
+export interface LinesMarkerDatum {
+  key: string;
+  index: number;
+  category: string;
+  display: string;
+}
+
+export class LinesConfig<Datum>
+  extends XyPrimaryMarksConfig<Datum>
+  implements LinesOptions<Datum>
+{
+  readonly curve: CurveFactory;
+  readonly labelLines: boolean;
+  readonly lineLabelsFormat: (d: string) => string;
+  linesD3Data;
+  linesKeyFunction: (d: LinesGroupSelectionDatum) => string;
+  readonly areaFills: AreaFills<Datum>;
+  readonly pointerDetectionRadius: number;
+  readonly pointMarkers: PointMarkers<Datum>;
+  readonly stroke: LinesStroke<Datum>;
+  readonly x:
+    | DateChartPositionDimension<Datum>
+    | NumberChartPositionDimension<Datum>;
+  readonly y: NumberChartPositionDimension<Datum>;
+
+  constructor(options: LinesOptions<Datum>) {
+    super();
+    safeAssign(this, options);
+    this.initPropertiesFromData();
+  }
+
+  protected initPropertiesFromData(): void {
+    this.setDimensionPropertiesFromData();
+    this.setValueIndices();
+    this.setLinesD3Data();
+    this.setLinesKeyFunction();
+  }
+
+  private setDimensionPropertiesFromData(): void {
+    this.x.setPropertiesFromData(this.data);
+    this.y.setPropertiesFromData(this.data);
+    this.stroke.color.setPropertiesFromData(this.data);
+  }
+
+  private setValueIndices(): void {
+    this.valueIndices = range(this.x.values.length).filter((i) =>
+      this.stroke.color.domainIncludes(this.stroke.color.values[i])
+    );
+  }
+
+  private setLinesD3Data(): void {
+    const definedIndices = this.valueIndices.filter(
+      (i) =>
+        this.x.isValidValue(this.x.values[i]) &&
+        this.y.isValidValue(this.y.values[i])
+    );
+    this.linesD3Data = group(
+      definedIndices,
+      (i) => this.stroke.color.values[i]
+    );
+  }
+
+  getDataFromCategory(category: string): Datum[] {
+    return this.linesD3Data.get(category).map((i) => this.data[i]);
+  }
+
+  private setLinesKeyFunction(): void {
+    this.linesKeyFunction = (d): string => d[0];
+  }
+
+  getPointMarkersData(indices: number[]): LinesMarkerDatum[] {
+    return indices.map((i) => {
+      return {
+        key: this.getMarkerKey(i),
+        index: i,
+        category: this.stroke.color.values[i],
+        display: this.pointMarkers.display(this.data[i]) ? 'block' : 'none',
+      };
+    });
+  }
+
+  private getMarkerKey(i: number): string {
+    return `${this.stroke.color.values[i]}-${this.x.values[i]}`;
+  }
+}

package/{lib/lines/config/lines-options.d.ts → src/lib/lines/config/lines-options.ts}

@@ -1,18 +1,19 @@
-import { CurveFactory } from 'd3';
-import { DateChartPositionDimension } from '../../data-dimensions/continuous-quantitative/date-chart-position/date-chart-position';
-import { NumberChartPositionDimension } from '../../data-dimensions/continuous-quantitative/number-chart-position/number-chart-position';
-import { DataMarksOptions } from '../../marks/config/marks-options';
-import { PointMarkers } from '../../point-markers/point-markers';
-import { AreaFills } from './area-fills/area-fills';
-import { LinesStrokeOptions } from './stroke/lines-stroke-options';
-export interface LinesOptions<Datum> extends DataMarksOptions<Datum> {
-    areaFills: AreaFills<Datum>;
-    curve: CurveFactory;
-    labelLines: boolean;
-    lineLabelsFormat: (d: string) => string;
-    pointerDetectionRadius: number;
-    pointMarkers: PointMarkers<Datum>;
-    stroke: LinesStrokeOptions<Datum>;
-    x: DateChartPositionDimension<Datum> | NumberChartPositionDimension<Datum>;
-    y: NumberChartPositionDimension<Datum>;
-}
+import { CurveFactory } from 'd3';
+import { DateChartPositionDimension } from '../../data-dimensions/continuous-quantitative/date-chart-position/date-chart-position';
+import { NumberChartPositionDimension } from '../../data-dimensions/continuous-quantitative/number-chart-position/number-chart-position';
+import { DataMarksOptions } from '../../marks/config/marks-options';
+import { PointMarkers } from '../../point-markers/point-markers';
+import { AreaFills } from './area-fills/area-fills';
+import { LinesStrokeOptions } from './stroke/lines-stroke-options';
+
+export interface LinesOptions<Datum> extends DataMarksOptions<Datum> {
+  areaFills: AreaFills<Datum>;
+  curve: CurveFactory;
+  labelLines: boolean;
+  lineLabelsFormat: (d: string) => string;
+  pointerDetectionRadius: number;
+  pointMarkers: PointMarkers<Datum>;
+  stroke: LinesStrokeOptions<Datum>;
+  x: DateChartPositionDimension<Datum> | NumberChartPositionDimension<Datum>;
+  y: NumberChartPositionDimension<Datum>;
+}