ggaction 0.0.1

package/src/materialization/selection/policies/index.js

@@ -0,0 +1,40 @@
+import { findDataset } from "../../../selectors/datasets.js";
+import { requireLayer } from "../../../selectors/layers.js";
+import { areaSelectionPolicy } from "./area.js";
+import { barSelectionPolicy } from "./bar.js";
+import { lineSelectionPolicy } from "./line.js";
+import { pointSelectionPolicy } from "./point.js";
+import { ruleSelectionPolicy } from "./rule.js";
+
+const POLICIES = Object.freeze({
+  area: areaSelectionPolicy,
+  bar: barSelectionPolicy,
+  line: lineSelectionPolicy,
+  point: pointSelectionPolicy,
+  rule: ruleSelectionPolicy
+});
+
+export function findSelectionPolicy(markType) {
+  return POLICIES[markType];
+}
+
+export function requireSelectionPolicy(markType) {
+  const policy = findSelectionPolicy(markType);
+  if (policy === undefined) {
+    throw new Error(`Mark type "${markType}" has no selection policy.`);
+  }
+  return policy;
+}
+
+export function resolveMarkItems(program, target, grain = "item") {
+  const layer = requireLayer(program, target, `Unknown mark target "${target}"`);
+  const dataset = findDataset(program, layer.data);
+  if (dataset === undefined) {
+    throw new Error(`Mark "${target}" requires an existing dataset for selection.`);
+  }
+  const policy = requireSelectionPolicy(layer.mark?.type);
+  if (!policy.supportedGrains.includes(grain)) {
+    throw new Error(`Mark "${target}" does not support ${grain} selection grain.`);
+  }
+  return policy.resolveItems(program, layer, dataset, grain);
+}

package/src/materialization/selection/policies/line.js

@@ -0,0 +1,10 @@
+import { resolveLineItems } from "../items.js";
+import { normalizeStrokeHighlightStyle } from "../styles.js";
+
+export const lineSelectionPolicy = Object.freeze({
+  supportedGrains: Object.freeze(["item"]),
+  resolveItems: resolveLineItems,
+  normalizeHighlightStyle: args => normalizeStrokeHighlightStyle(args, "Line"),
+  applyHighlightOp: "applyPathHighlight",
+  rematerializeOp: "rematerializeLineMark"
+});

package/src/materialization/selection/policies/point.js

@@ -0,0 +1,10 @@
+import { resolvePointItems } from "../items.js";
+import { normalizePointHighlightStyle } from "../styles.js";
+
+export const pointSelectionPolicy = Object.freeze({
+  supportedGrains: Object.freeze(["item"]),
+  resolveItems: resolvePointItems,
+  normalizeHighlightStyle: normalizePointHighlightStyle,
+  applyHighlightOp: "applyPointHighlight",
+  rematerializeOp: "rematerializePointMark"
+});

package/src/materialization/selection/policies/rule.js

@@ -0,0 +1,10 @@
+import { resolveRuleItems } from "../items.js";
+import { normalizeStrokeHighlightStyle } from "../styles.js";
+
+export const ruleSelectionPolicy = Object.freeze({
+  supportedGrains: Object.freeze(["item"]),
+  resolveItems: resolveRuleItems,
+  normalizeHighlightStyle: args => normalizeStrokeHighlightStyle(args, "Rule"),
+  applyHighlightOp: "applyRuleHighlight",
+  rematerializeOp: "rematerializeRuleMark"
+});

package/src/materialization/selection/state.js

