ggaction 0.0.12 → 0.0.15

package/src/actions/guides/legends/remove.js

@@ -1,102 +1,62 @@
 import { action } from "../../../core/action.js";
 import { validateKeys } from "../../../core/validation.js";
-import { legendGraphicIds, legendResourcePolicy } from
-  "../../../materialization/guides/resources.js";
-import { LEGEND_CHANNELS } from "../../../core/vocabulary.js";
-import { resolveLegendTarget } from "./target.js";
+import {
+  removeLegendKinds,
+  resolveCategoricalLegendRevision,
+  createCategoricalLegendFromConfig
+} from "./lifecycle.js";
+import { resolveLegendTarget, validateLegendChannels } from "./target.js";
+import { planLegendBlockTransitions } from "./transition.js";
+
+export { removeLegendKinds } from "./lifecycle.js";
 
 const OPTIONS = Object.freeze(["target", "channels"]);
 
 function legendKindChannels(kind, config) {
-  if (["series", "color"].includes(kind)) return config.channels;
+  if (["series", "color", "stroke"].includes(kind)) return config.channels;
   return {
     size: ["size"],
     gradient: ["color"],
     interval: ["color"],
+    strokeGradient: ["stroke"],
+    strokeInterval: ["stroke"],
     opacity: ["opacity"],
     strokeWidth: ["strokeWidth"]
   }[kind];
 }
 
