dark (#1025)

* dark

* Update docs/lib/generators.md

---------

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

docs/lib/generators.md

@@ -74,3 +74,39 @@ const width = Generators.width(document.querySelector("main"));
 ```js echo
 width
 ```
+
+## dark()
+
+Returns an async generator that yields a boolean indicating whether the page is currently displayed with a dark [color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme).
+
+If the page supports dark mode (for example with the default Framework themes), the value reflects the user’s preferred color scheme. It will yield if that value changes, and update the charts that depend on it without needing to reload the page — this happens at dusk (if the user settings adapt from light to dark), and conversely at dawn, from dark to light; and of course, when the user is playing with their settings.
+
+If the page does _not_ support dark mode, and only has a light theme, the value is always false, and likewise it is always true if the page only has a dark theme.
+
+```js echo
+html`<em>Current theme: ${dark ? "dark" : "light"}</em>`
+```
+
+This generator is available by default as `dark` in Markdown. It can be used to pick a [color scheme](https://observablehq.com/plot/features/scales#color-scales) for a chart, or an appropriate [mix-blend-mode](https://developer.mozilla.org/en-US/docs/Web/CSS/mix-blend-mode):
+
+```js echo
+Plot.plot({
+  height: 260,
+  color: {scheme: dark ? "turbo" : "blues"},
+  marks: [
+    Plot.rectY(
+      olympians,
+      Plot.binX(
+        {y2: "count"},
+        {
+          x: "weight",
+          fill: "weight",
+          z: "sex",
+          mixBlendMode: dark ? "screen" : "multiply"
+        }
+      )
+    ),
+    Plot.ruleY([0])
+  ]
+})
+```

src/client/main.js

@@ -7,6 +7,7 @@ import * as sampleDatasets from "./stdlib/sampleDatasets.js";
 const library = {
   now: () => Generators.now(),
   width: () => Generators.width(document.querySelector("main")),
+  dark: () => Generators.dark(),
   resize: () => resize,
   FileAttachment: () => FileAttachment,
   Generators: () => Generators,

src/client/stdlib/generators/dark.ts

@@ -0,0 +1,13 @@
+import {observe} from "./observe.js";
+
+// Watches dark mode based on theme and user preference.
+// TODO: in preview, also watch for changes in the theme meta.
+export function dark() {
+  return observe((notify: (dark: boolean) => void) => {
+    const media = matchMedia("(prefers-color-scheme: dark)");
+    const changed = () => notify(getComputedStyle(document.body).getPropertyValue("color-scheme") === "dark");
+    changed();
+    media.addEventListener("change", changed);
+    return () => media.removeEventListener("change", changed);
+  });
+}

src/client/stdlib/generators/index.ts

@@ -1,3 +1,4 @@
+export {dark} from "./dark.js";
 export {input} from "./input.js";
 export {now} from "./now.js";
 export {observe} from "./observe.js";