@mathstack/viz 1.1.5 → 2.1.0

package/src/lib/charts/chart/config/chart-builder.ts

@@ -0,0 +1,194 @@
+import { Injectable } from '@angular/core';
+import { safeAssign } from '@mathstack/app-kit';
+import { ElementSpacing } from '../../../core/types/layout';
+import { ChartConfig } from './chart-config';
+
+export type ScalingStrategy = 'fixed' | 'responsive-width' | 'viewbox';
+
+export const CHART_SIZE = {
+  scaledWidth: 800,
+  viewBoxWidth: 800,
+  minWidth: 320,
+  aspectRatio: 16 / 9,
+};
+
+const DEFAULT = {
+  _fixedHeight: false,
+  _margin: { top: 36, right: 36, bottom: 36, left: 36 },
+  _scalingStrategy: 'responsive-width' as ScalingStrategy,
+  _transitionDuration: 250,
+};
+
+/**
+ * Builds a configuration object for a ChartComponent.
+ *
+ * Must be added to a providers array in or above the component that consumes it if it is injected via the constructor. (e.g. `providers: [VicChartConfigBuilder]` in the component decorator)
+ *
+ */
+@Injectable()
+export class VicChartConfigBuilder {
+  private _aspectRatio?: number;
+  private _fixedHeight: boolean;
+  private _height: number;
+  private _margin: ElementSpacing;
+  private _minWidth: number;
+  private _scalingStrategy: ScalingStrategy;
+  private _transitionDuration: number;
+  private _width: number;
+
+  constructor() {
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL. Explicitly sets the aspect ratio to use when scalingStrategy is 'responsive-width' and fixedHeight is false, or when scalingStrategy is 'viewbox'.
+   *
+   * @param value - The aspect ratio (width / height) to use. If not called or called with null, a default value of 16/9 will be used. If maxWidth and maxHeight are set, aspect ratio will be derived from those values.
+   */
+  aspectRatio(value: number): this {
+    this._aspectRatio = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. If set to true and used with 'responsive-width' scaling strategy, height will be fixed and not derived from aspect ratio.
+   *
+   * Has no effect if scaling strategy is 'fixed' or 'viewbox'.
+   */
+  fixedHeight(value: boolean): this {
+    this._fixedHeight = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Determines the margin that will be established between the edges of the svg and the svg's contents, in px.
+   *
+   * @param value - The margin that will be established between the edges of the svg and the svg's contents, in px. If called with null, a default value of `{ top: 36, right: 36, bottom: 36, left: 36 }` will be used.
+   */
+  margin(
+    value: {
+      top: number;
+      right: number;
+      bottom: number;
+      left: number;
+    } | null
+  ): this {
+    if (value === null) {
+      value = DEFAULT._margin;
+      return this;
+    }
+    this._margin = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. If scaling strategy is 'responsive-width' or 'viewbox', determines the maximum height of the chart. This will override any provided aspect ratio.
+   *
+   * If scaling strategy is 'fixed', sets the fixed height of the chart.
+   *
+   * @param value - The maximum height of the chart, in px. If chart size is static, the fixed height of the chart. If not called or called with `null`, chart height will be set via aspect ratio.
+   */
+  maxHeight(value: number | null): this {
+    this._height = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. If scaling strategy is responsive-width or viewbox, sets the maximum width of the chart. In this case, this value is also used to determine the aspect ratio of the chart which will be maintained on resizing.
+   *
+   * If scaling strategy is fixed, sets the fixed width of the chart.
+   *
+   * @param value - The maximum width of the chart, in px. If chart size is static, the fixed width of the chart.
+   *
+   * If not called or called with `null`, a default value of 800 will be used.
+   */
+  maxWidth(value: number | null): this {
+    this._width = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. If scaling strategy is responsive-width or viewbox, sets the minimum width of the chart. Has no effect if scaling strategy is fixed.
+   *
+   * @param value - The minimum width of the chart, in px. If not called or called with `null`, a default value of 320 will be used.
+   */
+  minWidth(value: number | null): this {
+    this._minWidth = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. Determines how the chart scales in response to container or window size changes.
+   *
+   * Default value, if not called, is 'responsive-width'.
+   *
+   * @param value - One of:
+   * - 'fixed': Chart dimensions remain constant. Width and height are fixed. Dimensions can be set with maxWidth and maxHeight.
+   * - 'responsive-width': Chart width responds to container; height is derived via aspect ratio, unless fixedHeight is true.
+   * - 'viewbox': Chart is scaled entirely via SVG viewBox. All resizing behavior is controlled through CSS.
+   */
+  scalingStrategy(value: ScalingStrategy): this {
+    this._scalingStrategy = value;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. A time duration for all transitions in the chart, in ms.
+   *
+   * @@param value - The time duration for all transitions in the chart, in ms. If not called or called with null, a default value of 250 will be used.
+   */
+  transitionDuration(value: number | null): this {
+    if (value === null) {
+      value = DEFAULT._transitionDuration;
+      return this;
+    }
+    this._transitionDuration = value;
+    return this;
+  }
+
+  getConfig(): ChartConfig {
+    this.validateBuilder();
+
+    return new ChartConfig({
+      aspectRatio: this._aspectRatio,
+      height: this._height,
+      isFixedHeight: this._fixedHeight,
+      margin: this._margin,
+      minWidth: this._minWidth,
+      scalingStrategy: this._scalingStrategy,
+      transitionDuration: this._transitionDuration,
+      width: this._width,
+      viewBoxX: CHART_SIZE.viewBoxWidth,
+      viewBoxY:
+        CHART_SIZE.viewBoxWidth / (this._aspectRatio ?? CHART_SIZE.aspectRatio),
+    });
+  }
+
+  private validateBuilder(): void {
+    if (this._width === undefined || this._width === null) {
+      this._width =
+        this._scalingStrategy === 'viewbox' ? null : CHART_SIZE.scaledWidth;
+    }
+    if (this._height === undefined || this._height === null) {
+      this._height =
+        this._scalingStrategy === 'viewbox'
+          ? null
+          : this._width / (this._aspectRatio ?? CHART_SIZE.aspectRatio);
+    }
+    if (this._minWidth === undefined || this._minWidth === null) {
+      this._minWidth =
+        this._scalingStrategy === 'viewbox' ? null : CHART_SIZE.minWidth;
+    }
+    if (this._scalingStrategy !== 'viewbox' && this._minWidth > this._width) {
+      const [oldMin, oldWidth] = [this._minWidth, this._width];
+      this._minWidth = oldWidth;
+      this._width = oldMin;
+      console.warn(
+        `[vic-chart] The configured minWidth (${oldMin}px) cannot be larger than the configured width (${oldWidth}px). The values have been swapped.`
+      );
+    }
+    if (this._scalingStrategy === 'responsive-width' && !this._fixedHeight) {
+      this._aspectRatio = this._width / this._height;
+    }
+  }
+}

package/src/lib/charts/chart/config/chart-config.ts

@@ -0,0 +1,21 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { ElementSpacing } from '../../../core/types/layout';
+import { ScalingStrategy } from './chart-builder';
+import { ChartOptions } from './chart-options';
+
+export class ChartConfig implements ChartOptions {
+  aspectRatio?: number;
+  height: number | null;
+  isFixedHeight: boolean;
+  margin: ElementSpacing;
+  minWidth: number | null;
+  scalingStrategy: ScalingStrategy;
+  transitionDuration: number;
+  width: number | null;
+  viewBoxX: number;
+  viewBoxY: number;
+
+  constructor(config: ChartConfig) {
+    safeAssign(this, config);
+  }
+}

package/src/lib/charts/chart/config/chart-options.ts

@@ -0,0 +1,11 @@
+import { ElementSpacing } from '../../../core/types/layout';
+import { ScalingStrategy } from './chart-builder';
+
+export interface ChartOptions {
+  aspectRatio?: number;
+  height: number;
+  margin: ElementSpacing;
+  scalingStrategy: ScalingStrategy;
+  transitionDuration: number;
+  width: number;
+}

package/src/lib/charts/chart.module.ts

@@ -0,0 +1,10 @@
+import { NgModule } from '@angular/core';
+import { ChartComponent } from './chart/chart.component';
+import { MapChartComponent } from './map-chart/map-chart.component';
+import { XyChartComponent } from './xy-chart/xy-chart.component';
+
+@NgModule({
+  imports: [ChartComponent, XyChartComponent, MapChartComponent],
+  exports: [ChartComponent, XyChartComponent, MapChartComponent],
+})
+export class VicChartModule {}

package/{lib/charts/index.d.ts → src/lib/charts/index.ts}

@@ -1,8 +1,9 @@
-export * from './chart.module';
-export * from './chart/chart';
-export * from './chart/chart.component';
-export * from './chart/chart.token';
-export * from './chart/config/chart-builder';
-export * from './chart/config/chart-config';
-export * from './map-chart/map-chart.component';
-export * from './xy-chart/xy-chart.component';
+export * from './chart.module';
+export * from './chart/chart';
+export * from './chart/chart.component';
+export * from './chart/chart.token';
+export * from './chart/config/chart-builder';
+export * from './chart/config/chart-config';
+export * from './chart/config/chart-options';
+export * from './map-chart/map-chart.component';
+export * from './xy-chart/xy-chart.component';

package/src/lib/charts/map-chart/map-chart.component.spec.ts

@@ -0,0 +1,35 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { MapChartComponent } from './map-chart.component';
+
+describe('MapChartComponent', () => {
+  let component: MapChartComponent<any>;
+  let fixture: ComponentFixture<MapChartComponent<any>>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [MapChartComponent],
+    }).compileComponents();
+  });
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(MapChartComponent);
+    component = fixture.componentInstance;
+  });
+
+  describe('updateAttributeProperties', () => {
+    it('calls next on updateAttributeProperties', () => {
+      spyOn((component as any).attributeProperties, 'next');
+      component.updateAttributeProperties({
+        scale: 'test scale',
+        config: 'test config',
+      } as any);
+      expect(
+        (component as any).attributeProperties.next
+      ).toHaveBeenCalledOnceWith({
+        scale: 'test scale',
+        config: 'test config',
+      });
+    });
+  });
+});

package/src/lib/charts/map-chart/map-chart.component.ts

@@ -0,0 +1,61 @@
+import { CommonModule } from '@angular/common';
+import { Component, inject, NgZone } from '@angular/core';
+import { BehaviorSubject } from 'rxjs';
+import { VicAttributeDataDimensionConfig } from '../../geographies/config/layers/attribute-data-layer/dimensions/attribute-data-bin-types';
+import { Chart } from '../chart/chart';
+import { ChartComponent } from '../chart/chart.component';
+import { CHART } from '../chart/chart.token';
+
+/**
+ * A `Chart` component to be used with a `Geographies` `PrimaryMarks` component.
+ *
+ * This component adds an attribute data scale and config to the base `ChartComponent` that can
+ *  be used by any components projected into the chart.
+ *
+ * Components that may use these scales include the `Geographies` component
+ *  and the `MapLegend` component.
+ *
+ * <p class="comment-slots">Content projection slots</p>
+ *
+ * `html-elements-before`: Elements that will be projected before the chart's scaled div
+ *  and scaled svg element in the DOM. USeful for adding elements that require access to chart scales.
+ *
+ * `svg-defs`: Used to create any required defs for the chart's svg element. For example, patterns or gradients.
+ *
+ * `svg-elements`: Used for all elements that should be children of the chart's scaled svg element.
+ *
+ * `html-elements-after`: Elements that will be projected after the chart's scaled div
+ *  and scaled svg element in the DOM. USeful for adding elements that require access to chart scales.
+ */
+@Component({
+  selector: 'vic-map-chart',
+  templateUrl: '../chart/chart.component.html',
+  styleUrls: ['../chart/chart.component.scss'],
+  providers: [{ provide: CHART, useExisting: ChartComponent }],
+  host: {
+    class: 'vic-map-chart',
+  },
+  imports: [CommonModule],
+})
+export class MapChartComponent<Datum> extends ChartComponent implements Chart {
+  private attributeProperties: BehaviorSubject<{
+    config: VicAttributeDataDimensionConfig<Datum>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    scale: any;
+  }> = new BehaviorSubject({ config: undefined, scale: undefined });
+  attributeProperties$ = this.attributeProperties.asObservable();
+  protected zone = inject(NgZone);
+
+  updateAttributeProperties(properties: {
+    config: VicAttributeDataDimensionConfig<Datum>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    scale: any;
+  }): void {
+    this.zone.run(() => {
+      this.attributeProperties.next({
+        config: properties.config,
+        scale: properties.scale,
+      });
+    });
+  }
+}

package/src/lib/charts/xy-chart/xy-chart.component.spec.ts

@@ -0,0 +1,34 @@
+/* eslint-disable  @typescript-eslint/no-explicit-any */
+import { ComponentFixture, TestBed } from '@angular/core/testing';
+import { XyChartComponent } from './xy-chart.component';
+
+describe('XyChartComponent', () => {
+  let component: XyChartComponent;
+  let fixture: ComponentFixture<XyChartComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [XyChartComponent],
+    }).compileComponents();
+  });
+
+  beforeEach(() => {
+    fixture = TestBed.createComponent(XyChartComponent);
+    component = fixture.componentInstance;
+  });
+
+  describe('updateScales', () => {
+    beforeEach(() => {
+      (component as any).scales.next({ x: 1, y: 2, categorical: 3 } as any);
+    });
+    it('calls next on scales', () => {
+      spyOn((component as any).scales, 'next');
+      component.updateScales({ x: 4 } as any);
+      expect((component as any).scales.next).toHaveBeenCalledOnceWith({
+        x: 4,
+        y: 2,
+        categorical: 3,
+      } as any);
+    });
+  });
+});

