custom format option

Author: mbostock

src/marks/tip.d.ts

@@ -61,6 +61,22 @@ export interface TipOptions extends MarkOptions, TextStyles {
    * the right of the anchor position.
    */
   anchor?: FrameAnchor;
+
+  /**
+   * A custom format function specifying what the tip shows. This function is
+   * passed the datum d and zero-based index i for each tip. It may return
+   * either a string, an object of name-value pairs, or an iterable of {name,
+   * value, color, opacity} objects.
+   */
+  format?: (d: any, i: number) => string | {[name: string]: string} | Iterable<TipItem>;
+}
+
+/** A formatted line item to show in a tip. */
+export interface TipItem {
+  name?: string;
+  value?: string;
+  color?: string;
+  opacity?: number;
 }
 
 /**

src/marks/tip.js

@@ -5,9 +5,9 @@ import {defined} from "../defined.js";
 import {formatDefault} from "../format.js";
 import {anchorX, anchorY} from "../interactions/pointer.js";
 import {Mark} from "../mark.js";
-import {maybeAnchor, maybeFrameAnchor, maybeTuple, number, string} from "../options.js";
+import {maybeAnchor, maybeFrameAnchor, maybeFunction, maybeTuple, number, string} from "../options.js";
 import {applyDirectStyles, applyFrameAnchor, applyIndirectStyles, applyTransform, impliedString} from "../style.js";
-import {identity, isIterable, isTextual} from "../options.js";
+import {identity, isIterable, isTextual, isObject} from "../options.js";
 import {inferTickFormat} from "./axis.js";
 import {applyIndirectTextStyles, defaultWidth, ellipsis, monospaceWidth} from "./text.js";
 import {cut, clipper, splitter, maybeTextOverflow} from "./text.js";
@@ -42,6 +42,7 @@ export class Tip extends Mark {
       lineHeight = 1,
       lineWidth = 20,
       frameAnchor,
+      format,
       textAnchor = "start",
       textOverflow,
       textPadding = 8,
@@ -82,6 +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 = maybeFunction(format);
   }
   render(index, scales, values, dimensions, context) {
     const mark = this;
@@ -116,7 +118,9 @@ export class Tip extends Mark {
 
     // Determine the appropriate formatter.
     const format =
-      "title" in sources // if there is a title channel
+      this.format !== undefined
+        ? formatData(this.format, values.data) // use the custom format, if any
+        : "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
@@ -312,6 +316,14 @@ function getSources({channels}) {
   return sources;
 }
 
+function formatData(format, data) {
+  return function (i) {
+    let result = format.call(this, data[i], i);
+    if (isObject(result)) result = Object.entries(result).map(([name, value]) => ({name, value}));
+    return result;
+  };
+}
+
 function formatTitle(i, {title}) {
   return formatDefault(title.value[i]);
 }

src/options.js

@@ -130,6 +130,13 @@ export function keyword(input, name, allowed) {
   return i;
 }
 
+// Validates the specified optional function.
+export function maybeFunction(input, name) {
+  if (input == null) return;
+  if (typeof input !== "function") throw new Error(`invalid ${name}: ${input}`);
+  return input;
+}
+
 // Promotes the specified data to an array as needed.
 export function arrayify(data) {
   return data == null || data instanceof Array || data instanceof TypedArray ? data : Array.from(data);

src/plot.js

@@ -239,6 +239,7 @@ export function plot(options = {}) {
   // Compute value objects, applying scales and projection as needed.
   for (const [mark, state] of stateByMark) {
     state.values = mark.scale(state.channels, scales, context);
+    state.values.data = state.data; // Expose the data, too.
   }
 
   const {width, height} = dimensions;