ggaction 0.0.1

package/src/grammar/scales/validation.js

@@ -0,0 +1,66 @@
+import { cloneAndFreeze } from "../../core/immutable.js";
+import { POSITION_CHANNELS } from "../../core/vocabulary.js";
+import { validateCompleteScaleType } from "./types.js";
+
+export function validatePair(value, label) {
+  if (
+    !Array.isArray(value) ||
+    value.length !== 2 ||
+    !value.every(Number.isFinite)
+  ) {
+    throw new TypeError(`${label} must be "auto" or two finite numbers.`);
+  }
+  return cloneAndFreeze(value);
+}
+
+export function validatePositionChannel(channel) {
+  if (!POSITION_CHANNELS.includes(channel)) {
+    throw new Error(`Unknown position channel "${channel}".`);
+  }
+  return channel;
+}
+
+export function validateScaleType(type) {
+  return validateCompleteScaleType(type);
+}
+
+export function validateSemanticScaleType(type) {
+  return validateCompleteScaleType(type);
+}
+
+export function validateLinearScaleType(type) {
+  if (type !== "linear") {
+    throw new Error(`Unsupported position scale type "${type}".`);
+  }
+  return type;
+}
+
+export function validateTimeScaleType(type) {
+  if (type !== "time") {
+    throw new Error(`Unsupported temporal scale type "${type}".`);
+  }
+  return type;
+}
+
+export function validateOrdinalScaleType(type) {
+  if (type !== "ordinal") {
+    throw new Error(`Unsupported color scale type "${type}".`);
+  }
+  return type;
+}
+
+export function validateScaleDomain(domain) {
+  return domain === "auto" ? domain : validatePair(domain, "Scale domain");
+}
+
+export function validateScaleRange(range) {
+  return range === "auto" ? range : validatePair(range, "Scale range");
+}
+
+export function validateSemanticScaleDomain(domain) {
+  if (domain === "auto") return domain;
+  if (!Array.isArray(domain) || domain.length === 0) {
+    throw new TypeError("Scale domain must be \"auto\" or a non-empty array.");
+  }
+  return cloneAndFreeze(domain);
+}

package/src/grammar/scales.js

@@ -0,0 +1 @@
+export * from "./scales/index.js";

package/src/grammar/schemas/concreteGraphic.js

@@ -0,0 +1,73 @@
+import { isPlainObject } from "../../core/immutable.js";
+import { validatePathCommands } from "../pathCommands.js";
+import { validateGraphicProperty } from "./graphic.js";
+
+const FINITE_PROPERTIES = new Set([
+  "x", "y", "x1", "y1", "x2", "y2", "width", "height", "radius",
+  "strokeWidth", "fontSize", "rotation", "opacity", "gap"
+]);
+const NON_NEGATIVE_PROPERTIES = new Set([
+  "width", "height", "radius", "strokeWidth", "fontSize", "gap"
+]);
+const STRING_PROPERTIES = new Set([
+  "background", "fill", "stroke", "fontFamily", "text", "textAlign",
+  "textBaseline"
+]);
+const TEXT_ALIGNS = new Set(["left", "right", "center", "start", "end"]);
+const TEXT_BASELINES = new Set([
+  "top", "hanging", "middle", "alphabetic", "ideographic", "bottom"
+]);
+
+export function validateConcreteGraphicValue(type, property, value) {
+  if (FINITE_PROPERTIES.has(property) && !Number.isFinite(value)) {
+    throw new TypeError(`${type}.${property} must be a finite number.`);
+  }
+  if (NON_NEGATIVE_PROPERTIES.has(property) && value < 0) {
+    throw new RangeError(`${type}.${property} must not be negative.`);
+  }
+  if (type === "text" && property === "fontSize" && value === 0) {
+    throw new RangeError("text.fontSize must be positive.");
+  }
+  if (property === "opacity" && (value < 0 || value > 1)) {
+    throw new RangeError(`${type}.opacity must be between 0 and 1.`);
+  }
+  if (STRING_PROPERTIES.has(property) && (
+    typeof value !== "string" || value.length === 0
+  )) {
+    throw new TypeError(`${type}.${property} must be a non-empty string.`);
+  }
+  if (property === "fontWeight" && !(
+    (typeof value === "string" && value.length > 0) || Number.isFinite(value)
+  )) {
+    throw new TypeError("text.fontWeight must be a non-empty string or finite number.");
+  }
+  if (property === "textAlign" && !TEXT_ALIGNS.has(value)) {
+    throw new Error(`Unsupported text.textAlign "${value}".`);
+  }
+  if (property === "textBaseline" && !TEXT_BASELINES.has(value)) {
+    throw new Error(`Unsupported text.textBaseline "${value}".`);
+  }
+  if (property === "strokeDash" && (
+    !Array.isArray(value) ||
+    !value.every(item => Number.isFinite(item) && item >= 0)
+  )) {
+    throw new TypeError(
+      `${type}.strokeDash must be an array of non-negative finite numbers.`
+    );
+  }
+  if (type === "path" && property === "commands") {
+    validatePathCommands(value);
+  }
+  return value;
+}
+
+export function validateConcreteGraphicProperties(type, properties) {
+  if (!isPlainObject(properties)) {
+    throw new TypeError(`${type}.properties must be a plain object.`);
+  }
+  for (const [property, value] of Object.entries(properties)) {
+    validateGraphicProperty(type, property);
+    validateConcreteGraphicValue(type, property, value);
+  }
+  return properties;
+}

