ggaction 0.0.12 → 0.0.15

package/src/actions/guides/legends/continuous/common.js

@@ -9,24 +9,32 @@ import {
   validateGeneratedItemLimit
 } from "../../../../core/validation.js";
 import { formatTimeTick } from "../../../../grammar/ticks.js";
+import {
+  formatValue,
+  validateValueFormat
+} from "../../../../grammar/valueFormat.js";
 import {
   formatDistinctNumericSamples,
   sampleNumericRange
 } from "../../../../grammar/numeric.js";
 import { resolveGraphicBounds } from "../../../../layout/canvas.js";
+import { isHorizontalEdgeLegend } from "../../../../layout/legendLane.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../../theme/defaults.js";
 import { findLayer } from "../../../../selectors/layers.js";
+import { isOpacityLegendLayer } from "../../../../materialization/legends.js";
 import { findCanvasGraphic } from
   "../../../../materialization/graphicHierarchy.js";
+import { normalizeLegendSampling } from "../sampling.js";
 
 const OPTIONS = [
   "target", "channels", "position", "align", "offset", "title", "count",
+  "values",
   "gradient", "symbol", "labels", "titleStyle", "itemGap", "border",
   "direction", "columns", "titlePosition"
 ];
 const TEXT_OPTIONS = [
-  "offset", "color", "fontSize", "fontFamily", "fontWeight"
+  "offset", "color", "fontSize", "fontFamily", "fontWeight", "format"
 ];
 const BORDER_OPTIONS = [
   "color", "lineWidth", "padding", "background"
@@ -82,9 +90,19 @@ export function normalizeLegendTextOptions(value, label, defaults) {
   ) {
     throw new TypeError(`${label} fontWeight must be a string or finite number.`);
   }
+  if (Object.hasOwn(result, "format")) {
+    result.format = validateValueFormat(result.format, `${label} format`);
+  }
   return result;
 }
 
