Merge branch 'main' into fil/render-api-docs

Author: Fil

.github/workflows/deploy.yml

@@ -15,18 +15,18 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
-          cache: 'yarn'
+          node-version: 20
+          cache: yarn
       - run: yarn --frozen-lockfile
       - run: yarn prepublishOnly
       - run: yarn docs:build
-      - uses: actions/configure-pages@v3
-      - uses: actions/upload-pages-artifact@v1
+      - uses: actions/configure-pages@v4
+      - uses: actions/upload-pages-artifact@v3
         with:
           path: docs/.vitepress/dist
       - name: Deploy
         id: deployment
-        uses: actions/deploy-pages@v1
+        uses: actions/deploy-pages@v4

.github/workflows/publish.yml

@@ -0,0 +1,25 @@
+name: Publish
+
+on:
+  workflow_dispatch: {}
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'yarn'
+      - run: yarn --frozen-lockfile
+      - run: yarn test
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test.yml

@@ -10,11 +10,11 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          node-version: 16
-          cache: 'yarn'
+          node-version: 20
+          cache: yarn
       - run: yarn --frozen-lockfile
       - run: yarn test:mocha
       - run: yarn test:tsc
@@ -24,7 +24,7 @@ jobs:
       - run: yarn test:prettier
       - run: yarn prepublishOnly
       - run: yarn docs:build
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         if: failure()
         with:
           name: test-output-changes

.mocharc.json

@@ -1,6 +1,6 @@
 # Observable Plot - Changelog [2021]
 
-Year: [Current (2023)](./CHANGELOG.md) · [2022](./CHANGELOG-2022.md) · **2021**
+Year: [Current (2024)](./CHANGELOG.md) · [2023](./CHANGELOG-2023.md) · [2022](./CHANGELOG-2022.md) · **2021**
 
 ## 0.3.2
 

CHANGELOG-2021.md

@@ -1,6 +1,6 @@
 # Observable Plot - Changelog [2022]
 
-Year: [Current (2023)](./CHANGELOG.md) · **2022** · [2021](./CHANGELOG-2021.md)
+Year: [Current (2024)](./CHANGELOG.md) · [2023](./CHANGELOG-2023.md) · **2022** · [2021](./CHANGELOG-2021.md)
 
 ## 0.6.1
 

CHANGELOG-2022.md

