ggaction 0.0.23 → 0.0.24

package/src/actions/guides/axes/labels.js

@@ -1,537 +1 @@
-import { axisTitleAllowsLabelOverlap } from "../../../grammar/axisTextPlacement.js";
-import { selectCartesianAxis, axisTargetArgs } from "../../../selectors/axes.js";
-import { axisGraphicIds } from "../../../materialization/guides/resources.js";
-import { axisThemeTypography } from "../../theme/state.js";
-import { validateAxisTextPlacement } from "../../../grammar/axisTextPlacement.js";
-import { canvasOverflowError } from "../../../layout/canvas.js";
-import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
-import { action } from "../../../core/action.js";
-import { validateUserId } from "../../../core/identifiers.js";
-import {
-  sameOrderedValues,
-  validateGeneratedItemLimit,
-  validateTextStyle,
-  validateOptionObject,
-  validateNonNegativeFinite,
-  validatePositiveFinite
-} from "../../../core/validation.js";
-import { resolveCartesianAxisFrameBounds } from "../../../materialization/coordinateBounds.js";
-import {
-  isTransformedScaleType,
-  mapContinuousScaleValues,
-  formatTransformedTick,
-  mapOrdinalPositionValues
-} from "../../../grammar/scales/index.js";
-import { formatTimeTick, formatTimeTicks, validateTickRounding } from "../../../grammar/ticks.js";
-import { resolveRotation } from "../../../grammar/rotation.js";
-import { valuesFromTickConfig } from "../tickValues.js";
-import { AXIS_LABEL_FONT_SIZES, DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
-  "../../../theme/defaults.js";
-import {
-  defaultAxisPosition,
-  formatAxisValue,
-  formatNumericAxisTicks,
-  resolveAxisLabelGeometry,
-  validateAxisFormat,
-  validateAxisPosition
-} from "./policy.js";
-import { findCanvasGraphic, resolvePlotGraphicPlacement } from
-  "../../../materialization/graphicHierarchy.js";
-import {
-  resolveTextBounds,
-  textBoundsFitCanvas,
-  textBoundsIntersect
-} from "../../../core/textMetrics.js";
-import { resolveConcreteGraphicBounds } from
-  "../../../grammar/schemas/graphicBounds.js";
-import { wrapText } from "../../../layout/text.js";
-import {
-  normalizeDisplayLabelMap,
-  normalizeDisplayColorMap,
-  resolveDisplayLabelColor,
-  resolveDisplayLabel
-} from "../../../grammar/displayLabels.js";
-
-const OPTIONS = [
-  "target", "scale", "position", "count", "values", "rounding", "offset", "format", "color",
-  "fontSize", "fontFamily", "fontWeight", "rotation", "maxWidth", "wrap",
-  "lineHeight", "overlap", "labelMap", "alongOffset", "flush", "colorMap", "align"
-];
-
-const DEFAULTS = {
-  count: 5,
-  color: DEFAULT_COLORS.text,
-  fontSize: AXIS_LABEL_FONT_SIZES.cartesian,
-  fontFamily: DEFAULT_FONT_FAMILY,
-  fontWeight: "normal",
-  rotation: 0,
-  overlap: "error"
-};
-
-function normalizeLabelLayout(config, args, operation) {
-  const next = { ...config };
-  next.rotation = Object.hasOwn(args, "rotation")
-    ? resolveRotation(args.rotation, `${operation} rotation`)
-    : next.rotation ?? 0;
-  next.overlap ??= "error";
-  if (args.maxWidth === false) {
-    if (Object.hasOwn(args, "wrap") || Object.hasOwn(args, "lineHeight")) {
-      throw new Error(`${operation} cannot combine maxWidth false with wrap or lineHeight.`);
-    }
-    delete next.maxWidth;
-    delete next.wrap;
-    delete next.lineHeight;
-  } else if (next.maxWidth !== undefined) {
-    next.wrap ??= "word";
-  }
-  return next;
-}
-
-export { validateTextStyle as validateAxisTextStyle };
-
-function validateOptions(args, operation, create) {
-  validateTickRounding(args.rounding, !Object.hasOwn(args, "rounding"));
-  if (Object.hasOwn(args, "rounding") && Object.hasOwn(args, "values")) {
-    throw new Error(`${operation} cannot use rounding and values together.`);
-  }
-  validateAxisTextPlacement(args);
-  validateOptionObject(
-    args,
-    create ? OPTIONS : OPTIONS.filter(key => key !== "scale"),
-    operation
-  );
-  if (Object.hasOwn(args, "flush") && typeof args.flush !== "boolean") throw new TypeError("Label flush must be a boolean.");
-  if (Object.hasOwn(args, "alongOffset") && !Number.isFinite(args.alongOffset)) throw new TypeError("Label alongOffset must be a finite number.");
-  if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) {
-    throw new Error(`${operation} cannot use count and values together.`);
-  }
-}
-
-function validateConfig(channel, config) {
-  validateAxisTextPlacement(config);
-  validateAxisPosition(channel, config.position);
-  if (config.mode === "count") {
-    if (!Number.isInteger(config.count) || config.count <= 0) throw new RangeError("Label count must be a positive integer.");
-    validateGeneratedItemLimit(config.count, "Label count");
-  }
-  if (
-    config.mode === "values" &&
-    (!Array.isArray(config.values) || !config.values.every(value =>
-      typeof value === "string" ||
-      typeof value === "boolean" ||
-      (typeof value === "number" && Number.isFinite(value))
-    ))
-  ) throw new TypeError("Label values must be nominal values or finite numbers.");
-  if (config.mode === "values") {
-    validateGeneratedItemLimit(config.values.length, "Label value count");
-  }
-  if (config.alongOffset !== undefined && !Number.isFinite(config.alongOffset)) throw new TypeError("Label alongOffset must be a finite number.");
-  validateNonNegativeFinite(config.offset, "Label offset");
-  validateTextStyle(config, "Label");
-  validateAxisFormat(config.format);
-  if (config.flush === true && config.rotation !== 0) throw new Error("Label flush requires unrotated Cartesian labels.");
-  if (!Number.isFinite(config.rotation)) {
-    throw new TypeError("Label rotation must resolve to finite radians.");
-  }
-  if (config.maxWidth !== undefined) {
-    validatePositiveFinite(config.maxWidth, "Label maxWidth");
-    if (!["word", "character"].includes(config.wrap)) {
-      throw new Error(`Unsupported axis label wrap "${config.wrap}".`);
-    }
-  } else if (config.wrap !== undefined || config.lineHeight !== undefined) {
-    throw new Error("Axis label wrap and lineHeight require maxWidth.");
-  }
-  if (config.lineHeight !== undefined && (
-    !Number.isFinite(config.lineHeight) || config.lineHeight < config.fontSize
-  )) {
-    throw new RangeError("Axis label lineHeight must cover fontSize.");
-  }
-  if (!["error", "allow"].includes(config.overlap)) {
-    throw new Error(`Unsupported axis label overlap policy "${config.overlap}".`);
-  }
-}
-
-function normalizeAxisLabelMaps(program, config, args, operation) {
-  const next = { ...config };
-  for (const [property, normalize] of [
-    ["labelMap", normalizeDisplayLabelMap],
-    ["colorMap", normalizeDisplayColorMap]
-  ]) {
-    if (!Object.hasOwn(args, property)) continue;
-    if (args[property] === "auto") delete next[property];
-    else next[property] = normalize(args[property], `${operation} ${property}`);
-  }
-  validateAxisLabelMapScale(next, program.resolvedScales[config.scale], operation);
-  return next;
-}
-
-function validateAxisLabelMapScale(config, scale, operation = "Axis") {
-  if (["ordinal", "band", "point"].includes(scale?.type)) return;
-  for (const property of ["labelMap", "colorMap"]) {
-    if (config[property] !== undefined &&
-        !config[property].every(entry => Number.isFinite(entry.value))) {
-      throw new TypeError(`${operation} continuous ${property} values must be finite numbers or timestamps.`);
-    }
-  }
-}
-
-function assertTickCompatibility(ticks, config, operation) {
-  if (!ticks) return;
-  if (ticks.scale !== config.scale || ticks.mode !== config.mode) throw new Error(`${operation} conflicts with axis ticks.`);
-  if (config.mode === "count" && ticks.count !== config.count) throw new Error(`${operation} conflicts with axis ticks.`);
-  if (config.mode === "count" && (ticks.rounding ?? "ceiling") !== (config.rounding ?? "ceiling")) {
-    throw new Error(`${operation} conflicts with axis tick rounding.`);
-  }
-  if (config.mode === "values" && !sameOrderedValues(ticks.values, config.values)) throw new Error(`${operation} conflicts with axis ticks.`);
-}
-
-function expandWrappedLabels(resolved, text, config, channel, profile) {
-  if (config.maxWidth === undefined) {
-    return {
-      ...resolved,
-      text,
-      groups: text.map((_, index) => index)
-    };
-  }
-  const style = {
-    fontSize: config.fontSize,
-    fontFamily: config.fontFamily,
-    fontWeight: config.fontWeight
-  };
-  const lineHeight = config.lineHeight ?? config.fontSize * 1.2;
-  const expanded = { text: [], x: [], y: [], groups: [] };
-  for (let index = 0; index < text.length; index += 1) {
-    const lines = wrapText(text[index], {
-      maxWidth: config.maxWidth,
-      mode: config.wrap,
-      style, profile
-    });
-    validateGeneratedItemLimit(
-      expanded.text.length + lines.length,
-      "Axis label line count"
-    );
-    const baseX = Array.isArray(resolved.x) ? resolved.x[index] : resolved.x;
-    const baseY = Array.isArray(resolved.y) ? resolved.y[index] : resolved.y;
-    for (let line = 0; line < lines.length; line += 1) {
-      expanded.text.push(lines[line]);
-      expanded.x.push(baseX);
-      expanded.y.push(channel === "x"
-        ? baseY + (resolved.textBaseline === "top" ? line : -line) * lineHeight
-        : baseY + (line - (lines.length - 1) / 2) * lineHeight);
-      expanded.groups.push(index);
-    }
-  }
-  return { ...resolved, ...expanded };
-}
-
-function unionLabelBounds(records) {
-  const byGroup = new Map();
-  for (const { bounds, group } of records) {
-    const previous = byGroup.get(group);
-    byGroup.set(group, previous === undefined ? bounds : {
-      left: Math.min(previous.left, bounds.left),
-      right: Math.max(previous.right, bounds.right),
-      top: Math.min(previous.top, bounds.top),
-      bottom: Math.max(previous.bottom, bounds.bottom)
-    });
-  }
-  return [...byGroup.values()];
-}
-
-function resolve(program, channel, config, axisId = channel) {
-  const scale = program.resolvedScales[config.scale];
-  const bounds = resolveCartesianAxisFrameBounds(program, channel, config.position, config.scale, axisId);
-  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
-  validateAxisLabelMapScale(config, scale);
-  if ((
-    !["linear", "time", "ordinal", "band", "point"].includes(scale?.type) &&
-    !isTransformedScaleType(scale?.type)
-  ) || !bounds) throw new Error("Axis labels require a supported resolved scale and Canvas bounds.");
-  if (discrete && config.mode !== "values") throw new Error("Discrete axis labels require explicit or inferred values, not count.");
-  let values = valuesFromTickConfig(program, config);
-  validateGeneratedItemLimit(values.length, "Label value count");
-  if (discrete) {
-    const domainValues = new Set(scale.domain);
-    if (!values.every(value => domainValues.has(value))) throw new RangeError("Label values must be inside the scale domain.");
-  } else {
-    const low = Math.min(...scale.domain), high = Math.max(...scale.domain);
-    if (!values.every(value => value >= low && value <= high)) throw new RangeError("Label values must be inside the scale domain.");
-  }
-  let positions = discrete
-    ? mapOrdinalPositionValues(values, scale)
-    : mapContinuousScaleValues(values, scale);
-  const fallback = value => formatAxisValue(
-        value,
-        scale.type,
-        config.format,
-        item => scale.type === "time"
-          ? formatTimeTick(item, scale.domain)
-          : isTransformedScaleType(scale.type)
-            ? formatTransformedTick(scale.type, item)
-            : String(item)
-      );
-  const automaticLabels = config.format === "ticks"
-    ? formatNumericAxisTicks(values, scale.type)
-    : scale.type === "time" && config.format === "auto"
-      ? formatTimeTicks(values, scale.domain)
-      : undefined;
-  let text = values.map((value, index) =>
-    resolveDisplayLabel(value, config.labelMap, raw =>
-      automaticLabels?.[index] ?? fallback(raw)));
-  // Empty mapped text suppresses the label, never its raw tick or scale value.
-  // Filter all aligned arrays before wrapping so group/color indices stay dense.
-  if (text.includes("")) {
-    const visible = text.map((value, index) => value === "" ? -1 : index)
-      .filter(index => index !== -1);
-    values = visible.map(index => values[index]);
-    positions = visible.map(index => positions[index]);
-    text = visible.map(index => text[index]);
-  }
-  const geometry = {
-    values,
-    ...resolveAxisLabelGeometry({
-      bounds,
-      channel,
-      position: config.position,
-      positions: positions.map(value => value + (config.alongOffset ?? 0)),
-      offset: config.offset
-    })
-  };
-  const resolved = expandWrappedLabels(geometry, text, config, channel, program.materializationConfigs.textMetrics);
-  if (channel === "x" && Math.abs(Math.sin(config.rotation)) > 1e-9) {
-    const outward = config.position === "bottom" ? 1 : -1;
-    resolved.textAlign = Math.sin(config.rotation) * outward < 0 ? "right" : "left";
-    resolved.textBaseline = "middle";
-  }
-  const canvas = findCanvasGraphic(program)?.properties;
-  const measuredBounds = () => resolved.text.map((value, index) => resolveTextBounds({
-    x: Array.isArray(resolved.x) ? resolved.x[index] : resolved.x,
-    y: Array.isArray(resolved.y) ? resolved.y[index] : resolved.y,
-    text: value,
-    fontSize: config.fontSize,
-    fontFamily: config.fontFamily,
-    fontWeight: config.fontWeight,
-    textAlign: resolved.textAlign,
-    textBaseline: resolved.textBaseline,
-    rotation: config.rotation
-  }, program.materializationConfigs.textMetrics));
-  let labelBounds = measuredBounds();
-  if (program.materializationConfigs.canvas?.plot !== undefined || config.rotation !== 0) {
-    const horizontal = channel === "x";
-    const near = ["bottom", "right"].includes(config.position);
-    const edge = horizontal ? bounds.y + (near ? bounds.height : 0)
-      : bounds.x + (near ? bounds.width : 0);
-    const boundKey = horizontal ? (near ? "top" : "bottom") : (near ? "left" : "right");
-    const grouped = unionLabelBounds(labelBounds.map((bounds, index) => ({ bounds, group: resolved.groups[index] })));
-    const shifts = grouped.map(item => edge + (near ? config.offset : -config.offset) - item[boundKey]);
-    const axis = horizontal ? "y" : "x";
-    const positions = resolved[axis];
-    resolved[axis] = resolved.text.map((_, index) =>
-      (Array.isArray(positions) ? positions[index] : positions) + shifts[resolved.groups[index]]);
-    labelBounds = labelBounds.map((item, index) => {
-      const delta = shifts[resolved.groups[index]];
-      return horizontal ? { ...item, top: item.top + delta, bottom: item.bottom + delta }
-        : { ...item, left: item.left + delta, right: item.right + delta };
-    });
-  }
-  if (config.flush === true) {
-    const along = channel === "x" ? "x" : "y";
-    const lowKey = channel === "x" ? "left" : "top";
-    const highKey = channel === "x" ? "right" : "bottom";
-    const low = Math.min(...scale.range) + (config.alongOffset ?? 0);
-    const high = Math.max(...scale.range) + (config.alongOffset ?? 0);
-    const grouped = unionLabelBounds(labelBounds.map((bounds, index) => ({ bounds, group: resolved.groups[index] })));
-    const shifts = grouped.map(item => {
-      if (item[highKey] - item[lowKey] > high - low + 1e-9) {
-        throw new Error(`The ${channel}-axis label cannot flush inside the scale span.`);
-      }
-      return item[lowKey] < low ? low - item[lowKey]
-        : item[highKey] > high ? high - item[highKey] : 0;
-    });
-    const positions = resolved[along];
-    resolved[along] = resolved.text.map((_, index) =>
-      (Array.isArray(positions) ? positions[index] : positions) + shifts[resolved.groups[index]]);
-    labelBounds = labelBounds.map((item, index) => {
-      const delta = shifts[resolved.groups[index]];
-      return { ...item, [lowKey]: item[lowKey] + delta, [highKey]: item[highKey] + delta };
-    });
-  }
-  if (config.align !== undefined) {
-    resolved.textAlign = config.align;
-    labelBounds = measuredBounds();
-  }
-  const rotatedOverlap = config.rotation !== 0;
-  const collisionBounds = rotatedOverlap ? resolved.text.map((text, index) => {
-    const x = Array.isArray(resolved.x) ? resolved.x[index] : resolved.x;
-    const y = Array.isArray(resolved.y) ? resolved.y[index] : resolved.y;
-    const cosine = Math.cos(config.rotation), sine = Math.sin(config.rotation);
-    return resolveTextBounds({
-      x: x * cosine + y * sine, y: -x * sine + y * cosine, text,
-      fontSize: config.fontSize, fontFamily: config.fontFamily, fontWeight: config.fontWeight,
-      textAlign: resolved.textAlign, textBaseline: resolved.textBaseline
-    }, program.materializationConfigs.textMetrics);
-  }) : labelBounds;
-  const groupedBounds = unionLabelBounds(collisionBounds.map((bounds, index) => ({
-    bounds,
-    group: resolved.groups[index]
-  })));
-  const orderedBounds = groupedBounds.sort((left, right) => channel === "x"
-    ? left.left - right.left
-    : left.top - right.top);
-  if (!canvas || !labelBounds.every(item => textBoundsFitCanvas(item, canvas))) {
-    throw canvasOverflowError(`The ${channel}-axis labels do not fit the Canvas margin.`, labelBounds, canvas);
-  }
-  if (config.overlap === "error" && orderedBounds.some((item, index) => rotatedOverlap
-    ? orderedBounds.slice(0, index).some(previous => textBoundsIntersect(previous, item))
-    : index > 0 && textBoundsIntersect(orderedBounds[index - 1], item))) {
-    throw new Error(`The ${channel}-axis labels overlap each other.`);
-  }
-  const title = program.graphicSpec.objects[axisGraphicIds(channel, axisId)[3]]
-    ? resolveConcreteGraphicBounds(program.graphicSpec, axisGraphicIds(channel, axisId)[3], program.materializationConfigs.textMetrics)
-    : undefined;
-  if (title && !axisTitleAllowsLabelOverlap(program.guideConfigs.axis?.[axisId]?.title) &&
-    program.guideConfigs.axis?.[axisId]?.title?.inferredOffset !== true &&
-    labelBounds.some(item => textBoundsIntersect(item, title))) {
-    throw new Error(`The ${channel}-axis labels overlap the axis title.`);
-  }
-  return resolved;
-}
-
-function makeEdit(channel) {
-  const op = channel === "x" ? "editXAxisLabels" : "editYAxisLabels";
-  return action({ op, description: `Edit concrete ${channel}-axis labels.` }, withGuideLayoutValidation(function (args = {}) {
-    validateOptions(args, op, false);
-    const selected = selectCartesianAxis(this, channel, args, { create: false });
-    const axisId = selected.id; args = selected.options;
-    const id = axisGraphicIds(channel, axisId)[2];
-    if (this.graphicSpec.objects[id]?.type !== "text") throw new Error(`${op} requires existing axis labels.`);
-    const previous = this.guideConfigs.axis?.[axisId]?.labels;
-    if (!previous) throw new Error(`${op} requires label configuration.`);
-    const explicitMode = Object.hasOwn(args, "values") || Object.hasOwn(args, "count");
-    const ticks = this.guideConfigs.axis?.[axisId]?.ticks;
-    const inferredValues = !explicitMode && previous.inferredValues === true &&
-      ticks?.mode === "values"
-      ? ticks.values
-      : undefined;
-    const mode = Object.hasOwn(args, "values") || inferredValues !== undefined
-      ? "values"
-      : Object.hasOwn(args, "count") ? "count" : previous.mode;
-    let config = normalizeLabelLayout({
-      ...previous,
-      ...args,
-      ...(inferredValues === undefined ? {} : { values: inferredValues }),
-      ...(explicitMode ? { inferredValues: false } : {}),
-      mode
-    }, args, op);
-    config = normalizeAxisLabelMaps(this, config, args, op);
-    if (mode === "values") {
-      delete config.count;
-      if (!Object.hasOwn(args, "rounding")) delete config.rounding;
-    } else delete config.values;
-    validateConfig(channel, config);
-    assertTickCompatibility(this.guideConfigs.axis?.[axisId]?.ticks, config, op);
-    const resolved = resolve(this, channel, config, axisId);
-    let next = this._withGuideConfig(axisId, "labels", config);
-    const properties = {
-      length: resolved.text.length,
-      x: resolved.x,
-      y: resolved.y,
-      text: resolved.text,
-      fill: config.colorMap === undefined ? config.color
-        : resolved.text.map((_, index) => resolveDisplayLabelColor(
-          resolved.values[resolved.groups[index]], config.colorMap, config.color)),
-      fontSize: config.fontSize,
-      fontFamily: config.fontFamily,
-      fontWeight: config.fontWeight,
-      textAlign: resolved.textAlign,
-      textBaseline: resolved.textBaseline
-    };
-    if (config.rotation !== 0 || this.graphicSpec.objects[id].items.some(
-      item => Object.hasOwn(item.properties, "rotation")
-    )) properties.rotation = config.rotation;
-    for (const [property, value] of Object.entries(properties)) {
-      next = next.editGraphics({ target: id, property, value });
-    }
-    const titleConfig = next.guideConfigs.axis?.[axisId]?.title;
-    if (titleConfig?.inferredOffset === true) {
-      const editTitle = channel === "x" ? "editXAxisTitle" : "editYAxisTitle";
-      next = next[editTitle](axisId === channel ? undefined : axisTargetArgs(axisId, channel));
-    }
-    return next;
-  }));
-}
-
-const editXAxisLabels = /* @__PURE__ */ makeEdit("x");
-const editYAxisLabels = /* @__PURE__ */ makeEdit("y");
-
-function makeCreate(channel) {
-  const op = channel === "x" ? "createXAxisLabels" : "createYAxisLabels";
-  const edit = channel === "x" ? "editXAxisLabels" : "editYAxisLabels";
-  return action({ op, description: `Create concrete ${channel}-axis labels.` }, withGuideLayoutValidation(function (args = {}) {
-    validateOptions(args, op, true);
-    const selected = selectCartesianAxis(this, channel, args, { create: true });
-    const axisId = selected.id; args = selected.options;
-    const scale = validateUserId(args.scale ?? channel, "Scale id");
-    const guideScale = this.semanticSpec.guides.axis?.[axisId]?.scale;
-    if (guideScale && guideScale !== scale) throw new Error(`${op} conflicts with the existing axis scale.`);
-    const id = axisGraphicIds(channel, axisId)[2];
-    if (this.graphicSpec.objects[id]) throw new Error(`${op} requires missing axis labels.`);
-    const ticks = this.guideConfigs.axis?.[axisId]?.ticks;
-    const hasValues = Object.hasOwn(args, "values");
-    const hasCount = Object.hasOwn(args, "count");
-    const resolvedScale = this.resolvedScales[scale];
-    const inferredDiscreteValues = !hasValues && !hasCount && ticks === undefined &&
-      ["ordinal", "band", "point"].includes(resolvedScale?.type)
-      ? resolvedScale.domain
-      : undefined;
-    const mode = hasValues || inferredDiscreteValues !== undefined
-      ? "values"
-      : hasCount ? "count" : ticks?.mode ?? "count";
-    let config = normalizeLabelLayout({
-      scale,
-      position: defaultAxisPosition(channel),
-      offset: channel === "x" ? 18 : 12,
-      format: "auto",
-      color: DEFAULTS.color,
-      fontSize: DEFAULTS.fontSize,
-      fontFamily: DEFAULTS.fontFamily,
-      fontWeight: DEFAULTS.fontWeight,
-      ...axisThemeTypography(this.materializationConfigs.theme, "labels"),
-      rotation: DEFAULTS.rotation,
-      overlap: DEFAULTS.overlap,
-      ...(ticks?.rounding === undefined ? {} : { rounding: ticks.rounding }),
-      ...args,
-      inferredValues: !hasValues && !hasCount &&
-        (ticks?.inferredValues === true || inferredDiscreteValues !== undefined),
-      mode
-    }, args, op);
-    config = normalizeAxisLabelMaps(this, config, args, op);
-    if (mode === "values") {
-      config.values ??= ticks?.values ?? inferredDiscreteValues;
-      if (!Object.hasOwn(args, "rounding")) delete config.rounding;
-    } else {
-      config.count ??= ticks?.count ?? DEFAULTS.count;
-    }
-    validateConfig(channel, config);
-    assertTickCompatibility(ticks, config, op);
-    resolve(this, channel, config, axisId);
-    return this.editSemantic({ property: `guide.axis.${axisId}.scale`, value: scale })
-      .createGraphics({
-        id,
-        type: "text",
-        length: 0,
-        ...resolvePlotGraphicPlacement(this)
-      })
-      ._withGuideConfig(axisId, "labels", config)[edit](axisId === channel ? undefined : axisTargetArgs(axisId, channel));
-  }));
-}
-
-const createXAxisLabels = /* @__PURE__ */ makeCreate("x");
-const createYAxisLabels = /* @__PURE__ */ makeCreate("y");
-
-export function registerAxisLabelActions(Class) {
-  Class.prototype.editXAxisLabels = editXAxisLabels;
-  Class.prototype.editYAxisLabels = editYAxisLabels;
-  Class.prototype.createXAxisLabels = createXAxisLabels;
-  Class.prototype.createYAxisLabels = createYAxisLabels;
-}
+import{axisTitleAllowsLabelOverlap as ie,axisTitleFollowsLabels as N}from"../../../grammar/axisTextPlacement.js";import{selectCartesianAxis as V,axisTargetArgs as G}from"../../../selectors/axes.js";import{axisGraphicIds as C,hasPendingAxisTitleRematerialization as se}from"../../../materialization/guides/resources.js";import{axisThemeTypography as re}from"../../theme/state.js";import{validateAxisLabelFlushThreshold as H,validateAxisTextPlacement as _}from"../../../grammar/axisTextPlacement.js";import{canvasOverflowError as ae}from"../../../layout/canvas.js";import{withGuideLayoutValidation as X}from"../../../materialization/guides/layout.js";import{action as Y}from"../../../core/action.js";import{validateUserId as ne}from"../../../core/identifiers.js";import{sameOrderedValues as le,validateGeneratedItemLimit as F,validateTextStyle as P,validateOptionObject as ue,validateNonNegativeFinite as de,validatePositiveFinite as fe}from"../../../core/validation.js";import{resolveCartesianAxisFrameBounds as pe}from"../../../materialization/coordinateBounds.js";import{isTransformedScaleType as R,mapContinuousScaleValues as he,formatTransformedTick as me,mapOrdinalPositionValues as ce}from"../../../grammar/scales/index.js";import{formatTimeTick as xe,formatTimeTicks as be,validateTickRounding as we}from"../../../grammar/ticks.js";import{resolveRotation as ye}from"../../../grammar/rotation.js";import{valuesFromTickConfig as ve}from"../tickValues.js";import{AXIS_LABEL_FONT_SIZES as Ae,DEFAULT_COLORS as Oe,DEFAULT_FONT_FAMILY as Le}from"../../../theme/defaults.js";import{defaultAxisPosition as Te,formatAxisValue as Se,formatNumericAxisTicks as Ee,resolveAxisLabelGeometry as ge,validateAxisFormat as Me,validateAxisPosition as Ce}from"./policy.js";import{findCanvasGraphic as Fe,resolvePlotGraphicPlacement as ze}from"../../../materialization/graphicHierarchy.js";import{resolveTextBounds as D,textBoundsFitCanvas as je,textBoundsIntersect as j}from"../../../core/textMetrics.js";import{resolveConcreteGraphicBounds as We}from"../../../grammar/schemas/graphicBounds.js";import{wrapText as $e}from"../../../layout/text.js";import{normalizeDisplayLabelMap as Be,normalizeDisplayColorMap as ke,resolveDisplayLabelColor as Ne,resolveDisplayLabel as Ve}from"../../../grammar/displayLabels.js";const q=["target","scale","position","count","values","rounding","offset","format","color","fontSize","fontFamily","fontWeight","rotation","maxWidth","wrap","lineHeight","overlap","labelMap","alongOffset","flush","flushThreshold","colorMap","align"],S={count:5,color:Oe.text,fontSize:Ae.cartesian,fontFamily:Le,fontWeight:"normal",rotation:0,overlap:"error"};function U(o,e,t){const s={...o};if(s.rotation=Object.hasOwn(e,"rotation")?ye(e.rotation,`${t} rotation`):s.rotation??0,s.overlap??="error",e.maxWidth===!1){if(Object.hasOwn(e,"wrap")||Object.hasOwn(e,"lineHeight"))throw new Error(`${t} cannot combine maxWidth false with wrap or lineHeight.`);delete s.maxWidth,delete s.wrap,delete s.lineHeight}else s.maxWidth!==void 0&&(s.wrap??="word");return s}function W(o,e,t){if(we(o.rounding,!Object.hasOwn(o,"rounding")),Object.hasOwn(o,"rounding")&&Object.hasOwn(o,"values"))throw new Error(`${e} cannot use rounding and values together.`);if(_(o),H(o.flushThreshold,{allowReset:!0}),ue(o,t?q:q.filter(s=>s!=="scale"),e),Object.hasOwn(o,"flush")&&typeof o.flush!="boolean")throw new TypeError("Label flush must be a boolean.");if(Object.hasOwn(o,"alongOffset")&&!Number.isFinite(o.alongOffset))throw new TypeError("Label alongOffset must be a finite number.");if(Object.hasOwn(o,"count")&&Object.hasOwn(o,"values"))throw new Error(`${e} cannot use count and values together.`)}function I(o,e){if(_(e),Ce(o,e.position),e.mode==="count"){if(!Number.isInteger(e.count)||e.count<=0)throw new RangeError("Label count must be a positive integer.");F(e.count,"Label count")}if(e.mode==="values"&&(!Array.isArray(e.values)||!e.values.every(t=>typeof t=="string"||typeof t=="boolean"||typeof t=="number"&&Number.isFinite(t))))throw new TypeError("Label values must be nominal values or finite numbers.");if(e.mode==="values"&&F(e.values.length,"Label value count"),e.alongOffset!==void 0&&!Number.isFinite(e.alongOffset))throw new TypeError("Label alongOffset must be a finite number.");if(de(e.offset,"Label offset"),P(e,"Label"),Me(e.format),H(e.flushThreshold),e.flush===!0&&e.rotation!==0)throw new Error("Label flush requires unrotated Cartesian labels.");if(!Number.isFinite(e.rotation))throw new TypeError("Label rotation must resolve to finite radians.");if(e.maxWidth!==void 0){if(fe(e.maxWidth,"Label maxWidth"),!["word","character"].includes(e.wrap))throw new Error(`Unsupported axis label wrap "${e.wrap}".`)}else if(e.wrap!==void 0||e.lineHeight!==void 0)throw new Error("Axis label wrap and lineHeight require maxWidth.");if(e.lineHeight!==void 0&&(!Number.isFinite(e.lineHeight)||e.lineHeight<e.fontSize))throw new RangeError("Axis label lineHeight must cover fontSize.");if(!["error","allow"].includes(e.overlap))throw new Error(`Unsupported axis label overlap policy "${e.overlap}".`)}function K(o,e,t,s){const i={...e};t.flushThreshold==="auto"&&delete i.flushThreshold;for(const[u,d]of[["labelMap",Be],["colorMap",ke]])Object.hasOwn(t,u)&&(t[u]==="auto"?delete i[u]:i[u]=d(t[u],`${s} ${u}`));return Z(i,o.resolvedScales[e.scale],s),i}function Z(o,e,t="Axis"){if(!["ordinal","band","point"].includes(e?.type)){for(const s of["labelMap","colorMap"])if(o[s]!==void 0&&!o[s].every(i=>Number.isFinite(i.value)))throw new TypeError(`${t} continuous ${s} values must be finite numbers or timestamps.`)}}function J(o,e,t){if(o){if(o.scale!==e.scale||o.mode!==e.mode)throw new Error(`${t} conflicts with axis ticks.`);if(e.mode==="count"&&o.count!==e.count)throw new Error(`${t} conflicts with axis ticks.`);if(e.mode==="count"&&(o.rounding??"ceiling")!==(e.rounding??"ceiling"))throw new Error(`${t} conflicts with axis tick rounding.`);if(e.mode==="values"&&!le(o.values,e.values))throw new Error(`${t} conflicts with axis ticks.`)}}function Ge(o,e,t,s,i){if(t.maxWidth===void 0)return{...o,text:e,groups:e.map((f,h)=>h)};const u={fontSize:t.fontSize,fontFamily:t.fontFamily,fontWeight:t.fontWeight},d=t.lineHeight??t.fontSize*1.2,l={text:[],x:[],y:[],groups:[]};for(let f=0;f<e.length;f+=1){const h=$e(e[f],{maxWidth:t.maxWidth,mode:t.wrap,style:u,profile:i});F(l.text.length+h.length,"Axis label line count");const x=Array.isArray(o.x)?o.x[f]:o.x,c=Array.isArray(o.y)?o.y[f]:o.y;for(let b=0;b<h.length;b+=1)l.text.push(h[b]),l.x.push(x),l.y.push(s==="x"?c+(o.textBaseline==="top"?b:-b)*d:c+(b-(h.length-1)/2)*d),l.groups.push(f)}return{...o,...l}}function $(o){const e=new Map;for(const{bounds:t,group:s}of o){const i=e.get(s);e.set(s,i===void 0?t:{left:Math.min(i.left,t.left),right:Math.max(i.right,t.right),top:Math.min(i.top,t.top),bottom:Math.max(i.bottom,t.bottom)})}return[...e.values()]}function Q(o,e,t,s=e){const i=o.resolvedScales[t.scale],u=pe(o,e,t.position,t.scale,s),d=["ordinal","band","point"].includes(i?.type);if(Z(t,i),!["linear","time","ordinal","band","point"].includes(i?.type)&&!R(i?.type)||!u)throw new Error("Axis labels require a supported resolved scale and Canvas bounds.");if(d&&t.mode!=="values")throw new Error("Discrete axis labels require explicit or inferred values, not count.");let l=ve(o,t);if(F(l.length,"Label value count"),d){const n=new Set(i.domain);if(!l.every(r=>n.has(r)))throw new RangeError("Label values must be inside the scale domain.")}else{const n=Math.min(...i.domain),r=Math.max(...i.domain);if(!l.every(m=>m>=n&&m<=r))throw new RangeError("Label values must be inside the scale domain.")}let f=d?ce(l,i):he(l,i);const h=n=>Se(n,i.type,t.format,r=>i.type==="time"?xe(r,i.domain):R(i.type)?me(i.type,r):String(r)),x=t.format==="ticks"?Ee(l,i.type):i.type==="time"&&t.format==="auto"?be(l,i.domain):void 0;let c=l.map((n,r)=>Ve(n,t.labelMap,m=>x?.[r]??h(m)));if(c.includes("")){const n=c.map((r,m)=>r===""?-1:m).filter(r=>r!==-1);l=n.map(r=>l[r]),f=n.map(r=>f[r]),c=n.map(r=>c[r])}const b={values:l,...ge({bounds:u,channel:e,position:t.position,positions:f.map(n=>n+(t.alongOffset??0)),offset:t.offset})},a=Ge(b,c,t,e,o.materializationConfigs.textMetrics);if(e==="x"&&Math.abs(Math.sin(t.rotation))>1e-9){const n=t.position==="bottom"?1:-1;a.textAlign=Math.sin(t.rotation)*n<0?"right":"left",a.textBaseline="middle"}const E=Fe(o)?.properties,y=()=>a.text.map((n,r)=>D({x:Array.isArray(a.x)?a.x[r]:a.x,y:Array.isArray(a.y)?a.y[r]:a.y,text:n,fontSize:t.fontSize,fontFamily:t.fontFamily,fontWeight:t.fontWeight,textAlign:a.textAlign,textBaseline:a.textBaseline,rotation:t.rotation},o.materializationConfigs.textMetrics));let v=y();if(o.materializationConfigs.canvas?.plot!==void 0||t.rotation!==0){const n=e==="x",r=["bottom","right"].includes(t.position),m=n?u.y+(r?u.height:0):u.x+(r?u.width:0),O=n?r?"top":"bottom":r?"left":"right",g=$(v.map((p,w)=>({bounds:p,group:a.groups[w]}))).map(p=>m+(r?t.offset:-t.offset)-p[O]),M=n?"y":"x",T=a[M];a[M]=a.text.map((p,w)=>(Array.isArray(T)?T[w]:T)+g[a.groups[w]]),v=v.map((p,w)=>{const A=g[a.groups[w]];return n?{...p,top:p.top+A,bottom:p.bottom+A}:{...p,left:p.left+A,right:p.right+A}})}if(t.flush===!0){const n=e==="x"?"x":"y",r=e==="x"?"left":"top",m=e==="x"?"right":"bottom",O=Math.min(...i.range)+(t.alongOffset??0),L=Math.max(...i.range)+(t.alongOffset??0),M=$(v.map((p,w)=>({bounds:p,group:a.groups[w]}))).map((p,w)=>{const A=f[w]+(t.alongOffset??0);if(t.flushThreshold!==void 0&&Math.min(Math.abs(A-O),Math.abs(A-L))>t.flushThreshold)return 0;if(p[m]-p[r]>L-O+1e-9)throw new Error(`The ${e}-axis label cannot flush inside the scale span.`);return p[r]<O?O-p[r]:p[m]>L?L-p[m]:0}),T=a[n];a[n]=a.text.map((p,w)=>(Array.isArray(T)?T[w]:T)+M[a.groups[w]]),v=v.map((p,w)=>{const A=M[a.groups[w]];return{...p,[r]:p[r]+A,[m]:p[m]+A}})}t.align!==void 0&&(a.textAlign=t.align,v=y());const B=t.rotation!==0,oe=B?a.text.map((n,r)=>{const m=Array.isArray(a.x)?a.x[r]:a.x,O=Array.isArray(a.y)?a.y[r]:a.y,L=Math.cos(t.rotation),g=Math.sin(t.rotation);return D({x:m*L+O*g,y:-m*g+O*L,text:n,fontSize:t.fontSize,fontFamily:t.fontFamily,fontWeight:t.fontWeight,textAlign:a.textAlign,textBaseline:a.textBaseline},o.materializationConfigs.textMetrics)}):v,z=$(oe.map((n,r)=>({bounds:n,group:a.groups[r]}))).sort((n,r)=>e==="x"?n.left-r.left:n.top-r.top);if(!E||!v.every(n=>je(n,E)))throw ae(`The ${e}-axis labels do not fit the Canvas margin.`,v,E);if(t.overlap==="error"&&z.some((n,r)=>B?z.slice(0,r).some(m=>j(m,n)):r>0&&j(z[r-1],n)))throw new Error(`The ${e}-axis labels overlap each other.`);const k=o.graphicSpec.objects[C(e,s)[3]]?We(o.graphicSpec,C(e,s)[3],o.materializationConfigs.textMetrics):void 0;if(k&&!ie(o.guideConfigs.axis?.[s]?.title)&&!N(o.guideConfigs.axis?.[s]?.title)&&!se(o,e,s)&&v.some(n=>j(n,k)))throw new Error(`The ${e}-axis labels overlap the axis title.`);return a}function He(o,e,t,s=e){const i=e==="x"?"editXAxisLabels":"editYAxisLabels";W(t,i,!1);const u=o.guideConfigs.axis?.[s]?.labels;if(!u)throw new Error(`${i} requires label configuration.`);const d=Object.hasOwn(t,"values")||Object.hasOwn(t,"count"),l=o.guideConfigs.axis?.[s]?.ticks,f=!d&&u.inferredValues===!0&&l?.mode==="values"?l.values:void 0,h=Object.hasOwn(t,"values")||f!==void 0?"values":Object.hasOwn(t,"count")?"count":u.mode;let x=U({...u,...t,...f===void 0?{}:{values:f},...d?{inferredValues:!1}:{},mode:h},t,i);return x=K(o,x,t,i),h==="values"?(delete x.count,Object.hasOwn(t,"rounding")||delete x.rounding):delete x.values,I(e,x),x}function ee(o){const e=o==="x"?"editXAxisLabels":"editYAxisLabels";return Y({op:e,description:`Edit concrete ${o}-axis labels.`},X(function(t={}){W(t,e,!1);const s=V(this,o,t,{create:!1}),i=s.id;t=s.options;const u=C(o,i)[2];if(this.graphicSpec.objects[u]?.type!=="text")throw new Error(`${e} requires existing axis labels.`);const d=He(this,o,t,i);J(this.guideConfigs.axis?.[i]?.ticks,d,e);const l=Q(this,o,d,i);let f=this._withGuideConfig(i,"labels",d);const h={length:l.text.length,x:l.x,y:l.y,text:l.text,fill:d.colorMap===void 0?d.color:l.text.map((c,b)=>Ne(l.values[l.groups[b]],d.colorMap,d.color)),fontSize:d.fontSize,fontFamily:d.fontFamily,fontWeight:d.fontWeight,textAlign:l.textAlign,textBaseline:l.textBaseline};(d.rotation!==0||this.graphicSpec.objects[u].items.some(c=>Object.hasOwn(c.properties,"rotation")))&&(h.rotation=d.rotation);for(const[c,b]of Object.entries(h))f=f.editGraphics({target:u,property:c,value:b});const x=f.guideConfigs.axis?.[i]?.title;return N(x)&&f.context.pendingRelativeTitleAxis!==i&&(f=f[o==="x"?"editXAxisTitle":"editYAxisTitle"](i===o?void 0:G(i,o))),f}))}const _e=ee("x"),Xe=ee("y");function te(o){const e=o==="x"?"createXAxisLabels":"createYAxisLabels",t=o==="x"?"editXAxisLabels":"editYAxisLabels";return Y({op:e,description:`Create concrete ${o}-axis labels.`},X(function(s={}){W(s,e,!0);const i=V(this,o,s,{create:!0}),u=i.id;s=i.options;const d=ne(s.scale??o,"Scale id"),l=this.semanticSpec.guides.axis?.[u]?.scale;if(l&&l!==d)throw new Error(`${e} conflicts with the existing axis scale.`);const f=C(o,u)[2];if(this.graphicSpec.objects[f])throw new Error(`${e} requires missing axis labels.`);const h=this.guideConfigs.axis?.[u]?.ticks,x=Object.hasOwn(s,"values"),c=Object.hasOwn(s,"count"),b=this.resolvedScales[d],a=!x&&!c&&h===void 0&&["ordinal","band","point"].includes(b?.type)?b.domain:void 0,E=x||a!==void 0?"values":c?"count":h?.mode??"count";let y=U({scale:d,position:Te(o),offset:o==="x"?18:12,format:"auto",color:S.color,fontSize:S.fontSize,fontFamily:S.fontFamily,fontWeight:S.fontWeight,...re(this.materializationConfigs.theme,"labels"),rotation:S.rotation,overlap:S.overlap,...h?.rounding===void 0?{}:{rounding:h.rounding},...s,inferredValues:!x&&!c&&(h?.inferredValues===!0||a!==void 0),mode:E},s,e);return y=K(this,y,s,e),E==="values"?(y.values??=h?.values??a,Object.hasOwn(s,"rounding")||delete y.rounding):y.count??=h?.count??S.count,I(o,y),J(h,y,e),Q(this,o,y,u),this.editSemantic({property:`guide.axis.${u}.scale`,value:d}).createGraphics({id:f,type:"text",length:0,...ze(this)})._withGuideConfig(u,"labels",y)[t](u===o?void 0:G(u,o))}))}const Ye=te("x"),Pe=te("y");function mt(o){o.prototype.editXAxisLabels=_e,o.prototype.editYAxisLabels=Xe,o.prototype.createXAxisLabels=Ye,o.prototype.createYAxisLabels=Pe}export{mt as registerAxisLabelActions,He as resolveAxisLabelEditConfig,P as validateAxisTextStyle};

