ggaction 0.0.1

package/src/actions/guides/legends/categorical/actions.js

@@ -0,0 +1,329 @@
+import { action } from "../../../../core/action.js";
+import { isPlainObject } from "../../../../core/immutable.js";
+import { noOptions, resolveLayout, activeConfig } from "./layout.js";
+import { normalizeOptions } from "./options.js";
+import { findLayer } from "../../../../selectors/layers.js";
+import { findSemanticScale } from "../../../../selectors/scales.js";
+import {
+  resolveCurrentDefinition,
+  resolveDefinition,
+  resolveLegendKind,
+  resolveTarget,
+  sameValues
+} from "./resolve.js";
+
+export const rematerializeLegend = action(
+  { op: "rematerializeLegend", description: "Rematerialize every existing legend component." },
+  function (args = {}) {
+    noOptions(args, "rematerializeLegend");
+    let next = this;
+    const hasCategorical =
+      this.guideConfigs.legend?.series !== undefined ||
+      this.guideConfigs.legend?.color !== undefined;
+    if (hasCategorical) {
+      const { kind, config } = activeConfig(this);
+      const definition = resolveCurrentDefinition(this, config);
+      const changed =
+        !sameValues(config.channels, definition.channels) ||
+        !sameValues(config.domain, definition.domain) ||
+        !sameValues(config.scales, definition.scales) ||
+        config.field !== definition.field ||
+        config.title !== definition.title;
+      next = changed
+        ? this._withLegendConfig(kind, {
+            ...config,
+            channels: definition.channels,
+            scales: definition.scales,
+            field: definition.field,
+            title: definition.title,
+            domain: definition.domain
+          })
+        : this;
+      if (kind === "series") {
+        if (!sameValues(
+          this.semanticSpec.guides.legend.series.scales,
+          definition.scales
+        )) {
+          next = next.editSemantic({
+            property: "guide.legend.series.scales",
+            value: definition.scales
+          });
+        }
+        if (this.semanticSpec.guides.legend.series.title !== definition.title) {
+          next = next.editSemantic({
+            property: "guide.legend.series.title",
+            value: definition.title
+          });
+        }
+      } else {
+        if (this.semanticSpec.guides.legend.color.scale !== definition.scales[0]) {
+          next = next.editSemantic({
+            property: "guide.legend.color.scale",
+            value: definition.scales[0]
+          });
+        }
+        if (this.semanticSpec.guides.legend.color.title !== definition.title) {
+          next = next.editSemantic({
+            property: "guide.legend.color.title",
+            value: definition.title
+          });
+        }
+      }
+      if (config.border !== false) next = next.editLegendBackground();
+      next = next
+        .editLegendSymbols()
+        .editLegendLabels();
+      if (config.titleVisible !== false) next = next.editLegendTitle();
+      const hasHighlight = Object.values(
+        next.materializationConfigs.highlights ?? {}
+      ).some(highlight => highlight.target === config.target);
+      if (hasHighlight) next = next.rematerializeLegendHighlights();
+    }
+    if (this.guideConfigs.legend?.size !== undefined) {
+      next = next.rematerializeSizeLegend();
+    }
+    if (this.guideConfigs.legend?.gradient !== undefined) {
+      next = next.rematerializeGradientLegend();
+    }
+    if (this.guideConfigs.legend?.interval !== undefined) {
+      next = next.rematerializeIntervalLegend();
+    }
+    if (this.guideConfigs.legend?.opacity !== undefined) {
+      next = next.rematerializeOpacityLegend();
+    }
+    return next;
+  }
+);
+
+export const createCategoricalLegend = action(
+  { op: "createCategoricalLegend", description: "Create one categorical legend block." },
+  function (args = {}) {
+    const layer = resolveTarget(this, args.target);
+    const kind = resolveLegendKind(layer, args.channels);
+    const options = normalizeOptions(args, kind);
+    if (
+      this.semanticSpec.guides.legend?.series !== undefined ||
+      this.semanticSpec.guides.legend?.color !== undefined
+    ) {
+      throw new Error("createCategoricalLegend requires a missing legend.");
+    }
+    const definition = resolveDefinition(
+      this,
+      layer,
+      options.channels,
+      options.title
+    );
+    const config = {
+      target: layer.id,
+      ...definition,
+      inferredTitle: !Object.hasOwn(args, "title"),
+      position: options.position,
+      align: options.align,
+      direction: options.direction,
+      columns: options.columns,
+      offset: options.offset,
+      titlePosition: options.titlePosition,
+      symbol: options.symbol,
+      labels: options.labels,
+      titleStyle: options.titleStyle,
+      itemGap: options.itemGap,
+      bottomGrid: options.bottomGrid,
+      border: options.border,
+      titleVisible: true
+    };
+    resolveLayout(this, config);
+    let next = this;
+    if (kind === "series") {
+      next = next
+        .editSemantic({
+          property: "guide.legend.series.channels",
+          value: definition.channels
+        })
+        .editSemantic({
+          property: "guide.legend.series.scales",
+          value: definition.scales
+        })
+        .editSemantic({
+          property: "guide.legend.series.title",
+          value: definition.title
+        });
+    } else {
+      next = next
+        .editSemantic({
+          property: "guide.legend.color.scale",
+          value: definition.scales[0]
+        })
+        .editSemantic({
+          property: "guide.legend.color.title",
+          value: definition.title
+        });
+    }
+    next = next._withLegendConfig(kind, config);
+    if (config.border !== false) next = next.createLegendBackground();
+    return next
+      .createLegendSymbols()
+      .createLegendLabels()
+      .createLegendTitle();
+  }
+);
+
+export const createLegend = action(
+  { op: "createLegend", description: "Create an inferred legend for selected channels." },
+  function (args = {}) {
+    if (!isPlainObject(args)) {
+      throw new TypeError("createLegend options must be a plain object.");
+    }
+    const channels = args.channels;
+    if (channels !== undefined && !Array.isArray(channels)) {
+      throw new TypeError("createLegend channels must be an array.");
+    }
+    const opacityCandidates = this.semanticSpec.layers.filter(layer =>
+      layer.mark?.type === "point" && layer.encoding?.opacity?.scale !== undefined
+    );
+    const hasOtherLegendCandidate = this.semanticSpec.layers.some(layer =>
+      ["color", "shape", "strokeDash", "size"].some(channel =>
+        layer.encoding?.[channel]?.scale !== undefined
+      )
+    );
+    if (
+      (channels?.length === 1 && channels[0] === "opacity") ||
+      (channels === undefined && opacityCandidates.length === 1 &&
+        !hasOtherLegendCandidate)
+    ) {
+      return this.createOpacityLegend(args);
+    }
+    const continuousColorCandidates = this.semanticSpec.layers.filter(layer => {
+      const encoding = ["point", "bar"].includes(layer.mark?.type)
+        ? layer.encoding?.color
+        : undefined;
+      const scale = findSemanticScale(this, encoding?.scale);
+      return scale?.type === "sequential";
+    });
+    const continuousColor = args.target === undefined
+      ? continuousColorCandidates.length === 1
+        ? continuousColorCandidates[0]
+        : undefined
+      : (() => {
+          const layer = findLayer(this, args.target);
+          return continuousColorCandidates.includes(layer) ? layer : undefined;
+        })();
+    if (
+      (channels?.length === 1 && channels[0] === "color" && continuousColor) ||
+      (channels === undefined && continuousColor)
+    ) {
+      return this.createGradientLegend(args);
+    }
+    const intervalColorCandidates = this.semanticSpec.layers.filter(layer => {
+      const encoding = layer.mark?.type === "point" ? layer.encoding?.color : undefined;
+      const scale = findSemanticScale(this, encoding?.scale);
+      return ["quantize", "quantile", "threshold"].includes(scale?.type);
+    });
+    const intervalColor = args.target === undefined
+      ? intervalColorCandidates.length === 1
+        ? intervalColorCandidates[0]
+        : undefined
+      : (() => {
+          const layer = findLayer(this, args.target);
+          return intervalColorCandidates.includes(layer) ? layer : undefined;
+        })();
+    if (
+      (channels?.length === 1 && channels[0] === "color" &&
+        intervalColorCandidates.length > 0) ||
+      (channels === undefined && intervalColorCandidates.length > 0)
+    ) {
+      return this.createIntervalLegend(args);
+    }
+    const wantsShape = channels?.includes("shape") === true;
+    const pointCandidates = this.semanticSpec.layers.filter(layer =>
+      layer.mark?.type === "point" &&
+      layer.encoding?.shape?.scale !== undefined &&
+      (wantsShape || layer.encoding?.color?.scale !== undefined)
+    );
+    const requestedPoint = args.target === undefined
+      ? pointCandidates.length === 1 ? pointCandidates[0] : undefined
+      : (() => {
+          const layer = findLayer(this, args.target);
+          return pointCandidates.includes(layer) ? layer : undefined;
+        })();
+    if (requestedPoint !== undefined) {
+      const { count, ...categoricalArgs } = args;
+      if (
+        requestedPoint.encoding?.size?.scale !== undefined &&
+        categoricalArgs.position !== undefined &&
+        !["right", "left"].includes(categoricalArgs.position)
+      ) {
+        throw new Error(
+          "Combined point series and size legends currently require a side position."
+        );
+      }
+      const hasMatchingLine = this.semanticSpec.layers.some(candidate =>
+        candidate.mark?.type === "line" &&
+        candidate.encoding?.color?.field === requestedPoint.encoding.color.field &&
+        candidate.encoding.color.scale === requestedPoint.encoding.color.scale
+      );
+      const symbol = categoricalArgs.symbol ?? {
+        layers: [
+          ...(hasMatchingLine
+            ? [{ type: "line", length: 32, lineWidth: 3 }]
+            : []),
+          {
+            type: "point",
+            size: Math.sqrt(64 / Math.PI),
+            stroke: "white",
+            strokeWidth: 0
+          }
+        ]
+      };
+      const inferredChannels = ["color", "shape"].filter(
+        channel => requestedPoint.encoding?.[channel]?.scale !== undefined
+      );
+      let next = this.createCategoricalLegend({
+        ...categoricalArgs,
+        target: requestedPoint.id,
+        channels: categoricalArgs.channels ?? inferredChannels,
+        symbol
+      });
+      if (requestedPoint.encoding?.size?.scale !== undefined) {
+        next = next.createSizeLegend({
+          target: requestedPoint.id,
+          ...(count === undefined ? {} : { count }),
+          inheritAppearance:
+            categoricalArgs.position === "left" ||
+            categoricalArgs.labels !== undefined ||
+            categoricalArgs.titleStyle !== undefined
+        });
+        next = next.rematerializeLegend();
+      }
+      return next;
+    }
+    return this.createCategoricalLegend(args);
+  }
+);
+
+export const removeCategoricalLegend = action(
+  {
+    op: "removeCategoricalLegend",
+    description: "Remove the active categorical legend and its concrete components."
+  },
+  function (args = {}) {
+    noOptions(args, "removeCategoricalLegend");
+    const entries = ["series", "color"]
+      .filter(kind => this.guideConfigs.legend?.[kind] !== undefined);
+    if (entries.length === 0) return this;
+    if (entries.length !== 1) {
+      throw new Error("removeCategoricalLegend requires one active categorical legend.");
+    }
+    const kind = entries[0];
+    const prefix = kind === "series" ? "seriesLegend" : "colorLegend";
+    const targets = Object.keys(this.graphicSpec.objects)
+      .filter(id => id.startsWith(prefix));
+    let next = this.editSemantic({
+      property: `guide.legend.${kind}`,
+      remove: true
+    });
+    for (const target of targets) {
+      next = next.editGraphics({ target, remove: true });
+    }
+    return next._withoutMaterializationConfig(["guides", "legend", kind]);
+  }
+);

