dataAspectRatio: boolean | number, document and test

Author: Fil

README.md

@@ -206,7 +206,7 @@ Quantitative scales can be further customized with additional options:
 
 Clamping is typically used in conjunction with setting an explicit domain since if the domain is inferred, no values will be outside the domain. Clamping is useful for focusing on a subset of the data while ensuring that extreme values remain visible, but use caution: clamped values may need an annotation to avoid misinterpretation. Top-level **clamp**, **nice**, and **zero** options are supported as shorthand for setting the respective option on all scales.
 
-The top-level **daspect** option, if specified, computes a default height such that a variation of 1 unit in the *x* dimension roughly corresponds to the same number of pixels as a variation of *daspect* unit in the *y* dimension. Note: for an exact data aspect ratio, set *fx* and *fy*’s round option to false.
+The top-level **dataAspectRatio** option, if true, computes a default height such that a variation of one unit in the *x* dimension is represented by the same number of pixels as a variation in the *y* dimension of one unit—or *t* units if the option is specified as a positive number *t*. Note: when using facets, make sure to set *fx* and *fy*’s round option to false if you need an exact data aspect ratio.
 
 The *scale*.**transform** option allows you to apply a function to all values before they are passed through the scale. This is convenient for transforming a scale’s data, say to convert to thousands or between temperature units.
 

src/dimensions.js

@@ -12,8 +12,6 @@ export function Dimensions(
   },
   {
     width = 640,
-    daspect,
-    height,
     facet: {
       margin: facetMargin,
       marginTop: facetMarginTop = facetMargin !== undefined ? facetMargin : fxAxis === "top" ? 30 : 0,
@@ -25,12 +23,14 @@ export function Dimensions(
     marginTop = margin !== undefined ? margin : Math.max((xAxis === "top" ? 30 : 0) + facetMarginTop, yAxis || fyAxis ? 20 : 0.5 - offset),
     marginRight = margin !== undefined ? margin : Math.max((yAxis === "right" ? 40 : 0) + facetMarginRight, xAxis || fxAxis ? 20 : 0.5 + offset),
     marginBottom = margin !== undefined ? margin : Math.max((xAxis === "bottom" ? 30 : 0) + facetMarginBottom, yAxis || fyAxis ? 20 : 0.5 + offset),
-    marginLeft = margin !== undefined ? margin : Math.max((yAxis === "left" ? 40 : 0) + facetMarginLeft, xAxis || fxAxis ? 20 : 0.5 - offset)
+    marginLeft = margin !== undefined ? margin : Math.max((yAxis === "left" ? 40 : 0) + facetMarginLeft, xAxis || fxAxis ? 20 : 0.5 - offset),
+    dataAspectRatio,
+    height = autoHeight(scales, {width, marginLeft, marginRight, marginTop, marginBottom}, dataAspectRatio)
   } = {}
 ) {
   return {
     width,
-    height: height !== undefined ? height : autoHeight(scales, {width, marginLeft, marginRight, marginTop, marginBottom}, daspect),
+    height,
     marginTop,
     marginRight,
     marginBottom,
@@ -42,17 +42,17 @@ export function Dimensions(
   };
 }
 
-function autoHeight({x, y, fy, fx}, {width, marginLeft, marginRight, marginTop, marginBottom}, daspect) {
+function autoHeight({x, y, fy, fx}, {width, marginLeft, marginRight, marginTop, marginBottom}, dataAspectRatio) {
   const nfy = fy ? fy.scale.domain().length : 1;
   const ny = y ? (isOrdinalScale(y) ? y.scale.domain().length : Math.max(7, 17 / nfy)) : 1;
 
   // If a data aspect ratio is given, tweak the height to match
-  if (daspect != null && daspect !== false) {
-    if (!(isFinite(daspect) && daspect > 0)) throw new Error(`invalid data aspect ratio: ${daspect}`);
+  if (dataAspectRatio = +dataAspectRatio) {
+    if (!(isFinite(dataAspectRatio) && dataAspectRatio > 0)) throw new Error(`invalid data aspect ratio: ${dataAspectRatio}`);
     if (!["utc", "time", "linear"].includes(x?.type) || !["utc", "time", "linear"].includes(y?.type)) {
-      warn(`invalid x/y scale types for the daspect option: ${x?.type}/${y?.type}`);
+      warn(`invalid x/y scale types for the dataAspectRatio option: ${x?.type}/${y?.type}`);
     } else {
-      const ratio = Math.abs((y.domain[1] - y.domain[0]) / (x.domain[1] - x.domain[0]) / daspect);
+      const ratio = Math.abs((y.domain[1] - y.domain[0]) / (x.domain[1] - x.domain[0]) / dataAspectRatio);
       const trueWidth = (fx ? fx.scale.bandwidth() : 1) * (width - marginLeft - marginRight) - x.insetLeft - x.insetRight;
       return (ratio * trueWidth + y.insetTop + y.insetBottom) / (fy ? fy.scale.bandwidth() : 1) + marginTop + marginBottom;
     }