ggaction 0.0.2 → 0.0.3

package/src/actions/errorBars/create.js

@@ -1,15 +1,8 @@
 import { action } from "../../core/action.js";
-import { validateKeys, validatePositiveFinite } from "../../core/validation.js";
-import {
-  normalizeStrokeDashPattern,
-  validateOpacityValue
-} from "../../grammar/scales.js";
-import {
-  validateRuleStroke,
-  validateRuleStrokeWidth
-} from "../../grammar/ruleAppearance.js";
+import { validateKeys } from "../../core/validation.js";
 import { findLayer } from "../../selectors/layers.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { resolveErrorBarAppearance } from "./options.js";
 import { resolveErrorBar } from "./resolve.js";
 
 const OPTIONS = Object.freeze([
@@ -29,24 +22,22 @@ const OPTIONS = Object.freeze([
 ]);
 
 function resolveAppearance(args) {
-  const caps = args.caps ?? true;
-  if (typeof caps !== "boolean") {
-    throw new TypeError("createErrorBar caps must be a boolean.");
-  }
-  const capSize = args.capSize ?? 8;
-  validatePositiveFinite(capSize, "createErrorBar capSize");
-  const stroke = validateRuleStroke(
-    args.stroke ?? DEFAULT_COLORS.mark,
-    "createErrorBar stroke"
-  );
-  const strokeWidth = validateRuleStrokeWidth(
-    args.strokeWidth ?? 1.5,
-    "createErrorBar strokeWidth"
+  const appearanceArgs = Object.fromEntries(
+    ["caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"]
+      .filter(key => Object.hasOwn(args, key))
+      .map(key => [key, args[key]])
   );
-  const strokeDash = args.strokeDash ?? "solid";
-  normalizeStrokeDashPattern(strokeDash);
-  const opacity = validateOpacityValue(args.opacity ?? 1, "createErrorBar opacity");
-  return { caps, capSize, stroke, strokeWidth, strokeDash, opacity };
+  return resolveErrorBarAppearance(appearanceArgs, {
+    defaults: {
+      caps: true,
+      capSize: 8,
+      stroke: DEFAULT_COLORS.mark,
+      strokeWidth: 1.5,
+      strokeDash: "solid",
+      opacity: 1
+    },
+    operation: "createErrorBar"
+  });
 }
 
 function positionArgs(resolved) {
@@ -115,30 +106,46 @@ export const createErrorBar = action(
       .encodeStrokeDash({ target: resolved.id, value: appearance.strokeDash })
       .encodeOpacity({ target: resolved.id, value: appearance.opacity });
 
-    if (!appearance.caps) return next;
-
     const intervalLayer = findLayer(next, resolved.id);
-    for (const [id, field] of [
-      [resolved.lowerCapId, resolved.fields.lower],
-      [resolved.upperCapId, resolved.fields.upper]
-    ]) {
-      next = next.createErrorBarCap({
-        id,
+    if (appearance.caps) {
+      for (const [id, field] of [
+        [resolved.lowerCapId, resolved.fields.lower],
+        [resolved.upperCapId, resolved.fields.upper]
+      ]) {
+        next = next.createErrorBarCap({
+          id,
+          data: resolved.dataId,
+          orientation: resolved.orientation,
+          positionField: resolved.position.field,
+          positionFieldType: resolved.position.fieldType,
+          intervalField: field,
+          coordinate: resolved.coordinate,
+          positionScale: intervalLayer.encoding[resolved.position.channel].scale,
+          intervalScale: intervalLayer.encoding[resolved.interval.channel].scale,
+          capSize: appearance.capSize,
+          stroke: appearance.stroke,
+          strokeWidth: appearance.strokeWidth,
+          strokeDash: appearance.strokeDash,
+          opacity: appearance.opacity
+        });
+      }
+    }
+    return next._withMarkConfig(resolved.id, {
+      ...next.markConfigs[resolved.id],
+      errorBar: {
         data: resolved.dataId,
         orientation: resolved.orientation,
         positionField: resolved.position.field,
         positionFieldType: resolved.position.fieldType,
-        intervalField: field,
+        lowerField: resolved.fields.lower,
+        upperField: resolved.fields.upper,
         coordinate: resolved.coordinate,
         positionScale: intervalLayer.encoding[resolved.position.channel].scale,
         intervalScale: intervalLayer.encoding[resolved.interval.channel].scale,
-        capSize: appearance.capSize,
-        stroke: appearance.stroke,
-        strokeWidth: appearance.strokeWidth,
-        strokeDash: appearance.strokeDash,
-        opacity: appearance.opacity
-      });
-    }
-    return next;
+        lowerCapId: resolved.lowerCapId,
+        upperCapId: resolved.upperCapId,
+        ...appearance
+      }
+    });
   }
 );

package/src/actions/errorBars/edit.js

@@ -0,0 +1,130 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { findLayer, resolveEligibleLayer } from "../../selectors/layers.js";
+import {
+  ERROR_BAR_EDIT_OPTIONS,
+  resolveErrorBarAppearance
+} from "./options.js";
+
+const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+
+function resolveOwner(program, requested) {
+  const target = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Error-bar id");
+  return resolveEligibleLayer(program, {
+    target,
+    label: "error bar",
+    predicate: layer =>
+      layer.mark?.type === "rule" &&
+      program.markConfigs[layer.id]?.errorBar !== undefined
+  });
+}
+
+function removeCap(program, id) {
+  if (findLayer(program, id) === undefined) return program;
+  return program
+    .editSemantic({ property: `layer[${id}]`, remove: true })
+    .editGraphics({ target: id, remove: true })
+    ._withoutMaterializationConfig(["marks", id]);
+}
+
+function capArgs(config, id, intervalField) {
+  return {
+    id,
+    data: config.data,
+    orientation: config.orientation,
+    positionField: config.positionField,
+    positionFieldType: config.positionFieldType,
+    intervalField,
+    coordinate: config.coordinate,
+    positionScale: config.positionScale,
+    intervalScale: config.intervalScale,
+    capSize: config.capSize,
+    stroke: config.stroke,
+    strokeWidth: config.strokeWidth,
+    strokeDash: config.strokeDash,
+    opacity: config.opacity
+  };
+}
+
+function rematerializeRuleAppearance(program, id, config, fixedSpan) {
+  return program
+    .editSemantic({
+      property: `layer[${id}].encoding.strokeDash.datum`,
+      value: config.strokeDash
+    })
+    ._withMarkConfig(id, {
+      ...program.markConfigs[id],
+      stroke: config.stroke,
+      strokeWidth: config.strokeWidth,
+      strokeDash: config.strokeDash,
+      opacity: config.opacity,
+      ...(fixedSpan === undefined ? {} : { fixedSpan })
+    })
+    .rematerializeRuleMark({ id });
+}
+
+export const rematerializeErrorBar = action(
+  {
+    op: "rematerializeErrorBar",
+    description: "Reconcile one error bar and its owned caps."
+  },
+  function (args = {}) {
+    validateKeys(args, REMATERIALIZE_OPTIONS, "rematerializeErrorBar");
+    const id = validateUserId(args.id, "Error-bar id");
+    const layer = findLayer(this, id);
+    const config = this.markConfigs[id]?.errorBar;
+    if (layer?.mark?.type !== "rule" || config === undefined) {
+      throw new Error(`Unknown error bar "${id}".`);
+    }
+    let next = rematerializeRuleAppearance(this, id, config);
+    const capDefinitions = [
+      [config.lowerCapId, config.lowerField],
+      [config.upperCapId, config.upperField]
+    ];
+    if (!config.caps) {
+      for (const [capId] of capDefinitions) next = removeCap(next, capId);
+      return next;
+    }
+    const span = {
+      orientation: config.orientation === "vertical" ? "horizontal" : "vertical",
+      size: config.capSize
+    };
+    for (const [capId, field] of capDefinitions) {
+      if (findLayer(next, capId) === undefined) {
+        next = next.createErrorBarCap(capArgs(config, capId, field));
+      } else {
+        next = rematerializeRuleAppearance(next, capId, config, span);
+      }
+    }
+    return next;
+  }
+);
+
+export const editErrorBar = action(
+  {
+    op: "editErrorBar",
+    description: "Edit one error bar and its owned cap appearance."
+  },
+  function (args = {}) {
+    validateKeys(args, ERROR_BAR_EDIT_OPTIONS, "editErrorBar");
+    const editable = ERROR_BAR_EDIT_OPTIONS.filter(option => option !== "target");
+    if (!editable.some(option => Object.hasOwn(args, option))) {
+      throw new Error("editErrorBar requires at least one appearance change.");
+    }
+    const owner = resolveOwner(this, args.target);
+    const current = this.markConfigs[owner.id].errorBar;
+    const appearance = resolveErrorBarAppearance(args, {
+      defaults: current,
+      operation: "editErrorBar"
+    });
+    return this
+      ._withMarkConfig(owner.id, {
+        ...this.markConfigs[owner.id],
+        errorBar: { ...current, ...appearance }
+      })
+      .rematerializeErrorBar({ id: owner.id });
+  }
+);

package/src/actions/errorBars/index.js

@@ -1,7 +1,10 @@
 import { createErrorBarCap } from "./components.js";
 import { createErrorBar } from "./create.js";
+import { editErrorBar, rematerializeErrorBar } from "./edit.js";
 
 export function registerErrorBarActions(ProgramClass) {
   ProgramClass.prototype.createErrorBarCap = createErrorBarCap;
   ProgramClass.prototype.createErrorBar = createErrorBar;
+  ProgramClass.prototype.editErrorBar = editErrorBar;
+  ProgramClass.prototype.rematerializeErrorBar = rematerializeErrorBar;
 }

package/src/actions/errorBars/options.js

@@ -0,0 +1,52 @@
+import {
+  validateKeys,
+  validatePositiveFinite
+} from "../../core/validation.js";
+import {
+  normalizeStrokeDashPattern,
+  validateOpacityValue
+} from "../../grammar/scales.js";
+import {
+  validateRuleStroke,
+  validateRuleStrokeWidth
+} from "../../grammar/ruleAppearance.js";
+
+export const ERROR_BAR_EDIT_OPTIONS = Object.freeze([
+  "target", "caps", "capSize", "stroke", "strokeWidth",
+  "strokeDash", "opacity"
+]);
+
+export function resolveErrorBarAppearance(args, {
+  defaults,
+  operation
+}) {
+  validateKeys(args, ERROR_BAR_EDIT_OPTIONS, operation);
+  const caps = args.caps ?? defaults.caps;
+  if (typeof caps !== "boolean") {
+    throw new TypeError(`${operation} caps must be a boolean.`);
+  }
+  const capSize = args.capSize ?? defaults.capSize;
+  validatePositiveFinite(capSize, `${operation} capSize`);
+  const stroke = validateRuleStroke(
+    args.stroke ?? defaults.stroke,
+    `${operation} stroke`
+  );
+  const strokeWidth = validateRuleStrokeWidth(
+    args.strokeWidth ?? defaults.strokeWidth,
+    `${operation} strokeWidth`
+  );
+  const strokeDash = args.strokeDash ?? defaults.strokeDash;
+  normalizeStrokeDashPattern(strokeDash);
+  const opacity = validateOpacityValue(
+    args.opacity ?? defaults.opacity,
+    `${operation} opacity`
+  );
+  return {
+    caps,
+    capSize,
+    stroke,
+    strokeWidth,
+    strokeDash,
+    opacity
+  };
+}

package/src/actions/facets/actions.js

@@ -0,0 +1,162 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateOptionObject,
+  validatePositiveFinite
+} from "../../core/validation.js";
+import { resolveFacetDefinition } from "../../grammar/facets.js";
+import { normalizeFacetScalePolicies } from
+  "../../grammar/facets/scales.js";
+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 { rebindLayerData, replayDerivedData } from "./replay.js";
+import { composeFacetGuides } from "./guides.js";
+
+const FACET_OPTIONS = Object.freeze([
+  "id", "field", "data", "columns", "gap", "align", "padding", "scales",
+  "guides"
+]);
+const GUIDE_OPTIONS = Object.freeze(["axes", "legend"]);
+const HEADER_OPTIONS = Object.freeze([
+  "fontSize", "fontFamily", "fontWeight", "color", "offset"
+]);
+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 };
+  validateOptionObject(guides, GUIDE_OPTIONS, "facet.guides");
+  const axes = guides.axes ?? "each";
+  if (!["each", "outer"].includes(axes)) {
+    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".');
+  }
+  return { axes, legend };
+}
+
+function normalizeHeaderPatch(args, previous) {
+  validateOptionObject(args, HEADER_OPTIONS, "editFacetHeaders", {
+    allowEmpty: false,
+    emptyMessage: "editFacetHeaders requires at least one change."
+  });
+  const next = { ...previous, ...args };
+  validatePositiveFinite(next.fontSize, "Facet header fontSize");
+  validateNonEmptyString(next.fontFamily, "Facet header fontFamily");
+  validateNonEmptyString(next.color, "Facet header color");
+  validateNonNegativeFinite(next.offset, "Facet header offset");
+  if (!(
+    (typeof next.fontWeight === "string" && next.fontWeight.length > 0) ||
+    Number.isFinite(next.fontWeight)
+  )) {
+    throw new TypeError("Facet header fontWeight must be a non-empty string or number.");
+  }
+  return next;
+}
+
+function requireFacetProgram(program, operation) {
+  program._assertCompositionProgram(operation);
+  if (program.compositionSpec.type !== "facet") {
+    throw new Error(`${operation} requires a facet composition.`);
+  }
+}
+
+export const facet = action(
+  {
+    op: "facet",
+    description: "Repeat one direct-source chart by field value."
+  },
+  function (args = {}) {
+    validateOptionObject(args, FACET_OPTIONS, "facet");
+    const guides = normalizeGuides(args.guides);
+    const definition = resolveFacetDefinition(this.semanticSpec, args);
+    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
+      }
+    };
+    let next = this
+      ._withCompositionState({
+        children: derived.children,
+        compositionSpec
+      })
+      ._withMaterializationConfig(["facets", definition.id], {
+        headers: DEFAULT_HEADERS
+      });
+    for (const id of compositionSpec.children) {
+      next = next.useProgram({ id });
+    }
+    return next.materializeComposition();
+  }
+);
+
+export const editFacetHeaders = action(
+  {
+    op: "editFacetHeaders",
+    description: "Edit parent-owned facet header appearance.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    requireFacetProgram(this, "editFacetHeaders");
+    const id = this.compositionSpec.id;
+    const config = this.materializationConfigs.facets?.[id];
+    if (!isPlainObject(config?.headers)) {
+      throw new Error(`Facet "${id}" requires header configuration.`);
+    }
+    const headers = normalizeHeaderPatch(args, config.headers);
+    return this
+      ._withMaterializationConfig(["facets", id], { ...config, headers })
+      .materializeComposition();
+  }
+);
+
+export function registerFacetActions(ProgramClass) {
+  ProgramClass.prototype.replayDerivedData = replayDerivedData;
+  ProgramClass.prototype.rebindLayerData = rebindLayerData;
+  ProgramClass.prototype.composeFacetGuides = composeFacetGuides;
+  ProgramClass.prototype.facet = facet;
+  ProgramClass.prototype.editFacetHeaders = editFacetHeaders;
+}

