docs: add example of rendering images in tooltips (vega#8048)

* docs: add example of rendering images in tooltips

* docs: add link to vega-tooltip plugin in the image tooltip section

* chore: update TOC [CI]

* chore: update examples [CI]

* style: auto-formatting [CI]

* Improve wording

Co-authored-by: Dominik Moritz <domoritz@gmail.com>

* Remove stroke outline

* chore: update examples [CI]

Co-authored-by: GitHub Actions Bot <vega-actions-bot@users.noreply.github.com>
Co-authored-by: Dominik Moritz <domoritz@gmail.com>

examples/compiled/text_tooltip_image.vg.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://vega.github.io/schema/vega/v5.json",
+  "description": "A simple chart with an image tooltip.",
+  "background": "white",
+  "padding": 5,
+  "width": 20,
+  "style": "cell",
+  "encode": {"update": {"stroke": {"value": null}}},
+  "data": [
+    {
+      "name": "source_0",
+      "values": [
+        {"image": "data/ffox.png"},
+        {"image": "data/gimp.png"},
+        {"image": "data/7zip.png"}
+      ]
+    }
+  ],
+  "signals": [
+    {"name": "y_step", "value": 20},
+    {
+      "name": "height",
+      "update": "bandspace(domain('y').length, 1, 0.5) * y_step"
+    }
+  ],
+  "marks": [
+    {
+      "name": "marks",
+      "type": "text",
+      "style": ["text"],
+      "from": {"data": "source_0"},
+      "encode": {
+        "update": {
+          "fill": {"value": "black"},
+          "tooltip": {
+            "signal": "{\"image\": isValid(datum[\"image\"]) ? datum[\"image\"] : \"\"+datum[\"image\"]}"
+          },
+          "description": {
+            "signal": "\"image: \" + (isValid(datum[\"image\"]) ? datum[\"image\"] : \"\"+datum[\"image\"])"
+          },
+          "x": {"signal": "width", "mult": 0.5},
+          "y": {"scale": "y", "field": "image"},
+          "text": {
+            "signal": "isValid(datum[\"image\"]) ? datum[\"image\"] : \"\"+datum[\"image\"]"
+          },
+          "align": {"value": "center"},
+          "baseline": {"value": "middle"}
+        }
+      }
+    }
+  ],
+  "scales": [
+    {
+      "name": "y",
+      "type": "point",
+      "domain": {"data": "source_0", "field": "image", "sort": true},
+      "range": {"step": {"signal": "y_step"}},
+      "padding": 0.5
+    }
+  ]
+}

examples/specs/text_tooltip_image.vl.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
+   "view": {"stroke": null},
+  "description": "A simple chart with an image tooltip.",
+  "data": {
+    "values": [
+      {"image": "data/ffox.png"},
+      {"image": "data/gimp.png"},
+      {"image": "data/7zip.png"}
+    ]
+  },
+  "mark": "text",
+  "encoding": {
+    "text": {"field": "image"},
+    "y": {"field": "image", "axis": null},
+    "tooltip": [{"field": "image"}]
+  }
+}

site/_includes/docs_toc.md

@@ -374,5 +374,6 @@
     - [Tooltip Based on Encoding]({{site.baseurl}}/docs/tooltip.html#encoding)
     - [Tooltip Based on Underlying Data Point]({{site.baseurl}}/docs/tooltip.html#data)
     - [Tooltip channel]({{site.baseurl}}/docs/tooltip.html#channel)
+    - [Tooltip image]({{site.baseurl}}/docs/tooltip.html#tooltip-image)
     - [Disable tooltips]({{site.baseurl}}/docs/tooltip.html#disable-tooltips)
     - [Vega Tooltip plugin]({{site.baseurl}}/docs/tooltip.html#plugin)

site/docs/tooltip.md

@@ -64,6 +64,14 @@ To avoid that the tooltips groups the data, add an aggregate to the tooltip enco
 
 <div class="vl-example" data-name="bar_tooltip_aggregate"></div>
 
+## Tooltip image
+
+To display an image in a tooltip you can use the [Vega Tooltip plugin](#plugin). Vega Tooltip requires the special field name `image` to indicate that the field values should be rendered as images instead of displayed as text. The image tooltip can be specified either by setting the `tooltip` property of the mark definition (as detailed above) or by passing the field _as an array_ to the tooltip encoding channel, as in the example below:
+
+<div class="vl-example" data-name="text_tooltip_image"></div>
+
+In addition to providing the path to an image, the Vega Tooltip plugin can also render base64 encoded images prefixed with `data:image/png;base64,` [similarly to how these are rendered inside HTML image tags](https://www.w3docs.com/snippets/html/how-to-display-base64-images-in-html.html). To change the maximum size of the rendered tooltip images, you can adjust the `max-width` and `max-height` properties of the CSS selector `#vg-tooltip-element img`.
+
 ## Disable tooltips
 
 To disable tooltips for a particular single view specification, you can set the `"tooltip"` property of a mark definition block to `null`.