package/src/grammar/schemas/graphic.js

@@ -0,0 +1,131 @@
+const PRIMITIVE_DRAWABLE_TYPES = new Set([
+  "circle",
+  "rect",
+  "line",
+  "text",
+  "path"
+]);
+const DRAWABLE_TYPES = new Set([
+  ...PRIMITIVE_DRAWABLE_TYPES,
+  "collection"
+]);
+const STRUCTURAL_TYPES = new Set(["canvas"]);
+const GRAPHIC_PROPERTIES = Object.freeze({
+  canvas: new Set(["width", "height", "background"]),
+  collection: new Set([
+    "items",
+    "x",
+    "y",
+    "x1",
+    "y1",
+    "x2",
+    "y2",
+    "width",
+    "height",
+    "radius",
+    "fill",
+    "stroke",
+    "strokeWidth",
+    "strokeDash",
+    "fontSize",
+    "fontFamily",
+    "fontWeight",
+    "text",
+    "textAlign",
+    "textBaseline",
+    "rotation",
+    "commands",
+    "opacity"
+  ]),
+  circle: new Set([
+    "x",
+    "y",
+    "radius",
+    "fill",
+    "stroke",
+    "strokeWidth",
+    "opacity",
+    "length"
+  ]),
+  rect: new Set([
+    "x",
+    "y",
+    "width",
+    "height",
+    "fill",
+    "stroke",
+    "strokeWidth",
+    "opacity",
+    "length"
+  ]),
+  line: new Set([
+    "x1",
+    "y1",
+    "x2",
+    "y2",
+    "stroke",
+    "strokeWidth",
+    "strokeDash",
+    "opacity",
+    "length"
+  ]),
+  text: new Set([
+    "x",
+    "y",
+    "text",
+    "fill",
+    "fontSize",
+    "fontFamily",
+    "fontWeight",
+    "textAlign",
+    "textBaseline",
+    "rotation",
+    "opacity",
+    "length"
+  ]),
+  path: new Set([
+    "commands",
+    "fill",
+    "stroke",
+    "strokeWidth",
+    "strokeDash",
+    "opacity",
+    "length"
+  ])
+});
+
+export function validateGraphicType(type) {
+  if (!DRAWABLE_TYPES.has(type) && !STRUCTURAL_TYPES.has(type)) {
+    throw new Error(`Unknown graphic type "${type}".`);
+  }
+
+  return type;
+}
+
+export function isDrawableGraphicType(type) {
+  return DRAWABLE_TYPES.has(type);
+}
+
+export function isPrimitiveDrawableGraphicType(type) {
+  return PRIMITIVE_DRAWABLE_TYPES.has(type);
+}
+
+export function isStructuralGraphicType(type) {
+  return STRUCTURAL_TYPES.has(type);
+}
+
+export function isGraphicContainerType(type) {
+  return type === "canvas" || type === "collection";
+}
+
+export function validateGraphicProperty(type, property) {
+  if (typeof property !== "string" || property.length === 0) {
+    throw new TypeError("editGraphics requires a non-empty property string.");
+  }
+
+  if (!GRAPHIC_PROPERTIES[type]?.has(property)) {
+    throw new Error(`Unknown ${type} graphic property "${property}".`);
+  }
+
+  return property;
+}

