ggaction 0.0.13 → 0.0.16

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

@@ -22,15 +22,18 @@ import { legendResourcePolicy } from
 const FAMILY_ORDER = Object.freeze({
   series: 0,
   color: 0,
+  stroke: 0,
   gradient: 0,
   interval: 0,
+  strokeGradient: 0,
+  strokeInterval: 0,
   size: 1,
   opacity: 2,
   strokeWidth: 3
 });
 
 function categoricalFor(program, target) {
-  return ["series", "color"]
+  return ["series", "color", "stroke"]
     .map(kind => program.guideConfigs.legend?.[kind])
     .find(config => config?.target === target);
 }
@@ -63,6 +66,41 @@ function componentIds(program, kind) {
   return { titleId, labelId, backgroundId, symbolIds };
 }
 
+function legendGraphicBounds(program, id) {
+  let bounds = resolveConcreteGraphicBounds(program.graphicSpec, id, program.materializationConfigs.textMetrics);
+  const graphic = program.graphicSpec.objects[id];
+  if (!id.includes("LegendSymbol") || graphic?.type !== "line") return bounds;
+  const properties = graphic.items?.map(item => item.properties) ??
+    [graphic.properties];
+  for (const item of properties) {
+    if (
+      Object.hasOwn(item, "lineCap") ||
+      typeof item.stroke !== "string" ||
+      !(item.strokeWidth > 0)
+    ) continue;
+    const extent = item.strokeWidth / 2;
+    bounds = {
+      left: Math.min(bounds.left, Math.min(item.x1, item.x2) - extent),
+      right: Math.max(bounds.right, Math.max(item.x1, item.x2) + extent),
+      top: Math.min(bounds.top, Math.min(item.y1, item.y2) - extent),
+      bottom: Math.max(bounds.bottom, Math.max(item.y1, item.y2) + extent)
+    };
+  }
+  return bounds;
+}
+
+function unionLegendBounds(program, ids) {
+  return ids.map(id => legendGraphicBounds(program, id))
+    .reduce((result, bounds) => result === undefined
+      ? bounds
+      : {
+          left: Math.min(result.left, bounds.left),
+          right: Math.max(result.right, bounds.right),
+          top: Math.min(result.top, bounds.top),
+          bottom: Math.max(result.bottom, bounds.bottom)
+        }, undefined);
+}
+
 function textAnchor(program, id) {
   const graphic = program.graphicSpec.objects[id];
   const properties = graphic.items?.[0]?.properties ?? graphic.properties;
@@ -79,22 +117,16 @@ function blockDescriptor(program, kind, config) {
     components.labelId,
     ...(components.titleId === undefined ? [] : [components.titleId])
   ];
-  const bounds = unionConcreteGraphicBounds(program.graphicSpec, foregroundIds);
-  const symbolAnchorIds = kind === "gradient"
-    ? ["colorGradientStrips"]
+  const bounds = unionLegendBounds(program, foregroundIds);
+  const symbolAnchorIds = ["gradient", "strokeGradient"].includes(kind)
+    ? [kind === "gradient" ? "colorGradientStrips" : "strokeGradientStrips"]
     : components.symbolIds;
-  const symbolAnchor = unionConcreteGraphicBounds(
-    program.graphicSpec,
-    symbolAnchorIds
-  );
-  const symbolBounds = unionConcreteGraphicBounds(
-    program.graphicSpec,
-    components.symbolIds
-  );
+  const symbolAnchor = unionLegendBounds(program, symbolAnchorIds);
+  const symbolBounds = unionLegendBounds(program, components.symbolIds);
   const labels = resolveConcreteGraphicBounds(
     program.graphicSpec,
     components.labelId
-  );
+  , program.materializationConfigs.textMetrics);
   const title = components.titleId === undefined
     ? undefined
     : (() => {
@@ -102,7 +134,7 @@ function blockDescriptor(program, kind, config) {
         const titleBounds = resolveConcreteGraphicBounds(
           program.graphicSpec,
           components.titleId
-        );
+        , program.materializationConfigs.textMetrics);
         return {
           x: graphic.properties.x,
           y: graphic.properties.y,
@@ -132,7 +164,7 @@ function blockDescriptor(program, kind, config) {
       x: textAnchor(program, components.labelId),
       width: labels.right - labels.left
     },
-    occupiedBounds: unionConcreteGraphicBounds(program.graphicSpec, [
+    occupiedBounds: unionLegendBounds(program, [
       ...foregroundIds,
       ...(components.backgroundId === undefined ? [] : [components.backgroundId])
     ]),
@@ -142,7 +174,10 @@ function blockDescriptor(program, kind, config) {
 }
 
 function borderFor(kind, config) {
-  return ["series", "color", "gradient", "opacity", "interval", "strokeWidth", "size"].includes(kind)
+  return [
+    "series", "color", "stroke", "gradient", "strokeGradient", "opacity",
+    "interval", "strokeInterval", "strokeWidth", "size"
+  ].includes(kind)
     ? config.border
     : false;
 }
@@ -154,7 +189,7 @@ function groupBlocks(blocks, configs) {
     const config = configs[block.kind];
     const next = blocks[index + 1];
     if (
-      ["series", "color"].includes(block.kind) &&
+      ["series", "color", "stroke"].includes(block.kind) &&
       next?.kind === "size" && next.target === block.target
     ) {
       groups.push({
@@ -282,9 +317,9 @@ function horizontalGroups(program, groups) {
       .filter(id => id !== titleId);
     if (atomic) contentIds.push(...group.blocks.slice(1).flatMap(block =>
       block.backgroundId === undefined ? [] : [block.backgroundId]));
-    const content = unionConcreteGraphicBounds(program.graphicSpec, contentIds);
-    const foreground = unionConcreteGraphicBounds(
-      program.graphicSpec,
+    const content = unionLegendBounds(program, contentIds);
+    const foreground = unionLegendBounds(
+      program,
       [...contentIds, ...(titleId === undefined ? [] : [titleId])]
     );
     if (content === undefined || foreground === undefined) {
@@ -339,7 +374,7 @@ function applyHorizontalPlan(program, groups, plan) {
   return next;
 }
 
-export const rematerializeSideLegendLane = action(
+export const rematerializeSideLegendLane = /* @__PURE__ */ action(
   {
     op: "rematerializeSideLegendLane",
     description: "Align and stack every right or left legend block."
@@ -404,7 +439,7 @@ export const rematerializeSideLegendLane = action(
       }
       for (const block of blocks) {
         if (block.backgroundId === undefined || plan.backgrounds.some(item => item.id === block.backgroundId)) continue;
-        const bounds = unionConcreteGraphicBounds(next.graphicSpec, block.foregroundIds);
+        const bounds = unionLegendBounds(next, block.foregroundIds);
         const background = resolveLegendBackgroundFromBounds([bounds], block.border, canvas, "Legend");
         next = editLegendBackground(next, block.backgroundId, background, block.border);
       }
@@ -422,7 +457,7 @@ export const rematerializeSideLegendLane = action(
   }
 );
 
-export const rematerializeHorizontalLegendLane = action(
+export const rematerializeHorizontalLegendLane = /* @__PURE__ */ action(
   {
     op: "rematerializeHorizontalLegendLane",
     description: "Pack and align every top or bottom legend block."
@@ -444,7 +479,7 @@ export const rematerializeHorizontalLegendLane = action(
       if (entries.length === 1) {
         const [kind, config] = entries[0];
         const ids = existingIds(next, kind);
-        const bounds = unionConcreteGraphicBounds(next.graphicSpec, ids);
+        const bounds = unionConcreteGraphicBounds(next.graphicSpec, ids, next.materializationConfigs.textMetrics);
         const { dx, dy } = resolveSingleHorizontalLegendPlacement({
           plot, canvas, config, bounds
         });

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

@@ -49,8 +49,13 @@ export function resolveCategoricalLegendRevision(program, kind, previous, channe
   const config = {
     ...previous,
     ...definition,
-    symbol: normalizeRecipe(resolveLegendSymbol(program, layer, channels,
-      previous.inferredSymbol ? undefined : previous.symbol), definition.kind)
+    symbol: normalizeRecipe(resolveLegendSymbol(
+      program,
+      layer,
+      channels,
+      previous.inferredSymbol ? undefined : previous.symbol,
+      definition.kind
+    ), definition.kind, { internal: previous.inferredSymbol })
   };
   if (validateLayout) resolveLayout(program, config);
   return { kind, config, order };
@@ -76,11 +81,11 @@ export function createCategoricalLegendFromConfig(program, config, order) {
   } else {
     next = next
       .editSemantic({
-        property: "guide.legend.color.scale",
+        property: `guide.legend.${kind}.scale`,
         value: config.scales[0]
       })
       .editSemantic({
-        property: "guide.legend.color.title",
+        property: `guide.legend.${kind}.title`,
         value: config.title
       });
   }
@@ -91,9 +96,15 @@ export function createCategoricalLegendFromConfig(program, config, order) {
     });
   }
   next = next._withLegendConfig(kind, config);
-  if (config.border !== false) next = next.createLegendBackground();
-  next = next.createLegendSymbols().createLegendLabels();
-  return config.titleVisible === false ? next : next.createLegendTitle();
+  if (config.border !== false) {
+    next = next.createLegendBackground({ kind });
+  }
+  next = next
+    .createLegendSymbols({ kind })
+    .createLegendLabels({ kind });
+  return config.titleVisible === false
+    ? next
+    : next.createLegendTitle({ kind });
 }
 
 // Categorical content precedes its sampled companions in both creation and revision.
@@ -125,7 +136,7 @@ export function reconcileCategoricalSymbols(program, previous, config) {
   for (const layer of config.symbol.layers) {
     if (next.graphicSpec.objects[symbolGraphic(config, layer.type)] === undefined) {
       const suffix = { line: "Lines", point: "Points", swatch: "Swatches" }[layer.type];
-      next = next[`createLegendSymbol${suffix}`]();
+      next = next[`createLegendSymbol${suffix}`]({ kind: config.kind });
     }
   }
   return next;

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

@@ -1,22 +1,25 @@
-import { action } from "../../../core/action.js";
-import { validateKeys } from "../../../core/validation.js";
+import { closedAction } from "../../../core/action.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];
@@ -46,8 +49,13 @@ function resolveRequestedRemoval(program, target, channels) {
   // Remove departing sibling configs from the immutable layout preflight view.
   const view = kinds.reduce((next, kind) =>
     next._withoutMaterializationConfig(["guides", "legend", kind]), program);
-  const revision = partial === undefined ? undefined
+  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 };
 }
 
@@ -59,10 +67,9 @@ export function removeOwnedColorLegends(program, target) {
   return kinds.length === 0 ? program : removeLegendKinds(program, kinds);
 }
 
-export const removeLegend = action(
-  { op: "removeLegend", description: "Remove selected legend content or every block owned by one mark." },
+export const removeLegend = /* @__PURE__ */ closedAction(
+  { op: "removeLegend", description: "Remove selected legend content or every block owned by one mark." }, OPTIONS,
   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)
@@ -81,7 +88,9 @@ 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 && revision === undefined &&
       remainingTargetKinds.includes("size") &&

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