@@ -0,0 +1,67 @@
+import { validateUserId } from "../../core/identifiers.js";
+import { normalizeMarkSelector, selectMarkItemKeys } from "../../grammar/markSelection.js";
+import { resolveMarkItems } from "./policies/index.js";
+
+export function resolveMarkSelection(program, target, selector) {
+  const normalized = normalizeMarkSelector(selector);
+  const items = resolveMarkItems(program, target, normalized.grain);
+  if (items.length > 0) {
+    const source = normalized.field !== undefined
+      ? "fields"
+      : normalized.channel !== undefined
+        ? "channels"
+        : "properties";
+    const kind = normalized.field !== undefined
+      ? "field"
+      : normalized.channel !== undefined
+        ? "channel"
+        : "graphic property";
+    const key = normalized.field ?? normalized.channel ?? normalized.property;
+    if (!items.some(item => Object.hasOwn(item[source], key))) {
+      throw new Error(
+        `Selection ${kind} "${key}" is not uniquely defined at the target ${normalized.grain} grain.`
+      );
+    }
+  }
+  return Object.freeze({
+    selector: normalized,
+    items,
+    keys: selectMarkItemKeys(items, normalized)
+  });
+}
+
+export function resolveSelectionCreationId(program, id, target) {
+  const resolved = validateUserId(
+    id ?? `${target}Selection`,
+    "Selection id"
+  );
+  if (program.materializationConfigs.selections?.[resolved] !== undefined) {
+    throw new Error(`Selection "${resolved}" already exists.`);
+  }
+  return resolved;
+}
+
+export function resolveStoredSelection(program, id) {
+  const selections = program.materializationConfigs.selections ?? {};
+  const requested = id ?? program.context.currentSelection;
+  const resolvedId = requested ?? (
+    Object.keys(selections).length === 1 ? Object.keys(selections)[0] : undefined
+  );
+  if (resolvedId === undefined) {
+    if (Object.keys(selections).length === 0) {
+      throw new Error("Selection resolution requires an existing selection.");
+    }
+    throw new Error("Selection is ambiguous; provide selection.");
+  }
+  validateUserId(resolvedId, "Selection id");
+  const definition = selections[resolvedId];
+  if (definition === undefined) {
+    throw new Error(`Unknown selection "${resolvedId}".`);
+  }
+  const resolved = resolveMarkSelection(
+    program,
+    definition.target,
+    definition.selector
+  );
+  return Object.freeze({ id: resolvedId, definition, ...resolved });
+}

package/src/materialization/selection/styles.js

