ggaction 0.0.3 → 0.0.4

package/src/core/ChartProgram.js

@@ -6,9 +6,7 @@ import {
 import {
   cloneAndFreeze,
   freezeOwned,
-  isOwned,
-  isPlainObject,
-  removeOwnedPath
+  isPlainObject
 } from "./immutable.js";
 import {
   createEmptyGraphicSpec,
@@ -16,207 +14,15 @@ import {
   createTraceRoot
 } from "./specs.js";
 import {
-  FACET_SCALE_CHANNELS,
-  FACET_SCALE_RESOLUTIONS,
   LEGEND_CONFIG_KINDS
 } from "./vocabulary.js";
-
-function ownState(value) {
-  return isOwned(value) ? value : cloneAndFreeze(value);
-}
-
-function ownChildPrograms(children) {
-  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 ChartProgram)) {
-      throw new TypeError(`ChartProgram child "${id}" must be a ChartProgram.`);
-    }
-    owned[id] = program;
-  }
-  return freezeOwned(owned);
-}
-
-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) {
-    if (compositionSpec.direction !== undefined) {
-      throw new Error("Facet compositionSpec does not use direction.");
-    }
-  } else if (!["horizontal", "vertical"].includes(compositionSpec.direction)) {
-    throw new Error("compositionSpec.direction must be horizontal or vertical.");
-  }
-  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 => !Object.hasOwn(children, id))
-  ) {
-    throw new Error("compositionSpec.children must match ChartProgram children exactly.");
-  }
-  if (facet) {
-    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".'
-      );
-    }
-  } else if (
-    compositionSpec.columns !== undefined ||
-    compositionSpec.facet !== undefined
-  ) {
-    throw new Error("Concat compositionSpec does not accept facet properties.");
-  }
-  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.");
-  }
-  return ownState(compositionSpec);
-}
-
-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 { ownCompositionSpec } from "./compositionState.js";
+import {
+  createMaterializationConfigs,
+  removeMaterializationConfig,
+  setMaterializationConfig
+} from "./materializationState.js";
+import { ownChildPrograms, ownProgramState } from "./programState.js";
 
 export class ChartProgram {
   constructor({
@@ -235,9 +41,9 @@ export class ChartProgram {
     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,
@@ -245,12 +51,12 @@ export class ChartProgram {
           titleConfig,
           canvasConfig
         )
-      : ownState(materializationConfigs);
-    this.children = ownChildPrograms(children);
+      : ownProgramState(materializationConfigs);
+    this.children = ownChildPrograms(children, ChartProgram);
     this.compositionSpec = ownCompositionSpec(compositionSpec, this.children);
-    this.context = ownState(context);
-    this.trace = ownState(trace);
-    this.actionStack = ownState(actionStack);
+    this.context = ownProgramState(context);
+    this.trace = ownProgramState(trace);
+    this.actionStack = ownProgramState(actionStack);
     Object.defineProperty(this, "_actionSequence", {
       value: actionSequence ?? countActionNodes(this.trace),
       enumerable: false
@@ -386,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
@@ -406,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) {

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);
+}

package/src/grammar/arcs.js

@@ -4,7 +4,7 @@ import {
   mapOrdinalPositionValues,
   readNominalField,
   readQuantitativeField
-} from "./scales.js";
+} from "./scales/index.js";
 
 function requireArcLayer(layer) {
   if (layer?.mark?.type !== "arc") {

package/src/grammar/areaSeries.js

@@ -3,7 +3,7 @@ import {
   readNominalField,
   readQuantitativeField,
   readTemporalField
-} from "./scales.js";
+} from "./scales/index.js";
 import {
   layoutSeriesPartition,
   validateColorLayout

package/src/grammar/bars/aggregate.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze } from "../../core/immutable.js";
-import { readNominalField, readTemporalField } from "../scales.js";
+import { readNominalField, readTemporalField } from "../scales/index.js";
 import {
   aggregateRows,
   validateAggregateFieldType,

package/src/grammar/density.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze } from "../core/immutable.js";
-import { isNominalValue } from "./scales.js";
+import { isNominalValue } from "./scales/index.js";
 
 const SQRT_TWO_PI = Math.sqrt(2 * Math.PI);
 

package/src/grammar/{facets.js → facets/index.js}

@@ -1,8 +1,8 @@
-import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import { validateUserId } from "../core/identifiers.js";
-import { BAR_GRAINS, resolveBarGrain } from "./bars/policy.js";
-import { planFacetDependencies } from "./facets/dependencies.js";
-import { readNominalField } from "./scales.js";
+import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { BAR_GRAINS, resolveBarGrain } from "../bars/policy.js";
+import { planFacetDependencies } from "./dependencies.js";
+import { readNominalField } from "../scales/index.js";
 
 const SUPPORTED_MARKS = new Set(["point", "line", "area", "bar", "rule"]);
 const SUPPORTED_BAR_GRAINS = new Set([