Migration Guide to v2

The migration process isn't hard work.
The changes are minimal, but need to know what are the changes. Let's get started!

NOTE: If you haven't read v2 CHANGELOG, checkout the detailed changes before continuing with this document.

1) Update your callbacks options context

• All callback-ish options' context has been updated to bound to the current chart instance by default.
• Those callback options where passing a context param, was removed.

Ref: v2 CHANGELOG > Callbacks context

tooltip: {
    position: function() {
        this;  // <-- current chart instance
    },

    // v1
    onshow: function(ctx, selectedData) {
        ctx;
    },

    // v2
    onshow: function(selectedData) {
        this;
    }
}

2) Update the interface changes

zoom.enabled.type

To simply and align with other interaction options format, moved the type field from being member of 'enabled' to member of 'zoom'.

// v1.x
zoom: {
  enabled: {
    type: "drag"
  }
}

// v2
  zoom: {
  enabled: true,
  type: "drag" // if omit, 'wheel' will set by default
}

// There's no need to update if 'wheel' zoom type is used
// v1.x
zoom: {
  enabled: true
}

// v2
zoom: {
  enabled: true
}

3) Update your ESM imports

NOTE: Only for ESM import usage. If you're using UMD build(via <script> tag or else), you can ignore this section.

// v1
import bb from "billboard.js";

bb.generate({
  ...,
  data: {
    type: "line",
    
    // or specifying type for each data
    types: {
      data1: "bar",
      data1: "area-spline"
    }
    selection: {
        enabled: true
    }
  },
  subchart: {
      show: true
  },
  zoom: {
      enabled: true
  }
});

v2, every chart types modules and interaction(data.selection, subchart and zoom) modules, will be exported as Named Exports.
From this approach, will make beneficial tree-shake unused codes to get much smaller build size.

Ref: v2 CHANGELOG > Example of size reduction by types

NOTE: v1 could be omitting 'data.type' setting for 'line'(the default value), but in v2 you MUST specify 'data.type' option value.

// v2 
import bb, {
  // import used chart types only
  area,
  areaLineRange,
  areaSpline,
  areaSplineRange,
  areaStep,
  bar,
  bubble,
  donut,
  gauge,
  line,
  pie,
  radar,
  scatter,
  spline,
  step,

  // import used interaction modules only
  selection,
  subchart,
  zoom
}

bb.generate({
  ...,
  data: {
    // by calling `line()`, will make internally extend 'line' type related functionality.
    // line() will return "line" string.
    type: line(),
    
    // or specifying type for each data
    types: {
      data1: bar(),
      data1: areaSpline()
    },

    // if used "data.selection"
    selection: {
      enabled: selection() // selection() will return 'true'
    }
  },

  // if used "subchart"
  subchart: {
    show: subchart()  // subchart() will return 'true'
  },

  // if used "zoom"
  zoom: {
    enabled: zoom() // zoom() will return 'true',
    type: "drag" (or 'wheel')
  }
});

4) Specify data.type/data.types for ESM import

If data.type option not specified, previously v1 treated as "line" type by default.

// v1
import bb from "billboard.js";

bb.generate({
  ...,
  data: {
    // There's no need to explicitly specify 'data.type' option for 'line'
    // type: "line",
  }
});

As of the changes in chart types modules(named exports), need specify explicitly data.type/data.types option value. (for UMD build, no need to. Only for importing as ESM)

// v2
import bb, {line} from "billboard.js";

bb.generate({
  ...,
  data: {
    /// Specify 'data.type' option value
    type: line(),
  }
});

If wants to use same as v1.x, import UMD build as follow.

NOTE: In this case will not get the beneficials of tree-shakes of unused code.

// v2 - import UMD build
import bb from "billboard.js/dist/billboard.js";

bb.generate({
  data: {
    ...
    type: "bar"
  }
});