Skip to content

Commit 3b6e75b

Browse files
trebortrebor
committed
Merge branch 'components' of https://github.com/observablehq/cli into components
2 parents 1256daa + 1b197cc commit 3b6e75b

File tree

10 files changed

+350
-28
lines changed

10 files changed

+350
-28
lines changed

‎docs/charts/grouping-data.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Grouping data
2+
3+
[Observable Plot](https://observablehq.com/plot/) provides a number of [transforms](https://observablehq.com/plot/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.
4+
5+
## Hexbin chart
6+
7+
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).
8+
9+
```js echo
10+
Plot.plot({
11+
color: {scheme: "ylgnbu"},
12+
marks: [
13+
Plot.dot(olympians, Plot.hexbin({fill: "sum"}, {x: "weight", y: "height"}))
14+
]
15+
})
16+
```
17+
18+
## Histogram
19+
20+
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).
21+
22+
```js echo
23+
Plot.plot({
24+
marks: [
25+
Plot.rectY(olympians, Plot.binX({y: "count"}, {x: "weight"})),
26+
Plot.ruleY([0])
27+
]
28+
})
29+
```

‎docs/charts/hexbin.md

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎docs/charts/histogram.md

Lines changed: 0 additions & 12 deletions
This file was deleted.

‎docs/components.md

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Components
2+
3+
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.
4+
5+
The Observable CLI offers three flavors of components: [layout helpers](#layout-helpers), [Observable Plot snippets](#observable-plot-snippets), and [Observable Inputs](#observable-inputs).
6+
7+
## Layout helpers
8+
9+
A collection of elements useful for formatting page content: themes, cards, and the `resize` function.
10+
11+
### Themes
12+
13+
<!-- TODO update link to themes gallery page once added-->
14+
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:
15+
16+
```js run=false
17+
theme: ["dark-alt", "wide"]
18+
```
19+
20+
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):
21+
22+
```yaml
23+
---
24+
theme: ["dark-alt", "wide"]
25+
---
26+
```
27+
28+
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.
29+
30+
### Grid
31+
32+
The included [`grid`](./layout/grid) CSS classes make it easier to control how page content is arranged.
33+
34+
<div class="grid grid-cols-2">
35+
<div class="card"><h1>A</h1>1 × 1</div>
36+
<div class="card grid-rowspan-2"><h1>B</h1> 1 × 2</div>
37+
<div class="card"><h1>C</h1>1 × 1</div>
38+
<div class="card grid-colspan-2"><h1>D</h1>1 × 2</div>
39+
</div>
40+
41+
```html run=false
42+
<div class="grid grid-cols-2">
43+
<div class="card"><h1>A</h1>1 × 1</div>
44+
<div class="card grid-rowspan-2"><h1>B</h1> 1 × 2</div>
45+
<div class="card"><h1>C</h1>1 × 1</div>
46+
<div class="card grid-colspan-2"><h1>D</h1>1 × 2</div>
47+
</div>
48+
```
49+
50+
### Card
51+
52+
The [`card`](./layout/card) CSS class has default styles that help create a card: container borders, background color, padding and optional titles and subtitles.
53+
54+
<div class="grid grid-cols-2">
55+
<div class="card">
56+
<h2>A card title</h2>
57+
<h3>A card subtitle</h3>
58+
${
59+
Plot.plot({
60+
marks: [
61+
Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm"})
62+
]
63+
})
64+
}
65+
</div>
66+
<div class="card">
67+
<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>
68+
</div>
69+
</div>
70+
71+
```html run=false
72+
<div class="grid grid-cols-2">
73+
<div class="card">
74+
<h2>A card title</h2>
75+
<h3>A card subtitle</h3>
76+
${
77+
Plot.plot({
78+
marks: [
79+
Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm"})
80+
]
81+
})
82+
}
83+
</div>
84+
<div class="card">
85+
<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>
86+
</div>
87+
</div>
88+
```
89+
90+
### Resize
91+
92+
<!-- TODO update link to layout/grid?-->
93+
The [`resize`](./javascript/display#responsive-display) function automatically recomputes a DOM element (often, a chart) when the dimensions of its parent container change.
94+
95+
Resize exists in the Observable standard library, or can be imported explicitly:
96+
97+
```js
98+
import {resize} from "npm:@observablehq/stdlib";
99+
```
100+
101+
<div>
102+
${resize((width) => Plot.barY([9, 4, 8, 1, 11, 3, 4, 2, 7, 5]).plot({width}))}
103+
</div>
104+
105+
```html run=false
106+
<div>
107+
${resize((width) => Plot.barY([9, 4, 8, 1, 11, 3, 4, 2, 7, 5]).plot({width}))}
108+
</div>
109+
```
110+
111+
## Observable Plot snippets
112+
113+
[Observable Plot](https://observablehq.com/plot/) is a free, open source JavaScript library for concise and expressive data visualization, built by Observable.
114+
115+
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.
116+
117+
All our examples use common datasets that are loaded when referenced by name, such as the `weather` dataset in the code snippet below.
118+
119+
```js echo
120+
Plot.plot({
121+
marks: [
122+
Plot.cell(weather, {
123+
x: d => d.date.getUTCDate(),
124+
y: d => d.date.getUTCMonth(),
125+
fill: "temp_max"
126+
})
127+
]
128+
})
129+
```
130+
131+
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.
132+
133+
**Can I use other data visualization libraries?** Absolutely. Use any other visualization library you like by [importing from npm](./javascript/imports).
134+
135+
## Observable Inputs
136+
137+
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).
138+
139+
The [radio input](./inputs/radio) prompts a user to select a penguin species:
140+
141+
```js echo
142+
const pickSpecies = view(Inputs.radio(["Adelie", "Chinstrap", "Gentoo"], {value: "Gentoo", label: "Penguin species:"}))
143+
```
144+
145+
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).

