ggaction 0.0.17 → 0.0.19

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

@@ -1,19 +1,27 @@
+import { AXIS_RESOURCE_CHANNELS } from "../../../core/vocabulary.js";
+import { cartesianAxisOwners, axisTargetArgs, assertCartesianAxisSideAvailable } from "../../../selectors/axes.js";
+import { axisGraphicIds } from "../../../materialization/guides/resources.js";
+import { defaultAxisPosition, validateAxisPosition } from "./policy.js";
 import { isSourceOwnedText } from "../../../grammar/text.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
 import { validateUserId } from "../../../core/identifiers.js";
-import { validateKeys } from "../../../core/validation.js";
+import { validateKeys, validateNonNegativeFinite } from "../../../core/validation.js";
 import { hasCoordinate } from "../../../selectors/index.js";
 import { validateEnabledAxisComponents } from "./components.js";
+import { requireSemanticScale } from "../../../selectors/scales.js";
+import { requireCoordinate } from "../../../selectors/coordinates.js";
 
 const TOP_OPTIONS = Object.freeze([
+  "id",
   "scale",
   "coordinate",
   "position",
   "line",
   "ticksAndLabels",
-  "title"
+  "title",
+  "offset"
 ]);
 const LINE_OPTIONS = Object.freeze(["color", "lineWidth"]);
 const TICK_GROUP_OPTIONS = Object.freeze([
@@ -30,7 +38,8 @@ const TITLE_OPTIONS = Object.freeze([
   "color",
   "fontSize",
   "fontFamily",
-  "fontWeight"
+  "fontWeight",
+  "alongOffset", "align", "baseline"
 ]);
 
 function validateNested(value, supported, label) {
@@ -43,6 +52,7 @@ function validateNested(value, supported, label) {
 
 export function validateAxisArgs(args, operation) {
   validateKeys(args, TOP_OPTIONS, operation);
+  if (Object.hasOwn(args, "offset")) validateNonNegativeFinite(args.offset, "Axis frame offset");
 
   validateEnabledAxisComponents(args, operation);
   if (Object.hasOwn(args, "line") && args.line !== false) {
@@ -82,10 +92,52 @@ function makeCreateAxis(channel) {
     },
     withGuideLayoutValidation(function (args = {}) {
       validateAxisArgs(args, operation.create);
-      const shared = {};
+      const axisId = validateUserId(args.id ?? channel, "Axis id");
+      if (AXIS_RESOURCE_CHANNELS.includes(axisId) && axisId !== channel) {
+        throw new Error(`Axis id "${axisId}" is reserved for another axis channel.`);
+      }
+      const named = axisId !== channel;
+      let source = this;
+      if (named) {
+        if (cartesianAxisOwners(this).some(owner => owner.id === axisId) ||
+            axisGraphicIds(channel, axisId).some(id => this.graphicSpec.objects[id] !== undefined)) {
+          throw new Error(`Axis "${axisId}" requires a missing resource and missing concrete components.`);
+        }
+        const layers = this.semanticSpec.layers.filter(layer => !isSourceOwnedText(layer) &&
+          layer.encoding?.[channel]?.scale !== undefined &&
+          (args.coordinate === undefined || layer.coordinate === args.coordinate) &&
+          (args.scale === undefined || layer.encoding[channel].scale === args.scale));
+        const scales = [...new Set(layers.map(layer => layer.encoding[channel].scale))];
+        if (args.scale === undefined && scales.length !== 1) throw new Error("Named axes require an explicit scale when the channel binding is ambiguous.");
+        const scale = args.scale ?? scales[0];
+        const coordinates = [...new Set(layers.map(layer => layer.coordinate))];
+        if (args.coordinate === undefined && coordinates.length !== 1) throw new Error("Named axes require an explicit coordinate when the binding is ambiguous.");
+        const coordinate = args.coordinate ?? coordinates[0];
+        if (requireCoordinate(this, coordinate).type !== "cartesian") throw new Error("Named Cartesian axes require a Cartesian coordinate.");
+        const position = validateAxisPosition(channel, args.position ?? defaultAxisPosition(channel));
+        assertCartesianAxisSideAvailable(this, { id: axisId, channel, coordinate, position });
+        args = { ...args, scale, coordinate, position };
+        source = source.editSemantic({ property: `guide.axis.${axisId}.channel`, value: channel })
+          .editSemantic({ property: `guide.axis.${axisId}.position`, value: position })
+          .editSemantic({ property: `guide.axis.${axisId}.scale`, value: scale })
+          .editSemantic({ property: `guide.axis.${axisId}.coordinate`, value: coordinate });
+      } else if (cartesianAxisOwners(this).some(owner => owner.named)) {
+        const scale = args.scale ?? channel;
+        const coordinates = [...new Set(this.semanticSpec.layers.filter(layer =>
+          layer.encoding?.[channel]?.scale === scale).map(layer => layer.coordinate))];
+        const coordinate = args.coordinate ?? (coordinates.length === 1 ? coordinates[0] : undefined);
+        assertCartesianAxisSideAvailable(this, { id: axisId, channel, coordinate,
+          position: validateAxisPosition(channel, args.position ?? defaultAxisPosition(channel)) });
+        if (!cartesianAxisOwners(this).some(owner => owner.id === channel)) {
+          source = source.editSemantic({ property: `guide.axis.${axisId}.scale`, value: scale });
+          if (coordinate !== undefined) source = source.editSemantic({ property: `guide.axis.${axisId}.coordinate`, value: coordinate });
+        }
+      }
+      const shared = axisTargetArgs(axisId, channel);
       if (Object.hasOwn(args, "scale")) shared.scale = args.scale;
       if (Object.hasOwn(args, "position")) shared.position = args.position;
-      let next = this;
+      let next = Object.hasOwn(args, "offset")
+        ? source._withGuideConfig(axisId, "frame", { offset: args.offset }) : source;
 
       if (Object.hasOwn(args, "coordinate")) {
         const coordinate = validateUserId(args.coordinate, "Coordinate id");
@@ -100,16 +152,26 @@ function makeCreateAxis(channel) {
         if (!exists) {
           throw new Error(`Unknown coordinate "${coordinate}".`);
         }
-        if (!hasConsumer) {
-          throw new Error(
-            `${operation.create} found no ${channel} encoding for coordinate "${coordinate}" and scale "${scale}".`
-          );
+        const standalone = !hasConsumer;
+        if (standalone && (!Object.hasOwn(args, "scale") ||
+            next.semanticSpec.layers.some(layer => Object.values(layer.encoding ?? {}).some(encoding => encoding?.scale === scale)))) {
+          throw new Error(`${operation.create} found no ${channel} encoding for coordinate "${coordinate}" and scale "${scale}"; standalone binding requires an explicit unused scale.`);
+        }
+        if (standalone) {
+          const definition = requireSemanticScale(next, scale);
+          if (!Array.isArray(definition.domain) || definition.domain.length === 0 ||
+              requireCoordinate(next, coordinate).type !== "cartesian") {
+            throw new Error("Standalone axes require a Cartesian coordinate and explicit nonempty scale domain.");
+          }
         }
 
         next = next.editSemantic({
-          property: `guide.axis.${channel}.coordinate`,
+          property: `guide.axis.${axisId}.coordinate`,
           value: coordinate
         });
+        if (standalone) next = next._withGuideConfig(axisId, "binding", { standalone: true })
+          .editSemantic({ property: `guide.axis.${axisId}.scale`, value: scale })
+          .rematerializeScale({ id: scale, guides: false, marks: false });
       }
 
       for (const component of ["line", "ticksAndLabels", "title"]) {

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

@@ -2,8 +2,8 @@ import { axisGraphicIds } from "../../../materialization/guides/resources.js";
 
 export const AXIS_COMPONENTS = Object.freeze(["line", "ticks", "labels", "title"]);
 
-export function axisComponentId(channel, component) {
-  return axisGraphicIds(channel)[AXIS_COMPONENTS.indexOf(component)];
+export function axisComponentId(channel, component, axisId = channel) {
+  return axisGraphicIds(channel, axisId)[AXIS_COMPONENTS.indexOf(component)];
 }
 
 export function axisComponentDisabled(args, component) {
@@ -17,27 +17,27 @@ export function validateEnabledAxisComponents(args, operation) {
   }
 }
 
-export function hasAxisComponent(program, channel, component) {
-  return program.graphicSpec.objects[axisComponentId(channel, component)] !== undefined ||
-    program.guideConfigs.axis?.[channel]?.[component] !== undefined ||
+export function hasAxisComponent(program, channel, component, axisId = channel) {
+  return program.graphicSpec.objects[axisComponentId(channel, component, axisId)] !== undefined ||
+    program.guideConfigs.axis?.[axisId]?.[component] !== undefined ||
     (component === "title" &&
-      program.semanticSpec.guides.axis?.[channel]?.title !== undefined);
+      program.semanticSpec.guides.axis?.[axisId]?.title !== undefined);
 }
 
-export function assertRemovableAxisComponent(program, channel, component, operation) {
-  if (!hasAxisComponent(program, channel, component)) {
+export function assertRemovableAxisComponent(program, channel, component, operation, axisId = channel) {
+  if (!hasAxisComponent(program, channel, component, axisId)) {
     throw new Error(`${operation}.${component} requires an existing ${channel}-axis ${component}.`);
   }
 }
 
-export function removeAxisComponent(program, channel, component) {
-  const id = axisComponentId(channel, component);
+export function removeAxisComponent(program, channel, component, axisId = channel) {
+  const id = axisComponentId(channel, component, axisId);
   let next = program;
-  if (component === "title" && next.semanticSpec.guides.axis?.[channel]?.title !== undefined) {
-    next = next.editSemantic({ property: `guide.axis.${channel}.title`, remove: true });
+  if (component === "title" && next.semanticSpec.guides.axis?.[axisId]?.title !== undefined) {
+    next = next.editSemantic({ property: `guide.axis.${axisId}.title`, remove: true });
   }
   if (next.graphicSpec.objects[id] !== undefined) {
     next = next.editGraphics({ target: id, remove: true });
   }
-  return next._withoutMaterializationConfig(["guides", "axis", channel, component]);
+  return next._withoutMaterializationConfig(["guides", "axis", axisId, component]);
 }

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

@@ -1,7 +1,9 @@
+import { selectCartesianAxis, axisTargetArgs, assertCartesianAxisSideAvailable } from "../../../selectors/axes.js";
+import { validateAxisPosition } from "./policy.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
-import { validateKeys, validateOptionObject } from "../../../core/validation.js";
+import { validateKeys, validateOptionObject, validateNonNegativeFinite } from "../../../core/validation.js";
 
 import {
   AXIS_COMPONENTS,
@@ -12,21 +14,21 @@ import {
 } from "./components.js";
 
 const OPTIONS = Object.freeze([
-  "position", "line", "ticks", "labels", "ticksAndLabels", "title"
+  "target", "position", "line", "ticks", "labels", "ticksAndLabels", "title", "offset"
 ]);
 const LINE_OPTIONS = Object.freeze(["color", "lineWidth"]);
 const TICK_OPTIONS = Object.freeze([
-  "count", "values", "length", "color", "lineWidth"
+  "count", "values", "length", "color", "lineWidth", "alongOffset", "strokeDash", "strokeDashMap"
 ]);
 const LABEL_OPTIONS = Object.freeze([
   "count", "values", "offset", "format", "color", "fontSize",
   "fontFamily", "fontWeight", "rotation", "maxWidth", "wrap",
-  "lineHeight", "overlap"
+  "lineHeight", "overlap", "alongOffset", "labelMap", "flush", "colorMap", "align"
 ]);
 const GROUP_OPTIONS = Object.freeze(["count", "values", "ticks", "labels"]);
 const TITLE_OPTIONS = Object.freeze([
   "text", "at", "offset", "rotation", "color", "fontSize",
-  "fontFamily", "fontWeight"
+  "fontFamily", "fontWeight", "alongOffset", "align", "baseline"
 ]);
 
 function validateNested(args, key, options, operation, { allowFalse = false } = {}) {
@@ -40,6 +42,7 @@ function validateNested(args, key, options, operation, { allowFalse = false } =
 }
 
 function validateArgs(args, operation) {
+  if (Object.hasOwn(args, "offset")) validateNonNegativeFinite(args.offset, "Axis frame offset");
   validateOptionObject(args, OPTIONS, operation, {
     allowEmpty: false,
     emptyMessage: `${operation} requires at least one axis change.`,
@@ -59,12 +62,12 @@ function validateArgs(args, operation) {
     );
   }
   if (args.ticksAndLabels !== false && args.ticksAndLabels?.ticks !== undefined) {
-    validateNested(args.ticksAndLabels, "ticks", ["length", "color", "lineWidth"], `${operation}.ticksAndLabels`);
+    validateNested(args.ticksAndLabels, "ticks", ["length", "color", "lineWidth", "alongOffset", "strokeDash", "strokeDashMap"], `${operation}.ticksAndLabels`);
   }
   if (args.ticksAndLabels !== false && args.ticksAndLabels?.labels !== undefined) {
     validateNested(args.ticksAndLabels, "labels", [
       "offset", "format", "color", "fontSize", "fontFamily", "fontWeight",
-      "rotation", "maxWidth", "wrap", "lineHeight", "overlap"
+      "rotation", "maxWidth", "wrap", "lineHeight", "overlap", "alongOffset", "labelMap", "flush", "colorMap", "align"
     ], `${operation}.ticksAndLabels`);
   }
 }
@@ -82,27 +85,26 @@ function names(channel) {
   };
 }
 
-function buildPlan(program, channel, args, operation) {
-  const shared = Object.hasOwn(args, "position")
-    ? { position: args.position }
-    : {};
+function buildPlan(program, channel, args, operation, axisId = channel) {
+  const shared = { ...axisTargetArgs(axisId, channel),
+    ...(Object.hasOwn(args, "position") ? { position: args.position } : {}) };
   const plan = [];
   const addLeaf = (component, edit) => {
     const value = args[component];
     if (value === false) {
-      assertRemovable(program, channel, component, operation.operation);
+      assertRemovable(program, channel, component, operation.operation, axisId);
       plan.push({ kind: "remove", component });
     } else if (value !== undefined) {
       plan.push({ kind: "edit", operation: edit, args: { ...shared, ...value } });
-    } else if (args.position !== undefined && hasComponent(program, channel, component)) {
+    } else if ((args.position !== undefined || Object.hasOwn(args, "offset")) && hasComponent(program, channel, component, axisId)) {
       plan.push({ kind: "edit", operation: edit, args: shared });
     }
   };
 
   addLeaf("line", operation.line);
   if (args.ticksAndLabels === false) {
-    assertRemovable(program, channel, "ticks", operation.operation);
-    assertRemovable(program, channel, "labels", operation.operation);
+    assertRemovable(program, channel, "ticks", operation.operation, axisId);
+    assertRemovable(program, channel, "labels", operation.operation, axisId);
     plan.push(
       { kind: "remove", component: "ticks" },
       { kind: "remove", component: "labels" }
@@ -125,22 +127,22 @@ function buildPlan(program, channel, args, operation) {
   return plan;
 }
 
-function applyPlan(program, channel, plan, operation) {
+function applyPlan(program, channel, plan, operation, axisId = channel) {
   let next = program;
   for (const step of plan) {
     next = step.kind === "remove"
-      ? removeComponent(next, channel, step.component)
+      ? removeComponent(next, channel, step.component, axisId)
       : next[step.operation](step.args);
   }
 
   const hasRetainedGraphic = AXIS_COMPONENTS.some(
-    component => next.graphicSpec.objects[graphicId(channel, component)] !== undefined
+    component => next.graphicSpec.objects[graphicId(channel, component, axisId)] !== undefined
   );
   if (!hasRetainedGraphic && (
-    next.semanticSpec.guides.axis?.[channel] !== undefined ||
-    next.guideConfigs.axis?.[channel] !== undefined
+    next.semanticSpec.guides.axis?.[axisId] !== undefined ||
+    next.guideConfigs.axis?.[axisId] !== undefined
   )) {
-    next = next[operation.remove]();
+    next = next[operation.remove](axisId === channel ? undefined : axisTargetArgs(axisId, channel));
   }
   return next;
 }
@@ -154,12 +156,22 @@ function makeEditAxis(channel) {
     },
     withGuideLayoutValidation(function (args = {}) {
       validateArgs(args, operation.operation);
-      const plan = buildPlan(this, channel, args, operation);
+      const selected = selectCartesianAxis(this, channel, args, { whole: true });
+      const axisId = selected.id; args = selected.options;
+      let source = this;
+      if (selected.owner?.named && args.position !== undefined) {
+        const position = validateAxisPosition(channel, args.position);
+        assertCartesianAxisSideAvailable(this, { id: axisId, channel,
+          coordinate: selected.owner.coordinate, position });
+        source = source.editSemantic({ property: `guide.axis.${axisId}.position`, value: position });
+      }
+      if (Object.hasOwn(args, "offset")) source = source._withGuideConfig(axisId, "frame", { offset: args.offset });
+      const plan = buildPlan(source, channel, args, operation, axisId);
 
       // Run the complete proposal against an immutable speculative branch so a
       // later leaf failure cannot begin the returned action trace or state.
-      applyPlan(this, channel, plan, operation);
-      return applyPlan(this, channel, plan, operation);
+      applyPlan(source, channel, plan, operation, axisId);
+      return applyPlan(source, channel, plan, operation, axisId);
     })
   );
 }