default paintOrder

README.md

@@ -1128,7 +1128,7 @@ 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.
+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*)
 

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

src/style.js

@@ -32,7 +32,8 @@ export function styles(
     strokeWidth: defaultStrokeWidth,
     strokeLinecap: defaultStrokeLinecap,
     strokeLinejoin: defaultStrokeLinejoin,
-    strokeMiterlimit: defaultStrokeMiterlimit
+    strokeMiterlimit: defaultStrokeMiterlimit,
+    paintOrder: defaultPaintOrder
   }
 ) {
 
@@ -73,6 +74,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/plots/metro-inequality-change.js

@@ -34,7 +34,6 @@ export default async function() {
         text: "nyt_display",
         fill: "black",
         stroke: "white",
-        strokeWidth: 4,
         dy: -8
       })
     ]