@@ -0,0 +1,183 @@
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validatePositiveFinite,
+  validateUnitInterval
+} from "../../core/validation.js";
+import { validatePointShape } from "../../grammar/pointShapes.js";
+import { normalizeStrokeDashPattern } from "../../grammar/scales.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+
+const DEFAULT_POINT_SIZE = 2;
+const DEFAULT_DIM_OPACITY = 0.25;
+
+export { validateUnitInterval };
+
+function normalizeOffset(offset) {
+  if (offset === undefined) return { x: 0, y: 0 };
+  if (!isPlainObject(offset)) {
+    throw new TypeError("Highlight offset must be a plain object.");
+  }
+  validateKeys(offset, ["x", "y"], "highlight offset");
+  const x = offset.x ?? 0;
+  const y = offset.y ?? 0;
+  if (!Number.isFinite(x) || !Number.isFinite(y)) {
+    throw new TypeError("Highlight offset x and y must be finite numbers.");
+  }
+  return { x, y };
+}
+
+export function normalizeDimOthers(dimOthers) {
+  if (dimOthers === undefined || dimOthers === false) return false;
+  if (dimOthers === true) return { opacity: DEFAULT_DIM_OPACITY };
+  if (!isPlainObject(dimOthers)) {
+    throw new TypeError("Highlight dimOthers must be a boolean or plain object.");
+  }
+  validateKeys(dimOthers, ["opacity"], "highlight dimOthers");
+  return {
+    opacity: validateUnitInterval(
+      dimOthers.opacity ?? DEFAULT_DIM_OPACITY,
+      "Highlight dim opacity"
+    )
+  };
+}
+
+export function normalizePointHighlightStyle(args) {
+  if (args.color !== undefined && args.fill !== undefined) {
+    throw new Error("Point highlight accepts color or fill, not both.");
+  }
+  if (args.strokeDash !== undefined) {
+    throw new Error("Point highlight does not support strokeDash.");
+  }
+  const fill = validateNonEmptyString(
+    args.fill ?? args.color ?? DEFAULT_COLORS.highlight,
+    "Point highlight fill"
+  );
+  const opacity = args.opacity === undefined
+    ? undefined
+    : validateUnitInterval(args.opacity, "Point highlight opacity");
+  const stroke = args.stroke === undefined
+    ? undefined
+    : validateNonEmptyString(args.stroke, "Point highlight stroke");
+  const strokeWidth = args.strokeWidth === undefined
+    ? undefined
+    : validateNonNegativeFinite(args.strokeWidth, "Point highlight strokeWidth");
+  if (strokeWidth !== undefined && stroke === undefined) {
+    throw new Error("Point highlight strokeWidth requires stroke.");
+  }
+  return {
+    fill,
+    ...(opacity === undefined ? {} : { opacity }),
+    ...(stroke === undefined ? {} : { stroke }),
+    ...(strokeWidth === undefined ? {} : { strokeWidth }),
+    ...(args.shape === undefined ? {} : { shape: validatePointShape(args.shape) }),
+    size: args.size === undefined
+      ? DEFAULT_POINT_SIZE
+      : validatePositiveFinite(args.size, "Point highlight size"),
+    offset: normalizeOffset(args.offset)
+  };
+}
+
+export function normalizeBarHighlightStyle(args) {
+  for (const option of ["shape", "size", "offset", "strokeDash"]) {
+    if (args[option] !== undefined) {
+      throw new Error(`Bar highlight does not support ${option}.`);
+    }
+  }
+  if (args.color !== undefined && args.fill !== undefined) {
+    throw new Error("Bar highlight accepts color or fill, not both.");
+  }
+  const fill = validateNonEmptyString(
+    args.fill ?? args.color ?? DEFAULT_COLORS.highlight,
+    "Bar highlight fill"
+  );
+  const opacity = args.opacity === undefined
+    ? undefined
+    : validateUnitInterval(args.opacity, "Bar highlight opacity");
+  const stroke = args.stroke === undefined
+    ? undefined
+    : validateNonEmptyString(args.stroke, "Bar highlight stroke");
+  const strokeWidth = args.strokeWidth === undefined
+    ? undefined
+    : validateNonNegativeFinite(args.strokeWidth, "Bar highlight strokeWidth");
+  if (strokeWidth !== undefined && stroke === undefined) {
+    throw new Error("Bar highlight strokeWidth requires stroke.");
+  }
+  return {
+    fill,
+    ...(opacity === undefined ? {} : { opacity }),
+    ...(stroke === undefined ? {} : { stroke }),
+    ...(strokeWidth === undefined ? {} : { strokeWidth })
+  };
+}
+
+function rejectHighlightOptions(args, mark, options) {
+  for (const option of options) {
+    if (args[option] !== undefined) {
+      throw new Error(`${mark} highlight does not support ${option}.`);
+    }
+  }
+}
+
+export function normalizeStrokeHighlightStyle(args, mark) {
+  rejectHighlightOptions(args, mark, ["fill", "shape", "size"]);
+  if (args.color !== undefined && args.stroke !== undefined) {
+    throw new Error(`${mark} highlight accepts color or stroke, not both.`);
+  }
+  return {
+    stroke: validateNonEmptyString(
+      args.stroke ?? args.color ?? DEFAULT_COLORS.highlight,
+      `${mark} highlight stroke`
+    ),
+    ...(args.strokeWidth === undefined
+      ? {}
+      : {
+          strokeWidth: validateNonNegativeFinite(
+            args.strokeWidth,
+            `${mark} highlight strokeWidth`
+          )
+        }),
+    ...(args.strokeDash === undefined
+      ? {}
+      : { strokeDash: normalizeStrokeDashPattern(args.strokeDash) }),
+    ...(args.opacity === undefined
+      ? {}
+      : {
+          opacity: validateUnitInterval(
+            args.opacity,
+            `${mark} highlight opacity`
+          )
+        }),
+    offset: normalizeOffset(args.offset)
+  };
+}
+
+export function normalizeAreaHighlightStyle(args) {
+  rejectHighlightOptions(args, "Area", ["shape", "size", "strokeDash"]);
+  if (args.color !== undefined && args.fill !== undefined) {
+    throw new Error("Area highlight accepts color or fill, not both.");
+  }
+  const stroke = args.stroke === undefined
+    ? undefined
+    : validateNonEmptyString(args.stroke, "Area highlight stroke");
+  const strokeWidth = args.strokeWidth === undefined
+    ? undefined
+    : validateNonNegativeFinite(args.strokeWidth, "Area highlight strokeWidth");
+  if (strokeWidth !== undefined && stroke === undefined) {
+    throw new Error("Area highlight strokeWidth requires stroke.");
+  }
+  return {
+    fill: validateNonEmptyString(
+      args.fill ?? args.color ?? DEFAULT_COLORS.highlight,
+      "Area highlight fill"
+    ),
+    ...(args.opacity === undefined
+      ? {}
+      : { opacity: validateUnitInterval(args.opacity, "Area highlight opacity") }),
+    ...(stroke === undefined ? {} : { stroke }),
+    ...(strokeWidth === undefined ? {} : { strokeWidth }),
+    offset: normalizeOffset(args.offset)
+  };
+}