+export function normalizeLegendTitleOptions(value, label, defaults) {
+  if (value !== undefined) {
+    validateOptionObject(value, ["color", "fontSize", "fontFamily", "fontWeight"], label);
+  }
+  return normalizeLegendTextOptions(value, label, defaults);
+}
+
 export function normalizeLegendBorder(value) {
   if (value === undefined || value === false) return false;
   if (value !== true && !isPlainObject(value)) {
@@ -110,13 +128,27 @@ export function normalizeContinuousLegend(args, kind) {
   if (!["left", "center", "right"].includes(align)) {
     throw new Error(`Unsupported legend alignment "${align}".`);
   }
-  const count = args.count ?? 5;
-  if (!Number.isInteger(count) || count < 2) {
-    throw new RangeError(
-      "Continuous legend count must be an integer of at least 2."
-    );
+  if (["left", "right"].includes(position) && align !== "center") {
+    throw new Error("Side continuous legends require center alignment.");
+  }
+  if (kind === "gradient" && Object.hasOwn(args, "values")) {
+    throw new Error("Gradient legends do not support exact sample values.");
+  }
+  const sampling = kind === "opacity"
+    ? normalizeLegendSampling(args, {
+        operation: "create",
+        label: "Opacity legend"
+      })
+    : undefined;
+  const count = kind === "gradient" ? args.count ?? 5 : undefined;
+  if (kind === "gradient") {
+    if (!Number.isInteger(count) || count < 2) {
+      throw new RangeError(
+        "Continuous legend count must be an integer of at least 2."
+      );
+    }
+    validateGeneratedItemLimit(count, "Continuous legend count");
   }
-  validateGeneratedItemLimit(count, "Continuous legend count");
   const offset = args.offset ?? 30;
   validateNonNegative(offset, "Legend offset");
   const titlePosition = args.titlePosition ?? "top";
@@ -152,7 +184,7 @@ export function normalizeContinuousLegend(args, kind) {
     position,
     align,
     offset,
-    count,
+    ...(kind === "gradient" ? { count } : { sampling }),
     title: args.title,
     inferredTitle: args.title === undefined,
     labels: normalizeLegendTextOptions(
@@ -162,7 +194,7 @@ export function normalizeContinuousLegend(args, kind) {
         ? { ...DEFAULT_LABELS, offset: 8 }
         : DEFAULT_LABELS
     ),
-    titleStyle: normalizeLegendTextOptions(
+    titleStyle: normalizeLegendTitleOptions(
       args.titleStyle,
       "createLegend.titleStyle",
       DEFAULT_TITLE
@@ -182,35 +214,40 @@ export function selectLegendLayer(program, requested, predicate) {
   return candidates.includes(candidate) ? candidate : undefined;
 }
 
-export function resolveContinuousPoint(program, requested, channel) {
+export function resolveContinuousLegendLayer(program, requested, channel) {
   const layer = selectLegendLayer(
     program,
     requested,
-    candidate => candidate.mark?.type === "point" &&
-      candidate.encoding?.[channel]?.scale !== undefined
+    channel === "opacity" ? isOpacityLegendLayer : candidate =>
+      candidate.mark?.type === "point" && candidate.encoding?.[channel]?.scale !== undefined
   );
   if (layer === undefined) {
     throw new Error(
       requested === undefined
-        ? `${channel} legend requires one eligible point mark.`
+        ? `${channel} legend requires one eligible ${channel === "opacity" ? "point or line" : "point"} mark.`
         : `Unknown ${channel} legend target "${requested}".`
     );
   }
   return layer;
 }
 
-export function resolveContinuousColorLayer(program, requested) {
+export function resolveContinuousColorLayer(program, requested, channel = "color") {
   const layer = selectLegendLayer(
     program,
     requested,
-    candidate => ["point", "bar", "rect"].includes(candidate.mark?.type) &&
-      candidate.encoding?.color?.scale !== undefined
+    candidate => (channel === "stroke"
+      ? ["point", "line", "area", "bar", "rect", "arc", "rule", "tick"]
+      : ["point", "bar", "rect"]
+    ).includes(candidate.mark?.type) &&
+      candidate.encoding?.[channel]?.scale !== undefined
   );
   if (layer === undefined) {
     throw new Error(
       requested === undefined
-        ? "color legend requires one eligible point, bar, or rect mark."
-        : `Unknown color legend target "${requested}".`
+        ? channel === "color"
+          ? "color legend requires one eligible point, bar, or rect mark."
+          : "stroke legend requires one eligible mark."
+        : `Unknown ${channel} legend target "${requested}".`
     );
   }
   return layer;
@@ -251,10 +288,18 @@ export function sampleContinuousValues(domain, count) {
   );
 }
 
-export function formatContinuousValues(values, domain, fieldType) {
-  return fieldType === "temporal"
-    ? values.map(value => formatTimeTick(value, domain))
-    : formatDistinctNumericSamples(values);
+export function formatContinuousValues(values, domain, fieldType, format = "auto") {
+  const resolved = validateValueFormat(format, "Legend label format");
+  if (resolved === "auto") {
+    return fieldType === "temporal"
+      ? values.map(value => formatTimeTick(value, domain))
+      : formatDistinctNumericSamples(values);
+  }
+  return values.map(value => formatValue(value, {
+    format: resolved,
+    valueType: fieldType === "temporal" ? "temporal" : "quantitative",
+    label: "Legend label format"
+  }));
 }
 
 export function styleContinuousText(
@@ -284,7 +329,10 @@ export function resolveLegendTextBounds(position, text, style) {
   });
 }
 
-export function assertLegendBoundsInsideCanvas(bounds, canvas, label) {
+export function assertLegendBoundsInsideCanvas(bounds, canvas, label, config) {
+  // Horizontal content is intrinsic until the shared lane places its actual
+  // concrete bounds. Only that final placement can determine Canvas fit.
+  if (isHorizontalEdgeLegend(config)) return;
   if (bounds.some(item =>
     item.left < 0 || item.right > canvas.width ||
     item.top < 0 || item.bottom > canvas.height
@@ -297,7 +345,8 @@ export function resolveLegendBackgroundFromBounds(
   bounds,
   border,
   canvas,
-  label
+  label,
+  config
 ) {
   if (border === false) return undefined;
   const strokeExtent = border.lineWidth / 2;
@@ -315,11 +364,11 @@ export function resolveLegendBackgroundFromBounds(
   y -= border.padding;
   right += border.padding;
   bottom += border.padding;
-  if (
+  if (!isHorizontalEdgeLegend(config) && (
     x - strokeExtent < 0 || y - strokeExtent < 0 ||
     right + strokeExtent > canvas.width ||
     bottom + strokeExtent > canvas.height
-  ) {
+  )) {
     throw new Error(`${label} background requires more Canvas margin space.`);
   }
   return { x, y, width: right - x, height: bottom - y };
@@ -334,3 +383,27 @@ export function editLegendBackground(program, id, bounds, border) {
     strokeWidth: border.lineWidth
   });
 }
+
+export function normalizeItemLegendLayout(args) {
+  const position = args.position ?? "right";
+  if (!["right", "left", "top", "bottom"].includes(position)) throw new Error(`Unsupported legend position "${position}".`);
+  const side = ["left", "right"].includes(position);
+  const layout = args.layout === undefined ? "edge" : args.layout;
+  if (layout !== "edge") throw new Error('This legend requires layout "edge".');
+  const align = args.align ?? "center";
+  if (!["left", "center", "right"].includes(align)) throw new Error(`Unsupported legend alignment "${align}".`);
+  const direction = args.direction ?? (side ? "vertical" : "horizontal");
+  if (!["horizontal", "vertical"].includes(direction)) throw new Error(`Unsupported legend direction "${direction}".`);
+  const columns = args.columns;
+  if (columns !== undefined && (!Number.isInteger(columns) || columns < 1)) throw new RangeError("Legend columns must be a positive integer.");
+  const titlePosition = args.titlePosition ?? "top";
+  if (!["top", "left"].includes(titlePosition)) throw new Error(`Unsupported legend titlePosition "${titlePosition}".`);
+  if (side && (direction !== "vertical" || align !== "center" || (columns !== undefined && columns !== 1) || titlePosition !== "top")) {
+    throw new Error("Side item legends require vertical direction, center alignment, top title and one column.");
+  }
+  const offset = args.offset ?? 30;
+  const itemGap = args.itemGap ?? 28;
+  validateNonNegative(offset, "Legend offset");
+  validatePositive(itemGap, "Legend itemGap");
+  return { position, layout, align, direction, columns, titlePosition, offset, itemGap };
+}

package/src/actions/guides/legends/continuous/gradient.js

@@ -1,7 +1,8 @@
 import { action } from "../../../../core/action.js";
 import { isPlainObject } from "../../../../core/immutable.js";
 import { validateKeys } from "../../../../core/validation.js";
-import { interpolateColorStops } from "../../../../grammar/scales/color.js";
+import { mapScaleConsumerValues } from "../../../../materialization/scales/map.js";
+import { inverseLerp, interpolateNumber } from "../../../../grammar/numeric.js";
 import { DEFAULT_COLORS } from "../../../../theme/defaults.js";
 import {
   assertLegendBoundsInsideCanvas,
@@ -19,22 +20,26 @@ import {
 } from "./common.js";
 import { resolveLegendGraphicPlacement } from
   "../../../../materialization/graphicHierarchy.js";
+import { resolveEffectiveLegendBlockConfig } from "../blocks.js";
+
+export const DEFAULT_GRADIENT_SIZE = Object.freeze({ length: 120, thickness: 12 });
 
 const GRADIENT_OPTIONS = Object.freeze(["length", "thickness"]);
 
-function resolveGradientLayout(program, config, scale) {
+export function resolveGradientLayout(program, config, scale) {
   const { plot, canvas } = resolveContinuousBounds(program);
   const vertical = ["right", "left"].includes(config.position);
   const length = config.gradient.length;
   const thickness = config.gradient.thickness;
+  const titleGap = config.blockGap ?? 12;
   let x;
   let y;
   if (config.position === "right") {
     x = plot.x + plot.width + config.offset;
-    y = plot.y + 46;
+    y = plot.y + 46 + titleGap - 12;
   } else if (config.position === "left") {
     x = plot.x - config.offset - thickness;
-    y = plot.y + 46;
+    y = plot.y + 46 + titleGap - 12;
   } else {
     x = config.align === "left" ? plot.x
       : config.align === "right" ? plot.x + plot.width - length
@@ -43,18 +48,29 @@ function resolveGradientLayout(program, config, scale) {
       ? plot.y - config.offset - thickness - config.labels.offset -
         config.labels.fontSize
       : plot.y + plot.height + config.offset +
-        config.titleStyle.fontSize + 12;
+        (config.titleVisible === false ? 0 : config.titleStyle.fontSize + titleGap);
   }
   const title = vertical
     ? { x, y: plot.y + 20, align: "left" }
     : {
         x: x + length / 2,
-        y: y - 12 - config.titleStyle.fontSize / 2,
+        y: y - titleGap - config.titleStyle.fontSize / 2,
         align: "center"
       };
-  const values = sampleContinuousValues(scale.domain, config.count);
-  const texts = formatContinuousValues(values, scale.domain, config.fieldType);
-  const fractions = values.map((_, index) => index / (values.length - 1));
+  const values = [...sampleContinuousValues(scale.domain, config.count)];
+  if (scale.midpoint !== undefined && !values.includes(scale.midpoint)) {
+    values.push(scale.midpoint);
+    values.sort((a, b) => scale.domain[1] > scale.domain[0] ? a - b : b - a);
+  }
+  const texts = formatContinuousValues(
+    values,
+    scale.domain,
+    config.fieldType,
+    config.labels.format
+  );
+  const fractions = values.map((value, index) => scale.midpoint === undefined
+    ? index / (values.length - 1)
+    : inverseLerp(value, ...scale.domain));
   const labelOffset = config.labels.offset;
   const labels = vertical
     ? fractions.map(fraction => ({
@@ -97,22 +113,23 @@ function resolveGradientLayout(program, config, scale) {
   const labelBounds = labels.map((label, index) =>
     resolveLegendTextBounds(label, texts[index], config.labels)
   );
-  const titleBounds = resolveLegendTextBounds(
+  const titleBounds = config.titleVisible === false ? undefined : resolveLegendTextBounds(
     title,
     config.title,
     config.titleStyle
   );
-  const occupiedBounds = [stripBounds, ...tickBounds, ...labelBounds, titleBounds];
+  const occupiedBounds = [stripBounds, ...tickBounds, ...labelBounds,
+    ...(config.titleVisible === false ? [] : [titleBounds])];
   assertLegendBoundsInsideCanvas(
     occupiedBounds,
     canvas,
-    "Gradient legend layout"
+    "Gradient legend layout", config
   );
   const background = resolveLegendBackgroundFromBounds(
     occupiedBounds,
     config.border,
     canvas,
-    "Gradient legend"
+    "Gradient legend", config
   );
   return {
     vertical, x, y, length, thickness, values, texts, labels, ticks, title,
@@ -157,17 +174,18 @@ export const rematerializeGradientLegend = action(
     if (stored === undefined) {
       throw new Error("Gradient legend requires stored configuration.");
     }
-    const { scale, encoding, config } = resolveGradientConfig(this, stored);
+    const { scale, encoding, config: currentConfig } = resolveGradientConfig(this, stored);
+    const config = resolveEffectiveLegendBlockConfig(this, "gradient", currentConfig);
     const layout = resolveGradientLayout(this, config, scale);
     const stripCount = 60;
     const stripSize = layout.length / stripCount;
     const strips = Array.from({ length: stripCount }, (_, index) => {
       const fraction = (index + 0.5) / stripCount;
-      const color = interpolateColorStops(
-        scale.range,
-        layout.vertical ? 1 - fraction : fraction,
-        scale.interpolate
-      );
+      const position = layout.vertical ? 1 - fraction : fraction;
+      // Keep legacy uniform samples exact without a value/domain round trip.
+      const samplingScale = scale.midpoint === undefined ? { ...scale, domain: [0, 1] } : scale;
+      const value = scale.midpoint === undefined ? position : interpolateNumber(...scale.domain, position);
+      const [color] = mapScaleConsumerValues([value], samplingScale, "color");
       return {
         x: layout.x + (layout.vertical ? 0 : index * stripSize),
         y: layout.y + (layout.vertical ? index * stripSize : 0),
@@ -187,7 +205,7 @@ export const rematerializeGradientLegend = action(
         property: "guide.legend.color.title",
         value: config.title
       })
-      ._withLegendConfig("gradient", config)
+      ._withLegendConfig("gradient", currentConfig)
       .editGraphics({
         target: "colorGradientStrips",
         property: "length",
@@ -283,86 +301,99 @@ export const rematerializeGradientLegend = action(
   }
 );
 
+
+export function resolveGradientLegendCreation(program, args = {}) {
+  const config = normalizeContinuousLegend(args, "gradient");
+  if (args.channels !== undefined && (
+    !Array.isArray(args.channels) ||
+    args.channels.length !== 1 ||
+    args.channels[0] !== "color"
+  )) {
+    throw new Error('Gradient legend requires channels: ["color"].');
+  }
+  if (args.gradient !== undefined && !isPlainObject(args.gradient)) {
+    throw new TypeError("createLegend.gradient must be a plain object.");
+  }
+  validateKeys(
+    args.gradient ?? {},
+    GRADIENT_OPTIONS,
+    "createLegend.gradient"
+  );
+  config.gradient = {
+    length: args.gradient?.length ?? DEFAULT_GRADIENT_SIZE.length,
+    thickness: args.gradient?.thickness ?? DEFAULT_GRADIENT_SIZE.thickness
+  };
+  config.titleVisible = true;
+  validatePositive(config.gradient.length, "Gradient length");
+  validatePositive(config.gradient.thickness, "Gradient thickness");
+  const resolved = resolveGradientConfig(program, config);
+  return resolved;
+}
+
+export function createGradientLegendFromConfig(program, config) {
+  const resolved = resolveGradientConfig(program, config);
+  resolveGradientLayout(program, resolved.config, resolved.scale);
+  let next = program
+    .editSemantic({
+      property: "guide.legend.color.scale",
+      value: resolved.encoding.scale
+    })
+    .editSemantic({
+      property: "guide.legend.color.title",
+      value: resolved.config.title
+    })
+    ._withLegendConfig("gradient", resolved.config);
+  if (resolved.config.border !== false) {
+    next = next.createGraphics({
+      id: "colorGradientBackground",
+      type: "rect",
+      ...resolveLegendGraphicPlacement(next)
+    });
+  }
+  next = next
+    .createGraphics({
+      id: "colorGradientStrips",
+      type: "rect",
+      length: 0,
+      ...resolveLegendGraphicPlacement(next, resolved.config.border === false
+        ? {}
+        : { after: "colorGradientBackground" })
+    })
+    .createGraphics({
+      id: "colorGradientTicks",
+      type: "line",
+      length: 0,
+      ...resolveLegendGraphicPlacement(next)
+    })
+    .createGraphics({
+      id: "colorGradientLabels",
+      type: "text",
+      length: 0,
+      ...resolveLegendGraphicPlacement(next)
+    });
+  if (resolved.config.titleVisible !== false) {
+    next = next.createGraphics({
+      id: "colorGradientTitle",
+      type: "text",
+      ...resolveLegendGraphicPlacement(next)
+    });
+  }
+  return next.rematerializeGradientLegend();
+}
+
 export const createGradientLegend = action(
   {
     op: "createGradientLegend",
     description: "Create a continuous color gradient legend."
   },
   function (args = {}) {
-    const config = normalizeContinuousLegend(args, "gradient");
-    if (args.channels !== undefined && (
-      !Array.isArray(args.channels) ||
-      args.channels.length !== 1 ||
-      args.channels[0] !== "color"
-    )) {
-      throw new Error('Gradient legend requires channels: ["color"].');
-    }
-    if (args.gradient !== undefined && !isPlainObject(args.gradient)) {
-      throw new TypeError("createLegend.gradient must be a plain object.");
-    }
-    validateKeys(
-      args.gradient ?? {},
-      GRADIENT_OPTIONS,
-      "createLegend.gradient"
-    );
-    config.gradient = {
-      length: args.gradient?.length ?? 120,
-      thickness: args.gradient?.thickness ?? 12
-    };
-    config.titleVisible = true;
-    validatePositive(config.gradient.length, "Gradient length");
-    validatePositive(config.gradient.thickness, "Gradient thickness");
-    const resolved = resolveGradientConfig(this, config);
+    const resolved = resolveGradientLegendCreation(this, args);
     resolveGradientLayout(this, resolved.config, resolved.scale);
     if (this.graphicSpec.objects.colorGradientStrips !== undefined) {
       throw new Error(
         "createGradientLegend requires a missing gradient legend."
       );
     }
-    let next = this
-      .editSemantic({
-        property: "guide.legend.color.scale",
-        value: resolved.encoding.scale
-      })
-      .editSemantic({
-        property: "guide.legend.color.title",
-        value: resolved.config.title
-      })
-      ._withLegendConfig("gradient", resolved.config);
-    if (resolved.config.border !== false) {
-      next = next.createGraphics({
-        id: "colorGradientBackground",
-        type: "rect",
-        ...resolveLegendGraphicPlacement(next)
-      });
-    }
-    return next
-      .createGraphics({
-        id: "colorGradientStrips",
-        type: "rect",
-        length: 0,
-        ...resolveLegendGraphicPlacement(next),
-        ...(resolved.config.border === false
-          ? {}
-          : { after: "colorGradientBackground" })
-      })
-      .createGraphics({
-        id: "colorGradientTicks",
-        type: "line",
-        length: 0,
-        ...resolveLegendGraphicPlacement(next)
-      })
-      .createGraphics({
-        id: "colorGradientLabels",
-        type: "text",
-        length: 0,
-        ...resolveLegendGraphicPlacement(next)
-      })
-      .createGraphics({
-        id: "colorGradientTitle",
-        type: "text",
-        ...resolveLegendGraphicPlacement(next)
-      })
-      .rematerializeGradientLegend();
+    return createGradientLegendFromConfig(this, resolved.config);
   }
 );

package/src/actions/guides/legends/continuous/index.js

@@ -5,6 +5,7 @@ import {
   removeOpacityLegend
 } from "./opacity.js";
 import { createIntervalLegend, rematerializeIntervalLegend } from "./interval.js";
+import { registerStrokeColorLegendActions } from "./stroke.js";
 
 export { createGradientLegend, rematerializeGradientLegend } from "./gradient.js";
 export {
@@ -19,11 +20,16 @@ export function registerContinuousLegendActions(ProgramClass) {
   ProgramClass.prototype.createOpacityLegend = createOpacityLegend;
   ProgramClass.prototype.rematerializeOpacityLegend = rematerializeOpacityLegend;
   ProgramClass.prototype.removeOpacityLegend = removeOpacityLegend;
-  ProgramClass.prototype.createIntervalLegend = createIntervalLegend;
-  ProgramClass.prototype.rematerializeIntervalLegend = rematerializeIntervalLegend;
+  registerIntervalLegendActions(ProgramClass);
+  registerStrokeColorLegendActions(ProgramClass);
 }
 
 export function registerGradientLegendActions(ProgramClass) {
   ProgramClass.prototype.createGradientLegend = createGradientLegend;
   ProgramClass.prototype.rematerializeGradientLegend = rematerializeGradientLegend;
 }
+
+export function registerIntervalLegendActions(ProgramClass) {
+  ProgramClass.prototype.createIntervalLegend = createIntervalLegend;
+  ProgramClass.prototype.rematerializeIntervalLegend = rematerializeIntervalLegend;
+}