ggaction 0.0.17 → 0.0.19

package/src/actions/facets/actions.js

@@ -1,3 +1,4 @@
+import { resolveGraphicBounds } from "../../layout/canvas.js";
 import { action, closedAction } from "../../core/action.js";
 import { registerFacetDataRevision, reviseUnitData } from "../data/revise.js";
 import { freezeOwned, isPlainObject } from "../../core/immutable.js";
@@ -38,16 +39,16 @@ import {
 } from "../../materialization/facetHeaders.js";
 
 const FACET_OPTIONS = Object.freeze([
-  "id", "field", "data", "values", "columns", "gap", "align", "padding", "scales",
-  "guides"
+  "id", "field", "data", "values", "columns", "gap", "spacing", "align", "padding", "scales",
+  "guides", "headers"
 ]);
 const FACET_GRID_OPTIONS = Object.freeze([
-  "id", "data", "rows", "columns", "combinations", "gap", "align",
-  "padding", "scales", "guides"
+  "id", "data", "rows", "columns", "combinations", "gap", "spacing", "align",
+  "padding", "scales", "guides", "headers"
 ]);
 const REPEAT_OPTIONS = Object.freeze([
-  "id", "target", "channel", "fields", "columns", "gap", "align",
-  "padding", "scales", "guides"
+  "id", "target", "channel", "fields", "columns", "gap", "spacing", "align",
+  "padding", "scales", "guides", "headers"
 ]);
 const SOURCE_EDIT_OPTIONS = Object.freeze(["program"]);
 const GUIDE_OPTIONS = Object.freeze(["axes", "legend"]);
@@ -59,7 +60,7 @@ const HEADER_STYLE_OPTIONS = Object.freeze([
   "fontSize", "fontFamily", "fontWeight", "color", "offset", "align"
 ]);
 
-function normalizeGuides(guides) {
+function normalizeGuides(guides, allowStored = false) {
   if (guides === undefined) return { axes: "each", legend: false };
   validateOptionObject(guides, GUIDE_OPTIONS, "facet.guides");
   const axes = guides.axes ?? "each";
@@ -67,8 +68,11 @@ function normalizeGuides(guides) {
     throw new Error('facet guides.axes must be "each" or "outer".');
   }
   const legend = guides.legend ?? false;
-  if (legend !== false && legend !== "shared") {
-    throw new Error('facet guides.legend must be false or "shared".');
+  if (legend !== false && legend !== "shared" && !isPlainObject(legend)) {
+    throw new Error('facet guides.legend must be false, "shared", or legend options.');
+  }
+  if (!allowStored && isPlainObject(legend) && Object.hasOwn(legend, "type")) {
+    throw new Error("Facet legend options do not accept internal type tags.");
   }
   return { axes, legend };
 }
@@ -184,65 +188,149 @@ function rederiveFacet(program, { scales, guides }) {
   }, compositionSpec.children);
 }
 
