ggaction 0.0.12 → 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/encodings/strokeDash.js

@@ -11,10 +11,10 @@ import {
   resolveReassignmentScaleOptions,
   resolveTarget,
   setEncodingProperties,
-  validateLineSeriesCompatibility,
   validateOptions
 } from "./shared.js";
 import { findLayer } from "../../selectors/layers.js";
+import { validatePathSeriesAppearance } from "../../grammar/pathSeries.js";
 
 const STROKE_DASH_ENCODING_OPTIONS = Object.freeze([
   "field", "value", "target", "fieldType", "scale"
@@ -81,6 +81,9 @@ const encodeStrokeDash = action(
     );
     if (hasValue) {
       normalizeStrokeDashPattern(args.value);
+      validatePathSeriesAppearance(dataset.values, {
+        ...layer, encoding: { ...layer.encoding, strokeDash: { datum: args.value } }
+      });
       let next = layer.encoding?.strokeDash === undefined
         ? this
         : this.clearStrokeDashEncoding({ target });
@@ -89,13 +92,13 @@ const encodeStrokeDash = action(
         value: args.value
       });
       next = reconcileLegendAfterDashRemoval(next, target);
-      return layer.mark.type === "rule"
-        ? next.rematerializeRuleMark({ id: target })
-        : next.rematerializeLineMark({ id: target });
+      return rematerializeEncoding(next, target, "strokeDash", undefined, layer);
     }
 
     const fieldType = validateNominalFieldType(args.fieldType ?? "nominal");
-    validateLineSeriesCompatibility(layer, "strokeDash", args.field);
+    validatePathSeriesAppearance(dataset.values, {
+      ...layer, encoding: { ...layer.encoding, strokeDash: { field: args.field, fieldType } }
+    });
     const previous = layer.encoding?.strokeDash;
     const requestedScale = previous?.field === args.field
       ? resolveReassignmentScaleOptions(previous, args.scale ?? {})
@@ -120,7 +123,7 @@ const encodeStrokeDash = action(
       reassignment: previous?.scale === scale.id
     });
 
-    return rematerializeEncoding(next, target, "strokeDash", scale.id);
+    return rematerializeEncoding(next, target, "strokeDash", scale.id, layer);
   }
 );
 

package/src/actions/encodings/temporal.js

@@ -0,0 +1,7 @@
+export function applyTemporalUnit(program, target, channel, unit, previous) {
+  if (unit === previous?.temporalUnit) return program;
+  return program.editSemantic({
+    property: `layer[${target}].encoding.${channel}.temporalUnit`,
+    ...(unit === undefined ? { remove: true } : { value: unit })
+  });
+}

package/src/actions/encodings/text.js

@@ -1,6 +1,8 @@
 import { action } from "../../core/action.js";
 import { formatTextValue, validateTextFormat } from "../../grammar/text.js";
+import { normalizeMarkLabelContent, resolveMarkLabelValues } from "../../grammar/markLabels.js";
 import { canMaterializeText } from "../../materialization/marks/index.js";
