ggaction 0.0.10 → 0.0.12

package/src/actions/titles/actions.js

@@ -21,9 +21,9 @@ function assertTitleScope(program, operation) {
 }
 
 function hasRotation(graphic) {
-  const properties = graphic.items?.map(child => child.properties) ??
-    [graphic.properties];
-  return properties.some(item => Object.hasOwn(item, "rotation"));
+  return (graphic.items ?? [graphic]).some(
+    item => Object.hasOwn(item.properties, "rotation")
+  );
 }
 
 function ensureTextShape(program, id, component) {
@@ -45,14 +45,7 @@ function ensureTextShape(program, id, component) {
         ...placement
       });
   }
-  if (!collection && needsCollection) {
-    return program.editGraphics({
-      target: id,
-      property: "length",
-      value: component.lines.length
-    });
-  }
-  if (collection && graphic.items.length !== component.lines.length) {
+  if (needsCollection && graphic.items?.length !== component.lines.length) {
     return program.editGraphics({
       target: id,
       property: "length",
@@ -68,20 +61,20 @@ function distributed(value, count) {
 
 function editTextGraphic(program, id, component, style) {
   const count = component.lines.length;
-  let next = ensureTextShape(program, id, component)
-    .editGraphics({ target: id, property: "x", value: distributed(component.x, count) })
-    .editGraphics({ target: id, property: "y", value: distributed(component.y, count) })
-    .editGraphics({
-      target: id,
-      property: "text",
-      value: distributed(component.lines, count)
-    })
-    .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: component.textAlign })
-    .editGraphics({ target: id, property: "textBaseline", value: "middle" });
+  let next = ensureTextShape(program, id, component);
+  for (const [property, value] of Object.entries({
+    x: distributed(component.x, count),
+    y: distributed(component.y, count),
+    text: distributed(component.lines, count),
+    fill: style.color,
+    fontSize: style.fontSize,
+    fontFamily: style.fontFamily,
+    fontWeight: style.fontWeight,
+    textAlign: component.textAlign,
+    textBaseline: "middle"
+  })) {
+    next = next.editGraphics({ target: id, property, value });
+  }
   if (component.explicitRotation) {
     next = next.editGraphics({
       target: id,
@@ -92,78 +85,39 @@ function editTextGraphic(program, id, component, style) {
   return next;
 }
 
-function createTextGraphic(program, id, component) {
-  return program.createGraphics({
-    id,
-    type: "text",
-    ...(component.lines.length > 1 ? { length: component.lines.length } : {}),
-    ...resolveCanvasGraphicPlacement(program)
+function titleTextAction(kind, create) {
+  const suffix = `${kind[0].toUpperCase()}${kind.slice(1)}Text`;
+  const op = `${create ? "create" : "edit"}${suffix}`;
+  const id = `chart${kind[0].toUpperCase()}${kind.slice(1)}`;
+  return action({
+    op,
+    description: `${create ? "Create" : "Rematerialize"} chart ${kind} text.`
+  }, function (args = {}) {
+    noOptions(args, op);
+    const config = requireTitleConfig(this);
+    if (create && this.graphicSpec.objects[id] !== undefined) {
+      throw new Error(`${op} requires a missing chart ${kind} graphic.`);
+    }
+    const component = resolveTitleLayout(this, config)[kind];
+    if (component === undefined) {
+      throw new Error(`${op} requires semantic subtitle text.`);
+    }
+    if (!create) {
+      return editTextGraphic(this, id, component, config[`${kind}Style`]);
+    }
+    return this.createGraphics({
+      id,
+      type: "text",
+      ...(component.lines.length > 1 ? { length: component.lines.length } : {}),
+      ...resolveCanvasGraphicPlacement(this)
+    })[`edit${suffix}`]();
   });
 }
 
-export const editTitleText = action(
-  { op: "editTitleText", description: "Rematerialize chart title text." },
-  function (args = {}) {
-    noOptions(args, "editTitleText");
-    const config = requireTitleConfig(this);
-    const layout = resolveTitleLayout(this, config);
-    return editTextGraphic(
-      this,
-      "chartTitle",
-      layout.title,
-      config.titleStyle
-    );
-  }
-);
-
-export const createTitleText = action(
-  { op: "createTitleText", description: "Create chart title text." },
-  function (args = {}) {
-    noOptions(args, "createTitleText");
-    const config = requireTitleConfig(this);
-    if (this.graphicSpec.objects.chartTitle !== undefined) {
-      throw new Error("createTitleText requires a missing chart title graphic.");
-    }
-    const layout = resolveTitleLayout(this, config);
-    return createTextGraphic(this, "chartTitle", layout.title)
-      .editTitleText();
-  }
-);
-
-export const editSubtitleText = action(
-  { op: "editSubtitleText", description: "Rematerialize chart subtitle text." },
-  function (args = {}) {
-    noOptions(args, "editSubtitleText");
-    const config = requireTitleConfig(this);
-    const layout = resolveTitleLayout(this, config);
-    if (layout.subtitle === undefined) {
-      throw new Error("editSubtitleText requires semantic subtitle text.");
-    }
-    return editTextGraphic(
-      this,
-      "chartSubtitle",
-      layout.subtitle,
-      config.subtitleStyle
-    );
-  }
-);
-
-export const createSubtitleText = action(
-  { op: "createSubtitleText", description: "Create chart subtitle text." },
-  function (args = {}) {
-    noOptions(args, "createSubtitleText");
-    const config = requireTitleConfig(this);
-    if (this.graphicSpec.objects.chartSubtitle !== undefined) {
-      throw new Error("createSubtitleText requires a missing chart subtitle graphic.");
-    }
-    const layout = resolveTitleLayout(this, config);
-    if (layout.subtitle === undefined) {
-      throw new Error("createSubtitleText requires semantic subtitle text.");
-    }
-    return createTextGraphic(this, "chartSubtitle", layout.subtitle)
-      .editSubtitleText();
-  }
-);
+export const editTitleText = titleTextAction("title", false);
+export const createTitleText = titleTextAction("title", true);
+export const editSubtitleText = titleTextAction("subtitle", false);
+export const createSubtitleText = titleTextAction("subtitle", true);
 
 export const rematerializeTitle = action(
   { op: "rematerializeTitle", description: "Rematerialize chart title graphics." },

package/src/actions/titles/resolve.js

@@ -252,29 +252,20 @@ export function resolveTitleLayout(program, config) {
         )
   }, config);
   const horizontal = ["top", "bottom"].includes(config.position);
-  let title;
-  let subtitle;
+  let component;
   if (horizontal) {
     const x = alignedTextAnchor(plot.x, plot.width, config.align);
     const blockTop = config.position === "top"
       ? 16 + config.offset
       : plot.y + plot.height + config.offset;
-    title = {
-      lines: block.titleLines,
+    component = (lines, centers) => ({
+      lines,
       x,
-      y: block.titleCenters.map(value => blockTop + value),
+      y: centers.map(value => blockTop + value),
       textAlign: config.align,
       rotation: 0,
-      explicitRotation: config.position !== "top" || block.titleLines.length > 1
-    };
-    subtitle = block.subtitleLines.length === 0 ? undefined : {
-      lines: block.subtitleLines,
-      x,
-      y: block.subtitleCenters.map(value => blockTop + value),
-      textAlign: config.align,
-      rotation: 0,
-      explicitRotation: config.position !== "top" || block.subtitleLines.length > 1
-    };
+      explicitRotation: config.position !== "top" || lines.length > 1
+    });
   } else {
     const rotation = config.position === "left" ? -Math.PI / 2 : Math.PI / 2;
     const y = alignedTitleAnchor(plot.y, plot.height, block.width, config.align);
@@ -282,23 +273,19 @@ export function resolveTitleLayout(program, config) {
       ? 16 + config.offset
       : canvas.properties.width - 16 + config.offset;
     const mapX = value => config.position === "left" ? edge + value : edge - value;
-    title = {
-      lines: block.titleLines,
-      x: block.titleCenters.map(mapX),
-      y,
-      textAlign: "center",
-      rotation,
-      explicitRotation: true
-    };
-    subtitle = block.subtitleLines.length === 0 ? undefined : {
-      lines: block.subtitleLines,
-      x: block.subtitleCenters.map(mapX),
+    component = (lines, centers) => ({
+      lines,
+      x: centers.map(mapX),
       y,
       textAlign: "center",
       rotation,
       explicitRotation: true
-    };
+    });
   }
+  const title = component(block.titleLines, block.titleCenters);
+  const subtitle = block.subtitleLines.length === 0
+    ? undefined
+    : component(block.subtitleLines, block.subtitleCenters);
   const titleBounds = unionTitleBounds([
     resolveTitleComponentBounds(title, config.titleStyle),
     ...(subtitle === undefined

package/src/actions/violinPlots/create.js

@@ -27,6 +27,8 @@ const AREA_OPTIONS = Object.freeze([
   "fill", "opacity", "stroke", "strokeWidth", "curve"
 ]);
 const CATEGORICAL_TYPES = Object.freeze(["nominal", "ordinal"]);
+const OPERATION = "createViolinPlot";
+const ROLE_ERROR = `${OPERATION} requires one categorical axis and one quantitative axis.`;
 
 function inferFieldType(dataset, encoding, label) {
   if (encoding.fieldType !== undefined) return encoding.fieldType;
@@ -51,29 +53,6 @@ function normalizePosition(dataset, value, label) {
   };
 }
 
-function normalizeDensity(value) {
-  if (value === undefined) return { options: {}, width: undefined };
-  validateOptionObject(value, DENSITY_OPTIONS, "createViolinPlot density");
-  if (value.width !== undefined) {
-    validateOptionObject(
-      value.width,
-      WIDTH_OPTIONS,
-      "createViolinPlot density.width"
-    );
-  }
-  const { width, ...options } = value;
-  return { options, width };
-}
-
-function normalizeSplit(value) {
-  if (value === undefined) return undefined;
-  validateOptionObject(value, SPLIT_OPTIONS, "createViolinPlot split");
-  if (typeof value.field !== "string" || value.field.length === 0) {
-    throw new TypeError("createViolinPlot split.field must be a non-empty string.");
-  }
-  return { ...value };
-}
-
 function axisGuideOptions(value, field) {
   if (value === false) return false;
   return {
@@ -109,55 +88,69 @@ export const createViolinPlot = action(
     description: "Create a categorical kernel-density violin plot."
   },
   function (args = {}) {
-    validateFacadeOptions(args, OPTIONS, "createViolinPlot");
+    validateFacadeOptions(args, OPTIONS, OPERATION);
     const id = resolveFacadeId(this, args.id, {
       defaultId: "violinPlot",
-      operation: "createViolinPlot"
+      operation: OPERATION
     });
-    const data = resolveFacadeData(this, args.data, "createViolinPlot");
+    const data = resolveFacadeData(this, args.data, OPERATION);
     const dataset = findDataset(this, data);
-    const x = normalizePosition(dataset, args.x, "createViolinPlot x");
-    const y = normalizePosition(dataset, args.y, "createViolinPlot y");
+    const x = normalizePosition(dataset, args.x, `${OPERATION} x`);
+    const y = normalizePosition(dataset, args.y, `${OPERATION} y`);
     const xCategorical = CATEGORICAL_TYPES.includes(x.fieldType);
     const yCategorical = CATEGORICAL_TYPES.includes(y.fieldType);
     if (xCategorical === yCategorical || (
       x.fieldType !== "quantitative" && y.fieldType !== "quantitative"
     )) {
-      throw new Error(
-        "createViolinPlot requires one categorical axis and one quantitative axis."
-      );
+      throw new Error(ROLE_ERROR);
     }
     const category = xCategorical ? x : y;
     const value = xCategorical ? y : x;
     if (value.fieldType !== "quantitative") {
-      throw new Error(
-        "createViolinPlot requires one categorical axis and one quantitative axis."
-      );
+      throw new Error(ROLE_ERROR);
+    }
+    let split = args.split;
+    if (split !== undefined) {
+      validateOptionObject(split, SPLIT_OPTIONS, `${OPERATION} split`);
+      if (typeof split.field !== "string" || split.field.length === 0) {
+        throw new TypeError(`${OPERATION} split.field must be a non-empty string.`);
+      }
+      split = { ...split };
     }
-    const split = normalizeSplit(args.split);
     if (split?.field === category.field) {
-      throw new Error("createViolinPlot split field must differ from its category field.");
+      throw new Error(`${OPERATION} split field must differ from its category field.`);
     }
-    const color = normalizeEncoding(args.color, "createViolinPlot color");
+    const color = normalizeEncoding(args.color, `${OPERATION} color`);
     if (
       color !== undefined &&
       ![category.field, split?.field].includes(color.field)
     ) {
       throw new Error(
-        "createViolinPlot color must encode its category or split field."
+        `${OPERATION} color must encode its category or split field.`
       );
     }
-    const density = normalizeDensity(args.density);
+    const density = args.density === undefined ? {} : args.density;
+    if (args.density !== undefined) {
+      validateOptionObject(density, DENSITY_OPTIONS, `${OPERATION} density`);
+      if (density.width !== undefined) {
+        validateOptionObject(
+          density.width,
+          WIDTH_OPTIONS,
+          `${OPERATION} density.width`
+        );
+      }
+    }
+    const { width: densityWidth, ...densityOptions } = density;
     const area = normalizeAppearance(
       args.area,
       AREA_OPTIONS,
-      "createViolinPlot area"
+      `${OPERATION} area`
     );
     if (color !== undefined && Object.hasOwn(area, "fill")) {
-      throw new Error("createViolinPlot area.fill cannot be combined with color.");
+      throw new Error(`${OPERATION} area.fill cannot be combined with color.`);
     }
     const guides = guideOptions(
-      normalizeGuides(args.guides, "createViolinPlot"),
+      normalizeGuides(args.guides, OPERATION),
       x,
       y,
       category,
@@ -184,10 +177,10 @@ export const createViolinPlot = action(
       densityChannel: xCategorical ? "x" : "y",
       ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
       ...(value.scale === undefined ? {} : { valueScale: value.scale }),
-      ...density.options,
+      ...densityOptions,
       placement: {
         type: "category",
-        ...(density.width === undefined ? {} : { width: density.width }),
+        ...(densityWidth === undefined ? {} : { width: densityWidth }),
         ...(split === undefined ? {} : { split }),
         ...(category.scale === undefined ? {} : { scale: category.scale })
       }

package/src/core/textMetrics.js

@@ -1,38 +1,69 @@
 function codePointWidth(codePoint) {
   if (/\s/u.test(codePoint)) return 0.28;
-  if (/[iIl1.,:;!'|]/u.test(codePoint)) return 0.27;
+  if (/[iIl.,:;!'|]/u.test(codePoint)) return 0.27;
   if (/[mwMW@#%&]/u.test(codePoint)) return 0.82;
-  if (/[A-Z]/u.test(codePoint)) return 0.61;
-  if (/[0-9]/u.test(codePoint)) return 0.53;
+  if (/[A-Z0-9]/u.test(codePoint)) return 0.61;
   if (/[-_]/u.test(codePoint)) return 0.34;
   if (codePoint.codePointAt(0) > 0x7f) return 1;
   return 0.47;
 }
 
-export function measureTextWidth(text, { fontSize } = {}) {
+export function formatVisibleText(value) {
+  return String(value) || "(empty)";
+}
+
+export function textBoundsIntersect(first, second) {
+  return first.left < second.right && first.right > second.left &&
+    first.top < second.bottom && first.bottom > second.top;
+}
+
+export function textBoundsFitCanvas(bounds, canvas) {
+  const epsilon = 1e-9;
+  return bounds.left >= -epsilon && bounds.right <= canvas.width + epsilon &&
+    bounds.top >= -epsilon && bounds.bottom <= canvas.height + epsilon;
+}
+
+export function measureTextWidth(
+  text,
+  { fontSize, fontFamily, fontWeight } = {}
+) {
   if (typeof text !== "string") {
     throw new TypeError("Text measurement requires a string.");
   }
   if (!Number.isFinite(fontSize) || fontSize <= 0) {
     throw new RangeError("Text measurement requires a positive fontSize.");
   }
-  return [...text].reduce(
-    (width, codePoint) => width + codePointWidth(codePoint) * fontSize,
-    0
-  );
-}
-
-function horizontalExtents(width, align) {
-  if (align === "center") return [-width / 2, width / 2];
-  if (["right", "end"].includes(align)) return [-width, 0];
-  return [0, width];
+  let joined = false;
+  let width = 0;
+  for (const codePoint of text) {
+    if (codePoint === "\u200d") {
+      joined = true;
+    } else if (!/\p{Mark}|\p{Format}|\p{Emoji_Modifier}/u.test(codePoint)) {
+      if (joined) joined = false;
+      else width += codePointWidth(codePoint) * fontSize;
+    }
+  }
+  const family = typeof fontFamily === "string" ? fontFamily.toLowerCase() : "";
+  const familyFactor = /mono/u.test(family)
+    ? 1.08
+    : /serif/u.test(family) && !/sans-serif/u.test(family) ? 1.03 : 1;
+  const weight = Number(fontWeight);
+  width *= familyFactor * ((
+    Number.isFinite(weight)
+      ? weight >= 600
+      : /bold|black|heavy/iu.test(fontWeight ?? "")
+  ) ? 1.04 : 1);
+  if (!Number.isFinite(width)) {
+    throw new RangeError("Text measurement exceeds the finite numeric range.");
+  }
+  return width;
 }
 
-function verticalExtents(fontSize, baseline) {
-  if (baseline === "middle") return [-fontSize / 2, fontSize / 2];
-  if (["top", "hanging"].includes(baseline)) return [0, fontSize];
-  if (["bottom", "ideographic"].includes(baseline)) return [-fontSize, 0];
-  return [-fontSize * 0.8, fontSize * 0.2];
+export function requireFiniteBounds(bounds, label = "Graphic") {
+  if (bounds !== undefined && !Object.values(bounds).every(Number.isFinite)) {
+    throw new RangeError(`${label} bounds exceed the finite numeric range.`);
+  }
+  return bounds;
 }
 
 export function resolveTextBounds({
@@ -40,6 +71,8 @@ export function resolveTextBounds({
   y,
   text,
   fontSize,
+  fontFamily,
+  fontWeight,
   textAlign = "left",
   textBaseline = "alphabetic",
   rotation = 0
@@ -47,24 +80,28 @@ export function resolveTextBounds({
   if (![x, y, rotation].every(Number.isFinite)) {
     throw new TypeError("Text bounds require finite x, y, and rotation values.");
   }
-  const width = measureTextWidth(text, { fontSize });
-  const [left, right] = horizontalExtents(width, textAlign);
-  const [top, bottom] = verticalExtents(fontSize, textBaseline);
+  const width = measureTextWidth(text, { fontSize, fontFamily, fontWeight });
+  const [left, right] = textAlign === "center"
+    ? [-width / 2, width / 2]
+    : ["right", "end"].includes(textAlign) ? [-width, 0] : [0, width];
+  const [top, bottom] = textBaseline === "middle"
+    ? [-fontSize / 2, fontSize / 2]
+    : ["top", "hanging"].includes(textBaseline)
+      ? [0, fontSize]
+      : ["bottom", "ideographic"].includes(textBaseline)
+        ? [-fontSize, 0]
+        : [-fontSize * 0.8, fontSize * 0.2];
   const cosine = Math.cos(rotation);
   const sine = Math.sin(rotation);
-  const corners = [
-    [left, top],
-    [right, top],
-    [right, bottom],
-    [left, bottom]
-  ].map(([localX, localY]) => ({
-    x: x + localX * cosine - localY * sine,
-    y: y + localX * sine + localY * cosine
-  }));
-  return Object.freeze({
-    left: Math.min(...corners.map(point => point.x)),
-    right: Math.max(...corners.map(point => point.x)),
-    top: Math.min(...corners.map(point => point.y)),
-    bottom: Math.max(...corners.map(point => point.y))
-  });
+  const bounds = {
+    left: x + Math.min(left * cosine, right * cosine) -
+      Math.max(top * sine, bottom * sine),
+    right: x + Math.max(left * cosine, right * cosine) -
+      Math.min(top * sine, bottom * sine),
+    top: y + Math.min(left * sine, right * sine) +
+      Math.min(top * cosine, bottom * cosine),
+    bottom: y + Math.max(left * sine, right * sine) +
+      Math.max(top * cosine, bottom * cosine)
+  };
+  return Object.freeze(requireFiniteBounds(bounds, "Text"));
 }

package/src/core/validation.js

@@ -1,5 +1,23 @@
 import { isPlainObject } from "./immutable.js";
 
+export const MAX_GENERATED_ITEMS = 10_000;
+export const MAX_WORK_ITEMS = 10_000_000;
+
+export function validateGeneratedItemLimit(
+  value,
+  label,
+  maximum = MAX_GENERATED_ITEMS
+) {
+  if (value > maximum) {
+    throw new RangeError(`${label} must not exceed ${maximum}.`);
+  }
+  return value;
+}
+
+export function validateWorkLimit(value, label) {
+  return validateGeneratedItemLimit(value, label, MAX_WORK_ITEMS);
+}
+
 export function validateKeys(value, supported, label) {
   for (const key of Object.keys(value)) {
     if (!supported.includes(key)) {

package/src/core/vocabulary.js

@@ -86,14 +86,14 @@ export const POSITION_CHANNEL_DEFINITIONS = Object.freeze({
     role: "offset",
     scaleChannel: "xOffset",
     coordinate: Object.freeze({ id: "main", type: "cartesian" }),
-    markTypes: Object.freeze(["bar"])
+    markTypes: Object.freeze(["bar", "point", "rule"])
   }),
   yOffset: Object.freeze({
     family: "cartesian",
     role: "offset",
     scaleChannel: "yOffset",
     coordinate: Object.freeze({ id: "main", type: "cartesian" }),
-    markTypes: Object.freeze(["bar"])
+    markTypes: Object.freeze(["bar", "point", "rule"])
   }),
   theta: Object.freeze({
     family: "polar",