temporal tick format (#321)

* time tickFormat

When a point or band scale is based on time values, use a time format for ticks; the default time format is the multi-time format from utcScale, but can be overridden with tickFormat: "%a". Similarly, if the point or band scale is based on numeric (ie non-ordinal) values, tickFormat: "," is interpreted with d3.format.

closes #212

* tweak branching

* shorten

* export formatIsoDate

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

Author: Fil

src/axis.js

@@ -1,5 +1,7 @@
-import {axisTop, axisBottom, axisRight, axisLeft, create} from "d3";
-import {boolean, number, string, keyword, maybeKeyword} from "./mark.js";
+import {axisTop, axisBottom, axisRight, axisLeft, create, format, utcFormat} from "d3";
+import {formatIsoDate} from "./format.js";
+import {boolean, number, string, keyword, maybeKeyword, constant} from "./mark.js";
+import {isTemporal} from "./scales.js";
 
 export class AxisX {
   constructor({
@@ -46,10 +48,6 @@ export class AxisX {
   ) {
     const {
       axis,
-      ticks,
-      tickSize,
-      tickPadding,
-      tickFormat,
       grid,
       label,
       labelAnchor,
@@ -61,13 +59,7 @@ export class AxisX {
     const ty = offsetSign * offset + (axis === "top" ? marginTop : height - marginBottom);
     return create("svg:g")
         .attr("transform", `translate(0,${ty})`)
-        .call((axis === "top" ? axisTop : axisBottom)(x)
-            .ticks(Array.isArray(ticks) ? null : ticks, typeof tickFormat === "function" ? null : tickFormat)
-            .tickFormat(typeof tickFormat === "function" || !x.tickFormat ? tickFormat : null)
-            .tickSizeInner(tickSize)
-            .tickSizeOuter(0)
-            .tickPadding(tickPadding)
-            .tickValues(Array.isArray(ticks) ? ticks : null))
+        .call(createAxis(axis === "top" ? axisTop : axisBottom, x, this))
         .call(maybeTickRotate, tickRotate)
         .attr("font-size", null)
         .attr("font-family", null)
@@ -134,10 +126,6 @@ export class AxisY {
   ) {
     const {
       axis,
-      ticks,
-      tickSize,
-      tickPadding,
-      tickFormat,
       grid,
       label,
       labelAnchor,
@@ -149,13 +137,7 @@ export class AxisY {
     const tx = offsetSign * offset + (axis === "right" ? width - marginRight : marginLeft);
     return create("svg:g")
         .attr("transform", `translate(${tx},0)`)
-        .call((axis === "right" ? axisRight : axisLeft)(y)
-            .ticks(Array.isArray(ticks) ? null : ticks, typeof tickFormat === "function" ? null : tickFormat)
-            .tickFormat(typeof tickFormat === "function" || !y.tickFormat ? tickFormat : null)
-            .tickSizeInner(tickSize)
-            .tickSizeOuter(0)
-            .tickPadding(tickPadding)
-            .tickValues(Array.isArray(ticks) ? ticks : null))
+        .call(createAxis(axis === "right" ? axisRight : axisLeft, y, this))
         .call(maybeTickRotate, tickRotate)
         .attr("font-size", null)
         .attr("font-family", null)
@@ -213,6 +195,24 @@ function gridFacetY(fx, tx) {
       .attr("d", fx.domain().map(v => `M${fx(v) + tx},0h${dx}`).join(""));
 }
 
+function createAxis(axis, scale, {ticks, tickSize, tickPadding, tickFormat}) {
+  if (!scale.tickFormat && typeof tickFormat !== "function") {
+    // D3 doesn’t provide a tick format for ordinal scales; we want shorthand
+    // when an ordinal domain is numbers or dates, and we want null to mean the
+    // empty string, not the default identity format.
+    tickFormat = tickFormat === undefined ? (isTemporal(scale.domain()) ? formatIsoDate : string)
+      : (typeof tickFormat === "string" ? (isTemporal(scale.domain()) ? utcFormat : format)
+      : constant)(tickFormat);
+  }
+  return axis(scale)
+    .ticks(Array.isArray(ticks) ? null : ticks, typeof tickFormat === "function" ? null : tickFormat)
+    .tickFormat(typeof tickFormat === "function" ? tickFormat : null)
+    .tickSizeInner(tickSize)
+    .tickSizeOuter(0)
+    .tickPadding(tickPadding)
+    .tickValues(Array.isArray(ticks) ? ticks : null);
+}
+
 function maybeTickRotate(g, rotate) {
   if (!(rotate = +rotate)) return;
   const radians = Math.PI / 180;

src/format.js

@@ -15,3 +15,28 @@ export function formatWeekday(locale = "en-US", weekday = "short") {
     }
   };
 }
+
+export function formatIsoDate(date) {
+  if (isNaN(date)) return "Invalid Date";
+  const hours = date.getUTCHours();
+  const minutes = date.getUTCMinutes();
+  const seconds = date.getUTCSeconds();
+  const milliseconds = date.getUTCMilliseconds();
+  return `${formatIsoYear(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1, 2)}-${pad(date.getUTCDate(), 2)}${
+    hours || minutes || seconds || milliseconds ? `T${pad(hours, 2)}:${pad(minutes, 2)}${
+      seconds || milliseconds ? `:${pad(seconds, 2)}${
+        milliseconds ? `.${pad(milliseconds, 3)}` : ``
+      }` : ``
+    }Z` : ``
+  }`;
+}
+
+function formatIsoYear(year) {
+  return year < 0 ? `-${pad(-year, 6)}`
+    : year > 9999 ? `+${pad(year, 6)}`
+    : pad(year, 4);
+}
+
+function pad(value, width) {
+  return (value + "").padStart(width, "0");
+}

src/index.js

@@ -18,4 +18,4 @@ export {map, mapX, mapY} from "./transforms/map.js";
 export {windowX, windowY} from "./transforms/window.js";
 export {selectFirst, selectLast, selectMaxX, selectMaxY, selectMinX, selectMinY} from "./transforms/select.js";
 export {stackX, stackX1, stackX2, stackY, stackY1, stackY2} from "./transforms/stack.js";
-export {formatWeekday, formatMonth} from "./format.js";
+export {formatIsoDate, formatWeekday, formatMonth} from "./format.js";

src/mark.js

@@ -75,6 +75,7 @@ export const number = x => x == null ? x : +x;
 export const boolean = x => x == null ? x : !!x;
 export const first = d => d[0];
 export const second = d => d[1];
+export const constant = x => () => x;
 
 // A few extra color keywords not known to d3-color.
 const colors = new Set(["currentColor", "none"]);

src/scales.js

@@ -100,15 +100,15 @@ function inferScaleType(key, channels, {type, domain, range}) {
   return "linear";
 }
 
-function isOrdinal(values) {
+export function isOrdinal(values) {
   for (const value of values) {
     if (value == null) continue;
     const type = typeof value;
     return type === "string" || type === "boolean";
   }
 }
 
-function isTemporal(values) {
+export function isTemporal(values) {
   for (const value of values) {
     if (value == null) continue;
     return value instanceof Date;

src/scales/quantitative.js

@@ -57,8 +57,8 @@ import {
 } from "d3";
 import {registry, radius, opacity, color} from "./index.js";
 import {positive, negative} from "../defined.js";
+import {constant} from "../mark.js";
 
-const constant = x => () => x;
 const flip = i => t => i(1 - t);
 
 // TODO Allow this to be extended.

test/output/fruitSalesDate.svg

@@ -7,7 +7,7 @@ export default async function() {
   const data = causes.flatMap(cause => crimea.map(({date, [cause]: deaths}) => ({date, cause, deaths})));
   return Plot.plot({
     x: {
-      tickFormat: d3.utcFormat("%b"),
+      tickFormat: "%b",
       label: null
     },
     marks: [

test/plots/crimean-war-overlapped.js

@@ -7,7 +7,7 @@ export default async function() {
   const data = causes.flatMap(cause => crimea.map(({date, [cause]: deaths}) => ({date, cause, deaths})));
   return Plot.plot({
     x: {
-      tickFormat: d3.utcFormat("%b"),
+      tickFormat: "%b",
       label: null
     },
     marks: [

test/plots/crimean-war-stacked.js

@@ -0,0 +1,12 @@
+import * as Plot from "@observablehq/plot";
+import * as d3 from "d3";
+
+export default async function() {
+  const sales = await d3.csv("data/fruit-sales.csv", d3.autoType);
+  return Plot.plot({
+    marks: [
+      Plot.barY(sales, Plot.stackY({x: "date", y: "units", fill: "fruit"})),
+      Plot.text(sales, Plot.stackY({x: "date", y: "units", text: "fruit" }))
+    ]
+  });
+}