Skip to content

Commit 1f7489b

Browse files
mbostockmbostock
authored
themes as parameterized page loaders (#1587)
1 parent 329d89c commit 1f7489b

File tree

3 files changed

+325
-298
lines changed

3 files changed

+325
-298
lines changed

‎docs/theme/[theme].md.ts

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
import {parseArgs} from "node:util";
2+
import {fileURLToPath} from "node:url";
3+
4+
export default function render(theme: string): string {
5+
return `---
6+
theme: ${theme}
7+
toc: false
8+
head: false
9+
header: false
10+
sidebar: false
11+
---
12+
13+
~~~js
14+
const subset = new Set(["Transportation and Utilities", "Mining and Extraction", "Finance", "Agriculture", "Information"]);
15+
const industriesSubset = industries.filter(d => subset.has(d.industry));
16+
const barData = [
17+
{Category: "Alpha", Value: 9.8},
18+
{Category: "Beta", Value: 7.8},
19+
{Category: "Gamma", Value: 6.3},
20+
{Category: "Delta", Value: 5},
21+
{Category: "Epsilon", Value: 4},
22+
{Category: "Zeta", Value: 3.2},
23+
];
24+
~~~
25+
26+
# Theme: ${theme}
27+
## A preview of the \`${theme}\` [theme](../themes)
28+
29+
<div class="grid grid-cols-2">
30+
<div class="card">\${
31+
resize((width) => Plot.plot({
32+
title: "Construction unemployment reaches record high",
33+
subtitle: "And it’s not just seasonal variation",
34+
y: {grid: true, transform: (d) => d * 1000},
35+
color: {range: ["var(--theme-foreground-fainter)", "var(--theme-foreground-focus)"]},
36+
height: 320,
37+
width,
38+
marks: [
39+
Plot.ruleY([0]),
40+
Plot.axisY({label: "Unemployed (millions)", tickFormat: (d) => (d / 1e6).toFixed(1)}),
41+
Plot.lineY(industries, {x: "date", y: "unemployed", z: "industry", stroke: "var(--theme-foreground-fainter)", strokeWidth: 1}),
42+
Plot.lineY(industries, {x: "date", y: "unemployed", filter: (d) => d.industry === industry, stroke: "var(--theme-foreground-focus)", tip: true})
43+
]
44+
}))
45+
}</div>
46+
<div class="card">\${
47+
resize((width) => Plot.plot({
48+
title: "Vowels are some of the most frequent letters in English",
49+
x: {grid: true, percent: true},
50+
marginTop: 0,
51+
color: {domain: "AEIOUY", unknown: "var(--theme-foreground-fainter)", legend: true},
52+
height: 300,
53+
width,
54+
marks: [
55+
Plot.rectX(alphabet, {x: "frequency", y: "letter", fill: (d) => /[aeiouy]/i.test(d.letter) ? d.letter : "other", sort: {y: "-x"}, tip: {format: {x: true, y: true}}}),
56+
Plot.ruleX([0])
57+
]
58+
}))
59+
}</div>
60+
</div>
61+
62+
~~~js
63+
const industry = view(Inputs.select(industries.map((d) => d.industry), {unique: true, sort: true, label: "Industry", value: "Construction"}));
64+
~~~
65+
66+
Call me Ishmael. Some years ago — never mind how long precisely — having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation.
67+
68+
~~~js
69+
Inputs.table(penguins)
70+
~~~
71+
72+
Whenever I find myself growing grim about the mouth; whenever it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my hypos get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into the street, and methodically knocking people’s hats off — then, I account it high time to get to sea as soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself upon his sword; I quietly take to the ship.
73+
74+
There is nothing surprising in this. If they but knew it, almost all men in their degree, some time or other, cherish very nearly the same feelings towards the ocean with me.
75+
`;
76+
}
77+
78+
function normalizeTheme(theme: string | undefined): string {
79+
if (!theme) throw new Error("missing theme");
80+
switch (theme) {
81+
case "light-alt":
82+
return "[light, alt]";
83+
case "dark-alt":
84+
return "[dark, alt]";
85+
}
86+
return theme;
87+
}
88+
89+
if (process.argv[1] === fileURLToPath(import.meta.url)) {
90+
const {values} = parseArgs({options: {theme: {type: "string"}}});
91+
process.stdout.write(render(normalizeTheme(values.theme)));
92+
}

‎docs/theme/generate-themes.ts

Lines changed: 2 additions & 298 deletions
Original file line numberDiff line numberDiff line change
@@ -1,303 +1,7 @@
1-
/* eslint-disable import/no-named-as-default-member */
21
import {writeFile} from "node:fs/promises";
3-
import he from "he";
42
import {faint} from "../../src/tty.js";
5-
6-
const light = "air";
7-
const dark = "near-midnight";
8-
9-
const themes = {
10-
light: ["air", "cotton", "glacier", "parchment"],
11-
dark: ["coffee", "deep-space", "ink", "midnight", "near-midnight", "ocean-floor", "slate", "stark", "sun-faded"]
12-
} as const;
13-
14-
function renderThemeThumbnail(theme: string, attributes: Record<string, string> = {}): string {
15-
return `<a href="./theme/${theme}" target="_blank" class="card thumbnail">
16-
<iframe loading="lazy" scrolling="no" src="./theme/${theme}"${Object.entries(attributes)
17-
.map(([name, value]) => `${name}="${he.escape(value)}"`)
18-
.join(" ")}></iframe>
19-
</a>`;
20-
}
21-
22-
function renderThemeSection(themes: readonly string[]): string {
23-
return themes.map((theme) => renderThemeThumbnail(theme)).join("\n");
24-
}
25-
26-
function renderIndex(): string {
27-
return `# Themes
28-
29-
<style>
30-
31-
:root {
32-
--thumbnail-width: 920;
33-
--thumbnail-height: 450;
34-
}
35-
36-
.thumbnail {
37-
padding: 0;
38-
aspect-ratio: var(--thumbnail-width) / var(--thumbnail-height);
39-
overflow: hidden;
40-
}
41-
42-
.thumbnail iframe {
43-
transform: scale(calc(var(--container-width) / var(--thumbnail-width)));
44-
transform-origin: top left;
45-
pointer-events: none;
46-
width: calc(var(--thumbnail-width) * 1px);
47-
height: calc(var(--thumbnail-height) * 1px);
48-
border: none;
49-
}
50-
51-
</style>
52-
53-
\`\`\`js
54-
for (const card of document.querySelectorAll(".card")) {
55-
const observer = new ResizeObserver(([entry]) => {
56-
card.style.setProperty("--container-width", entry.contentRect.width);
57-
});
58-
observer.observe(card);
59-
invalidation?.then(() => observer.disconnect());
60-
}
61-
\`\`\`
62-
63-
Themes affect the visual appearance of pages by specifying colors and fonts, or by augmenting default styles. Framework includes several built-in themes, but you can also design your own themes by specifying a [custom stylesheet](./config#style).
64-
65-
The theme is typically set via the [\`theme\` config option](./config#theme), such as:
66-
67-
\`\`\`js run=false
68-
theme: "cotton"
69-
\`\`\`
70-
71-
You can also apply a theme to an individual page via the [front matter](./markdown#front-matter):
72-
73-
\`\`\`yaml
74-
---
75-
theme: [glacier, slate]
76-
---
77-
\`\`\`
78-
79-
Here is an overview of the available themes.
80-
81-
## Light mode
82-
83-
The built-in light-mode color themes are:
84-
85-
${themes.light.map((theme) => `- \`${theme}\`${theme === light ? " (default)" : ""}`).join("\n")}
86-
87-
<div class="grid grid-cols-2">${renderThemeSection(themes.light)}</div>
88-
89-
## Dark mode
90-
91-
The built-in dark-mode color themes are:
92-
93-
${themes.dark.map((theme) => `- \`${theme}\`${theme === dark ? " (default)" : ""}`).join("\n")}
94-
95-
<div class="grid grid-cols-2">${renderThemeSection(themes.dark)}</div>
96-
97-
## Auto mode
98-
99-
When both a light and a dark mode theme are specified, theme styles are applied selectively based on the user’s preferred color scheme. This is implemented via [\`prefers-color-scheme\`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme) and typically relies on the user’s operating system settings.
100-
101-
<div class="tip">On macOS, you can create a menubar <a href="https://support.apple.com/guide/shortcuts-mac/intro-to-shortcuts-apdf22b0444c/mac">shortcut</a> to quickly toggle between light and dark mode. This is useful for testing.</div>
102-
103-
<div class="tip">Designing charts that work well in both light and dark mode can be challenging. If you’d prefer to design for only one mode, set the theme explicitly to <code>light</code> or <code>dark</code>.</div>
104-
105-
## Modifiers
106-
107-
Theme modifiers are intended to compose with the above color themes. They are:
108-
109-
- \`alt\` - swap the page and card background colors
110-
- \`wide\` - make the main column full-width
111-
112-
The \`alt\` theme swaps the page and card background colors. This brings [cards](./markdown#cards) to the foreground and is recommended for dashboards.
113-
114-
<div class="grid grid-cols-2">${renderThemeSection(["light-alt", "light", "dark-alt", "dark"])}</div>
115-
116-
The \`wide\` theme removes the maximum width constraint of the main column, which is normally 1152 pixels, allowing it to span the full width of the page. This is recommended for dashboards and is typically combined with the \`alt\` theme modifier and \`toc: false\` to disable the table of contents.
117-
118-
<div class="grid grid-cols-1" style="--thumbnail-width: 1600; --thumbnail-height: 800; max-width: 640px;">${renderThemeThumbnail(
119-
"wide"
120-
)}</div>
121-
122-
The \`dashboard\` [theme alias](#aliases) composes the default light and dark themes (\`${light}\` and \`${dark}\`) with the \`alt\` and \`wide\` modifiers. On its own, \`dashboard\` is equivalent to \`[light, dark, alt, wide]\`.
123-
124-
<div class="grid grid-cols-1" style="--thumbnail-width: 1600; --thumbnail-height: 800; max-width: 640px;">${renderThemeThumbnail(
125-
"dashboard"
126-
)}</div>
127-
128-
## Aliases
129-
130-
In addition to themes and theme modifiers, there are special aliases:
131-
132-
- \`default\` - either \`light\` or \`dark\` depending on user preference
133-
- \`dashboard\` - \`[light, dark]\` if needed, plus \`alt\` and \`wide\`
134-
- \`light\` - an alias for \`${light}\`
135-
- \`dark\` - an alias for \`${dark}\`
136-
137-
On its own, \`default\` is equivalent to \`[light, dark]\` (or \`[${light}, ${dark}]\`). The \`default\` theme is applied by default if you don’t specify any color theme. You can also use \`default\` to combine a specific light or dark theme with the default theme of the opposing mode; for example \`[cotton, default]\` is equivalent to \`[cotton, dark]\`, and \`[coffee, default]\` is equivalent to \`[coffee, light]\`.
138-
139-
## Colors
140-
141-
The following custom properties are defined by the current theme:
142-
143-
<table>
144-
<thead>
145-
<tr>
146-
<th>Name</th>
147-
<th>Color</th>
148-
<th>Description</th>
149-
</tr>
150-
</thead>
151-
<tbody>
152-
<tr>
153-
<td><code>--theme-foreground</code></td>
154-
<td><div style="background-color: var(--theme-foreground); width: 2rem; height: 1rem;"></div></td>
155-
<td>page foreground color</td>
156-
</tr>
157-
<tr>
158-
<td><code>--theme-background</code></td>
159-
<td><div style="background-color: var(--theme-background); width: 2rem; height: 1rem;"></div></td>
160-
<td>page background color</td>
161-
</tr>
162-
<tr>
163-
<td><code>--theme-background-alt</code></td>
164-
<td><div style="background-color: var(--theme-background-alt); width: 2rem; height: 1rem;"></div></td>
165-
<td>block background color</td>
166-
</tr>
167-
<tr>
168-
<td><code>--theme-foreground-alt</code></td>
169-
<td><div style="background-color: var(--theme-foreground-alt); width: 2rem; height: 1rem;"></div></td>
170-
<td>heading foreground color</td>
171-
</tr>
172-
<tr>
173-
<td><code>--theme-foreground-muted</code></td>
174-
<td><div style="background-color: var(--theme-foreground-muted); width: 2rem; height: 1rem;"></div></td>
175-
<td>secondary text foreground color</td>
176-
</tr>
177-
<tr>
178-
<td><code>--theme-foreground-faint</code></td>
179-
<td><div style="background-color: var(--theme-foreground-faint); width: 2rem; height: 1rem;"></div></td>
180-
<td>faint border color</td>
181-
</tr>
182-
<tr>
183-
<td><code>--theme-foreground-fainter</code></td>
184-
<td><div style="background-color: var(--theme-foreground-fainter); width: 2rem; height: 1rem;"></div></td>
185-
<td>fainter border color</td>
186-
</tr>
187-
<tr>
188-
<td><code>--theme-foreground-faintest</code></td>
189-
<td><div style="background-color: var(--theme-foreground-faintest); width: 2rem; height: 1rem;"></div></td>
190-
<td>faintest border color</td>
191-
</tr>
192-
<tr>
193-
<td><code>--theme-foreground-focus</code></td>
194-
<td><div style="background-color: var(--theme-foreground-focus); width: 2rem; height: 1rem;"></div></td>
195-
<td>emphasis foreground color</td>
196-
</tr>
197-
</tbody>
198-
</table>
199-
200-
You can use these properties anywhere you like. For example, to style a line chart to match the focus color:
201-
202-
\`\`\`js echo
203-
Plot.lineY(aapl, {x: "Date", y: "Close", stroke: "var(--theme-foreground-focus)"}).plot()
204-
\`\`\`
205-
206-
A handful of color classes are also provided:
207-
208-
\`\`\`html echo
209-
<div class="red">I am red text.</div>
210-
\`\`\`
211-
212-
\`\`\`html echo
213-
<div class="yellow">I am yellow text.</div>
214-
\`\`\`
215-
216-
\`\`\`html echo
217-
<div class="green">I am green text.</div>
218-
\`\`\`
219-
220-
\`\`\`html echo
221-
<div class="blue">I am blue text.</div>
222-
\`\`\`
223-
224-
\`\`\`html echo
225-
<div class="muted">I am muted text.</div>
226-
\`\`\``;
227-
}
228-
229-
function renderTheme(theme: string): string {
230-
return `---
231-
theme: ${theme}
232-
toc: false
233-
head: false
234-
header: false
235-
sidebar: false
236-
---
237-
238-
\`\`\`js
239-
const subset = new Set(["Transportation and Utilities", "Mining and Extraction", "Finance", "Agriculture", "Information"]);
240-
const industriesSubset = industries.filter(d => subset.has(d.industry));
241-
const barData = [
242-
{Category: "Alpha", Value: 9.8},
243-
{Category: "Beta", Value: 7.8},
244-
{Category: "Gamma", Value: 6.3},
245-
{Category: "Delta", Value: 5},
246-
{Category: "Epsilon", Value: 4},
247-
{Category: "Zeta", Value: 3.2},
248-
];
249-
\`\`\`
250-
251-
# Theme: ${theme}
252-
## A preview of the \`${theme}\` [theme](../themes)
253-
254-
<div class="grid grid-cols-2">
255-
<div class="card">\${
256-
resize((width) => Plot.plot({
257-
title: "Construction unemployment reaches record high",
258-
subtitle: "And it’s not just seasonal variation",
259-
y: {grid: true, transform: (d) => d * 1000},
260-
color: {range: ["var(--theme-foreground-fainter)", "var(--theme-foreground-focus)"]},
261-
height: 320,
262-
width,
263-
marks: [
264-
Plot.ruleY([0]),
265-
Plot.axisY({label: "Unemployed (millions)", tickFormat: (d) => (d / 1e6).toFixed(1)}),
266-
Plot.lineY(industries, {x: "date", y: "unemployed", z: "industry", stroke: "var(--theme-foreground-fainter)", strokeWidth: 1}),
267-
Plot.lineY(industries, {x: "date", y: "unemployed", filter: (d) => d.industry === industry, stroke: "var(--theme-foreground-focus)", tip: true})
268-
]
269-
}))
270-
}</div>
271-
<div class="card">\${
272-
resize((width) => Plot.plot({
273-
title: "Vowels are some of the most frequent letters in English",
274-
x: {grid: true, percent: true},
275-
marginTop: 0,
276-
color: {domain: "AEIOUY", unknown: "var(--theme-foreground-fainter)", legend: true},
277-
height: 300,
278-
width,
279-
marks: [
280-
Plot.rectX(alphabet, {x: "frequency", y: "letter", fill: (d) => /[aeiouy]/i.test(d.letter) ? d.letter : "other", sort: {y: "-x"}, tip: {format: {x: true, y: true}}}),
281-
Plot.ruleX([0])
282-
]
283-
}))
284-
}</div>
285-
</div>
286-
287-
\`\`\`js
288-
const industry = view(Inputs.select(industries.map((d) => d.industry), {unique: true, sort: true, label: "Industry", value: "Construction"}));
289-
\`\`\`
290-
291-
Call me Ishmael. Some years ago — never mind how long precisely — having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation.
292-
293-
\`\`\`js
294-
Inputs.table(penguins)
295-
\`\`\`
296-
297-
Whenever I find myself growing grim about the mouth; whenever it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my hypos get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into the street, and methodically knocking people’s hats off — then, I account it high time to get to sea as soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself upon his sword; I quietly take to the ship.
298-
299-
There is nothing surprising in this. If they but knew it, almost all men in their degree, some time or other, cherish very nearly the same feelings towards the ocean with me.`;
300-
}
3+
import renderIndex, {themes} from "../themes.md.js";
4+
import renderTheme from "./[theme].md.js";
3015

3026
async function generateFile(path: string, contents: string): Promise<void> {
3037
console.log(`${faint("generating")} ${path}`);

0 commit comments

Comments
 (0)