ggaction 0.0.8 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ggaction",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "Build charts through immutable, traceable graphical actions.",
   "license": "MIT",
   "author": "Hyeon Jeon",
@@ -24,11 +24,19 @@
   "files": [
     "src/",
     "!src/**/AGENTS.md",
+    "knowledge/action-cards.json",
+    "knowledge/intent-taxonomy.json",
+    "knowledge/mcp-resources.json",
+    "knowledge/task-packet.schema.json",
+    "knowledge/task-resolver.js",
     "types/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "bin": {
+    "ggaction-mcp": "./src/mcp/cli.js"
+  },
   "types": "./types/index.d.ts",
   "exports": {
     ".": {
@@ -110,6 +118,7 @@
     "tag": "latest"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
     "@napi-rs/canvas": "^1.0.2"
   },
   "devDependencies": {

package/src/actions/basic.js

@@ -1,15 +1,15 @@
 import { registerBasicCanvasActions } from "./canvas/index.js";
 import { registerBasicChartActions } from "./charts/basic.js";
-import { registerCoordinateActions } from "./coordinates/index.js";
+import { registerCoordinateActions } from "./coordinates/actions.js";
 import { registerBasicDataActions } from "./data/basic.js";
 import { registerBasicEncodingActions } from "./encodings/basic.js";
 import { registerBasicGuideActions } from "./guides/basic.js";
 import { registerBasicMarkActions } from "./marks/basic.js";
-import { registerPrimitiveActions } from "./primitives/index.js";
+import { registerBasicPrimitiveActions } from "./primitives/index.js";
 import { registerBasicScaleActions } from "./scales/index.js";
 
 export function registerBasicActions(ProgramClass) {
-  registerPrimitiveActions(ProgramClass);
+  registerBasicPrimitiveActions(ProgramClass);
   registerBasicCanvasActions(ProgramClass);
   registerBasicDataActions(ProgramClass);
   registerBasicMarkActions(ProgramClass);

package/src/actions/coordinates/actions.js

@@ -80,3 +80,7 @@ export const createCoordinate = action(
     return program;
   }
 );
+
+export function registerCoordinateActions(ProgramClass) {
+  ProgramClass.prototype.createCoordinate = createCoordinate;
+}

package/src/actions/encodings/position/policies/line.js

@@ -38,6 +38,10 @@ export function resolveLinePositionPolicy({
   }
   const regression = dataset.transform?.some(item => item.type === "regression");
   const interval = dataset.transform?.some(item => item.type === "interval");
+  const windowOutput = dataset.transform?.some(item =>
+    item.type === "window" &&
+    item.operations?.some(operation => operation.as === args.field)
+  );
 
   if (channel === "x") {
     const directPair =
@@ -73,7 +77,7 @@ export function resolveLinePositionPolicy({
     (fieldType === "temporal" ||
       (fieldType === "quantitative" &&
         (layer.encoding?.x === undefined || quantitativePair)));
-  if (interval || prospectiveDirect) {
+  if (interval || (windowOutput && args.aggregate === undefined) || prospectiveDirect) {
     if (!["quantitative", "temporal"].includes(fieldType)) {
       throw new Error(
         "Direct line y encoding requires a quantitative or temporal field."

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

@@ -1,3 +1,6 @@
+import { action } from "../../../../core/action.js";
+import { resolveStoredSelection } from
+  "../../../../materialization/selection/state.js";
 import {
   createCategoricalLegend,
   createLegend,
@@ -12,6 +15,7 @@ import {
   rematerializeLegendLabels,
   rematerializeLegendTitle
 } from "./components.js";
+import { activeConfig, noOptions, symbolGraphic } from "./layout.js";
 import {
   createLegendSymbolLines,
   createLegendSymbolPoints,
@@ -21,7 +25,7 @@ import {
   rematerializeLegendSymbolPoints,
   rematerializeLegendSymbolSwatches,
   rematerializeLegendSymbols,
-  rematerializeLegendHighlights
+  rematerializeBasicLegendHighlights
 } from "./symbols.js";
 import { editLegend } from "../edit.js";
 import {
@@ -29,6 +33,82 @@ import {
   rematerializeSideLegendLane
 } from "../lane.js";
 
+function exactLegendSelection(program, config, highlight) {
+  if (highlight.target !== config.target) return undefined;
+  const resolved = resolveStoredSelection(program, highlight.selection);
+  const selected = new Set(resolved.keys);
+  const groups = config.domain.map(value =>
+    resolved.items.filter(item => item.fields?.[config.field] === value)
+  );
+  if (
+    groups.some(group => group.length === 0) ||
+    resolved.items.some(item => !config.domain.includes(item.fields?.[config.field]))
+  ) return undefined;
+  const states = groups.map(group => {
+    const count = group.filter(item => selected.has(item.key)).length;
+    return count === 0 ? false : count === group.length ? true : undefined;
+  });
+  return states.includes(undefined) ? undefined : states;
+}
+
+function legendLayerStyle(layer, style) {
+  const properties = layer.type === "line"
+    ? ["stroke", "strokeWidth", "strokeDash", "opacity"]
+    : ["fill", "stroke", "strokeWidth", "opacity"];
+  return Object.fromEntries(
+    properties.flatMap(key => Object.hasOwn(style, key) ? [[key, style[key]]] : [])
+  );
+}
+
+function createLegendHighlightAction() {
+  return action(
+    {
+      op: "rematerializeLegendHighlights",
+      description: "Reflect exact categorical mark highlights in legend symbols."
+    },
+    function (args = {}) {
+      noOptions(args, "rematerializeLegendHighlights");
+      const hasCategorical =
+        this.guideConfigs.legend?.series !== undefined ||
+        this.guideConfigs.legend?.color !== undefined;
+      if (!hasCategorical) return this;
+      const { config } = activeConfig(this);
+      const highlights = Object.values(
+        this.materializationConfigs.highlights ?? {}
+      ).map(highlight => ({
+        highlight,
+        states: exactLegendSelection(this, config, highlight)
+      })).filter(entry => entry.states !== undefined);
+      if (highlights.length === 0) return this;
+
+      let next = this.rematerializeLegendSymbols();
+      for (const { highlight, states } of highlights) {
+        for (const layer of config.symbol.layers) {
+          const id = symbolGraphic(config, layer.type);
+          const graphic = next.graphicSpec.objects[id];
+          const selectedStyle = legendLayerStyle(layer, highlight.style);
+          const dimOpacity = highlight.dimOthers === false
+            ? undefined
+            : highlight.dimOthers.opacity;
+          next = next.editGraphics({
+            target: id,
+            property: "items",
+            value: graphic.items.map((child, index) => ({
+              type: child.type ?? graphic.type,
+              properties: states[index]
+                ? { ...child.properties, ...selectedStyle }
+                : dimOpacity === undefined
+                  ? child.properties
+                  : { ...child.properties, opacity: dimOpacity }
+            }))
+          });
+        }
+      }
+      return next;
+    }
+  );
+}
+
 export function registerBasicCategoricalLegendActions(ProgramClass) {
   ProgramClass.prototype.createLegend = createLegend;
   ProgramClass.prototype.createCategoricalLegend = createCategoricalLegend;
@@ -37,7 +117,8 @@ export function registerBasicCategoricalLegendActions(ProgramClass) {
   ProgramClass.prototype.rematerializeLegendBackground = rematerializeLegendBackground;
   ProgramClass.prototype.createLegendSymbols = createLegendSymbols;
   ProgramClass.prototype.rematerializeLegendSymbols = rematerializeLegendSymbols;
-  ProgramClass.prototype.rematerializeLegendHighlights = rematerializeLegendHighlights;
+  ProgramClass.prototype.rematerializeLegendHighlights =
+    rematerializeBasicLegendHighlights;
   ProgramClass.prototype.createLegendSymbolLines = createLegendSymbolLines;
   ProgramClass.prototype.rematerializeLegendSymbolLines = rematerializeLegendSymbolLines;
   ProgramClass.prototype.createLegendSymbolPoints = createLegendSymbolPoints;
@@ -57,5 +138,7 @@ export function registerBasicCategoricalLegendActions(ProgramClass) {
 
 export function registerCategoricalLegendActions(ProgramClass) {
   registerBasicCategoricalLegendActions(ProgramClass);
+  ProgramClass.prototype.rematerializeLegendHighlights =
+    createLegendHighlightAction();
   ProgramClass.prototype.editLegend = editLegend;
 }

package/src/actions/guides/legends/categorical/symbols.js

@@ -12,44 +12,6 @@ import {
 import { resolveLegendGraphicPlacement } from
   "../../../../materialization/graphicHierarchy.js";
 import { createPointShapeGraphic } from "../../../../grammar/pointShapes.js";
-import { resolveStoredSelection } from "../../../../materialization/selection/state.js";
-
-function exactLegendSelection(program, config, highlight) {
-  if (highlight.target !== config.target) return undefined;
-  const resolved = resolveStoredSelection(program, highlight.selection);
-  const selected = new Set(resolved.keys);
-  const groups = config.domain.map(value =>
-    resolved.items.filter(item => item.fields?.[config.field] === value)
-  );
-  if (
-    groups.some(group => group.length === 0) ||
-    resolved.items.some(item => !config.domain.includes(item.fields?.[config.field]))
-  ) return undefined;
-  const states = groups.map(group => {
-    const count = group.filter(item => selected.has(item.key)).length;
-    return count === 0 ? false : count === group.length ? true : undefined;
-  });
-  return states.includes(undefined) ? undefined : states;
-}
-
-function legendLayerStyle(layer, style) {
-  if (layer.type === "line") {
-    return Object.fromEntries(
-      ["stroke", "strokeWidth", "strokeDash", "opacity"]
-        .flatMap(key => Object.hasOwn(style, key) ? [[key, style[key]]] : [])
-    );
-  }
-  if (layer.type === "swatch") {
-    return Object.fromEntries(
-      ["fill", "stroke", "strokeWidth", "opacity"]
-        .flatMap(key => Object.hasOwn(style, key) ? [[key, style[key]]] : [])
-    );
-  }
-  return Object.fromEntries(
-    ["fill", "stroke", "strokeWidth", "opacity"]
-      .flatMap(key => Object.hasOwn(style, key) ? [[key, style[key]]] : [])
-  );
-}
 
 function makeEditSymbol(type) {
   const suffix = { line: "Lines", point: "Points", swatch: "Swatches" }[type];
@@ -232,49 +194,13 @@ export const rematerializeLegendSymbols = action(
   }
 );
 
-export const rematerializeLegendHighlights = action(
+export const rematerializeBasicLegendHighlights = action(
   {
     op: "rematerializeLegendHighlights",
     description: "Reflect exact categorical mark highlights in legend symbols."
   },
   function (args = {}) {
     noOptions(args, "rematerializeLegendHighlights");
-    const hasCategorical =
-      this.guideConfigs.legend?.series !== undefined ||
-      this.guideConfigs.legend?.color !== undefined;
-    if (!hasCategorical) return this;
-    const { config } = activeConfig(this);
-    const highlights = Object.values(
-      this.materializationConfigs.highlights ?? {}
-    ).map(highlight => ({
-      highlight,
-      states: exactLegendSelection(this, config, highlight)
-    })).filter(entry => entry.states !== undefined);
-    if (highlights.length === 0) return this;
-
-    let next = this.rematerializeLegendSymbols();
-    for (const { highlight, states } of highlights) {
-      for (const layer of config.symbol.layers) {
-        const id = symbolGraphic(config, layer.type);
-        const graphic = next.graphicSpec.objects[id];
-        const selectedStyle = legendLayerStyle(layer, highlight.style);
-        const dimOpacity = highlight.dimOthers === false
-          ? undefined
-          : highlight.dimOthers.opacity;
-        next = next.editGraphics({
-          target: id,
-          property: "items",
-          value: graphic.items.map((child, index) => ({
-            type: child.type ?? graphic.type,
-            properties: states[index]
-              ? { ...child.properties, ...selectedStyle }
-              : dimOpacity === undefined
-                ? child.properties
-                : { ...child.properties, opacity: dimOpacity }
-          }))
-        });
-      }
-    }
-    return next;
+    return this;
   }
 );

package/src/actions/index.js

@@ -1,7 +1,7 @@
 import { registerCanvasActions } from "./canvas/index.js";
 import { registerChartActions } from "./charts/index.js";
 import { registerCategoryOrderActions } from "./categoryOrder/index.js";
-import { registerCoordinateActions } from "./coordinates/index.js";
+import { registerCoordinateActions } from "./coordinates/actions.js";
 import { registerCompositionActions } from "./composition/index.js";
 import { registerDataActions } from "./data/index.js";
 import { registerEncodingActions } from "./encodings/index.js";

package/src/actions/primitives/index.js

@@ -1,6 +1,33 @@
+import { isPlainObject } from "../../core/immutable.js";
+import { validateBin2DTransform } from "../../grammar/bin2d.js";
 import { registerCreateGraphicsAction } from "./createGraphics.js";
 import { registerEditGraphicsAction } from "./editGraphics.js";
 import { registerSemanticPrimitiveAction } from "./semantic.js";
+import { createSemanticPrimitiveAction } from "./semanticAction.js";
+import { createSemanticValueValidator } from "./semanticValidation/index.js";
+
+function validateBasicDatasetTransforms(value) {
+  if (!Array.isArray(value) || value.length !== 1 || !isPlainObject(value[0])) {
+    throw new TypeError(
+      "Dataset transform must contain exactly one plain object."
+    );
+  }
+  if (value[0].type !== "bin2d") {
+    throw new Error(`Unsupported dataset transform "${value[0].type}".`);
+  }
+  validateBin2DTransform(value[0]);
+}
+
+export function registerBasicPrimitiveActions(ProgramClass) {
+  const validateBasicSemanticValue = createSemanticValueValidator({
+    validateDatasetTransforms: validateBasicDatasetTransforms,
+    sourceMarkTypes: ["point", "bar", "rect"]
+  });
+  ProgramClass.prototype.editSemantic =
+    createSemanticPrimitiveAction(validateBasicSemanticValue);
+  registerCreateGraphicsAction(ProgramClass);
+  registerEditGraphicsAction(ProgramClass);
+}
 
 export function registerPrimitiveActions(ProgramClass) {
   registerSemanticPrimitiveAction(ProgramClass);

package/src/actions/primitives/semantic.js

@@ -1,191 +1,28 @@
-import { action } from "../../core/action.js";
+import { createSemanticPrimitiveAction } from "./semanticAction.js";
+import { validateDatasetTransforms } from "../../grammar/transforms.js";
 import {
-  cloneAndFreeze,
-  freezeOwned,
-  isPlainObject,
-  removeOwnedPath
-} from "../../core/immutable.js";
-import { parseSemanticPath } from "../../grammar/schemas/semanticPath.js";
-import { validateSemanticValue } from "./semanticValue.js";
-
-const CONTEXT_KEYS = Object.freeze({
-  dataset: "currentData",
-  layer: "currentMark",
-  scale: "currentScale",
-  coordinate: "currentCoordinate",
-  guide: "currentGuide"
-});
-
-function setNestedProperty(source, path, value) {
-  const [key, ...rest] = path;
-
-  if (rest.length === 0) {
-    return freezeOwned({ ...source, [key]: cloneAndFreeze(value) });
-  }
-
-  const child = isPlainObject(source[key]) ? source[key] : {};
-  return freezeOwned({
-    ...source,
-    [key]: setNestedProperty(child, rest, value)
-  });
-}
-
-function updateEntity(spec, parsed, value) {
-  const collection = spec[parsed.collection];
-  const index = collection.findIndex(item => item.id === parsed.id);
-
-  if (
-    parsed.kind === "dataset" &&
-    index !== -1 &&
-    Object.hasOwn(collection[index], "values")
-  ) {
-    throw new Error(`Dataset "${parsed.id}" is immutable after creation.`);
-  }
-
-  const current = index === -1 ? { id: parsed.id } : collection[index];
-  const updated = setNestedProperty(current, parsed.path, value);
-  const nextCollection = [...collection];
-
-  if (index === -1) {
-    nextCollection.push(updated);
-  } else {
-    nextCollection[index] = updated;
-  }
-
-  return freezeOwned({
-    ...spec,
-    [parsed.collection]: freezeOwned(nextCollection)
-  });
-}
-
-function updateGuides(spec, parsed, value) {
-  return freezeOwned({
-    ...spec,
-    guides: setNestedProperty(spec.guides, parsed.path, value)
-  });
-}
-
-function updateTitle(spec, parsed, value) {
-  return freezeOwned({
-    ...spec,
-    title: setNestedProperty(spec.title, parsed.path, value)
-  });
-}
-
-function removeEntity(spec, parsed) {
-  const collection = spec[parsed.collection];
-  const index = collection.findIndex(item => item.id === parsed.id);
-  if (index === -1) return spec;
-  if (parsed.kind === "layer" && parsed.path.length === 0) {
-    const nextCollection = collection.filter((_, itemIndex) => itemIndex !== index);
-    return freezeOwned({
-      ...spec,
-      [parsed.collection]: freezeOwned(nextCollection)
-    });
-  }
-  if (parsed.kind === "dataset" && parsed.path.length === 0) {
-    const dataset = collection[index];
-    if (dataset.source === undefined) {
-      throw new Error(`Source dataset "${parsed.id}" is immutable after creation.`);
-    }
-    const referenced = spec.layers.some(layer => layer.data === parsed.id) ||
-      spec.datasets.some(candidate => candidate.source === parsed.id);
-    if (referenced) {
-      throw new Error(`Derived dataset "${parsed.id}" is still referenced.`);
-    }
-    const nextCollection = collection.filter((_, itemIndex) => itemIndex !== index);
-    return freezeOwned({
-      ...spec,
-      [parsed.collection]: freezeOwned(nextCollection)
-    });
+  validateParallelDimensions,
+  validateParallelKeyField,
+  validateParallelMissingPolicy
+} from "../../grammar/parallelCoordinates.js";
+import { createSemanticValueValidator } from "./semanticValidation/index.js";
+
+function validateParallel(property, value) {
+  if (property === "encoding.parallel.dimensions") {
+    validateParallelDimensions(value, { normalized: true });
+  } else if (property === "encoding.parallel.key") {
+    validateParallelKeyField(value);
+  } else if (property === "encoding.parallel.missing") {
+    validateParallelMissingPolicy(value);
   }
-  if (parsed.kind === "dataset") {
-    throw new Error(`Dataset "${parsed.id}" is immutable after creation.`);
-  }
-  const removed = removeOwnedPath(collection[index], parsed.path);
-  if (!removed.removed) return spec;
-  const nextCollection = [...collection];
-  nextCollection[index] = removed.value;
-  return freezeOwned({
-    ...spec,
-    [parsed.collection]: freezeOwned(nextCollection)
-  });
 }
 
-function removeRootProperty(spec, root, path) {
-  const removed = removeOwnedPath(spec[root], path);
-  return removed.removed
-    ? freezeOwned({ ...spec, [root]: removed.value })
-    : spec;
-}
-
-const editSemantic = action(
-  {
-    op: "editSemantic",
-    description: "Create, replace, or remove one semantic property.",
-    scope: "any"
-  },
-  function ({ property, value, remove = false } = {}) {
-    if (typeof remove !== "boolean") {
-      throw new TypeError("editSemantic remove must be a boolean.");
-    }
-    if (remove && value !== undefined) {
-      throw new Error("editSemantic cannot combine value and remove.");
-    }
-    if (!remove && value === undefined) {
-      throw new TypeError("editSemantic requires a value.");
-    }
-
-    const parsed = parseSemanticPath(property, { allowContainer: remove });
-    if (this.compositionSpec !== undefined && !(
-      this.compositionSpec.type === "facet" && parsed.kind === "title"
-    )) {
-      throw new Error(
-        "editSemantic on a composition parent currently supports only facet title state."
-      );
-    }
-    if (remove) {
-      const semanticSpec = parsed.kind === "guide"
-        ? removeRootProperty(this.semanticSpec, "guides", parsed.path)
-        : parsed.kind === "title"
-          ? removeRootProperty(this.semanticSpec, "title", parsed.path)
-          : removeEntity(this.semanticSpec, parsed);
-      if (semanticSpec === this.semanticSpec) return this;
-      const clearsCurrentData =
-        parsed.kind === "dataset" &&
-        parsed.path.length === 0 &&
-        this.context.currentData === parsed.id;
-      const clearsCurrentMark =
-        parsed.kind === "layer" &&
-        parsed.path.length === 0 &&
-        this.context.currentMark === parsed.id;
-      return this._clone({
-        semanticSpec,
-        ...(clearsCurrentData || clearsCurrentMark
-          ? { context: freezeOwned({
-              ...this.context,
-              ...(clearsCurrentData ? { currentData: undefined } : {}),
-              ...(clearsCurrentMark ? { currentMark: undefined } : {})
-            }) }
-          : {})
-      });
-    }
-    validateSemanticValue(this, parsed, value);
-
-    const semanticSpec = parsed.kind === "guide"
-      ? updateGuides(this.semanticSpec, parsed, value)
-      : parsed.kind === "title"
-        ? updateTitle(this.semanticSpec, parsed, value)
-        : updateEntity(this.semanticSpec, parsed, value);
-    const contextKey = CONTEXT_KEYS[parsed.kind];
-    const context = contextKey === undefined
-      ? this.context
-      : freezeOwned({ ...this.context, [contextKey]: parsed.id });
-
-    return this._clone({ semanticSpec, context });
-  }
-);
-
 export function registerSemanticPrimitiveAction(ProgramClass) {
-  ProgramClass.prototype.editSemantic = editSemantic;
+  const validateSemanticValue = createSemanticValueValidator({
+    validateDatasetTransforms,
+    validateParallel,
+    sourceMarkTypes: ["point", "bar", "rule", "rect"]
+  });
+  ProgramClass.prototype.editSemantic =
+    createSemanticPrimitiveAction(validateSemanticValue);
 }