@mathstack/viz 1.1.4 → 2.0.3

package/src/lib/axes/ticks/tick-wrap/tick-wrap.ts

@@ -0,0 +1,21 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { TickWrapOptions } from './tick-wrap-options';
+
+/**
+ * A config that specifies how axis tick labels should wrap.
+ */
+export class TickWrap {
+  maintainXPosition: boolean;
+  maintainYPosition: boolean;
+  lineHeight: number;
+  breakOnChars: string[];
+  spaceAroundBreakChars: boolean;
+  width:
+    | 'bandwidth'
+    | number
+    | ((chartWidth: number, numOfTicks: number) => number);
+
+  constructor(options: TickWrapOptions) {
+    safeAssign(this, options);
+  }
+}

package/src/lib/axes/ticks/ticks-builder.ts

@@ -0,0 +1,370 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { AxisTimeInterval } from 'd3';
+import { TickWrapBuilder } from './tick-wrap/tick-wrap-builder';
+import { QuantitativeTicks, Ticks } from './ticks';
+
+export interface AxisSpecificTickBuilderOptions {
+  _sizeOuter: number;
+}
+
+export interface AxisSpecificQuantitativeTickBuilderOptions<
+  Tick,
+> extends AxisSpecificTickBuilderOptions {
+  _format: string | ((value: Tick) => string);
+}
+
+const DEFAULT = {
+  _class: () => '',
+  _labelsDisplay: true,
+  _marksDisplay: true,
+  _remove: false,
+  _stroke: 'none',
+  _strokeOpacity: 1,
+  _strokeWidth: 3,
+};
+
+const QUANT_DEFAULT = {
+  _spacing: 40,
+};
+
+export class TicksBuilder<Tick> {
+  protected _class: (d: Tick) => string;
+  protected _fontSize: number;
+  protected _format: string | ((value: Tick) => string);
+  protected _labelsDisplay: boolean;
+  protected _rotate: number;
+  protected _labelsStroke: string;
+  protected _labelsStrokeOpacity: number;
+  protected _labelsStrokeWidth: number;
+  protected _marksDisplay: boolean;
+  protected _size: number;
+  protected _sizeInner: number;
+  protected _sizeOuter: number;
+  protected wrapBuilder: TickWrapBuilder;
+
+  constructor(options: Partial<AxisSpecificTickBuilderOptions>) {
+    safeAssign(this, DEFAULT);
+    safeAssign(this, options);
+  }
+
+  /**
+   * OPTIONAL. Provides a class on the SVG G element that corresponds to a single tick.
+   *
+   * 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: Tick) => string): this;
+  class(value: ((d: Tick) => 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. Sets the font size of the tick labels.
+   *
+   * @param value - The font size of the tick labels, in px.
+   *
+   * If not called, the default font size is D3's default, which is 10px.
+   */
+  fontSize(value: number | null): this {
+    if (value === null) {
+      this._fontSize = undefined;
+      return this;
+    }
+    this._fontSize = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Specifies how tick labels will be formatted. The format can be a string or a function.
+   *
+   * @param value - Either a D3 format string, a function that takes a value and returns a string, or `null` to unset the format.
+   *
+   * If not called, the default value for quantitative axes is ',.1f'. If not called for an ordinal axis, tick labels will be the unformatted ordinal value.
+   */
+  format(format: string): this;
+  format(format: (value: Tick) => string): this;
+  format(format: null): this;
+  format(format: string | ((value: Tick) => string) | null): this {
+    if (format === null) {
+      this._format = undefined;
+      return this;
+    }
+    this._format = format;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. If false, tick labels will be removed.
+   *
+   * @param value - `true` to retain all tick labels, `false` to remove all tick labels.
+   *
+   * If not called, the default value is `true`.
+   */
+  labelsDisplay(value: boolean): this {
+    this._labelsDisplay = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Sets the color of the stroke around the tick labels. Often used to improve the legibility of tick labels, for example, on dark backgrounds.
+   *
+   * @param value - The stroke of the tick labels.
+   *
+   * If not called, the default value is 'none'.
+   */
+  labelsStroke(value: string | null): this {
+    if (value === null) {
+      this._labelsStroke = DEFAULT._stroke;
+      return this;
+    }
+    this._labelsStroke = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Sets the opacity of the stroke applied around the tick labels.
+   *
+   * @param value - The opacity of the stroke around the tick labels.
+   *
+   * If not called, the default value is 1.
+   */
+  labelsStrokeOpacity(value: number | null): this {
+    if (value === null) {
+      this._labelsStrokeOpacity = undefined;
+      return this;
+    }
+    this._labelsStrokeOpacity = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Sets the width of the stroke around the tick labels. Often used to improve the legibility of tick labels, for example, on dark backgrounds.
+   *
+   * @param value - The width of the stroke around the tick labels.
+   *
+   * If not called, the default value is 3.
+   */
+  labelsStrokeWidth(value: number | null): this {
+    if (value === null) {
+      this._labelsStrokeWidth = undefined;
+      return this;
+    }
+    this._labelsStrokeWidth = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. If false, tick marks (lines) will be removed.
+   *
+   * @param value - `true` to retain all tick marks, `false` to remove all tick marks.
+   *
+   * If not called, the default value is `true`.
+   */
+  marksDisplay(value: boolean): this {
+    this._marksDisplay = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Determines the rotation of tick labels.
+   *
+   * @param value - The rotation of the tick labels in degrees, or `null` to unset the rotation.
+   *
+   * Positive values rotate clockwise, negative values rotate counterclockwise.
+   *
+   * If not called, ticks will not be rotated.
+   */
+
+  rotate(value: number | null): this {
+    if (value === null) {
+      this._rotate = undefined;
+      return this;
+    }
+    this._rotate = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Sets the size of inner and outer tick marks.
+   *
+   * @param value - The size of the ticks, in px.
+   *
+   * If not called or called with `null`, the default size is the D3 default size.
+   *
+   * If specified, this value will override any values set by `sizeInner` or `sizeOuter`.
+   */
+  size(value: number | null): this {
+    if (value === null) {
+      this._size = undefined;
+      return this;
+    }
+    this._size = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Determines the length of the inner ticks drawn by D3. Does not apply to the outermost ticks.
+   *
+   * @param value - The length of the inner ticks in pixels, or `null` to unset the value.
+   *
+   * If not called or called with `null`, the default value is the D3 default size.
+   *
+   */
+  sizeInner(value: number | null): this {
+    if (value === null) {
+      this._sizeInner = undefined;
+      return this;
+    }
+    this._sizeInner = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Determines the length of the square ends of the domain path drawn by D3.
+   *
+   * @param value - The length of the square ends of the domain path in pixels, or `null` to unset the value.
+   *
+   * If not called on ordinal axes, the default value is 0. If not called on quantitative axes, no modification is made to D3's default value.
+   */
+  sizeOuter(value: number | null): this {
+    if (value === null) {
+      this._sizeOuter = undefined;
+      return this;
+    }
+    this._sizeOuter = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Specifies how tick labels will be wrapped.
+   *
+   * @param wrap - A callback that specifies how tick labels will be wrapped, or `null` to unset the wrapping.
+   *
+   * If not called, the tick labels will not be wrapped.
+   */
+  wrap(wrap: (wrap: TickWrapBuilder) => void): this;
+  wrap(wrap: null): this;
+  wrap(wrap: (wrap: TickWrapBuilder) => void | null): this {
+    if (wrap === null) {
+      this.wrapBuilder = undefined;
+      return this;
+    }
+    this.wrapBuilder = new TickWrapBuilder();
+    wrap(this.wrapBuilder);
+    return this;
+  }
+
+  _build(dimension: 'x' | 'y'): Ticks<Tick> {
+    return new Ticks({
+      class: this._class,
+      fontSize: this._fontSize,
+      format: this._format,
+      labelsDisplay: this._labelsDisplay,
+      labelsStroke: this._labelsStroke,
+      labelsStrokeOpacity: this._labelsStrokeOpacity,
+      labelsStrokeWidth: this._labelsStrokeWidth,
+      marksDisplay: this._marksDisplay,
+      rotate: this._rotate,
+      size: this._size,
+      sizeInner: this._sizeInner,
+      sizeOuter: this._sizeOuter,
+      wrap: this.wrapBuilder?._build(dimension),
+    });
+  }
+}
+
+export class QuantitativeTicksBuilder<Tick> extends TicksBuilder<Tick> {
+  private _count: number | AxisTimeInterval;
+  private _spacing: number;
+  private _values: Tick[];
+
+  constructor(
+    options: Partial<AxisSpecificQuantitativeTickBuilderOptions<Tick>>
+  ) {
+    super(options);
+    safeAssign(this, DEFAULT);
+    safeAssign(this, QUANT_DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. Approximately specifies the number of ticks for the axis.
+   *
+   * @param value - The number of ticks to pass to D3's axis.ticks(), or null to unset the number of ticks.
+   *
+   * If not called, a reasonable and valid default will be used based on the size of the chart.
+   *
+   * Note that this number will be passed to D3's `ticks()` method and therefore it can be an approximate number of ticks.
+   *
+   * If this method is called, the passed in number of ticks will be validated against the data domain and the value formatter for the axis. If the number of ticks is not valid—for example, if the ticks are formatted with %Y and there are three years of values in the data, and this method is called with 10, a valid number will be used instead.
+   */
+  count(value: number | AxisTimeInterval | null): this {
+    if (value === null) {
+      this._count = undefined;
+      return this;
+    }
+    this._count = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Specifies the an approximate spacing between ticks, in pixels.
+   *
+   * @param value - The spacing between ticks in pixels, or null to unset the spacing.
+   *
+   * If not called, the default value is 40. If `count` is set, this value will be ignored.
+   */
+  spacing(value: number | null): this {
+    if (value === null) {
+      this._spacing = undefined;
+      return this;
+    }
+    this._spacing = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Determines the values that will show up as ticks on the axis.
+   *
+   * @param values - An array of quantitative values to pass to D3's axis.tickValues(), or null to unset the tick values.
+   *
+   */
+  values(values: Tick[] | null): this {
+    if (values === null) {
+      this._values = undefined;
+      return this;
+    }
+    this._values = values;
+    return this;
+  }
+
+  override _build(dimension: 'x' | 'y'): QuantitativeTicks<Tick> {
+    return new QuantitativeTicks({
+      class: this._class,
+      count: this._count,
+      fontSize: this._fontSize,
+      format: this._format,
+      labelsDisplay: this._labelsDisplay,
+      labelsStroke: this._labelsStroke,
+      labelsStrokeOpacity: this._labelsStrokeOpacity,
+      labelsStrokeWidth: this._labelsStrokeWidth,
+      marksDisplay: this._marksDisplay,
+      rotate: this._rotate,
+      size: this._size,
+      sizeInner: this._sizeInner,
+      sizeOuter: this._sizeOuter,
+      spacing: this._spacing,
+      values: this._values,
+      wrap: this.wrapBuilder?._build(dimension),
+    });
+  }
+}

package/src/lib/axes/ticks/ticks-options.ts

@@ -0,0 +1,24 @@
+import { AxisTimeInterval } from 'd3';
+import { TickWrap } from './tick-wrap/tick-wrap';
+
+export interface TicksOptions<Tick> {
+  class: (d: Tick) => string;
+  fontSize: number;
+  format: string | ((value: Tick) => string);
+  labelsDisplay: boolean;
+  labelsStroke: string;
+  labelsStrokeOpacity: number;
+  labelsStrokeWidth: number;
+  marksDisplay: boolean;
+  rotate: number;
+  size: number;
+  sizeInner: number;
+  sizeOuter: number;
+  wrap: TickWrap;
+}
+
+export interface QuantitativeTicksOptions<Tick> extends TicksOptions<Tick> {
+  count: number | AxisTimeInterval;
+  spacing: number;
+  values: Tick[];
+}

package/src/lib/axes/ticks/ticks.ts

@@ -0,0 +1,33 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { TickWrap } from './tick-wrap/tick-wrap';
+import { QuantitativeTicksOptions, TicksOptions } from './ticks-options';
+
+export class Ticks<Tick> implements TicksOptions<Tick> {
+  class: (d: Tick) => string;
+  fontSize: number;
+  format: string | ((value: Tick) => string);
+  labelsDisplay: boolean;
+  labelsStroke: string;
+  labelsStrokeOpacity: number;
+  labelsStrokeWidth: number;
+  marksDisplay: boolean;
+  rotate: number;
+  size: number;
+  sizeInner: number;
+  sizeOuter: number;
+  wrap: TickWrap;
+
+  constructor(options: TicksOptions<Tick>) {
+    safeAssign(this, options);
+  }
+}
+
+export class QuantitativeTicks<Tick> extends Ticks<Tick> {
+  count: number;
+  spacing: number;
+  values: Tick[];
+
+  constructor(options: QuantitativeTicksOptions<Tick>) {
+    super(options);
+  }
+}

package/src/lib/axes/x/x-axis-config.ts

@@ -0,0 +1,48 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { DataValue } from '../../core';
+import { AbstractConstructor } from '../../core/common-behaviors/constructor';
+import { XyAxisConfig } from '../base/config/xy-axis-config';
+import { XyAxisBaseOptions } from '../base/config/xy-axis-options';
+import { Ticks } from '../ticks/ticks';
+
+export interface XAxisOptions extends XyAxisBaseOptions {
+  /**
+   * The side of the chart on which the axis will be placed.
+   */
+  side: 'top' | 'bottom';
+}
+
+export function mixinXAxisConfig<
+  Tick extends DataValue,
+  TicksConfig extends Ticks<Tick>,
+  T extends AbstractConstructor<XyAxisConfig<Tick, TicksConfig>>,
+>(Base: T) {
+  abstract class Mixin extends Base {
+    side: 'top' | 'bottom';
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(...args: any[]) {
+      super(...args);
+      if (args.length > 0) {
+        safeAssign(this, args[0]);
+      }
+    }
+
+    getNumTicksBySpacing(
+      spacing: number,
+      dimensions: {
+        height: number;
+        width: number;
+      }
+    ): number {
+      const d3SuggestedDefault = dimensions.width / spacing;
+      return this.getValidatedNumTicks(d3SuggestedDefault);
+    }
+  }
+  return Mixin;
+}
+
+export class XAxisConfig<
+  Tick extends DataValue,
+  TicksConfig extends Ticks<Tick>,
+> extends mixinXAxisConfig(XyAxisConfig)<Tick, TicksConfig> {}

package/src/lib/axes/x/x-axis.spec.ts

@@ -0,0 +1,90 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ElementRef } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { XyChartComponent } from '@mathstack/viz';
+import { axisBottom, axisTop } from 'd3';
+import { XAxisStub } from '../../testing/stubs/x-axis.stub';
+import { VicXQuantitativeAxisConfigBuilder } from '../x-quantitative/x-quantitative-axis-builder';
+
+describe('the XAxis mixin', () => {
+  let abstractClass: XAxisStub<number>;
+  const mockElementRef = {
+    nativeElement: {
+      querySelector: jasmine.createSpy('querySelector'),
+      style: {},
+    },
+  };
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({
+      providers: [
+        XAxisStub,
+        XyChartComponent,
+        { provide: ElementRef, useValue: mockElementRef },
+      ],
+    });
+    abstractClass = TestBed.inject(XAxisStub);
+    abstractClass.scales = {
+      y: {
+        range: jasmine.createSpy().and.returnValue([100, 20]),
+      },
+      x: 'scale',
+    } as any;
+    abstractClass.chart.config = {
+      margin: { top: 10 },
+    } as any;
+  });
+
+  describe('setTranslate()', () => {
+    beforeEach(() => {
+      spyOn(abstractClass, 'getTranslateDistance').and.returnValue(90);
+      abstractClass.setTranslate();
+    });
+    it('calls getTranslateDistance once', () => {
+      expect(abstractClass.getTranslateDistance).toHaveBeenCalledTimes(1);
+    });
+    it('returns the correct string', () => {
+      expect(abstractClass.translate).toEqual('translate(0, 90)');
+    });
+  });
+
+  describe('integration: getTranslateDistance', () => {
+    it('returns the correct value for the top side', () => {
+      abstractClass.config = new VicXQuantitativeAxisConfigBuilder()
+        .side('top')
+        .getConfig() as any;
+      expect(abstractClass.getTranslateDistance()).toBe(20);
+    });
+    it('returns the correct value for the bottom side', () => {
+      abstractClass.config = new VicXQuantitativeAxisConfigBuilder()
+        .side('bottom')
+        .getConfig() as any;
+      expect(abstractClass.getTranslateDistance()).toBe(100);
+    });
+  });
+
+  describe('setScale', () => {
+    it('sets scale to the correct value', () => {
+      abstractClass.setScale();
+      expect(abstractClass.scale).toBe('scale');
+    });
+  });
+
+  describe('setAxisFunction', () => {
+    it('sets the axis function to the correct value if side is top', () => {
+      abstractClass.config = new VicXQuantitativeAxisConfigBuilder()
+        .side('top')
+        .getConfig() as any;
+      abstractClass.setAxisFunction();
+      expect(abstractClass.axisFunction).toEqual(axisTop);
+    });
+
+    it('sets the axis function to the correct value if side is bottom', () => {
+      abstractClass.config = new VicXQuantitativeAxisConfigBuilder()
+        .side('bottom')
+        .getConfig() as any;
+      abstractClass.setAxisFunction();
+      expect(abstractClass.axisFunction).toEqual(axisBottom);
+    });
+  });
+});

package/src/lib/axes/x/x-axis.ts

@@ -0,0 +1,109 @@
+import { axisBottom, axisTop } from 'd3';
+import { AbstractConstructor } from '../../core/common-behaviors/constructor';
+import { ContinuousValue, DataValue } from '../../core/types/values';
+import { XyAxis } from '../base/xy-axis-base';
+import { Ticks } from '../ticks/ticks';
+import { XAxisConfig } from './x-axis-config';
+
+export function xAxisMixin<
+  Tick extends DataValue | ContinuousValue,
+  TicksConfig extends Ticks<Tick>,
+  T extends AbstractConstructor<XyAxis<Tick, TicksConfig>>,
+>(Base: T) {
+  abstract class Mixin extends Base {
+    override config: XAxisConfig<Tick, TicksConfig>;
+    translate: string;
+
+    setTranslate(): void {
+      const translate = this.getTranslateDistance();
+      this.translate = `translate(0, ${translate})`;
+    }
+
+    getTranslateDistance(): number {
+      return this.config.side === 'top'
+        ? this.getTopTranslate()
+        : this.getBottomTranslate();
+    }
+
+    getTopTranslate(): number {
+      return this.scales.y.range()[1];
+    }
+
+    getBottomTranslate(): number {
+      return this.scales.y.range()[0];
+    }
+
+    getBaselineTranslate(): string | null {
+      if (!this.otherAxisHasPosAndNegValues('x')) return null;
+
+      const rangeIndexForSide = this.config.side === 'top' ? 1 : 0;
+      const translateDistance =
+        this.scales.y(0) - this.scales.y.range()[rangeIndexForSide];
+      return `translate(0, ${translateDistance})`;
+    }
+
+    setScale(): void {
+      this.scale = this.scales.x;
+    }
+
+    setAxisFunction(): void {
+      this.axisFunction = this.config.side === 'top' ? axisTop : axisBottom;
+    }
+
+    createLabel(): void {
+      const config = this.config.label;
+      if (!config) return;
+
+      const spaceFromMarginEdge = 4;
+      let x = config.offset.x || 0;
+      let y = config.offset.y || 0;
+
+      y +=
+        this.config.side === 'top'
+          ? this.chart.config.margin.top * -1 + spaceFromMarginEdge
+          : this.chart.config.margin.bottom - spaceFromMarginEdge;
+
+      let anchor: 'start' | 'middle' | 'end';
+      const range = this.scales.x.range();
+
+      if (config.position === 'start') {
+        x += range[0];
+        anchor = config.anchor || 'start';
+      } else if (config.position === 'middle') {
+        x += (range[1] - range[0]) / 2 + range[0];
+        anchor = config.anchor || 'middle';
+      } else {
+        x += range[1];
+        anchor = config.anchor || 'end';
+      }
+
+      let label = this.axisGroup.select<SVGTextElement>(`.${this.class.label}`);
+      const needsInit = label.empty();
+
+      if (needsInit) {
+        label = this.axisGroup
+          .append<SVGTextElement>('text')
+          .attr('class', this.class.label);
+      }
+
+      label
+        .text(this.config.label.text)
+        .attr('text-anchor', anchor)
+        .attr('y', y)
+        .style('visibility', config.wrap ? 'hidden' : 'visible');
+
+      if (config.wrap) {
+        requestAnimationFrame(() => {
+          this.config.label.wrap.wrap(label);
+          label.attr('x', x).style('visibility', 'visible');
+
+          label.selectAll('tspan').attr('x', x);
+        });
+      } else {
+        label.attr('x', x);
+      }
+    }
+  }
+
+  return Mixin;
+}