-function validateRequestedChannels(channels) {
-  if (!Array.isArray(channels)) {
-    throw new TypeError("removeLegend channels must be an array.");
-  }
-  if (channels.length === 0) {
-    throw new Error("removeLegend channels must select at least one channel.");
-  }
-  const seen = new Set();
-  for (const channel of channels) {
-    if (!LEGEND_CHANNELS.includes(channel)) {
-      throw new Error(`Unsupported legend channel "${channel}".`);
-    }
-    if (seen.has(channel)) {
-      throw new Error(`removeLegend channels contains duplicate "${channel}".`);
-    }
-    seen.add(channel);
-  }
-}
-
-function resolveRequestedKinds(program, target, channels) {
-  validateRequestedChannels(channels);
+function resolveRequestedRemoval(program, target, channels) {
+  validateLegendChannels(channels, "removeLegend");
   const requested = new Set(channels);
   const matched = new Set();
   const kinds = [];
+  let partial;
   for (const [kind, config] of Object.entries(program.guideConfigs.legend ?? {})) {
     if (config?.target !== target) continue;
     const owned = legendKindChannels(kind, config);
     const overlap = owned.filter(channel => requested.has(channel));
-    if (overlap.length > 0 && overlap.length !== owned.length) {
-      throw new Error(
-        `Legend channels ${owned.map(channel => `"${channel}"`).join(", ")} ` +
-        "belong to one combined block and must be removed together."
-      );
-    }
-    if (overlap.length === owned.length) {
-      kinds.push(kind);
-      for (const channel of owned) matched.add(channel);
+    if (overlap.length === 0) continue;
+    kinds.push(kind);
+    for (const channel of overlap) matched.add(channel);
+    if (overlap.length !== owned.length) {
+      partial = { kind, config, channels: owned.filter(channel => !requested.has(channel)) };
     }
   }
   const missing = channels.filter(channel => !matched.has(channel));
   if (missing.length > 0) {
-    throw new Error(
-      `Legend target "${target}" has no complete block for channel "${missing[0]}".`
-    );
-  }
-  return kinds;
-}
-
-export function removeLegendKinds(program, kinds) {
-  const removed = new Set(kinds);
-  const retainedSemanticKinds = new Set(
-    Object.entries(program.guideConfigs.legend ?? {})
-      .filter(([kind]) => !removed.has(kind))
-      .map(([kind]) => legendResourcePolicy(kind).semanticKind)
-  );
-  const semanticKinds = new Set(
-    kinds.map(kind => legendResourcePolicy(kind).semanticKind)
-  );
-  let next = program;
-  for (const kind of semanticKinds) {
-    if (
-      !retainedSemanticKinds.has(kind) &&
-      next.semanticSpec.guides.legend?.[kind] !== undefined
-    ) {
-      next = next.editSemantic({
-        property: `guide.legend.${kind}`,
-        remove: true
-      });
-    }
+    throw new Error(`Legend target "${target}" has no complete block for channel "${missing[0]}".`);
   }
-  for (const id of new Set(kinds.flatMap(legendGraphicIds))) {
-    if (next.graphicSpec.objects[id] !== undefined) {
-      next = next.editGraphics({ target: id, remove: true });
-    }
-  }
-  for (const kind of kinds) {
-    next = next._withoutMaterializationConfig(["guides", "legend", kind]);
-  }
-  return next;
+  // Remove departing sibling configs from the immutable layout preflight view.
+  const view = kinds.reduce((next, kind) =>
+    next._withoutMaterializationConfig(["guides", "legend", kind]), program);
+  const resolved = partial === undefined ? undefined
+    : resolveCategoricalLegendRevision(view, partial.kind, partial.config, partial.channels);
+  const revision = resolved === undefined ? undefined : planLegendBlockTransitions(
+    program,
+    target,
+    [{ ...resolved, kind: resolved.config.kind }]
+  )[0];
+  return { kinds, revision };
 }
 
 export function removeOwnedColorLegends(program, target) {
@@ -108,17 +68,20 @@ export function removeOwnedColorLegends(program, target) {
 }
 
 export const removeLegend = action(
-  { op: "removeLegend", description: "Remove every legend block owned by one mark." },
+  { op: "removeLegend", description: "Remove selected legend content or every block owned by one mark." },
   function (args = {}) {
     validateKeys(args, OPTIONS, "removeLegend");
     const target = resolveLegendTarget(this, args.target, "removeLegend");
     const targetKinds = Object.entries(this.guideConfigs.legend ?? {})
       .filter(([, config]) => config?.target === target)
       .map(([kind]) => kind);
-    const kinds = args.channels === undefined
-      ? targetKinds
-      : resolveRequestedKinds(this, target, args.channels);
+    const { kinds, revision } = args.channels === undefined
+      ? { kinds: targetKinds }
+      : resolveRequestedRemoval(this, target, args.channels);
     let next = removeLegendKinds(this, kinds);
+    if (revision !== undefined) {
+      next = createCategoricalLegendFromConfig(next, revision.config, revision.order);
+    }
     const retainedKinds = Object.keys(next.guideConfigs.legend ?? {});
     if (args.channels === undefined) {
       return retainedKinds.length === 0
@@ -126,9 +89,11 @@ export const removeLegend = action(
         : next.rematerializeLegend();
     }
     const remainingTargetKinds = targetKinds.filter(kind => !kinds.includes(kind));
-    const removedCategorical = kinds.some(kind => ["series", "color"].includes(kind));
+    const removedCategorical = kinds.some(kind =>
+      ["series", "color", "stroke"].includes(kind)
+    );
     if (
-      removedCategorical &&
+      removedCategorical && revision === undefined &&
       remainingTargetKinds.includes("size") &&
       next.guideConfigs.legend.size.inheritAppearance === true
     ) {

package/src/actions/guides/legends/sampling.js

@@ -0,0 +1,140 @@
+import { sampleNumericRange } from "../../../grammar/numeric.js";
+import {
+  validateGeneratedItemLimit
+} from "../../../core/validation.js";
+
+const DEFAULT_COUNT = 5;
+const MAX_EXACT_VALUES = 100;
+
+function validateCount(value, label) {
+  if (!Number.isInteger(value) || value < 2) {
+    throw new RangeError(`${label} count must be an integer of at least 2.`);
+  }
+  validateGeneratedItemLimit(value, `${label} count`);
+  return value;
+}
+
+function normalizeExactValues(value, label) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${label} values must be an array or "auto".`);
+  }
+  if (value.length === 0 || value.length > MAX_EXACT_VALUES) {
+    throw new RangeError(
+      `${label} values must contain between 1 and ${MAX_EXACT_VALUES} values.`
+    );
+  }
+  const values = [...value];
+  for (let index = 0; index < values.length; index += 1) {
+    if (!Number.isFinite(values[index])) {
+      throw new TypeError(`${label} values must contain only finite numbers.`);
+    }
+    if (index > 0 && !(values[index] > values[index - 1])) {
+      throw new RangeError(
+        `${label} values must be unique and strictly increasing.`
+      );
+    }
+  }
+  return Object.freeze(values);
+}
+
+export function readLegendSampling(config, defaultCount = DEFAULT_COUNT) {
+  if (config?.sampling?.mode === "values") {
+    return {
+      mode: "values",
+      values: config.sampling.values,
+      count: config.sampling.count ?? config.count ?? defaultCount
+    };
+  }
+  return {
+    mode: "auto",
+    count: config?.sampling?.count ?? config?.count ?? defaultCount
+  };
+}
+
+export function normalizeLegendSampling(
+  patch,
+  { previous, operation = "create", label = "Legend" } = {}
+) {
+  const prior = readLegendSampling(previous);
+  const hasValues = Object.hasOwn(patch, "values");
+  const hasCount = Object.hasOwn(patch, "count");
+  const requestedValues = patch.values;
+
+  if (hasValues && requestedValues !== "auto" && hasCount) {
+    throw new Error(`${label} cannot specify both count and exact values.`);
+  }
+  if (requestedValues === "auto" && operation === "create") {
+    throw new Error(`${label} creation uses omission for automatic values.`);
+  }
+  if (!hasValues && !hasCount) {
+    return Object.freeze({
+      ...prior,
+      ...(prior.values === undefined
+        ? {}
+        : { values: Object.freeze([...prior.values]) })
+    });
+  }
+  if (!hasValues) {
+    if (prior.mode === "values") {
+      throw new Error(
+        `${label} count cannot replace exact values; set values to "auto" first.`
+      );
+    }
+    return Object.freeze({ mode: "auto", count: validateCount(patch.count, label) });
+  }
+  if (requestedValues === "auto") {
+    return Object.freeze({
+      mode: "auto",
+      count: hasCount ? validateCount(patch.count, label) : validateCount(prior.count, label)
+    });
+  }
+  return Object.freeze({
+    mode: "values",
+    values: normalizeExactValues(requestedValues, label),
+    count: validateCount(prior.count, label)
+  });
+}
+
+export function validateSamplingAgainstScale(sampling, scale, label = "Legend") {
+  if (sampling.mode !== "values") return sampling;
+  const domain = scale?.domain;
+  if (!Array.isArray(domain) || domain.length < 2 || !domain.every(Number.isFinite)) {
+    throw new Error(`${label} exact values require a finite quantitative scale domain.`);
+  }
+  const lower = Math.min(...domain);
+  const upper = Math.max(...domain);
+  for (const value of sampling.values) {
+    if (scale.type === "log" && value <= 0) {
+      throw new RangeError(`${label} exact values must be positive for a log scale.`);
+    }
+    if (value < lower || value > upper) {
+      throw new RangeError(
+        `${label} exact value ${value} is outside the scale domain [${lower}, ${upper}].`
+      );
+    }
+  }
+  return sampling;
+}
+
+export function resolveLegendSampleValues(config, scale, label = "Legend") {
+  const sampling = validateSamplingAgainstScale(
+    readLegendSampling(config),
+    scale,
+    label
+  );
+  return sampling.mode === "values"
+    ? [...sampling.values]
+    : sampleNumericRange(
+        scale.domain[0],
+        scale.domain[1],
+        sampling.count,
+        `${label} domain`
+      );
+}
+
+export function hasExactLegendSamplingForScale(program, scaleId) {
+  return ["size", "opacity", "strokeWidth"].some(kind => {
+    const config = program.guideConfigs.legend?.[kind];
+    return config?.scale === scaleId && readLegendSampling(config).mode === "values";
+  });
+}