ggaction 0.0.4 → 0.0.6

package/src/actions/selection/actions.js

@@ -17,6 +17,7 @@ import {
   findSelectionPolicy,
   requireSelectionPolicy
 } from "../../materialization/selection/policies/index.js";
+import { legendGraphicIds } from "../../materialization/guides/resources.js";
 import {
   normalizeDimOthers,
   validateUnitInterval
@@ -27,6 +28,8 @@ const SELECTOR_KEYS = Object.freeze([
   "inclusive", "count", "groupBy", "ties"
 ]);
 const SELECT_OPTIONS = Object.freeze(["id", "target", ...SELECTOR_KEYS]);
+const EDIT_SELECTION_OPTIONS = Object.freeze(["selection", ...SELECTOR_KEYS]);
+const REMOVE_SELECTION_OPTIONS = Object.freeze(["selection"]);
 const HIGHLIGHT_OPTIONS = Object.freeze([
   "id", "target", "select", "selection", "color", "opacity", "fill",
   "stroke", "strokeWidth", "strokeDash", "shape", "size", "offset",
@@ -63,6 +66,51 @@ function hasLegendSelection(program, target, selection) {
     selector.field === legend.field;
 }
 
+function categoricalLegendKind(program, target) {
+  return ["series", "color"].find(
+    kind => program.guideConfigs.legend?.[kind]?.target === target
+  );
+}
+
+function resetCategoricalLegendSymbols(program, target) {
+  const kind = categoricalLegendKind(program, target);
+  if (kind === undefined) return program;
+  let next = program;
+  for (const id of legendGraphicIds(kind).filter(id => id.includes("Symbol"))) {
+    const graphic = next.graphicSpec.objects[id];
+    if (graphic === undefined) continue;
+    next = graphic.type === "collection"
+      ? next.editGraphics({ target: id, property: "items", value: [] })
+      : next.editGraphics({ target: id, property: "length", value: 0 });
+  }
+  return next.rematerializeLegendSymbols();
+}
+
+function targetHighlightEntries(program, target) {
+  return Object.entries(program.materializationConfigs.highlights ?? {})
+    .filter(([, config]) => config.target === target);
+}
+
+function rebuildTargetHighlights(program, target) {
+  const layer = resolveTarget(program, target, "highlight mark");
+  const highlights = targetHighlightEntries(program, target);
+  let baseline = program;
+  for (const [id] of highlights) {
+    baseline = baseline._withoutMaterializationConfig(["highlights", id]);
+  }
+  const graphic = baseline.graphicSpec.objects[target];
+  baseline = graphic.type === "collection"
+    ? baseline.editGraphics({ target, property: "items", value: [] })
+    : baseline.editGraphics({ target, property: "length", value: 0 });
+  baseline = baseline[requireSelectionPolicy(
+    layer.mark.type
+  ).rematerializeOp]({ id: target });
+  baseline = resetCategoricalLegendSymbols(baseline, target);
+  return highlights.length === 0
+    ? baseline
+    : baseline.rematerializeMarkHighlights({ target, highlights });
+}
+
 function selectedKeys(args, resolved) {
   if (args.keys === undefined) return resolved.keys;
   if (!Array.isArray(args.keys) || !args.keys.every(key =>
@@ -86,6 +134,79 @@ export const selectMarks = action(
   }
 );
 
+export const editMarkSelection = action(
+  {
+    op: "editMarkSelection",
+    description: "Replace one stored mark selector while preserving its identity and target."
+  },
+  function (args = {}) {
+    validateKeys(args, EDIT_SELECTION_OPTIONS, "editMarkSelection");
+    const current = resolveStoredSelection(this, args.selection);
+    const replacement = resolveMarkSelection(
+      this,
+      current.definition.target,
+      selectorFrom(args)
+    );
+    const next = this
+      ._withSelectionConfig(current.id, {
+        target: current.definition.target,
+        selector: replacement.selector
+      })
+      ._withContext({ currentSelection: current.id });
+    const hasDependentHighlight = Object.values(
+      next.materializationConfigs.highlights ?? {}
+    ).some(config => config.selection === current.id);
+    return hasDependentHighlight
+      ? rebuildTargetHighlights(next, current.definition.target)
+      : next;
+  }
+);
+
+export const removeMarkHighlight = action(
+  {
+    op: "removeMarkHighlight",
+    description: "Remove one stored highlight assignment and restore the clean mark baseline."
+  },
+  function (args = {}) {
+    validateKeys(args, REMOVE_SELECTION_OPTIONS, "removeMarkHighlight");
+    const current = resolveStoredSelection(this, args.selection);
+    const dependent = Object.entries(
+      this.materializationConfigs.highlights ?? {}
+    ).filter(([, config]) => config.selection === current.id);
+    if (dependent.length === 0) {
+      throw new Error(
+        `Selection "${current.id}" has no highlight assignment.`
+      );
+    }
+    let next = this;
+    for (const [id] of dependent) {
+      next = next._withoutMaterializationConfig(["highlights", id]);
+    }
+    return rebuildTargetHighlights(next, current.definition.target);
+  }
+);
+
+export const removeMarkSelection = action(
+  {
+    op: "removeMarkSelection",
+    description: "Remove one stored selection after removing its dependent highlight."
+  },
+  function (args = {}) {
+    validateKeys(args, REMOVE_SELECTION_OPTIONS, "removeMarkSelection");
+    const current = resolveStoredSelection(this, args.selection);
+    const hasDependentHighlight = Object.values(
+      this.materializationConfigs.highlights ?? {}
+    ).some(config => config.selection === current.id);
+    let next = hasDependentHighlight
+      ? this.removeMarkHighlight({ selection: current.id })
+      : this;
+    next = next._withoutMaterializationConfig(["selections", current.id]);
+    return this.context.currentSelection === current.id
+      ? next._withContext({ currentSelection: undefined })
+      : next;
+  }
+);
+
 export const applyPointHighlight = action(
   { op: "applyPointHighlight", description: "Apply selected point appearance and geometry." },
   function (args = {}) {
@@ -117,7 +238,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 +276,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 +292,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 }
+    );
   }
 );
 
@@ -368,8 +514,7 @@ export const highlightMarks = action(
     const existing = next.materializationConfigs.highlights?.[selection];
     if (existing !== undefined) {
       next = next._withoutMaterializationConfig(["highlights", selection]);
-      const policy = requireSelectionPolicy(layer.mark.type);
-      next = next[policy.rematerializeOp]({ id: resolved.definition.target });
+      next = rebuildTargetHighlights(next, resolved.definition.target);
     }
     const policy = requireSelectionPolicy(layer.mark.type);
     next = next[policy.applyHighlightOp]({ selection, style, keys });

package/src/actions/selection/index.js

@@ -5,14 +5,20 @@ import {
   applyPointHighlight,
   applyRuleHighlight,
   dimUnselectedMarkItems,
+  editMarkSelection,
   highlightMarks,
   placeSelectedMarkItemsLast,
   rematerializeMarkHighlights,
+  removeMarkHighlight,
+  removeMarkSelection,
   selectMarks
 } from "./actions.js";
 
 export function registerSelectionActions(ProgramClass) {
   ProgramClass.prototype.selectMarks = selectMarks;
+  ProgramClass.prototype.editMarkSelection = editMarkSelection;
+  ProgramClass.prototype.removeMarkHighlight = removeMarkHighlight;
+  ProgramClass.prototype.removeMarkSelection = removeMarkSelection;
   ProgramClass.prototype.highlightMarks = highlightMarks;
   ProgramClass.prototype.applyBarHighlight = applyBarHighlight;
   ProgramClass.prototype.applyRectHighlight = applyRectHighlight;

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;
+}

package/src/core/textMetrics.js

@@ -21,3 +21,50 @@ export function measureTextWidth(text, { fontSize } = {}) {
     0
   );
 }
+
+function horizontalExtents(width, align) {
+  if (align === "center") return [-width / 2, width / 2];
+  if (["right", "end"].includes(align)) return [-width, 0];
+  return [0, width];
+}
+
+function verticalExtents(fontSize, baseline) {
+  if (baseline === "middle") return [-fontSize / 2, fontSize / 2];
+  if (["top", "hanging"].includes(baseline)) return [0, fontSize];
+  if (["bottom", "ideographic"].includes(baseline)) return [-fontSize, 0];
+  return [-fontSize * 0.8, fontSize * 0.2];
+}
+
+export function resolveTextBounds({
+  x,
+  y,
+  text,
+  fontSize,
+  textAlign = "left",
+  textBaseline = "alphabetic",
+  rotation = 0
+} = {}) {
+  if (![x, y, rotation].every(Number.isFinite)) {
+    throw new TypeError("Text bounds require finite x, y, and rotation values.");
+  }
+  const width = measureTextWidth(text, { fontSize });
+  const [left, right] = horizontalExtents(width, textAlign);
+  const [top, bottom] = verticalExtents(fontSize, textBaseline);
+  const cosine = Math.cos(rotation);
+  const sine = Math.sin(rotation);
+  const corners = [
+    [left, top],
+    [right, top],
+    [right, bottom],
+    [left, bottom]
+  ].map(([localX, localY]) => ({
+    x: x + localX * cosine - localY * sine,
+    y: y + localX * sine + localY * cosine
+  }));
+  return Object.freeze({
+    left: Math.min(...corners.map(point => point.x)),
+    right: Math.max(...corners.map(point => point.x)),
+    top: Math.min(...corners.map(point => point.y)),
+    bottom: Math.max(...corners.map(point => point.y))
+  });
+}

package/src/core/vocabulary.js

@@ -31,9 +31,11 @@ export const ENCODING_CHANNELS = Object.freeze([
   "radius",
   "color",
   "strokeDash",
+  "strokeWidth",
   "size",
   "shape",
   "group",
+  "pathOrder",
   "opacity",
   "text"
 ]);
@@ -111,7 +113,9 @@ export const POSITION_CHANNEL_DEFINITIONS = Object.freeze({
 });
 
 export const SCALED_ENCODING_CHANNELS = Object.freeze(
-  ENCODING_CHANNELS.filter(channel => !["group", "text"].includes(channel))
+  ENCODING_CHANNELS.filter(channel =>
+    !["group", "pathOrder", "text"].includes(channel)
+  )
 );
 
 export const POSITION_ENCODING_CHANNELS = Object.freeze(
@@ -194,13 +198,21 @@ export const CATEGORICAL_LEGEND_CHANNELS = Object.freeze([
   "shape"
 ]);
 
+export const LEGEND_CHANNELS = Object.freeze([
+  ...CATEGORICAL_LEGEND_CHANNELS,
+  "strokeWidth",
+  "size",
+  "opacity"
+]);
+
 export const LEGEND_CONFIG_KINDS = Object.freeze([
   "series",
   "color",
   "size",
   "gradient",
   "interval",
-  "opacity"
+  "opacity",
+  "strokeWidth"
 ]);
 
 export function includesVocabulary(vocabulary, value) {

package/src/grammar/arcs.js

@@ -36,42 +36,79 @@ function colorValues(rows, encoding) {
     : readNominalField(rows, encoding.field);
 }
 
-function countSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
+export function readArcThetaWeights(rows, field, layerId = "arc") {
+  if (!Array.isArray(rows)) throw new TypeError("Arc theta weights require rows.");
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError("Arc theta weight must be a non-empty string.");
+  }
+  const weights = rows.map((row, index) => {
+    const value = row?.[field];
+    if (!Number.isFinite(value) || value < 0) {
+      throw new TypeError(
+        `Arc theta weight field "${field}" must contain non-negative finite numbers at row ${index}.`
+      );
+    }
+    return value;
+  });
+  if (weights.every(value => value === 0)) {
+    throw new Error(`Arc mark "${layerId}" theta weights must have a positive total.`);
+  }
+  return cloneAndFreeze(weights);
+}
+
+function proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
   const theta = layer.encoding.theta;
-  if (theta.aggregate !== "count") {
-    throw new Error(`Arc mark "${layer.id}" requires count or radial layout.`);
+  if (!["count", "sum"].includes(theta.aggregate)) {
+    throw new Error(`Arc mark "${layer.id}" requires count, sum, or radial layout.`);
   }
   const values = readNominalField(rows, theta.field);
   const colors = colorValues(rows, layer.encoding?.color);
+  const weights = theta.aggregate === "count"
+    ? rows.map(() => 1)
+    : readArcThetaWeights(rows, theta.weight, layer.id);
   const groups = new Map(thetaScale.domain.map(value => [value, []]));
   for (let index = 0; index < rows.length; index += 1) {
     const group = groups.get(values[index]);
     if (group === undefined) {
       throw new Error(`Arc theta value "${values[index]}" is outside the scale domain.`);
     }
-    group.push({ row: rows[index], color: colors[index], sourceIndex: index });
+    group.push({
+      row: rows[index],
+      color: colors[index],
+      sourceIndex: index,
+      weight: weights[index]
+    });
   }
-  const total = [...groups.values()].reduce((sum, group) => sum + group.length, 0);
-  if (total === 0) throw new Error(`Arc mark "${layer.id}" has no rows to count.`);
+  const total = [...groups.values()].reduce(
+    (sum, group) => sum + group.reduce((groupSum, item) => groupSum + item.weight, 0),
+    0
+  );
+  if (total === 0) throw new Error(`Arc mark "${layer.id}" has no positive theta weight.`);
   const start = thetaScale.range[0];
   const span = thetaScale.range[1] - thetaScale.range[0];
   const innerRadius = frame.availableRadius * innerRadiusRatio;
   let cursor = start;
   const sectors = [];
-  for (const value of thetaScale.domain) {
+  const positiveValues = thetaScale.domain.filter(value =>
+    groups.get(value).some(item => item.weight > 0)
+  );
+  for (const [positiveIndex, value] of positiveValues.entries()) {
     const group = groups.get(value);
-    if (group.length === 0) continue;
-    const endTheta = cursor + group.length / total * span;
+    const aggregateValue = group.reduce((sum, item) => sum + item.weight, 0);
+    const endTheta = positiveIndex === positiveValues.length - 1
+      ? thetaScale.range[1]
+      : cursor + aggregateValue / total * span;
     const distinctColors = [...new Set(group.map(item => item.color))];
     if (distinctColors.length > 1) {
       throw new Error(
-        `Count arc theta group "${value}" must resolve to one color value.`
+        `Aggregated arc theta group "${value}" must resolve to one color value.`
       );
     }
     sectors.push({
       key: value,
       theta: value,
       count: group.length,
+      aggregateValue,
       color: distinctColors[0],
       startTheta: cursor,
       endTheta,
@@ -147,8 +184,8 @@ export function deriveArcSectors(rows, layer, {
   ) {
     throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");
   }
-  const sectors = theta.aggregate === "count"
-    ? countSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
+  const sectors = ["count", "sum"].includes(theta.aggregate)
+    ? proportionalSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
     : radialSectors(rows, layer, thetaScale, radiusScale);
   return cloneAndFreeze({ sectors });
 }