ggaction 0.0.11 → 0.0.13

package/src/actions/guides/axes/lines.js

@@ -1,3 +1,5 @@
+import { isSourceOwnedText } from "../../../grammar/text.js";
+import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
@@ -40,7 +42,7 @@ function resolveLineRange(resolvedScale, bounds, channel) {
 
 function resolveGeometry(program, channel, scaleId, position) {
   const hasConsumer = program.semanticSpec.layers.some(
-    layer => layer.encoding?.[channel]?.scale === scaleId
+    layer => !isSourceOwnedText(layer) && layer.encoding?.[channel]?.scale === scaleId
   );
 
   if (!hasConsumer) {
@@ -84,7 +86,7 @@ function createEditAxisLine(channel) {
 
   return action(
     { op: operation, description: `Edit the concrete ${channel}-axis line.` },
-    function (args = {}) {
+    withGuideLayoutValidation(function (args = {}) {
       validateKeys(args, EDIT_OPTIONS, operation);
       const { graphic } = axisIds(channel);
       const line = this.graphicSpec.objects[graphic];
@@ -116,7 +118,7 @@ function createEditAxisLine(channel) {
       return next
         .editGraphics({ target: graphic, property: "stroke", value: color })
         .editGraphics({ target: graphic, property: "strokeWidth", value: lineWidth });
-    }
+    })
   );
 }
 
@@ -129,7 +131,7 @@ function createAxisLine(channel) {
 
   return action(
     { op: operation, description: `Create the concrete ${channel}-axis line.` },
-    function (args = {}) {
+    withGuideLayoutValidation(function (args = {}) {
       validateKeys(args, CREATE_OPTIONS, operation);
       const scale = validateUserId(args.scale ?? channel, "Scale id");
       const position = validateAxisPosition(
@@ -154,7 +156,7 @@ function createAxisLine(channel) {
           ...resolvePlotGraphicPlacement(this)
         })
         [editOperation]({ position, color, lineWidth });
-    }
+    })
   );
 }
 

package/src/actions/guides/axes/parallel/lifecycle.js

@@ -0,0 +1,117 @@
+import { action } from "../../../../core/action.js";
+import { validateNonEmptyString, validateOptionObject } from "../../../../core/validation.js";
+import { requireParallelAxisLayer, resolveParallelAxisTarget } from "./resolve.js";
+import {
+  defaultParallelAxis, hasParallelAxisParts, PARALLEL_AXIS_GRAPHICS,
+  PARALLEL_AXIS_PARTS, patchParallelAxis, resolveParallelAxisConfigs, validateParallelAxisOptions
+} from "./policy.js";
+
+function owner(program, args, operation, existing = false) {
+  const stored = program.semanticSpec.guides.axis?.parallel;
+  if (existing && stored === undefined) throw new Error(`${operation} requires existing Parallel axes.`);
+  const target = resolveParallelAxisTarget(program, args.target === undefined ? stored?.target : args.target);
+  if (stored !== undefined && stored.target !== target) throw new Error("Parallel axes belong to another target.");
+  const resolved = requireParallelAxisLayer(program, target);
+  if (args.coordinate !== undefined && args.coordinate !== resolved.coordinate.id) {
+    throw new Error(`Parallel layer "${target}" uses coordinate "${resolved.coordinate.id}".`);
+  }
+  if (Object.hasOwn(args, "field") && !resolved.dimensions.some(dimension => dimension.field === args.field)) {
+    throw new Error(`${operation} requires an encoded dimension field "${args.field}".`);
+  }
+  return { ...resolved, target, stored };
+}
+
+function withOwner(program, resolved, config) {
+  let next = program;
+  if (resolved.stored === undefined) {
+    next = next.editSemantic({ property: "guide.axis.parallel.target", value: resolved.target })
+      .editSemantic({ property: "guide.axis.parallel.coordinate", value: resolved.coordinate.id })
+      .editSemantic({ property: "guide.axis.parallel.scales", value: resolved.dimensions.map(dimension => dimension.scale) });
+  }
+  return next._withGuideConfig("parallel", "axes", {
+    target: resolved.target, scales: resolved.dimensions.map(dimension => dimension.scale), ...config
+  });
+}
+
+function withTitle(program, args, create) {
+  const remove = !create && args.title === false;
+  const text = args.title?.text;
+  if (!remove && text === undefined) return program;
+  const previous = program.semanticSpec.guides.axis?.parallel?.titles ?? [];
+  const titles = previous.filter(title => title.field !== args.field);
+  if (!remove) titles.push({ field: args.field, text });
+  if (titles.length === 0 && previous.length === 0) return program;
+  return program.editSemantic({ property: "guide.axis.parallel.titles",
+    ...(titles.length === 0 ? { remove: true } : { value: titles }) });
+}
+
+const createParallelAxes = action({
+  op: "createParallelAxes", description: "Create axes for every encoded Parallel dimension."
+}, function (args = {}) {
+  validateOptionObject(args, ["target", "coordinate"], "createParallelAxes");
+  const resolved = owner(this, args, "createParallelAxes");
+  if (resolved.stored !== undefined || this.guideConfigs.axis?.parallel !== undefined ||
+      Object.values(PARALLEL_AXIS_GRAPHICS).some(id => this.graphicSpec.objects[id] !== undefined)) {
+    throw new Error("createParallelAxes requires missing Parallel axes.");
+  }
+  return withOwner(this, resolved, {
+    mode: "all", dimensions: resolved.dimensions.map(dimension => defaultParallelAxis(dimension.field))
+  }).rematerializeParallelAxes({ target: resolved.target });
+});
+
+function makeAxisAction(create) {
+  const operation = create ? "createParallelAxis" : "editParallelAxis";
+  return action({ op: operation, description: `${create ? "Create" : "Edit"} selected components of a Parallel field axis.` }, function (args = {}) {
+    validateParallelAxisOptions(args, operation, create);
+    const resolved = owner(this, args, operation, !create);
+    const config = resolved.stored === undefined
+      ? { mode: "selected", dimensions: resolved.dimensions.map(dimension => ({ field: dimension.field })) }
+      : resolveParallelAxisConfigs(this, resolved.dimensions);
+    const previous = config.dimensions.find(dimension => dimension.field === args.field);
+    const updated = patchParallelAxis(previous, args, create, operation);
+    const next = withTitle(withOwner(this, resolved, {
+      ...config, dimensions: config.dimensions.map(dimension => dimension.field === args.field ? updated : dimension)
+    }), args, create);
+    return next.rematerializeParallelAxes({ target: resolved.target });
+  });
+}
+
+const createParallelAxis = makeAxisAction(true);
+const editParallelAxis = makeAxisAction(false);
+
+const removeParallelAxis = action({
+  op: "removeParallelAxis", description: "Remove every component of one Parallel field axis."
+}, function (args = {}) {
+  validateOptionObject(args, ["field", "target"], "removeParallelAxis");
+  validateNonEmptyString(args.field, "Parallel axis field");
+  const resolved = owner(this, args, "removeParallelAxis", true);
+  const config = resolveParallelAxisConfigs(this, resolved.dimensions).dimensions.find(dimension => dimension.field === args.field);
+  if (!hasParallelAxisParts(config)) throw new Error("removeParallelAxis requires an existing field axis.");
+  return this.editParallelAxis({ field: args.field, target: resolved.target,
+    ...Object.fromEntries(PARALLEL_AXIS_PARTS.filter(part => config[part] !== undefined).map(part => [part, false])) });
+});
+
+const removeParallelAxes = action({
+  op: "removeParallelAxes", description: "Remove all Parallel axis semantics, recipes and graphics."
+}, function (args = {}) {
+  validateOptionObject(args, ["target", "coordinate"], "removeParallelAxes");
+  const stored = this.semanticSpec.guides.axis?.parallel;
+  if (stored === undefined) throw new Error("removeParallelAxes requires existing Parallel axes.");
+  if (args.target !== undefined && args.target !== stored.target ||
+      args.coordinate !== undefined && args.coordinate !== stored.coordinate) {
+    throw new Error("removeParallelAxes selectors must match the stored owner.");
+  }
+  let next = this.editSemantic({ property: "guide.axis.parallel", remove: true });
+  for (const id of Object.values(PARALLEL_AXIS_GRAPHICS)) {
+    if (next.graphicSpec.objects[id] !== undefined) next = next.editGraphics({ target: id, remove: true });
+  }
+  return next._withoutMaterializationConfig(["guides", "axis", "parallel"]);
+});
+
+export function registerParallelAxisLifecycleActions(ProgramClass) {
+  ProgramClass.prototype.createParallelAxes = createParallelAxes;
+  ProgramClass.prototype.createParallelAxis = createParallelAxis;
+  ProgramClass.prototype.editParallelAxis = editParallelAxis;
+  ProgramClass.prototype.removeParallelAxis = removeParallelAxis;
+  ProgramClass.prototype.removeParallelAxes = removeParallelAxes;
+}

package/src/actions/guides/axes/parallel/policy.js

@@ -0,0 +1,137 @@
+import {
+  validateGeneratedItemLimit,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateOptionObject
+} from "../../../../core/validation.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../../../theme/defaults.js";
+import { validateAxisTextStyle } from "../labels.js";
+import { validateAxisFormat } from "../policy.js";
+
+export const PARALLEL_AXIS_PARTS = Object.freeze(["line", "ticks", "labels", "title"]);
+export const PARALLEL_AXIS_GRAPHICS = Object.freeze({
+  line: "parallelAxisLines", ticks: "parallelAxisTicks",
+  labels: "parallelAxisLabels", title: "parallelAxisTitles"
+});
+const STYLE_OPTIONS = Object.freeze({
+  line: ["color", "lineWidth"],
+  ticks: ["count", "values", "length", "color", "lineWidth"],
+  labels: ["count", "values", "offset", "format", "color", "fontSize", "fontFamily", "fontWeight"],
+  title: ["text", "offset", "color", "fontSize", "fontFamily", "fontWeight"]
+});
+
+export function defaultParallelAxis(field) {
+  return {
+    field,
+    line: { color: DEFAULT_COLORS.axis, lineWidth: 1.25 },
+    ticks: { mode: "auto", length: 8, color: DEFAULT_COLORS.mutedText, lineWidth: 1 },
+    labels: { mode: "auto", offset: 9, format: "auto", color: DEFAULT_COLORS.axis,
+      fontSize: 11, fontFamily: DEFAULT_FONT_FAMILY, fontWeight: "normal" },
+    title: { offset: 20, color: DEFAULT_COLORS.axisTitle,
+      fontSize: 13, fontFamily: DEFAULT_FONT_FAMILY, fontWeight: 600 }
+  };
+}
+
+function validateMode(options, operation) {
+  if (Object.hasOwn(options, "count") && Object.hasOwn(options, "values")) {
+    throw new Error(`${operation} cannot use count and values together.`);
+  }
+}
+
+export function validateParallelAxisOptions(args, operation, create) {
+  validateOptionObject(args, ["target", "field", "line", "ticksAndLabels", "title", "ticks", "labels"], operation);
+  validateNonEmptyString(args.field, "Parallel axis field");
+  if (create && args.line === false && args.title === false &&
+      (args.ticksAndLabels === false || args.ticks === false && args.labels === false)) {
+    throw new Error(`${operation} requires at least one enabled axis component.`);
+  }
+  if (!create && ![...PARALLEL_AXIS_PARTS, "ticksAndLabels"].some(key => Object.hasOwn(args, key))) {
+    throw new Error(`${operation} requires at least one axis change.`);
+  }
+  if (args.ticksAndLabels !== undefined && (args.ticks !== undefined || args.labels !== undefined)) {
+    throw new Error(`${operation} cannot combine ticksAndLabels with ticks or labels.`);
+  }
+  for (const part of PARALLEL_AXIS_PARTS) {
+    if (!Object.hasOwn(args, part) || args[part] === false) continue;
+    validateOptionObject(args[part], STYLE_OPTIONS[part], `${operation}.${part}`);
+    validateMode(args[part], `${operation}.${part}`);
+  }
+  if (Object.hasOwn(args, "ticksAndLabels") && args.ticksAndLabels !== false) {
+    const group = args.ticksAndLabels;
+    validateOptionObject(group, ["count", "values", "ticks", "labels"], `${operation}.ticksAndLabels`);
+    validateMode(group, `${operation}.ticksAndLabels`);
+    for (const part of ["ticks", "labels"]) {
+      if (Object.hasOwn(group, part)) {
+        validateOptionObject(group[part], STYLE_OPTIONS[part].filter(key => !["count", "values"].includes(key)),
+          `${operation}.ticksAndLabels.${part}`);
+      }
+    }
+  }
+}
+
+function patchComponent(previous, defaults, options, part, create, operation) {
+  if (create && previous !== undefined) throw new Error(`${operation} requires missing ${part}.`);
+  if (!create && previous === undefined) throw new Error(`${operation} requires existing ${part}.`);
+  if (options === false) return undefined;
+  const next = { ...(create ? defaults : previous), ...options };
+  delete next.text;
+  if (Object.hasOwn(options, "count")) { next.mode = "count"; delete next.values; }
+  if (Object.hasOwn(options, "values")) { next.mode = "values"; delete next.count; }
+  validateNonEmptyString(next.color, "Parallel axis color");
+  if (part === "line" || part === "ticks") validateNonNegativeFinite(next.lineWidth, "Parallel axis lineWidth");
+  if (part === "ticks") validateNonNegativeFinite(next.length, "Parallel tick length");
+  if (part === "labels" || part === "title") {
+    validateAxisTextStyle(next, "Parallel axis text");
+    validateNonNegativeFinite(next.offset, "Parallel text offset");
+  }
+  if (part === "labels") validateAxisFormat(next.format);
+  if (Object.hasOwn(options, "text")) validateNonEmptyString(options.text, "Parallel axis title");
+  if (next.mode === "count") {
+    if (!Number.isInteger(next.count) || next.count <= 0) throw new RangeError("Parallel tick count must be a positive integer.");
+    validateGeneratedItemLimit(next.count, "Parallel tick count");
+  }
+  if (next.mode === "values") {
+    if (!Array.isArray(next.values)) throw new TypeError("Parallel tick values must be an array.");
+    validateGeneratedItemLimit(next.values.length, "Parallel tick values");
+    next.values = [...next.values];
+  }
+  return next;
+}
+
+export function patchParallelAxis(previous, args, create, operation) {
+  const defaults = defaultParallelAxis(args.field);
+  const next = { ...previous, field: args.field };
+  const updates = {};
+  for (const part of ["line", "title"]) {
+    if (create ? args[part] !== false : Object.hasOwn(args, part)) updates[part] = args[part] ?? {};
+  }
+  if (args.ticksAndLabels === false) {
+    if (!create) { updates.ticks = false; updates.labels = false; }
+  } else if (args.ticksAndLabels !== undefined) {
+    const group = args.ticksAndLabels ?? {};
+    const mode = Object.fromEntries(["count", "values"].filter(key => Object.hasOwn(group, key)).map(key => [key, group[key]]));
+    updates.ticks = { ...mode, ...(group.ticks ?? {}) };
+    updates.labels = { ...mode, ...(group.labels ?? {}) };
+  } else {
+    for (const part of ["ticks", "labels"]) {
+      if (create ? args[part] !== false : Object.hasOwn(args, part)) updates[part] = args[part] ?? {};
+    }
+  }
+  for (const [part, options] of Object.entries(updates)) {
+    const value = patchComponent(previous?.[part], defaults[part], options, part, create, operation);
+    if (value === undefined) delete next[part]; else next[part] = value;
+  }
+  return next;
+}
+
+export function hasParallelAxisParts(config) {
+  return PARALLEL_AXIS_PARTS.some(part => config?.[part] !== undefined);
+}
+
+export function resolveParallelAxisConfigs(program, dimensions) {
+  const previous = program.guideConfigs.axis?.parallel?.axes;
+  const mode = previous?.mode ?? "all";
+  const configs = dimensions.map(dimension => previous?.dimensions?.find(config => config.field === dimension.field) ??
+    (mode === "all" ? defaultParallelAxis(dimension.field) : { field: dimension.field }));
+  return { mode, dimensions: configs };
+}

package/src/actions/guides/axes/parallel/resolve.js

@@ -9,6 +9,8 @@ import { niceTicks } from "../../../../grammar/ticks.js";
 import { resolveGraphicBounds } from "../../../../layout/canvas.js";
 import { findCoordinate } from "../../../../selectors/coordinates.js";
 import { findLayer } from "../../../../selectors/layers.js";
+import { formatAxisValue } from "../policy.js";
+import { resolveParallelAxisConfigs } from "./policy.js";
 
 export function requireParallelAxisLayer(program, target) {
   const layer = findLayer(program, target);
@@ -18,7 +20,8 @@ export function requireParallelAxisLayer(program, target) {
   if (
     layer?.mark?.type !== "line" ||
     coordinate?.type !== "parallel" ||
-    layer.encoding?.parallel?.dimensions?.length < 2
+    !Array.isArray(layer.encoding?.parallel?.dimensions) ||
+    layer.encoding.parallel.dimensions.length < 2
   ) {
     throw new Error(`Parallel axes require an encoded Parallel line "${target}".`);
   }
@@ -43,16 +46,16 @@ export function resolveParallelAxisTarget(program, requested) {
   return candidates[0].id;
 }
 
-function ticksForScale(scale) {
+function ticksForScale(scale, count = 5) {
   if (["ordinal", "band", "point"].includes(scale.type)) return scale.domain;
   if (isTransformedScaleType(scale.type)) {
-    return transformedTicks(scale.type, scale.domain, 5, {
+    return transformedTicks(scale.type, scale.domain, count, {
       ...(scale.base === undefined ? {} : { base: scale.base }),
       ...(scale.exponent === undefined ? {} : { exponent: scale.exponent }),
       ...(scale.constant === undefined ? {} : { constant: scale.constant })
     });
   }
-  return niceTicks(scale.domain, 5);
+  return niceTicks(scale.domain, count);
 }
 
 function formatValue(value) {
@@ -62,25 +65,43 @@ function formatValue(value) {
   return String(value);
 }
 
-export function resolveParallelAxisValues(program, dimensions) {
+function componentValues(program, dimension, config) {
+  const scale = program.resolvedScales[dimension.scale];
+  if (scale === undefined) throw new Error(`Parallel axis requires resolved scale "${dimension.scale}".`);
+  const discrete = ["ordinal", "band", "point"].includes(scale.type);
+  if (discrete && config.mode === "count") throw new Error("Ordinal Parallel axes use domain values, not count.");
+  const values = config.mode === "values" ? config.values : ticksForScale(scale, config.count ?? 5);
+  if (new Set(values).size !== values.length || values.some(value => discrete
+    ? !scale.domain.includes(value)
+    : !Number.isFinite(value) || value < Math.min(...scale.domain) || value > Math.max(...scale.domain))) {
+    throw new Error(`Parallel axis values must be distinct values inside the scale domain for "${dimension.field}".`);
+  }
+  return {
+    values,
+    y: discrete ? mapOrdinalPositionValues(values, scale) : mapContinuousScaleValues(values, scale),
+    text: config.format === undefined ? undefined : values.map(value =>
+      formatAxisValue(value, scale.type, config.format, formatValue))
+  };
+}
+
+export function resolveStyledParallelAxes(program, dimensions) {
   const bounds = resolveGraphicBounds(program);
   const step = bounds.width / (dimensions.length - 1);
-  const axes = dimensions.map((dimension, index) => {
-    const scale = program.resolvedScales[dimension.scale];
-    if (scale === undefined) {
-      throw new Error(`Parallel axis requires resolved scale "${dimension.scale}".`);
-    }
-    const values = ticksForScale(scale);
-    const y = ["ordinal", "band", "point"].includes(scale.type)
-      ? mapOrdinalPositionValues(values, scale)
-      : mapContinuousScaleValues(values, scale);
-    return {
-      ...dimension,
-      x: bounds.x + step * index,
-      values,
-      y,
-      labels: values.map(formatValue)
-    };
-  });
-  return { axes, bounds };
+  const configs = resolveParallelAxisConfigs(program, dimensions);
+  const titles = program.semanticSpec.guides.axis?.parallel?.titles ?? [];
+  return {
+    bounds,
+    configs,
+    axes: dimensions.map((dimension, index) => {
+      const config = configs.dimensions[index];
+      return {
+        ...dimension,
+        x: bounds.x + step * index,
+        config,
+        title: titles.find(title => title.field === dimension.field)?.text ?? dimension.title,
+        ticks: config.ticks === undefined ? undefined : componentValues(program, dimension, config.ticks),
+        labels: config.labels === undefined ? undefined : componentValues(program, dimension, config.labels)
+      };
+    })
+  };
 }