ggaction 0.0.1

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

@@ -0,0 +1,273 @@
+import { isPlainObject } from "../../../../core/immutable.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validatePositiveFinite
+} from "../../../../core/validation.js";
+import { formatTimeTick } from "../../../../grammar/ticks.js";
+import { resolveGraphicBounds } from "../../../../layout/canvas.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
+  "../../../../theme/defaults.js";
+import { findLayer } from "../../../../selectors/layers.js";
+
+const OPTIONS = Object.freeze([
+  "target", "channels", "position", "align", "offset", "title", "count",
+  "gradient", "symbol", "labels", "titleStyle", "itemGap", "border",
+  "direction", "columns", "titlePosition"
+]);
+const TEXT_OPTIONS = Object.freeze([
+  "offset", "color", "fontSize", "fontFamily", "fontWeight"
+]);
+const BORDER_OPTIONS = Object.freeze([
+  "color", "lineWidth", "padding", "background"
+]);
+const POSITIONS = Object.freeze(["right", "left", "top", "bottom"]);
+const DEFAULT_LABELS = Object.freeze({
+  offset: 12,
+  color: DEFAULT_COLORS.text,
+  fontSize: 12,
+  fontFamily: DEFAULT_FONT_FAMILY,
+  fontWeight: "normal"
+});
+const DEFAULT_TITLE = Object.freeze({
+  color: DEFAULT_COLORS.text,
+  fontSize: 13,
+  fontFamily: DEFAULT_FONT_FAMILY,
+  fontWeight: 600
+});
+const DEFAULT_BORDER = Object.freeze({
+  color: DEFAULT_COLORS.border,
+  lineWidth: 1,
+  padding: 12,
+  background: "transparent"
+});
+
+export const validatePositive = validatePositiveFinite;
+export const validateNonNegative = validateNonNegativeFinite;
+
+function validateTextOptions(value, label, defaults) {
+  if (value === undefined) return { ...defaults };
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  validateKeys(value, TEXT_OPTIONS, label);
+  const result = { ...defaults, ...value };
+  if (Object.hasOwn(result, "offset")) {
+    validateNonNegative(result.offset, `${label} offset`);
+  }
+  validatePositive(result.fontSize, `${label} fontSize`);
+  for (const key of ["color", "fontFamily"]) {
+    validateNonEmptyString(result[key], `${label} ${key}`);
+  }
+  if (
+    typeof result.fontWeight !== "string" &&
+    !Number.isFinite(result.fontWeight)
+  ) {
+    throw new TypeError(`${label} fontWeight must be a string or finite number.`);
+  }
+  return result;
+}
+
+function normalizeBorder(value) {
+  if (value === undefined || value === false) return false;
+  if (value !== true && !isPlainObject(value)) {
+    throw new TypeError("createLegend.border must be a boolean or plain object.");
+  }
+  if (value !== true) validateKeys(value, BORDER_OPTIONS, "createLegend.border");
+  const border = { ...DEFAULT_BORDER, ...(value === true ? {} : value) };
+  for (const key of ["color", "background"]) {
+    validateNonEmptyString(border[key], `Legend border ${key}`);
+  }
+  validateNonNegative(border.lineWidth, "Legend border lineWidth");
+  validateNonNegative(border.padding, "Legend border padding");
+  return border;
+}
+
+export function normalizeContinuousLegend(args, kind) {
+  if (!isPlainObject(args)) {
+    throw new TypeError("createLegend options must be a plain object.");
+  }
+  validateKeys(args, OPTIONS, "createLegend");
+  const position = args.position ?? "right";
+  if (!POSITIONS.includes(position)) {
+    throw new Error(`Unsupported legend position "${position}".`);
+  }
+  const align = args.align ?? "center";
+  if (!["left", "center", "right"].includes(align)) {
+    throw new Error(`Unsupported legend alignment "${align}".`);
+  }
+  const count = args.count ?? 5;
+  if (!Number.isInteger(count) || count < 2) {
+    throw new RangeError(
+      "Continuous legend count must be an integer of at least 2."
+    );
+  }
+  const offset = args.offset ?? 30;
+  validateNonNegative(offset, "Legend offset");
+  const itemGap = args.itemGap ?? 28;
+  validatePositive(itemGap, "Legend itemGap");
+  if (args.title !== undefined) validateNonEmptyString(args.title, "Legend title");
+  if (args.titlePosition !== undefined && args.titlePosition !== "top") {
+    throw new Error("Continuous legends currently require top titlePosition.");
+  }
+  if (kind === "gradient") {
+    for (const key of ["symbol", "columns", "direction", "itemGap"]) {
+      if (Object.hasOwn(args, key)) {
+        throw new Error(`Gradient legend does not accept ${key}.`);
+      }
+    }
+  } else {
+    for (const key of ["columns", "direction", "gradient"]) {
+      if (Object.hasOwn(args, key)) {
+        throw new Error(`Opacity legend does not accept ${key}.`);
+      }
+    }
+  }
+  return {
+    target: args.target,
+    position,
+    align,
+    offset,
+    count,
+    title: args.title,
+    inferredTitle: args.title === undefined,
+    labels: validateTextOptions(
+      args.labels,
+      "createLegend.labels",
+      DEFAULT_LABELS
+    ),
+    titleStyle: validateTextOptions(
+      args.titleStyle,
+      "createLegend.titleStyle",
+      DEFAULT_TITLE
+    ),
+    itemGap,
+    border: normalizeBorder(args.border)
+  };
+}
+
+export function resolveContinuousPoint(program, requested, channel) {
+  const candidates = program.semanticSpec.layers.filter(layer =>
+    layer.mark?.type === "point" &&
+    layer.encoding?.[channel]?.scale !== undefined
+  );
+  const layer = requested === undefined
+    ? candidates.length === 1 ? candidates[0] : undefined
+    : (() => {
+        const candidate = findLayer(program, requested);
+        return candidates.includes(candidate) ? candidate : undefined;
+      })();
+  if (layer === undefined) {
+    throw new Error(
+      requested === undefined
+        ? `${channel} legend requires one eligible point mark.`
+        : `Unknown ${channel} legend target "${requested}".`
+    );
+  }
+  return layer;
+}
+
+export function resolveContinuousColorLayer(program, requested) {
+  const candidates = program.semanticSpec.layers.filter(layer =>
+    ["point", "bar"].includes(layer.mark?.type) &&
+    layer.encoding?.color?.scale !== undefined
+  );
+  const layer = requested === undefined
+    ? candidates.length === 1 ? candidates[0] : undefined
+    : (() => {
+        const candidate = findLayer(program, requested);
+        return candidates.includes(candidate) ? candidate : undefined;
+      })();
+  if (layer === undefined) {
+    throw new Error(
+      requested === undefined
+        ? "color legend requires one eligible point or bar mark."
+        : `Unknown color legend target "${requested}".`
+    );
+  }
+  return layer;
+}
+
+export function requireResolvedLegendScale(program, id, type) {
+  const scale = program.resolvedScales[id];
+  if (scale?.type !== type) {
+    throw new Error(`Legend requires resolved ${type} scale "${id}".`);
+  }
+  return scale;
+}
+
+export function resolveContinuousBounds(program) {
+  const plot = resolveGraphicBounds(program);
+  const canvas = program.graphicSpec.objects.canvas;
+  if (
+    plot === undefined ||
+    ![plot.x, plot.y, plot.width, plot.height].every(Number.isFinite) ||
+    canvas?.type !== "canvas" ||
+    !Number.isFinite(canvas.properties.width) ||
+    !Number.isFinite(canvas.properties.height)
+  ) {
+    throw new Error("Continuous legend layout requires Canvas bounds.");
+  }
+  return { plot, canvas: canvas.properties };
+}
+
+export function sampleContinuousValues(domain, count) {
+  return Array.from({ length: count }, (_, index) =>
+    domain[0] + index / (count - 1) * (domain[1] - domain[0])
+  );
+}
+
+export function formatContinuousValues(values, domain, fieldType) {
+  return values.map(value => fieldType === "temporal"
+    ? formatTimeTick(value, domain)
+    : String(+value.toPrecision(3))
+  );
+}
+
+export function styleContinuousText(
+  program,
+  id,
+  style,
+  { align = "left" } = {}
+) {
+  return program
+    .editGraphics({ target: id, property: "fill", value: style.color })
+    .editGraphics({ target: id, property: "fontSize", value: style.fontSize })
+    .editGraphics({ target: id, property: "fontFamily", value: style.fontFamily })
+    .editGraphics({ target: id, property: "fontWeight", value: style.fontWeight })
+    .editGraphics({ target: id, property: "textAlign", value: align })
+    .editGraphics({ target: id, property: "textBaseline", value: "middle" });
+}
+
+export function assertLegendInsideCanvas(items, canvas, label) {
+  if (items.some(item =>
+    item.x < 0 || item.y < 0 || item.x > canvas.width || item.y > canvas.height
+  )) {
+    throw new Error(`${label} requires more Canvas margin space.`);
+  }
+}
+
+export function resolveLegendBackgroundBounds(points, border, canvas, label) {
+  if (border === false) return undefined;
+  const x = Math.min(...points.map(point => point.x)) - border.padding;
+  const y = Math.min(...points.map(point => point.y)) - border.padding;
+  const right = Math.max(...points.map(point => point.x)) + border.padding;
+  const bottom = Math.max(...points.map(point => point.y)) + border.padding;
+  if (x < 0 || y < 0 || right > canvas.width || bottom > canvas.height) {
+    throw new Error(`${label} background requires more Canvas margin space.`);
+  }
+  return { x, y, width: right - x, height: bottom - y };
+}
+
+export function editLegendBackground(program, id, bounds, border) {
+  if (bounds === undefined) return program;
+  return program
+    .editGraphics({ target: id, property: "x", value: bounds.x })
+    .editGraphics({ target: id, property: "y", value: bounds.y })
+    .editGraphics({ target: id, property: "width", value: bounds.width })
+    .editGraphics({ target: id, property: "height", value: bounds.height })
+    .editGraphics({ target: id, property: "fill", value: border.background })
+    .editGraphics({ target: id, property: "stroke", value: border.color })
+    .editGraphics({ target: id, property: "strokeWidth", value: border.lineWidth });
+}

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

