ggaction 0.0.13 → 0.0.15

package/src/actions/encodings/stroke.js

@@ -0,0 +1,226 @@
+import { action } from "../../core/action.js";
+import {
+  readNominalField,
+  readQuantitativeField,
+  readScaleField,
+  readTemporalField,
+  resolveTemporalUnit,
+  validateCategoricalFieldType
+} from "../../grammar/scales/index.js";
+import { validateContinuousColorConsumer } from
+  "../../grammar/scales/colorConsumers.js";
+import { validatePathSeriesAppearance } from "../../grammar/pathSeries.js";
+import { validateRuleStroke } from "../../grammar/ruleAppearance.js";
+import { assertEncodingSelectionCompatibility } from
+  "../../materialization/selection/compatibility.js";
+import {
+  resolveColorScaleDefinition,
+  resolveQuantitativeColorScaleDefinition
+} from "../scales/definitions.js";
+import { applyTemporalUnit } from "./temporal.js";
+import {
+  applyEncodingScale,
+  rematerializeEncoding,
+  resolveReassignmentScaleOptions,
+  resolveTarget,
+  setEncodingProperties,
+  validateOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "target", "value", "field", "fieldType", "temporalUnit", "scale"
+]);
+const MARK_TYPES = Object.freeze([
+  "point", "line", "area", "bar", "rect", "arc", "rule", "tick"
+]);
+
+function withoutConstantStroke(program, layer) {
+  const config = { ...program.markConfigs[layer.id] };
+  if (layer.mark.type === "bar") {
+    const appearance = { ...config.barAppearance };
+    delete appearance.stroke;
+    config.barAppearance = appearance;
+  } else {
+    delete config.stroke;
+    if (layer.mark.type === "area") delete config.strokeFromFill;
+  }
+  return program._withMarkConfig(layer.id, config);
+}
+
+function withConstantStroke(program, layer, value) {
+  const config = { ...program.markConfigs[layer.id] };
+  if (layer.mark.type === "bar") {
+    const appearance = { ...config.barAppearance, stroke: value };
+    if (config.barAppearance?.stroke === false && appearance.strokeWidth === undefined) {
+      appearance.strokeWidth = 0.5;
+    }
+    config.barAppearance = appearance;
+  } else {
+    const restores = config.stroke === false;
+    config.stroke = value;
+    if (layer.mark.type === "area") delete config.strokeFromFill;
+    if (
+      (restores || ["point", "area"].includes(layer.mark.type)) &&
+      config.strokeWidth === undefined
+    ) {
+      config.strokeWidth = 1;
+    }
+  }
+  return program._withMarkConfig(layer.id, config);
+}
+
+function hasStrokeLegend(program, target) {
+  return Object.values(program.guideConfigs.legend ?? {}).some(config =>
+    config?.target === target && (
+      config.channel === "stroke" || config.channels?.includes("stroke")
+    )
+  );
+}
+
+function validateStrokeField(dataset, layer, args, scale, temporalUnit) {
+  const { field, fieldType } = args;
+  validateContinuousColorConsumer(layer, args, scale, { channel: "stroke" });
+  if (["line", "area"].includes(layer.mark.type)) {
+    validatePathSeriesAppearance(dataset.values, {
+      ...layer,
+      encoding: {
+        ...layer.encoding,
+        stroke: { field, fieldType, temporalUnit, scale: scale.id }
+      }
+    });
+  }
+  if (Object.hasOwn(scale, "unknown")) {
+    readScaleField(dataset.values, field, fieldType, {
+      allowUnknown: true,
+      temporalUnit
+    });
+  } else if (fieldType === "temporal") {
+    readTemporalField(dataset.values, field, temporalUnit);
+  } else {
+    readQuantitativeField(dataset.values, field);
+  }
+}
+
+export const encodeStroke = action(
+  {
+    op: "encodeStroke",
+    description: "Assign constant or field-driven graphical stroke color."
+  },
+  function (args = {}) {
+    validateOptions(args, OPTIONS, "encodeStroke");
+    const hasValue = Object.hasOwn(args, "value");
+    const hasField = Object.hasOwn(args, "field");
+    if (hasValue === hasField) {
+      throw new Error("encodeStroke requires exactly one of value or field.");
+    }
+    if (hasValue && (
+      args.fieldType !== undefined ||
+      args.temporalUnit !== undefined ||
+      args.scale !== undefined
+    )) {
+      throw new Error(
+        "Constant stroke does not accept fieldType, temporalUnit, or scale."
+      );
+    }
+    const { id: target, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      MARK_TYPES,
+      "stroke-capable mark"
+    );
+
+    if (hasValue) {
+      const value = validateRuleStroke(args.value);
+      if (
+        layer.mark.type === "rule" &&
+        layer.encoding?.stroke === undefined &&
+        !hasStrokeLegend(this, target)
+      ) {
+        return this
+          ._withMarkConfig(target, { ...this.markConfigs[target], stroke: value })
+          .rematerializeRuleMark({ id: target });
+      }
+      assertEncodingSelectionCompatibility(this, target, ["stroke"]);
+      let next = hasStrokeLegend(this, target)
+        ? this.removeLegend({ target, channels: ["stroke"] })
+        : this;
+      if (layer.encoding?.stroke !== undefined) {
+        next = next.editSemantic({
+          property: `layer[${target}].encoding.stroke`,
+          remove: true
+        });
+      }
+      next = withConstantStroke(next, layer, value);
+      return rematerializeEncoding(next, target, "stroke", undefined, layer);
+    }
+
+    const fieldType = args.fieldType ?? "nominal";
+    const previous = layer.encoding?.stroke;
+    const temporalUnit = resolveTemporalUnit(args, fieldType, previous);
+    const requestedScale = resolveReassignmentScaleOptions(
+      previous,
+      args.scale ?? {}
+    );
+    let scale;
+    if (["nominal", "ordinal"].includes(fieldType)) {
+      validateCategoricalFieldType(fieldType);
+      if (temporalUnit !== undefined) {
+        throw new Error("Categorical stroke does not support temporalUnit.");
+      }
+      scale = resolveColorScaleDefinition(this, requestedScale, "stroke");
+      if (Object.hasOwn(scale, "unknown")) {
+        readScaleField(dataset.values, args.field, fieldType, {
+          allowUnknown: true
+        });
+      } else {
+        readNominalField(dataset.values, args.field);
+      }
+      if (["line", "area"].includes(layer.mark.type)) {
+        validatePathSeriesAppearance(dataset.values, {
+          ...layer,
+          encoding: {
+            ...layer.encoding,
+            stroke: {
+              field: args.field,
+              fieldType,
+              scale: scale.id
+            }
+          }
+        });
+      }
+    } else if (["quantitative", "temporal"].includes(fieldType)) {
+      scale = resolveQuantitativeColorScaleDefinition(
+        this,
+        fieldType,
+        requestedScale,
+        "stroke"
+      );
+      validateStrokeField(
+        dataset,
+        layer,
+        { ...args, fieldType },
+        scale,
+        temporalUnit
+      );
+    } else {
+      throw new Error(`Unsupported stroke field type "${fieldType}".`);
+    }
+
+    let next = withoutConstantStroke(this, layer);
+    next = applyTemporalUnit(next, target, "stroke", temporalUnit, previous);
+    next = setEncodingProperties(next, target, "stroke", {
+      field: args.field,
+      fieldType,
+      scale: scale.id
+    });
+    next = applyEncodingScale(next, scale, requestedScale, {
+      reassignment: previous?.scale === scale.id,
+      allowTypeChange: true
+    });
+    return rematerializeEncoding(next, target, "stroke", scale.id, layer);
+  }
+);
+
+export function registerStrokeEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeStroke = encodeStroke;
+}

