ggaction 0.0.17 → 0.0.18

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

@@ -1,447 +1 @@
-import { isPlainObject } from "../../../../core/immutable.js";
-import { resolveTextBounds } from "../../../../core/textMetrics.js";
-import {
-  validateKeys,
-  validateOptionObject,
-  validateNonEmptyString,
-  validateNonNegativeFinite,
-  validatePositiveFinite,
-  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";
-import { editGraphicProperties } from "../../../primitives/graphicProperties.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", "format"
-];
-const BORDER_OPTIONS = [
-  "color", "lineWidth", "padding", "background"
-];
-const POSITIONS = ["right", "left", "top", "bottom"];
-const DEFAULT_LABELS = {
-  offset: 12,
-  color: DEFAULT_COLORS.text,
-  fontSize: 12,
-  fontFamily: DEFAULT_FONT_FAMILY,
-  fontWeight: "normal"
-};
-const DEFAULT_TITLE = {
-  color: DEFAULT_COLORS.text,
-  fontSize: 13,
-  fontFamily: DEFAULT_FONT_FAMILY,
-  fontWeight: 600
-};
-const DEFAULT_BORDER = {
-  color: DEFAULT_COLORS.border,
-  lineWidth: 1,
-  padding: 12,
-  background: "transparent"
-};
-
-export const validatePositive = validatePositiveFinite;
-export const validateNonNegative = validateNonNegativeFinite;
-
-export { editGraphicProperties };
-
-export function normalizeLegendTextOptions(value, label, defaults) {
-  if (value === undefined) return { ...defaults };
-  if (!isPlainObject(value)) {
-    throw new TypeError(`${label} must be a plain object.`);
-  }
-  validateKeys(value, TEXT_OPTIONS, label);
-  const result = { ...defaults, ...value };
-  if (Object.hasOwn(result, "offset")) {
-    validateNonNegative(result.offset, `${label} offset`);
-  }
-  validatePositive(result.fontSize, `${label} fontSize`);
-  for (const key of ["color", "fontFamily"]) {
-    validateNonEmptyString(result[key], `${label} ${key}`);
-  }
-  if (
-    typeof result.fontWeight !== "string" &&
-    !Number.isFinite(result.fontWeight)
-  ) {
-    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)) {
-    throw new TypeError("createLegend.border must be a boolean or plain object.");
-  }
-  if (value !== true) validateKeys(value, BORDER_OPTIONS, "createLegend.border");
-  const border = { ...DEFAULT_BORDER, ...(value === true ? {} : value) };
-  for (const key of ["color", "background"]) {
-    validateNonEmptyString(border[key], `Legend border ${key}`);
-  }
-  validateNonNegative(border.lineWidth, "Legend border lineWidth");
-  validateNonNegative(border.padding, "Legend border padding");
-  return border;
-}
-
-export function normalizeContinuousLegend(args, kind) {
-  validateOptionObject(args, OPTIONS, "createLegend");
-  const position = args.position ?? "right";
-  if (!POSITIONS.includes(position)) {
-    throw new Error(`Unsupported legend position "${position}".`);
-  }
-  const align = args.align ?? "center";
-  if (!["left", "center", "right"].includes(align)) {
-    throw new Error(`Unsupported legend alignment "${align}".`);
-  }
-  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");
-  }
-  const offset = args.offset ?? 30;
-  validateNonNegative(offset, "Legend offset");
-  const titlePosition = args.titlePosition ?? "top";
-  if (!["top", "left"].includes(titlePosition)) {
-    throw new Error(`Unsupported legend titlePosition "${titlePosition}".`);
-  }
-  if (
-    titlePosition === "left" &&
-    (!["top", "bottom"].includes(position) || kind !== "opacity")
-  ) {
-    throw new Error(
-      "Only horizontal opacity legends support left titlePosition."
-    );
-  }
-  const itemGap = args.itemGap ?? (titlePosition === "left" ? 20 : 28);
-  validatePositive(itemGap, "Legend itemGap");
-  if (args.title !== undefined) validateNonEmptyString(args.title, "Legend title");
-  if (kind === "gradient") {
-    for (const key of ["symbol", "columns", "direction", "itemGap"]) {
-      if (Object.hasOwn(args, key)) {
-        throw new Error(`Gradient legend does not accept ${key}.`);
-      }
-    }
-  } else {
-    for (const key of ["columns", "direction", "gradient"]) {
-      if (Object.hasOwn(args, key)) {
-        throw new Error(`Opacity legend does not accept ${key}.`);
-      }
-    }
-  }
-  return {
-    target: args.target,
-    position,
-    align,
-    offset,
-    ...(kind === "gradient" ? { count } : { sampling }),
-    title: args.title,
-    inferredTitle: args.title === undefined,
-    labels: normalizeLegendTextOptions(
-      args.labels,
-      "createLegend.labels",
-      titlePosition === "left"
-        ? { ...DEFAULT_LABELS, offset: 8 }
-        : DEFAULT_LABELS
-    ),
-    titleStyle: normalizeLegendTitleOptions(
-      args.titleStyle,
-      "createLegend.titleStyle",
-      DEFAULT_TITLE
-    ),
-    itemGap,
-    titlePosition,
-    border: normalizeLegendBorder(args.border)
-  };
-}
-
-export function selectLegendLayer(program, requested, predicate) {
-  const candidates = program.semanticSpec.layers.filter(predicate);
-  if (requested === undefined) return candidates.length === 1
-    ? candidates[0]
-    : undefined;
-  const candidate = findLayer(program, requested);
-  return candidates.includes(candidate) ? candidate : undefined;
-}
-
-export function resolveContinuousLegendLayer(program, requested, channel) {
-  const layer = selectLegendLayer(
-    program,
-    requested,
-    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 ${channel === "opacity" ? "point or line" : "point"} mark.`
-        : `Unknown ${channel} legend target "${requested}".`
-    );
-  }
-  return layer;
-}
-
-export function resolveContinuousColorLayer(program, requested, channel = "color") {
-  const layer = selectLegendLayer(
-    program,
-    requested,
-    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
-        ? 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;
-}
-
-export function requireResolvedLegendScale(program, id, type) {
-  const scale = program.resolvedScales[id];
-  if (scale?.type !== type) {
-    throw new Error(`Legend requires resolved ${type} scale "${id}".`);
-  }
-  return scale;
-}
-
-export function resolveContinuousBounds(
-  program,
-  message = "Continuous legend layout requires Canvas bounds."
-) {
-  const plot = resolveGraphicBounds(program);
-  const canvas = findCanvasGraphic(program);
-  if (
-    plot === undefined ||
-    ![plot.x, plot.y, plot.width, plot.height].every(Number.isFinite) ||
-    canvas?.type !== "canvas" ||
-    !Number.isFinite(canvas.properties.width) ||
-    !Number.isFinite(canvas.properties.height)
-  ) {
-    throw new Error(message);
-  }
-  return { plot, canvas: canvas.properties };
-}
-
-export function sampleContinuousValues(domain, count) {
-  return sampleNumericRange(
-    domain[0],
-    domain[1],
-    count,
-    "Continuous legend domain"
-  );
-}
-
-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(
-  program,
-  id,
-  style,
-  { align = "left" } = {}
-) {
-  return editGraphicProperties(program, id, {
-    fill: style.color,
-    fontSize: style.fontSize,
-    fontFamily: style.fontFamily,
-    fontWeight: style.fontWeight,
-    textAlign: align,
-    textBaseline: "middle"
-  });
-}
-
-export function resolveLegendTextBounds(position, text, style, profile) {
-  return resolveTextBounds({
-    x: position.x,
-    y: position.y,
-    text: String(text),
-    ...style,
-    textAlign: position.align ?? "left",
-    textBaseline: "middle"
-  }, profile);
-}
-
-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
-  )) {
-    throw new Error(`${label} requires more Canvas margin space.`);
-  }
-}
-
-export function resolveLegendBackgroundFromBounds(
-  bounds,
-  border,
-  canvas,
-  label,
-  config
-) {
-  if (border === false) return undefined;
-  const strokeExtent = border.lineWidth / 2;
-  let x = Infinity;
-  let y = Infinity;
-  let right = -Infinity;
-  let bottom = -Infinity;
-  for (const item of bounds) {
-    x = Math.min(x, item.left);
-    y = Math.min(y, item.top);
-    right = Math.max(right, item.right);
-    bottom = Math.max(bottom, item.bottom);
-  }
-  x -= border.padding;
-  y -= border.padding;
-  right += border.padding;
-  bottom += border.padding;
-  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 };
-}
-
-export function editLegendBackground(program, id, bounds, border) {
-  if (bounds === undefined) return program;
-  return editGraphicProperties(program, id, {
-    ...bounds,
-    fill: border.background,
-    stroke: border.color,
-    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 };
-}
-
-export function materializeItemLegend(program, kind, config, layout, {
-  symbols, optional = {}, text = layout.labels,
-  labels = layout.config.labels, titleStyle = layout.config.titleStyle
-}) {
-  const prefix = `${kind}Legend`;
-  let next = program
-    .editSemantic({ property: `guide.legend.${kind}.scale`, value: config.scale })
-    .editSemantic({ property: `guide.legend.${kind}.title`, value: config.title })
-    ._withLegendConfig(kind, config);
-  next = editGraphicProperties(next, `${prefix}Symbols`, {
-    length: text.length,
-    ...symbols
-  });
-  next = editGraphicProperties(next, `${prefix}Labels`, {
-    length: text.length, x: layout.labelX, y: layout.itemY, text
-  });
-  next = editLegendBackground(next, `${prefix}Background`, layout.background, config.border);
-  next = editGraphicProperties(next, `${prefix}Symbols`, Object.fromEntries(
-    Object.entries(optional).filter(([, value]) => value !== undefined)
-  ));
-  next = styleContinuousText(next, `${prefix}Labels`, labels);
-  const effective = layout.config;
-  if (effective.titleVisible === false) return next;
-  next = editGraphicProperties(next, `${prefix}Title`, {
-    x: layout.title.x, y: layout.title.y, text: effective.title
-  });
-  return styleContinuousText(next, `${prefix}Title`, titleStyle, { align: layout.title.align });
-}
-
-export function createItemLegendGraphics(program, kind, config, count, type, placement) {
-  const prefix = `${kind}Legend`;
-  let next = program
-    .editSemantic({ property: `guide.legend.${kind}.scale`, value: config.scale })
-    .editSemantic({ property: `guide.legend.${kind}.title`, value: config.title })
-    ._withLegendConfig(kind, config);
-  if (config.border !== false) next = next.createGraphics({ id: `${prefix}Background`, type: "rect", ...placement });
-  next = next.createGraphics({ id: `${prefix}Symbols`, type, length: count, ...placement })
-    .createGraphics({ id: `${prefix}Labels`, type: "text", length: count, ...placement });
-  if (config.titleVisible !== false) next = next.createGraphics({ id: `${prefix}Title`, type: "text", ...placement });
-  return next;
-}
+import{LEGEND_TITLE_STYLE_KEYS as A,mergeLegendTitleStyle as W,validateLegendTitleAlignment as x}from"../../../../grammar/legendTitleStyle.js";import{PLOT_LEGEND_POSITIONS as k,isPlotLegend as p}from"../../../../layout/legend.js";import{isContinuousColorScaleType as D}from"../../../../grammar/scales/types.js";import{isPlainObject as T}from"../../../../core/immutable.js";import{resolveTextBounds as U}from"../../../../core/textMetrics.js";import{resolveLegendTitleText as R}from"../../../../layout/legendText.js";import{materializeLegendTitleLines as M}from"../../../../materialization/legendText.js";import{validateKeys as S,validateFontWeight as q,validateOptionObject as O,validateNonEmptyString as h,validateNonNegativeFinite as V,validatePositiveFinite as Y,validateGeneratedItemLimit as K}from"../../../../core/validation.js";import{formatTimeTick as X}from"../../../../grammar/ticks.js";import{formatValue as H,validateValueFormat as $}from"../../../../grammar/valueFormat.js";import{formatDistinctNumericSamples as J,sampleNumericRange as Q}from"../../../../grammar/numeric.js";import{resolveGraphicBounds as Z,canvasOverflowError as v}from"../../../../layout/canvas.js";import{isHorizontalEdgeLegend as I}from"../../../../layout/legendLane.js";import{DEFAULT_COLORS as m,DEFAULT_FONT_FAMILY as G,DEFAULT_VERTICAL_LEGEND_ITEM_GAP as L}from"../../../../theme/defaults.js";import{findLayer as ee}from"../../../../selectors/layers.js";import{isOpacityLegendLayer as te}from"../../../../materialization/legends.js";import{findCanvasGraphic as ne}from"../../../../materialization/graphicHierarchy.js";import{normalizeLegendSampling as ie}from"../sampling.js";import{editGraphicProperties as u}from"../../../primitives/graphicProperties.js";const oe=["target","channels","position","align","offset","title","count","values","gradient","symbol","labels","titleStyle","itemGap","border","direction","columns","titlePosition"],ze=Object.freeze(["target","count","values","position","layout","align","direction","columns","titlePosition","offset","itemGap","title","labels","titleStyle","border","overflow"]),re=["offset","color","fontSize","fontFamily","fontWeight","format"],le=["color","lineWidth","padding","background"],_=["right","left","top","bottom",...k],b={offset:12,color:m.text,fontSize:12,fontFamily:G,fontWeight:"normal"},z={color:m.text,fontSize:13,fontFamily:G,fontWeight:600},de=Object.freeze(b),se=Object.freeze({...z,color:m.strongText});function N(e,t){return e!==void 0&&e!==!1&&h(e,"Legend title"),{title:e===!1||e===void 0?t:e,inferredTitle:e===!1||e===void 0,titleVisible:e!==!1}}function Ne(e,t,n){const i=["right","left"].includes(e.position??"right")||p(e),r=(e.direction??(i?"vertical":"horizontal"))==="vertical"?L:n;return{...ce({...e,itemGap:e.itemGap??r}),...N(e.title,t.field),labels:w(e.labels,"createLegend.labels",de),titleStyle:C(e.titleStyle,"createLegend.titleStyle",se),border:F(e.border)}}const ae={color:m.border,lineWidth:1,padding:12,background:"transparent"},y=Y,g=V;function w(e,t,n){if(e===void 0)return{...n};if(!T(e))throw new TypeError(`${t} must be a plain object.`);S(e,re,t);const i={...n,...e};Object.hasOwn(i,"offset")&&g(i.offset,`${t} offset`),y(i.fontSize,`${t} fontSize`);for(const o of["color","fontFamily"])h(i[o],`${t} ${o}`);return q(i.fontWeight,`${t} fontWeight`,"finite number"),Object.hasOwn(i,"format")&&(i.format=$(i.format,`${t} format`)),i}function C(e,t,n,i=!1){e!==void 0&&O(e,A,t);const o=W(n,e,{edit:i}),{align:r,...d}=o;return{...w(d,t,{}),...r===void 0?{}:{align:r}}}function F(e){if(e===void 0||e===!1)return!1;if(e!==!0&&!T(e))throw new TypeError("createLegend.border must be a boolean or plain object.");e!==!0&&S(e,le,"createLegend.border");const t={...ae,...e===!0?{}:e};for(const n of["color","background"])h(t[n],`Legend border ${n}`);return g(t.lineWidth,"Legend border lineWidth"),g(t.padding,"Legend border padding"),t}function Ce(e,t){O(e,oe,"createLegend");const n=e.position??"right";if(!_.includes(n))throw new Error(`Unsupported legend position "${n}".`);const i=e.align??"center";if(!["left","center","right"].includes(i))throw new Error(`Unsupported legend alignment "${i}".`);if(["left","right"].includes(n)&&i!=="center")throw new Error("Side continuous legends require center alignment.");if(t==="gradient"&&Object.hasOwn(e,"values"))throw new Error("Gradient legends do not support exact sample values.");const o=t==="opacity"?ie(e,{operation:"create",label:"Opacity legend"}):void 0,r=t==="gradient"?e.count??5:void 0;if(t==="gradient"){if(!Number.isInteger(r)||r<2)throw new RangeError("Continuous legend count must be an integer of at least 2.");K(r,"Continuous legend count")}const d=e.offset??(p({position:n})?8:30);g(d,"Legend offset");const l=e.titlePosition??"top";if(x(e.titleStyle,l),!["top","left"].includes(l))throw new Error(`Unsupported legend titlePosition "${l}".`);if(l==="left"&&(!["top","bottom"].includes(n)||t!=="opacity"))throw new Error("Only horizontal opacity legends support left titlePosition.");const a=e.itemGap??(t==="opacity"&&(["right","left"].includes(n)||p({position:n}))?L:l==="left"?20:28);if(y(a,"Legend itemGap"),t==="gradient"){for(const s of["symbol","columns","direction","itemGap"])if(Object.hasOwn(e,s))throw new Error(`Gradient legend does not accept ${s}.`)}else for(const s of["columns","direction","gradient"])if(Object.hasOwn(e,s))throw new Error(`Opacity legend does not accept ${s}.`);return{target:e.target,position:n,align:i,offset:d,...t==="gradient"?{count:r}:{sampling:o},...N(e.title),labels:w(e.labels,"createLegend.labels",l==="left"?{...b,offset:8}:b),titleStyle:C(e.titleStyle,"createLegend.titleStyle",z),itemGap:a,titlePosition:l,border:F(e.border)}}function P(e,t,n){const i=e.semanticSpec.layers.filter(n);if(t===void 0)return i.length===1?i[0]:void 0;const o=ee(e,t);return i.includes(o)?o:void 0}function Fe(e,t,n){const i=P(e,t,n==="opacity"?te:o=>o.mark?.type==="point"&&o.encoding?.[n]?.scale!==void 0);if(i===void 0)throw new Error(t===void 0?`${n} legend requires one eligible ${n==="opacity"?"point, line or bar":"point"} mark.`:`Unknown ${n} legend target "${t}".`);return i}function Pe(e,t,n="color"){const i=P(e,t,o=>(n==="stroke"?["point","line","area","bar","rect","arc","rule","tick"]:["point","bar","rect","text"]).includes(o.mark?.type)&&o.encoding?.[n]?.scale!==void 0);if(i===void 0)throw new Error(t===void 0?n==="color"?"color legend requires one eligible point, bar, or rect mark.":"stroke legend requires one eligible mark.":`Unknown ${n} legend target "${t}".`);return i}function Be(e,t,n){const i=e.resolvedScales[t];if(n==="sequential"?!D(i?.type):i?.type!==n)throw new Error(`Legend requires resolved ${n} scale "${t}".`);return i}function je(e,t="Continuous legend layout requires Canvas bounds."){const n=Z(e),i=ne(e);if(n===void 0||![n.x,n.y,n.width,n.height].every(Number.isFinite)||i?.type!=="canvas"||!Number.isFinite(i.properties.width)||!Number.isFinite(i.properties.height))throw new Error(t);return{plot:n,canvas:i.properties}}function Ae(e,t){return Q(e[0],e[1],t,"Continuous legend domain")}function We(e,t,n,i="auto"){const o=$(i,"Legend label format");return o==="auto"?n==="temporal"?e.map(r=>X(r,t)):J(e):e.map(r=>H(r,{format:o,valueType:n==="temporal"?"temporal":"quantitative",label:"Legend label format"}))}function B(e,t,n,{align:i="left"}={}){const o=u(e,t,{fill:n.color,fontSize:n.fontSize,fontFamily:n.fontFamily,fontWeight:n.fontWeight,textAlign:i,textBaseline:"middle"});return t.endsWith("Title")?M(o,t,o.graphicSpec.objects[t].properties.text,n):o}function ke(e,t,n,i,{hardBreaks:o=!1}={}){return U({x:e.x,y:e.y,text:String(t),...n,...o?{lines:R(t,n,i).lines}:{},textAlign:e.align??"left",textBaseline:"middle"},i)}function De(e,t,n,i){if(!(i?.groupIntrinsic||I(i)||["left","right"].includes(i?.position))&&e.some(o=>o.left<0||o.right>t.width||o.top<0||o.bottom>t.height))throw v(`${n} requires more Canvas margin space.`,e,t)}function Ue(e,t,n,i,o){if(t===!1)return;const r=t.lineWidth/2;let d=1/0,l=1/0,a=-1/0,s=-1/0;for(const c of e)d=Math.min(d,c.left),l=Math.min(l,c.top),a=Math.max(a,c.right),s=Math.max(s,c.bottom);if(d-=t.padding,l-=t.padding,a+=t.padding,s+=t.padding,!o?.groupIntrinsic&&!I(o)&&!["left","right"].includes(o?.position)&&(d-r<0||l-r<0||a+r>n.width||s+r>n.height))throw v(`${i} background requires more Canvas margin space.`,[{left:d-r,right:a+r,top:l-r,bottom:s+r}],n);return{x:d,y:l,width:a-d,height:s-l}}function fe(e,t,n,i){return n===void 0?e:u(e,t,{...n,fill:i.background,stroke:i.color,strokeWidth:i.lineWidth})}function ce(e,{multiColumnSide:t=!1}={}){const n=e.position??"right";if(!_.includes(n))throw new Error(`Unsupported legend position "${n}".`);const i=["left","right"].includes(n)||p({position:n}),o=e.layout===void 0?"edge":e.layout;if(o!=="edge")throw new Error('This legend requires layout "edge".');const r=e.align??"center";if(!["left","center","right"].includes(r))throw new Error(`Unsupported legend alignment "${r}".`);const d=e.direction??(i?"vertical":"horizontal");if(!["horizontal","vertical"].includes(d))throw new Error(`Unsupported legend direction "${d}".`);const l=e.columns;if(l!==void 0&&(!Number.isInteger(l)||l<1))throw new RangeError("Legend columns must be a positive integer.");const a=e.titlePosition??"top";if(x(e.titleStyle,a),!["top","left"].includes(a))throw new Error(`Unsupported legend titlePosition "${a}".`);if(i&&(r!=="center"||a!=="top"||!t&&(d!=="vertical"||l!==void 0&&l!==1)))throw new Error("Side item legends require vertical direction, center alignment, top title and one column.");const s=e.offset??(p({position:n})?8:30),c=e.itemGap??(d==="vertical"?L:28);return g(s,"Legend offset"),y(c,"Legend itemGap"),{position:n,layout:o,align:r,direction:d,columns:l,titlePosition:a,offset:s,itemGap:c}}function Re(e,t,n,i,{symbols:o,optional:r={},text:d=i.labels,labels:l=i.config.labels,titleStyle:a=i.config.titleStyle}){const s=`${t}Legend`,c=Object.values(o).find(Array.isArray)?.length??d.length;let f=e.editSemantic({property:`guide.legend.${t}.scale`,value:n.scale}).editSemantic({property:`guide.legend.${t}.title`,value:n.title})._withLegendConfig(t,n);f=u(f,`${s}Symbols`,{length:c,...o}),f=u(f,`${s}Labels`,{length:d.length,x:i.labelX,y:i.itemY,text:d}),f=fe(f,`${s}Background`,i.background,n.border),f=u(f,`${s}Symbols`,Object.fromEntries(Object.entries(r).filter(([,j])=>j!==void 0))),f=B(f,`${s}Labels`,l);const E=i.config;return E.titleVisible===!1?f:(f=u(f,`${s}Title`,{x:i.title.x,y:i.title.y,text:E.title}),B(f,`${s}Title`,a,{align:i.title.align}))}function Me(e,t,n,i,o,r){const d=`${t}Legend`;let l=e.editSemantic({property:`guide.legend.${t}.scale`,value:n.scale}).editSemantic({property:`guide.legend.${t}.title`,value:n.title})._withLegendConfig(t,n);return n.border!==!1&&(l=l.createGraphics({id:`${d}Background`,type:"rect",...r})),l=l.createGraphics({id:`${d}Symbols`,type:o,length:i,...r}).createGraphics({id:`${d}Labels`,type:"text",length:i,...r}),n.titleVisible!==!1&&(l=l.createGraphics({id:`${d}Title`,type:"text",...r})),l}export{de as ITEM_LEGEND_LABELS,ze as ITEM_LEGEND_OPTIONS,se as ITEM_LEGEND_TITLE_STYLE,De as assertLegendBoundsInsideCanvas,Me as createItemLegendGraphics,u as editGraphicProperties,fe as editLegendBackground,We as formatContinuousValues,Re as materializeItemLegend,Ce as normalizeContinuousLegend,N as normalizeInitialLegendTitle,Ne as normalizeItemLegendConfig,ce as normalizeItemLegendLayout,F as normalizeLegendBorder,w as normalizeLegendTextOptions,C as normalizeLegendTitleOptions,Be as requireResolvedLegendScale,je as resolveContinuousBounds,Pe as resolveContinuousColorLayer,Fe as resolveContinuousLegendLayer,Ue as resolveLegendBackgroundFromBounds,ke as resolveLegendTextBounds,Ae as sampleContinuousValues,P as selectLegendLayer,B as styleContinuousText,g as validateNonNegative,y as validatePositive};

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

@@ -1,6 +1,10 @@
+import { normalizeColorSymbols, resolveColorSymbolsLayout, materializeColorSymbols } from "./colorSymbols.js";
+import { alignLegendTitle, resolveLegendTitleText } from "../../../../layout/legendText.js";
+import { intrinsicLegendConfig } from "../../../../materialization/legendGroups.js";
+import { mapContinuousScaleValues, transformedTicks } from "../../../../grammar/scales/index.js";
 import { action, closedAction } from "../../../../core/action.js";
 import { isPlainObject } from "../../../../core/immutable.js";
-import { validateKeys } from "../../../../core/validation.js";
+import { normalizeLegendGradient, DEFAULT_LEGEND_GRADIENT } from "../../../../grammar/legendGradient.js";
 import { mapScaleConsumerValues } from "../../../../materialization/scales/map.js";
 import { inverseLerp, interpolateNumber } from "../../../../grammar/numeric.js";
 import { DEFAULT_COLORS } from "../../../../theme/defaults.js";
@@ -16,31 +20,32 @@ import {
   resolveLegendBackgroundFromBounds,
   resolveLegendTextBounds,
   sampleContinuousValues,
-  styleContinuousText,
-  validatePositive
+  styleContinuousText
 } 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 });
+export const DEFAULT_GRADIENT_SIZE = DEFAULT_LEGEND_GRADIENT;
 
-const GRADIENT_OPTIONS = Object.freeze(["length", "thickness"]);
-
-export function resolveGradientLayout(program, config, scale, label = "Gradient legend") {
+export function resolveGradientLayout(program, config, scale, label = "Gradient legend", stripStrokeWidth = 0) {
+  if (config.representation === "symbols") return resolveColorSymbolsLayout(program, config, scale);
+  config = intrinsicLegendConfig(program, config);
   const { plot, canvas } = resolveContinuousBounds(program);
   const vertical = ["right", "left"].includes(config.position);
   const length = config.gradient.length;
   const thickness = config.gradient.thickness;
+  const titleText = config.titleVisible === false ? { height: 0, extraHeight: 0 }
+    : resolveLegendTitleText(config.title, config.titleStyle, program.materializationConfigs.textMetrics);
   const titleGap = config.blockGap ?? 12;
   let x;
   let y;
   if (config.position === "right") {
     x = plot.x + plot.width + config.offset;
-    y = plot.y + 46 + titleGap - 12;
+    y = plot.y + 46 + titleGap - 12 + titleText.extraHeight / 2;
   } else if (config.position === "left") {
     x = plot.x - config.offset - thickness;
-    y = plot.y + 46 + titleGap - 12;
+    y = plot.y + 46 + titleGap - 12 + titleText.extraHeight / 2;
   } else {
     x = config.align === "left" ? plot.x
       : config.align === "right" ? plot.x + plot.width - length
@@ -49,16 +54,21 @@ export function resolveGradientLayout(program, config, scale, label = "Gradient
       ? plot.y - config.offset - thickness - config.labels.offset -
         config.labels.fontSize
       : plot.y + plot.height + config.offset +
-        (config.titleVisible === false ? 0 : config.titleStyle.fontSize + titleGap);
+        (config.titleVisible === false ? 0 : titleText.height + titleGap);
   }
-  const title = vertical
+  let title = vertical
     ? { x, y: plot.y + 20, align: "left" }
     : {
         x: x + length / 2,
-        y: y - titleGap - config.titleStyle.fontSize / 2,
+        y: y - titleGap - titleText.height / 2,
         align: "center"
       };
-  const values = [...sampleContinuousValues(scale.domain, config.count)];
+  const transformed = ["log", "sqrt", "symlog"].includes(scale.type);
+  const values = transformed
+    ? transformedTicks(scale.type, scale.domain, config.count,
+        scale.type === "log" ? {base: scale.base}
+          : scale.type === "symlog" ? {constant: scale.constant} : {})
+    : [...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);
@@ -69,7 +79,8 @@ export function resolveGradientLayout(program, config, scale, label = "Gradient
     config.fieldType,
     config.labels.format
   );
-  const fractions = values.map((value, index) => scale.midpoint === undefined
+  const fractions = transformed ? mapContinuousScaleValues(values, {...scale, range: [0, 1]})
+    : values.map((value, index) => scale.midpoint === undefined
     ? index / (values.length - 1)
     : inverseLerp(value, ...scale.domain));
   const labelOffset = config.labels.offset;
@@ -114,11 +125,15 @@ export function resolveGradientLayout(program, config, scale, label = "Gradient
   const labelBounds = labels.map((label, index) =>
     resolveLegendTextBounds(label, texts[index], config.labels, program.materializationConfigs.textMetrics)
   );
+  if (config.titleVisible !== false) title = alignLegendTitle(title, config.title, config.titleStyle,
+    [{ left: stripBounds.left - stripStrokeWidth / 2, right: stripBounds.right + stripStrokeWidth / 2,
+      top: stripBounds.top - stripStrokeWidth / 2, bottom: stripBounds.bottom + stripStrokeWidth / 2 },
+      ...tickBounds, ...labelBounds], program.materializationConfigs.textMetrics);
   const titleBounds = config.titleVisible === false ? undefined : resolveLegendTextBounds(
     title,
     config.title,
     config.titleStyle
-  , program.materializationConfigs.textMetrics);
+  , program.materializationConfigs.textMetrics, { hardBreaks: true });
   const occupiedBounds = [stripBounds, ...tickBounds, ...labelBounds,
     ...(config.titleVisible === false ? [] : [titleBounds])];
   assertLegendBoundsInsideCanvas(
@@ -173,14 +188,15 @@ export function materializeGradientLegend(program, resolved, appearance) {
   const prefix = `${channel}Gradient`;
   const { scale, encoding, config: currentConfig } = resolved;
   const config = resolveEffectiveLegendBlockConfig(program, kind, currentConfig);
+  if (!stroke && config.representation === "symbols") return materializeColorSymbols(program, resolved, config);
   const layout = resolveGradientLayout(program, config, scale,
-    stroke ? "Stroke gradient legend" : "Gradient legend");
+    stroke ? "Stroke gradient legend" : "Gradient legend", appearance?.strokeWidth ?? 0);
   const stripCount = 60;
   const stripSize = layout.length / stripCount;
   const strips = Array.from({ length: stripCount }, (_, index) => {
     const fraction = (index + 0.5) / stripCount;
     const position = layout.vertical ? 1 - fraction : fraction;
-    const samplingScale = scale.midpoint === undefined ? { ...scale, domain: [0, 1] } : scale;
+    const samplingScale = scale.midpoint === undefined ? { ...scale, type: "sequential", domain: [0, 1] } : scale;
     const value = scale.midpoint === undefined ? position : interpolateNumber(...scale.domain, position);
     const [color] = mapScaleConsumerValues([value], samplingScale, channel);
     return {
@@ -204,6 +220,9 @@ export function materializeGradientLegend(program, resolved, appearance) {
   for (const property of ["x", "y", "width", "height", "fill", "stroke", "strokeWidth"]) {
     next = next.editGraphics({ target: `${prefix}Strips`, property, value: strips.map(strip => strip[property]) });
   }
+  if (config.gradient.opacity !== undefined) {
+    next = next.editGraphics({ target: `${prefix}Strips`, property: "opacity", value: config.gradient.opacity });
+  }
   next = next.editGraphics({ target: `${prefix}Ticks`, property: "length", value: layout.ticks.length });
   for (const property of ["x1", "y1", "x2", "y2"]) {
     next = next.editGraphics({ target: `${prefix}Ticks`, property, value: layout.ticks.map(tick => tick[property]) });
@@ -235,7 +254,10 @@ export const rematerializeGradientLegend = /* @__PURE__ */ closedAction(
 
 
 export function resolveGradientLegendCreation(program, args = {}, channel = "color") {
-  const config = normalizeContinuousLegend(args, "gradient");
+  const { representation, ...options } = args;
+  if (representation !== undefined && !["gradient", "symbols"].includes(representation)) throw new Error("Legend representation must be gradient or symbols.");
+  if (channel !== "color" && representation !== undefined) throw new Error("Legend representation requires continuous color.");
+  const config = representation === "symbols" ? normalizeColorSymbols(options) : normalizeContinuousLegend(options, "gradient");
   if (args.channels !== undefined && (
     !Array.isArray(args.channels) ||
     args.channels.length !== 1 ||
@@ -246,18 +268,7 @@ export function resolveGradientLegendCreation(program, args = {}, channel = "col
   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");
+  if (config.representation !== "symbols") config.gradient = normalizeLegendGradient(args.gradient);
   const resolved = resolveGradientConfig(program, config, channel);
   return resolved;
 }
@@ -284,7 +295,9 @@ export function createGradientLegendFromConfig(program, config, channel = "color
       ...resolveLegendGraphicPlacement(next)
     });
   }
-  next = next
+  if (resolved.config.representation === "symbols") {
+    next = next.createGraphics({ id: `${prefix}Symbols`, type: "circle", length: 0, ...resolveLegendGraphicPlacement(next) });
+  } else next = next
     .createGraphics({
       id: `${prefix}Strips`,
       type: "rect",
@@ -298,8 +311,8 @@ export function createGradientLegendFromConfig(program, config, channel = "color
       type: "line",
       length: 0,
       ...resolveLegendGraphicPlacement(next)
-    })
-    .createGraphics({
+    });
+  next = next.createGraphics({
       id: `${prefix}Labels`,
       type: "text",
       length: 0,
@@ -323,7 +336,7 @@ export const createGradientLegend = /* @__PURE__ */ action(
   function (args = {}) {
     const resolved = resolveGradientLegendCreation(this, args);
     resolveGradientLayout(this, resolved.config, resolved.scale);
-    if (this.graphicSpec.objects.colorGradientStrips !== undefined) {
+    if (this.guideConfigs.legend?.gradient !== undefined) {
       throw new Error(
         "createGradientLegend requires a missing gradient legend."
       );