ggaction 0.0.12 → 0.0.15

package/src/actions/scales/create.js

@@ -14,9 +14,11 @@ import {
   isColorScaleType,
   isContinuousColorScaleType,
   isDiscretizedColorScaleType,
+  normalizeSizeScaleDefinition,
   normalizeScaleDefinition
 } from "../../grammar/scales/index.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { findScaleConsumers } from "./consumers/index.js";
 
 const CREATE_SCALE_OPTIONS = Object.freeze([
   "id",
@@ -35,8 +37,8 @@ const CREATE_SCALE_OPTIONS = Object.freeze([
   "padding",
   "align",
   "palette",
-  "interpolate",
-  "unknown"
+  "interpolate", "midpoint",
+  "radialMapping", "unknown"
 ]);
 
 function validateOptions(args) {
@@ -97,28 +99,58 @@ export const createScale = action(
     const requestedRange = args.palette === undefined
       ? args.range
       : { palette: args.palette };
-    const definition = normalizeScaleDefinition({
-      type,
-      patch: {
-        ...args,
-        ...(requestedRange === undefined ? {} : { range: requestedRange })
-      },
-      validateDomain: (scaleType, value) =>
-        isDiscretizedColorScaleType(scaleType)
-          ? validateDiscretizedColorDomain(scaleType, value)
-          : hasOrdinalDomain(scaleType)
-            ? validateOrdinalDomain(value)
-            : validateScaleDomain(value),
-      validateRange: (scaleType, value) =>
-        isDiscretizedColorScaleType(scaleType)
-          ? validateDiscretizedColorRange(value)
-          : isContinuousColorScaleType(scaleType)
-            ? validateSequentialColorRange(value)
-            : scaleType === "ordinal"
-              ? validateOrdinalRange(value)
-              : validateScaleRange(value)
-    });
-    if (Object.hasOwn(args, "unknown")) definition.unknown = args.unknown;
+    const consumers = findScaleConsumers(this, id);
+    const offsetScale = consumers.length > 0 && consumers.every(
+      consumer => ["xOffset", "yOffset"].includes(consumer.channel)
+    );
+    const sizeScale = consumers.length > 0 && consumers.every(
+      consumer => consumer.channel === "size"
+    );
+    if (offsetScale && type !== "ordinal") {
+      throw new Error(`Scale type "${type}" is not valid for offset positions.`);
+    }
+    if (
+      offsetScale &&
+      Object.hasOwn(args, "range") &&
+      args.range !== "auto"
+    ) {
+      throw new Error(
+        "Offset scale range is derived from its parent categorical slot."
+      );
+    }
+    const definition = sizeScale
+      ? normalizeSizeScaleDefinition({
+          patch: {
+            ...args,
+            type,
+            ...(requestedRange === undefined ? {} : { range: requestedRange })
+          }
+        })
+      : normalizeScaleDefinition({
+          type,
+          patch: {
+            ...args,
+            ...(requestedRange === undefined ? {} : { range: requestedRange })
+          },
+          allowOrdinalBandParameters: offsetScale,
+          validateDomain: (scaleType, value) =>
+            isDiscretizedColorScaleType(scaleType)
+              ? validateDiscretizedColorDomain(scaleType, value)
+              : hasOrdinalDomain(scaleType)
+                ? validateOrdinalDomain(value)
+                : validateScaleDomain(value),
+          validateRange: (scaleType, value) =>
+            isDiscretizedColorScaleType(scaleType)
+              ? validateDiscretizedColorRange(value)
+              : isContinuousColorScaleType(scaleType)
+                ? validateSequentialColorRange(value)
+                : scaleType === "ordinal"
+                  ? validateOrdinalRange(value)
+                  : validateScaleRange(value)
+        });
+    if (Object.hasOwn(args, "unknown") && !sizeScale) {
+      definition.unknown = args.unknown;
+    }
     const existing = findSemanticScale(this, id);
 
     if (existing !== undefined) {
@@ -133,8 +165,8 @@ export const createScale = action(
 
     for (const property of [
       "nice", "zero", "clamp", "reverse", "base", "exponent", "constant",
-      "paddingInner", "paddingOuter", "padding", "align", "interpolate",
-      "unknown"
+      "paddingInner", "paddingOuter", "padding", "align", "interpolate", "midpoint",
+      "radialMapping", "unknown"
     ]) {
       if (definition[property] === undefined) continue;
       next = next.editSemantic({

package/src/actions/scales/definitions.js

@@ -1,9 +1,11 @@
+import { prepareScaleEdit } from "./editPolicy.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { validateKeys } from "../../core/validation.js";
 import {
   validateColorRange,
   validateContinuousColorInterpolation,
+  validateSequentialMidpoint,
   validateLinearScaleType,
   validateOpacityRange,
   validateOrdinalDomain,
@@ -11,7 +13,6 @@ import {
   validateScaleDomain,
   validateScaleRange,
   validateShapeRange,
-  validateSizeRange,
   validateStrokeDashRange,
   validateStrokeWidthRange,
   validateSequentialColorRange,
@@ -23,6 +24,7 @@ import {
   validateScalePropertyForType,
   validateScaleTypeForRole,
   isDiscretePositionScaleType,
+  normalizeSizeScaleDefinition,
   withScaleUnknown
 } from "../../grammar/scales/index.js";
 import {
@@ -30,6 +32,10 @@ import {
   validateThetaRange
 } from "../../grammar/polar.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { normalizeOffsetScalePolicy } from "../../grammar/bars/geometry.js";
+import { resolveRequestedOffsetPolicy } from
+  "../../materialization/scales/policies/offset.js";
+import { findScaleConsumers } from "./consumers/index.js";
 
 const BASE_OPTIONS = ["id", "type", "domain", "range"];
 const UNKNOWN_OPTIONS = [...BASE_OPTIONS, "unknown"];
@@ -49,13 +55,16 @@ const POSITION_OPTIONS = [
 const COLOR_OPTIONS = [...BASE_OPTIONS, "palette", "unknown"];
 const SEQUENTIAL_COLOR_OPTIONS = [
   ...COLOR_OPTIONS,
-  "interpolate",
+  "interpolate", "midpoint",
   ...CLAMP_REVERSE
 ];
 const OPACITY_OPTIONS = [...BASE_OPTIONS, ...BOOLEAN_OPTIONS, "unknown"];
 const STROKE_WIDTH_OPTIONS = [
   ...BASE_OPTIONS, ...BOOLEAN_OPTIONS, ...TRANSFORM_OPTIONS
 ];
+const SIZE_OPTIONS = [
+  ...UNKNOWN_OPTIONS, "clamp", "reverse", "base", "exponent"
+];
 
 function optionsObject(options) {
   if (!isPlainObject(options)) {
@@ -121,7 +130,7 @@ export function resolvePositionScaleDefinition(
     ...normalizeScaleDefinition({
       type,
       previous: existing,
-      patch: options,
+      patch: { ...options, ...(defaults.radialMapping === undefined ? {} : { radialMapping: defaults.radialMapping }) },
       defaults: {
         ...(existing === undefined && defaults.nice !== undefined
           ? { nice: defaults.nice }
@@ -149,21 +158,22 @@ export function resolvePositionScaleDefinition(
   return withScaleUnknown(scale, { ...existing, ...options }, channel);
 }
 
-export function resolveColorScaleDefinition(program, options) {
+export function resolveColorScaleDefinition(program, options, channel = "color") {
   optionsObject(options);
   validateKeys(options, COLOR_OPTIONS, "scale");
   validatePaletteRange(options);
-  const id = validateUserId(options.id ?? "color", "Scale id");
+  const id = validateUserId(options.id ?? channel, "Scale id");
   const existing = findSemanticScale(program, id);
+  const previous = existing?.type === "ordinal" ? existing : undefined;
   const range = options.palette === undefined
     ? options.range
     : { palette: options.palette };
   return withScaleUnknown({
     id,
-    type: validateOrdinalScaleType(options.type ?? existing?.type ?? "ordinal"),
-    domain: validateOrdinalDomain(options.domain ?? existing?.domain ?? "auto"),
-    range: validateColorRange(range ?? existing?.range ?? "auto")
-  }, { ...existing, ...options }, "color");
+    type: validateOrdinalScaleType(options.type ?? previous?.type ?? "ordinal"),
+    domain: validateOrdinalDomain(options.domain ?? previous?.domain ?? "auto"),
+    range: validateColorRange(range ?? previous?.range ?? "auto")
+  }, { ...previous, ...options }, channel);
 }
 
 function continuousDomain(value, fieldType) {
@@ -184,14 +194,16 @@ function continuousDomain(value, fieldType) {
 export function resolveSequentialColorScaleDefinition(
   program,
   fieldType,
-  options
+  options,
+  channel = "color"
 ) {
   optionsObject(options);
   validateKeys(options, SEQUENTIAL_COLOR_OPTIONS, "scale");
   validatePaletteRange(options);
-  const id = validateUserId(options.id ?? "color", "Scale id");
+  const id = validateUserId(options.id ?? channel, "Scale id");
   const existing = findSemanticScale(program, id);
-  const type = options.type ?? existing?.type ?? "sequential";
+  const previous = existing?.type === "sequential" ? existing : undefined;
+  const type = options.type ?? previous?.type ?? "sequential";
   if (type !== "sequential") {
     throw new Error(`Unsupported continuous color scale type "${type}".`);
   }
@@ -202,33 +214,52 @@ export function resolveSequentialColorScaleDefinition(
   const scale = {
     id,
     type,
-    domain: continuousDomain(options.domain ?? existing?.domain ?? "auto", fieldType),
+    domain: continuousDomain(options.domain ?? previous?.domain ?? "auto", fieldType),
     range: validateSequentialColorRange(
-      requestedRange ?? existing?.range ?? { palette: "viridis" }
+      requestedRange ?? previous?.range ?? { palette: "viridis" }
     ),
     interpolate: validateContinuousColorInterpolation(
-      options.interpolate ?? existing?.interpolate ?? "rgb"
+      options.interpolate ?? previous?.interpolate ?? "rgb"
     )
   };
+  const midpoint = validateSequentialMidpoint(
+    Object.hasOwn(options, "midpoint") ? options.midpoint : previous?.midpoint, type, scale.domain
+  );
+  if (midpoint !== undefined) {
+    if (fieldType !== "quantitative") {
+      throw new Error("Scale midpoint requires quantitative color consumers.");
+    }
+    scale.midpoint = midpoint;
+  }
   return withScaleUnknown(
-    assignOptions(scale, options, existing, CLAMP_REVERSE),
-    { ...existing, ...options },
-    "color"
+    assignOptions(scale, options, previous, CLAMP_REVERSE),
+    { ...previous, ...options },
+    channel
   );
 }
 
 export function resolveQuantitativeColorScaleDefinition(
   program,
   fieldType,
-  options
+  options,
+  channel = "color"
 ) {
   optionsObject(options);
-  const type = options.type ?? findSemanticScale(
-    program,
-    options.id ?? "color"
-  )?.type ?? "sequential";
+  const existing = findSemanticScale(program, options.id ?? channel);
+  const existingContinuous = existing !== undefined && (
+    existing.type === "sequential" ||
+    ["quantize", "quantile", "threshold"].includes(existing.type)
+  );
+  const type = options.type ?? (
+    existingContinuous ? existing.type : "sequential"
+  );
+  if (existingContinuous && existing.type !== type) {
+    validateKeys(options, type === "sequential" ? SEQUENTIAL_COLOR_OPTIONS : [...COLOR_OPTIONS, ...CLAMP_REVERSE], "scale");
+    if (fieldType !== "quantitative") throw new Error("Color scale type transition requires quantitative color.");
+    return { id: existing.id, ...prepareScaleEdit(program, existing, channel, [], options) };
+  }
   if (type === "sequential") {
-    return resolveSequentialColorScaleDefinition(program, fieldType, options);
+    return resolveSequentialColorScaleDefinition(program, fieldType, options, channel);
   }
   validateKeys(options, [...COLOR_OPTIONS, ...CLAMP_REVERSE], "scale");
   if (fieldType !== "quantitative") {
@@ -237,8 +268,7 @@ export function resolveQuantitativeColorScaleDefinition(
   validateScaleTypeForRole(type, SCALE_ROLES.discretizedColor);
   validatePaletteRange(options);
   validateBooleanOptions(options, CLAMP_REVERSE, type);
-  const id = validateUserId(options.id ?? "color", "Scale id");
-  const existing = findSemanticScale(program, id);
+  const id = validateUserId(options.id ?? channel, "Scale id");
   const previous = existing?.type === type ? existing : undefined;
   const requestedRange = options.palette === undefined
     ? options.range
@@ -257,7 +287,7 @@ export function resolveQuantitativeColorScaleDefinition(
   return withScaleUnknown(
     assignOptions(scale, options, previous, CLAMP_REVERSE),
     { ...existing, ...options },
-    "color"
+    channel
   );
 }
 
@@ -282,21 +312,23 @@ export function resolveStrokeDashScaleDefinition(program, options) {
 
 export function resolveAppearanceScaleDefinition(program, channel, options) {
   optionsObject(options);
+  if (channel === "size") {
+    validateKeys(options, SIZE_OPTIONS, "scale");
+    const id = validateUserId(options.id ?? channel, "Scale id");
+    const existing = findSemanticScale(program, id);
+    return {
+      id,
+      ...normalizeSizeScaleDefinition({ previous: existing, patch: options })
+    };
+  }
   validateKeys(options, UNKNOWN_OPTIONS, "scale");
   const id = validateUserId(options.id ?? channel, "Scale id");
   const existing = findSemanticScale(program, id);
-  const shape = channel === "shape";
   return withScaleUnknown({
     id,
-    type: shape
-      ? validateOrdinalScaleType(options.type ?? existing?.type ?? "ordinal")
-      : validateLinearScaleType(options.type ?? existing?.type ?? "linear"),
-    domain: shape
-      ? validateOrdinalDomain(options.domain ?? existing?.domain ?? "auto")
-      : validateScaleDomain(options.domain ?? existing?.domain ?? "auto"),
-    range: shape
-      ? validateShapeRange(options.range ?? existing?.range ?? "auto")
-      : validateSizeRange(options.range ?? existing?.range ?? "auto")
+    type: validateOrdinalScaleType(options.type ?? existing?.type ?? "ordinal"),
+    domain: validateOrdinalDomain(options.domain ?? existing?.domain ?? "auto"),
+    range: validateShapeRange(options.range ?? existing?.range ?? "auto")
   }, { ...existing, ...options }, channel);
 }
 
@@ -349,7 +381,45 @@ export function resolveStrokeWidthScaleDefinition(program, options) {
 }
 
 export function resolveOffsetScaleDefinition(program, options, channel = "xOffset") {
-  return resolveOrdinalScaleDefinition(
-    program, options, channel, validateScaleRange
+  optionsObject(options);
+  validateKeys(options, [
+    "id", "type", "domain", "range", "reverse",
+    "padding", "paddingInner", "paddingOuter", "align"
+  ], "scale");
+  const id = validateUserId(options.id ?? channel, "Scale id");
+  const existing = findSemanticScale(program, id);
+  const type = options.type ?? existing?.type ?? "ordinal";
+  if (type !== "ordinal") {
+    throw new Error(`Scale type "${type}" is not valid for ${channel}.`);
+  }
+  if (Object.hasOwn(options, "range") && options.range !== "auto") {
+    throw new Error(
+      `${channel} scale range is derived from its parent categorical slot.`
+    );
+  }
+  const consumers = findScaleConsumers(program, id).filter(
+    consumer => consumer.channel === channel
   );
+  const currentPolicy = resolveRequestedOffsetPolicy({
+    scale: existing,
+    consumers,
+    markConfigs: program.markConfigs,
+    id,
+    channel
+  });
+  const policy = normalizeOffsetScalePolicy(options, currentPolicy, channel);
+  const patch = Object.fromEntries(Object.entries(options).filter(
+    ([property]) => !["id", "padding"].includes(property)
+  ));
+  return {
+    id,
+    ...normalizeScaleDefinition({
+      type,
+      previous: existing,
+      patch: { ...patch, ...policy },
+      allowOrdinalBandParameters: true,
+      validateDomain: (_scaleType, value) => validateOrdinalDomain(value),
+      validateRange: (_scaleType, value) => validateScaleRange(value)
+    })
+  };
 }

package/src/actions/scales/edit.js

@@ -1,10 +1,18 @@
+import { withGuideLayoutValidation } from "../../materialization/guides/layout.js";
+import {
+  applyColorLegendTransition,
+  planColorLegendTransitions
+} from "../guides/legends/transition.js";
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { validateOptionObject } from "../../core/validation.js";
-import { getMarkMaterializationStep } from "../../materialization/marks/index.js";
+import { getMarkMaterializationStep, getSourceDependentMarkSteps } from "../../materialization/marks/index.js";
 import {
-  applyMaterializationPlan
+  applyMaterializationPlan,
+  planCoordinateRematerialization
 } from "../../materialization/dependencies.js";
+import { findDataAspectCoordinatesForScale } from
+  "../../materialization/coordinateBounds.js";
 import {
   findSemanticScale,
   requireSemanticScale
@@ -14,11 +22,13 @@ import {
   prepareScaleEdit,
   resolveScaleConsumerChannel
 } from "./editPolicy.js";
+import { hasExactLegendSamplingForScale } from
+  "../guides/legends/sampling.js";
 
 const OPTIONS = Object.freeze([
   "id", "type", "domain", "range", "nice", "zero", "clamp", "reverse",
   "base", "exponent", "constant", "paddingInner", "paddingOuter", "padding",
-  "align", "interpolate", "unknown", "palette"
+  "align", "interpolate", "midpoint", "unknown", "palette", "radialMapping"
 ]);
 const EDITABLE = Object.freeze(
   OPTIONS.filter(option => !["id", "palette"].includes(option))
@@ -63,7 +73,76 @@ function planMarkRematerialization(program, consumers) {
     seen.add(consumer.layer.id);
     plan.push(step);
   }
-  return plan;
+  return [
+    ...plan,
+    ...consumers.flatMap(consumer => getSourceDependentMarkSteps(program, consumer.layer.id))
+  ];
+}
+
+function applyScaleEdit(program, {
+  id,
+  scale,
+  channel,
+  consumers,
+  definition,
+  legendTransitions
+}) {
+  let next = program;
+  for (const transition of legendTransitions) {
+    next = next.removeLegend({
+      target: transition.args.target,
+      channels: [transition.channel]
+    });
+  }
+  for (const property of EDITABLE) {
+    if (
+      Object.hasOwn(scale, property) &&
+      !Object.hasOwn(definition, property)
+    ) {
+      next = next.editSemantic({
+        property: `scale[${id}].${property}`,
+        remove: true
+      });
+    }
+  }
+  for (const property of EDITABLE) {
+    if (
+      !Object.hasOwn(definition, property) ||
+      sameValue(scale[property], definition[property])
+    ) continue;
+    next = next.editSemantic({
+      property: `scale[${id}].${property}`,
+      value: definition[property]
+    });
+  }
+  if (consumers.length === 0) return next;
+
+  const aspectCoordinates = findDataAspectCoordinatesForScale(next, id);
+  if (aspectCoordinates.length > 0) {
+    for (const coordinate of aspectCoordinates) {
+      next = applyMaterializationPlan(
+        next,
+        planCoordinateRematerialization(next, coordinate.id)
+      );
+    }
+  } else {
+    next = next.rematerializeScale({ id });
+    next = applyMaterializationPlan(
+      next,
+      planMarkRematerialization(next, consumers)
+    );
+  }
+  if (["xOffset", "yOffset"].includes(channel)) {
+    for (const consumer of consumers) {
+      next = next._withoutMaterializationConfig([
+        "marks", consumer.layer.id, channel
+      ]);
+    }
+  }
+  for (const transition of legendTransitions) {
+    next = applyColorLegendTransition(next, transition);
+  }
+  return next;
 }
 
 export const editScale = action(
@@ -71,7 +150,7 @@ export const editScale = action(
     op: "editScale",
     description: "Edit an existing scale and rematerialize its consumers."
   },
-  function (args = {}) {
+  withGuideLayoutValidation(function (args = {}) {
     validateOptionObject(args, OPTIONS, "editScale");
     if (!REQUESTED_CHANGES.some(property => Object.hasOwn(args, property))) {
       throw new Error("editScale requires at least one editable property.");
@@ -82,34 +161,22 @@ export const editScale = action(
     const channel = resolveScaleConsumerChannel(consumers, id);
     const definition = prepareScaleEdit(this, scale, channel, consumers, args);
 
-    let next = this;
-    for (const property of EDITABLE) {
-      if (
-        Object.hasOwn(scale, property) &&
-        !Object.hasOwn(definition, property)
-      ) {
-        next = next.editSemantic({
-          property: `scale[${id}].${property}`,
-          remove: true
-        });
-      }
+    const legendTransitions = planColorLegendTransitions(this, scale, definition.type);
+    const proposal = {
+      id,
+      scale,
+      channel,
+      consumers,
+      definition,
+      legendTransitions
+    };
+    // Preflight every dependent mark and guide on a discarded immutable branch.
+    if (
+      scale.type !== definition.type ||
+      hasExactLegendSamplingForScale(this, id)
+    ) {
+      applyScaleEdit(this, proposal);
     }
-    for (const property of EDITABLE) {
-      if (
-        !Object.hasOwn(definition, property) ||
-        sameValue(scale[property], definition[property])
-      ) continue;
-      next = next.editSemantic({
-        property: `scale[${id}].${property}`,
-        value: definition[property]
-      });
-    }
-    if (consumers.length === 0) return next;
-
-    next = next.rematerializeScale({ id });
-    return applyMaterializationPlan(
-      next,
-      planMarkRematerialization(next, consumers)
-    );
-  }
+    return applyScaleEdit(this, proposal);
+  })
 );