@unovis/ts 1.1.1-beta.5 → 1.1.1-beta.7

package/src/core/component/config.ts

@@ -0,0 +1,61 @@
+/* eslint-disable no-irregular-whitespace */
+import { Config } from 'core/config'
+import { VisEventCallback, VisEventType } from 'core/component/types'
+
+export interface ComponentConfigInterface {
+  /** Animation duration of the data update transitions in milliseconds. Default: `600` */
+  duration?: number;
+  /** Events configuration. An object containing properties in the following format:
+   *
+   * ```
+   * {
+   *   [selectorString]: {
+   *       [eventType]: callbackFunction
+   *   }
+   * }
+   * ```
+   * e.g.:
+   * ```
+   * {
+   *   [Area.selectors.area]: {
+   *     click: (d) => console.log("Clicked Area", d)
+   *   }
+   * }
+   * ```
+   */
+  events?: {
+    [selector: string]: {
+      [eventType in VisEventType]?: VisEventCallback;
+    };
+  };
+  /** You can set every SVG and HTML visualization object to have a custom DOM attributes, which is useful
+   * when you want to do unit or end-to-end testing. Attributes configuration object has the following structure:
+   *
+   * ```
+   * {
+   *   [selectorString]: {
+   *       [attributeName]: attribute constant value or accessor function
+   *   }
+   * }
+   * ```
+   * e.g.:
+   * ```
+   * {
+   *   [Area.selectors.area]: {
+   *     "test-value": d => d.value
+   *   }
+   * }
+   * ```
+   */
+  attributes?: {
+    [selector: string]: {
+      [attr: string]: string | number | boolean | ((datum: any) => string | number | boolean);
+    };
+  };
+}
+
+export class ComponentConfig extends Config implements ComponentConfigInterface {
+  duration = 600
+  events = {}
+  attributes = {}
+}

package/src/core/component/index.ts

