ggaction 0.0.21 → 0.0.23

package/src/grammar/datasetDependencies.js

@@ -0,0 +1,97 @@
+import { datasetInputIds } from "../core/datasetReferences.js";
+export { datasetInputReferences, datasetInputIds, rebindTransformDatasetInputs } from "../core/datasetReferences.js";
+
+export function orderedDatasetAncestors(datasets, root) {
+  const byId = new Map(datasets.map(dataset => [dataset.id, dataset]));
+  const visiting = new Set(), visited = new Set(), result = [];
+  if (byId.size !== datasets.length) throw new Error("Dataset dependency graph contains duplicate ids.");
+  function visit(id) {
+    if (visiting.has(id)) throw new Error(`Dataset dependency graph contains a cycle at "${id}".`);
+    if (visited.has(id)) return;
+    const dataset = byId.get(id);
+    if (dataset === undefined) throw new Error(`Dataset dependency graph references missing input "${id}".`);
+    visiting.add(id);
+    for (const input of datasetInputIds(dataset)) visit(input);
+    visiting.delete(id);
+    visited.add(id);
+    result.push(dataset);
+  }
+  visit(root);
+  return result;
+}
+
+// A stable topological extension of the historical primary-tree DFS order.
+// A binary input waits for both changed parents; an ordinary tree keeps its old order.
+export function orderedDatasetDependents(datasets, root, { skip = () => false } = {}) {
+  const byId = new Map(datasets.map(dataset => [dataset.id, dataset]));
+  if (byId.size !== datasets.length) throw new Error("Dataset dependency graph contains duplicate ids.");
+  if (!byId.has(root)) throw new Error(`Dataset dependency graph has no root "${root}".`);
+  const children = new Map();
+  for (const dataset of datasets) {
+    for (const input of datasetInputIds(dataset)) {
+      if (!byId.has(input)) throw new Error(`Dataset "${dataset.id}" references missing input "${input}".`);
+      const values = children.get(input) ?? [];
+      values.push(dataset);
+      children.set(input, values);
+    }
+  }
+  const rank = new Map(), visiting = new Set(), visited = new Set();
+  function visit(id) {
+    if (visiting.has(id)) throw new Error(`Dataset dependency graph contains a cycle at "${id}".`);
+    if (visited.has(id)) return;
+    visiting.add(id);
+    for (const dataset of children.get(id) ?? []) {
+      if (skip(dataset)) continue;
+      if (!rank.has(dataset.id)) rank.set(dataset.id, rank.size);
+      visit(dataset.id);
+    }
+    visiting.delete(id);
+    visited.add(id);
+  }
+  visit(root);
+  const remaining = new Map([...rank].map(([id]) => [id,
+    datasetInputIds(byId.get(id)).filter(parent => rank.has(parent)).length]));
+  const ready = [];
+  const less = (a, b) => rank.get(a) < rank.get(b);
+  function push(id) {
+    ready.push(id);
+    let index = ready.length - 1;
+    while (index > 0) {
+      const parent = Math.floor((index - 1) / 2);
+      if (!less(ready[index], ready[parent])) break;
+      [ready[index], ready[parent]] = [ready[parent], ready[index]];
+      index = parent;
+    }
+  }
+  function pop() {
+    const first = ready[0], last = ready.pop();
+    if (ready.length) {
+      ready[0] = last;
+      let index = 0;
+      for (;;) {
+        const left = index * 2 + 1, right = left + 1;
+        let next = index;
+        if (left < ready.length && less(ready[left], ready[next])) next = left;
+        if (right < ready.length && less(ready[right], ready[next])) next = right;
+        if (next === index) break;
+        [ready[index], ready[next]] = [ready[next], ready[index]];
+        index = next;
+      }
+    }
+    return first;
+  }
+  for (const [id, count] of remaining) if (count === 0) push(id);
+  const result = [];
+  while (ready.length) {
+    const id = pop();
+    result.push(byId.get(id));
+    for (const child of children.get(id) ?? []) {
+      if (!remaining.has(child.id)) continue;
+      const count = remaining.get(child.id) - 1;
+      remaining.set(child.id, count);
+      if (count === 0) push(child.id);
+    }
+  }
+  if (result.length !== rank.size) throw new Error("Dataset dependency graph contains a cycle.");
+  return result;
+}

