ggaction 0.0.4 → 0.0.6

package/src/actions/marks/text/layout.js

@@ -0,0 +1,321 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import { validateOptionObject } from "../../../core/validation.js";
+import { DEFAULT_TEXT_MARK } from "../../../grammar/text.js";
+import { findGraphicParent } from "../../../grammar/schemas/graphicTree.js";
+import { validateConcreteGraphicValue } from
+  "../../../grammar/schemas/concreteGraphic.js";
+import {
+  normalizeLabelLayoutGeometry,
+  resolveLabelLayout,
+  resolveLabelLeader
+} from "../../../layout/labels.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { canMaterializeText } from "../../../materialization/marks/index.js";
+import { resolveTextGraphicEntries } from "../../../materialization/text.js";
+import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
+
+const LAYOUT_OPTIONS = Object.freeze([
+  "target", "axis", "padding", "maxDisplacement", "bounds", "leader"
+]);
+const REMOVE_OPTIONS = Object.freeze(["target"]);
+const MATERIALIZE_OPTIONS = Object.freeze(["id", "rematerializeBase"]);
+const LEADER_OPTIONS = Object.freeze([
+  "stroke", "strokeWidth", "strokeDash", "opacity"
+]);
+
+function normalizeLeader(value) {
+  if (value === false || value === undefined) return false;
+  validateOptionObject(value, LEADER_OPTIONS, "label leader");
+  const normalized = {
+    stroke: "#94a3b8",
+    strokeWidth: 1,
+    strokeDash: [],
+    opacity: 1,
+    ...value
+  };
+  for (const [property, propertyValue] of Object.entries(normalized)) {
+    validateConcreteGraphicValue("line", property, propertyValue);
+  }
+  return normalized;
+}
+
+function normalizePolicy(args) {
+  const geometry = normalizeLabelLayoutGeometry(Object.fromEntries(
+    Object.entries(args).filter(
+      ([key]) => key !== "target" && key !== "leader"
+    )
+  ));
+  return { ...geometry, leader: normalizeLeader(args.leader) };
+}
+
+function leaderId(target) {
+  return `${target}-label-leaders`;
+}
+
+function requireCompleteText(program, requested, operation) {
+  const target = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Text mark id");
+  if (target !== undefined) {
+    const layer = findLayer(program, target);
+    if (layer?.mark?.type !== "text") {
+      throw new Error(`Unknown ${operation} text mark target "${target}".`);
+    }
+    if (!canMaterializeText(program, layer)) {
+      throw new Error(`${operation} requires a complete text mark.`);
+    }
+    return layer;
+  }
+  return resolveEligibleLayer(program, {
+    predicate: layer =>
+      layer.mark?.type === "text" && canMaterializeText(program, layer),
+    label: `${operation} text mark`
+  });
+}
+
+function requireConfiguredText(program, requested) {
+  const target = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Text mark id");
+  return resolveEligibleLayer(program, {
+    target,
+    predicate: layer =>
+      layer.mark?.type === "text" &&
+      program.materializationConfigs.labelLayouts?.[layer.id] !== undefined,
+    label: "removeLabelLayout text mark"
+  });
+}
+
+function concreteBounds(program, kind) {
+  if (kind === "plot") {
+    const plot = resolveGraphicBounds(program);
+    return {
+      left: plot.x,
+      right: plot.x + plot.width,
+      top: plot.y,
+      bottom: plot.y + plot.height
+    };
+  }
+  const canvas = program.graphicSpec.objects.canvas;
+  if (
+    canvas?.type !== "canvas" ||
+    !Number.isFinite(canvas.properties.width) ||
+    !Number.isFinite(canvas.properties.height)
+  ) {
+    throw new Error("Canvas label bounds require concrete Canvas dimensions.");
+  }
+  const x = canvas.properties.x ?? 0;
+  const y = canvas.properties.y ?? 0;
+  return {
+    left: x,
+    right: x + canvas.properties.width,
+    top: y,
+    bottom: y + canvas.properties.height
+  };
+}
+
+function layoutInputs(program, layer) {
+  const entries = resolveTextGraphicEntries(
+    program,
+    layer,
+    program.markConfigs[layer.id] ?? DEFAULT_TEXT_MARK
+  );
+  const graphic = program.graphicSpec.objects[layer.id];
+  if (graphic?.type !== "text" || !Array.isArray(graphic.items)) {
+    throw new Error(`Text mark "${layer.id}" requires text collection graphics.`);
+  }
+  if (entries.length !== graphic.items.length) {
+    throw new Error(`Text mark "${layer.id}" base materialization is inconsistent.`);
+  }
+  return entries.map((entry, index) => ({
+    id: graphic.items[index].id,
+    x: entry.graphic.properties.x,
+    y: entry.graphic.properties.y,
+    sourceX: entry.anchor.x,
+    sourceY: entry.anchor.y,
+    text: entry.graphic.properties.text,
+    fontSize: entry.graphic.properties.fontSize,
+    textAlign: entry.graphic.properties.textAlign,
+    textBaseline: entry.graphic.properties.textBaseline,
+    rotation: entry.graphic.properties.rotation
+  }));
+}
+
+function leaderPlacement(program, layer) {
+  const targetParent = findGraphicParent(program.graphicSpec, layer.id);
+  if (targetParent?.kind !== "parent") {
+    throw new Error("Label leaders require the text graphic to have a parent container.");
+  }
+  const source = layer.source === undefined
+    ? undefined
+    : program.graphicSpec.objects[layer.source];
+  const sourceParent = source === undefined
+    ? undefined
+    : findGraphicParent(program.graphicSpec, layer.source);
+  const before = sourceParent?.kind === "parent" && sourceParent.id === targetParent.id
+    ? layer.source
+    : layer.id;
+  return { parent: targetParent.id, before };
+}
+
+function removeLeaderGraphic(program, id) {
+  return program.graphicSpec.objects[id] === undefined
+    ? program
+    : program.editGraphics({ target: id, remove: true });
+}
+
+function materializeLeaders(program, layer, config, resolved) {
+  let next = removeLeaderGraphic(program, config.leaderId);
+  if (config.leader === false) return { program: next, count: 0 };
+  const leaders = resolved.items.map(resolveLabelLeader).filter(Boolean);
+  if (leaders.length === 0) return { program: next, count: 0 };
+  next = next
+    .createGraphics({
+      id: config.leaderId,
+      type: "line",
+      length: leaders.length,
+      ...leaderPlacement(next, layer)
+    })
+    .editGraphics({
+      target: config.leaderId,
+      property: "x1",
+      value: leaders.map(line => line.x1)
+    })
+    .editGraphics({
+      target: config.leaderId,
+      property: "y1",
+      value: leaders.map(line => line.y1)
+    })
+    .editGraphics({
+      target: config.leaderId,
+      property: "x2",
+      value: leaders.map(line => line.x2)
+    })
+    .editGraphics({
+      target: config.leaderId,
+      property: "y2",
+      value: leaders.map(line => line.y2)
+    });
+  for (const property of ["stroke", "strokeWidth", "strokeDash", "opacity"]) {
+    next = next.editGraphics({
+      target: config.leaderId,
+      property,
+      value: property === "strokeDash"
+        ? leaders.map(() => config.leader.strokeDash)
+        : config.leader[property]
+    });
+  }
+  return { program: next, count: leaders.length };
+}
+
+const materializeLabelLayout = action(
+  {
+    op: "materializeLabelLayout",
+    description: "Resolve concrete label positions and optional leader lines."
+  },
+  function (args = {}) {
+    validateOptionObject(args, MATERIALIZE_OPTIONS, "materializeLabelLayout");
+    const id = validateUserId(args.id, "Text mark id");
+    const rematerializeBase = args.rematerializeBase ?? true;
+    if (typeof rematerializeBase !== "boolean") {
+      throw new TypeError("materializeLabelLayout rematerializeBase must be a boolean.");
+    }
+    const layer = findLayer(this, id);
+    if (layer?.mark?.type !== "text") throw new Error(`Unknown text mark "${id}".`);
+    const config = this.materializationConfigs.labelLayouts?.[id];
+    if (config === undefined) {
+      throw new Error(`Text mark "${id}" has no label layout policy.`);
+    }
+    let next = rematerializeBase
+      ? this.rematerializeTextMark({ id, replayLayout: false })
+      : this;
+    const resolved = resolveLabelLayout({
+      items: canMaterializeText(next, layer) ? layoutInputs(next, layer) : [],
+      bounds: concreteBounds(next, config.bounds),
+      axis: config.axis,
+      padding: config.padding,
+      maxDisplacement: config.maxDisplacement
+    });
+    next = next
+      .editGraphics({
+        target: id,
+        property: "x",
+        value: resolved.items.map(item => item.x)
+      })
+      .editGraphics({
+        target: id,
+        property: "y",
+        value: resolved.items.map(item => item.y)
+      });
+    const leaders = materializeLeaders(next, layer, config, resolved);
+    next = leaders.program;
+    return next._withMaterializationConfig(["labelLayouts", id], {
+      axis: config.axis,
+      padding: config.padding,
+      maxDisplacement: config.maxDisplacement,
+      bounds: config.bounds,
+      leader: config.leader,
+      leaderId: config.leaderId,
+      resolution: {
+        overlapBefore: resolved.overlapBefore,
+        overlapAfter: resolved.overlapAfter,
+        displaced: resolved.items.filter(item => item.distance > 0).length,
+        leaders: leaders.count,
+        maximumDisplacement: resolved.items.reduce(
+          (maximum, item) => Math.max(maximum, item.distance),
+          0
+        ),
+        warnings: resolved.warnings
+      }
+    });
+  }
+);
+
+const layoutLabels = action(
+  {
+    op: "layoutLabels",
+    description: "Assign deterministic collision-aware layout to a text mark."
+  },
+  function (args = {}) {
+    validateOptionObject(args, LAYOUT_OPTIONS, "layoutLabels");
+    const layer = requireCompleteText(this, args.target, "layoutLabels");
+    const policy = normalizePolicy(args);
+    const generatedId = leaderId(layer.id);
+    const existingConfig = this.materializationConfigs.labelLayouts?.[layer.id];
+    if (
+      this.graphicSpec.objects[generatedId] !== undefined &&
+      existingConfig?.leaderId !== generatedId
+    ) {
+      throw new Error(`Label layout leader graphic "${generatedId}" already exists.`);
+    }
+    return this
+      ._withMaterializationConfig(["labelLayouts", layer.id], {
+        ...policy,
+        leaderId: generatedId
+      })
+      .materializeLabelLayout({ id: layer.id });
+  }
+);
+
+const removeLabelLayout = action(
+  {
+    op: "removeLabelLayout",
+    description: "Remove label layout and restore semantic base text positions."
+  },
+  function (args = {}) {
+    validateOptionObject(args, REMOVE_OPTIONS, "removeLabelLayout");
+    const layer = requireConfiguredText(this, args.target);
+    const config = this.materializationConfigs.labelLayouts[layer.id];
+    return removeLeaderGraphic(
+      this._withoutMaterializationConfig(["labelLayouts", layer.id]),
+      config.leaderId
+    ).rematerializeTextMark({ id: layer.id });
+  }
+);
+
+export function registerTextLabelLayoutActions(ProgramClass) {
+  ProgramClass.prototype.layoutLabels = layoutLabels;
+  ProgramClass.prototype.removeLabelLayout = removeLabelLayout;
+  ProgramClass.prototype.materializeLabelLayout = materializeLabelLayout;
+}

