bug #870 [ChartJs] Adding a better way to register Chartjs plugins (weaverryan)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

[ChartJs] Adding a better way to register Chartjs plugins

| Q             | A
| ------------- | ---
| Bug fix?      | yes
| New feature?  | yes, but in order to fix a bug
| Tickets       | Fix #867 Fix #754 Fix #598 Fix #167
| License       | MIT

The previous method, in npm (and likely in the native browser via importmaps) the Chart would always be imported into the Chartjs UX controller before your userland code would run to register the plugin.

Cheers!

Commits
-------

ab5f111 [ChartJs] Adding a better way to register Chartjs plugins

Author: weaverryan

src/Chartjs/assets/dist/controller.js

@@ -1,20 +1,30 @@
 import { Controller } from '@hotwired/stimulus';
 import Chart from 'chart.js/auto';
 
+let isChartInitialized = false;
 class default_1 extends Controller {
     constructor() {
         super(...arguments);
         this.chart = null;
     }
     connect() {
+        if (!isChartInitialized) {
+            isChartInitialized = true;
+            this.dispatchEvent('init', {
+                Chart,
+            });
+        }
         if (!(this.element instanceof HTMLCanvasElement)) {
             throw new Error('Invalid element');
         }
         const payload = this.viewValue;
         if (Array.isArray(payload.options) && 0 === payload.options.length) {
             payload.options = {};
         }
-        this.dispatchEvent('pre-connect', { options: payload.options });
+        this.dispatchEvent('pre-connect', {
+            options: payload.options,
+            config: payload,
+        });
         const canvasContext = this.element.getContext('2d');
         if (!canvasContext) {
             throw new Error('Could not getContext() from Element');

src/Chartjs/assets/src/controller.ts

@@ -12,6 +12,8 @@
 import { Controller } from '@hotwired/stimulus';
 import Chart from 'chart.js/auto';
 
+let isChartInitialized = false;
+
 export default class extends Controller {
     declare readonly viewValue: any;
 
@@ -22,6 +24,13 @@ export default class extends Controller {
     private chart: Chart | null = null;
 
     connect() {
+        if (!isChartInitialized) {
+            isChartInitialized = true;
+            this.dispatchEvent('init', {
+                Chart,
+            });
+        }
+
         if (!(this.element instanceof HTMLCanvasElement)) {
             throw new Error('Invalid element');
         }
@@ -31,7 +40,10 @@ export default class extends Controller {
             payload.options = {};
         }
 
-        this.dispatchEvent('pre-connect', { options: payload.options });
+        this.dispatchEvent('pre-connect', {
+            options: payload.options,
+            config: payload,
+        });
 
         const canvasContext = this.element.getContext('2d');
         if (!canvasContext) {

src/Chartjs/assets/test/controller.test.ts

@@ -13,9 +13,18 @@ import { Application } from '@hotwired/stimulus';
 import { waitFor } from '@testing-library/dom';
 import ChartjsController from '../src/controller';
 
+// Kept track of globally, but just used in one test.
+// This is because, by the time that test has run, it is likely that the
+// chartjs:init event has already been dispatched. So, we capture it out here.
+let initCallCount = 0;
+
 const startChartTest = async (canvasHtml: string): Promise<{ canvas: HTMLCanvasElement, chart: Chart }> => {
     let chart: Chart | null = null;
 
+    document.body.addEventListener('chartjs:init', () => {
+        initCallCount++;
+    });
+
     document.body.addEventListener('chartjs:pre-connect', () => {
         document.body.classList.add('pre-connected');
     });
@@ -95,4 +104,51 @@ describe('ChartjsController', () => {
             expect(chart.options.showLines).toBe(true);
         });
     });
+
+    it('dispatches the events correctly', async () => {
+        let preConnectCallCount = 0;
+        let preConnectDetail: any = null;
+
+        document.body.addEventListener('chartjs:pre-connect', (event: any) => {
+            preConnectCallCount++;
+            preConnectDetail = event.detail;
+        });
+
+        await startChartTest(`
+            <canvas
+                data-testid="canvas"
+                data-controller="chartjs"
+                data-chartjs-view-value="&#x7B;&quot;type&quot;&#x3A;&quot;line&quot;,&quot;data&quot;&#x3A;&#x7B;&quot;labels&quot;&#x3A;&#x5B;&quot;January&quot;,&quot;February&quot;,&quot;March&quot;,&quot;April&quot;,&quot;May&quot;,&quot;June&quot;,&quot;July&quot;&#x5D;,&quot;datasets&quot;&#x3A;&#x5B;&#x7B;&quot;label&quot;&#x3A;&quot;My&#x20;First&#x20;dataset&quot;,&quot;backgroundColor&quot;&#x3A;&quot;rgb&#x28;255,&#x20;99,&#x20;132&#x29;&quot;,&quot;borderColor&quot;&#x3A;&quot;rgb&#x28;255,&#x20;99,&#x20;132&#x29;&quot;,&quot;data&quot;&#x3A;&#x5B;0,10,5,2,20,30,45&#x5D;&#x7D;&#x5D;&#x7D;,&quot;options&quot;&#x3A;&#x7B;&quot;showLines&quot;&#x3A;false&#x7D;&#x7D;"
+            ></canvas>
+        `);
+        expect(initCallCount).toBe(1);
+        expect(preConnectCallCount).toBe(1);
+        expect(preConnectDetail.options.showLines).toBe(false);
+        expect(preConnectDetail.config.type).toBe('line');
+        expect(preConnectDetail.config.data.datasets[0].data).toEqual([0, 10, 5, 2, 20, 30, 45]);
+
+        // add a second chart!
+        const canvas = document.createElement('canvas');
+        canvas.dataset.controller = 'chartjs';
+        canvas.dataset.chartjsViewValue = JSON.stringify({
+            type: 'line',
+            data: {
+                labels: ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
+                datasets: [{
+                    label: 'My First dataset',
+                    backgroundColor: 'rgb(255, 99, 132)',
+                    borderColor: 'rgb(255, 99, 132)',
+                    data: [0, 10, 5, 2, 20, 30, 45],
+                }],
+            },
+            options: {
+                showLines: false,
+            },
+        });
+        document.body.appendChild(canvas);
+
+        await waitFor(() => expect(preConnectCallCount).toBe(2));
+        // still only initialized once
+        expect(initCallCount).toBe(1);
+    });
 });

src/Chartjs/doc/index.rst

@@ -98,18 +98,20 @@ First, install the plugin:
     $ npm install chartjs-plugin-zoom -D
 
     # or use yarn
-    $ yarn add chartjs-plugin-zoom -dev
+    $ yarn add chartjs-plugin-zoom --dev
 
 Then register the plugin globally. This can be done in your ``app.js`` file:
 
 .. code-block:: javascript
 
     // assets/app.js
-
-    import { Chart } from 'chart.js';
     import zoomPlugin from 'chartjs-plugin-zoom';
 
-    Chart.register(zoomPlugin);
+    // register globally for all charts
+    document.addEventListener('chartjs:init', function (event) {
+        const Chart = event.detail.Chart;
+        Chart.register(zoomPlugin);
+    });
 
     // ...
 
@@ -177,10 +179,11 @@ custom Stimulus controller:
 
         _onPreConnect(event) {
             // The chart is not yet created
-            console.log(event.detail.options); // You can access the chart options using the event details
+            // You can access the config that will be passed to "new Chart()"
+            console.log(event.detail.config);
 
             // For instance you can format Y axis
-            event.detail.options.scales = {
+            event.detail.config.options.scales = {
                 yAxes: [
                     {
                         ticks: {
@@ -213,6 +216,24 @@ Then in your render call, add your controller as an HTML attribute:
 
     {{ render_chart(chart, {'data-controller': 'mychart'}) }}
 
+There is also a ``chartjs:init`` event that is called just *one* time before your
+first chart is rendered. That's an ideal place to `register plugins globally <Using Plugins>`_
+or make other changes to any "static"/global part of Chart.js. For example,
+to add a global `Tooltip positioner`_:
+
+.. code-block:: javascript
+
+    // assets/app.js
+
+    // register globally for all charts
+    document.addEventListener('chartjs:init', function (event) {
+        const Chart = event.detail.Chart;
+        const Tooltip = Chart.registry.plugins.get('tooltip');
+        Tooltip.positioners.bottom = function(items) {
+            /* ... */
+        };
+    });
+
 Backward Compatibility promise
 ------------------------------
 
@@ -228,3 +249,4 @@ the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html
 .. _`a lot of plugins`: https://github.com/chartjs/awesome#plugins
 .. _`zoom plugin`: https://www.chartjs.org/chartjs-plugin-zoom/latest/
 .. _`zoom plugin documentation`: https://www.chartjs.org/chartjs-plugin-zoom/latest/guide/integration.html
+.. _`Tooltip positioner`: https://www.chartjs.org/docs/latest/samples/tooltip/position.html