ggaction 0.0.15 → 0.0.17

package/src/core/identifiers.js

@@ -1,12 +1,13 @@
+import { annotateError } from "./diagnostics.js";
 export const USER_ID_SOURCE = "[A-Za-z0-9_-]+";
 
 const USER_ID_PATTERN = new RegExp(`^${USER_ID_SOURCE}$`);
 
 export function validateUserId(id, label = "ID") {
   if (typeof id !== "string" || !USER_ID_PATTERN.test(id)) {
-    throw new TypeError(
+    throw annotateError(new TypeError(
       `${label} must contain only letters, numbers, _ or - and must not be empty.`
-    );
+    ), { code: "invalid-value", optionPath: label });
   }
 
   return id;
@@ -20,9 +21,9 @@ export function resolveOptionalUserId(id, {
 }) {
   if (id !== undefined) return validateUserId(id, label);
   if (ambiguous) {
-    throw new Error(
+    throw annotateError(new Error(
       `${operation} requires an explicit ${label.toLowerCase()} because its default is ambiguous.`
-    );
+    ), { code: "ambiguous-resource", operation, optionPath: label });
   }
   return validateUserId(defaultId, label);
 }

package/src/core/immutable.js

@@ -22,11 +22,18 @@ export function isOwned(value) {
   return value !== null && typeof value === "object" && ownedValues.has(value);
 }
 
-export function cloneAndFreeze(value, ancestors = new WeakSet()) {
+export function cloneAndFreeze(value, ancestors = new WeakSet(), path = "state") {
+  if (typeof value === "function") {
+    throw new TypeError(`Cannot store a function at ${path} in a ChartProgram.`);
+  }
   if (value === null || typeof value !== "object") {
     return value;
   }
 
+  // Only library-owned values are recursively immutable; Object.freeze alone
+  // does not prove ownership of a caller's descendants.
+  if (isOwned(value)) return value;
+
   if (ancestors.has(value)) {
     throw new TypeError("Cannot store cyclic values in a ChartProgram.");
   }
@@ -36,12 +43,12 @@ export function cloneAndFreeze(value, ancestors = new WeakSet()) {
   let clone;
 
   if (Array.isArray(value)) {
-    clone = value.map(item => cloneAndFreeze(item, ancestors));
+    clone = value.map((item, index) => cloneAndFreeze(item, ancestors, `${path}[${index}]`));
   } else if (isPlainObject(value)) {
     clone = Object.fromEntries(
       Object.entries(value).map(([key, item]) => [
         key,
-        cloneAndFreeze(item, ancestors)
+        cloneAndFreeze(item, ancestors, `${path}.${key}`)
       ])
     );
   } else {

package/src/core/optionRequirements.js

@@ -0,0 +1,8 @@
+// The method's value-producing contract is shared by runtime validation and
+// authoring knowledge; editing can inherit these values from stored state.
+export const IMPUTE_REQUIRED_OPTIONS = Object.freeze({
+  constant: Object.freeze(["value"]),
+  forward: Object.freeze(["sortBy"]),
+  backward: Object.freeze(["sortBy"]),
+  linear: Object.freeze(["sortBy"])
+});

package/src/core/programState.js

@@ -23,7 +23,7 @@ export function ownChildPrograms(children, ProgramClass) {
     if (!(program instanceof ProgramClass)) {
       throw new TypeError(`ChartProgram child "${id}" must be a ChartProgram.`);
     }
-    owned[id] = program;
+    Object.defineProperty(owned, id, { value: program, enumerable: true });
   }
   return freezeOwned(owned);
 }
@@ -34,12 +34,16 @@ export function ownChildPrograms(children, ProgramClass) {
 // domain's dependency validation and before the primitive deletion.
 export function releaseNamedResourceOwnership(program, { kind, id, dataOwner }) {
   if (kind !== "data") return program;
-  const materializationConfigs = dataOwner === undefined
+  let materializationConfigs = dataOwner === undefined
     ? program.materializationConfigs
     : removeMaterializationConfig(
         program.materializationConfigs,
         ["data", dataOwner.family, dataOwner.owner]
       ).value;
+  materializationConfigs = removeMaterializationConfig(
+    materializationConfigs,
+    ["calculations", "datasets", dataOwner?.current ?? id]
+  ).value;
   const context = program.context.currentData === id
     ? freezeOwned({ ...program.context, currentData: undefined })
     : program.context;

package/src/core/resourceReferences.js

@@ -148,14 +148,19 @@ export function collectMarkConfigReferences(program) {
           "coordinate", value, "markConfig", ownerId, path
         ));
       }
-      if ((key === "scale" || key.endsWith("Scale")) && typeof value === "string") {
+      const reservedScale = root === "regression" && key === "colorScale" && config.regression.groupBy === undefined;
+      if (!reservedScale && (key === "scale" || key.endsWith("Scale")) && typeof value === "string") {
         append(references, reference("scale", value, "markConfig", ownerId, path));
       } else if (key === "scale" && isPlainObject(value)) {
         append(references, reference(
           "scale", value.id, "markConfig", ownerId, [...path, "id"]
         ));
       }
-      if (MARK_ID_KEYS.has(key)) {
+      const inactiveMark = (root === "boxPlot" && key === "outlierId" && !Object.hasOwn(program.markConfigs, value)) ||
+        (root === "errorBar" && ["lowerCapId", "upperCapId"].includes(key) && config.errorBar.caps === false) ||
+        (root === "errorBand" && ["lowerBoundaryId", "upperBoundaryId"].includes(key) &&
+          !Object.hasOwn(program.markConfigs, value));
+      if (MARK_ID_KEYS.has(key) && !inactiveMark) {
         append(references, reference("mark", value, "markConfig", ownerId, path));
       }
       if (
@@ -316,7 +321,13 @@ export function collectResourceReferences(program, { kind, id }) {
     throw new Error(`Unknown resource kind "${kind}".`);
   }
   const target = validateUserId(id, "Resource id");
-  const combined = [
+  const combined = collectAllResourceReferences(program).filter(value => value.kind === kind && value.id === target);
+  const unique = new Map(combined.map(value => [referenceKey(value), value]));
+  return freezeOwned([...unique.values()].sort(compareReferences));
+}
+
+export function collectAllResourceReferences(program) {
+  return [
     ...collectSemanticDataReferences(program),
     ...collectSemanticScaleReferences(program),
     ...collectSemanticCoordinateReferences(program),
@@ -326,7 +337,5 @@ export function collectResourceReferences(program, { kind, id }) {
     ...collectDataOwnerReferences(program),
     ...collectCompositionReferences(program),
     ...collectContextReferences(program)
-  ].filter(value => value.kind === kind && value.id === target);
-  const unique = new Map(combined.map(value => [referenceKey(value), value]));
-  return freezeOwned([...unique.values()].sort(compareReferences));
+  ];
 }

package/src/core/textMetricProfile.js

@@ -0,0 +1,28 @@
+import { cloneAndFreeze } from "./immutable.js";
+import { validateUserId } from "./identifiers.js";
+import { validateOptionObject, validatePositiveFinite, validateNonNegativeFinite, validateNonEmptyString } from "./validation.js";
+
+import { textMetricKey } from "./font.js";
+
+export function normalizeTextMetricProfile(profile) {
+  validateOptionObject(profile, ["schemaVersion", "id", "measurements"], "Text metrics profile");
+  if (profile.schemaVersion !== 1) throw new Error("Text metrics require schemaVersion 1.");
+  validateUserId(profile.id, "Text metrics profile id");
+  if (!Array.isArray(profile.measurements)) throw new TypeError("Text metrics measurements must be an array.");
+  const seen = new Set();
+  for (const measurement of profile.measurements) {
+    validateOptionObject(measurement, ["text", "fontFamily", "fontSize", "fontWeight", "width"], "Text measurement");
+    if (typeof measurement.text !== "string") throw new TypeError("Text measurement text must be a string.");
+    validateNonEmptyString(measurement.fontFamily, "Text measurement fontFamily");
+    validatePositiveFinite(measurement.fontSize, "Text measurement fontSize");
+    validateNonNegativeFinite(measurement.width, "Text measurement width");
+    if (!Number.isInteger(measurement.fontWeight) || measurement.fontWeight < 100 ||
+        measurement.fontWeight > 900 || measurement.fontWeight % 100 !== 0) {
+      throw new RangeError("Text measurement fontWeight must be 100–900 in steps of 100.");
+    }
+    const key = textMetricKey(measurement);
+    if (seen.has(key)) throw new Error("Duplicate text measurement combination.");
+    seen.add(key);
+  }
+  return cloneAndFreeze(profile);
+}

package/src/core/textMetrics.js

@@ -1,3 +1,21 @@
+import { DEFAULT_FONT_FAMILY, textMetricFontWeight, textMetricKey } from "./font.js";
+
+import { isOwned } from "./immutable.js";
+
+const measurementIndexes = new WeakMap();
+
+function measuredWidth(profile, text, style) {
+  if (profile === undefined) return undefined;
+  let index = measurementIndexes.get(profile);
+  if (index === undefined) {
+    index = new Map(profile.measurements.map(measurement =>
+      [textMetricKey(measurement), measurement.width]));
+    if (isOwned(profile)) measurementIndexes.set(profile, index);
+  }
+  return index.get(textMetricKey({ text, fontFamily: style.fontFamily ?? DEFAULT_FONT_FAMILY,
+    fontSize: style.fontSize, fontWeight: textMetricFontWeight(style.fontWeight) }));
+}
+
 function codePointWidth(codePoint) {
   if (/\s/u.test(codePoint)) return 0.28;
   if (/[iIl.,:;!'|]/u.test(codePoint)) return 0.27;
@@ -25,7 +43,8 @@ export function textBoundsFitCanvas(bounds, canvas) {
 
 export function measureTextWidth(
   text,
-  { fontSize, fontFamily, fontWeight } = {}
+  { fontSize, fontFamily, fontWeight } = {},
+  profile
 ) {
   if (typeof text !== "string") {
     throw new TypeError("Text measurement requires a string.");
@@ -33,6 +52,8 @@ export function measureTextWidth(
   if (!Number.isFinite(fontSize) || fontSize <= 0) {
     throw new RangeError("Text measurement requires a positive fontSize.");
   }
+  const measured = measuredWidth(profile, text, { fontSize, fontFamily, fontWeight });
+  if (measured !== undefined) return measured;
   let joined = false;
   let width = 0;
   for (const codePoint of text) {
@@ -76,11 +97,11 @@ export function resolveTextBounds({
   textAlign = "left",
   textBaseline = "alphabetic",
   rotation = 0
-} = {}) {
+} = {}, profile) {
   if (![x, y, rotation].every(Number.isFinite)) {
     throw new TypeError("Text bounds require finite x, y, and rotation values.");
   }
-  const width = measureTextWidth(text, { fontSize, fontFamily, fontWeight });
+  const width = measureTextWidth(text, { fontSize, fontFamily, fontWeight }, profile);
   const [left, right] = textAlign === "center"
     ? [-width / 2, width / 2]
     : ["right", "end"].includes(textAlign) ? [-width, 0] : [0, width];

package/src/core/validation.js

@@ -1,15 +1,27 @@
+import { annotateError } from "./diagnostics.js";
 import { isPlainObject } from "./immutable.js";
 
 export const MAX_GENERATED_ITEMS = 10_000;
 export const MAX_WORK_ITEMS = 10_000_000;
 
+export function validateDataRows(values, label = "Dataset") {
+  if (!Array.isArray(values)) {
+    throw annotateError(new TypeError(`${label} requires values to be an array.`), { code: "invalid-value", optionPath: "values" });
+  }
+  for (let index = 0; index < values.length; index += 1) {
+    if (!Object.hasOwn(values, index) || !isPlainObject(values[index])) {
+      throw annotateError(new TypeError(`${label} requires every row to be a plain object; invalid row at index ${index}.`), { code: "invalid-value", optionPath: `values[${index}]` });
+    }
+  }
+}
+
 export function validateGeneratedItemLimit(
   value,
   label,
   maximum = MAX_GENERATED_ITEMS
 ) {
   if (value > maximum) {
-    throw new RangeError(`${label} must not exceed ${maximum}.`);
+    throw annotateError(new RangeError(`${label} must not exceed ${maximum}.`), { code: "resource-limit", optionPath: label, limit: maximum, actual: value });
   }
   return value;
 }
@@ -21,7 +33,7 @@ export function validateWorkLimit(value, label) {
 export function validateKeys(value, supported, label) {
   for (const key of Object.keys(value)) {
     if (!supported.includes(key)) {
-      throw new Error(`Unknown ${label} option "${key}".`);
+      throw annotateError(new Error(`Unknown ${label} option "${key}".`), { code: "invalid-option", optionPath: key });
     }
   }
 }
@@ -33,18 +45,18 @@ export function validateOptionObject(value, supported, label, {
   emptyError = TypeError
 } = {}) {
   if (!isPlainObject(value)) {
-    throw new TypeError(plainObjectMessage);
+    throw annotateError(new TypeError(plainObjectMessage), { code: "invalid-option" });
   }
   if (supported !== undefined) validateKeys(value, supported, label);
   if (!allowEmpty && Object.keys(value).length === 0) {
-    throw new emptyError(emptyMessage);
+    throw annotateError(new emptyError(emptyMessage), { code: "invalid-option" });
   }
   return value;
 }
 
 export function noOptions(args, operation) {
   if (!isPlainObject(args) || Object.keys(args).length > 0) {
-    throw new Error(`${operation} does not accept options.`);
+    throw annotateError(new Error(`${operation} does not accept options.`), { code: "invalid-option", operation });
   }
 }
 
@@ -59,30 +71,30 @@ export function sameOrderedValues(left, right) {
 
 export function validateNonEmptyString(value, label) {
   if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
+    throw annotateError(new TypeError(`${label} must be a non-empty string.`), { code: "invalid-value", optionPath: label });
   }
   return value;
 }
 
 export function validateUnitInterval(value, label) {
   if (!Number.isFinite(value) || value < 0 || value > 1) {
-    throw new RangeError(
+    throw annotateError(new RangeError(
       `${label} must be between 0 and 1 (values from 0 to 1).`
-    );
+    ), { code: "invalid-value", optionPath: label });
   }
   return value;
 }
 
 export function validatePositiveFinite(value, label) {
   if (!Number.isFinite(value) || value <= 0) {
-    throw new RangeError(`${label} must be a positive finite number.`);
+    throw annotateError(new RangeError(`${label} must be a positive finite number.`), { code: "invalid-value", optionPath: label });
   }
   return value;
 }
 
 export function validateNonNegativeFinite(value, label) {
   if (!Number.isFinite(value) || value < 0) {
-    throw new RangeError(`${label} must be a non-negative finite number.`);
+    throw annotateError(new RangeError(`${label} must be a non-negative finite number.`), { code: "invalid-value", optionPath: label });
   }
   return value;
 }

package/src/diagnostics.js

@@ -0,0 +1 @@
+export { getErrorDetails } from "./core/diagnostics.js";

package/src/grammar/bin.js

@@ -15,7 +15,7 @@ import {
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "field", "bin", "extent", "nice", "zero", "includeEmpty",
-  "members", "as", "weight", "resolved"
+  "members", "as", "weight", "missing", "resolved"
 ]);
 const AS_KEYS = Object.freeze(["lower", "upper", "count", "members"]);
 const RESOLVED_KEYS = Object.freeze(["domain", "step", "boundaries"]);
@@ -59,7 +59,8 @@ export function normalizeBinTransform({
   includeEmpty,
   members,
   as,
-  weight
+  weight,
+  missing
 } = {}) {
   const selected = [maxBins, step, boundaries].filter(value => value !== undefined);
   if (selected.length > 1) {
@@ -83,7 +84,8 @@ export function normalizeBinTransform({
     as: normalizeAs(field, as, resolvedMembers),
     ...(weight === undefined
       ? {}
-      : { weight: normalizeStatisticalWeight(weight, "Bin weight") })
+      : { weight: normalizeStatisticalWeight(weight, "Bin weight") }),
+    ...(missing === undefined ? {} : { missing })
   };
   validateBinTransform(transform);
   return cloneAndFreeze(transform);
@@ -101,6 +103,9 @@ export function validateBinTransform(transform) {
   if (transform.weight !== undefined) {
     normalizeStatisticalWeight(transform.weight, "Bin weight");
   }
+  if (transform.missing !== undefined && !["error", "drop"].includes(transform.missing)) {
+    throw new Error('Bin missing must be "error" or "drop".');
+  }
   normalizeHistogramBin(transform.bin);
   if (
     transform.extent !== "auto" &&
@@ -142,22 +147,31 @@ export function validateBinTransform(transform) {
   return transform;
 }
 
-function readValues(rows, field) {
-  return rows.map((row, index) => {
+function readValues(rows, field, missing) {
+  const eligible = [];
+  let excluded = 0;
+  rows.forEach((row, index) => {
     const value = row[field];
+    if (value === null || value === undefined) {
+      if (missing === "drop") { excluded += 1; return; }
+      throw new TypeError(`Bin field "${field}" must contain a finite number at row ${index}.`);
+    }
     if (!Number.isFinite(value)) {
       throw new TypeError(`Bin field "${field}" must contain a finite number at row ${index}.`);
     }
-    return value;
+    eligible.push({ row, index });
   });
+  return { eligible, excluded };
 }
 
 export function deriveBinRows(rows, transform) {
   validateBinTransform(transform);
-  const values = readValues(rows, transform.field);
+  const selected = readValues(rows, transform.field, transform.missing);
+  const eligibleRows = selected.eligible.map(entry => entry.row);
+  const values = eligibleRows.map(row => row[transform.field]);
   const weights = transform.weight === undefined
     ? undefined
-    : readStatisticalWeights(rows, transform.weight, "Bin");
+    : readStatisticalWeights(eligibleRows, transform.weight, "Bin");
   if (weights !== undefined) {
     validateWeightedNumericFields(weights.entries, [transform.field], "Bin");
   }
@@ -188,7 +202,7 @@ export function deriveBinRows(rows, transform) {
   });
   const members = resolved.boundaries.slice(0, -1).map(() => []);
   const entries = weightSummary === undefined
-    ? rows.map((row, index) => ({ row, index }))
+    ? selected.eligible
     : weightSummary.positive;
   entries.forEach(entry => {
     const value = entry.row[transform.field];
@@ -217,7 +231,22 @@ export function deriveBinRows(rows, transform) {
       domain: resolved.domain,
       ...(resolved.step === undefined ? {} : { step: resolved.step }),
       boundaries: resolved.boundaries
-    }
+    },
+    ...(transform.missing === undefined ? {} : {
+      report: {
+        version: 1,
+        owner: { kind: "data", id: "pending" },
+        inputs: [],
+        units: [{
+          role: transform.as.count,
+          group: {},
+          inputRows: rows.length,
+          usedRows: eligibleRows.length,
+          excludedRows: selected.excluded,
+          excludedByReason: selected.excluded === 0 ? {} : { "missing-value": selected.excluded }
+        }]
+      }
+    })
   };
 }