@mathstack/viz 2.1.0 → 2.2.0

package/src/lib/data-dimensions/continuous-quantitative/number-visual-value/number-visual-value-builder.ts

@@ -1,166 +0,0 @@
-import { safeAssign } from '@mathstack/app-kit';
-import { ScaleContinuousNumeric, scaleLinear } from 'd3';
-import { VisualValue } from '../../../core';
-import { DataDimensionBuilder } from '../../dimension-builder';
-import { NumberVisualValueDimension } from './number-visual-value';
-
-const DEFAULT = {
-  _includeZeroInDomain: false,
-  _scaleFn: scaleLinear,
-};
-
-export class NumberVisualValueDimensionBuilder<
-  Datum,
-  Range extends VisualValue,
-> extends DataDimensionBuilder<Datum, number> {
-  private _domain: [number, number];
-  private _formatSpecifier: string;
-  private _includeZeroInDomain: boolean;
-  private _range: [Range, Range];
-  private _scale: (value: number) => Range;
-  private _scaleFn: (
-    domain?: Iterable<number>,
-    range?: Iterable<Range>
-  ) => ScaleContinuousNumeric<Range, Range>;
-
-  constructor() {
-    super();
-    safeAssign(this, DEFAULT);
-  }
-
-  /**
-   * OPTIONAL. Sets the domain of the scale.
-   *
-   * Should be in the form of [min, max].
-   *
-   * If not provided, the domain will be determined by the data.
-   */
-  domain(domain: null): this;
-  domain(domain: [number, number]): this;
-  domain(domain: [number, number]): this {
-    if (domain === null) {
-      this._domain = undefined;
-      return this;
-    }
-    this._domain = domain;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Sets a format specifier that will be applied to the value of this dimension for display purposes.
-   */
-  formatSpecifier(formatSpecifier: null): this;
-  formatSpecifier(formatSpecifier: string): this;
-  formatSpecifier(formatSpecifier: string): this {
-    if (formatSpecifier === null) {
-      this._formatSpecifier = undefined;
-      return this;
-    }
-    this._formatSpecifier = formatSpecifier;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Sets a boolean that indicates whether the domain of the dimension's scale should include zero.
-   *
-   * @default false
-   */
-  includeZeroInDomain(includeZeroInDomain: boolean): this {
-    this._includeZeroInDomain = includeZeroInDomain;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Sets a range of visual values that will be the output from D3 scale linear.
-   *
-   * If not provided, a scale must be provided.
-   *
-   * For example, this could be a range of colors or sizes.
-   *
-   * To have all marks use the same visual value, use an array with a single element.
-   */
-  range(range: null): this;
-  range(range: [Range, Range]): this;
-  range(range: [Range, Range]): this {
-    if (range === null) {
-      this._range = undefined;
-      return this;
-    }
-    this._range = range;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. This is a D3 scale function that maps values from the dimension's domain to the dimension's range.
-   *
-   * If the user provides a custom scale function through the `scale` method, this will be ignored.
-   *
-   * @default d3.scaleLinear
-   */
-  scaleFn(scaleFn: null): this;
-  scaleFn(
-    scaleFn: (
-      domain?: Iterable<number>,
-      range?: Iterable<Range>
-    ) => ScaleContinuousNumeric<Range, Range>
-  ): this;
-  scaleFn(
-    scaleFn: (
-      domain?: Iterable<number>,
-      range?: Iterable<Range>
-    ) => ScaleContinuousNumeric<Range, Range>
-  ): this {
-    if (scaleFn === null) {
-      this._scaleFn = undefined;
-      return this;
-    }
-    this._scaleFn = scaleFn;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Allows a user to set a completely custom scale that transforms the value returned by this dimension's valueAccessor into a visual value (string or number).
-   *
-   * If not provided, a range must be provided.
-   *
-   * If provided, this will override any values provided to domain, range, and scaleFn.
-   */
-  scale(scale: null): this;
-  scale(scale: (value: number) => Range): this;
-  scale(scale: (value: number) => Range): this {
-    if (scale === null) {
-      this._scale = undefined;
-      return this;
-    }
-    this._scale = scale;
-    return this;
-  }
-
-  /**
-   * @internal This method is not intended to be used by consumers of this library.
-   *
-   * @param dimensionName A user-intelligible name for the dimension being built. Used for error messages. Should be title cased.
-   */
-  _build(dimensionName: string): NumberVisualValueDimension<Datum, Range> {
-    this.validateBuilder(dimensionName);
-    return new NumberVisualValueDimension({
-      domain: this._domain,
-      formatFunction: this._formatFunction,
-      formatSpecifier: this._formatSpecifier,
-      includeZeroInDomain: this._includeZeroInDomain,
-      range: this._range,
-      scaleFn: this._scaleFn,
-      scale: this._scale,
-      valueAccessor: this._valueAccessor,
-    });
-  }
-
-  private validateBuilder(dimensionName: string): void {
-    this.validateValueAccessor(dimensionName);
-    if (!this._range && !this._scale) {
-      throw new Error(
-        `${dimensionName} Dimension: Either a range or a scale must be provided.`
-      );
-    }
-  }
-}

package/src/lib/data-dimensions/continuous-quantitative/number-visual-value/number-visual-value-options.ts

@@ -1,10 +0,0 @@
-import { VisualValue } from '../../../core/types/values';
-import { NumberDimensionOptions } from '../number-dimension/number-dimension-options';
-
-export interface NumberVisualValueDimensionOptions<
-  Datum,
-  Range extends VisualValue,
-> extends NumberDimensionOptions<Datum, Range> {
-  range: [Range, Range];
-  scale: (value: number) => Range;
-}

package/src/lib/data-dimensions/continuous-quantitative/number-visual-value/number-visual-value.spec.ts

@@ -1,34 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { NumberVisualValueDimension } from './number-visual-value';
-import { NumberVisualValueDimensionBuilder } from './number-visual-value-builder';
-
-describe('NumberVisualValueDimension', () => {
-  let dimension: NumberVisualValueDimension<number, number>;
-  beforeEach(() => {
-    dimension = new NumberVisualValueDimensionBuilder<number, number>()
-      .valueAccessor((d) => d)
-      .range([0, 100])
-      ._build('Test');
-  });
-  describe('setPropertiesFromData', () => {
-    beforeEach(() => {
-      spyOn(dimension as any, 'setValues');
-      spyOn(dimension as any, 'setDomain');
-      spyOn(dimension as any, 'setScale');
-    });
-    it('calls setValues once', () => {
-      dimension.setPropertiesFromData([1, 2, 3, 4, 5]);
-      expect((dimension as any).setValues).toHaveBeenCalledOnceWith([
-        1, 2, 3, 4, 5,
-      ]);
-    });
-    it('calls setDomain once', () => {
-      dimension.setPropertiesFromData([1, 2, 3, 4, 5]);
-      expect((dimension as any).setDomain).toHaveBeenCalledTimes(1);
-    });
-    it('calls setScale once', () => {
-      dimension.setPropertiesFromData([1, 2, 3, 4, 5]);
-      expect((dimension as any).setScale).toHaveBeenCalledTimes(1);
-    });
-  });
-});

package/src/lib/data-dimensions/continuous-quantitative/number-visual-value/number-visual-value.ts

@@ -1,57 +0,0 @@
-import { safeAssign } from '@mathstack/app-kit';
-import { ScaleContinuousNumeric } from 'd3';
-import { VisualValue } from '../../../core';
-import { NumberDimension } from '../number-dimension/number-dimension';
-import { NumberVisualValueDimensionOptions } from './number-visual-value-options';
-
-/**
- * A dimension that transforms number values into a value of type number or string.
- *
- * This dimension is intended to be used to set a visual property of an element in a chart.
- *
- * The first generic is the type of the data that will be passed to the dimension. The second generic is the type of the range of the scale / the output value.
- *
- * TESTABLE FUNCTIONALITY
- *
- * - It extracts values for the dimension from data.
- *   - tested in: dots.cy.ts
- * - It sets the domain of the dimension.
- *   - tested in: dots.cy.ts
- * - It set the scale from the calculated domain and the user-provided range of the user does not provide a scale.
- *   - tested in: dots.cy.ts
- */
-
-export class NumberVisualValueDimension<
-  Datum,
-  Range extends VisualValue,
-> extends NumberDimension<Datum> {
-  readonly range: [Range, Range];
-  private scale: (value: number) => Range;
-  readonly scaleFn: (
-    domain?: Iterable<number>,
-    range?: Iterable<Range>
-  ) => ScaleContinuousNumeric<Range, Range>;
-
-  constructor(options: NumberVisualValueDimensionOptions<Datum, Range>) {
-    super('number');
-    safeAssign(this, options);
-  }
-
-  getScale(): (value: number) => Range {
-    return this.scale;
-  }
-
-  setPropertiesFromData(data: Datum[]): void {
-    this.setValues(data);
-    this.setDomain();
-    this.setScale();
-  }
-
-  private setScale(): void {
-    if (this.scale === undefined) {
-      this.scale = this.scaleFn()
-        .domain(this.calculatedDomain)
-        .range(this.range);
-    }
-  }
-}

package/src/lib/data-dimensions/dimension-builder.ts

@@ -1,45 +0,0 @@
-import { DataValue } from '../core/types/values';
-
-export abstract class DataDimensionBuilder<
-  Datum,
-  TDataValue extends DataValue,
-> {
-  protected _formatFunction: (d: Datum) => string;
-  protected _valueAccessor: (d: Datum) => TDataValue;
-
-  /**
-   * OPTIONAL. Sets a function that will be applied to the value of this dimension for display purposes.
-   *
-   * If provided, this function will be used instead of the format specifier (available only for quantitative dimensions)
-   */
-  formatFunction(formatFunction: null): this;
-  formatFunction(formatFunction: (d: Datum) => string): this;
-  formatFunction(formatFunction: ((d: Datum) => string) | null): this {
-    if (formatFunction === null) {
-      this._formatFunction = undefined;
-      return this;
-    }
-    this._formatFunction = formatFunction;
-    return this;
-  }
-
-  /**
-   * Sets a user-provided method that extracts the value for this dimension from a datum.
-   *
-   * REQUIRED. for quantitative dimensions.
-   *
-   * OPTIONAL. for categorical and ordinal dimensions, though if not provided, the properties of those dimensions cannot reflect the data values.
-   */
-  valueAccessor(valueAccessor: (d: Datum) => TDataValue): this {
-    this._valueAccessor = valueAccessor;
-    return this;
-  }
-
-  protected validateValueAccessor(dimensionName: string): void {
-    if (!this._valueAccessor) {
-      throw new Error(
-        `${dimensionName} Dimension: valueAccessor is required. Please use method 'valueAccessor' to set it.`
-      );
-    }
-  }
-}

package/src/lib/data-dimensions/dimension-options.ts

@@ -1,12 +0,0 @@
-import { DataValue } from '../core/types/values';
-
-export interface DataDimensionOptions<Datum, TDataValue extends DataValue> {
-  /**
-   * A function that will be applied to the value of this dimension for display purposes. If provided, this function will be used instead of the format specifier (available only for quantitative dimensions)
-   */
-  formatFunction: (d: Datum) => string;
-  /**
-   * A user-provided method that extracts the value for this dimension from a datum. If the dimension is continuous (number of Date), a user *must* provide this method.
-   */
-  valueAccessor: (d: Datum) => TDataValue;
-}

package/src/lib/data-dimensions/dimension.ts

@@ -1,30 +0,0 @@
-import { map } from 'd3';
-import { DataValue } from '../core/types/values';
-import { DataDimensionOptions } from './dimension-options';
-
-export abstract class DataDimension<
-  Datum,
-  TDataValue extends DataValue,
-> implements DataDimensionOptions<Datum, TDataValue> {
-  readonly dimensionType: 'number' | 'ordinal' | 'date';
-  readonly formatFunction: (d: Datum) => string;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  readonly valueAccessor: (d: Datum) => TDataValue;
-  /**
-   * An array of values for this dimension, extracted from the data using the value accessor.
-   * @see {@link valueAccessor}
-   */
-  values: TDataValue[];
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  abstract setPropertiesFromData(data: Datum[], ...args: any): void;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  protected abstract setDomain(...args: any): void;
-  protected setValues(data: Datum[]): void {
-    this.values = map(data, this.valueAccessor);
-  }
-
-  constructor(dimensionType: 'number' | 'ordinal' | 'date') {
-    this.dimensionType = dimensionType;
-  }
-}

package/src/lib/data-dimensions/index.ts

@@ -1,31 +0,0 @@
-export * from '../fill-definitions/fill-definitions';
-export * from './continuous-quantitative/date-chart-position/date-chart-position';
-export * from './continuous-quantitative/date-chart-position/date-chart-position-builder';
-export * from './continuous-quantitative/date-chart-position/date-chart-position-options';
-export * from './continuous-quantitative/number-chart-position/domain-padding/concrete-domain-padding';
-export * from './continuous-quantitative/number-chart-position/domain-padding/domain-padding';
-export * from './continuous-quantitative/number-chart-position/domain-padding/percent-over/percent-over';
-export * from './continuous-quantitative/number-chart-position/domain-padding/percent-over/percent-over-options';
-export * from './continuous-quantitative/number-chart-position/domain-padding/pixel/pixel';
-export * from './continuous-quantitative/number-chart-position/domain-padding/pixel/pixel-options';
-export * from './continuous-quantitative/number-chart-position/domain-padding/round-to-interval/round-to-interval';
-export * from './continuous-quantitative/number-chart-position/domain-padding/round-to-interval/round-to-interval-options';
-export * from './continuous-quantitative/number-chart-position/domain-padding/round-to-sig-fig/round-to-sig-fig';
-export * from './continuous-quantitative/number-chart-position/domain-padding/round-to-sig-fig/round-to-sig-fig-options';
-export * from './continuous-quantitative/number-chart-position/number-chart-position';
-export * from './continuous-quantitative/number-chart-position/number-chart-position-builder';
-export * from './continuous-quantitative/number-chart-position/number-chart-position-options';
-export * from './continuous-quantitative/number-dimension/number-dimension';
-export * from './continuous-quantitative/number-dimension/number-dimension-options';
-export * from './continuous-quantitative/number-visual-value/number-visual-value';
-export * from './continuous-quantitative/number-visual-value/number-visual-value-builder';
-export * from './continuous-quantitative/number-visual-value/number-visual-value-options';
-export * from './dimension';
-export * from './dimension-builder';
-export * from './dimension-options';
-export * from './ordinal/ordinal-chart-position/ordinal-chart-position';
-export * from './ordinal/ordinal-chart-position/ordinal-chart-position-builder';
-export * from './ordinal/ordinal-chart-position/ordinal-chart-position-options';
-export * from './ordinal/ordinal-visual-value/ordinal-visual-value';
-export * from './ordinal/ordinal-visual-value/ordinal-visual-value-builder';
-export * from './ordinal/ordinal-visual-value/ordinal-visual-value-options';

package/src/lib/data-dimensions/ordinal/ordinal-chart-position/ordinal-chart-position-builder.ts

@@ -1,122 +0,0 @@
-import { safeAssign } from '@mathstack/app-kit';
-import { DataValue } from '../../../core/types/values';
-import { DataDimensionBuilder } from '../../dimension-builder';
-import { OrdinalChartPositionDimension } from './ordinal-chart-position';
-
-const DEFAULT = {
-  _align: 0.5,
-  _paddingInner: 0.1,
-  _paddingOuter: 0.1,
-  _valueAccessor: (d, i) => i,
-};
-
-export class OrdinalChartPositionDimensionBuilder<
-  Datum,
-  Domain extends DataValue,
-> extends DataDimensionBuilder<Datum, Domain> {
-  private _align: number;
-  private _domain: Domain[];
-  private _paddingInner: number;
-  private _paddingOuter: number;
-
-  constructor() {
-    super();
-    safeAssign(this, DEFAULT);
-  }
-
-  /**
-   * OPTIONAL. Sets the alignment of the ordinal scale and is provided to [D3's align method](https://d3js.org/d3-scale/band#band_align)
-   *
-   * The value must be between 0 and 1.
-   *
-   * @default 0.5.
-   */
-  align(align: null): this;
-  align(align: number): this;
-  align(align: number): this {
-    if (align === null) {
-      this._align = DEFAULT._align;
-      return this;
-    }
-    this._align = align;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Sets an array of ordinal values that will be used to define the domain of the scale.
-   *
-   * If not provided, the domain will be determined by the data.
-   */
-  domain(domain: null): this;
-  domain(domain: Domain[]): this;
-  domain(domain: Domain[]): this {
-    if (domain === null) {
-      this._domain = undefined;
-      return this;
-    }
-    this._domain = domain;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Sets the inner padding of the ordinal scale and is provided to [D3's paddingInner method](https://d3js.org/d3-scale/band#band_paddingInner)
-   *
-   * Will have no effect if the scale is a point scale.
-   *
-   * The value must be between 0 and 1.
-   *
-   * @default 0.1.
-   */
-  paddingInner(paddingInner: null): this;
-  paddingInner(paddingInner: number): this;
-  paddingInner(paddingInner: number): this {
-    if (paddingInner === null) {
-      this._paddingInner = DEFAULT._paddingInner;
-      return this;
-    }
-    this._paddingInner = paddingInner;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Sets the outer padding of the ordinal scale and is provided to [D3's paddingOuter method](https://d3js.org/d3-scale/band#band_paddingOuter)
-   *
-   * The value must be between 0 and 1.
-   *
-   * @default 0.1.
-   */
-  paddingOuter(paddingOuter: null): this;
-  paddingOuter(paddingOuter: number): this;
-  paddingOuter(paddingOuter: number): this {
-    if (paddingOuter === null) {
-      this._paddingOuter = DEFAULT._paddingOuter;
-      return this;
-    }
-    this._paddingOuter = paddingOuter;
-    return this;
-  }
-
-  /**
-   * @internal This method is not intended to be used by consumers of this library.
-   *
-   * @param dimensionName A user-intelligible name for the dimension being built. Used for error messages. Should be title cased.
-   */
-  _build(
-    scaleType: 'band' | 'point',
-    dimensionName: string
-  ): OrdinalChartPositionDimension<Datum, Domain> {
-    this.validateDimension(dimensionName);
-    return new OrdinalChartPositionDimension(scaleType, {
-      align: this._align,
-      domain: this._domain,
-      formatFunction: this._formatFunction,
-      paddingInner: this._paddingInner,
-      paddingOuter: this._paddingOuter,
-      valueAccessor: this._valueAccessor,
-    });
-  }
-
-  private validateDimension(dimensionName: string): void {
-    this.validateValueAccessor(dimensionName);
-  }
-}

package/src/lib/data-dimensions/ordinal/ordinal-chart-position/ordinal-chart-position-options.ts

@@ -1,12 +0,0 @@
-import { DataValue } from '../../../core/types/values';
-import { DataDimensionOptions } from '../../dimension-options';
-
-export interface OrdinalChartPositionDimensionOptions<
-  Datum,
-  Domain extends DataValue,
-> extends DataDimensionOptions<Datum, Domain> {
-  align: number;
-  domain: Domain[];
-  paddingInner: number;
-  paddingOuter: number;
-}

package/src/lib/data-dimensions/ordinal/ordinal-chart-position/ordinal-chart-position.spec.ts

@@ -1,83 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { OrdinalChartPositionDimension } from './ordinal-chart-position';
-import { OrdinalChartPositionDimensionBuilder } from './ordinal-chart-position-builder';
-
-const data = [
-  { value: 1, category: 'a' },
-  { value: 2, category: 'b' },
-  { value: 3, category: 'c' },
-  { value: 4, category: 'a' },
-  { value: 5, category: 'b' },
-];
-
-describe('OrdinalChartPositionDimension', () => {
-  let dimension: OrdinalChartPositionDimension<
-    { value: number; category: string },
-    string
-  >;
-  beforeEach(() => {
-    dimension = new OrdinalChartPositionDimensionBuilder<
-      { value: number; category: string },
-      string
-    >()
-      .valueAccessor((d) => d.category)
-      ._build('band', 'Test');
-  });
-  describe('setPropertiesFromData', () => {
-    beforeEach(() => {
-      spyOn(dimension as any, 'setValues');
-      spyOn(dimension as any, 'setDomain');
-    });
-    it('calls setValues once', () => {
-      dimension.setPropertiesFromData(data, false);
-      expect((dimension as any).setValues).toHaveBeenCalledOnceWith(data);
-    });
-    it('calls initDomain once', () => {
-      dimension.setPropertiesFromData(data, false);
-      expect((dimension as any).setDomain).toHaveBeenCalledOnceWith(false);
-    });
-  });
-
-  describe('setDomain()', () => {
-    describe('when user specifies a domain', () => {
-      beforeEach(() => {
-        (dimension as any).domain = ['e', 'f', 'g', 'e'];
-      });
-      it('sets the domain to the unique values in user specified domain in the provided order, and ignores values from data', () => {
-        dimension.setPropertiesFromData(data, false);
-        expect((dimension as any)._calculatedDomain).toEqual(['e', 'f', 'g']);
-      });
-      describe('when reverseDomain is true', () => {
-        it('sets the domain to the unique values in user specified domain in reverse order, and ignores values from data', () => {
-          dimension.setPropertiesFromData(data, true);
-          expect((dimension as any)._calculatedDomain).toEqual(['g', 'f', 'e']);
-        });
-      });
-    });
-    describe('when user does not specify a domain', () => {
-      it('sets the domain to the unique values in the data in the provided order', () => {
-        dimension.setPropertiesFromData(data, false);
-        expect((dimension as any)._calculatedDomain).toEqual(['a', 'b', 'c']);
-      });
-      describe('when reverseDomain is true', () => {
-        it('sets the domain to the unique values in the data in reverse order', () => {
-          dimension.setPropertiesFromData(data, true);
-          expect((dimension as any)._calculatedDomain).toEqual(['c', 'b', 'a']);
-        });
-      });
-    });
-  });
-
-  describe('domainIncludes()', () => {
-    it('correctly sets internSetDomain and domainIncludes returns correct value', () => {
-      (dimension as any).domain = ['c', 'd', 'b', 'a', 'd'];
-      dimension.setPropertiesFromData(data, false);
-      expect(dimension.domainIncludes('a')).toEqual(true);
-    });
-    it('correctly sets internSetDomain and domainIncludes returns correct value - scenario 2', () => {
-      (dimension as any).domain = ['c', 'd', 'b', 'a', 'd'];
-      dimension.setPropertiesFromData(data, false);
-      expect(dimension.domainIncludes('z')).toEqual(false);
-    });
-  });
-});