ggaction 0.0.2 → 0.0.3

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

@@ -0,0 +1,269 @@
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validatePositiveFinite
+} from "../../../core/validation.js";
+import { resolvePolarFrame } from "../../../grammar/polar.js";
+import {
+  formatTransformedTick,
+  isTransformedScaleType,
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues
+} from "../../../grammar/scales.js";
+import { formatTimeTick, formatTimeTicks } from "../../../grammar/ticks.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
+  "../../../theme/defaults.js";
+import {
+  findGraphicParent,
+  walkGraphicDrawOrder
+} from "../../../grammar/schemas/graphicTree.js";
+import { valuesFromTickConfig } from "../tickValues.js";
+import { formatAxisValue, validateAxisFormat } from "../axes/policy.js";
+
+export const POLAR_AXIS_DEFAULTS = Object.freeze({
+  angle: 90,
+  line: Object.freeze({ color: "#475569", lineWidth: 1.25 }),
+  ticks: Object.freeze({
+    thetaCount: 6,
+    radiusCount: 5,
+    length: 6,
+    radialLength: 8,
+    color: "#475569",
+    lineWidth: 1
+  }),
+  labels: Object.freeze({
+    thetaOffset: 18,
+    radiusOffset: 10,
+    format: "auto",
+    color: DEFAULT_COLORS.text,
+    fontSize: 11,
+    fontFamily: DEFAULT_FONT_FAMILY,
+    fontWeight: "normal"
+  }),
+  title: Object.freeze({
+    thetaOffset: 42,
+    radiusOffset: 8,
+    color: DEFAULT_COLORS.strongText,
+    fontSize: 13,
+    fontFamily: DEFAULT_FONT_FAMILY,
+    fontWeight: 600
+  })
+});
+
+export const POLAR_GRID_DEFAULTS = Object.freeze({
+  color: "#d7e0ea",
+  lineWidth: 1,
+  strokeDash: Object.freeze([]),
+  thetaCount: 6,
+  radiusCount: 5
+});
+
+export function polarGuideNames(kind) {
+  if (kind === "theta") {
+    return Object.freeze({
+      channel: "theta",
+      axis: "thetaAxis",
+      line: "thetaAxisLine",
+      ticks: "thetaAxisTicks",
+      labels: "thetaAxisLabels",
+      title: "thetaAxisTitle",
+      grid: "thetaGridLines"
+    });
+  }
+  if (kind === "radial" || kind === "radius") {
+    return Object.freeze({
+      channel: "radius",
+      axis: "radiusAxis",
+      line: "radialAxisLine",
+      ticks: "radialAxisTicks",
+      labels: "radialAxisLabels",
+      title: "radialAxisTitle",
+      grid: "radialGridCircles"
+    });
+  }
+  throw new Error(`Unknown Polar guide kind "${kind}".`);
+}
+
+export function resolvePolarGuideResources(program, kind, args, operation) {
+  const { channel } = polarGuideNames(kind);
+  const requestedCoordinate = args.coordinate === undefined
+    ? undefined
+    : validateUserId(args.coordinate, `${operation} coordinate id`);
+  const requestedScale = args.scale === undefined
+    ? undefined
+    : validateUserId(args.scale, `${operation} scale id`);
+  let layers = program.semanticSpec.layers.filter(layer =>
+    layer.encoding?.[channel]?.scale !== undefined
+  );
+  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(`${operation} requires a stored ${channel} encoding.`);
+  }
+  if (layers.some(layer => layer.coordinate === undefined)) {
+    throw new Error(`${operation} requires a stored Polar coordinate.`);
+  }
+  const coordinates = [...new Set(layers.map(layer => layer.coordinate))];
+  if (coordinates.length > 1) {
+    throw new Error(
+      `${operation} found multiple Polar coordinates; provide coordinate explicitly.`
+    );
+  }
+  const coordinate = requestedCoordinate ?? coordinates[0];
+  if (findCoordinate(program, coordinate)?.type !== "polar") {
+    throw new Error(`${operation} requires a Polar coordinate.`);
+  }
+  const scales = [...new Set(
+    layers.map(layer => layer.encoding[channel].scale)
+  )];
+  if (scales.length > 1) {
+    throw new Error(
+      `${operation} found multiple ${channel} scales; provide scale explicitly.`
+    );
+  }
+  const scale = requestedScale ?? scales[0];
+  const resolved = program.resolvedScales[scale];
+  const discrete = ["ordinal", "band", "point"].includes(resolved?.type);
+  const continuous = ["linear", "time"].includes(resolved?.type) ||
+    isTransformedScaleType(resolved?.type);
+  if ((channel === "theta" && !continuous && !discrete) ||
+      (channel === "radius" && !continuous)) {
+    throw new Error(
+      `${operation} requires a supported resolved ${channel} 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(`${operation} requires related materialized marks.`);
+  }
+  const owner = findGraphicParent(program.graphicSpec, before);
+  return Object.freeze({
+    channel,
+    coordinate,
+    scale,
+    before,
+    ...(owner?.kind === "parent" ? { parent: owner.id } : {})
+  });
+}
+
+export function resolvePolarFrameForProgram(program) {
+  const bounds = resolveGraphicBounds(program);
+  if (bounds === undefined) {
+    throw new Error("Polar guides require graphical Canvas bounds.");
+  }
+  return resolvePolarFrame(bounds);
+}
+
+export function resolvePolarTickValues(program, config) {
+  const scale = program.resolvedScales[config.scale];
+  const discrete = ["ordinal", "band", "point"].includes(scale?.type);
+  if (discrete) {
+    if (config.mode !== "values") {
+      throw new Error("Discrete theta guides require explicit or inferred values.");
+    }
+    const domain = new Set(scale.domain);
+    if (!config.values.every(value => domain.has(value))) {
+      throw new RangeError("Polar guide values must be inside the scale domain.");
+    }
+    return config.values;
+  }
+  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("Polar guide values must be inside the scale domain.");
+  }
+  return values;
+}
+
+export function mapPolarGuideValues(program, config) {
+  const scale = program.resolvedScales[config.scale];
+  const values = resolvePolarTickValues(program, config);
+  const positions = ["ordinal", "band", "point"].includes(scale.type)
+    ? mapOrdinalPositionValues(values, scale)
+    : mapContinuousScaleValues(values, scale);
+  return Object.freeze({ values, positions });
+}
+
+export function formatPolarGuideValues(program, config, values) {
+  const scale = program.resolvedScales[config.scale];
+  if (scale.type === "time" && config.format === "auto") {
+    return formatTimeTicks(values, scale.domain);
+  }
+  return values.map(value => formatAxisValue(
+    value,
+    scale.type,
+    config.format,
+    item => scale.type === "time"
+      ? formatTimeTick(item, scale.domain)
+      : isTransformedScaleType(scale.type)
+        ? formatTransformedTick(scale.type, item)
+        : String(item)
+  ));
+}
+
+export function normalizePolarTickMode(program, scale, args, defaultCount) {
+  const resolved = program.resolvedScales[scale];
+  if (Object.hasOwn(args, "values")) {
+    return { mode: "values", values: args.values, inferredValues: false };
+  }
+  if (Object.hasOwn(args, "count")) {
+    return { mode: "count", count: args.count, inferredValues: false };
+  }
+  if (["ordinal", "band", "point"].includes(resolved?.type)) {
+    return {
+      mode: "values",
+      values: resolved.domain,
+      inferredValues: true
+    };
+  }
+  return { mode: "count", count: defaultCount, inferredValues: true };
+}
+
+export function validatePolarTickConfig(config, label) {
+  if (config.mode === "count" &&
+      (!Number.isInteger(config.count) || config.count <= 0)) {
+    throw new RangeError(`${label} count must be a positive integer.`);
+  }
+  if (config.mode === "values" && (
+    !Array.isArray(config.values) || config.values.length === 0 ||
+    !config.values.every(value =>
+      typeof value === "string" || typeof value === "boolean" ||
+      (typeof value === "number" && Number.isFinite(value))
+    )
+  )) {
+    throw new TypeError(`${label} values must be a non-empty domain-value array.`);
+  }
+}
+
+export function validatePolarLineStyle(config, label) {
+  validateNonEmptyString(config.color, `${label} color`);
+  validateNonNegativeFinite(config.lineWidth, `${label} lineWidth`);
+}
+
+export function validatePolarTextStyle(config, label) {
+  validateNonEmptyString(config.color, `${label} color`);
+  validatePositiveFinite(config.fontSize, `${label} fontSize`);
+  validateNonEmptyString(config.fontFamily, `${label} fontFamily`);
+  if (typeof config.fontWeight !== "string" &&
+      !Number.isFinite(config.fontWeight)) {
+    throw new TypeError(`${label} fontWeight must be a string or number.`);
+  }
+}
+
+export function validatePolarLabelFormat(format) {
+  return validateAxisFormat(format);
+}

package/src/actions/index.js

@@ -1,9 +1,11 @@
 import { registerCanvasActions } from "./canvas/index.js";
 import { registerCoordinateActions } from "./coordinates/index.js";
+import { registerCompositionActions } from "./composition/index.js";
 import { registerDataActions } from "./data/index.js";
 import { registerEncodingActions } from "./encodings/index.js";
 import { registerErrorBandActions } from "./errorBands/index.js";
 import { registerErrorBarActions } from "./errorBars/index.js";
+import { registerFacetActions } from "./facets/index.js";
 import { registerBoxPlotActions } from "./boxPlots/index.js";
 import { registerGuideActions } from "./guides/index.js";
 import { registerMarkActions } from "./marks/index.js";
@@ -15,6 +17,8 @@ import { registerSelectionActions } from "./selection/index.js";
 
 export function registerActions(ProgramClass) {
   registerPrimitiveActions(ProgramClass);
+  registerCompositionActions(ProgramClass);
+  registerFacetActions(ProgramClass);
   registerCanvasActions(ProgramClass);
   registerDataActions(ProgramClass);
   registerMarkActions(ProgramClass);

package/src/actions/marks/arc/actions.js

@@ -0,0 +1,239 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../../core/validation.js";
+import { deriveArcSectors } from "../../../grammar/arcs.js";
+import { buildAnnularSectorCommands } from "../../../grammar/polarPaths.js";
+import { resolvePolarFrame } from "../../../grammar/polar.js";
+import { mapOrdinalValues } from "../../../grammar/scales.js";
+import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { canMaterializeArc } from "../../../materialization/marks.js";
+import { findDataset } from "../../../selectors/datasets.js";
+import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
+import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import { resolveMarkGraphicPlacement } from
+  "../../../materialization/graphicHierarchy.js";
+import { rematerializeHighlightBaseline } from "../lifecycle.js";
+import {
+  assertMarkAvailable,
+  applyLayeredMarkInheritance,
+  materializeInheritedMark,
+  resolveLayeredMarkInheritance,
+  resolveMarkData,
+  resolveMarkId,
+  validateMarkOptions
+} from "../shared.js";
+
+const CREATE_OPTIONS = Object.freeze([
+  "id", "data", "innerRadius", "padAngle", "fill", "opacity", "stroke",
+  "strokeWidth"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "innerRadius", "padAngle", "fill", "opacity", "stroke",
+  "strokeWidth"
+]);
+const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+
+function validateInnerRadius(value) {
+  if (!Number.isFinite(value) || value < 0 || value >= 1) {
+    throw new RangeError(
+      "Arc innerRadius must be from 0 (inclusive) to 1 (exclusive)."
+    );
+  }
+  return value;
+}
+
+function normalizeConfig(args, previous = {}) {
+  return {
+    ...previous,
+    ...(Object.hasOwn(args, "innerRadius")
+      ? { innerRadius: validateInnerRadius(args.innerRadius) }
+      : {}),
+    ...(Object.hasOwn(args, "padAngle")
+      ? { padAngle: validateNonNegativeFinite(args.padAngle, "Arc padAngle") }
+      : {}),
+    ...(Object.hasOwn(args, "fill")
+      ? { fill: validateNonEmptyString(args.fill, "Arc fill") }
+      : {}),
+    ...(Object.hasOwn(args, "opacity")
+      ? { opacity: validateUnitInterval(args.opacity, "Arc opacity") }
+      : {}),
+    ...(Object.hasOwn(args, "stroke")
+      ? { stroke: validateNonEmptyString(args.stroke, "Arc stroke") }
+      : {}),
+    ...(Object.hasOwn(args, "strokeWidth")
+      ? {
+          strokeWidth: validateNonNegativeFinite(
+            args.strokeWidth,
+            "Arc strokeWidth"
+          )
+        }
+      : {})
+  };
+}
+
+const createArcMark = action(
+  {
+    op: "createArcMark",
+    description: "Create a semantic arc mark and empty path collection."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, CREATE_OPTIONS, "createArcMark");
+    const id = resolveMarkId(this, args.id, {
+      defaultId: "arc",
+      label: "Arc mark id",
+      markType: "arc",
+      operation: "createArcMark"
+    });
+    const inherited = resolveLayeredMarkInheritance(this, args, "arc");
+    const { data } = resolveMarkData(this, {
+      ...args,
+      ...(args.data === undefined && this.context.currentData === undefined &&
+        inherited?.data !== undefined ? { data: inherited.data } : {})
+    });
+    assertMarkAvailable(this, id);
+    const config = normalizeConfig(args, {
+      innerRadius: 0,
+      padAngle: 0,
+      opacity: 1,
+      stroke: "#ffffff",
+      strokeWidth: 1
+    });
+    let created = this
+      .editSemantic({ property: `layer[${id}].mark.type`, value: "arc" })
+      .editSemantic({ property: `layer[${id}].data`, value: data });
+    created = applyLayeredMarkInheritance(created, id, inherited);
+    created = created
+      .createGraphics({
+        id,
+        type: "path",
+        length: 0,
+        ...resolveMarkGraphicPlacement(created, { data, markType: "arc" })
+      })
+      ._withMarkConfig(id, config);
+    return materializeInheritedMark(created, id);
+  }
+);
+
+function requireArc(program, id) {
+  const layer = findLayer(program, id);
+  const dataset = findDataset(program, layer?.data);
+  if (layer?.mark?.type !== "arc" || program.graphicSpec.objects[id]?.type !== "path") {
+    throw new Error(`Unknown arc mark "${id}".`);
+  }
+  if (dataset === undefined) {
+    throw new Error(`Arc mark "${id}" requires an existing dataset.`);
+  }
+  return { layer, dataset };
+}
+
+const rematerializeArcMark = action(
+  {
+    op: "rematerializeArcMark",
+    description: "Recompute concrete annular-sector paths."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, REMATERIALIZE_OPTIONS, "rematerializeArcMark");
+    const id = validateUserId(args.id, "Arc mark id");
+    const highlighted = rematerializeHighlightBaseline(this, {
+      target: id,
+      operation: "rematerializeArcMark",
+      resetProperty: "length",
+      resetValue: 0
+    });
+    if (highlighted !== undefined) return highlighted;
+    const { layer, dataset } = requireArc(this, id);
+    if (!canMaterializeArc(this, layer)) {
+      throw new Error(`Arc mark "${id}" does not have a complete encoding.`);
+    }
+    const thetaScaleId = layer.encoding.theta.scale;
+    const radiusScaleId = layer.encoding?.radius?.scale;
+    const colorScaleId = layer.encoding?.color?.scale;
+    let resolved = this.rematerializeScale({ id: thetaScaleId });
+    if (radiusScaleId !== undefined) {
+      resolved = resolved.rematerializeScale({ id: radiusScaleId });
+    }
+    if (colorScaleId !== undefined) {
+      resolved = resolved.rematerializeScale({ id: colorScaleId });
+    }
+    const config = resolved.markConfigs[id] ?? {};
+    const derived = deriveArcSectors(dataset.values, layer, {
+      thetaScale: resolved.resolvedScales[thetaScaleId],
+      ...(radiusScaleId === undefined
+        ? {}
+        : { radiusScale: resolved.resolvedScales[radiusScaleId] }),
+      frame: resolvePolarFrame(resolveGraphicBounds(resolved)),
+      innerRadiusRatio: config.innerRadius ?? 0
+    });
+    const frame = resolvePolarFrame(resolveGraphicBounds(resolved));
+    const commands = derived.sectors.map(sector => buildAnnularSectorCommands({
+      frame,
+      startTheta: sector.startTheta,
+      endTheta: sector.endTheta,
+      innerRadius: sector.innerRadius,
+      outerRadius: sector.outerRadius,
+      padAngle: config.padAngle ?? 0
+    }));
+    const fills = colorScaleId === undefined
+      ? commands.map(() => config.fill ?? DEFAULT_COLORS.mark)
+      : mapOrdinalValues(
+          derived.sectors.map(sector => sector.color),
+          resolved.resolvedScales[colorScaleId].domain,
+          resolved.resolvedScales[colorScaleId].range
+        );
+    return resolved
+      .editGraphics({ target: id, property: "length", value: commands.length })
+      .editGraphics({ target: id, property: "commands", value: commands })
+      .editGraphics({ target: id, property: "fill", value: fills })
+      .editGraphics({ target: id, property: "opacity", value: config.opacity ?? 1 })
+      .editGraphics({ target: id, property: "stroke", value: config.stroke ?? "#ffffff" })
+      .editGraphics({ target: id, property: "strokeWidth", value: config.strokeWidth ?? 1 })
+      .editGraphics({
+        target: id,
+        property: "strokeDash",
+        value: commands.map(() => [])
+      });
+  }
+);
+
+const editArcMark = action(
+  {
+    op: "editArcMark",
+    description: "Edit arc geometry and appearance."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, EDIT_OPTIONS, "editArcMark");
+    if (Object.keys(args).every(key => key === "target")) {
+      throw new Error(
+        "editArcMark requires innerRadius, padAngle, fill, opacity, stroke, or strokeWidth."
+      );
+    }
+    const target = Object.hasOwn(args, "target")
+      ? validateUserId(args.target, "Arc mark id")
+      : undefined;
+    const layer = resolveEligibleLayer(this, {
+      target,
+      predicate: candidate => candidate.mark?.type === "arc",
+      label: "arc mark"
+    });
+    if (Object.hasOwn(args, "fill") && layer.encoding?.color !== undefined) {
+      throw new Error("editArcMark fill cannot be combined with a color encoding.");
+    }
+    const next = this._withMarkConfig(
+      layer.id,
+      normalizeConfig(args, this.markConfigs[layer.id])
+    );
+    return canMaterializeArc(next, layer)
+      ? next.rematerializeArcMark({ id: layer.id })
+      : next;
+  }
+);
+
+export function registerArcMarkActions(ProgramClass) {
+  ProgramClass.prototype.createArcMark = createArcMark;
+  ProgramClass.prototype.editArcMark = editArcMark;
+  ProgramClass.prototype.rematerializeArcMark = rematerializeArcMark;
+}

package/src/actions/marks/arc/index.js

@@ -0,0 +1 @@
+export { registerArcMarkActions } from "./actions.js";