make it easier to create a text halo (#703)

* make it easier to create a text halo by defaulting paintOrder to stroke and strokeWidth to 3 if the stroke option is specified.
supersedes #667
closes #666

* default paintOrder

* currentColor, not black

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

README.md

@@ -1128,6 +1128,8 @@ The **fontSize** and **rotate** options can be specified as either channels or c
 
 If the **frameAnchor** option is not specified, then **textAnchor** and **lineAnchor** default to middle. Otherwise, **textAnchor** defaults to start if **frameAnchor** is on the left, end if **frameAnchor** is on the right, and otherwise middle. Similarly, **lineAnchor** defaults to top if **frameAnchor** is on the top, bottom if **frameAnchor** is on the bottom, and otherwise middle.
 
+The **paintOrder** option defaults to “stroke” and the **strokeWidth** option defaults to 3. By setting **fill** to the foreground color and **stroke** to the background color (such as black and white, respectively), you can surround text with a “halo” which may improve legibility against a busy background.
+
 #### Plot.text(*data*, *options*)
 
 Returns a new text mark with the given *data* and *options*. If neither the **x** nor **y** nor **frameAnchor** options are specified, *data* is assumed to be an array of pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …].

src/marks/text.js

@@ -6,7 +6,9 @@ import {Mark} from "../plot.js";
 import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyAttr, applyTransform, offset, impliedString, applyFrameAnchor} from "../style.js";
 
 const defaults = {
-  strokeLinejoin: "round"
+  strokeLinejoin: "round",
+  strokeWidth: 3,
+  paintOrder: "stroke"
 };
 
 export class Text extends Mark {

src/style.js

@@ -32,7 +32,8 @@ export function styles(
     strokeWidth: defaultStrokeWidth,
     strokeLinecap: defaultStrokeLinecap,
     strokeLinejoin: defaultStrokeLinejoin,
-    strokeMiterlimit: defaultStrokeMiterlimit
+    strokeMiterlimit: defaultStrokeMiterlimit,
+    paintOrder: defaultPaintOrder
   }
 ) {
 
@@ -75,6 +76,10 @@ export function styles(
     if (strokeLinecap === undefined) strokeLinecap = defaultStrokeLinecap;
     if (strokeLinejoin === undefined) strokeLinejoin = defaultStrokeLinejoin;
     if (strokeMiterlimit === undefined) strokeMiterlimit = defaultStrokeMiterlimit;
+
+    // The paint order only takes effect if there is both a fill and a stroke
+    // (at least if we ignore markers, which no built-in marks currently use).
+    if (cfill !== "none" && paintOrder === undefined) paintOrder = defaultPaintOrder;
   }
 
   const [vstrokeWidth, cstrokeWidth] = maybeNumberChannel(strokeWidth);

test/output/carsParcoords.svg

@@ -37,8 +37,7 @@ export default async function() {
     marks: [
       Plot.ruleY(dimensions),
       Plot.line(data, {...xy, z: "name", stroke: "#444", strokeWidth: 0.5, strokeOpacity: 0.5}),
-      Plot.text(ticks, {...xy, fill: null, stroke: "white", strokeWidth: 3, strokeLinejoin: "round", text: "value"}),
-      Plot.text(ticks, {...xy, text: "value"})
+      Plot.text(ticks, {...xy, text: "value", fill: "black", stroke: "white"})
     ]
   });
 }

test/output/metroInequalityChange.svg

@@ -32,6 +32,8 @@ export default async function() {
         y: "R90_10_2015",
         filter: "highlight",
         text: "nyt_display",
+        fill: "currentColor",
+        stroke: "white",
         dy: -8
       })
     ]