ggaction 0.0.3 → 0.0.5

package/src/actions/scales/editPolicy.js

@@ -0,0 +1,214 @@
+import {
+  hasOrdinalDomain,
+  isDiscretizedColorScaleType,
+  isDiscretePositionScaleType,
+  isTransformedScaleType,
+  normalizeScaleDefinition,
+  SCALE_ROLES,
+  validateColorRange,
+  validateDiscretizedColorDomain,
+  validateDiscretizedColorRange,
+  validateOrdinalDomain,
+  validateScaleDomain,
+  validateScaleRange,
+  validateScaleType,
+  validateScaleTypeForRole,
+  validateScaleUnknown,
+  validateSequentialColorRange,
+  validateShapeRange,
+  validateSizeRange,
+  validateStrokeDashRange,
+  validateStrokeWidthRange
+} from "../../grammar/scales/index.js";
+import {
+  validateRadialRange,
+  validateThetaRange
+} from "../../grammar/polar.js";
+import { normalizePositionScaleChannel } from "../../core/vocabulary.js";
+
+export function resolveScaleConsumerChannel(consumers, id) {
+  const channels = new Set(
+    consumers.map(consumer => normalizePositionScaleChannel(consumer.channel))
+  );
+  if (channels.size > 1) {
+    throw new Error(`Scale "${id}" cannot be shared across channels.`);
+  }
+  return channels.values().next().value;
+}
+
+function validateRangeForChannel(scale, channel, value) {
+  if (value === "auto") return value;
+  if (channel === "theta") return validateThetaRange(value);
+  if (channel === "radius") return validateRadialRange(value);
+  if (scale.type === "sequential") {
+    return validateSequentialColorRange(value);
+  }
+  if (isDiscretizedColorScaleType(scale.type)) {
+    return validateDiscretizedColorRange(value);
+  }
+  if (scale.type !== "ordinal") return validateScaleRange(value);
+  if (channel === "color") return validateColorRange(value);
+  if (channel === "shape") return validateShapeRange(value);
+  if (channel === "strokeDash") return validateStrokeDashRange(value);
+  if (channel === "size") return validateSizeRange(value);
+  if (channel === "strokeWidth") return validateStrokeWidthRange(value);
+  return validateScaleRange(value);
+}
+
+function validateTypeTransition(scale, nextType, channel, consumers) {
+  if (nextType === scale.type) return;
+  validateScaleType(nextType);
+  if (consumers.length === 0) return;
+  if (nextType === "sequential" || isDiscretizedColorScaleType(nextType)) {
+    const discretized = isDiscretizedColorScaleType(nextType);
+    if (channel !== "color" || consumers.some(consumer =>
+      ["nominal", "ordinal"].includes(consumer.encoding.fieldType) ||
+      (discretized && (
+        consumer.encoding.fieldType !== "quantitative" ||
+        consumer.layer.mark?.type !== "point"
+      )) ||
+      (!discretized && !["point", "bar"].includes(consumer.layer.mark?.type))
+    )) {
+      throw new Error(
+        `Scale "${scale.id}" has a consumer incompatible with type "${nextType}".`
+      );
+    }
+    return;
+  }
+  if (nextType === "time") {
+    if (
+      !["x", "y", "theta"].includes(channel) ||
+      consumers.some(consumer => consumer.encoding.fieldType !== "temporal")
+    ) {
+      throw new Error(
+        `Scale "${scale.id}" has a consumer incompatible with type "time".`
+      );
+    }
+    return;
+  }
+  if (isDiscretePositionScaleType(nextType)) {
+    if (
+      !["x", "y", "theta"].includes(channel) || consumers.some(consumer =>
+        !["nominal", "ordinal"].includes(consumer.encoding.fieldType)
+      )
+    ) {
+      throw new Error(
+        `Scale "${scale.id}" has a consumer incompatible with type "${nextType}".`
+      );
+    }
+    if (
+      nextType === "point" &&
+      consumers.some(consumer => consumer.layer.mark?.type === "bar")
+    ) {
+      throw new Error("Point scales cannot provide bar bandwidth.");
+    }
+    return;
+  }
+  const quantitative = nextType === "linear" || isTransformedScaleType(nextType);
+  if (
+    !quantitative ||
+    !["x", "y", "theta", "radius", "strokeWidth"].includes(channel)
+  ) {
+    throw new Error(
+      "editScale type transition currently requires a quantitative position scale."
+    );
+  }
+  validateScaleTypeForRole(nextType, SCALE_ROLES.quantitativePosition);
+  if (channel === "theta" && nextType !== "linear") {
+    throw new Error("Theta quantitative position currently requires a linear scale.");
+  }
+  if (
+    channel === "strokeWidth" &&
+    consumers.some(consumer => !["line", "rule"].includes(consumer.layer.mark?.type))
+  ) {
+    throw new Error(
+      `Scale "${scale.id}" has a consumer incompatible with type "${nextType}".`
+    );
+  }
+  if (consumers.some(consumer => consumer.encoding.fieldType !== "quantitative")) {
+    throw new Error(
+      `Scale "${scale.id}" has a consumer incompatible with type "${nextType}".`
+    );
+  }
+}
+
+function validateLegendTypeTransition(program, scale, nextType) {
+  if (nextType === scale.type) return;
+  const legends = program.guideConfigs.legend ?? {};
+  if (legends.gradient?.scale === scale.id && nextType !== "sequential") {
+    throw new Error(
+      `Scale "${scale.id}" cannot change type while its gradient legend is active.`
+    );
+  }
+  if (
+    legends.interval?.scale === scale.id &&
+    !isDiscretizedColorScaleType(nextType)
+  ) {
+    throw new Error(
+      `Scale "${scale.id}" cannot change type while its interval legend is active.`
+    );
+  }
+}
+
+function normalizeDefinition(scale, channel, consumers, patch) {
+  const type = patch.type ?? scale.type;
+  validateTypeTransition(scale, type, channel, consumers);
+  const definition = normalizeScaleDefinition({
+    type,
+    previous: scale,
+    patch,
+    retainCoreOnTypeChange: true,
+    retainCompatibleOnTypeChange: true,
+    validateDomain: (scaleType, value) =>
+      isDiscretizedColorScaleType(scaleType)
+        ? validateDiscretizedColorDomain(scaleType, value)
+        : hasOrdinalDomain(scaleType)
+          ? validateOrdinalDomain(value)
+          : validateScaleDomain(value),
+    validateRange: (scaleType, value) =>
+      validateRangeForChannel({ type: scaleType }, channel, value)
+  });
+  if (
+    channel === "strokeWidth" &&
+    definition.domain !== "auto" &&
+    definition.domain.some(value => value < 0)
+  ) {
+    throw new RangeError("StrokeWidth scale domain cannot contain negative values.");
+  }
+  const typeChanged = type !== scale.type;
+  const unknown = Object.hasOwn(patch, "unknown")
+    ? patch.unknown
+    : typeChanged ? undefined : scale.unknown;
+  if (unknown !== undefined) {
+    if (consumers.some(consumer => consumer.layer.mark?.type !== "point")) {
+      throw new Error("Scale unknown currently requires row-owned point consumers.");
+    }
+    definition.unknown = consumers.length === 0
+      ? unknown
+      : validateScaleUnknown(channel, unknown);
+  }
+  return definition;
+}
+
+export function prepareScaleEdit(program, scale, channel, consumers, args) {
+  const hasPalette = Object.hasOwn(args, "palette");
+  if (hasPalette && Object.hasOwn(args, "range")) {
+    throw new Error("editScale cannot specify both palette and range.");
+  }
+  if (
+    hasPalette &&
+    channel !== "color" &&
+    scale.type !== "sequential" &&
+    !isDiscretizedColorScaleType(scale.type)
+  ) {
+    throw new Error("editScale palette requires a color scale.");
+  }
+  const patch = !hasPalette
+    ? args
+    : Object.fromEntries([
+        ...Object.entries(args).filter(([key]) => key !== "palette"),
+        ["range", { palette: args.palette }]
+      ]);
+  validateLegendTypeTransition(program, scale, args.type ?? scale.type);
+  return normalizeDefinition(scale, channel, consumers, patch);
+}