package/src/lib/charts/xy-chart/xy-chart.component.ts

@@ -0,0 +1,65 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { CommonModule } from '@angular/common';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  inject,
+  NgZone,
+  OnInit,
+} from '@angular/core';
+import { BehaviorSubject, filter } from 'rxjs';
+import { GenericScale } from '../../core';
+import { Chart } from '../chart/chart';
+import { ChartComponent } from '../chart/chart.component';
+import { CHART } from '../chart/chart.token';
+
+export enum XyContentScale {
+  x = 'x',
+  y = 'y',
+}
+
+export interface XyChartScales {
+  [XyContentScale.x]: GenericScale<any, any>;
+  [XyContentScale.y]: GenericScale<any, any>;
+  useTransition: boolean;
+}
+/**
+ * A `Chart` component to be used with `PrimaryMarks` components that have X and Y axes, such as `Bars` and `Lines`.
+ *
+ * This component adds x, y, and categorical scales to the base `ChartComponent` that can
+ *  be used by any components projected into the chart.
+ *
+ * <p class="comment-slots">Content projection slots</p>
+ *
+ * `html-elements-before`: Elements that will be projected before the chart's scaled div
+ *  and scaled svg element in the DOM. USeful for adding elements that require access to chart scales.
+ *
+ * `svg-defs`: Used to create any required defs for the chart's svg element. For example, patterns or gradients.
+ *
+ * `svg-elements`: Used for all elements that should be children of the chart's scaled svg element.
+ *
+ * `html-elements-after`: Elements that will be projected after the chart's scaled div
+ *  and scaled svg element in the DOM. USeful for adding elements that require access to chart scales.
+ */
+@Component({
+  selector: 'vic-xy-chart',
+  templateUrl: '../chart/chart.component.html',
+  styleUrls: ['../chart/chart.component.scss'],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  providers: [{ provide: CHART, useExisting: ChartComponent }],
+  host: {
+    class: 'vic-xy-chart',
+  },
+  imports: [CommonModule],
+})
+export class XyChartComponent extends ChartComponent implements Chart, OnInit {
+  private scales: BehaviorSubject<XyChartScales> = new BehaviorSubject(null);
+  scales$ = this.scales.asObservable().pipe(filter((scales) => !!scales));
+  protected zone = inject(NgZone);
+
+  updateScales(scales: Partial<XyChartScales>): void {
+    this.zone.run(() => {
+      this.scales.next({ ...this.scales.value, ...scales });
+    });
+  }
+}

