descending shorthand

Author: mbostock

docs/features/facets.md

@@ -42,7 +42,7 @@ Plot.plot({
       y: "variety",
       fy: "site",
       stroke: "year",
-      sort: {y: "x", fy: "x", reduce: "median", reverse: true}
+      sort: {y: "-x", fy: "-x", reduce: "median"}
     })
   ]
 })
@@ -81,7 +81,7 @@ Plot.plot({
       fy: "site",
       stroke: "yield",
       strokeWidth: 2,
-      sort: {y: "x1", fy: "x1", reduce: "median", reverse: true}
+      sort: {y: "-x1", fy: "-x1", reduce: "median"}
     }))
   ]
 })

docs/features/scales.md

@@ -977,10 +977,10 @@ Plot.barY(alphabet, {x: "letter", y: "frequency", sort: {x: "y", reduce: "max"}}
 
 Generally speaking, a reducer only needs to be specified when there are multiple secondary values for a given primary value. See the [group transform](../transforms/group.md) for the list of supported reducers.
 
-For descending rather than ascending order, use the *reverse* option:
+For descending rather than ascending order, use the *reverse* option, or *-name* when referring to a channel:
 
 ```js
-Plot.barY(alphabet, {x: "letter", y: "frequency", sort: {x: "y", reverse: true}})
+Plot.barY(alphabet, {x: "letter", y: "frequency", sort: {x: "-y"}})
 ```
 
 An additional *limit* option truncates the domain to the first *n* values after sorting. If *limit* is negative, the last *n* values are used instead. Hence, a positive *limit* with *reverse* = true will return the top *n* values in descending order. If *limit* is an array [*lo*, *hi*], the *i*th values with *lo* ≤ *i* < *hi* will be selected. (Note that like the [basic filter transform](../transforms/filter.md), limiting the *x* domain here does not affect the computation of the *y* domain, which is computed independently without respect to filtering.)

docs/marks/bar.md

@@ -41,7 +41,7 @@ Ordinal domains are sorted naturally (alphabetically) by default. Either set the
 
 :::plot https://observablehq.com/@observablehq/plot-vertical-bars
 ```js
-Plot.barY(alphabet, {x: "letter", y: "frequency", sort: {x: "y", reverse: true}}).plot()
+Plot.barY(alphabet, {x: "letter", y: "frequency", sort: {x: "-y"}}).plot()
 ```
 :::
 

docs/transforms/group.md

@@ -52,7 +52,7 @@ Plot.plot({
   x: {label: null, tickRotate: 90},
   y: {grid: true},
   marks: [
-    Plot.barY(olympians, Plot.groupX({y: "count"}, {x: "sport", sort: {x: "y", reverse: true}})),
+    Plot.barY(olympians, Plot.groupX({y: "count"}, {x: "sport", sort: {x: "-y"}})),
     Plot.ruleY([0])
   ]
 })

docs/transforms/sort.md

@@ -49,7 +49,7 @@ Plot.plot({
       fill: "currentColor",
       stroke: "var(--vp-c-bg)",
       strokeWidth: 1,
-      sort: sorted ? {channel: "r", order: "descending"} : null
+      sort: sorted ? {channel: "-r"} : null
     }))
   ]
 })
@@ -134,7 +134,7 @@ Sorts the data by the specified *order*, which is one of:
 - a field name
 - a {*channel*, *order*} object
 
-In the object case, the **channel** option specifies the name of the channel, while the **order** option specifies *ascending* (the default) or *descending* order. For example, `sort: {channel: "r", order: "descending"}` will sort by descending radius (**r**).
+In the object case, the **channel** option specifies the name of the channel, while the **order** option specifies *ascending* (the default) or *descending* order. You can also use the shorthand *-name* to sort by descending order of the channel with the given *name*. For example, `sort: {channel: "-r"}` will sort by descending radius (**r**).
 
 In the function case, if the sort function does not take exactly one argument, it is interpreted as a comparator function; otherwise it is interpreted as an accessor function.
 

src/channel.d.ts

@@ -161,6 +161,9 @@ export type ChannelValueBinSpec = ChannelValue | ({value: ChannelValue} & BinOpt
  */
 export type ChannelValueDenseBinSpec = ChannelValue | ({value: ChannelValue; scale?: Channel["scale"]} & Omit<BinOptions, "interval">); // prettier-ignore
 
+/** A channel name, or an implied one for domain sorting. */
+type ChannelDomainName = ChannelName | "data" | "width" | "height";
+
 /**
  * The available inputs for imputing scale domains. In addition to a named
  * channel, an input may be specified as:
@@ -176,7 +179,7 @@ export type ChannelValueDenseBinSpec = ChannelValue | ({value: ChannelValue; sca
  * custom **reduce** function, as when the built-in single-channel reducers are
  * insufficient.
  */
-export type ChannelDomainValue = ChannelName | "data" | "width" | "height" | null;
+export type ChannelDomainValue = ChannelDomainName | `-${ChannelDomainName}` | null;
 
 /** Options for imputing scale domains from channel values. */
 export interface ChannelDomainOptions {

src/channel.js

@@ -82,7 +82,10 @@ export function channelDomain(data, facets, channels, facetChannels, options) {
   for (const x in options) {
     if (!registry.has(x)) continue; // ignore unknown scale keys (including generic options)
     let {value: y, reverse = defaultReverse, reduce = defaultReduce, limit = defaultLimit} = maybeValue(options[x]);
+    const negate = y?.startsWith("-");
+    if (negate) y = y.slice(1);
     if (reverse === undefined) reverse = y === "width" || y === "height"; // default to descending for lengths
+    if (negate) reverse = !reverse;
     if (reduce == null || reduce === false) continue; // disabled reducer
     const X = x === "fx" || x === "fy" ? reindexFacetChannel(facets, facetChannels[x]) : findScaleChannel(channels, x);
     if (!X) throw new Error(`missing channel for scale: ${x}`);

src/mark.d.ts

@@ -102,7 +102,7 @@ export interface MarkOptions {
    * with a *value* object and per-scale options:
    *
    * ```js
-   * sort: {y: {value: "x", reverse: true}}
+   * sort: {y: {value: "-x"}}
    * ```
    *
    * When sorting the mark’s index, the **sort** option is instead one of:

src/marks/dot.js

@@ -23,9 +23,7 @@ const defaults = {
 };
 
 export function withDefaultSort(options) {
-  return options.sort === undefined && options.reverse === undefined
-    ? sort({channel: "r", order: "descending"}, options)
-    : options;
+  return options.sort === undefined && options.reverse === undefined ? sort({channel: "-r"}, options) : options;
 }
 
 export class Dot extends Mark {

src/transforms/basic.d.ts

@@ -149,7 +149,7 @@ export type SortOrder =
   | CompareFunction
   | ChannelValue
   | {value?: ChannelValue; order?: CompareFunction | "ascending" | "descending"}
-  | {channel?: ChannelName; order?: CompareFunction | "ascending" | "descending"};
+  | {channel?: ChannelName | `-${ChannelName}`; order?: CompareFunction | "ascending" | "descending"};
 
 /**
  * Applies a transform to *options* to sort the mark’s index by the specified