@mathstack/viz 2.1.0 → 2.2.1

package/src/lib/core/utilities/values.ts

@@ -1,189 +0,0 @@
-import { format, utcFormat } from 'd3';
-import { ValueExtent } from '../types/values';
-import { isDate } from './type-guards';
-export type VicFormatSpecifier<Datum> = string | ((x: Datum) => string);
-
-/**
- * @internal
- */
-export class ValueUtilities {
-  static getValueRoundedToNSignificantFigures(
-    value: number,
-    sigFigures: number,
-    valueExtent: keyof typeof ValueExtent
-  ): number {
-    // If the value type is VicValueExtent.max, rounds up if value is > 0 and down if value is < 0
-    // If the value type is VicValueExtent.min, rounds down if value is > 0 and up if value is < 0
-    // ex: 1234 => 1235, -1234 => -1235
-    // SigDigits here means the first N non-zero as units holder values
-    // ex: 1234, sigFigures = 2, "1" and "2" are "significant"
-    // ex: 0.001234, sigFigures = 3, "1", "2", and "3" are "significant"
-    this.validateSigFigures(sigFigures);
-    let absRoundedValue;
-    if (Math.abs(value) < 1) {
-      absRoundedValue = this.getRoundedDecimalLessThanOne(
-        value,
-        sigFigures,
-        valueExtent
-      );
-    } else {
-      const absValueStr = Math.abs(value).toString();
-      const decimalIndex = absValueStr.indexOf('.');
-      let firstNDigits;
-      let numZeros = 0;
-      if (decimalIndex < sigFigures && decimalIndex > -1) {
-        firstNDigits = absValueStr.substring(0, sigFigures + 1);
-      } else {
-        firstNDigits = absValueStr.substring(0, sigFigures);
-        if (decimalIndex > -1) {
-          numZeros = decimalIndex - sigFigures;
-        } else {
-          numZeros = absValueStr.length - sigFigures;
-        }
-        numZeros = numZeros < 0 ? 0 : numZeros;
-      }
-      const offset = this.getRoundingOffset(value, valueExtent);
-      const lastSigDigit = Number(firstNDigits[firstNDigits.length - 1]);
-      // handle cases where the last rounded significant is 9 and the value is rounded up
-      if (offset === 1 && lastSigDigit === 9) {
-        firstNDigits = this.getNewValueForNine(
-          value,
-          firstNDigits.split(''),
-          absValueStr,
-          sigFigures,
-          valueExtent
-        );
-        if (firstNDigits[0] === '0') {
-          firstNDigits.unshift('1');
-        }
-        firstNDigits = firstNDigits.join('');
-      } else {
-        firstNDigits =
-          firstNDigits.substring(0, firstNDigits.length - 1) +
-          (lastSigDigit + offset).toString();
-      }
-      absRoundedValue = Number(firstNDigits + '0'.repeat(numZeros));
-    }
-    return value >= 0 || absRoundedValue === 0
-      ? absRoundedValue
-      : -absRoundedValue;
-  }
-
-  private static validateSigFigures(sigFigures: number): void {
-    if (sigFigures < 1) {
-      throw new Error('sigFigures must be greater than or equal to 1');
-    }
-  }
-
-  private static getRoundedDecimalLessThanOne(
-    value: number,
-    sigFigures: number,
-    valueExtent: keyof typeof ValueExtent
-  ): number {
-    const valueStr = Math.abs(value).toString();
-    let newValue = [];
-    let sigDigitsFound = 0;
-    for (let i = 0; i < valueStr.length; i++) {
-      const char = valueStr[i];
-      if (char === '.' || (char === '0' && sigDigitsFound === 0)) {
-        newValue.push(char);
-      } else {
-        ++sigDigitsFound;
-        if (sigDigitsFound <= sigFigures) {
-          let newDigit = '0';
-          if (sigDigitsFound === sigFigures || i === valueStr.length - 1) {
-            if (char === '9') {
-              newValue = this.getNewValueForNine(
-                value,
-                newValue,
-                valueStr,
-                i,
-                valueExtent
-              );
-            } else {
-              const offset = this.getRoundingOffset(value, valueExtent);
-              newDigit = `${Number(char) + offset}`;
-            }
-          } else if (sigDigitsFound < sigFigures) {
-            newDigit = char;
-          }
-          newValue.push(newDigit);
-        }
-      }
-    }
-    return parseFloat(newValue.join(''));
-  }
-
-  private static getNewValueForNine(
-    value: number,
-    newValue: string[],
-    valueStr: string,
-    i: number,
-    valueExtent: keyof typeof ValueExtent
-  ): string[] {
-    const prevChar = valueStr[i - 1];
-    if (prevChar === '9') {
-      newValue[i - 1] = '0';
-      newValue = this.getNewValueForNine(
-        value,
-        newValue,
-        valueStr,
-        i - 1,
-        valueExtent
-      );
-    } else if (prevChar === '.') {
-      newValue = this.getNewValueForNine(
-        value,
-        newValue,
-        valueStr,
-        i - 1,
-        valueExtent
-      );
-    } else {
-      const offset = this.getRoundingOffset(value, valueExtent);
-      newValue[i - 1] = `${Number(prevChar) + offset}`;
-    }
-    return newValue;
-  }
-
-  private static getRoundingOffset(
-    value: number,
-    valueExtent: keyof typeof ValueExtent
-  ): number {
-    return (value > 0 && valueExtent === ValueExtent.max) ||
-      (value < 0 && valueExtent === ValueExtent.min)
-      ? 1
-      : 0;
-  }
-
-  static getValueRoundedToInterval(
-    value: number,
-    interval: number,
-    valueExtent: keyof typeof ValueExtent
-  ): number {
-    if (interval === 0) {
-      return value;
-    }
-    const round = valueExtent === ValueExtent.max ? Math.ceil : Math.floor;
-    return round(value / interval) * interval;
-  }
-
-  static d3Format(value: Date | number, formatter: string): string {
-    return formatter
-      ? isDate(value)
-        ? utcFormat(formatter)(value)
-        : format(formatter)(value)
-      : value.toString();
-  }
-
-  static customFormat<Datum>(
-    value: Datum,
-    formatter: (x: Datum) => string
-  ): string {
-    return formatter ? formatter(value) : value.toString();
-  }
-
-  static formatForHtmlAttribute(value: string): string {
-    return value.replace(/\s/g, '-');
-  }
-}

