ggaction 0.0.1

package/src/actions/errorBars/create.js

@@ -0,0 +1,144 @@
+import { action } from "../../core/action.js";
+import { validateKeys, validatePositiveFinite } from "../../core/validation.js";
+import {
+  normalizeStrokeDashPattern,
+  validateOpacityValue
+} from "../../grammar/scales.js";
+import {
+  validateRuleStroke,
+  validateRuleStrokeWidth
+} from "../../grammar/ruleAppearance.js";
+import { findLayer } from "../../selectors/layers.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { resolveErrorBar } from "./resolve.js";
+
+const OPTIONS = Object.freeze([
+  "id",
+  "target",
+  "data",
+  "x",
+  "y",
+  "groupBy",
+  "coordinate",
+  "caps",
+  "capSize",
+  "stroke",
+  "strokeWidth",
+  "strokeDash",
+  "opacity"
+]);
+
+function resolveAppearance(args) {
+  const caps = args.caps ?? true;
+  if (typeof caps !== "boolean") {
+    throw new TypeError("createErrorBar caps must be a boolean.");
+  }
+  const capSize = args.capSize ?? 8;
+  validatePositiveFinite(capSize, "createErrorBar capSize");
+  const stroke = validateRuleStroke(
+    args.stroke ?? DEFAULT_COLORS.mark,
+    "createErrorBar stroke"
+  );
+  const strokeWidth = validateRuleStrokeWidth(
+    args.strokeWidth ?? 1.5,
+    "createErrorBar strokeWidth"
+  );
+  const strokeDash = args.strokeDash ?? "solid";
+  normalizeStrokeDashPattern(strokeDash);
+  const opacity = validateOpacityValue(args.opacity ?? 1, "createErrorBar opacity");
+  return { caps, capSize, stroke, strokeWidth, strokeDash, opacity };
+}
+
+function positionArgs(resolved) {
+  return {
+    target: resolved.id,
+    field: resolved.position.field,
+    fieldType: resolved.position.fieldType,
+    coordinate: resolved.coordinate,
+    scale: resolved.position.scale
+  };
+}
+
+function intervalArgs(resolved, field) {
+  return {
+    target: resolved.id,
+    field,
+    fieldType: "quantitative",
+    coordinate: resolved.coordinate,
+    scale: resolved.interval.scale
+  };
+}
+
+export const createErrorBar = action(
+  {
+    op: "createErrorBar",
+    description: "Create a statistical or explicit vertical or horizontal interval."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createErrorBar");
+    const resolved = resolveErrorBar(this, args);
+    const appearance = resolveAppearance(args);
+    let next = this;
+
+    if (resolved.interval.mode === "statistical") {
+      next = next.createIntervalData({
+        id: resolved.dataId,
+        source: resolved.source,
+        field: resolved.interval.field,
+        groupBy: resolved.groupBy,
+        center: resolved.interval.center,
+        extent: resolved.interval.extent,
+        level: resolved.interval.level,
+        as: resolved.fields
+      });
+    }
+
+    next = next.createRuleMark({ id: resolved.id, data: resolved.dataId });
+    const positionAction = resolved.position.channel === "x" ? "encodeX" : "encodeY";
+    const intervalAction = resolved.interval.channel === "x" ? "encodeX" : "encodeY";
+    const secondaryAction = resolved.interval.channel === "x" ? "encodeX2" : "encodeY2";
+    next = next[positionAction](positionArgs(resolved));
+    next = next[intervalAction](intervalArgs(resolved, resolved.fields.lower));
+    if (resolved.interval.mode === "explicit") {
+      next = next.editSemantic({
+        property: `layer[${resolved.id}].encoding.${resolved.interval.channel}.title`,
+        value: resolved.interval.title
+      });
+    }
+    next = next[secondaryAction]({
+      target: resolved.id,
+      field: resolved.fields.upper,
+      fieldType: "quantitative"
+    })
+      .encodeStroke({ target: resolved.id, value: appearance.stroke })
+      .encodeStrokeWidth({ target: resolved.id, value: appearance.strokeWidth })
+      .encodeStrokeDash({ target: resolved.id, value: appearance.strokeDash })
+      .encodeOpacity({ target: resolved.id, value: appearance.opacity });
+
+    if (!appearance.caps) return next;
+
+    const intervalLayer = findLayer(next, resolved.id);
+    for (const [id, field] of [
+      [resolved.lowerCapId, resolved.fields.lower],
+      [resolved.upperCapId, resolved.fields.upper]
+    ]) {
+      next = next.createErrorBarCap({
+        id,
+        data: resolved.dataId,
+        orientation: resolved.orientation,
+        positionField: resolved.position.field,
+        positionFieldType: resolved.position.fieldType,
+        intervalField: field,
+        coordinate: resolved.coordinate,
+        positionScale: intervalLayer.encoding[resolved.position.channel].scale,
+        intervalScale: intervalLayer.encoding[resolved.interval.channel].scale,
+        capSize: appearance.capSize,
+        stroke: appearance.stroke,
+        strokeWidth: appearance.strokeWidth,
+        strokeDash: appearance.strokeDash,
+        opacity: appearance.opacity
+      });
+    }
+    return next;
+  }
+);

