Documentation and type definitions for zoomFunctions and panFunctions (…

…#534) * Add type definitions for `zoomFunctions` and `panFunctions` * Add documentation for zoomFunctions and panFunctions * Update docs/guide/developers.md Co-authored-by: Jukka Kurkela <[email protected]> Co-authored-by: Jukka Kurkela <[email protected]>
chartjs · Jun 2, 2021 · 33ba619 · 33ba619
1 parent bb7b8fc
commit 33ba619
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 5 deletions.
diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
@@ -75,6 +75,7 @@ module.exports = {
         'usage',
         'options',
         'animations',
+        'developers',
       ],
       '/samples/': [
         'basic',

diff --git a/docs/guide/developers.md b/docs/guide/developers.md
@@ -0,0 +1,29 @@
+# Developers
+
+You can extend chartjs-plugin-zoom with support for [custom scales](https://www.chartjs.org/docs/latest/developers/axes.html) by using the zoom plugin's `zoomFunctions` and `panFunctions` members. These objects are indexed by scale types (scales' `id` members) and give optional handlers for zoom and pan functionality.
+
+```js
+import {Scale} from 'chart.js';
+import zoomPlugin from 'chartjs-plugin-zoom';
+
+class MyScale extends Scale {
+  /* extensions ... */
+}
+MyScale.id = 'myScale';
+MyScale.defaults = defaultConfigObject;
+
+zoomPlugin.zoomFunctions.myScale = (scale, zoom, center, limits) => false;
+zoomPlugin.panFunctions.myScale = (scale, delta, limits) => false;
+```
+
+The zoom and pan functions take the following arguments:
+
+| Name | Type | For | Description
+| ---- | ---- | --- | ----------
+| `scale` | `Scale` | Zoom, Pan | The custom scale instance (usually derived from `Chart.Scale`)
+| `zoom` | `number` | Zoom | The zoom fraction; 1.0 is unzoomed, 0.5 means zoomed in to 50% of the original area, etc.
+| `center` | `{x, y}` | Zoom | Pixel coordinates of the center of the zoom operation. `{x: 0, y: 0}` is the upper left corner of the chart's canvas.
+| `pan` | `number` | Pan | Pixel amount to pan by
+| `limits` | [Limits](./options#limits) | Zoom, Pan | Zoom and pan limits (from chart options)
+
+For examples, see chartjs-plugin-zoom's [default zoomFunctions and panFunctions handling for standard Chart.js axes](https://github.com/chartjs/chartjs-plugin-zoom/blob/v1.0.1/src/scale.types.js#L128).
diff --git a/types/index.d.ts b/types/index.d.ts
@@ -1,15 +1,15 @@
-import { Plugin, ChartType, Chart, Scale, UpdateMode } from 'chart.js';
+import { Plugin, ChartType, Chart, Scale, UpdateMode, ScaleTypeRegistry } from 'chart.js';
 import { DistributiveArray } from 'chart.js/types/utils';
-import { ZoomPluginOptions } from './options';
+import { LimitOptions, ZoomPluginOptions } from './options';
 
 type Point = { x: number, y: number };
 type ZoomAmount = number | Partial<Point> & { focalPoint?: Point };
 type PanAmount = number | Partial<Point>;
 type ScaleRange = { min: number, max: number };
 
 declare module 'chart.js' {
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	interface PluginOptionsByType<TType extends ChartType> {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface PluginOptionsByType<TType extends ChartType> {
     zoom: ZoomPluginOptions;
   }
 
@@ -26,7 +26,19 @@ declare module 'chart.js' {
   }
 }
 
-declare const Zoom: Plugin;
+export type ZoomFunction = (scale: Scale, zoom: number, center: Point, limits: LimitOptions) => boolean;
+export type PanFunction = (scale: Scale, delta: number, limits: LimitOptions) => boolean;
+
+type ScaleFunctions<T> = {
+  [scaleType in keyof ScaleTypeRegistry]?: T | undefined;
+} & {
+  default: T;
+};
+
+declare const Zoom: Plugin & {
+  zoomFunctions: ScaleFunctions<ZoomFunction>;
+  panFunctions: ScaleFunctions<PanFunction>;
+};
 
 export default Zoom;