cx 26.5.1 → 26.7.0

package/dist/ui.js

@@ -3829,9 +3829,38 @@ function startHotAppLoop(appModule, element, store, widgets, options = {}) {
 }
 
 class GroupAdapter extends ArrayAdapter {
+	/**
+	 * Per-level comparer derived from the active record sorters, used to reorder groups when
+	 * `sortGroupsBySorters` is set. A level's entry is `null` when no active sorter maps to that
+	 * level's key/aggregate, so the grouping's own configured order is kept.
+	 */
+	groupSortComparers;
 	constructor(config) {
 		super(config);
 	}
+	sort(sorters) {
+		super.sort(sorters);
+		// When enabled, derive a group comparer from the active record sorters so that interactive
+		// column sorting also reorders the groups. A column only reorders groups at levels where its
+		// field is a group key or aggregate; other levels keep their configured order. The record-level
+		// value selector is ignored — the field is resolved against the group's key/aggregates/name.
+		if (this.sortGroupsBySorters && this.groupings) {
+			const cultureComparer = this.sortOptions ? Culture.getComparer(this.sortOptions) : undefined;
+			const colSorters = isNonEmptyArray(sorters)
+				? sorters.map((s) => ({
+						field: s.field,
+						direction: s.direction,
+						comparer: s.comparer,
+					}))
+				: [];
+			this.groupSortComparers = this.groupings.map((g) => {
+				if (colSorters.length === 0) return null;
+				const fields = groupFieldNames(g, this.aggregates);
+				const applicable = colSorters.filter((s) => s.field && fields.has(s.field));
+				return applicable.length > 0 ? buildGroupComparer(applicable, cultureComparer) : null;
+			});
+		}
+	}
 	init() {
 		super.init();
 		if (this.groupRecordsAlias) {
@@ -3866,8 +3895,12 @@ class GroupAdapter extends ArrayAdapter {
 		grouper.reset();
 		grouper.processAll(records);
 		let results = grouper.getResults();
-		if (grouping.comparer && !this.preserveOrder) {
-			results.sort(grouping.comparer);
+		// An active column sort that maps to this level's key/aggregate (when `sortGroupsBySorters` is
+		// enabled) takes over; otherwise the grouping's configured comparer (or implicit key order) applies.
+		const dynamicComparer = this.sortGroupsBySorters ? this.groupSortComparers?.[level] : undefined;
+		const comparer = dynamicComparer ?? grouping.comparer;
+		if (comparer && !this.preserveOrder) {
+			results.sort(comparer);
 		}
 		results.forEach((gr) => {
 			keys.push(gr.key);
@@ -3949,15 +3982,26 @@ class GroupAdapter extends ArrayAdapter {
 					(r) => r.store.getData(),
 					g.text,
 				);
+				const cultureComparer = this.sortOptions ? Culture.getComparer(this.sortOptions) : undefined;
+				// Sort groups by an aggregate/key/name through `sortField`/`sortDirection` or a `sorters` array.
+				let sortSorters = null;
+				if (isNonEmptyArray(g.sorters)) sortSorters = g.sorters;
+				else if (g.sortField)
+					sortSorters = [
+						{
+							field: g.sortField,
+							direction: g.sortDirection ?? "ASC",
+						},
+					];
+				// `comparer`, `sortField`/`sorters` and the implicit key order are equivalent alternatives; an
+				// explicit `comparer` wins, then declarative sorters, then sorting by key in declaration order.
 				const comparer =
 					g.comparer ??
-					(groupSorters.length > 0
-						? getComparer(
-								groupSorters,
-								(x) => x.key,
-								this.sortOptions ? Culture.getComparer(this.sortOptions) : undefined,
-							)
-						: null);
+					(sortSorters
+						? buildGroupComparer(sortSorters, cultureComparer)
+						: groupSorters.length > 0
+							? getComparer(groupSorters, (x) => x.key, cultureComparer)
+							: null);
 				return {
 					...g,
 					key: resolvedKey,
@@ -3972,6 +4016,47 @@ class GroupAdapter extends ArrayAdapter {
 }
 GroupAdapter.prototype.groupName = "$group";
 GroupAdapter.prototype.preserveOrder = false;
+GroupAdapter.prototype.sortGroupsBySorters = false;
+// The set of fields a group can be sorted by at a given level: its key fields, its aggregate aliases
+// and the group name. Used to decide whether an active column sort applies to that grouping level.
+function groupFieldNames(grouping, adapterAggregates) {
+	const names = new Set();
+	for (const k of grouping.grouper.keys) names.add(k.name);
+	const aggregates = {
+		...adapterAggregates,
+		...grouping.aggregates,
+	};
+	for (const a in aggregates) names.add(a);
+	names.add("name");
+	names.add("$name");
+	return names;
+}
+// Reads a sort field straight from the GroupResult — first its key fields, then its aggregates, then
+// its name. Returns a plain selector so groups can be sorted without cloning the result per comparison.
+function groupFieldSelector(field) {
+	if (field === "name" || field === "$name") return (gr) => gr?.name;
+	return (gr) => {
+		if (gr?.key && field in gr.key) return gr.key[field];
+		if (gr?.aggregates && field in gr.aggregates) return gr.aggregates[field];
+		return undefined;
+	};
+}
+// Builds a group comparer from a list of sorters. Each sorter resolves by its explicit `value`
+// selector, or by `field` looked up against the group's key/aggregates/name.
+function buildGroupComparer(sorters, cultureComparer) {
+	return getComparer(
+		sorters.map((s) =>
+			isDefined(s.value) || !s.field
+				? s
+				: {
+						...s,
+						value: groupFieldSelector(s.field),
+					},
+		),
+		undefined,
+		cultureComparer,
+	);
+}
 function serializeKey(data) {
 	if (isDataRecord(data)) {
 		return Object.keys(data)

package/dist/widgets.css

@@ -1086,6 +1086,10 @@
   padding-left: 26px;
 }
 
+.cxs-clear > .cxe-numberfield-input {
+  padding-right: 22px;
+}
+
 .cxe-numberfield-tool {
   pointer-events: none;
   display: block;
@@ -5313,6 +5317,10 @@ th.cxe-calendar-display {
   content: counter(cx-row-number);
 }
 
+.cxe-grid-group-caption.cxs-reset-row-numbers {
+  counter-set: cx-row-number 0;
+}
+
 .cxe-grid-fixed-header {
   overflow: hidden;
   position: absolute;

package/dist/widgets.js

@@ -2050,6 +2050,7 @@ function captureMouse2(e, options) {
 		}
 	}
 	e.stopPropagation();
+	return tear;
 	function move(e) {
 		if (!active) {
 			tear();
@@ -2105,7 +2106,11 @@ function captureMouseOrTouch2(e, options) {
 		el.addEventListener("touchmove", move);
 		el.addEventListener("touchend", end);
 		e.stopPropagation();
-	} else captureMouse2(e, options);
+		return () => {
+			el.removeEventListener("touchmove", move);
+			el.removeEventListener("touchend", end);
+		};
+	} else return captureMouse2(e, options);
 }
 /**
  * Legacy function for capturing mouse events with individual parameters
@@ -2116,7 +2121,7 @@ function captureMouseOrTouch2(e, options) {
  * @param cursor - CSS cursor style for the capture surface
  */
 function captureMouse(e, onMouseMove, onMouseUp, captureData, cursor) {
-	captureMouse2(e, {
+	return captureMouse2(e, {
 		onMouseMove,
 		onMouseUp,
 		captureData,
@@ -2132,7 +2137,7 @@ function captureMouse(e, onMouseMove, onMouseUp, captureData, cursor) {
  * @param cursor - CSS cursor style for the capture surface
  */
 function captureMouseOrTouch(e, onMouseMove, onMouseUp, captureData, cursor) {
-	captureMouseOrTouch2(e, {
+	return captureMouseOrTouch2(e, {
 		onMouseMove,
 		onMouseUp,
 		captureData,
@@ -2403,6 +2408,7 @@ let puppet = null;
 let scrollTimer = null;
 let vscrollParent = null;
 let hscrollParent = null;
+let releaseCapture = null;
 function registerDropZone(dropZone) {
 	dropZones.push(dropZone);
 	return () => {
@@ -2488,7 +2494,15 @@ function initiateDragDrop(e, options = {}, onDragEnd) {
 		dragStartedZones.set(zone, true);
 	});
 	notifyDragMove(e);
-	captureMouseOrTouch(e, notifyDragMove, notifyDragDrop);
+	releaseCapture = captureMouseOrTouch(e, notifyDragMove, notifyDragDrop);
+	document.addEventListener("keydown", onDragKeyDown, true);
+}
+function onDragKeyDown(e) {
+	if (!puppet || e.key !== "Escape") return;
+	//cancel the operation without dropping; there is no pointer event to report
+	e.preventDefault();
+	e.stopPropagation();
+	notifyDragDrop(null, true);
 }
 function notifyDragMove(e, _captureData) {
 	let event = getDragEvent(e, "dragmove");
@@ -2613,21 +2627,36 @@ function clearScrollTimer() {
 		scrollTimer = null;
 	}
 }
-function notifyDragDrop(e) {
+function notifyDragDrop(e, cancelled = false) {
+	if (!puppet) return;
 	clearScrollTimer();
-	let event = getDragEvent(e, "dragdrop");
+	document.removeEventListener("keydown", onDragKeyDown, true);
 	if (puppet.stop) puppet.stop();
-	if (activeZone && activeZone.onDrop) event.result = activeZone.onDrop(event);
+	//a keyboard cancellation has no pointer event, so the drop and away notifications are skipped
+	let dropEvent = !cancelled && e ? getDragEvent(e, "dragdrop") : null;
+	let result;
+	if (dropEvent && activeZone && activeZone.onDrop) result = activeZone.onDrop(dropEvent);
+	let endEvent = {
+		type: "dragend",
+		event: e,
+		cursor: e ? getCursorPos(e) : null,
+		source: puppet.source,
+		cancelled,
+		result,
+	};
 	dropZones.forEach((zone) => {
-		if (nearZones != null && zone.onDragAway && nearZones.has(zone)) zone.onDragAway(event);
+		if (dropEvent && nearZones != null && zone.onDragAway && nearZones.has(zone)) zone.onDragAway(dropEvent);
 		if (!dragStartedZones.has(zone)) return;
-		if (zone.onDragEnd) zone.onDragEnd(event);
+		if (zone.onDragEnd) zone.onDragEnd(endEvent);
 	});
-	if (puppet.onDragEnd) puppet.onDragEnd(event);
+	if (puppet.onDragEnd) puppet.onDragEnd(endEvent);
+	//tear down the mouse/touch capture when cancelling; on a normal drop the capture ends itself
+	if (cancelled && releaseCapture) releaseCapture();
 	nearZones = null;
 	activeZone = null;
 	puppet = null;
 	dragStartedZones = null;
+	releaseCapture = null;
 }
 function getDragEvent(event, type) {
 	return {
@@ -8677,6 +8706,19 @@ class LookupField extends Field {
 			}
 		}
 		instance.lastDropdown = context.lastDropdown;
+		if (this.validateOptionExists && isArray(data.options) && !this.isEmpty(data)) {
+			let invalid = this.multiple
+				? isArray(data.values) && data.records.length < data.values.length
+				: !data.options.some(($option) =>
+						areKeysEqual(
+							getOptionKey(this.keyBindings, {
+								$option,
+							}),
+							data.selectedKeys[0],
+						),
+					);
+			if (invalid) data.error = this.invalidOptionText;
+		}
 		super.prepareData(context, instance);
 	}
 	renderInput(context, instance, key) {
@@ -8742,6 +8784,8 @@ LookupField.prototype.hideSearchField = false;
 LookupField.prototype.minOptionsForSearchField = 7;
 LookupField.prototype.loadingText = "Loading...";
 LookupField.prototype.queryErrorText = "Error occurred while querying for lookup data.";
+LookupField.prototype.validateOptionExists = false;
+LookupField.prototype.invalidOptionText = "The selected option is no longer available.";
 LookupField.prototype.noResultsText = "No results found.";
 LookupField.prototype.optionIdField = "id";
 LookupField.prototype.optionTextField = "text";
@@ -9775,6 +9819,7 @@ let Input$1 = class Input extends VDOM.Component {
 					visited: state.visited,
 					focus: this.state.focus,
 					icon: !!icon,
+					clear: insideButton != null,
 					empty: empty && !data.placeholder,
 					error: data.error && (state.visited || !suppressErrorsUntilVisited || !empty),
 				}),
@@ -15023,6 +15068,7 @@ class Grid extends ContainerBase {
 							sortOptions: this.sortOptions,
 							groupings: grouping,
 							preserveOrder: this.preserveGroupOrder,
+							sortGroupsBySorters: this.sortGroups,
 						},
 						this.dataAdapter,
 					);
@@ -15600,12 +15646,13 @@ class Grid extends ContainerBase {
 	renderGroupHeader(context, instance, g, level, group, i, store, fixedColumns) {
 		let { CSS, baseClass } = this;
 		let data = store.getData();
+		let resetRowNumbers = g.resetRowNumbers ? "reset-row-numbers" : null;
 		if (g.caption) {
 			let caption = g.caption(data);
 			return jsx(
 				"tbody",
 				{
-					className: CSS.element(baseClass, "group-caption", ["level-" + level]),
+					className: CSS.element(baseClass, "group-caption", ["level-" + level, resetRowNumbers]),
 					"data-group-key": group.$key,
 					"data-group-element": `group-caption-${level}`,
 					children: jsx("tr", {
@@ -15696,7 +15743,7 @@ class Grid extends ContainerBase {
 			return jsx(
 				"tbody",
 				{
-					className: CSS.element(baseClass, "group-caption", ["level-" + level]),
+					className: CSS.element(baseClass, "group-caption", ["level-" + level, resetRowNumbers]),
 					"data-group-key": group.$key,
 					"data-group-element": `group-caption-${level}`,
 					children: lines,
@@ -15967,6 +16014,7 @@ Grid.prototype.hoverChannel = "default";
 Grid.prototype.focusable = null; // automatically resolved
 Grid.prototype.allowsFileDrops = false;
 Grid.prototype.preserveGroupOrder = false;
+Grid.prototype.sortGroups = false;
 Widget.alias("grid", Grid);
 Localization.registerPrototype("cx/widgets/Grid", Grid);
 class GridComponent extends VDOM.Component {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cx",
-  "version": "26.5.1",
+  "version": "26.7.0",
   "description": "Advanced JavaScript UI framework for admin and dashboard applications with ready to use grid, form and chart components.",
   "exports": {
     "./data": {

package/src/data/ExposedValueView.spec.ts

@@ -0,0 +1,57 @@
+import assert from "assert";
+
+import { Binding } from "./Binding";
+import { Store } from "./Store";
+import { ExposedValueView } from "./ExposedValueView";
+
+describe("ExposedValueView", () => {
+   // Mirrors how Sandbox wires it: a `storage` object keyed by a slot `key`,
+   // exposed to children under `recordName` (e.g. "$page").
+   const getView = (key = "~/ordering/new") => {
+      let store = new Store({
+         data: {
+            pages: {
+               "~/ordering/new": { description: "draft order", count: 3 },
+            },
+         },
+      });
+
+      let view = new ExposedValueView({
+         store,
+         containerBinding: Binding.get("pages"),
+         key,
+         recordName: "$page",
+      });
+
+      return { store, view };
+   };
+
+   it("exposes the keyed slot under the record name", () => {
+      let { view } = getView();
+      assert.equal(view.get("$page.description"), "draft order");
+      assert.equal(view.get("$page.count"), 3);
+   });
+
+   it("writes back to the keyed slot on set", () => {
+      let { store, view } = getView();
+      view.set("$page.description", "edited");
+      assert.equal(store.get("pages")["~/ordering/new"].description, "edited");
+   });
+
+   it("deletes a property within the exposed record", () => {
+      let { store, view } = getView();
+      view.delete("$page.count");
+      assert.equal(view.get("$page.count"), undefined);
+      assert.ok(!store.get("pages")["~/ordering/new"].hasOwnProperty("count"));
+   });
+
+   it("deletes the entire exposed record (removes the keyed slot)", () => {
+      let { store, view } = getView();
+      view.delete("$page");
+      assert.equal(view.get("$page"), undefined);
+      assert.ok(
+         !store.get("pages").hasOwnProperty("~/ordering/new"),
+         "the keyed storage slot should be removed"
+      );
+   });
+});

package/src/data/ExposedValueView.ts

@@ -67,7 +67,7 @@ export class ExposedValueView extends View {
       if (path == this.recordName) {
          data = this.getData();
          container = this.containerBinding.value(data);
-         if (!container || !container.hasOwnProperty(path)) return false;
+         if (!container || !container.hasOwnProperty(this.key)) return false;
          newContainer = Object.assign({}, container);
          delete newContainer[this.key];
          this.store.set(this.containerBinding.path, newContainer);

package/src/data/comparer.ts

@@ -1,17 +1,16 @@
 import { getSelector } from "./getSelector";
 import { isDefined } from "../util/isDefined";
 import { defaultCompare } from "./defaultCompare";
+import type { CollatorOptions, Sorter } from "../ui/Prop";
 
-interface Sorter {
-   value?: any;
-   field?: string;
-   direction?: string;
+export interface ExtendedSorter extends Sorter {
    comparer?: (a: any, b: any) => number;
    compare?: (a: any, b: any) => number;
+   sortOptions?: CollatorOptions;
 }
 
 export function getComparer(
-   sorters: Sorter[],
+   sorters: ExtendedSorter[],
    dataAccessor?: (x: any) => any,
    comparer?: (a: any, b: any) => number,
 ): (a: any, b: any) => number {
@@ -51,7 +50,7 @@ export function getComparer(
 }
 
 export function indexSorter(
-   sorters: Sorter[],
+   sorters: ExtendedSorter[],
    dataAccessor?: (x: any) => any,
    compare?: (a: any, b: any) => number,
 ): (data: any[]) => number[] {
@@ -64,7 +63,7 @@ export function indexSorter(
 }
 
 export function sorter(
-   sorters: Sorter[],
+   sorters: ExtendedSorter[],
    dataAccessor?: (x: any) => any,
    compare?: (a: any, b: any) => number,
 ): (data: any[]) => any[] {

package/src/locale/de-de.ts

@@ -16,6 +16,7 @@ Localization.localize(c, "cx/widgets/LookupField", {
    queryErrorText: "Bei der Abfrage der gesuchten Daten ist ein Felhler aufgetreten.",
    noResultsText: "Keine Ergebnisse gefunden.",
    minQueryLengthMessageText: "Geben Sie mindestens {0} Zeichen ein.",
+   invalidOptionText: "Die ausgewählte Option ist nicht mehr verfügbar.",
 });
 
 // In common for Calendar and MonthPicker

package/src/locale/en-us.ts

@@ -15,6 +15,7 @@ Localization.localize(c, "cx/widgets/LookupField", {
    queryErrorText: "Error occurred while querying for lookup data.",
    noResultsText: "No results found.",
    minQueryLengthMessageText: "Type in at least {0} character(s).",
+   invalidOptionText: "The selected option is no longer available.",
 });
 
 // In common for Calendar and MonthPicker

package/src/locale/es-es.ts

@@ -16,6 +16,7 @@ Localization.localize(c, "cx/widgets/LookupField", {
    queryErrorText: "Se produjo un error al consultar los datos de búsqueda.",
    noResultsText: "No se han encontrado resultados.",
    minQueryLengthMessageText: "Escriba al menos {0} caracteres.",
+   invalidOptionText: "La opción seleccionada ya no está disponible.",
 });
 
 // In common for Calendar and MonthPicker

package/src/locale/fr-fr.ts

@@ -16,6 +16,7 @@ Localization.localize(c, "cx/widgets/LookupField", {
    queryErrorText: "Une erreur s'est produite lors de l'interrogation des données de recherche.",
    noResultsText: "Aucun résultat trouvé.",
    minQueryLengthMessageText: "Tapez au moins {0} caractère (s).",
+   invalidOptionText: "L'option sélectionnée n'est plus disponible.",
 });
 
 // In common for Calendar and MonthPicker

package/src/locale/nl-nl.ts

@@ -16,6 +16,7 @@ Localization.localize(c, "cx/widgets/LookupField", {
    queryErrorText: "Er is een fout opgetreden bij het weergeven van gegevens.",
    noResultsText: "Geen resultaten gevonden",
    minQueryLengthMessageText: "Voer minimaal {0} tekens in.",
+   invalidOptionText: "De geselecteerde optie is niet meer beschikbaar.",
 });
 
 // In common for Calendar and MonthPicker

package/src/locale/pt-pt.ts

@@ -16,6 +16,7 @@ Localization.localize(c, "cx/widgets/LookupField", {
    queryErrorText: "Ocorreu um erro ao consultar os dados de pesquisa.",
    noResultsText: "Nenhum resultado encontrado.",
    minQueryLengthMessageText: "Digite pelo menos {0} caractere(s).",
+   invalidOptionText: "A opção selecionada já não está disponível.",
 });
 
 // In common for Calendar and MonthPicker

package/src/locale/sr-latn-ba.ts

@@ -16,6 +16,7 @@ Localization.localize(c, "cx/widgets/LookupField", {
    queryErrorText: "Došlo je do greške kod pribavljanja podataka za prikaz.",
    noResultsText: "Rezultati nisu pronađeni.",
    minQueryLengthMessageText: "Unesite najmanje {0} karakter(a).",
+   invalidOptionText: "Izabrana opcija više nije dostupna.",
 });
 
 // In common for Calendar and MonthPicker

package/src/ui/Prop.ts

@@ -127,7 +127,7 @@ export type SortDirection = "ASC" | "DESC";
 
 export interface Sorter {
    field?: string;
-   value?: (record: DataRecord) => any;
+   value?: Prop<any>;
    direction: SortDirection;
 }
 

package/src/ui/adapter/ArrayAdapter.ts

@@ -1,6 +1,6 @@
 import { DataAdapter, DataAdapterRecord, DataAdapterConfig } from "./DataAdapter";
 import { ReadOnlyDataView } from "../../data/ReadOnlyDataView";
-import { sorter } from "../../data/comparer";
+import { sorter, type ExtendedSorter } from "../../data/comparer";
 import { isArray } from "../../util/isArray";
 import { ArrayElementView } from "../../data/ArrayElementView";
 import { Accessor, getAccessor } from "../../data/getAccessor";
@@ -9,7 +9,7 @@ import { isDefined, isObject } from "../../util";
 import { RenderingContext } from "../RenderingContext";
 import { Instance } from "../Instance";
 import { View } from "../../data/View";
-import { Prop, Sorter, CollatorOptions } from "../Prop";
+import { Prop, CollatorOptions } from "../Prop";
 
 export interface RecordStoreCache {
    recordStoreCache: WeakMap<any, View>;
@@ -26,10 +26,8 @@ export interface ArrayAdapterConfig extends DataAdapterConfig {
    preserveOrder?: boolean;
 }
 
-export interface ExtendedSorter extends Sorter {
-   comparer?: (a: any, b: any) => number;
-   sortOptions?: CollatorOptions;
-}
+// Re-exported for back-compat; the canonical definition lives in `data/comparer`.
+export type { ExtendedSorter } from "../../data/comparer";
 
 export interface ResolvedSorter {
    getter: (x: any) => any;
@@ -213,9 +211,9 @@ export class ArrayAdapter<T = any> extends DataAdapter<T> {
       }
    }
 
-   public sort(sorters?: Sorter[] | ExtendedSorter[]): void {
+   public sort(sorters?: ExtendedSorter[]): void {
       if (sorters) {
-         this.buildSorter(sorters as ExtendedSorter[]);
+         this.buildSorter(sorters);
       }
    }
 }

package/src/ui/adapter/GroupAdapter.spec.ts

@@ -39,4 +39,79 @@ describe("GroupAdapter", () => {
 
       assert.deepStrictEqual(newKeys, [], `Grouping config was mutated. New keys: ${newKeys.join(", ")}`);
    });
+
+   // Region totals after aggregation: A=10, B=30, C=20.
+   const records = [
+      { region: "A", sales: 10, product: "p3" },
+      { region: "B", sales: 30, product: "p1" },
+      { region: "C", sales: 20, product: "p2" },
+   ];
+
+   const baseGrouping: GroupingConfig = {
+      key: { region: { bind: "$record.region" } },
+      aggregates: { total: { type: "sum", value: { bind: "$record.sales" } } },
+   };
+
+   // Runs the full grouping pipeline and returns the resulting group order (region keys).
+   function groupOrder(grouping: GroupingConfig[], options?: { sortGroupsBySorters?: boolean }, sorters?: any[]) {
+      const adapter = new GroupAdapter({ groupings: grouping, ...options });
+      adapter.init();
+      if (sorters) adapter.sort(sorters);
+      const result = adapter.getRecords({} as any, {} as any, records, new Store({ data: {} }));
+      return result.filter((r) => r.type === "group-header").map((r: any) => r.group.region);
+   }
+
+   it("sorts groups by an aggregate via sortField/sortDirection", () => {
+      assert.deepStrictEqual(groupOrder([{ ...baseGrouping, sortField: "total", sortDirection: "DESC" }]), [
+         "B",
+         "C",
+         "A",
+      ]);
+   });
+
+   it("sorts groups by a key field via sortField", () => {
+      assert.deepStrictEqual(groupOrder([{ ...baseGrouping, sortField: "region", sortDirection: "DESC" }]), [
+         "C",
+         "B",
+         "A",
+      ]);
+   });
+
+   it("supports a multi-field sorters array", () => {
+      assert.deepStrictEqual(groupOrder([{ ...baseGrouping, sorters: [{ field: "total", direction: "ASC" }] }]), [
+         "A",
+         "C",
+         "B",
+      ]);
+   });
+
+   it("defaults to ascending sort by key", () => {
+      assert.deepStrictEqual(groupOrder([baseGrouping]), ["A", "B", "C"]);
+   });
+
+   it("lets an explicit comparer win over sortField", () => {
+      // Custom comparer sorts groups by total ascending, despite sortField asking for DESC.
+      const comparer = (a: any, b: any) => a.aggregates.total - b.aggregates.total;
+      assert.deepStrictEqual(groupOrder([{ ...baseGrouping, comparer, sortField: "total", sortDirection: "DESC" }]), [
+         "A",
+         "C",
+         "B",
+      ]);
+   });
+
+   it("reorders groups by the active column sort when sortGroupsBySorters is set", () => {
+      // The record-level value selector must be ignored; the column field drives group order.
+      const order = groupOrder([baseGrouping], { sortGroupsBySorters: true }, [
+         { field: "total", direction: "DESC", value: () => 999 },
+      ]);
+      assert.deepStrictEqual(order, ["B", "C", "A"]);
+   });
+
+   it("keeps configured group order when the sorted column is not a group field", () => {
+      // `product` is neither a key nor an aggregate, so groups keep their default (key ASC) order.
+      const order = groupOrder([baseGrouping], { sortGroupsBySorters: true }, [
+         { field: "product", direction: "DESC" },
+      ]);
+      assert.deepStrictEqual(order, ["A", "B", "C"]);
+   });
 });