wunderbaum 0.10.1 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wunderbaum",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "title": "A treegrid control.",
   "description": "JavaScript tree/grid/treegrid control.",
   "homepage": "https://github.com/mar10/wunderbaum",
@@ -54,7 +54,6 @@
     "@typescript-eslint/eslint-plugin": "^6.7.5",
     "@typescript-eslint/parser": "^6.7.5",
     "concurrently": "^8.1.0",
-    "docsify-cli": "^4.4.4",
     "eslint": "^8.51.0",
     "eslint-config-jquery": "^3.0.0",
     "eslint-config-prettier": "^8.8.0",
@@ -101,7 +100,7 @@
   },
   "scripts": {
     "test": "npm run lint && npm run build:js && grunt ci --verbose",
-    "docs": "typedoc && touch docs/api/.nojekyll && rm docs/unittest/*.*; cp test/unit/*.* docs/unittest",
+    "api_docs": "typedoc && touch docs/api/.nojekyll && rm docs/unittest/*.*; cp test/unit/*.* docs/unittest",
     "format": "eslint src --fix && prettier src docs/demo -w && npm run lint",
     "lint": "prettier src docs/demo --check && eslint src docs/demo && tsc -t esnext --moduleResolution node --noEmit src/wunderbaum.ts",
     "build:minjs:umd": "terser build/wunderbaum.umd.js --compress --mangle --source-map \"base='build',url='wunderbaum.umd.min.js.map',filename='wunderbaum.umd.js'\" --output build/wunderbaum.umd.min.js",
@@ -110,13 +109,13 @@
     "build:scss": "sass src/wunderbaum.scss build/wunderbaum.css",
     "build:js": "rollup -c rollup.config.mjs && npm run build:minjs",
     "build:types": "tsc -t esnext --moduleResolution node -d --emitDeclarationOnly --outFile build/wunderbaum.d.ts src/wunderbaum.ts",
-    "build": "npm run format && mkdir build; rm build/*.*; ls build && npm run build:js -s  && npm run build:scss && npm run build:types -s && npm run docs",
+    "build": "npm run format && mkdir build; rm build/*.*; ls build && npm run build:js -s  && npm run build:scss && npm run build:types -s && npm run api_docs",
     "make_dist": "npm run build && rm dist/*.* ; cp build/*.* dist",
     "watch:umd": "nodemon --watch src --ext 'ts' -x \"npm run build:minjs\"",
     "watch": "nodemon",
     "serve": "http-server test -p 8080 -o /",
-    "docsify": "docsify serve docs -o",
-    "dev": "concurrently \"http-server . -p 8080 -o /docs/demo \" \"nodemon\""
+    "dev": "concurrently \"http-server . -p 8080 -o /docs/demo \" \"nodemon\"",
+    "dev_mkdocs": "pipenv run mkdocs serve"
   },
   "npmName": "wunderbaum",
   "npmFileMap": [

package/src/common.ts

@@ -64,6 +64,15 @@ export const iconMaps: { [key: string]: { [key: string]: string } } = {
     folderOpen: "bi bi-folder2-open",
     folderLazy: "bi bi-folder-symlink",
     doc: "bi bi-file-earmark",
+    colSortable: "bi bi-chevron-expand",
+    // colSortable: "bi bi-arrow-down-up",
+    // colSortAsc: "bi bi-chevron-down",
+    // colSortDesc: "bi bi-chevron-up",
+    colSortAsc: "bi bi-arrow-down",
+    colSortDesc: "bi bi-arrow-up",
+    colFilter: "bi bi-filter-circle",
+    colFilterActive: "bi bi-filter-circle-fill wb-helper-invalid",
+    colMenu: "bi bi-three-dots-vertical",
   },
   fontawesome6: {
     error: "fa-solid fa-triangle-exclamation",
@@ -82,6 +91,12 @@ export const iconMaps: { [key: string]: { [key: string]: string } } = {
     folderOpen: "fa-regular fa-folder-open",
     folderLazy: "fa-solid fa-folder-plus",
     doc: "fa-regular fa-file",
+    colSortable: "fa-solid fa-fw fa-sort",
+    colSortAsc: "fa-solid fa-fw fa-sort-up",
+    colSortDesc: "fa-solid fa-fw fa-sort-down",
+    colFilter: "fa-solid fa-fw fa-filter",
+    colFilterActive: "fa-solid fa-fw fa-filter wb-helper-invalid",
+    colMenu: "fa-solid fa-fw fa-ellipsis-v",
   },
 };
 
@@ -149,7 +164,7 @@ export const KEY_TO_ACTION_DICT: { [key: string]: string } = {
 
 /** Return a callback that returns true if the node title matches the string
  * or regular expression.
- * @see {@link WunderbaumNode.findAll()}
+ * @see {@link WunderbaumNode.findAll}
  */
 export function makeNodeTitleMatcher(match: string | RegExp): MatcherCallback {
   if (match instanceof RegExp) {

package/src/types.ts

@@ -72,11 +72,23 @@ export type BoolOrStringOptionResolver = (
 export type NodeAnyCallback = (node: WunderbaumNode) => any;
 /** A callback that receives a node instance and returns a string value. */
 export type NodeStringCallback = (node: WunderbaumNode) => string;
+/** A callback that receives a node instance and property name returns a value. */
+export type NodePropertyGetterCallback = (
+  node: WunderbaumNode,
+  propName: string
+) => any;
 /** A callback that receives a node instance and returns an iteration modifier. */
 export type NodeVisitCallback = (node: WunderbaumNode) => NodeVisitResponse;
-/** A callback that receives a node instance and returns a string value. */
+/**
+ * Returned by `NodeVisitCallback` to control iteration.
+ * `false` stops iteration, `skip` skips descendants but continues.
+ * All other values continue iteration.
+ */
 export type NodeVisitResponse = "skip" | boolean | void;
-/** A callback that receives a node-data dictionary and a node instance and returns an iteration modifier. */
+/**
+ * A callback that receives a node-data dictionary and a node instance and
+ * returns an iteration modifier.
+ */
 export type NodeToDictCallback = (
   dict: WbNodeData,
   node: WunderbaumNode
@@ -264,6 +276,12 @@ export interface WbSelectEventType extends WbNodeEventType {
   flag: boolean;
 }
 
+export interface WbButtonClickEventType extends WbTreeEventType {
+  info: WbEventInfo;
+  /** The associated command, e.g. 'menu', 'sort', 'filter', ... */
+  command: string;
+}
+
 export interface WbRenderEventType extends WbNodeEventType {
   /**
    * True if the node's markup was not yet created. In this case the render
@@ -351,30 +369,58 @@ export interface ColumnDefinition {
    */
   minWidth?: string | number;
   /** Allow user to resize the column.
-   * Default: false.
+   * @default false (or global tree option `columnsSortable`)
+   * @see {@link WunderbaumOptions.columnsResizable}.
+   * @since 0.10.0
    */
   resizable?: boolean;
   /** Optional custom column width when user resized by mouse drag.
    * Default: unset.
    */
   customWidthPx?: number;
-  /** Allow user to sort the column. Default: false. <br>
-   * **Note:** Sorting is not implemented yet.
+  /** Display a 'filter' button in the column header. Default: false. <br>
+   * Note: The actual filtering must be implemented in the `buttonClick()` event.
+   * @default false (or global tree option `columnsFilterable`)
+   * @since 0.11.0
+   */
+  filterable?: boolean;
+  /** .
+   * Default: inactive. <br>
+   * Note: The actual filtering must be implemented in the `buttonClick()` event.
+   */
+  filterActive?: boolean;
+  /** Display a 'sort' button in the column header. Default: false. <br>
+   * Note: The actual sorting must be implemented in the `buttonClick()` event.
+   * @default false (or global tree option `columnsSortable`)
+   * @see {@link WunderbaumOptions.columnsSortable}.
+   * @since 0.11.0
    */
   sortable?: boolean;
   /** Optional custom column sort orde when user clicked the sort icon.
-   * Default: unset. <br>
-   * **Note:** Sorting is not implemented yet.
+   * Default: unset, e.g. not sorted. <br>
+   * Note: The actual sorting must be implemented in the `buttonClick()` event.
+   * @since 0.11.0
    */
   sortOrder?: SortOrderType;
+  /** Display a menu icon that may open a context menu for this column.
+   * Note: The actual functionality must be implemented in the `buttonClick()` event.
+   * @default false (or global tree option `columnsMenu`)
+   * @see {@link WunderbaumOptions.columnsMenu}.
+   * @since 0.11.0
+   */
+  menu?: boolean;
   /** Optional class names that are added to all `span.wb-col` header AND data
-   * elements of that column.
+   * elements of that column. Separate multiple classes with space.
    */
   classes?: string;
   /** If `headerClasses` is a set, it will be used for the header element only
    * (unlike `classes`, which is used for body and header cells).
+   * Separate multiple classes with space.
    */
   headerClasses?: string;
+  // /** A list of icon definitions added to the column header.
+  //  */
+  // headerIcons?: string;
   /** Optional HTML content that is rendered into all `span.wb-col` elements of that column.*/
   html?: string;
   /** @internal */
@@ -464,7 +510,7 @@ export type NodeFilterResponse = "skip" | "branch" | boolean | void;
 export type NodeFilterCallback = (node: WunderbaumNode) => NodeFilterResponse;
 
 /**
- * Possible values for {@link WunderbaumNode.update()} and {@link Wunderbaum.update()}.
+ * Possible values for {@link WunderbaumNode.update} and {@link Wunderbaum.update}.
  */
 export enum ChangeType {
   /** Re-render the whole viewport, headers, and all rows. */
@@ -493,7 +539,7 @@ export enum RenderFlag {
   scroll = "scroll",
 }
 
-/** Possible values for {@link WunderbaumNode.setStatus()}. */
+/** Possible values for {@link WunderbaumNode.setStatus}. */
 export enum NodeStatusType {
   ok = "ok",
   loading = "loading",
@@ -525,7 +571,7 @@ export enum NavModeEnum {
  * METHOD OPTIONS TYPES
  * ---------------------------------------------------------------------------*/
 
-/** Possible values for {@link WunderbaumNode.addChildren()}. */
+/** Possible values for {@link WunderbaumNode.addChildren}. */
 export interface AddChildrenOptions {
   /** Insert children before this node (or index)
    * @default undefined or null:  append as last child
@@ -541,12 +587,12 @@ export interface AddChildrenOptions {
   _level?: number;
 }
 
-/** Possible values for {@link Wunderbaum.applyCommand()} and {@link WunderbaumNode.applyCommand()}. */
+/** Possible values for {@link Wunderbaum.applyCommand} and {@link WunderbaumNode.applyCommand}. */
 export interface ApplyCommandOptions {
   [key: string]: unknown;
 }
 
-/** Possible values for {@link Wunderbaum.expandAll()} and {@link WunderbaumNode.expandAll()}. */
+/** Possible values for {@link Wunderbaum.expandAll} and {@link WunderbaumNode.expandAll}. */
 export interface ExpandAllOptions {
   /** Restrict expand level @default 99 */
   depth?: number;
@@ -559,7 +605,7 @@ export interface ExpandAllOptions {
 }
 
 /**
- * Possible option values for {@link Wunderbaum.filterNodes()}.
+ * Possible option values for {@link Wunderbaum.filterNodes}.
  * The defaults are inherited from the tree instances ´tree.options.filter`
  * settings (see also {@link FilterOptionsType}).
  */
@@ -585,7 +631,7 @@ export interface FilterNodesOptions {
   noData?: boolean | string;
 }
 
-/** Possible values for {@link WunderbaumNode.makeVisible()}. */
+/** Possible values for {@link WunderbaumNode.makeVisible}. */
 export interface MakeVisibleOptions {
   /** Do not animate expand (currently not implemented). @default false */
   noAnimation?: boolean;
@@ -595,7 +641,7 @@ export interface MakeVisibleOptions {
   noEvents?: boolean;
 }
 
-/** Possible values for {@link WunderbaumNode.navigate()}. */
+/** Possible values for {@link WunderbaumNode.navigate}. */
 export interface NavigateOptions {
   /** Activate the new node (otherwise focus only). @default true */
   activate?: boolean;
@@ -603,7 +649,7 @@ export interface NavigateOptions {
   event?: Event;
 }
 
-/** Possible values for {@link WunderbaumNode._render()}. */
+/** Possible values for {@link WunderbaumNode._render}. */
 export interface RenderOptions {
   /** Which parts need update? @default ChangeType.data */
   change?: ChangeType;
@@ -621,7 +667,7 @@ export interface RenderOptions {
   resizeCols?: boolean;
 }
 
-/** Possible values for {@link WunderbaumNode.scrollIntoView()} `options` argument. */
+/** Possible values for {@link WunderbaumNode.scrollIntoView} `options` argument. */
 export interface ScrollIntoViewOptions {
   /** Do not animate (currently not implemented). @default false */
   noAnimation?: boolean;
@@ -633,7 +679,7 @@ export interface ScrollIntoViewOptions {
   ofsY?: number;
 }
 
-/** Possible values for {@link Wunderbaum.scrollTo()} `options` argument. */
+/** Possible values for {@link Wunderbaum.scrollTo} `options` argument. */
 export interface ScrollToOptions extends ScrollIntoViewOptions {
   /** Which node to scroll into the viewport.*/
   node: WunderbaumNode;
@@ -653,7 +699,7 @@ export interface SetActiveOptions {
   focusTree?: boolean;
   /** Optional original event that will be passed to the (de)activate handler. */
   event?: Event;
-  /** Also call {@link Wunderbaum.setColumn()}. */
+  /** Also call {@link Wunderbaum.setColumn}. */
   colIdx?: number | string;
   /**
    * Focus embedded input control of the grid cell if any (requires colIdx >= 0).
@@ -663,7 +709,7 @@ export interface SetActiveOptions {
   edit?: boolean;
 }
 
-/** Possible values for {@link Wunderbaum.setColumn()} `options` argument. */
+/** Possible values for {@link Wunderbaum.setColumn} `options` argument. */
 export interface SetColumnOptions {
   /**
    * Focus embedded input control of the grid cell if any .
@@ -689,7 +735,7 @@ export interface SetExpandedOptions {
   scrollIntoView?: boolean;
 }
 
-/** Possible values for {@link WunderbaumNode.update()} `options` argument. */
+/** Possible values for {@link WunderbaumNode.update} `options` argument. */
 export interface UpdateOptions {
   /** Force immediate redraw instead of throttled/async mode. @default false */
   immediate?: boolean;
@@ -697,7 +743,7 @@ export interface UpdateOptions {
   // removeMarkup?: boolean;
 }
 
-/** Possible values for {@link WunderbaumNode.setSelected()} `options` argument. */
+/** Possible values for {@link WunderbaumNode.setSelected} `options` argument. */
 export interface SetSelectedOptions {
   /** Ignore restrictions, e.g. (`unselectable`). @default false */
   force?: boolean;
@@ -711,7 +757,7 @@ export interface SetSelectedOptions {
   callback?: NodeSelectCallback;
 }
 
-/** Possible values for {@link WunderbaumNode.setStatus()} `options` argument. */
+/** Possible values for {@link WunderbaumNode.setStatus} `options` argument. */
 export interface SetStatusOptions {
   /** Displayed as status node title. */
   message?: string;
@@ -719,7 +765,57 @@ export interface SetStatusOptions {
   details?: string;
 }
 
-/** Options passed to {@link Wunderbaum.visitRows()}. */
+/**
+ * Possible values for {@link WunderbaumNode.sortByProperty} `options` argument.
+ */
+export interface ResetOrderOptions {
+  /** Sort descendants recursively. @default true */
+  recursive?: boolean;
+  /** The name of the node property that will be renumbered.
+   * @default `_nativeIndex`.
+   */
+  propName?: string;
+}
+
+/**
+ * Possible values for {@link WunderbaumNode.sortByProperty} `options` argument.
+ */
+export interface SortByPropertyOptions {
+  /** Column ID as defined in `tree.columns` definition. Required if updateColInfo is true.*/
+  colId?: string;
+  /** The name of the node property that will be used for sorting.
+   * @default use the `colId` as property name.
+   */
+  propName?: string;
+  // /** If defined, this callback is used to extract the value to be sorted. */
+  // vallueGetter?: NodePropertyGetterCallback;
+  /** Sort order. @default Use value from column definition (rotated).*/
+  order?: SortOrderType;
+  /**
+   * Sort by this property if order is `undefined`.
+   * See also {@link WunderbaumNode.resetNativeChildOrder}.
+   * @default `_nativeIndex`.
+   */
+  nativeOrderPropName?: string;
+  /** Sort string values case insensitive. @default false */
+  caseInsensitive?: boolean;
+  /** Sort descendants recursively. @default true */
+  deep?: boolean;
+  // /** Rotate sort order (asc -> desc -> none) before sorting. @default false */
+  // rotateOrder?: boolean;
+  /**
+   * Rotate sort order (asc -> desc -> none) before sorting.
+   * Update the sort icons in the column header
+   * Note:
+   * Sorting is done in-place. There is no 'unsorted' state, but we can
+   * call `setCurrentSortOrder()` to renumber the `node._sortIdx` property,
+   * which will be used as sort key, when `order` is `undefined`.
+   * @default false
+   */
+  updateColInfo?: boolean;
+}
+
+/** Options passed to {@link Wunderbaum.visitRows}. */
 export interface VisitRowsOptions {
   /** Skip filtered nodes and children of collapsed nodes. @default false */
   includeHidden?: boolean;
@@ -998,7 +1094,7 @@ export type DndOptionsType = {
   //  */
   // setTextTypeJson: boolean;
   /**
-   * Optional callback passed to `toDict` on dragStart @since 2.38
+   * Optional callback passed to `toDict` on dragStart
    * @default null
    * @category Callback
    */

package/src/util.ts

@@ -746,6 +746,12 @@ export function getOption(
   return value ?? defaultValue;
 }
 
+/** Return the next value from a list of values (rotating). @since 0.11 */
+export function rotate(value: any, values: any[]): any {
+  const idx = values.indexOf(value);
+  return values[(idx + 1) % values.length];
+}
+
 /** Convert an Array or space-separated string to a Set. */
 export function toSet(val: any): Set<string> {
   if (val instanceof Set) {
@@ -776,12 +782,8 @@ export function toSet(val: any): Set<string> {
  * ```
  */
 export function toPixel(
-  // val: string | number | undefined | null,
   ...defaults: (string | number | undefined | null)[]
 ): number {
-  // if (typeof val === "number") {
-  //   return val;
-  // }
   for (const d of defaults) {
     if (typeof d === "number") {
       return d;
@@ -802,12 +804,8 @@ export function toPixel(
  * ```
  */
 export function toBool(
-  // val: boolean | undefined | null,
   ...boolDefaults: (boolean | undefined | null)[]
 ): boolean {
-  // if (val != null) {
-  //   return !!val;
-  // }
   for (const d of boolDefaults) {
     if (d != null) {
       return !!d;

package/src/wb_ext_grid.ts

@@ -29,7 +29,7 @@ export class GridExtension extends WunderbaumExtension<GridOptionsType> {
         const allow =
           colDef &&
           this.tree.element.contains(e.dragElem) &&
-          toBool(colDef.resizable, tree.options.resizableColumns, false);
+          toBool(colDef.resizable, tree.options.columnsResizable, false);
 
         // this.tree.log("dragstart", colDef, e, info);
 

package/src/wb_node.ts

@@ -13,6 +13,7 @@ import {
   ApplyCommandType,
   ChangeType,
   CheckboxOption,
+  ColumnDefinition,
   ColumnEventInfoMap,
   ExpandAllOptions,
   IconOption,
@@ -27,12 +28,15 @@ import {
   NodeVisitCallback,
   NodeVisitResponse,
   RenderOptions,
+  ResetOrderOptions,
   ScrollIntoViewOptions,
   SetActiveOptions,
   SetExpandedOptions,
   SetSelectedOptions,
   SetStatusOptions,
+  SortByPropertyOptions,
   SortCallback,
+  SortOrderType,
   SourceType,
   TooltipOption,
   TristateType,
@@ -104,12 +108,26 @@ export class WunderbaumNode {
    * @see Use {@link setKey} to modify.
    */
   public readonly refKey: string | undefined = undefined;
+  /**
+   * Array of child nodes (null for leaf nodes).
+   * For lazy nodes, this is `null` or ùndefined` until the children are loaded
+   * and leaf nodes may be `[]` (empty array).
+   * @see {@link hasChildren}, {@link addChildren}, {@link lazy}.
+   */
   public children: WunderbaumNode[] | null = null;
+  /** Render a checkbox or radio button @see {@link selected}. */
   public checkbox?: CheckboxOption;
+  /** If true, this node's children are considerd radio buttons.
+   * @see {@link isRadio}.
+   */
   public radiogroup?: boolean;
   /** If true, (in grid mode) no cells are rendered, except for the node title.*/
   public colspan?: boolean;
+  /** Icon definition. */
   public icon?: IconOption;
+  /** Lazy loading flag.
+   * @see {@link isLazy}, {@link isLoaded}, {@link isUnloaded}.
+   */
   public lazy?: boolean;
   /** Expansion state.
    * @see {@link isExpandable}, {@link isExpanded}, {@link setExpanded}. */
@@ -118,7 +136,11 @@ export class WunderbaumNode {
    * @see {@link isSelected}, {@link setSelected}, {@link toggleSelected}. */
   public selected?: boolean;
   public unselectable?: boolean;
+  /** Node type (used for styling).
+   * @see {@link Wunderbaum.types}.
+   */
   public type?: string;
+  /** Tooltip definition (`true`: use node's title). */
   public tooltip?: string | boolean;
   /** Additional classes added to `div.wb-row`.
    * @see {@link hasClass}, {@link setClass}. */
@@ -787,7 +809,7 @@ export class WunderbaumNode {
     return this.classes ? this.classes.has(className) : false;
   }
 
-  /** Return true if node ist the currently focused node. */
+  /** Return true if node ist the currently focused node. @since 0.9.0 */
   hasFocus(): boolean {
     return this.tree.focusNode === this;
   }
@@ -1054,6 +1076,8 @@ export class WunderbaumNode {
     if (tree.options.selectMode === "hier") {
       this.fixSelection3FromEndNodes();
     }
+    // Allow to un-sort nodes after sorting
+    this.resetNativeChildOrder();
 
     this._callEvent("load");
   }
@@ -2091,7 +2115,7 @@ export class WunderbaumNode {
    *
    * @param name name of the option property (on node and tree)
    * @param defaultValue return this if nothing else matched
-   * {@link Wunderbaum.getOption|Wunderbaum.getOption()}
+   * {@link Wunderbaum.getOption|Wunderbaum.getOption}
    */
   getOption(name: string, defaultValue?: any) {
     const tree = this.tree;
@@ -2130,7 +2154,7 @@ export class WunderbaumNode {
   }
 
   /** Make sure that this node is visible in the viewport.
-   * @see {@link Wunderbaum.scrollTo|Wunderbaum.scrollTo()}
+   * @see {@link Wunderbaum.scrollTo|Wunderbaum.scrollTo}
    */
   async scrollIntoView(options?: ScrollIntoViewOptions) {
     const opts = Object.assign({ node: this }, options);
@@ -2284,9 +2308,9 @@ export class WunderbaumNode {
    * and column content. It can be reduced to 'ChangeType.status' if only
    * active/focus/selected state has changed.
    *
-   * This method will eventually call  {@link WunderbaumNode._render()} with
+   * This method will eventually call  {@link WunderbaumNode._render} with
    * default options, but may be more consistent with the tree's
-   * {@link Wunderbaum.update()} API.
+   * {@link Wunderbaum.update} API.
    */
   update(change: ChangeType = ChangeType.data) {
     util.assert(
@@ -2669,6 +2693,93 @@ export class WunderbaumNode {
     // this.triggerModify("sort"); // TODO
   }
 
+  /**
+   * Renumber nodes `_nativeIndex`. This is useful to allow to restore the
+   * order after sorting a column.
+   * This method is automatically called after loading new child nodes.
+   * @since 0.11.0
+   */
+  resetNativeChildOrder(options?: ResetOrderOptions) {
+    const { recursive = true, propName = "_nativeIndex" } = options ?? {};
+
+    if (this.children) {
+      this.children.forEach((child, i) => {
+        child.data[propName] = i;
+        if (recursive && child.children) {
+          child.resetNativeChildOrder(options);
+        }
+      });
+    }
+  }
+
+  /**
+   * Convenience method to implement column sorting.
+   * @since 0.11.0
+   */
+  sortByProperty(options: SortByPropertyOptions) {
+    const {
+      caseInsensitive = true,
+      deep = true,
+      nativeOrderPropName = "_nativeIndex",
+      updateColInfo = false,
+    } = options;
+
+    let order: SortOrderType;
+    let colDef: ColumnDefinition | null;
+
+    if (updateColInfo) {
+      colDef = this.tree["_columnsById"][options.colId!];
+      util.assert(colDef, `Invalid colId specified: ${options.colId}`);
+      order =
+        options.order ??
+        util.rotate(colDef!.sortOrder, ["asc", "desc", undefined]);
+
+      for (const col of this.tree.columns) {
+        col.sortOrder = col === colDef ? order : undefined;
+      }
+
+      this.tree.update(ChangeType.colStructure);
+    } else {
+      order = options.order ?? "asc";
+    }
+
+    let propName = options.propName ?? (options.colId || "");
+    if (propName === "*") {
+      propName = "title";
+    }
+    if (order == null) {
+      propName = nativeOrderPropName;
+      order = "asc";
+    }
+    this.logDebug(`sortByProperty(), propName=${propName}, ${order}`, options);
+    util.assert(propName, "No property name specified");
+
+    const cmp = (a: WunderbaumNode, b: WunderbaumNode) => {
+      let av, bv;
+      if (NODE_DICT_PROPS.has(<string>propName)) {
+        av = a[propName as keyof WunderbaumNode];
+        bv = b[propName as keyof WunderbaumNode];
+      } else {
+        av = a.data[propName];
+        bv = b.data[propName];
+      }
+      if (caseInsensitive) {
+        if (typeof av === "string") {
+          av = av.toLowerCase();
+        }
+        if (typeof bv === "string") {
+          bv = bv.toLowerCase();
+        }
+      }
+      if (order === "desc") {
+        return av === bv ? 0 : av > bv ? -1 : 1;
+      }
+      return av === bv ? 0 : av > bv ? 1 : -1;
+    };
+
+    return this.sortChildren(cmp, deep);
+  }
+
   /**
    * Trigger `modifyChild` event on a parent to signal that a child was modified.
    * @param {string} operation Type of change: 'add', 'remove', 'rename', 'move', 'data', ...