DDV #

DDV represents the top-level component of every chart type. It sets up a container and an SVG for later drawing. It holds information about the wrapper element size and position, the mouse state, and space reserved in the element by child components.

Props #

Provided Objects #

Child objects can inject() these with type information and reactivity (see Vue Dependency Injection)

Slots #

default #

toolTip #

Responsibilities #

As the highest level chart component, DDV is responsible for a variety of setup tasks, which all child components can then make use of.

Dimensions #

The dimensions of the chart are controlled by the width of the container element and the aspectRatio prop (see also minimumHeightPx);

DOM & Mouse #

The chart is responsible for managing observers on the DOM element (see DOMState) containing our generated SVG as well as observers for the mouse (see MouseState) relative to the element (assuming showCrosshairs is enabled). Both of these states are provide()ed to all child components.

In addition to observing the surrounding DOM state, DDV computes where the "plot area" is inside the available space. This number is continually computed based on a reactive registry called spaceReservations (see SpaceReservations). Child components that wish to reserve space in the chart must inject the provided DOMState, calculate how much space they need, then add it to the appropriate side of the chart in their reservations.

Plot Area #

Every chart constructs a "plot area" as a subset of its real-estate. These sizes are found in DOMState as elementWidth and elementHeigh which represent the pixel dimensions of the wrapping DOM element. You will also find plotWidth and plotHeight representing the dimensions of the plot area. To know how the plot area is offset from the top left of the container, we must consult the DDV's provide()ed object margins (see Margins). These margins are computed continuously based on the chart's spaceReservations.

Space Reservations #

Every child component such as Axis, ChartLegend that wishes to reserve an area in the chart may do so by registering itself in the chart's spaceReservations. An example of a reactive custom element reserving left-side margin is below...

/** A contrived custom child of a DDVChart, illustrating how to
 * - identify the component uniquely (myId)
 * - inject the provided plot information
 * - properly register the space used by this component in the chart on mount/unmount/computed update
 *
 */
...
import type {
  DOMState, SpaceReservations
} from "@incytestudios/ddv/types/common";
...
setup() {
  ...
  // anything unique
  const myId = Math.round(Math.random() * 100_000);
  // in case our size depends on plotWidth/Height, let's inject the DOMState
  const domState = inject('domState') as DOMState;
  // we need to inject this registry to add our reservation
  const reservations = inject('spaceReservations') as SpaceReservations;
  // imagine some code your component runs to size itself based on the current
  // injected state and comes up with a left-margin it needs to apply to the
  // chart
  const myWidth = computed(() => domState.value.plotHeight > 100 : 64 : 0)

  // updating your reservation is as simple as setting the correct pixel value in the
  // correct margin
  const updateReservation = (newWidth:number) {
    reservations[myId] = {
      top: 0,
      bottom: 0,
      left: newWidth,
      right: 0
    }
  }
  // watch your own computed prop since we're looking at mouse state
  watch(myWidth, updateReservation);
  // register ourselves on mount
  onMounted(() => updateReservation(myWidth.value));
  // remove our reservation
  onBeforeUmount(() => delete reservations[myId])
}