ggaction 0.0.2 → 0.0.4

package/src/actions/marks/line/actions.js

@@ -0,0 +1,373 @@
+import { action } from "../../../core/action.js";
+import { deriveLineSeries } from "../../../grammar/lineSeries.js";
+import { mapContinuousScaleValues, mapOrdinalValues } from "../../../grammar/scales/index.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../../core/validation.js";
+import {
+  assertMarkAvailable,
+  applyLayeredMarkInheritance,
+  materializeInheritedMark,
+  resolveLayeredMarkInheritance,
+  resolveMarkId,
+  resolveMarkData,
+  validateMarkOptions
+} from "../shared.js";
+import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import { findDataset } from "../../../selectors/datasets.js";
+import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
+import {
+  buildCurvePathCommands,
+  validateCurveInterpolation
+} from "../../../grammar/curveCommands.js";
+import { buildPolarLinePathCommands } from "../../../grammar/polarLineCommands.js";
+import { resolvePolarFrame } from "../../../grammar/polar.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { normalizeStrokeDashPattern } from "../../../grammar/scales/index.js";
+import { canMaterializeLine } from "../../../materialization/marks/index.js";
+import { resolveMarkGraphicPlacement } from
+  "../../../materialization/graphicHierarchy.js";
+import { rematerializeHighlightBaseline } from "../lifecycle.js";
+
+const DEFAULT_LINE_STROKE = DEFAULT_COLORS.mark;
+const DEFAULT_LINE_WIDTH = 2;
+const CREATE_OPTIONS = Object.freeze([
+  "id", "data", "stroke", "strokeWidth", "opacity", "curve", "closed"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "stroke", "strokeWidth", "opacity", "curve", "closed"
+]);
+const REMATERIALIZE_OPTIONS = Object.freeze(["id", "scales"]);
+
+function validateClosed(value) {
+  if (typeof value !== "boolean") {
+    throw new TypeError("Line closed must be a boolean.");
+  }
+  return value;
+}
+
+function isPolarLine(layer) {
+  return layer.encoding?.theta !== undefined ||
+    layer.encoding?.radius !== undefined;
+}
+
+function validatePolarLineConfig(layer, config) {
+  if (!isPolarLine(layer)) return;
+  if ((config.curve ?? "linear") !== "linear") {
+    throw new Error("Polar line position currently requires curve \"linear\".");
+  }
+}
+
+const createLineMark = action(
+  {
+    op: "createLineMark",
+    description: "Create a semantic line mark and empty path collection."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, CREATE_OPTIONS, "createLineMark");
+    const id = resolveMarkId(this, args.id, {
+      defaultId: "line",
+      label: "Line mark id",
+      markType: "line",
+      operation: "createLineMark"
+    });
+    const inherited = resolveLayeredMarkInheritance(this, args, "line");
+    const { data } = resolveMarkData(this, {
+      ...args,
+      ...(args.data === undefined && this.context.currentData === undefined &&
+        inherited?.data !== undefined ? { data: inherited.data } : {})
+    });
+    const strokeWidth = validateNonNegativeFinite(
+      args.strokeWidth ?? DEFAULT_LINE_WIDTH,
+      "Line strokeWidth"
+    );
+    if (args.scales !== undefined && typeof args.scales !== "boolean") {
+      throw new TypeError("rematerializeLineMark scales must be a boolean.");
+    }
+    const curve = validateCurveInterpolation(args.curve ?? "linear");
+    const closed = Object.hasOwn(args, "closed")
+      ? validateClosed(args.closed)
+      : false;
+    const stroke = Object.hasOwn(args, "stroke")
+      ? validateNonEmptyString(args.stroke, "Line stroke")
+      : undefined;
+    const opacity = Object.hasOwn(args, "opacity")
+      ? validateUnitInterval(args.opacity, "Line opacity")
+      : undefined;
+    assertMarkAvailable(this, id);
+
+    let created = this
+      .editSemantic({
+        property: `layer[${id}].mark.type`,
+        value: "line"
+      })
+      .editSemantic({
+        property: `layer[${id}].data`,
+        value: data
+      });
+    created = applyLayeredMarkInheritance(created, id, inherited);
+    created = created
+      .createGraphics({
+        id,
+        type: "path",
+        length: 0,
+        ...resolveMarkGraphicPlacement(created, { data, markType: "line" })
+      })
+      ._withMarkConfig(
+        id,
+        {
+          ...(Object.hasOwn(args, "strokeWidth") ? { strokeWidth } : {}),
+          ...(Object.hasOwn(args, "curve") ? { curve } : {}),
+          ...(Object.hasOwn(args, "closed") ? { closed } : {})
+        }
+      );
+    created = materializeInheritedMark(created, id);
+    const appearance = {
+      ...(stroke === undefined ? {} : { stroke }),
+      ...(opacity === undefined ? {} : { opacity })
+    };
+    return Object.keys(appearance).length === 0
+      ? created
+      : created.editLineMark({ target: id, ...appearance });
+  }
+);
+
+function requireLine(program, id) {
+  const layer = findLayer(program, id);
+
+  if (layer?.mark?.type !== "line") {
+    throw new Error(`Unknown line mark "${id}".`);
+  }
+
+  const dataset = findDataset(program, layer.data);
+
+  if (dataset === undefined) {
+    throw new Error(`Line mark "${id}" requires an existing dataset.`);
+  }
+
+  if (program.graphicSpec.objects[id]?.type !== "path") {
+    throw new Error(`Line mark "${id}" requires path graphics.`);
+  }
+
+  return { dataset, layer };
+}
+
+const rematerializeLineMark = action(
+  {
+    op: "rematerializeLineMark",
+    description: "Recompute aggregate series and concrete line paths."
+  },
+  function (args = {}) {
+    validateMarkOptions(
+      args,
+      REMATERIALIZE_OPTIONS,
+      "rematerializeLineMark"
+    );
+    const id = validateUserId(args.id, "Line mark id");
+    const highlighted = rematerializeHighlightBaseline(this, {
+      target: id,
+      operation: "rematerializeLineMark",
+      resetProperty: "length",
+      resetValue: 0
+    });
+    if (highlighted !== undefined) return highlighted;
+    const { dataset, layer } = requireLine(this, id);
+    const existingChildren = this.graphicSpec.objects[id].items;
+    const xScaleId = layer.encoding?.x?.scale;
+    const yScaleId = layer.encoding?.y?.scale;
+    const thetaScaleId = layer.encoding?.theta?.scale;
+    const radiusScaleId = layer.encoding?.radius?.scale;
+    const polar = isPolarLine(layer);
+    const config = this.markConfigs[id] ?? {};
+    validatePolarLineConfig(layer, config);
+
+    if (
+      polar
+        ? thetaScaleId === undefined || radiusScaleId === undefined
+        : xScaleId === undefined || yScaleId === undefined
+    ) {
+      throw new Error(
+        polar
+          ? `Line mark "${id}" requires theta and radius scales.`
+          : `Line mark "${id}" requires x and y scales.`
+      );
+    }
+
+    let resolved = args.scales === false
+      ? this
+      : polar
+        ? this
+            .rematerializeScale({ id: thetaScaleId })
+            .rematerializeScale({ id: radiusScaleId })
+        : this
+            .rematerializeScale({ id: xScaleId })
+            .rematerializeScale({ id: yScaleId });
+
+    for (const channel of args.scales === false ? [] : ["color", "strokeDash"]) {
+      const scaleId = layer.encoding?.[channel]?.scale;
+      if (scaleId !== undefined) {
+        resolved = resolved.rematerializeScale({ id: scaleId });
+      }
+    }
+
+    const derived = deriveLineSeries(
+      dataset.values,
+      layer,
+      polar
+        ? { thetaDomain: resolved.resolvedScales[thetaScaleId].domain }
+        : undefined
+    );
+    const commands = polar
+      ? derived.series.map(series => buildPolarLinePathCommands({
+          series: series.values,
+          thetaFieldType: derived.thetaFieldType,
+          thetaScale: resolved.resolvedScales[thetaScaleId],
+          radiusScale: resolved.resolvedScales[radiusScaleId],
+          frame: resolvePolarFrame(resolveGraphicBounds(resolved)),
+          closed: config.closed ?? false
+        }))
+      : derived.series.map(series => {
+          const x = mapContinuousScaleValues(
+            series.values.map(value => value.x),
+            resolved.resolvedScales[xScaleId]
+          );
+          const y = mapContinuousScaleValues(
+            series.values.map(value => value.y),
+            resolved.resolvedScales[yScaleId]
+          );
+
+          return buildCurvePathCommands(
+            series.values.map((_, index) => ({ x: x[index], y: y[index] })),
+            config.curve ?? "linear"
+          );
+        });
+    const colorEncoding = layer.encoding?.color;
+    const dashEncoding = layer.encoding?.strokeDash;
+    const strokes = colorEncoding?.scale === undefined
+      ? commands.map(
+          (_, index) =>
+            config.stroke ??
+            existingChildren[index]?.properties.stroke ??
+            DEFAULT_LINE_STROKE
+        )
+      : mapOrdinalValues(
+          derived.series.map(series => series.key[colorEncoding.field]),
+          resolved.resolvedScales[colorEncoding.scale].domain,
+          resolved.resolvedScales[colorEncoding.scale].range
+        );
+    const strokeWidths = commands.map(
+      (_, index) =>
+        config.strokeWidth ??
+        existingChildren[index]?.properties.strokeWidth ??
+        DEFAULT_LINE_WIDTH
+    );
+    const strokeDashes = dashEncoding?.datum !== undefined
+      ? commands.map(() => normalizeStrokeDashPattern(dashEncoding.datum))
+      : dashEncoding?.scale === undefined
+      ? commands.map(
+          (_, index) => existingChildren[index]?.properties.strokeDash ?? []
+        )
+      : mapOrdinalValues(
+          derived.series.map(series => series.key[dashEncoding.field]),
+          resolved.resolvedScales[dashEncoding.scale].domain,
+          resolved.resolvedScales[dashEncoding.scale].range
+        );
+
+    let next = resolved
+      .editGraphics({ target: id, property: "length", value: commands.length })
+      .editGraphics({ target: id, property: "commands", value: commands })
+      .editGraphics({ target: id, property: "stroke", value: strokes })
+      .editGraphics({ target: id, property: "strokeWidth", value: strokeWidths })
+      .editGraphics({
+        target: id,
+        property: "strokeDash",
+        value: strokeDashes
+      });
+    if (config.opacity !== undefined) {
+      next = next.editGraphics({
+        target: id,
+        property: "opacity",
+        value: config.opacity
+      });
+    }
+    return next;
+  }
+);
+
+const editLineMark = action(
+  {
+    op: "editLineMark",
+    description: "Edit line-mark curve and stroke width."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, EDIT_OPTIONS, "editLineMark");
+    if (
+      !Object.hasOwn(args, "stroke") &&
+      !Object.hasOwn(args, "strokeWidth") &&
+      !Object.hasOwn(args, "opacity") &&
+      !Object.hasOwn(args, "curve") &&
+      !Object.hasOwn(args, "closed")
+    ) {
+      throw new Error(
+        "editLineMark requires stroke, strokeWidth, opacity, curve, or closed."
+      );
+    }
+    const target = Object.hasOwn(args, "target")
+      ? validateUserId(args.target, "Line mark id")
+      : undefined;
+    const layer = resolveEligibleLayer(this, {
+      target,
+      predicate: candidate => candidate.mark?.type === "line",
+      label: "line mark"
+    });
+    if (Object.hasOwn(args, "stroke") && layer.encoding?.color !== undefined) {
+      throw new Error(
+        "editLineMark stroke cannot be combined with a color encoding."
+      );
+    }
+    if (Object.hasOwn(args, "closed") && args.closed === true &&
+        layer.encoding?.x !== undefined) {
+      throw new Error("Line closed requires theta/radius Polar position encodings.");
+    }
+    if (Object.hasOwn(args, "curve") && isPolarLine(layer) &&
+        args.curve !== "linear") {
+      throw new Error("Polar line position currently requires curve \"linear\".");
+    }
+    const config = {
+      ...this.markConfigs[layer.id],
+      ...(Object.hasOwn(args, "stroke")
+        ? { stroke: validateNonEmptyString(args.stroke, "Line stroke") }
+        : {}),
+      ...(Object.hasOwn(args, "strokeWidth")
+        ? {
+            strokeWidth: validateNonNegativeFinite(
+              args.strokeWidth,
+              "Line strokeWidth"
+            )
+          }
+        : {}),
+      ...(Object.hasOwn(args, "opacity")
+        ? { opacity: validateUnitInterval(args.opacity, "Line opacity") }
+        : {}),
+      ...(Object.hasOwn(args, "curve")
+        ? { curve: validateCurveInterpolation(args.curve) }
+        : {}),
+      ...(Object.hasOwn(args, "closed")
+        ? { closed: validateClosed(args.closed) }
+        : {})
+    };
+    const next = this._withMarkConfig(layer.id, config);
+    return canMaterializeLine(next, layer)
+      ? next.rematerializeLineMark({ id: layer.id })
+      : next;
+  }
+);
+
+export function registerLineMarkActions(ProgramClass) {
+  ProgramClass.prototype.createLineMark = createLineMark;
+  ProgramClass.prototype.editLineMark = editLineMark;
+  ProgramClass.prototype.rematerializeLineMark = rematerializeLineMark;
+}

