introduce spacingMode

Author: danielgindi

src/controllers/controller.doughnut.js

@@ -71,12 +71,15 @@ export default class DoughnutController extends DatasetController {
     // Spacing between arcs
     spacing: 0,
 
+    // Geometry used to apply spacing between arcs
+    spacingMode: 'angular',
+
     indexAxis: 'r',
   };
 
   static descriptors = {
-    _scriptable: (name) => name !== 'spacing',
-    _indexable: (name) => name !== 'spacing' && !name.startsWith('borderDash') && !name.startsWith('hoverBorderDash'),
+    _scriptable: (name) => name !== 'spacing' && name !== 'spacingMode',
+    _indexable: (name) => name !== 'spacing' && name !== 'spacingMode' && !name.startsWith('borderDash') && !name.startsWith('hoverBorderDash'),
   };
 
   /**
@@ -279,8 +282,7 @@ export default class DoughnutController extends DatasetController {
         endAngle: startAngle + circumference,
         circumference,
         outerRadius,
-        innerRadius,
-        circular: false
+        innerRadius
       };
       if (includeOptions) {
         properties.options = sharedOptions || this.resolveDataElementOptions(i, arc.active ? 'active' : mode);

src/controllers/controller.polarArea.js

@@ -22,6 +22,8 @@ export default class PolarAreaController extends DatasetController {
     },
     indexAxis: 'r',
     startAngle: 0,
+    spacing: 0,
+    spacingMode: 'proportional',
   };
 
   /**
@@ -196,10 +198,17 @@ export default class PolarAreaController extends DatasetController {
         outerRadius,
         startAngle,
         endAngle,
-        circular: true,
         options: this.resolveDataElementOptions(i, arc.active ? 'active' : mode)
       };
 
+      // Arc defaults (`spacing=0`, `spacingMode='angular'`) can mask polarArea-level values.
+      if (properties.options.spacing === 0) {
+        properties.options.spacing = this.options.spacing;
+      }
+      if (properties.options.spacingMode === 'angular') {
+        properties.options.spacingMode = this.options.spacingMode;
+      }
+
       this.updateElement(arc, i, properties, mode);
     }
   }

src/elements/element.arc.ts

@@ -122,12 +122,18 @@ function pathArc(
   circular: boolean,
 ) {
   const {x, y, startAngle: start, pixelMargin, innerRadius: innerR} = element;
+  const {spacingMode = 'angular'} = element.options;
 
   const outerRadius = Math.max(element.outerRadius + spacing + offset - pixelMargin, 0);
-  const innerRadius = innerR > 0 ? innerR + spacing + offset + pixelMargin : 0;
+  let innerRadius = innerR > 0 ? innerR + spacing + offset + pixelMargin : 0;
 
-  let spacingOffset = 0;
+  let outerSpacingOffset = 0;
+  let innerSpacingOffset = 0;
   const alpha = end - start;
+  const beta = outerRadius > 0
+    ? Math.max(0.001, alpha * outerRadius - offset / PI) / outerRadius
+    : 0.001;
+  const angleOffset = (alpha - beta) / 2;
 
   if (spacing) {
     // When spacing is present, it is the same for all items
@@ -136,29 +142,63 @@ function pathArc(
     const noSpacingInnerRadius = innerR > 0 ? innerR - spacing : 0;
     const noSpacingOuterRadius = outerRadius > 0 ? outerRadius - spacing : 0;
     const avgNoSpacingRadius = (noSpacingInnerRadius + noSpacingOuterRadius) / 2;
-    if (circular && avgNoSpacingRadius > 0) {
-      spacingOffset = Math.asin(Math.min(1, spacing / avgNoSpacingRadius));
-    } else {
+    const proportionalOffset = (() => {
       const adjustedAngle = avgNoSpacingRadius !== 0 ? (alpha * avgNoSpacingRadius) / (avgNoSpacingRadius + spacing) : alpha;
-      spacingOffset = (alpha - adjustedAngle) / 2;
+      return (alpha - adjustedAngle) / 2;
+    })();
+    const angularOffset = avgNoSpacingRadius > 0 ? Math.asin(Math.min(1, spacing / avgNoSpacingRadius)) : 0;
+
+    // Keep spacing trims below half the available span after base offset trimming.
+    const maxOffset = Math.max(0, beta / 2 - 0.001);
+    const maxOffsetSin = Math.sin(maxOffset);
+
+    if (spacingMode === 'parallel') {
+      if (innerRadius === 0 && maxOffsetSin > 0) {
+        // A root radius of zero cannot realize a non-zero parallel separator width.
+        // Raise the root just enough for the available angular span.
+        const minInnerRadius = spacing / maxOffsetSin;
+        const maxInnerRadius = Math.max(0, outerRadius - 0.001);
+        innerRadius = Math.min(minInnerRadius, maxInnerRadius);
+      }
+
+      // Use one bounded spacing value for both radii so large spacing keeps stable geometry.
+      const maxParallelSpacing = Math.min(
+        outerRadius > 0 ? outerRadius * maxOffsetSin : Number.POSITIVE_INFINITY,
+        innerRadius > 0 ? innerRadius * maxOffsetSin : Number.POSITIVE_INFINITY
+      );
+      const parallelSpacing = Math.min(spacing, maxParallelSpacing);
+
+      outerSpacingOffset = outerRadius > 0
+        ? Math.asin(Math.min(1, parallelSpacing / outerRadius))
+        : Math.min(maxOffset, angularOffset);
+      innerSpacingOffset = innerRadius > 0
+        ? Math.asin(Math.min(1, parallelSpacing / innerRadius))
+        : outerSpacingOffset;
+    } else if (spacingMode === 'proportional') {
+      outerSpacingOffset = Math.min(maxOffset, proportionalOffset);
+      innerSpacingOffset = Math.min(maxOffset, proportionalOffset);
+    } else {
+      outerSpacingOffset = Math.min(maxOffset, angularOffset);
+      innerSpacingOffset = Math.min(maxOffset, angularOffset);
     }
   }
 
-  const beta = Math.max(0.001, alpha * outerRadius - offset / PI) / outerRadius;
-  const angleOffset = (alpha - beta) / 2;
-  const startAngle = start + angleOffset + spacingOffset;
-  const endAngle = end - angleOffset - spacingOffset;
-  const {outerStart, outerEnd, innerStart, innerEnd} = parseBorderRadius(element, innerRadius, outerRadius, endAngle - startAngle);
+  const outerStartAngle = start + angleOffset + outerSpacingOffset;
+  const outerEndAngle = end - angleOffset - outerSpacingOffset;
+  const innerStartAngle = start + angleOffset + innerSpacingOffset;
+  const innerEndAngle = end - angleOffset - innerSpacingOffset;
+  const angleDelta = Math.min(outerEndAngle - outerStartAngle, innerEndAngle - innerStartAngle);
+  const {outerStart, outerEnd, innerStart, innerEnd} = parseBorderRadius(element, innerRadius, outerRadius, angleDelta);
 
   const outerStartAdjustedRadius = outerRadius - outerStart;
   const outerEndAdjustedRadius = outerRadius - outerEnd;
-  const outerStartAdjustedAngle = startAngle + outerStart / outerStartAdjustedRadius;
-  const outerEndAdjustedAngle = endAngle - outerEnd / outerEndAdjustedRadius;
+  const outerStartAdjustedAngle = outerStartAngle + outerStart / outerStartAdjustedRadius;
+  const outerEndAdjustedAngle = outerEndAngle - outerEnd / outerEndAdjustedRadius;
 
   const innerStartAdjustedRadius = innerRadius + innerStart;
   const innerEndAdjustedRadius = innerRadius + innerEnd;
-  const innerStartAdjustedAngle = startAngle + innerStart / innerStartAdjustedRadius;
-  const innerEndAdjustedAngle = endAngle - innerEnd / innerEndAdjustedRadius;
+  const innerStartAdjustedAngle = innerStartAngle + innerStart / innerStartAdjustedRadius;
+  const innerEndAdjustedAngle = innerEndAngle - innerEnd / innerEndAdjustedRadius;
 
   ctx.beginPath();
 
@@ -171,38 +211,38 @@ function pathArc(
     // The corner segment from point 2 to point 3
     if (outerEnd > 0) {
       const pCenter = rThetaToXY(outerEndAdjustedRadius, outerEndAdjustedAngle, x, y);
-      ctx.arc(pCenter.x, pCenter.y, outerEnd, outerEndAdjustedAngle, endAngle + HALF_PI);
+      ctx.arc(pCenter.x, pCenter.y, outerEnd, outerEndAdjustedAngle, outerEndAngle + HALF_PI);
     }
 
     // The line from point 3 to point 4
-    const p4 = rThetaToXY(innerEndAdjustedRadius, endAngle, x, y);
+    const p4 = rThetaToXY(innerEndAdjustedRadius, innerEndAngle, x, y);
     ctx.lineTo(p4.x, p4.y);
 
     // The corner segment from point 4 to point 5
     if (innerEnd > 0) {
       const pCenter = rThetaToXY(innerEndAdjustedRadius, innerEndAdjustedAngle, x, y);
-      ctx.arc(pCenter.x, pCenter.y, innerEnd, endAngle + HALF_PI, innerEndAdjustedAngle + Math.PI);
+      ctx.arc(pCenter.x, pCenter.y, innerEnd, innerEndAngle + HALF_PI, innerEndAdjustedAngle + Math.PI);
     }
 
     // The inner arc from point 5 to point b to point 6
-    const innerMidAdjustedAngle = ((endAngle - (innerEnd / innerRadius)) + (startAngle + (innerStart / innerRadius))) / 2;
-    ctx.arc(x, y, innerRadius, endAngle - (innerEnd / innerRadius), innerMidAdjustedAngle, true);
-    ctx.arc(x, y, innerRadius, innerMidAdjustedAngle, startAngle + (innerStart / innerRadius), true);
+    const innerMidAdjustedAngle = ((innerEndAngle - (innerEnd / innerRadius)) + (innerStartAngle + (innerStart / innerRadius))) / 2;
+    ctx.arc(x, y, innerRadius, innerEndAngle - (innerEnd / innerRadius), innerMidAdjustedAngle, true);
+    ctx.arc(x, y, innerRadius, innerMidAdjustedAngle, innerStartAngle + (innerStart / innerRadius), true);
 
     // The corner segment from point 6 to point 7
     if (innerStart > 0) {
       const pCenter = rThetaToXY(innerStartAdjustedRadius, innerStartAdjustedAngle, x, y);
-      ctx.arc(pCenter.x, pCenter.y, innerStart, innerStartAdjustedAngle + Math.PI, startAngle - HALF_PI);
+      ctx.arc(pCenter.x, pCenter.y, innerStart, innerStartAdjustedAngle + Math.PI, innerStartAngle - HALF_PI);
     }
 
     // The line from point 7 to point 8
-    const p8 = rThetaToXY(outerStartAdjustedRadius, startAngle, x, y);
+    const p8 = rThetaToXY(outerStartAdjustedRadius, outerStartAngle, x, y);
     ctx.lineTo(p8.x, p8.y);
 
     // The corner segment from point 8 to point 1
     if (outerStart > 0) {
       const pCenter = rThetaToXY(outerStartAdjustedRadius, outerStartAdjustedAngle, x, y);
-      ctx.arc(pCenter.x, pCenter.y, outerStart, startAngle - HALF_PI, outerStartAdjustedAngle);
+      ctx.arc(pCenter.x, pCenter.y, outerStart, outerStartAngle - HALF_PI, outerStartAdjustedAngle);
     }
   } else {
     ctx.moveTo(x, y);
@@ -315,6 +355,7 @@ export default class ArcElement extends Element<ArcProps, ArcOptions> {
     borderWidth: 2,
     offset: 0,
     spacing: 0,
+    spacingMode: 'angular',
     angle: undefined,
     circular: true,
     selfJoin: false,

src/types/index.d.ts

@@ -274,11 +274,20 @@ export interface DoughnutControllerDatasetOptions
   weight: number;
 
   /**
-   * Similar to the `offset` option, but applies to all arcs. This can be used to to add spaces
-   * between arcs
-   * @default 0
-   */
+    * Similar to the `offset` option, but applies to all arcs. This can be used to to add spaces
+    * between arcs
+    * @default 0
+    */
   spacing: number;