package/src/renderers/canvas/circle.js

@@ -0,0 +1,62 @@
+import { requireFiniteProperty } from "./validation.js";
+import { validateConcreteGraphicProperties } from
+  "../../grammar/schemas/concreteGraphic.js";
+
+function drawCircle(context, child, collectionId) {
+  const properties = child.properties ?? {};
+  const graphicId = child.id ?? collectionId;
+  validateConcreteGraphicProperties("circle", properties);
+  const x = requireFiniteProperty(properties, "x", graphicId);
+  const y = requireFiniteProperty(properties, "y", graphicId);
+  const radius = requireFiniteProperty(properties, "radius", graphicId);
+
+  if (radius < 0) {
+    throw new Error(`Graphic "${graphicId}" requires a non-negative radius.`);
+  }
+
+  if (typeof properties.fill !== "string") {
+    throw new Error(`Graphic "${graphicId}" requires a string fill property.`);
+  }
+
+  const opacity = properties.opacity ?? 1;
+
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
+    throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
+  }
+
+  context.fillStyle = properties.fill;
+  context.globalAlpha = opacity;
+  context.beginPath();
+  context.arc(x, y, radius, 0, Math.PI * 2);
+  context.fill();
+  if (properties.stroke !== undefined) {
+    if (typeof properties.stroke !== "string") {
+      throw new Error(`Graphic "${graphicId}" requires a string stroke property.`);
+    }
+    const strokeWidth = requireFiniteProperty(
+      properties,
+      "strokeWidth",
+      graphicId
+    );
+    if (strokeWidth < 0) {
+      throw new Error(
+        `Graphic "${graphicId}" requires a non-negative strokeWidth.`
+      );
+    }
+    context.strokeStyle = properties.stroke;
+    context.lineWidth = strokeWidth;
+    context.setLineDash([]);
+    context.stroke();
+  }
+}
+
+export function drawCircleGraphic(context, id, graphic) {
+  if (graphic.items) {
+    for (const item of graphic.items) {
+      drawCircle(context, item, id);
+    }
+    return;
+  }
+
+  drawCircle(context, { id, properties: graphic.properties }, id);
+}

package/src/renderers/canvas/index.js

