ggaction 0.0.1

package/src/actions/guides/legends/continuous/interval.js

@@ -0,0 +1,234 @@
+import { action } from "../../../../core/action.js";
+import { isPlainObject } from "../../../../core/immutable.js";
+import { validateKeys } from "../../../../core/validation.js";
+import { formatDiscretizedIntervals } from "../../../../grammar/scales.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
+  "../../../../theme/defaults.js";
+import {
+  assertLegendInsideCanvas,
+  resolveContinuousBounds,
+  resolveContinuousPoint,
+  styleContinuousText,
+  validateNonNegative,
+  validatePositive
+} from "./common.js";
+import { resolveLegendGraphicPlacement } from
+  "../../../../materialization/graphicHierarchy.js";
+
+const OPTIONS = Object.freeze([
+  "target", "channels", "position", "align", "offset", "title",
+  "symbol", "labels", "titleStyle", "itemGap", "direction", "border"
+]);
+const SYMBOL_OPTIONS = Object.freeze([
+  "width", "height", "stroke", "strokeWidth"
+]);
+const TEXT_OPTIONS = Object.freeze([
+  "offset", "color", "fontSize", "fontFamily", "fontWeight"
+]);
+
+function textOptions(value, label, defaults) {
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  validateKeys(value ?? {}, TEXT_OPTIONS, label);
+  const result = { ...defaults, ...(value ?? {}) };
+  if (result.offset !== undefined) validateNonNegative(result.offset, `${label} offset`);
+  validatePositive(result.fontSize, `${label} fontSize`);
+  return result;
+}
+
+export function normalizeIntervalLegend(args) {
+  if (!isPlainObject(args)) {
+    throw new TypeError("createLegend options must be a plain object.");
+  }
+  validateKeys(args, OPTIONS, "createLegend");
+  if (args.channels !== undefined && (
+    !Array.isArray(args.channels) ||
+    args.channels.length !== 1 ||
+    args.channels[0] !== "color"
+  )) {
+    throw new Error('Interval legend requires channels: ["color"].');
+  }
+  if ((args.position ?? "right") !== "right") {
+    throw new Error('Interval legends currently support position "right".');
+  }
+  if ((args.direction ?? "vertical") !== "vertical") {
+    throw new Error('Interval legends currently support direction "vertical".');
+  }
+  if (args.border !== undefined && args.border !== false) {
+    throw new Error("Interval legend border is not implemented yet.");
+  }
+  if (args.symbol !== undefined && !isPlainObject(args.symbol)) {
+    throw new TypeError("createLegend.symbol must be a plain object.");
+  }
+  validateKeys(args.symbol ?? {}, SYMBOL_OPTIONS, "createLegend.symbol");
+  const symbol = {
+    width: args.symbol?.width ?? 14,
+    height: args.symbol?.height ?? 12,
+    stroke: args.symbol?.stroke ?? "white",
+    strokeWidth: args.symbol?.strokeWidth ?? 0.5
+  };
+  validatePositive(symbol.width, "Legend symbol width");
+  validatePositive(symbol.height, "Legend symbol height");
+  validateNonNegative(symbol.strokeWidth, "Legend symbol strokeWidth");
+  const offset = args.offset ?? 30;
+  const itemGap = args.itemGap ?? 28;
+  validateNonNegative(offset, "Legend offset");
+  validatePositive(itemGap, "Legend itemGap");
+  return {
+    target: args.target,
+    position: "right",
+    direction: "vertical",
+    align: args.align ?? "center",
+    offset,
+    itemGap,
+    title: args.title,
+    inferredTitle: args.title === undefined,
+    titleVisible: true,
+    symbol,
+    labels: textOptions(args.labels, "createLegend.labels", {
+      offset: 8,
+      color: DEFAULT_COLORS.text,
+      fontSize: 12,
+      fontFamily: DEFAULT_FONT_FAMILY,
+      fontWeight: "normal"
+    }),
+    titleStyle: textOptions(args.titleStyle, "createLegend.titleStyle", {
+      color: DEFAULT_COLORS.text,
+      fontSize: 13,
+      fontFamily: DEFAULT_FONT_FAMILY,
+      fontWeight: 600
+    }),
+    border: false
+  };
+}
+
+function resolveIntervalConfig(program, stored) {
+  const layer = resolveContinuousPoint(program, stored.target, "color");
+  const encoding = layer.encoding.color;
+  if (encoding.fieldType !== "quantitative") {
+    throw new Error("Interval legend requires quantitative color.");
+  }
+  const scale = program.resolvedScales[encoding.scale];
+  if (!["quantize", "quantile", "threshold"].includes(scale?.type)) {
+    throw new Error(`Interval legend requires a resolved discretized scale "${encoding.scale}".`);
+  }
+  return {
+    layer,
+    encoding,
+    scale,
+    config: {
+      ...stored,
+      target: layer.id,
+      scale: encoding.scale,
+      title: stored.inferredTitle ? encoding.field : stored.title
+    }
+  };
+}
+
+function resolveIntervalLayout(program, config, scale) {
+  const { plot, canvas } = resolveContinuousBounds(program);
+  const labels = formatDiscretizedIntervals(scale.thresholds);
+  const symbolX = plot.x + plot.width + config.offset;
+  const itemY = labels.map((_, index) => plot.y + 52 + index * config.itemGap);
+  const labelX = symbolX + config.symbol.width + config.labels.offset;
+  const title = { x: symbolX, y: plot.y + 20 };
+  assertLegendInsideCanvas([
+    title,
+    ...itemY.flatMap(y => [
+      { x: symbolX, y },
+      { x: labelX, y }
+    ])
+  ], canvas, "Interval legend layout");
+  return { labels, symbolX, labelX, itemY, title };
+}
+
+export const rematerializeIntervalLegend = action(
+  {
+    op: "rematerializeIntervalLegend",
+    description: "Rematerialize a discretized color interval legend."
+  },
+  function (args = {}) {
+    validateKeys(args, [], "rematerializeIntervalLegend");
+    const stored = this.guideConfigs.legend?.interval;
+    if (stored === undefined) {
+      throw new Error("Interval legend requires stored configuration.");
+    }
+    const { encoding, scale, config } = resolveIntervalConfig(this, stored);
+    const layout = resolveIntervalLayout(this, config, scale);
+    let next = this
+      .editSemantic({ property: "guide.legend.color.scale", value: encoding.scale })
+      .editSemantic({ property: "guide.legend.color.title", value: config.title })
+      ._withLegendConfig("interval", config)
+      .editGraphics({
+        target: "colorLegendSymbols",
+        property: "length",
+        value: scale.range.length
+      })
+      .editGraphics({ target: "colorLegendSymbols", property: "x", value: layout.symbolX })
+      .editGraphics({
+        target: "colorLegendSymbols",
+        property: "y",
+        value: layout.itemY.map(value => value - config.symbol.height / 2)
+      })
+      .editGraphics({ target: "colorLegendSymbols", property: "width", value: config.symbol.width })
+      .editGraphics({ target: "colorLegendSymbols", property: "height", value: config.symbol.height })
+      .editGraphics({ target: "colorLegendSymbols", property: "fill", value: scale.range })
+      .editGraphics({ target: "colorLegendSymbols", property: "stroke", value: config.symbol.stroke })
+      .editGraphics({ target: "colorLegendSymbols", property: "strokeWidth", value: config.symbol.strokeWidth })
+      .editGraphics({ target: "colorLegendLabels", property: "length", value: layout.labels.length })
+      .editGraphics({ target: "colorLegendLabels", property: "x", value: layout.labelX })
+      .editGraphics({ target: "colorLegendLabels", property: "y", value: layout.itemY })
+      .editGraphics({ target: "colorLegendLabels", property: "text", value: layout.labels });
+    next = styleContinuousText(next, "colorLegendLabels", config.labels);
+    if (config.titleVisible === false) return next;
+    next = next
+      .editGraphics({ target: "colorLegendTitle", property: "x", value: layout.title.x })
+      .editGraphics({ target: "colorLegendTitle", property: "y", value: layout.title.y })
+      .editGraphics({ target: "colorLegendTitle", property: "text", value: config.title });
+    return styleContinuousText(next, "colorLegendTitle", config.titleStyle);
+  }
+);
+
+export const createIntervalLegend = action(
+  {
+    op: "createIntervalLegend",
+    description: "Create a discretized color interval legend."
+  },
+  function (args = {}) {
+    const config = normalizeIntervalLegend(args);
+    const resolved = resolveIntervalConfig(this, config);
+    resolveIntervalLayout(this, resolved.config, resolved.scale);
+    if (this.graphicSpec.objects.colorLegendSymbols !== undefined) {
+      throw new Error("createIntervalLegend requires a missing interval legend.");
+    }
+    return this
+      .editSemantic({
+        property: "guide.legend.color.scale",
+        value: resolved.encoding.scale
+      })
+      .editSemantic({
+        property: "guide.legend.color.title",
+        value: resolved.config.title
+      })
+      ._withLegendConfig("interval", resolved.config)
+      .createGraphics({
+        id: "colorLegendSymbols",
+        type: "rect",
+        length: 0,
+        ...resolveLegendGraphicPlacement(this)
+      })
+      .createGraphics({
+        id: "colorLegendLabels",
+        type: "text",
+        length: 0,
+        ...resolveLegendGraphicPlacement(this)
+      })
+      .createGraphics({
+        id: "colorLegendTitle",
+        type: "text",
+        ...resolveLegendGraphicPlacement(this)
+      })
+      .rematerializeIntervalLegend();
+  }
+);