package/src/lib/data-dimensions/continuous-quantitative/date-chart-position/date-chart-position-builder.ts

@@ -1,105 +0,0 @@
-import { safeAssign } from '@mathstack/app-kit';
-import { ScaleTime, scaleUtc } from 'd3';
-import { DataDimensionBuilder } from '../../dimension-builder';
-import { DateChartPositionDimension } from './date-chart-position';
-
-const DEFAULT = {
-  _scaleFn: scaleUtc,
-  _formatSpecifier: '%Y %m',
-};
-
-export class DateChartPositionDimensionBuilder<
-  Datum,
-> extends DataDimensionBuilder<Datum, Date> {
-  private _domain: [Date, Date];
-  private _formatSpecifier: string;
-  private _scaleFn: (
-    domain?: Iterable<Date>,
-    range?: Iterable<number>
-  ) => ScaleTime<number, number>;
-
-  constructor() {
-    super();
-    safeAssign(this, DEFAULT);
-  }
-
-  /**
-   * OPTIONAL. Sets the domain of the scale.
-   *
-   * If not provided, the domain will be determined by the data.
-   */
-  domain(domain: null): this;
-  domain(domain: [Date, Date]): this;
-  domain(domain: [Date, Date]): this {
-    if (domain === null) {
-      this._domain = undefined;
-      return this;
-    }
-    this._domain = domain;
-    return this;
-  }
-
-  /**
-   * OPTIONAL. Sets a format specifier that will be applied to values from this dimension for display purposes, for example, in a tooltip.
-   *
-   * This is a string that is passed to D3's timeFormat function.
-   *
-   * @default '%Y %m'
-   */
-  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. This is a D3 scale function that maps values from the dimension's domain to the dimension's range.
-   *
-   * @default d3.scaleUtc
-   */
-  scaleFn(scaleFn: null): this;
-  scaleFn(
-    scaleFn: (
-      domain?: Iterable<Date>,
-      range?: Iterable<number>
-    ) => ScaleTime<number, number>
-  ): this;
-  scaleFn(
-    scaleFn: (
-      domain?: Iterable<Date>,
-      range?: Iterable<number>
-    ) => ScaleTime<number, number>
-  ): this {
-    if (scaleFn === null) {
-      this._scaleFn = undefined;
-      return this;
-    }
-    this._scaleFn = scaleFn;
-    return this;
-  }
-
-  /**
-   * @internal This function is for internal use only and should never be called by the user.
-   *
-   * @param dimensionName A user-intelligible name for the dimension being built. Used for error messages. Should be title cased.
-   */
-  _build(dimensionName: string): DateChartPositionDimension<Datum> {
-    this.validateBuilder(dimensionName);
-    return new DateChartPositionDimension<Datum>({
-      domain: this._domain,
-      formatFunction: this._formatFunction,
-      formatSpecifier: this._formatSpecifier,
-      scaleFn: this._scaleFn,
-      valueAccessor: this._valueAccessor,
-    });
-  }
-
-  private validateBuilder(dimensionName): void {
-    this.validateValueAccessor(dimensionName);
-  }
-}

