@mathstack/viz 1.1.4 → 2.0.3

package/src/lib/geographies/config/layers/geojson-properties-layer/geojson-properties-layer-builder.ts

@@ -0,0 +1,111 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { Geometry, MultiPolygon, Polygon } from 'geojson';
+import { OrdinalVisualValueDimensionBuilder } from '../../../../data-dimensions/ordinal/ordinal-visual-value/ordinal-visual-value-builder';
+import { FillDefinition } from '../../../../fill-definitions/fill-definitions';
+import { GeographiesFeature } from '../../../geographies-feature';
+import { GeographiesLayerBuilder } from '../geographies-layer/geographies-layer-builder';
+import { GeographiesGeojsonPropertiesLayer } from './geojson-properties-layer';
+
+const DEFAULT = {
+  _class: () => '',
+  _enableEventActions: false,
+};
+
+export class GeographiesGeojsonPropertiesLayerBuilder<
+  TProperties,
+  TGeometry extends Geometry = MultiPolygon | Polygon,
+> extends GeographiesLayerBuilder<TProperties, TGeometry> {
+  private fillBuilder: OrdinalVisualValueDimensionBuilder<
+    GeographiesFeature<TProperties, TGeometry>,
+    string,
+    string
+  >;
+  private _customFills: FillDefinition<
+    GeographiesFeature<TProperties, TGeometry>
+  >[];
+
+  constructor() {
+    super();
+    safeAssign(this, DEFAULT);
+  }
+
+  /**
+   * OPTIONAL: Set a fill color or function that yields a color for all geographies in the layer.
+   *
+   * If a string is provided, all geographies will be filled with that color.
+   *
+   * Otherwise, you can use this method to specify how each geography should be filled based on the properties of the geojson feature.
+   */
+  fill(fill: null): this;
+  fill(fill: string): this;
+  fill(
+    fill: (
+      fill: OrdinalVisualValueDimensionBuilder<
+        GeographiesFeature<TProperties, TGeometry>,
+        string,
+        string
+      >
+    ) => void
+  ): this;
+  fill(
+    fill:
+      | string
+      | null
+      | ((
+          fill: OrdinalVisualValueDimensionBuilder<
+            GeographiesFeature<TProperties, TGeometry>,
+            string,
+            string
+          >
+        ) => void)
+  ): this {
+    this.initFillBuilder();
+
+    if (fill === null) {
+      this.fillBuilder.valueAccessor(() => null).range(['None']);
+      return this;
+    }
+
+    if (typeof fill === 'string') {
+      this.fillBuilder.valueAccessor(() => null).range([fill]);
+    } else {
+      fill(this.fillBuilder);
+    }
+    return this;
+  }
+
+  customFills(
+    customFills: FillDefinition<GeographiesFeature<TProperties, TGeometry>>[]
+  ): this {
+    this._customFills = customFills;
+    return this;
+  }
+
+  private initFillBuilder(): void {
+    this.fillBuilder = new OrdinalVisualValueDimensionBuilder();
+  }
+
+  _build(): GeographiesGeojsonPropertiesLayer<TProperties, TGeometry> {
+    this.validateBuilder();
+    return new GeographiesGeojsonPropertiesLayer({
+      marksClass: 'vic-geographies-geojson-properties-layer',
+      customFills: this._customFills,
+      featureClass: this._class,
+      enableEventActions: this._enableEventActions,
+      fill: this.fillBuilder._build('Fill'),
+      geographies: this._geographies,
+      labels: this.labelsBuilder?._build(),
+      mixBlendMode: this._mixBlendMode,
+      stroke: this.strokeBuilder?._build(),
+    });
+  }
+
+  validateBuilder(): void {
+    if (!this.fillBuilder) {
+      this.initFillBuilder();
+    }
+    if (!this.strokeBuilder) {
+      this.initStrokeBuilder();
+    }
+  }
+}

package/src/lib/geographies/config/layers/geojson-properties-layer/geojson-properties-layer-options.ts

