Add x/y shorthand for padding options (#8637)

docs/docs/axes/labelling.md

@@ -15,7 +15,7 @@ Namespace: `options.scales[scaleId].title`, it defines options for the scale tit
 | `text` | `string`\|`string[]` | `''` | The text for the title. (i.e. "# of People" or "Response Choices").
 | `color` | [`Color`](../general/colors.md) | `Chart.defaults.color` | Color of label.
 | `font` | `Font` | `Chart.defaults.font` | See [Fonts](../general/fonts.md)
-| `padding` | `number`\|`object` | `4` | Padding to apply around scale labels. Only `top` and `bottom` are implemented.
+| `padding` | [`Padding`](../general/padding.md) | `4` | Padding to apply around scale labels. Only `top` and `bottom` are implemented.
 
 ## Creating Custom Tick Formats
 

docs/docs/axes/radial/linear.mdx

@@ -34,11 +34,11 @@ Namespace: `options.scales[scaleId].ticks`
 | Name | Type | Scriptable | Default | Description
 | ---- | ---- | ------- | ------- | -----------
 | `backdropColor` | [`Color`](../../general/colors.md) | Yes | `'rgba(255, 255, 255, 0.75)'` | Color of label backdrops.
-| `backdropPadding` | `number`\|`{top: number, bottom: number}` | | `2` | Padding of label backdrop.
-| `format` | `object` | | | The [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) options used by the default label formatter
-| `maxTicksLimit` | `number` | | `11` | Maximum number of ticks and gridlines to show.
-| `precision` | `number` | | | if defined and `stepSize` is not specified, the step size will be rounded to this many decimal places.
-| `stepSize` | `number` | | | User defined fixed step size for the scale. [more...](#step-size)
+| `backdropPadding` | [`Padding`](../../general/padding.md) | Yes | `2` | Padding of label backdrop.
+| `format` | `object` | Yes | | The [`Intl.NumberFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat) options used by the default label formatter
+| `maxTicksLimit` | `number` | Yes | `11` | Maximum number of ticks and gridlines to show.
+| `precision` | `number` | Yes | | if defined and `stepSize` is not specified, the step size will be rounded to this many decimal places.
+| `stepSize` | `number` | Yes | | User defined fixed step size for the scale. [more...](#step-size)
 | `showLabelBackdrop` | `boolean` | Yes | `true` | If true, draw a background behind the tick labels.
 
 <CommonTicksAll />
@@ -126,7 +126,7 @@ Namespace: `options.scales[scaleId].pointLabels`
 | Name | Type | Scriptable | Default | Description
 | ---- | ---- | ------- | ------- | -----------
 | `backdropColor` | [`Color`](../../general/colors.md) | `true` | `undefined` | Background color of the point label.
-| `backdropPadding` | `number`\|`{top: number, bottom: number}` | | `2` | Padding of label backdrop.
+| `backdropPadding` | [`Padding`](../../general/padding.md) | | `2` | Padding of label backdrop.
 | `display` | `boolean` | | `true` | if true, point labels are shown.
 | `callback` | `function` | | | Callback function to transform data labels to point labels. The default implementation simply returns the current string.
 | `color` | [`Color`](../../general/colors.md) | Yes | `Chart.defaults.color` | Color of label.

docs/docs/configuration/layout.md

@@ -6,27 +6,4 @@ Namespace: `options.layout`, the global options for the chart layout is defined
 
 | Name | Type | Default | [Scriptable](../general/options.md#scriptable-options) | Description
 | ---- | ---- | ------- | :----: | -----------
-| `padding` | `number`\|`object` | `0` | Yes | The padding to add inside the chart. [more...](#padding)
-
-## Padding
-
-If this value is a number, it is applied to all sides of the chart (left, top, right, bottom). If this value is an object, the `left` property defines the left padding. Similarly the `right`, `top` and `bottom` properties can also be specified.
-
-Lets say you wanted to add 50px of padding to the left side of the chart canvas, you would do:
-
-```javascript
-let chart = new Chart(ctx, {
-    type: 'line',
-    data: data,
-    options: {
-        layout: {
-            padding: {
-                left: 50,
-                right: 0,
-                top: 0,
-                bottom: 0
-            }
-        }
-    }
-});
-```
+| `padding` | [`Padding`](../general/padding.md) | `0` | Yes | The padding to add inside the chart.

docs/docs/configuration/legend.md

@@ -73,7 +73,7 @@ Namespace: `options.plugins.legend.title`
 | `color` | [`Color`](../general/colors.md) | `Chart.defaults.color` | Color of text.
 | `display` | `boolean` | `false` | Is the legend title displayed.
 | `font` | `Font` | `Chart.defaults.font` | See [Fonts](../general/fonts.md)
-| `padding` | `number`\|`object` | `0` | Padding around the title. If specified as a number, it applies evenly to all sides.
+| `padding` | [`Padding`](../general/padding.md) | `0` | Padding around the title.
 | `text` | `string` | | The string title.
 
 ## Legend Item Interface

docs/docs/configuration/title.md

@@ -16,7 +16,7 @@ Namespace: `options.plugins.title`, the global options for the chart title is de
 | `fullSize` | `boolean` | `true` | Marks that this box should take the full width/height of the canvas. If `false`, the box is sized and placed above/beside the chart area.
 | `position` | `string` | `'top'` | Position of title. [more...](#position)
 | `font` | `Font` | `{style: 'bold'}` | See [Fonts](../general/fonts.md)
-| `padding` | `number`\|`{top: number, bottom: number}` | `10` | Adds padding above and below the title text if a single number is specified. It is also possible to change top and bottom padding separately.
+| `padding` | [`Padding`](../general/padding.md) | `10` | Padding to apply around the title. Only `top` and `bottom` are implemented.
 | `text` | `string`\|`string[]` | `''` | Title text to display. If specified as an array, text is rendered on multiple lines.
 
 ### Position

docs/docs/configuration/tooltip.md

@@ -31,7 +31,7 @@ Namespace: `options.plugins.tooltip`, the global options for the chart tooltips
 | `footerAlign` | `string` | `'left'` | Horizontal alignment of the footer text lines. [more...](#alignment)
 | `footerSpacing` | `number` | `2` | Spacing to add to top and bottom of each footer line.
 | `footerMarginTop` | `number` | `6` | Margin to add before drawing the footer.
-| `padding` | | `6` | Padding inside the tooltip on the 4 sides
+| `padding` | [`Padding`](../general/padding.md) | `6` | Padding inside the tooltip.
 | `caretPadding` | `number` | `2` | Extra distance to move the end of the tooltip arrow away from the tooltip point.
 | `caretSize` | `number` | `5` | Size, in px, of the tooltip arrow.
 | `cornerRadius` | `number` | `6` | Radius of tooltip corner curves.

docs/docs/general/padding.md

@@ -0,0 +1,68 @@
+---
+title: Padding
+---
+
+Padding values in Chart options can be supplied in couple of different formats.
+
+### Number
+
+If this value is a number, it is applied to all sides (left, top, right, bottom).
+
+For exmaple, defining a 20px padding to all sides of chart:
+
+```javascript
+let chart = new Chart(ctx, {
+    type: 'line',
+    data: data,
+    options: {
+        layout:
+            padding: 20
+        }
+    }
+});
+```
+
+### {top, left, bottom, right} object
+
+If this value is an object, the `left` property defines the left padding. Similarly the `right`, `top` and `bottom` properties can also be specified.
+Omitted properties default to `0`.
+
+Lets say you wanted to add 50px of padding to the left side of the chart canvas, you would do:
+
+```javascript
+let chart = new Chart(ctx, {
+    type: 'line',
+    data: data,
+    options: {
+        layout: {
+            padding: {
+                left: 50
+            }
+        }
+    }
+});
+```
+
+### {x, y} object
+
+This is a shorthand for defining left/right and top/bottom to same values.
+
+For example, 10px left / right and 4px top / bottom padding on a Radial Linear Axis [tick backdropPadding](../axes/radial/linear#tick-configuration):
+
+```javascript
+let chart = new Chart(ctx, {
+    type: 'radar',
+    data: data,
+    options: {
+        scales: {
+          r: {
+            ticks: {
+              backdropPadding: {
+                  x: 10,
+                  y: 4
+              }
+            }
+        }
+    }
+});
+```

docs/sidebars.js

@@ -17,6 +17,7 @@ module.exports = {
       'general/options',
       'general/colors',
       'general/fonts',
+      'general/padding',
       'general/performance'
     ],
     Configuration: [

src/helpers/helpers.options.js

@@ -38,11 +38,13 @@ export function toLineHeight(value, size) {
 }
 
 const numberOrZero = v => +v || 0;
+const numberOrZero2 = (v1, v2) => numberOrZero(valueOrDefault(v1, v2));
 
 /**
  * Converts the given value into a TRBL object.
  * @param {number|object} value - If a number, set the value to all TRBL component,
  *  else, if an object, use defined properties and sets undefined ones to 0.
+ *  x / y are shorthands for same value for left/right and top/bottom.
  * @returns {object} The padding values (top, right, bottom, left)
  * @since 3.0.0
  */
@@ -50,10 +52,11 @@ export function toTRBL(value) {
   let t, r, b, l;
 
   if (isObject(value)) {
-    t = numberOrZero(value.top);
-    r = numberOrZero(value.right);
-    b = numberOrZero(value.bottom);
-    l = numberOrZero(value.left);
+    const {x, y} = value;
+    t = numberOrZero2(value.top, y);
+    r = numberOrZero2(value.right, x);
+    b = numberOrZero2(value.bottom, y);
+    l = numberOrZero2(value.left, x);
   } else {
     t = r = b = l = numberOrZero(value);
   }
@@ -97,6 +100,7 @@ export function toTRBLCorners(value) {
  * Converts the given value into a padding object with pre-computed width/height.
  * @param {number|object} value - If a number, set the value to all TRBL component,
  *  else, if an object, use defined properties and sets undefined ones to 0.
+ *  x / y are shorthands for same value for left/right and top/bottom.
  * @returns {object} The padding values (top, right, bottom, left, width, height)
  * @since 2.7.0
  */

test/specs/helpers.options.tests.js

@@ -95,6 +95,14 @@ describe('Chart.helpers.options', function() {
       expect(toPadding(undefined)).toEqual(
         {top: 0, right: 0, bottom: 0, left: 0, height: 0, width: 0});
     });
+    it('should support x / y shorthands', function() {
+      expect(toPadding({x: 1, y: 2})).toEqual(
+        {top: 2, right: 1, bottom: 2, left: 1, height: 4, width: 2});
+      expect(toPadding({x: 1, left: 0})).toEqual(
+        {top: 0, right: 1, bottom: 0, left: 0, height: 0, width: 1});
+      expect(toPadding({y: 5, bottom: 0})).toEqual(
+        {top: 5, right: 0, bottom: 0, left: 0, height: 5, width: 0});
+    });
   });
 
   describe('toFont', function() {

types/helpers/helpers.options.d.ts

@@ -28,7 +28,7 @@ export function toLineHeight(value: string, size: number): number;
  * @since 2.7.0
  */
 export function toPadding(
-	value?: number | { top?: number; left?: number; right?: number; bottom?: number }
+  value?: number | { top?: number; left?: number; right?: number; bottom?: number; x?:number, y?: number }
 ): { top: number; left: number; right: number; bottom: number; width: number; height: number };
 
 /**