ggaction 0.0.7 → 0.0.8

package/src/actions/marks/tick/actions.js

@@ -0,0 +1,225 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validatePositiveFinite,
+  validateUnitInterval
+} from "../../../core/validation.js";
+import {
+  centeredDirectionalSegment,
+  resolveDirectionValues
+} from "../../../grammar/direction.js";
+import { resolveMarkGraphicPlacement } from
+  "../../../materialization/graphicHierarchy.js";
+import { resolveRowEncodingValues } from
+  "../../../materialization/rowEncoding.js";
+import { findDataset } from "../../../selectors/datasets.js";
+import { findLayer } from "../../../selectors/layers.js";
+import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import { rematerializeHighlightBaseline } from "../lifecycle.js";
+import {
+  applyLayeredMarkInheritance,
+  assertMarkAvailable,
+  materializeInheritedMark,
+  resolveLayeredMarkInheritance,
+  resolveMarkData,
+  resolveMarkId,
+  validateMarkOptions
+} from "../shared.js";
+
+const CREATE_OPTIONS = Object.freeze([
+  "id", "data", "length", "stroke", "strokeWidth", "opacity"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "length", "stroke", "strokeWidth", "opacity"
+]);
+const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+
+export const DEFAULT_TICK_CONFIG = Object.freeze({
+  length: 14,
+  stroke: DEFAULT_COLORS.mark,
+  strokeWidth: 2,
+  opacity: 1
+});
+
+function resolveTick(program, requested, operation) {
+  const candidates = program.semanticSpec.layers.filter(
+    layer => layer.mark?.type === "tick"
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Tick mark id");
+    const layer = findLayer(program, id);
+    if (layer?.mark?.type !== "tick") {
+      throw new Error(`Unknown tick mark "${id}".`);
+    }
+    return layer;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current?.mark?.type === "tick") return current;
+  if (candidates.length === 1) return candidates[0];
+  if (candidates.length === 0) {
+    throw new Error(`${operation} requires an existing tick mark.`);
+  }
+  throw new Error(`${operation} target is ambiguous; provide target.`);
+}
+
+function validateTickConfig(args, current = DEFAULT_TICK_CONFIG) {
+  return {
+    length: Object.hasOwn(args, "length")
+      ? validatePositiveFinite(args.length, "Tick length")
+      : current.length,
+    stroke: Object.hasOwn(args, "stroke")
+      ? validateNonEmptyString(args.stroke, "Tick stroke")
+      : current.stroke,
+    strokeWidth: Object.hasOwn(args, "strokeWidth")
+      ? validateNonNegativeFinite(args.strokeWidth, "Tick strokeWidth")
+      : current.strokeWidth,
+    opacity: Object.hasOwn(args, "opacity")
+      ? validateUnitInterval(args.opacity, "Tick opacity")
+      : current.opacity
+  };
+}
+
+export const createTickMark = action(
+  {
+    op: "createTickMark",
+    description: "Create a centered fixed-length Tick mark."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, CREATE_OPTIONS, "createTickMark");
+    const id = resolveMarkId(this, args.id, {
+      defaultId: "tick",
+      label: "Tick mark id",
+      markType: "tick",
+      operation: "createTickMark"
+    });
+    const inherited = resolveLayeredMarkInheritance(this, args, "tick");
+    const { data } = resolveMarkData(this, {
+      ...args,
+      ...(args.data === undefined && this.context.currentData === undefined &&
+        inherited?.data !== undefined ? { data: inherited.data } : {})
+    });
+    const config = validateTickConfig(args);
+    assertMarkAvailable(this, id);
+
+    let created = this
+      .editSemantic({ property: `layer[${id}].mark.type`, value: "tick" })
+      .editSemantic({ property: `layer[${id}].data`, value: data });
+    created = applyLayeredMarkInheritance(created, id, inherited)
+      .createGraphics({
+        id,
+        type: "line",
+        length: 0,
+        ...resolveMarkGraphicPlacement(created, { data, markType: "tick" })
+      })
+      ._withMarkConfig(id, DEFAULT_TICK_CONFIG);
+    const materialized = materializeInheritedMark(created, id);
+    const appearance = Object.fromEntries(
+      ["length", "stroke", "strokeWidth", "opacity"]
+        .filter(property => Object.hasOwn(args, property))
+        .map(property => [property, config[property]])
+    );
+    return Object.keys(appearance).length === 0
+      ? materialized
+      : materialized.editTickMark({ target: id, ...appearance });
+  }
+);
+
+export const editTickMark = action(
+  {
+    op: "editTickMark",
+    description: "Edit Tick length and constant line appearance."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, EDIT_OPTIONS, "editTickMark");
+    const editable = ["length", "stroke", "strokeWidth", "opacity"];
+    if (!editable.some(property => Object.hasOwn(args, property))) {
+      throw new Error(
+        "editTickMark requires length, stroke, strokeWidth, or opacity."
+      );
+    }
+    const layer = resolveTick(this, args.target, "editTickMark");
+    const config = validateTickConfig(args, {
+      ...DEFAULT_TICK_CONFIG,
+      ...this.markConfigs[layer.id]
+    });
+    return this
+      ._withMarkConfig(layer.id, config)
+      .rematerializeTickMark({ id: layer.id });
+  }
+);
+
+export const rematerializeTickMark = action(
+  {
+    op: "rematerializeTickMark",
+    description: "Recompute concrete centered Tick endpoints and appearance."
+  },
+  function (args = {}) {
+    validateMarkOptions(
+      args,
+      REMATERIALIZE_OPTIONS,
+      "rematerializeTickMark"
+    );
+    const id = validateUserId(args.id, "Tick mark id");
+    const highlighted = rematerializeHighlightBaseline(this, {
+      target: id,
+      operation: "rematerializeTickMark",
+      resetProperty: "length",
+      resetValue: 0
+    });
+    if (highlighted !== undefined) return highlighted;
+    const layer = findLayer(this, id);
+    if (layer?.mark?.type !== "tick") {
+      throw new Error(`Unknown tick mark "${id}".`);
+    }
+    const graphic = this.graphicSpec.objects[id];
+    if (graphic?.type !== "line" || !Array.isArray(graphic.items)) {
+      throw new Error(`Tick mark "${id}" requires line collection graphics.`);
+    }
+    const dataset = findDataset(this, layer.data);
+    if (dataset === undefined) {
+      throw new Error(`Tick mark "${id}" requires an existing dataset.`);
+    }
+    if (
+      layer.encoding?.x?.scale === undefined ||
+      layer.encoding?.y?.scale === undefined
+    ) {
+      return graphic.items.length === 0
+        ? this
+        : this.editGraphics({ target: id, property: "length", value: 0 });
+    }
+
+    const x = resolveRowEncodingValues(this, layer, dataset, "x");
+    const y = resolveRowEncodingValues(this, layer, dataset, "y");
+    const angles = resolveDirectionValues(dataset.values, layer.encoding?.angle);
+    const config = validateTickConfig({}, {
+      ...DEFAULT_TICK_CONFIG,
+      ...this.markConfigs[id]
+    });
+    const segments = dataset.values.map((_, index) =>
+      centeredDirectionalSegment({
+        x: x[index],
+        y: y[index],
+        degrees: angles?.[index] ?? 0,
+        length: config.length
+      })
+    );
+
+    return this
+      .editGraphics({ target: id, property: "length", value: segments.length })
+      .editGraphics({ target: id, property: "x1", value: segments.map(item => item.x1) })
+      .editGraphics({ target: id, property: "y1", value: segments.map(item => item.y1) })
+      .editGraphics({ target: id, property: "x2", value: segments.map(item => item.x2) })
+      .editGraphics({ target: id, property: "y2", value: segments.map(item => item.y2) })
+      .editGraphics({ target: id, property: "stroke", value: config.stroke })
+      .editGraphics({ target: id, property: "strokeWidth", value: config.strokeWidth })
+      .editGraphics({ target: id, property: "opacity", value: config.opacity });
+  }
+);
+
+export function registerTickMarkActions(ProgramClass) {
+  ProgramClass.prototype.createTickMark = createTickMark;
+  ProgramClass.prototype.editTickMark = editTickMark;
+  ProgramClass.prototype.rematerializeTickMark = rematerializeTickMark;
+}

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

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