package/src/actions/guides/axes/tickGroups.js

@@ -1,3 +1,5 @@
+import { resolveAxisTickEditConfig } from "./ticks.js";
+import { resolveAxisLabelEditConfig } from "./labels.js";
 import { withGuideLayoutValidation } from "../../../materialization/guides/layout.js";
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
@@ -35,7 +37,7 @@ const LABEL_OPTIONS = Object.freeze([
   "overlap",
   "labelMap",
   "alongOffset",
-  "flush",
+  "flush", "flushThreshold",
   "colorMap",
   "align"
 ]);
@@ -94,6 +96,19 @@ function names(channel) {
   };
 }
 
+// Validate original options before a materialization plan stores normalized arguments.
+export function validateAxisTickGroupEditConfig(program, channel, args, axisId = channel) {
+  validateAxisTickGroupArgs(args, names(channel).edit, false);
+  const shared = select(args, SHARED_EDIT);
+  const hasShared = Object.keys(shared).length > 0;
+  if (hasShared || Object.hasOwn(args, "ticks")) {
+    resolveAxisTickEditConfig(program, channel, { ...shared, ...(args.ticks ?? {}) }, axisId);
+  }
+  if (hasShared || Object.hasOwn(args, "labels")) {
+    resolveAxisLabelEditConfig(program, channel, { ...shared, ...(args.labels ?? {}) }, axisId);
+  }
+}
+
 function makeCreate(channel) {
   const operation = names(channel);