package/src/lib/core/common-behaviors/constructor.ts

@@ -0,0 +1,7 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type Constructor<T = object> = new (...args: any[]) => T;
+
+export type AbstractConstructor<T = object> = abstract new (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ...args: any[]
+) => T;

package/src/lib/core/index.ts

@@ -0,0 +1,11 @@
+export * from './common-behaviors/constructor';
+export * from './pipes/resize-chart-height.pipe';
+export * from './types/layout';
+export * from './types/scale';
+export * from './types/utility';
+export * from './types/values';
+export * from './utilities/colors';
+export * from './utilities/fill-utilities';
+export * from './utilities/type-guards';
+export * from './utilities/value-format';
+export * from './utilities/values';

package/src/lib/core/pipes/resize-chart-height.pipe.spec.ts

@@ -0,0 +1,23 @@
+import { ResizeChartHeightPipe } from './resize-chart-height.pipe';
+
+describe('ResizeChartHeightPipe', () => {
+  let pipe: ResizeChartHeightPipe;
+
+  beforeEach(() => {
+    pipe = new ResizeChartHeightPipe();
+  });
+
+  it('returns divWidth if divWidth is not a number', () => {
+    expect(pipe.transform('divWidth', 100, 100)).toBe('divWidth');
+  });
+
+  it('returns the correct value if divWidth is less than maxWidth', () => {
+    const result = pipe.transform(100, 300, 200);
+    expect(result).toEqual(150);
+  });
+
+  it('returns maxHeight if divWidth is greater than or equal to maxWidth', () => {
+    const result = pipe.transform(400, 300, 200);
+    expect(result).toEqual(300);
+  });
+});