+import { resolveMarkItems } from "../../materialization/selection/policies/index.js";
 import { findLayer } from "../../selectors/layers.js";
 import {
   resolveTarget,
@@ -8,7 +10,7 @@ import {
   validateOptions
 } from "./shared.js";
 
-const OPTIONS = Object.freeze(["target", "field", "value", "format"]);
+const OPTIONS = Object.freeze(["target", "field", "value", "content", "normalizeBy", "format"]);
 
 function validateTextField(rows, field, format) {
   if (typeof field !== "string" || field.length === 0) {
@@ -26,14 +28,18 @@ function validateTextField(rows, field, format) {
 export const encodeText = action(
   {
     op: "encodeText",
-    description: "Assign field-driven or constant text content."
+    description: "Assign field, constant, or source semantic text content."
   },
   function (args = {}) {
     validateOptions(args, OPTIONS, "encodeText");
     const hasField = Object.hasOwn(args, "field");
     const hasValue = Object.hasOwn(args, "value");
-    if (hasField === hasValue) {
-      throw new Error("encodeText requires exactly one of field or value.");
+    const hasContent = Object.hasOwn(args, "content");
+    if ([hasField, hasValue, hasContent].filter(Boolean).length !== 1) {
+      throw new Error("encodeText requires exactly one of field, value, or content.");
+    }
+    if (Object.hasOwn(args, "normalizeBy") && (!hasContent || args.content !== "share")) {
+      throw new Error("Text normalizeBy is only supported with share content.");
     }
     const { id: target, dataset, layer } = resolveTarget(
       this,
@@ -43,23 +49,32 @@ export const encodeText = action(
     );
     const previous = layer.encoding?.text;
     const format = validateTextFormat(args.format ?? previous?.format ?? "auto");
+    const content = hasContent
+      ? normalizeMarkLabelContent(findLayer(this, layer.source), args)
+      : undefined;
     if (hasField) validateTextField(dataset.values, args.field, format);
-    else if (formatTextValue(args.value, format) === undefined) {
+    else if (hasValue && formatTextValue(args.value, format) === undefined) {
       throw new Error("encodeText value must produce non-empty text.");
     }
 
+    const properties = {
+      ...(hasContent ? content : { [hasField ? "field" : "datum"]: hasField ? args.field : args.value }),
+      format
+    };
+    const proposed = { ...layer, encoding: { ...layer.encoding, text: properties } };
+    if (hasContent && canMaterializeText(this, proposed)) {
+      const source = findLayer(this, layer.source);
+      for (const value of resolveMarkLabelValues(source, resolveMarkItems(this, source.id), content)) {
+        formatTextValue(value, format);
+      }
+    }
     let next = this;
-    const alternate = hasField ? "datum" : "field";
-    if (Object.hasOwn(previous ?? {}, alternate)) {
-      next = next.editSemantic({
-        property: `layer[${target}].encoding.text.${alternate}`,
-        remove: true
-      });
+    for (const property of ["field", "datum", "content", "normalizeBy"]) {
+      if (Object.hasOwn(previous ?? {}, property) && !Object.hasOwn(properties, property)) {
+        next = next.editSemantic({ property: `layer[${target}].encoding.text.${property}`, remove: true });
+      }
     }
-    next = setEncodingProperties(next, target, "text", {
-      [hasField ? "field" : "datum"]: hasField ? args.field : args.value,
-      format
-    });
+    next = setEncodingProperties(next, target, "text", properties);
     const updated = findLayer(next, target);
     return canMaterializeText(next, updated)
       ? next.rematerializeTextMark({ id: target })

package/src/actions/errorBands/create.js

@@ -2,9 +2,14 @@ import { action } from "../../core/action.js";
 import { isPlainObject } from "../../core/immutable.js";
 import {
   validateKeys,
+  validateNonEmptyString,
 } 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";
@@ -20,10 +25,11 @@ const OPTIONS = Object.freeze([
   "fill",
   "opacity",
   "curve",
+  ...STROKE_STYLE_PROPERTIES,
   "boundaries"
 ]);
 
-const ERROR_BAND_POLICY = Object.freeze({
+export const ERROR_BAND_POLICY = Object.freeze({
   operation: "createErrorBand",
   resourceLabel: "error-band",
   defaultId: "errorBand",
@@ -40,8 +46,8 @@ const ERROR_BAND_POLICY = Object.freeze({
     "createErrorBand cannot infer the interval axis when both positions are quantitative; provide an interval option."
 });
 
-function resolveErrorBand(program, args) {
-  const resolved = resolveIntervalComposite(program, args, ERROR_BAND_POLICY);
+export function resolveErrorBand(program, args, policy = ERROR_BAND_POLICY) {
+  const resolved = resolveIntervalComposite(program, args, policy);
   if (resolved.groupField === resolved.position.field) {
     throw new Error(
       "createErrorBand groupBy must differ from the independent position field."
@@ -71,8 +77,9 @@ function resolveBoundaries(value, areaCurve) {
   });
 }
 
-function positionOptions({ target, field, fieldType, coordinate, scale }) {
-  return { target, field, fieldType, coordinate, scale: { id: scale } };
+function positionOptions({ target, field, fieldType, coordinate, scale, temporalUnit }) {
+  return { target, field, fieldType, coordinate, scale: { id: scale },
+    ...(temporalUnit === undefined ? {} : { temporalUnit }) };
 }
 
 export const createErrorBandBoundary = action(
@@ -94,15 +101,29 @@ 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,
         fieldType: vertical ? "quantitative" : position.fieldType,
+        temporalUnit: vertical ? undefined : position.temporalUnit,
         coordinate,
         scale: vertical ? intervalScale : positionScale
       }))
@@ -110,6 +131,7 @@ export const createErrorBandBoundary = action(
         target: id,
         field: vertical ? position.field : bound,
         fieldType: vertical ? position.fieldType : "quantitative",
+        temporalUnit: vertical ? position.temporalUnit : undefined,
         coordinate,
         scale: vertical ? positionScale : intervalScale
       }));
@@ -132,6 +154,7 @@ function positionArgs(resolved) {
     target: resolved.id,
     field: resolved.position.field,
     fieldType: resolved.position.fieldType,
+    ...(resolved.position.temporalUnit === undefined ? {} : { temporalUnit: resolved.position.temporalUnit }),
     coordinate: resolved.coordinate,
     scale: resolved.position.scale
   };
@@ -155,16 +178,19 @@ 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);
+    if (args.fill !== undefined) validateNonEmptyString(args.fill, "Error-band fill");
     let next = createResolvedIntervalData(this, resolved);
     next = next.createAreaMark({
       id: resolved.id,
       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));
@@ -216,6 +242,13 @@ export const createErrorBand = action(
     return next._withMarkConfig(resolved.id, {
       ...next.markConfigs[resolved.id],
       errorBand: {
+        ...(args.fill === undefined ? {} : { fill: args.fill }),
+        source: resolved.source,
+        intervalMode: resolved.interval.mode,
+        ...(resolved.interval.mode === "statistical"
+          ? { intervalField: resolved.interval.field }
+          : { centerField: resolved.fields.center }),
+        transformGroupBy: resolved.groupBy,
         data: resolved.dataId,
         orientation: resolved.orientation,
         position: resolved.position,