ggaction 0.0.16 → 0.0.18

package/src/grammar/filter.js

@@ -39,33 +39,62 @@ function validateRange(range) {
     throw new TypeError("Filter range must be a plain object.");
   }
   const unknown = Object.keys(range).find(
-    key => !["min", "max", "inclusive"].includes(key)
+    key => !["min", "max", "inclusive", "minInclusive", "maxInclusive"].includes(key)
   );
   if (unknown !== undefined) {
     throw new Error(`Unknown filter range property "${unknown}".`);
   }
-  if (
-    !isFiniteOrString(range.min) ||
-    !isFiniteOrString(range.max) ||
-    typeof range.min !== typeof range.max
-  ) {
-    throw new TypeError(
-      "Filter range endpoints must be finite numbers or strings of one type."
-    );
+  const hasMin = Object.hasOwn(range, "min");
+  const hasMax = Object.hasOwn(range, "max");
+  if (!hasMin && !hasMax) throw new TypeError("Filter range requires min or max.");
+  if ((hasMin && !isFiniteOrString(range.min)) || (hasMax && !isFiniteOrString(range.max))) {
+    throw new TypeError("Filter range endpoints must be finite numbers or strings.");
+  }
+  if (hasMin && hasMax && typeof range.min !== typeof range.max) {
+    throw new TypeError("Filter range endpoints must use one type.");
   }
-  if (range.min > range.max) {
+  if (hasMin && hasMax && range.min > range.max) {
     throw new RangeError("Filter range min must not exceed max.");
   }
   if (range.inclusive !== undefined && typeof range.inclusive !== "boolean") {
     throw new TypeError("Filter range inclusive must be a boolean.");
   }
+  if (range.inclusive !== undefined && (
+    range.minInclusive !== undefined || range.maxInclusive !== undefined
+  )) throw new Error("Filter range cannot combine inclusive with endpoint inclusivity.");
+  for (const [key, endpoint] of [["minInclusive", "min"], ["maxInclusive", "max"]]) {
+    if (range[key] !== undefined && typeof range[key] !== "boolean") {
+      throw new TypeError(`Filter range ${key} must be a boolean.`);
+    }
+    if (range[key] !== undefined && !Object.hasOwn(range, endpoint)) {
+      throw new Error(`Filter range ${key} requires ${endpoint}.`);
+    }
+  }
+}
+
+function normalizeRange(range) {
+  validateRange(range);
+  const shared = range.inclusive;
+  return {
+    ...(Object.hasOwn(range, "min") ? { min: range.min, minInclusive: shared ?? range.minInclusive ?? true } : {}),
+    ...(Object.hasOwn(range, "max") ? { max: range.max, maxInclusive: shared ?? range.maxInclusive ?? true } : {})
+  };
+}
+
+function normalizeSet(values, name) {
+  if (!Array.isArray(values) || values.length === 0 ||
+      Array.from({ length: values.length }, (_, index) => index).some(index => !Object.hasOwn(values, index)) ||
+      values.some(value => value !== null && typeof value !== "string" && typeof value !== "boolean" && !(typeof value === "number" && Number.isFinite(value)))) {
+    throw new TypeError(`Filter ${name} must be a non-empty dense array of scalar values.`);
+  }
+  return [...new Set(values)];
 }
 
 export function validateFilterTransform(transform) {
   if (!isPlainObject(transform)) {
     throw new TypeError("Filter transform must be a plain object.");
   }
-  const supported = ["type", "field", "oneOf", "predicate", "range"];
+  const supported = ["type", "field", "oneOf", "noneOf", "predicate", "range", "nulls"];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
   if (unknown !== undefined) {
     throw new Error(`Unknown filter transform property "${unknown}".`);
@@ -73,12 +102,15 @@ export function validateFilterTransform(transform) {
   if (typeof transform.field !== "string" || transform.field.length === 0) {
     throw new TypeError("Filter field must be a non-empty field string.");
   }
-  const modes = ["oneOf", "predicate", "range"].filter(
+  if (transform.nulls !== undefined && !["include", "exclude"].includes(transform.nulls)) {
+    throw new Error('Filter nulls must be "include" or "exclude".');
+  }
+  const modes = ["oneOf", "noneOf", "predicate", "range"].filter(
     key => Object.hasOwn(transform, key)
   );
   if (modes.length !== 1) {
     throw new Error(
-      "Filter transform requires exactly one of oneOf, predicate, or range."
+      "Filter transform requires exactly one of oneOf, noneOf, predicate, or range."
     );
   }
   if (modes[0] === "predicate") {
@@ -89,46 +121,101 @@ export function validateFilterTransform(transform) {
     validateRange(transform.range);
     return;
   }
-  if (
-    !Array.isArray(transform.oneOf) ||
-    transform.oneOf.length === 0 ||
-    transform.oneOf.some(value =>
-      value !== null &&
-      typeof value !== "string" &&
-      typeof value !== "boolean" &&
-      !(typeof value === "number" && Number.isFinite(value))
-    )
-  ) {
-    throw new TypeError("Filter oneOf must be a non-empty array of scalar values.");
-  }
+  normalizeSet(transform[modes[0]], modes[0]);
 }
 
 export function normalizeFilterTransform({
   field,
   oneOf,
+  noneOf,
   predicate,
-  range
+  range,
+  nulls
 }) {
-  const modes = { oneOf, predicate, range };
+  const modes = { oneOf, noneOf, predicate, range };
   const selected = Object.keys(modes).filter(key => modes[key] !== undefined);
   const transform = {
     type: "filter",
     field,
-    ...(selected[0] === "oneOf" ? { oneOf } : {}),
+    ...(selected[0] === "oneOf" ? { oneOf: normalizeSet(oneOf, "oneOf") } : {}),
+    ...(selected[0] === "noneOf" ? { noneOf: normalizeSet(noneOf, "noneOf") } : {}),
     ...(selected[0] === "predicate" ? { predicate } : {}),
     ...(selected[0] === "range"
-      ? { range: { ...range, inclusive: range?.inclusive ?? true } }
-      : {})
+      ? { range: normalizeRange(range) }
+      : {}),
+    ...(nulls === undefined ? {} : { nulls })
   };
   if (selected.length !== 1) {
     throw new Error(
-      "filterData requires exactly one of oneOf, predicate, or range."
+      "filterData requires exactly one of oneOf, noneOf, predicate, or range."
     );
   }
   validateFilterTransform(transform);
   return cloneAndFreeze(transform);
 }
 
+export function normalizeFilterTransformEdit(transform, patch) {
+  const modes = ["oneOf", "noneOf", "predicate", "range"];
+  const previousMode = modes.find(key => Object.hasOwn(transform, key));
+  const requestedModes = modes.filter(key => Object.hasOwn(patch, key));
+  if (requestedModes.length > 1) {
+    throw new Error("Filter edit can replace only one filter mode.");
+  }
+  const fieldChanged = Object.hasOwn(patch, "field") && patch.field !== transform.field;
+  if (fieldChanged && requestedModes.length === 0) {
+    throw new Error("Changing a filter field requires a complete filter mode.");
+  }
+  let mode = previousMode;
+  let modeValue = transform[previousMode];
+  if (requestedModes.length === 1) {
+    mode = requestedModes[0];
+    if (mode === "range" && previousMode === "range" && !fieldChanged) {
+      if (!isPlainObject(patch.range)) throw new TypeError("Filter range patch must be a plain object.");
+      const legacy = normalizeRange(transform.range);
+      const next = { ...legacy };
+      const rangePatch = patch.range;
+      const unknown = Object.keys(rangePatch).find(key => !["min", "max", "inclusive", "minInclusive", "maxInclusive"].includes(key));
+      if (unknown !== undefined) throw new Error(`Unknown filter range property "${unknown}".`);
+      if (rangePatch.inclusive !== undefined && (rangePatch.minInclusive !== undefined || rangePatch.maxInclusive !== undefined)) {
+        throw new Error("Filter range cannot combine inclusive with endpoint inclusivity.");
+      }
+      for (const endpoint of ["min", "max"]) {
+        if (!Object.hasOwn(rangePatch, endpoint)) continue;
+        if (rangePatch[endpoint] === false) {
+          delete next[endpoint];
+          delete next[`${endpoint}Inclusive`];
+        } else {
+          next[endpoint] = rangePatch[endpoint];
+          next[`${endpoint}Inclusive`] = Object.hasOwn(legacy, endpoint)
+            ? legacy[`${endpoint}Inclusive`]
+            : true;
+        }
+      }
+      if (rangePatch.inclusive !== undefined) {
+        if (typeof rangePatch.inclusive !== "boolean") throw new TypeError("Filter range inclusive must be a boolean.");
+        if (Object.hasOwn(next, "min")) next.minInclusive = rangePatch.inclusive;
+        if (Object.hasOwn(next, "max")) next.maxInclusive = rangePatch.inclusive;
+      }
+      for (const endpoint of ["min", "max"]) {
+        const key = `${endpoint}Inclusive`;
+        if (rangePatch[key] !== undefined) {
+          if (!Object.hasOwn(next, endpoint)) throw new Error(`Filter range ${key} requires ${endpoint}.`);
+          next[key] = rangePatch[key];
+        }
+      }
+      modeValue = next;
+    } else {
+      modeValue = patch[mode];
+    }
+  }
+  const nulls = patch.nulls === false ? undefined : (patch.nulls ?? transform.nulls);
+  return normalizeFilterTransform({
+    field: patch.field ?? transform.field,
+    [mode]: modeValue,
+    ...(nulls === undefined ? {} : { nulls })
+  });
+}
+
 function comparable(value, operand) {
   return (
     Number.isFinite(value) && Number.isFinite(operand)
@@ -141,6 +228,7 @@ function matches(value, transform) {
   if (transform.oneOf !== undefined) {
     return transform.oneOf.includes(value);
   }
+  if (transform.noneOf !== undefined) return !transform.noneOf.includes(value);
   if (transform.predicate !== undefined) {
     const { op, value: operand } = transform.predicate;
     if (op === "eq") return value === operand;
@@ -151,11 +239,12 @@ function matches(value, transform) {
     if (op === "gt") return value > operand;
     return value >= operand;
   }
-  const { min, max, inclusive = true } = transform.range;
-  if (!comparable(value, min) || !comparable(value, max)) return false;
-  return inclusive
-    ? value >= min && value <= max
-    : value > min && value < max;
+  const { min, max, minInclusive = transform.range.inclusive ?? true, maxInclusive = transform.range.inclusive ?? true } = transform.range;
+  if (min !== undefined && !comparable(value, min)) return false;
+  if (max !== undefined && !comparable(value, max)) return false;
+  if (min !== undefined && (value < min || (value === min && !minInclusive))) return false;
+  if (max !== undefined && (value > max || (value === max && !maxInclusive))) return false;
+  return true;
 }
 
 export function deriveFilteredRows(values, transform) {
@@ -163,7 +252,12 @@ export function deriveFilteredRows(values, transform) {
     throw new TypeError("Filter source values must be an array.");
   }
   validateFilterTransform(transform);
-  return values.filter(row =>
-    isPlainObject(row) && matches(row[transform.field], transform)
-  );
+  return values.filter(row => {
+    if (!isPlainObject(row)) return false;
+    const value = row[transform.field];
+    if (value === null || value === undefined) {
+      if (transform.nulls !== undefined) return transform.nulls === "include";
+    }
+    return matches(value, transform);
+  });
 }

package/src/grammar/fold.js

@@ -1,3 +1,5 @@
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
+import { requireStringValue as requireField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 
 const TRANSFORM_KEYS = Object.freeze(["type", "fields", "as"]);
@@ -5,19 +7,7 @@ const AS_KEYS = Object.freeze(["key", "value"]);
 const MAX_FIELDS = 64;
 const MAX_OUTPUT_ROWS = 10_000;
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) {
-    throw new Error(`Unknown ${label} property "${unknown}".`);
-  }
-}
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 function normalizeAs(value) {
   const requested = value ?? {};

package/src/grammar/gradientProfile.js

@@ -1,3 +1,4 @@
+import { requireStringValue as requireField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import {
   deriveKernelDensity,
@@ -23,12 +24,6 @@ const TRANSFORM_KEYS = [
 ];
 const OUTPUT_KEYS = Object.keys(GRADIENT_PROFILE_FIELDS);
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 function validatePair(value, label) {
   if (

package/src/grammar/impute.js

@@ -1,26 +1,16 @@
+import { normalizeSortBy, validateSortBy } from "./transformKeys.js";
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
+import { requireStringValue as requireField } from "../core/validation.js";
 import { IMPUTE_REQUIRED_OPTIONS } from "../core/optionRequirements.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import { interpolateNumber, inverseLerp } from "./numeric.js";
+import { interpolateNumber, inverseLerp, stableFiniteMean } from "./numeric.js";
 import { normalizeTemporalValue } from "./scales/fields.js";
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "fields", "groupBy", "sortBy", "method", "value", "edges", "maxGap"
 ]);
-const SORT_KEYS = Object.freeze(["field", "order"]);
 const METHODS = Object.freeze(Object.keys(IMPUTE_REQUIRED_OPTIONS));
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) throw new Error(`Unknown ${label} property "${unknown}".`);
-}
-
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
-
 function validateFieldList(value, label) {
   if (!Array.isArray(value) || value.length === 0 || value.some(field =>
     typeof field !== "string" || field.length === 0
@@ -35,33 +25,6 @@ function normalizeFieldList(value, { allowEmpty = false } = {}) {
   return Array.isArray(value) ? [...value] : [value];
 }
 
-function normalizeSortBy(value) {
-  if (value === undefined) return [];
-  if (!Array.isArray(value)) return value;
-  return value.map(sort => isPlainObject(sort)
-    ? { ...sort, order: sort.order ?? "ascending" }
-    : sort
-  );
-}
-
-function validateSortBy(sortBy) {
-  if (!Array.isArray(sortBy)) throw new TypeError("Impute sortBy must be an array.");
-  const fields = [];
-  sortBy.forEach((sort, index) => {
-    if (!isPlainObject(sort)) {
-      throw new TypeError(`Impute sortBy[${index}] must be a plain object.`);
-    }
-    rejectUnknownKeys(sort, SORT_KEYS, `impute sortBy[${index}]`);
-    fields.push(requireField(sort.field, `Impute sortBy[${index}].field`));
-    if (!["ascending", "descending"].includes(sort.order)) {
-      throw new Error(`Unsupported impute sort order "${sort.order}".`);
-    }
-  });
-  if (new Set(fields).size !== fields.length) {
-    throw new Error("Impute sortBy fields must be unique.");
-  }
-}
-
 function scalarType(value, label) {
   if (value === null || value === undefined) return undefined;
   if (typeof value === "string" || typeof value === "boolean") return typeof value;
@@ -94,7 +57,7 @@ export function validateImputeTransform(transform) {
   if (new Set(transform.groupBy).size !== transform.groupBy.length) {
     throw new Error("Impute groupBy fields must be unique.");
   }
-  validateSortBy(transform.sortBy);
+  validateSortBy(transform.sortBy, "Impute");
   if (!METHODS.includes(transform.method)) {
     throw new Error(`Unsupported impute method "${transform.method}".`);
   }
@@ -107,7 +70,7 @@ export function validateImputeTransform(transform) {
     scalarType(transform.value, "Impute constant value");
   } else {
     if (hasValue) throw new Error(`Impute value is not available for ${transform.method}.`);
-    if (transform.sortBy.length === 0) {
+    if (transform.method !== "mean" && transform.sortBy.length === 0) {
       throw new Error(`Impute ${transform.method} requires non-empty sortBy.`);
     }
   }
@@ -132,7 +95,7 @@ export function normalizeImputeTransform(args = {}) {
     fields: normalizeFieldList(args.fields),
     groupBy: normalizeFieldList(args.groupBy, { allowEmpty: true }),
     sortBy: normalizeSortBy(args.sortBy),
-    method: args.method,
+    method: args.method ?? "mean",
     edges: args.edges ?? "keep"
   };
   if (Object.hasOwn(args, "value")) transform.value = args.value;
@@ -212,9 +175,9 @@ function validateFieldTypes(entries, transform) {
     if (types.size > 1) {
       throw new TypeError(`Impute field "${field}" must contain one scalar type.`);
     }
-    if (transform.method === "linear" &&
+    if (["linear", "mean"].includes(transform.method) &&
       (types.size > 0 && !types.has("number"))) {
-      throw new TypeError(`Impute linear field "${field}" must contain finite numbers.`);
+      throw new TypeError(`Impute ${transform.method} field "${field}" must contain finite numbers.`);
     }
   }
 }
@@ -278,10 +241,18 @@ function setField(row, field, value) {
   });
 }
 
-function fillRun(partition, field, run, transform, positions) {
+function fillRun(partition, field, run, transform, positions, mean) {
   const [start, end] = run;
   const length = end - start + 1;
   if (transform.maxGap !== undefined && length > transform.maxGap) return;
+  if (transform.method === "mean") {
+    if (mean === undefined) {
+      if (transform.edges === "error") throw new RangeError(`Impute mean requires an observed value in field "${field}".`);
+      return;
+    }
+    for (let index = start; index <= end; index += 1) setField(partition[index].row, field, mean);
+    return;
+  }
   if (transform.method === "constant") {
     for (let index = start; index <= end; index += 1) {
       setField(partition[index].row, field, transform.value);
@@ -332,8 +303,10 @@ export function deriveImputedRows(rows, transform) {
     partition.sort((left, right) => compareEntries(left, right, transform.sortBy));
     const positions = linearPositions(partition, transform);
     for (const field of transform.fields) {
+      const observed = transform.method === "mean" ? partition.map(entry => entry.row[field]).filter(value => value !== null && value !== undefined) : [];
+      const mean = observed.length ? stableFiniteMean(observed, "Impute group mean") : undefined;
       for (const run of missingRuns(partition, field)) {
-        fillRun(partition, field, run, transform, positions);
+        fillRun(partition, field, run, transform, positions, mean);
       }
     }
   }

package/src/grammar/interval.js

@@ -1,3 +1,5 @@
+import { requireStringValue as nonEmptyString } from "../core/validation.js";
+import { isGroupValue } from "./transformKeys.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { aggregateScalarValues } from "./aggregate.js";
 import { requireFiniteResult, stableDecimal } from "./numeric.js";
@@ -16,15 +18,11 @@ const TRANSFORM_KEYS = [
   "extent",
   "method",
   "level",
+  "missing",
   "as"
 ];
 const OUTPUT_KEYS = ["center", "lower", "upper"];
 
-function nonEmptyString(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-}
 
 function validateGrouping(groupBy) {
   if (
@@ -82,6 +80,9 @@ export function validateIntervalTransform(transform) {
   if (!EXTENT_VALUES.includes(transform.extent)) {
     throw new Error(`Unsupported interval extent "${transform.extent}".`);
   }
+  if (transform.missing !== undefined && !["error", "drop"].includes(transform.missing)) {
+    throw new Error('Interval missing must be "error" or "drop".');
+  }
   if (
     (transform.center === "median") !== (transform.extent === "iqr")
   ) {
@@ -162,10 +163,6 @@ function isMissing(value) {
     (typeof value === "number" && Number.isNaN(value));
 }
 
-function isGroupValue(value) {
-  return typeof value === "string" || typeof value === "boolean" ||
-    (typeof value === "number" && Number.isFinite(value));
-}
 
 function deriveGroup(values, transform) {
   if (transform.center === "median") {
@@ -201,15 +198,24 @@ export function deriveInterval(rows, transform) {
   }
   validateIntervalTransform(transform);
   const groups = new Map();
+  let missingRows = 0;
   for (const row of rows) {
     if (!isPlainObject(row)) continue;
     const value = row[transform.field];
     if (isMissing(value) || !Number.isFinite(value)) {
+      const nullish = value === undefined || value === null;
+      if (transform.missing === "error" && nullish) {
+        throw new TypeError(`Interval field "${transform.field}" is missing.`);
+      }
+      if (transform.missing !== undefined && !nullish) {
+        throw new TypeError(`Interval field "${transform.field}" must contain finite numbers.`);
+      }
       if (value !== undefined && value !== null && typeof value !== "number") {
         throw new TypeError(
           `Interval field "${transform.field}" must contain numeric or missing values.`
         );
       }
+      if (nullish) missingRows += 1;
       continue;
     }
     const groupValues = transform.groupBy.map(field => row[field]);
@@ -240,7 +246,23 @@ export function deriveInterval(rows, transform) {
       [transform.as.upper]: stableDecimal(result.upper)
     });
   }
-  return cloneAndFreeze(output);
+  if (transform.missing === undefined) return cloneAndFreeze(output);
+  return cloneAndFreeze({
+    values: output,
+    report: {
+      version: 1,
+      owner: { kind: "data", id: "pending" },
+      inputs: [],
+      units: [{
+        role: transform.as.center,
+        group: {},
+        inputRows: rows.length,
+        usedRows: rows.length - missingRows,
+        excludedRows: missingRows,
+        excludedByReason: missingRows === 0 ? {} : { "missing-value": missingRows }
+      }]
+    }
+  });
 }
 
 export function normalizeIntervalTransform({
@@ -250,6 +272,7 @@ export function normalizeIntervalTransform({
   extent,
   method,
   level,
+  missing,
   as
 }) {
   nonEmptyString(field, "Interval field");
@@ -260,6 +283,7 @@ export function normalizeIntervalTransform({
     field,
     groupBy: grouping,
     ...parameters,
+    ...(missing === undefined ? {} : { missing }),
     as
   };
   validateIntervalTransform(transform);

package/src/grammar/itemMissing.js

@@ -0,0 +1,59 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+
+export const ITEM_MISSING_MARK_TYPES = Object.freeze([
+  "point", "bar", "rect", "tick", "rule", "text"
+]);
+
+export function validateItemMissing(value, label = "Mark missing") {
+  if (!["error", "skip"].includes(value)) {
+    throw new Error(`${label} must be "error" or "skip".`);
+  }
+  return value;
+}
+
+function collectFields(value, fields, seen) {
+  if (value === null || typeof value !== "object" || seen.has(value)) return;
+  seen.add(value);
+  if (typeof value.field === "string" && value.field.length > 0) {
+    fields.add(value.field);
+  }
+  for (const child of Object.values(value)) collectFields(child, fields, seen);
+}
+
+export function itemMissingFields(layer) {
+  const fields = new Set();
+  collectFields(layer.encoding ?? {}, fields, new Set());
+  return [...fields];
+}
+
+export function applyItemMissingPolicy(layer, dataset) {
+  const policy = layer.mark?.missing;
+  if (policy === undefined) return dataset;
+  if (!ITEM_MISSING_MARK_TYPES.includes(layer.mark?.type)) return dataset;
+  validateItemMissing(policy, `${layer.mark.type} missing`);
+  const fields = itemMissingFields(layer);
+  if (fields.length === 0) return dataset;
+  const eligible = [];
+  for (const [index, row] of dataset.values.entries()) {
+    const missing = fields.find(field => row[field] === null || row[field] === undefined);
+    if (missing === undefined) {
+      eligible.push(row);
+    } else if (policy === "error") {
+      throw new Error(
+        `${layer.mark.type} mark "${layer.id}" field "${missing}" is missing at row ${index}.`
+      );
+    }
+  }
+  if (eligible.length === dataset.values.length) return dataset;
+  return cloneAndFreeze({ ...dataset, values: eligible });
+}
+
+export function applyRequestedItemMissingPolicy(layer, dataset, field) {
+  if (typeof field !== "string" || field.length === 0) {
+    return applyItemMissingPolicy(layer, dataset);
+  }
+  return applyItemMissingPolicy({
+    ...layer,
+    encoding: { ...layer.encoding, __requested: { field } }
+  }, dataset);
+}

package/src/grammar/legendGradient.js

@@ -0,0 +1,18 @@
+import { validateOptionObject, validatePositiveFinite, validateUnitInterval } from "../core/validation.js";
+
+export const DEFAULT_LEGEND_GRADIENT = Object.freeze({ length: 120, thickness: 12 });
+const OPTIONS = Object.freeze(["length", "thickness", "opacity"]);
+
+export function validateLegendGradient(value, label = "Legend gradient") {
+  validateOptionObject(value, OPTIONS, label);
+  validatePositiveFinite(value.length, `${label} length`);
+  validatePositiveFinite(value.thickness, `${label} thickness`);
+  if (Object.hasOwn(value, "opacity")) validateUnitInterval(value.opacity, `${label} opacity`);
+}
+
+export function normalizeLegendGradient(patch, previous = DEFAULT_LEGEND_GRADIENT) {
+  if (patch !== undefined) validateOptionObject(patch, OPTIONS, "Legend gradient");
+  const value = { ...previous, ...patch };
+  validateLegendGradient(value);
+  return value;
+}

package/src/grammar/legendGroups.js

@@ -0,0 +1 @@
+import{validateOptionObject as r,validateNonNegativeFinite as i}from"../core/validation.js";import{validateUserId as a}from"../core/identifiers.js";import{PLOT_LEGEND_POSITIONS as g,LEGEND_POSITIONS as d,LEGEND_BLOCK_LAYOUTS as f}from"../core/vocabulary.js";function s(n){r(n,void 0,"Legend groups");for(const[o,t]of Object.entries(n)){if(a(o,"Legend group target"),r(t,["placement","blockLayout","inferredOffset"],"Legend group"),!f.includes(t.blockLayout))throw new Error("Legend group blockLayout must be row, column or wrap.");if(t.inferredOffset!==void 0&&typeof t.inferredOffset!="boolean")throw new TypeError("Legend group inferredOffset must be boolean.");const e=t.placement;if(r(e,["at","position","align","offset"],"Legend group placement"),Object.hasOwn(e,"at")){if(Object.keys(e).length!==1)throw new Error("Legend group at cannot coexist with an edge anchor.");if(r(e.at,["x","y"],"Legend group at"),!Number.isFinite(e.at.x)||!Number.isFinite(e.at.y))throw new Error("Legend group at requires finite x and y.")}else{if(Object.keys(e).length!==3||!d.includes(e.position))throw new Error("Legend group requires a complete edge placement.");if(!["left","center","right"].includes(e.align))throw new Error("Unsupported legend group alignment.");if((g.includes(e.position)||["left","right"].includes(e.position))&&e.align!=="center")throw new Error("Side and in-plot legend groups require center alignment.");i(e.offset,"Legend group offset")}}return n}export{s as validateLegendGroupState};

package/src/grammar/legendTitleStyle.js

@@ -0,0 +1,22 @@
+import { validateOptionObject } from "../core/validation.js";
+
+export const LEGEND_TITLE_STYLE_KEYS = Object.freeze([
+  "color", "fontSize", "fontFamily", "fontWeight", "align"
+]);
+
+export function validateLegendTitleAlignment(style, titlePosition = "top") {
+  if (style?.align === undefined) {
+    if (style !== undefined && Object.hasOwn(style, "align")) throw new TypeError("Legend title align requires left, center or right.");
+    return;
+  }
+  if (!["left", "center", "right"].includes(style.align)) throw new Error("Legend title align requires left, center or right.");
+  if (titlePosition === "left") throw new Error("Inline legend titles do not accept title alignment.");
+}
+
+export function mergeLegendTitleStyle(previous, patch, { edit = false } = {}) {
+  if (patch !== undefined) validateOptionObject(patch, LEGEND_TITLE_STYLE_KEYS, "Legend titleStyle");
+  const result = { ...previous, ...patch };
+  if (edit && patch?.align === "auto") delete result.align;
+  validateLegendTitleAlignment(result);
+  return result;
+}