ggaction 0.0.11 → 0.0.13

package/src/actions/facets/actions.js

@@ -1,12 +1,16 @@
 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 {
   FACET_SCALE_CHANNELS,
   normalizeFacetScalePolicies
@@ -16,14 +20,26 @@ 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 { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.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"
@@ -57,18 +73,32 @@ function requireFacetProgram(program, operation) {
   }
 }
 
+function usedFacetScalePolicies(program, policies) {
+  return Object.fromEntries(FACET_SCALE_CHANNELS.flatMap(channel =>
+    program.semanticSpec.layers.some(
+      layer => layer.encoding?.[channel]?.scale !== undefined
+    ) ? [[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.guides === undefined
+        ? {}
+        : { guides: seed.materializationConfigs.guides }),
       canvas: seed.materializationConfigs.canvas
     }),
     children: {},
@@ -81,19 +111,48 @@ 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
-  });
+  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 = Object.fromEntries(FACET_SCALE_CHANNELS.flatMap(channel =>
     program.semanticSpec.layers.some(
       layer => layer.encoding?.[channel]?.scale !== undefined
     ) ? [[channel, scales[channel]]] : []
   ));
   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 +165,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);
@@ -170,6 +233,242 @@ 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");
+  if (!["x", "y"].includes(args.channel)) {
+    throw new Error('repeatCharts channel must be "x" or "y".');
+  }
+  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 eligible = program.semanticSpec.layers.filter(layer =>
+    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)
+  );
+  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 an eligible Cartesian mark.`);
+    }
+  } else if (eligible.length === 1) {
+    target = eligible[0].id;
+  } else {
+    throw new Error(
+      eligible.length === 0
+        ? "repeatCharts requires one complete Cartesian mark."
+        : "repeatCharts target is ambiguous; provide target."
+    );
+  }
+  if (program.semanticSpec.layers.length !== 1) {
+    throw new Error("repeatCharts currently supports one direct Cartesian 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 = layer.encoding[args.channel];
+  return {
+    id,
+    target,
+    channel: args.channel,
+    fields: [...args.fields],
+    data: layer.data,
+    encoding,
+    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 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,
+    template[definition.channel === "x" ? "encodeX" : "encodeY"](
+      repeatEncodingArgs(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 Cartesian chart across an ordered field 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.channel]: args.scales?.[definition.channel] ?? "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: DEFAULT_HEADERS
+      }),
+      { 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);
+    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: DEFAULT_HEADERS
+      }),
+      { children: derived.children, compositionSpec },
+      compositionSpec.children
+    );
+  }
+);
+
 export const editFacetHeaders = action(
   {
     op: "editFacetHeaders",
@@ -255,6 +554,9 @@ export const editFacetGuides = action(
     });
     const current = this.compositionSpec.facet;
     const guides = normalizeGuides({ ...current.guides, ...args });
+    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 +564,107 @@ 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.");
+  }
+  return new actionOwner.constructor({
+    semanticSpec: program.semanticSpec,
+    graphicSpec: program.graphicSpec,
+    resolvedScales: program.resolvedScales,
+    materializationConfigs: program.materializationConfigs,
+    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 revised;
+  }
+);
+
 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;
 }

package/src/actions/facets/derive.js

@@ -63,12 +63,30 @@ function deriveCellProgram(
   histogramBoundaries,
   scales
 ) {
-  let child = base.filterData({
-    id: cell.data,
-    source: definition.data,
+  const filters = cell.filters ?? [{
     field: definition.field,
-    oneOf: [cell.value]
-  });
+    value: cell.value
+  }];
+  let child = base;
+  let source = definition.data;
+  for (const [index, filter] of filters.entries()) {
+    const id = index === filters.length - 1
+      ? cell.data
+      : `${cell.id}-partition-${index + 1}-data`;
+    child = child.filterData({
+      id,
+      source,
+      field: filter.field,
+      oneOf: [filter.value]
+    });
+    source = id;
+  }
+  if (requireDataset(child, cell.data).values.length === 0) {
+    while (child.semanticSpec.layers.length > 0) {
+      child = child.removeMark({ target: child.semanticSpec.layers[0].id });
+    }
+    return child;
+  }
   const datasets = new Map([[definition.data, cell.data]]);
   for (const replay of definition.dependencies.replay) {
     const source = datasets.get(replay.source);
@@ -182,9 +200,35 @@ export function deriveFacetChildren(
     cell.id,
     deriveCellProgram(template, definition, cell, bins, scales)
   ]));
+  return resolveFacetChildrenScales(
+    template,
+    definition.cells.map(cell => cell.id),
+    independentlyResolved,
+    scales,
+    closeInheritedAction
+  );
+}
+
+export function resolveFacetChildrenScales(
+  template,
+  cellIds,
+  independentlyResolved,
+  scales = {},
+  closeInheritedAction = false
+) {
+  const populated = Object.fromEntries(cellIds.flatMap(id => {
+    const child = independentlyResolved[id];
+    if (child === undefined) {
+      throw new Error(`Facet derivation is missing child "${id}".`);
+    }
+    return child.semanticSpec.layers.length > 0 ? [[id, child]] : [];
+  }));
+  if (Object.keys(populated).length === 0) {
+    throw new Error("Facet derivation requires at least one populated cell.");
+  }
   const resolution = resolveFacetScaleDomains(
     template.semanticSpec,
-    Object.fromEntries(Object.entries(independentlyResolved).map(([id, child]) => [
+    Object.fromEntries(Object.entries(populated).map(([id, child]) => [
       id,
       child.resolvedScales
     ])),
@@ -192,7 +236,11 @@ export function deriveFacetChildren(
     template.resolvedScales
   );
   const resolvedChildren = Object.fromEntries(
-    Object.entries(independentlyResolved).map(([id, child]) => {
+    cellIds.map(id => {
+      const child = independentlyResolved[id];
+      if (child.semanticSpec.layers.length === 0) {
+        return [id, closeInheritedAction ? child._exitAction() : child];
+      }
       const resolved = applyResolvedDomains(
         child,
         id,
@@ -202,10 +250,11 @@ export function deriveFacetChildren(
       return [id, closeInheritedAction ? resolved._exitAction() : resolved];
     })
   );
+  const firstPopulatedId = Object.keys(populated)[0];
   const sharedScales = Object.fromEntries(
     Object.entries(resolution.scales)
       .filter(([, value]) => value.policy === "shared")
-      .map(([id]) => [id, resolvedChildren[definition.cells[0].id].resolvedScales[id]])
+      .map(([id]) => [id, resolvedChildren[firstPopulatedId].resolvedScales[id]])
   );
   return freezeOwned({
     children: freezeOwned(resolvedChildren),

package/src/actions/gradientPlots/components.js

@@ -1,3 +1,4 @@
+import { assertGuideOptions, guideConflict } from "../guides/reuse.js";
 import { action } from "../../core/action.js";
 import { validateKeys } from "../../core/validation.js";
 import { GRADIENT_PROFILE_FIELDS } from "../../grammar/gradientProfile.js";
@@ -120,23 +121,44 @@ export const rematerializeGradientPlotLegend = action(
   }
 );
 
+function resolveDensityLegend(program, args) {
+  validateKeys(args, LEGEND_OPTIONS, "createGradientPlotLegend");
+  requireLegendOwner(program, args.owner);
+  if (args.position !== undefined && args.position !== "right") {
+    throw new Error('Gradient plot density legend currently requires position "right".');
+  }
+  if (args.title !== undefined && (typeof args.title !== "string" || args.title.length === 0)) {
+    throw new TypeError("Gradient plot density legend title must be a non-empty string.");
+  }
+  const ids = legendIds(args.owner);
+  const densityScale = `${args.owner}Density`;
+  const title = args.title ?? "Relative density";
+  return { ids, densityScale, title };
+}
+
+export function fulfillGradientPlotLegend(program, args) {
+  const { ids, densityScale } = resolveDensityLegend(program, args);
+  const occupied = program.semanticSpec.guides.legend?.color;
+  if (occupied !== undefined && occupied.scale !== densityScale) {
+    guideConflict("Gradient plot density legend uses a different scale or family");
+  }
+  const existing = Object.values(ids).filter(id => program.graphicSpec.objects[id] !== undefined);
+  if (existing.length === 0) return program.createGradientPlotLegend(args);
+  if (existing.length !== Object.keys(ids).length || occupied?.scale !== densityScale) {
+    guideConflict("Gradient plot density legend has incomplete ownership");
+  }
+  const { owner, ...explicit } = args;
+  assertGuideOptions(explicit, program.markConfigs[owner].gradientPlot.guides.legend, "Gradient plot density legend");
+  return program;
+}
+
 export const createGradientPlotLegend = action(
   {
     op: "createGradientPlotLegend",
     description: "Create the neutral density legend owned by one gradient plot."
   },
   function (args = {}) {
-    validateKeys(args, LEGEND_OPTIONS, "createGradientPlotLegend");
-    requireLegendOwner(this, args.owner);
-    if (args.position !== undefined && args.position !== "right") {
-      throw new Error('Gradient plot density legend currently requires position "right".');
-    }
-    if (args.title !== undefined && (typeof args.title !== "string" || args.title.length === 0)) {
-      throw new TypeError("Gradient plot density legend title must be a non-empty string.");
-    }
-    const ids = legendIds(args.owner);
-    const densityScale = `${args.owner}Density`;
-    const title = args.title ?? "Relative density";
+    const { ids, densityScale, title } = resolveDensityLegend(this, args);
     let next = this;
     for (const [property, value] of [
       [`scale[${densityScale}].type`, "sequential"],

package/src/actions/gradientPlots/materialize.js

@@ -1,3 +1,5 @@
+import { applyFacadeGuides } from "../charts/shared.js";
+import { fulfillGradientPlotLegend } from "./components.js";
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { isPlainObject } from "../../core/immutable.js";
@@ -253,19 +255,15 @@ export const materializeGradientPlot = action(
     if (guides !== false) {
       const wantsStandard = guides.axes !== false || guides.grid !== false;
       if (wantsStandard) {
-        next = next.createGuides({
+        next = applyFacadeGuides(next, {
           axes: gradientAxesOptions(next.markConfigs[owner].gradientPlot),
           grid: guides.grid,
           legend: false
-        });
+        }, owner, guides);
       }
       if (guides.legend !== false) {
         const legend = isPlainObject(guides.legend) ? guides.legend : {};
-        next = next.createGradientPlotLegend({
-          owner,
-          title: legend.title ?? "Relative density",
-          position: legend.position ?? "right"
-        });
+        next = fulfillGradientPlotLegend(next, { owner, ...legend });
       }
     }
     return next._withContext({ currentMark: owner, currentData: layer.data });