ggaction 0.0.1

package/src/actions/guides/grids/resolve.js

@@ -0,0 +1,258 @@
+import { validateUserId } from "../../../core/identifiers.js";
+import { isPlainObject } from "../../../core/immutable.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite
+} from "../../../core/validation.js";
+import {
+  isTransformedScaleType,
+  mapContinuousScaleValues
+} from "../../../grammar/scales.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { resolveGridLineGeometry } from "../../../layout/grid.js";
+import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
+import {
+  inferGridTickConfig,
+  valuesFromTickConfig
+} from "../tickValues.js";
+import {
+  findGraphicParent,
+  walkGraphicDrawOrder
+} from "../../../grammar/schemas/graphicTree.js";
+
+const GRID_OPTIONS = Object.freeze([
+  "scale", "coordinate", "count", "values", "color", "lineWidth", "strokeDash"
+]);
+const GRID_EDIT_OPTIONS = Object.freeze([
+  "count", "values", "color", "lineWidth", "strokeDash"
+]);
+const DEFAULT_STYLE = Object.freeze({
+  color: DEFAULT_COLORS.grid,
+  lineWidth: 1,
+  strokeDash: Object.freeze([])
+});
+
+export function gridNames(direction) {
+  const prefix = direction === "horizontal" ? "Horizontal" : "Vertical";
+  return {
+    channel: direction === "horizontal" ? "y" : "x",
+    create: `create${prefix}Grid`,
+    rematerialize: `rematerialize${prefix}Grid`,
+    graphic: `${direction}GridLines`
+  };
+}
+
+function validateStrokeDash(value) {
+  if (
+    !Array.isArray(value) ||
+    value.length % 2 !== 0 ||
+    !value.every(item => Number.isFinite(item) && item >= 0)
+  ) {
+    throw new TypeError(
+      "Grid strokeDash must be an even-length array of non-negative finite numbers."
+    );
+  }
+  return value;
+}
+
+export function validateGridCreateArgs(args, operation) {
+  if (!isPlainObject(args)) {
+    throw new TypeError(`${operation} options must be a plain object.`);
+  }
+  validateKeys(args, GRID_OPTIONS, operation);
+  if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) {
+    throw new Error(`${operation} cannot use count and values together.`);
+  }
+  if (Object.hasOwn(args, "count") && (!Number.isInteger(args.count) || args.count <= 0)) {
+    throw new RangeError("Grid count must be a positive integer.");
+  }
+  if (Object.hasOwn(args, "values") && (
+    !Array.isArray(args.values) ||
+    args.values.length === 0 ||
+    !args.values.every(Number.isFinite)
+  )) {
+    throw new TypeError("Grid values must be a non-empty finite number array.");
+  }
+  if (Object.hasOwn(args, "color")) {
+    validateNonEmptyString(args.color, "Grid color");
+  }
+  if (Object.hasOwn(args, "lineWidth")) {
+    validateNonNegativeFinite(args.lineWidth, "Grid lineWidth");
+  }
+  if (Object.hasOwn(args, "strokeDash")) validateStrokeDash(args.strokeDash);
+}
+
+export function validateGridEditArgs(args, operation) {
+  if (!isPlainObject(args)) {
+    throw new TypeError(`${operation} options must be a plain object.`);
+  }
+  validateKeys(args, GRID_EDIT_OPTIONS, operation);
+  if (Object.keys(args).length === 0) {
+    throw new TypeError(`${operation} requires at least one option.`);
+  }
+  if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) {
+    throw new Error(`${operation} cannot use count and values together.`);
+  }
+  if (Object.hasOwn(args, "count") && (
+    !Number.isInteger(args.count) || args.count <= 0
+  )) {
+    throw new RangeError("Grid count must be a positive integer.");
+  }
+  if (Object.hasOwn(args, "values") && args.values !== "auto" && (
+    !Array.isArray(args.values) ||
+    args.values.length === 0 ||
+    !args.values.every(Number.isFinite)
+  )) {
+    throw new TypeError(
+      'Grid values must be "auto" or a non-empty finite number array.'
+    );
+  }
+  if (Object.hasOwn(args, "color")) {
+    validateNonEmptyString(args.color, "Grid color");
+  }
+  if (Object.hasOwn(args, "lineWidth")) {
+    validateNonNegativeFinite(args.lineWidth, "Grid lineWidth");
+  }
+  if (Object.hasOwn(args, "strokeDash")) validateStrokeDash(args.strokeDash);
+}
+
+export function resolveGridResources(program, direction, args) {
+  const { channel } = gridNames(direction);
+  let layers = program.semanticSpec.layers.filter(
+    layer => layer.encoding?.[channel]?.scale !== undefined
+  );
+  if (layers.length === 0) throw new Error(`${direction} grid requires a ${channel} encoding.`);
+  const requestedCoordinate = args.coordinate === undefined
+    ? undefined
+    : validateUserId(args.coordinate, "Grid coordinate id");
+  const requestedScale = args.scale === undefined
+    ? undefined
+    : validateUserId(args.scale, "Grid scale id");
+  if (requestedCoordinate !== undefined) {
+    layers = layers.filter(layer => layer.coordinate === requestedCoordinate);
+  }
+  if (requestedScale !== undefined) {
+    layers = layers.filter(layer => layer.encoding[channel].scale === requestedScale);
+  }
+  if (layers.length === 0) throw new Error(`${direction} grid found no matching encoded layers.`);
+  const coordinateIds = [...new Set(layers.map(layer => layer.coordinate).filter(Boolean))];
+  if (layers.some(layer => layer.coordinate === undefined)) {
+    throw new Error(`${direction} grid requires a stored coordinate.`);
+  }
+  if (coordinateIds.length === 0) throw new Error(`Unknown grid coordinate "${requestedCoordinate}".`);
+  if (coordinateIds.length > 1) {
+    throw new Error(`${direction} grid found multiple coordinates; provide coordinate explicitly.`);
+  }
+  const coordinate = requestedCoordinate ?? coordinateIds[0];
+  const definition = findCoordinate(program, coordinate);
+  if (definition?.type !== "cartesian") {
+    throw new Error(`${direction} grid requires a Cartesian coordinate.`);
+  }
+  const scaleIds = [...new Set(layers.map(layer => layer.encoding[channel].scale))];
+  if (scaleIds.length === 0) throw new Error(`Unknown grid scale "${requestedScale}".`);
+  if (scaleIds.length > 1) {
+    throw new Error(`${direction} grid found multiple ${channel} scales; provide scale explicitly.`);
+  }
+  const scale = requestedScale ?? scaleIds[0];
+  if (
+    !["linear", "time"].includes(program.resolvedScales[scale]?.type) &&
+    !isTransformedScaleType(program.resolvedScales[scale]?.type)
+  ) {
+    throw new Error(`${direction} grid requires resolved continuous scale "${scale}".`);
+  }
+  const related = new Set(layers.map(layer => layer.id));
+  let before;
+  walkGraphicDrawOrder(program.graphicSpec, ({ id }) => {
+    if (before === undefined && related.has(id)) before = id;
+  });
+  if (before === undefined) throw new Error(`${direction} grid requires related mark graphics.`);
+  const owner = findGraphicParent(program.graphicSpec, before);
+  return {
+    channel,
+    coordinate,
+    scale,
+    before,
+    ...(owner?.kind === "parent" ? { parent: owner.id } : {})
+  };
+}
+
+export function resolveGridConfig(program, direction, args, resources) {
+  const hasExplicitValues = Object.hasOwn(args, "values") ||
+    Object.hasOwn(args, "count");
+  const explicit = Object.hasOwn(args, "values")
+    ? { mode: "values", values: args.values }
+    : Object.hasOwn(args, "count")
+      ? { mode: "count", count: args.count }
+      : inferGridTickConfig(program, resources.channel, resources.scale);
+  return {
+    direction,
+    scale: resources.scale,
+    coordinate: resources.coordinate,
+    ...explicit,
+    inferredValues: !hasExplicitValues,
+    color: args.color ?? DEFAULT_STYLE.color,
+    lineWidth: args.lineWidth ?? DEFAULT_STYLE.lineWidth,
+    strokeDash: args.strokeDash ?? DEFAULT_STYLE.strokeDash
+  };
+}
+
+export function refreshGridConfig(program, config) {
+  if (config.inferredValues !== true) return config;
+  const channel = config.direction === "horizontal" ? "y" : "x";
+  const refreshed = {
+    ...config,
+    ...inferGridTickConfig(program, channel, config.scale)
+  };
+  if (refreshed.mode === "values") delete refreshed.count;
+  else delete refreshed.values;
+  return refreshed;
+}
+
+export function editGridConfig(previous, args) {
+  const config = {
+    ...previous,
+    ...Object.fromEntries(
+      Object.entries(args).filter(([key]) => !["count", "values"].includes(key))
+    )
+  };
+  if (Object.hasOwn(args, "count")) {
+    config.mode = "count";
+    config.count = args.count;
+    config.inferredValues = false;
+    delete config.values;
+  } else if (Array.isArray(args.values)) {
+    config.mode = "values";
+    config.values = args.values;
+    config.inferredValues = false;
+    delete config.count;
+  } else if (args.values === "auto") {
+    config.inferredValues = true;
+  }
+  return config;
+}
+
+export function resolveGridGeometry(program, config) {
+  const scale = program.resolvedScales[config.scale];
+  const bounds = resolveGraphicBounds(program);
+  if ((
+    !["linear", "time"].includes(scale?.type) &&
+    !isTransformedScaleType(scale?.type)
+  ) || bounds === undefined) {
+    throw new Error("Grid materialization requires a continuous scale and Canvas bounds.");
+  }
+  const values = valuesFromTickConfig(program, config);
+  const low = Math.min(...scale.domain);
+  const high = Math.max(...scale.domain);
+  if (!values.every(value => value >= low && value <= high)) {
+    throw new RangeError("Grid values must be inside the scale domain.");
+  }
+  const positions = mapContinuousScaleValues(values, scale);
+  return resolveGridLineGeometry({
+    direction: config.direction,
+    values,
+    positions,
+    bounds
+  });
+}

