ggaction 0.0.2 → 0.0.4

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

@@ -0,0 +1,164 @@
+import { action } from "../../../../core/action.js";
+import { validateNonNegativeFinite } from "../../../../core/validation.js";
+import {
+  resolveRadialAxisTicks,
+  resolveThetaAxisTicks
+} from "../../../../grammar/polarGuides.js";
+import { resolvePlotGraphicPlacement } from
+  "../../../../materialization/graphicHierarchy.js";
+import {
+  mapPolarGuideValues,
+  normalizePolarTickMode,
+  POLAR_AXIS_DEFAULTS,
+  polarGuideNames,
+  resolvePolarFrameForProgram,
+  validatePolarLineStyle,
+  validatePolarTickConfig
+} from "../resolve.js";
+import {
+  componentResources,
+  operations,
+  prefix,
+  resolveAngle,
+  TICK_CREATE_OPTIONS,
+  TICK_EDIT_OPTIONS,
+  validateModeOptions,
+  validateObject,
+  withAxisSemantics
+} from "./shared.js";
+
+function tickGeometry(program, kind, config) {
+  const frame = resolvePolarFrameForProgram(program);
+  const mapped = mapPolarGuideValues(program, config);
+  return {
+    values: mapped.values,
+    ...(kind === "theta"
+      ? resolveThetaAxisTicks({
+          frame,
+          angles: mapped.positions,
+          length: config.length
+        })
+      : resolveRadialAxisTicks({
+          frame,
+          angle: resolveAngle(program, kind, {}),
+          radii: mapped.positions,
+          length: config.length
+        }))
+  };
+}
+
+function resolveTickConfig(program, kind, args, resources, previous) {
+  const count = kind === "theta"
+    ? POLAR_AXIS_DEFAULTS.ticks.thetaCount
+    : POLAR_AXIS_DEFAULTS.ticks.radiusCount;
+  const explicitMode = Object.hasOwn(args, "count") ||
+    Object.hasOwn(args, "values");
+  const mode = explicitMode
+    ? normalizePolarTickMode(program, resources.scale, args, count)
+    : previous?.inferredValues === false
+      ? previous.mode === "values"
+        ? { mode: "values", values: previous.values, inferredValues: false }
+        : { mode: "count", count: previous.count, inferredValues: false }
+      : normalizePolarTickMode(program, resources.scale, {}, count);
+  const config = {
+    ...(previous ?? {}),
+    scale: resources.scale,
+    coordinate: resources.coordinate,
+    ...mode,
+    length: args.length ?? previous?.length ?? (kind === "theta"
+      ? POLAR_AXIS_DEFAULTS.ticks.length
+      : POLAR_AXIS_DEFAULTS.ticks.radialLength),
+    color: args.color ?? previous?.color ?? POLAR_AXIS_DEFAULTS.ticks.color,
+    lineWidth: args.lineWidth ?? previous?.lineWidth ??
+      POLAR_AXIS_DEFAULTS.ticks.lineWidth
+  };
+  validatePolarTickConfig(config, `${kind}-axis ticks`);
+  validateNonNegativeFinite(config.length, "Polar axis tick length");
+  validatePolarLineStyle(config, `${prefix(kind)} axis ticks`);
+  return config;
+}
+
+function makeEditTicks(kind) {
+  const operation = operations(kind, "Ticks");
+  return action({
+    op: operation.edit,
+    description: `Edit the Polar ${kind}-axis ticks.`
+  }, function (args = {}) {
+    validateObject(args, TICK_EDIT_OPTIONS, operation.edit);
+    validateModeOptions(args, operation.edit);
+    const names = polarGuideNames(kind);
+    const previous = this.guideConfigs.axis?.[kind]?.ticks;
+    if (this.graphicSpec.objects[names.ticks]?.type !== "line" ||
+        previous === undefined) {
+      throw new Error(`${operation.edit} requires existing axis ticks.`);
+    }
+    const resources = {
+      scale: previous.scale,
+      coordinate: previous.coordinate
+    };
+    const config = resolveTickConfig(this, kind, args, resources, previous);
+    const geometry = tickGeometry(this, kind, config);
+    let next = this._withGuideConfig(kind, "ticks", config)
+      .editGraphics({
+        target: names.ticks,
+        property: "length",
+        value: geometry.values.length
+      });
+    for (const property of ["x1", "y1", "x2", "y2"]) {
+      next = next.editGraphics({
+        target: names.ticks,
+        property,
+        value: geometry[property]
+      });
+    }
+    return next
+      .editGraphics({
+        target: names.ticks,
+        property: "stroke",
+        value: config.color
+      })
+      .editGraphics({
+        target: names.ticks,
+        property: "strokeWidth",
+        value: config.lineWidth
+      });
+  });
+}
+
+function makeCreateTicks(kind) {
+  const operation = operations(kind, "Ticks");
+  return action({
+    op: operation.create,
+    description: `Create the Polar ${kind}-axis ticks.`
+  }, function (args = {}) {
+    validateObject(args, TICK_CREATE_OPTIONS, operation.create);
+    validateModeOptions(args, operation.create);
+    const names = polarGuideNames(kind);
+    if (this.graphicSpec.objects[names.ticks] !== undefined) {
+      throw new Error(`${operation.create} requires missing axis ticks.`);
+    }
+    const resources = componentResources(this, kind, args, operation.create);
+    const angle = resolveAngle(this, kind, args);
+    const config = resolveTickConfig(this, kind, args, resources);
+    tickGeometry(this, kind, config);
+    let next = withAxisSemantics(this, kind, resources);
+    if (kind === "radius" &&
+        next.guideConfigs.axis?.radius?.layout === undefined) {
+      next = next._withGuideConfig("radius", "layout", { angle });
+    }
+    return next
+      .createGraphics({
+        id: names.ticks,
+        type: "line",
+        length: 0,
+        ...resolvePlotGraphicPlacement(next)
+      })
+      ._withGuideConfig(kind, "ticks", config)
+      [operation.edit]();
+  });
+}
+
+export const createThetaAxisTicks = makeCreateTicks("theta");
+export const createRadialAxisTicks = makeCreateTicks("radius");
+export const editThetaAxisTicks = makeEditTicks("theta");
+export const editRadialAxisTicks = makeEditTicks("radius");

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