package/src/actions/scales/materialize.js

@@ -11,7 +11,7 @@ import {
   canDeferScaleConsumerApplication,
   getMarkRematerializationStep,
   getScaleConsumerMaterializationMode
-} from "../../materialization/marks.js";
+} from "../../materialization/marks/index.js";
 import { mapScaleConsumerValues } from
   "../../materialization/scales/map.js";
 import { resolveScaleMaterialization } from
@@ -21,7 +21,7 @@ import {
   findScaleConsumers,
   resolveConsumerValues,
   resolveSeriesLayoutScaleValues
-} from "./consumers.js";
+} from "./consumers/index.js";
 
 const OPTIONS = Object.freeze(["id", "guides", "marks"]);
 
@@ -70,7 +70,7 @@ export const rematerializeScale = action(
       channel,
       consumers,
       valuesByConsumer,
-      bounds: ["color", "strokeDash", "shape", "size", "opacity", "xOffset", "yOffset"]
+      bounds: ["color", "strokeDash", "strokeWidth", "shape", "size", "opacity", "xOffset", "yOffset"]
         .includes(channel)
         ? undefined
         : resolveGraphicBounds(this),

package/src/actions/scales/patch.js

@@ -0,0 +1,26 @@
+const SCALE_EDIT_PROPERTIES = Object.freeze([
+  "type", "domain", "range", "nice", "zero", "clamp", "reverse",
+  "base", "exponent", "constant", "paddingInner", "paddingOuter",
+  "padding", "align", "interpolate", "unknown"
+]);
+
+function sameValue(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+export function scaleEditPatch(id, definition) {
+  return {
+    id,
+    ...Object.fromEntries(SCALE_EDIT_PROPERTIES
+      .filter(property => Object.hasOwn(definition, property))
+      .map(property => [property, definition[property]]))
+  };
+}
+
+export function changedScaleEditPatch(current, definition) {
+  const patch = scaleEditPatch(current.id, definition);
+  return Object.entries(patch).some(
+    ([property, value]) => property !== "id" &&
+      !sameValue(current[property], value)
+  ) ? patch : undefined;
+}

package/src/actions/selection/actions.js

@@ -117,7 +117,26 @@ export const applyPointHighlight = action(
   }
 );
 
-function applyRectangularHighlight(program, args, operation, markType) {
+function transformRectangularProperties(properties, style, offset = false) {
+  if (!offset || style.offset === undefined) {
+    return { ...properties, ...style };
+  }
+  const { offset: translation, ...appearance } = style;
+  return {
+    ...properties,
+    ...appearance,
+    x: properties.x + translation.x,
+    y: properties.y + translation.y
+  };
+}
+
+function applyRectangularHighlight(
+  program,
+  args,
+  operation,
+  markType,
+  { offset = false } = {}
+) {
   validateKeys(args, INTERNAL_SELECTION_OPTIONS, operation);
   const resolved = resolveStoredSelection(program, args.selection);
   const keys = selectedKeys(args, resolved);
@@ -136,7 +155,7 @@ function applyRectangularHighlight(program, args, operation, markType) {
     value: graphic.items.map(child => ({
       type: child.type ?? graphic.type,
       properties: selected.has(keyByGraphic.get(child.id))
-        ? { ...child.properties, ...args.style }
+        ? transformRectangularProperties(child.properties, args.style, offset)
         : child.properties
     }))
   });
@@ -152,7 +171,13 @@ export const applyBarHighlight = action(
 export const applyRectHighlight = action(
   { op: "applyRectHighlight", description: "Apply selected rect appearance." },
   function (args = {}) {
-    return applyRectangularHighlight(this, args, "applyRectHighlight", "rect");
+    return applyRectangularHighlight(
+      this,
+      args,
+      "applyRectHighlight",
+      "rect",
+      { offset: true }
+    );
   }
 );
 

package/src/actions/violinPlots/create.js

@@ -0,0 +1,198 @@
+import { action } from "../../core/action.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { findDataset } from "../../selectors/datasets.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "../charts/shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "split", "color", "density",
+  "area", "guides"
+]);
+const POSITION_OPTIONS = Object.freeze(["field", "fieldType", "scale"]);
+const DENSITY_OPTIONS = Object.freeze([
+  "bandwidth", "extent", "steps", "kernel", "normalization", "width"
+]);
+const WIDTH_OPTIONS = Object.freeze(["band", "resolve"]);
+const SPLIT_OPTIONS = Object.freeze(["field", "domain"]);
+const AREA_OPTIONS = Object.freeze([
+  "fill", "opacity", "stroke", "strokeWidth", "curve"
+]);
+const CATEGORICAL_TYPES = Object.freeze(["nominal", "ordinal"]);
+
+function inferFieldType(dataset, encoding, label) {
+  if (encoding.fieldType !== undefined) return encoding.fieldType;
+  if (typeof encoding.field !== "string" || encoding.field.length === 0) {
+    throw new TypeError(`${label} field must be a non-empty string.`);
+  }
+  const values = dataset.values
+    .map(row => row?.[encoding.field])
+    .filter(value => value !== undefined && value !== null && value !== "");
+  if (values.length === 0) {
+    throw new Error(`${label} field "${encoding.field}" has no values.`);
+  }
+  return values.every(Number.isFinite) ? "quantitative" : "nominal";
+}
+
+function normalizePosition(dataset, value, label) {
+  const encoding = normalizeFieldEncoding(value, label);
+  validateOptionObject(encoding, POSITION_OPTIONS, label);
+  return {
+    ...encoding,
+    fieldType: inferFieldType(dataset, encoding, label)
+  };
+}
+
+function normalizeDensity(value) {
+  if (value === undefined) return { options: {}, width: undefined };
+  validateOptionObject(value, DENSITY_OPTIONS, "createViolinPlot density");
+  if (value.width !== undefined) {
+    validateOptionObject(
+      value.width,
+      WIDTH_OPTIONS,
+      "createViolinPlot density.width"
+    );
+  }
+  const { width, ...options } = value;
+  return { options, width };
+}
+
+function normalizeSplit(value) {
+  if (value === undefined) return undefined;
+  validateOptionObject(value, SPLIT_OPTIONS, "createViolinPlot split");
+  if (typeof value.field !== "string" || value.field.length === 0) {
+    throw new TypeError("createViolinPlot split.field must be a non-empty string.");
+  }
+  return { ...value };
+}
+
+function axisGuideOptions(value, field) {
+  if (value === false) return false;
+  return {
+    ...(value ?? {}),
+    title: {
+      text: field,
+      ...(value?.title ?? {})
+    }
+  };
+}
+
+function guideOptions(guides, x, y, category, color) {
+  if (guides === false) return false;
+  const axes = guides.axes === false
+    ? false
+    : {
+        ...(guides.axes ?? {}),
+        x: axisGuideOptions(guides.axes?.x, x.field),
+        y: axisGuideOptions(guides.axes?.y, y.field)
+      };
+  const redundantLegend = color?.field === category.field &&
+    !Object.hasOwn(guides, "legend");
+  return {
+    ...guides,
+    axes,
+    ...(redundantLegend ? { legend: false } : {})
+  };
+}
+
+export const createViolinPlot = action(
+  {
+    op: "createViolinPlot",
+    description: "Create a categorical kernel-density violin plot."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createViolinPlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "violinPlot",
+      operation: "createViolinPlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createViolinPlot");
+    const dataset = findDataset(this, data);
+    const x = normalizePosition(dataset, args.x, "createViolinPlot x");
+    const y = normalizePosition(dataset, args.y, "createViolinPlot y");
+    const xCategorical = CATEGORICAL_TYPES.includes(x.fieldType);
+    const yCategorical = CATEGORICAL_TYPES.includes(y.fieldType);
+    if (xCategorical === yCategorical || (
+      x.fieldType !== "quantitative" && y.fieldType !== "quantitative"
+    )) {
+      throw new Error(
+        "createViolinPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const category = xCategorical ? x : y;
+    const value = xCategorical ? y : x;
+    if (value.fieldType !== "quantitative") {
+      throw new Error(
+        "createViolinPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const split = normalizeSplit(args.split);
+    if (split?.field === category.field) {
+      throw new Error("createViolinPlot split field must differ from its category field.");
+    }
+    const color = normalizeEncoding(args.color, "createViolinPlot color");
+    if (
+      color !== undefined &&
+      ![category.field, split?.field].includes(color.field)
+    ) {
+      throw new Error(
+        "createViolinPlot color must encode its category or split field."
+      );
+    }
+    const density = normalizeDensity(args.density);
+    const area = normalizeAppearance(
+      args.area,
+      AREA_OPTIONS,
+      "createViolinPlot area"
+    );
+    if (color !== undefined && Object.hasOwn(area, "fill")) {
+      throw new Error("createViolinPlot area.fill cannot be combined with color.");
+    }
+    const guides = guideOptions(
+      normalizeGuides(args.guides, "createViolinPlot"),
+      x,
+      y,
+      category,
+      color
+    );
+    const { strokeWidth, ...areaCreate } = area;
+    const hasFillStroke = strokeWidth !== undefined && area.stroke === undefined;
+    let next = this.createAreaMark({
+      id,
+      data,
+      ...areaCreate,
+      ...(area.stroke === undefined || strokeWidth === undefined
+        ? {}
+        : { strokeWidth })
+    });
+    if (hasFillStroke) {
+      next = next.configureAreaStrokeFromFill({ id, strokeWidth });
+    }
+    next = next.encodeDensity({
+      target: id,
+      source: data,
+      field: value.field,
+      groupBy: category.field,
+      densityChannel: xCategorical ? "x" : "y",
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      ...(value.scale === undefined ? {} : { valueScale: value.scale }),
+      ...density.options,
+      placement: {
+        type: "category",
+        ...(density.width === undefined ? {} : { width: density.width }),
+        ...(split === undefined ? {} : { split }),
+        ...(category.scale === undefined ? {} : { scale: category.scale })
+      }
+    });
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/violinPlots/index.js

@@ -0,0 +1,5 @@
+import { createViolinPlot } from "./create.js";
+
+export function registerViolinPlotActions(ProgramClass) {
+  ProgramClass.prototype.createViolinPlot = createViolinPlot;
+}