package/src/grammar/datasetSchema.js

@@ -268,8 +268,33 @@ function generatedField(name, storageType, transform, role, inputs = []) {
   };
 }
 
-export function deriveTransformSchema(inputSchema, transform, values, { sourceId, ownerId, sourceTransform } = {}) {
+export function datasetSchemaContext(source,transform,ownerId,resolveInput) {
+  const context={sourceId:source.id,ownerId,sourceTransform:source.transform?.[0]};
+  if(transform.type==="lookup"){
+    const input=resolveInput(transform.lookup.data);
+    if(input?.schema===undefined)throw new Error(`Lookup dataset "${transform.lookup.data}" requires schema.`);
+    assertFieldsAvailable(source.schema,[transform.field],{data:source.id,operation:"Lookup"});
+    assertFieldsAvailable(input.schema,[transform.lookup.key,...transform.lookup.fields],{data:input.id,operation:"Lookup"});
+    context.lookupSchema=input.schema;context.lookupSourceId=input.id;
+  }
+  return context;
+}
+
+export function deriveTransformSchema(inputSchema, transform, values, { sourceId, ownerId, sourceTransform,lookupSchema,lookupSourceId } = {}) {
   const input = validateDatasetSchema(inputSchema);
+  if(transform.type==="lookup"){
+    const right=validateDatasetSchema(lookupSchema),fields=input.fields.map(field=>({...field}));
+    for(let i=0;i<transform.lookup.fields.length;i++){
+      const field=transform.lookup.fields[i],name=transform.lookup.as[i];
+      if(fields.some(f=>f.name===name))throw new Error(`Lookup output field "${name}" already exists in primary data.`);
+      const inherited=right.fields.find(f=>f.name===field);
+      const references=[{data:sourceId,field:transform.field},{data:lookupSourceId,field:transform.lookup.key},{data:lookupSourceId,field}];
+      fields.push({name,storageType:inherited?.storageType??"unknown",nullable:true,optional:false,lineage:{
+        inputs:[...new Map(references.map(r=>[JSON.stringify(r),r])).values()],owner:ownerId,role:`lookup:${field}`
+      }});
+    }
+    return cloneAndFreeze({version:1,completeness:input.completeness==="known"||fields.length>0?"known":"unknown",origin:"derived",fields});
+  }
   const definition = { ...transform, __sourceId: sourceId, __ownerId: ownerId };
   const retain = ["filter", "markFilter", "sort", "computed", "timeUnit", "window", "normalize", "stack", "impute", "complete"];
   let fields = retain.includes(transform.type) ? input.fields.map(field => ({ ...field })) : [];
@@ -354,6 +379,11 @@ export function deriveTransformSchema(inputSchema, transform, values, { sourceId
     for (const [role, name] of Object.entries(transform.as ?? {})) {
       push(generatedField(name, "number", definition, role, [transform.field]));
     }
+  } else if (transform.type === "flatten") {
+    fields = input.fields.map(field => ({ ...field }));
+    transform.fields.forEach((field, index) => {
+      push(generatedField(transform.as[index], "unknown", definition, `value:${field}`, [field]));
+    });
   } else if (transform.type === "fold") {
     fields = input.fields.filter(field => !transform.fields.includes(field.name)).map(field => ({ ...field }));
     push(generatedField(transform.as.key, "string", definition, "key", transform.fields));
@@ -374,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

@@ -0,0 +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","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/dependencies.js

@@ -227,9 +227,13 @@ function resolveAnchor(paths, datasets, classifications, requested) {
     if (!datasets.has(id)) {
       throw new Error(`Facet partition dataset "${id}" does not exist.`);
     }
-    if (!common.includes(id)) {
+    const explicitExpansion = ["fold", "flatten"].includes(
+      datasets.get(id).value.transform?.[0]?.type
+    ) &&
+      paths.every(path => path.includes(id));
+    if (!common.includes(id) && !explicitExpansion) {
       throw new Error(
-        `Facet partition dataset "${id}" is not a common row-preserving ancestor of every layer.`
+        `Facet partition dataset "${id}" is not a common row-preserving ancestor or materialized fold boundary or aligned-array boundary of every layer.`
       );
     }
     return id;

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/facets/legendIntent.js

@@ -1,17 +1,19 @@
 import { isPlainObject } from "../../core/immutable.js";
+import {validateLegendSpacing} from "../legendSpacing.js";
 import { validateOptionObject, validateNonEmptyString } from "../../core/validation.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { LEGEND_CONFIG_KINDS, LEGEND_POSITIONS } from "../../core/vocabulary.js";
 import { describeLegendBlock } from "../legendBlocks.js";
 import { validateLegendGroupState } from "../legendGroups.js";
 import { resolveSharedFacetLegends, sameFacetGuideValue as same } from "./guides.js";
+import { normalizeDisplayLabelMap } from "../displayLabels.js";
 
 const CONFIG_KEYS = Object.freeze([
   "kind", "target", "channels", "scales", "scale", "field", "fieldType", "domain", "title", "titleVisible",
   "inferredTitle", "inferredSymbol", "inferredStrokeWidth", "inferredOffset", "position", "align", "offset", "direction", "columns",
-  "titlePosition", "symbol", "labels", "titleStyle", "itemGap", "layout", "overflow", "border", "gradient",
+  "titlePosition", "symbol", "labels", "titleStyle", "itemGap", "rowPadding", "titlePadding", "layout", "overflow", "border", "gradient",
   "count", "sampling", "representation", "gradientDirection", "inheritAppearance", "inheritPosition", "blockOverrides",
-  "combine", "sizeAreas", "clipHeight"
+  "combine", "sizeAreas", "clipHeight", "defaultLabelMap"
 ]);
 
 export function isAuthoredFacetLegend(value) {
@@ -31,6 +33,8 @@ export function validateAuthoredFacetLegend(program, intent) {
     validateOptionObject(block, ["config", "guide"], "Stored parent legend block");
     validateOptionObject(block.config, kind === "colorSize" ? [...CONFIG_KEYS, "colorScale", "sizeScale"] : CONFIG_KEYS, "Stored parent legend config");
     const config = block.config;
+    validateLegendSpacing(kind,config);
+    if (config.defaultLabelMap !== undefined) normalizeDisplayLabelMap(config.defaultLabelMap, "Stored inferred legend labels");
     validateUserId(config.target, "Parent legend target");
     if (!LEGEND_POSITIONS.includes(config.position)) throw new Error("Stored parent legend requires a native position.");
     for (const flag of ["inferredTitle", "inferredSymbol", "inferredStrokeWidth", "inferredOffset", "titleVisible", "inheritAppearance", "inheritPosition"]) {

package/src/grammar/facets/scales.js

@@ -89,17 +89,37 @@ export function normalizeFacetScalePolicies(semanticSpec, requested = {}) {
       );
     }
   }
+  const inferred = { ...requested };
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [id, channelSet] of used) {
+      const attached = [...channelSet];
+      const policies = [...new Set(attached
+        .filter(channel => inferred[channel] !== undefined)
+        .map(channel => inferred[channel]))];
+      if (policies.length > 1) {
+        throw new Error(
+          `Facet scale "${id}" has conflicting channel policies for ${attached.join(", ")}.`
+        );
+      }
+      if (policies.length === 1) for (const channel of attached) {
+        if (inferred[channel] === undefined) {
+          inferred[channel] = policies[0];
+          changed = true;
+        }
+      }
+    }
+  }
+  Object.assign(channels, inferred);
   const scalePolicies = {};
   for (const [id, channelSet] of used) {
     const attached = [...channelSet];
-    const policies = [...new Set(attached.map(channel => channels[channel]))];
-    if (policies.length !== 1) {
-      throw new Error(
-        `Facet scale "${id}" has conflicting channel policies for ${attached.join(", ")}.`
-      );
-    }
+    // One semantic scale cannot have different resolutions through its aliases.
+    // An explicitly chosen channel policy also owns omitted aliases; only
+    // contradictory explicit requests are ambiguous.
     scalePolicies[id] = {
-      policy: policies[0],
+      policy: channels[attached[0]],
       channels: attached
     };
   }

package/src/grammar/flatten.js

@@ -0,0 +1,85 @@
+import { rejectUnknownProperties, requireStringValue } from "../core/validation.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+
+const KEYS = Object.freeze(["type", "fields", "as"]);
+const MAX_FIELDS = 64;
+const MAX_OUTPUT_ROWS = 10_000;
+
+export function normalizeFlattenTransform({ fields, as } = {}) {
+  const aliases = as === undefined ? fields : as;
+  const transform = {
+    type: "flatten",
+    fields: Array.isArray(fields) ? [...fields] : fields,
+    as: Array.isArray(aliases) ? [...aliases] : aliases
+  };
+  validateFlattenTransform(transform);
+  return cloneAndFreeze(transform);
+}
+
+export function validateFlattenTransform(transform) {
+  if (!isPlainObject(transform)) {
+    throw new TypeError("Flatten transform must be a plain object.");
+  }
+  rejectUnknownProperties(transform, KEYS, "flatten transform");
+  if (transform.type !== "flatten") {
+    throw new Error(`Unsupported flatten transform "${transform.type}".`);
+  }
+  if (!Array.isArray(transform.fields) || transform.fields.length === 0) {
+    throw new TypeError("Flatten fields must be a non-empty array.");
+  }
+  if (transform.fields.length > MAX_FIELDS) {
+    throw new RangeError(`Flatten fields cannot contain more than ${MAX_FIELDS} entries.`);
+  }
+  if (!Array.isArray(transform.as) || transform.as.length !== transform.fields.length) {
+    throw new TypeError("Flatten as must be an array with one alias per field.");
+  }
+  for (const key of ["fields", "as"]) {
+    for (const [index, field] of transform[key].entries()) {
+      requireStringValue(field, `Flatten ${key}[${index}]`);
+    }
+    if (new Set(transform[key]).size !== transform[key].length) {
+      throw new Error(`Flatten ${key} must be unique.`);
+    }
+  }
+  return transform;
+}
+
+export function deriveFlattenRows(rows, transform) {
+  validateFlattenTransform(transform);
+  const selected = new Set(transform.fields);
+  const existing = new Set(rows.flatMap(row => Object.keys(row)));
+  for (const name of transform.as) {
+    if (existing.has(name) && !selected.has(name)) {
+      throw new Error(`Flatten output field "${name}" already exists outside the selected fields.`);
+    }
+  }
+  let total = 0;
+  const lengths = rows.map((row, rowIndex) => {
+    let length = 0;
+    for (const field of transform.fields) {
+      const value = row[field];
+      if (value === undefined || value === null) continue;
+      if (!Array.isArray(value)) {
+        throw new TypeError(`Flatten field "${field}" must be an array at row ${rowIndex}.`);
+      }
+      length = Math.max(length, value.length);
+    }
+    total += length;
+    if (total > MAX_OUTPUT_ROWS) {
+      throw new RangeError(`Flatten output cannot exceed ${MAX_OUTPUT_ROWS} rows.`);
+    }
+    return length;
+  });
+  const output = [];
+  rows.forEach((row, rowIndex) => {
+    for (let index = 0; index < lengths[rowIndex]; index += 1) {
+      const next = { ...row };
+      transform.fields.forEach((field, fieldIndex) => {
+        const values = row[field];
+        next[transform.as[fieldIndex]] = values?.[index] ?? null;
+      });
+      output.push(next);
+    }
+  });
+  return output;
+}

package/src/grammar/histogram.js

@@ -1,5 +1,6 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { MAX_GENERATED_ITEMS } from "../core/validation.js";
+import { niceLinearCountDomain, normalizeScaleNice } from "./scales/continuous.js";
 import {
   alignNumericStep,
   cleanNumericValue,
@@ -299,7 +300,18 @@ function niceBins(extent, maxBins) {
   return equalBins(extent, maxBins);
 }
 
-export function resolveHistogramBins({
+export function resolveHistogramBins(options) {
+  if (isPlainObject(options.nice)) {
+    const { count } = normalizeScaleNice("linear", options.nice);
+    const bins = resolveBooleanHistogramBins({ ...options, nice: true });
+    return options.domain === undefined || options.domain === "auto"
+      ? cloneAndFreeze({ ...bins, domain: niceLinearCountDomain(bins.domain, count) })
+      : bins;
+  }
+  return resolveBooleanHistogramBins(options);
+}
+
+function resolveBooleanHistogramBins({
   values,
   bin,
   maxBins,