package/src/actions/errorBars/index.js

@@ -0,0 +1,7 @@
+import { createErrorBarCap } from "./components.js";
+import { createErrorBar } from "./create.js";
+
+export function registerErrorBarActions(ProgramClass) {
+  ProgramClass.prototype.createErrorBarCap = createErrorBarCap;
+  ProgramClass.prototype.createErrorBar = createErrorBar;
+}

package/src/actions/errorBars/resolve.js

@@ -0,0 +1,25 @@
+import { resolveIntervalComposite } from "../intervals/resolve.js";
+
+const ERROR_BAR_POLICY = Object.freeze({
+  operation: "createErrorBar",
+  resourceLabel: "error-bar",
+  defaultId: "errorBar",
+  ownerLabel: "Error-bar id",
+  positionTypes: Object.freeze(["nominal", "ordinal", "temporal"]),
+  defaultPositionType: "nominal",
+  defaultIntervalChannel: "y",
+  scaleDefaults: () => ({}),
+  intervalScaleDefaults: Object.freeze({ nice: true, zero: false }),
+  allowExplicitGrouping: false,
+  ambiguousMessage:
+    "createErrorBar requires one quantitative interval axis and one nominal, ordinal, or temporal position axis."
+});
+
+export function resolveErrorBar(program, args) {
+  const resolved = resolveIntervalComposite(program, args, ERROR_BAR_POLICY);
+  return {
+    ...resolved,
+    lowerCapId: `${resolved.id}LowerCap`,
+    upperCapId: `${resolved.id}UpperCap`
+  };
+}

package/src/actions/guides/axes/axes.js

