diff --git a/docs/theme/[theme].md.ts b/docs/theme/[theme].md.ts new file mode 100644 index 000000000..065dc7c58 --- /dev/null +++ b/docs/theme/[theme].md.ts @@ -0,0 +1,92 @@ +import {parseArgs} from "node:util"; +import {fileURLToPath} from "node:url"; + +export default function render(theme: string): string { + return `--- +theme: ${theme} +toc: false +head: false +header: false +sidebar: false +--- + +~~~js +const subset = new Set(["Transportation and Utilities", "Mining and Extraction", "Finance", "Agriculture", "Information"]); +const industriesSubset = industries.filter(d => subset.has(d.industry)); +const barData = [ + {Category: "Alpha", Value: 9.8}, + {Category: "Beta", Value: 7.8}, + {Category: "Gamma", Value: 6.3}, + {Category: "Delta", Value: 5}, + {Category: "Epsilon", Value: 4}, + {Category: "Zeta", Value: 3.2}, +]; +~~~ + +# Theme: ${theme} +## A preview of the \`${theme}\` [theme](../themes) + +
+
\${ + resize((width) => Plot.plot({ + title: "Construction unemployment reaches record high", + subtitle: "And it’s not just seasonal variation", + y: {grid: true, transform: (d) => d * 1000}, + color: {range: ["var(--theme-foreground-fainter)", "var(--theme-foreground-focus)"]}, + height: 320, + width, + marks: [ + Plot.ruleY([0]), + Plot.axisY({label: "Unemployed (millions)", tickFormat: (d) => (d / 1e6).toFixed(1)}), + Plot.lineY(industries, {x: "date", y: "unemployed", z: "industry", stroke: "var(--theme-foreground-fainter)", strokeWidth: 1}), + Plot.lineY(industries, {x: "date", y: "unemployed", filter: (d) => d.industry === industry, stroke: "var(--theme-foreground-focus)", tip: true}) + ] + })) + }
+
\${ + resize((width) => Plot.plot({ + title: "Vowels are some of the most frequent letters in English", + x: {grid: true, percent: true}, + marginTop: 0, + color: {domain: "AEIOUY", unknown: "var(--theme-foreground-fainter)", legend: true}, + height: 300, + width, + marks: [ + 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}}}), + Plot.ruleX([0]) + ] + })) + }
+
+ +~~~js +const industry = view(Inputs.select(industries.map((d) => d.industry), {unique: true, sort: true, label: "Industry", value: "Construction"})); +~~~ + +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. + +~~~js +Inputs.table(penguins) +~~~ + +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. + +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. +`; +} + +function normalizeTheme(theme: string | undefined): string { + if (!theme) throw new Error("missing theme"); + switch (theme) { + case "light-alt": + return "[light, alt]"; + case "dark-alt": + return "[dark, alt]"; + } + return theme; +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + const {values} = parseArgs({options: {theme: {type: "string"}}}); + process.stdout.write(render(normalizeTheme(values.theme))); +} diff --git a/docs/theme/generate-themes.ts b/docs/theme/generate-themes.ts index f22839a65..4f3a7e700 100644 --- a/docs/theme/generate-themes.ts +++ b/docs/theme/generate-themes.ts @@ -1,303 +1,7 @@ -/* eslint-disable import/no-named-as-default-member */ import {writeFile} from "node:fs/promises"; -import he from "he"; import {faint} from "../../src/tty.js"; - -const light = "air"; -const dark = "near-midnight"; - -const themes = { - light: ["air", "cotton", "glacier", "parchment"], - dark: ["coffee", "deep-space", "ink", "midnight", "near-midnight", "ocean-floor", "slate", "stark", "sun-faded"] -} as const; - -function renderThemeThumbnail(theme: string, attributes: Record = {}): string { - return ` - -`; -} - -function renderThemeSection(themes: readonly string[]): string { - return themes.map((theme) => renderThemeThumbnail(theme)).join("\n"); -} - -function renderIndex(): string { - return `# Themes - - - -\`\`\`js -for (const card of document.querySelectorAll(".card")) { - const observer = new ResizeObserver(([entry]) => { - card.style.setProperty("--container-width", entry.contentRect.width); - }); - observer.observe(card); - invalidation?.then(() => observer.disconnect()); -} -\`\`\` - -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). - -The theme is typically set via the [\`theme\` config option](./config#theme), such as: - -\`\`\`js run=false -theme: "cotton" -\`\`\` - -You can also apply a theme to an individual page via the [front matter](./markdown#front-matter): - -\`\`\`yaml ---- -theme: [glacier, slate] ---- -\`\`\` - -Here is an overview of the available themes. - -## Light mode - -The built-in light-mode color themes are: - -${themes.light.map((theme) => `- \`${theme}\`${theme === light ? " (default)" : ""}`).join("\n")} - -
${renderThemeSection(themes.light)}
- -## Dark mode - -The built-in dark-mode color themes are: - -${themes.dark.map((theme) => `- \`${theme}\`${theme === dark ? " (default)" : ""}`).join("\n")} - -
${renderThemeSection(themes.dark)}
- -## Auto mode - -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. - -
On macOS, you can create a menubar shortcut to quickly toggle between light and dark mode. This is useful for testing.
- -
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 light or dark.
- -## Modifiers - -Theme modifiers are intended to compose with the above color themes. They are: - -- \`alt\` - swap the page and card background colors -- \`wide\` - make the main column full-width - -The \`alt\` theme swaps the page and card background colors. This brings [cards](./markdown#cards) to the foreground and is recommended for dashboards. - -
${renderThemeSection(["light-alt", "light", "dark-alt", "dark"])}
- -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. - -
${renderThemeThumbnail( - "wide" - )}
- -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]\`. - -
${renderThemeThumbnail( - "dashboard" - )}
- -## Aliases - -In addition to themes and theme modifiers, there are special aliases: - -- \`default\` - either \`light\` or \`dark\` depending on user preference -- \`dashboard\` - \`[light, dark]\` if needed, plus \`alt\` and \`wide\` -- \`light\` - an alias for \`${light}\` -- \`dark\` - an alias for \`${dark}\` - -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]\`. - -## Colors - -The following custom properties are defined by the current theme: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameColorDescription
--theme-foreground
page foreground color
--theme-background
page background color
--theme-background-alt
block background color
--theme-foreground-alt
heading foreground color
--theme-foreground-muted
secondary text foreground color
--theme-foreground-faint
faint border color
--theme-foreground-fainter
fainter border color
--theme-foreground-faintest
faintest border color
--theme-foreground-focus
emphasis foreground color
- -You can use these properties anywhere you like. For example, to style a line chart to match the focus color: - -\`\`\`js echo -Plot.lineY(aapl, {x: "Date", y: "Close", stroke: "var(--theme-foreground-focus)"}).plot() -\`\`\` - -A handful of color classes are also provided: - -\`\`\`html echo -
I am red text.
-\`\`\` - -\`\`\`html echo -
I am yellow text.
-\`\`\` - -\`\`\`html echo -
I am green text.
-\`\`\` - -\`\`\`html echo -
I am blue text.
-\`\`\` - -\`\`\`html echo -
I am muted text.
-\`\`\``; -} - -function renderTheme(theme: string): string { - return `--- -theme: ${theme} -toc: false -head: false -header: false -sidebar: false ---- - -\`\`\`js -const subset = new Set(["Transportation and Utilities", "Mining and Extraction", "Finance", "Agriculture", "Information"]); -const industriesSubset = industries.filter(d => subset.has(d.industry)); -const barData = [ - {Category: "Alpha", Value: 9.8}, - {Category: "Beta", Value: 7.8}, - {Category: "Gamma", Value: 6.3}, - {Category: "Delta", Value: 5}, - {Category: "Epsilon", Value: 4}, - {Category: "Zeta", Value: 3.2}, -]; -\`\`\` - -# Theme: ${theme} -## A preview of the \`${theme}\` [theme](../themes) - -
-
\${ - resize((width) => Plot.plot({ - title: "Construction unemployment reaches record high", - subtitle: "And it’s not just seasonal variation", - y: {grid: true, transform: (d) => d * 1000}, - color: {range: ["var(--theme-foreground-fainter)", "var(--theme-foreground-focus)"]}, - height: 320, - width, - marks: [ - Plot.ruleY([0]), - Plot.axisY({label: "Unemployed (millions)", tickFormat: (d) => (d / 1e6).toFixed(1)}), - Plot.lineY(industries, {x: "date", y: "unemployed", z: "industry", stroke: "var(--theme-foreground-fainter)", strokeWidth: 1}), - Plot.lineY(industries, {x: "date", y: "unemployed", filter: (d) => d.industry === industry, stroke: "var(--theme-foreground-focus)", tip: true}) - ] - })) - }
-
\${ - resize((width) => Plot.plot({ - title: "Vowels are some of the most frequent letters in English", - x: {grid: true, percent: true}, - marginTop: 0, - color: {domain: "AEIOUY", unknown: "var(--theme-foreground-fainter)", legend: true}, - height: 300, - width, - marks: [ - 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}}}), - Plot.ruleX([0]) - ] - })) - }
-
- -\`\`\`js -const industry = view(Inputs.select(industries.map((d) => d.industry), {unique: true, sort: true, label: "Industry", value: "Construction"})); -\`\`\` - -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. - -\`\`\`js -Inputs.table(penguins) -\`\`\` - -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. - -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.`; -} +import renderIndex, {themes} from "../themes.md.js"; +import renderTheme from "./[theme].md.js"; async function generateFile(path: string, contents: string): Promise { console.log(`${faint("generating")} ${path}`); diff --git a/docs/themes.md.ts b/docs/themes.md.ts new file mode 100644 index 000000000..1fad3becb --- /dev/null +++ b/docs/themes.md.ts @@ -0,0 +1,231 @@ +/* eslint-disable import/no-named-as-default-member */ +import {fileURLToPath} from "node:url"; +import he from "he"; + +const light = "air"; +const dark = "near-midnight"; + +export const themes = { + light: ["air", "cotton", "glacier", "parchment"], + dark: ["coffee", "deep-space", "ink", "midnight", "near-midnight", "ocean-floor", "slate", "stark", "sun-faded"] +} as const; + +function renderThemeThumbnail(theme: string, attributes: Record = {}): string { + return ` + +`; +} + +function renderThemeSection(themes: readonly string[]): string { + return themes.map((theme) => renderThemeThumbnail(theme)).join("\n"); +} + +export default function render(): string { + return `# Themes + + + +~~~js +for (const card of document.querySelectorAll(".card")) { + const observer = new ResizeObserver(([entry]) => { + card.style.setProperty("--container-width", entry.contentRect.width); + }); + observer.observe(card); + invalidation?.then(() => observer.disconnect()); +} +~~~ + +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). + +The theme is typically set via the [\`theme\` config option](./config#theme), such as: + +~~~js run=false +theme: "cotton" +~~~ + +You can also apply a theme to an individual page via the [front matter](./markdown#front-matter): + +~~~yaml +--- +theme: [glacier, slate] +--- +~~~ + +Here is an overview of the available themes. + +## Light mode + +The built-in light-mode color themes are: + +${themes.light.map((theme) => `- \`${theme}\`${theme === light ? " (default)" : ""}`).join("\n")} + +
${renderThemeSection(themes.light)}
+ +## Dark mode + +The built-in dark-mode color themes are: + +${themes.dark.map((theme) => `- \`${theme}\`${theme === dark ? " (default)" : ""}`).join("\n")} + +
${renderThemeSection(themes.dark)}
+ +## Auto mode + +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. + +
On macOS, you can create a menubar shortcut to quickly toggle between light and dark mode. This is useful for testing.
+ +
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 light or dark.
+ +## Modifiers + +Theme modifiers are intended to compose with the above color themes. They are: + +- \`alt\` - swap the page and card background colors +- \`wide\` - make the main column full-width + +The \`alt\` theme swaps the page and card background colors. This brings [cards](./markdown#cards) to the foreground and is recommended for dashboards. + +
${renderThemeSection(["light-alt", "light", "dark-alt", "dark"])}
+ +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. + +
${renderThemeThumbnail( + "wide" + )}
+ +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]\`. + +
${renderThemeThumbnail( + "dashboard" + )}
+ +## Aliases + +In addition to themes and theme modifiers, there are special aliases: + +- \`default\` - either \`light\` or \`dark\` depending on user preference +- \`dashboard\` - \`[light, dark]\` if needed, plus \`alt\` and \`wide\` +- \`light\` - an alias for \`${light}\` +- \`dark\` - an alias for \`${dark}\` + +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]\`. + +## Colors + +The following custom properties are defined by the current theme: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameColorDescription
--theme-foreground
page foreground color
--theme-background
page background color
--theme-background-alt
block background color
--theme-foreground-alt
heading foreground color
--theme-foreground-muted
secondary text foreground color
--theme-foreground-faint
faint border color
--theme-foreground-fainter
fainter border color
--theme-foreground-faintest
faintest border color
--theme-foreground-focus
emphasis foreground color
+ +You can use these properties anywhere you like. For example, to style a line chart to match the focus color: + +~~~js echo +Plot.lineY(aapl, {x: "Date", y: "Close", stroke: "var(--theme-foreground-focus)"}).plot() +~~~ + +A handful of color classes are also provided: + +~~~html echo +
I am red text.
+~~~ + +~~~html echo +
I am yellow text.
+~~~ + +~~~html echo +
I am green text.
+~~~ + +~~~html echo +
I am blue text.
+~~~ + +~~~html echo +
I am muted text.
+~~~ +`; +} + +if (process.argv[1] === fileURLToPath(import.meta.url)) { + process.stdout.write(render()); +}