ggaction 0.0.24 → 0.0.26

package/src/actions/charts/endpoints.js

@@ -1,3 +1,4 @@
+import { prepareFacadeMissingData } from './missing.js';
 import { validateUserId } from "../../core/identifiers.js";
 import { action } from "../../core/action.js";
 import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
@@ -14,6 +15,7 @@ import { findDataset } from "../../selectors/datasets.js";
 import { findSemanticScale } from "../../selectors/scales.js";
 import {
   applyFacadeGuides,
+  retainFacadeAxisPresence,
   normalizeAppearance,
   normalizeFieldEncoding,
   normalizeGuides,
@@ -24,7 +26,7 @@ import {
 } from "./shared.js";
 
 const COMMON_OPTIONS = Object.freeze([
-  "id", "data", "coordinate", "category", "orientation", "summary", "guides", "labels"
+  "id", "data", "coordinate", "category", "orientation", "summary", "guides", "labels", "missing"
 ]);
 const DOT_OPTIONS = Object.freeze([...COMMON_OPTIONS, "value", "point"]);
 const LOLLIPOP_OPTIONS = Object.freeze([...DOT_OPTIONS, "baseline", "stem"]);
@@ -48,7 +50,7 @@ const LABEL_OPTIONS = Object.freeze([
 const SUMMARY_OPERATIONS = Object.freeze(["mean", "median", "sum", "min", "max"]);
 const EDIT_OPTIONS = Object.freeze([
   "target", "data", "coordinate", "category", "value", "start", "end",
-  "orientation", "summary", "baseline"
+  "orientation", "summary", "baseline", "missing"
 ]);
 
 function normalizeCategory(value, operation) {
@@ -124,9 +126,12 @@ function outputField(id, role) {
   return `__${id}_${role}`;
 }
 
-function prepareData(program, { id, data, category, measures, summary, operation }) {
+function prepareData(program, { id, data, category, measures, summary, operation, missing }) {
+  const prepared = prepareFacadeMissingData(program, { id, source: data,
+    fields: [category.field, ...measures.map(item => item.field)], missing });
+  program = prepared.program; data = prepared.data;
   validateRows(program, data, category.field, measures.map(item => item.field), operation);
-  if (summary === false) return { program, data, measures };
+  if (summary === false) return { program, data, measures, ownedData: prepared.ownedData };
   const derived = `${id}SummaryData`;
   const outputs = measures.map((item, index) => ({
     ...item,
@@ -144,6 +149,7 @@ function prepareData(program, { id, data, category, measures, summary, operation
       }))
     }),
     data: derived,
+    ownedData: prepared.ownedData,
     measures: outputs
   };
 }
@@ -249,10 +255,10 @@ function attachLabels(program, id, labels, defaultField) {
   });
 }
 
-function finish(program, { id, source, data, kind, roles, summary, orientation, options }) {
+function finish(program, { id, source, data, kind, roles, summary, orientation, options, ownedData }) {
   return program._withMarkConfig(id, {
     ...program.markConfigs[id],
-    endpointPlot: { kind, source, data, roles, summary, orientation, options }
+    endpointPlot: { kind, source, data, roles, summary, orientation, options, ownedData }
   });
 }
 
@@ -271,7 +277,7 @@ export const createDotPlot = /* @__PURE__ */ action(
     const guides = normalizeGuides(args.guides, operation);
     const labels = normalizeLabels(args.labels, operation, false);
     const prepared = prepareData(this, {
-      id, data: source, category, measures: [{ ...value, role: "value" }], summary, operation
+      id, data: source, category, measures: [{ ...value, role: "value" }], summary, operation, missing: args.missing
     });
     const finalValue = prepared.measures[0];
     const bindings = positionBindings(id, category, finalValue, orientation, args.coordinate);
@@ -280,7 +286,8 @@ export const createDotPlot = /* @__PURE__ */ action(
     next = applyFacadeGuides(next, guides, id, guides);
     return finish(next, {
       id, source, data: prepared.data, kind: "dot", roles: { category, value }, summary, orientation,
-      options: { id, data: source, coordinate: args.coordinate, category, value, orientation,
+      ownedData: prepared.ownedData,
+      options: { id, data: source, missing: args.missing, coordinate: args.coordinate, category, value, orientation,
         summary, point, guides, labels }
     });
   }
@@ -304,7 +311,7 @@ export const createLollipopPlot = /* @__PURE__ */ action(
     const guides = normalizeGuides(args.guides, operation);
     const labels = normalizeLabels(args.labels, operation, false);
     const prepared = prepareData(this, {
-      id, data: source, category, measures: [{ ...value, role: "value" }], summary, operation
+      id, data: source, category, measures: [{ ...value, role: "value" }], summary, operation, missing: args.missing
     });
     const finalValue = prepared.measures[0];
     const bindings = positionBindings(id, category, finalValue, orientation, args.coordinate);
@@ -323,7 +330,8 @@ export const createLollipopPlot = /* @__PURE__ */ action(
     return finish(next, {
       id, source, data: prepared.data, kind: "lollipop",
       roles: { category, value, baseline, stemId }, summary, orientation,
-      options: { id, data: source, coordinate: args.coordinate, category, value, orientation,
+      ownedData: prepared.ownedData,
+      options: { id, data: source, missing: args.missing, coordinate: args.coordinate, category, value, orientation,
         summary, baseline, point, stem, guides, labels }
     });
   }
@@ -358,7 +366,7 @@ export const createDumbbellPlot = /* @__PURE__ */ action(
         { ...start, scale: sharedScale, role: "start" },
         { ...end, scale: sharedScale, role: "end" }
       ],
-      summary, operation
+      summary, operation, missing: args.missing
     });
     const [finalStart, finalEnd] = prepared.measures;
     const startBindings = positionBindings(id, category, finalStart, orientation, args.coordinate);
@@ -396,7 +404,8 @@ export const createDumbbellPlot = /* @__PURE__ */ action(
     return finish(next, {
       id, source, data: prepared.data, kind: "dumbbell",
       roles: { category, start, end, startId, connectorId }, summary, orientation,
-      options: { id, data: source, coordinate: args.coordinate, category, start, end, orientation,
+      ownedData: prepared.ownedData,
+      options: { id, data: source, missing: args.missing, coordinate: args.coordinate, category, start, end, orientation,
         summary, startPoint, endPoint, connector, guides, labels }
     });
   }
@@ -410,12 +419,12 @@ const KIND_METHOD = Object.freeze({
   dumbbell: "createDumbbellPlot"
 });
 const KIND_ROLES = Object.freeze({
-  dot: new Set(["data", "coordinate", "category", "value", "orientation", "summary"]),
+  dot: new Set(["data", "coordinate", "category", "value", "orientation", "summary", "missing"]),
   lollipop: new Set([
-    "data", "coordinate", "category", "value", "orientation", "summary", "baseline"
+    "data", "coordinate", "category", "value", "orientation", "summary", "baseline", "missing"
   ]),
   dumbbell: new Set([
-    "data", "coordinate", "category", "start", "end", "orientation", "summary"
+    "data", "coordinate", "category", "start", "end", "orientation", "summary", "missing"
   ])
 });
 
@@ -494,7 +503,7 @@ export const editEndpointPlot = /* @__PURE__ */ action(
     if (invalid !== undefined) {
       throw new Error(`editEndpointPlot ${invalid} is not available for ${current.kind} plots.`);
     }
-    const revised = { ...current.options };
+    const revised = { ...current.options, guides: retainFacadeAxisPresence(this, owner, current.options.guides) };
     for (const key of changes) revised[key] = args[key];
     const axes = { fromAxis: current.orientation === "vertical" ? "y" : "x",
       toAxis: revised.orientation === "vertical" ? "y" : "x" };

package/src/actions/charts/heatmap.js

@@ -1,3 +1,4 @@
+import { findSemanticScale } from "../../selectors/scales.js";
 import { action } from "../../core/action.js";
 import { isPlainObject } from "../../core/immutable.js";
 import {
@@ -71,7 +72,8 @@ function normalizeBinnedColor(value) {
   return { ...value };
 }
 
-function resolvedPosition(encoding, field, extent) {
+function resolvedPosition(encoding, field, extent, program) {
+  if (encoding.scale?.id && findSemanticScale(program, encoding.scale.id)) return {field,fieldType:"quantitative",scale:encoding.scale};
   const scale = encoding.scale ?? {};
   return {
     field,
@@ -178,8 +180,8 @@ export const createHeatmap = /* @__PURE__ */ action(
     });
     const transform = requireDataset(binned, generatedData).transform[0];
     const resolved = transform.resolved;
-    const xEncoding = resolvedPosition(x, transform.as.x0, resolved.extent.x);
-    const yEncoding = resolvedPosition(y, transform.as.y0, resolved.extent.y);
+    const xEncoding = resolvedPosition(x, transform.as.x0, resolved.extent.x, this);
+    const yEncoding = resolvedPosition(y, transform.as.y0, resolved.extent.y, this);
     const next = binned
       .createRectMark({ id, data: generatedData, ...rect })
       .encodeX(positionArgs(xEncoding, { target: id, coordinate: args.coordinate }))

package/src/actions/charts/missing.js

@@ -0,0 +1,17 @@
+import { validateItemMissing } from '../../grammar/itemMissing.js';
+
+// Complete-case source ownership for composite statistical charts. Keep the
+// original source in the facade config; every child consumes this same view.
+// Native filters preserve schemas, dependencies, trace and rematerialization.
+export function prepareFacadeMissingData(program, { id, source, fields, missing }) {
+  const policy = validateItemMissing(missing ?? 'error', 'Chart missing');
+  if (policy === 'error') return { program, data: source, ownedData: [] };
+  let next = program, data = source;
+  const ownedData = [];
+  for (const [index, field] of [...new Set(fields.filter(Boolean))].entries()) {
+    const target = `${id}CompleteCases${index + 1}`;
+    next = next.filterData({ id: target, source: data, field, noneOf: [null], nulls: 'exclude' });
+    data = target; ownedData.unshift(target);
+  }
+  return { program: next, data, ownedData };
+}

package/src/actions/charts/radar.js

@@ -10,7 +10,6 @@ import { findDataset } from "../../selectors/datasets.js";
 import { resolveEligibleLayer } from "../../selectors/layers.js";
 import { planDerivedDataRevision } from "../../materialization/dataProvenance.js";
 import { applyLayerDataRematerialization } from "../../materialization/dependencies.js";
-import { deriveFoldRows, normalizeFoldTransform } from "../../grammar/fold.js";
 import {
   normalizeAppearance,
   normalizeEncoding,
@@ -33,7 +32,7 @@ const CATEGORY_SCALE_OPTIONS = Object.freeze([
   "id", "type", "domain", "range", "reverse", "paddingInner", "paddingOuter",
   "padding", "align"
 ]);
-const WIDE_OPTIONS = Object.freeze(["fields", "as"]);
+const WIDE_OPTIONS = Object.freeze(["fields", "as", "summary", "normalize"]);
 const WIDE_AS_OPTIONS = Object.freeze(["key", "value"]);
 const LINE_OPTIONS = Object.freeze([
   "strokeWidth", "curve", "stroke", "opacity", "closed",
@@ -105,7 +104,15 @@ function normalizeWide(value, id, operation, minimum = 3) {
   if (key === foldedValue || fields.includes(key) || fields.includes(foldedValue)) {
     throw new Error(`${operation} wide aliases must be distinct from selected fields.`);
   }
-  return { fields, as: { key, value: foldedValue } };
+  const summary = value.summary ?? false;
+  const normalize = value.normalize ?? false;
+  if (![false, "mean", "median"].includes(summary)) {
+    throw new TypeError(`${operation} wide.summary must be false, mean, or median.`);
+  }
+  if (![false, "minmax"].includes(normalize)) {
+    throw new TypeError(`${operation} wide.normalize must be false or minmax.`);
+  }
+  return { fields, as: { key, value: foldedValue }, summary, normalize };
 }
 
 function orderedCategories(rows, field, requested, operation) {
@@ -189,6 +196,33 @@ function scaleWithOrder(category, order, operation) {
   return { ...category, scale: { ...scale, domain: order } };
 }
 
+// Keep summaries and normalization in the public data grammar. Original values
+// remain available, and each derived dataset has ordinary trace/provenance.
+function prepareWideData(program, { source, wide, groupBy, color, strokeDash, data, operation }) {
+  let next = program, input = source;
+  const ownedData = [];
+  if (wide.summary) {
+    input = `${data}Summary`;
+    const groups = [...new Set([...groupBy, color?.field, strokeDash?.field].filter(Boolean))];
+    next = next.createSummaryData({ id: input, source,
+      ...(groups.length ? { groupBy: groups } : {}),
+      aggregates: wide.fields.filter(field => !groups.includes(field)).map(field => ({ op: wide.summary, field, as: field })), missing: "error" });
+    ownedData.push(input);
+  }
+  const folded = wide.normalize ? `${data}Fold` : data;
+  next = next.createFoldData({ id: folded, source: input, fields: wide.fields, as: wide.as });
+  ownedData.push(folded);
+  const value = wide.normalize ? `${wide.as.value}Normalized` : wide.as.value;
+  if (wide.normalize) {
+    next = next.createNormalizedData({ id: data, source: folded, field: wide.as.value,
+      as: value, groupBy: wide.as.key, method: "minmax", zeroDenominator: "zero" });
+    ownedData.push(data);
+  }
+  validateRadarRows(findDataset(next, data).values, { category: wide.as.key,
+    value, groupBy, order: wide.fields }, operation);
+  return { next, data, value, ownedData };
+}
+
 export const createRadarPlot = /* @__PURE__ */ action(
   {
     op: "createRadarPlot",
@@ -240,6 +274,7 @@ export const createRadarPlot = /* @__PURE__ */ action(
     let category;
     let radarValue;
     let order;
+    let radarPlot;
     if (longForm) {
       category = normalizeCategory(args.category, operation);
       radarValue = normalizeValue(args.value, operation);
@@ -252,7 +287,7 @@ export const createRadarPlot = /* @__PURE__ */ action(
       }, operation);
     } else {
       const wide = normalizeWide(args.wide, id, operation);
-      if (sourceRows.length > 1 && groupBy.length === 0) {
+      if (sourceRows.length > 1 && groupBy.length === 0 && !wide.summary) {
         throw new Error(`${operation} wide rows require groupBy as series identity.`);
       }
       for (const field of wide.fields) readQuantitativeField(sourceRows, field);
@@ -271,21 +306,14 @@ export const createRadarPlot = /* @__PURE__ */ action(
         );
       }
       data = `${id}FoldData`;
-      next = next.createFoldData({
-        id: data,
-        source,
-        fields: wide.fields,
-        as: wide.as
-      });
-      const foldedRows = findDataset(next, data).values;
+      const prepared = prepareWideData(next, { source, wide, groupBy: seriesFields,
+        color, strokeDash, data, operation });
+      next = prepared.next;
       category = { field: wide.as.key, fieldType: "nominal" };
-      radarValue = { field: wide.as.value, fieldType: "quantitative" };
-      validateRadarRows(foldedRows, {
-        category: category.field,
-        value: radarValue.field,
-        groupBy: seriesFields,
-        order
-      }, operation);
+      radarValue = { field: prepared.value, fieldType: "quantitative",
+        ...(wide.normalize ? { scale: { domain: [0, 1], nice: false } } : {}) };
+      radarPlot = { source, wide, ownedData: prepared.ownedData };
+
     }
 
     category = scaleWithOrder(category, order, operation);
@@ -303,7 +331,8 @@ export const createRadarPlot = /* @__PURE__ */ action(
     });
     return next._withMarkConfig(id, {
       ...next.markConfigs[id],
-      compositionRole: "radar"
+      compositionRole: "radar",
+      ...(radarPlot ? { radarPlot } : {})
     });
   }
 );
@@ -316,30 +345,34 @@ export const editRadarPlot = /* @__PURE__ */ action(
   function (args = {}) {
     const operation = "editRadarPlot";
     validateFacadeOptions(args, ["target", "wide"], operation);
-    validateOptionObject(args.wide, ["fields"], `${operation} wide`);
+    validateOptionObject(args.wide, ["fields", "summary", "normalize"], `${operation} wide`);
     const owner = resolveEligibleLayer(this, {
       target: args.target,
       label: "wide Radar plot",
       predicate: layer => this.markConfigs[layer.id]?.compositionRole === "radar" &&
-        findDataset(this, layer.data)?.transform?.[0]?.type === "fold"
+        (this.markConfigs[layer.id]?.radarPlot !== undefined ||
+          findDataset(this, layer.data)?.transform?.[0]?.type === "fold")
     });
     const previous = findDataset(this, owner.data);
-    const prior = previous.transform[0];
-    const source = findDataset(this, previous.source);
-    const wide = normalizeWide({ ...args.wide, as: prior.as }, owner.id, operation, 2);
+    const stored = this.markConfigs[owner.id].radarPlot;
+    const prior = stored?.wide ?? previous.transform[0];
+    const source = findDataset(this, stored?.source ?? previous.source);
+    const wide = normalizeWide({ summary: prior.summary, normalize: prior.normalize, ...args.wide, as: prior.as,
+      fields: args.wide.fields }, owner.id, operation, 2);
     for (const field of wide.fields) readQuantitativeField(source.values, field);
-    const transform = normalizeFoldTransform(wide, previous.id);
-    const rows = deriveFoldRows(source.values, transform);
     const group = owner.encoding.group;
     const groupBy = group?.fields ?? (group?.field ? [group.field] : []);
-    validateRadarRows(rows, { category: prior.as.key, value: prior.as.value,
-      groupBy, order: wide.fields }, operation);
     const revision = planDerivedDataRevision(this, {
       owner: owner.id, role: "RadarData", previous: previous.id, consumers: [owner.id]
     });
-    let next = this.createFoldData({
-      id: revision.id, source: source.id, fields: wide.fields, as: prior.as
-    }).rebindLayerData(revision.rebinds[0]);
+    const prepared = prepareWideData(this, { source: source.id, wide, groupBy,
+      color: owner.encoding.color, strokeDash: owner.encoding.strokeDash,
+      data: revision.id, operation });
+    let next = prepared.next.rebindLayerData(revision.rebinds[0]);
+    if (Boolean(prior.normalize) !== Boolean(wide.normalize)) {
+      next = next.encodeR({ target: owner.id, field: prepared.value,
+        fieldType: "quantitative", scale: { domain: wide.normalize ? [0, 1] : "auto", nice: false } });
+    }
     const theta = owner.encoding.theta.scale;
     const revisedValues = config => {
       const full = config.inferredValues || !Array.isArray(config.values) ||
@@ -359,7 +392,11 @@ export const editRadarPlot = /* @__PURE__ */ action(
     next = next.editThetaScale({ target: owner.id, domain: wide.fields });
     next = applyLayerDataRematerialization(next, owner.id);
     if (next.markConfigs[owner.id]?.closed !== true) next = next.editLineMark({ target: owner.id, closed: true });
-    return next.releaseDerivedData(revision.release)
-      ._withContext({ currentMark: owner.id, currentData: source.id });
+    next = next._withMarkConfig(owner.id, { ...next.markConfigs[owner.id],
+      radarPlot: { source: source.id, wide, ownedData: prepared.ownedData } });
+    for (const id of [...(stored?.ownedData ?? [previous.id])].reverse()) {
+      next = next.releaseDerivedData({ id });
+    }
+    return next._withContext({ currentMark: owner.id, currentData: source.id });
   }
 );

package/src/actions/charts/raincloud.js

@@ -1,3 +1,4 @@
+import { prepareFacadeMissingData } from './missing.js';
 import { action } from "../../core/action.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
@@ -5,6 +6,7 @@ import { validateOptionObject } from "../../core/validation.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { resolveColorScaleDefinition } from "../scales/definitions.js";
 import { retainStatisticalDependents, restoreStatisticalDependents } from "../marks/dependentReferences.js";
 import { resolveViolinRoles } from "../violinPlots/create.js";
 import {
@@ -18,11 +20,11 @@ import {
 
 const CREATE_OPTIONS = Object.freeze([
   "id", "data", "coordinate", "category", "value", "orientation", "side",
-  "density", "summary", "points", "color", "guides"
+  "density", "summary", "points", "color", "guides", "missing"
 ]);
 const EDIT_OPTIONS = Object.freeze([
   "target", "data", "category", "value", "orientation", "side", "density",
-  "summary", "points", "color"
+  "summary", "points", "color", "missing"
 ]);
 const DENSITY_OPTIONS = Object.freeze([
   "bandwidth", "extent", "steps", "kernel", "normalization", "width", "area"
@@ -275,6 +277,12 @@ function addPoints(program, config, positions) {
 }
 
 function buildRaincloud(program, config) {
+  const original = config;
+  const prepared = prepareFacadeMissingData(program, { id: config.id, source: config.source,
+    fields: [config.category.field, config.value.field, config.color?.field,
+      config.points?.size?.field, config.points?.shape?.field], missing: config.missing });
+  program = prepared.program;
+  config = { ...config, source: prepared.data };
   const positions = rolePositions(config.category, config.value, config.orientation);
   let next = program;
   if (config.density !== false) {
@@ -308,7 +316,7 @@ function buildRaincloud(program, config) {
     .filter(id => findLayer(next, id) !== undefined);
   return next._withMarkConfig(ownerId, {
     ...next.markConfigs[ownerId],
-    raincloudPlot: { ...config, ownerId, ownedChildIds, materialized: true }
+    raincloudPlot: { ...original, ownedData: prepared.ownedData, ownerId, ownedChildIds, materialized: true }
   })._withContext({ currentMark: ownerId, currentData: config.source });
 }
 
@@ -317,7 +325,11 @@ function alignExistingRoleScales(program, config) {
   for (const encoding of [config.category, config.value, config.color]) {
     const scale = encoding?.scale;
     if (!isPlainObject(scale) || findSemanticScale(next, scale.id) === undefined) continue;
-    const patch = Object.fromEntries(Object.entries(scale).filter(
+    // Rebuilding removes the owned consumers first. Normalize the known color
+    // role before editing its retained resource, so palette does not depend on
+    // a temporarily absent consumer to infer that role.
+    const definition = encoding === config.color ? resolveColorScaleDefinition(next, scale) : scale;
+    const patch = Object.fromEntries(Object.entries(definition).filter(
       ([property, value]) => property !== "id" && value !== undefined
     ));
     if (Object.keys(patch).length > 0) next = next.editScale({ id: scale.id, ...patch });
@@ -358,6 +370,7 @@ function normalizeCreate(program, args, operation) {
   return {
     id,
     source,
+    missing: args.missing ?? "error",
     ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
     category,
     value,
@@ -419,6 +432,7 @@ export const editRaincloudPlot = /* @__PURE__ */ action(
     const candidateArgs = {
       id: current.id,
       data: Object.hasOwn(args, "data") ? args.data : current.source,
+      missing: args.missing ?? current.missing,
       ...(current.coordinate === undefined ? {} : { coordinate: current.coordinate }),
       category,
       value: Object.hasOwn(args, "value") ? args.value : current.value,

package/src/actions/charts/rug-strip.js

@@ -24,7 +24,7 @@ const TICK_OPTIONS = Object.freeze([
   "clip", "length", "stroke", "strokeWidth", "opacity", ...STROKE_STYLE_PROPERTIES
 ]);
 const STRIP_OPTIONS = Object.freeze([
-  "id", "data", "coordinate", "x", "y", "color", "size", "shape", "point", "jitter", "guides"
+  "id", "data", "coordinate", "x", "y", "color", "size", "shape", "point", "jitter", "guides", "missing"
 ]);
 const POINT_OPTIONS = Object.freeze([
   "clip",   "radius", "shape", "fill", "opacity", "stroke", "strokeWidth",
@@ -260,7 +260,7 @@ export const createStripPlot = /* @__PURE__ */ action(
       operation
     );
 
-    let next = this.createPointMark({ id, data, ...point });
+    let next = this.createPointMark({ id, data, ...point, ...(args.missing === undefined ? {} : { missing: args.missing }) });
     if (args.coordinate !== undefined) {
       next = next.createCoordinate({ id: args.coordinate, type: "cartesian", layers: [id] });
     }

package/src/actions/charts/shared.js

@@ -173,6 +173,23 @@ export function applyFacadeGuides(program, guides, target, explicitGuides = guid
   return fulfillFacadeGuides(program, guides, target, explicitGuides);
 }
 
+// Rebuilding a facade must not resurrect an axis removed after construction.
+// This also lets callers fit a changed variable by removing its old axis and
+// recreating it against the new domain through ordinary public guide actions.
+export function retainFacadeAxisPresence(program, owner, guides) {
+  if (guides === false) return false;
+  const axes = { ...guides?.axes };
+  for (const channel of ['x', 'y']) {
+    if (!owner.encoding[channel]?.scale) continue;
+    const present = Object.entries(program.semanticSpec.guides.axis ?? {}).some(([id, axis]) =>
+      (axis.channel ?? id) === channel && axis.scale === owner.encoding[channel].scale &&
+      (axis.coordinate ?? owner.coordinate) === owner.coordinate);
+    if (!present) axes[channel] = false;
+    else axes[channel] ??= {};
+  }
+  return { ...guides, axes };
+}
+
 export function normalizeArcCategory(value, operation) {
   const label = `${operation} category`;
   const category = normalizeFieldEncoding(value, label);

package/src/actions/composition/actions.js

@@ -1,3 +1,5 @@
+import { normalizeCompositionLegends } from "../../core/compositionState.js";
+import { normalizeCompositionShares } from "../../core/compositionScales.js";
 import { resolveGraphicBounds } from "../../layout/canvas.js";
 import { inheritTextMetrics } from "../textMetrics/index.js";
 import { action, closedAction } from "../../core/action.js";
@@ -17,10 +19,10 @@ import { materializeFacetGraphics } from "../../materialization/facets.js";
 import { replayInheritedThemeFrames } from "../theme/composition.js";
 
 const CONCAT_OPTIONS = Object.freeze([
-  "id", "programs", "gap", "align", "padding"
+  "id", "programs", "gap", "align", "padding", "share", "legends"
 ]);
 const LAYOUT_EDIT_OPTIONS = Object.freeze([
-  "columns", "gap", "spacing", "topLane", "align", "padding"
+  "columns", "gap", "spacing", "topLane", "align", "padding", "legends"
 ]);
 const REPLACEMENT_OPTIONS = Object.freeze(["target", "program"]);
 const INSERTION_OPTIONS = Object.freeze(["id", "program", "before", "after"]);
@@ -94,7 +96,7 @@ function normalizeCompositionInput(args, direction) {
     direction,
     children: entries.map(childDescriptor),
     ...(Object.hasOwn(args, "gap") ? { gap: args.gap } : {}),
-    ...(Object.hasOwn(args, "align") ? { align: args.align } : {}),
+    ...(Object.hasOwn(args, "align") ? { align: args.align === "plot" ? "start" : args.align } : {}),
     ...(Object.hasOwn(args, "padding") ? { padding: args.padding } : {})
   });
   return {
@@ -106,8 +108,10 @@ function normalizeCompositionInput(args, direction) {
       direction,
       children: ids,
       gap: layout.gap,
-      align: layout.align,
-      padding: layout.padding
+      align: args.align === "plot" ? "plot" : layout.align,
+      padding: layout.padding,
+      ...(Object.hasOwn(args, "legends") ? { legends: normalizeCompositionLegends(args.legends) } : {}),
+      ...(args.share === undefined ? {} : { share: normalizeCompositionShares(args.share) })
     }
   };
 }
@@ -175,6 +179,7 @@ const editCompositionLayout = /* @__PURE__ */ closedAction(
       throw new TypeError("editCompositionLayout requires at least one layout option.");
     }
     const current = this.compositionSpec;
+    if (Object.hasOwn(args, "legends") && current.type === "facet") throw new Error("Facet uses editFacetGuides for legend placement.");
     if (current.type !== "facet" && Object.hasOwn(args, "columns")) {
       throw new Error(
         "editCompositionLayout columns is available only on a facet composition."
@@ -218,7 +223,7 @@ const editCompositionLayout = /* @__PURE__ */ closedAction(
           program: this.children[id]
         })),
         gap: option(args, "gap", current.gap),
-        align: option(args, "align", current.align),
+        align: option(args, "align", current.align) === "plot" ? "start" : option(args, "align", current.align),
         padding
       });
     }
@@ -227,11 +232,12 @@ const editCompositionLayout = /* @__PURE__ */ closedAction(
       children: this.children,
       compositionSpec: {
         ...currentLayoutSpec,
+        ...(Object.hasOwn(args, "legends") ? { legends: normalizeCompositionLegends(args.legends) } : {}),
         ...(current.type === "facet" ? { columns: layout.columns,
           ...(layout.spacing !== undefined ? { spacing: layout.spacing } : current.spacing !== undefined ? { spacing: "canvas" } : {}),
           ...(layout.topLane === undefined ? {} : { topLane: layout.topLane }) } : {}),
         gap: layout.gap,
-        align: layout.align,
+        align: current.type !== "facet" && option(args, "align", current.align) === "plot" ? "plot" : layout.align,
         padding: layout.padding
       }
     });
@@ -376,7 +382,18 @@ const reorderCompositionChildren = /* @__PURE__ */ closedAction(
   }
 );
 
+const editCompositionScales = /* @__PURE__ */ closedAction({
+  op: "editCompositionScales", description: "Edit shared scale policies across adjacent chart views.", scope: "composition"
+}, ["share"], function ({ share } = {}) {
+  requireConcat(this, "editCompositionScales");
+  if (share === undefined || !Object.keys(share).length) throw new Error("editCompositionScales requires a nonempty share edit.");
+  const patch = normalizeCompositionShares(share);
+  return applyCompositionState(this, { children: this.children,
+    compositionSpec: { ...this.compositionSpec, share: { ...this.compositionSpec.share, ...patch } } });
+});
+
 export function registerCompositionActions(ProgramClass) {
+  ProgramClass.prototype.editCompositionScales = editCompositionScales;
   ProgramClass.prototype.useProgram = useProgram;
   ProgramClass.prototype.materializeComposition = materializeComposition;
   ProgramClass.prototype.editCompositionLayout = editCompositionLayout;