package/src/actions/primitives/semanticValidation/dataset.js

@@ -0,0 +1,22 @@
+import { validateUserId } from "../../../core/identifiers.js";
+import { isPlainObject } from "../../../core/immutable.js";
+import { validateDatasetTransforms } from "../../../grammar/transforms.js";
+import { hasDataset } from "../../../selectors/datasets.js";
+
+export function validateDatasetSemanticValue(program, parsed, value) {
+  const property = parsed.path[0];
+  if (property === "values") {
+    if (!Array.isArray(value) || !value.every(isPlainObject)) {
+      throw new TypeError("Dataset values must be an array of plain row objects.");
+    }
+    return;
+  }
+  if (property === "source") {
+    validateUserId(value, "Dataset source id");
+    if (!hasDataset(program, value)) {
+      throw new Error(`Unknown source dataset "${value}".`);
+    }
+    return;
+  }
+  if (property === "transform") validateDatasetTransforms(value);
+}

package/src/actions/primitives/semanticValidation/guide.js

@@ -0,0 +1,43 @@
+import { validateUserId } from "../../../core/identifiers.js";
+import { CATEGORICAL_LEGEND_CHANNELS } from "../../../core/vocabulary.js";
+import { validateNonEmptySemanticString } from "./shared.js";
+
+function validateLegend(property, value) {
+  if (property === "title") {
+    validateNonEmptySemanticString(value, "Legend title");
+    return;
+  }
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new TypeError(`Legend ${property} must be a non-empty array.`);
+  }
+  if (new Set(value).size !== value.length) {
+    throw new Error(`Legend ${property} must not contain duplicates.`);
+  }
+  if (property === "channels") {
+    if (!value.every(channel => CATEGORICAL_LEGEND_CHANNELS.includes(channel))) {
+      throw new Error("Legend channels support only color, strokeDash, and shape.");
+    }
+    return;
+  }
+  for (const id of value) validateUserId(id, "Legend scale id");
+}
+
+export function validateGuideSemanticValue(_program, parsed, value) {
+  const property = parsed.path.at(-1);
+  if (parsed.id === "legend.series") {
+    validateLegend(property, value);
+    return;
+  }
+  if (!parsed.id.startsWith("grid.") && !parsed.id.startsWith("axis.")) return;
+  if (parsed.id === "axis.parallel" && property === "scales") {
+    if (!Array.isArray(value) || value.length < 2) {
+      throw new TypeError("Parallel axis scales must contain at least two ids.");
+    }
+    value.forEach(id => validateUserId(id, "Parallel axis scale id"));
+  } else if (property === "title") {
+    validateNonEmptySemanticString(value, "Axis title");
+  } else {
+    const guideKind = parsed.id.startsWith("grid.") ? "Grid" : "Axis";
+    validateUserId(value, `${guideKind} ${property} id`);
+  }
+}

