ggaction 0.0.1

package/src/actions/marks/rule.js

@@ -0,0 +1,287 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validatePositiveFinite } from "../../core/validation.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues,
+  mapOrdinalValues,
+  normalizeStrokeDashPattern
+} from "../../grammar/scales.js";
+import { deriveRuleValues, resolveRuleMode } from "../../grammar/rules.js";
+import { resolveGraphicBounds } from "../../layout/canvas.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import {
+  assertMarkAvailable,
+  resolveMarkData,
+  resolveMarkId,
+  validateMarkOptions
+} from "./shared.js";
+import { resolveMarkGraphicPlacement } from
+  "../../materialization/graphicHierarchy.js";
+
+const CREATE_OPTIONS = Object.freeze(["id", "data"]);
+const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+const SPAN_OPTIONS = Object.freeze(["id", "orientation", "size"]);
+const DEFAULT_RULE_CONFIG = Object.freeze({
+  stroke: DEFAULT_COLORS.mark,
+  strokeWidth: 2,
+  strokeDash: Object.freeze([]),
+  opacity: 1
+});
+
+function mapPosition(values, scale) {
+  return ["ordinal", "band", "point"].includes(scale.type)
+    ? mapOrdinalPositionValues(values, scale)
+    : mapContinuousScaleValues(values, scale);
+}
+
+function requireRule(program, id) {
+  const layer = findLayer(program, id);
+  if (layer?.mark?.type !== "rule") {
+    throw new Error(`Unknown rule mark "${id}".`);
+  }
+  const dataset = findDataset(program, layer.data);
+  if (dataset === undefined) {
+    throw new Error(`Rule mark "${id}" requires an existing dataset.`);
+  }
+  const graphic = program.graphicSpec.objects[id];
+  if (graphic?.type !== "line" || graphic.items === undefined) {
+    throw new Error(`Rule mark "${id}" requires line collection graphics.`);
+  }
+  return { dataset, graphic, layer };
+}
+
+function validateEndpointBindings(layer) {
+  if (
+    layer.encoding?.x2 !== undefined &&
+    layer.encoding.x2.scale !== layer.encoding?.x?.scale
+  ) {
+    throw new Error(`Rule mark "${layer.id}" requires x and x2 to share one scale.`);
+  }
+  if (
+    layer.encoding?.y2 !== undefined &&
+    layer.encoding.y2.scale !== layer.encoding?.y?.scale
+  ) {
+    throw new Error(`Rule mark "${layer.id}" requires y and y2 to share one scale.`);
+  }
+}
+
+const createRuleMark = action(
+  {
+    op: "createRuleMark",
+    description: "Create a semantic rule mark and empty line collection."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, CREATE_OPTIONS, "createRuleMark");
+    const id = resolveMarkId(this, args.id, {
+      defaultId: "rule",
+      label: "Rule mark id",
+      markType: "rule",
+      operation: "createRuleMark"
+    });
+    const { data } = resolveMarkData(this, args);
+    assertMarkAvailable(this, id);
+
+    return this
+      .editSemantic({ property: `layer[${id}].mark.type`, value: "rule" })
+      .editSemantic({ property: `layer[${id}].data`, value: data })
+      .createGraphics({
+        id,
+        type: "line",
+        length: 0,
+        ...resolveMarkGraphicPlacement(this, { data, markType: "rule" })
+      })
+      ._withMarkConfig(id, DEFAULT_RULE_CONFIG);
+  }
+);
+
+const rematerializeRuleMark = action(
+  {
+    op: "rematerializeRuleMark",
+    description: "Recompute concrete rule endpoints and appearance."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, REMATERIALIZE_OPTIONS, "rematerializeRuleMark");
+    const id = validateUserId(args.id, "Rule mark id");
+    const highlights = Object.entries(
+      this.materializationConfigs.highlights ?? {}
+    ).filter(([, config]) => config.target === id);
+    if (highlights.length > 0) {
+      let baseline = this;
+      for (const [highlightId] of highlights) {
+        baseline = baseline._withoutMaterializationConfig(["highlights", highlightId]);
+      }
+      return baseline
+        .editGraphics({ target: id, property: "length", value: 0 })
+        .rematerializeRuleMark({ id })
+        .rematerializeMarkHighlights({ target: id, highlights });
+    }
+    const { dataset, graphic, layer } = requireRule(this, id);
+    validateEndpointBindings(layer);
+    const config = this.markConfigs[id] ?? DEFAULT_RULE_CONFIG;
+    const fixedSpan = config.fixedSpan;
+    const boxSpan = config.boxSpanOwner;
+    const mode = boxSpan !== undefined
+      ? "box-span"
+      : fixedSpan !== undefined &&
+      layer.encoding?.x?.scale !== undefined &&
+      layer.encoding?.y?.scale !== undefined
+      ? "fixed-span"
+      : resolveRuleMode(layer);
+    if (mode === undefined) {
+      return graphic.items.length === 0
+        ? this
+        : this.editGraphics({ target: id, property: "length", value: 0 });
+    }
+
+    const scaleIds = [...new Set(
+      ["x", "y", "x2", "y2", "strokeDash", "opacity"]
+        .map(channel => layer.encoding?.[channel]?.scale)
+        .filter(scale => scale !== undefined)
+    )];
+    let resolved = this;
+    for (const scaleId of scaleIds) {
+      resolved = resolved.rematerializeScale({ id: scaleId });
+    }
+
+    const derived = deriveRuleValues(dataset.values, layer);
+    const mapped = {};
+    for (const channel of ["x", "y", "x2", "y2"]) {
+      const encoding = layer.encoding?.[channel];
+      if (encoding === undefined) continue;
+      mapped[channel] = mapPosition(
+        derived.values[channel],
+        resolved.resolvedScales[encoding.scale]
+      );
+    }
+    const bounds = resolveGraphicBounds(resolved);
+    const x1 = [];
+    const y1 = [];
+    const x2 = [];
+    const y2 = [];
+    for (let index = 0; index < derived.length; index += 1) {
+      if (mode === "vertical-span") {
+        x1.push(mapped.x[index]);
+        y1.push(bounds.y);
+        x2.push(mapped.x[index]);
+        y2.push(bounds.y + bounds.height);
+      } else if (mode === "horizontal-span") {
+        x1.push(bounds.x);
+        y1.push(mapped.y[index]);
+        x2.push(bounds.x + bounds.width);
+        y2.push(mapped.y[index]);
+      } else if (mode === "vertical-interval") {
+        x1.push(mapped.x[index]);
+        y1.push(mapped.y[index]);
+        x2.push(mapped.x[index]);
+        y2.push(mapped.y2[index]);
+      } else if (mode === "horizontal-interval") {
+        x1.push(mapped.x[index]);
+        y1.push(mapped.y[index]);
+        x2.push(mapped.x2[index]);
+        y2.push(mapped.y[index]);
+      } else if (mode === "box-span") {
+        const owner = resolved.graphicSpec.objects[boxSpan];
+        const box = owner?.items?.[index]?.properties;
+        if (box === undefined) throw new Error(`Rule mark "${id}" requires box span owner "${boxSpan}".`);
+        if (layer.encoding?.x?.fieldType === "quantitative") {
+          x1.push(mapped.x[index]);
+          y1.push(box.y);
+          x2.push(mapped.x[index]);
+          y2.push(box.y + box.height);
+        } else {
+          x1.push(box.x);
+          y1.push(mapped.y[index]);
+          x2.push(box.x + box.width);
+          y2.push(mapped.y[index]);
+        }
+      } else if (mode === "fixed-span") {
+        if (fixedSpan.orientation === "horizontal") {
+          x1.push(mapped.x[index] - fixedSpan.size / 2);
+          y1.push(mapped.y[index]);
+          x2.push(mapped.x[index] + fixedSpan.size / 2);
+          y2.push(mapped.y[index]);
+        } else {
+          x1.push(mapped.x[index]);
+          y1.push(mapped.y[index] - fixedSpan.size / 2);
+          x2.push(mapped.x[index]);
+          y2.push(mapped.y[index] + fixedSpan.size / 2);
+        }
+      } else {
+        x1.push(mapped.x[index]);
+        y1.push(mapped.y[index]);
+        x2.push(mapped.x2[index]);
+        y2.push(mapped.y2[index]);
+      }
+    }
+
+    const resolvedConfig = resolved.markConfigs[id] ?? DEFAULT_RULE_CONFIG;
+    const dashEncoding = layer.encoding?.strokeDash;
+    const opacityEncoding = layer.encoding?.opacity;
+    const strokeDash = dashEncoding?.scale === undefined
+      ? Array.from(
+          { length: derived.length },
+          () => normalizeStrokeDashPattern(
+            dashEncoding?.datum ?? resolvedConfig.strokeDash
+          )
+        )
+      : mapOrdinalValues(
+          derived.values.strokeDash,
+          resolved.resolvedScales[dashEncoding.scale].domain,
+          resolved.resolvedScales[dashEncoding.scale].range
+        );
+    const opacity = opacityEncoding?.scale === undefined
+      ? resolvedConfig.opacity
+      : mapContinuousScaleValues(
+          derived.values.opacity,
+          resolved.resolvedScales[opacityEncoding.scale]
+        );
+
+    return resolved
+      .editGraphics({ target: id, property: "length", value: derived.length })
+      .editGraphics({ target: id, property: "x1", value: x1 })
+      .editGraphics({ target: id, property: "y1", value: y1 })
+      .editGraphics({ target: id, property: "x2", value: x2 })
+      .editGraphics({ target: id, property: "y2", value: y2 })
+      .editGraphics({ target: id, property: "stroke", value: resolvedConfig.stroke })
+      .editGraphics({
+        target: id,
+        property: "strokeWidth",
+        value: resolvedConfig.strokeWidth
+      })
+      .editGraphics({ target: id, property: "strokeDash", value: strokeDash })
+      .editGraphics({ target: id, property: "opacity", value: opacity });
+  }
+);
+
+export const materializeRuleSpan = action(
+  {
+    op: "materializeRuleSpan",
+    description: "Materialize a fixed-pixel span around a rule anchor."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, SPAN_OPTIONS, "materializeRuleSpan");
+    const id = validateUserId(args.id, "Rule mark id");
+    requireRule(this, id);
+    if (!["horizontal", "vertical"].includes(args.orientation)) {
+      throw new Error(
+        `Unsupported rule span orientation "${args.orientation}".`
+      );
+    }
+    validatePositiveFinite(args.size, "Rule span size");
+    return this
+      ._withMarkConfig(id, {
+        ...this.markConfigs[id],
+        fixedSpan: { orientation: args.orientation, size: args.size }
+      })
+      .rematerializeRuleMark({ id });
+  }
+);
+
+export function registerRuleMarkActions(ProgramClass) {
+  ProgramClass.prototype.createRuleMark = createRuleMark;
+  ProgramClass.prototype.rematerializeRuleMark = rematerializeRuleMark;
+  ProgramClass.prototype.materializeRuleSpan = materializeRuleSpan;
+}