package/src/actions/facets/derive.js

@@ -0,0 +1,200 @@
+import { freezeOwned } from "../../core/immutable.js";
+import { resolveHistogramBins } from "../../grammar/histogram.js";
+import { readQuantitativeField } from "../../grammar/scales.js";
+import { BAR_GRAINS, resolveBarGrain } from "../../grammar/bars/policy.js";
+import { resolveFacetScaleDomains } from "../../grammar/facets/scales.js";
+import {
+  applyMaterializationPlan,
+  planScaleGuideRematerialization
+} from "../../materialization/dependencies.js";
+import { getMarkMaterializationStep } from "../../materialization/marks.js";
+import { buildMaterializationPlan } from "../../materialization/planner.js";
+import { requireDataset } from "../../selectors/datasets.js";
+import { requireLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+
+function sharedHistogramBoundaries(program) {
+  const boundaries = new Map();
+  for (const layer of program.semanticSpec.layers) {
+    if (
+      layer.mark?.type !== "bar" ||
+      resolveBarGrain(layer) !== BAR_GRAINS.histogram
+    ) {
+      continue;
+    }
+    const x = layer.encoding.x;
+    const scale = findSemanticScale(program, x.scale);
+    const dataset = requireDataset(program, layer.data);
+    const values = readQuantitativeField(dataset.values, x.field);
+    boundaries.set(layer.id, resolveHistogramBins({
+      values,
+      bin: x.bin,
+      domain: scale.domain,
+      nice: scale.nice ?? true,
+      zero: scale.zero ?? false
+    }).boundaries);
+  }
+  return boundaries;
+}
+
+function applySharedHistogramBoundaries(program, layerId, boundaries) {
+  if (boundaries === undefined) return program;
+  const layer = requireLayer(program, layerId);
+  let next = program;
+  for (const property of ["maxBins", "step"]) {
+    if (Object.hasOwn(layer.encoding.x.bin, property)) {
+      next = next.editSemantic({
+        property: `layer[${layerId}].encoding.x.bin.${property}`,
+        remove: true
+      });
+    }
+  }
+  return next.editSemantic({
+    property: `layer[${layerId}].encoding.x.bin.boundaries`,
+    value: boundaries
+  });
+}
+
+function replayDatasetId(cell, owner) {
+  return `${cell.id}-${owner}-data`;
+}
+
+function cellMaterializationPlan(program) {
+  const scaleIds = [...new Set(program.semanticSpec.layers.flatMap(layer =>
+    Object.values(layer.encoding ?? {})
+      .map(encoding => encoding?.scale)
+      .filter(id => id !== undefined)
+  ))];
+  const scales = scaleIds.map(id => ({
+    op: "rematerializeScale",
+    args: { id, guides: false, marks: false }
+  }));
+  return buildMaterializationPlan({ scales });
+}
+
+function deriveCellProgram(base, definition, cell, histogramBoundaries) {
+  let child = base.filterData({
+    id: cell.data,
+    source: definition.data,
+    field: definition.field,
+    oneOf: [cell.value]
+  });
+  const datasets = new Map([[definition.data, cell.data]]);
+  for (const replay of definition.dependencies.replay) {
+    const source = datasets.get(replay.source);
+    if (source === undefined) {
+      throw new Error(
+        `Facet replay source "${replay.source}" is not available in cell "${cell.id}".`
+      );
+    }
+    const id = replayDatasetId(cell, replay.id);
+    child = child.replayDerivedData({
+      id,
+      source,
+      transform: replay.transform
+    });
+    datasets.set(replay.id, id);
+  }
+  for (const layer of definition.dependencies.layers) {
+    const data = datasets.get(layer.data);
+    if (data === undefined) {
+      throw new Error(
+        `Facet layer "${layer.id}" has no replayed dataset in cell "${cell.id}".`
+      );
+    }
+    child = child.rebindLayerData({ id: layer.id, data });
+    child = applySharedHistogramBoundaries(
+      child,
+      layer.id,
+      histogramBoundaries.get(layer.id)
+    );
+  }
+  return applyMaterializationPlan(child, cellMaterializationPlan(child));
+}
+
+function applyResolvedDomains(program, childId, resolution, baseResolved) {
+  let next = program;
+  for (const [id, scaleResolution] of Object.entries(resolution.scales)) {
+    const current = next.resolvedScales[id];
+    if (current === undefined) {
+      throw new Error(`Facet child "${childId}" is missing resolved scale "${id}".`);
+    }
+    const shared = scaleResolution.policy === "shared"
+      ? baseResolved?.[id]
+      : undefined;
+    next = next._withResolvedScale(id, {
+      ...current,
+      ...shared,
+      domain: scaleResolution.childDomains[childId]
+    });
+  }
+  const marks = next.semanticSpec.layers.flatMap(layer => {
+    const step = getMarkMaterializationStep(next, layer);
+    if (step === undefined) return [];
+    return ["bar", "line", "area"].includes(layer.mark?.type)
+      ? [{ ...step, args: { ...step.args, scales: false } }]
+      : [step];
+  });
+  const guides = Object.keys(resolution.scales).flatMap(id =>
+    planScaleGuideRematerialization(next, id)
+  );
+  return applyMaterializationPlan(
+    next,
+    buildMaterializationPlan({ marks, guides })
+  );
+}
+
+export function deriveFacetChildren(
+  base,
+  definition,
+  {
+    closeInheritedAction = false,
+    stripTitle = false,
+    scales = {}
+  } = {}
+) {
+  const template = stripTitle && base.semanticSpec.title.text !== undefined
+    ? base.removeTitle()
+    : base;
+  const resolutionRequest = scales ?? {};
+  const xPolicy = resolutionRequest.x ?? "shared";
+  const bins = xPolicy === "shared"
+    ? sharedHistogramBoundaries(template)
+    : new Map();
+  const independentlyResolved = Object.fromEntries(definition.cells.map(cell => [
+    cell.id,
+    deriveCellProgram(template, definition, cell, bins)
+  ]));
+  const resolution = resolveFacetScaleDomains(
+    template.semanticSpec,
+    Object.fromEntries(Object.entries(independentlyResolved).map(([id, child]) => [
+      id,
+      child.resolvedScales
+    ])),
+    resolutionRequest,
+    template.resolvedScales
+  );
+  const resolvedChildren = Object.fromEntries(
+    Object.entries(independentlyResolved).map(([id, child]) => [
+      id,
+      applyResolvedDomains(child, id, resolution, template.resolvedScales)
+    ])
+  );
+  const sharedScales = Object.fromEntries(
+    Object.entries(resolution.scales)
+      .filter(([, value]) => value.policy === "shared")
+      .map(([id]) => [id, resolvedChildren[definition.cells[0].id].resolvedScales[id]])
+  );
+  return freezeOwned({
+    children: freezeOwned(Object.fromEntries(
+      Object.entries(resolvedChildren).map(([id, child]) => [
+        id,
+        closeInheritedAction
+          ? child._exitAction()
+          : child
+      ])
+    )),
+    sharedScales: freezeOwned(sharedScales),
+    resolution
+  });
+}

package/src/actions/facets/guides.js

@@ -0,0 +1,16 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+import { applyFacetGuideComposition } from
+  "../../materialization/facetGuides.js";
+
+export const composeFacetGuides = action(
+  {
+    op: "composeFacetGuides",
+    description: "Apply outer-axis ownership and promote shared facet legends.",
+    scope: "composition"
+  },
+  function ({ layout, plot } = {}) {
+    validateKeys({ layout, plot }, ["layout", "plot"], "composeFacetGuides");
+    return applyFacetGuideComposition(this, { layout, plot });
+  }
+);