document more libs (#345)

* arrow, d3, and versions

* htl

* inputs

* L

* plot

* topojson

* remove versions

* colors that work well in both light and dark modes
I couldn't find how to use var(--theme-foreground-focus).

* less awful start and end steps

* Apply suggestions from code review

* link to katex.org

* Update docs/lib/inputs.md

---------

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

docs/lib/arquero.md

@@ -1,6 +1,6 @@
 # Arquero
 
-[Arquero](https://uwdata.github.io/arquero/) is a JavaScript library for “query processing and transformation of array-backed data tables.” Arquero (currently version ${aq.version}) is available by default as `aq` in Markdown, but you can import it explicitly like so:
+[Arquero](https://uwdata.github.io/arquero/) is a JavaScript library for “query processing and transformation of array-backed data tables.” Arquero is available by default as `aq` in Markdown, but you can import it explicitly like so:
 
 ```js echo
 import * as aq from "npm:arquero";

docs/lib/arrow.md

@@ -1,5 +1,28 @@
 # Apache Arrow
 
+[Apache Arrow](https://arrow.apache.org/) defines a language-independent columnar memory format for flat and hierarchical data, organized for efficient analytic operations. You will probably not consume it directly, but it is used by [Arquero](arquero), [DuckDB](duckdb), and other libraries to handle data efficiently.
+
+Apache Arrow is available by default as `Arrow` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as Arrow from "npm:apache-arrow";
 ```
+
+For example, let’s create a table representing a year’s worth of random walk:
+
+```js echo
+const date = d3.utcDay.range(new Date("2023-01-01"), new Date("2024-01-02"));
+const random = d3.randomNormal.source(d3.randomLcg(42))(); // seeded random
+const value = d3.cumsum(date, random);
+const table = Arrow.tableFromArrays({date, value});
+display([...table]);
+```
+
+```js echo
+display(Plot.plot({
+  marks: [
+    Plot.ruleY([0]),
+    Plot.lineY(table, {x: "date", y: "value"})
+  ]
+}));
+```

docs/lib/counties-albers-10m.json

@@ -1,5 +1,13 @@
 # D3
 
+[D3](https://d3js.org) (or D3.js) is a free, open-source JavaScript library for visualizing data. Its low-level approach built on web standards offers unparalleled flexibility in authoring dynamic, data-driven graphics.
+
+D3 is available by default as `d3` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as d3 from "npm:d3";
 ```
+
+We recommend using [Observable Plot](plot) if you want to create _simple_ charts from your data; but for more complex needs, including interactivity and animations, and more generally for bespoke data visualization, you will most probably want to use D3.
+
+Check out [D3’s extensive documentation](https://d3js.org/) for examples.

docs/lib/d3.md

@@ -41,11 +41,12 @@ digraph G {
   subgraph cluster_0 {
     a0 -> a1 -> a2 -> a3
     label = "process #1"
+    color = lightblue
   }
   subgraph cluster_1 {
     b0 -> b1 -> b2 -> b3
     label = "process #2"
-    color = blue
+    color = orange
   }
   start -> a0
   start -> b0
@@ -54,7 +55,7 @@ digraph G {
   a3 -> a0
   a3 -> end
   b3 -> end
-  start [shape = Mdiamond]
-  end [shape = Msquare]
+  start [shape = diamond]
+  end [shape = square]
 }
 ```

docs/lib/dot.md

@@ -1,13 +1,45 @@
 # Hypertext Literal
 
+[Hypertext Literal](https://github.com/observablehq/htl) is a tagged template literal for HTML which interpolates _values based on context_, allowing automatic escaping and the interpolation of non-serializable values.
+
+Hypertext Literal is available by default as `htl` in Markdown, together with its methods `html` and `svg`. You can import it explicitly like so:
+
 ```js echo
 import {html} from "npm:htl";
 ```
 
+```js echo
+html`<span ${{
+  style: {
+    background: "yellow",
+    padding: "3px",
+    cursor: "pointer",
+    userSelect: "none"
+  },
+  onclick() {
+    this.style.background = d3.interpolateRainbow(Math.random());
+  }
+}}>Click me!</span>`
+```
+
+The `svg` method likewise generates contextual SVG fragments, which can be useful, say, to position two charts side by side:
+
 ```js echo
 import {svg} from "npm:htl";
 ```
 
+```js echo
+const chart1 = Plot.barY([3, 4, 2, 7, 5]).plot({width: 120, height: 80});
+const chart2 = Plot.barY([5, 1, 7, 6, 2]).plot({width: 120, height: 80});
+display(svg`<svg width=260 height=80>
+  <g>${chart1}</g>
+  <g ${{transform: "translate(140,0)"}}>${chart2}</g>
+</svg>`);
+```
+
+If you prefer using `htl.html` and `htl.svg`, just import everything:
+
 ```js echo
 import * as htl from "npm:htl";
 ```
+

docs/lib/htl.md

@@ -1,9 +1,19 @@
 # Observable Inputs
 
+[Observable Inputs](https://github.com/observablehq/inputs) provides lightweight interface components — buttons, sliders, dropdowns, tables, and the like — to help you explore data and build interactive displays.
+
+Observable Inputs is available by default as `Inputs` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as Inputs from "npm:@observablehq/inputs";
 ```
 
+or just import the inputs you use:
+
+```js echo
+import {Button, Color} from "npm:@observablehq/inputs";
+```
+
 These basic inputs will get you started.
 
 * [Button](#button) - do something when a button is clicked

docs/lib/inputs.md

@@ -1,12 +1,18 @@
 # Leaflet
 
+[Leaflet](https://leafletjs.com/) is an open-source JavaScript library for mobile-friendly interactive maps.
+
+Leaflet is available by default as `L` in Observable markdown, you can also import it explicitly:
+
 ```js echo
 import * as L from "npm:leaflet";
 ```
 
+To create a map, follow the [tutorial](https://leafletjs.com/examples/quick-start/):
+
 ```js echo
 const div = Object.assign(display(document.createElement("div")), {style: "height: 400px;"});
 const map = L.map(div).setView([51.505, -0.09], 13);
 L.tileLayer("https://tile.openstreetmap.org/{z}/{x}/{y}.png").addTo(map);
-L.marker([51.5, -0.09]).addTo(map).bindPopup("A pretty CSS popup.<br> Easily customizable.").openPopup();
+L.marker([51.5, -0.09]).addTo(map).bindPopup("A nice popup<br> indicating a point of interest.");
 ```

docs/lib/leaflet.md

@@ -1,9 +1,35 @@
 # Observable Plot
 
+[Observable Plot](https://observablehq.com/plot/) is a JavaScript library for exploratory data visualization, made by the same team as [D3](d3). Plot is available by default as `Plot` in Markdown, but you can import it explicitly like so:
+
 ```js echo
 import * as Plot from "npm:@observablehq/plot";
 ```
 
+To display a chart in Observable Markdown, simply call `Plot.plot` in a JavaScript expression code block:
+
+````md
+```js
+Plot.plot({
+  marks: [
+    Plot.barY(alphabet, {x: "letter", y: "frequency"})
+  ]
+})
+```
+````
+
+For example, here’s a Voronoi chart:
+
 ```js echo
-Plot.frame().plot()
+const random = d3.randomLcg(42);
+const chart = Plot.voronoi(Array.from({length: 100}, () => [random(), random()])).plot({nice: true}); 
+
+display(chart);
 ```
+
+Or, to include a ${Plot.lineY([1, 2, 0, 4, 0, 3, 1, 5, 7, 2, 3]).plot({axis: null, width: 80, height: 18})} sparkline in your text — or bars ${Plot.barY([1, 2, 4, 3, 1, 5], {fill: Plot.identity}).plot({axis: null, width: 80, height: 18})} — just call:
+
+```md
+… include a ${Plot.lineY([1, 2, 0, 4, 0, 3, 1, 5, 7, 2, 3]).plot({axis: null, width: 80, height: 18})} sparkline…
+… bars ${Plot.lineY([1, 2, 4, 3, 1, 5], {fill: Plot.identity}).plot({axis: null, width: 80, height: 18})} — just…
+```

docs/lib/plot.md

@@ -52,3 +52,5 @@ c = \pm\sqrt{a^2 + b^2}
     \f\hat\xi\,e^{2 \pi i \xi x}
     \,d\xi
 ```
+
+For more, see [the documentation website](https://katex.org/), in particular the [list of supported functions](https://katex.org/docs/supported).