Components

docs/charts/area.md

@@ -0,0 +1,40 @@
+# Area chart
+
+Copy the code snippets below, paste into a JavaScript code block, then substitute your own data to create area charts using the [area mark](https://observablehq.com/plot/marks/area) from [Observable Plot](https://observablehq.com/plot/). 
+
+## Area chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.areaY(aapl, {x: "Date", y: "Close"}),
+    Plot.ruleY([0])
+  ]
+})
+```
+
+## Band area chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.areaY(weather.slice(-365), {x: "date", y1: "temp_min", y2: "temp_max", curve: "step"})
+  ]
+})
+```
+
+## Stacked area chart
+
+```js echo
+Plot.plot({
+  y: {
+    tickFormat: "s"
+  },
+  marks: [
+    Plot.areaY(industries, {x: "date", y: "unemployed", fill: "industry"}),
+    Plot.ruleY([0])
+  ]
+})
+```
+
+

docs/charts/arrow.md

@@ -0,0 +1,20 @@
+# Arrow chart
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create arrow charts using the [arrow mark](https://observablehq.com/plot/marks/arrow) from [Observable Plot](https://observablehq.com/plot/). 
+
+```js echo
+Plot.plot({
+  x: {
+    type: "log"
+  },
+  marks: [
+    Plot.arrow(citywages, {
+      x1: "POP_1980",
+      y1: "R90_10_1980",
+      x2: "POP_2015",
+      y2: "R90_10_2015",
+      bend: true
+    })
+  ]
+})
+```

docs/charts/bar.md

@@ -0,0 +1,58 @@
+# Bar chart
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create bar charts using the [bar mark](https://observablehq.com/plot/marks/bar) from [Observable Plot](https://observablehq.com/plot/). 
+
+## Sorted bar chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.barY(alphabet, {x: "letter", y: "frequency", sort: {x: "y", reverse: true}}),
+    Plot.ruleY([0])
+  ]
+})
+```
+
+## Horizontal bar chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.barX(alphabet, {x: "frequency", y: "letter", sort: {y: "x", reverse: true}}),
+    Plot.ruleX([0])
+  ]
+})
+```
+
+## Top 10 bar chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.barX(olympians, Plot.groupY({x: "count"}, {y: "nationality", sort: {y: "x", reverse: true, limit: 10}})),
+    Plot.ruleX([0])
+  ]
+})
+```
+
+## Weighted top 10 bar chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.barX(olympians, Plot.groupY({x: "sum"}, {x: "gold", y: "nationality", sort: {y: "x", reverse: true, limit: 10}})),
+    Plot.ruleX([0])
+  ]
+})
+```
+
+## Temporal bar chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.rectY(weather.slice(-42), {x: "date", y: "wind", interval: d3.utcDay}),
+    Plot.ruleY([0])
+  ]
+})
+```

docs/charts/cell.md

@@ -0,0 +1,15 @@
+# Cell chart
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create a cell chart using the [cell mark](https://observablehq.com/plot/marks/cell) from [Observable Plot](https://observablehq.com/plot/). 
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.cell(weather.slice(-365), {
+      x: d => d.date.getUTCDate(),
+      y: d => d.date.getUTCMonth(),
+      fill: "temp_max"
+    })
+  ]
+})
+```

docs/charts/dot.md

@@ -0,0 +1,11 @@
+# Scatterplot
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create a scatterplot chart using the [dot mark](https://observablehq.com/plot/marks/dot) from [Observable Plot](https://observablehq.com/plot/). 
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.dot(cars, {x: "power (hp)", y: "economy (mpg)"})
+  ]
+})
+```

docs/charts/facets.md

@@ -0,0 +1,16 @@
+# Faceted chart
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create a faceted chart with small multiples using the [facet channel](https://observablehq.com/plot/features/facets) from [Observable Plot](https://observablehq.com/plot/). 
+
+```js echo
+Plot.plot({
+  facet: {
+    data: penguins,
+    x: "species"
+  },
+  marks: [
+    Plot.frame(),
+    Plot.dot(penguins, {x: "culmen_length_mm", y: "culmen_depth_mm"})
+  ]
+})
+```

docs/charts/grouping-data.md

@@ -0,0 +1,29 @@
+# Grouping data
+
+[Observable Plot](https://observablehq.com/plot/) provides a number of [transforms](https://observablehq.com/plot/features/transforms) that help you perform common data transformations. The [group](https://observablehq.com/plot/transforms/group) and [bin](https://observablehq.com/plot/transforms/bin) transforms (for categorical and quantitative dimensions, respectively) group data into discrete bins. A reducer (_e.g._ sum, count, or mean) can then be applied to visualize summary values by bin. 
+
+## Hexbin chart 
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create a hexbin chart using the [dot mark](https://observablehq.com/plot/marks/dot) and the [hexbin transform](https://observablehq.com/plot/transforms/hexbin). 
+
+```js echo
+Plot.plot({
+  color: {scheme: "ylgnbu"},
+  marks: [
+    Plot.dot(olympians, Plot.hexbin({fill: "sum"}, {x: "weight", y: "height"}))
+  ]
+})
+```
+
+## Histogram
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create a histogram using the [rect mark](https://observablehq.com/plot/marks/rect) and the [bin transform](https://observablehq.com/plot/transforms/bin). 
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.rectY(olympians, Plot.binX({y: "count"}, {x: "weight"})),
+    Plot.ruleY([0])
+  ]
+})
+```