package/src/actions/primitives/semanticValidation/index.js

@@ -0,0 +1,23 @@
+import { validateCoordinateType } from "../../../grammar/coordinates.js";
+import { validateDatasetSemanticValue } from "./dataset.js";
+import { validateGuideSemanticValue } from "./guide.js";
+import { validateLayerSemanticValue } from "./layer.js";
+import { validateScaleSemanticValue } from "./scale.js";
+import { validateNonEmptySemanticString } from "./shared.js";
+
+const VALIDATORS = Object.freeze({
+  dataset: validateDatasetSemanticValue,
+  layer: validateLayerSemanticValue,
+  scale: validateScaleSemanticValue,
+  coordinate(_program, parsed, value) {
+    if (parsed.path[0] === "type") validateCoordinateType(value);
+  },
+  guide: validateGuideSemanticValue,
+  title(_program, parsed, value) {
+    validateNonEmptySemanticString(value, `Chart title ${parsed.path[0]}`);
+  }
+});
+
+export function validateSemanticValue(program, parsed, value) {
+  VALIDATORS[parsed.kind]?.(program, parsed, value);
+}

package/src/actions/primitives/semanticValidation/layer.js

@@ -0,0 +1,74 @@
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  COLOR_LAYOUTS,
+  MARK_TYPES,
+  STACK_MODES
+} from "../../../core/vocabulary.js";
+import { validateAggregate } from "../../../grammar/aggregate.js";
+import {
+  normalizeHistogramBin,
+  validateHistogramBinBoundaries,
+  validateHistogramBinStep
+} from "../../../grammar/histogram.js";
+import {
+  validateParallelDimensions,
+  validateParallelKeyField,
+  validateParallelMissingPolicy
+} from "../../../grammar/parallelCoordinates.js";
+import { validatePathOrderDirection } from "../../../grammar/pathOrder.js";
+import { validateSemanticFieldType } from "../../../grammar/scales/index.js";
+import { findLayer } from "../../../selectors/layers.js";
+import { validateNonEmptySemanticString } from "./shared.js";
+
+function validateLayerSource(program, parsed, value) {
+  validateUserId(value, "Layer source id");
+  if (value === parsed.id) {
+    throw new Error("A layer cannot use itself as its source.");
+  }
+  const source = findLayer(program, value);
+  if (source === undefined) {
+    throw new Error(`Unknown source layer "${value}".`);
+  }
+  if (!["point", "bar", "rule", "rect"].includes(source.mark?.type)) {
+    throw new Error(
+      `Layer source "${value}" must be a point, bar, rule, or rect mark.`
+    );
+  }
+}
+
+export function validateLayerSemanticValue(program, parsed, value) {
+  const property = parsed.path.join(".");
+  if (property === "mark.type" && !MARK_TYPES.includes(value)) {
+    throw new Error(`Unknown mark type "${value}".`);
+  }
+  if (property === "source") validateLayerSource(program, parsed, value);
+  if (property.endsWith(".title")) {
+    validateNonEmptySemanticString(value, "Encoding title");
+  }
+  if (property === "encoding.pathOrder.fieldType" && value !== "quantitative") {
+    throw new Error("Path order field type must be quantitative.");
+  }
+  if (property.endsWith(".fieldType")) validateSemanticFieldType(value);
+  if (property === "encoding.pathOrder.order") validatePathOrderDirection(value);
+  if (property === "encoding.parallel.dimensions") {
+    validateParallelDimensions(value, { normalized: true });
+  }
+  if (property === "encoding.parallel.key") validateParallelKeyField(value);
+  if (property === "encoding.parallel.missing") {
+    validateParallelMissingPolicy(value);
+  }
+  if (property.endsWith(".aggregate")) validateAggregate(value);
+  if (property.endsWith(".bin.maxBins")) normalizeHistogramBin({ maxBins: value });
+  if (property.endsWith(".bin.step")) validateHistogramBinStep(value);
+  if (property.endsWith(".bin.boundaries")) validateHistogramBinBoundaries(value);
+  if (
+    property.endsWith(".stack") &&
+    value !== null &&
+    !STACK_MODES.includes(value)
+  ) {
+    throw new Error(`Unsupported stack "${value}".`);
+  }
+  if (property === "encoding.color.layout" && !COLOR_LAYOUTS.includes(value)) {
+    throw new Error(`Unsupported color layout "${value}".`);
+  }
+}

