Option to show an explicit label for swatches

Note: the scale’s label is not shown for swatches, since most of the time it is obvious from the context

Author: Fil

README.md

@@ -509,7 +509,8 @@ mylegend = myplot.legend("color")
 
 Categorical and ordinal color legends are rendered as swatches, unless *options*.**legend** is set to *ramp*. The swatches can be configured with the following options:
 
-* *options*.**tickFormat** - a format function for the labels
+* *options*.**tickFormat** - a format function for the domain values
+* *options*.**label** - explicit label for the legend—by default, no label is shown
 * *options*.**swatchSize** - the size of the swatch (if square)
 * *options*.**swatchWidth** - the swatches’ width
 * *options*.**swatchHeight** - the swatches’ height

src/legends.js

@@ -27,7 +27,7 @@ export function exposeLegends(scales, defaults = {}) {
 }
 
 function legendOptions({label, ticks, tickFormat} = {}, options = {}) {
-  return {label, ticks, tickFormat, ...options};
+  return {label, ticks, tickFormat, ...options, explicitLabel: options.label != null};
 }
 
 export function Legends(scales, options) {

src/legends/swatches.js

@@ -7,7 +7,8 @@ export function legendSwatches(color, {
   columns,
   tickFormat,
   fontVariant = inferFontVariant(color),
-  // TODO label,
+  explicitLabel,
+  label,
   swatchSize = 15,
   swatchWidth = swatchSize,
   swatchHeight = swatchSize,
@@ -26,6 +27,13 @@ export function legendSwatches(color, {
         --swatchHeight: ${+swatchHeight}px;
       `);
 
+  const palette = explicitLabel
+      ? swatches.call(div => div.append("p")
+          .text(label)
+          .style("font-weight", "bold"))
+        .append("div")
+      : swatches;
+
   let extraStyle;
 
   if (columns != null) {
@@ -46,7 +54,7 @@ export function legendSwatches(color, {
       }
     `;
 
-    swatches
+    palette
         .style("columns", columns)
       .selectAll()
       .data(color.domain)
@@ -72,8 +80,7 @@ export function legendSwatches(color, {
       }
     `;
 
-    swatches
-      .selectAll()
+    palette.selectAll()
       .data(color.domain)
       .join("span")
         .attr("class", `${className}-swatch`)
@@ -102,4 +109,4 @@ export function legendSwatches(color, {
       .style("font-variant", impliedString(fontVariant, "normal"))
       .call(applyInlineStyles, style)
     .node();
-}
+}

test/output/colorLegendCategoricalColumns.html

@@ -1,4 +1,7 @@
-<div class="plot" style="--swatchWidth: 15px; --swatchHeight: 15px; columns: 180px;">
+<div class="plot" style="
+        --swatchWidth: 15px;
+        --swatchHeight: 15px;
+      ">
   <style>
     .plot {
       font-family: system-ui, sans-serif;
@@ -32,34 +35,37 @@
       text-overflow: ellipsis;
     }
   </style>
-  <div class="plot-swatch" style="--color: #4e79a7;">
-    <div class="plot-label" title="Wholesale and Retail Trade">Wholesale and Retail Trade</div>
-  </div>
-  <div class="plot-swatch" style="--color: #f28e2c;">
-    <div class="plot-label" title="Manufacturing">Manufacturing</div>
-  </div>
-  <div class="plot-swatch" style="--color: #e15759;">
-    <div class="plot-label" title="Leisure and hospitality">Leisure and hospitality</div>
-  </div>
-  <div class="plot-swatch" style="--color: #76b7b2;">
-    <div class="plot-label" title="Business services">Business services</div>
-  </div>
-  <div class="plot-swatch" style="--color: #59a14f;">
-    <div class="plot-label" title="Construction">Construction</div>
-  </div>
-  <div class="plot-swatch" style="--color: #edc949;">
-    <div class="plot-label" title="Education and Health">Education and Health</div>
-  </div>
-  <div class="plot-swatch" style="--color: #af7aa1;">
-    <div class="plot-label" title="Government">Government</div>
-  </div>
-  <div class="plot-swatch" style="--color: #ff9da7;">
-    <div class="plot-label" title="Finance">Finance</div>
-  </div>
-  <div class="plot-swatch" style="--color: #9c755f;">
-    <div class="plot-label" title="Self-employed">Self-employed</div>
-  </div>
-  <div class="plot-swatch" style="--color: #bab0ab;">
-    <div class="plot-label" title="Other">Other</div>
+  <p style="font-weight: bold;">Industry</p>
+  <div style="columns: 180px;">
+    <div class="plot-swatch" style="--color: #4e79a7;">
+      <div class="plot-label" title="Wholesale and Retail Trade">Wholesale and Retail Trade</div>
+    </div>
+    <div class="plot-swatch" style="--color: #f28e2c;">
+      <div class="plot-label" title="Manufacturing">Manufacturing</div>
+    </div>
+    <div class="plot-swatch" style="--color: #e15759;">
+      <div class="plot-label" title="Leisure and hospitality">Leisure and hospitality</div>
+    </div>
+    <div class="plot-swatch" style="--color: #76b7b2;">
+      <div class="plot-label" title="Business services">Business services</div>
+    </div>
+    <div class="plot-swatch" style="--color: #59a14f;">
+      <div class="plot-label" title="Construction">Construction</div>
+    </div>
+    <div class="plot-swatch" style="--color: #edc949;">
+      <div class="plot-label" title="Education and Health">Education and Health</div>
+    </div>
+    <div class="plot-swatch" style="--color: #af7aa1;">
+      <div class="plot-label" title="Government">Government</div>
+    </div>
+    <div class="plot-swatch" style="--color: #ff9da7;">
+      <div class="plot-label" title="Finance">Finance</div>
+    </div>
+    <div class="plot-swatch" style="--color: #9c755f;">
+      <div class="plot-label" title="Self-employed">Self-employed</div>
+    </div>
+    <div class="plot-swatch" style="--color: #bab0ab;">
+      <div class="plot-label" title="Other">Other</div>
+    </div>
   </div>
 </div>

test/plots/legend-color.js

@@ -21,7 +21,7 @@ export function colorLegendCategoricalColumns() {
         "Other"
       ]
     },
-    label: "Hello",
+    label: "Industry",
     columns: "180px"
   });
 }