+
+  /**
+    * Geometry used to apply arc spacing.
+    * - `proportional`: legacy behavior (default for polarArea).
+    * - `angular`: constant angular trim (default for doughnut/pie).
+    * - `parallel`: separate inner/outer trims for constant-width separators (best for small-moderate spacings).
+    * @default 'angular'
+    */
+  spacingMode: ArcSpacingMode;
 }
 
 export interface DoughnutAnimationOptions extends AnimationSpec<'doughnut'> {
@@ -327,11 +336,20 @@ export interface DoughnutControllerChartOptions {
   rotation: number;
 
   /**
-   * Spacing between the arcs
-   * @default 0
-   */
+    * Spacing between the arcs
+    * @default 0
+    */
   spacing: number;
 
+  /**
+    * Geometry used to apply arc spacing.
+    * - `proportional`: legacy behavior (default for polarArea).
+    * - `angular`: constant angular trim (default for doughnut/pie).
+    * - `parallel`: separate inner/outer trims for constant-width separators (best for small-moderate spacings).
+    * @default 'angular'
+    */
+  spacingMode: ArcSpacingMode;
+
   animation: false | DoughnutAnimationOptions;
 }
 
@@ -386,6 +404,18 @@ export interface PolarAreaControllerChartOptions {
    */
   startAngle: number;
 
+  /**
+   * Spacing between the arcs
+   * @default 0
+   */
+  spacing: number;
+
+  /**
+   * Geometry used to apply arc spacing.
+   * @default 'proportional'
+   */
+  spacingMode: ArcSpacingMode;
+
   animation: false | PolarAreaAnimationOptions;
 }
 
@@ -1847,6 +1877,8 @@ export interface ArcBorderRadius {
   innerEnd: number;
 }
 
+export type ArcSpacingMode = 'proportional' | 'angular' | 'parallel';
+
 export interface ArcOptions extends CommonElementOptions {
   /**
    * If true, Arc can take up 100% of a circular graph without any visual split or cut. This option doesn't support borderRadius and borderJoinStyle miter
@@ -1893,7 +1925,20 @@ export interface ArcOptions extends CommonElementOptions {
   /**
    * Spacing between arcs
    */
-  spacing: number
+  spacing: number;
+
+  /**
+   * Geometry used to apply arc spacing. Only applies to chart types with arc elements (doughnut, pie, polarArea).
+   * Radar charts use line elements and do not support arc spacing modes.
+   *
+   * - `proportional`: keeps the legacy proportional spacing behavior.
+   * - `angular`: applies a constant angular trim based on average radius.
+   * - `parallel`: applies separate inner/outer trims to keep separator width constant.
+   *   Works best for small to moderate spacings. For very large spacings, the offset is capped
+   *   to prevent arc angle reversals.
+   * @default 'angular'
+   */
+  spacingMode: ArcSpacingMode;
 }
 
 export interface ArcHoverOptions extends CommonHoverOptions {

test/specs/controller.doughnut.tests.js

@@ -46,7 +46,7 @@ describe('Chart.controllers.doughnut', function() {
     expect(meta.data[3] instanceof Chart.elements.ArcElement).toBe(true);
   });
 
-  it('should mark arcs as non-circular', function() {
+  it('should default arc spacingMode to angular', function() {
     var chart = window.acquireChart({
       type: 'doughnut',
       data: {
@@ -58,8 +58,8 @@ describe('Chart.controllers.doughnut', function() {
     });
 
     var meta = chart.getDatasetMeta(0);
-    expect(meta.data[0].circular).toBe(false);
-    expect(meta.data[1].circular).toBe(false);
+    expect(meta.data[0].options.spacingMode).toBe('angular');
+    expect(meta.data[1].options.spacingMode).toBe('angular');
   });
 
   it ('should reset and update elements', function() {

test/specs/controller.polarArea.tests.js

@@ -66,7 +66,7 @@ describe('Chart.controllers.polarArea', function() {
     expect(meta.data[3] instanceof Chart.elements.ArcElement).toBe(true);
   });
 
-  it('should mark arcs as circular', function() {
+  it('should default arc spacingMode to proportional', function() {
     var chart = window.acquireChart({
       type: 'polarArea',
       data: {
@@ -78,8 +78,30 @@ describe('Chart.controllers.polarArea', function() {
     });
 
     var meta = chart.getDatasetMeta(0);
-    expect(meta.data[0].circular).toBe(true);
-    expect(meta.data[1].circular).toBe(true);
+    expect(meta.data[0].options.spacingMode).toBe('proportional');
+    expect(meta.data[1].options.spacingMode).toBe('proportional');
+  });
+
+  it('should respect chart-level spacingMode override', function() {
+    var chart = window.acquireChart({
+      type: 'polarArea',
+      data: {
+        datasets: [{
+          data: [10, 20]
+        }],
+        labels: ['a', 'b']
+      },
+      options: {
+        spacing: 12,
+        spacingMode: 'parallel'
+      }
+    });
+
+    var meta = chart.getDatasetMeta(0);
+    expect(meta.data[0].options.spacingMode).toBe('parallel');
+    expect(meta.data[1].options.spacingMode).toBe('parallel');
+    expect(meta.data[0].options.spacing).toBe(12);
+    expect(meta.data[1].options.spacing).toBe(12);
   });
 
   it('should draw all elements', function() {