package/src/actions/primitives/semanticValidation/scale.js

@@ -0,0 +1,74 @@
+import {
+  validateContinuousColorInterpolation,
+  validateScalePropertyForType,
+  validateSemanticScaleDomain,
+  validateSemanticScaleRange,
+  validateSemanticScaleType
+} from "../../../grammar/scales/index.js";
+import { findSemanticScale } from "../../../selectors/scales.js";
+
+function validateOwnedProperty(existing, property) {
+  if (existing?.type !== undefined) {
+    validateScalePropertyForType(existing.type, property);
+  }
+}
+
+export function validateScaleSemanticValue(program, parsed, value) {
+  const property = parsed.path.join(".");
+  const existing = findSemanticScale(program, parsed.id);
+  if (property === "type") {
+    validateSemanticScaleType(value);
+    for (const owned of [
+      "nice", "zero", "clamp", "base", "exponent", "constant",
+      "paddingInner", "paddingOuter", "padding", "align"
+    ]) {
+      if (existing?.[owned] !== undefined) validateScalePropertyForType(value, owned);
+    }
+    return;
+  }
+  if (property === "domain") return validateSemanticScaleDomain(value);
+  if (property === "range") return validateSemanticScaleRange(value);
+  if (["nice", "zero", "clamp", "reverse"].includes(property)) {
+    if (typeof value !== "boolean") {
+      throw new TypeError(`Scale ${property} must be a boolean.`);
+    }
+    if (property !== "reverse") validateOwnedProperty(existing, property);
+    return;
+  }
+  if (["base", "exponent", "constant"].includes(property)) {
+    if (!Number.isFinite(value) || value <= 0) {
+      throw new RangeError(`Scale ${property} must be a positive finite number.`);
+    }
+    if (property === "base" && value === 1) {
+      throw new RangeError("Scale base must not equal 1.");
+    }
+    validateOwnedProperty(existing, property);
+    return;
+  }
+  if (property === "interpolate") {
+    validateContinuousColorInterpolation(value);
+    return;
+  }
+  if (property === "paddingInner") {
+    if (!Number.isFinite(value) || value < 0 || value >= 1) {
+      throw new RangeError(
+        "Scale paddingInner must be from 0 (inclusive) to 1 (exclusive)."
+      );
+    }
+    validateOwnedProperty(existing, property);
+    return;
+  }
+  if (property === "paddingOuter" || property === "padding") {
+    if (!Number.isFinite(value) || value < 0) {
+      throw new RangeError(`Scale ${property} must be a non-negative finite number.`);
+    }
+    validateOwnedProperty(existing, property);
+    return;
+  }
+  if (property === "align") {
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+      throw new RangeError("Scale align must be between 0 and 1.");
+    }
+    validateOwnedProperty(existing, property);
+  }
+}

package/src/actions/primitives/semanticValidation/shared.js

@@ -0,0 +1,5 @@
+export function validateNonEmptySemanticString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+}