feature: legend navigation

docs/.vuepress/config.ts

@@ -34,18 +34,18 @@ export default defineConfig({
     }],
     ['vuepress-plugin-code-copy', true],
     ['vuepress-plugin-typedoc', {
-        entryPoints: ['../../src/types/index.d.ts'],
-        hideInPageTOC: true,
-        tsconfig: path.resolve(__dirname, '../../tsconfig.json'),
-      },
+      entryPoints: ['../../src/types/index.d.ts'],
+      hideInPageTOC: true,
+      tsconfig: path.resolve(__dirname, '../../tsconfig.json'),
+    },
     ],
     ['@simonbrunel/vuepress-plugin-versions', {
       filters: {
         suffix: (tag) => tag ? ` (${tag})` : '',
         title: (v, vars) => {
           return window.location.href.includes('master') ? 'Development (master)' :
-                 vars.tag === 'latest' ? 'Latest (' + v + ')' :
-                 v + (vars.tag ? ` (${vars.tag})` : '') + ' (outdated)';
+            vars.tag === 'latest' ? 'Latest (' + v + ')' :
+              v + (vars.tag ? ` (${vars.tag})` : '') + ' (outdated)';
         },
       },
       menu: {
@@ -219,6 +219,7 @@ export default defineConfig({
             'legend/point-style',
             'legend/position',
             'legend/title',
+            'legend/navigation'
           ]
         },
         {

docs/configuration/legend.md

@@ -26,6 +26,7 @@ The doughnut, pie, and polar area charts override the legend defaults. To change
 | `rtl` | `boolean` | | `true` for rendering the legends from right to left.
 | `textDirection` | `string` | canvas' default | This will force the text direction `'rtl'` or `'ltr'` on the canvas for rendering the legend, regardless of the css specified on the canvas
 | `title` | `object` | | See the [Legend Title Configuration](#legend-title-configuration) section below.
+| `navigation` | `object` | | Handle large sets of legends with pagination. [more...](#legend-navigation-configuration)
 
 :::tip Note
 If you need more visual customizations, please use an [HTML legend](../samples/legend/html.md).
@@ -86,6 +87,24 @@ Namespace: `options.plugins.legend.title`
 | `padding` | [`Padding`](../general/padding.md) | `0` | Padding around the title.
 | `text` | `string` | | The string title.
 
+## Legend Navigation Configuration
+
+Namespace: `options.plugins.legend.navigation`
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| `display` | `string`\|`boolean` | `false` | Show/hide legend navigation. If `auto` is used, the navigation will be shown only if the legend overflows.
+| `color` | [`Color`](../general/colors.md) | `Chart.defaults.color` | Color of the navigation page count label.
+| `activeColor` | [`Color`](../general/colors.md) | `Chart.defaults.color` | Color of active navigation arrows.
+| `inactiveColor` | [`Color`](../general/colors.md) | 40% opacity of the active color | Color of inactive navigation arrows.
+| `arrowSize` | `number` | `12` | Size of navigation arrows.
+| `maxCols` | `number` | `1` | Maximum number of columns, in vertical legends, for navigation to be activated.
+| `maxRows` | `number` | `3` | Maximum number of rows, in horizontal legends, for navigation to be activated.
+| `padding` | [`Padding`](../general/padding.md) | `{ x: 10, y: 10, top: 0 }` | Navigation buttons padding.
+| `align` | `string` | `'start'` | Alignment of navigation buttons. Possible options are `start`, `center` and `end`.
+| `grid` | `boolean`\|`object` | `true` | Align legends horizontally and vertically. Can be a `boolean` or an object containing `x` and `y` with boolean values ​​indicating whether the axis should be aligned.
+| `font` | `Font` | `{ weight: 'bold', size: 14 }` | Font style of the navigation page count label. See [Fonts](../general/fonts.md)
+
 ## Legend Item Interface
 
 Items passed to the legend `onClick` function are the ones returned from `labels.generateLabels`. These items must implement the following interface.

docs/samples/legend/navigation.md

@@ -0,0 +1,124 @@
+# Navigation
+
+This sample shows how to use legend navigation to handle overflow.
+
+```js chart-editor
+
+// <block:setup:1>
+const DATA_COUNT = 100;
+const NUMBER_CFG = {count: DATA_COUNT, decimals: 0};
+const LABEL_CFG = {count: DATA_COUNT, prefix: 'Group ', min: 1, max: DATA_COUNT + 1};
+
+const data = {
+  labels: Utils.labels(LABEL_CFG),
+  datasets: [{
+    label: '# of Votes',
+    data: Utils.numbers(NUMBER_CFG),
+    backgroundColor: Object.values(Utils.CHART_COLORS),
+  }]
+};
+// </block:setup>
+
+// <block:config:0>
+const config = {
+  type: 'pie',
+  data: data,
+  options: {
+    plugins: {
+      legend: {
+        position: 'right',
+        align: 'start',
+        title: {
+          display: true,
+          text: 'Chart.js Legend Navigation Example',
+          position: 'start',
+        },
+        navigation: {
+          display: 'auto',
+          maxCols: 1,
+          maxRows: 3,
+          arrowSize: 12,
+          align: 'start',
+          grid: true
+        }
+      },
+    }
+  }
+};
+// </block:config>
+
+// <block:actions:2>
+const actions = [
+  {
+    name: 'Toggle',
+    handler(chart) {
+      const {navigation} = chart.options.plugins.legend;
+      navigation.display = navigation.display ? false : 'auto';
+      chart.update();
+    }
+  },
+  {
+    name: '+ Label',
+    handler(chart) {
+      console.log(chart);
+      const lastLabel = chart.data.labels[chart.data.labels.length - 1] || '';
+      const lastIndex = +lastLabel.substring(6);
+      chart.data.labels.push(LABEL_CFG.prefix + (lastIndex + 1));
+      chart.update();
+    }
+  },
+  {
+    name: '- Label',
+    handler(chart) {
+      chart.data.labels.pop();
+      chart.update();
+    }
+  },
+  {
+    name: 'Position: left',
+    handler(chart) {
+      chart.options.plugins.legend.position = 'left';
+      chart.update();
+    }
+  },
+  {
+    name: 'Position: top',
+    handler(chart) {
+      chart.options.plugins.legend.position = 'top';
+      chart.update();
+    }
+  },
+  {
+    name: 'Position: right',
+    handler(chart) {
+      chart.options.plugins.legend.position = 'right';
+      chart.update();
+    }
+  },
+  {
+    name: 'Position: bottom',
+    handler(chart) {
+      chart.options.plugins.legend.position = 'bottom';
+      chart.update();
+    }
+  },
+  {
+    name: 'Toggle grid',
+    handler(chart) {
+      chart.options.plugins.legend.navigation.grid = !chart.options.plugins.legend.navigation.grid;
+      chart.update();
+    }
+  },
+];
+// </block:actions>
+
+module.exports = {
+  config,
+  actions
+};
+```
+
+## Docs
+* [Doughnut and Pie Charts](../../charts/doughnut.md)
+* [Legend](../../configuration/legend.md)
+  * [Navigation](../../configuration/legend.md#legend-navigation-configuration)