package/src/actions/guides/guides.js

@@ -0,0 +1,138 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  BAR_ORIENTATIONS,
+  resolveBarOrientation
+} from "../../grammar/bars/policy.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+
+const OPTIONS = Object.freeze(["axes", "grid", "legend"]);
+
+function validateGuideOption(value, label) {
+  if (value !== undefined && value !== false && !isPlainObject(value)) {
+    throw new TypeError(`${label} must be false or a plain object.`);
+  }
+}
+
+function validateOptions(args) {
+  if (!isPlainObject(args)) {
+    throw new TypeError("createGuides options must be a plain object.");
+  }
+  for (const key of Object.keys(args)) {
+    if (!OPTIONS.includes(key)) {
+      throw new Error(`Unknown createGuides option "${key}".`);
+    }
+  }
+  validateGuideOption(args.axes, "createGuides axes");
+  validateGuideOption(args.grid, "createGuides grid");
+  validateGuideOption(args.legend, "createGuides legend");
+}
+
+function hasCartesianEncoding(program) {
+  return program.semanticSpec.layers.some(
+    layer => layer.encoding?.x !== undefined || layer.encoding?.y !== undefined
+  );
+}
+
+function hasGridEncoding(program) {
+  return program.semanticSpec.layers.some(
+    layer => layer.encoding?.x?.scale !== undefined ||
+      layer.encoding?.y?.scale !== undefined
+  );
+}
+
+function inferGridOptions(program) {
+  const barOrientations = program.semanticSpec.layers
+    .map(resolveBarOrientation)
+    .filter(Boolean);
+  const positionedLayers = program.semanticSpec.layers.filter(
+    layer => layer.encoding?.x !== undefined && layer.encoding?.y !== undefined
+  );
+  const horizontalQuantitative = positionedLayers.length > 0 &&
+    positionedLayers.every(layer =>
+      layer.encoding.x.fieldType === "quantitative" &&
+      ["nominal", "ordinal", "temporal"].includes(layer.encoding.y.fieldType)
+    );
+  if (
+    horizontalQuantitative ||
+    (barOrientations.length > 0 &&
+      barOrientations.every(value => value === BAR_ORIENTATIONS.horizontal))
+  ) {
+    return { horizontal: false, vertical: true };
+  }
+  return { horizontal: true, vertical: false };
+}
+
+function inferAxesOptions(program) {
+  const horizontalInterval = program.semanticSpec.layers.some(layer =>
+    layer.mark?.type === "rule" &&
+    layer.encoding?.x?.fieldType === "quantitative" &&
+    layer.encoding?.x2?.fieldType === "quantitative" &&
+    ["nominal", "ordinal", "temporal"].includes(layer.encoding?.y?.fieldType)
+  );
+  return horizontalInterval
+    ? { x: { ticksAndLabels: { count: 7 } } }
+    : {};
+}
+
+function hasLegendEncoding(program) {
+  return program.semanticSpec.layers.some(
+    layer =>
+      (layer.mark?.type === "point" &&
+        layer.encoding?.opacity?.scale !== undefined) ||
+      (layer.mark?.type === "point" &&
+        layer.encoding?.color?.scale !== undefined &&
+        (layer.encoding?.shape?.scale !== undefined ||
+          ["sequential", "quantize", "quantile", "threshold"].includes(
+            findSemanticScale(program, layer.encoding.color.scale)?.type
+          ))) ||
+      (layer.mark?.type === "line" &&
+        ["color", "strokeDash"].some(
+          channel => layer.encoding?.[channel]?.scale !== undefined
+        )) ||
+      (layer.mark?.type === "bar" &&
+        layer.encoding?.color?.scale !== undefined) ||
+      (layer.mark?.type === "area" &&
+        layer.encoding?.color?.scale !== undefined)
+  );
+}
+
+function selectOption(explicit, applicable) {
+  if (explicit === false) return undefined;
+  if (explicit !== undefined) return explicit;
+  return applicable ? {} : undefined;
+}
+
+const createGuides = action(
+  {
+    op: "createGuides",
+    description: "Create applicable axes, grid, and legend."
+  },
+  function (args = {}) {
+    validateOptions(args);
+    const axes = args.axes === undefined && hasCartesianEncoding(this)
+      ? inferAxesOptions(this)
+      : selectOption(args.axes, hasCartesianEncoding(this));
+    const grid = args.grid === undefined && hasGridEncoding(this)
+      ? inferGridOptions(this)
+      : selectOption(args.grid, hasGridEncoding(this));
+    const legend = selectOption(
+      args.legend,
+      hasLegendEncoding(this)
+    );
+
+    if (axes === undefined && grid === undefined && legend === undefined) {
+      throw new Error("createGuides requires at least one selected guide.");
+    }
+
+    let next = this;
+    if (axes !== undefined) next = next.createAxes(axes);
+    if (grid !== undefined) next = next.createGrid(grid);
+    if (legend !== undefined) next = next.createLegend(legend);
+    return next;
+  }
+);
+
+export function registerGuideCollectionActions(ProgramClass) {
+  ProgramClass.prototype.createGuides = createGuides;
+}

package/src/actions/guides/index.js

@@ -0,0 +1,11 @@
+import { registerGuideAxisActions } from "./axes/index.js";
+import { registerGuideCollectionActions } from "./guides.js";
+import { registerGridActions } from "./grids/index.js";
+import { registerLegendActions } from "./legends/index.js";
+
+export function registerGuideActions(ProgramClass) {
+  registerGuideAxisActions(ProgramClass);
+  registerLegendActions(ProgramClass);
+  registerGridActions(ProgramClass);
+  registerGuideCollectionActions(ProgramClass);
+}