package/src/lib/data-dimensions/continuous-quantitative/date-chart-position/date-chart-position-options.ts

@@ -1,24 +0,0 @@
-import { ScaleTime } from 'd3';
-import { DataDimensionOptions } from '../../dimension-options';
-
-export interface DateChartPositionDimensionOptions<
-  Datum,
-> extends DataDimensionOptions<Datum, Date> {
-  /**
-   * An optional, user-provided range of values that is used as the domain of the dimension's scale.
-   *
-   * If not provided by the user, it remains undefined.
-   */
-  domain: [Date, Date];
-  /**
-   * A format specifier that will be applied to the value of this dimension for display purposes.
-   */
-  readonly formatSpecifier: string;
-  /**
-   * The scale function for the dimension. This is a D3 scale function that maps values from the dimension's domain to the dimension's range.
-   */
-  scaleFn: (
-    domain?: Iterable<Date>,
-    range?: Iterable<number>
-  ) => ScaleTime<number, number>;
-}

package/src/lib/data-dimensions/continuous-quantitative/date-chart-position/date-chart-position.spec.ts

@@ -1,66 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import { DateChartPositionDimension } from './date-chart-position';
-import { DateChartPositionDimensionBuilder } from './date-chart-position-builder';
-
-describe('DateChartPositionDimension', () => {
-  let dimension: DateChartPositionDimension<Date>;
-  beforeEach(() => {
-    dimension = new DateChartPositionDimensionBuilder<Date>()
-      .valueAccessor((d) => d)
-      ._build('Test');
-  });
-  describe('setPropertiesFromData', () => {
-    beforeEach(() => {
-      spyOn(dimension as any, 'setValues');
-      spyOn(dimension as any, 'setDomain');
-    });
-    it('calls setValues once', () => {
-      dimension.setPropertiesFromData([
-        new Date(2000, 2),
-        new Date(2001, 2),
-        new Date(2002, 2),
-      ]);
-      expect((dimension as any).setValues).toHaveBeenCalledOnceWith([
-        new Date(2000, 2),
-        new Date(2001, 2),
-        new Date(2002, 2),
-      ]);
-    });
-    it('calls setDomain once', () => {
-      dimension.setPropertiesFromData([new Date(), new Date(), new Date()]);
-      expect((dimension as any).setDomain).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  describe('setDomain()', () => {
-    describe('when user specifies a domain', () => {
-      it('sets the domain to an array of unique values in the user-provided domain', () => {
-        (dimension as any).domain = [
-          new Date('2020-01-03'),
-          new Date('2020-01-01'),
-        ];
-        dimension.setPropertiesFromData([
-          new Date('2020-02-01'),
-          new Date('2020-02-02'),
-        ]);
-        expect((dimension as any).calculatedDomain).toEqual([
-          new Date('2020-01-03'),
-          new Date('2020-01-01'),
-        ]);
-      });
-    });
-    describe('when user does not specify a domain', () => {
-      it('sets the domain to the unique values from the data', () => {
-        dimension.setPropertiesFromData([
-          new Date('2020-01-01'),
-          new Date('2020-01-01'),
-          new Date('2020-01-03'),
-        ]);
-        expect((dimension as any).calculatedDomain).toEqual([
-          new Date('2020-01-01'),
-          new Date('2020-01-03'),
-        ]);
-      });
-    });
-  });
-});

package/src/lib/data-dimensions/continuous-quantitative/date-chart-position/date-chart-position.ts

@@ -1,72 +0,0 @@
-import { safeAssign } from '@mathstack/app-kit';
-import { ScaleTime, max, min } from 'd3';
-import { isDate } from '../../../core/utilities/type-guards';
-import { DataDimension } from '../../dimension';
-import { DateChartPositionDimensionOptions } from './date-chart-position-options';
-
-/**
- * A dimension that transforms Date values into a position on a chart.
- *
- * This dimension is used for the positional dimensions of a chart, such as x and y. The underlying scale will always be a [D3 time scale](https://d3js.org/d3-scale/time). The range of the scale will be a dimension from the chart.
- *
- * The generic is the type of the data that will be passed to the dimension.
- *
- * TESTABLE FUNCTIONALITY
- *
- * - It extracts values for the dimension from data.
- *   - tested in: lines.cy.ts
- * - It sets the domain of the dimension.
- *   - tested in: lines.cy.ts
- * - It creates and returns a scale from a range.
- *   - tested in: lines.cy.ts
- * - It checks if a value is in valid.
- *   - tested in: lines.cy.ts
- * - The domain will be unique values from the user-provided domain if the user provides a domain.
- *   - tested in: date-chart-position.spec.ts
- * - The domain will be unique values from the data if no custom domain is given by the user.
- *   - tested in: date-chart-position.spec.ts
- * - The domain can be set in reverse order.
- *   - tested in: date-chart-position.spec.ts
- */
-
-export class DateChartPositionDimension<Datum>
-  extends DataDimension<Datum, Date>
-  implements DateChartPositionDimensionOptions<Datum>
-{
-  private calculatedDomain: [Date, Date];
-  readonly domain: [Date, Date];
-  readonly formatSpecifier: string;
-  scaleFn: (
-    domain?: Iterable<Date>,
-    range?: Iterable<number>
-  ) => ScaleTime<number, number>;
-
-  constructor(options: DateChartPositionDimensionOptions<Datum>) {
-    super('date');
-    safeAssign(this, options);
-  }
-
-  setPropertiesFromData(data: Datum[]): void {
-    this.setValues(data);
-    this.setDomain();
-  }
-
-  protected setDomain() {
-    const extents: [Date, Date] =
-      this.domain === undefined
-        ? [min(this.values), max(this.values)]
-        : this.domain;
-    this.calculatedDomain = extents;
-  }
-
-  getScaleFromRange(range: [number, number]): ScaleTime<number, number> {
-    return this.scaleFn().domain(this.calculatedDomain).range(range);
-  }
-
-  // returns false if data is undefined or null of not a Date
-  // for some charts this may be fine
-  // original intended use case: d3Line can only handle defined values
-  isValidValue(x: unknown): boolean {
-    return isDate(x);
-  }
-}

package/src/lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/concrete-domain-padding.ts

@@ -1,10 +0,0 @@
-import { PercentOverDomainPadding } from './percent-over/percent-over';
-import { PixelDomainPadding } from './pixel/pixel';
-import { RoundUpToIntervalDomainPadding } from './round-to-interval/round-to-interval';
-import { RoundUpToSigFigDomainPadding } from './round-to-sig-fig/round-to-sig-fig';
-
-export type ConcreteDomainPadding =
-  | RoundUpToSigFigDomainPadding
-  | RoundUpToIntervalDomainPadding
-  | PercentOverDomainPadding
-  | PixelDomainPadding;

package/src/lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/domain-padding.ts

@@ -1,76 +0,0 @@
-import { ScaleContinuousNumeric } from 'd3';
-import { ValueExtent } from '../../../../core/types/values';
-
-export enum DomainPaddingType {
-  roundUp = 'roundUp',
-  roundInterval = 'roundInterval',
-  percentOver = 'percentOver',
-  numPixels = 'numPixels',
-}
-
-export interface PaddedDomainArguments {
-  value?: number;
-  valueType: keyof typeof ValueExtent;
-  scaleFn?: (
-    domain?: Iterable<number>,
-    range?: Iterable<number>
-  ) => ScaleContinuousNumeric<number, number>;
-  unpaddedDomain?: [number, number];
-  dimensionRange?: [number, number];
-}
-
-export abstract class DomainPadding {
-  abstract getPaddedValue(args: PaddedDomainArguments): number;
-
-  getPaddedDomain(
-    unpaddedDomain: [number, number],
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    scaleFn: any,
-    dimensionRange?: [number, number]
-  ): [number, number] {
-    const domainMinArgs: PaddedDomainArguments = {
-      value: unpaddedDomain[0],
-      valueType: 'min',
-      scaleFn,
-      unpaddedDomain,
-      dimensionRange: dimensionRange,
-    };
-    const domainMaxArgs: PaddedDomainArguments = {
-      value: unpaddedDomain[1],
-      valueType: 'max',
-      scaleFn,
-      unpaddedDomain,
-      dimensionRange: dimensionRange,
-    };
-    let domainMin: number;
-    let domainMax: number;
-    if (unpaddedDomain[0] >= 0 && unpaddedDomain[1] >= 0) {
-      domainMin = unpaddedDomain[0];
-      domainMax = this.getPaddedValue(domainMaxArgs);
-    } else if (unpaddedDomain[0] <= 0 && unpaddedDomain[1] <= 0) {
-      domainMin = this.getPaddedValue(domainMinArgs);
-      domainMax = unpaddedDomain[1];
-    } else if (unpaddedDomain[0] < 0 && unpaddedDomain[1] > 0) {
-      [domainMin, domainMax] = this.getPaddedDomainForPositiveAndNegativeValues(
-        domainMinArgs,
-        domainMaxArgs,
-        unpaddedDomain,
-        scaleFn,
-        dimensionRange
-      );
-    }
-    return [domainMin, domainMax];
-  }
-
-  protected getPaddedDomainForPositiveAndNegativeValues(
-    domainMinArgs: PaddedDomainArguments,
-    domainMaxArgs: PaddedDomainArguments,
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
-    ...args: any
-  ): [number, number] {
-    return [
-      this.getPaddedValue(domainMinArgs),
-      this.getPaddedValue(domainMaxArgs),
-    ];
-  }
-}

package/src/lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/domain-test-utility.ts

@@ -1,130 +0,0 @@
-import { expect } from 'local-cypress';
-
-type Assert = 'isEqual' | 'isAbove' | 'isBelow' | 'isCloseTo';
-
-/**
- * ValidateValue class
- * @class
- * @classdesc ValidateValue class is used to validate the value of a domain
- * @example
- * const validateValue = new ValidateValue({ value: 10 });
- * validateValue.validate(10);
- * @example
- * const validateValue = new ValidateValue({ value: 10, assertion: 'equal' });
- * validateValue.validate(10);
- * @example
- * const validateValue = new ValidateValue({ value: 10, assertion: 'above' });
- * validateValue.validate(11);
- * @example
- * const validateValue = new ValidateValue({ value: 10, assertion: 'below' });
- * validateValue.validate(9);
- * @example
- * const validateValue = new ValidateValue({ value: 10, assertion: 'closeTo', tolerance: 0.0001 });
- * validateValue.validate(10.00001);
- */
-class ValidateValue {
-  private value: number;
-  private assert: Assert;
-  private tolerance: number;
-
-  constructor(options: { value: number; assert?: Assert; tolerance?: number }) {
-    this.value = options.value;
-    this.assert = options.assert;
-    this.tolerance = options.tolerance;
-  }
-
-  validate(expected: number): void {
-    if (this.assert === undefined) {
-      this.assert = 'isEqual';
-    }
-    if (this.tolerance === undefined && this.assert === 'isCloseTo') {
-      this.tolerance = 0.0001;
-    }
-    switch (this.assert) {
-      case 'isEqual':
-        expect(expected).to.equal(this.value);
-        break;
-      case 'isAbove':
-        expect(expected).to.be.above(this.value);
-        break;
-      case 'isBelow':
-        expect(expected).to.be.below(this.value);
-        break;
-      case 'isCloseTo':
-        expect(expected).to.be.closeTo(this.value, this.tolerance);
-        break;
-    }
-  }
-}
-
-/**
- * ValidateDomain class
- * @class
- * @classdesc ValidateDomain class is used to validate the domain of a chart
- * @example
- * const validateDomain = new ValidateDomain();
- * validateDomain.min(0).max(10);
- * validateDomain.validate();
- * @example
- * const validateDomain = new ValidateDomain();
- * validateDomain.min(0, { assertion: 'above' }).max(10, { assertion: 'below' });
- * validateDomain.validate();
- * @example
- * const validateDomain = new ValidateDomain();
- * validateDomain.min(0, { assertion: 'closeTo', tolerance: 0.0001 }).max(10, { assertion: 'closeTo', tolerance: 0.0001 });
- */
-class ValidateDomain {
-  private min?: ValidateValue;
-  private max?: ValidateValue;
-  expected: [number, number];
-
-  constructor(expected: [number, number]) {
-    this.expected = expected;
-  }
-
-  minToBe(
-    min: number,
-    options?: {
-      assert: Assert;
-      tolerance?: number;
-    }
-  ): ValidateDomain {
-    this.min = new ValidateValue({ value: min, ...options });
-    return this;
-  }
-
-  maxToBe(
-    max: number,
-    options?: {
-      assert: Assert;
-      tolerance?: number;
-    }
-  ): ValidateDomain {
-    this.max = new ValidateValue({ value: max, ...options });
-    return this;
-  }
-
-  validate(): void {
-    if (this.min) {
-      this.min.validate(this.expected[0]);
-    }
-    if (this.max) {
-      this.max.validate(this.expected[1]);
-    }
-  }
-}
-
-/**
- * expectDomain function
- * @function
- * @functiondesc expectDomain function is used to create a new instance of ValidateDomain
- * @example
- * expectDomain().min(0).max(10).validate();
- * @example
- * expectDomain().min(0, { assertion: 'above' }).max(10, { assertion: 'below' }).validate();
- * @example
- * expectDomain().min(0, { assertion: 'closeTo', tolerance: 0.0001 }).max(10, { assertion: 'closeTo', tolerance: 0.0001 }).validate();
- */
-export function expectDomain(values: [number, number]): ValidateDomain {
-  return new ValidateDomain(values);
-}

package/src/lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/percent-over/percent-over-options.ts

@@ -1,3 +0,0 @@
-export interface PercentOverDomainPaddingOptions {
-  percentOver: number;
-}