wunderbaum 0.12.1 → 0.14.0

package/src/wunderbaum.ts

@@ -25,15 +25,13 @@ import {
   ApplyCommandType,
   ChangeType,
   ColumnDefinitionList,
-  DynamicBoolOption,
-  DynamicCheckboxOption,
-  DynamicIconOption,
-  DynamicStringOption,
-  DynamicTooltipOption,
   ExpandAllOptions,
   FilterModeType,
   FilterNodesOptions,
+  IconMapType,
+  GetStateOptions,
   MatcherCallback,
+  NavigationType,
   NavModeEnum,
   NodeFilterCallback,
   NodeRegion,
@@ -46,27 +44,38 @@ import {
   ScrollToOptions,
   SetActiveOptions,
   SetColumnOptions,
+  SetStateOptions,
   SetStatusOptions,
-  SortByPropertyOptions,
   SortCallback,
   SourceType,
+  TreeStateDefinition,
   UpdateOptions,
   VisitRowsOptions,
   WbEventInfo,
   WbNodeData,
+  FilterOptionsType,
+  EditOptionsType,
+  DndOptionsType,
+  SortOptions,
+  DeprecationOptions,
+  SortByPropertyOptions,
+  ReloadOptions,
+  LoadLazyNodesOptions,
 } from "./types";
 import {
   DEFAULT_DEBUGLEVEL,
-  iconMaps,
+  defaultIconMaps,
   makeNodeTitleStartMatcher,
   nodeTitleSorter,
   RENDER_MAX_PREFETCH,
   DEFAULT_ROW_HEIGHT,
+  TEST_FILE_PATH,
+  TEST_HTML,
 } from "./common";
 import { WunderbaumNode } from "./wb_node";
 import { Deferred } from "./deferred";
 import { EditExtension } from "./wb_ext_edit";
-import { WunderbaumOptions } from "./wb_options";
+import { InitWunderbaumOptions, WunderbaumOptions } from "./wb_options";
 import { DebouncedFunction } from "./debounce";
 
 class WbSystemRoot extends WunderbaumNode {
@@ -110,7 +119,7 @@ export class Wunderbaum {
 
   protected readonly _updateViewportThrottled: DebouncedFunction<() => void>;
   protected extensionList: WunderbaumExtension<any>[] = [];
-  protected extensions: ExtensionsDict = {};
+  protected extensions: ExtensionsDict = <ExtensionsDict>{};
 
   /** Merged options from constructor args and tree- and extension defaults. */
   public options: WunderbaumOptions;
@@ -123,6 +132,7 @@ export class Wunderbaum {
 
   protected _activeNode: WunderbaumNode | null = null;
   protected _focusNode: WunderbaumNode | null = null;
+  protected _initialSource: SourceType | null = null;
 
   /** Currently active node if any.
    * Use {@link WunderbaumNode.setActive|setActive} to modify.
@@ -142,18 +152,7 @@ export class Wunderbaum {
   /** Shared properties, referenced by `node.type`. */
   public types: NodeTypeDefinitionMap = {};
   /** List of column definitions. */
-  public columns: ColumnDefinitionList = []; // any[] = [];
-  /** Show/hide a checkbox or radiobutton. */
-  public checkbox?: DynamicCheckboxOption;
-  /** Show/hide a node icon. */
-  public icon?: DynamicIconOption;
-  /** Show/hide a tooltip for the node icon. */
-  public iconTooltip?: DynamicStringOption;
-  /** Show/hide a tooltip. */
-  public tooltip?: DynamicTooltipOption;
-  /** Define a node checkbox as readonly. */
-  public unselectable?: DynamicBoolOption;
-
+  public columns: ColumnDefinitionList = [];
   protected _columnsById: { [key: string]: any } = {};
   protected resizeObserver: ResizeObserver;
 
@@ -164,13 +163,28 @@ export class Wunderbaum {
   public readonly ready: Promise<any>;
   /** Expose some useful methods of the util.ts module as `Wunderbaum.util`. */
   public static util = util;
+  /** A map of default iconMaps.
+   * May be used as default, when passing partial icon definition maps:
+   * ```js
+   * const tree = new mar10.Wunderbaum({
+   *   ...
+   *   iconMap: Object.assign(Wunderbaum.iconMaps.bootstrap, {
+   *     folder: "bi bi-archive",
+   *   }),
+   * });
+   * ```
+   */
+  public static iconMaps = defaultIconMaps;
   /** Expose some useful methods of the util.ts module as `tree._util`. */
   public _util = util;
 
   // --- SELECT ---
-  // /** @internal */
   // public selectRangeAnchor: WunderbaumNode | null = null;
 
+  // --- BREADCRUMB ---
+  /** Filter options (used as defaults for calls to {@link Wunderbaum.filterNodes} ) */
+  public breadcrumb: HTMLElement | null = null;
+
   // --- FILTER ---
   /** Filter options (used as defaults for calls to {@link Wunderbaum.filterNodes} ) */
   public filterMode: FilterModeType = null;
@@ -188,49 +202,65 @@ export class Wunderbaum {
   // --- EDIT ---
   protected lastClickTime = 0;
 
-  constructor(options: WunderbaumOptions) {
-    const opts = (this.options = util.extend(
+  constructor(options: InitWunderbaumOptions) {
+    // Set default options and merge with user options
+    const initOptions = Object.assign<
+      InitWunderbaumOptions,
+      InitWunderbaumOptions
+    >(
       {
-        id: null,
-        source: null, // URL for GET/PUT, Ajax options, or callback
-        element: null, // <div class="wunderbaum">
+        id: undefined,
+        source: [], // URL for GET/PUT, Ajax options, or callback
+        element: util.unsafeCast<string>(null),
         debugLevel: DEFAULT_DEBUGLEVEL, // 0:quiet, 1:errors, 2:warnings, 3:info, 4:verbose
         header: null, // Show/hide header (pass bool or string)
-        // headerHeightPx: ROW_HEIGHT,
         rowHeightPx: DEFAULT_ROW_HEIGHT,
         iconMap: "bootstrap",
-        columns: null,
-        types: null,
-        // escapeTitles: true,
+        columns: [], //util.unsafeCast<ColumnDefinitionList>(null),
+        types: {},
         enabled: true,
         fixedCol: false,
         showSpinner: false,
         checkbox: false,
         minExpandLevel: 0,
         emptyChildListExpandable: false,
-        // updateThrottleWait: 200,
         skeleton: false,
-        connectTopBreadcrumb: null, // HTMLElement that receives the top nodes breadcrumb
+        autoCollapse: false,
+        adjustHeight: true,
+        connectTopBreadcrumb: null,
+        columnsFilterable: false,
+        columnsMenu: false,
+        columnsResizable: false,
+        columnsSortable: false,
         selectMode: "multi", // SelectModeType
+        scrollIntoViewOnExpandClick: true,
+        // --- Extensions (actually set by exensions on init)
+        dnd: util.unsafeCast<DndOptionsType>(null),
+        edit: util.unsafeCast<EditOptionsType>(null),
+        filter: util.unsafeCast<FilterOptionsType>(null),
         // --- KeyNav ---
-        navigationModeOption: null, // NavModeEnum.startRow,
+        navigationModeOption: util.unsafeCast<NavModeEnum>(null),
         quicksearch: true,
         // --- Events ---
-        iconBadge: null,
-        change: null,
-        // enhanceTitle: null,
-        error: null,
-        receive: null,
+        // iconBadge: null,
+        // change: null,
+        // ...
+
         // --- Strings ---
         strings: {
           loadError: "Error",
           loading: "Loading...",
-          // loading: "Loading&hellip;",
           noData: "No data",
+          breadcrumbDelimiter: " » ",
+          queryResult: "Found ${matches} of ${count}",
+          noMatch: "No results",
+          matchIndex: "${match} of ${matches}",
         },
       },
       options
-    ));
+    );
+    const opts = initOptions as WunderbaumOptions;
+    this.options = opts;
 
     const readyDeferred = new Deferred();
     this.ready = readyDeferred.promise();
@@ -257,7 +287,8 @@ export class Wunderbaum {
         }
       });
 
-    this.id = opts.id || "wb_" + ++Wunderbaum.sequence;
+    this.id = initOptions.id || "wb_" + ++Wunderbaum.sequence;
+    delete initOptions.id;
     this.root = new WbSystemRoot(this);
 
     this._registerExtension(new KeynavExtension(this));
@@ -273,21 +304,25 @@ export class Wunderbaum {
     );
 
     // --- Evaluate options
-    this.columns = opts.columns;
-    delete opts.columns;
+    this.columns = initOptions.columns || [];
+    delete initOptions.columns;
     if (!this.columns || !this.columns.length) {
       const title = typeof opts.header === "string" ? opts.header : this.id;
       this.columns = [{ id: "*", title: title, width: "*" }];
     }
 
-    if (opts.types) {
-      this.setTypes(opts.types, true);
+    if (initOptions.types) {
+      this.setTypes(initOptions.types, true);
     }
-    delete opts.types;
+    delete initOptions.types;
 
     // --- Create Markup
-    this.element = util.elemFromSelector<HTMLDivElement>(opts.element)!;
-    util.assert(!!this.element, `Invalid 'element' option: ${opts.element}`);
+    this.element = util.elemFromSelector<HTMLDivElement>(initOptions.element)!;
+    util.assert(
+      !!this.element,
+      `Invalid 'element' option: ${initOptions.element}`
+    );
+    delete (<any>initOptions).element;
 
     this.element.classList.add("wunderbaum");
     if (!this.element.getAttribute("tabindex")) {
@@ -368,21 +403,39 @@ export class Wunderbaum {
 
     this.element.classList.toggle("wb-grid", this.columns.length > 1);
 
+    if (this.options.connectTopBreadcrumb) {
+      this.breadcrumb = util.elemFromSelector(
+        this.options.connectTopBreadcrumb
+      )!;
+      util.assert(
+        !this.breadcrumb || this.breadcrumb.innerHTML != null,
+        `Invalid 'connectTopBreadcrumb' option: ${this.breadcrumb}.`
+      );
+      this.breadcrumb.addEventListener("click", (e) => {
+        // const node = Wunderbaum.getNode(e)!;
+        const elem = e.target as HTMLElement;
+        if (elem && elem.matches("a.wb-breadcrumb")) {
+          const node = this.keyMap.get(elem.dataset.key!);
+          node?.setActive();
+          e.preventDefault();
+        }
+      });
+    }
     this._initExtensions();
 
     // --- apply initial options
     ["enabled", "fixedCol"].forEach((optName) => {
-      if (opts[optName] != null) {
-        this.setOption(optName, opts[optName]);
+      if ((opts as any)[optName] != null) {
+        this.setOption(optName, (opts as any)[optName]);
       }
     });
 
     // --- Load initial data
-    if (opts.source) {
+    if (initOptions.source) {
       if (opts.showSpinner) {
         this.nodeListElement.innerHTML = `<progress class='spinner'>${opts.strings.loading}</progress>`;
       }
-      this.load(opts.source)
+      this.load(initOptions.source)
         .then(() => {
           // The source may have defined columns, so we may adjust the nav mode
           if (opts.navigationModeOption == null) {
@@ -413,16 +466,20 @@ export class Wunderbaum {
     this.update(ChangeType.any);
 
     // --- Bind listeners
-    this.element.addEventListener("scroll", (e: Event) => {
-      // this.log(`scroll, scrollTop:${e.target.scrollTop}`, e);
-      this.update(ChangeType.scroll);
-    });
+    this._registerEventHandlers();
 
     this.resizeObserver = new ResizeObserver((entries) => {
       // this.log("ResizeObserver: Size changed", entries);
       this.update(ChangeType.resize);
     });
     this.resizeObserver.observe(this.element);
+  }
+
+  private _registerEventHandlers() {
+    this.element.addEventListener("scroll", (e: Event) => {
+      // this.log(`scroll, scrollTop:${e.target.scrollTop}`, e);
+      this.update(ChangeType.scroll);
+    });
 
     util.onEvent(this.element, "click", ".wb-button,.wb-col-icon", (e) => {
       const info = Wunderbaum.getEventInfo(e);
@@ -442,10 +499,6 @@ export class Wunderbaum {
 
       // this.log("click", info);
 
-      // if (this._selectRange(info) === false) {
-      //   return;
-      // }
-
       if (
         this._callEvent("click", { event: e, node: node, info: info }) === false
       ) {
@@ -469,18 +522,18 @@ export class Wunderbaum {
           node.startEditTitle();
         }
 
-        if (info.colIdx >= 0) {
-          node.setActive(true, { colIdx: info.colIdx, event: e });
-        } else {
-          node.setActive(true, { event: e });
-        }
-
         if (info.region === NodeRegion.expander) {
           node.setExpanded(!node.isExpanded(), {
-            scrollIntoView: options.scrollIntoViewOnExpandClick !== false,
+            scrollIntoView: this.options.scrollIntoViewOnExpandClick !== false,
           });
         } else if (info.region === NodeRegion.checkbox) {
           node.toggleSelected();
+        } else {
+          if (info.colIdx >= 0) {
+            node.setActive(true, { colIdx: info.colIdx, event: e });
+          } else {
+            node.setActive(true, { event: e });
+          }
         }
       }
       this.lastClickTime = Date.now();
@@ -528,7 +581,7 @@ export class Wunderbaum {
       this._callEvent("focus", { flag: flag, event: e });
 
       if (flag && this.isRowNav() && !this.isEditingTitle()) {
-        if ((opts.navigationModeOption as NavModeEnum) === NavModeEnum.row) {
+        if (this.options.navigationModeOption === NavModeEnum.row) {
           targetNode?.setActive();
         } else {
           this.setCellNav();
@@ -542,7 +595,6 @@ export class Wunderbaum {
       }
     });
   }
-
   /**
    * Return a Wunderbaum instance, from element, id, index, or event.
    *
@@ -596,14 +648,16 @@ export class Wunderbaum {
 
   /**
    * Return the icon-function -> icon-definition mapping.
+   * @deprecated Use {@link Wunderbaum.iconMaps}
    */
-  get iconMap(): { [key: string]: string } {
-    const map = this.options.iconMap!;
+  get iconMap(): IconMapType {
+    const map = this.options.iconMap;
     if (typeof map === "string") {
-      return iconMaps[map];
+      return defaultIconMaps[map as keyof typeof defaultIconMaps];
     }
     return map;
   }
+
   /**
    * Return a WunderbaumNode instance from element or event.
    */
@@ -656,7 +710,42 @@ export class Wunderbaum {
     }
   }
 
-  /** Add node to tree's bookkeeping data structures. */
+  /**
+   * Calculate a *stable*, unique key for a node from its refKey (or title).
+   * We also add information from the parent, because a refKey may occur multiple
+   * times in a tree (but not as child of the same parent).
+   * @internal
+   */
+  _calculateKey(data: WbNodeData, parent?: WunderbaumNode): string {
+    if (data.key) {
+      // Always use an explicitly passed key
+      return data.key;
+    }
+    // Auto-keys are optional, use a monotonic counter by default:
+    if (!this.options.autoKeys) {
+      return "" + ++WunderbaumNode.sequence;
+    }
+    // Add the parent's key to the hash. Assuming this was generated by the
+    // same algorithm, this should incorporate the whole path:
+    const s = (parent ? parent.key : "") + (data.refKey || data.title);
+    // 32-bit has a high probability of collisions, so we pump up to 64-bit
+    // https://security.stackexchange.com/q/209882/207588
+    const h1 = util.murmurHash3(s, true);
+    let key = "id_" + h1 + util.murmurHash3(h1 + s, true);
+    // Check for collisions
+    // (Most likely if the same title occurs multiple in the same parent).
+    const existingNode = this.keyMap.get(key);
+    if (existingNode) {
+      key += "." + ++Wunderbaum.sequence;
+      this.logWarn(
+        `Node with existing key: '${existingNode}', using ${key}.`,
+        data
+      );
+    }
+    return key;
+  }
+
+  /** Add node to tree's bookkeeping data structures. @internal */
   _registerNode(node: WunderbaumNode): void {
     const key = node.key;
     util.assert(key != null, `Missing key: '${node}'.`);
@@ -673,7 +762,7 @@ export class Wunderbaum {
     }
   }
 
-  /** Remove node from tree's bookkeeping data structures. */
+  /** Remove node from tree's bookkeeping data structures. @internal  */
   _unregisterNode(node: WunderbaumNode): void {
     // Remove refKey reference from map (if any)
     const rk = node.refKey;
@@ -771,9 +860,12 @@ export class Wunderbaum {
     return <WunderbaumNode>node!;
   }
 
-  /** Return the topmost visible node in the viewport. */
+  /** Return the topmost visible node in the viewport.
+   * @param complete If `false`, the node is considered visible if at least one
+   * pixel is visible.
+   */
   getTopmostVpNode(complete = true) {
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const gracePx = 1; // ignore subpixel scrolling
     const scrollParent = this.element;
     // const headerHeight = this.headerElement.clientHeight;  // May be 0
@@ -790,7 +882,7 @@ export class Wunderbaum {
 
   /** Return the lowest visible node in the viewport. */
   getLowestVpNode(complete = true) {
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const scrollParent = this.element;
     const headerHeight = this.headerElement.clientHeight; // May be 0
     const scrollTop = scrollParent.scrollTop;
@@ -806,7 +898,7 @@ export class Wunderbaum {
     return this._getNodeByRowIdx(bottomIdx)!;
   }
 
-  /** Return preceeding visible node in the viewport. */
+  /** Return preceding visible node in the viewport. */
   protected _getPrevNodeInView(node?: WunderbaumNode, ofs = 1) {
     this.visitRows(
       (n) => {
@@ -821,15 +913,28 @@ export class Wunderbaum {
   }
 
   /** Return following visible node in the viewport. */
-  protected _getNextNodeInView(node?: WunderbaumNode, ofs = 1) {
+  protected _getNextNodeInView(
+    node?: WunderbaumNode,
+    options?: {
+      ofs?: number;
+      reverse?: boolean;
+      cb?: (n: WunderbaumNode) => boolean;
+    }
+  ) {
+    let ofs = options?.ofs || 1;
+    const reverse = !!options?.reverse;
+
     this.visitRows(
       (n) => {
         node = n;
+        if (options?.cb && options.cb(n)) {
+          return false;
+        }
         if (ofs-- <= 0) {
           return false;
         }
       },
-      { reverse: false, start: node || this.getActiveNode() }
+      { reverse: reverse, start: node || this.getActiveNode() }
     );
     return node;
   }
@@ -972,9 +1077,11 @@ export class Wunderbaum {
       case "first":
       case "last":
       case "left":
+      case "nextMatch":
       case "pageDown":
       case "pageUp":
       case "parent":
+      case "prevMatch":
       case "right":
       case "up":
         return node.navigate(cmd);
@@ -1103,24 +1210,40 @@ export class Wunderbaum {
   /** Run code, but defer rendering of viewport until done.
    *
    * ```js
-   * tree.runWithDeferredUpdate(() => {
-   *   return someFuncThatWouldUpdateManyNodes();
+   * const res = tree.runWithDeferredUpdate(() => {
+   *   return someFunctionThatWouldUpdateManyNodes();
    * });
    * ```
    */
-  runWithDeferredUpdate(func: () => any, hint = null): any {
+  runWithDeferredUpdate<T>(func: () => util.NotPromise<T>): T {
     try {
       this.enableUpdate(false);
       const res = func();
       util.assert(
         !(res instanceof Promise),
-        `Promise return not allowed: ${res}`
+        `Promise return not allowed (see 'runWithDeferredUpdateAsync()'): ${res}`
       );
       return res;
     } finally {
       this.enableUpdate(true);
     }
   }
+  /** Run code, but defer rendering of viewport until done.
+   *
+   * ```js
+   * const res = await tree.runWithDeferredUpdate(async () => {
+   *   return someAsyncFunctionThatWouldUpdateManyNodes();
+   * });
+   * ```
+   */
+  async runWithDeferredUpdateAsync<T>(func: () => Promise<T>): Promise<T> {
+    try {
+      this.enableUpdate(false);
+      return await func();
+    } finally {
+      this.enableUpdate(true);
+    }
+  }
 
   /** Recursively expand all expandable nodes (triggers lazy load if needed). */
   async expandAll(flag: boolean = true, options?: ExpandAllOptions) {
@@ -1145,6 +1268,18 @@ export class Wunderbaum {
     return this.root.getSelectedNodes(stopOnParents);
   }
 
+  /**
+   * Return an array of refKey values.
+   *
+   * RefKeys are unique identifiers for a node data, and are used to identify
+   * clones.
+   * If more than one node has the same refKey, it is only returned once.
+   * @param selected if true, only return refKeys of selected nodes.
+   */
+  getRefKeys(selected = false): string[] {
+    return this.root.getRefKeys(selected);
+  }
+
   /*
    * Return an array of selected nodes.
    */
@@ -1190,6 +1325,12 @@ export class Wunderbaum {
     return visible ? this.treeRowCount : this.keyMap.size;
   }
 
+  /** Return the number of *unique* nodes in the data model, i.e. unique `node.refKey`.
+   */
+  countUnique(): number {
+    return this.refKeyMap.size;
+  }
+
   /** @internal sanity check. */
   _check() {
     let i = 0;
@@ -1255,15 +1396,18 @@ export class Wunderbaum {
    */
   findNextNode(
     match: string | MatcherCallback,
-    startNode?: WunderbaumNode | null
+    startNode?: WunderbaumNode | null,
+    reverse = false
   ): WunderbaumNode | null {
     //, visibleOnly) {
     let res: WunderbaumNode | null = null;
     const firstNode = this.getFirstChild()!;
+    // Last visible node (calculation is expensive, so do only if we need it):
+    const lastNode = reverse ? this.findRelatedNode(firstNode, "last")! : null;
 
     const matcher =
       typeof match === "string" ? makeNodeTitleStartMatcher(match) : match;
-    startNode = startNode || firstNode;
+    startNode = startNode || (reverse ? lastNode : firstNode);
 
     function _checkNode(n: WunderbaumNode) {
       // console.log("_check " + n)
@@ -1277,12 +1421,14 @@ export class Wunderbaum {
     this.visitRows(_checkNode, {
       start: startNode,
       includeSelf: false,
+      reverse: reverse,
     });
     // Wrap around search
     if (!res && startNode !== firstNode) {
       this.visitRows(_checkNode, {
-        start: firstNode,
+        start: reverse ? lastNode : firstNode,
         includeSelf: true,
+        reverse: reverse,
       });
     }
     return res;
@@ -1297,8 +1443,12 @@ export class Wunderbaum {
    *   e.g. `$.ui.keyCode.LEFT` = 'left'.
    * @param includeHidden Not yet implemented
    */
-  findRelatedNode(node: WunderbaumNode, where: string, includeHidden = false) {
-    const rowHeight = this.options.rowHeightPx!;
+  findRelatedNode(
+    node: WunderbaumNode,
+    where: NavigationType,
+    includeHidden = false
+  ) {
+    const rowHeight = this.options.rowHeightPx;
     let res = null;
     const pageSize = Math.floor(
       this.listContainerElement.clientHeight / rowHeight
@@ -1353,7 +1503,7 @@ export class Wunderbaum {
         // }
         break;
       case "up":
-        res = this._getPrevNodeInView(node);
+        res = this._getNextNodeInView(node, { reverse: true });
         break;
       case "down":
         res = this._getNextNodeInView(node);
@@ -1366,7 +1516,10 @@ export class Wunderbaum {
           if (node._rowIdx! < bottomNode._rowIdx!) {
             res = bottomNode;
           } else {
-            res = this._getNextNodeInView(node, pageSize);
+            res = this._getNextNodeInView(node, {
+              reverse: false,
+              ofs: pageSize,
+            });
           }
         }
         break;
@@ -1380,10 +1533,28 @@ export class Wunderbaum {
           if (node._rowIdx! > topNode._rowIdx!) {
             res = topNode;
           } else {
-            res = this._getPrevNodeInView(node, pageSize);
+            res = this._getNextNodeInView(node, {
+              reverse: true,
+              ofs: pageSize,
+            });
           }
         }
         break;
+
+      case "prevMatch":
+      // fallthrough
+      case "nextMatch":
+        if (!this.isFilterActive) {
+          this.logWarn(`${where}: Filter is not active.`);
+          break;
+        }
+        res = this.findNextNode(
+          (n) => n.isMatched(),
+          node,
+          where === "prevMatch"
+        );
+        res?.setActive();
+        break;
       default:
         this.logWarn("Unknown relation '" + where + "'.");
     }
@@ -1424,6 +1595,20 @@ export class Wunderbaum {
     return this.root.format(name_cb, connectors);
   }
 
+  /**
+   * Always returns null (so a tree instance behaves as `tree.root`).
+   */
+  get parent(): null {
+    return null;
+  }
+
+  /**
+   * Return a list of top-level nodes.
+   */
+  get children(): WunderbaumNode[] {
+    return this.root.children || [];
+  }
+
   /**
    * Return the active cell (`span.wb-col`) of the currently active node or null.
    */
@@ -1454,6 +1639,13 @@ export class Wunderbaum {
     return this.root.getFirstChild();
   }
 
+  /**
+   * Return the last top level node if any (not the invisible root node).
+   */
+  getLastChild() {
+    return this.root.getLastChild();
+  }
+
   /**
    * Return the node that currently has keyboard focus or null.
    * Alias for {@link Wunderbaum.focusNode}.
@@ -1539,7 +1731,7 @@ export class Wunderbaum {
 
   /** Return true if any node title or grid cell is currently beeing edited.
    *
-   * See also {@link Wunderbaum.isEditingTitle}.
+   * See also {@link isEditingTitle}.
    */
   isEditing(): boolean {
     const focusElem = this.nodeListElement.querySelector(
@@ -1550,7 +1742,7 @@ export class Wunderbaum {
 
   /** Return true if any node is currently in edit-title mode.
    *
-   * See also {@link WunderbaumNode.isEditingTitle} and {@link Wunderbaum.isEditing}.
+   * See also {@link WunderbaumNode.isEditingTitle} and {@link isEditing}.
    */
   isEditingTitle(): boolean {
     return this._callMethod("edit.isEditingTitle");
@@ -1573,7 +1765,7 @@ export class Wunderbaum {
   }
 
   /** Write to `console.log` with tree name as prefix if opts.debugLevel >= 4.
-   * @see {@link Wunderbaum.logDebug}
+   * @see {@link logDebug}
    */
   log(...args: any[]) {
     if (this.options.debugLevel! >= 4) {
@@ -1583,7 +1775,7 @@ export class Wunderbaum {
 
   /** Write to `console.debug`  with tree name as prefix if opts.debugLevel >= 4.
    * and browser console level includes debug/verbose messages.
-   * @see {@link Wunderbaum.log}
+   * @see {@link log}
    */
   logDebug(...args: any[]) {
     if (this.options.debugLevel! >= 4) {
@@ -1627,6 +1819,20 @@ export class Wunderbaum {
     }
   }
 
+  /** Emit a warning for deprecated methods. @internal */
+  logDeprecate(method: string, options?: DeprecationOptions) {
+    if (this.options.debugLevel! >= 2) {
+      let msg = `${this}: ${method} is deprecated`;
+      if (options?.since) {
+        msg += ` since ${options.since}`;
+      }
+      if (options?.hint) {
+        msg += ` (${options.since})`;
+      }
+      console.warn(msg + "."); // eslint-disable-line no-console
+    }
+  }
+
   /** Reset column widths to default. @since 0.10.0 */
   resetColumns() {
     this.columns.forEach((col) => {
@@ -1661,7 +1867,7 @@ export class Wunderbaum {
     }
     util.assert(node && node._rowIdx != null, `Invalid node: ${node}`);
 
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const scrollParent = this.element;
     const headerHeight = this.headerElement.clientHeight; // May be 0
     const scrollTop = scrollParent.scrollTop;
@@ -1816,6 +2022,75 @@ export class Wunderbaum {
     this._focusNode = node;
   }
 
+  /** Return the current selection/expansion/activation status. @experimental */
+  getState(options: GetStateOptions = {}): TreeStateDefinition {
+    const {
+      activeKey = true,
+      expandedKeys = false,
+      selectedKeys = false,
+    } = options;
+
+    const expandSet = new Set<string>();
+
+    if (expandedKeys) {
+      for (const node of this) {
+        if (node.isExpanded() && node.hasChildren()) {
+          expandSet.add(node.key);
+        }
+      }
+    }
+    // Parents of active node are always expanded
+    if (activeKey && this.activeNode) {
+      this.activeNode.visitParents((n) => {
+        if (n.parent) {
+          expandSet.add(n.key);
+        }
+      }, false);
+    }
+
+    const state: TreeStateDefinition = {
+      expandedKeys: expandSet.size ? Array.from(expandSet) : undefined,
+      activeKey: this.activeNode?.key ?? null,
+      activeColIdx: this.activeColIdx,
+      selectedKeys: selectedKeys
+        ? this.getSelectedNodes().flatMap((n) => n.key)
+        : undefined,
+    };
+    return state;
+  }
+
+  /** Apply selection/expansion/activation status. @experimental */
+  async setState(state: TreeStateDefinition, options: SetStateOptions = {}) {
+    const { expandLazy = true } = options;
+    return this.runWithDeferredUpdateAsync(async () => {
+      if (state.expandedKeys && state.expandedKeys.length) {
+        if (expandLazy) {
+          // Expand all keys recursively, even if they are not in the tree yet
+          await this._loadLazyNodes(state.expandedKeys, {
+            expand: true,
+            noEvents: true,
+          });
+        } else {
+          for (const key of state.expandedKeys) {
+            this.findKey(key)?.setExpanded(true);
+          }
+        }
+      }
+      if (state.activeKey) {
+        this.setActiveNode(state.activeKey);
+      }
+      if (state.selectedKeys) {
+        this.selectAll(false);
+        for (const key of state.selectedKeys) {
+          this.findKey(key)?.setSelected(true);
+        }
+      }
+      if (this.isCellNav() && state.activeColIdx != null) {
+        this.setColumn(state.activeColIdx);
+      }
+    });
+  }
+
   /**
    * Schedule an update request to reflect a tree change.
    * The render operation is async and debounced unless the `immediate` option
@@ -2011,23 +2286,39 @@ export class Wunderbaum {
    * @param {function} cmp custom compare function(a, b) that returns -1, 0, or 1
    *    (defaults to sorting by title).
    * @param {boolean} deep pass true to sort all descendant nodes recursively
+   * @deprecated use {@link sort}
    */
   sortChildren(
     cmp: SortCallback | null = nodeTitleSorter,
     deep: boolean = false
   ): void {
-    this.root.sortChildren(cmp, deep);
+    this.logDeprecate("sortChildren()", { since: "0.14.0" });
+    return this.sort({
+      cmp: cmp ? cmp : undefined,
+      deep: deep,
+      propName: "title",
+    });
   }
 
   /**
    * Convenience method to implement column sorting.
    * @see {@link WunderbaumNode.sortByProperty}.
    * @since 0.11.0
+   * @deprecated use {@link sort}
    */
   sortByProperty(options: SortByPropertyOptions) {
+    this.logDeprecate("sortByProperty()", { since: "0.14.0" });
     this.root.sortByProperty(options);
   }
 
+  /**
+   * Sort nodes list by title or custom criteria.
+   * @since 0.14.0
+   */
+  sort(options: SortOptions): void {
+    this.root.sort(options);
+  }
+
   /** Convert tree to an array of plain objects.
    *
    * @param callback is called for every node, in order to allow
@@ -2149,11 +2440,11 @@ export class Wunderbaum {
     return modified;
   }
 
-  protected _insertIcon(icon: string, elem: HTMLElement) {
-    const iconElem = document.createElement("i");
-    iconElem.className = icon;
-    elem.appendChild(iconElem);
-  }
+  // protected _insertIcon(icon: string, elem: HTMLElement) {
+  //   const iconElem = document.createElement("i");
+  //   iconElem.className = icon;
+  //   elem.appendChild(iconElem);
+  // }
 
   /** Create/update header markup from `this.columns` definition.
    * @internal
@@ -2257,6 +2548,109 @@ export class Wunderbaum {
     }
   }
 
+  /** @internal */
+  public _createNodeIcon(
+    node: WunderbaumNode,
+    showLoading: boolean,
+    showBadge: boolean
+  ): HTMLElement | null {
+    const iconMap = this.iconMap;
+    let iconElem;
+    let icon = node.getOption("icon");
+    if (node._errorInfo) {
+      icon = iconMap.error;
+    } else if (node._isLoading && showLoading) {
+      // Status nodes, or nodes without expander (< minExpandLevel) should
+      // display the 'loading' status with the i.wb-icon span
+      icon = iconMap.loading;
+    }
+    if (icon === false) {
+      return null; // explicitly disabled: don't try default icons
+    }
+    if (typeof icon === "string") {
+      // Callback returned an icon definition
+      // icon = icon.trim()
+    } else if (node.statusNodeType) {
+      icon = (<any>iconMap)[node.statusNodeType];
+    } else if (node.expanded) {
+      icon = iconMap.folderOpen;
+    } else if (node.children) {
+      icon = iconMap.folder;
+    } else if (node.lazy) {
+      icon = iconMap.folderLazy;
+    } else {
+      icon = iconMap.doc;
+    }
+
+    if (!icon) {
+      iconElem = document.createElement("i");
+      iconElem.className = "wb-icon";
+    } else if (TEST_HTML.test(icon)) {
+      iconElem = util.elemFromHtml(icon);
+    } else if (TEST_FILE_PATH.test(icon)) {
+      iconElem = util.elemFromHtml(
+        `<i class="wb-icon" style="background-image: url('${icon}');">`
+      );
+    } else {
+      // Class name
+      iconElem = document.createElement("i");
+      iconElem.className = "wb-icon " + icon;
+    }
+
+    // Event handler `tree.iconBadge` can return a badge text or HTMLSpanElement
+    const cbRes =
+      showBadge && node._callEvent("iconBadge", { iconSpan: iconElem });
+
+    let badge = null;
+    if (cbRes != null && cbRes !== false) {
+      let classes = "";
+      let tooltip = "";
+      if (util.isPlainObject(cbRes)) {
+        badge = "" + cbRes.badge;
+        classes = cbRes.badgeClass ? " " + cbRes.badgeClass : "";
+        tooltip = cbRes.badgeTooltip ? ` title="${cbRes.badgeTooltip}"` : "";
+      } else if (typeof cbRes === "number") {
+        badge = "" + cbRes;
+      } else {
+        badge = cbRes; // string or HTMLSpanElement
+      }
+      if (typeof badge === "string") {
+        badge = util.elemFromHtml(
+          `<span class="wb-badge${classes}"${tooltip}>${util.escapeHtml(
+            badge
+          )}</span>`
+        );
+      }
+      if (badge) {
+        iconElem.append(<HTMLSpanElement>badge);
+      }
+    }
+    return iconElem;
+  }
+
+  private _updateTopBreadcrumb() {
+    const breadcrumb = this.breadcrumb!;
+    const topmost = this.getTopmostVpNode(true);
+    const parentList = topmost?.getParentList(false, false);
+    if (parentList?.length) {
+      breadcrumb.innerHTML = "";
+      for (const n of topmost.getParentList(false, false)) {
+        const icon = this._createNodeIcon(n, false, false);
+        if (icon) {
+          breadcrumb.append(icon, " ");
+        }
+        const part = document.createElement("a");
+        part.textContent = n.title;
+        part.href = "#";
+        part.classList.add("wb-breadcrumb");
+        part.dataset.key = n.key;
+        breadcrumb.append(part, this.options.strings.breadcrumbDelimiter);
+      }
+    } else {
+      breadcrumb.innerHTML = "&nbsp;";
+    }
+  }
+
   /**
    * This is the actual update method, which is wrapped inside a throttle method.
    * It calls `updateColumns()` and `_updateRows()`.
@@ -2321,14 +2715,8 @@ export class Wunderbaum {
       // console.profileEnd(`_updateViewportImmediately()`)
     }
 
-    if (this.options.connectTopBreadcrumb) {
-      util.assert(
-        this.options.connectTopBreadcrumb.textContent != null,
-        `Invalid 'connectTopBreadcrumb' option (input element expected).`
-      );
-      let path = this.getTopmostVpNode(true)?.getPath(false, "title", " > ");
-      path = path ? path + " >" : "";
-      this.options.connectTopBreadcrumb.textContent = path;
+    if (this.breadcrumb) {
+      this._updateTopBreadcrumb();
     }
     this._callEvent("update");
   }
@@ -2380,7 +2768,7 @@ export class Wunderbaum {
     options = Object.assign({ newNodesOnly: false }, options);
     const newNodesOnly = !!options.newNodesOnly;
 
-    const rowHeight = this.options.rowHeightPx!;
+    const rowHeight = this.options.rowHeightPx;
     const vpHeight = this.element.clientHeight;
     const prefetch = RENDER_MAX_PREFETCH;
     // const grace_prefetch = RENDER_MAX_PREFETCH - RENDER_MIN_PREFETCH;
@@ -2460,7 +2848,8 @@ export class Wunderbaum {
 
   /**
    * Call `callback(node)` for all nodes in hierarchical order (depth-first, pre-order).
-   * @see {@link IterableIterator<WunderbaumNode>}, {@link WunderbaumNode.visit}.
+   * @see `wb_node.WunderbaumNode.IterableIterator<WunderbaumNode>`
+   * @see {@link WunderbaumNode.visit}.
    *
    * @param {function} callback the callback function.
    *     Return false to stop iteration, return "skip" to skip this node and
@@ -2632,12 +3021,77 @@ export class Wunderbaum {
    *
    * Previous data is cleared. Note that also column- and type defintions may
    * be passed with the `source` object.
+   * @see {@link Wunderbaum.reload} for a shortcut to reload the last ajax request
+   * and restore the previous state.
    */
-  load(source: SourceType) {
+  async load(source: SourceType) {
     this.clear();
+    this._initialSource = source;
     return this.root.load(source);
   }
 
+  /** Reload the tree and optionally restore state.
+   * Source defaults to last ajax url if any.
+   * Restoring the active node requires stable keys
+   * @see {@link WunderbaumOptions.autoKeys}
+   * @see {@link Wunderbaum.load}
+   * @experimental
+   */
+  async reload(options: ReloadOptions = {}) {
+    const { source = this._initialSource, reactivate = true } = options;
+    if (!source) {
+      this.logWarn("No previous ajax source to reload.");
+      return;
+    }
+    if (!reactivate) {
+      return this.load(source);
+    }
+    const state = this.getState();
+    await this.load(source);
+    return this.setState(state);
+  }
+
+  /**
+   * Make sure that all nodes in the given keyList are accessible.
+   * This may include loading lazy parent nodes.
+   * Recursively load (and optionally expand) all requested node paths.
+   */
+  protected async _loadLazyNodes(
+    keyList: string[],
+    options: LoadLazyNodesOptions = {}
+  ) {
+    const { expand = true } = options;
+    const keySet = new Set<string>(keyList);
+
+    // Make sure that all parent nodes are loaded (and expand if requested)
+    while (keySet.size > 0) {
+      const pendingNodes: Promise<void>[] = [];
+      const curSet = new Set(keySet);
+      for (const key of curSet) {
+        const node = this.findKey(key);
+        if (!node) {
+          continue; // key not yet found (need to load lazy parent?)
+        }
+        keySet.delete(key);
+        if (expand) {
+          pendingNodes.push(node.setExpanded(true));
+        } else if (node.isUnloaded()) {
+          pendingNodes.push(node.loadLazy());
+        }
+        if (node._rowElem) {
+          node._render(); // show spinner even is update is suppressed
+        }
+      }
+      if (pendingNodes.length === 0) {
+        // will not load any more nodes, so if if there are still keys
+        // left in the set, we will never find them
+        this.logWarn(`Could not expand ${keySet.size} nodes:`, keySet);
+        break;
+      }
+      await Promise.allSettled(pendingNodes);
+    }
+  }
+
   /**
    * Disable render requests during operations that would trigger many updates.
    *
@@ -2705,10 +3159,7 @@ export class Wunderbaum {
     filter: string | RegExp | NodeFilterCallback,
     options: FilterNodesOptions
   ): number {
-    return (this.extensions.filter as FilterExtension).filterNodes(
-      filter,
-      options
-    );
+    return this.extensions.filter.filterNodes(filter, options);
   }
 
   /**
@@ -2717,7 +3168,7 @@ export class Wunderbaum {
    * @since 0.9.0
    */
   countMatches(): number {
-    return (this.extensions.filter as FilterExtension).countMatches();
+    return this.extensions.filter.countMatches();
   }
 
   /**
@@ -2728,17 +3179,14 @@ export class Wunderbaum {
     filter: string | NodeFilterCallback,
     options: FilterNodesOptions
   ) {
-    return (this.extensions.filter as FilterExtension).filterBranches(
-      filter,
-      options
-    );
+    return this.extensions.filter.filterBranches(filter, options);
   }
 
   /**
    * Reset the filter.
    */
   clearFilter() {
-    return (this.extensions.filter as FilterExtension).clearFilter();
+    return this.extensions.filter.clearFilter();
   }
   /**
    * Return true if a filter is currently applied.
@@ -2750,6 +3198,6 @@ export class Wunderbaum {
    * Re-apply current filter.
    */
   updateFilter() {
-    return (this.extensions.filter as FilterExtension).updateFilter();
+    return this.extensions.filter.updateFilter();
   }
 }