@@ -0,0 +1,154 @@
+import { select, Selection } from 'd3-selection'
+import { Transition } from 'd3-transition'
+
+// Core
+import { CoreDataModel } from 'data-models/core'
+
+// Utils
+import { throttle } from 'utils/data'
+import { guid } from 'utils/misc'
+
+// Types
+import { ComponentType, Sizing } from 'types/component'
+import { Spacing } from 'types/spacing'
+
+// Local Types
+import { VisEventCallback, VisEventType } from './types'
+
+// Config
+import { ComponentConfig, ComponentConfigInterface } from './config'
+
+export class ComponentCore<
+  CoreDatum,
+  ConfigClass extends ComponentConfig = ComponentConfig,
+  ConfigInterface extends ComponentConfigInterface = ComponentConfigInterface,
+> {
+  element: SVGGElement | HTMLElement
+  type: ComponentType = ComponentType.SVG
+  g: Selection<SVGGElement, unknown, null, undefined> | Selection<HTMLElement, unknown, null, undefined>
+  config: ConfigClass
+  prevConfig: ConfigClass
+  datamodel: CoreDataModel<CoreDatum> = new CoreDataModel()
+  sizing: Sizing | string = Sizing.Fit // Supported by SingleContainer and a subset of components only (Sankey)
+  uid: string
+
+  events: {
+    [selector: string]: {
+      [eventType in VisEventType]?: VisEventCallback;
+    };
+  } = {}
+
+  /** Component width in pixels. This property is set automatically by the container. */
+  protected _width = 400
+  /** Component height in pixels. This property is set automatically by the container. */
+  protected _height = 200
+  /** Container width in pixels. This property is set automatically by the container. */
+  protected _containerWidth: number | undefined = undefined
+  /** Container height in pixels. This property is set automatically by the container. */
+  protected _containerHeight: number | undefined = undefined
+
+  _setUpComponentEventsThrottled = throttle(this._setUpComponentEvents, 500)
+  _setCustomAttributesThrottled = throttle(this._setCustomAttributes, 500)
+
+  constructor (type = ComponentType.SVG) {
+    if (type === ComponentType.SVG) {
+      this.element = document.createElementNS('http://www.w3.org/2000/svg', 'g')
+    } else {
+      this.element = document.createElement('div')
+    }
+    this.uid = guid()
+    this.g = select(this.element) as Selection<SVGGElement, unknown, null, undefined> | Selection<HTMLElement, unknown, null, undefined>
+
+    // Setting the root class if available
+    // eslint-disable-next-line dot-notation
+    const rootClass = this.constructor?.['selectors']?.root as string
+    if (rootClass) this.g.attr('class', rootClass)
+  }
+
+  setConfig (config: ConfigInterface): void {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    const ConfigModel = (this.config.constructor as typeof ComponentConfig)
+    this.prevConfig = this.config // Store the previous config instance
+    this.config = new ConfigModel().init(config) as ConfigClass
+  }
+
+  setData (data: CoreDatum): void {
+    this.datamodel.data = data
+  }
+
+  setSize (width: number, height: number, containerWidth: number, containerHeight: number): void {
+    if (isFinite(width)) this._width = width
+    if (isFinite(height)) this._height = height
+    if (isFinite(containerWidth)) this._containerWidth = containerWidth
+    if (isFinite(containerHeight)) this._containerHeight = containerHeight
+  }
+
+  render (duration = this.config.duration): void {
+    this._render(duration)
+
+    // While transition is in progress, we add the 'animating' attribute to the component's SVG group
+    const ANIMATING_ATTR = 'animating'
+    if (duration) {
+      this.g.attr(ANIMATING_ATTR, '')
+      const transition = this.g
+        .transition(ANIMATING_ATTR)
+        .duration(duration) as Transition<SVGGElement | HTMLElement, unknown, null, undefined>
+
+      transition.on('end interrupt', () => {
+        this.g.attr(ANIMATING_ATTR, null)
+      })
+    }
+    this._setUpComponentEventsThrottled()
+    this._setCustomAttributesThrottled()
+  }
+
+  get bleed (): Spacing {
+    return { top: 0, bottom: 0, left: 0, right: 0 }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  _render (duration = this.config.duration): void {
+  }
+
+  private _setCustomAttributes (): void {
+    const attributeMap = this.config.attributes
+
+    Object.keys(attributeMap).forEach(className => {
+      Object.keys(attributeMap[className]).forEach(attr => {
+        (this.g as Selection<SVGGElement | HTMLElement, unknown, null, undefined>)
+          .selectAll(`.${className}`)
+          .attr(attr, attributeMap[className][attr])
+      })
+    })
+  }
+
+  private _setUpComponentEvents (): void {
+    // Set up default events
+    this._bindEvents(this.events)
+
+    // Set up user-defined events
+    this._bindEvents(this.config.events, '.user')
+  }
+
+  private _bindEvents (events = this.events, suffix = ''): void {
+    Object.keys(events).forEach(className => {
+      Object.keys(events[className]).forEach(eventType => {
+        const selection = (this.g as Selection<SVGGElement | HTMLElement, unknown, null, undefined>).selectAll(`.${className}`)
+        selection.on(eventType + suffix, (event: Event, d) => {
+          const els = selection.nodes()
+          const i = els.indexOf(event.currentTarget as SVGGElement | HTMLElement)
+          return events[className][eventType](d, event, i, els)
+        })
+      })
+    })
+  }
+
+  public destroy (): void {
+    this.g?.remove()
+    this.element = undefined
+  }
+
+  public isDestroyed (): boolean {
+    return !this.element
+  }
+}

package/src/core/component/types.ts

@@ -0,0 +1,9 @@
+export type VisEventType = 'touchstart' | 'touchmove' | 'touchend' | 'mouseover' | 'mousemove' | 'mousedown' | 'mouseup'
+| 'click' | 'auxclick' | 'contextmenu' | 'dblclick' | 'mouseenter' | 'mouseleave' | 'mouseout' | 'scroll'
+| 'select' | 'wheel' | 'pointerdown' | 'pointerup' | 'pointerout' | 'pointermove'
+
+export type VisEventCallback<Datum = any> =
+  ((data: Datum, event: MouseEvent, i: number, els: (SVGElement | HTMLElement)[]) => void) |
+  ((data: Datum, event: WheelEvent, i: number, els: (SVGElement | HTMLElement)[]) => void) |
+  ((data: Datum, event: PointerEvent, i: number, els: (SVGElement | HTMLElement)[]) => void) |
+  ((data: Datum, event: TouchEvent, i: number, els: (SVGElement | HTMLElement)[]) => void);

package/src/core/config/index.ts

@@ -0,0 +1,12 @@
+import { isPlainObject, merge } from 'utils/data'
+
+export class Config {
+  init<T> (config: T): this {
+    Object.keys(config).forEach(key => {
+      if (isPlainObject(this[key]) && isPlainObject(config[key])) this[key] = merge(this[key], config[key])
+      else this[key] = config[key]
+    })
+
+    return this
+  }
+}

package/src/core/container/config.ts

@@ -0,0 +1,56 @@
+// Core
+import { Config } from 'core/config'
+
+// Types
+import { Sizing } from 'types/component'
+import { Spacing } from 'types/spacing'
+
+export interface ContainerConfigInterface {
+  /** Animation duration of all the components within the container. Default: `undefined` */
+  duration?: number;
+  /** Margins. Default: `{ top: 0, bottom: 0, left: 0, right: 0 }` */
+  margin?: Spacing;
+  /** Padding. Default: `{ top: 0, bottom: 0, left: 0, right: 0 }` */
+  padding?: Spacing;
+  /** Defines whether components should fit into the container or the container should expand to fit to the component's size. Default: `Sizing.Fit` */
+  sizing?: Sizing | string;
+  /** Width in pixels or in CSS units.
+   * Percentage units `"%"` are not supported here. If you want to set `width` as a percentage, do it via `style`
+   * of the corresponding DOM element.
+   * By default, Container automatically fits to the size of the parent element.
+   * Default: `undefined`
+  */
+  width?: number | string;
+  /** Height in pixels or in CSS units.
+   * Percentage units `"%"` are not supported here. If you want to set `height` as a percentage, do it via `style`
+   * of the corresponding DOM element.
+   * By default, Container automatically fits to the size of the parent element.
+   * Default: `undefined`
+  */
+  height?: number | string;
+  /** Custom SVG defs available to all the components within the container. Default: `undefined`. */
+  svgDefs?: string;
+}
+
+export class ContainerConfig extends Config implements ContainerConfigInterface {
+  duration = undefined
+  margin = {
+    top: 0,
+    bottom: 0,
+    left: 0,
+    right: 0,
+  }
+
+  padding = {
+    top: 0,
+    bottom: 0,
+    left: 0,
+    right: 0,
+  }
+
+  sizing = Sizing.Fit
+  width = undefined
+  height = undefined
+
+  svgDefs = undefined
+}

package/src/core/container/index.ts

@@ -0,0 +1,136 @@
+import { select, Selection } from 'd3-selection'
+import { ResizeObserver } from '@juggle/resize-observer'
+
+// Types
+import { Sizing } from 'types/component'
+
+// Utils
+import { isEqual, clamp } from 'utils/data'
+
+// Config
+import { ContainerConfig, ContainerConfigInterface } from './config'
+
+export class ContainerCore {
+  svg: Selection<SVGSVGElement, unknown, null, undefined>
+  element: SVGSVGElement
+  prevConfig: ContainerConfig
+  config: ContainerConfig
+
+  protected _container: HTMLElement
+  protected _requestedAnimationFrame: number
+  private _isFirstRender = true
+  private _containerSize: { width: number; height: number }
+  private _resizeObserver: ResizeObserver | undefined
+
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  static DEFAULT_CONTAINER_HEIGHT = 300
+
+  constructor (element: HTMLElement) {
+    this._requestedAnimationFrame = null
+    this._container = element
+
+    // Create SVG element for visualizations
+    this.svg = select(this._container).append('svg')
+      // We set `display` to `block` because inline elements have an invisible
+      //   inline space that adds 4px to the height of the container
+      .style('display', 'block')
+      .attr('xmlns', 'http://www.w3.org/2000/svg')
+      .attr('height', ContainerCore.DEFAULT_CONTAINER_HEIGHT)
+
+    this.element = this.svg.node()
+  }
+
+  updateContainer<T extends ContainerConfigInterface> (config: T): void {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    const ConfigModel = (this.config.constructor as typeof ContainerConfig)
+    this.prevConfig = this.config
+    this.config = new ConfigModel().init(config)
+  }
+
+  _render (duration?: number): void {
+    if (this.config.svgDefs) {
+      this.svg.select('.svgDefs').remove()
+      this.svg.append('defs').attr('class', 'svgDefs').html(this.config.svgDefs)
+    }
+
+    this._isFirstRender = false
+  }
+
+  render (duration = this.config.duration): void {
+    const width = this.config.width || this.containerWidth
+    const height = this.config.height || this.containerHeight
+
+    // We set SVG size in `render()` instead of `_render()`, because the size values in pixels will become
+    // available only in the next animation when being accessed via `element.clientWidth` and `element.clientHeight`,
+    // and we rely on those values when setting width and size of the components.
+    this.svg
+      .attr('width', width)
+      .attr('height', height)
+
+    // Set up Resize Observer. We do it in `render()` to capture container size change if it happened
+    // in the next animation frame after the initial `render` was called.
+    if (!this._resizeObserver) this._setUpResizeObserver()
+
+    // Schedule the actual rendering in the next frame
+    cancelAnimationFrame(this._requestedAnimationFrame)
+    this._requestedAnimationFrame = requestAnimationFrame(() => {
+      this._render(duration)
+    })
+  }
+
+  get containerWidth (): number {
+    return this.config.width
+      ? this.element.clientWidth
+      : clamp(this._container.clientWidth || this._container.getBoundingClientRect().width, 0, Number.POSITIVE_INFINITY)
+  }
+
+  get containerHeight (): number {
+    return this.config.height
+      ? this.element.clientHeight
+      : clamp(this._container.clientHeight || this._container.getBoundingClientRect().height, 0, Number.POSITIVE_INFINITY)
+  }
+
+  get width (): number {
+    return clamp(this.containerWidth - this.config.margin.left - this.config.margin.right, 0, Number.POSITIVE_INFINITY)
+  }
+
+  get height (): number {
+    return clamp(this.containerHeight - this.config.margin.top - this.config.margin.bottom, 0, Number.POSITIVE_INFINITY)
+  }
+
+  removeAllChildren (): void {
+    while (this.element.firstChild) {
+      this.element.removeChild(this.element.firstChild)
+    }
+  }
+
+  _onResize (): void {
+    const { config } = this
+    const redrawOnResize = config.sizing === Sizing.Fit || config.sizing === Sizing.FitWidth
+    if (redrawOnResize) this.render(0)
+  }
+
+  _setUpResizeObserver (): void {
+    const containerRect = this._container.getBoundingClientRect()
+    this._containerSize = { width: containerRect.width, height: containerRect.height }
+
+    this._resizeObserver = new ResizeObserver((entries, observer) => {
+      const resizedContainerRect = this._container.getBoundingClientRect()
+      const resizedContainerSize = { width: resizedContainerRect.width, height: resizedContainerRect.height }
+      const hasSizeChanged = !isEqual(this._containerSize, resizedContainerSize)
+      // Do resize only if element is attached to the DOM
+      // will come in useful when some ancestor of container becomes detached
+      if (hasSizeChanged && resizedContainerSize.width && resizedContainerSize.height) {
+        this._containerSize = resizedContainerSize
+        this._onResize()
+      }
+    })
+    this._resizeObserver.observe(this._container)
+  }
+
+  destroy (): void {
+    cancelAnimationFrame(this._requestedAnimationFrame)
+    this._resizeObserver?.disconnect()
+    this.svg.remove()
+  }
+}

package/src/core/xy-component/config.ts

@@ -0,0 +1,46 @@
+import { ContinuousScale } from 'types/scale'
+
+// Types
+import { ColorAccessor, NumericAccessor } from 'types/accessor'
+
+// Config
+import { ComponentConfig, ComponentConfigInterface } from '../component/config'
+
+export interface XYComponentConfigInterface<Datum> extends ComponentConfigInterface {
+  /** Accessor function for getting the values along the X axis. Default: `undefined` */
+  x: NumericAccessor<Datum>;
+  /** A single of multiple accessor functions for getting the values along the Y axis. Default: `undefined` */
+  y: NumericAccessor<Datum> | NumericAccessor<Datum>[];
+  /** Accessor function for getting the unique data record id. Used for more persistent data updates. Default: `(d, i) => d.id ?? i` */
+  id?: ((d: Datum, i: number, ...any: any[]) => string);
+  /** Component color accessor function. Default: `d => d.color` */
+  color?: ColorAccessor<Datum> | ColorAccessor<Datum[]>;
+  /** Scale for X dimension, e.g. Scale.scaleLinear(). If you set xScale you'll be responsible for setting it's `domain` and `range` as well.
+   * Only continuous scales are supported.
+   * Default: `undefined`
+  */
+  xScale?: ContinuousScale;
+  /** Scale for Y dimension, e.g. Scale.scaleLinear(). If you set yScale you'll be responsible for setting it's `domain` and `range` as well.
+   * Only continuous scales are supported.
+   * Default: `undefined`
+  */
+  yScale?: ContinuousScale;
+  /** Identifies whether the component should be excluded from overall X and Y domain calculations or not.
+   * This property can be useful when you want pass individual data to a component and you don't want it to affect
+   * the scales of the chart.
+   * Default: `false`
+  */
+  excludeFromDomainCalculation?: boolean;
+}
+
+export class XYComponentConfig<Datum> extends ComponentConfig implements XYComponentConfigInterface<Datum> {
+  x = undefined
+  y = undefined
+  // eslint-disable-next-line dot-notation
+  id = (d: Datum, i: number): string => d['id'] ?? `${i}`
+  // eslint-disable-next-line dot-notation
+  color = (d: Datum | Datum[]): string => d['color']
+  xScale = undefined
+  yScale = undefined
+  excludeFromDomainCalculation = false
+}

package/src/core/xy-component/index.ts

@@ -0,0 +1,90 @@
+import { Selection } from 'd3-selection'
+
+// Core
+import { ComponentCore } from 'core/component'
+import { SeriesDataModel } from 'data-models/series'
+
+// Utils
+import { filterDataByRange, getExtent, isArray } from 'utils/data'
+
+// Types
+import { NumericAccessor } from 'types/accessor'
+import { ContinuousScale, Scale, ScaleDimension } from 'types/scale'
+
+// Config
+import { XYComponentConfig, XYComponentConfigInterface } from './config'
+
+export class XYComponentCore<
+  Datum,
+  ConfigClass extends XYComponentConfig<Datum> = XYComponentConfig<Datum>,
+  ConfigInterface extends Partial<XYComponentConfigInterface<Datum>> = Partial<XYComponentConfigInterface<Datum>>,
+> extends ComponentCore<Datum[], ConfigClass, ConfigInterface> {
+  element: SVGGraphicsElement
+  g: Selection<SVGGElement, unknown, null, undefined>
+  config: ConfigClass
+  prevConfig: ConfigClass
+  datamodel: SeriesDataModel<Datum> = new SeriesDataModel()
+
+  /** Clippable components can be affected by a clipping path (set up in the container) */
+  clippable = true
+
+  /** Identifies whether the component displayed stacked data (eg StackedBar, Area) */
+  stacked = false
+
+  private _xScale: ContinuousScale = Scale.scaleLinear()
+  private _yScale: ContinuousScale = Scale.scaleLinear()
+
+  get xScale (): ContinuousScale {
+    return this.config.xScale || this._xScale
+  }
+
+  get yScale (): ContinuousScale {
+    return this.config.yScale || this._yScale
+  }
+
+  setConfig (config: ConfigInterface): void {
+    // We don't allow changing scales after the component has been initialized
+    if (this.config?.xScale) config.xScale = this.config.xScale
+    if (this.config?.yScale) config.yScale = this.config.yScale
+
+    super.setConfig(config)
+  }
+
+  setScaleDomain (dimension: ScaleDimension, domain: number[]): void {
+    if (dimension === ScaleDimension.X) this._xScale?.domain(domain)
+    if (dimension === ScaleDimension.Y) this._yScale?.domain(domain)
+  }
+
+  setScaleRange (dimension: ScaleDimension, range: number[]): void {
+    if (dimension === ScaleDimension.X) this._xScale?.range(range)
+    if (dimension === ScaleDimension.Y) this._yScale?.range(range)
+  }
+
+  setScale (dimension: ScaleDimension, scale: ContinuousScale): void {
+    if (scale && (dimension === ScaleDimension.X)) this._xScale = scale
+    if (scale && (dimension === ScaleDimension.Y)) this._yScale = scale
+  }
+
+  getDataExtent (dimension: ScaleDimension, scaleByVisibleData: boolean): number[] {
+    const { config, datamodel } = this
+
+    switch (dimension) {
+      case ScaleDimension.X: return this.getXDataExtent()
+      case ScaleDimension.Y: return this.getYDataExtent(scaleByVisibleData)
+      default: return getExtent(datamodel.data, config[dimension])
+    }
+  }
+
+  getXDataExtent (): number[] {
+    const { config, datamodel } = this
+    return getExtent(datamodel.data, config.x)
+  }
+
+  getYDataExtent (scaleByVisibleData: boolean): number[] {
+    const { config, datamodel } = this
+
+    const data = scaleByVisibleData ? filterDataByRange(datamodel.data, this.xScale.domain() as [number, number], config.x) : datamodel.data
+    const yAccessors = (isArray(config.y) ? config.y : [config.y]) as NumericAccessor<Datum>[]
+    return getExtent(data, ...yAccessors)
+  }
+}

package/src/data-models/core.ts

@@ -0,0 +1,15 @@
+export class CoreDataModel<T> {
+  protected _data: T | undefined
+
+  get data (): T {
+    return this._data
+  }
+
+  set data (value: T) {
+    this._data = value
+  }
+
+  constructor (data?: T) {
+    this.data = data
+  }
+}