package/src/actions/marks/line/index.js

@@ -0,0 +1 @@
+export { registerLineMarkActions } from "./actions.js";

package/src/actions/marks/{point.js → point/actions.js}

@@ -1,41 +1,39 @@
-import { action } from "../../core/action.js";
-import { validateUserId } from "../../core/identifiers.js";
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
 import {
   validateNonEmptyString,
   validateNonNegativeFinite,
   validateUnitInterval
-} from "../../core/validation.js";
-import { getPointGraphicType } from "../../grammar/schemas/mark.js";
+} from "../../../core/validation.js";
+import { getPointGraphicType } from "../../../grammar/schemas/mark.js";
 import {
   createPointShapeGraphic,
   validatePointShape
-} from "../../grammar/pointShapes.js";
-import {
-  mapContinuousScaleValues,
-  mapDiscretizedColors,
-  mapOrdinalPositionValues,
-  mapOrdinalValues,
-  mapSequentialColors,
-  readScaleField,
-  readNominalField,
-  readQuantitativeField,
-  readTemporalField
-} from "../../grammar/scales.js";
+} from "../../../grammar/pointShapes.js";
+import { polarToCartesian, resolvePolarFrame } from "../../../grammar/polar.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
 import {
   assertMarkAvailable,
+  applyLayeredMarkInheritance,
+  materializeInheritedMark,
   resolveLayeredMarkInheritance,
   resolveMarkId,
   resolveMarkData,
   validateMarkOptions
-} from "./shared.js";
-import { DEFAULT_COLORS } from "../../theme/defaults.js";
-import { findDataset } from "../../selectors/datasets.js";
-import { findLayer } from "../../selectors/layers.js";
-import { rematerializeExistingLegend } from "../encodings/shared.js";
+} from "../shared.js";
+import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import { findDataset } from "../../../selectors/datasets.js";
+import { findLayer } from "../../../selectors/layers.js";
+import { rematerializeExistingLegend } from "../../encodings/shared.js";
 import { resolveMarkGraphicPlacement } from
