ggaction 0.0.4 → 0.0.5

package/src/actions/marks/area/materialize.js

@@ -0,0 +1,163 @@
+import {
+  deriveAreaSeries,
+  deriveDensityAreaSeries,
+  layoutDensityAreaSeries
+} from "../../../grammar/areaSeries.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalValues
+} from "../../../grammar/scales/index.js";
+import { buildAreaCurvePathCommands } from
+  "../../../grammar/curveCommands.js";
+import { buildLinearPathCommands } from
+  "../../../grammar/pathCommands.js";
+import { buildCategoricalDensityPaths } from
+  "../../../grammar/categoricalDensity.js";
+
+function resolveAreaPaths({
+  derived,
+  densityTransform,
+  categoricalDensity,
+  xScale,
+  yScale,
+  densityScale,
+  layout,
+  curve
+}) {
+  if (categoricalDensity) {
+    return buildCategoricalDensityPaths(derived, {
+      categoryScale: densityTransform.placement.channel === "x" ? xScale : yScale,
+      valueScale: densityTransform.placement.channel === "x" ? yScale : xScale,
+      curve
+    });
+  }
+  return derived.series.map(series => {
+    if (densityTransform === undefined && derived.orientation === "horizontal") {
+      const y = mapContinuousScaleValues(
+        series.values.map(value => value.y),
+        yScale
+      );
+      const lower = mapContinuousScaleValues(
+        series.values.map(value => value.x),
+        xScale
+      );
+      const upper = mapContinuousScaleValues(
+        series.values.map(value => value.x2),
+        xScale
+      );
+      return buildAreaCurvePathCommands(
+        y.map((value, index) => ({ x: lower[index], y: value })),
+        y.map((value, index) => ({ x: upper[index], y: value })),
+        curve,
+        { independentAxis: "y" }
+      );
+    }
+    if (densityTransform !== undefined && derived.mode === "x-density") {
+      const y = mapContinuousScaleValues(
+        series.values.map(value => value.y),
+        yScale
+      );
+      const upper = mapContinuousScaleValues(
+        series.values.map(value => value.x),
+        xScale
+      );
+      const baseline = mapContinuousScaleValues([0], densityScale)[0];
+      if (curve === "linear") {
+        return buildLinearPathCommands([
+          { x: baseline, y: y[0] },
+          ...y.map((value, index) => ({ x: upper[index], y: value })),
+          { x: baseline, y: y.at(-1) }
+        ], { close: true });
+      }
+      return buildAreaCurvePathCommands(
+        y.map(value => ({ x: baseline, y: value })),
+        y.map((value, index) => ({ x: upper[index], y: value })),
+        curve,
+        { independentAxis: "y" }
+      );
+    }
+    const x = mapContinuousScaleValues(
+      series.values.map(value => value.x),
+      xScale
+    );
+    const lowerValues = densityTransform === undefined
+      ? series.values.map(value => value.y)
+      : derived.mode === "y-density"
+        ? series.values.map(value => value.lower)
+        : series.values.map(value => value.y);
+    const lower = mapContinuousScaleValues(lowerValues, yScale);
+    const upperValues = densityTransform === undefined
+      ? series.values.map(value => value.y2)
+      : series.values.map(value => value.upper);
+    const upper = mapContinuousScaleValues(upperValues, yScale);
+    if (densityTransform !== undefined && layout === "overlay") {
+      const baseline = mapContinuousScaleValues([0], yScale)[0];
+      if (curve === "linear") {
+        return buildLinearPathCommands([
+          { x: x[0], y: baseline },
+          ...x.map((value, index) => ({ x: value, y: upper[index] })),
+          { x: x.at(-1), y: baseline }
+        ], { close: true });
+      }
+      return buildAreaCurvePathCommands(
+        x.map(value => ({ x: value, y: baseline })),
+        x.map((value, index) => ({ x: value, y: upper[index] })),
+        curve
+      );
+    }
+    return buildAreaCurvePathCommands(
+      x.map((value, index) => ({ x: value, y: lower[index] })),
+      x.map((value, index) => ({ x: value, y: upper[index] })),
+      curve
+    );
+  });
+}
+
+export function resolveAreaMaterialization({
+  rows,
+  layer,
+  densityTransform,
+  resolvedScales,
+  config
+}) {
+  const xScale = resolvedScales[layer.encoding.x.scale];
+  const yScale = resolvedScales[layer.encoding.y.scale];
+  const rawDerived = densityTransform === undefined
+    ? deriveAreaSeries(rows, layer)
+    : deriveDensityAreaSeries(rows, layer, densityTransform);
+  const colorEncoding = layer.encoding?.color;
+  const layout = colorEncoding?.layout ?? "overlay";
+  const categoricalDensity = densityTransform?.placement?.type === "category";
+  const derived = densityTransform === undefined || categoricalDensity
+    ? rawDerived
+    : layoutDensityAreaSeries(rawDerived, layout);
+  const densityScale = densityTransform === undefined || categoricalDensity
+    ? undefined
+    : derived.mode === "y-density" ? yScale : xScale;
+  if (
+    densityScale !== undefined &&
+    (densityScale.domain[0] > 0 || densityScale.domain[1] < 0)
+  ) {
+    throw new Error(`Density area mark "${layer.id}" requires a scale domain containing zero.`);
+  }
+  const paths = resolveAreaPaths({
+    derived,
+    densityTransform,
+    categoricalDensity,
+    xScale,
+    yScale,
+    densityScale,
+    layout,
+    curve: config.curve ?? "linear"
+  });
+  const fills = config.errorBand?.fill !== undefined
+    ? paths.map(() => config.errorBand.fill)
+    : colorEncoding?.scale === undefined
+      ? paths.map(() => config.fill)
+      : mapOrdinalValues(
+          derived.series.map(series => series.key[colorEncoding.field]),
+          resolvedScales[colorEncoding.scale].domain,
+          resolvedScales[colorEncoding.scale].range
+        );
+  return { paths, fills };
+}

