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

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.
 
+If the **stroke** option is specified, the **paintOrder** option defaults to stroke, and the **strokeWidth** option defaults to 3, making it easy to create a “halo” around text labels.
+
 #### 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

@@ -39,7 +39,10 @@ export class Text extends Mark {
         {name: "rotate", value: numberChannel(vrotate), optional: true},
         {name: "text", value: text, filter: nonempty}
       ],
-      options,
+      {
+        ...options.stroke && {paintOrder: "stroke", strokeWidth: 3},
+        ...options
+      },
       defaults
     );
     this.rotate = crotate;

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,9 @@ export default async function() {
         y: "R90_10_2015",
         filter: "highlight",
         text: "nyt_display",
+        fill: "black",
+        stroke: "white",
+        strokeWidth: 4,
         dy: -8
       })
     ]