@@ -0,0 +1,132 @@
+import { drawCircleGraphic } from "./circle.js";
+import { drawLineGraphic } from "./line.js";
+import { drawPathGraphic } from "./path.js";
+import { drawRectGraphic } from "./rect.js";
+import { drawTextGraphic } from "./text.js";
+import { requireFiniteProperty } from "./validation.js";
+import { walkGraphicDrawOrder } from "../../grammar/schemas/graphicTree.js";
+
+const DRAWERS = Object.freeze({
+  circle: drawCircleGraphic,
+  rect: drawRectGraphic,
+  line: drawLineGraphic,
+  text: drawTextGraphic,
+  path: drawPathGraphic
+});
+
+function requireCanvasContext(context) {
+  const methods = [
+    "save",
+    "restore",
+    "clearRect",
+    "fillRect",
+    "beginPath",
+    "closePath",
+    "arc",
+    "fill",
+    "moveTo",
+    "lineTo",
+    "bezierCurveTo",
+    "setLineDash",
+    "stroke",
+    "translate",
+    "rotate",
+    "fillText",
+    "scale"
+  ];
+
+  if (context === null || typeof context !== "object" || !context.canvas) {
+    throw new TypeError("render requires a Canvas 2D context.");
+  }
+
+  for (const method of methods) {
+    if (typeof context[method] !== "function") {
+      throw new TypeError(`Canvas context is missing ${method}().`);
+    }
+  }
+}
+
+function findCanvas(graphicSpec) {
+  const canvasIds = graphicSpec.order.filter(
+    id => graphicSpec.objects[id]?.type === "canvas"
+  );
+
+  if (canvasIds.length !== 1) {
+    throw new Error("graphicSpec must contain exactly one ordered canvas.");
+  }
+
+  return { id: canvasIds[0], graphic: graphicSpec.objects[canvasIds[0]] };
+}
+
+export function render(program, context, { pixelRatio = 1 } = {}) {
+  const graphicSpec = program?.graphicSpec;
+
+  if (
+    graphicSpec === null ||
+    typeof graphicSpec !== "object" ||
+    graphicSpec.objects === null ||
+    typeof graphicSpec.objects !== "object" ||
+    !Array.isArray(graphicSpec.order)
+  ) {
+    throw new TypeError("render requires a program with a graphicSpec.");
+  }
+
+  requireCanvasContext(context);
+
+  if (!Number.isFinite(pixelRatio) || pixelRatio <= 0) {
+    throw new RangeError("render pixelRatio must be a positive finite number.");
+  }
+
+  const { id: canvasId, graphic: canvas } = findCanvas(graphicSpec);
+  const width = requireFiniteProperty(canvas.properties ?? {}, "width", canvasId);
+  const height = requireFiniteProperty(
+    canvas.properties ?? {},
+    "height",
+    canvasId
+  );
+
+  if (width < 0 || height < 0) {
+    throw new Error("Canvas width and height must not be negative.");
+  }
+
+  context.canvas.width = Math.round(width * pixelRatio);
+  context.canvas.height = Math.round(height * pixelRatio);
+  context.save();
+
+  try {
+    context.scale(pixelRatio, pixelRatio);
+    context.clearRect(0, 0, width, height);
+
+    if (canvas.properties.background !== undefined) {
+      if (typeof canvas.properties.background !== "string") {
+        throw new Error(
+          `Graphic "${canvasId}" requires a string background property.`
+        );
+      }
+
+      context.globalAlpha = 1;
+      context.fillStyle = canvas.properties.background;
+      context.fillRect(0, 0, width, height);
+    }
+
+    walkGraphicDrawOrder(graphicSpec, ({ id, object }) => {
+      if (id !== canvasId) drawConcreteGraphic(context, id, object);
+    });
+  } finally {
+    context.restore();
+  }
+}
+
+function drawConcreteGraphic(context, id, graphic) {
+  if (graphic.type === "collection") {
+    for (const item of graphic.items ?? []) {
+      drawConcreteGraphic(context, item.id ?? id, item);
+    }
+    return;
+  }
+  const draw = DRAWERS[graphic.type];
+  if (draw === undefined) {
+    throw new Error(`Canvas renderer does not support "${graphic.type}" yet.`);
+  }
+  draw(context, id, graphic);
+}

package/src/renderers/canvas/line.js

@@ -0,0 +1,54 @@
+import { requireFiniteProperty } from "./validation.js";
+import { validateConcreteGraphicProperties } from
+  "../../grammar/schemas/concreteGraphic.js";
+
+function drawLine(context, child, collectionId) {
+  const properties = child.properties ?? {};
+  const graphicId = child.id ?? collectionId;
+  validateConcreteGraphicProperties("line", properties);
+  const x1 = requireFiniteProperty(properties, "x1", graphicId);
+  const y1 = requireFiniteProperty(properties, "y1", graphicId);
+  const x2 = requireFiniteProperty(properties, "x2", graphicId);
+  const y2 = requireFiniteProperty(properties, "y2", graphicId);
+  const strokeWidth = requireFiniteProperty(
+    properties,
+    "strokeWidth",
+    graphicId
+  );
+
+  if (strokeWidth < 0) {
+    throw new Error(
+      `Graphic "${graphicId}" requires a non-negative strokeWidth.`
+    );
+  }
+
+  if (typeof properties.stroke !== "string") {
+    throw new Error(`Graphic "${graphicId}" requires a string stroke property.`);
+  }
+
+  const opacity = properties.opacity ?? 1;
+
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
+    throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
+  }
+
+  context.strokeStyle = properties.stroke;
+  context.lineWidth = strokeWidth;
+  context.globalAlpha = opacity;
+  context.setLineDash(properties.strokeDash ?? []);
+  context.beginPath();
+  context.moveTo(x1, y1);
+  context.lineTo(x2, y2);
+  context.stroke();
+}
+
+export function drawLineGraphic(context, id, graphic) {
+  if (graphic.items) {
+    for (const item of graphic.items) {
+      drawLine(context, item, id);
+    }
+    return;
+  }
+
+  drawLine(context, { id, properties: graphic.properties }, id);
+}