@@ -0,0 +1,19 @@
+import { Geometry, MultiPolygon, Polygon } from 'geojson';
+import { OrdinalVisualValueDimension } from '../../../../data-dimensions/ordinal/ordinal-visual-value/ordinal-visual-value';
+import { FillDefinition } from '../../../../fill-definitions/fill-definitions';
+import { GeographiesFeature } from '../../../geographies-feature';
+import { GeographiesLayerOptions } from '../geographies-layer/geographies-layer-options';
+
+export interface GeographiesGeojsonPropertiesLayerOptions<
+  TProperties,
+  TGeometry extends Geometry = MultiPolygon | Polygon,
+> extends GeographiesLayerOptions<TProperties, TGeometry> {
+  customFills: FillDefinition<GeographiesFeature<TProperties, TGeometry>>[];
+  fill: OrdinalVisualValueDimension<
+    GeographiesFeature<TProperties, TGeometry>,
+    string,
+    string
+  >;
+  marksClass: string;
+  mixBlendMode: string;
+}

package/src/lib/geographies/config/layers/geojson-properties-layer/geojson-properties-layer.spec.ts

@@ -0,0 +1,41 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { OrdinalVisualValueDimension } from '../../../../data-dimensions/ordinal/ordinal-visual-value/ordinal-visual-value';
+import { GeographiesGeojsonPropertiesLayer } from './geojson-properties-layer';
+import { GeographiesGeojsonPropertiesLayerBuilder } from './geojson-properties-layer-builder';
+
+type FeatureProperties = { name: string };
+const features = [
+  { name: 'Alabama' },
+  { name: 'Alaska' },
+  { name: 'Arizona' },
+  { name: 'California' },
+  { name: 'Colorado' },
+];
+function createLayer(): GeographiesGeojsonPropertiesLayer<
+  { name: string },
+  any
+> {
+  return new GeographiesGeojsonPropertiesLayerBuilder<FeatureProperties>()
+    .geographies(features as any)
+    .fill((dimension) => dimension.range(['lime']))
+    ._build();
+}
+
+describe('GeographiesGeojsonPropertiesLayer', () => {
+  let layer: GeographiesGeojsonPropertiesLayer<{ name: string }, any>;
+
+  describe('initPropertiesFromGeographies()', () => {
+    beforeEach(() => {
+      spyOn(
+        OrdinalVisualValueDimension.prototype as any,
+        'setPropertiesFromData'
+      );
+      layer = createLayer();
+    });
+    it('calls setPropertiesFromData once if fill dimension exists', () => {
+      expect(
+        (layer as any).fill.setPropertiesFromData
+      ).toHaveBeenCalledOnceWith(features);
+    });
+  });
+});

package/src/lib/geographies/config/layers/geojson-properties-layer/geojson-properties-layer.ts

@@ -0,0 +1,67 @@
+import { safeAssign } from '@mathstack/app-kit';
+import { select } from 'd3';
+import { Geometry, MultiPolygon, Polygon } from 'geojson';
+import { FillUtilities } from '../../../../core/utilities/fill-utilities';
+import { OrdinalVisualValueDimension } from '../../../../data-dimensions/ordinal/ordinal-visual-value/ordinal-visual-value';
+import { FillDefinition } from '../../../../fill-definitions/fill-definitions';
+import { GeographiesFeature } from '../../../geographies-feature';
+import {
+  GeographiesLayer,
+  GeographiesTooltipDatum,
+} from '../geographies-layer/geographies-layer';
+import { GeographiesGeojsonPropertiesLayerOptions } from './geojson-properties-layer-options';
+
+export class GeographiesGeojsonPropertiesLayer<
+  TProperties,
+  TGeometry extends Geometry = MultiPolygon | Polygon,
+>
+  extends GeographiesLayer<string, TProperties, TGeometry>
+  implements GeographiesGeojsonPropertiesLayerOptions<TProperties, TGeometry>
+{
+  readonly customFills: FillDefinition<
+    GeographiesFeature<TProperties, TGeometry>
+  >[];
+  readonly fill: OrdinalVisualValueDimension<
+    GeographiesFeature<TProperties, TGeometry>,
+    string,
+    string
+  >;
+  readonly marksClass: string;
+  readonly mixBlendMode: string;
+
+  constructor(
+    options: GeographiesGeojsonPropertiesLayerOptions<TProperties, TGeometry>
+  ) {
+    super();
+    safeAssign(this, options);
+    this.initPropertiesFromGeographies();
+  }
+
+  private initPropertiesFromGeographies(): void {
+    this.fill.setPropertiesFromData(this.geographies);
+  }
+
+  getFill(feature: GeographiesFeature<TProperties, TGeometry>): string {
+    const featureIndex = this.featureIndexAccessor(feature);
+    const defaultFill = this.fill.getScale()(featureIndex);
+    return this.customFills
+      ? FillUtilities.getFill(feature, defaultFill, this.customFills)
+      : defaultFill;
+  }
+
+  getTooltipData(path: SVGPathElement): GeographiesTooltipDatum<undefined> {
+    const feature = select(path).datum() as GeographiesFeature<
+      TProperties,
+      TGeometry
+    >;
+    const featureIndex = this.featureIndexAccessor(feature);
+    const tooltipData: GeographiesTooltipDatum<undefined> = {
+      attributeValue: undefined,
+      datum: undefined,
+      color: this.getFill(feature),
+      geography: featureIndex,
+    };
+
+    return tooltipData;
+  }
+}