package/src/grammar/schemas/graphicBounds.js

@@ -0,0 +1,146 @@
+import { measureTextWidth } from "../../core/textMetrics.js";
+import { findGraphic, requireGraphic } from "./graphicTree.js";
+
+function unionBounds(bounds) {
+  if (bounds.length === 0) return undefined;
+  return {
+    left: Math.min(...bounds.map(item => item.left)),
+    right: Math.max(...bounds.map(item => item.right)),
+    top: Math.min(...bounds.map(item => item.top)),
+    bottom: Math.max(...bounds.map(item => item.bottom))
+  };
+}
+
+function primitiveBounds(type, properties = {}) {
+  const strokeExtent = (properties.strokeWidth ?? 0) / 2;
+  if (type === "circle") {
+    if (![properties.x, properties.y, properties.radius].every(Number.isFinite)) {
+      return undefined;
+    }
+    const radius = properties.radius + strokeExtent;
+    return {
+      left: properties.x - radius,
+      right: properties.x + radius,
+      top: properties.y - radius,
+      bottom: properties.y + radius
+    };
+  }
+  if (type === "rect") {
+    if (![properties.x, properties.y, properties.width, properties.height]
+      .every(Number.isFinite)) return undefined;
+    return {
+      left: properties.x - strokeExtent,
+      right: properties.x + properties.width + strokeExtent,
+      top: properties.y - strokeExtent,
+      bottom: properties.y + properties.height + strokeExtent
+    };
+  }
+  if (type === "line") {
+    if (![properties.x1, properties.y1, properties.x2, properties.y2]
+      .every(Number.isFinite)) return undefined;
+    return {
+      left: Math.min(properties.x1, properties.x2) - strokeExtent,
+      right: Math.max(properties.x1, properties.x2) + strokeExtent,
+      top: Math.min(properties.y1, properties.y2) - strokeExtent,
+      bottom: Math.max(properties.y1, properties.y2) + strokeExtent
+    };
+  }
+  if (type === "text") {
+    if (
+      !Number.isFinite(properties.x) ||
+      !Number.isFinite(properties.y) ||
+      !Number.isFinite(properties.fontSize) ||
+      typeof properties.text !== "string"
+    ) return undefined;
+    const width = measureTextWidth(properties.text, properties);
+    const align = properties.textAlign ?? "left";
+    const left = align === "center" ? -width / 2 :
+      ["right", "end"].includes(align) ? -width : 0;
+    const baseline = properties.textBaseline ?? "alphabetic";
+    const [top, bottom] = baseline === "middle"
+      ? [-properties.fontSize / 2, properties.fontSize / 2]
+      : ["top", "hanging"].includes(baseline)
+        ? [0, properties.fontSize]
+        : ["bottom", "ideographic"].includes(baseline)
+          ? [-properties.fontSize, 0]
+          : [-properties.fontSize * 0.8, properties.fontSize * 0.2];
+    const rotation = properties.rotation ?? 0;
+    const cosine = Math.cos(rotation);
+    const sine = Math.sin(rotation);
+    const corners = [
+      [left, top],
+      [left + width, top],
+      [left + width, bottom],
+      [left, bottom]
+    ].map(([x, y]) => ({
+      x: properties.x + x * cosine - y * sine,
+      y: properties.y + x * sine + y * cosine
+    }));
+    return {
+      left: Math.min(...corners.map(point => point.x)),
+      right: Math.max(...corners.map(point => point.x)),
+      top: Math.min(...corners.map(point => point.y)),
+      bottom: Math.max(...corners.map(point => point.y))
+    };
+  }
+  if (type === "path") {
+    const commands = properties.commands;
+    if (!Array.isArray(commands)) return undefined;
+    const points = commands.flatMap(command => {
+      if (command.op === "M" || command.op === "L") return [{ x: command.x, y: command.y }];
+      if (command.op === "C") return [
+        { x: command.x1, y: command.y1 },
+        { x: command.x2, y: command.y2 },
+        { x: command.x, y: command.y }
+      ];
+      return [];
+    }).filter(point => Number.isFinite(point.x) && Number.isFinite(point.y));
+    if (points.length === 0) return undefined;
+    return {
+      left: Math.min(...points.map(point => point.x)) - strokeExtent,
+      right: Math.max(...points.map(point => point.x)) + strokeExtent,
+      top: Math.min(...points.map(point => point.y)) - strokeExtent,
+      bottom: Math.max(...points.map(point => point.y)) + strokeExtent
+    };
+  }
+  return undefined;
+}
+
+function objectBounds(graphicSpec, id, object, ancestors) {
+  if (ancestors.includes(id)) {
+    throw new Error(`Graphic attachment cycle includes "${id}".`);
+  }
+  const own = object.items === undefined
+    ? primitiveBounds(object.type, object.properties)
+    : unionBounds(object.items.flatMap(item => {
+        const bounds = primitiveBounds(item.type ?? object.type, item.properties);
+        return bounds === undefined ? [] : [bounds];
+      }));
+  const descendants = (object.children ?? []).flatMap(childId => {
+    const child = findGraphic(graphicSpec, childId);
+    if (child?.kind !== "object") {
+      throw new Error(`Unknown attached graphic "${childId}".`);
+    }
+    const bounds = objectBounds(graphicSpec, childId, child.object, [...ancestors, id]);
+    return bounds === undefined ? [] : [bounds];
+  });
+  return unionBounds([...(own === undefined ? [] : [own]), ...descendants]);
+}
+
+export function resolveConcreteGraphicBounds(graphicSpec, target) {
+  const found = requireGraphic(graphicSpec, target);
+  if (found.kind === "item") {
+    return primitiveBounds(found.object.type ?? found.owner.type, found.object.properties);
+  }
+  return objectBounds(graphicSpec, found.id, found.object, []);
+}
+
+export function unionConcreteGraphicBounds(graphicSpec, targets) {
+  if (!Array.isArray(targets)) {
+    throw new TypeError("Graphic bounds targets must be an array.");
+  }
+  return unionBounds(targets.flatMap(target => {
+    const bounds = resolveConcreteGraphicBounds(graphicSpec, target);
+    return bounds === undefined ? [] : [bounds];
+  }));
+}