@@ -0,0 +1,363 @@
+import { action } from "../../../../core/action.js";
+import { isPlainObject } from "../../../../core/immutable.js";
+import { validateKeys } from "../../../../core/validation.js";
+import { interpolateColorStops } from "../../../../grammar/scales/color.js";
+import { DEFAULT_COLORS } from "../../../../theme/defaults.js";
+import {
+  assertLegendInsideCanvas,
+  editLegendBackground,
+  formatContinuousValues,
+  normalizeContinuousLegend,
+  requireResolvedLegendScale,
+  resolveContinuousBounds,
+  resolveContinuousColorLayer,
+  resolveLegendBackgroundBounds,
+  sampleContinuousValues,
+  styleContinuousText,
+  validatePositive
+} from "./common.js";
+import { resolveLegendGraphicPlacement } from
+  "../../../../materialization/graphicHierarchy.js";
+
+const GRADIENT_OPTIONS = Object.freeze(["length", "thickness"]);
+
+function resolveGradientLayout(program, config, scale) {
+  const { plot, canvas } = resolveContinuousBounds(program);
+  const vertical = ["right", "left"].includes(config.position);
+  const length = config.gradient.length;
+  const thickness = config.gradient.thickness;
+  let x;
+  let y;
+  if (config.position === "right") {
+    x = plot.x + plot.width + config.offset;
+    y = plot.y + 46;
+  } else if (config.position === "left") {
+    x = plot.x - config.offset - thickness;
+    y = plot.y + 46;
+  } else {
+    x = config.align === "left" ? plot.x
+      : config.align === "right" ? plot.x + plot.width - length
+        : plot.x + (plot.width - length) / 2;
+    y = config.position === "top"
+      ? plot.y - config.offset - thickness
+      : plot.y + plot.height + config.offset;
+  }
+  const title = vertical
+    ? { x, y: plot.y + 20, align: "left" }
+    : { x: x + length / 2, y: y - 20, align: "center" };
+  const values = sampleContinuousValues(scale.domain, config.count);
+  const fractions = values.map((_, index) => index / (values.length - 1));
+  const labelOffset = config.labels.offset;
+  const labels = vertical
+    ? fractions.map(fraction => ({
+        x: config.position === "right"
+          ? x + thickness + labelOffset
+          : x - labelOffset,
+        y: y + length * (1 - fraction),
+        align: config.position === "right" ? "left" : "right"
+      }))
+    : fractions.map(fraction => ({
+        x: x + length * fraction,
+        y: config.position === "top"
+          ? y - labelOffset
+          : y + thickness + labelOffset,
+        align: "center"
+      }));
+  const ticks = vertical
+    ? labels.map(label => ({
+        x1: config.position === "right" ? x + thickness : x,
+        y1: label.y,
+        x2: config.position === "right" ? x + thickness + 6 : x - 6,
+        y2: label.y
+      }))
+    : labels.map(label => ({
+        x1: label.x,
+        y1: config.position === "top" ? y : y + thickness,
+        x2: label.x,
+        y2: config.position === "top" ? y - 6 : y + thickness + 6
+      }));
+  assertLegendInsideCanvas([
+    title,
+    ...labels,
+    ...ticks.flatMap(tick => [
+      { x: tick.x1, y: tick.y1 },
+      { x: tick.x2, y: tick.y2 }
+    ])
+  ], canvas, "Gradient legend layout");
+  if (
+    x < 0 ||
+    y < 0 ||
+    x + (vertical ? thickness : length) > canvas.width ||
+    y + (vertical ? length : thickness) > canvas.height
+  ) {
+    throw new Error("Gradient legend layout requires more Canvas margin space.");
+  }
+  const background = resolveLegendBackgroundBounds([
+    { x, y },
+    {
+      x: x + (vertical ? thickness : length),
+      y: y + (vertical ? length : thickness)
+    },
+    title,
+    ...labels.map(label => ({
+      x: label.x + (
+        label.align === "left" ? 42 : label.align === "right" ? -42 : 0
+      ),
+      y: label.y
+    }))
+  ], config.border, canvas, "Gradient legend");
+  return {
+    vertical, x, y, length, thickness, values, labels, ticks, title, background
+  };
+}
+
+function resolveGradientConfig(program, config) {
+  const layer = resolveContinuousColorLayer(program, config.target);
+  const encoding = layer.encoding.color;
+  if (!["quantitative", "temporal"].includes(encoding.fieldType)) {
+    throw new Error("Gradient legend requires quantitative or temporal color.");
+  }
+  const scale = requireResolvedLegendScale(
+    program,
+    encoding.scale,
+    "sequential"
+  );
+  return {
+    layer,
+    encoding,
+    scale,
+    config: {
+      ...config,
+      target: layer.id,
+      scale: encoding.scale,
+      fieldType: encoding.fieldType,
+      title: config.inferredTitle ? encoding.field : config.title,
+      domain: scale.domain
+    }
+  };
+}
+
+export const rematerializeGradientLegend = action(
+  {
+    op: "rematerializeGradientLegend",
+    description: "Rematerialize a continuous color gradient legend."
+  },
+  function (args = {}) {
+    validateKeys(args, [], "rematerializeGradientLegend");
+    const stored = this.guideConfigs.legend?.gradient;
+    if (stored === undefined) {
+      throw new Error("Gradient legend requires stored configuration.");
+    }
+    const { scale, encoding, config } = resolveGradientConfig(this, stored);
+    const layout = resolveGradientLayout(this, config, scale);
+    const stripCount = 60;
+    const stripSize = layout.length / stripCount;
+    const strips = Array.from({ length: stripCount }, (_, index) => {
+      const fraction = (index + 0.5) / stripCount;
+      const color = interpolateColorStops(
+        scale.range,
+        layout.vertical ? 1 - fraction : fraction,
+        scale.interpolate
+      );
+      return {
+        x: layout.x + (layout.vertical ? 0 : index * stripSize),
+        y: layout.y + (layout.vertical ? index * stripSize : 0),
+        width: layout.vertical ? layout.thickness : stripSize,
+        height: layout.vertical ? stripSize : layout.thickness,
+        fill: color,
+        stroke: color,
+        strokeWidth: 0
+      };
+    });
+    let next = this
+      .editSemantic({
+        property: "guide.legend.color.scale",
+        value: encoding.scale
+      })
+      .editSemantic({
+        property: "guide.legend.color.title",
+        value: config.title
+      })
+      ._withLegendConfig("gradient", config)
+      .editGraphics({
+        target: "colorGradientStrips",
+        property: "length",
+        value: strips.length
+      });
+    next = editLegendBackground(
+      next,
+      "colorGradientBackground",
+      layout.background,
+      config.border
+    );
+    for (const property of [
+      "x", "y", "width", "height", "fill", "stroke", "strokeWidth"
+    ]) {
+      next = next.editGraphics({
+        target: "colorGradientStrips",
+        property,
+        value: strips.map(strip => strip[property])
+      });
+    }
+    next = next.editGraphics({
+      target: "colorGradientTicks",
+      property: "length",
+      value: layout.ticks.length
+    });
+    for (const property of ["x1", "y1", "x2", "y2"]) {
+      next = next.editGraphics({
+        target: "colorGradientTicks",
+        property,
+        value: layout.ticks.map(tick => tick[property])
+      });
+    }
+    next = next
+      .editGraphics({
+        target: "colorGradientTicks",
+        property: "stroke",
+        value: DEFAULT_COLORS.mutedText
+      })
+      .editGraphics({
+        target: "colorGradientTicks",
+        property: "strokeWidth",
+        value: 1
+      })
+      .editGraphics({
+        target: "colorGradientLabels",
+        property: "length",
+        value: layout.labels.length
+      })
+      .editGraphics({
+        target: "colorGradientLabels",
+        property: "x",
+        value: layout.labels.map(label => label.x)
+      })
+      .editGraphics({
+        target: "colorGradientLabels",
+        property: "y",
+        value: layout.labels.map(label => label.y)
+      })
+      .editGraphics({
+        target: "colorGradientLabels",
+        property: "text",
+        value: formatContinuousValues(
+          layout.values,
+          scale.domain,
+          config.fieldType
+        )
+      });
+    next = styleContinuousText(
+      next,
+      "colorGradientLabels",
+      config.labels,
+      { align: layout.labels[0].align }
+    );
+    if (config.titleVisible === false) return next;
+    next = next
+      .editGraphics({
+        target: "colorGradientTitle",
+        property: "x",
+        value: layout.title.x
+      })
+      .editGraphics({
+        target: "colorGradientTitle",
+        property: "y",
+        value: layout.title.y
+      })
+      .editGraphics({
+        target: "colorGradientTitle",
+        property: "text",
+        value: config.title
+      });
+    return styleContinuousText(
+      next,
+      "colorGradientTitle",
+      config.titleStyle,
+      { align: layout.title.align }
+    );
+  }
+);
+
+export const createGradientLegend = action(
+  {
+    op: "createGradientLegend",
+    description: "Create a continuous color gradient legend."
+  },
+  function (args = {}) {
+    const config = normalizeContinuousLegend(args, "gradient");
+    if (args.channels !== undefined && (
+      !Array.isArray(args.channels) ||
+      args.channels.length !== 1 ||
+      args.channels[0] !== "color"
+    )) {
+      throw new Error('Gradient legend requires channels: ["color"].');
+    }
+    if (args.gradient !== undefined && !isPlainObject(args.gradient)) {
+      throw new TypeError("createLegend.gradient must be a plain object.");
+    }
+    validateKeys(
+      args.gradient ?? {},
+      GRADIENT_OPTIONS,
+      "createLegend.gradient"
+    );
+    config.gradient = {
+      length: args.gradient?.length ?? 120,
+      thickness: args.gradient?.thickness ?? 12
+    };
+    config.titleVisible = true;
+    validatePositive(config.gradient.length, "Gradient length");
+    validatePositive(config.gradient.thickness, "Gradient thickness");
+    const resolved = resolveGradientConfig(this, config);
+    resolveGradientLayout(this, resolved.config, resolved.scale);
+    if (this.graphicSpec.objects.colorGradientStrips !== undefined) {
+      throw new Error(
+        "createGradientLegend requires a missing gradient legend."
+      );
+    }
+    let next = this
+      .editSemantic({
+        property: "guide.legend.color.scale",
+        value: resolved.encoding.scale
+      })
+      .editSemantic({
+        property: "guide.legend.color.title",
+        value: resolved.config.title
+      })
+      ._withLegendConfig("gradient", resolved.config);
+    if (resolved.config.border !== false) {
+      next = next.createGraphics({
+        id: "colorGradientBackground",
+        type: "rect",
+        ...resolveLegendGraphicPlacement(next)
+      });
+    }
+    return next
+      .createGraphics({
+        id: "colorGradientStrips",
+        type: "rect",
+        length: 0,
+        ...resolveLegendGraphicPlacement(next),
+        ...(resolved.config.border === false
+          ? {}
+          : { after: "colorGradientBackground" })
+      })
+      .createGraphics({
+        id: "colorGradientTicks",
+        type: "line",
+        length: 0,
+        ...resolveLegendGraphicPlacement(next)
+      })
+      .createGraphics({
+        id: "colorGradientLabels",
+        type: "text",
+        length: 0,
+        ...resolveLegendGraphicPlacement(next)
+      })
+      .createGraphics({
+        id: "colorGradientTitle",
+        type: "text",
+        ...resolveLegendGraphicPlacement(next)
+      })
+      .rematerializeGradientLegend();
+  }
+);

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