@@ -0,0 +1,204 @@
+import { action } from "../../../core/action.js";
+import { isPlainObject } from "../../../core/immutable.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import { validateKeys } from "../../../core/validation.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
+
+const TOP_OPTIONS = Object.freeze(["coordinate", "x", "y"]);
+const COORDINATE_OPTIONS = Object.freeze(["id", "type"]);
+const COORDINATE_API_TYPES = new Set(["auto", "cartesian", "polar"]);
+
+function validateAxisOption(value, channel) {
+  if (value !== undefined && value !== false && !isPlainObject(value)) {
+    throw new TypeError(`createAxes ${channel} must be false or a plain object.`);
+  }
+}
+
+function validateArgs(args) {
+  if (!isPlainObject(args)) {
+    throw new TypeError("createAxes options must be a plain object.");
+  }
+
+  validateKeys(args, TOP_OPTIONS, "createAxes");
+  validateAxisOption(args.x, "x");
+  validateAxisOption(args.y, "y");
+
+  const coordinate = args.coordinate ?? {};
+  if (!isPlainObject(coordinate)) {
+    throw new TypeError("createAxes coordinate must be a plain object.");
+  }
+
+  validateKeys(coordinate, COORDINATE_OPTIONS, "createAxes.coordinate");
+  const type = coordinate.type ?? "auto";
+
+  if (!COORDINATE_API_TYPES.has(type)) {
+    throw new Error(`Unknown createAxes coordinate type "${type}".`);
+  }
+
+  return coordinate;
+}
+
+function inspectChannels(layers) {
+  const cartesianLayers = layers.filter(
+    layer => layer.encoding?.x !== undefined || layer.encoding?.y !== undefined
+  );
+  const polarLayers = layers.filter(
+    layer =>
+      layer.encoding?.theta !== undefined || layer.encoding?.radius !== undefined
+  );
+  const hasMixedLayer = layers.some(layer => {
+    const hasCartesian =
+      layer.encoding?.x !== undefined || layer.encoding?.y !== undefined;
+    const hasPolar =
+      layer.encoding?.theta !== undefined || layer.encoding?.radius !== undefined;
+    return hasCartesian && hasPolar;
+  });
+
+  if (hasMixedLayer) {
+    throw new Error(
+      "createAxes cannot infer a coordinate from mixed Cartesian and Polar channels."
+    );
+  }
+
+  return { cartesianLayers, hasPolar: polarLayers.length > 0 };
+}
+
+function resolveCoordinate(program, descriptor, cartesianLayers, hasPolar) {
+  if (hasPolar && cartesianLayers.length === 0) {
+    throw new Error("createAxes does not yet support Polar axes.");
+  }
+
+  if (cartesianLayers.length === 0) {
+    throw new Error("createAxes requires an x or y encoding.");
+  }
+
+  const referencedIds = [
+    ...new Set(
+      cartesianLayers
+        .map(layer => layer.coordinate)
+        .filter(id => id !== undefined)
+    )
+  ];
+
+  if (cartesianLayers.some(layer => layer.coordinate === undefined)) {
+    throw new Error(
+      "createAxes requires every positional layer to have a stored coordinate."
+    );
+  }
+
+  if (descriptor.id === undefined && referencedIds.length > 1) {
+    throw new Error(
+      "createAxes found multiple coordinates; provide coordinate.id explicitly."
+    );
+  }
+
+  const id = validateUserId(descriptor.id ?? referencedIds[0], "Coordinate id");
+  const existing = findCoordinate(program, id);
+
+  if (existing === undefined) {
+    throw new Error(`Unknown coordinate "${id}".`);
+  }
+
+  if (
+    descriptor.type !== undefined &&
+    descriptor.type !== "auto" &&
+    descriptor.type !== existing.type
+  ) {
+    throw new Error(
+      `Coordinate "${id}" has type "${existing.type}", not "${descriptor.type}".`
+    );
+  }
+
+  const layers = cartesianLayers.filter(
+    layer => layer.coordinate === id
+  );
+
+  if (layers.length === 0) {
+    throw new Error(`createAxes found no layers for coordinate "${id}".`);
+  }
+
+  if (existing.type !== "cartesian") {
+    throw new Error("createAxes does not yet support Polar axes.");
+  }
+
+  return { id, layers };
+}
+
+function hasChannel(layers, channel) {
+  return layers.some(layer => layer.encoding?.[channel] !== undefined);
+}
+
+function resolveAxisArgs(layers, channel, option) {
+  const selected = option === false
+    ? false
+    : option !== undefined || hasChannel(layers, channel);
+
+  if (!selected) return undefined;
+
+  const args = option ?? {};
+  const encodedScaleIds = [
+    ...new Set(
+      layers
+        .map(layer => layer.encoding?.[channel]?.scale)
+        .filter(id => id !== undefined)
+    )
+  ];
+  let scale = args.scale;
+
+  if (scale === undefined) {
+    if (encodedScaleIds.length === 0) {
+      throw new Error(`createAxes cannot infer the ${channel}-axis scale.`);
+    }
+
+    if (encodedScaleIds.length > 1) {
+      throw new Error(
+        `createAxes found multiple ${channel}-axis scales; provide ${channel}.scale explicitly.`
+      );
+    }
+
+    [scale] = encodedScaleIds;
+  }
+
+  validateUserId(scale, `${channel}-axis scale id`);
+  return { ...args, scale };
+}
+
+const createAxes = action(
+  {
+    op: "createAxes",
+    description: "Read a semantic coordinate and create its Cartesian axes."
+  },
+  function (args = {}) {
+    const coordinateDescriptor = validateArgs(args);
+    const { cartesianLayers, hasPolar } = inspectChannels(
+      this.semanticSpec.layers
+    );
+    const coordinate = resolveCoordinate(
+      this,
+      coordinateDescriptor,
+      cartesianLayers,
+      hasPolar
+    );
+    const x = resolveAxisArgs(coordinate.layers, "x", args.x);
+    const y = resolveAxisArgs(coordinate.layers, "y", args.y);
+
+    if (x === undefined && y === undefined) {
+      throw new Error("createAxes requires at least one selected axis.");
+    }
+
+    let program = this;
+
+    if (x !== undefined) {
+      program = program.createXAxis({ ...x, coordinate: coordinate.id });
+    }
+    if (y !== undefined) {
+      program = program.createYAxis({ ...y, coordinate: coordinate.id });
+    }
+
+    return program;
+  }
+);
+
+export function registerAxisCollectionActions(ProgramClass) {
+  ProgramClass.prototype.createAxes = createAxes;
+}

package/src/actions/guides/axes/axis.js

