ggaction 0.0.2 → 0.0.4

package/src/actions/titles/actions.js

@@ -11,6 +11,15 @@ import {
   resolveCanvasGraphicPlacement
 } from "../../materialization/graphicHierarchy.js";
 
+function assertTitleScope(program, operation) {
+  if (
+    program.compositionSpec !== undefined &&
+    program.compositionSpec.type !== "facet"
+  ) {
+    throw new Error(`${operation} is not available on this composition ChartProgram.`);
+  }
+}
+
 function hasRotation(graphic) {
   const properties = graphic.items?.map(child => child.properties) ??
     [graphic.properties];
@@ -179,8 +188,13 @@ export const rematerializeTitle = action(
 );
 
 export const createTitle = action(
-  { op: "createTitle", description: "Create a chart title and optional subtitle." },
+  {
+    op: "createTitle",
+    description: "Create a chart title and optional subtitle.",
+    scope: "any"
+  },
   function (args = {}) {
+    assertTitleScope(this, "createTitle");
     const options = normalizeTitleOptions(args);
     if (Object.keys(this.semanticSpec.title).length > 0) {
       throw new Error("createTitle requires missing semantic title state.");
@@ -197,6 +211,9 @@ export const createTitle = action(
       next = next.editSemantic({ property: "title.subtitle", value: subtitle });
     }
     next = next._withTitleConfig(config);
+    if (next.compositionSpec?.type === "facet") {
+      return next.materializeComposition();
+    }
     resolveTitleLayout(next, config);
     next = next.createTitleText();
     if (subtitle !== undefined) next = next.createSubtitleText();
@@ -205,8 +222,13 @@ export const createTitle = action(
 );
 
 export const editTitle = action(
-  { op: "editTitle", description: "Edit one stable chart title resource." },
+  {
+    op: "editTitle",
+    description: "Edit one stable chart title resource.",
+    scope: "any"
+  },
   function (args = {}) {
+    assertTitleScope(this, "editTitle");
     if (this.semanticSpec.title.text === undefined) {
       throw new Error("editTitle requires an existing chart title.");
     }
@@ -229,7 +251,46 @@ export const editTitle = action(
       });
     }
     next = next._withTitleConfig(normalized.config);
+    if (next.compositionSpec?.type === "facet") {
+      return next.materializeComposition();
+    }
     resolveTitleLayout(next, normalized.config);
     return next.rematerializeTitle();
   }
 );
+
+export const removeTitle = action(
+  {
+    op: "removeTitle",
+    description: "Remove the complete chart title resource.",
+    scope: "any"
+  },
+  function (args = {}) {
+    assertTitleScope(this, "removeTitle");
+    noOptions(args, "removeTitle");
+    if (
+      this.semanticSpec.title.text === undefined &&
+      this.titleConfig === undefined &&
+      this.graphicSpec.objects.chartTitle === undefined &&
+      this.graphicSpec.objects.chartSubtitle === undefined
+    ) {
+      throw new Error("removeTitle requires an existing chart title.");
+    }
+    let next = this;
+    if (next.semanticSpec.title.subtitle !== undefined) {
+      next = next.editSemantic({ property: "title.subtitle", remove: true });
+    }
+    if (next.semanticSpec.title.text !== undefined) {
+      next = next.editSemantic({ property: "title.text", remove: true });
+    }
+    for (const id of ["chartTitle", "chartSubtitle"]) {
+      if (next.graphicSpec.objects[id] !== undefined) {
+        next = next.editGraphics({ target: id, remove: true });
+      }
+    }
+    next = next._withoutMaterializationConfig(["title"]);
+    return next.compositionSpec?.type === "facet"
+      ? next.materializeComposition()
+      : next;
+  }
+);

package/src/actions/titles/index.js

@@ -3,6 +3,7 @@ import {
   createTitle,
   createTitleText,
   editTitle,
+  removeTitle,
   editSubtitleText,
   editTitleText,
   rematerializeTitle
@@ -11,6 +12,7 @@ import {
 export function registerTitleActions(ProgramClass) {
   ProgramClass.prototype.createTitle = createTitle;
   ProgramClass.prototype.editTitle = editTitle;
+  ProgramClass.prototype.removeTitle = removeTitle;
   ProgramClass.prototype.createTitleText = createTitleText;
   ProgramClass.prototype.editTitleText = editTitleText;
   ProgramClass.prototype.createSubtitleText = createSubtitleText;

package/src/actions/titles/resolve.js

@@ -1,6 +1,7 @@
 import { isPlainObject } from "../../core/immutable.js";
 import {
   validateKeys,
+  validateOptionObject,
   validateNonEmptyString,
   validateNonNegativeFinite,
   validatePositiveFinite
@@ -8,6 +9,7 @@ import {
 import { resolveGraphicBounds } from "../../layout/canvas.js";
 import { resolveConcreteGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
 import {
+  alignedTextAnchor,
   alignedTitleAnchor,
   buildTitleReadingBlock,
   layoutBoundsIntersect,
@@ -15,6 +17,8 @@ import {
   unionTitleBounds
 } from "../../layout/title.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../theme/defaults.js";
+import { findCanvasGraphic } from
+  "../../materialization/graphicHierarchy.js";
 
 const OPTIONS = Object.freeze([
   "text", "subtitle", "position", "align", "offset", "gap", "titleStyle",
@@ -129,10 +133,7 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
 }
 
 export function normalizeTitleOptions(args) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("createTitle options must be a plain object.");
-  }
-  validateKeys(args, OPTIONS, "createTitle");
+  validateOptionObject(args, OPTIONS, "createTitle");
   const text = validateTitleString(args.text, "Chart title text");
   const subtitle = args.subtitle === undefined
     ? undefined
@@ -145,13 +146,11 @@ export function normalizeTitleOptions(args) {
 }
 
 export function normalizeTitleEditOptions(args, previous, semanticTitle) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("editTitle options must be a plain object.");
-  }
-  validateKeys(args, OPTIONS, "editTitle");
-  if (Object.keys(args).length === 0) {
-    throw new Error("editTitle requires at least one change.");
-  }
+  validateOptionObject(args, OPTIONS, "editTitle", {
+    allowEmpty: false,
+    emptyMessage: "editTitle requires at least one change.",
+    emptyError: Error
+  });
   const text = args.text === undefined
     ? semanticTitle.text
     : validateTitleString(args.text, "Chart title text");
@@ -233,7 +232,7 @@ function validateLayout(program, position, titleBounds, plot, canvas) {
 
 export function resolveTitleLayout(program, config) {
   const plot = resolveGraphicBounds(program);
-  const canvas = program.graphicSpec.objects.canvas;
+  const canvas = findCanvasGraphic(program);
   if (
     plot === undefined ||
     ![plot.x, plot.y, plot.width, plot.height].every(Number.isFinite) ||
@@ -256,11 +255,7 @@ export function resolveTitleLayout(program, config) {
   let title;
   let subtitle;
   if (horizontal) {
-    const x = config.align === "left"
-      ? plot.x
-      : config.align === "center"
-        ? plot.x + plot.width / 2
-        : plot.x + plot.width;
+    const x = alignedTextAnchor(plot.x, plot.width, config.align);
     const blockTop = config.position === "top"
       ? 16 + config.offset
       : plot.y + plot.height + config.offset;

package/src/composition.js

@@ -0,0 +1,10 @@
+import { chart } from "./ChartProgram.js";
+import { hconcatAction, vconcatAction } from "./actions/composition/actions.js";
+
+export function hconcat(options) {
+  return hconcatAction.call(chart(), options);
+}
+
+export function vconcat(options) {
+  return vconcatAction.call(chart(), options);
+}

package/src/core/ChartProgram.js

@@ -6,43 +6,23 @@ import {
 import {
   cloneAndFreeze,
   freezeOwned,
-  isOwned,
-  isPlainObject,
-  removeOwnedPath
+  isPlainObject
 } from "./immutable.js";
 import {
   createEmptyGraphicSpec,
   createEmptySemanticSpec,
   createTraceRoot
 } from "./specs.js";
-import { LEGEND_CONFIG_KINDS } from "./vocabulary.js";
-
-function ownState(value) {
-  return isOwned(value) ? value : cloneAndFreeze(value);
-}
-
-function createMaterializationConfigs(
-  markConfigs,
-  guideConfigs,
-  titleConfig,
-  canvasConfig
-) {
-  return cloneAndFreeze({
-    marks: markConfigs,
-    guides: guideConfigs,
-    ...(canvasConfig === undefined ? {} : { canvas: canvasConfig }),
-    ...(titleConfig === undefined ? {} : { title: titleConfig })
-  });
-}
-
-function updateConfigPath(value, path, config) {
-  if (path.length === 0) return cloneAndFreeze(config);
-  const [key, ...rest] = path;
-  return freezeOwned({
-    ...value,
-    [key]: updateConfigPath(value?.[key] ?? {}, rest, config)
-  });
-}
+import {
+  LEGEND_CONFIG_KINDS
+} from "./vocabulary.js";
+import { ownCompositionSpec } from "./compositionState.js";
+import {
+  createMaterializationConfigs,
+  removeMaterializationConfig,
+  setMaterializationConfig
+} from "./materializationState.js";
+import { ownChildPrograms, ownProgramState } from "./programState.js";
 
 export class ChartProgram {
   constructor({
@@ -54,14 +34,16 @@ export class ChartProgram {
     guideConfigs = {},
     titleConfig,
     canvasConfig,
+    children = {},
+    compositionSpec,
     context = {},
     trace = createTraceRoot(),
     actionStack = [],
     actionSequence
   } = {}) {
-    this.semanticSpec = ownState(semanticSpec);
-    this.graphicSpec = ownState(graphicSpec);
-    this.resolvedScales = ownState(resolvedScales);
+    this.semanticSpec = ownProgramState(semanticSpec);
+    this.graphicSpec = ownProgramState(graphicSpec);
+    this.resolvedScales = ownProgramState(resolvedScales);
     this.materializationConfigs = materializationConfigs === undefined
       ? createMaterializationConfigs(
           markConfigs,
@@ -69,10 +51,12 @@ export class ChartProgram {
           titleConfig,
           canvasConfig
         )
-      : ownState(materializationConfigs);
-    this.context = ownState(context);
-    this.trace = ownState(trace);
-    this.actionStack = ownState(actionStack);
+      : ownProgramState(materializationConfigs);
+    this.children = ownChildPrograms(children, ChartProgram);
+    this.compositionSpec = ownCompositionSpec(compositionSpec, this.children);
+    this.context = ownProgramState(context);
+    this.trace = ownProgramState(trace);
+    this.actionStack = ownProgramState(actionStack);
     Object.defineProperty(this, "_actionSequence", {
       value: actionSequence ?? countActionNodes(this.trace),
       enumerable: false
@@ -118,6 +102,8 @@ export class ChartProgram {
     graphicSpec = this.graphicSpec,
     resolvedScales = this.resolvedScales,
     materializationConfigs = this.materializationConfigs,
+    children = this.children,
+    compositionSpec = this.compositionSpec,
     context = this.context,
     trace = this.trace,
     actionStack = this.actionStack,
@@ -128,6 +114,8 @@ export class ChartProgram {
       graphicSpec,
       resolvedScales,
       materializationConfigs,
+      children,
+      compositionSpec,
       context,
       trace,
       actionStack,
@@ -135,6 +123,22 @@ export class ChartProgram {
     });
   }
 
+  _assertUnitProgram(operation) {
+    if (this.compositionSpec !== undefined) {
+      throw new Error(`${operation} is not available on a composition ChartProgram.`);
+    }
+  }
+
+  _assertCompositionProgram(operation) {
+    if (this.compositionSpec === undefined) {
+      throw new Error(`${operation} requires a composition ChartProgram.`);
+    }
+  }
+
+  _withCompositionState({ children, compositionSpec, graphicSpec = this.graphicSpec }) {
+    return this._clone({ children, compositionSpec, graphicSpec });
+  }
+
   _withContext(patch = {}) {
     if (!isPlainObject(patch)) {
       throw new TypeError("Context patch must be a plain object.");
@@ -188,18 +192,8 @@ export class ChartProgram {
   }
 
   _withMaterializationConfig(path, config) {
-    if (
-      !Array.isArray(path) ||
-      path.length === 0 ||
-      !path.every(key => typeof key === "string" && key.length > 0)
-    ) {
-      throw new TypeError("Materialization config path must contain names.");
-    }
-    if (!isPlainObject(config)) {
-      throw new TypeError("Materialization config must be a plain object.");
-    }
     return this._clone({
-      materializationConfigs: updateConfigPath(
+      materializationConfigs: setMaterializationConfig(
         this.materializationConfigs,
         path,
         config
@@ -208,22 +202,12 @@ export class ChartProgram {
   }
 
   _withoutMaterializationConfig(path) {
-    if (
-      !Array.isArray(path) ||
-      path.length === 0 ||
-      !path.every(key => typeof key === "string" && key.length > 0)
-    ) {
-      throw new TypeError("Materialization config path must contain names.");
-    }
-    const removed = removeOwnedPath(this.materializationConfigs, path);
+    const removed = removeMaterializationConfig(
+      this.materializationConfigs,
+      path
+    );
     if (!removed.removed) return this;
-    return this._clone({
-      materializationConfigs: freezeOwned({
-        ...removed.value,
-        marks: removed.value.marks ?? freezeOwned({}),
-        guides: removed.value.guides ?? freezeOwned({})
-      })
-    });
+    return this._clone({ materializationConfigs: removed.value });
   }
 
   _withGuideConfig(channel, component, config) {
@@ -257,7 +241,7 @@ export class ChartProgram {
   }
 
   _withGridConfig(direction, config) {
-    if (!["horizontal", "vertical"].includes(direction)) {
+    if (!["horizontal", "vertical", "theta", "radial"].includes(direction)) {
       throw new Error(`Unknown grid direction "${direction}".`);
     }
     if (!isPlainObject(config)) {

package/src/core/action.js

@@ -12,6 +12,8 @@ function summarizeObject(value, ancestors = new WeakSet()) {
       summary[`${key}Count`] = item.length;
     } else if (isPlainObject(item)) {
       summary[key] = summarizeObject(item, ancestors);
+    } else if (item !== null && typeof item === "object") {
+      summary[`${key}Type`] = item.constructor?.name ?? "object";
     } else {
       summary[key] = item;
     }
@@ -100,11 +102,19 @@ export function action(metadata, implementation) {
     throw new TypeError("Action implementation must be a function.");
   }
 
+  const scope = metadata.scope ?? "unit";
+  if (!["unit", "composition", "any"].includes(scope)) {
+    throw new Error(`Unknown action scope "${scope}".`);
+  }
+
   return 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);
+
     const entered = this._enterAction({
       ...metadata,
       args: summarizeArgs(args)

package/src/core/compositionState.js

@@ -0,0 +1,169 @@
+import { isPlainObject } from "./immutable.js";
+import { ownProgramState } from "./programState.js";
+import {
+  FACET_SCALE_CHANNELS,
+  FACET_SCALE_RESOLUTIONS
+} from "./vocabulary.js";
+
+function validateFacetSpec(compositionSpec) {
+  if (compositionSpec.direction !== undefined) {
+    throw new Error("Facet compositionSpec does not use direction.");
+  }
+  if (
+    !Number.isInteger(compositionSpec.columns) ||
+    compositionSpec.columns <= 0 ||
+    compositionSpec.columns > compositionSpec.children.length
+  ) {
+    throw new RangeError(
+      "Facet compositionSpec.columns must be a positive integer no larger than its children."
+    );
+  }
+  if (!isPlainObject(compositionSpec.facet)) {
+    throw new TypeError("Facet compositionSpec.facet must be a plain object.");
+  }
+  const facetKeys = ["data", "field", "values", "scales", "guides"];
+  const unknownFacet = Object.keys(compositionSpec.facet).find(
+    key => !facetKeys.includes(key)
+  );
+  if (unknownFacet !== undefined) {
+    throw new Error(`Unknown compositionSpec.facet property "${unknownFacet}".`);
+  }
+  for (const property of ["data", "field"]) {
+    if (
+      typeof compositionSpec.facet[property] !== "string" ||
+      compositionSpec.facet[property].length === 0
+    ) {
+      throw new TypeError(`compositionSpec.facet.${property} must be a non-empty string.`);
+    }
+  }
+  const values = compositionSpec.facet.values;
+  if (
+    !Array.isArray(values) ||
+    values.length !== compositionSpec.children.length ||
+    values.some(value => !(
+      typeof value === "string" ||
+      typeof value === "boolean" ||
+      (typeof value === "number" && Number.isFinite(value))
+    )) ||
+    new Set(values).size !== values.length
+  ) {
+    throw new TypeError(
+      "compositionSpec.facet.values must contain one unique scalar per child."
+    );
+  }
+  const scales = compositionSpec.facet.scales;
+  if (
+    !isPlainObject(scales) ||
+    Object.keys(scales).length !== FACET_SCALE_CHANNELS.length ||
+    FACET_SCALE_CHANNELS.some(channel =>
+      !FACET_SCALE_RESOLUTIONS.includes(scales[channel])
+    ) ||
+    Object.keys(scales).some(channel => !FACET_SCALE_CHANNELS.includes(channel))
+  ) {
+    throw new Error(
+      "compositionSpec.facet.scales requires one shared or independent policy per supported channel."
+    );
+  }
+  const guides = compositionSpec.facet.guides;
+  if (
+    !isPlainObject(guides) ||
+    Object.keys(guides).some(key => !["axes", "legend"].includes(key)) ||
+    !["each", "outer"].includes(guides.axes) ||
+    ![false, "shared"].includes(guides.legend)
+  ) {
+    throw new Error(
+      'compositionSpec.facet.guides requires axes "each" or "outer" and legend false or "shared".'
+    );
+  }
+}
+
+function validateCompositionChildren(compositionSpec, childIds, facet) {
+  if (
+    !Array.isArray(compositionSpec.children) ||
+    compositionSpec.children.length < (facet ? 1 : 2) ||
+    !compositionSpec.children.every(id => typeof id === "string" && id.length > 0)
+  ) {
+    throw new TypeError(
+      facet
+        ? "Facet compositionSpec.children requires at least one child ID."
+        : "compositionSpec.children requires at least two child IDs."
+    );
+  }
+  if (new Set(compositionSpec.children).size !== compositionSpec.children.length) {
+    throw new Error("compositionSpec.children must not contain duplicate IDs.");
+  }
+  if (
+    compositionSpec.children.length !== childIds.length ||
+    compositionSpec.children.some(id => !childIds.includes(id))
+  ) {
+    throw new Error("compositionSpec.children must match ChartProgram children exactly.");
+  }
+}
+
+function validateLayout(compositionSpec) {
+  if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
+    throw new RangeError("compositionSpec.gap must be a non-negative finite number.");
+  }
+  if (!["start", "center", "end"].includes(compositionSpec.align)) {
+    throw new Error("compositionSpec.align must be start, center, or end.");
+  }
+  if (!isPlainObject(compositionSpec.padding)) {
+    throw new TypeError("compositionSpec.padding must be a plain object.");
+  }
+  for (const side of ["top", "right", "bottom", "left"]) {
+    if (!Number.isFinite(compositionSpec.padding[side]) || compositionSpec.padding[side] < 0) {
+      throw new RangeError(
+        `compositionSpec.padding.${side} must be a non-negative finite number.`
+      );
+    }
+  }
+  const paddingKeys = Object.keys(compositionSpec.padding);
+  if (
+    paddingKeys.length !== 4 ||
+    paddingKeys.some(key => !["top", "right", "bottom", "left"].includes(key))
+  ) {
+    throw new Error("compositionSpec.padding must contain exactly four sides.");
+  }
+}
+
+export function ownCompositionSpec(compositionSpec, children) {
+  const childIds = Object.keys(children);
+  if (compositionSpec === undefined) {
+    if (childIds.length > 0) {
+      throw new Error("ChartProgram children require a compositionSpec.");
+    }
+    return undefined;
+  }
+  if (!isPlainObject(compositionSpec)) {
+    throw new TypeError("ChartProgram compositionSpec must be a plain object.");
+  }
+  const allowed = [
+    "id", "type", "direction", "children", "columns", "gap", "align",
+    "padding", "facet"
+  ];
+  const unknown = Object.keys(compositionSpec).find(key => !allowed.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown compositionSpec property "${unknown}".`);
+  }
+  if (typeof compositionSpec.id !== "string" || compositionSpec.id.length === 0) {
+    throw new TypeError("compositionSpec.id must be a non-empty string.");
+  }
+  const facet = compositionSpec.type === "facet";
+  if (compositionSpec.type !== undefined && !facet) {
+    throw new Error(`Unknown compositionSpec type "${compositionSpec.type}".`);
+  }
+  if (!facet && !["horizontal", "vertical"].includes(compositionSpec.direction)) {
+    throw new Error("compositionSpec.direction must be horizontal or vertical.");
+  }
+  validateCompositionChildren(compositionSpec, childIds, facet);
+  if (facet) {
+    validateFacetSpec(compositionSpec);
+  } else if (
+    compositionSpec.columns !== undefined ||
+    compositionSpec.facet !== undefined
+  ) {
+    throw new Error("Concat compositionSpec does not accept facet properties.");
+  }
+  validateLayout(compositionSpec);
+  return ownProgramState(compositionSpec);
+}

package/src/core/materializationState.js

@@ -0,0 +1,65 @@
+import {
+  cloneAndFreeze,
+  freezeOwned,
+  isPlainObject,
+  removeOwnedPath
+} from "./immutable.js";
+
+function validatePath(path) {
+  if (
+    !Array.isArray(path) ||
+    path.length === 0 ||
+    !path.every(key => typeof key === "string" && key.length > 0)
+  ) {
+    throw new TypeError("Materialization config path must contain names.");
+  }
+}
+
+function validateConfig(config) {
+  if (!isPlainObject(config)) {
+    throw new TypeError("Materialization config must be a plain object.");
+  }
+}
+
+function updateConfigPath(value, path, config) {
+  if (path.length === 0) return cloneAndFreeze(config);
+  const [key, ...rest] = path;
+  return freezeOwned({
+    ...value,
+    [key]: updateConfigPath(value?.[key] ?? {}, rest, config)
+  });
+}
+
+export function createMaterializationConfigs(
+  markConfigs,
+  guideConfigs,
+  titleConfig,
+  canvasConfig
+) {
+  return cloneAndFreeze({
+    marks: markConfigs,
+    guides: guideConfigs,
+    ...(canvasConfig === undefined ? {} : { canvas: canvasConfig }),
+    ...(titleConfig === undefined ? {} : { title: titleConfig })
+  });
+}
+
+export function setMaterializationConfig(configs, path, config) {
+  validatePath(path);
+  validateConfig(config);
+  return updateConfigPath(configs, path, config);
+}
+
+export function removeMaterializationConfig(configs, path) {
+  validatePath(path);
+  const removed = removeOwnedPath(configs, path);
+  if (!removed.removed) return { removed: false, value: configs };
+  return {
+    removed: true,
+    value: freezeOwned({
+      ...removed.value,
+      marks: removed.value.marks ?? freezeOwned({}),
+      guides: removed.value.guides ?? freezeOwned({})
+    })
+  };
+}

package/src/core/programState.js

@@ -0,0 +1,28 @@
+import {
+  cloneAndFreeze,
+  freezeOwned,
+  isOwned,
+  isPlainObject
+} from "./immutable.js";
+
+export function ownProgramState(value) {
+  return isOwned(value) ? value : cloneAndFreeze(value);
+}
+
+export function ownChildPrograms(children, ProgramClass) {
+  if (!isPlainObject(children)) {
+    throw new TypeError("ChartProgram children must be a plain object.");
+  }
+  if (isOwned(children)) return children;
+  const owned = {};
+  for (const [id, program] of Object.entries(children)) {
+    if (typeof id !== "string" || id.length === 0) {
+      throw new TypeError("ChartProgram child IDs must be non-empty strings.");
+    }
+    if (!(program instanceof ProgramClass)) {
+      throw new TypeError(`ChartProgram child "${id}" must be a ChartProgram.`);
+    }
+    owned[id] = program;
+  }
+  return freezeOwned(owned);
+}