asymmetric insets (#567)

* asymmetric insets

* document

* test asymmetric insets

* Update README

* revert asymmetric inset tests

Co-authored-by: Philippe Rivière <[email protected]>

Author: mbostock

README.md

@@ -225,7 +225,17 @@ The position scales (*x*, *y*, *fx*, and *fy*) support additional options:
 * *scale*.**inset** - inset the default range by the specified amount in pixels
 * *scale*.**round** - round the output value to the nearest integer (whole pixel)
 
-The *scale*.inset option can provide “breathing room” to separate marks from axes or the plot’s edge. For example, in a scatterplot with a Plot.dot with the default 3-pixel radius and 1.5-pixel stroke width, an inset of 5 pixels prevents dots from overlapping with the axes. The *scale*.round option is useful for crisp edges by rounding to the nearest pixel boundary.
+The *x* scale supports asymmetric insets for more precision. Replace inset by:
+
+* *scale*.**insetLeft** - insets the start of the default range by the specified number of pixels
+* *scale*.**insetRight** - insets the end of the default range by the specified number of pixels
+
+Similarly, the *y* scale supports asymmetric insets with:
+
+* *scale*.**insetTop** - insets the top of the default range by the specified number of pixels
+* *scale*.**insetBottom** - insets the bottom of the default range by the specified number of pixels
+
+The inset scale options can provide “breathing room” to separate marks from axes or the plot’s edge. For example, in a scatterplot with a Plot.dot with the default 3-pixel radius and 1.5-pixel stroke width, an inset of 5 pixels prevents dots from overlapping with the axes. The *scale*.round option is useful for crisp edges by rounding to the nearest pixel boundary.
 
 In addition to the generic *ordinal* scale type, which requires an explicit output range value for each input domain value, Plot supports special *point* and *band* scale types for encoding ordinal data as position. These scale types accept a [*min*, *max*] range similar to quantitative scales, and divide this continuous interval into discrete points or bands based on the number of distinct values in the domain (*i.e.*, the domain’s cardinality). If the associated marks have no effective width along the ordinal dimension — such as a dot, rule, or tick — then use a *point* scale; otherwise, say for a bar, use a *band* scale. In the image below, the top *x*-scale is a *point* scale while the bottom *x*-scale is a *band* scale; see [Plot: Scales](https://observablehq.com/@observablehq/plot-scales) for an interactive version.
 

src/scales.js

@@ -7,27 +7,51 @@ import {ScaleTime, ScaleUtc} from "./scales/temporal.js";
 import {ScaleOrdinal, ScalePoint, ScaleBand} from "./scales/ordinal.js";
 import {isOrdinal, isTemporal} from "./mark.js";
 
-export function Scales(channels, {inset, round, nice, align, padding, ...options} = {}) {
+export function Scales(channels, {
+  inset: globalInset = 0,
+  insetTop: globalInsetTop = globalInset,
+  insetRight: globalInsetRight = globalInset,
+  insetBottom: globalInsetBottom = globalInset,
+  insetLeft: globalInsetLeft = globalInset,
+  round,
+  nice,
+  align,
+  padding,
+  ...options
+} = {}) {
   const scales = {};
   for (const key of registry.keys()) {
     const scaleChannels = channels.get(key);
     const scaleOptions = options[key];
     if (scaleChannels || scaleOptions) {
       const scale = Scale(key, scaleChannels, {
-        inset: key === "x" || key === "y" ? inset : undefined, // not for facet
         round: registry.get(key) === position ? round : undefined, // only for position
         nice,
         align,
         padding,
         ...scaleOptions
       });
       if (scale) {
-        if (scaleOptions) { // populate generic scale options (percent, transform)
-          let {percent, transform} = scaleOptions;
-          if (transform == null) transform = undefined;
-          else if (typeof transform !== "function") throw new Error("invalid scale transform");
-          scale.percent = !!percent;
-          scale.transform = transform;
+        // populate generic scale options (percent, transform, insets)
+        let {
+          percent,
+          transform,
+          inset,
+          insetTop = inset !== undefined ? inset : key === "y" ? globalInsetTop : 0, // not fy
+          insetRight = inset !== undefined ? inset : key === "x" ? globalInsetRight : 0, // not fx
+          insetBottom = inset !== undefined ? inset : key === "y" ? globalInsetBottom : 0, // not fy
+          insetLeft = inset !== undefined ? inset : key === "x" ? globalInsetLeft : 0 // not fx
+        } = scaleOptions || {};
+        if (transform == null) transform = undefined;
+        else if (typeof transform !== "function") throw new Error("invalid scale transform");
+        scale.percent = !!percent;
+        scale.transform = transform;
+        if (key === "x" || key === "fx") {
+          scale.insetLeft = +insetLeft;
+          scale.insetRight = +insetRight;
+        } else if (key === "y" || key === "fy") {
+          scale.insetTop = +insetTop;
+          scale.insetBottom = +insetBottom;
         }
         scales[key] = scale;
       }
@@ -46,9 +70,9 @@ export function autoScaleRange({x, y, fx, fy}, dimensions) {
 
 function autoScaleRangeX(scale, dimensions) {
   if (scale.range === undefined) {
-    const {inset = 0} = scale;
+    const {insetLeft, insetRight} = scale;
     const {width, marginLeft = 0, marginRight = 0} = dimensions;
-    scale.range = [marginLeft + inset, width - marginRight - inset];
+    scale.range = [marginLeft + insetLeft, width - marginRight - insetRight];
     if (!isOrdinalScale(scale)) scale.range = piecewiseRange(scale);
     scale.scale.range(scale.range);
   }
@@ -57,9 +81,9 @@ function autoScaleRangeX(scale, dimensions) {
 
 function autoScaleRangeY(scale, dimensions) {
   if (scale.range === undefined) {
-    const {inset = 0} = scale;
+    const {insetTop, insetBottom} = scale;
     const {height, marginTop = 0, marginBottom = 0} = dimensions;
-    scale.range = [height - marginBottom - inset, marginTop + inset];
+    scale.range = [height - marginBottom - insetBottom, marginTop + insetTop];
     if (isOrdinalScale(scale)) scale.range.reverse();
     else scale.range = piecewiseRange(scale);
     scale.scale.range(scale.range);

src/scales/ordinal.js

@@ -8,19 +8,17 @@ export function ScaleO(scale, channels, {
   type,
   domain = inferDomain(channels),
   range,
-  reverse,
-  inset = 0
+  reverse
 }) {
   if (type === "categorical") type = "ordinal"; // shorthand for color schemes
   if (reverse) domain = reverseof(domain);
-  inset = +inset;
   scale.domain(domain);
   if (range !== undefined) {
     // If the range is specified as a function, pass it the domain.
     if (typeof range === "function") range = range(domain);
     scale.range(range);
   }
-  return {type, domain, range, scale, inset};
+  return {type, domain, range, scale};
 }
 
 export function ScaleOrdinal(key, channels, {

src/scales/quantitative.js

@@ -58,12 +58,10 @@ export function ScaleQ(key, scale, channels, {
   scheme,
   range = registry.get(key) === radius ? inferRadialRange(channels, domain) : registry.get(key) === opacity ? unit : undefined,
   interpolate = registry.get(key) === color ? (scheme == null && range !== undefined ? interpolateRgb : quantitativeScheme(scheme !== undefined ? scheme : type === "cyclical" ? "rainbow" : "turbo")) : round ? interpolateRound : interpolateNumber,
-  reverse,
-  inset = 0
+  reverse
 }) {
   if (type === "cyclical" || type === "sequential") type = "linear"; // shorthand for color schemes
   reverse = !!reverse;
-  inset = +inset;
 
   // Sometimes interpolate is a named interpolator, such as "lab" for Lab color
   // space. Other times interpolate is a function that takes two arguments and
@@ -106,7 +104,7 @@ export function ScaleQ(key, scale, channels, {
   if (nice) scale.nice(nice === true ? undefined : nice);
   if (range !== undefined) scale.range(range);
   if (clamp) scale.clamp(clamp);
-  return {type, domain, range, scale, interpolate, inset};
+  return {type, domain, range, scale, interpolate};
 }
 
 export function ScaleLinear(key, channels, options) {