tip edits

CHANGELOG.md

@@ -17,7 +17,7 @@ Plot.plot({
     Plot.lineY(aapl, {x: "Date", y: "Close"}),
     Plot.tip(
       [`Apple stock drops 8% after the company misses Q2 revenue targets and reports declining iPhone sales. It reaches a two-year low of $90.34 on May 12.`],
-      {x: new Date("2016-05-12"), y: 90.34, dy: 3, anchor: "top", title: Plot.identity}
+      {x: new Date("2016-05-12"), y: 90.34, dy: 3, anchor: "top"}
     )
   ]
 })

docs/marks/tip.md

@@ -2,18 +2,88 @@
 
 import * as Plot from "@observablehq/plot";
 import * as d3 from "d3";
+import {shallowRef, onMounted} from "vue";
+
+const aapl = shallowRef([]);
+
+const olympians = shallowRef([
+  {weight: 31, height: 1.21, sex: "female"},
+  {weight: 170, height: 2.21, sex: "male"}
+]);
+
+onMounted(() => {
+  d3.csv("../data/aapl.csv", d3.autoType).then((data) => (aapl.value = data));
+  d3.csv("../data/athletes.csv", d3.autoType).then((data) => (olympians.value = data));
+});
 
 </script>
 
 # Tip mark
 
-The **tip mark** …
+The **tip mark** displays text, or name-value pairs, in a floating box anchored for a given position in **x** and **y**. The tip mark is often paired with the [pointer transform](../interactions/pointer.md) to reveal details on demand when hovering over a chart, as in this line chart of Apple stock price:
+
+:::plot defer
+```js
+Plot.lineY(aapl, {x: "Date", y: "Close", tip: true}).plot({y: {grid: true}})
+```
+:::
+
+The above code uses the **tip** [mark option](../features/marks.md#mark-options); the code can be written more explicitly with a tip mark and a pointer transform.
+
+```js
+Plot.plot({
+  y: {grid: true},
+  marks: [
+    Plot.lineY(aapl, {x: "Date", y: "Close"}),
+    Plot.tip(aapl, Plot.pointerX({x: "Date", y: "Close"}))
+  ]
+})
+```
+
+The tip mark can also be used for static annotations, say to draw attention to elements of interest or to add context. The tip text is supplied via the **title** channel. If the tip mark‘s data is an array of strings, the **title** channel defaults to [identity](../features/transforms.md#identity).
+
+:::plot defer
+```js
+Plot.plot({
+  y: {grid: true},
+  marks: [
+    Plot.lineY(aapl, {x: "Date", y: "Close"}),
+    Plot.tip(
+      [`Apple stock reaches a new high of $133 on Feb. 23, 2015. The release of the first Apple Watch, slated for April, is hotly anticipated.`],
+      {x: new Date("2015-02-23"), y: 133, dy: -3, anchor: "bottom"}
+    ),
+    Plot.tip(
+      [`Apple stock drops 8% after the company misses Q2 revenue targets and reports declining iPhone sales. It reaches a two-year low of $90.34 on May 12.`],
+      {x: new Date("2016-05-12"), y: 90.34, dy: 3, anchor: "top"}
+    )
+  ]
+})
+```
+:::
+
+If no **title** channel is supplied, the tip mark displays all channel values. You can supply additional name-value pairs by registering extra channels using the **channels** mark option. In the scatterplot of Olympic athletes below, you can hover to see the *name* and *sport* of each athlete. This is helpful for noticing patterns—tall basketball players, giant weightlifters and judoka, diminutive gymnasts—and for seeing individuals.
+
+:::plot defer
+```js
+Plot.dot(olympians, {
+  x: "weight",
+  y: "height",
+  stroke: "sex",
+  channels: {name: "name", sport: "sport"},
+  tip: true
+}).plot()
+```
+:::
+
+:::info
+The tallest athlete in this dataset, swimmer [Kevin Cordes](https://en.wikipedia.org/wiki/Kevin_Cordes), is likely an error: his official height is 1.96m (6′ 5″) not 2.21m (7′ 3″). Basketball player [Li Muhao](https://en.wikipedia.org/wiki/Li_Muhao) is likely the true tallest.
+:::
+
+If a channel is bound to the *color* scale, the tip mark displays a swatch to reinforce the encoding, such as female <span :style="{color: d3.schemeTableau10[0]}">■</span> or male <span :style="{color: d3.schemeTableau10[1]}">■</span>.
+
+TODO Show all nine anchors.
 
-* tip option
-* interaction
-* fixed tip example
-* orientations
-* geo + centroid example
+TODO geo + centroid example
 
 Notes: