custom format redux

Author: mbostock

src/marks/tip.d.ts

@@ -1,4 +1,4 @@
-import type {ChannelName, ChannelValue, ChannelValueSpec} from "../channel.js";
+import type {ChannelName, ChannelValueSpec} from "../channel.js";
 import type {Data, FrameAnchor, MarkOptions, RenderableMark} from "../mark.js";
 import type {TextStyles} from "./text.js";
 
@@ -62,29 +62,8 @@ export interface TipOptions extends MarkOptions, TextStyles {
    */
   anchor?: FrameAnchor;
 
-  /**
-   * The format option controls what the tip shows; either a function which is
-   * passed the datum d and zero-based index i and returns a string or an
-   * iterable of formatted tip items, or an iterable of channel names or values
-   * and optionally how to label and format them.
-   */
-  format?: ((d: any, i: number) => string | Iterable<TipItem>) | Iterable<ChannelName | ChannelValue | TipFormatItem>;
-}
-
-/** Shorthand for formatting channels and values. */
-export interface TipFormatItem {
-  label?: string;
-  value?: ChannelValue;
-  channel?: ChannelName;
-  format?: (d: any, i: number) => string;
-}
-
-/** A formatted line item to show in a tip. */
-export interface TipItem {
-  label?: string;
-  value?: string;
-  color?: string;
-  opacity?: number;
+  /** How channel values are formatted for display. */
+  format?: {[name in ChannelName]?: string | ((d: any, i: number) => string)};
 }
 
 /**

src/marks/tip.js

@@ -1,4 +1,4 @@
-import {select, format as numberFormat} from "d3";
+import {select, format as numberFormat, utcFormat} from "d3";
 import {getSource} from "../channel.js";
 import {create} from "../context.js";
 import {defined} from "../defined.js";
@@ -7,7 +7,7 @@ import {anchorX, anchorY} from "../interactions/pointer.js";
 import {Mark} from "../mark.js";
 import {maybeAnchor, maybeFrameAnchor, maybeTuple, number, string} from "../options.js";
 import {applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, impliedString} from "../style.js";
-import {identity, isIterable, isTextual, labelof, maybeValue} from "../options.js";
+import {identity, isIterable, isTemporal, isTextual} from "../options.js";
 import {inferTickFormat} from "./axis.js";
 import {applyIndirectTextStyles, defaultWidth, ellipsis, monospaceWidth} from "./text.js";
 import {cut, clipper, splitter, maybeTextOverflow} from "./text.js";
@@ -83,7 +83,7 @@ export class Tip extends Mark {
     for (const key in defaults) if (key in this.channels) this[key] = defaults[key]; // apply default even if channel
     this.splitLines = splitter(this);
     this.clipLine = clipper(this);
-    this.format = maybeTipFormat(this.channels, format);
+    this.format = {...format}; // defensive copy, and promote nullish to empty
   }
   render(index, scales, values, dimensions, context) {
     const mark = this;
@@ -116,11 +116,24 @@ export class Tip extends Mark {
     const widthof = monospace ? monospaceWidth : defaultWidth;
     const ee = widthof(ellipsis);
 
+    // Initialize shorthand formats. TODO Don’t mutate.
+    for (const key in this.format) {
+      const format = this.format[key];
+      if (typeof format === "string" && key in sources) {
+        this.format[key] = (isTemporal(sources[key].value) ? utcFormat : numberFormat)(format);
+      }
+    }
+
+    // Initialize default formats for the facet scales. TODO Don’t mutate.
+    if (index.fi != null) {
+      const {fx, fy} = scales;
+      if (fx && this.format.fx === undefined) this.format.fx = inferTickFormat(fx, fx.domain());
+      if (fy && this.format.fy === undefined) this.format.fy = inferTickFormat(fy, fy.domain());
+    }
+
     // Determine the appropriate formatter.
     const format =
-      this.format !== undefined
-        ? this.format // use the custom format, if any
-        : "title" in sources // if there is a title channel
+      "title" in sources // if there is a title channel
         ? formatTitle // display the title as-is
         : index.fi == null // if this mark is not faceted
         ? formatChannels // display name-value pairs for channels
@@ -173,8 +186,7 @@ export class Tip extends Mark {
     // exact text metrics and translate the text as needed once we know the
     // tip’s orientation (anchor).
     function renderLine(selection, {label, value, color, opacity}) {
-      label ??= ""; // TODO fix earlier?
-      value ??= ""; // TODO fix earlier?
+      (label ??= ""), (value ??= "");
       const swatch = color != null || opacity != null;
       let title;
       let w = lineWidth * 100;
@@ -318,60 +330,9 @@ function getSources({channels}) {
   return sources;
 }
 
-// Note: mutates channels!
-function maybeTipFormat(channels, format) {
-  if (format === undefined) return;
-  if (typeof format === "function") {
-    return function (i, index, channels, scales, {data}) {
-      return format.call(this, data[i], i);
-    };
-  }
-  format = Array.from(format, (f) => maybeTipFormatItem(f, channels));
-  return function* (i, index, channels, scales, values) {
-    for (let {label, channel: key, format: formatValue} of format) {
-      if (label === undefined) label = formatLabel(scales, channels, key);
-      if (key === "fx" || key === "fy") {
-        if (formatValue === undefined) formatValue = inferTickFormat(scales[key]); // TODO optimize
-        yield {
-          label,
-          value: formatValue(index[key])
-        };
-      } else {
-        if (formatValue === undefined) formatValue = formatDefault;
-        const channel = channels[key];
-        const scale = channel.scale;
-        yield {
-          label,
-          value: formatValue(channel.value[i]),
-          color: scale === "color" ? values[key][i] : null,
-          opacity: scale === "opacity" ? values[key][i] : null
-        };
-      }
-    }
-  };
-}
-
-// Note: mutates channels!
-function maybeTipFormatItem(f, channels) {
-  if (typeof f === "string") f = {channel: f}; // shorthand channel name
-  f = maybeValue(f); // shorthand function, array, etc.
-  if (typeof f.format === "string") f = {...f, format: numberFormat(f.format)}; // shorthand format; TODO dates
-  if (f.value !== undefined) f = {...f, channel: deriveChannel(channels, f)}; // shorthand channel
-  return f;
-}
-
-let nextTipId = 0;
-
-// Note: mutates channels!
-function deriveChannel(channels, f) {
-  const key = `--tip-${++nextTipId}`; // TODO better anonymous channels
-  const {value, label = labelof(value) ?? ""} = f;
-  channels[key] = {label, value, filter: null};
-  return key;
-}
-
 function formatTitle(i, index, {title}) {
-  return formatDefault(title.value[i]);
+  const format = this.format?.title;
+  return format === null ? [] : (format ?? formatDefault)(title.value[i]);
 }
 
 function* formatChannels(i, index, channels, scales, values) {
@@ -380,22 +341,28 @@ function* formatChannels(i, index, channels, scales, values) {
     if (key === "y1" && "y2" in channels) continue;
     const channel = channels[key];
     if (key === "x2" && "x1" in channels) {
+      const format = this.format?.x; // TODO x1, x2?
+      if (format === null) continue;
       yield {
         label: formatPairLabel(scales, channels, "x"),
-        value: formatPair(channels.x1, channel, i)
+        value: formatPair(format ?? formatDefault, channels.x1, channel, i)
       };
     } else if (key === "y2" && "y1" in channels) {
+      const format = this.format?.y; // TODO y1, y2?
+      if (format === null) continue;
       yield {
         label: formatPairLabel(scales, channels, "y"),
-        value: formatPair(channels.y1, channel, i)
+        value: formatPair(format ?? formatDefault, channels.y1, channel, i)
       };
     } else {
+      const format = this.format?.[key];
+      if (format === null) continue;
       const value = channel.value[i];
       const scale = channel.scale;
-      if (!defined(value) && scale == null) return;
+      if (!defined(value) && scale == null) continue;
       yield {
         label: formatLabel(scales, channels, key),
-        value: formatDefault(value),
+        value: (format ?? formatDefault)(value),
         color: scale === "color" ? values[key][i] : null,
         opacity: scale === "opacity" ? values[key][i] : null
       };
@@ -404,25 +371,22 @@ function* formatChannels(i, index, channels, scales, values) {
 }
 
 function* formatFacetedChannels(i, index, channels, scales, values) {
-  yield* formatChannels(i, index, channels, scales, values);
-  if (scales.fx) {
-    yield {
-      label: formatLabel(scales, channels, "fx"),
-      value: inferTickFormat(scales.fx)(index.fx) // TODO optimize
-    };
-  }
-  if (scales.fy) {
+  yield* formatChannels.call(this, i, index, channels, scales, values);
+  for (const key of ["fx", "fy"]) {
+    if (!scales[key]) return;
+    const format = this.format?.[key];
+    if (format === null) continue;
     yield {
-      label: formatLabel(scales, channels, "fy"),
-      value: inferTickFormat(scales.fy)(index.fy) // TODO optimize
+      label: formatLabel(scales, channels, key),
+      value: (format ?? formatDefault)(index[key])
     };
   }
 }
 
-function formatPair(c1, c2, i) {
+function formatPair(formatValue, c1, c2, i) {
   return c2.hint?.length // e.g., stackY’s y1 and y2
-    ? `${formatDefault(c2.value[i] - c1.value[i])}`
-    : `${formatDefault(c1.value[i])}–${formatDefault(c2.value[i])}`;
+    ? `${formatValue(c2.value[i] - c1.value[i])}`
+    : `${formatValue(c1.value[i])}–${formatValue(c2.value[i])}`;
 }
 
 function formatPairLabel(scales, channels, key) {