package/src/actions/guides/legends/categorical/components.js

@@ -0,0 +1,140 @@
+import { action } from "../../../../core/action.js";
+import { activeConfig, graphic, noOptions, resolveLayout } from "./layout.js";
+import { resolveLegendGraphicPlacement } from
+  "../../../../materialization/graphicHierarchy.js";
+
+export const editLegendLabels = action(
+  { op: "editLegendLabels", description: "Rematerialize categorical legend labels." },
+  function (args = {}) {
+    noOptions(args, "editLegendLabels");
+    const { config } = activeConfig(this);
+    const id = graphic(config, "Labels");
+    if (this.graphicSpec.objects[id]?.type !== "text") {
+      throw new Error("editLegendLabels requires existing legend labels.");
+    }
+    const layout = resolveLayout(this, config);
+    return this
+      .editGraphics({ target: id, property: "length", value: config.domain.length })
+      .editGraphics({ target: id, property: "x", value: layout.labelX })
+      .editGraphics({ target: id, property: "y", value: layout.itemY })
+      .editGraphics({ target: id, property: "text", value: config.domain.map(String) })
+      .editGraphics({ target: id, property: "fill", value: config.labels.color })
+      .editGraphics({ target: id, property: "fontSize", value: config.labels.fontSize })
+      .editGraphics({ target: id, property: "fontFamily", value: config.labels.fontFamily })
+      .editGraphics({ target: id, property: "fontWeight", value: config.labels.fontWeight })
+      .editGraphics({ target: id, property: "textAlign", value: "left" })
+      .editGraphics({ target: id, property: "textBaseline", value: "middle" });
+  }
+);
+
+export const createLegendLabels = action(
+  { op: "createLegendLabels", description: "Create categorical legend labels." },
+  function (args = {}) {
+    noOptions(args, "createLegendLabels");
+    const { config } = activeConfig(this);
+    const id = graphic(config, "Labels");
+    if (this.graphicSpec.objects[id] !== undefined) {
+      throw new Error("createLegendLabels requires missing legend labels.");
+    }
+    return this
+      .createGraphics({
+        id,
+        type: "text",
+        length: config.domain.length,
+        ...resolveLegendGraphicPlacement(this)
+      })
+      .editLegendLabels();
+  }
+);
+
+export const editLegendTitle = action(
+  { op: "editLegendTitle", description: "Rematerialize the categorical legend title." },
+  function (args = {}) {
+    noOptions(args, "editLegendTitle");
+    const { config } = activeConfig(this);
+    const id = graphic(config, "Title");
+    if (this.graphicSpec.objects[id]?.type !== "text") {
+      throw new Error("editLegendTitle requires an existing legend title.");
+    }
+    const layout = resolveLayout(this, config);
+    return this
+      .editGraphics({ target: id, property: "x", value: layout.titleX })
+      .editGraphics({ target: id, property: "y", value: layout.titleY })
+      .editGraphics({ target: id, property: "text", value: config.title })
+      .editGraphics({ target: id, property: "fill", value: config.titleStyle.color })
+      .editGraphics({ target: id, property: "fontSize", value: config.titleStyle.fontSize })
+      .editGraphics({ target: id, property: "fontFamily", value: config.titleStyle.fontFamily })
+      .editGraphics({ target: id, property: "fontWeight", value: config.titleStyle.fontWeight })
+      .editGraphics({
+        target: id,
+        property: "textAlign",
+        value: ["top", "bottom"].includes(config.position) &&
+          config.titlePosition === "top"
+          ? "center"
+          : "left"
+      })
+      .editGraphics({ target: id, property: "textBaseline", value: "middle" });
+  }
+);
+
+export const createLegendTitle = action(
+  { op: "createLegendTitle", description: "Create the categorical legend title." },
+  function (args = {}) {
+    noOptions(args, "createLegendTitle");
+    const { config } = activeConfig(this);
+    const id = graphic(config, "Title");
+    if (this.graphicSpec.objects[id] !== undefined) {
+      throw new Error("createLegendTitle requires a missing legend title.");
+    }
+    return this
+      .createGraphics({
+        id,
+        type: "text",
+        ...resolveLegendGraphicPlacement(this)
+      })
+      .editLegendTitle();
+  }
+);
+
+export const editLegendBackground = action(
+  { op: "editLegendBackground", description: "Rematerialize the legend background." },
+  function (args = {}) {
+    noOptions(args, "editLegendBackground");
+    const { config } = activeConfig(this);
+    if (config.border === false) {
+      throw new Error("editLegendBackground requires border configuration.");
+    }
+    const id = graphic(config, "Background");
+    if (this.graphicSpec.objects[id]?.type !== "rect") {
+      throw new Error("editLegendBackground requires an existing background.");
+    }
+    const layout = resolveLayout(this, config).background;
+    return this
+      .editGraphics({ target: id, property: "x", value: layout.x })
+      .editGraphics({ target: id, property: "y", value: layout.y })
+      .editGraphics({ target: id, property: "width", value: layout.width })
+      .editGraphics({ target: id, property: "height", value: layout.height })
+      .editGraphics({ target: id, property: "fill", value: config.border.background })
+      .editGraphics({ target: id, property: "stroke", value: config.border.color })
+      .editGraphics({ target: id, property: "strokeWidth", value: config.border.lineWidth });
+  }
+);
+
+export const createLegendBackground = action(
+  { op: "createLegendBackground", description: "Create the legend background rect." },
+  function (args = {}) {
+    noOptions(args, "createLegendBackground");
+    const { config } = activeConfig(this);
+    const id = graphic(config, "Background");
+    if (this.graphicSpec.objects[id] !== undefined) {
+      throw new Error("createLegendBackground requires a missing background.");
+    }
+    return this
+      .createGraphics({
+        id,
+        type: "rect",
+        ...resolveLegendGraphicPlacement(this)
+      })
+      .editLegendBackground();
+  }
+);