@@ -0,0 +1,165 @@
+import { action } from "../../../../core/action.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite
+} from "../../../../core/validation.js";
+import {
+  resolveRadialAxisTitle,
+  resolveThetaAxisTitle
+} from "../../../../grammar/polarGuides.js";
+import { resolvePlotGraphicPlacement } from
+  "../../../../materialization/graphicHierarchy.js";
+import { inferAxisTitleText } from "../../axes/titles.js";
+import {
+  POLAR_AXIS_DEFAULTS,
+  polarGuideNames,
+  resolvePolarFrameForProgram,
+  validatePolarTextStyle
+} from "../resolve.js";
+import {
+  componentResources,
+  operations,
+  prefix,
+  resolveAngle,
+  TITLE_CREATE_OPTIONS,
+  TITLE_EDIT_OPTIONS,
+  validateObject,
+  withAxisSemantics
+} from "./shared.js";
+
+function titleGeometry(program, kind, config) {
+  const frame = resolvePolarFrameForProgram(program);
+  return kind === "theta"
+    ? resolveThetaAxisTitle({ frame, offset: config.offset })
+    : resolveRadialAxisTitle({
+        frame,
+        angle: resolveAngle(program, kind, {}),
+        offset: config.offset,
+        position: config.position
+      });
+}
+
+function resolveTitleConfig(kind, args, resources, previous) {
+  const config = {
+    ...(previous ?? {}),
+    scale: resources.scale,
+    coordinate: resources.coordinate,
+    inferredText: previous?.inferredText ?? !Object.hasOwn(args, "text"),
+    offset: args.offset ?? previous?.offset ?? (kind === "theta"
+      ? POLAR_AXIS_DEFAULTS.title.thetaOffset
+      : POLAR_AXIS_DEFAULTS.title.radiusOffset),
+    color: args.color ?? previous?.color ?? POLAR_AXIS_DEFAULTS.title.color,
+    fontSize: args.fontSize ?? previous?.fontSize ??
+      POLAR_AXIS_DEFAULTS.title.fontSize,
+    fontFamily: args.fontFamily ?? previous?.fontFamily ??
+      POLAR_AXIS_DEFAULTS.title.fontFamily,
+    fontWeight: args.fontWeight ?? previous?.fontWeight ??
+      POLAR_AXIS_DEFAULTS.title.fontWeight
+  };
+  if (kind === "theta" && Object.hasOwn(args, "position")) {
+    throw new Error("Theta axis title does not support position.");
+  }
+  if (kind === "radius") {
+    config.position = args.position ?? previous?.position ?? "inside";
+    if (!["inside", "outside"].includes(config.position)) {
+      throw new Error(
+        `Unknown radial-axis title position "${config.position}".`
+      );
+    }
+  }
+  if (Object.hasOwn(args, "text")) config.inferredText = false;
+  validateNonNegativeFinite(config.offset, "Polar axis title offset");
+  validatePolarTextStyle(config, `${prefix(kind)} axis title`);
+  return config;
+}
+
+function makeEditTitle(kind) {
+  const operation = operations(kind, "Title");
+  return action({
+    op: operation.edit,
+    description: `Edit the Polar ${kind}-axis title.`
+  }, function (args = {}) {
+    validateObject(args, TITLE_EDIT_OPTIONS, operation.edit);
+    const names = polarGuideNames(kind);
+    const previous = this.guideConfigs.axis?.[kind]?.title;
+    if (this.graphicSpec.objects[names.title]?.type !== "text" ||
+        previous === undefined) {
+      throw new Error(`${operation.edit} requires an existing axis title.`);
+    }
+    const resources = {
+      scale: previous.scale,
+      coordinate: previous.coordinate
+    };
+    const config = resolveTitleConfig(kind, args, resources, previous);
+    const text = Object.hasOwn(args, "text")
+      ? validateNonEmptyString(args.text, "Polar axis title text")
+      : config.inferredText
+        ? inferAxisTitleText(this, polarGuideNames(kind).channel, config.scale)
+        : this.semanticSpec.guides.axis?.[kind]?.title;
+    let next = this;
+    if (text !== this.semanticSpec.guides.axis?.[kind]?.title) {
+      next = next.editSemantic({
+        property: `guide.axis.${kind}.title`,
+        value: text
+      });
+    }
+    const geometry = titleGeometry(next, kind, config);
+    next = next._withGuideConfig(kind, "title", config);
+    const properties = {
+      ...geometry,
+      text,
+      fill: config.color,
+      fontSize: config.fontSize,
+      fontFamily: config.fontFamily,
+      fontWeight: config.fontWeight
+    };
+    for (const [property, value] of Object.entries(properties)) {
+      next = next.editGraphics({ target: names.title, property, value });
+    }
+    return next;
+  });
+}
+
+function makeCreateTitle(kind) {
+  const operation = operations(kind, "Title");
+  return action({
+    op: operation.create,
+    description: `Create the Polar ${kind}-axis title.`
+  }, function (args = {}) {
+    validateObject(args, TITLE_CREATE_OPTIONS, operation.create);
+    const names = polarGuideNames(kind);
+    if (this.graphicSpec.objects[names.title] !== undefined) {
+      throw new Error(`${operation.create} requires a missing axis title.`);
+    }
+    const resources = componentResources(this, kind, args, operation.create);
+    const angle = resolveAngle(this, kind, args);
+    const config = resolveTitleConfig(kind, args, resources);
+    const text = validateNonEmptyString(
+      args.text ?? inferAxisTitleText(this, names.channel, resources.scale),
+      "Polar axis title text"
+    );
+    titleGeometry(this, kind, config);
+    let next = withAxisSemantics(this, kind, resources);
+    if (kind === "radius" &&
+        next.guideConfigs.axis?.radius?.layout === undefined) {
+      next = next._withGuideConfig("radius", "layout", { angle });
+    }
+    next = next.editSemantic({
+      property: `guide.axis.${kind}.title`,
+      value: text
+    });
+    return next
+      .createGraphics({
+        id: names.title,
+        type: "text",
+        ...resolvePlotGraphicPlacement(next)
+      })
+      ._withGuideConfig(kind, "title", config)
+      [operation.edit]();
+  });
+}
+
+export const createThetaAxisTitle = makeCreateTitle("theta");
+export const createRadialAxisTitle = makeCreateTitle("radius");
+export const editThetaAxisTitle = makeEditTitle("theta");
+export const editRadialAxisTitle = makeEditTitle("radius");

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

