ggaction 0.0.12 → 0.0.15

package/src/actions/facets/actions.js

@@ -1,12 +1,18 @@
 import { action } from "../../core/action.js";
 import { freezeOwned, isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
 import {
   validateNonEmptyString,
   validateNonNegativeFinite,
   validateOptionObject,
   validatePositiveFinite
 } from "../../core/validation.js";
-import { resolveFacetDefinition } from "../../grammar/facets/index.js";
+import {
+  resolveFacetDefinition,
+  resolveFacetGridDefinition
+} from "../../grammar/facets/index.js";
+import { collectFacetScaleBindings, resolveFacetFamily } from
+  "../../grammar/facets/dependencies.js";
 import {
   FACET_SCALE_CHANNELS,
   normalizeFacetScalePolicies
@@ -14,27 +20,43 @@ import {
 import { resolveFacetLayout } from "../../layout/facets.js";
 import { compositionChildDescriptor } from
   "../../materialization/composition.js";
-import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../theme/defaults.js";
 import { deriveFacetChildren } from "./derive.js";
+import { resolveFacetChildrenScales } from "./derive.js";
 import { replayDerivedData } from "./replay.js";
 import { composeFacetGuides } from "./guides.js";
 import { applyCompositionState } from "../composition/actions.js";
+import { replayCompositionThemeState } from "../theme/composition.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+import { normalizeDisplayLabelMap } from "../../grammar/displayLabels.js";
+import {
+  createDefaultFacetHeaders,
+  normalizeFacetHeadersConfig,
+  resolveFacetHeaderConfig
+} from "../../materialization/facetHeaders.js";
 
 const FACET_OPTIONS = Object.freeze([
-  "id", "field", "data", "columns", "gap", "align", "padding", "scales",
+  "id", "field", "data", "values", "columns", "gap", "align", "padding", "scales",
   "guides"
 ]);
+const FACET_GRID_OPTIONS = Object.freeze([
+  "id", "data", "rows", "columns", "combinations", "gap", "align",
+  "padding", "scales", "guides"
+]);
+const REPEAT_OPTIONS = Object.freeze([
+  "id", "target", "channel", "fields", "columns", "gap", "align",
+  "padding", "scales", "guides"
+]);
+const SOURCE_EDIT_OPTIONS = Object.freeze(["program"]);
 const GUIDE_OPTIONS = Object.freeze(["axes", "legend"]);
 const HEADER_OPTIONS = Object.freeze([
-  "fontSize", "fontFamily", "fontWeight", "color", "offset"
+  "fontSize", "fontFamily", "fontWeight", "color", "offset", "role",
+  "labelMap", "side", "align"
+]);
+const HEADER_STYLE_OPTIONS = Object.freeze([
+  "fontSize", "fontFamily", "fontWeight", "color", "offset", "align"
 ]);
-const DEFAULT_HEADERS = Object.freeze({
-  fontSize: 12,
-  fontFamily: DEFAULT_FONT_FAMILY,
-  fontWeight: 600,
-  color: DEFAULT_COLORS.strongText,
-  offset: 10
-});
 
 function normalizeGuides(guides) {
   if (guides === undefined) return { axes: "each", legend: false };
@@ -57,18 +79,38 @@ function requireFacetProgram(program, operation) {
   }
 }
 
+function usedFacetScalePolicies(program, policies) {
+  const used = new Set(
+    collectFacetScaleBindings(program.semanticSpec).map(binding => binding.policyKey)
+  );
+  return Object.fromEntries(
+    FACET_SCALE_CHANNELS.flatMap(channel =>
+      used.has(channel) ? [[channel, policies[channel]]] : []
+    )
+  );
+}
+
 function facetUnitTemplate(program) {
-  const seed = program.children[program.compositionSpec.children[0]];
+  const seedId = program.compositionSpec.children.find(id =>
+    program.children[id]?.semanticSpec.layers.length > 0
+  ) ?? program.compositionSpec.children[0];
+  const seed = program.children[seedId];
   if (seed === undefined) {
     throw new Error(`Facet "${program.compositionSpec.id}" requires a retained child.`);
   }
-  const { facets: _facets, ...unitConfigs } = program.materializationConfigs;
+  const { facets: _facets, guides: _guides, ...unitConfigs } = program.materializationConfigs;
   return new program.constructor({
     semanticSpec: program.semanticSpec,
     graphicSpec: seed.graphicSpec,
     resolvedScales: program.resolvedScales,
     materializationConfigs: freezeOwned({
       ...unitConfigs,
+      ...(seed.materializationConfigs.theme === undefined
+        ? {}
+        : { theme: seed.materializationConfigs.theme }),
+      ...(seed.materializationConfigs.guides === undefined
+        ? {}
+        : { guides: seed.materializationConfigs.guides }),
       canvas: seed.materializationConfigs.canvas
     }),
     children: {},
@@ -81,19 +123,44 @@ function facetUnitTemplate(program) {
 
 function rederiveFacet(program, { scales, guides }) {
   const current = program.compositionSpec;
-  const definition = resolveFacetDefinition(program.semanticSpec, {
-    id: current.id,
-    data: current.facet.data,
-    field: current.facet.field,
-    values: current.facet.values
-  });
-  const request = Object.fromEntries(FACET_SCALE_CHANNELS.flatMap(channel =>
-    program.semanticSpec.layers.some(
-      layer => layer.encoding?.[channel]?.scale !== undefined
-    ) ? [[channel, scales[channel]]] : []
-  ));
+  if (current.facet.repeat !== undefined) {
+    const template = facetUnitTemplate(program);
+    const definition = resolveRepeatDefinition(template, {
+      id: current.id,
+      ...current.facet.repeat
+    });
+    const derived = deriveRepeatChildren(
+      template,
+      definition,
+      usedFacetScalePolicies(template, scales),
+      true
+    );
+    return applyCompositionState(program, {
+      children: derived.children,
+      compositionSpec: {
+        ...current,
+        facet: { ...current.facet, scales, guides }
+      }
+    }, current.children);
+  }
+  const definition = current.facet.grid === undefined
+    ? resolveFacetDefinition(program.semanticSpec, {
+        id: current.id,
+        data: current.facet.data,
+        field: current.facet.field,
+        values: current.facet.values
+      })
+    : resolveFacetGridDefinition(program.semanticSpec, {
+        id: current.id,
+        data: current.facet.data,
+        rows: current.facet.grid.rows,
+        columns: current.facet.grid.columns,
+        combinations: current.facet.grid.combinations
+      });
+  const request = usedFacetScalePolicies(program, scales);
   const normalized = normalizeFacetScalePolicies(program.semanticSpec, request);
-  const derived = deriveFacetChildren(facetUnitTemplate(program), definition, {
+  const template = facetUnitTemplate(program);
+  const derived = deriveFacetChildren(template, definition, {
     closeInheritedAction: true,
     stripTitle: true,
     scales: request
@@ -106,7 +173,11 @@ function rederiveFacet(program, { scales, guides }) {
       guides
     }
   };
-  return applyCompositionState(program, {
+  let parent = program._withoutMaterializationConfig(["guides", "legend"]);
+  for (const [kind, config] of Object.entries(template.guideConfigs.legend ?? {})) {
+    parent = parent._withLegendConfig(kind, config);
+  }
+  return applyCompositionState(parent, {
     children: derived.children,
     compositionSpec
   }, compositionSpec.children);
@@ -121,6 +192,9 @@ export const facet = action(
     validateOptionObject(args, FACET_OPTIONS, "facet");
     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.");
+    }
     const scalePolicies = normalizeFacetScalePolicies(
       this.semanticSpec,
       args.scales ?? {}
@@ -159,7 +233,7 @@ export const facet = action(
     };
     return applyCompositionState(
       this._withMaterializationConfig(["facets", definition.id], {
-        headers: DEFAULT_HEADERS
+        headers: createDefaultFacetHeaders()
       }),
       {
         children: derived.children,
@@ -170,6 +244,327 @@ export const facet = action(
   }
 );
 
+function resolveRepeatDefinition(program, args) {
+  if (!isPlainObject(args)) {
+    throw new TypeError("repeatCharts options must be a plain object.");
+  }
+  const id = validateUserId(args.id ?? "repeat", "Repeat id");
+  const parallelChannel = isPlainObject(args.channel);
+  if (parallelChannel) {
+    const keys = Object.keys(args.channel);
+    if (keys.length !== 1 || keys[0] !== "parallelDimension" ||
+        typeof args.channel.parallelDimension !== "string" ||
+        args.channel.parallelDimension.length === 0) {
+      throw new Error(
+        "repeatCharts Parallel channel must contain exactly one non-empty parallelDimension."
+      );
+    }
+  } else if (!["x", "y", "theta", "r"].includes(args.channel)) {
+    throw new Error(
+      'repeatCharts channel must be "x", "y", "theta", "r", or one parallelDimension.'
+    );
+  }
+  if (!Array.isArray(args.fields) || args.fields.length === 0 ||
+      args.fields.some(field => typeof field !== "string" || field.length === 0)) {
+    throw new TypeError("repeatCharts fields must be a non-empty array of field names.");
+  }
+  if (new Set(args.fields).size !== args.fields.length) {
+    throw new Error("repeatCharts fields must be unique.");
+  }
+  const family = resolveFacetFamily(program.semanticSpec).family;
+  const semanticChannel = args.channel === "r" ? "radius" : args.channel;
+  const eligible = program.semanticSpec.layers.filter(layer => {
+    if (parallelChannel) {
+      const matches = (layer.encoding?.parallel?.dimensions ?? []).filter(
+        dimension => dimension.field === args.channel.parallelDimension
+      );
+      return family === "parallel" && layer.mark?.type === "line" && matches.length === 1;
+    }
+    if (["x", "y"].includes(args.channel)) {
+      return family === "cartesian" &&
+        layer.encoding?.x?.scale !== undefined &&
+        layer.encoding?.y?.scale !== undefined &&
+        layer.encoding?.[args.channel]?.field !== undefined &&
+        ["point", "line", "area", "bar", "rule", "tick", "rect"].includes(layer.mark?.type);
+    }
+    const role = program.markConfigs[layer.id]?.compositionRole;
+    if (family !== "polar" || ["pie", "radar"].includes(role)) return false;
+    return ["point", "line", "arc"].includes(layer.mark?.type) &&
+      layer.encoding?.[semanticChannel]?.field !== undefined;
+  });
+  let target;
+  if (args.target !== undefined) {
+    target = validateUserId(args.target, "Repeat target");
+    if (!eligible.some(layer => layer.id === target)) {
+      throw new Error(
+        `repeatCharts target "${target}" is not eligible for the requested field role.`
+      );
+    }
+  } else if (eligible.length === 1) {
+    target = eligible[0].id;
+  } else {
+    throw new Error(
+      eligible.length === 0
+        ? "repeatCharts requires one eligible complete mark for the requested field role."
+        : "repeatCharts target is ambiguous; provide target."
+    );
+  }
+  const unrelatedLayers = program.semanticSpec.layers.filter(layer => {
+    if (layer.id === target) return false;
+    const attachedLabel = layer.mark?.type === "text" && layer.source === target;
+    const statisticalReference = program.markConfigs[layer.id]
+      ?.statisticalReference?.source === target;
+    return !attachedLabel && !statisticalReference;
+  });
+  if (unrelatedLayers.length > 0) {
+    throw new Error("repeatCharts currently supports one direct mark only.");
+  }
+  const config = program.markConfigs[target] ?? {};
+  const composite = [
+    "boxPlot", "gradientPlot", "violinPlot", "regressionPlot", "endpointPlot",
+    "ecdfPlot", "raincloudPlot", "intervalPlot"
+  ].find(key => config[key] !== undefined);
+  if (composite !== undefined) {
+    throw new Error(`repeatCharts does not replace the ${composite} composite role.`);
+  }
+  const layer = findLayer(program, target);
+  const dataset = findDataset(program, layer.data);
+  if (dataset?.transform?.length > 0) {
+    throw new Error("repeatCharts does not rewrite a derived dataset dependency.");
+  }
+  const encoding = parallelChannel
+    ? layer.encoding.parallel
+    : layer.encoding[semanticChannel];
+  const dimensionIndex = parallelChannel
+    ? encoding.dimensions.findIndex(
+        dimension => dimension.field === args.channel.parallelDimension
+      )
+    : undefined;
+  return {
+    id,
+    target,
+    channel: parallelChannel ? { ...args.channel } : args.channel,
+    policyKey: parallelChannel ? "parallelDimensions" : args.channel,
+    fields: [...args.fields],
+    data: layer.data,
+    encoding,
+    ...(dimensionIndex === undefined ? {} : { dimensionIndex }),
+    cells: args.fields.map((field, index) => ({
+      id: `${id}-field-${index + 1}`,
+      field,
+      value: field
+    }))
+  };
+}
+
+function repeatEncodingArgs(definition, field) {
+  const encoding = definition.encoding;
+  return {
+    target: definition.target,
+    field,
+    fieldType: encoding.fieldType,
+    ...(encoding.temporalUnit === undefined ? {} : { temporalUnit: encoding.temporalUnit }),
+    ...(encoding.aggregate === undefined ? {} : { aggregate: encoding.aggregate }),
+    ...(encoding.bin === undefined ? {} : { bin: encoding.bin }),
+    ...(encoding.stack === undefined ? {} : { stack: encoding.stack }),
+    ...(encoding.weight === undefined ? {} : { weight: encoding.weight }),
+    scale: { id: encoding.scale }
+  };
+}
+
+function parallelRepeatDimensions(program, definition, field) {
+  return definition.encoding.dimensions.map((dimension, index) => {
+    const semanticScale = findSemanticScale(program, dimension.scale);
+    if (semanticScale === undefined) {
+      throw new Error(`repeatCharts Parallel dimension scale "${dimension.scale}" is missing.`);
+    }
+    const { id: _id, ...scale } = semanticScale;
+    void _id;
+    const replacement = index === definition.dimensionIndex;
+    return {
+      field: replacement ? field : dimension.field,
+      fieldType: dimension.fieldType,
+      title: replacement && dimension.title === dimension.field
+        ? field
+        : dimension.title,
+      scale
+    };
+  });
+}
+
+function deriveRepeatedProgram(template, definition, field) {
+  if (isPlainObject(definition.channel)) {
+    return template.encodeParallelCoordinates({
+      target: definition.target,
+      coordinate: findLayer(template, definition.target).coordinate,
+      dimensions: parallelRepeatDimensions(template, definition, field),
+      ...(definition.encoding.key === undefined ? {} : { key: definition.encoding.key }),
+      missing: definition.encoding.missing
+    });
+  }
+  const operation = {
+    x: "encodeX",
+    y: "encodeY",
+    theta: "encodeTheta",
+    r: "encodeR"
+  }[definition.channel];
+  return template[operation](repeatEncodingArgs(definition, field));
+}
+
+function deriveRepeatChildren(base, definition, scales, closeInheritedAction) {
+  const template = base.semanticSpec.title.text === undefined
+    ? base
+    : base.removeTitle();
+  const independentlyResolved = Object.fromEntries(definition.cells.map(cell => [
+    cell.id,
+    deriveRepeatedProgram(template, definition, cell.field)
+  ]));
+  return resolveFacetChildrenScales(
+    template,
+    definition.cells.map(cell => cell.id),
+    independentlyResolved,
+    scales,
+    closeInheritedAction
+  );
+}
+
+export const repeatCharts = action(
+  {
+    op: "repeatCharts",
+    description: "Repeat one direct chart across an ordered field-role list."
+  },
+  function (args = {}) {
+    validateOptionObject(args, REPEAT_OPTIONS, "repeatCharts");
+    const guides = normalizeGuides(args.guides);
+    if (guides.axes === "outer") {
+      throw new Error("repeatCharts does not promote axes across different repeated fields.");
+    }
+    const definition = resolveRepeatDefinition(this, args);
+    const requestedScales = {
+      ...(args.scales ?? {}),
+      [definition.policyKey]: args.scales?.[definition.policyKey] ?? "independent"
+    };
+    const scalePolicies = normalizeFacetScalePolicies(
+      this.semanticSpec,
+      requestedScales
+    );
+    const derived = deriveRepeatChildren(
+      this,
+      definition,
+      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"
+    });
+    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 = action(
+  {
+    op: "facetGrid",
+    description: "Repeat one direct-source Cartesian chart across a row and column field grid."
+  },
+  function (args = {}) {
+    validateOptionObject(args, FACET_GRID_OPTIONS, "facetGrid");
+    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 editFacetHeaders = action(
   {
     op: "editFacetHeaders",
@@ -187,18 +582,73 @@ export const editFacetHeaders = action(
       allowEmpty: false,
       emptyMessage: "editFacetHeaders requires at least one change."
     });
-    const headers = { ...config.headers, ...args };
-    validatePositiveFinite(headers.fontSize, "Facet header fontSize");
-    validateNonEmptyString(headers.fontFamily, "Facet header fontFamily");
-    validateNonEmptyString(headers.color, "Facet header color");
-    validateNonNegativeFinite(headers.offset, "Facet header offset");
-    if (!(
-      (typeof headers.fontWeight === "string" && headers.fontWeight.length > 0) ||
-      Number.isFinite(headers.fontWeight)
-    )) {
-      throw new TypeError(
-        "Facet header fontWeight must be a non-empty string or number."
-      );
+    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`
+        );
+      }
     }
     return this
       ._withMaterializationConfig(["facets", id], { ...config, headers })
@@ -219,8 +669,8 @@ export const editFacetScales = action(
       emptyMessage: "editFacetScales requires at least one channel policy change."
     });
     for (const channel of Object.keys(args)) {
-      if (!this.semanticSpec.layers.some(
-        layer => layer.encoding?.[channel]?.scale !== undefined
+      if (!collectFacetScaleBindings(this.semanticSpec).some(
+        binding => binding.policyKey === channel
       )) {
         throw new Error(
           `Facet scale channel "${channel}" is not used by an affected layer.`
@@ -255,6 +705,13 @@ export const editFacetGuides = action(
     });
     const current = this.compositionSpec.facet;
     const guides = normalizeGuides({ ...current.guides, ...args });
+    const family = resolveFacetFamily(this.semanticSpec).family;
+    if (family !== "cartesian" && guides.axes === "outer") {
+      throw new Error("Polar and Parallel facets do not support outer axes.");
+    }
+    if (current.repeat !== undefined && guides.axes === "outer") {
+      throw new Error("repeatCharts does not promote axes across different repeated fields.");
+    }
     return rederiveFacet(this, {
       scales: current.scales,
       guides
@@ -262,11 +719,132 @@ export const editFacetGuides = action(
   }
 );
 
+function adoptUnitState(program, actionOwner) {
+  if (!(program instanceof actionOwner.constructor)) {
+    throw new TypeError("editFacetSource program must be a ChartProgram.");
+  }
+  if (program.compositionSpec !== undefined) {
+    throw new Error("editFacetSource program must be a complete unit ChartProgram.");
+  }
+  if (program.actionStack.length !== 0) {
+    throw new Error("editFacetSource program has an unfinished action stack.");
+  }
+  const seedId = actionOwner.compositionSpec.children.find(id =>
+    actionOwner.children[id]?.semanticSpec.layers.length > 0
+  ) ?? actionOwner.compositionSpec.children[0];
+  const retained = actionOwner.children[seedId]?.materializationConfigs ?? {};
+  const {
+    canvas: _retainedCanvas,
+    theme: _retainedTheme,
+    facets: _retainedFacets,
+    ...retainedRecipe
+  } = retained;
+  void _retainedCanvas;
+  void _retainedTheme;
+  void _retainedFacets;
+  return new actionOwner.constructor({
+    semanticSpec: program.semanticSpec,
+    graphicSpec: program.graphicSpec,
+    resolvedScales: program.resolvedScales,
+    materializationConfigs: freezeOwned({
+      ...program.materializationConfigs,
+      ...retainedRecipe,
+      ...(program.materializationConfigs.canvas === undefined
+        ? {}
+        : { canvas: program.materializationConfigs.canvas }),
+      ...(program.materializationConfigs.theme === undefined
+        ? {}
+        : { theme: program.materializationConfigs.theme })
+    }),
+    children: {},
+    context: program.context,
+    trace: actionOwner.trace,
+    actionStack: actionOwner.actionStack,
+    actionSequence: actionOwner._actionSequence
+  });
+}
+
+export const editFacetSource = action(
+  {
+    op: "editFacetSource",
+    description: "Reapply one facet, grid, or repeat recipe to a revised complete unit program.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    validateOptionObject(args, SOURCE_EDIT_OPTIONS, "editFacetSource");
+    requireFacetProgram(this, "editFacetSource");
+    const current = this.compositionSpec;
+    const facetConfig = this.materializationConfigs.facets?.[current.id];
+    const base = adoptUnitState(args.program, this);
+    let revised;
+    const scales = usedFacetScalePolicies(base, current.facet.scales);
+    if (current.facet.grid !== undefined) {
+      revised = base.facetGrid({
+        id: current.id,
+        data: current.facet.data,
+        rows: current.facet.grid.rows,
+        columns: current.facet.grid.columns,
+        combinations: current.facet.grid.combinations,
+        gap: current.gap,
+        align: current.align,
+        padding: current.padding,
+        scales,
+        guides: current.facet.guides
+      });
+    } else if (current.facet.repeat !== undefined) {
+      revised = base.repeatCharts({
+        id: current.id,
+        ...current.facet.repeat,
+        columns: current.columns,
+        gap: current.gap,
+        align: current.align,
+        padding: current.padding,
+        scales,
+        guides: current.facet.guides
+      });
+    } else {
+      revised = base.facet({
+        id: current.id,
+        data: current.facet.data,
+        field: current.facet.field,
+        values: current.facet.values,
+        columns: current.columns,
+        gap: current.gap,
+        align: current.align,
+        padding: current.padding,
+        scales,
+        guides: current.facet.guides
+      });
+    }
+    if (facetConfig !== undefined) {
+      revised = revised
+        ._withMaterializationConfig(["facets", current.id], facetConfig)
+        .materializeComposition();
+    }
+    if (revised.semanticSpec.title.text !== undefined) {
+      revised = revised.removeTitle();
+    }
+    if (this.semanticSpec.title.text !== undefined) {
+      revised = revised.createTitle({
+        ...this.titleConfig,
+        ...this.semanticSpec.title
+      });
+    }
+    return replayCompositionThemeState(
+      revised,
+      this.materializationConfigs.theme
+    );
+  }
+);
+
 export function registerFacetActions(ProgramClass) {
   ProgramClass.prototype.replayDerivedData = replayDerivedData;
   ProgramClass.prototype.composeFacetGuides = composeFacetGuides;
   ProgramClass.prototype.facet = facet;
+  ProgramClass.prototype.facetGrid = facetGrid;
+  ProgramClass.prototype.repeatCharts = repeatCharts;
   ProgramClass.prototype.editFacetHeaders = editFacetHeaders;
   ProgramClass.prototype.editFacetScales = editFacetScales;
   ProgramClass.prototype.editFacetGuides = editFacetGuides;
+  ProgramClass.prototype.editFacetSource = editFacetSource;
 }