@mathstack/viz 1.1.5 → 2.1.0

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

@@ -0,0 +1,189 @@
+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

@@ -0,0 +1,105 @@
+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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,66 @@
+/* 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

@@ -0,0 +1,72 @@
+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/{lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/concrete-domain-padding.d.ts → src/lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/concrete-domain-padding.ts}

@@ -1,5 +1,10 @@
-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;
+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

@@ -0,0 +1,76 @@
+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

@@ -0,0 +1,130 @@
+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/{lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/percent-over/percent-over-options.d.ts → src/lib/data-dimensions/continuous-quantitative/number-chart-position/domain-padding/percent-over/percent-over-options.ts}

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