ggaction 0.0.2 → 0.0.4

package/src/actions/encodings/color/continuous.js

@@ -0,0 +1,137 @@
+import {
+  readQuantitativeField,
+  readScaleField,
+  readTemporalField
+} from "../../../grammar/scales/index.js";
+import {
+  BAR_GRAINS,
+  resolveBarChannels,
+  resolveBarGrain
+} from "../../../grammar/bars/policy.js";
+import {
+  validateAggregate,
+  validateAggregateFieldType,
+  validateAggregateFieldValues
+} from "../../../grammar/aggregate.js";
+import {
+  resolveQuantitativeColorScaleDefinition
+} from "../../scales/definitions.js";
+import {
+  resolveReassignmentScaleOptions,
+  resolveTarget
+} from "../shared.js";
+import { applyMaterializationPlan } from "../../../materialization/dependencies.js";
+import {
+  planEncodingRematerialization
+} from "../../../materialization/encodings.js";
+import {
+  assertNoConstantColor,
+  resolveColorScaleOptions
+} from "./policy.js";
+
+export function encodeContinuousColor(program, args) {
+  if (!["quantitative", "temporal"].includes(args.fieldType)) {
+    throw new Error(`Unsupported color field type "${args.fieldType}".`);
+  }
+  if (args.layout !== undefined) {
+    throw new Error("Continuous color does not support layout.");
+  }
+  const { id: target, dataset, layer } = resolveTarget(
+    program,
+    args.target,
+    ["point", "bar", "rect"],
+    "continuous color mark"
+  );
+  assertNoConstantColor(program, layer);
+  const requestedScale = resolveReassignmentScaleOptions(
+    layer.encoding?.color,
+    resolveColorScaleOptions(args)
+  );
+  const scale = resolveQuantitativeColorScaleDefinition(
+    program,
+    args.fieldType,
+    requestedScale
+  );
+  if (Object.hasOwn(scale, "unknown") && layer.mark.type !== "point") {
+    throw new Error(
+      "Continuous color scale unknown currently requires a row-owned point mark."
+    );
+  }
+  if (
+    layer.mark.type === "bar" &&
+    ["nominal", "ordinal"].includes(layer.encoding?.color?.fieldType)
+  ) {
+    throw new Error(
+      "Continuous bar color cannot replace an existing nominal color layout."
+    );
+  }
+  let aggregate;
+  if (["point", "rect"].includes(layer.mark.type)) {
+    if (args.aggregate !== undefined) {
+      throw new Error(`${layer.mark.type} continuous color does not support aggregate.`);
+    }
+  } else {
+    if (args.fieldType !== "quantitative") {
+      throw new Error("Aggregate bar color currently requires a quantitative field.");
+    }
+    if (resolveBarGrain(layer) !== BAR_GRAINS.aggregate) {
+      throw new Error(
+        "Continuous bar color requires a complete categorical aggregate bar."
+      );
+    }
+    const channels = resolveBarChannels(layer);
+    const measure = layer.encoding?.[channels.measure];
+    aggregate = args.aggregate ?? (
+      measure?.field === args.field ? measure.aggregate : undefined
+    );
+    if (aggregate === undefined) {
+      throw new Error(
+        "Continuous bar color requires aggregate when its field differs from the measure field."
+      );
+    }
+    aggregate = validateAggregate(aggregate);
+    validateAggregateFieldType(aggregate, args.fieldType);
+    validateAggregateFieldValues(dataset.values, args.field, args.fieldType);
+  }
+  if (layer.mark.type === "rect") {
+    readScaleField(dataset.values, args.field, args.fieldType, {
+      allowUnknown: true
+    });
+  } else if (Object.hasOwn(scale, "unknown")) {
+    readScaleField(dataset.values, args.field, args.fieldType, {
+      allowUnknown: true
+    });
+  } else if (args.fieldType === "temporal") {
+    readTemporalField(dataset.values, args.field);
+  } else {
+    readQuantitativeField(dataset.values, args.field);
+  }
+  const next = program
+    .editSemantic({
+      property: `layer[${target}].encoding.color.field`,
+      value: args.field
+    })
+    .editSemantic({
+      property: `layer[${target}].encoding.color.fieldType`,
+      value: args.fieldType
+    })
+    .editSemantic({
+      property: `layer[${target}].encoding.color.scale`,
+      value: scale.id
+    });
+  const encoded = aggregate === undefined
+    ? next
+    : next.editSemantic({
+        property: `layer[${target}].encoding.color.aggregate`,
+        value: aggregate
+      });
+  const scaled = encoded.setQuantitativeColorScale(scale);
+  return applyMaterializationPlan(
+    scaled,
+    planEncodingRematerialization(scaled, {
+      target,
+      channel: "color",
+      scale: scale.id
+    })
+  );
+}