package/src/renderers/canvas/path.js

@@ -0,0 +1,98 @@
+import { requireFiniteProperty } from "./validation.js";
+import { validateConcreteGraphicProperties } from
+  "../../grammar/schemas/concreteGraphic.js";
+
+function drawPath(context, child, collectionId) {
+  const properties = child.properties ?? {};
+  const graphicId = child.id ?? collectionId;
+  validateConcreteGraphicProperties("path", properties);
+  const commands = properties.commands;
+
+  if (!Array.isArray(commands)) {
+    throw new Error(
+      `Graphic "${graphicId}" requires concrete path commands.`
+    );
+  }
+
+  const hasFill = properties.fill !== undefined;
+  const hasStroke = properties.stroke !== undefined;
+  if (!hasFill && !hasStroke) {
+    throw new Error(`Graphic "${graphicId}" requires a fill or stroke property.`);
+  }
+  if (hasFill && typeof properties.fill !== "string") {
+    throw new Error(`Graphic "${graphicId}" requires a string fill property.`);
+  }
+  if (hasFill && commands.at(-1).op !== "Z") {
+    throw new Error(`Graphic "${graphicId}" requires a final Z command when filled.`);
+  }
+  if (hasStroke && typeof properties.stroke !== "string") {
+    throw new Error(`Graphic "${graphicId}" requires a string stroke property.`);
+  }
+
+  const strokeWidth = hasStroke
+    ? requireFiniteProperty(properties, "strokeWidth", graphicId)
+    : undefined;
+  if (hasStroke && strokeWidth < 0) {
+    throw new Error(
+      `Graphic "${graphicId}" requires a non-negative strokeWidth.`
+    );
+  }
+
+  const strokeDash = properties.strokeDash ?? [];
+  if (
+    !Array.isArray(strokeDash) ||
+    !strokeDash.every(value => Number.isFinite(value) && value >= 0)
+  ) {
+    throw new Error(
+      `Graphic "${graphicId}" requires a non-negative finite strokeDash array.`
+    );
+  }
+
+  const opacity = properties.opacity ?? 1;
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) {
+    throw new Error(`Graphic "${graphicId}" requires opacity from 0 to 1.`);
+  }
+
+  context.globalAlpha = opacity;
+  context.beginPath();
+  for (const command of commands) {
+    if (command.op === "M") {
+      context.moveTo(command.x, command.y);
+    } else if (command.op === "L") {
+      context.lineTo(command.x, command.y);
+    } else if (command.op === "C") {
+      context.bezierCurveTo(
+        command.x1,
+        command.y1,
+        command.x2,
+        command.y2,
+        command.x,
+        command.y
+      );
+    } else {
+      context.closePath();
+    }
+  }
+
+  if (hasFill) {
+    context.fillStyle = properties.fill;
+    context.fill();
+  }
+  if (hasStroke) {
+    context.strokeStyle = properties.stroke;
+    context.lineWidth = strokeWidth;
+    context.setLineDash(strokeDash);
+    context.stroke();
+  }
+}
+
+export function drawPathGraphic(context, id, graphic) {
+  if (graphic.items) {
+    for (const item of graphic.items) {
+      drawPath(context, item, id);
+    }
+    return;
+  }
+
+  drawPath(context, { id, properties: graphic.properties }, id);
+}