-  "../../materialization/graphicHierarchy.js";
+  "../../../materialization/graphicHierarchy.js";
+import { rematerializeHighlightBaseline } from "../lifecycle.js";
+import { resolveRowEncodingValues } from
+  "../../../materialization/rowEncoding.js";
 
-const POINT_MARK_OPTIONS = Object.freeze(["id", "data", "shape"]);
+const POINT_MARK_OPTIONS = Object.freeze([
+  "id", "data", "shape", "fill", "opacity", "stroke", "strokeWidth"
+]);
 const EDIT_POINT_OPTIONS = Object.freeze([
   "target", "shape", "fill", "opacity", "stroke", "strokeWidth"
 ]);
@@ -55,7 +53,7 @@ const createPointMark = action(
       markType: "point",
       operation: "createPointMark"
     });
-    const inherited = resolveLayeredMarkInheritance(this, args);
+    const inherited = resolveLayeredMarkInheritance(this, args, "point");
     const { data, dataset } = resolveMarkData(this, {
       ...args,
       ...(args.data === undefined &&
@@ -80,23 +78,7 @@ const createPointMark = action(
         property: `layer[${id}].data`,
         value: data
       });
-    if (inherited?.coordinate !== undefined) {
-      next = next.editSemantic({
-        property: `layer[${id}].coordinate`,
-        value: inherited.coordinate
-      });
-    }
-    for (const channel of ["x", "y"]) {
-      for (const [property, value] of Object.entries(
-        inherited?.encoding[channel] ?? {}
-      )) {
-        next = next.editSemantic({
-          property: `layer[${id}].encoding.${channel}.${property}`,
-          value
-        });
-      }
-    }
-    next = next
+    next = applyLayeredMarkInheritance(next, id, inherited)
       .createGraphics({
         id,
         type: graphicType,
@@ -104,56 +86,43 @@ const createPointMark = action(
         ...resolveMarkGraphicPlacement(next, { data, markType: "point" })
       })
       ._withMarkConfig(id, { shape });
-    const inheritedEncodings = Object.values(inherited?.encoding ?? {});
-    const canMaterializeInherited = inheritedEncodings.length > 0 &&
-      inheritedEncodings.every(encoding =>
-        encoding.scale !== undefined && next.resolvedScales[encoding.scale] !== undefined
-      );
-    return !canMaterializeInherited
-      ? next
-      : next.rematerializePointMark({ id });
+    const created = materializeInheritedMark(next, id);
+    const appearance = Object.fromEntries(
+      ["fill", "opacity", "stroke", "strokeWidth"]
+        .filter(property => Object.hasOwn(args, property))
+        .map(property => [property, args[property]])
+    );
+    return Object.keys(appearance).length === 0
+      ? created
+      : created.editPointMark({ target: id, ...appearance });
   }
 );
 
-function resolveMappedValues(program, layer, dataset, channel) {
-  const encoding = layer.encoding?.[channel];
-  if (encoding === undefined) return undefined;
-  const scale = program.resolvedScales[encoding.scale];
-  if (scale === undefined) {
-    throw new Error(
-      `Point mark "${layer.id}" requires resolved ${channel} scale "${encoding.scale}".`
-    );
+function resolvePointPositions(program, layer, dataset) {
+  const hasPolar = layer.encoding?.theta !== undefined ||
+    layer.encoding?.radius !== undefined;
+  if (!hasPolar) {
+    return {
+      x: resolveRowEncodingValues(program, layer, dataset, "x"),
+      y: resolveRowEncodingValues(program, layer, dataset, "y")
+    };
   }
-  const ordinal = ["nominal", "ordinal"].includes(encoding.fieldType);
-  const values = Object.hasOwn(scale, "unknown")
-    ? readScaleField(dataset.values, encoding.field, encoding.fieldType, {
-        allowUnknown: true
-      })
-    : ordinal
-      ? readNominalField(dataset.values, encoding.field)
-      : encoding.fieldType === "temporal"
-        ? readTemporalField(dataset.values, encoding.field)
-        : readQuantitativeField(dataset.values, encoding.field);
-  if (channel === "color" && scale.type === "sequential") {
-    return mapSequentialColors(values, scale.domain, scale.range, {
-      interpolation: scale.interpolate,
-      clamp: scale.clamp ?? false,
-      ...(Object.hasOwn(scale, "unknown") ? { unknown: scale.unknown } : {})
-    });
+  const theta = resolveRowEncodingValues(program, layer, dataset, "theta");
+  const radius = resolveRowEncodingValues(program, layer, dataset, "radius");
+  if (theta === undefined || radius === undefined) {
+    return { x: undefined, y: undefined };
   }
-  if (
-    channel === "color" &&
-    ["quantize", "quantile", "threshold"].includes(scale.type)
-  ) {
-    return mapDiscretizedColors(values, scale);
-  }
-  return ordinal
-    ? ["x", "y"].includes(channel)
-      ? mapOrdinalPositionValues(values, scale)
-      : mapOrdinalValues(values, scale.domain, scale.range, {
-          ...(Object.hasOwn(scale, "unknown") ? { unknown: scale.unknown } : {})
-        })
-    : mapContinuousScaleValues(values, scale);
+  const frame = resolvePolarFrame(resolveGraphicBounds(program));
+  const positions = theta.map((angle, index) => {
+    const distance = radius[index];
+    return Number.isFinite(angle) && Number.isFinite(distance)
+      ? polarToCartesian({ theta: angle, radius: distance, frame })
+      : { x: undefined, y: undefined };
+  });
+  return {
+    x: positions.map(position => position.x),
+    y: positions.map(position => position.y)
+  };
 }
 
 function compactProperties(properties) {
@@ -193,22 +162,13 @@ const rematerializePointMark = action(
   function (args = {}) {
     validateMarkOptions(args, REMATERIALIZE_OPTIONS, "rematerializePointMark");
     const id = validateUserId(args.id, "Point mark id");
-    const highlights = Object.entries(
-      this.materializationConfigs.highlights ?? {}
-    ).filter(([, config]) => config.target === id);
-    if (highlights.length > 0) {
-      let baseline = this;
-      for (const [highlightId] of highlights) {
-        baseline = baseline._withoutMaterializationConfig([
-          "highlights",
-          highlightId
-        ]);
-      }
-      return baseline
-        .editGraphics({ target: id, property: "items", value: [] })
-        .rematerializePointMark({ id })
-        .rematerializeMarkHighlights({ target: id, highlights });
-    }
+    const highlighted = rematerializeHighlightBaseline(this, {
+      target: id,
+      operation: "rematerializePointMark",
+      resetProperty: "items",
+      resetValue: []
+    });
+    if (highlighted !== undefined) return highlighted;
     const layer = findLayer(this, id);
     const graphic = this.graphicSpec.objects[id];
 
@@ -223,12 +183,11 @@ const rematerializePointMark = action(
       throw new Error(`Point mark "${id}" requires an existing dataset.`);
     }
 
-    const x = resolveMappedValues(this, layer, dataset, "x");
-    const y = resolveMappedValues(this, layer, dataset, "y");
-    const mappedFill = resolveMappedValues(this, layer, dataset, "color");
-    const area = resolveMappedValues(this, layer, dataset, "size");
-    const encodedShape = resolveMappedValues(this, layer, dataset, "shape");
-    const encodedOpacity = resolveMappedValues(this, layer, dataset, "opacity");
+    const { x, y } = resolvePointPositions(this, layer, dataset);
+    const mappedFill = resolveRowEncodingValues(this, layer, dataset, "color");
+    const area = resolveRowEncodingValues(this, layer, dataset, "size");
+    const encodedShape = resolveRowEncodingValues(this, layer, dataset, "shape");
+    const encodedOpacity = resolveRowEncodingValues(this, layer, dataset, "opacity");
     const config = this.markConfigs[id] ?? {};
     const fill = mappedFill ?? config.fill ?? DEFAULT_POINT_FILL;
     const shapes = encodedShape ?? dataset.values.map(() => config.shape ?? "circle");

package/src/actions/marks/point/index.js

@@ -0,0 +1 @@
+export { registerPointMarkActions } from "./actions.js";