package/src/actions/marks/index.js

@@ -2,7 +2,10 @@ import { registerBarMarkActions } from "./bar/index.js";
 import { registerAreaMarkActions } from "./area/index.js";
 import { registerArcMarkActions } from "./arc/index.js";
 import { registerLineMarkActions } from "./line/index.js";
-import { registerPointMarkActions } from "./point/index.js";
+import {
+  registerPointJitterActions,
+  registerPointMarkActions
+} from "./point/index.js";
 import { registerRectMarkActions } from "./rect/index.js";
 import { registerRuleMarkActions } from "./rule/index.js";
 import { registerTextMarkActions } from "./text/index.js";
@@ -10,6 +13,7 @@ import { removeMark } from "./remove.js";
 
 export function registerMarkActions(ProgramClass) {
   registerPointMarkActions(ProgramClass);
+  registerPointJitterActions(ProgramClass);
   registerRectMarkActions(ProgramClass);
   registerAreaMarkActions(ProgramClass);
   registerArcMarkActions(ProgramClass);

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

@@ -1,6 +1,4 @@
 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,
@@ -19,18 +17,17 @@ import {
 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 { validateCurveInterpolation } from "../../../grammar/curveCommands.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";
+import { validateParallelRows } from "../../../grammar/parallelCoordinates.js";
+import {
+  resolveParallelLineMaterialization,
+  resolvePositionedLineMaterialization
+} from "./materialize.js";
 
 const DEFAULT_LINE_STROKE = DEFAULT_COLORS.mark;
 const DEFAULT_LINE_WIDTH = 2;
@@ -54,7 +51,17 @@ function isPolarLine(layer) {
     layer.encoding?.radius !== undefined;
 }
 
+function isParallelLine(layer) {
+  return layer.encoding?.parallel !== undefined;
+}
+
 function validatePolarLineConfig(layer, config) {
+  if (isParallelLine(layer)) {
+    if ((config.curve ?? "linear") !== "linear" || config.closed === true) {
+      throw new Error("Parallel lines require curve \"linear\" and closed false.");
+    }
+    return;
+  }
   if (!isPolarLine(layer)) return;
   if ((config.curve ?? "linear") !== "linear") {
     throw new Error("Polar line position currently requires curve \"linear\".");
@@ -84,9 +91,6 @@ const createLineMark = action(
       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)
@@ -176,6 +180,7 @@ const rematerializeLineMark = action(
     if (highlighted !== undefined) return highlighted;
     const { dataset, layer } = requireLine(this, id);
     const existingChildren = this.graphicSpec.objects[id].items;
+    const parallel = layer.encoding?.parallel;
     const xScaleId = layer.encoding?.x?.scale;
     const yScaleId = layer.encoding?.y?.scale;
     const thetaScaleId = layer.encoding?.theta?.scale;
@@ -184,6 +189,64 @@ const rematerializeLineMark = action(
     const config = this.markConfigs[id] ?? {};
     validatePolarLineConfig(layer, config);
 
+    if (parallel !== undefined) {
+      validateParallelRows(dataset.values, parallel.dimensions, parallel);
+      let resolved = this;
+      if (args.scales !== false) {
+        for (const dimension of parallel.dimensions) {
+          resolved = resolved.rematerializeScale({ id: dimension.scale });
+        }
+      }
+      for (const channel of args.scales === false
+        ? []
+        : ["color", "strokeDash", "strokeWidth"]) {
+        const scaleId = layer.encoding?.[channel]?.scale;
+        if (scaleId !== undefined) {
+          resolved = resolved.rematerializeScale({ id: scaleId });
+        }
+      }
+      const materialization = resolveParallelLineMaterialization({
+        rows: dataset.values,
+        parallel,
+        layer,
+        resolvedScales: resolved.resolvedScales,
+        bounds: resolveGraphicBounds(resolved),
+        config,
+        existingChildren,
+        defaults: { stroke: DEFAULT_LINE_STROKE, strokeWidth: DEFAULT_LINE_WIDTH }
+      });
+      let next = resolved
+        .editGraphics({
+          target: id,
+          property: "length",
+          value: materialization.commands.length
+        })
+        .editGraphics({
+          target: id,
+          property: "commands",
+          value: materialization.commands
+        })
+        .editGraphics({ target: id, property: "stroke", value: materialization.strokes })
+        .editGraphics({
+          target: id,
+          property: "strokeWidth",
+          value: materialization.strokeWidths
+        })
+        .editGraphics({
+          target: id,
+          property: "strokeDash",
+          value: materialization.strokeDashes
+        });
+      if (config.opacity !== undefined) {
+        next = next.editGraphics({
+          target: id,
+          property: "opacity",
+          value: config.opacity
+        });
+      }
+      return next;
+    }
+
     if (
       polar
         ? thetaScaleId === undefined || radiusScaleId === undefined
@@ -206,85 +269,37 @@ const rematerializeLineMark = action(
             .rematerializeScale({ id: xScaleId })
             .rematerializeScale({ id: yScaleId });
 
-    for (const channel of args.scales === false ? [] : ["color", "strokeDash"]) {
+    for (const channel of args.scales === false ? [] : ["color", "strokeDash", "strokeWidth"]) {
       const scaleId = layer.encoding?.[channel]?.scale;
       if (scaleId !== undefined) {
         resolved = resolved.rematerializeScale({ id: scaleId });
       }
     }
 
-    const derived = deriveLineSeries(
-      dataset.values,
+    const materialization = resolvePositionedLineMaterialization({
+      rows: 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
-        );
+      resolvedScales: resolved.resolvedScales,
+      bounds: resolveGraphicBounds(resolved),
+      config,
+      existingChildren,
+      polar,
+      defaults: { stroke: DEFAULT_LINE_STROKE, strokeWidth: DEFAULT_LINE_WIDTH }
+    });
 
     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: "length",
+        value: materialization.commands.length
+      })
+      .editGraphics({ target: id, property: "commands", value: materialization.commands })
+      .editGraphics({ target: id, property: "stroke", value: materialization.strokes })
+      .editGraphics({ target: id, property: "strokeWidth", value: materialization.strokeWidths })
       .editGraphics({
         target: id,
         property: "strokeDash",
-        value: strokeDashes
+        value: materialization.strokeDashes
       });
     if (config.opacity !== undefined) {
       next = next.editGraphics({
@@ -329,13 +344,17 @@ const editLineMark = action(
       );
     }
     if (Object.hasOwn(args, "closed") && args.closed === true &&
-        layer.encoding?.x !== undefined) {
+        (layer.encoding?.x !== undefined || isParallelLine(layer))) {
       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\".");
     }
+    if (Object.hasOwn(args, "curve") && isParallelLine(layer) &&
+        args.curve !== "linear") {
+      throw new Error("Parallel lines require curve \"linear\".");
+    }
     const config = {
       ...this.markConfigs[layer.id],
       ...(Object.hasOwn(args, "stroke")

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

@@ -0,0 +1,146 @@
+import {
+  deriveLineSeries,
+  deriveLineSeriesFieldValues
+} from "../../../grammar/lineSeries.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalValues,
+  normalizeStrokeDashPattern
+} from "../../../grammar/scales/index.js";
+import { buildCurvePathCommands } from
+  "../../../grammar/curveCommands.js";
+import { buildPolarLinePathCommands } from
+  "../../../grammar/polarLineCommands.js";
+import { resolvePolarFrame } from "../../../grammar/polar.js";
+import { materializeParallelRows } from
+  "../../../grammar/parallelCoordinates.js";
+import { mapScaleConsumerValues } from
+  "../../../materialization/scales/map.js";
+
+function existingValue(children, index, property, fallback) {
+  return children[index]?.properties[property] ?? fallback;
+}
+
+export function resolveParallelLineMaterialization({
+  rows,
+  parallel,
+  layer,
+  resolvedScales,
+  bounds,
+  config,
+  existingChildren,
+  defaults
+}) {
+  const items = materializeParallelRows(
+    rows,
+    parallel.dimensions,
+    resolvedScales,
+    bounds,
+    parallel
+  );
+  const sourceRows = items.map(item => rows[item.sourceRowIndex]);
+  const mapAppearance = (channel, fallback) => {
+    const encoding = layer.encoding?.[channel];
+    if (encoding?.datum !== undefined) {
+      return items.map(() => channel === "strokeDash"
+        ? normalizeStrokeDashPattern(encoding.datum)
+        : encoding.datum);
+    }
+    if (encoding?.scale === undefined) return items.map(fallback);
+    return mapScaleConsumerValues(
+      sourceRows.map(row => row[encoding.field]),
+      resolvedScales[encoding.scale],
+      channel
+    );
+  };
+  return {
+    commands: items.map(item => item.commands),
+    strokes: mapAppearance(
+      "color",
+      (_, index) => config.stroke ??
+        existingValue(existingChildren, index, "stroke", defaults.stroke)
+    ),
+    strokeWidths: mapAppearance(
+      "strokeWidth",
+      (_, index) => config.strokeWidth ??
+        existingValue(existingChildren, index, "strokeWidth", defaults.strokeWidth)
+    ),
+    strokeDashes: mapAppearance(
+      "strokeDash",
+      (_, index) => existingValue(existingChildren, index, "strokeDash", [])
+    )
+  };
+}
+
+export function resolvePositionedLineMaterialization({
+  rows,
+  layer,
+  resolvedScales,
+  bounds,
+  config,
+  existingChildren,
+  polar,
+  defaults
+}) {
+  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 derived = deriveLineSeries(
+    rows,
+    layer,
+    polar ? { thetaDomain: resolvedScales[thetaScaleId].domain } : undefined
+  );
+  const commands = polar
+    ? derived.series.map(series => buildPolarLinePathCommands({
+        series: series.values,
+        thetaFieldType: derived.thetaFieldType,
+        thetaScale: resolvedScales[thetaScaleId],
+        radiusScale: resolvedScales[radiusScaleId],
+        frame: resolvePolarFrame(bounds),
+        closed: config.closed ?? false
+      }))
+    : derived.series.map(series => {
+        const x = mapContinuousScaleValues(
+          series.values.map(value => value.x),
+          resolvedScales[xScaleId]
+        );
+        const y = mapContinuousScaleValues(
+          series.values.map(value => value.y),
+          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 widthEncoding = layer.encoding?.strokeWidth;
+  const strokes = colorEncoding?.scale === undefined
+    ? commands.map((_, index) => config.stroke ??
+        existingValue(existingChildren, index, "stroke", defaults.stroke))
+    : mapOrdinalValues(
+        derived.series.map(series => series.key[colorEncoding.field]),
+        resolvedScales[colorEncoding.scale].domain,
+        resolvedScales[colorEncoding.scale].range
+      );
+  const strokeWidths = widthEncoding?.scale === undefined
+    ? commands.map((_, index) => config.strokeWidth ??
+        existingValue(existingChildren, index, "strokeWidth", defaults.strokeWidth))
+    : mapContinuousScaleValues(
+        deriveLineSeriesFieldValues(rows, layer, derived, widthEncoding.field),
+        resolvedScales[widthEncoding.scale]
+      );
+  const strokeDashes = dashEncoding?.datum !== undefined
+    ? commands.map(() => normalizeStrokeDashPattern(dashEncoding.datum))
+    : dashEncoding?.scale === undefined
+      ? commands.map((_, index) =>
+          existingValue(existingChildren, index, "strokeDash", []))
+      : mapOrdinalValues(
+          derived.series.map(series => series.key[dashEncoding.field]),
+          resolvedScales[dashEncoding.scale].domain,
+          resolvedScales[dashEncoding.scale].range
+        );
+  return { commands, strokes, strokeWidths, strokeDashes };
+}

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

@@ -0,0 +1,76 @@
+import { action } from "../../../core/action.js";
+import { validatePointShape } from "../../../grammar/pointShapes.js";
+import { getPointGraphicType } from "../../../grammar/schemas/mark.js";
+import { resolveMarkGraphicPlacement } from
+  "../../../materialization/graphicHierarchy.js";
+import {
+  applyLayeredMarkInheritance,
+  assertMarkAvailable,
+  materializeInheritedMark,
+  resolveLayeredMarkInheritance,
+  resolveMarkData,
+  resolveMarkId,
+  validateMarkOptions
+} from "../shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "shape", "fill", "opacity", "stroke", "strokeWidth"
+]);
+
+export const createPointMark = action(
+  {
+    op: "createPointMark",
+    description: "Create a semantic point mark and concrete point graphics."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, OPTIONS, "createPointMark");
+    const id = resolveMarkId(this, args.id, {
+      defaultId: "point",
+      label: "Point mark id",
+      markType: "point",
+      operation: "createPointMark"
+    });
+    const inherited = resolveLayeredMarkInheritance(this, args, "point");
+    const { data, dataset } = resolveMarkData(this, {
+      ...args,
+      ...(args.data === undefined &&
+        this.context.currentData === undefined &&
+        inherited?.data !== undefined
+        ? { data: inherited.data }
+        : {})
+    });
+    const shape = Object.hasOwn(args, "shape") ? args.shape : "circle";
+    validatePointShape(shape);
+    const resolvedType = getPointGraphicType(shape);
+    const graphicType = resolvedType === "path" ? "circle" : resolvedType;
+
+    assertMarkAvailable(this, id);
+
+    let next = this
+      .editSemantic({
+        property: `layer[${id}].mark.type`,
+        value: "point"
+      })
+      .editSemantic({
+        property: `layer[${id}].data`,
+        value: data
+      });
+    next = applyLayeredMarkInheritance(next, id, inherited)
+      .createGraphics({
+        id,
+        type: graphicType,
+        length: dataset.values.length,
+        ...resolveMarkGraphicPlacement(next, { data, markType: "point" })
+      })
+      ._withMarkConfig(id, { shape });
+    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 });
+  }
+);