checkpoint documentation

mbostock · mbostock · commit 570334c11e78 · 2023-11-09T23:36:07.000-08:00
diff --git a/docs/javascript/generators.md b/docs/javascript/generators.md
@@ -1,22 +1,32 @@
 # Generators
 
-When code refers to a [generator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator) defined in another code block, the referencing code automatically runs each time the generator yields a value. Values that change over time, such as interactive inputs and animation parameters, are often represented as generators. For example, you can use [Observable Inputs](https://github.com/observablehq/inputs) and the built-in [`view` function](./inputs) to construct a live text input. Try entering your name into the box below:
+Values that change over time, such as interactive inputs and animation parameters, can represented as [async generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Generator). When a top-level generator is declared, code in other blocks sees the generator’s latest yielded value and runs whenever the generator yields a new value.
+
+For example, here is a generator that increments once a second:
 
 ```js show
-const name = view(Inputs.text({label: "Name", placeholder: "Enter your name"}));
+const j = (async function* () {
+  for (let j = 0; true; ++j) {
+    yield j;
+    await new Promise((resolve) => setTimeout(resolve, 1000));
+  }
+})();
 ```
 
-Name is: ${name}.
-
-The `view` function calls `Generators.input` under the hood, which takes an input element and returns a generator that yields the input’s value whenever it changes. The code above can be written more explicitly as:
+The value of j is: ${j}.
 
-```js no-run
-const nameInput = Inputs.text({label: "Name", placeholder: "Enter your name"});
-const name = Generators.input(nameInput);
+If the generator is synchronous, the generator will yield every animation frame, which is typically 60 frames per second:
 
-display(nameInput);
+```js show
+const i = (function* () {
+  for (let i = 0; true; ++i) {
+    yield i;
+  }
+})();
 ```
 
+The value of i is: ${i}.
+
 As another example, you can use the built-in `Generators.observe` to represent the current pointer coordinates:
 
 ```js show
@@ -29,3 +39,50 @@ const pointer = Generators.observe((notify) => {
 ```
 
 Pointer is: ${pointer.map(Math.round).join(", ")}.
+
+A WebSocket that lists for Blockchain transactions:
+
+```js show
+const socket = new WebSocket("wss://ws.blockchain.info/inv");
+invalidation.then(() => socket.close());
+socket.addEventListener("open", () => socket.send(JSON.stringify({op: "unconfirmed_sub"})));
+const messages = Generators.observe((notify) => {
+  const messages = [];
+  const messaged = (event) => {
+    messages.unshift(JSON.parse(event.data));
+    if (messages.length > 30) {
+      messages.pop();
+      socket.close();
+    }
+    notify(messages.slice());
+  };
+  socket.addEventListener("message", messaged);
+  return () => socket.removeEventListener("message", messaged);
+});
+```
+
+```js
+messages
+```
+
+```js
+Inputs.table(
+  messages.map((d) => ({
+    time: new Date(d.x.time * 1000),
+    hash: d.x.hash,
+    ins: d3.sum(d.x.inputs.map((d) => d.prev_out.value)) / 1e8,
+    outs: d3.sum(d.x.out.map((d) => d.value)) / 1e8
+  }))
+)
+```
+
+An HTML input element and `Generators.input`:
+
+```js show
+const nameInput = display(document.createElement("input"));
+const name = Generators.input(nameInput);
+```
+
+Name is: ${name}.
+
+See the [`view` function](./inputs) for shorthand inputs.
diff --git a/docs/javascript/inputs.md b/docs/javascript/inputs.md
@@ -1,5 +1,239 @@
 # Inputs
 
-As described above, this function displays the given `input` and then returns its corresponding generator via `Generators.input`. Use this to display an input element while also declaring the input’s current value as a reactive top-level variable.
+You can use the built-in [`view` function](#view(input)) and an HTML input element to create a reactive input. For example, here is a slider:
+
+```js show
+const gain = view(Inputs.range([0, 11], {value: 5, step: 0.1, label: "Gain"}));
+```
+
+Now you can reference the input’s value (here `gain`) anywhere. The code will run whenever the input changes; no event listeners required!
+
+```md
+The current gain is ${gain.toFixed(1)}!
+```
+
+The current gain is ${gain.toFixed(1)}!
 
 ## view(*input*)
+
+As described above, this function [displays](./display) the given input element and then returns its corresponding [generator](./generators) via `Generators.input`. Use this to display an input element while also exposing the input’s value as a [reactive top-level variable](./reactivity).
+
+## Built-in inputs
+
+These basic inputs will get you started.
+
+* [Button](#button) - do something when a button is clicked
+* [Toggle](#toggle) - toggle between two values (on or off)
+* [Checkbox](#checkbox) - choose any from a set
+* [Radio](#radio) - choose one from a set
+* [Range](#range) or [Number](https://observablehq.com/@observablehq/input-range) - choose a number in a range (slider)
+* [Select](#select) - choose one or any from a set (drop-down menu)
+* [Text](#text) - enter freeform single-line text
+* [Textarea](#textarea) - enter freeform multi-line text
+* [Date](#date) or [Datetime](https://observablehq.com/@observablehq/input-date) - choose a date
+* [Color](#color) - choose a color
+* [File](#file) - choose a local file
+
+These fancy inputs are designed to work with tabular data such as CSV or TSV [file attachments](./files).
+
+* [Search](#search) - query a tabular dataset
+* [Table](#table) - browse a tabular dataset
+
+---
+
+### Button
+
+Do something when a button is clicked. [Examples ›](https://observablehq.com/@observablehq/input-button) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#button)
+
+```js show
+const clicks = view(Inputs.button("Click me"));
+```
+
+```js
+clicks
+```
+
+---
+
+### Toggle
+
+Toggle between two values (on or off). [Examples ›](https://observablehq.com/@observablehq/input-toggle) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#toggle)
+
+```js show
+const mute = view(Inputs.toggle({label: "Mute"}));
+```
+
+```js
+mute
+```
+
+---
+
+### Checkbox
+
+Choose any from a set. [Examples ›](https://observablehq.com/@observablehq/input-checkbox) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#checkbox)
+
+```js show
+const flavors = view(Inputs.checkbox(["salty", "sweet", "bitter", "sour", "umami"], {label: "Flavors"}));
+```
+
+```js
+flavors
+```
+
+---
+
+### Radio
+
+Choose one from a set. [Examples ›](https://observablehq.com/@observablehq/input-radio) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#radio)
+
+```js show
+const flavor = view(Inputs.radio(["salty", "sweet", "bitter", "sour", "umami"], {label: "Flavor"}));
+```
+
+```js
+flavor
+```
+
+---
+
+### Range
+
+Pick a number. [Examples ›](https://observablehq.com/@observablehq/input-range) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#range)
+
+```js show
+const n = view(Inputs.range([0, 255], {step: 1, label: "Favorite number"}));
+```
+
+```js
+n
+```
+
+---
+
+### Select
+
+Choose one, or any, from a menu. [Examples ›](https://observablehq.com/@observablehq/input-select) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#select)
+
+```js
+const capitals = FileAttachment("us-state-capitals.tsv").tsv({typed: true});
+const stateNames = capitals.then((capitals) => capitals.map(d => d.State));
+```
+
+```js show
+const homeState = view(Inputs.select([null].concat(stateNames), {label: "Home state"}));
+```
+
+```js
+homeState
+```
+
+```js show
+const visitedStates = view(Inputs.select(stateNames, {label: "Visited states", multiple: true}));
+```
+
+```js
+visitedStates
+```
+
+---
+
+### Text
+
+Enter freeform single-line text. [Examples ›](https://observablehq.com/@observablehq/input-text) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#text)
+
+```js show
+const name = view(Inputs.text({label: "Name", placeholder: "What’s your name?"}));
+```
+
+```js
+name
+```
+
+---
+
+### Textarea
+
+Enter freeform multi-line text. [Examples ›](https://observablehq.com/@observablehq/input-textarea) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#textarea)
+
+```js show
+const bio = view(Inputs.textarea({label: "Biography", placeholder: "What’s your story?"}));
+```
+
+```js
+bio
+```
+
+---
+
+### Date
+
+Choose a date, or a date and time. [Examples ›](https://observablehq.com/@observablehq/input-date) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#date)
+
+```js show
+const birthday = view(Inputs.date({label: "Birthday"}));
+```
+
+```js
+birthday
+```
+
+---
+
+### Color
+
+Choose a color. [Examples ›](https://observablehq.com/@observablehq/input-color) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#color)
+
+```js show
+const color = view(Inputs.color({label: "Favorite color", value: "#4682b4"}));
+```
+
+```js
+color
+```
+
+---
+
+### File
+
+Choose a local file. [Examples ›](https://observablehq.com/@observablehq/input-file) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#file)
+
+```js show
+const file = view(Inputs.file({label: "CSV file", accept: ".csv", required: true}));
+```
+
+```js
+data = file.csv({typed: true})
+```
+
+---
+
+### Search
+
+Query a tabular dataset. [Examples ›](https://observablehq.com/@observablehq/input-search) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#search)
+
+```js show
+const search = view(Inputs.search(capitals, {placeholder: "Search U.S. capitals"}));
+```
+
+```js
+search // see table below!
+```
+
+---
+
+### Table
+
+Browse a tabular dataset. [Examples ›](https://observablehq.com/@observablehq/input-table) [API Reference ›](https://github.com/observablehq/inputs/blob/main/README.md#table)
+
+```js show
+const rows = view(Inputs.table(search));
+```
+
+```js
+rows // click a checkbox in the leftmost column
+```
+
+---
+
+* [Form](https://observablehq.com/@observablehq/input-form?collection=@observablehq/inputs) - combine multiple inputs for a compact display
diff --git a/docs/javascript/us-state-capitals.tsv b/docs/javascript/us-state-capitals.tsv
@@ -0,0 +1,51 @@
+State	Capital	Since	Area	Population	MSA/µSA	CSA	Rank
+Alabama	Montgomery	1846-01-01	159.8	198525	373290	461516	3
+Alaska	Juneau	1906-01-01	2716.7	32113	32113		3
+Arizona	Phoenix	1912-01-01	517.6	1680992	4948203	5002221	1
+Arkansas	Little Rock	1821-01-01	116.2	197312	742384	908941	1
+California	Sacramento	1854-01-01	97.9	513624	2363730	2639124	6
+Colorado	Denver	1867-01-01	153.3	727211	2967239	3617927	1
+Connecticut	Hartford	1875-01-01	17.3	122105	1204877	1470083	3
+Delaware	Dover	1777-01-01	22.4	38079	180786	7209620	2
+Florida	Tallahassee	1824-01-01	95.7	194500	387227		7
+Georgia	Atlanta	1868-01-01	133.5	506811	6020364	6853392	1
+Hawaii	Honolulu	1845-01-01	68.4	345064	974563		1
+Idaho	Boise	1865-01-01	63.8	228959	749202	831235	1
+Illinois	Springfield	1837-01-01	54.0	114230	206868	306399	6
+Indiana	Indianapolis	1825-01-01	361.5	876384	2074537	2457286	1
+Iowa	Des Moines	1857-01-01	75.8	214237	699292	877991	1
+Kansas	Topeka	1856-01-01	56.0	125310	231969		4
+Kentucky	Frankfort	1792-01-01	14.7	27679	73663	745033	15
+Louisiana	Baton Rouge	1880-01-01	76.8	220236	854884		2
+Maine	Augusta	1832-01-01	55.4	18681	122302		8
+Maryland	Annapolis	1694-01-01	6.73	39174	2800053	9814928	7
+Massachusetts	Boston	1630-01-01	89.6	692600	4873019	8287710	1
+Michigan	Lansing	1847-01-01	35.0	118210	550391		5
+Minnesota	Saint Paul	1849-01-01	52.8	308096	3654908	4027861	2
+Mississippi	Jackson	1821-01-01	104.9	160628	594806	674340	1
+Missouri	Jefferson City	1826-01-01	27.3	42838	151235		15
+Montana	Helena	1875-01-01	14.0	32315	77414		6
+Nebraska	Lincoln	1867-01-01	74.6	289102	336374	357887	2
+Nevada	Carson City	1861-01-01	143.4	55916	55916	637973	6
+New Hampshire	Concord	1808-01-01	64.3	43627	151391	8287710	3
+New Jersey	Trenton	1784-01-01	7.66	83203	367430	22589036	10
+New Mexico	Santa Fe	1610-01-01	37.3	84683	150358	1158464	4
+New York	Albany	1797-01-01	21.4	96460	880381	1167594	6
+North Carolina	Raleigh	1792-01-01	114.6	474069	1390785	2079687	2
+North Dakota	Bismarck	1883-01-01	26.9	73529	128949		2
+Ohio	Columbus	1816-01-01	210.3	898553	2122271	2525639	1
+Oklahoma	Oklahoma City	1910-01-01	620.3	655057	1408950	1481542	1
+Oregon	Salem	1855-01-01	45.7	174365	433903	3259710	3
+Pennsylvania	Harrisburg	1812-01-01	8.11	49528	577941	1271801	9
+Rhode Island	Providence	1900-01-01	18.5	179883	1624578	8287710	1
+South Carolina	Columbia	1786-01-01	125.2	131674	838433	963048	2
+South Dakota	Pierre	1889-01-01	13.0	13646	20672		8
+Tennessee	Nashville	1826-01-01	525.9	670820	1934317	2062547	1
+Texas	Austin	1839-01-01	305.1	978908	2227083		4
+Utah	Salt Lake City	1858-01-01	109.1	200567	1232696	2641048	1
+Vermont	Montpelier	1805-01-01	10.2	7855			6
+Virginia	Richmond	1780-01-01	60.1	230436	1291900		4
+Washington	Olympia	1853-01-01	16.7	46478	290536	4903675	24
+West Virginia	Charleston	1885-01-01	31.6	46536	257074	776694	1
+Wisconsin	Madison	1838-01-01	68.7	259680	664865	892661	2
+Wyoming	Cheyenne	1869-01-01	21.1	64235	99500		1
