cx 26.6.0 → 26.7.0

package/src/ui/adapter/GroupAdapter.ts

@@ -4,11 +4,13 @@ import { ReadOnlyDataView } from "../../data/ReadOnlyDataView";
 import { View } from "../../data/View";
 import { isDataRecord } from "../../util";
 import { isArray } from "../../util/isArray";
+import { isDefined } from "../../util/isDefined";
+import { isNonEmptyArray } from "../../util/isNonEmptyArray";
 import { Culture } from "../Culture";
 import { Instance } from "../Instance";
 import { Prop, SortDirection, Sorter, StructuredProp } from "../Prop";
 import { RenderingContext } from "../RenderingContext";
-import { ArrayAdapter, ArrayAdapterConfig, RecordStoreCache } from "./ArrayAdapter";
+import { ArrayAdapter, ArrayAdapterConfig, ExtendedSorter, RecordStoreCache } from "./ArrayAdapter";
 import { DataAdapterRecord } from "./DataAdapter";
 
 export interface GroupKey {
@@ -21,7 +23,17 @@ export interface GroupingConfig {
    text?: Prop<string>;
    includeHeader?: boolean;
    includeFooter?: boolean;
+   /** Custom group comparer. Takes precedence over `sortField`/`sortDirection`/`sorters`. */
    comparer?: ((a: any, b: any) => number) | null;
+   /**
+    * Sort groups by a single field resolved against the group's `key`, `aggregates` and `name`.
+    * Use an aggregate alias (e.g. `"total"`) to sort by an aggregate, or a key field to sort by key.
+    */
+   sortField?: string;
+   /** Sort direction used together with `sortField`. Defaults to `"ASC"`. */
+   sortDirection?: SortDirection;
+   /** Multi-field group sorting. Each sorter's `field` is resolved against the group's `key`, `aggregates` and `name`. */
+   sorters?: Sorter[];
    header?: any;
    footer?: any;
 }
@@ -50,6 +62,8 @@ export interface GroupAdapterConfig extends ArrayAdapterConfig {
    groupRecordsName?: string;
    groupings?: GroupingConfig[] | null;
    groupName?: string;
+   /** When enabled, the active record sorters also reorder groups (resolved against each group's key/aggregates/name). */
+   sortGroupsBySorters?: boolean;
 }
 
 export class GroupAdapter<T = any> extends ArrayAdapter<T> {
@@ -58,11 +72,41 @@ export class GroupAdapter<T = any> extends ArrayAdapter<T> {
    declare public groupRecordsName?: string;
    declare public groupings?: ResolvedGrouping[] | null;
    declare public groupName: string;
+   declare public sortGroupsBySorters?: boolean;
+
+   /**
+    * 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.
+    */
+   protected groupSortComparers?: (((a: any, b: any) => number) | null)[];
 
    constructor(config?: GroupAdapterConfig) {
       super(config);
    }
 
+   public sort(sorters?: ExtendedSorter[]): void {
+      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: ExtendedSorter[] = 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;
+         });
+      }
+   }
+
    public init(): void {
       super.init();
 
@@ -116,8 +160,13 @@ export class GroupAdapter<T = any> extends ArrayAdapter<T> {
       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) => {
@@ -208,15 +257,22 @@ export class GroupAdapter<T = any> extends ArrayAdapter<T> {
                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: Sorter[] | null = 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: any) => x.key,
-                       this.sortOptions ? Culture.getComparer(this.sortOptions) : undefined,
-                    )
-                  : null);
+               (sortSorters
+                  ? buildGroupComparer(sortSorters, cultureComparer)
+                  : groupSorters.length > 0
+                    ? getComparer(groupSorters, (x: any) => x.key, cultureComparer)
+                    : null);
 
             return {
                ...g,
@@ -233,6 +289,43 @@ export class GroupAdapter<T = any> extends ArrayAdapter<T> {
 
 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: ResolvedGrouping, adapterAggregates?: StructuredProp): Set<string> {
+   const names = new Set<string>();
+   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: string): (gr: any) => any {
+   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: ExtendedSorter[],
+   cultureComparer?: (a: any, b: any) => number,
+): (a: any, b: any) => number {
+   return getComparer(
+      sorters.map((s) => (isDefined(s.value) || !s.field ? s : { ...s, value: groupFieldSelector(s.field) })),
+      undefined,
+      cultureComparer,
+   );
+}
 
 function serializeKey(data: any): string {
    if (isDataRecord(data)) {

package/src/widgets/drag-drop/DragSource.tsx

@@ -2,7 +2,7 @@
 
 import { Widget, VDOM } from "../../ui/Widget";
 import { ContainerBase, ContainerConfig, StyledContainerBase, StyledContainerConfig } from "../../ui/Container";
-import { ddMouseDown, ddDetect, ddMouseUp, initiateDragDrop, isDragHandleEvent } from "./ops";
+import { ddMouseDown, ddDetect, ddMouseUp, initiateDragDrop, isDragHandleEvent, DragEndEvent } from "./ops";
 import { preventFocus } from "../../ui/FocusManager";
 import { parseStyle } from "../../util/parseStyle";
 import { Instance } from "../../ui/Instance";
@@ -30,7 +30,7 @@ export interface DragSourceConfig extends StyledContainerConfig {
 
    onDragStart?: (e: React.MouseEvent | React.TouchEvent, instance: Instance) => any;
 
-   onDragEnd?: (e: React.MouseEvent | React.TouchEvent, instance: Instance) => void;
+   onDragEnd?: (e: DragEndEvent, instance: Instance) => void;
 
    id?: StringProp;
 
@@ -64,7 +64,7 @@ export class DragSource extends StyledContainerBase<DragSourceConfig, DragSource
    declare cloneStyle: any;
    declare draggedStyle: any;
    declare onDragStart?: (e: React.MouseEvent | React.TouchEvent, instance: DragSourceInstance) => any;
-   declare onDragEnd?: (e: React.MouseEvent | React.TouchEvent, instance: DragSourceInstance) => void;
+   declare onDragEnd?: (e: DragEndEvent, instance: DragSourceInstance) => void;
 
    constructor(config?: DragSourceConfig) {
       super(config);

package/src/widgets/drag-drop/DropZone.tsx

@@ -3,7 +3,7 @@
 import { Widget, VDOM } from "../../ui/Widget";
 import { ContainerBase, ContainerConfig, StyledContainerBase, StyledContainerConfig } from "../../ui/Container";
 import { parseStyle } from "../../util/parseStyle";
-import { registerDropZone, DragDropContext, DragEvent } from "./ops";
+import { registerDropZone, DragDropContext, DragEvent, DragEndEvent } from "./ops";
 import { findScrollableParent } from "../../util/findScrollableParent";
 import { isNumber } from "../../util/isNumber";
 import { getTopLevelBoundingClientRect } from "../../util/getTopLevelBoundingClientRect";
@@ -90,8 +90,8 @@ export interface DropZoneConfig extends StyledContainerConfig {
    /** A callback method invoked when at the beginning of the drag & drop operation. */
    onDragStart?: string | ((event: DragEvent, instance: Instance) => void);
 
-   /** A callback method invoked when at the end of the drag & drop operation. */
-   onDragEnd?: string | ((event: DragEvent, instance: Instance) => void);
+   /** A callback method invoked when at the end of the drag & drop operation. `event.cancelled` is `true` when the operation was cancelled (e.g. via Esc) instead of dropped. */
+   onDragEnd?: string | ((event: DragEndEvent, instance: Instance) => void);
 
    /** Match height of the item being dragged */
    matchHeight?: boolean;
@@ -126,7 +126,7 @@ export class DropZone extends StyledContainerBase<DropZoneConfig, DropZoneInstan
    declare onDragEnter?: string | ((event?: DragEvent, instance?: Instance) => void);
    declare onDragLeave?: string | ((event?: DragEvent, instance?: Instance) => void);
    declare onDragStart?: string | ((event?: DragEvent, instance?: Instance) => void);
-   declare onDragEnd?: string | ((event?: DragEvent, instance?: Instance) => void);
+   declare onDragEnd?: string | ((event?: DragEndEvent, instance?: Instance) => void);
 
    constructor(config?: DropZoneConfig) {
       super(config);
@@ -342,7 +342,7 @@ class DropZoneComponent extends VDOM.Component<DropZoneComponentProps, DropZoneC
       if (this.state.state == "over" && widget.onDrop) instance.invoke("onDrop", e, instance);
    }
 
-   onDragEnd(e: DragEvent) {
+   onDragEnd(e: DragEndEvent) {
       this.setState({
          state: false,
          style: null,

package/src/widgets/drag-drop/ops.tsx

@@ -21,6 +21,18 @@ export interface DragEvent {
    result?: any;
 }
 
+export interface DragEndEvent {
+   type: "dragend";
+   /** The triggering pointer event, or `null` when the operation was cancelled via the keyboard. */
+   event: DragEvent["event"] | null;
+   /** Cursor position, or `null` when the operation was cancelled via the keyboard. */
+   cursor: CursorPosition | null;
+   source: DragEvent["source"];
+   /** `true` when the operation was cancelled (e.g. by pressing Esc) instead of dropped. */
+   cancelled: boolean;
+   result?: any;
+}
+
 export interface DragDropOptions {
    sourceEl?: Element | null;
    clone?: any;
@@ -38,7 +50,7 @@ export interface IDropZone {
    onDragStart?: DragEventHandler;
    onDragAway?: DragEventHandler;
    onDragNear?: DragEventHandler;
-   onDragEnd?: DragEventHandler;
+   onDragEnd?: (e: DragEndEvent) => void;
    onDragMeasure?: (
       e: DragEvent,
       operation: DragDropOperationContext,
@@ -62,7 +74,6 @@ import { getTopLevelBoundingClientRect } from "../../util/getTopLevelBoundingCli
 import { VDOM } from "../../ui/VDOM";
 import { Container } from "../../ui/Container";
 import { Console } from "../../util";
-import { WidgetConfig } from "../../ui";
 
 interface Puppet {
    deltaX: number;
@@ -70,7 +81,7 @@ interface Puppet {
    el: HTMLDivElement;
    clone: any;
    source: any;
-   onDragEnd?: (e?: DragEvent) => void;
+   onDragEnd?: (e?: DragEndEvent) => void;
    stop?: () => void;
 }
 
@@ -82,6 +93,7 @@ let puppet: Puppet | null = null;
 let scrollTimer: number | null = null;
 let vscrollParent: Element | null = null;
 let hscrollParent: Element | null = null;
+let releaseCapture: (() => void) | null = null;
 
 export function registerDropZone(dropZone: IDropZone): UnregisterFunction {
    dropZones.push(dropZone);
@@ -94,7 +106,7 @@ export function registerDropZone(dropZone: IDropZone): UnregisterFunction {
 export function initiateDragDrop(
    e: MouseEvent | TouchEvent | React.MouseEvent | React.TouchEvent,
    options: DragDropOptions = {},
-   onDragEnd?: (e?: DragEvent) => void,
+   onDragEnd?: (e?: DragEndEvent) => void,
 ): void {
    if (puppet) {
       //last operation didn't finish properly
@@ -187,7 +199,16 @@ export function initiateDragDrop(
 
    notifyDragMove(e, null);
 
-   captureMouseOrTouch(e, notifyDragMove, notifyDragDrop);
+   releaseCapture = captureMouseOrTouch(e, notifyDragMove, notifyDragDrop);
+   document.addEventListener("keydown", onDragKeyDown, true);
+}
+
+function onDragKeyDown(e: KeyboardEvent): void {
+   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: React.MouseEvent | React.TouchEvent | MouseEvent | TouchEvent, _captureData: any): void {
@@ -321,29 +342,50 @@ function clearScrollTimer() {
    }
 }
 
-function notifyDragDrop(e: MouseEvent | TouchEvent | React.MouseEvent | React.TouchEvent): void {
+function notifyDragDrop(
+   e: MouseEvent | TouchEvent | React.MouseEvent | React.TouchEvent | null,
+   cancelled: boolean = false,
+): void {
+   if (!puppet) return;
+
    clearScrollTimer();
+   document.removeEventListener("keydown", onDragKeyDown, true);
 
-   let event = getDragEvent(e, "dragdrop");
+   if (puppet.stop) puppet.stop();
 
-   if (puppet!.stop) puppet!.stop();
+   //a keyboard cancellation has no pointer event, so the drop and away notifications are skipped
+   let dropEvent = !cancelled && e ? getDragEvent(e, "dragdrop") : null;
 
-   if (activeZone && activeZone.onDrop) event.result = activeZone.onDrop(event);
+   let result: any;
+   if (dropEvent && activeZone && activeZone.onDrop) result = activeZone.onDrop(dropEvent);
+
+   let endEvent: DragEndEvent = {
+      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(

package/src/widgets/form/NumberField.scss

@@ -42,6 +42,10 @@
       .#{$state}icon > & {
          padding-left: cx-calc(cx-top($padding), $cx-default-input-left-tool-size, $cx-default-input-left-tool-spacing);
       }
+
+      .#{$state}clear > & {
+         padding-right: cx-calc(cx-top($padding), $cx-default-clear-size, $cx-default-clear-spacing);
+      }
    }
 
    .#{$element}#{$name}-tool {

package/src/widgets/form/NumberField.tsx

@@ -312,6 +312,7 @@ class Input extends VDOM.Component<InputProps, InputState> {
             visited: state.visited,
             focus: this.state.focus,
             icon: !!icon,
+            clear: insideButton != null,
             empty: empty && !data.placeholder,
             error:
               data.error &&

package/src/widgets/grid/Grid.tsx

@@ -23,6 +23,7 @@ import {
    NumberProp,
    Prop,
    RecordAlias,
+   Sorter,
    SortDirection,
    SortersProp,
    StringProp,
@@ -62,6 +63,7 @@ import {
    ddMouseDown,
    DragDropOperationContext,
    DragEvent,
+   DragEndEvent,
    initiateDragDrop,
    registerDropZone,
 } from "../drag-drop/ops";
@@ -165,6 +167,15 @@ export interface GridGroupingConfig<T> {
    name?: StringProp;
    text?: StringProp;
    comparer?: (a: GroupingResult<T>, b: GroupingResult<T>) => number;
+   /**
+    * Sort groups by a single field resolved against the group's key, aggregates and name.
+    * Use an aggregate alias to sort by an aggregate, or a key field to sort by key.
+    */
+   sortField?: string;
+   /** Sort direction used together with `sortField`. Defaults to `"ASC"`. */
+   sortDirection?: SortDirection;
+   /** Multi-field group sorting. Each sorter's `field` is resolved against the group's key, aggregates and name. */
+   sorters?: Sorter[];
 }
 
 export interface GridColumnHeaderConfig {
@@ -390,7 +401,7 @@ export interface GridConfig<T = any> extends StyledContainerConfig {
    onDrop?: string | ((e: GridDragEvent<T>, instance: Instance) => void);
    onDropTest?: string | ((e: DragEvent, instance: Instance) => boolean);
    onDragStart?: string | ((e: DragEvent, instance: Instance) => void);
-   onDragEnd?: string | ((e: DragEvent, instance: Instance) => void);
+   onDragEnd?: string | ((e: DragEndEvent, instance: Instance) => void);
    onDragOver?: string | ((e: GridDragEvent<T>, instance: Instance) => void | boolean);
 
    onRowDropTest?: string | ((e: DragEvent, instance: Instance) => boolean);
@@ -502,6 +513,13 @@ export interface GridConfig<T = any> extends StyledContainerConfig {
 
    /** When enabled, groups are shown in the same order as the source records. */
    preserveGroupOrder?: boolean;
+
+   /**
+    * When enabled, sorting by a column header also reorders groups. The active sort field is resolved
+    * against each group's key fields, aggregates and name, so it works for both grouping columns and
+    * aggregate columns. Ignored when `preserveGroupOrder` is set.
+    */
+   sortGroups?: boolean;
 }
 
 export interface GridCellInfo {
@@ -635,6 +653,7 @@ export class Grid<T = unknown> extends ContainerBase<GridConfig<T>, GridInstance
    declare onCreateIsRecordDraggable?: any;
    declare onRef?: any;
    declare preserveGroupOrder: boolean;
+   declare sortGroups: boolean;
    declare styled: boolean;
    declare selectable?: boolean;
    declare recordsAccessor: any;
@@ -844,6 +863,7 @@ export class Grid<T = unknown> extends ContainerBase<GridConfig<T>, GridInstance
                     sortOptions: this.sortOptions,
                     groupings: grouping,
                     preserveOrder: this.preserveGroupOrder,
+                    sortGroupsBySorters: this.sortGroups,
                  },
                  this.dataAdapter,
               );
@@ -1903,6 +1923,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);
@@ -2851,7 +2872,7 @@ class GridComponent extends VDOM.Component<GridComponentProps, GridComponentStat
       return (grid || row || column) && { grid, row, column };
    }
 
-   onDragEnd(e: DragEvent) {
+   onDragEnd(e: DragEndEvent) {
       this.setState({
          dropTarget: null,
          dropInsertionIndex: null,

package/src/widgets/overlay/captureMouse.ts

@@ -31,7 +31,7 @@ interface CaptureMouseOptions {
 export function captureMouse2(
    e: React.MouseEvent | React.TouchEvent | MouseEvent | TouchEvent,
    options: CaptureMouseOptions,
-): void {
+): () => void {
    let surface = document.createElement("div");
    surface.className = "cxb-mousecapture";
    surface.style.cursor = options.cursor || getComputedStyle(e.currentTarget as Element).cursor;
@@ -67,6 +67,8 @@ export function captureMouse2(
 
    e.stopPropagation();
 
+   return tear;
+
    function move(e: Event) {
       if (!active) {
          tear();
@@ -110,7 +112,7 @@ export function captureMouse2(
 export function captureMouseOrTouch2(
    e: React.MouseEvent | React.TouchEvent | MouseEvent | TouchEvent,
    options: CaptureMouseOptions,
-): void {
+): () => void {
    if (e.type.indexOf("touch") == 0) {
       let el = e.currentTarget as HTMLElement;
 
@@ -136,7 +138,12 @@ export function captureMouseOrTouch2(
       el.addEventListener("touchend", end);
 
       e.stopPropagation();
-   } else captureMouse2(e, options);
+
+      return () => {
+         el.removeEventListener("touchmove", move);
+         el.removeEventListener("touchend", end);
+      };
+   } else return captureMouse2(e, options);
 }
 
 /**
@@ -153,8 +160,8 @@ export function captureMouse(
    onMouseUp?: (e: MouseEvent | TouchEvent, captureData?: any) => void,
    captureData?: any,
    cursor?: string,
-): void {
-   captureMouse2(e, {
+): () => void {
+   return captureMouse2(e, {
       onMouseMove,
       onMouseUp,
       captureData,
@@ -176,8 +183,8 @@ export function captureMouseOrTouch(
    onMouseUp?: (e: MouseEvent, captureData?: any) => void,
    captureData?: any,
    cursor?: string,
-): void {
-   captureMouseOrTouch2(e, { onMouseMove, onMouseUp, captureData, cursor });
+): () => void {
+   return captureMouseOrTouch2(e, { onMouseMove, onMouseUp, captureData, cursor });
 }
 
 /**