-export const facet = /* @__PURE__ */ closedAction(
-  {
-    op: "facet",
-    description: "Repeat one direct-source chart by field value."
-  }, FACET_OPTIONS,
-  function (args = {}) {
-    const guides = normalizeGuides(args.guides);
-    const definition = resolveFacetDefinition(this.semanticSpec, args);
-    if (definition.family !== "cartesian" && guides.axes === "outer") {
-      throw new Error("Polar and Parallel facets do not support outer axes.");
+function resolveEditedFacetHeaders(currentHeaders, args, grid, operation = "editFacetHeaders") {
+  validateOptionObject(args, HEADER_OPTIONS, operation, {
+    allowEmpty: false,
+    emptyMessage: `${operation} requires at least one change.`
+  });
+  const role = args.role ?? "all";
+  if (!["all", "row", "column"].includes(role)) {
+    throw new Error(`Unknown facet header role "${role}".`);
+  }
+  if (role === "all" && Object.hasOwn(args, "side")) {
+    throw new Error(`${operation} side requires an explicit row or column role.`);
+  }
+  if (role === "row" && grid === undefined) {
+    throw new Error(`${operation} row role requires a row-column facet grid.`);
+  }
+  if (Object.hasOwn(args, "side")) {
+    const sides = role === "row" ? ["left", "right"]
+      : grid === undefined
+        ? ["top", "bottom", "left", "right"] : ["top", "bottom"];
+    if (!sides.includes(args.side)) {
+      throw new Error(`${operation} ${role} side must be ${sides.join(" or ")}.`);
     }
-    const scalePolicies = normalizeFacetScalePolicies(
-      this.semanticSpec,
-      args.scales ?? {}
-    );
-    const derived = deriveFacetChildren(this, definition, {
-      closeInheritedAction: true,
-      stripTitle: true,
-      scales: args.scales ?? {}
-    });
-    const preflight = resolveFacetLayout({
-      children: definition.cells.map(cell => ({
-        ...compositionChildDescriptor(cell.id, derived.children[cell.id]),
-        value: cell.value
-      })),
-      ...(Object.hasOwn(args, "columns") ? { columns: args.columns } : {}),
-      ...(Object.hasOwn(args, "gap") ? { gap: args.gap } : {}),
-      ...(Object.hasOwn(args, "align") ? { align: args.align } : {}),
-      ...(Object.hasOwn(args, "padding") ? { padding: args.padding } : {}),
-      sharedLegend: guides.legend === "shared"
-    });
-    const compositionSpec = {
-      id: definition.id,
-      type: "facet",
-      children: definition.cells.map(cell => cell.id),
-      columns: preflight.columns,
-      gap: preflight.gap,
-      align: preflight.align,
-      padding: preflight.padding,
-      facet: {
-        data: definition.data,
-        field: definition.field,
-        values: definition.values,
-        scales: scalePolicies.channels,
-        guides
-      }
-    };
-    return applyCompositionState(
-      this._withMaterializationConfig(["facets", definition.id], {
-        headers: createDefaultFacetHeaders()
-      }),
-      {
-        children: derived.children,
-        compositionSpec
-      },
-      compositionSpec.children
-    );
   }
-);
+  if (Object.hasOwn(args, "align") &&
+      !["start", "center", "end"].includes(args.align)) {
+    throw new Error(`${operation} align must be start, center, or end.`);
+  }
+  if (role === "all" && Object.keys(args).every(key => key === "role")) {
+    throw new Error(`${operation} requires at least one change.`);
+  }
+  const current = normalizeFacetHeadersConfig(currentHeaders);
+  const owner = role === "all" ? "common" : role;
+  const patch = { ...current[owner] };
+  for (const key of HEADER_STYLE_OPTIONS) {
+    if (Object.hasOwn(args, key)) patch[key] = args[key];
+  }
+  if (Object.hasOwn(args, "side")) patch.side = args.side;
+  if (Object.hasOwn(args, "labelMap")) {
+    if (args.labelMap === "auto") delete patch.labelMap;
+    else {
+      patch.labelMap = normalizeDisplayLabelMap(
+        args.labelMap,
+        `${operation} ${role} labelMap`
+      );
+    }
+  }
+  const headers = {
+    ...current,
+    ...(role === "all" ? {} : { mode: "roles" }),
+    [owner]: patch
+  };
+  for (const headerRole of ["all", "row", "column"]) {
+    const resolved = resolveFacetHeaderConfig(headers, headerRole);
+    validatePositiveFinite(resolved.fontSize, `Facet ${headerRole} header fontSize`);
+    validateNonEmptyString(resolved.fontFamily, `Facet ${headerRole} header fontFamily`);
+    validateNonEmptyString(resolved.color, `Facet ${headerRole} header color`);
+    validateNonNegativeFinite(resolved.offset, `Facet ${headerRole} header offset`);
+    if (!(
+      (typeof resolved.fontWeight === "string" && resolved.fontWeight.length > 0) ||
+      Number.isFinite(resolved.fontWeight)
+    )) {
+      throw new TypeError(
+        `Facet ${headerRole} header fontWeight must be a non-empty string or number.`
+      );
+    }
+    if (!["start", "center", "end"].includes(resolved.align)) {
+      throw new Error(`Facet ${headerRole} header align must be start, center, or end.`);
+    }
+    if (resolved.labelMap !== undefined) {
+      normalizeDisplayLabelMap(
+        resolved.labelMap,
+        `Facet ${headerRole} header labelMap`
+      );
+    }
+  }
+  return headers;
+}
+
+function initialFacetHeaders(value, grid) {
+  let headers = createDefaultFacetHeaders();
+  if (value === undefined) return headers;
+  validateOptionObject(value, [...HEADER_STYLE_OPTIONS, "labelMap", "row", "column"], "facet.headers");
+  const { row, column, ...common } = value;
+  if (Object.keys(common).length > 0) headers = resolveEditedFacetHeaders(headers, common, grid, "facet.headers");
+  for (const [role, patch] of [["row", row], ["column", column]]) {
+    if (patch === undefined) continue;
+    validateOptionObject(patch, HEADER_OPTIONS.filter(key => key !== "role"), `facet.headers.${role}`);
+    headers = resolveEditedFacetHeaders(headers, { ...patch, role }, grid, `facet.headers.${role}`);
+  }
+  return headers;
+}
+
+function composeDerivedFacet(program, args, { definition, derived, guides, scalePolicies, facet }) {
+  const headers = initialFacetHeaders(args.headers, definition.grid);
+  const preflight = resolveFacetLayout({
+    spacing: args.spacing,
+    plots: Object.entries(derived.children).map(([id, child]) => ({ id, ...resolveGraphicBounds(child) })),
+    children: definition.cells.map(cell => ({
+      ...compositionChildDescriptor(cell.id, derived.children[cell.id]), value: cell.value,
+      ...(definition.grid === undefined ? {} : { row: cell.row, column: cell.column })
+    })),
+    columns: definition.grid?.columns.values.length ?? args.columns,
+    gap: args.gap, align: args.align, padding: args.padding,
+    sharedLegend: guides.legend === "shared"
+  });
+  const compositionSpec = {
+    id: definition.id, type: "facet", children: definition.cells.map(cell => cell.id),
+    columns: preflight.columns, gap: preflight.gap, align: preflight.align, padding: preflight.padding,
+    ...(preflight.spacing === undefined ? {} : { spacing: preflight.spacing }),
+    facet: { data: definition.data, ...facet, scales: scalePolicies.channels, guides }
+  };
+  return applyCompositionState(
+    program._withMaterializationConfig(["facets", definition.id], { headers }),
+    { children: derived.children, compositionSpec }, compositionSpec.children
+  );
+}
+
+function partitionFacetAction(op, description, definitionResolver) {
+  return closedAction({ op, description }, op === "facet" ? FACET_OPTIONS : FACET_GRID_OPTIONS,
+    function (args = {}) {
+      const guides = normalizeGuides(args.guides);
+      const definition = definitionResolver(this.semanticSpec, args);
+      if (definition.family !== "cartesian" && guides.axes === "outer") {
+        throw new Error("Polar and Parallel facets do not support outer axes.");
+      }
+      const scalePolicies = normalizeFacetScalePolicies(this.semanticSpec, args.scales ?? {});
+      const derived = deriveFacetChildren(this, definition, {
+        closeInheritedAction: true, stripTitle: true, scales: args.scales ?? {}
+      });
+      const facet = definition.grid === undefined
+        ? { field: definition.field, values: definition.values }
+        : { values: definition.cells.map(cell => cell.value), grid: {
+            ...definition.grid, cells: definition.cells.map(cell => ({
+              id: cell.id, row: cell.row, column: cell.column,
+              rowValue: cell.rowValue, columnValue: cell.columnValue, empty: cell.empty
+            }))
+          } };
+      return composeDerivedFacet(this, args, { definition, derived, guides, scalePolicies, facet });
+    });
+}
+
+export const facet = /* @__PURE__ */ partitionFacetAction("facet",
+  "Repeat one direct-source chart by field value.", resolveFacetDefinition);
 
 function resolveRepeatDefinition(program, args) {
   if (!isPlainObject(args)) {
@@ -453,115 +541,16 @@ export const repeatCharts = /* @__PURE__ */ closedAction(
       requestedScales,
       true
     );
-    const preflight = resolveFacetLayout({
-      children: definition.cells.map(cell => ({
-        ...compositionChildDescriptor(cell.id, derived.children[cell.id]),
-        value: cell.value
-      })),
-      ...(Object.hasOwn(args, "columns") ? { columns: args.columns } : {}),
-      ...(Object.hasOwn(args, "gap") ? { gap: args.gap } : {}),
-      ...(Object.hasOwn(args, "align") ? { align: args.align } : {}),
-      ...(Object.hasOwn(args, "padding") ? { padding: args.padding } : {}),
-      sharedLegend: guides.legend === "shared"
+    return composeDerivedFacet(this, args, {
+      definition, derived, guides, scalePolicies,
+      facet: { values: definition.fields,
+        repeat: { target: definition.target, channel: definition.channel, fields: definition.fields } }
     });
-    const compositionSpec = {
-      id: definition.id,
-      type: "facet",
-      children: definition.cells.map(cell => cell.id),
-      columns: preflight.columns,
-      gap: preflight.gap,
-      align: preflight.align,
-      padding: preflight.padding,
-      facet: {
-        data: definition.data,
-        values: definition.fields,
-        repeat: {
-          target: definition.target,
-          channel: definition.channel,
-          fields: definition.fields
-        },
-        scales: scalePolicies.channels,
-        guides
-      }
-    };
-    return applyCompositionState(
-      this._withMaterializationConfig(["facets", definition.id], {
-        headers: createDefaultFacetHeaders()
-      }),
-      { children: derived.children, compositionSpec },
-      compositionSpec.children
-    );
   }
 );
 
-export const facetGrid = /* @__PURE__ */ closedAction(
-  {
-    op: "facetGrid",
-    description: "Repeat one direct-source Cartesian chart across a row and column field grid."
-  }, FACET_GRID_OPTIONS,
-  function (args = {}) {
-    const guides = normalizeGuides(args.guides);
-    const definition = resolveFacetGridDefinition(this.semanticSpec, args);
-    if (definition.family !== "cartesian" && guides.axes === "outer") {
-      throw new Error("Polar and Parallel facets do not support outer axes.");
-    }
-    const scalePolicies = normalizeFacetScalePolicies(
-      this.semanticSpec,
-      args.scales ?? {}
-    );
-    const derived = deriveFacetChildren(this, definition, {
-      closeInheritedAction: true,
-      stripTitle: true,
-      scales: args.scales ?? {}
-    });
-    const preflight = resolveFacetLayout({
-      children: definition.cells.map(cell => ({
-        ...compositionChildDescriptor(cell.id, derived.children[cell.id]),
-        value: cell.value,
-        row: cell.row,
-        column: cell.column
-      })),
-      columns: definition.grid.columns.values.length,
-      ...(Object.hasOwn(args, "gap") ? { gap: args.gap } : {}),
-      ...(Object.hasOwn(args, "align") ? { align: args.align } : {}),
-      ...(Object.hasOwn(args, "padding") ? { padding: args.padding } : {}),
-      sharedLegend: guides.legend === "shared"
-    });
-    const compositionSpec = {
-      id: definition.id,
-      type: "facet",
-      children: definition.cells.map(cell => cell.id),
-      columns: preflight.columns,
-      gap: preflight.gap,
-      align: preflight.align,
-      padding: preflight.padding,
-      facet: {
-        data: definition.data,
-        values: definition.cells.map(cell => cell.value),
-        grid: {
-          ...definition.grid,
-          cells: definition.cells.map(cell => ({
-            id: cell.id,
-            row: cell.row,
-            column: cell.column,
-            rowValue: cell.rowValue,
-            columnValue: cell.columnValue,
-            empty: cell.empty
-          }))
-        },
-        scales: scalePolicies.channels,
-        guides
-      }
-    };
-    return applyCompositionState(
-      this._withMaterializationConfig(["facets", definition.id], {
-        headers: createDefaultFacetHeaders()
-      }),
-      { children: derived.children, compositionSpec },
-      compositionSpec.children
-    );
-  }
-);
+export const facetGrid = /* @__PURE__ */ partitionFacetAction("facetGrid",
+  "Repeat one direct-source Cartesian chart across a row and column field grid.", resolveFacetGridDefinition);
 
 export const editFacetHeaders = /* @__PURE__ */ action(
   {
@@ -576,78 +565,7 @@ export const editFacetHeaders = /* @__PURE__ */ action(
     if (!isPlainObject(config?.headers)) {
       throw new Error(`Facet "${id}" requires header configuration.`);
     }
-    validateOptionObject(args, HEADER_OPTIONS, "editFacetHeaders", {
-      allowEmpty: false,
-      emptyMessage: "editFacetHeaders requires at least one change."
-    });
-    const role = args.role ?? "all";
-    if (!["all", "row", "column"].includes(role)) {
-      throw new Error(`Unknown facet header role "${role}".`);
-    }
-    if (role === "all" && Object.hasOwn(args, "side")) {
-      throw new Error("editFacetHeaders side requires an explicit row or column role.");
-    }
-    if (role === "row" && this.compositionSpec.facet.grid === undefined) {
-      throw new Error("editFacetHeaders row role requires a row-column facet grid.");
-    }
-    if (Object.hasOwn(args, "side")) {
-      const sides = role === "row" ? ["left", "right"] : ["top", "bottom"];
-      if (!sides.includes(args.side)) {
-        throw new Error(`editFacetHeaders ${role} side must be ${sides.join(" or ")}.`);
-      }
-    }
-    if (Object.hasOwn(args, "align") &&
-        !["start", "center", "end"].includes(args.align)) {
-      throw new Error("editFacetHeaders align must be start, center, or end.");
-    }
-    if (role === "all" && Object.keys(args).every(key => key === "role")) {
-      throw new Error("editFacetHeaders requires at least one change.");
-    }
-    const current = normalizeFacetHeadersConfig(config.headers);
-    const owner = role === "all" ? "common" : role;
-    const patch = { ...current[owner] };
-    for (const key of HEADER_STYLE_OPTIONS) {
-      if (Object.hasOwn(args, key)) patch[key] = args[key];
-    }
-    if (Object.hasOwn(args, "side")) patch.side = args.side;
-    if (Object.hasOwn(args, "labelMap")) {
-      if (args.labelMap === "auto") delete patch.labelMap;
-      else {
-        patch.labelMap = normalizeDisplayLabelMap(
-          args.labelMap,
-          `editFacetHeaders ${role} labelMap`
-        );
-      }
-    }
-    const headers = {
-      ...current,
-      ...(role === "all" ? {} : { mode: "roles" }),
-      [owner]: patch
-    };
-    for (const headerRole of ["all", "row", "column"]) {
-      const resolved = resolveFacetHeaderConfig(headers, headerRole);
-      validatePositiveFinite(resolved.fontSize, `Facet ${headerRole} header fontSize`);
-      validateNonEmptyString(resolved.fontFamily, `Facet ${headerRole} header fontFamily`);
-      validateNonEmptyString(resolved.color, `Facet ${headerRole} header color`);
-      validateNonNegativeFinite(resolved.offset, `Facet ${headerRole} header offset`);
-      if (!(
-        (typeof resolved.fontWeight === "string" && resolved.fontWeight.length > 0) ||
-        Number.isFinite(resolved.fontWeight)
-      )) {
-        throw new TypeError(
-          `Facet ${headerRole} header fontWeight must be a non-empty string or number.`
-        );
-      }
-      if (!["start", "center", "end"].includes(resolved.align)) {
-        throw new Error(`Facet ${headerRole} header align must be start, center, or end.`);
-      }
-      if (resolved.labelMap !== undefined) {
-        normalizeDisplayLabelMap(
-          resolved.labelMap,
-          `Facet ${headerRole} header labelMap`
-        );
-      }
-    }
+    const headers = resolveEditedFacetHeaders(config.headers, args, this.compositionSpec.facet.grid);
     return this
       ._withMaterializationConfig(["facets", id], { ...config, headers })
       .materializeComposition();
@@ -702,7 +620,8 @@ export const editFacetGuides = /* @__PURE__ */ action(
       emptyMessage: "editFacetGuides requires at least one guide policy."
     });
     const current = this.compositionSpec.facet;
-    const guides = normalizeGuides({ ...current.guides, ...args });
+    if (Object.hasOwn(args, "legend")) normalizeGuides({ legend: args.legend });
+    const guides = normalizeGuides({ ...current.guides, ...args }, true);
     const family = resolveFacetFamily(this.semanticSpec).family;
     if (family !== "cartesian" && guides.axes === "outer") {
       throw new Error("Polar and Parallel facets do not support outer axes.");
@@ -773,6 +692,8 @@ export const editFacetSource = /* @__PURE__ */ closedAction(
     const current = this.compositionSpec;
     const facetConfig = this.materializationConfigs.facets?.[current.id];
     const base = adoptUnitState(args.program, this);
+    const authored = isPlainObject(current.facet.guides.legend);
+    const guides = authored ? { ...current.facet.guides, legend: false } : current.facet.guides;
     let revised;
     const scales = usedFacetScalePolicies(base, current.facet.scales);
     if (current.facet.grid !== undefined) {
@@ -783,10 +704,11 @@ export const editFacetSource = /* @__PURE__ */ closedAction(
         columns: current.facet.grid.columns,
         combinations: current.facet.grid.combinations,
         gap: current.gap,
+        ...(current.spacing === undefined ? {} : { spacing: current.spacing }),
         align: current.align,
         padding: current.padding,
         scales,
-        guides: current.facet.guides
+        guides
       });
     } else if (current.facet.repeat !== undefined) {
       revised = base.repeatCharts({
@@ -794,10 +716,11 @@ export const editFacetSource = /* @__PURE__ */ closedAction(
         ...current.facet.repeat,
         columns: current.columns,
         gap: current.gap,
+        ...(current.spacing === undefined ? {} : { spacing: current.spacing }),
         align: current.align,
         padding: current.padding,
         scales,
-        guides: current.facet.guides
+        guides
       });
     } else {
       revised = base.facet({
@@ -807,12 +730,18 @@ export const editFacetSource = /* @__PURE__ */ closedAction(
         values: current.facet.values,
         columns: current.columns,
         gap: current.gap,
+        ...(current.spacing === undefined ? {} : { spacing: current.spacing }),
         align: current.align,
         padding: current.padding,
         scales,
-        guides: current.facet.guides
+        guides
       });
     }
+    if (authored) {
+      const spec = revised.compositionSpec;
+      revised = revised._withCompositionState({ children: revised.children,
+        compositionSpec: { ...spec, facet: { ...spec.facet, guides: current.facet.guides } } });
+    }
     if (facetConfig !== undefined) {
       revised = revised
         ._withMaterializationConfig(["facets", current.id], facetConfig)

package/src/actions/facets/guides.js

@@ -1,3 +1,4 @@
+import { synchronizeFacetColorSizeMeaning } from "../primitives/semanticAction.js";
 import { closedAction } from "../../core/action.js";
 
 import { applyFacetGuideComposition } from
@@ -10,6 +11,6 @@ export const composeFacetGuides = /* @__PURE__ */ closedAction(
     scope: "composition"
   }, ["layout", "plot"],
   function ({ layout, plot } = {}) {
-    return applyFacetGuideComposition(this, { layout, plot });
+    return applyFacetGuideComposition(this, { layout, plot, synchronizeColorSizeMeaning: synchronizeFacetColorSizeMeaning });
   }
 );

package/src/actions/gradientPlots/resolve.js

@@ -1,5 +1,5 @@
 import { resolveOptionalUserId, validateUserId } from "../../core/identifiers.js";
-import { findLayer, hasLayer } from "../../selectors/layers.js";
+import { findLayer, hasLayer, resolveConfiguredOwner } from "../../selectors/layers.js";
 
 const CATEGORICAL = Object.freeze(["nominal", "ordinal"]);
 
@@ -62,20 +62,5 @@ export function resolveGradientPlotId(program, requested) {
 }
 
 export function resolveGradientOwner(program, requested, operation) {
-  const eligible = program.semanticSpec.layers.filter(
-    layer => program.markConfigs[layer.id]?.gradientPlot?.materialized === true
-  );
-  if (requested !== undefined) {
-    const id = validateUserId(requested, "Gradient-plot owner id");
-    const layer = findLayer(program, id);
-    if (layer === undefined || !eligible.includes(layer)) {
-      throw new Error(`Unknown gradient-plot owner "${id}".`);
-    }
-    return layer;
-  }
-  const current = findLayer(program, program.context.currentMark);
-  if (current !== undefined && eligible.includes(current)) return current;
-  if (eligible.length === 1) return eligible[0];
-  if (eligible.length === 0) throw new Error(`${operation} requires a gradient plot.`);
-  throw new Error(`${operation} target is ambiguous; provide target.`);
+  return resolveConfiguredOwner(program, requested, { config: "gradientPlot", operation, kind: "gradient", materialized: true }, validateUserId);
 }

package/src/actions/guides/applicability.js

@@ -56,7 +56,7 @@ export function hasInferableLegend(program, layers = program.semanticSpec.layers
       (layer.mark?.type === "point" &&
         layer.encoding?.color?.scale !== undefined &&
         (layer.encoding?.shape?.scale !== undefined ||
-          ["sequential", "quantize", "quantile", "threshold"].includes(
+          ["sequential", "log", "sqrt", "symlog", "quantize", "quantile", "threshold"].includes(
             findSemanticScale(program, layer.encoding.color.scale)?.type
           ))) ||
       (layer.mark?.type === "line" &&

package/src/actions/guides/axes/axes.js

@@ -1,3 +1,4 @@
+import { withGuideLayoutTransaction } from "../../../materialization/guides/layout.js";
 import { isSourceOwnedText } from "../../../grammar/text.js";
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
@@ -15,6 +16,13 @@ const COORDINATE_API_TYPES = new Set([
 ]);
 
 function validateAxisOption(value, channel) {
+  if (["x", "y"].includes(channel) && Array.isArray(value)) {
+    if (value.length === 0 || value.some(entry => !isPlainObject(entry) || !Object.hasOwn(entry, "id"))) {
+      throw new TypeError(`createAxes ${channel} arrays require nonempty named axis descriptors.`);
+    }
+    for (const entry of value) validateUserId(entry.id, "Axis id");
+    return;
+  }
   if (value !== undefined && value !== false && !isPlainObject(value)) {
     throw new TypeError(`createAxes ${channel} must be false or a plain object.`);
   }
@@ -287,23 +295,34 @@ const createAxes = /* @__PURE__ */ action(
       coordinateDescriptor,
       cartesianLayers
     );
-    const x = resolveAxisArgs(coordinate.layers, "x", args.x);
-    const y = resolveAxisArgs(coordinate.layers, "y", args.y);
+    const resolve = (channel, value) => Array.isArray(value)
+      ? value.map(entry => resolveAxisArgs(coordinate.layers, channel, entry))
+      : resolveAxisArgs(coordinate.layers, channel, value);
+    const x = resolve("x", args.x);
+    const y = resolve("y", args.y);
 
     if (x === undefined && y === undefined) {
       throw new Error("createAxes requires at least one selected axis.");
     }
 
-    let program = this;
-
-    if (x !== undefined) {
-      program = program.createXAxis({ ...x, coordinate: coordinate.id });
-    }
-    if (y !== undefined) {
-      program = program.createYAxis({ ...y, coordinate: coordinate.id });
+    const apply = source => {
+      let program = source;
+      for (const [channel, option] of [["x", x], ["y", y]]) {
+        if (option === undefined) continue;
+        for (const entry of Array.isArray(option) ? option : [option]) {
+          program = program[`create${channel.toUpperCase()}Axis`]({ ...entry, coordinate: coordinate.id });
+        }
+      }
+      return program;
+    };
+    if (Array.isArray(x) || Array.isArray(y)) {
+      const ids = [...(Array.isArray(x) ? x : x === undefined ? [] : [x]),
+        ...(Array.isArray(y) ? y : y === undefined ? [] : [y])].map((entry, index) => entry.id ?? (index === 0 ? "x" : "y"));
+      if (new Set(ids).size !== ids.length) throw new Error("createAxes requires unique axis ids across its descriptors.");
+      withGuideLayoutTransaction(this, apply);
+      return withGuideLayoutTransaction(this, apply);
     }
-
-    return program;
+    return apply(this);
   }
 );