@mathstack/viz 1.1.5 → 2.1.0

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

@@ -0,0 +1,134 @@
+import { Injectable } from '@angular/core';
+import { safeAssign } from '@mathstack/app-kit';
+import { VicAuxMarksBuilder } from '../../marks/aux-marks/config/aux-marks-builder';
+import { StrokeBuilder } from '../../stroke/stroke-builder';
+import { RulesLabelsBuilder } from './labels/quantitative-rules-labels-builder';
+import { QuantitativeRulesConfig } from './quantitative-rules-config';
+import {
+  HORIZONTAL_RULE_DIMENSIONS,
+  QuantitativeRulesDimensions,
+  VERTICAL_RULE_DIMENSIONS,
+} from './quantitative-rules-dimensions';
+
+const DEFAULT = {
+  _color: () => '#cccccc',
+};
+
+@Injectable()
+export class VicQuantitativeRulesConfigBuilder<
+  Datum extends number | Date,
+> extends VicAuxMarksBuilder<Datum> {
+  protected _color: (d: Datum) => string;
+  protected _data: Datum[];
+  protected dimensions: QuantitativeRulesDimensions;
+  protected _orientation: 'horizontal' | 'vertical';
+  private labelsBuilder: RulesLabelsBuilder<Datum>;
+  private strokeBuilder: StrokeBuilder;
+
+  constructor() {
+    super();
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. Sets the color of the rule.
+   *
+   * @default #cccccc.
+   */
+  color(color: string | ((d: Datum) => string)): this {
+    if (typeof color === 'string') {
+      this._color = () => color;
+    } else {
+      this._color = color;
+    }
+    return this;
+  }
+
+  /**
+   * REQUIRED. Sets the data that will be used to render the quantitative rules.
+   *
+   * This component is not a Primary Marks component, so this data will not affect chart-level scales.
+   *
+   * @param data The data to be used to render the quantitative rules. Should be an array of numbers or dates.
+   */
+  data(data: Datum[]): this {
+    this._data = data;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A config for the behavior of the rule labels.
+   */
+  labels(): this;
+  labels(labels: null): this;
+  labels(labels: (labels: RulesLabelsBuilder<Datum>) => void): this;
+  labels(labels?: ((labels: RulesLabelsBuilder<Datum>) => void) | null): this {
+    if (labels === null) {
+      this.labelsBuilder = undefined;
+      return this;
+    }
+    this.labelsBuilder = new RulesLabelsBuilder();
+    labels?.(this.labelsBuilder);
+    return this;
+  }
+
+  /**
+   * REQUIRED. Sets the orientation of the rule.
+   */
+  orientation(orientation: 'horizontal' | 'vertical'): this {
+    this._orientation = orientation;
+    this.dimensions =
+      orientation === 'horizontal'
+        ? HORIZONTAL_RULE_DIMENSIONS
+        : VERTICAL_RULE_DIMENSIONS;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A config for the behavior of the rule stroke.
+   */
+  stroke(stroke: null): this;
+  stroke(stroke: (stroke: StrokeBuilder) => void): this;
+  stroke(stroke: ((stroke: StrokeBuilder) => void) | null): this {
+    if (stroke === null) {
+      this.strokeBuilder = undefined;
+      return this;
+    }
+    this.initStrokeBuilder();
+    stroke(this.strokeBuilder);
+    return this;
+  }
+
+  private initStrokeBuilder(): void {
+    this.strokeBuilder = new StrokeBuilder();
+  }
+
+  /**
+   * REQUIRED. Builds the configuration object for the RuleComponent.
+   */
+  getConfig(): QuantitativeRulesConfig<Datum> {
+    this.validateBuilder();
+    return new QuantitativeRulesConfig({
+      marksClass: 'vic-quantitative-rules',
+      color: this._color,
+      data: this._data,
+      datumClass: this._class,
+      dimensions: this.dimensions,
+      labels: this.labelsBuilder?._build(),
+      mixBlendMode: this._mixBlendMode,
+      stroke: this.strokeBuilder._build(),
+    });
+  }
+
+  protected validateBuilder(): void {
+    if (this.data === undefined) {
+      throw new Error('Data is required for the Quantitative Rules component.');
+    }
+    if (this.strokeBuilder === undefined) {
+      this.initStrokeBuilder();
+    }
+    if (this.labelsBuilder) {
+      this.labelsBuilder.validateBuilder(this._orientation, this._color);
+    }
+  }
+}

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

@@ -0,0 +1,21 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { XyMarksConfig } from '../../marks/xy-marks/xy-marks-config';
+import { Stroke } from '../../stroke/stroke';
+import { QuantitativeRulesLabels } from './labels/quantitative-rules-labels';
+import { QuantitativeRulesDimensions } from './quantitative-rules-dimensions';
+import { QuantitativeRulesOptions } from './quantitative-rules-options';
+
+export class QuantitativeRulesConfig<Datum extends number | Date>
+  extends XyMarksConfig<Datum>
+  implements QuantitativeRulesOptions<Datum>
+{
+  color: (d: Datum) => string;
+  readonly dimensions: QuantitativeRulesDimensions;
+  labels: QuantitativeRulesLabels<Datum>;
+  stroke: Stroke;
+
+  constructor(options: QuantitativeRulesOptions<Datum>) {
+    super();
+    safeAssign(this, options);
+  }
+}

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

@@ -0,0 +1,20 @@
+export interface QuantitativeRulesDimensions {
+  quantitative: 'x' | 'y';
+  quantitativeDimension: 'width' | 'height';
+  isHorizontal: boolean;
+  isVertical: boolean;
+}
+
+export const HORIZONTAL_RULE_DIMENSIONS: QuantitativeRulesDimensions = {
+  quantitative: 'x',
+  quantitativeDimension: 'width',
+  isHorizontal: true,
+  isVertical: false,
+};
+
+export const VERTICAL_RULE_DIMENSIONS: QuantitativeRulesDimensions = {
+  quantitative: 'y',
+  quantitativeDimension: 'height',
+  isHorizontal: false,
+  isVertical: true,
+};

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

@@ -1,10 +1,13 @@
-import { DataMarksOptions } from '../../marks/config/marks-options';
-import { Stroke } from '../../stroke/stroke';
-import { QuantitativeRulesLabels } from './labels/quantitative-rules-labels';
-import { QuantitativeRulesDimensions } from './quantitative-rules-dimensions';
-export interface QuantitativeRulesOptions<Datum extends number | Date> extends DataMarksOptions<Datum> {
-    color: (d: Datum) => string;
-    stroke: Stroke;
-    dimensions: QuantitativeRulesDimensions;
-    labels: QuantitativeRulesLabels<Datum>;
-}
+import { DataMarksOptions } from '../../marks/config/marks-options';
+import { Stroke } from '../../stroke/stroke';
+import { QuantitativeRulesLabels } from './labels/quantitative-rules-labels';
+import { QuantitativeRulesDimensions } from './quantitative-rules-dimensions';
+
+export interface QuantitativeRulesOptions<
+  Datum extends number | Date,
+> extends DataMarksOptions<Datum> {
+  color: (d: Datum) => string;
+  stroke: Stroke;
+  dimensions: QuantitativeRulesDimensions;
+  labels: QuantitativeRulesLabels<Datum>;
+}

package/{lib/quantitative-rules/index.d.ts → src/lib/quantitative-rules/index.ts}

@@ -1,6 +1,6 @@
-export * from './config/labels/quantitative-rules-labels';
-export * from './config/labels/quantitative-rules-labels-options';
-export * from './config/quantitative-rules-builder';
-export * from './config/quantitative-rules-config';
-export * from './quantitative-rules.component';
-export * from './quantitative-rules.module';
+export * from './config/labels/quantitative-rules-labels';
+export * from './config/labels/quantitative-rules-labels-options';
+export * from './config/quantitative-rules-builder';
+export * from './config/quantitative-rules-config';
+export * from './quantitative-rules.component';
+export * from './quantitative-rules.module';

package/src/lib/quantitative-rules/quantitative-rules.component.scss

@@ -0,0 +1,3 @@
+:host {
+  display: block;
+}

package/src/lib/quantitative-rules/quantitative-rules.component.spec.ts

@@ -0,0 +1,50 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { XyChartComponent } from '../charts/xy-chart/xy-chart.component';
+import { QuantitativeRulesComponent } from './quantitative-rules.component';
+
+describe('QuantitativeRulesComponent', () => {
+  let component: QuantitativeRulesComponent<any>;
+  let fixture: ComponentFixture<QuantitativeRulesComponent<any>>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      schemas: [CUSTOM_ELEMENTS_SCHEMA],
+      imports: [QuantitativeRulesComponent],
+      providers: [XyChartComponent],
+    }).compileComponents();
+  });
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(QuantitativeRulesComponent);
+    component = fixture.componentInstance;
+  });
+
+  describe('drawMarks()', () => {
+    beforeEach(() => {
+      spyOn(component, 'getTransitionDuration').and.returnValue(50);
+      spyOn(component, 'drawRules');
+      spyOn(component, 'drawLabels');
+      spyOn(component, 'chartScalesMatchConfigOrientation').and.returnValue(
+        true
+      );
+      component.config = {
+        data: [1, 2, 3],
+        labels: true,
+      } as any;
+    });
+    it('calls getTransitionDuration once', () => {
+      component.drawMarks();
+      expect(component.getTransitionDuration).toHaveBeenCalledTimes(1);
+    });
+    it('calls drawRules once with transitionDuration', () => {
+      component.drawMarks();
+      expect(component.drawRules).toHaveBeenCalledOnceWith(50);
+    });
+    it('calls drawLabels once with transitionDuration if config.labels is truthy', () => {
+      component.drawMarks();
+      expect(component.drawLabels).toHaveBeenCalledOnceWith(50);
+    });
+  });
+});