package/src/actions/marks/shared.js

@@ -0,0 +1,112 @@
+import {
+  resolveOptionalUserId,
+  validateUserId
+} from "../../core/identifiers.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer, hasLayer } from "../../selectors/layers.js";
+
+export function validateMarkOptions(args, supported, operation) {
+  for (const key of Object.keys(args)) {
+    if (!supported.includes(key)) {
+      throw new Error(`Unknown ${operation} option "${key}".`);
+    }
+  }
+}
+
+export function resolveMarkData(program, requested) {
+  const data = Object.hasOwn(requested, "data")
+    ? validateUserId(requested.data, "Dataset id")
+    : program.context.currentData;
+
+  if (data === undefined) {
+    throw new Error("Mark creation requires data or a current dataset.");
+  }
+
+  const dataset = findDataset(program, data);
+
+  if (dataset === undefined) {
+    throw new Error(`Unknown dataset "${data}".`);
+  }
+
+  return { data, dataset };
+}
+
+export function resolveMarkId(program, requested, {
+  defaultId,
+  label,
+  markType,
+  operation
+}) {
+  const sameRoleExists = program.semanticSpec.layers.some(
+    layer => layer.mark?.type === markType
+  );
+  const defaultUnavailable = hasLayer(program, defaultId) ||
+    program.graphicSpec.objects[defaultId] !== undefined;
+  return resolveOptionalUserId(requested, {
+    defaultId,
+    label,
+    operation,
+    ambiguous: sameRoleExists || defaultUnavailable
+  });
+}
+
+export function assertMarkAvailable(program, id) {
+  if (hasLayer(program, id)) {
+    throw new Error(`Mark "${id}" already exists.`);
+  }
+
+  if (program.graphicSpec.objects[id] !== undefined) {
+    throw new Error(`Graphic "${id}" already exists.`);
+  }
+}
+
+function inheritedPositionEncoding(encoding) {
+  if (encoding === undefined) return undefined;
+  return Object.fromEntries(
+    ["field", "datum", "fieldType", "scale", "title"]
+      .filter(property => Object.hasOwn(encoding, property))
+      .map(property => [property, encoding[property]])
+  );
+}
+
+function eligibleLayeredSource(layer, requestedData) {
+  if (layer?.data === undefined) return false;
+  if (requestedData !== undefined && layer.data !== requestedData) return false;
+  return layer.encoding?.x !== undefined || layer.encoding?.y !== undefined;
+}
+
+export function resolveLayeredMarkInheritance(program, requested = {}) {
+  const requestedData = Object.hasOwn(requested, "data")
+    ? validateUserId(requested.data, "Dataset id")
+    : undefined;
+  const eligible = program.semanticSpec.layers.filter(layer =>
+    eligibleLayeredSource(layer, requestedData)
+  );
+  const current = findLayer(program, program.context.currentMark);
+  const source = eligibleLayeredSource(current, requestedData)
+    ? current
+    : eligible.length === 1
+      ? eligible[0]
+      : undefined;
+
+  if (source === undefined && eligible.length > 1) {
+    throw new Error(
+      "Layered mark inference is ambiguous; specify data and encode its position explicitly."
+    );
+  }
+  if (source === undefined) return undefined;
+
+  return {
+    source: source.id,
+    data: source.data,
+    coordinate: source.coordinate,
+    encoding: Object.fromEntries(
+      ["x", "y"]
+        .map(channel => [
+          channel,
+          inheritedPositionEncoding(source.encoding?.[channel])
+        ])
+        .filter(([, encoding]) => encoding !== undefined)
+    )
+  };
+}