package/src/lib/core/pipes/resize-chart-height.pipe.ts

@@ -0,0 +1,20 @@
+import { Pipe, PipeTransform } from '@angular/core';
+/**
+ * @internal
+ */
+@Pipe({
+  name: 'resizeChartHeight',
+})
+export class ResizeChartHeightPipe implements PipeTransform {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  transform(divWidth: any, maxHeight: number, maxWidth: number): any {
+    if (typeof divWidth !== 'number') {
+      return divWidth;
+    } else if (divWidth < maxWidth) {
+      const aspectRatio = maxWidth / maxHeight;
+      return divWidth / aspectRatio;
+    } else {
+      return maxHeight;
+    }
+  }
+}

package/src/lib/core/styles/_spacing.scss

@@ -0,0 +1,4 @@
+@function grid($number) {
+  $grid: 0.25rem;
+  @return $number * $grid;
+}

package/src/lib/core/types/layout.ts

@@ -0,0 +1,28 @@
+export enum Orientation {
+  horizontal = 'horizontal',
+  vertical = 'vertical',
+}
+
+export enum Side {
+  top = 'top',
+  right = 'right',
+  bottom = 'bottom',
+  left = 'left',
+}
+
+export interface ElementSpacing {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export interface Dimensions {
+  width: number;
+  height: number;
+}
+
+export interface Position {
+  x: number;
+  y: number;
+}

package/src/lib/core/types/scale.ts

@@ -0,0 +1,6 @@
+export interface GenericScale<Domain, Range> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (...args: any): Range;
+  domain?(): [Domain, Domain];
+  range?(): [Range, Range];
+}

