ggaction 0.0.9 → 0.0.11

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/action.js

@@ -1,5 +1,11 @@
 import { cloneAndFreeze, freezeOwned, isPlainObject } from "./immutable.js";
 
+const metadataByWrappedAction = new WeakMap();
+
+export function getWrappedActionMetadata(value) {
+  return metadataByWrappedAction.get(value);
+}
+
 function summarizeObject(value, ancestors = new WeakSet()) {
   if (ancestors.has(value)) {
     throw new TypeError("Action arguments must not contain circular references.");
@@ -107,24 +113,33 @@ export function action(metadata, implementation) {
     throw new Error(`Unknown action scope "${scope}".`);
   }
 
-  return function wrappedAction(args = {}) {
+  const ownedMetadata = freezeOwned({
+    op: metadata.op,
+    description: metadata.description,
+    scope
+  });
+
+  const wrappedAction = function wrappedAction(args = {}) {
     if (!isPlainObject(args)) {
       throw new TypeError("Action arguments must be a plain object.");
     }
 
-    if (scope === "unit") this._assertUnitProgram(metadata.op);
-    if (scope === "composition") this._assertCompositionProgram(metadata.op);
+    if (scope === "unit") this._assertUnitProgram(ownedMetadata.op);
+    if (scope === "composition") this._assertCompositionProgram(ownedMetadata.op);
 
     const entered = this._enterAction({
-      ...metadata,
+      ...ownedMetadata,
       args: summarizeArgs(args)
     });
     const result = implementation.call(entered, args);
 
     if (!(result instanceof this.constructor)) {
-      throw new TypeError(`${metadata.op} must return a ChartProgram.`);
+      throw new TypeError(`${ownedMetadata.op} must return a ChartProgram.`);
     }
 
     return result._exitAction();
   };
+
+  metadataByWrappedAction.set(wrappedAction, ownedMetadata);
+  return wrappedAction;
 }

package/src/core/extensionRegistry.js

@@ -0,0 +1,104 @@
+import { getWrappedActionMetadata } from "./action.js";
+import { isPlainObject } from "./immutable.js";
+
+const ACTION_NAME_PATTERN = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const DEFINITION_KEYS = new Set(["name", "actions"]);
+const registeredExtensionNames = new Set();
+
+function readDataProperty(object, key, owner) {
+  const descriptor = Object.getOwnPropertyDescriptor(object, key);
+  if (descriptor === undefined) {
+    throw new TypeError(`${owner} requires a ${key} property.`);
+  }
+  if (!("value" in descriptor)) {
+    throw new TypeError(`${owner} ${key} must be a data property.`);
+  }
+  return descriptor.value;
+}
+
+function validateDefinitionShape(definition) {
+  if (!isPlainObject(definition)) {
+    throw new TypeError("Extension definition must be a plain object.");
+  }
+
+  for (const key of Reflect.ownKeys(definition)) {
+    if (typeof key !== "string" || !DEFINITION_KEYS.has(key)) {
+      throw new TypeError(`Unknown extension definition property "${String(key)}".`);
+    }
+  }
+
+  const name = readDataProperty(definition, "name", "Extension definition");
+  const actions = readDataProperty(
+    definition,
+    "actions",
+    "Extension definition"
+  );
+
+  if (
+    typeof name !== "string" ||
+    name.length === 0 ||
+    name !== name.trim()
+  ) {
+    throw new TypeError("Extension name must be a non-empty trimmed string.");
+  }
+  if (!isPlainObject(actions)) {
+    throw new TypeError("Extension actions must be a plain object.");
+  }
+
+  return { name, actions };
+}
+
+export function registerProgramExtension(ProgramClass, definition) {
+  const { name, actions } = validateDefinitionShape(definition);
+
+  if (registeredExtensionNames.has(name)) {
+    throw new Error(`Extension "${name}" is already registered.`);
+  }
+  if (!Object.isExtensible(ProgramClass.prototype)) {
+    throw new Error("ChartProgram prototype does not accept extension actions.");
+  }
+
+  const program = new ProgramClass();
+  const descriptors = Object.create(null);
+  const actionNames = Reflect.ownKeys(actions);
+  if (actionNames.length === 0) {
+    throw new TypeError("Extension actions must contain at least one action.");
+  }
+
+  for (const actionName of actionNames) {
+    if (
+      typeof actionName !== "string" ||
+      !ACTION_NAME_PATTERN.test(actionName)
+    ) {
+      throw new TypeError(
+        `Extension action name "${String(actionName)}" must be a JavaScript identifier.`
+      );
+    }
+
+    const action = readDataProperty(actions, actionName, "Extension actions");
+    const metadata = getWrappedActionMetadata(action);
+    if (metadata === undefined) {
+      throw new TypeError(
+        `Extension action "${actionName}" must be created with action().`
+      );
+    }
+    if (metadata.op !== actionName) {
+      throw new Error(
+        `Extension action "${actionName}" must use the same action op.`
+      );
+    }
+    if (actionName in program) {
+      throw new Error(`ChartProgram action "${actionName}" is already defined.`);
+    }
+
+    descriptors[actionName] = {
+      value: action,
+      configurable: false,
+      enumerable: true,
+      writable: false
+    };
+  }
+
+  Object.defineProperties(ProgramClass.prototype, descriptors);
+  registeredExtensionNames.add(name);
+}