package/src/lib/quantitative-rules/quantitative-rules.component.ts

@@ -0,0 +1,224 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  inject,
+} from '@angular/core';
+import { select, Selection, Transition } from 'd3';
+import { ChartComponent } from '../charts/chart/chart.component';
+import { XyChartComponent } from '../charts/xy-chart/xy-chart.component';
+import { XyAuxMarks } from '../marks';
+import { QuantitativeRulesConfig } from './config/quantitative-rules-config';
+
+type RulesSvgElements = 'g' | 'rule' | 'label';
+
+@Component({
+  // eslint-disable-next-line @angular-eslint/component-selector
+  selector: '[vic-quantitative-rules]',
+  template: '',
+  styleUrl: './quantitative-rules.component.scss',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: ChartComponent, useExisting: XyChartComponent }],
+  host: {
+    '[class]': 'config.marksClass',
+  },
+})
+export class QuantitativeRulesComponent<
+  Datum extends number | Date,
+> extends XyAuxMarks<Datum, QuantitativeRulesConfig<Datum>> {
+  rulesGroups: Selection<SVGGElement, Datum, SVGGElement, unknown>;
+  protected elRef = inject<ElementRef<SVGGElement>>(ElementRef);
+
+  get class(): Record<RulesSvgElements, string> {
+    return {
+      g: this.config.marksClass + '-group',
+      rule: this.config.marksClass + '-rule',
+      label: this.config.marksClass + '-label',
+    };
+  }
+
+  drawMarks(): void {
+    if (this.chartScalesMatchConfigOrientation()) {
+      const transitionDuration = this.getTransitionDuration();
+      this.drawRules(transitionDuration);
+      if (this.config.labels) {
+        this.drawLabels(transitionDuration);
+      }
+    }
+  }
+
+  drawRules(transitionDuration: number): void {
+    const t = select(this.chart.svgRef.nativeElement)
+      .transition()
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .duration(transitionDuration) as Transition<SVGSVGElement, any, any, any>;
+
+    this.rulesGroups = select(this.elRef.nativeElement)
+      .selectAll<SVGGElement, Datum>(`.${this.class.g}`)
+      .data<Datum>(this.config.data, (d) => d.toString())
+      .join(
+        (enter) =>
+          enter
+            .append('g')
+            .attr('class', (d, i) =>
+              `${this.class.g} ${this.config.datumClass(d, i)}`.trim()
+            )
+            .attr('transform', (d) => this.getRuleTransform(d)),
+        (update) =>
+          update
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .transition(t as any)
+            .attr('transform', (d) => this.getRuleTransform(d)),
+        (exit) => exit.remove()
+      );
+
+    this.rulesGroups
+      .selectAll<SVGLineElement, Datum>(`.${this.class.rule}`)
+      .data<Datum>((d) => [d])
+      .join(
+        (enter) =>
+          enter
+            .append('line')
+            .attr('class', this.class.rule)
+            .attr('stroke', (d) => this.config.color(d))
+            .attr('stroke-width', this.config.stroke.width)
+            .attr('opacity', this.config.stroke.opacity)
+            .attr('stroke-dasharray', this.config.stroke.dasharray)
+            .attr('stroke-linecap', this.config.stroke.linecap)
+            .attr('stroke-linejoin', this.config.stroke.linejoin)
+            .attr('x1', 0)
+            .attr('x2', this.getWidth())
+            .attr('y1', 0)
+            .attr('y2', this.getHeight()),
+        (update) =>
+          update
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .transition(t as any)
+            .attr('x1', 0)
+            .attr('x2', this.getWidth())
+            .attr('y1', 0)
+            .attr('y2', this.getHeight()),
+        (exit) => exit.remove()
+      );
+  }
+
+  drawLabels(transitionDuration: number): void {
+    const t = select(this.chart.svgRef.nativeElement)
+      .transition()
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      .duration(transitionDuration) as Transition<SVGSVGElement, any, any, any>;
+
+    this.rulesGroups
+      .selectAll<SVGTextElement, Datum>(`.${this.class.label}`)
+      .data<Datum>((d) => [d])
+      .join(
+        (enter) =>
+          enter
+            .append('text')
+            .attr('class', this.class.label)
+            .style('display', (d) =>
+              this.config.labels.display(d) ? null : 'none'
+            )
+            .attr('fill', (d) => this.config.labels.color(d))
+            .attr('text-anchor', this.config.labels.textAnchor)
+            .attr('dominant-baseline', this.config.labels.dominantBaseline)
+            .attr('x', (d) => this.getLabelX(d))
+            .attr('y', (d) => this.getLabelY(d))
+            .text((d) => this.config.labels.value(d)),
+        (update) =>
+          update
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            .transition(t as any)
+            .style('display', (d) =>
+              this.config.labels.display(d) ? null : 'none'
+            )
+            .attr('fill', (d) => this.config.labels.color(d))
+            .attr('text-anchor', this.config.labels.textAnchor)
+            .attr('dominant-baseline', this.config.labels.dominantBaseline)
+            .attr('x', (d) => this.getLabelX(d))
+            .attr('y', (d) => this.getLabelY(d)),
+        (exit) => exit.remove()
+      );
+  }
+
+  // Intended to flag situations where both chart scales and the config are both updated
+  // and one goes before the other.
+  chartScalesMatchConfigOrientation(): boolean {
+    if (this.config.dimensions.isHorizontal) {
+      return this.config.data.every((d) => this.scales.y(d) !== undefined);
+    } else {
+      return this.config.data.every((d) => this.scales.x(d) !== undefined);
+    }
+  }
+
+  getRuleTransform(d: Datum): string {
+    let x;
+    let y;
+    if (this.config.dimensions.isHorizontal) {
+      x = this.scales.x.range()[0];
+      y = this.getYStart(d);
+    } else {
+      x = this.getXStart(d);
+      y = this.scales.y.range()[0];
+    }
+    return `translate(${x}, ${y})`;
+  }
+
+  getXStart(d: Datum): number {
+    if (this.config.dimensions.isHorizontal) {
+      return this.scales.x.range()[0];
+    }
+    return this.scales.x(d);
+  }
+
+  getYStart(d: Datum): number {
+    if (this.config.dimensions.isHorizontal) {
+      return this.scales.y(d);
+    }
+    return this.scales.y.range()[1] - this.scales.y.range()[0];
+  }
+
+  getWidth(): number {
+    if (this.config.dimensions.isHorizontal) {
+      return this.scales.x.range()[1] - this.scales.x.range()[0];
+    } else {
+      return 0;
+    }
+  }
+
+  getHeight(): number {
+    if (this.config.dimensions.isHorizontal) {
+      return 0;
+    } else {
+      return this.scales.y.range()[1] - this.scales.y.range()[0];
+    }
+  }
+
+  getLabelX(d: Datum): number {
+    if (this.config.dimensions.isHorizontal) {
+      return this.config.labels.position(this.getXStart(d), this.getXEnd(d), d);
+    }
+    return this.config.labels.offset;
+  }
+
+  getLabelY(d: Datum): number {
+    if (this.config.dimensions.isHorizontal) {
+      return this.config.labels.offset;
+    }
+    return this.config.labels.position(this.getYStart(d), this.getYEnd(d), d);
+  }
+
+  getXEnd(d: Datum): number {
+    if (this.config.dimensions.isHorizontal) {
+      return this.scales.x.range()[1] - this.scales.x.range()[0];
+    }
+    return this.scales.x(d);
+  }
+
+  getYEnd(d: Datum): number {
+    if (this.config.dimensions.isHorizontal) {
+      return this.scales.y(d);
+    }
+    return this.scales.y.range()[1];
+  }
+}