@@ -0,0 +1,25 @@
+import { createGradientLegend, rematerializeGradientLegend } from "./gradient.js";
+import {
+  createOpacityLegend,
+  rematerializeOpacityLegend,
+  removeOpacityLegend
+} from "./opacity.js";
+import { createIntervalLegend, rematerializeIntervalLegend } from "./interval.js";
+
+export { createGradientLegend, rematerializeGradientLegend } from "./gradient.js";
+export {
+  createOpacityLegend,
+  rematerializeOpacityLegend,
+  removeOpacityLegend
+} from "./opacity.js";
+export { createIntervalLegend, rematerializeIntervalLegend } from "./interval.js";
+
+export function registerContinuousLegendActions(ProgramClass) {
+  ProgramClass.prototype.createGradientLegend = createGradientLegend;
+  ProgramClass.prototype.rematerializeGradientLegend = rematerializeGradientLegend;
+  ProgramClass.prototype.createOpacityLegend = createOpacityLegend;
+  ProgramClass.prototype.rematerializeOpacityLegend = rematerializeOpacityLegend;
+  ProgramClass.prototype.removeOpacityLegend = removeOpacityLegend;
+  ProgramClass.prototype.createIntervalLegend = createIntervalLegend;
+  ProgramClass.prototype.rematerializeIntervalLegend = rematerializeIntervalLegend;
+}