docs/charts/line.md

@@ -0,0 +1,36 @@
+# Line chart
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create a line chart using the [line mark](https://observablehq.com/plot/marks/line) from [Observable Plot](https://observablehq.com/plot/).
+
+## Basic line chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.ruleY([0]),
+    Plot.lineY(aapl, {x: "Date", y: "Close"})
+  ]
+})
+```
+
+## Multi-series line chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.ruleY([0]),
+    Plot.lineY(industries, {x: "date", y: "unemployed", z: "industry"})
+  ]
+})
+```
+
+## Moving average line chart
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.ruleY([0]),
+    Plot.lineY(aapl, Plot.windowY({x: "Date", y: "Close", k: 10, reduce: "mean"}))
+  ]
+})
+```

docs/charts/tick.md

@@ -0,0 +1,11 @@
+# Tick chart
+
+Copy the code snippet below, paste into a JavaScript code block, then substitute your own data to create a tick chart using the [tick mark](https://observablehq.com/plot/marks/tick) from [Observable Plot](https://observablehq.com/plot/).
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.tickX(cars, {x: "economy (mpg)", y: "year"})
+  ]
+})
+```

docs/components.md

@@ -0,0 +1,144 @@
+# Components
+
+You don’t have to start from scratch: components are reusable pieces of code (functions, themes, snippets, etc.) that make it quicker to update page layout and appearance, and add common page content.
+
+The Observable CLI offers three flavors of components: [layout helpers](#layout-helpers), [Observable Plot snippets](#observable-plot-snippets), and [Observable Inputs](#observable-inputs).
+
+## Layout helpers
+
+A collection of elements useful for formatting page content: themes, `card` and `grid` CSS classes, and the `resize` function.
+
+### Themes
+
+<!-- TODO update link to themes gallery layout/themes.md page once added-->
+Observable Markdown offers a number of [built-in themes](./config#theme) that you can compose to create, say, wide pages with an alternative dark color theme:
+
+```js run=false
+theme: ["dark", "alt", "wide"]
+```
+
+The code above, when included in the [config file](./config), specifies the default theme for the project. In addition, you can specify the theme for a single page in its [front matter](markdown#front-matter):
+
+```yaml
+---
+theme: [dark, alt, wide]
+---
+```
+
+You are not limited to the built-in themes. For complete control over the design of your project, see the [style option](./config/#style) instead.
+
+### Grid
+
+The included [`grid`](./layout/grid) CSS classes make it easier to control how page content is arranged. 
+
+<div class="grid grid-cols-2">
+  <div class="card"><h1>A</h1>1 × 1</div>
+  <div class="card grid-rowspan-2"><h1>B</h1>1 × 2</div>
+  <div class="card"><h1>C</h1>1 × 1</div>
+  <div class="card grid-colspan-2"><h1>D</h1>1 × 2</div>
+</div>
+
+```html run=false
+<div class="grid grid-cols-2">
+  <div class="card"><h1>A</h1>1 × 1</div>
+  <div class="card grid-rowspan-2"><h1>B</h1> 1 × 2</div>
+  <div class="card"><h1>C</h1>1 × 1</div>
+  <div class="card grid-colspan-2"><h1>D</h1>1 × 2</div>
+</div>
+```
+
+### Card
+
+The [`card`](./layout/card) CSS class has default styles that help create a card: container borders, background color, padding and optional titles and subtitles. 
+
+<div class="grid grid-cols-2">
+  <div class="card">
+    <h2>A card title</h2>
+    <h3>A card subtitle</h3>
+    ${
+      Plot.plot({
+        marks: [
+          Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm"})
+        ]
+      })
+    }
+  </div>
+  <div class="card">
+    <p>Tortor condimentum lacinia quis vel eros. Arcu risus quis varius quam quisque id. Magnis dis parturient montes nascetur ridiculus mus mauris. Porttitor leo a diam sollicitudin. Odio facilisis mauris sit amet massa vitae tortor. Nibh venenatis cras sed felis eget velit aliquet sagittis. Ullamcorper sit amet risus nullam eget felis eget nunc. In egestas erat imperdiet sed euismod nisi porta lorem mollis. A erat nam at lectus urna duis convallis. Id eu nisl nunc mi ipsum faucibus vitae. Purus ut faucibus pulvinar elementum integer enim neque volutpat ac.</p>
+    </div>
+</div>
+
+```html run=false
+<div class="grid grid-cols-2">
+  <div class="card">
+    <h2>A card title</h2>
+    <h3>A card subtitle</h3>
+    ${
+      Plot.plot({
+        marks: [
+          Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm"})
+        ]
+      })
+    }
+  </div>
+  <div class="card">
+    <p>Tortor condimentum lacinia quis vel eros. Arcu risus quis varius quam quisque id. Magnis dis parturient montes nascetur ridiculus mus mauris. Porttitor leo a diam sollicitudin. Odio facilisis mauris sit amet massa vitae tortor. Nibh venenatis cras sed felis eget velit aliquet sagittis. Ullamcorper sit amet risus nullam eget felis eget nunc. In egestas erat imperdiet sed euismod nisi porta lorem mollis. A erat nam at lectus urna duis convallis. Id eu nisl nunc mi ipsum faucibus vitae. Purus ut faucibus pulvinar elementum integer enim neque volutpat ac.</p>
+  </div>
+</div>
+```
+
+### Resize
+
+The [`resize`](./layout/resize) function automatically recomputes a DOM element (often, a chart) when the dimensions of its parent container change. 
+
+Resize exists in the Observable standard library, or can be imported explicitly:
+
+```js echo
+import {resize} from "npm:@observablehq/stdlib";
+```
+
+<div>
+    ${resize((width) => Plot.barY([9, 4, 8, 1, 11, 3, 4, 2, 7, 5]).plot({width}))}
+</div>
+
+```html run=false
+<div>
+    ${resize((width) => Plot.barY([9, 4, 8, 1, 11, 3, 4, 2, 7, 5]).plot({width}))}
+</div>
+```
+
+## Observable Plot snippets
+
+[Observable Plot](https://observablehq.com/plot/) is a free, open source JavaScript library for concise and expressive data visualization, built by Observable.
+
+Several examples of Observable Plot code are included in this documentation, covering some common chart types including area charts ([stacked](./charts/area#stacked-area-chart) and [band area](./charts/area#band-area-chart)), bar charts ([sorted](./charts/bar#sorted-bar-chart), [temporal](./charts/bar#temporal-bar-chart), and [weighted](./charts/bar#weighted-top-10-bar-chart)), line charts ([single-series](./charts/line#basic-line-chart), [multi-series](./charts/line#multi-series-line-chart) and [moving average](./charts/line#moving-average-line-chart)), [scatterplots](./charts/dot#scatterplot), and more. See [Observable Plot’s gallery](https://observablehq.com/@observablehq/plot-gallery) for even more examples.
+
+All examples use common datasets that are loaded when referenced by name, such as the `weather` dataset in the code snippet below.
+
+```js echo
+Plot.plot({
+  marks: [
+    Plot.cell(weather, {
+      x: d => d.date.getUTCDate(),
+      y: d => d.date.getUTCMonth(),
+      fill: "temp_max"
+    })
+  ]
+})
+```
+
+If the chart type you want to add is not included as a snippet here, don’t sweat - a great number of examples (in both [Observable Plot](https://observablehq.com/@observablehq/plot-gallery) and [D3](https://observablehq.com/@d3/gallery)) are available to explore and reuse.
+
+**Can I use other data visualization libraries?** Absolutely. Use any other visualization library you like by [importing from npm](./javascript/imports).
+
+## Observable Inputs
+
+The [Observable Inputs](./lib/inputs) library provides a suite of lightweight interface components — buttons, sliders, dropdowns, checkboxes, and the like — that viewers can update to explore interactive displays (for example, selecting only a few of many categories to show in a bar chart).
+
+The [radio input](./inputs/radio) prompts a user to select a penguin species:
+
+```js echo
+const pickSpecies = view(Inputs.radio(["Adelie", "Chinstrap", "Gentoo"], {value: "Gentoo", label: "Penguin species:"}))
+```
+
+The value of `pickSpecies` (<tt>="${pickSpecies}"</tt>) can then be accessed elsewhere in the page, as a parameter in other computations, and to create interactive charts, tables or text with [inline expressions](./javascript#inline-expressions).