@@ -30,7 +30,7 @@ export default defineConfig({
     ["script", {}, "window.dataLayer=window.dataLayer||[];\nfunction gtag(){dataLayer.push(arguments);}\ngtag('js',new Date());\ngtag('config','G-9B88TP6PKQ');"]
   ],
   sitemap: {
-    hostname: 'https://observablehq.com/plot'
+    hostname: 'https://observablehq.com/plot/'
   },
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
@@ -88,6 +88,7 @@ export default defineConfig({
           {text: "Contour", link: "/marks/contour"},
           {text: "Delaunay", link: "/marks/delaunay"},
           {text: "Density", link: "/marks/density"},
+          {text: "Difference", link: "/marks/difference"},
           {text: "Dot", link: "/marks/dot"},
           {text: "Frame", link: "/marks/frame"},
           {text: "Geo", link: "/marks/geo"},
@@ -121,6 +122,7 @@ export default defineConfig({
           {text: "Map", link: "/transforms/map"},
           {text: "Normalize", link: "/transforms/normalize"},
           {text: "Select", link: "/transforms/select"},
+          {text: "Shift", link: "/transforms/shift"},
           {text: "Sort", link: "/transforms/sort"},
           {text: "Stack", link: "/transforms/stack"},
           {text: "Tree", link: "/transforms/tree"},
@@ -142,8 +144,7 @@ export default defineConfig({
     },
     socialLinks: [
       {icon: "github", link: "https://github.com/observablehq/plot"},
-      {icon: "twitter", link: "https://twitter.com/observablehq"},
-      {icon: "mastodon", link: "https://vis.social/@observablehq"},
+      {icon: "x", link: "https://twitter.com/observablehq"},
       {icon: "slack", link: "https://observablehq.com/slack/join"},
       {icon: "linkedin", link: "https://www.linkedin.com/company/observable"},
       {icon: "youtube", link: "https://www.youtube.com/c/Observablehq"}

CHANGELOG-2023.md

@@ -17,60 +17,16 @@ export default {
   }
 };
 
-function enableAnalytics(router) {
+async function enableAnalytics(router) {
   if (typeof location === "undefined" || location.origin !== "https://observablehq.com") return;
-
+  const {pageLoad, routeChanged} = await import("https://events.observablehq.com/client.js");
   let pageLoaded;
-  let queue: any[] | null = [];
-  let user;
-
   watch(router.route, () => {
     if (pageLoaded) {
-      emit({
-        type: "routeChanged",
-        event_version: 2,
-        data: {},
-        tags: {}
-      });
+      routeChanged();
     } else {
-      emit({
-        type: "pageLoad",
-        event_version: 1,
-        data: {referrer: document.referrer.replace(/\?.*/, "")},
-        tags: {}
-      });
+      pageLoad();
       pageLoaded = true;
     }
   });
-
-  fetch("https://api.observablehq.com/user", {credentials: "include"})
-    .then((response) => (response.ok ? response.json() : null))
-    .then(
-      (u) => (user = u),
-      () => (user = null)
-    )
-    .then(() => (sendEvents(queue), (queue = null)));
-
-  function emit(event) {
-    event.time = new Date().toISOString();
-    event.location = `${location.origin}${location.pathname}${location.search}`; // drop hash
-    if (queue) queue.push(event);
-    else sendEvents([event]);
-  }
-
-  function sendEvents(events) {
-    if (!events.length) return;
-    navigator.sendBeacon(
-      "https://events.observablehq.com/beacon-events",
-      JSON.stringify({
-        events: events.map((event) => ({
-          ...event,
-          release: null,
-          user_id: user?.id ?? null,
-          user_agent: navigator.userAgent
-        })),
-        send_time: new Date().toISOString()
-      })
-    );
-  }
-}
+}

CHANGELOG.md

@@ -13,6 +13,8 @@ const olympians = shallowRef([
   {weight: 170, height: 2.21, sex: "male"}
 ]);
 
+const scheme = Plot.scale({color: {type: "categorical"}}).range;
+
 onMounted(() => {
   d3.csv("../data/athletes.csv", d3.autoType).then((data) => (olympians.value = data));
 });
@@ -23,7 +25,7 @@ onMounted(() => {
 
 Faceting partitions data by ordinal or categorical value and then repeats a plot for each partition (each **facet**), producing [small multiples](https://en.wikipedia.org/wiki/Small_multiple) for comparison. Faceting is typically enabled by declaring the horizontal↔︎ facet channel **fx**, the vertical↕︎ facet channel **fy**, or both for two-dimensional faceting.
 
-For example, below we recreate the Trellis display (“reminiscent of garden trelliswork”) of [Becker *et al.*](https://hci.stanford.edu/courses/cs448b/papers/becker-trellis-jcgs.pdf) using the dot’s **fy** channel to declare vertical↕︎ facets, showing the yields of several varieties of barley across several sites for the years <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[0]}`}">1931</span> and <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[1]}`}">1932</span>.
+For example, below we recreate the Trellis display (“reminiscent of garden trelliswork”) of [Becker *et al.*](https://hci.stanford.edu/courses/cs448b/papers/becker-trellis-jcgs.pdf) using the dot’s **fy** channel to declare vertical↕︎ facets, showing the yields of several varieties of barley across several sites for the years <span :style="{borderBottom: `solid 2px ${scheme[0]}`}">1931</span> and <span :style="{borderBottom: `solid 2px ${scheme[1]}`}">1932</span>.
 
 :::plot https://observablehq.com/@observablehq/plot-trellis
 ```js
@@ -57,7 +59,7 @@ This plot uses the [**sort** mark option](./scales.md#sort-mark-option) to order
 Use the [frame mark](../marks/frame.md) for stronger visual separation of facets.
 :::
 
-The chart above reveals a likely data collection error: the years appear to be reversed for the Morris site as it is the only site where the yields in <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[1]}`}">1932</span> were higher than in <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[0]}`}">1931</span>. The anomaly in Morris is more obvious if we use directed arrows to show the year-over-year change. The [group transform](../transforms/group.md) groups the observations by site and variety to compute the change.
+The chart above reveals a likely data collection error: the years appear to be reversed for the Morris site as it is the only site where the yields in <span :style="{borderBottom: `solid 2px ${scheme[1]}`}">1932</span> were higher than in <span :style="{borderBottom: `solid 2px ${scheme[0]}`}">1931</span>. The anomaly in Morris is more obvious if we use directed arrows to show the year-over-year change. The [group transform](../transforms/group.md) groups the observations by site and variety to compute the change.
 
 :::plot defer https://observablehq.com/@observablehq/plot-trellis-anomaly
 ```js

docs/.vitepress/config.ts

@@ -30,7 +30,7 @@ A **marker** defines a graphic drawn on vertices of a [line](../marks/line.md) o
   </label>
 </p>
 
-:::plot https://observablehq.com/d/cfc5b4e46aa18b57?intent=fork
+:::plot https://observablehq.com/@observablehq/plot-line-chart-with-markers?intent=fork
 ```js-vue
 Plot.plot({
   marks: [
@@ -56,9 +56,9 @@ The following named markers are supported:
 * *dot* - a filled *circle* without a stroke and 2.5px radius
 * *circle*, equivalent to *circle-fill* - a filled circle with a white stroke and 3px radius
 * *circle-stroke* - a hollow circle with a colored stroke and a white fill and 3px radius
-* *tick* - a small opposing line
-* *tick-x* - a small horizontal line
-* *tick-y* - a small vertical line
+* *tick* <VersionBadge version="0.6.12" pr="1872" /> - a small opposing line
+* *tick-x* <VersionBadge version="0.6.12" pr="1872" /> - a small horizontal line
+* *tick-y* <VersionBadge version="0.6.12" pr="1872" /> - a small vertical line
 
 If **marker** is true, it defaults to *circle*. If **marker** is a function, it will be called with a given *color* and must return an [SVG marker element](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/marker).
 

docs/.vitepress/theme/index.ts

@@ -11,7 +11,7 @@ const align = ref(0.5);
 const radius = ref(8);
 const schemeq = ref("turbo");
 const schemed = ref("rdbu");
-const schemeo = ref("Tableau10");
+const schemeo = ref("Observable10");
 const interpolateq = ref("rgb");
 const anomaly = gistemp.map((d) => d.Anomaly);
 const aapl = shallowRef([]);
@@ -457,6 +457,7 @@ Plot also provides color schemes for discrete data. Use the *categorical* type f
         <option>Accent</option>
         <option>Category10</option>
         <option>Dark2</option>
+        <option>Observable10</option>
         <option>Paired</option>
         <option>Pastel1</option>
         <option>Pastel2</option>
@@ -730,7 +731,7 @@ Plot.plot({
 
 The normal scale types — *linear*, *sqrt*, *pow*, *log*, *symlog*, and *ordinal* — can be used to encode color. In addition, Plot supports special scale types for color:
 
-* *categorical* - like *ordinal*, but defaults to *tableau10*
+* *categorical* - like *ordinal*, but defaults to *observable10*
 * *sequential* - like *linear*
 * *cyclical* - like *linear*, but defaults to *rainbow*
 * *threshold* - discretizes using thresholds given as the **domain**; defaults to *rdylbu*
@@ -878,6 +879,7 @@ Plot.plot({
       ["Accent", d3.schemeAccent],
       ["Category10", d3.schemeCategory10],
       ["Dark2", d3.schemeDark2],
+      ["Observable10", Plot.scale({color: {type: "categorical"}}).range],
       ["Paired", d3.schemePaired],
       ["Pastel1", d3.schemePastel1],
       ["Pastel2", d3.schemePastel2],
@@ -1011,19 +1013,35 @@ Note: when the value of the sort option is a string or a function, it is interpr
 
 ## scale(*options*) <VersionBadge version="0.4.0" /> {#scale}
 
-You can also create a standalone scale with Plot.**scale**(*options*). The *options* object must define at least one scale; see [Scale options](#scale-options) for how to define a scale. For example, here is a linear color scale with the default domain of [0, 1] and default scheme *turbo*:
+You can also create a standalone scale with Plot.**scale**(*options*). The *options* object must define at least one scale; see [Scale options](#scale-options) for how to define a scale. For example, here is a categorical color scale with the *Tableau10* color scheme and a domain of fruits:
 
 ```js
-const color = Plot.scale({color: {type: "linear"}});
+const color = Plot.scale({color: {scheme: "Tableau10", domain: ["apple", "orange", "pear"]}});
 ```
 
 Both [*plot*.scale](./plots.md#plot_scale) and [Plot.scale](#scale) return scale objects. These objects represent the actual (or “materialized”) scale options used by Plot, including the domain, range, interpolate function, *etc.* The scale’s label, if any, is also returned; however, note that other axis properties are not currently exposed. Point and band scales also expose their materialized bandwidth and step.
 
-To reuse a scale across plots, pass the corresponding scale object into another plot specification:
-
 ```js
-const plot1 = Plot.plot(options);
-const plot2 = Plot.plot({...options, color: plot1.scale("color")});
+color.domain // ["apple", "orange", "pear"]
 ```
 
 For convenience, scale objects expose a *scale*.**apply**(*input*) method which returns the scale’s output for the given *input* value. When applicable, scale objects also expose a *scale*.**invert**(*output*) method which returns the corresponding input value from the scale’s domain for the given *output* value.
+
+```js
+color.apply("apple") // "#4e79a7"
+```
+
+To apply a standalone scale object to a plot, pass it to Plot.plot as the corresponding scale options, such as **color**:
+
+:::plot
+```js
+Plot.cellX(["apple", "apple", "orange", "pear", "orange"]).plot({color})
+```
+:::
+
+As another example, below are two plots with different options where the second plot uses the *color* scale from the first plot:
+
+```js
+const plot1 = Plot.plot({...options1});
+const plot2 = Plot.plot({...options2, color: plot1.scale("color")});
+```

docs/features/facets.md

@@ -10,6 +10,8 @@ const olympians = shallowRef([]);
 const traffic = shallowRef(["Saarbrücken-Neuhaus", "Oldenburg (Holstein)", "Holz", "Göttelborn", "Riegelsberg", "Kastel", "Neustadt i. H.-Süd", "Nettersheim", "Hasborn", "Laufeld", "Otzenhausen", "Nonnweiler", "Kirschheck", "AS Eppelborn", "Bierfeld", "Von der Heydt", "Illingen", "Hetzerath", "Groß Ippener", "Bockel", "Ladbergen", "Dibbersen", "Euskirchen/Bliesheim", "Hürth", "Lotte", "Ascheberg", "Bad Schwartau", "Schloss Burg", "Uphusen", "HB-Silbersee", "Barsbüttel", "HB-Mahndorfer See", "Glüsingen", "HB-Weserbrücke", "Hengsen", "Köln-Nord", "Hagen-Vorhalle", "Unna"].map((location, i) => ({location, date: new Date(Date.UTC(2000, 0, 1, i)), vehicles: (10 + i) ** 2.382})));
 const bins = computed(() => d3.bin().thresholds(80).value((d) => d.weight)(olympians.value));
 
+const scheme = Plot.scale({color: {type: "categorical"}}).range;
+
 onMounted(() => {
   d3.csv("../data/athletes.csv", d3.autoType).then((data) => (olympians.value = data));
   d3.csv("../data/bls-metro-unemployment.csv", d3.autoType).then((data) => (bls.value = data));
@@ -116,7 +118,7 @@ If a transform isn’t doing what you expect, try inspecting the options object
 
 Transforms can derive channels (such as **y** above) as well as changing the default options. For example, the bin transform sets default insets for a one-pixel gap between adjacent rects.
 
-Transforms are composable: you can pass *options* through more than one transform before passing it to a mark. For example, above it’s a bit difficult to compare the weight distribution by sex because there are fewer <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[0]}`}">female</span> than <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[1]}`}">male</span> athletes in the data. We can remove this effect using the [normalize transform](../transforms/normalize.md) with the *sum* reducer.
+Transforms are composable: you can pass *options* through more than one transform before passing it to a mark. For example, above it’s a bit difficult to compare the weight distribution by sex because there are fewer <span :style="{borderBottom: `solid 2px ${scheme[0]}`}">female</span> than <span :style="{borderBottom: `solid 2px ${scheme[1]}`}">male</span> athletes in the data. We can remove this effect using the [normalize transform](../transforms/normalize.md) with the *sum* reducer.
 
 :::plot defer https://observablehq.com/@observablehq/plot-overlapping-relative-histogram
 ```js-vue

docs/features/markers.md

@@ -279,7 +279,7 @@ Plot.plot({
   marks: [
     Plot.frame(),
     Plot.dot(penguins, {x: "culmen_length_mm", y: "culmen_depth_mm", fx: "sex", fy: "species"}),
-    Plot.axisX({color: "red", anchor, facetAnchor: facetAnchor === "auto" ? undefined : facetAnchor}),
+    Plot.axisX({color: "red", anchor, facetAnchor: facetAnchor === "auto" ? undefined : facetAnchor === "null" ? null : facetAnchor}),
     Plot.axisFx({color: "blue", anchor: anchor === "top" ? "bottom" : "top"}) // place fx axis opposite x
   ]
 })