Add Export Chart Helpers (#2)

README.md

@@ -314,6 +314,66 @@ $chart = Chart::make('test-chart')
     });
 ```
 
+### Exporting a chart
+
+Each chart will listen to the `export-chart` event on the `window` object. By triggering this with the appropriate
+details, any chart can be exported either from JavaScript or from Livewire.
+
+The detail object must contain the `chartId` and `type` keys. The `chartId` must match the key you used when building
+the chart. The `type` must be a valid type for the Highcharts `exportChartLocal` method.
+
+The `exportSettings` can take an object with settings for the export per the Highcharts `exportChartLocal` method.
+The `options` take an object with chart options to customize the chart before exporting.
+
+The following example shows how to export a chart from JavaScript:
+
+```js
+window.dispatchEvent(new CustomEvent('export-chart', {
+    detail: {
+        chartId: 'test-chart',
+        type: 'image/png',
+        exportSettings: {}, // Optional.
+        options: {}, // Optional.
+    }
+}));
+```
+
+Using Livewire, you can either use the `dispatch` method, or use the bundled `ExportsChart` trait.
+
+```php
+
+// Using the trait.
+use BernskioldMedia\LaravelHighcharts\Concerns\Livewire\ExportsChart;
+
+$this->exportChart(
+    type: 'image/png',
+    chartKey: 'test-chart',
+    exportSettings: [], // Optional.
+    options: [], // Optional.
+);
+
+// Using Livewire 3's dispatch method.
+$this->dispatch(
+    'exportChart',
+    chartId: 'test-chart',
+    type: 'image/png',
+    exportSettings: [], // Optional.
+    options: [], // Optional.
+);
+```
+
+If you are using the `ExportsChart` trait, you can also customize the export settings and options by adding the 
+the `getChartExportSettings` and ? `getChartOptionsForExport` methods to your Livewire component. To ensure their signature,
+we suggest implementing the bundled `CustomizesChartExportOptions` and `CustomizesChartExportSettings` interfaces.
+
+If you are using the trait on the same component as the `InteractsWithChart` trait you don't have to provide the chart key, and can use the minimal syntax:
+
+```php
+use BernskioldMedia\LaravelHighcharts\Concerns\Livewire\ExportsChart;
+
+$this->exportChart('image/png');
+```
+
 ## Testing
 
 ```bash

src/Concerns/Livewire/ExportsChart.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace BernskioldMedia\LaravelHighcharts\Concerns\Livewire;
+
+use BernskioldMedia\LaravelHighcharts\Exceptions\ChartExportException;
+use function method_exists;
+
+trait ExportsChart
+{
+
+    /**
+     * @throws ChartExportException
+     */
+    public function exportChart(string $type, ?string $chartKey = null, array $exportSettings = [], array $chartOptions = []): void
+    {
+        if ($chartKey === null && property_exists($this, 'chartKey')) {
+            $chartKey = $this->chartKey;
+        }
+
+        if ($chartKey === null) {
+            throw ChartExportException::missingChartKey();
+        }
+
+        if (method_exists($this, 'getChartExportSettings')) {
+            $exportSettings = array_merge(
+                $this->getChartExportSettings(),
+                $exportSettings
+            );
+        }
+
+        if (method_exists($this, 'getChartOptionsForExport')) {
+            $chartOptions = array_merge(
+                $this->getChartOptionsForExport(),
+                $chartOptions
+            );
+        }
+
+        // Livewire 3.
+        if (method_exists($this, 'dispatch')) {
+            $this->dispatch(
+                'exportChart',
+                chartId: $chartKey,
+                type: $type,
+                exportSettings: $exportSettings,
+                options: $chartOptions,
+            );
+
+            return;
+        }
+
+        // Livewire 2.
+        if (method_exists($this, 'emit')) {
+            $this->emit('exportChart', [
+                'chartId' => $chartKey,
+                'type' => $type,
+                'exportSettings' => $exportSettings,
+                'options' => $chartOptions,
+            ]);
+        }
+    }
+}

src/Contracts/CustomizesChartExportOptions.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace BernskioldMedia\LaravelHighcharts\Contracts;
+
+interface CustomizesChartExportOptions
+{
+
+    public function getChartOptionsForExport(): array;
+
+}

src/Contracts/CustomizesChartExportSettings.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace BernskioldMedia\LaravelHighcharts\Contracts;
+
+interface CustomizesChartExportSettings
+{
+
+    public function getChartExportSettings(): array;
+
+}

src/Exceptions/ChartExportException.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace BernskioldMedia\LaravelHighcharts\Exceptions;
+
+use Exception;
+
+class ChartExportException extends Exception
+{
+
+    public static function missingChartKey(): self
+    {
+        return new static('The chart key is missing. Please provide a chart key to the exportChart() method or set a chartKey property on the component.');
+    }
+}