package/src/actions/primitives/createGraphics.js

@@ -0,0 +1,163 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { freezeOwned } from "../../core/immutable.js";
+import {
+  isDrawableGraphicType,
+  isGraphicContainerType,
+  validateGraphicType
+} from "../../grammar/schemas/graphic.js";
+import {
+  findGraphicParent,
+  graphicSiblings
+} from "../../grammar/schemas/graphicTree.js";
+
+const GRAPHIC_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+
+function createGraphicDefinition({ id, type, length }) {
+  if (type === "collection") {
+    return freezeOwned({ type, items: freezeOwned([]) });
+  }
+  if (length === undefined) {
+    return freezeOwned({ type, properties: freezeOwned({}) });
+  }
+  return freezeOwned({
+    type,
+    items: freezeOwned(Array.from({ length }, (_, index) => freezeOwned({
+      id: `${id}:${index}`,
+      properties: freezeOwned({})
+    }))),
+  });
+}
+
+function sameDefinition(existing, { type, length }) {
+  if (existing.type !== type) return false;
+  if (type === "collection") return length === undefined && existing.items?.length === 0;
+  if (length === undefined) return existing.items === undefined;
+  return existing.items?.length === length;
+}
+
+function samePlacement(graphicSpec, id, { parent, before, after }) {
+  const actualParent = findGraphicParent(graphicSpec, id);
+  const actualParentId = actualParent?.kind === "parent" ? actualParent.id : undefined;
+  if (actualParentId !== parent) return false;
+  const siblings = graphicSiblings(graphicSpec, id);
+  const index = siblings.indexOf(id);
+  if (before !== undefined) return index < siblings.indexOf(before);
+  if (after !== undefined) return index > siblings.indexOf(after);
+  return true;
+}
+
+function resolvePlacement(graphicSpec, { id, type, parent, before, after }) {
+  if (before !== undefined && after !== undefined) {
+    throw new Error("createGraphics cannot use before and after together.");
+  }
+  if (parent !== undefined) {
+    validateUserId(parent, "Graphic parent");
+    if (parent === id) throw new Error("createGraphics cannot attach a graphic to itself.");
+    const parentGraphic = graphicSpec.objects[parent];
+    if (parentGraphic === undefined) {
+      throw new Error(`Unknown graphic parent "${parent}".`);
+    }
+    if (!isGraphicContainerType(parentGraphic.type)) {
+      throw new Error(`Graphic parent "${parent}" must be a canvas or collection.`);
+    }
+    if (type === "canvas") {
+      throw new Error("Canvas graphics cannot have a parent.");
+    }
+  }
+  const anchor = before ?? after;
+  if (anchor === undefined) return;
+  validateUserId(anchor, "Graphic placement target");
+  if (anchor === id) {
+    throw new Error("createGraphics cannot place a graphic relative to itself.");
+  }
+  const anchorGraphic = graphicSpec.objects[anchor];
+  if (anchorGraphic === undefined) {
+    throw new Error(`Unknown graphic placement target "${anchor}".`);
+  }
+  const anchorParent = findGraphicParent(graphicSpec, anchor);
+  const anchorParentId = anchorParent?.kind === "parent" ? anchorParent.id : undefined;
+  if (anchorParentId !== parent) {
+    throw new Error("Graphic placement target must be a direct sibling.");
+  }
+  if (parent === undefined && before === "canvas") {
+    throw new Error("createGraphics cannot place a graphic before the canvas.");
+  }
+  if (type === "canvas") {
+    throw new Error("Canvas graphics do not accept before or after placement.");
+  }
+}
+
+function insertSibling(siblings, id, { before, after }) {
+  const next = [...siblings];
+  if (before !== undefined) next.splice(next.indexOf(before), 0, id);
+  else if (after !== undefined) next.splice(next.indexOf(after) + 1, 0, id);
+  else next.push(id);
+  return freezeOwned(next);
+}
+
+const createGraphics = action(
+  {
+    op: "createGraphics",
+    description: "Create and optionally attach a concrete graphic."
+  },
+  function ({ id, type, length, parent, before, after } = {}) {
+    if (typeof id !== "string" || !GRAPHIC_ID_PATTERN.test(id)) {
+      throw new TypeError(
+        "createGraphics requires an id containing only letters, numbers, _ or -."
+      );
+    }
+    const validatedType = validateGraphicType(type);
+    if (length !== undefined && (!Number.isInteger(length) || length < 0)) {
+      throw new TypeError("createGraphics length must be a non-negative integer.");
+    }
+    if (validatedType === "collection" && length !== undefined) {
+      throw new Error("Heterogeneous collections use editGraphics items instead of length.");
+    }
+    if (length !== undefined && !isDrawableGraphicType(validatedType)) {
+      throw new Error(`Graphic type "${validatedType}" does not accept length.`);
+    }
+    resolvePlacement(this.graphicSpec, {
+      id, type: validatedType, parent, before, after
+    });
+
+    const existing = this.graphicSpec.objects[id];
+    if (existing !== undefined) {
+      if (
+        sameDefinition(existing, { type: validatedType, length }) &&
+        samePlacement(this.graphicSpec, id, { parent, before, after })
+      ) return this;
+      throw new Error(`Graphic "${id}" already exists with a different definition or placement.`);
+    }
+    if (
+      validatedType === "canvas" &&
+      Object.values(this.graphicSpec.objects).some(graphic => graphic.type === "canvas")
+    ) {
+      throw new Error("graphicSpec supports exactly one canvas.");
+    }
+
+    const objects = {
+      ...this.graphicSpec.objects,
+      [id]: createGraphicDefinition({ id, type: validatedType, length })
+    };
+    let order = this.graphicSpec.order;
+    if (parent === undefined) {
+      order = insertSibling(order, id, { before, after });
+    } else {
+      objects[parent] = freezeOwned({
+        ...objects[parent],
+        children: insertSibling(objects[parent].children ?? [], id, { before, after })
+      });
+    }
+    return this._clone({
+      graphicSpec: freezeOwned({
+        objects: freezeOwned(objects),
+        order
+      })
+    });
+  }
+);
+
+export function registerCreateGraphicsAction(ProgramClass) {
+  ProgramClass.prototype.createGraphics = createGraphics;
+}