ggaction 0.0.22 → 0.0.23

package/src/actions/regression/edit.js

@@ -1,3 +1,5 @@
+import { reconcileRegressionPlacement } from "../../materialization/graphicHierarchy.js";
+import { validateRegressionPlacement } from "../../grammar/regression/parameters.js";
 import { closedAction } from "../../core/action.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
@@ -24,7 +26,7 @@ import { buildSourceRevisionPlan, applyRevisionPlan } from "../data/edit.js";
 const OPTIONS = Object.freeze([
   "target", "data", "x", "y", "groupBy", "method", "degree", "span", "robustIterations",
   "confidenceMethod", "level", "confidence", "interval", "band", "line"
-  , "predict", "sourceBinding", "missing"
+  , "predict", "sourceBinding", "missing", "placement"
 ]);
 const BAND_OPTIONS = Object.freeze([
   "color", "opacity", "stroke", "strokeWidth", "curve",
@@ -259,6 +261,7 @@ export const editRegression = /* @__PURE__ */ closedAction(
     }
     const owner = resolveRegressionOwner(this, args.target);
     const current = this.markConfigs[owner.id].regression;
+    const placement = validateRegressionPlacement(Object.hasOwn(args, "placement") ? args.placement : current.placement);
     const currentBinding = owner.derivedBindings?.regression?.mode === "follow" ? "follow" : "fixed";
     const sourceBinding = args.sourceBinding ?? currentBinding;
     if (!["fixed", "follow"].includes(sourceBinding)) throw new Error('Regression sourceBinding must be "fixed" or "follow".');
@@ -350,6 +353,8 @@ export const editRegression = /* @__PURE__ */ closedAction(
         }
       }
 
+      next = next._withMarkConfig(owner.id, { ...next.markConfigs[owner.id],
+        regression: { ...current, dataId } });
       let bandId = current.bandId;
       if (hadBand && !wantsBand) {
         next = removeOwnedMark(next, current.bandId);
@@ -411,6 +416,7 @@ export const editRegression = /* @__PURE__ */ closedAction(
         ...next.markConfigs[owner.id],
         regression: {
           ...current,
+          ...(Object.hasOwn(args, "placement") ? { placement } : {}),
           source,
           x,
           y,
@@ -432,6 +438,9 @@ export const editRegression = /* @__PURE__ */ closedAction(
       } else if (sourceBinding === "fixed" && binding !== undefined) {
         next = next.editSemantic({ property: `layer[${owner.id}].derivedBindings.regression`, remove: true });
       }
+      if (placement === "plot-last" || Object.hasOwn(args, "placement")) {
+        next = reconcileRegressionPlacement(next, owner.id);
+      }
       return next;
     };
     return applyEdit(this);

package/src/core/compositionState.js

@@ -1,3 +1,4 @@
+import { normalizeFacetAxes } from "./facetAxisPolicy.js";
 import { isOwned, isPlainObject } from "./immutable.js";
 import { ownProgramState } from "./programState.js";
 import {
@@ -43,6 +44,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 +206,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(
@@ -289,8 +291,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/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,