package/src/actions/primitives/semanticValidation/layer.js

@@ -16,6 +16,7 @@ import {
   validateParallelMissingPolicy
 } from "../../../grammar/parallelCoordinates.js";
 import { validatePathOrderDirection } from "../../../grammar/pathOrder.js";
+import { normalizeCategoryOrder } from "../../../grammar/categoryOrder.js";
 import { validateSemanticFieldType } from "../../../grammar/scales/index.js";
 import { findLayer } from "../../../selectors/layers.js";
 import { validateNonEmptySemanticString } from "./shared.js";
@@ -50,6 +51,7 @@ export function validateLayerSemanticValue(program, parsed, value) {
   }
   if (property.endsWith(".fieldType")) validateSemanticFieldType(value);
   if (property === "encoding.pathOrder.order") validatePathOrderDirection(value);
+  if (property.endsWith(".categoryOrder")) normalizeCategoryOrder(value);
   if (property === "encoding.parallel.dimensions") {
     validateParallelDimensions(value, { normalized: true });
   }

package/src/actions/scales/consumers/index.js

@@ -6,6 +6,7 @@ import {
   requireConsumerDataset
 } from "./common.js";
 import { resolveMarkFamilyConsumerValues } from "./families.js";
+import { resolveCategoryOrder } from "../../../grammar/categoryOrder.js";
 
 export { findScale, findScaleConsumers } from "./common.js";
 export {
@@ -39,3 +40,10 @@ export function resolveConsumerValues(program, consumer) {
     ? family.values
     : readConsumerFieldValues(program, consumer, dataset, scale);
 }
+
+export function resolveConsumerCategoryOrder(program, consumer) {
+  const order = consumer.encoding.categoryOrder;
+  if (order === undefined) return undefined;
+  const dataset = requireConsumerDataset(program, consumer);
+  return resolveCategoryOrder(dataset.values, consumer.encoding.field, order);
+}

package/src/actions/scales/consumers/seriesLayout.js

@@ -10,7 +10,10 @@ import {
   findHistogramBinIndex,
   resolveHistogramBins
 } from "../../../grammar/histogram.js";
-import { deriveDensityAreaSeries } from "../../../grammar/areaSeries.js";
+import {
+  deriveCenteredAreaSeries,
+  deriveDensityAreaSeries
+} from "../../../grammar/areaSeries.js";
 import {
   resolveSeriesLayoutDomainValues
 } from "../../../grammar/seriesLayout.js";
@@ -122,6 +125,16 @@ function resolveAreaPartitions(program, consumer) {
     dataset.transform[0].type === "density"
     ? dataset.transform[0]
     : undefined;
+  if (
+    transform === undefined &&
+    layer.encoding?.y?.stack === "center" &&
+    layer.encoding?.x !== undefined
+  ) {
+    const derived = deriveCenteredAreaSeries(dataset.values, layer);
+    return Array.from({ length: derived.series[0].values.length }, (_, index) =>
+      derived.series.map(series => series.values[index].y)
+    );
+  }
   if (transform === undefined) return undefined;
   const derived = deriveDensityAreaSeries(dataset.values, layer, transform);
   if (derived.mode !== "y-density") return undefined;
@@ -153,10 +166,17 @@ export function resolveSeriesLayoutScaleValues(program, consumer) {
   }
   if (consumer.channel !== "y") return undefined;
   if (consumer.layer.mark?.type === "area") {
-    const layout = consumer.layer.encoding?.color?.layout;
+    const layout = consumer.layer.encoding?.y?.stack === "center"
+      ? "center"
+      : consumer.layer.encoding?.color?.layout;
     if (layout === undefined || layout === "overlay") return undefined;
     const partitions = resolveAreaPartitions(program, consumer);
     if (partitions === undefined) {
+      if (
+        layout === "center" &&
+        consumer.layer.encoding?.y?.stack === "center" &&
+        consumer.layer.encoding?.x === undefined
+      ) return undefined;
       throw new Error(
         `Area layout "${layout}" currently requires vertical density series.`
       );

package/src/actions/scales/materialize.js

@@ -19,6 +19,7 @@ import { resolveScaleMaterialization } from
 import {
   findScale,
   findScaleConsumers,
+  resolveConsumerCategoryOrder,
   resolveConsumerValues,
   resolveSeriesLayoutScaleValues
 } from "./consumers/index.js";
@@ -62,6 +63,7 @@ export const rematerializeScale = action(
     const valuesByConsumer = consumers.map(consumer => ({
       consumer,
       values: resolveConsumerValues(this, consumer),
+      categoryOrder: resolveConsumerCategoryOrder(this, consumer),
       seriesLayout: resolveSeriesLayoutScaleValues(this, consumer)
     }));
     const resolvedScale = resolveScaleMaterialization({

package/src/actions/selection/actions.js

@@ -340,8 +340,11 @@ export const applyRuleHighlight = action(
     validateKeys(args, INTERNAL_SELECTION_OPTIONS, "applyRuleHighlight");
     const resolved = resolveStoredSelection(this, args.selection);
     const keys = selectedKeys(args, resolved);
-    if (resolved.items[0]?.markType !== "rule" && resolved.items.length > 0) {
-      throw new Error("applyRuleHighlight requires a rule selection.");
+    if (
+      resolved.items.length > 0 &&
+      !["rule", "tick"].includes(resolved.items[0]?.markType)
+    ) {
+      throw new Error("applyRuleHighlight requires a rule or Tick selection.");
     }
     if (keys.length === 0) return this;
     const selected = new Set(keys);

package/src/core/vocabulary.js

@@ -5,6 +5,7 @@ export const MARK_TYPES = Object.freeze([
   "area",
   "arc",
   "rule",
+  "tick",
   "text",
   "rect"
 ]);
@@ -16,6 +17,7 @@ export const MARK_GRAPHIC_TYPES = Object.freeze({
   area: Object.freeze(["path"]),
   arc: Object.freeze(["path"]),
   rule: Object.freeze(["line"]),
+  tick: Object.freeze(["line"]),
   text: Object.freeze(["text"]),
   rect: Object.freeze(["rect"])
 });
@@ -34,6 +36,7 @@ export const ENCODING_CHANNELS = Object.freeze([
   "strokeWidth",
   "size",
   "shape",
+  "angle",
   "group",
   "pathOrder",
   "opacity",
@@ -41,7 +44,7 @@ export const ENCODING_CHANNELS = Object.freeze([
 ]);
 
 const CARTESIAN_MARK_TYPES = Object.freeze([
-  "point", "line", "bar", "area", "rule", "text", "rect"
+  "point", "line", "bar", "area", "rule", "tick", "text", "rect"
 ]);
 const POLAR_MARK_TYPES = Object.freeze(["point", "line", "arc"]);
 
@@ -114,7 +117,7 @@ export const POSITION_CHANNEL_DEFINITIONS = Object.freeze({
 
 export const SCALED_ENCODING_CHANNELS = Object.freeze(
   ENCODING_CHANNELS.filter(channel =>
-    !["group", "pathOrder", "text"].includes(channel)
+    !["angle", "group", "pathOrder", "text"].includes(channel)
   )
 );
 
@@ -185,12 +188,13 @@ export function getMarkGraphicTypes(markType) {
 export const COLOR_LAYOUTS = Object.freeze([
   "stack",
   "fill",
+  "center",
   "group",
   "overlay",
   "diverging"
 ]);
 
-export const STACK_MODES = Object.freeze(["zero", "normalize"]);
+export const STACK_MODES = Object.freeze(["zero", "normalize", "center"]);
 
 export const CATEGORICAL_LEGEND_CHANNELS = Object.freeze([
   "color",

package/src/grammar/areaSeries.js

@@ -120,6 +120,110 @@ export function deriveAreaSeries(rows, layer) {
   });
 }
 
+export function deriveCenteredAreaSeries(rows, layer) {
+  if (layer?.mark?.type !== "area") {
+    throw new Error("Centered area series derivation requires an area mark.");
+  }
+  const { x, y, x2, y2, group, color } = layer.encoding ?? {};
+  if (
+    !["quantitative", "temporal"].includes(x?.fieldType) ||
+    y?.fieldType !== "quantitative" ||
+    y?.stack !== "center" ||
+    x2 !== undefined ||
+    y2 !== undefined
+  ) {
+    throw new Error(
+      `Centered area mark "${layer.id}" requires one x field and one quantitative y field without ranged endpoints.`
+    );
+  }
+  if (group?.fieldType !== "nominal") {
+    throw new Error(`Centered area mark "${layer.id}" requires a nominal group encoding.`);
+  }
+  if (color !== undefined && color.field !== group.field) {
+    throw new Error(
+      `Centered area color on mark "${layer.id}" must match its group field.`
+    );
+  }
+  const xValues = x.fieldType === "temporal"
+    ? readTemporalField(rows, x.field)
+    : readQuantitativeField(rows, x.field);
+  const yValues = readQuantitativeField(rows, y.field);
+  const groups = readNominalField(rows, group.field);
+  const groupOrder = [];
+  const positions = new Set();
+  const byGroup = new Map();
+  for (let index = 0; index < rows.length; index += 1) {
+    const key = groups[index];
+    if (!byGroup.has(key)) {
+      groupOrder.push(key);
+      byGroup.set(key, new Map());
+    }
+    const values = byGroup.get(key);
+    if (values.has(xValues[index])) {
+      throw new Error(
+        `Centered area mark "${layer.id}" has duplicate ${group.field}/${x.field} rows.`
+      );
+    }
+    values.set(xValues[index], yValues[index]);
+    positions.add(xValues[index]);
+  }
+  const orderedPositions = [...positions].sort((left, right) => left - right);
+  if (groupOrder.length === 0 || orderedPositions.length < 2) {
+    throw new Error(
+      `Centered area mark "${layer.id}" requires at least two aligned positions.`
+    );
+  }
+  for (const [key, values] of byGroup) {
+    if (
+      values.size !== orderedPositions.length ||
+      orderedPositions.some(position => !values.has(position))
+    ) {
+      throw new Error(
+        `Centered area series "${String(key)}" requires one aligned value at every x position.`
+      );
+    }
+  }
+
+  const valuesBySeries = groupOrder.map(() => []);
+  for (const position of orderedPositions) {
+    const partition = groupOrder.map(key => byGroup.get(key).get(position));
+    const segments = new Map(
+      layoutSeriesPartition(partition, "center").map(segment => [
+        segment.index,
+        segment
+      ])
+    );
+    let endpoint = -partition.reduce((sum, value) => sum + value, 0) / 2;
+    for (let index = 0; index < groupOrder.length; index += 1) {
+      const segment = segments.get(index);
+      valuesBySeries[index].push({
+        x: position,
+        y: partition[index],
+        lower: segment?.start ?? endpoint,
+        upper: segment?.end ?? endpoint
+      });
+      if (segment !== undefined) endpoint = segment.end;
+    }
+  }
+  const series = groupOrder.map((key, index) => ({
+    key: {
+      [group.field]: key,
+      ...(color === undefined ? {} : { [color.field]: key })
+    },
+    values: valuesBySeries[index]
+  }));
+  return cloneAndFreeze({
+    mode: "y-center",
+    orientation: "vertical",
+    xValues: orderedPositions,
+    yValues: series.flatMap(item => item.values.flatMap(value => [
+      value.lower,
+      value.upper
+    ])),
+    series
+  });
+}
+
 export function deriveDensityAreaSeries(rows, layer, transform) {
   if (layer?.mark?.type !== "area") {
     throw new Error("Density area derivation requires a semantic area mark.");
@@ -233,13 +337,19 @@ export function layoutDensityAreaSeries(derived, layout = "overlay") {
         segment
       ])
     );
+    let zeroThicknessEndpoint = layout === "center"
+      ? -densities.reduce((sum, value) => sum + value, 0) / 2
+      : 0;
     for (let index = 0; index < derived.series.length; index += 1) {
       const segment = segments.get(index);
       valuesBySeries[index].push({
         x,
-        lower: segment?.start ?? 0,
-        upper: segment?.end ?? 0
+        lower: segment?.start ?? zeroThicknessEndpoint,
+        upper: segment?.end ?? zeroThicknessEndpoint
       });
+      if (segment !== undefined && ["stack", "fill", "center"].includes(layout)) {
+        zeroThicknessEndpoint = segment.end;
+      }
     }
   }
 

package/src/grammar/categoryOrder.js

@@ -0,0 +1,138 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { isNominalValue, readNominalField } from "./scales/fields.js";
+
+const DIRECTIONS = Object.freeze(["ascending", "descending"]);
+const AGGREGATES = Object.freeze(["sum", "mean", "min", "max"]);
+
+function nonEmptyField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function sameValue(left, right) {
+  return Object.is(left, right);
+}
+
+export function normalizeCategoryOrder({ values, by, direction } = {}) {
+  const hasValues = values !== undefined;
+  const hasBy = by !== undefined;
+  if (hasValues === hasBy) {
+    throw new Error("Category order requires exactly one of values or by.");
+  }
+  if (hasValues) {
+    if (direction !== undefined) {
+      throw new Error("Explicit category order does not support direction.");
+    }
+    if (!Array.isArray(values) || values.length === 0) {
+      throw new TypeError("Category order values must be a non-empty array.");
+    }
+    if (!values.every(isNominalValue)) {
+      throw new TypeError("Category order values must contain nominal values.");
+    }
+    if (values.some((value, index) =>
+      values.slice(0, index).some(previous => sameValue(previous, value)))) {
+      throw new Error("Category order values must be unique.");
+    }
+    return cloneAndFreeze({ values });
+  }
+  if (!DIRECTIONS.includes(direction ?? "ascending")) {
+    throw new Error(`Unsupported category order direction "${direction}".`);
+  }
+  let normalizedBy;
+  if (["category", "count"].includes(by)) {
+    normalizedBy = by;
+  } else {
+    if (!isPlainObject(by)) {
+      throw new TypeError("Category order by must be category, count, or a summary object.");
+    }
+    const unknown = Object.keys(by).find(key => !["field", "aggregate"].includes(key));
+    if (unknown !== undefined) {
+      throw new Error(`Unknown category summary property "${unknown}".`);
+    }
+    const field = nonEmptyField(by.field, "Category summary field");
+    if (!AGGREGATES.includes(by.aggregate)) {
+      throw new Error(`Unsupported category summary aggregate "${by.aggregate}".`);
+    }
+    normalizedBy = { field, aggregate: by.aggregate };
+  }
+  return cloneAndFreeze({ by: normalizedBy, direction: direction ?? "ascending" });
+}
+
+function observedCategories(rows, field) {
+  return [...new Set(readNominalField(rows, field))];
+}
+
+function categoryComparison(left, right) {
+  if (typeof left !== typeof right) {
+    throw new TypeError("Category value ordering requires one uniform primitive type.");
+  }
+  if (typeof left === "number") return left - right;
+  if (typeof left === "boolean") return Number(left) - Number(right);
+  const leftPoints = Array.from(left, character => character.codePointAt(0));
+  const rightPoints = Array.from(right, character => character.codePointAt(0));
+  for (let index = 0; index < Math.min(leftPoints.length, rightPoints.length); index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) {
+      return leftPoints[index] - rightPoints[index];
+    }
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+function summaryValues(rows, categoryField, summary) {
+  const groups = new Map();
+  for (const [index, row] of rows.entries()) {
+    const category = row[categoryField];
+    const value = row[summary.field];
+    if (!Number.isFinite(value)) {
+      throw new TypeError(
+        `Category summary field "${summary.field}" must contain a finite number at row ${index}.`
+      );
+    }
+    const values = groups.get(category) ?? [];
+    values.push(value);
+    groups.set(category, values);
+  }
+  return new Map([...groups].map(([category, values]) => {
+    let value;
+    if (summary.aggregate === "sum") value = values.reduce((sum, item) => sum + item, 0);
+    else if (summary.aggregate === "mean") {
+      value = values.reduce((sum, item) => sum + item, 0) / values.length;
+    } else if (summary.aggregate === "min") value = Math.min(...values);
+    else value = Math.max(...values);
+    return [category, value];
+  }));
+}
+
+export function resolveCategoryOrder(rows, categoryField, order) {
+  const categories = observedCategories(rows, categoryField);
+  if (Object.hasOwn(order, "values")) {
+    for (const value of order.values) {
+      if (!categories.some(category => sameValue(category, value))) {
+        throw new Error(`Unknown category order value "${value}".`);
+      }
+    }
+    return cloneAndFreeze([
+      ...order.values,
+      ...categories.filter(category =>
+        !order.values.some(value => sameValue(value, category)))
+    ]);
+  }
+  const first = new Map(categories.map((value, index) => [value, index]));
+  const metrics = order.by === "count"
+    ? new Map(categories.map(category => [
+        category,
+        rows.filter(row => sameValue(row[categoryField], category)).length
+      ]))
+    : isPlainObject(order.by)
+      ? summaryValues(rows, categoryField, order.by)
+      : undefined;
+  const direction = order.direction === "descending" ? -1 : 1;
+  return cloneAndFreeze([...categories].sort((left, right) => {
+    const comparison = order.by === "category"
+      ? categoryComparison(left, right)
+      : metrics.get(left) - metrics.get(right);
+    return direction * comparison || first.get(left) - first.get(right);
+  }));
+}