ggaction 0.0.2 → 0.0.3

package/src/actions/titles/actions.js

@@ -11,6 +11,15 @@ import {
   resolveCanvasGraphicPlacement
 } from "../../materialization/graphicHierarchy.js";
 
+function assertTitleScope(program, operation) {
+  if (
+    program.compositionSpec !== undefined &&
+    program.compositionSpec.type !== "facet"
+  ) {
+    throw new Error(`${operation} is not available on this composition ChartProgram.`);
+  }
+}
+
 function hasRotation(graphic) {
   const properties = graphic.items?.map(child => child.properties) ??
     [graphic.properties];
@@ -179,8 +188,13 @@ export const rematerializeTitle = action(
 );
 
 export const createTitle = action(
-  { op: "createTitle", description: "Create a chart title and optional subtitle." },
+  {
+    op: "createTitle",
+    description: "Create a chart title and optional subtitle.",
+    scope: "any"
+  },
   function (args = {}) {
+    assertTitleScope(this, "createTitle");
     const options = normalizeTitleOptions(args);
     if (Object.keys(this.semanticSpec.title).length > 0) {
       throw new Error("createTitle requires missing semantic title state.");
@@ -197,6 +211,9 @@ export const createTitle = action(
       next = next.editSemantic({ property: "title.subtitle", value: subtitle });
     }
     next = next._withTitleConfig(config);
+    if (next.compositionSpec?.type === "facet") {
+      return next.materializeComposition();
+    }
     resolveTitleLayout(next, config);
     next = next.createTitleText();
     if (subtitle !== undefined) next = next.createSubtitleText();
@@ -205,8 +222,13 @@ export const createTitle = action(
 );
 
 export const editTitle = action(
-  { op: "editTitle", description: "Edit one stable chart title resource." },
+  {
+    op: "editTitle",
+    description: "Edit one stable chart title resource.",
+    scope: "any"
+  },
   function (args = {}) {
+    assertTitleScope(this, "editTitle");
     if (this.semanticSpec.title.text === undefined) {
       throw new Error("editTitle requires an existing chart title.");
     }
@@ -229,7 +251,46 @@ export const editTitle = action(
       });
     }
     next = next._withTitleConfig(normalized.config);
+    if (next.compositionSpec?.type === "facet") {
+      return next.materializeComposition();
+    }
     resolveTitleLayout(next, normalized.config);
     return next.rematerializeTitle();
   }
 );
+
+export const removeTitle = action(
+  {
+    op: "removeTitle",
+    description: "Remove the complete chart title resource.",
+    scope: "any"
+  },
+  function (args = {}) {
+    assertTitleScope(this, "removeTitle");
+    noOptions(args, "removeTitle");
+    if (
+      this.semanticSpec.title.text === undefined &&
+      this.titleConfig === undefined &&
+      this.graphicSpec.objects.chartTitle === undefined &&
+      this.graphicSpec.objects.chartSubtitle === undefined
+    ) {
+      throw new Error("removeTitle requires an existing chart title.");
+    }
+    let next = this;
+    if (next.semanticSpec.title.subtitle !== undefined) {
+      next = next.editSemantic({ property: "title.subtitle", remove: true });
+    }
+    if (next.semanticSpec.title.text !== undefined) {
+      next = next.editSemantic({ property: "title.text", remove: true });
+    }
+    for (const id of ["chartTitle", "chartSubtitle"]) {
+      if (next.graphicSpec.objects[id] !== undefined) {
+        next = next.editGraphics({ target: id, remove: true });
+      }
+    }
+    next = next._withoutMaterializationConfig(["title"]);
+    return next.compositionSpec?.type === "facet"
+      ? next.materializeComposition()
+      : next;
+  }
+);

package/src/actions/titles/index.js

@@ -3,6 +3,7 @@ import {
   createTitle,
   createTitleText,
   editTitle,
+  removeTitle,
   editSubtitleText,
   editTitleText,
   rematerializeTitle
@@ -11,6 +12,7 @@ import {
 export function registerTitleActions(ProgramClass) {
   ProgramClass.prototype.createTitle = createTitle;
   ProgramClass.prototype.editTitle = editTitle;
+  ProgramClass.prototype.removeTitle = removeTitle;
   ProgramClass.prototype.createTitleText = createTitleText;
   ProgramClass.prototype.editTitleText = editTitleText;
   ProgramClass.prototype.createSubtitleText = createSubtitleText;

package/src/actions/titles/resolve.js

@@ -1,6 +1,7 @@
 import { isPlainObject } from "../../core/immutable.js";
 import {
   validateKeys,
+  validateOptionObject,
   validateNonEmptyString,
   validateNonNegativeFinite,
   validatePositiveFinite
@@ -8,6 +9,7 @@ import {
 import { resolveGraphicBounds } from "../../layout/canvas.js";
 import { resolveConcreteGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
 import {
+  alignedTextAnchor,
   alignedTitleAnchor,
   buildTitleReadingBlock,
   layoutBoundsIntersect,
@@ -15,6 +17,8 @@ import {
   unionTitleBounds
 } from "../../layout/title.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../theme/defaults.js";
+import { findCanvasGraphic } from
+  "../../materialization/graphicHierarchy.js";
 
 const OPTIONS = Object.freeze([
   "text", "subtitle", "position", "align", "offset", "gap", "titleStyle",
@@ -129,10 +133,7 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
 }
 
 export function normalizeTitleOptions(args) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("createTitle options must be a plain object.");
-  }
-  validateKeys(args, OPTIONS, "createTitle");
+  validateOptionObject(args, OPTIONS, "createTitle");
   const text = validateTitleString(args.text, "Chart title text");
   const subtitle = args.subtitle === undefined
     ? undefined
@@ -145,13 +146,11 @@ export function normalizeTitleOptions(args) {
 }
 
 export function normalizeTitleEditOptions(args, previous, semanticTitle) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("editTitle options must be a plain object.");
-  }
-  validateKeys(args, OPTIONS, "editTitle");
-  if (Object.keys(args).length === 0) {
-    throw new Error("editTitle requires at least one change.");
-  }
+  validateOptionObject(args, OPTIONS, "editTitle", {
+    allowEmpty: false,
+    emptyMessage: "editTitle requires at least one change.",
+    emptyError: Error
+  });
   const text = args.text === undefined
     ? semanticTitle.text
     : validateTitleString(args.text, "Chart title text");
@@ -233,7 +232,7 @@ function validateLayout(program, position, titleBounds, plot, canvas) {
 
 export function resolveTitleLayout(program, config) {
   const plot = resolveGraphicBounds(program);
-  const canvas = program.graphicSpec.objects.canvas;
+  const canvas = findCanvasGraphic(program);
   if (
     plot === undefined ||
     ![plot.x, plot.y, plot.width, plot.height].every(Number.isFinite) ||
@@ -256,11 +255,7 @@ export function resolveTitleLayout(program, config) {
   let title;
   let subtitle;
   if (horizontal) {
-    const x = config.align === "left"
-      ? plot.x
-      : config.align === "center"
-        ? plot.x + plot.width / 2
-        : plot.x + plot.width;
+    const x = alignedTextAnchor(plot.x, plot.width, config.align);
     const blockTop = config.position === "top"
       ? 16 + config.offset
       : plot.y + plot.height + config.offset;

package/src/composition.js

@@ -0,0 +1,10 @@
+import { chart } from "./ChartProgram.js";
+import { hconcatAction, vconcatAction } from "./actions/composition/actions.js";
+
+export function hconcat(options) {
+  return hconcatAction.call(chart(), options);
+}
+
+export function vconcat(options) {
+  return vconcatAction.call(chart(), options);
+}

package/src/core/ChartProgram.js

@@ -15,12 +15,186 @@ import {
   createEmptySemanticSpec,
   createTraceRoot
 } from "./specs.js";
-import { LEGEND_CONFIG_KINDS } from "./vocabulary.js";
+import {
+  FACET_SCALE_CHANNELS,
+  FACET_SCALE_RESOLUTIONS,
+  LEGEND_CONFIG_KINDS
+} from "./vocabulary.js";
 
 function ownState(value) {
   return isOwned(value) ? value : cloneAndFreeze(value);
 }
 
+function ownChildPrograms(children) {
+  if (!isPlainObject(children)) {
+    throw new TypeError("ChartProgram children must be a plain object.");
+  }
+  if (isOwned(children)) return children;
+  const owned = {};
+  for (const [id, program] of Object.entries(children)) {
+    if (typeof id !== "string" || id.length === 0) {
+      throw new TypeError("ChartProgram child IDs must be non-empty strings.");
+    }
+    if (!(program instanceof ChartProgram)) {
+      throw new TypeError(`ChartProgram child "${id}" must be a ChartProgram.`);
+    }
+    owned[id] = program;
+  }
+  return freezeOwned(owned);
+}
+
+function ownCompositionSpec(compositionSpec, children) {
+  const childIds = Object.keys(children);
+  if (compositionSpec === undefined) {
+    if (childIds.length > 0) {
+      throw new Error("ChartProgram children require a compositionSpec.");
+    }
+    return undefined;
+  }
+  if (!isPlainObject(compositionSpec)) {
+    throw new TypeError("ChartProgram compositionSpec must be a plain object.");
+  }
+  const allowed = [
+    "id", "type", "direction", "children", "columns", "gap", "align",
+    "padding", "facet"
+  ];
+  const unknown = Object.keys(compositionSpec).find(key => !allowed.includes(key));
+  if (unknown !== undefined) {
+    throw new Error(`Unknown compositionSpec property "${unknown}".`);
+  }
+  if (typeof compositionSpec.id !== "string" || compositionSpec.id.length === 0) {
+    throw new TypeError("compositionSpec.id must be a non-empty string.");
+  }
+  const facet = compositionSpec.type === "facet";
+  if (compositionSpec.type !== undefined && !facet) {
+    throw new Error(`Unknown compositionSpec type "${compositionSpec.type}".`);
+  }
+  if (facet) {
+    if (compositionSpec.direction !== undefined) {
+      throw new Error("Facet compositionSpec does not use direction.");
+    }
+  } else if (!["horizontal", "vertical"].includes(compositionSpec.direction)) {
+    throw new Error("compositionSpec.direction must be horizontal or vertical.");
+  }
+  if (
+    !Array.isArray(compositionSpec.children) ||
+    compositionSpec.children.length < (facet ? 1 : 2) ||
+    !compositionSpec.children.every(id => typeof id === "string" && id.length > 0)
+  ) {
+    throw new TypeError(
+      facet
+        ? "Facet compositionSpec.children requires at least one child ID."
+        : "compositionSpec.children requires at least two child IDs."
+    );
+  }
+  if (new Set(compositionSpec.children).size !== compositionSpec.children.length) {
+    throw new Error("compositionSpec.children must not contain duplicate IDs.");
+  }
+  if (
+    compositionSpec.children.length !== childIds.length ||
+    compositionSpec.children.some(id => !Object.hasOwn(children, id))
+  ) {
+    throw new Error("compositionSpec.children must match ChartProgram children exactly.");
+  }
+  if (facet) {
+    if (
+      !Number.isInteger(compositionSpec.columns) ||
+      compositionSpec.columns <= 0 ||
+      compositionSpec.columns > compositionSpec.children.length
+    ) {
+      throw new RangeError(
+        "Facet compositionSpec.columns must be a positive integer no larger than its children."
+      );
+    }
+    if (!isPlainObject(compositionSpec.facet)) {
+      throw new TypeError("Facet compositionSpec.facet must be a plain object.");
+    }
+    const facetKeys = ["data", "field", "values", "scales", "guides"];
+    const unknownFacet = Object.keys(compositionSpec.facet).find(
+      key => !facetKeys.includes(key)
+    );
+    if (unknownFacet !== undefined) {
+      throw new Error(`Unknown compositionSpec.facet property "${unknownFacet}".`);
+    }
+    for (const property of ["data", "field"]) {
+      if (
+        typeof compositionSpec.facet[property] !== "string" ||
+        compositionSpec.facet[property].length === 0
+      ) {
+        throw new TypeError(`compositionSpec.facet.${property} must be a non-empty string.`);
+      }
+    }
+    const values = compositionSpec.facet.values;
+    if (
+      !Array.isArray(values) ||
+      values.length !== compositionSpec.children.length ||
+      values.some(value => !(
+        typeof value === "string" ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value))
+      )) ||
+      new Set(values).size !== values.length
+    ) {
+      throw new TypeError(
+        "compositionSpec.facet.values must contain one unique scalar per child."
+      );
+    }
+    const scales = compositionSpec.facet.scales;
+    if (
+      !isPlainObject(scales) ||
+      Object.keys(scales).length !== FACET_SCALE_CHANNELS.length ||
+      FACET_SCALE_CHANNELS.some(channel =>
+        !FACET_SCALE_RESOLUTIONS.includes(scales[channel])
+      ) ||
+      Object.keys(scales).some(channel => !FACET_SCALE_CHANNELS.includes(channel))
+    ) {
+      throw new Error(
+        "compositionSpec.facet.scales requires one shared or independent policy per supported channel."
+      );
+    }
+    const guides = compositionSpec.facet.guides;
+    if (
+      !isPlainObject(guides) ||
+      Object.keys(guides).some(key => !["axes", "legend"].includes(key)) ||
+      !["each", "outer"].includes(guides.axes) ||
+      ![false, "shared"].includes(guides.legend)
+    ) {
+      throw new Error(
+        'compositionSpec.facet.guides requires axes "each" or "outer" and legend false or "shared".'
+      );
+    }
+  } else if (
+    compositionSpec.columns !== undefined ||
+    compositionSpec.facet !== undefined
+  ) {
+    throw new Error("Concat compositionSpec does not accept facet properties.");
+  }
+  if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
+    throw new RangeError("compositionSpec.gap must be a non-negative finite number.");
+  }
+  if (!["start", "center", "end"].includes(compositionSpec.align)) {
+    throw new Error("compositionSpec.align must be start, center, or end.");
+  }
+  if (!isPlainObject(compositionSpec.padding)) {
+    throw new TypeError("compositionSpec.padding must be a plain object.");
+  }
+  for (const side of ["top", "right", "bottom", "left"]) {
+    if (!Number.isFinite(compositionSpec.padding[side]) || compositionSpec.padding[side] < 0) {
+      throw new RangeError(
+        `compositionSpec.padding.${side} must be a non-negative finite number.`
+      );
+    }
+  }
+  const paddingKeys = Object.keys(compositionSpec.padding);
+  if (
+    paddingKeys.length !== 4 ||
+    paddingKeys.some(key => !["top", "right", "bottom", "left"].includes(key))
+  ) {
+    throw new Error("compositionSpec.padding must contain exactly four sides.");
+  }
+  return ownState(compositionSpec);
+}
+
 function createMaterializationConfigs(
   markConfigs,
   guideConfigs,
@@ -54,6 +228,8 @@ export class ChartProgram {
     guideConfigs = {},
     titleConfig,
     canvasConfig,
+    children = {},
+    compositionSpec,
     context = {},
     trace = createTraceRoot(),
     actionStack = [],
@@ -70,6 +246,8 @@ export class ChartProgram {
           canvasConfig
         )
       : ownState(materializationConfigs);
+    this.children = ownChildPrograms(children);
+    this.compositionSpec = ownCompositionSpec(compositionSpec, this.children);
     this.context = ownState(context);
     this.trace = ownState(trace);
     this.actionStack = ownState(actionStack);
@@ -118,6 +296,8 @@ export class ChartProgram {
     graphicSpec = this.graphicSpec,
     resolvedScales = this.resolvedScales,
     materializationConfigs = this.materializationConfigs,
+    children = this.children,
+    compositionSpec = this.compositionSpec,
     context = this.context,
     trace = this.trace,
     actionStack = this.actionStack,
@@ -128,6 +308,8 @@ export class ChartProgram {
       graphicSpec,
       resolvedScales,
       materializationConfigs,
+      children,
+      compositionSpec,
       context,
       trace,
       actionStack,
@@ -135,6 +317,22 @@ export class ChartProgram {
     });
   }
 
+  _assertUnitProgram(operation) {
+    if (this.compositionSpec !== undefined) {
+      throw new Error(`${operation} is not available on a composition ChartProgram.`);
+    }
+  }
+
+  _assertCompositionProgram(operation) {
+    if (this.compositionSpec === undefined) {
+      throw new Error(`${operation} requires a composition ChartProgram.`);
+    }
+  }
+
+  _withCompositionState({ children, compositionSpec, graphicSpec = this.graphicSpec }) {
+    return this._clone({ children, compositionSpec, graphicSpec });
+  }
+
   _withContext(patch = {}) {
     if (!isPlainObject(patch)) {
       throw new TypeError("Context patch must be a plain object.");
@@ -257,7 +455,7 @@ export class ChartProgram {
   }
 
   _withGridConfig(direction, config) {
-    if (!["horizontal", "vertical"].includes(direction)) {
+    if (!["horizontal", "vertical", "theta", "radial"].includes(direction)) {
       throw new Error(`Unknown grid direction "${direction}".`);
     }
     if (!isPlainObject(config)) {

package/src/core/action.js

@@ -12,6 +12,8 @@ function summarizeObject(value, ancestors = new WeakSet()) {
       summary[`${key}Count`] = item.length;
     } else if (isPlainObject(item)) {
       summary[key] = summarizeObject(item, ancestors);
+    } else if (item !== null && typeof item === "object") {
+      summary[`${key}Type`] = item.constructor?.name ?? "object";
     } else {
       summary[key] = item;
     }
@@ -100,11 +102,19 @@ export function action(metadata, implementation) {
     throw new TypeError("Action implementation must be a function.");
   }
 
+  const scope = metadata.scope ?? "unit";
+  if (!["unit", "composition", "any"].includes(scope)) {
+    throw new Error(`Unknown action scope "${scope}".`);
+  }
+
   return function wrappedAction(args = {}) {
     if (!isPlainObject(args)) {
       throw new TypeError("Action arguments must be a plain object.");
     }
 
+    if (scope === "unit") this._assertUnitProgram(metadata.op);
+    if (scope === "composition") this._assertCompositionProgram(metadata.op);
+
     const entered = this._enterAction({
       ...metadata,
       args: summarizeArgs(args)

package/src/core/validation.js

@@ -8,6 +8,22 @@ export function validateKeys(value, supported, label) {
   }
 }
 
+export function validateOptionObject(value, supported, label, {
+  allowEmpty = true,
+  plainObjectMessage = `${label} options must be a plain object.`,
+  emptyMessage = `${label} requires at least one option.`,
+  emptyError = TypeError
+} = {}) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(plainObjectMessage);
+  }
+  if (supported !== undefined) validateKeys(value, supported, label);
+  if (!allowEmpty && Object.keys(value).length === 0) {
+    throw new emptyError(emptyMessage);
+  }
+  return value;
+}
+
 export function noOptions(args, operation) {
   if (!isPlainObject(args) || Object.keys(args).length > 0) {
     throw new Error(`${operation} does not accept options.`);

package/src/core/vocabulary.js

@@ -3,15 +3,30 @@ export const MARK_TYPES = Object.freeze([
   "line",
   "bar",
   "area",
-  "rule"
+  "arc",
+  "rule",
+  "text",
+  "rect"
 ]);
 
+export const MARK_GRAPHIC_TYPES = Object.freeze({
+  point: Object.freeze(["circle", "rect", "path", "collection"]),
+  line: Object.freeze(["path"]),
+  bar: Object.freeze(["rect"]),
+  area: Object.freeze(["path"]),
+  arc: Object.freeze(["path"]),
+  rule: Object.freeze(["line"]),
+  text: Object.freeze(["text"]),
+  rect: Object.freeze(["rect"])
+});
+
 export const ENCODING_CHANNELS = Object.freeze([
   "x",
   "y",
   "x2",
   "y2",
   "xOffset",
+  "yOffset",
   "theta",
   "radius",
   "color",
@@ -19,14 +34,149 @@ export const ENCODING_CHANNELS = Object.freeze([
   "size",
   "shape",
   "group",
-  "opacity"
+  "opacity",
+  "text"
+]);
+
+const CARTESIAN_MARK_TYPES = Object.freeze([
+  "point", "line", "bar", "area", "rule", "text", "rect"
 ]);
+const POLAR_MARK_TYPES = Object.freeze(["point", "line", "arc"]);
+
+export const POSITION_CHANNEL_DEFINITIONS = Object.freeze({
+  x: Object.freeze({
+    family: "cartesian",
+    role: "primary",
+    scaleChannel: "x",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    guideChannel: "x",
+    gridDirection: "vertical",
+    markTypes: CARTESIAN_MARK_TYPES
+  }),
+  y: Object.freeze({
+    family: "cartesian",
+    role: "primary",
+    scaleChannel: "y",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    guideChannel: "y",
+    gridDirection: "horizontal",
+    markTypes: CARTESIAN_MARK_TYPES
+  }),
+  x2: Object.freeze({
+    family: "cartesian",
+    role: "secondary",
+    scaleChannel: "x",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["area", "rule", "rect"])
+  }),
+  y2: Object.freeze({
+    family: "cartesian",
+    role: "secondary",
+    scaleChannel: "y",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["area", "rule", "rect"])
+  }),
+  xOffset: Object.freeze({
+    family: "cartesian",
+    role: "offset",
+    scaleChannel: "xOffset",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["bar"])
+  }),
+  yOffset: Object.freeze({
+    family: "cartesian",
+    role: "offset",
+    scaleChannel: "yOffset",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["bar"])
+  }),
+  theta: Object.freeze({
+    family: "polar",
+    role: "primary",
+    scaleChannel: "theta",
+    coordinate: Object.freeze({ id: "polar", type: "polar" }),
+    guideChannel: "theta",
+    gridDirection: "theta",
+    markTypes: POLAR_MARK_TYPES
+  }),
+  radius: Object.freeze({
+    family: "polar",
+    role: "primary",
+    scaleChannel: "radius",
+    coordinate: Object.freeze({ id: "polar", type: "polar" }),
+    guideChannel: "radius",
+    gridDirection: "radial",
+    markTypes: POLAR_MARK_TYPES
+  })
+});
 
 export const SCALED_ENCODING_CHANNELS = Object.freeze(
-  ENCODING_CHANNELS.filter(channel => channel !== "group")
+  ENCODING_CHANNELS.filter(channel => !["group", "text"].includes(channel))
+);
+
+export const POSITION_ENCODING_CHANNELS = Object.freeze(
+  Object.keys(POSITION_CHANNEL_DEFINITIONS)
+);
+
+export const OFFSET_POSITION_CHANNELS = Object.freeze(
+  POSITION_ENCODING_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].role === "offset"
+  )
+);
+
+export const CARTESIAN_POSITION_CHANNELS = Object.freeze(
+  POSITION_ENCODING_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].family === "cartesian" &&
+    POSITION_CHANNEL_DEFINITIONS[channel].role === "primary"
+  )
+);
+
+export const POLAR_POSITION_CHANNELS = Object.freeze(
+  POSITION_ENCODING_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].family === "polar" &&
+    POSITION_CHANNEL_DEFINITIONS[channel].role === "primary"
+  )
 );
 
-export const POSITION_CHANNELS = Object.freeze(["x", "y"]);
+export const POSITION_CHANNELS = Object.freeze([
+  ...CARTESIAN_POSITION_CHANNELS,
+  ...POLAR_POSITION_CHANNELS
+]);
+
+export const FACET_SCALE_CHANNELS = Object.freeze([
+  "x",
+  "y",
+  "xOffset",
+  "yOffset",
+  "color",
+  "size",
+  "shape",
+  "opacity",
+  "strokeDash"
+]);
+
+export const FACET_SCALE_RESOLUTIONS = Object.freeze([
+  "shared",
+  "independent"
+]);
+
+export function getPositionChannelDefinition(channel) {
+  return POSITION_CHANNEL_DEFINITIONS[channel];
+}
+
+export function normalizePositionScaleChannel(channel) {
+  return POSITION_CHANNEL_DEFINITIONS[channel]?.scaleChannel ?? channel;
+}
+
+export function positionChannelsForFamily(family) {
+  return POSITION_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].family === family
+  );
+}
+
+export function getMarkGraphicTypes(markType) {
+  return MARK_GRAPHIC_TYPES[markType];
+}
 
 export const COLOR_LAYOUTS = Object.freeze([
   "stack",