package/src/actions/guides/legends/categorical/index.js

@@ -0,0 +1,49 @@
+import {
+  createCategoricalLegend,
+  createLegend,
+  removeCategoricalLegend,
+  rematerializeLegend
+} from "./actions.js";
+import {
+  createLegendBackground,
+  createLegendLabels,
+  createLegendTitle,
+  editLegendBackground,
+  editLegendLabels,
+  editLegendTitle
+} from "./components.js";
+import {
+  createLegendSymbolLines,
+  createLegendSymbolPoints,
+  createLegendSymbolSwatches,
+  createLegendSymbols,
+  editLegendSymbolLines,
+  editLegendSymbolPoints,
+  editLegendSymbolSwatches,
+  editLegendSymbols,
+  rematerializeLegendHighlights
+} from "./symbols.js";
+import { editLegend } from "../edit.js";
+
+export function registerCategoricalLegendActions(ProgramClass) {
+  ProgramClass.prototype.createLegend = createLegend;
+  ProgramClass.prototype.editLegend = editLegend;
+  ProgramClass.prototype.createCategoricalLegend = createCategoricalLegend;
+  ProgramClass.prototype.removeCategoricalLegend = removeCategoricalLegend;
+  ProgramClass.prototype.createLegendBackground = createLegendBackground;
+  ProgramClass.prototype.editLegendBackground = editLegendBackground;
+  ProgramClass.prototype.createLegendSymbols = createLegendSymbols;
+  ProgramClass.prototype.editLegendSymbols = editLegendSymbols;
+  ProgramClass.prototype.rematerializeLegendHighlights = rematerializeLegendHighlights;
+  ProgramClass.prototype.createLegendSymbolLines = createLegendSymbolLines;
+  ProgramClass.prototype.editLegendSymbolLines = editLegendSymbolLines;
+  ProgramClass.prototype.createLegendSymbolPoints = createLegendSymbolPoints;
+  ProgramClass.prototype.editLegendSymbolPoints = editLegendSymbolPoints;
+  ProgramClass.prototype.createLegendSymbolSwatches = createLegendSymbolSwatches;
+  ProgramClass.prototype.editLegendSymbolSwatches = editLegendSymbolSwatches;
+  ProgramClass.prototype.createLegendLabels = createLegendLabels;
+  ProgramClass.prototype.editLegendLabels = editLegendLabels;
+  ProgramClass.prototype.createLegendTitle = createLegendTitle;
+  ProgramClass.prototype.editLegendTitle = editLegendTitle;
+  ProgramClass.prototype.rematerializeLegend = rematerializeLegend;
+}