ggaction 0.0.22 → 0.0.24

package/src/core/compositionState.js

@@ -1,3 +1,5 @@
+import { normalizeFacetGap } from "./facetGap.js";
+import { normalizeFacetAxes } from "./facetAxisPolicy.js";
 import { isOwned, isPlainObject } from "./immutable.js";
 import { ownProgramState } from "./programState.js";
 import {
@@ -43,6 +45,7 @@ function validateFacetSpec(compositionSpec) {
   }
   const grid = compositionSpec.facet.grid;
   const repeat = compositionSpec.facet.repeat;
+  if (grid !== undefined && compositionSpec.spacing === "content") throw new Error("Content flow requires a wrapped facet.");
   if (grid !== undefined && repeat !== undefined) {
     throw new Error("Facet compositionSpec cannot combine grid and repeat recipes.");
   }
@@ -204,10 +207,10 @@ function validateFacetSpec(compositionSpec) {
     );
   }
   const guides = compositionSpec.facet.guides;
+  normalizeFacetAxes(guides?.axes, "each", { stored: true });
   if (
     !isPlainObject(guides) ||
     Object.keys(guides).some(key => !["axes", "legend"].includes(key)) ||
-    !["each", "outer"].includes(guides.axes) ||
     (![false, "shared"].includes(guides.legend) && !isPlainObject(guides.legend))
   ) {
     throw new Error(
@@ -240,7 +243,9 @@ function validateCompositionChildren(compositionSpec, childIds, facet) {
 }
 
 function validateLayout(compositionSpec) {
-  if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
+  if (compositionSpec.type === "facet") {
+    normalizeFacetGap(compositionSpec.gap, "compositionSpec.gap");
+  } else if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
     throw new RangeError("compositionSpec.gap must be a non-negative finite number.");
   }
   if (!["start", "center", "end"].includes(compositionSpec.align)) {
@@ -289,8 +294,8 @@ export function ownCompositionSpec(compositionSpec, children) {
     throw new TypeError("compositionSpec.id must be a non-empty string.");
   }
   const facet = compositionSpec.type === "facet";
-  if (compositionSpec.spacing !== undefined && (!facet || !["plot", "canvas"].includes(compositionSpec.spacing))) {
-    throw new Error("compositionSpec.spacing requires a facet and canvas or plot spacing.");
+  if (compositionSpec.spacing !== undefined && (!facet || !["plot", "canvas", "content"].includes(compositionSpec.spacing))) {
+    throw new Error("compositionSpec.spacing requires a facet and canvas, plot, or content spacing.");
   }
   if (compositionSpec.topLane !== undefined && (!facet ||
       !FACET_TOP_LANE_MODES.includes(compositionSpec.topLane) ||

package/src/core/facetAxisPolicy.js

@@ -0,0 +1,30 @@
+import { cloneAndFreeze, isPlainObject } from "./immutable.js";
+
+export function normalizeFacetAxes(value, previous = "each", { stored = false } = {}) {
+  if (value === undefined && !stored) value = "each";
+  if (["each", "outer"].includes(value)) return value;
+  if (!isPlainObject(value) || Object.keys(value).length === 0 ||
+      Object.keys(value).some(key => !["x", "y"].includes(key)) ||
+      Object.values(value).some(mode => !["each", "outer"].includes(mode)) ||
+      stored && (!Object.hasOwn(value, "x") || !Object.hasOwn(value, "y"))) {
+    throw new Error('Facet axes must be each, outer, or a non-empty x/y policy object.');
+  }
+  return cloneAndFreeze({ x: value.x ?? facetAxisMode(previous, "x"), y: value.y ?? facetAxisMode(previous, "y") });
+}
+
+export function facetAxisMode(policy, channel) {
+  return typeof policy === "string" ? policy : policy[channel];
+}
+
+export function hasOuterFacetAxes(policy) {
+  return ["x", "y"].some(channel => facetAxisMode(policy, channel) === "outer");
+}
+
+export function validateFacetAxisPolicy(policy, family, repeat = false) {
+  if (family !== "cartesian" && (hasOuterFacetAxes(policy) || isPlainObject(policy))) {
+    throw new Error("Polar and Parallel facets do not support outer axes or per-channel axis policies.");
+  }
+  if (repeat && hasOuterFacetAxes(policy)) {
+    throw new Error("repeatCharts does not promote axes across different repeated fields.");
+  }
+}

package/src/core/facetGap.js

@@ -0,0 +1,44 @@
+import { cloneAndFreeze, isPlainObject } from "./immutable.js";
+import { annotateError } from "./diagnostics.js";
+export function validateCompositionSpacing(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}
+
+/** Keep scalar intent intact; a facet pair always declares both axes. */
+export function normalizeFacetGap(value, label = "Facet gap") {
+  if (!isPlainObject(value)) return validateCompositionSpacing(value, label);
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 2 || !keys.includes("x") || !keys.includes("y")) {
+    throw annotateError(new TypeError(`${label} must contain exactly x and y.`), {
+      code: "invalid-value", optionPath: "gap", actual: value
+    });
+  }
+  const result = {};
+  for (const axis of ["x", "y"]) {
+    try {
+      result[axis] = validateCompositionSpacing(value[axis], `${label}.${axis}`);
+    } catch (error) {
+      throw annotateError(error, {
+        code: "invalid-value", optionPath: `gap.${axis}`, actual: value[axis], limit: 0
+      });
+    }
+  }
+  return cloneAndFreeze(result);
+}
+
+/** Accept only a previously normalized scalar or pair. */
+export function facetGapAxis(gap, axis) {
+  return typeof gap === "number" ? gap : gap[axis];
+}
+
+/** Overflow remains axis-specific for a pair; scalar callers keep their old error. */
+export function assertFacetGapFinite(gap, axis, values, message) {
+  if (values.every(Number.isFinite)) return;
+  const error = new RangeError(message);
+  throw typeof gap === "number" ? error : annotateError(error, {
+    code: "invalid-value", optionPath: `gap.${axis}`, actual: gap[axis]
+  });
+}

package/src/grammar/axisTextPlacement.js

@@ -1 +1 @@
-import{resolveTextLines as l}from"../core/textMetrics.js";function a(e,{title:i=!1}={}){if(Object.hasOwn(e,"align")&&!["left","center","right"].includes(e.align))throw new TypeError("Axis text align must be left, center, or right.");if(i){if(Object.hasOwn(e,"overlap")&&!["error","allow"].includes(e.overlap))throw new TypeError("Axis title overlap must be error or allow.");if(Object.hasOwn(e,"baseline")&&!["top","hanging","middle","alphabetic","ideographic","bottom"].includes(e.baseline))throw new TypeError("Axis title baseline must be a supported text baseline.");for(const t of["offset","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Axis title ${t} must be a finite number.`)}}function f(e,i){if(!/[\r\n]/u.test(e))return;const t=i.baseline??"middle",n=l(e,{fontSize:i.fontSize,align:i.align??"center",baseline:t,...t==="middle"?{blockAlign:"middle"}:{}});if(["bottom","ideographic"].includes(t)){const o=(n.length-1)*i.fontSize*1.2;return n.map(r=>({...r,y:r.y-o}))}return n.length>1?n:void 0}function b(e){return e?.overlap==="allow"}export{b as axisTitleAllowsLabelOverlap,f as axisTitleTextLines,a as validateAxisTextPlacement};
+import{validateKeys as a,validateNonNegativeFinite as o}from"../core/validation.js";import{isPlainObject as s}from"../core/immutable.js";import{resolveTextLines as b}from"../core/textMetrics.js";function c(e,{title:t=!1}={}){if(Object.hasOwn(e,"align")&&!["left","center","right"].includes(e.align))throw new TypeError("Axis text align must be left, center, or right.");if(t){if(Object.hasOwn(e,"overlap")&&!["error","allow"].includes(e.overlap))throw new TypeError("Axis title overlap must be error or allow.");if(Object.hasOwn(e,"baseline")&&!["top","hanging","middle","alphabetic","ideographic","bottom"].includes(e.baseline))throw new TypeError("Axis title baseline must be a supported text baseline.");if(Object.hasOwn(e,"offset")&&s(e.offset)){if(a(e.offset,["from","gap"],"Axis title offset"),e.offset.from!=="labels"||!Object.hasOwn(e.offset,"gap"))throw new TypeError("Axis title offset requires from: labels and gap.");o(e.offset.gap,"Axis title label gap")}for(const i of["offset","alongOffset"])if(!(i==="offset"&&f(e.offset))&&Object.hasOwn(e,i)&&!Number.isFinite(e[i]))throw new TypeError(`Axis title ${i} must be a finite number.`)}}function f(e){return s(e)&&e.from==="labels"}function h(e){return e?.inferredOffset===!0||f(e?.offset)}function m(e){return(e?.lines??[{text:e?.text}]).some(t=>typeof t.text=="string"&&t.text.length>0)}function w(e,t){if(!/[\r\n]/u.test(e))return;const i=t.baseline??"middle",r=b(e,{fontSize:t.fontSize,align:t.align??"center",baseline:i,...i==="middle"?{blockAlign:"middle"}:{}});if(["bottom","ideographic"].includes(i)){const l=(r.length-1)*t.fontSize*1.2;return r.map(n=>({...n,y:n.y-l}))}return r.length>1?r:void 0}function u(e){return e?.overlap==="allow"}function g(e,{allowReset:t=!1}={}){e===void 0||t&&e==="auto"||o(e,"Label flushThreshold")}export{m as axisLabelHasText,u as axisTitleAllowsLabelOverlap,h as axisTitleFollowsLabels,w as axisTitleTextLines,f as isLabelRelativeTitleOffset,g as validateAxisLabelFlushThreshold,c as validateAxisTextPlacement};

package/src/grammar/bin2d.js

@@ -11,7 +11,7 @@ const MAX_CELLS = 1_000_000;
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "x", "y", "bins", "extent", "includeEmpty", "members", "as",
-  "resolved"
+  "resolved", "assignment"
 ]);
 const AXIS_KEYS = Object.freeze(["x", "y"]);
 const FIELD_KEYS = Object.freeze(["x0", "x1", "y0", "y1", "count", "members"]);
@@ -180,6 +180,11 @@ export function validateBin2DTransform(transform) {
   }
   requireField(transform.x, "2D bin x field");
   requireField(transform.y, "2D bin y field");
+  if (transform.assignment !== undefined && transform.assignment !== "step") {
+    throw new TypeError(
+      'Stored 2D bin assignment must be "step" or omitted.'
+    );
+  }
   validateBins(transform.bins);
   validateRequestedExtent(transform.extent);
   if (typeof transform.includeEmpty !== "boolean") {
@@ -201,10 +206,16 @@ export function normalizeBin2DTransform({
   y,
   bins,
   extent,
+  assignment = "edges",
   includeEmpty = false,
   members = false,
   as
 } = {}) {
+  if (assignment !== "edges" && assignment !== "step") {
+    throw new TypeError(
+      '2D bin assignment must be "edges" or "step".'
+    );
+  }
   const normalizedBins = normalizeBins(bins);
   const transform = {
     type: "bin2d",
@@ -214,7 +225,8 @@ export function normalizeBin2DTransform({
     extent: normalizeRequestedExtent(extent),
     includeEmpty,
     members,
-    as: normalizeOutputFields(id, as, members)
+    as: normalizeOutputFields(id, as, members),
+    ...(assignment === "step" ? { assignment } : {})
   };
   validateBin2DTransform(transform);
   return cloneAndFreeze(transform);
@@ -266,6 +278,20 @@ function findBinIndex(value, edges) {
   return low;
 }
 
+function findStepBinIndex(value, extent, count) {
+  if (count === 1 || value === extent[1]) return count - 1;
+  const [minimum, maximum] = extent;
+  const span = maximum - minimum;
+  const step = Number.isFinite(span)
+    ? span / count
+    : maximum / count - minimum / count;
+  const distance = value - minimum;
+  const position = Number.isFinite(distance)
+    ? distance / step
+    : value / step - minimum / step;
+  return Math.max(0, Math.min(count - 1, Math.floor(1e-14 + position)));
+}
+
 export function deriveBin2DRows(rows, transform) {
   if (!Array.isArray(rows)) {
     throw new TypeError("2D bin source rows must be an array.");
@@ -304,8 +330,12 @@ export function deriveBin2DRows(rows, transform) {
     () => []
   );
   for (const item of eligible) {
-    const xIndex = findBinIndex(item.row[transform.x], edges.x);
-    const yIndex = findBinIndex(item.row[transform.y], edges.y);
+    const xIndex = transform.assignment === "step"
+      ? findStepBinIndex(item.row[transform.x], extent.x, transform.bins.x)
+      : findBinIndex(item.row[transform.x], edges.x);
+    const yIndex = transform.assignment === "step"
+      ? findStepBinIndex(item.row[transform.y], extent.y, transform.bins.y)
+      : findBinIndex(item.row[transform.y], edges.y);
     buckets[yIndex * transform.bins.x + xIndex].push(item.index);
   }
   const values = [];

package/src/grammar/curveCommands.js

@@ -9,6 +9,7 @@ export const CURVE_INTERPOLATIONS = Object.freeze([
   "basis",
   "cardinal",
   "monotone",
+  "monotone-steffen",
   "natural"
 ]);
 
@@ -16,6 +17,7 @@ const SMOOTH_CURVES = new Set([
   "basis",
   "cardinal",
   "monotone",
+  "monotone-steffen",
   "natural"
 ]);
 
@@ -196,8 +198,38 @@ function monotoneTangents(points) {
   return tangents;
 }
 
-function buildMonotoneCommands(points) {
-  const tangents = monotoneTangents(points);
+function steffenTangents(points) {
+  const widths = points.slice(1).map((point, index) => point.x - points[index].x);
+  const direction = Math.sign(widths.find(width => width !== 0) ?? 0);
+  if (widths.some(width => width !== 0 && Math.sign(width) !== direction)) {
+    throw new Error("Steffen curve requires monotonic x values.");
+  }
+  const slopes = widths.map((width, i) =>
+    (points[i + 1].y - points[i].y) / (width || (direction < 0 ? -0 : 0)));
+  const tangents = Array(points.length);
+  for (let i = 1; i < points.length - 1; i += 1) {
+    const a = slopes[i - 1], b = slopes[i];
+    const mean = (a * widths[i] + b * widths[i - 1]) / (widths[i - 1] + widths[i]);
+    // A zero-width turn has no finite secant estimate; its Hermite limit is flat.
+    const sign = value => value < 0 ? -1 : 1;
+    const slope = (sign(a) + sign(b)) * Math.min(Math.abs(a), Math.abs(b), Math.abs(mean) / 2);
+    tangents[i] = Number.isNaN(slope) && (widths[i - 1] === 0 || widths[i] === 0) ? 0 : slope;
+  }
+  tangents[0] = widths[0] === 0 ? tangents[1] : (3 * slopes[0] - tangents[1]) / 2;
+  tangents[points.length - 1] = widths.at(-1) === 0 ? tangents.at(-2) :
+    (3 * slopes.at(-1) - tangents.at(-2)) / 2;
+  return tangents;
+}
+
+function buildSteffenCommands(points) {
+  const distinct = points.filter((point, i) => i === 0 ||
+    point.x !== points[i - 1].x || point.y !== points[i - 1].y);
+  if (distinct.length === 1) return ownCommands([{ op: "M", ...distinct[0] }]);
+  if (distinct.length === 2) return buildLinearPathCommands(distinct);
+  return buildMonotoneCommands(distinct, steffenTangents(distinct));
+}
+
+function buildMonotoneCommands(points, tangents = monotoneTangents(points)) {
   const commands = [{ op: "M", x: points[0].x, y: points[0].y }];
   for (let index = 1; index < points.length; index += 1) {
     const previous = points[index - 1];
@@ -274,6 +306,7 @@ function buildNaturalCommands(points) {
 }
 
 function buildValidatedCurvePathCommands(points, curve, tension) {
+  if (curve === "monotone-steffen") return buildSteffenCommands(points);
   if (curve === "linear" ||
       (SMOOTH_CURVES.has(curve) &&
         curve !== "monotone" &&

package/src/grammar/datasetSchema.js

@@ -404,7 +404,7 @@ export function deriveTransformSchema(inputSchema, transform, values, { sourceId
       if (planned.lineage === undefined && !["complete", "impute"].includes(transform.type)) {
         return planned;
       }
-      return { ...planned, storageType: transform.type === "regressionStatistics" && planned.storageType === "number"
+      return { ...planned, storageType: ["regressionStatistics", "timeUnit"].includes(transform.type) && planned.storageType === "number"
         ? "number" : field.storageType, nullable: field.nullable, optional: field.optional };
     });
     for (const field of inferred.fields) {

package/src/grammar/facetHeaders.js

@@ -1 +1 @@
-import{validateOptionObject as o,validateNonEmptyString as r,validatePositiveFinite as a,validateNonNegativeFinite as c}from"../core/validation.js";import{resolveRotation as s}from"./rotation.js";const f=Object.freeze(["text","fontSize","fontFamily","fontWeight","color","offset","align","rotation","alongOffset"]);function d(e){if(o(e,f,"Facet header title",{allowEmpty:!1}),r(e.text,"Facet header title text"),/[\r\n\u2028\u2029]/u.test(e.text))throw new TypeError("Facet header title text must be one line.");e.fontSize!==void 0&&a(e.fontSize,"Facet header title fontSize");for(const t of["fontFamily","color"])e[t]!==void 0&&r(e[t],`Facet header title ${t}`);if(e.fontWeight!==void 0&&!(typeof e.fontWeight=="string"&&e.fontWeight.length>0||Number.isFinite(e.fontWeight)))throw new TypeError("Facet header title fontWeight must be a non-empty string or finite number.");if(e.offset!==void 0&&c(e.offset,"Facet header title offset"),e.align!==void 0&&!["start","center","end"].includes(e.align))throw new TypeError("Facet header title align must be start, center, or end.");for(const t of["rotation","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Facet header title ${t} must contain finite normalized radians or coordinates.`)}function h(e,t){if(t===!1)return;o(t,f,"Facet header title",{allowEmpty:!1});for(const i of Object.keys(t))if(t[i]===void 0)throw new TypeError(`Facet header title ${i} must not be undefined.`);const n={...e,...t};return Object.hasOwn(t,"rotation")&&(n.rotation=s(t.rotation,"Facet header title rotation")),d(n),n}function w(e){for(const t of e.common===void 0?[e]:[e.common,e.row,e.column]){if(t!==void 0&&Object.hasOwn(t,"anchor")&&!["plot","content"].includes(t.anchor))throw new TypeError("Facet header anchor must be plot or content.");if(t?.rotation!==void 0&&!Number.isFinite(t.rotation))throw new TypeError("Facet header rotation must contain finite normalized radians.");t?.title!==void 0&&d(t.title)}if(e.title!==void 0||e.common?.title!==void 0)throw new TypeError("Facet header title requires an explicit row or column role.");if(e.mode!=="roles"&&(e.row?.title!==void 0||e.column?.title!==void 0))throw new TypeError("Facet field titles require role header mode.")}export{h as normalizeFacetHeaderTitle,w as validateFacetHeaderRotations,d as validateFacetHeaderTitle};
+import{validateOptionObject as o,validateNonEmptyString as r,validatePositiveFinite as a,validateNonNegativeFinite as c}from"../core/validation.js";import{resolveRotation as s}from"./rotation.js";const f=Object.freeze(["text","fontSize","fontFamily","fontWeight","color","offset","align","rotation","alongOffset"]);function d(e){if(o(e,f,"Facet header title",{allowEmpty:!1}),r(e.text,"Facet header title text"),/[\r\n\u2028\u2029]/u.test(e.text))throw new TypeError("Facet header title text must be one line.");e.fontSize!==void 0&&a(e.fontSize,"Facet header title fontSize");for(const t of["fontFamily","color"])e[t]!==void 0&&r(e[t],`Facet header title ${t}`);if(e.fontWeight!==void 0&&!(typeof e.fontWeight=="string"&&e.fontWeight.length>0||Number.isFinite(e.fontWeight)))throw new TypeError("Facet header title fontWeight must be a non-empty string or finite number.");if(e.offset!==void 0&&c(e.offset,"Facet header title offset"),e.align!==void 0&&!["start","center","end"].includes(e.align))throw new TypeError("Facet header title align must be start, center, or end.");for(const t of["rotation","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Facet header title ${t} must contain finite normalized radians or coordinates.`)}function h(e,t){if(t===!1)return;o(t,f,"Facet header title",{allowEmpty:!1});for(const i of Object.keys(t))if(t[i]===void 0)throw new TypeError(`Facet header title ${i} must not be undefined.`);const n={...e,...t};return Object.hasOwn(t,"rotation")&&(n.rotation=s(t.rotation,"Facet header title rotation")),d(n),n}function w(e){for(const t of e.common===void 0?[e]:[e.common,e.row,e.column]){if(t!==void 0&&Object.hasOwn(t,"anchor")&&!["plot","content","view"].includes(t.anchor))throw new TypeError("Facet header anchor must be plot, content, or view.");if(t?.rotation!==void 0&&!Number.isFinite(t.rotation))throw new TypeError("Facet header rotation must contain finite normalized radians.");t?.title!==void 0&&d(t.title)}if(e.title!==void 0||e.common?.title!==void 0)throw new TypeError("Facet header title requires an explicit row or column role.");if(e.mode!=="roles"&&(e.row?.title!==void 0||e.column?.title!==void 0))throw new TypeError("Facet field titles require role header mode.")}export{h as normalizeFacetHeaderTitle,w as validateFacetHeaderRotations,d as validateFacetHeaderTitle};

package/src/grammar/facets/guides.js

@@ -1,5 +1,8 @@
 import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 
+
+import { normalizeFacetAxes, facetAxisMode, hasOuterFacetAxes } from "../../core/facetAxisPolicy.js";
+
 const LEGEND_FAMILIES = Object.freeze({
   series: "categorical",
   color: "categorical",
@@ -243,9 +246,7 @@ export function planFacetGuideOwnership({
   if (!Array.isArray(children) || children.length !== cells.length) {
     throw new Error("Facet guide ownership requires one child descriptor per placement.");
   }
-  if (!["each", "outer"].includes(axes)) {
-    throw new Error("Facet axes must be each or outer.");
-  }
+  axes = normalizeFacetAxes(axes, "each", { stored: true });
   if (![false, "shared"].includes(legend) && !isPlainObject(legend)) {
     throw new Error("Facet legend must be false or shared.");
   }
@@ -264,11 +265,12 @@ export function planFacetGuideOwnership({
       const presentAxes = descriptor.axes ?? [];
       const records = descriptor.axisOwners;
       const removed = {};
-      const keepAxes = axes === "each" ? presentAxes : records === undefined
-        ? presentAxes.filter(channel => outer.children[cell.id][channel])
+      const keepAxes = !hasOuterFacetAxes(axes) ? presentAxes : records === undefined
+        ? presentAxes.filter(channel => facetAxisMode(axes, channel) === "each" || outer.children[cell.id][channel])
         : presentAxes.filter(id => {
           const owner = records.find(owner => owner.id === id);
           if (owner === undefined) throw new Error("Facet axis descriptors must identify every retained owner.");
+          if (facetAxisMode(axes, owner.channel) === "each") return true;
           const components = Object.entries(owner.components);
           const remove = components.filter(([, side]) => !sides[side]?.includes(cell.id)).map(([component]) => component);
           if (remove.length > 0 && remove.length < components.length) removed[id] = remove;

package/src/grammar/regression/parameters.js

@@ -233,3 +233,10 @@ export function normalizeRegressionTransform(args = {}) {
   validateRegressionTransform(transform);
   return cloneAndFreeze(transform);
 }
+
+export function validateRegressionPlacement(value) {
+  if (value !== undefined && !["source", "plot-last"].includes(value)) {
+    throw new Error('Regression placement must be "source" or "plot-last".');
+  }
+  return value ?? "source";
+}

package/src/grammar/timeUnit.js

@@ -41,7 +41,7 @@ export const TIME_UNITS = cloneAndFreeze([
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "field", "unit", "as", "temporalUnit", "timeZone",
-  "weekStartsOn", "weekRule"
+  "weekStartsOn", "weekRule", "missing"
 ]);
 
 const CALENDAR_FORMATTERS = new Map();
@@ -93,6 +93,9 @@ export function validateTimeUnitTransform(transform) {
   if (transform.type !== "timeUnit") {
     throw new Error(`Unsupported time-unit transform "${transform.type}".`);
   }
+  if (Object.hasOwn(transform, "missing") && !["error", "null"].includes(transform.missing)) {
+    throw new Error('Time-unit missing must be "error" or "null".');
+  }
   validateTemporalUnit(transform.temporalUnit);
   const field = requireField(transform.field, "Time-unit field");
   const output = requireField(transform.as, "Time-unit output field");
@@ -127,7 +130,8 @@ export function normalizeTimeUnitTransform(args = {}) {
   const as = args.as === undefined ? `${field}_${unit}` : args.as;
   const transform = { type: "timeUnit", field, unit, as,
     ...(temporalUnit === undefined ? {} : { temporalUnit }),
-    ...(timeZone === undefined ? {} : { timeZone }) };
+    ...(timeZone === undefined ? {} : { timeZone }),
+    ...(Object.hasOwn(args, "missing") ? { missing: args.missing } : {}) };
   if (unit === "week") {
     transform.weekStartsOn = args.weekStartsOn ?? 1;
     transform.weekRule = args.weekRule ?? "calendar";
@@ -319,7 +323,8 @@ export function deriveTimeUnitRows(rows, transform) {
     throw new TypeError("Time-unit source must contain plain row objects.");
   }
   const values = rows.map((row, index) => {
-    if (!Object.hasOwn(row, transform.field)) {
+    const missing = !Object.hasOwn(row, transform.field) || row[transform.field] === null;
+    if (!Object.hasOwn(row, transform.field) && transform.missing !== "null") {
       throw new Error(
         `Time-unit source does not contain field "${transform.field}" at row ${index}.`
       );
@@ -327,6 +332,7 @@ export function deriveTimeUnitRows(rows, transform) {
     if (Object.hasOwn(row, transform.as)) {
       throw new Error(`Time-unit output field "${transform.as}" already exists.`);
     }
+    if (missing && transform.missing === "null") return { ...row, [transform.as]: null };
     const timestamp = normalizeTemporalValue(row[transform.field], transform.field, index, transform.temporalUnit);
     return {
       ...row,