package/src/lib/core/types/utility.ts

@@ -0,0 +1,11 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ToArray<T> = T extends any[] ? T : T[];
+
+// https://stackoverflow.com/questions/49242232/constraining-type-in-typescript-generic-to-be-one-of-several-types
+export type OneOf<
+  T,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  V extends any[],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  NK extends keyof V = Exclude<keyof V, keyof any[]>,
+> = { [K in NK]: T extends V[K] ? V[K] : never }[NK];

package/{lib/core/types/values.d.ts → src/lib/core/types/values.ts}

@@ -1,7 +1,10 @@
-export declare enum ValueExtent {
-    max = "max",
-    min = "min"
-}
-export type ContinuousValue = number | Date;
-export type DataValue = number | string | Date;
-export type VisualValue = number | string;
+export enum ValueExtent {
+  max = 'max',
+  min = 'min',
+}
+
+export type ContinuousValue = number | Date;
+
+export type DataValue = number | string | Date;
+
+export type VisualValue = number | string;

package/src/lib/core/utilities/colors.spec.ts

@@ -0,0 +1,57 @@
+import { ColorUtilities } from './colors';
+
+describe('getContrastRatio', () => {
+  // https://webaim.org/resources/contrastchecker/
+  it('returns the same value as WebAIM checker given value - default WebAIM values', () => {
+    expect(
+      Math.floor(ColorUtilities.getContrastRatio('#0000FF', '#FFFFFF') * 100) /
+        100
+    ).toEqual(8.59);
+  });
+  it('returns the same value as WebAIM checker given value - green and red', () => {
+    expect(
+      Math.floor(ColorUtilities.getContrastRatio('#04FA00', '#FF0036') * 100) /
+        100
+    ).toEqual(2.76);
+  });
+  it('works with rgb values', () => {
+    expect(
+      Math.floor(
+        ColorUtilities.getContrastRatio(
+          'rgb(0, 0, 255)',
+          'rgb(255, 255, 255)'
+        ) * 100
+      ) / 100
+    ).toEqual(8.59);
+  });
+  it('works with named colors', () => {
+    expect(
+      Math.floor(ColorUtilities.getContrastRatio('blue', 'white') * 100) / 100
+    ).toEqual(8.59);
+  });
+  it('works with hsl values', () => {
+    expect(
+      Math.floor(
+        ColorUtilities.getContrastRatio(
+          'hsl(240, 100%, 50%)',
+          'hsl(0, 0%, 100%)'
+        ) * 100
+      ) / 100
+    ).toEqual(8.59);
+  });
+  it('works with mixed values - one named color and one hex', () => {
+    expect(
+      Math.floor(ColorUtilities.getContrastRatio('blue', '#FFFFFF') * 100) / 100
+    ).toEqual(8.59);
+  });
+  it('works with mixed values - one hsl color and one rgb', () => {
+    expect(
+      Math.floor(
+        ColorUtilities.getContrastRatio(
+          'hsl(240, 100%, 50%)',
+          'rgb(255, 255, 255)'
+        ) * 100
+      ) / 100
+    ).toEqual(8.59);
+  });
+});