package/src/actions/guides/legends/continuous/opacity.js

@@ -0,0 +1,382 @@
+import { action } from "../../../../core/action.js";
+import { isPlainObject } from "../../../../core/immutable.js";
+import { validateKeys } from "../../../../core/validation.js";
+import { mapLinearValues } from "../../../../grammar/scales.js";
+import { DEFAULT_COLORS } from "../../../../theme/defaults.js";
+import {
+  assertLegendInsideCanvas,
+  editLegendBackground,
+  formatContinuousValues,
+  normalizeContinuousLegend,
+  requireResolvedLegendScale,
+  resolveContinuousBounds,
+  resolveContinuousPoint,
+  resolveLegendBackgroundBounds,
+  sampleContinuousValues,
+  styleContinuousText,
+  validateNonNegative,
+  validatePositive
+} from "./common.js";
+import { resolveLegendGraphicPlacement } from
+  "../../../../materialization/graphicHierarchy.js";
+
+const SYMBOL_OPTIONS = Object.freeze([
+  "type", "radius", "fill", "stroke", "strokeWidth"
+]);
+
+export function normalizeOpacitySymbol(value) {
+  if (value === undefined) {
+    return { type: "point", radius: 7, fill: DEFAULT_COLORS.mark };
+  }
+  if (!isPlainObject(value)) {
+    throw new TypeError("createLegend.symbol must be one point recipe object.");
+  }
+  validateKeys(value, SYMBOL_OPTIONS, "createLegend.symbol");
+  const symbol = {
+    type: "point",
+    radius: 7,
+    fill: DEFAULT_COLORS.mark,
+    ...value
+  };
+  if (symbol.type !== "point") {
+    throw new Error("Opacity legend symbol must have type point.");
+  }
+  validatePositive(symbol.radius, "Opacity legend symbol radius");
+  if (typeof symbol.fill !== "string" || symbol.fill.length === 0) {
+    throw new TypeError("Opacity legend symbol fill must be non-empty.");
+  }
+  if (symbol.stroke !== undefined && (
+    typeof symbol.stroke !== "string" || symbol.stroke.length === 0
+  )) {
+    throw new TypeError("Opacity legend symbol stroke must be non-empty.");
+  }
+  if (symbol.strokeWidth !== undefined) {
+    validateNonNegative(
+      symbol.strokeWidth,
+      "Opacity legend symbol strokeWidth"
+    );
+  }
+  return symbol;
+}
+
+function resolveOpacityConfig(program, config) {
+  const layer = resolveContinuousPoint(program, config.target, "opacity");
+  const encoding = layer.encoding.opacity;
+  if (encoding.fieldType !== "quantitative") {
+    throw new Error("Opacity legend requires quantitative field opacity.");
+  }
+  const scale = requireResolvedLegendScale(program, encoding.scale, "linear");
+  return {
+    layer,
+    encoding,
+    scale,
+    config: {
+      ...config,
+      target: layer.id,
+      scale: encoding.scale,
+      title: config.inferredTitle ? encoding.field : config.title,
+      domain: scale.domain
+    }
+  };
+}
+
+function resolveOpacityLayout(program, config, scale) {
+  const { plot, canvas } = resolveContinuousBounds(program);
+  const vertical = ["right", "left"].includes(config.position);
+  const values = sampleContinuousValues(scale.domain, config.count);
+  const radius = config.symbol.radius;
+  let symbols;
+  let labels;
+  let title;
+  if (vertical) {
+    const baseX = config.position === "right"
+      ? plot.x + plot.width + config.offset
+      : plot.x - config.offset;
+    const y = values.map((_, index) => plot.y + 46 + index * config.itemGap);
+    symbols = y.map(itemY => ({
+      x: config.position === "right" ? baseX + radius : baseX - radius,
+      y: itemY
+    }));
+    labels = y.map(itemY => ({
+      x: config.position === "right"
+        ? baseX + radius * 2 + config.labels.offset - 2
+        : baseX - radius * 2 - config.labels.offset + 2,
+      y: itemY,
+      align: config.position === "right" ? "left" : "right"
+    }));
+    title = {
+      x: config.position === "right" ? baseX : baseX - radius * 2,
+      y: plot.y + 20,
+      align: config.position === "right" ? "left" : "right"
+    };
+  } else {
+    const width = (values.length - 1) * Math.max(56, config.itemGap * 2);
+    const startX = config.align === "left" ? plot.x
+      : config.align === "right" ? plot.x + plot.width - width
+        : plot.x + (plot.width - width) / 2;
+    const y = config.position === "top"
+      ? plot.y - config.offset - radius
+      : plot.y + plot.height + config.offset + radius;
+    symbols = values.map((_, index) => ({
+      x: startX + index * width / (values.length - 1),
+      y
+    }));
+    labels = symbols.map(symbol => ({
+      x: symbol.x,
+      y: config.position === "top"
+        ? symbol.y - radius - config.labels.offset
+        : symbol.y + radius + config.labels.offset,
+      align: "center"
+    }));
+    title = { x: startX + width / 2, y: y - 26, align: "center" };
+  }
+  assertLegendInsideCanvas(
+    [title, ...symbols, ...labels],
+    canvas,
+    "Opacity legend layout"
+  );
+  const background = resolveLegendBackgroundBounds([
+    title,
+    ...symbols.map(symbol => ({
+      x: symbol.x + radius,
+      y: symbol.y + radius
+    })),
+    ...symbols.map(symbol => ({
+      x: symbol.x - radius,
+      y: symbol.y - radius
+    })),
+    ...labels.map(label => ({
+      x: label.x + (
+        label.align === "left" ? 42 : label.align === "right" ? -42 : 0
+      ),
+      y: label.y
+    }))
+  ], config.border, canvas, "Opacity legend");
+  return { values, symbols, labels, title, background };
+}
+
+export const rematerializeOpacityLegend = action(
+  {
+    op: "rematerializeOpacityLegend",
+    description: "Rematerialize a field-opacity sample legend."
+  },
+  function (args = {}) {
+    validateKeys(args, [], "rematerializeOpacityLegend");
+    const stored = this.guideConfigs.legend?.opacity;
+    if (stored === undefined) {
+      throw new Error("Opacity legend requires stored configuration.");
+    }
+    const { encoding, scale, config } = resolveOpacityConfig(this, stored);
+    const layout = resolveOpacityLayout(this, config, scale);
+    const opacities = mapLinearValues(layout.values, scale.domain, scale.range, {
+      clamp: scale.clamp ?? false
+    });
+    let next = this
+      .editSemantic({
+        property: "guide.legend.opacity.scale",
+        value: encoding.scale
+      })
+      .editSemantic({
+        property: "guide.legend.opacity.title",
+        value: config.title
+      })
+      ._withLegendConfig("opacity", config)
+      .editGraphics({
+        target: "opacityLegendSymbols",
+        property: "length",
+        value: layout.values.length
+      })
+      .editGraphics({
+        target: "opacityLegendSymbols",
+        property: "x",
+        value: layout.symbols.map(symbol => symbol.x)
+      })
+      .editGraphics({
+        target: "opacityLegendSymbols",
+        property: "y",
+        value: layout.symbols.map(symbol => symbol.y)
+      })
+      .editGraphics({
+        target: "opacityLegendSymbols",
+        property: "radius",
+        value: config.symbol.radius
+      })
+      .editGraphics({
+        target: "opacityLegendSymbols",
+        property: "fill",
+        value: config.symbol.fill
+      })
+      .editGraphics({
+        target: "opacityLegendSymbols",
+        property: "opacity",
+        value: opacities
+      })
+      .editGraphics({
+        target: "opacityLegendLabels",
+        property: "length",
+        value: layout.values.length
+      })
+      .editGraphics({
+        target: "opacityLegendLabels",
+        property: "x",
+        value: layout.labels.map(label => label.x)
+      })
+      .editGraphics({
+        target: "opacityLegendLabels",
+        property: "y",
+        value: layout.labels.map(label => label.y)
+      })
+      .editGraphics({
+        target: "opacityLegendLabels",
+        property: "text",
+        value: formatContinuousValues(
+          layout.values,
+          scale.domain,
+          "quantitative"
+        )
+      });
+    next = editLegendBackground(
+      next,
+      "opacityLegendBackground",
+      layout.background,
+      config.border
+    );
+    if (config.symbol.stroke !== undefined) {
+      next = next.editGraphics({
+        target: "opacityLegendSymbols",
+        property: "stroke",
+        value: config.symbol.stroke
+      });
+    }
+    if (config.symbol.strokeWidth !== undefined) {
+      next = next.editGraphics({
+        target: "opacityLegendSymbols",
+        property: "strokeWidth",
+        value: config.symbol.strokeWidth
+      });
+    }
+    next = styleContinuousText(
+      next,
+      "opacityLegendLabels",
+      config.labels,
+      { align: layout.labels[0].align }
+    );
+    if (config.titleVisible === false) return next;
+    next = next
+      .editGraphics({
+        target: "opacityLegendTitle",
+        property: "x",
+        value: layout.title.x
+      })
+      .editGraphics({
+        target: "opacityLegendTitle",
+        property: "y",
+        value: layout.title.y
+      })
+      .editGraphics({
+        target: "opacityLegendTitle",
+        property: "text",
+        value: config.title
+      });
+    return styleContinuousText(
+      next,
+      "opacityLegendTitle",
+      config.titleStyle,
+      { align: layout.title.align }
+    );
+  }
+);
+
+export const createOpacityLegend = action(
+  {
+    op: "createOpacityLegend",
+    description: "Create a field-opacity sample legend."
+  },
+  function (args = {}) {
+    const config = normalizeContinuousLegend(args, "opacity");
+    if (args.channels !== undefined && (
+      !Array.isArray(args.channels) ||
+      args.channels.length !== 1 ||
+      args.channels[0] !== "opacity"
+    )) {
+      throw new Error('Opacity legend requires channels: ["opacity"].');
+    }
+    config.symbol = normalizeOpacitySymbol(args.symbol);
+    config.titleVisible = true;
+    const resolved = resolveOpacityConfig(this, config);
+    resolveOpacityLayout(this, resolved.config, resolved.scale);
+    if (this.graphicSpec.objects.opacityLegendSymbols !== undefined) {
+      throw new Error(
+        "createOpacityLegend requires a missing opacity legend."
+      );
+    }
+    let next = this
+      .editSemantic({
+        property: "guide.legend.opacity.scale",
+        value: resolved.encoding.scale
+      })
+      .editSemantic({
+        property: "guide.legend.opacity.title",
+        value: resolved.config.title
+      })
+      ._withLegendConfig("opacity", resolved.config);
+    if (resolved.config.border !== false) {
+      next = next.createGraphics({
+        id: "opacityLegendBackground",
+        type: "rect",
+        ...resolveLegendGraphicPlacement(next)
+      });
+    }
+    return next
+      .createGraphics({
+        id: "opacityLegendSymbols",
+        type: "circle",
+        length: 0,
+        ...resolveLegendGraphicPlacement(next),
+        ...(resolved.config.border === false
+          ? {}
+          : { after: "opacityLegendBackground" })
+      })
+      .createGraphics({
+        id: "opacityLegendLabels",
+        type: "text",
+        length: 0,
+        ...resolveLegendGraphicPlacement(next)
+      })
+      .createGraphics({
+        id: "opacityLegendTitle",
+        type: "text",
+        ...resolveLegendGraphicPlacement(next)
+      })
+      .rematerializeOpacityLegend();
+  }
+);
+
+export const removeOpacityLegend = action(
+  {
+    op: "removeOpacityLegend",
+    description: "Remove a field-opacity legend after switching to constant opacity."
+  },
+  function (args = {}) {
+    validateKeys(args, [], "removeOpacityLegend");
+    if (this.guideConfigs.legend?.opacity === undefined) return this;
+    const targets = [
+      "opacityLegendBackground",
+      "opacityLegendSymbols",
+      "opacityLegendLabels",
+      "opacityLegendTitle"
+    ];
+    let next = this.editSemantic({
+      property: "guide.legend.opacity",
+      remove: true
+    });
+    for (const target of targets) {
+      if (next.graphicSpec.objects[target] !== undefined) {
+        next = next.editGraphics({ target, remove: true });
+      }
+    }
+    return next._withoutMaterializationConfig([
+      "guides", "legend", "opacity"
+    ]);
+  }
+);