@@ -0,0 +1,131 @@
+import { action } from "../../../core/action.js";
+import { isPlainObject } from "../../../core/immutable.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import { validateKeys } from "../../../core/validation.js";
+import { hasCoordinate } from "../../../selectors/index.js";
+
+const TOP_OPTIONS = Object.freeze([
+  "scale",
+  "coordinate",
+  "position",
+  "line",
+  "ticksAndLabels",
+  "title"
+]);
+const LINE_OPTIONS = Object.freeze(["color", "lineWidth"]);
+const TICK_GROUP_OPTIONS = Object.freeze([
+  "count",
+  "values",
+  "ticks",
+  "labels"
+]);
+const TITLE_OPTIONS = Object.freeze([
+  "text",
+  "at",
+  "offset",
+  "rotation",
+  "color",
+  "fontSize",
+  "fontFamily",
+  "fontWeight"
+]);
+
+function validateNested(value, supported, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+
+  validateKeys(value, supported, label);
+}
+
+function validateArgs(args, operation) {
+  validateKeys(args, TOP_OPTIONS, operation);
+
+  if (Object.hasOwn(args, "line")) {
+    validateNested(args.line, LINE_OPTIONS, `${operation}.line`);
+  }
+
+  if (Object.hasOwn(args, "ticksAndLabels")) {
+    validateNested(
+      args.ticksAndLabels,
+      TICK_GROUP_OPTIONS,
+      `${operation}.ticksAndLabels`
+    );
+  }
+
+  if (Object.hasOwn(args, "title")) {
+    validateNested(args.title, TITLE_OPTIONS, `${operation}.title`);
+  }
+}
+
+function names(channel) {
+  const prefix = channel === "x" ? "X" : "Y";
+  return {
+    create: `create${prefix}Axis`,
+    line: `create${prefix}AxisLine`,
+    ticksAndLabels: `create${prefix}AxisTicksAndLabels`,
+    title: `create${prefix}AxisTitle`
+  };
+}
+
+function makeCreateAxis(channel) {
+  const operation = names(channel);
+
+  return action(
+    {
+      op: operation.create,
+      description: `Create the complete ${channel}-axis.`
+    },
+    function (args = {}) {
+      validateArgs(args, operation.create);
+      const shared = {};
+      if (Object.hasOwn(args, "scale")) shared.scale = args.scale;
+      if (Object.hasOwn(args, "position")) shared.position = args.position;
+      let next = this;
+
+      if (Object.hasOwn(args, "coordinate")) {
+        const coordinate = validateUserId(args.coordinate, "Coordinate id");
+        const scale = args.scale ?? channel;
+        const exists = hasCoordinate(next, coordinate);
+        const hasConsumer = next.semanticSpec.layers.some(
+          layer =>
+            layer.coordinate === coordinate &&
+            layer.encoding?.[channel]?.scale === scale
+        );
+
+        if (!exists) {
+          throw new Error(`Unknown coordinate "${coordinate}".`);
+        }
+        if (!hasConsumer) {
+          throw new Error(
+            `${operation.create} found no ${channel} encoding for coordinate "${coordinate}" and scale "${scale}".`
+          );
+        }
+
+        next = next.editSemantic({
+          property: `guide.axis.${channel}.coordinate`,
+          value: coordinate
+        });
+      }
+
+      return next[operation.line]({
+        ...shared,
+        ...(args.line ?? {})
+      })[operation.ticksAndLabels]({
+        ...shared,
+        ...(args.ticksAndLabels ?? {})
+      })[operation.title]({
+        ...shared,
+        ...(args.title ?? {})
+      });
+    }
+  );
+}
+
+const createXAxis = makeCreateAxis("x");
+const createYAxis = makeCreateAxis("y");
+
+export function registerAxisActions(Class) {
+  Class.prototype.createXAxis = createXAxis;
+  Class.prototype.createYAxis = createYAxis;
+}

package/src/actions/guides/axes/index.js

@@ -0,0 +1,17 @@
+import { registerAxisCollectionActions } from "./axes.js";
+import { registerAxisLabelActions } from "./labels.js";
+import { registerAxisLineActions } from "./lines.js";
+import { registerAxisTickGroupActions } from "./tickGroups.js";
+import { registerAxisTickActions } from "./ticks.js";
+import { registerAxisTitleActions } from "./titles.js";
+import { registerAxisActions } from "./axis.js";
+
+export function registerGuideAxisActions(ProgramClass) {
+  registerAxisLineActions(ProgramClass);
+  registerAxisTickActions(ProgramClass);
+  registerAxisLabelActions(ProgramClass);
+  registerAxisTickGroupActions(ProgramClass);
+  registerAxisTitleActions(ProgramClass);
+  registerAxisActions(ProgramClass);
+  registerAxisCollectionActions(ProgramClass);
+}