custom tip format (#1823)

* custom tip format

* format order; materialize defaults; fix facets

* revert data values, for now

* fix default tip pointer

* fix paired channels

* fix paired channel order

* fix crash with inferred tick format

* pReTTier

* oops, time zones!

Author: mbostock

src/channel.d.ts

@@ -145,7 +145,7 @@ export type ChannelValue =
  * object to override the scale that would normally be associated with the
  * channel.
  */
-export type ChannelValueSpec = ChannelValue | {value: ChannelValue; scale?: Channel["scale"]}; // TODO label
+export type ChannelValueSpec = ChannelValue | {value: ChannelValue; label?: string; scale?: Channel["scale"]};
 
 /**
  * In some contexts, when specifying a mark channel’s value, you can provide a

src/channel.js

@@ -5,13 +5,13 @@ import {registry} from "./scales/index.js";
 import {isSymbol, maybeSymbol} from "./symbol.js";
 import {maybeReduce} from "./transforms/group.js";
 
-export function createChannel(data, {scale, type, value, filter, hint}, name) {
+export function createChannel(data, {scale, type, value, filter, hint, label = labelof(value)}, name) {
   if (hint === undefined && typeof value?.transform === "function") hint = value.hint;
   return inferChannelScale(name, {
     scale,
     type,
     value: valueof(data, value),
-    label: labelof(value),
+    label,
     filter,
     hint
   });

src/mark.d.ts

@@ -1,6 +1,7 @@
 import type {Channel, ChannelDomainSort, ChannelValue, ChannelValues, ChannelValueSpec} from "./channel.js";
 import type {Context} from "./context.js";
 import type {Dimensions} from "./dimensions.js";
+import type {TipOptions} from "./marks/tip.js";
 import type {plot} from "./plot.js";
 import type {ScaleFunctions} from "./scales.js";
 import type {InitializerFunction, SortOrder, TransformFunction} from "./transforms/basic.js";
@@ -23,6 +24,9 @@ export type FrameAnchor =
   | "bottom-left"
   | "left";
 
+/** The pointer mode for the tip; corresponds to pointerX, pointerY, and pointer. */
+export type TipPointer = "x" | "y" | "xy";
+
 /**
  * A mark’s data; one of:
  *
@@ -275,8 +279,8 @@ export interface MarkOptions {
    */
   title?: ChannelValue;
 
-  /** Whether to generate a tooltip for this mark. */
-  tip?: boolean | "x" | "y" | "xy";
+  /** Whether to generate a tooltip for this mark, and any tip options. */
+  tip?: boolean | TipPointer | (TipOptions & {pointer?: TipPointer});
 
   /**
    * How to clip the mark; one of:

src/mark.js

@@ -1,8 +1,8 @@
 import {channelDomain, createChannels, valueObject} from "./channel.js";
 import {defined} from "./defined.js";
 import {maybeFacetAnchor} from "./facet.js";
-import {maybeKeyword, maybeNamed, maybeValue} from "./options.js";
-import {arrayify, isDomainSort, isOptions, keyword, range, singleton} from "./options.js";
+import {maybeNamed, maybeValue} from "./options.js";
+import {arrayify, isDomainSort, isObject, isOptions, keyword, range, singleton} from "./options.js";
 import {project} from "./projection.js";
 import {maybeClip, styles} from "./style.js";
 import {basic, initializer} from "./transforms/basic.js";
@@ -150,17 +150,27 @@ export function composeRender(r1, r2) {
 function maybeChannels(channels) {
   return Object.fromEntries(
     Object.entries(maybeNamed(channels)).map(([name, channel]) => {
-      channel = maybeValue(channel);
+      channel = typeof channel === "string" ? {value: channel, label: name} : maybeValue(channel); // for shorthand extra channels, use name as label
       if (channel.filter === undefined && channel.scale == null) channel = {...channel, filter: null};
       return [name, channel];
     })
   );
 }
 
 function maybeTip(tip) {
-  return tip === true ? "xy" : tip === false ? null : maybeKeyword(tip, "tip", ["x", "y", "xy"]);
+  return tip === true
+    ? "xy"
+    : tip === false || tip == null
+    ? null
+    : typeof tip === "string"
+    ? keyword(tip, "tip", ["x", "y", "xy"])
+    : tip; // tip options object
 }
 
-export function withTip(options, tip) {
-  return options?.tip === true ? {...options, tip} : options;
+export function withTip(options, pointer) {
+  return options?.tip === true
+    ? {...options, tip: pointer}
+    : isObject(options?.tip) && options.tip.pointer === undefined
+    ? {...options, tip: {...options.tip, pointer}}
+    : options;
 }

src/marks/tip.d.ts

@@ -1,4 +1,4 @@
-import type {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";
 
@@ -61,6 +61,13 @@ export interface TipOptions extends MarkOptions, TextStyles {
    * the right of the anchor position.
    */
   anchor?: FrameAnchor;
+
+  /**
+   * How channel values are formatted for display. If a format is a string, it
+   * is interpreted as a (UTC) time format for temporal channels, and otherwise
+   * a number format.
+   */
+  format?: {[name in ChannelName]?: boolean | string | ((d: any, i: number) => string)};
 }
 
 /**