package/src/lib/geographies/config/layers/labels/geographies-labels-builder.ts

@@ -0,0 +1,269 @@
+import { safeAssign } from '@mathstack/app-kit';
+import type * as CSSType from 'csstype';
+import {
+  GeoPath,
+  GeoProjection,
+  maxIndex,
+  polygonArea,
+  scaleLinear,
+  ScaleLinear,
+} from 'd3';
+import { Geometry, MultiPolygon, Polygon } from 'geojson';
+import polylabel from 'polylabel';
+import { Position } from '../../../../core/types/layout';
+import { GeographiesFeature } from '../../../geographies-feature';
+import { GeographiesLabels } from './geographies-labels';
+import {
+  GeographiesLabelsColorOptions,
+  GeographiesLabelsFontWeightOptions,
+} from './geographies-labels-options';
+
+const DEFAULT = {
+  _alignmentBaseline: 'middle',
+  _color: '#000',
+  _cursor: 'default',
+  _display: () => true,
+  _dominantBaseline: 'middle',
+  _fontScale: scaleLinear().domain([0, 800]).range([0, 17]),
+  _fontWeight: 400,
+  _textAnchor: 'middle',
+  _pointerEvents: 'none',
+  _valueAccessor: (feature) => feature,
+};
+
+export class GeographiesLabelsBuilder<
+  TProperties,
+  TGeometry extends Geometry = MultiPolygon | Polygon,
+> {
+  private _alignmentBaseline: CSSType.Property.AlignmentBaseline;
+  private _color: GeographiesLabelsColorOptions | CSSType.Property.Fill;
+  private _cursor: CSSType.Property.Cursor;
+  private _display: (featureIndex: string) => boolean;
+  private _dominantBaseline: CSSType.Property.DominantBaseline;
+  private _fontWeight:
+    | GeographiesLabelsFontWeightOptions
+    | CSSType.Property.FontWeight;
+  private _fontScale: ScaleLinear<number, number, never>;
+  private _pointerEvents: CSSType.Property.PointerEvents;
+  private _position: (
+    d: GeographiesFeature<TProperties, TGeometry>,
+    path: GeoPath,
+    projection?: GeoProjection
+  ) => Position;
+  private _textAnchor: CSSType.Property.TextAnchor;
+  private _valueAccessor: (
+    featureIndex: GeographiesFeature<TProperties, TGeometry>
+  ) => string;
+
+  constructor() {
+    safeAssign(this, DEFAULT);
+    this._position = (d, path) =>
+      this.positionAtCentroid<TProperties, TGeometry>(d, path);
+  }
+
+  /**
+   * OPTIONAL. The alignment of the baseline of the text relative to the text's font.
+   *
+   * @default 'middle'
+   */
+  alignmentBaseline(
+    alignmentBaseline: CSSType.Property.AlignmentBaseline
+  ): this {
+    this._alignmentBaseline = alignmentBaseline;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. The color of the text. If a string value is provided, that value will be used for all geographies on the layer.
+   *
+   * If an object is provided, the color between default and contrastAlternative that has the highest contrast ratio with the geography's background color will be used.
+   *
+   * If a value for `pattern` is provided, that value will be used for geographies with a fill pattern. If it is not provided, the default option will be used for geographies with a fill pattern.
+   *
+   * @default '#000'
+   */
+  color(color: GeographiesLabelsColorOptions | CSSType.Property.Fill): this {
+    this._color = color;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. The cursor to display when hovering over the text
+   *
+   * @default 'default'
+   */
+  cursor(cursor: CSSType.Property.Cursor): this {
+    this._cursor = cursor;
+    return this;
+  }
+
+  /**
+   * OPTIONAL, A function that determines whether to display the label for a given feature.
+   *
+   * @default () => true
+   */
+  display(display: boolean): this;
+  display(display: (featureIndex: string) => boolean): this;
+  display(display: boolean | ((featureIndex: string) => boolean)): this {
+    this._display = typeof display === 'boolean' ? () => display : display;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. The dominant baseline of the text.
+   *
+   * @default 'middle'
+   */
+  dominantBaseline(dominantBaseline: CSSType.Property.DominantBaseline): this {
+    this._dominantBaseline = dominantBaseline;
+    return this;
+  }
+
+  /**
+   * OPTIONAL. The font weight of the text.
+   *
+   * If an object is provided, the font weight for each property on the object will be used when the corresponding color is used.
+   *
+   * @default 400
+   */
+  fontWeight(
+    fontWeight: GeographiesLabelsFontWeightOptions | CSSType.Property.FontWeight
+  ): this {
+    this._fontWeight = fontWeight;
+    return this;
+  }
+
+  /**
+   * The scale used to determine the font size of the label.
+   */
+  fontScale(fontScale: ScaleLinear<number, number, never>): this {
+    this._fontScale = fontScale;
+    return this;
+  }
+
+  /**
+   * The pointer events of the text.
+   */
+  pointerEvents(pointerEvents: CSSType.Property.PointerEvents): this {
+    this._pointerEvents = pointerEvents;
+    return this;
+  }
+
+  /**
+   * The position of the label relative to the feature
+   */
+  position(
+    position: (
+      d: GeographiesFeature<TProperties, TGeometry>,
+      path: GeoPath,
+      projection: GeoProjection
+    ) => Position
+  ): this {
+    this._position = position;
+    return this;
+  }
+
+  /**
+   * The text anchor of the text.
+   */
+  textAnchor(textAnchor: CSSType.Property.TextAnchor): this {
+    this._textAnchor = textAnchor;
+    return this;
+  }
+
+  /**
+   * A function that determines the value of the label for a given feature
+   */
+  valueAccessor(
+    valueAccessor: (
+      featureIndex: GeographiesFeature<TProperties, TGeometry>
+    ) => string
+  ): this {
+    this._valueAccessor = valueAccessor;
+    return this;
+  }
+
+  _build(): GeographiesLabels<TProperties, TGeometry> {
+    return new GeographiesLabels<TProperties, TGeometry>({
+      alignmentBaseline: this._alignmentBaseline,
+      color: this._color,
+      cursor: this._cursor,
+      display: this._display,
+      dominantBaseline: this._dominantBaseline,
+      fontScale: this._fontScale,
+      fontWeight: this._fontWeight,
+      pointerEvents: this._pointerEvents,
+      position: this._position,
+      textAnchor: this._textAnchor,
+      valueAccessor: this._valueAccessor,
+    });
+  }
+
+  /**
+   * A function to position something at the centroid of a feature.
+   */
+  positionAtCentroid<TProperties, TGeometry extends Geometry>(
+    feature: GeographiesFeature<TProperties, TGeometry>,
+    path: GeoPath
+  ): Position {
+    const c = path.centroid(feature);
+    return { x: c[0], y: c[1] };
+  }
+
+  /**
+   * A function to position a label for Hawaii on a GeoAlbersUsa projection.
+   */
+  positionHawaiiOnGeoAlbersUsa<TProperties>(
+    feature: GeographiesFeature<TProperties, MultiPolygon>,
+    projection: GeoProjection
+  ): Position {
+    const startPolygon =
+      // we need to cast because Position can return two or three numbers but GeoProjection
+      // can only handle [number, number]
+      (feature.geometry.coordinates[0][0] as [number, number][]).map(
+        projection
+      );
+    const endPolygon = (
+      feature.geometry.coordinates[
+        feature.geometry.coordinates.length - 1
+      ][0] as [number, number][]
+    ).map(projection);
+
+    const approxStartCoords = startPolygon[0];
+    const approxEndCoords = endPolygon[0];
+    return {
+      x: approxStartCoords[0] + (approxEndCoords[0] - approxStartCoords[0]) / 2,
+      y: approxStartCoords[1],
+    };
+  }
+
+  /**
+   * A function to position a label with Polylabel lib
+   */
+  positionWithPolylabel<
+    TProperties,
+    TGeometry extends MultiPolygon | Polygon = MultiPolygon | Polygon,
+  >(
+    feature: GeographiesFeature<TProperties, TGeometry>,
+    projection: GeoProjection
+  ): Position {
+    const isMultiPolygon = feature.geometry.coordinates.length > 1;
+    let largestIndex = 0;
+    let largestPolygon: [number, number][];
+    if (isMultiPolygon) {
+      const coords = feature.geometry.coordinates as [number, number][][][];
+      largestIndex = maxIndex(
+        coords.map((polygon) => {
+          return polygonArea(polygon[0]);
+        })
+      );
+      largestPolygon = coords[largestIndex][0];
+    } else {
+      const coords = feature.geometry.coordinates as [number, number][][];
+      largestPolygon = coords[0];
+    }
+    const projectedPoints = largestPolygon.map(projection);
+    const adjustedPosition = polylabel([projectedPoints]);
+    return { x: adjustedPosition[0], y: adjustedPosition[1] };
+  }
+}

package/src/lib/geographies/config/layers/labels/geographies-labels-options.ts

@@ -0,0 +1,45 @@
+import type * as CSSType from 'csstype';
+import { GeoPath, GeoProjection, ScaleLinear } from 'd3';
+import { Geometry, MultiPolygon, Polygon } from 'geojson';
+import { Position } from '../../../../core/types/layout';
+import { GeographiesFeature } from '../../../geographies-feature';
+
+/**
+ * Configuration object for displaying labels on map.
+ *
+ * The generic parameters are the same as those in VicGeographiesConfig.
+ */
+export interface GeographiesLabelsOptions<
+  TProperties,
+  TGeometry extends Geometry = MultiPolygon | Polygon,
+> {
+  alignmentBaseline: CSSType.Property.AlignmentBaseline;
+  color: GeographiesLabelsColorOptions | CSSType.Property.Fill;
+  cursor: CSSType.Property.Cursor;
+  display: (featureIndex: string) => boolean;
+  dominantBaseline: CSSType.Property.DominantBaseline;
+  fontScale: ScaleLinear<number, number, never>;
+  fontWeight: GeographiesLabelsFontWeightOptions | CSSType.Property.FontWeight;
+  pointerEvents: CSSType.Property.PointerEvents;
+  position: (
+    d: GeographiesFeature<TProperties, TGeometry>,
+    path: GeoPath,
+    projection: GeoProjection
+  ) => Position;
+  textAnchor: CSSType.Property.TextAnchor;
+  valueAccessor: (
+    feature: GeographiesFeature<TProperties, TGeometry>
+  ) => string;
+}
+
+export interface GeographiesLabelsColorOptions {
+  default: CSSType.Property.Fill;
+  contrastAlternative: CSSType.Property.Fill;
+  pattern?: CSSType.Property.Fill;
+}
+
+export interface GeographiesLabelsFontWeightOptions {
+  default: CSSType.Property.FontWeight;
+  contrastAlternative: CSSType.Property.FontWeight;
+  pattern?: CSSType.Property.FontWeight;
+}

package/src/lib/geographies/config/layers/labels/geographies-labels.ts

@@ -0,0 +1,38 @@
+import { safeAssign } from '@mathstack/app-kit';
+import type * as CSSType from 'csstype';
+import { GeoPath, GeoProjection, ScaleLinear } from 'd3';
+import { Geometry, MultiPolygon, Polygon } from 'geojson';
+import { Position } from '../../../../core/types/layout';
+import { GeographiesFeature } from '../../../geographies-feature';
+import {
+  GeographiesLabelsColorOptions,
+  GeographiesLabelsFontWeightOptions,
+  GeographiesLabelsOptions,
+} from './geographies-labels-options';
+
+export class GeographiesLabels<
+  TProperties,
+  TGeometry extends Geometry = MultiPolygon | Polygon,
+> implements GeographiesLabelsOptions<TProperties, TGeometry> {
+  alignmentBaseline: CSSType.Property.AlignmentBaseline;
+  color: GeographiesLabelsColorOptions | CSSType.Property.Fill;
+  cursor: CSSType.Property.Cursor;
+  display: (featureIndex: string) => boolean;
+  dominantBaseline: CSSType.Property.DominantBaseline;
+  fontScale: ScaleLinear<number, number, never>;
+  fontWeight: GeographiesLabelsFontWeightOptions | CSSType.Property.FontWeight;
+  pointerEvents: CSSType.Property.PointerEvents;
+  position: (
+    d: GeographiesFeature<TProperties, TGeometry>,
+    path: GeoPath,
+    projection?: GeoProjection
+  ) => Position;
+  textAnchor: CSSType.Property.TextAnchor;
+  valueAccessor: (
+    feature: GeographiesFeature<TProperties, TGeometry>
+  ) => string;
+
+  constructor(options: GeographiesLabelsOptions<TProperties, TGeometry>) {
+    safeAssign(this, options);
+  }
+}

package/src/lib/geographies/events/actions/geographies-click-actions.ts

@@ -0,0 +1,21 @@
+import { EventAction, EventType } from '../../../events';
+import { GeographiesHost } from '../geographies-events.directive';
+import { GeographiesInteractionOutput } from '../geographies-interaction-output';
+
+export class GeographiesClickEmitTooltipDataPauseOtherActions<
+  Datum,
+> implements EventAction<
+  GeographiesHost<Datum>,
+  GeographiesInteractionOutput<Datum>
+> {
+  onStart(host: GeographiesHost<Datum>): void {
+    const output = host.getInteractionOutput(EventType.Click);
+    host.disableOtherActions(EventType.Click);
+    host.emitInteractionOutput(output);
+  }
+
+  onEnd(host: GeographiesHost<Datum>): void {
+    host.resumeOtherActions(EventType.Click);
+    host.emitInteractionOutput(null);
+  }
+}

package/src/lib/geographies/events/actions/geographies-hover-actions.ts

@@ -0,0 +1,17 @@
+import { EventAction, EventType } from '../../../events';
+import { GeographiesHost } from '../geographies-events.directive';
+import { GeographiesInteractionOutput } from '../geographies-interaction-output';
+
+export class GeographiesHoverEmitTooltipData<Datum> implements EventAction<
+  GeographiesHost<Datum>,
+  GeographiesInteractionOutput<Datum>
+> {
+  onStart(host: GeographiesHost<Datum>): void {
+    const outputData = host.getInteractionOutput(EventType.Hover);
+    host.emitInteractionOutput(outputData);
+  }
+
+  onEnd(host: GeographiesHost<Datum>): void {
+    host.emitInteractionOutput(null);
+  }
+}

package/src/lib/geographies/events/actions/geographies-hover-move-actions.ts

@@ -0,0 +1,19 @@
+import { EventType, HoverMoveAction } from '../../../events';
+import { GeographiesHost } from '../geographies-events.directive';
+import { GeographiesInteractionOutput } from '../geographies-interaction-output';
+
+export class GeographiesHoverMoveEmitTooltipData<
+  Datum,
+> implements HoverMoveAction<
+  GeographiesHost<Datum>,
+  GeographiesInteractionOutput<Datum>
+> {
+  onStart(host: GeographiesHost<Datum>): void {
+    const outputData = host.getInteractionOutput(EventType.HoverMove);
+    host.emitInteractionOutput(outputData);
+  }
+
+  onEnd(host: GeographiesHost<Datum>): void {
+    host.emitInteractionOutput(null);
+  }
+}