@@ -0,0 +1,252 @@
+import { action } from "../../../core/action.js";
+import {
+  noOptions,
+  validateOptionObject,
+  validateNonEmptyString,
+  validateNonNegativeFinite
+} from "../../../core/validation.js";
+import {
+  resolveRadialCircles,
+  resolveThetaSpokes
+} from "../../../grammar/polarGuides.js";
+import {
+  POLAR_GRID_DEFAULTS,
+  mapPolarGuideValues,
+  normalizePolarTickMode,
+  polarGuideNames,
+  resolvePolarFrameForProgram,
+  resolvePolarGuideResources,
+  validatePolarTickConfig
+} from "./resolve.js";
+
+const CREATE_OPTIONS = Object.freeze([
+  "scale", "coordinate", "count", "values", "color", "lineWidth",
+  "strokeDash"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "count", "values", "color", "lineWidth", "strokeDash"
+]);
+
+function operationNames(kind) {
+  const prefix = kind === "theta" ? "Theta" : "Radial";
+  return {
+    create: `create${prefix}Grid`,
+    edit: `edit${prefix}Grid`,
+    rematerialize: `rematerialize${prefix}Grid`
+  };
+}
+
+function validateStrokeDash(value) {
+  if (!Array.isArray(value) || value.length % 2 !== 0 ||
+      !value.every(item => Number.isFinite(item) && item >= 0)) {
+    throw new TypeError(
+      "Polar grid strokeDash must be an even-length array of non-negative finite numbers."
+    );
+  }
+}
+
+function validateOptions(args, operation, create) {
+  validateOptionObject(
+    args,
+    create ? CREATE_OPTIONS : EDIT_OPTIONS,
+    operation,
+    { allowEmpty: create, emptyError: Error }
+  );
+  if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) {
+    throw new Error(`${operation} cannot use count and values together.`);
+  }
+  if (Object.hasOwn(args, "color")) {
+    validateNonEmptyString(args.color, "Polar grid color");
+  }
+  if (Object.hasOwn(args, "lineWidth")) {
+    validateNonNegativeFinite(args.lineWidth, "Polar grid lineWidth");
+  }
+  if (Object.hasOwn(args, "strokeDash")) validateStrokeDash(args.strokeDash);
+}
+
+function resolveConfig(program, kind, args, resources, previous) {
+  const defaults = kind === "theta"
+    ? POLAR_GRID_DEFAULTS.thetaCount
+    : POLAR_GRID_DEFAULTS.radiusCount;
+  const explicitMode = Object.hasOwn(args, "count") ||
+    Object.hasOwn(args, "values");
+  const mode = explicitMode
+    ? normalizePolarTickMode(program, resources.scale, args, defaults)
+    : previous === undefined
+      ? normalizePolarTickMode(program, resources.scale, args, defaults)
+      : previous.inferredValues === true
+        ? normalizePolarTickMode(program, resources.scale, {}, defaults)
+        : previous.mode === "values"
+          ? { mode: "values", values: previous.values, inferredValues: false }
+          : { mode: "count", count: previous.count, inferredValues: false };
+  const config = {
+    ...(previous ?? {}),
+    kind,
+    scale: resources.scale,
+    coordinate: resources.coordinate,
+    ...mode,
+    color: args.color ?? previous?.color ?? POLAR_GRID_DEFAULTS.color,
+    lineWidth: args.lineWidth ?? previous?.lineWidth ??
+      POLAR_GRID_DEFAULTS.lineWidth,
+    strokeDash: args.strokeDash ?? previous?.strokeDash ??
+      POLAR_GRID_DEFAULTS.strokeDash
+  };
+  validatePolarTickConfig(config, `${kind} grid`);
+  validateNonEmptyString(config.color, "Polar grid color");
+  validateNonNegativeFinite(config.lineWidth, "Polar grid lineWidth");
+  validateStrokeDash(config.strokeDash);
+  return config;
+}
+
+function resolveGeometry(program, kind, config) {
+  const frame = resolvePolarFrameForProgram(program);
+  const mapped = mapPolarGuideValues(program, config);
+  if (kind === "theta") {
+    return { values: mapped.values, ...resolveThetaSpokes({
+      frame,
+      angles: mapped.positions
+    }) };
+  }
+  const circles = resolveRadialCircles({
+    frame,
+    radii: mapped.positions
+  });
+  return {
+    values: mapped.values.filter((_, index) => mapped.positions[index] > 0),
+    commands: circles.commands
+  };
+}
+
+function editConcrete(program, kind, config, geometry) {
+  const graphic = polarGuideNames(kind).grid;
+  const properties = kind === "theta"
+    ? {
+        x1: geometry.x1,
+        y1: geometry.y1,
+        x2: geometry.x2,
+        y2: geometry.y2
+      }
+    : { commands: geometry.commands };
+  let next = program.editGraphics({
+    target: graphic,
+    property: "length",
+    value: geometry.values.length
+  });
+  for (const [property, value] of Object.entries(properties)) {
+    next = next.editGraphics({ target: graphic, property, value });
+  }
+  return next
+    .editGraphics({ target: graphic, property: "stroke", value: config.color })
+    .editGraphics({
+      target: graphic,
+      property: "strokeWidth",
+      value: config.lineWidth
+    })
+    .editGraphics({
+      target: graphic,
+      property: "strokeDash",
+      value: geometry.values.map(() => config.strokeDash)
+    });
+}
+
+function makeRematerialize(kind) {
+  const operations = operationNames(kind);
+  return action({
+    op: operations.rematerialize,
+    description: `Recompute concrete Polar ${kind} grid geometry.`
+  }, function (args = {}) {
+    noOptions(args, operations.rematerialize);
+    const config = this.guideConfigs.grid?.[kind];
+    const semantic = this.semanticSpec.guides.grid?.[kind];
+    const graphic = this.graphicSpec.objects[polarGuideNames(kind).grid];
+    const expectedType = kind === "theta" ? "line" : "path";
+    if (config === undefined || semantic?.scale !== config.scale ||
+        semantic.coordinate !== config.coordinate || graphic?.type !== expectedType) {
+      throw new Error(`${operations.rematerialize} requires an existing grid.`);
+    }
+    const resources = { scale: config.scale, coordinate: config.coordinate };
+    const refreshed = resolveConfig(this, kind, {}, resources, config);
+    const geometry = resolveGeometry(this, kind, refreshed);
+    return editConcrete(
+      this._withGridConfig(kind, refreshed),
+      kind,
+      refreshed,
+      geometry
+    );
+  });
+}
+
+function makeCreate(kind) {
+  const operations = operationNames(kind);
+  return action({
+    op: operations.create,
+    description: `Create a semantic and concrete Polar ${kind} grid.`
+  }, function (args = {}) {
+    validateOptions(args, operations.create, true);
+    const graphic = polarGuideNames(kind).grid;
+    if (this.semanticSpec.guides.grid?.[kind] !== undefined ||
+        this.graphicSpec.objects[graphic] !== undefined) {
+      throw new Error(`${operations.create} requires a missing grid.`);
+    }
+    const resources = resolvePolarGuideResources(
+      this,
+      kind,
+      args,
+      operations.create
+    );
+    const config = resolveConfig(this, kind, args, resources);
+    resolveGeometry(this, kind, config);
+    return this
+      .editSemantic({
+        property: `guide.grid.${kind}.scale`,
+        value: resources.scale
+      })
+      .editSemantic({
+        property: `guide.grid.${kind}.coordinate`,
+        value: resources.coordinate
+      })
+      .createGraphics({
+        id: graphic,
+        type: kind === "theta" ? "line" : "path",
+        length: 0,
+        ...(resources.parent === undefined ? {} : { parent: resources.parent }),
+        before: resources.before
+      })
+      ._withGridConfig(kind, config)
+      [operations.rematerialize]();
+  });
+}
+
+function makeEdit(kind) {
+  const operations = operationNames(kind);
+  return action({
+    op: operations.edit,
+    description: `Edit the existing Polar ${kind} grid.`
+  }, function (args = {}) {
+    validateOptions(args, operations.edit, false);
+    const previous = this.guideConfigs.grid?.[kind];
+    if (previous === undefined) {
+      throw new Error(`${operations.edit} requires an existing grid.`);
+    }
+    const resources = { scale: previous.scale, coordinate: previous.coordinate };
+    const config = resolveConfig(this, kind, args, resources, previous);
+    resolveGeometry(this, kind, config);
+    return this._withGridConfig(kind, config)[operations.rematerialize]();
+  });
+}
+
+const createThetaGrid = makeCreate("theta");
+const createRadialGrid = makeCreate("radial");
+const editThetaGrid = makeEdit("theta");
+const editRadialGrid = makeEdit("radial");
+const rematerializeThetaGrid = makeRematerialize("theta");
+const rematerializeRadialGrid = makeRematerialize("radial");
+
+export function registerPolarGridActions(ProgramClass) {
+  ProgramClass.prototype.createThetaGrid = createThetaGrid;
+  ProgramClass.prototype.createRadialGrid = createRadialGrid;
+  ProgramClass.prototype.editThetaGrid = editThetaGrid;
+  ProgramClass.prototype.editRadialGrid = editRadialGrid;
+  ProgramClass.prototype.rematerializeThetaGrid = rematerializeThetaGrid;
+  ProgramClass.prototype.rematerializeRadialGrid = rematerializeRadialGrid;
+}

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

@@ -0,0 +1,2 @@
+export { registerPolarGridActions } from "./grids.js";
+export { registerPolarAxisActions } from "./axes/index.js";