package/src/grammar/schemas/graphicTree.js

@@ -0,0 +1,133 @@
+import { isPlainObject } from "../../core/immutable.js";
+
+function requireGraphicSpec(graphicSpec) {
+  if (
+    !isPlainObject(graphicSpec) ||
+    !isPlainObject(graphicSpec.objects) ||
+    !Array.isArray(graphicSpec.order)
+  ) {
+    throw new TypeError("A graphic tree requires objects and order.");
+  }
+  return graphicSpec;
+}
+
+export function findGraphic(graphicSpec, target) {
+  requireGraphicSpec(graphicSpec);
+  const object = graphicSpec.objects[target];
+  if (object !== undefined) {
+    return { id: target, object, kind: "object" };
+  }
+  for (const [ownerId, owner] of Object.entries(graphicSpec.objects)) {
+    const itemIndex = owner.items?.findIndex(item => item.id === target);
+    if (itemIndex !== undefined && itemIndex !== -1) {
+      return {
+        id: target,
+        object: owner.items[itemIndex],
+        kind: "item",
+        ownerId,
+        owner,
+        itemIndex
+      };
+    }
+  }
+  return undefined;
+}
+
+export function requireGraphic(graphicSpec, target) {
+  const found = findGraphic(graphicSpec, target);
+  if (found === undefined) {
+    throw new Error(`Unknown graphic target "${target}".`);
+  }
+  return found;
+}
+
+export function findGraphicParent(graphicSpec, target) {
+  requireGraphicSpec(graphicSpec);
+  const found = findGraphic(graphicSpec, target);
+  if (found?.kind === "item") {
+    return {
+      id: found.ownerId,
+      object: found.owner,
+      kind: "itemOwner",
+      index: found.itemIndex
+    };
+  }
+  for (const [id, candidate] of Object.entries(graphicSpec.objects)) {
+    const index = candidate.children?.indexOf(target);
+    if (index !== undefined && index !== -1) {
+      return { id, object: candidate, kind: "parent", index };
+    }
+  }
+  return undefined;
+}
+
+export function graphicSiblings(graphicSpec, target) {
+  const parent = findGraphicParent(graphicSpec, target);
+  if (parent?.kind === "parent") return parent.object.children;
+  if (parent?.kind === "itemOwner") {
+    return parent.object.items.map(item => item.id);
+  }
+  return graphicSpec.order;
+}
+
+function visitNamed(graphicSpec, id, visitor, path, visited) {
+  if (path.includes(id)) {
+    throw new Error(`Graphic attachment cycle includes "${id}".`);
+  }
+  const object = graphicSpec.objects[id];
+  if (object === undefined) {
+    throw new Error(`Unknown attached graphic "${id}".`);
+  }
+  if (visited.has(id)) {
+    throw new Error(`Graphic "${id}" is attached more than once.`);
+  }
+  visited.add(id);
+  visitor({ id, object, kind: "object", depth: path.length });
+  for (const item of object.items ?? []) {
+    visitor({
+      id: item.id,
+      object: item,
+      kind: "item",
+      ownerId: id,
+      depth: path.length + 1
+    });
+  }
+  for (const childId of object.children ?? []) {
+    visitNamed(graphicSpec, childId, visitor, [...path, id], visited);
+  }
+}
+
+export function walkGraphicTree(graphicSpec, visitor) {
+  requireGraphicSpec(graphicSpec);
+  if (typeof visitor !== "function") {
+    throw new TypeError("walkGraphicTree requires a visitor function.");
+  }
+  const visited = new Set();
+  for (const id of graphicSpec.order) {
+    visitNamed(graphicSpec, id, visitor, [], visited);
+  }
+  const orphan = Object.keys(graphicSpec.objects).find(id => !visited.has(id));
+  if (orphan !== undefined) {
+    throw new Error(`Graphic "${orphan}" is not attached to the graphic tree.`);
+  }
+}
+
+export function walkGraphicDrawOrder(graphicSpec, visitor) {
+  walkGraphicTree(graphicSpec, entry => {
+    if (entry.kind === "object") visitor(entry);
+  });
+}
+
+export function collectGraphicSubtreeIds(graphicSpec, target) {
+  const found = requireGraphic(graphicSpec, target);
+  if (found.kind === "item") {
+    throw new Error("Generated graphic items do not own named subtrees.");
+  }
+  const ids = [];
+  const visit = id => {
+    ids.push(id);
+    for (const childId of graphicSpec.objects[id].children ?? []) visit(childId);
+  };
+  visit(target);
+  return ids;
+}

package/src/grammar/schemas/mark.js

@@ -0,0 +1,4 @@
+export {
+  getPointGraphicType,
+  validatePointShape
+} from "../pointShapes.js";