package/src/actions/errorBands/create.js

@@ -6,6 +6,10 @@ import {
 } from "../../core/validation.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
 import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
+import {
+  requestedStrokeDetails,
+  STROKE_STYLE_PROPERTIES
+} from "../../grammar/strokeStyle.js";
 import { createResolvedIntervalData } from "../data/intervalEdit.js";
 import { resolveIntervalComposite } from "../intervals/resolve.js";
 import { errorBandBoundaries, resolveBoundaryAppearance } from "./edit.js";
@@ -21,6 +25,7 @@ const OPTIONS = Object.freeze([
   "fill",
   "opacity",
   "curve",
+  ...STROKE_STYLE_PROPERTIES,
   "boundaries"
 ]);
 
@@ -96,11 +101,24 @@ export const createErrorBandBoundary = action(
     strokeWidth,
     strokeDash,
     opacity,
-    curve
+    curve,
+    lineCap,
+    lineJoin,
+    miterLimit
   } = {}) {
     const vertical = orientation === "vertical";
     let next = this
-      .createLineMark({ id, data, strokeWidth, curve })
+      .createLineMark({
+        id,
+        data,
+        strokeWidth,
+        curve,
+        ...requestedStrokeDetails(Object.fromEntries([
+          ["lineCap", lineCap],
+          ["lineJoin", lineJoin],
+          ["miterLimit", miterLimit]
+        ].filter(([, value]) => value !== undefined)), "Error-band boundary")
+      })
       .encodeY(positionOptions({
         target: id,
         field: vertical ? bound : position.field,
@@ -160,6 +178,7 @@ export const createErrorBand = action(
   },
   function (args = {}) {
     validateKeys(args, OPTIONS, "createErrorBand");
+    const strokeDetails = requestedStrokeDetails(args, "createErrorBand");
     const resolved = resolveErrorBand(this, args);
     const curve = validateCurveInterpolation(args.curve ?? "linear");
     const boundaries = resolveBoundaries(args.boundaries, curve);
@@ -170,7 +189,8 @@ export const createErrorBand = action(
       data: resolved.dataId,
       ...(args.fill === undefined ? {} : { fill: args.fill }),
       ...(args.opacity === undefined ? {} : { opacity: args.opacity }),
-      ...(Object.hasOwn(args, "curve") ? { curve } : {})
+      ...(Object.hasOwn(args, "curve") ? { curve } : {}),
+      ...strokeDetails
     });
     const vertical = resolved.orientation === "vertical";
     next = next[vertical ? "encodeX" : "encodeY"](positionArgs(resolved));

package/src/actions/errorBands/edit.js

@@ -10,6 +10,10 @@ import {
 } from "../../core/validation.js";
 import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
 import { normalizeStrokeDashPattern } from "../../grammar/scales/index.js";
+import {
+  requestedStrokeDetails,
+  STROKE_STYLE_PROPERTIES
+} from "../../grammar/strokeStyle.js";
 import { findLayer } from "../../selectors/layers.js";
 import { findSemanticScale } from "../../selectors/scales.js";
 import { removeOwnedMark } from "../marks/remove.js";
@@ -32,7 +36,8 @@ import {
 } from "../data/intervalEdit.js";
 
 export const ERROR_BAND_BOUNDARY_OPTIONS = Object.freeze([
-  "stroke", "strokeWidth", "strokeDash", "opacity", "curve"
+  "stroke", "strokeWidth", "strokeDash", "opacity", "curve",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 
 export function resolveBoundaryAppearance(value, { defaults, operation }) {
@@ -49,12 +54,19 @@ export function resolveBoundaryAppearance(value, { defaults, operation }) {
   validateNonNegativeFinite(strokeWidth, `${operation} strokeWidth`);
   const resolvedStrokeDash = normalizeStrokeDashPattern(strokeDash);
   validateUnitInterval(opacity, `${operation} opacity`);
-  return { stroke, strokeWidth, strokeDash: resolvedStrokeDash, opacity, curve };
+  return {
+    stroke,
+    strokeWidth,
+    strokeDash: resolvedStrokeDash,
+    opacity,
+    curve,
+    ...requestedStrokeDetails({ ...defaults, ...value }, operation)
+  };
 }
 
 const EDIT_OPTIONS = Object.freeze([
   "target", "data", "x", "y", "groupBy", "fill", "opacity", "curve",
-  "statistics", "boundaries"
+  "statistics", "boundaries", ...STROKE_STYLE_PROPERTIES
 ]);
 const STATISTICS_OPTIONS = Object.freeze(["center", "extent", "method", "level"]);
 const EDIT_POLICY = Object.freeze({
@@ -331,7 +343,8 @@ function currentBoundaryAppearance(program, id) {
     strokeWidth: config.strokeWidth,
     strokeDash: config.strokeDash,
     opacity: config.opacity,
-    curve: config.curve ?? "linear"
+    curve: config.curve ?? "linear",
+    ...requestedStrokeDetails(config, "Error-band boundary")
   };
 }
 
@@ -397,7 +410,8 @@ export const rematerializeErrorBandBoundary = action(
         strokeWidth: args.strokeWidth,
         strokeDash: args.strokeDash,
         opacity: args.opacity,
-        curve: args.curve
+        curve: args.curve,
+        ...requestedStrokeDetails(args, "Error-band boundary")
       })
       .editGraphics({
         target: id,
@@ -416,12 +430,13 @@ export const editErrorBand = action(
   function (args = {}) {
     validateOptionObject(args, EDIT_OPTIONS, "editErrorBand");
     if (!["data", "x", "y", "groupBy", "fill", "opacity", "curve",
-      "statistics", "boundaries"]
+      "statistics", "boundaries", ...STROKE_STYLE_PROPERTIES]
       .some(key => Object.hasOwn(args, key))) {
       throw new Error("editErrorBand requires at least one change.");
     }
     const owner = resolveOwner(this, args.target);
     const config = { ...this.markConfigs[owner.id] };
+    Object.assign(config, requestedStrokeDetails(args, "editErrorBand"));
     const errorBand = { ...config.errorBand };
     if (Object.hasOwn(args, "fill")) {
       if (args.fill === false) {

package/src/actions/errorBars/create.js

@@ -5,12 +5,14 @@ import {
 } from "../../core/validation.js";
 import { findLayer } from "../../selectors/layers.js";
 import { findDataset } from "../../selectors/datasets.js";
+import { findSemanticScale } from "../../selectors/scales.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
 import {
   readNominalField,
   validateCategoricalFieldType
 } from "../../grammar/scales/index.js";
 import { normalizeOffsetPadding } from "../../grammar/bars/geometry.js";
+import { STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
 import { createResolvedIntervalData, ownOptions } from
   "../data/intervalEdit.js";
 import { resolveIntervalComposite } from "../intervals/resolve.js";
@@ -31,7 +33,8 @@ const OPTIONS = Object.freeze([
   "stroke",
   "strokeWidth",
   "strokeDash",
-  "opacity"
+  "opacity",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 
 const OFFSET_OPTIONS = Object.freeze([
@@ -101,7 +104,15 @@ function resolveErrorBarOffset(program, args, resolved, operation) {
     explicit ?? {},
     resolved.sourceLayer === undefined
       ? undefined
-      : program.markConfigs[resolved.sourceLayer.id]?.[channel],
+      : (() => {
+          const semantic = inferred?.scale === undefined
+            ? undefined
+            : findSemanticScale(program, inferred.scale);
+          return semantic !== undefined && ["paddingInner", "paddingOuter"]
+            .some(property => Object.hasOwn(semantic, property))
+            ? semantic
+            : program.markConfigs[resolved.sourceLayer.id]?.[channel];
+        })(),
     channel
   );
   return {
@@ -118,7 +129,8 @@ function resolveErrorBarOffset(program, args, resolved, operation) {
 
 function resolveAppearance(args) {
   return resolveErrorBarAppearance(ownOptions(args, [
-    "caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"
+    "caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity",
+    ...STROKE_STYLE_PROPERTIES
   ]), {
     defaults: {
       caps: true,
@@ -143,7 +155,8 @@ export const createErrorBarCap = action(
       "intervalField", "coordinate", "positionScale", "intervalScale", "positionTemporalUnit",
       "offsetChannel", "offsetField", "offsetFieldType", "offsetScale",
       "offsetPaddingInner", "offsetPaddingOuter",
-      "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"
+      "capSize", "stroke", "strokeWidth", "strokeDash", "opacity",
+      ...STROKE_STYLE_PROPERTIES
     ], "createErrorBarCap");
     if (!["vertical", "horizontal"].includes(args.orientation)) {
       throw new Error(`Unsupported error-bar orientation "${args.orientation}".`);
@@ -161,7 +174,13 @@ export const createErrorBarCap = action(
     const positionAction = vertical ? "encodeX" : "encodeY";
     const intervalAction = vertical ? "encodeY" : "encodeX";
     let next = this
-      .createRuleMark({ id: args.id, data: args.data })
+      .createRuleMark({
+        id: args.id,
+        data: args.data,
+        ...Object.fromEntries(STROKE_STYLE_PROPERTIES.flatMap(property =>
+          Object.hasOwn(args, property) ? [[property, args[property]]] : []
+        ))
+      })
       [positionAction]({
         target: args.id,
         field: args.positionField,
@@ -247,7 +266,13 @@ export const createErrorBar = action(
     const resolved = resolveErrorBar(this, args);
     const appearance = resolveAppearance(args);
     let next = createResolvedIntervalData(this, resolved);
-    next = next.createRuleMark({ id: resolved.id, data: resolved.dataId });
+    next = next.createRuleMark({
+      id: resolved.id,
+      data: resolved.dataId,
+      ...Object.fromEntries(STROKE_STYLE_PROPERTIES.flatMap(property =>
+        Object.hasOwn(appearance, property) ? [[property, appearance[property]]] : []
+      ))
+    });
     const positionAction = resolved.position.channel === "x" ? "encodeX" : "encodeY";
     const intervalAction = resolved.interval.channel === "x" ? "encodeX" : "encodeY";
     const secondaryAction = resolved.interval.channel === "x" ? "encodeX2" : "encodeY2";
@@ -303,7 +328,10 @@ export const createErrorBar = action(
           stroke: appearance.stroke,
           strokeWidth: appearance.strokeWidth,
           strokeDash: appearance.strokeDash,
-          opacity: appearance.opacity
+          opacity: appearance.opacity,
+          ...Object.fromEntries(STROKE_STYLE_PROPERTIES.flatMap(property =>
+            Object.hasOwn(appearance, property) ? [[property, appearance[property]]] : []
+          ))
         });
       }
     }

package/src/actions/errorBars/edit.js

@@ -31,15 +31,20 @@ import {
   releaseIntervalRevision,
   resolveIntervalOwner
 } from "../data/intervalEdit.js";
+import {
+  requestedStrokeDetails,
+  STROKE_STYLE_PROPERTIES
+} from "../../grammar/strokeStyle.js";
 
 export const ERROR_BAR_EDIT_OPTIONS = Object.freeze([
   "target", "data", "x", "y", "xOffset", "yOffset", "groupBy",
   "caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity",
-  "statistics"
+  "statistics", ...STROKE_STYLE_PROPERTIES
 ]);
 
 export const ERROR_BAR_APPEARANCE_OPTIONS = Object.freeze([
-  "caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"
+  "caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 const STATISTICS_OPTIONS = Object.freeze(["center", "extent", "method", "level"]);
 const EDIT_POLICY = Object.freeze({
@@ -81,7 +86,15 @@ export function resolveErrorBarAppearance(args, { defaults, operation }) {
     args.opacity ?? defaults.opacity,
     `${operation} opacity`
   );
-  return { caps, capSize, stroke, strokeWidth, strokeDash, opacity };
+  return {
+    caps,
+    capSize,
+    stroke,
+    strokeWidth,
+    strokeDash,
+    opacity,
+    ...requestedStrokeDetails({ ...defaults, ...args }, operation)
+  };
 }
 
 const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
@@ -307,7 +320,8 @@ function capArgs(config, id, intervalField) {
     stroke: config.stroke,
     strokeWidth: config.strokeWidth,
     strokeDash: config.strokeDash,
-    opacity: config.opacity
+    opacity: config.opacity,
+    ...requestedStrokeDetails(config, "Error bar")
   };
 }
 
@@ -323,6 +337,7 @@ function rematerializeRuleAppearance(program, id, config, fixedSpan) {
       strokeWidth: config.strokeWidth,
       strokeDash: config.strokeDash,
       opacity: config.opacity,
+      ...requestedStrokeDetails(config, "Error bar"),
       ...(fixedSpan === undefined ? {} : { fixedSpan })
     })
     .rematerializeRuleMark({ id });