package/src/actions/encodings/color/index.js

@@ -0,0 +1,151 @@
+import { action } from "../../../core/action.js";
+import {
+  readNominalField,
+  readScaleField,
+  validateCategoricalFieldType
+} from "../../../grammar/scales/index.js";
+import {
+  resolveBarGrain
+} from "../../../grammar/bars/policy.js";
+import { resolveColorScaleDefinition } from "../../scales/definitions.js";
+import {
+  applyEncodingScale,
+  resolveReassignmentScaleOptions,
+  resolveTarget,
+  validateLineSeriesCompatibility,
+  validateOptions
+} from "../shared.js";
+import { applyMaterializationPlan } from "../../../materialization/dependencies.js";
+import {
+  planEncodingRematerialization
+} from "../../../materialization/encodings.js";
+import { encodeContinuousColor } from "./continuous.js";
+import {
+  applyColorLayoutCompanion,
+  preSynchronizeGroupedOffset
+} from "./layout.js";
+import {
+  assertNoConstantColor,
+  COLOR_ENCODING_OPTIONS,
+  resolveColorLayout,
+  resolveColorScaleOptions
+} from "./policy.js";
+
+const encodeColor = action(
+  {
+    op: "encodeColor",
+    description: "Encode a field as graphical color."
+  },
+  function (args = {}) {
+    validateOptions(args, COLOR_ENCODING_OPTIONS, "encodeColor");
+    const requestedFieldType = args.fieldType ?? "nominal";
+    if (!["nominal", "ordinal"].includes(requestedFieldType)) {
+      return encodeContinuousColor(this, {
+        ...args,
+        fieldType: requestedFieldType
+      });
+    }
+    if (args.aggregate !== undefined) {
+      throw new Error("Categorical color does not support aggregate.");
+    }
+    const fieldType = validateCategoricalFieldType(requestedFieldType);
+    const { id: target, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      ["point", "line", "bar", "area", "arc", "rect"],
+      "color mark"
+    );
+    assertNoConstantColor(this, layer);
+    if (
+      layer.mark.type === "area" &&
+      (layer.encoding?.group?.field === undefined ||
+        layer.encoding.group.field !== args.field)
+    ) {
+      throw new Error(
+        "Area color encoding must match an existing group encoding."
+      );
+    }
+    validateLineSeriesCompatibility(layer, "color", args.field);
+
+    const barGrain = resolveBarGrain(layer);
+    if (layer.mark.type === "bar" && barGrain === undefined) {
+      throw new Error(
+        "Bar color encoding requires a complete histogram encoding or a complete ordinal aggregate encoding."
+      );
+    }
+    const layout = resolveColorLayout(layer, args.layout, barGrain);
+    const requestedScale = resolveReassignmentScaleOptions(
+      layer.encoding?.color,
+      resolveColorScaleOptions(args)
+    );
+    const scale = resolveColorScaleDefinition(this, requestedScale);
+    if (Object.hasOwn(scale, "unknown") && layer.mark.type !== "point") {
+      throw new Error(
+        "Categorical color scale unknown currently requires a row-owned point mark."
+      );
+    }
+    if (layer.mark.type === "rect") {
+      readScaleField(dataset.values, args.field, fieldType, {
+        allowUnknown: true
+      });
+    } else if (Object.hasOwn(scale, "unknown")) {
+      readScaleField(dataset.values, args.field, fieldType, {
+        allowUnknown: true
+      });
+    } else {
+      readNominalField(dataset.values, args.field);
+    }
+
+    let next = this
+      .editSemantic({
+        property: `layer[${target}].encoding.color.field`,
+        value: args.field
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.color.fieldType`,
+        value: fieldType
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.color.scale`,
+        value: scale.id
+      });
+    if (layout !== undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.color.layout`,
+        value: layout
+      });
+    }
+    next = preSynchronizeGroupedOffset(next, {
+      target,
+      layer,
+      layout,
+      field: args.field,
+      fieldType,
+      scale,
+      requestedScale
+    });
+    next = applyEncodingScale(next, scale, requestedScale, {
+      reassignment: layer.encoding?.color?.scale === scale.id
+    });
+    next = applyColorLayoutCompanion(next, {
+      target,
+      layer,
+      layout,
+      scale,
+      field: args.field
+    });
+
+    return applyMaterializationPlan(
+      next,
+      planEncodingRematerialization(next, {
+        target,
+        channel: "color",
+        scale: scale.id
+      })
+    );
+  }
+);
+
+export function registerColorEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeColor = encodeColor;
+}

package/src/actions/encodings/color/layout.js

@@ -0,0 +1,91 @@
+import {
+  BAR_GRAINS,
+  resolveBarChannels,
+  resolveBarGrain,
+  resolveBarOffsetChannel
+} from "../../../grammar/bars/policy.js";
+import { resolveOffsetScaleDefinition } from "../../scales/definitions.js";
+import { isRangedArea } from "./policy.js";
+
+export function applyColorLayoutCompanion(
+  program,
+  { target, layer, layout, scale, field }
+) {
+  if (layout === undefined || layer.mark.type === "arc") return program;
+  if (
+    layer.mark.type === "bar" &&
+    resolveBarGrain(layer) === BAR_GRAINS.ranged
+  ) {
+    return program;
+  }
+  if (isRangedArea(layer)) return program;
+  const channels = layer.mark.type === "bar"
+    ? resolveBarChannels(layer)
+    : undefined;
+  const measureChannel = channels?.measure ?? "y";
+  const measure = layer.encoding?.[measureChannel];
+  if (measure?.field === undefined || measure.scale === undefined) {
+    throw new Error(`Color layout on mark "${target}" requires a measure encoding.`);
+  }
+  const stack = layout === "fill"
+    ? "normalize"
+    : layout === "overlay" || layout === "group"
+      ? null
+      : "zero";
+  let next = program;
+  if (layout === "group") {
+    const offsetChannel = resolveBarOffsetChannel(layer);
+    const method = offsetChannel === "xOffset" ? "encodeXOffset" : "encodeYOffset";
+    next = next[method]({
+      field,
+      target,
+      scale: {
+        ...(layer.encoding?.[offsetChannel]?.scale === undefined
+          ? {}
+          : { id: layer.encoding[offsetChannel].scale }),
+        domain: scale.domain
+      }
+    });
+  }
+  return next[measureChannel === "x" ? "encodeX" : "encodeY"]({
+    target,
+    field: measure.field,
+    fieldType: measure.fieldType,
+    ...(measure.aggregate === undefined ? {} : { aggregate: measure.aggregate }),
+    stack
+  });
+}
+
+export function preSynchronizeGroupedOffset(
+  program,
+  { target, layer, layout, field, fieldType, scale, requestedScale }
+) {
+  if (
+    layer.mark.type !== "bar" ||
+    layout !== "group" ||
+    layer.encoding?.color?.scale !== scale.id ||
+    !Object.keys(requestedScale).some(key => key !== "id")
+  ) {
+    return program;
+  }
+  const offsetChannel = resolveBarOffsetChannel(layer);
+  const offset = layer.encoding?.[offsetChannel];
+  if (offset?.scale === undefined) return program;
+  const offsetScale = resolveOffsetScaleDefinition(program, {
+    id: offset.scale,
+    domain: scale.domain
+  }, offsetChannel);
+  return program
+    .editSemantic({
+      property: `layer[${target}].encoding.${offsetChannel}.field`,
+      value: field
+    })
+    .editSemantic({
+      property: `layer[${target}].encoding.${offsetChannel}.fieldType`,
+      value: fieldType
+    })
+    .editSemantic({
+      property: `scale[${offsetScale.id}].domain`,
+      value: offsetScale.domain
+    });
+}

package/src/actions/encodings/color/policy.js

@@ -0,0 +1,88 @@
+import {
+  BAR_GRAINS,
+  inferBarColorLayout
+} from "../../../grammar/bars/policy.js";
+import { validateColorLayout } from "../../../grammar/seriesLayout.js";
+
+export const COLOR_ENCODING_OPTIONS = Object.freeze([
+  "field", "target", "fieldType", "scale", "palette", "layout", "aggregate"
+]);
+
+export function resolveColorScaleOptions(args) {
+  const options = args.scale ?? {};
+  if (args.palette === undefined) return options;
+  if (options.palette !== undefined || options.range !== undefined) {
+    throw new Error(
+      "encodeColor palette cannot be combined with scale.palette or scale.range."
+    );
+  }
+  return { ...options, palette: args.palette };
+}
+
+export function assertNoConstantColor(program, layer) {
+  const config = program.markConfigs[layer.id];
+  const hasConstant = {
+    point: config?.fill !== undefined,
+    line: config?.stroke !== undefined,
+    bar: config?.barAppearance?.fill !== undefined,
+    arc: config?.fill !== undefined,
+    rect: config?.fillExplicit === true
+  }[layer.mark.type] ?? false;
+  if (hasConstant) {
+    throw new Error(
+      `encodeColor cannot replace constant appearance on ${layer.mark.type} mark "${layer.id}".`
+    );
+  }
+}
+
+export function isRangedArea(layer) {
+  return layer.mark.type === "area" && (
+    layer.encoding?.x2 !== undefined ||
+    layer.encoding?.y2 !== undefined
+  );
+}
+
+export function resolveColorLayout(layer, requested, barGrain) {
+  const existing = layer.encoding?.color === undefined
+    ? undefined
+    : layer.encoding.color.layout ?? (
+        layer.mark.type === "bar"
+          ? inferBarColorLayout(layer)
+          : layer.mark.type === "area"
+            ? "overlay"
+            : undefined
+      );
+  if (requested !== undefined) validateColorLayout(requested);
+  if (existing !== undefined && requested !== undefined && requested !== existing) {
+    throw new Error(
+      `Color layout transition from "${existing}" to "${requested}" is not supported.`
+    );
+  }
+  const layout = requested ?? existing ?? (
+    layer.mark.type === "bar"
+      ? barGrain === BAR_GRAINS.histogram
+        ? "stack"
+        : barGrain === BAR_GRAINS.ranged ? "overlay" : "group"
+      : layer.mark.type === "area"
+        ? "overlay"
+        : undefined
+  );
+
+  if (["point", "line", "rect"].includes(layer.mark.type) && layout !== undefined) {
+    throw new Error(`Color layout is not supported for ${layer.mark.type} marks.`);
+  }
+  if (layer.mark.type === "area" && layout === "group") {
+    throw new Error('Area color layout does not support "group".');
+  }
+  if (
+    layer.mark.type === "arc" &&
+    layout !== undefined &&
+    layout !== "overlay"
+  ) {
+    throw new Error('Arc color layout currently supports only "overlay".');
+  }
+  if (isRangedArea(layer) && layout !== "overlay") {
+    throw new Error('Ranged area color encoding supports only "overlay" layout.');
+  }
+  return layout;
+}

package/src/actions/encodings/index.js

@@ -1,13 +1,14 @@
 import { registerAppearanceEncodingAction } from "./appearance.js";
 import { registerBarWidthEncodingAction } from "./barWidth.js";
-import { registerColorEncodingAction } from "./color.js";
+import { registerColorEncodingAction } from "./color/index.js";
 import { registerDensityEncodingAction } from "./density.js";
 import { registerHistogramEncodingAction } from "./histogram.js";
 import { registerOffsetEncodingAction } from "./offset.js";
-import { registerPositionEncodingActions } from "./position.js";
+import { registerPositionEncodingActions } from "./position/index.js";
 import { registerRangedEncodingActions } from "./ranged.js";
 import { registerStrokeDashEncodingActions } from "./strokeDash.js";
 import { registerRuleAppearanceEncodingActions } from "./ruleAppearance.js";
+import { registerTextEncodingAction } from "./text.js";
 
 export function registerEncodingActions(ProgramClass) {
   registerPositionEncodingActions(ProgramClass);
@@ -20,4 +21,5 @@ export function registerEncodingActions(ProgramClass) {
   registerStrokeDashEncodingActions(ProgramClass);
   registerAppearanceEncodingAction(ProgramClass);
   registerRuleAppearanceEncodingActions(ProgramClass);
+  registerTextEncodingAction(ProgramClass);
 }

package/src/actions/encodings/offset.js

@@ -1,8 +1,8 @@
 import { action } from "../../core/action.js";
 import {
   readNominalField,
-  validateNominalFieldType
-} from "../../grammar/scales.js";
+  validateCategoricalFieldType
+} from "../../grammar/scales/index.js";
 import { resolveOffsetScaleDefinition } from "../scales/definitions.js";
 import {
   applyEncodingScale,
@@ -12,6 +12,7 @@ import {
 } from "./shared.js";
 import {
   resolveBarColorLayout,
+  resolveBarChannels,
   resolveBarGrain
 } from "../../grammar/bars/policy.js";
 import { normalizeOffsetPadding } from "../../grammar/bars/geometry.js";
@@ -21,84 +22,101 @@ import { planEncodingRematerialization } from "../../materialization/encodings.j
 const ENCODING_OPTIONS = Object.freeze([
   "field", "target", "fieldType", "scale", "paddingInner", "paddingOuter"
 ]);
-const encodeXOffset = action(
-  {
-    op: "encodeXOffset",
-    description: "Encode a nominal field within each ordinal x band."
-  },
-  function (args = {}) {
-    validateOptions(args, ENCODING_OPTIONS, "encodeXOffset");
-    const fieldType = validateNominalFieldType(args.fieldType ?? "nominal");
-    const { id: target, dataset, layer } = resolveTarget(
-      this,
-      args.target,
-      ["bar"],
-      "bar mark"
-    );
+function createOffsetEncoding(channel) {
+  const operation = channel === "xOffset" ? "encodeXOffset" : "encodeYOffset";
+  const parentChannel = channel === "xOffset" ? "x" : "y";
+  return action(
+    {
+      op: operation,
+      description: `Encode a categorical field within each ${parentChannel} category band.`
+    },
+    function (args = {}) {
+      validateOptions(args, ENCODING_OPTIONS, operation);
+      const fieldType = validateCategoricalFieldType(args.fieldType ?? "nominal");
+      const { id: target, dataset, layer } = resolveTarget(
+        this,
+        args.target,
+        ["bar"],
+        "bar mark"
+      );
+
+      const channels = resolveBarChannels(layer);
+      if (
+        resolveBarGrain(layer) === undefined ||
+        channels?.category !== parentChannel
+      ) {
+        throw new Error(
+          `${operation} requires a complete bar with a ${parentChannel} category encoding.`
+        );
+      }
+      if (
+        layer.encoding?.color !== undefined &&
+        (resolveBarColorLayout(layer) !== "group" ||
+          layer.encoding.color.field !== args.field)
+      ) {
+        throw new Error(
+          `${operation} field must match a grouped bar color field.`
+        );
+      }
 
-    if (
-      resolveBarGrain(layer) === undefined ||
-      layer.encoding.x.scale === undefined
-    ) {
-      throw new Error(
-        "encodeXOffset requires a complete bar x/y encoding."
+      readNominalField(dataset.values, args.field);
+      const requestedScale = resolveReassignmentScaleOptions(
+        layer.encoding?.[channel],
+        args.scale ?? {}
       );
-    }
-    if (
-      layer.encoding?.color !== undefined &&
-      (resolveBarColorLayout(layer) !== "group" ||
-        layer.encoding.color.field !== args.field)
-    ) {
-      throw new Error(
-        "encodeXOffset field must match a grouped bar color field."
+      const scale = resolveOffsetScaleDefinition(this, requestedScale, channel);
+      if (Object.hasOwn(scale, "unknown")) {
+        throw new Error(
+          `${channel} scale unknown is not supported for grouped bars.`
+        );
+      }
+      const padding = normalizeOffsetPadding(
+        args,
+        this.markConfigs[target]?.[channel],
+        channel
       );
-    }
 
-    readNominalField(dataset.values, args.field);
-    const requestedScale = resolveReassignmentScaleOptions(
-      layer.encoding?.xOffset,
-      args.scale ?? {}
-    );
-    const scale = resolveOffsetScaleDefinition(this, requestedScale);
-    if (Object.hasOwn(scale, "unknown")) {
-      throw new Error("xOffset scale unknown is not supported for grouped bars.");
+      let next = this
+        .editSemantic({
+          property: `layer[${target}].encoding.${channel}.field`,
+          value: args.field
+        })
+        .editSemantic({
+          property: `layer[${target}].encoding.${channel}.fieldType`,
+          value: fieldType
+        })
+        .editSemantic({
+          property: `layer[${target}].encoding.${channel}.scale`,
+          value: scale.id
+        })
+        ._withMarkConfig(target, {
+          ...this.markConfigs[target],
+          [channel]: padding
+        });
+      next = applyEncodingScale(next, scale, requestedScale, {
+        reassignment: layer.encoding?.[channel]?.scale === scale.id
+      });
+      if (layer.encoding?.color === undefined) {
+        return next
+          .rematerializeScale({ id: scale.id })
+          .editGraphics({ target, property: "length", value: 0 });
+      }
+      return applyMaterializationPlan(
+        next,
+        planEncodingRematerialization(next, {
+          target,
+          channel,
+          scale: scale.id
+        })
+      );
     }
-    const padding = normalizeOffsetPadding(
-      args,
-      this.markConfigs[target]?.xOffset
-    );
+  );
+}
 
-    let next = this
-      .editSemantic({
-        property: `layer[${target}].encoding.xOffset.field`,
-        value: args.field
-      })
-      .editSemantic({
-        property: `layer[${target}].encoding.xOffset.fieldType`,
-        value: fieldType
-      })
-      .editSemantic({
-        property: `layer[${target}].encoding.xOffset.scale`,
-        value: scale.id
-      })
-      ._withMarkConfig(target, {
-        ...this.markConfigs[target],
-        xOffset: padding
-      });
-    next = applyEncodingScale(next, scale, requestedScale, {
-      reassignment: layer.encoding?.xOffset?.scale === scale.id
-    });
-    return applyMaterializationPlan(
-      next,
-      planEncodingRematerialization(next, {
-        target,
-        channel: "xOffset",
-        scale: scale.id
-      })
-    );
-  }
-);
+const encodeXOffset = createOffsetEncoding("xOffset");
+const encodeYOffset = createOffsetEncoding("yOffset");
 
 export function registerOffsetEncodingAction(ProgramClass) {
   ProgramClass.prototype.encodeXOffset = encodeXOffset;
+  ProgramClass.prototype.encodeYOffset = encodeYOffset;
 }