‎docs/layout/annotation.md

Whitespace-only changes.

‎docs/layout/bignumber.md

Whitespace-only changes.

‎docs/layout/card.md

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# Cards
2+
3+
The `card` class adds polished styling to page content including a background and border color determined by the page theme, default padding, and an optional title and subtitle that match title styling for other components.
4+
5+
<div class="card">
6+
<h2>This is a card</h2>
7+
<h3>Cards add polished formatting to page content.</h3>
8+
${
9+
Plot.plot({
10+
marks: [
11+
Plot.cell(weather, {x: d => d.date.getUTCDate(), y: d => d.date.getUTCMonth(),fill: "temp_max"})
12+
]
13+
})
14+
}
15+
</div>
16+
17+
```html run=false
18+
<div class="card">
19+
<h2>This is a card</h2>
20+
<h3>Cards add polished formatting to page content.</h3>
21+
${
22+
Plot.plot({
23+
marks: [
24+
Plot.cell(weather, {x: d => d.date.getUTCDate(), y: d => d.date.getUTCMonth(),fill: "temp_max"})
25+
]
26+
})
27+
}
28+
</div>
29+
```
30+
31+
## Card content
32+
33+
Cards can contain whatever content you like, including text, images, charts, tables, inputs, and more.
34+
35+
<div class="grid grid-cols-2">
36+
<div class="card">
37+
<h2>Lorem ipsum</h2>
38+
<p>Id ornare arcu odio ut sem nulla pharetra. Aliquet lectus proin nibh nisl condimentum id venenatis a. Feugiat sed lectus vestibulum mattis ullamcorper velit. Aliquet nec ullamcorper sit amet. Sit amet tellus cras adipiscing. Condimentum id venenatis a condimentum vitae. Semper eget duis at tellus. Ut faucibus pulvinar elementum integer enim.</p>
39+
<p>Et malesuada fames ac turpis. Integer vitae justo eget magna fermentum iaculis eu non diam. Aliquet risus feugiat in ante metus dictum at. Consectetur purus ut faucibus pulvinar.</p>
40+
</div>
41+
<div class="card">
42+
<img src="../javascript/horse.jpg" width="100%">
43+
</div>
44+
<div class="card">
45+
${
46+
Plot.plot({
47+
marks: [
48+
Plot.rectY(olympians, Plot.binX({y: "count"}, {x: "weight"})),
49+
Plot.ruleY([0])
50+
]
51+
})
52+
}
53+
</div>
54+
<div class="card">
55+
${pickIndustry}
56+
${Inputs.table(industries.filter(d => d.industry === industryInput))}
57+
</div>
58+
</div>
59+
60+
```js echo
61+
const pickIndustry = Inputs.select(industries.map(d => d.industry), {unique: true, label: "Industry:"});
62+
const industryInput = view(pickIndustry)
63+
```
64+
65+
```html run=false
66+
<div class="grid grid-cols-2">
67+
<div class="card">
68+
<h2>Lorem ipsum</h2>
69+
<p>Id ornare arcu odio ut sem nulla pharetra. Aliquet lectus proin nibh nisl condimentum id venenatis a. Feugiat sed lectus vestibulum mattis ullamcorper velit. Aliquet nec ullamcorper sit amet. Sit amet tellus cras adipiscing. Condimentum id venenatis a condimentum vitae. Semper eget duis at tellus. Ut faucibus pulvinar elementum integer enim.</p>
70+
<p>Et malesuada fames ac turpis. Integer vitae justo eget magna fermentum iaculis eu non diam. Aliquet risus feugiat in ante metus dictum at. Consectetur purus ut faucibus pulvinar.</p>
71+
</div>
72+
<div class="card">
73+
<img src="../javascript/horse.jpg" width="100%">
74+
</div>
75+
<div class="card">
76+
${
77+
Plot.plot({
78+
marks: [
79+
Plot.rectY(olympians, Plot.binX({y: "count"}, {x: "weight"})),
80+
Plot.ruleY([0])
81+
]
82+
})
83+
}
84+
</div>
85+
<div class="card">
86+
${pickIndustry}
87+
${Inputs.table(industries.filter(d => d.industry === industryInput))}
88+
</div>
89+
</div>
90+
```
91+
92+
## Title and subtitle
93+
94+
Card titles and subtitles are added with h2 and h3 headers, respectively, and match the title styling in [Observable Plot](https://observablehq.com/plot/features/plots#other-options):
95+
96+
<div class="grid grid-cols-2"">
97+
<div class="card">
98+
<h2>A card title added as an h2 element</h2>
99+
<h3>A card subtitle added as an h3 element</h3>
100+
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
101+
<p>Massa sapien faucibus et molestie ac feugiat sed lectus. Sit amet volutpat consequat mauris nunc congue nisi. Maecenas pharetra convallis posuere morbi leo urna molestie at.</p>
102+
</div>
103+
<div class="card">
104+
${
105+
Plot.plot({
106+
title: "A chart title added in Observable Plot",
107+
subtitle: "A chart subtitle added in Observable Plot",
108+
marks: [
109+
Plot.areaY(industries, {x: "date", y: "unemployed", fill: "industry"}),
110+
]
111+
})
112+
}
113+
</div>
114+
</div>
115+
116+
```html run=false
117+
<div class="grid grid-cols-2"">
118+
<div class="card">
119+
<h2>A card title added as an h2 element</h2>
120+
<h3>A card subtitle added as an h3 element</h3>
121+
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.</p>
122+
<p>Massa sapien faucibus et molestie ac feugiat sed lectus. Sit amet volutpat consequat mauris nunc congue nisi. Maecenas pharetra convallis posuere morbi leo urna molestie at.</p>
123+
</div>
124+
<div class="card">
125+
${
126+
Plot.plot({
127+
title: "A chart title added in Observable Plot",
128+
subtitle: "A chart subtitle added in Observable Plot",
129+
marks: [
130+
Plot.areaY(industries, {x: "date", y: "unemployed", fill: "industry"}),
131+
]
132+
})
133+
}
134+
</div>
135+
</div>
136+
```
137+
138+
## Content without cards
139+
140+
Page content does not have to be within a card. Below, explanatory text is added to the right of a card.
141+
142+
<div class="grid grid-cols-2"">
143+
<div class="card">
144+
${
145+
Plot.plot({
146+
color: {legend: true},
147+
marks: [
148+
Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm", fill: "species", tip: true})
149+
]
150+
})
151+
}
152+
</div>
153+
<div>
154+
<p>Body mass (g) and flipper length (mm) for ${penguins.length} individual penguins (${penguins.filter(d => d.species === "Adelie").length} Adélie, ${penguins.filter(d => d.species === "Chinstrap").length} Chinstrap, and ${penguins.filter(d => d.species === "Gentoo").length} Gentoo) recorded on Dream, Biscoe, or Torgersen islands near Palmer Archipelago, Antarctica from 2007 — 2009. Data: <a href="https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0090081">K. B. Gorman et al. 2014.</a> </p>
155+
</div>
156+
</div>
157+
158+
```html run=false
159+
<div class="grid grid-cols-2"">
160+
<div class="card">
161+
${
162+
Plot.plot({
163+
color: {legend: true},
164+
marks: [
165+
Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm", fill: "species", tip: true})
166+
]
167+
})
168+
}
169+
</div>
170+
<div>
171+
<p>Body mass (g) and flipper length (mm) for ${penguins.length} individual penguins (${penguins.filter(d => d.species === "Adelie").length} Adélie, ${penguins.filter(d => d.species === "Chinstrap").length} Chinstrap, and ${penguins.filter(d => d.species === "Gentoo").length} Gentoo) recorded on Dream, Biscoe, or Torgersen islands near Palmer Archipelago, Antarctica from 2007 — 2009. Data: <a href="https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0090081">K. B. Gorman et al. 2014.</a> </p>
172+
</div>
173+
</div>
174+
```

‎docs/layout/tables.md

Whitespace-only changes.

‎docs/layout/themes.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Themes

‎observablehq.config.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,9 @@ export default {
4343
{name: "Cell", path: "/charts/cell"},
4444
{name: "Dot", path: "/charts/dot"},
4545
{name: "Facets", path: "/charts/facets"},
46-
{name: "Hexbin", path: "/charts/hexbin"},
4746
{name: "Line", path: "/charts/line"},
4847
{name: "Tick", path: "/charts/tick"},
48+
{name: "Grouping data", path: "/charts/grouping-data"}
4949
]
5050
},
5151
{

0 commit comments

Comments
 (0)