@mathstack/viz 1.1.5 → 2.1.0

package/src/lib/marks/xy-marks/xy-primary-marks/xy-primary-marks.spec.ts

@@ -0,0 +1,186 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import { TestBed } from '@angular/core/testing';
+import { BehaviorSubject } from 'rxjs';
+import { Ranges } from '../../../charts';
+import { XyChartComponent } from '../../../charts/xy-chart/xy-chart.component';
+import { XyChartComponentStub } from '../../../testing/stubs/xy-chart.component.stub';
+import { XyPrimaryMarksStub } from '../../../testing/stubs/xy-data-marks.stub';
+
+describe('XyPrimaryMarks abstract class', () => {
+  let abstractClass: XyPrimaryMarksStub<any>;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        XyPrimaryMarksStub,
+        {
+          provide: XyChartComponent,
+          useValue: XyChartComponentStub,
+        },
+      ],
+    });
+    abstractClass = TestBed.inject(XyPrimaryMarksStub);
+  });
+
+  describe('ngOnInit()', () => {
+    beforeEach(() => {
+      spyOn(abstractClass, 'subscribeToRanges');
+      spyOn(abstractClass, 'subscribeToScales');
+    });
+    it('calls subscribeToRanges()', () => {
+      abstractClass.ngOnInit();
+      expect(abstractClass.subscribeToRanges).toHaveBeenCalledTimes(1);
+    });
+    it('calls subscribeToScales()', () => {
+      abstractClass.ngOnInit();
+      expect(abstractClass.subscribeToScales).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('subscribeToRanges', () => {
+    let setChartScalesFromRangesSpy: jasmine.Spy;
+    const startRanges = { x: [20, 400], y: [0, 100] } as Ranges;
+    beforeEach(() => {
+      abstractClass.chart = {
+        ranges: new BehaviorSubject<Ranges>(startRanges),
+      } as any;
+      (abstractClass.chart as any).ranges$ = (
+        abstractClass.chart as any
+      ).ranges.asObservable();
+      setChartScalesFromRangesSpy = spyOn(
+        abstractClass,
+        'setChartScalesFromRanges'
+      );
+      spyOn(abstractClass, 'initFromConfig');
+    });
+
+    it('sets ranges to the emitted value from the subscription', () => {
+      abstractClass.subscribeToRanges();
+      expect(abstractClass.ranges).toEqual(startRanges);
+    });
+
+    describe('if scales are defined and all required scales are defined', () => {
+      beforeEach(() => {
+        abstractClass.scales = {
+          x: 'test x',
+          y: 'test y',
+        } as any;
+        abstractClass.requiredScales = ['x', 'y'];
+      });
+      it('calls setPropertiesFromRanges once with the correct values', () => {
+        abstractClass.subscribeToRanges();
+        setChartScalesFromRangesSpy.calls.reset();
+        (abstractClass.chart as any).ranges.next('test range');
+        expect(abstractClass.setChartScalesFromRanges).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    describe('if scales are not defined', () => {
+      beforeEach(() => {
+        abstractClass.scales = null as any;
+        abstractClass.requiredScales = ['x', 'y'];
+      });
+      it('does not call setPropertiesFromRanges', () => {
+        abstractClass.subscribeToRanges();
+        setChartScalesFromRangesSpy.calls.reset();
+        (abstractClass.chart as any).ranges.next('test range');
+        expect(abstractClass.setChartScalesFromRanges).not.toHaveBeenCalled();
+      });
+      it('calls initFromConfig', () => {
+        abstractClass.subscribeToRanges();
+        expect(abstractClass.initFromConfig).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    describe('if not all required scales are defined', () => {
+      beforeEach(() => {
+        abstractClass.scales = {
+          x: 'test x',
+          y: null,
+        } as any;
+        abstractClass.requiredScales = ['x', 'y'];
+      });
+      it('does not call setPropertiesFromRanges', () => {
+        abstractClass.subscribeToRanges();
+        setChartScalesFromRangesSpy.calls.reset();
+        (abstractClass.chart as any).ranges.next('test range');
+        expect(abstractClass.setChartScalesFromRanges).not.toHaveBeenCalled();
+      });
+    });
+  });
+
+  describe('subscribeToScales()', () => {
+    beforeEach(() => {
+      abstractClass.chart = {
+        scales: new BehaviorSubject<any>(null),
+      } as any;
+      abstractClass.chart.scales$ = (
+        abstractClass.chart as any
+      ).scales.asObservable();
+      spyOn(abstractClass, 'drawMarks');
+    });
+
+    describe('if scales are defined', () => {
+      beforeEach(() => {
+        abstractClass.scales = {
+          x: undefined as any,
+          y: undefined as any,
+          useTransition: undefined as any,
+        };
+      });
+      it('sets scales to the emitted value from the subscription', () => {
+        abstractClass.subscribeToScales();
+        (abstractClass.chart as any).scales.next({
+          x: 'test x' as any,
+          y: 'test y' as any,
+          useTransition: true,
+        });
+        expect(abstractClass.scales).toEqual({
+          x: 'test x' as any,
+          y: 'test y' as any,
+          useTransition: true,
+        });
+      });
+      it('calls drawMarks once with the correct values', () => {
+        abstractClass.subscribeToScales();
+        (abstractClass.chart as any).scales.next({
+          x: 'test x' as any,
+          y: 'test y' as any,
+          useTransition: true,
+        });
+        expect(abstractClass.drawMarks).toHaveBeenCalledTimes(1);
+      });
+    });
+
+    describe('if scales are not defined', () => {
+      it('does not call drawMarks', () => {
+        abstractClass.subscribeToScales();
+        expect(abstractClass.drawMarks).not.toHaveBeenCalled();
+      });
+      it('does not set scales', () => {
+        abstractClass.subscribeToScales();
+        expect(abstractClass.scales).toBeUndefined();
+      });
+    });
+  });
+
+  describe('getTransitionDuration', () => {
+    beforeEach(() => {
+      abstractClass.chart.config = {
+        transitionDuration: 123,
+      } as any;
+    });
+    it('returns chart.transitionDuration if useTransition is true', () => {
+      abstractClass.scales = {
+        useTransition: true,
+      } as any;
+      expect(abstractClass.getTransitionDuration()).toEqual(123);
+    });
+    it('returns 0 if useTransition is false', () => {
+      abstractClass.scales = {
+        useTransition: false,
+      } as any;
+      expect(abstractClass.getTransitionDuration()).toEqual(0);
+    });
+  });
+});

package/src/lib/marks/xy-marks/xy-primary-marks/xy-primary-marks.ts

@@ -0,0 +1,72 @@
+import { Directive, OnInit, inject } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { filter } from 'rxjs';
+import {
+  XyChartComponent,
+  XyChartScales,
+  XyContentScale,
+} from '../../../charts/xy-chart/xy-chart.component';
+import { DataMarksOptions } from '../../config/marks-options';
+import { PrimaryMarks } from '../../primary-marks/primary-marks';
+import { XyMarks } from '../xy-marks';
+
+/**
+ * @internal
+ */
+@Directive()
+export abstract class VicXyPrimaryMarks<
+  Datum,
+  TPrimaryMarksConfig extends DataMarksOptions<Datum>,
+>
+  extends PrimaryMarks<Datum, TPrimaryMarksConfig>
+  implements OnInit, XyMarks
+{
+  scales: XyChartScales;
+  requiredScales: (keyof typeof XyContentScale)[] = [
+    XyContentScale.x,
+    XyContentScale.y,
+  ];
+  public override chart = inject(XyChartComponent);
+
+  ngOnInit(): void {
+    this.subscribeToRanges();
+    this.subscribeToScales();
+  }
+
+  subscribeToRanges(): void {
+    this.chart.ranges$
+      .pipe(
+        takeUntilDestroyed(this.destroyRef),
+        filter((ranges) => !!ranges)
+      )
+      .subscribe((ranges) => {
+        this.ranges = ranges;
+        if (
+          this.scales &&
+          this.requiredScales.every((scale) => this.scales[scale])
+        ) {
+          this.setChartScalesFromRanges(false);
+        } else {
+          this.initFromConfig();
+        }
+      });
+  }
+
+  subscribeToScales(): void {
+    this.chart.scales$
+      .pipe(
+        takeUntilDestroyed(this.destroyRef),
+        filter((scales) => !!scales)
+      )
+      .subscribe((scales): void => {
+        this.scales.x = scales.x;
+        this.scales.y = scales.y;
+        this.scales.useTransition = scales.useTransition;
+        this.drawMarks();
+      });
+  }
+
+  getTransitionDuration(): number {
+    return this.scales.useTransition ? this.chart.config.transitionDuration : 0;
+  }
+}

package/{lib/point-markers/index.d.ts → src/lib/point-markers/index.ts}

@@ -1,2 +1,3 @@
-export * from './point-markers';
-export * from './point-markers-options';
+export * from './point-markers';
+export * from './point-markers-builder';
+export * from './point-markers-options';

package/src/lib/point-markers/point-markers-builder.ts

@@ -0,0 +1,93 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { PointMarkers } from './point-markers';
+
+const DEFAULT = {
+  _class: () => '',
+  _display: () => true,
+  _radius: 3,
+  _growByOnHover: 2,
+};
+
+export class PointMarkersBuilder<Datum> {
+  private _display: (d: Datum) => boolean;
+  private _class: (d: Datum) => string;
+  private _growByOnHover: number;
+  private _radius: number;
+
+  constructor() {
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. Provides a class on the SVG element that correspends to a single datum. If a datum creates multiple SVG elements -- for example, a rect and a label, the class will be applied on the parent SVGGElement.
+   *
+   * IF the chart does not have SVG elements that correspond to a single datum, this class will be placed on the SVG element that represents a collection of data, for example, a area in a stacked area chart, or a line in a line chart. In this case the datum passed to the callback function will be the first datum in the collection.
+   *
+   * Note that if the resultant string has spaces in the name, multiple classes will be applied. For example, if the class is 'North Carolina', the element will have the classes 'North' and 'Carolina'.
+   */
+  class(value: null): this;
+  class(value: string): this;
+  class(value: (d: Datum) => string): this;
+  class(value: ((d: Datum) => string) | string | null): this {
+    if (value === null) {
+      this._class = DEFAULT._class;
+      return this;
+    }
+    if (typeof value === 'string') {
+      this._class = () => value;
+      return this;
+    }
+    this._class = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A boolean to determine if point markers will be _displayed_.
+   *
+   * This is used to configure the visibilty of markers -- a `true` value will set the `display` of markers to `block`, while a `false` value will set the display of the markers to `none`.
+   *
+   * One use case is to have markers hidden until a user interaction, such as hover.
+   *
+   * If a function is provided, markers whose filtering predicate returns `true` will have `display: block` while those whose predicate returns `false` will have `display: none` when the markers are drawn.
+   *
+   * @default () => true
+   */
+  display(display: boolean): this;
+  display(display: (d: Datum) => boolean): this;
+  display(display: boolean | ((d: Datum) => boolean)): this {
+    this._display = typeof display === 'boolean' ? () => display : display;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A value by which the point marker will expand on hover, in px.
+   *
+   * @default 2
+   */
+  growByOnHover(growByOnHover: number): this {
+    this._growByOnHover = growByOnHover;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A value for the radius of the point marker, in px.
+   *
+   * @default 3
+   */
+  radius(radius: number): this {
+    this._radius = radius;
+    return this;
+  }
+
+  /**
+   * @internal This function is for internal use only and should never be called by the user.
+   */
+  _build(): PointMarkers<Datum> {
+    return new PointMarkers({
+      datumClass: this._class,
+      display: this._display,
+      growByOnHover: this._growByOnHover,
+      radius: this._radius,
+    });
+  }
+}

package/src/lib/point-markers/point-markers-options.ts

@@ -0,0 +1,6 @@
+export interface PointMarkersOptions<Datum> {
+  datumClass: (d: Datum, i: number) => string;
+  display: (d: Datum) => boolean;
+  growByOnHover: number;
+  radius: number;
+}

package/src/lib/point-markers/point-markers.ts

@@ -0,0 +1,13 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { PointMarkersOptions } from './point-markers-options';
+
+export class PointMarkers<Datum> implements PointMarkersOptions<Datum> {
+  readonly datumClass: (d: Datum, i: number) => string;
+  readonly display: (d: Datum) => boolean;
+  readonly growByOnHover: number;
+  readonly radius: number;
+
+  constructor(options: PointMarkersOptions<Datum>) {
+    safeAssign(this, options);
+  }
+}

package/src/lib/quantitative-rules/config/labels/quantitative-rules-labels-builder.ts

@@ -0,0 +1,162 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { QuantitativeRulesLabels } from './quantitative-rules-labels';
+
+const DEFAULT = {
+  _display: () => true,
+  _dominantBaseline: 'middle',
+};
+
+export class RulesLabelsBuilder<Datum> {
+  private _color: (d: Datum) => string;
+  private _display: (d: Datum) => boolean;
+  private _dominantBaseline:
+    | 'middle'
+    | 'text-after-edge'
+    | 'text-before-edge'
+    | 'central'
+    | 'auto'
+    | 'hanging'
+    | 'ideographic'
+    | 'alphabetic';
+  private _value: (d: Datum) => string;
+  private _offset: number;
+  private _position: (start: number, end: number, d: Datum) => number;
+  private _textAnchor: 'start' | 'middle' | 'end';
+
+  constructor() {
+    safeAssign(this, DEFAULT);
+    this._value = (d: Datum) => `${d}`;
+  }
+
+  /**
+   * OPTIONAL. Set the color of the labels.
+   *
+   * If not provided, the color of the line will be used.
+   *
+   * To unset the color, pass `null`.
+   */
+  color(color: null): this;
+  color(color: string): this;
+  color(color: (d: Datum) => string): this;
+  color(color: string | ((d: Datum) => string) | null) {
+    if (color === null) {
+      this._color = null;
+      return this;
+    }
+    this._color = typeof color === 'string' ? () => color : color;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Set the display of the labels.
+   *
+   * If not provided, the labels will be displayed.
+   *
+   * @default true
+   */
+  display(display: boolean): this;
+  display(display: (d: Datum) => boolean): this;
+  display(display: boolean | ((d: Datum) => boolean)) {
+    this._display = typeof display === 'boolean' ? () => display : display;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Set the dominant baseline of the labels.
+   *
+   * @default 'middle'
+   */
+  dominantBaseline(
+    dominantBaseline:
+      | 'middle'
+      | 'text-after-edge'
+      | 'text-before-edge'
+      | 'central'
+      | 'auto'
+      | 'hanging'
+      | 'ideographic'
+      | 'alphabetic'
+  ) {
+    this._dominantBaseline = dominantBaseline;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Set the offset of the labels.
+   *
+   * @default -12 for horizontal orientation, 0 for vertical orientation
+   */
+  offset(offset: number) {
+    this._offset = offset;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Set the position of the labels.
+   *
+   * @default end for horizontal orientation, end for vertical orientation
+   */
+  position(position: (start: number, end: number, d: Datum) => number) {
+    this._position = position;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Set the text anchor of the labels.
+   *
+   * @default 'end' for horizontal orientation, 'middle' for vertical orientation
+   */
+  textAnchor(textAnchor: 'start' | 'middle' | 'end') {
+    this._textAnchor = textAnchor;
+    return this;
+  }
+
+  /**
+   * REQUIRED. Set the value of the labels.
+   */
+  value(value: (d: Datum) => string) {
+    this._value = value;
+    return this;
+  }
+
+  _build(): QuantitativeRulesLabels<Datum> {
+    return new QuantitativeRulesLabels<Datum>({
+      color: this._color,
+      display: this._display,
+      dominantBaseline: this._dominantBaseline,
+      value: this._value,
+      offset: this._offset,
+      position: this._position,
+      textAnchor: this._textAnchor,
+    });
+  }
+
+  validateBuilder(
+    orientation: 'horizontal' | 'vertical',
+    lineColor: (d: Datum) => string
+  ): void {
+    if (!this._color) {
+      this._color = lineColor;
+    }
+    if (!this._offset) {
+      if (orientation === 'horizontal') {
+        this._offset = -12;
+      } else {
+        this._offset = 0;
+      }
+    }
+    if (!this._position) {
+      if (orientation === 'horizontal') {
+        this._position = (start: number, end: number) => end - 4;
+      } else {
+        this._position = (start: number, end: number) => end - 12;
+      }
+    }
+    if (!this._textAnchor) {
+      this._textAnchor = orientation === 'horizontal' ? 'end' : 'middle';
+    }
+    if (!this.value) {
+      throw new Error('QuantitativeRulesLabels: value is required');
+    }
+  }
+}

package/src/lib/quantitative-rules/config/labels/quantitative-rules-labels-options.ts

@@ -0,0 +1,17 @@
+export interface QuantitativeRulesLabelsOptions<Datum> {
+  color: (d: Datum) => string;
+  display: (d: Datum) => boolean;
+  dominantBaseline:
+    | 'auto'
+    | 'middle'
+    | 'central'
+    | 'text-before-edge'
+    | 'text-after-edge'
+    | 'hanging'
+    | 'ideographic'
+    | 'alphabetic';
+  value: (d: Datum) => string;
+  offset: number;
+  position: (start: number, end: number, d: Datum) => number;
+  textAnchor: 'start' | 'middle' | 'end';
+}

package/src/lib/quantitative-rules/config/labels/quantitative-rules-labels.ts

@@ -0,0 +1,26 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { QuantitativeRulesLabelsOptions } from './quantitative-rules-labels-options';
+
+export class QuantitativeRulesLabels<
+  Datum,
+> implements QuantitativeRulesLabelsOptions<Datum> {
+  color: (d: Datum) => string;
+  display: (d: Datum) => boolean;
+  dominantBaseline:
+    | 'middle'
+    | 'text-after-edge'
+    | 'text-before-edge'
+    | 'central'
+    | 'auto'
+    | 'hanging'
+    | 'ideographic'
+    | 'alphabetic';
+  value: (d: Datum) => string;
+  offset: number;
+  position: (start: number, end: number, d: Datum) => number;
+  textAnchor: 'start' | 'middle' | 'end';
+
+  constructor(options: QuantitativeRulesLabelsOptions<Datum>) {
+    safeAssign(this, options);
+  }
+}