wunderbaum 0.7.0 → 0.8.1

package/src/wunderbaum.ts

@@ -51,6 +51,7 @@ import {
   DynamicIconOption,
   DynamicStringOption,
   DynamicBoolOption,
+  SetColumnOptions,
 } from "./types";
 import {
   DEFAULT_DEBUGLEVEL,
@@ -64,6 +65,7 @@ import { WunderbaumNode } from "./wb_node";
 import { Deferred } from "./deferred";
 import { EditExtension } from "./wb_ext_edit";
 import { WunderbaumOptions } from "./wb_options";
+import { DebouncedFunction } from "./debounce";
 
 class WbSystemRoot extends WunderbaumNode {
   constructor(tree: Wunderbaum) {
@@ -80,7 +82,7 @@ class WbSystemRoot extends WunderbaumNode {
 /**
  * A persistent plain object or array.
  *
- * See also [[WunderbaumOptions]].
+ * See also {@link WunderbaumOptions}.
  */
 export class Wunderbaum {
   protected static sequence = 0;
@@ -104,7 +106,7 @@ export class Wunderbaum {
   /** Contains additional data that was sent as response to an Ajax source load request. */
   public readonly data: { [key: string]: any } = {};
 
-  protected readonly _updateViewportThrottled: (...args: any) => void;
+  protected readonly _updateViewportThrottled: DebouncedFunction<() => void>;
   protected extensionList: WunderbaumExtension<any>[] = [];
   protected extensions: ExtensionsDict = {};
 
@@ -117,10 +119,23 @@ export class Wunderbaum {
   protected _disableUpdateCount = 0;
   protected _disableUpdateIgnoreCount = 0;
 
-  /** Currently active node if any. */
-  public activeNode: WunderbaumNode | null = null;
-  /** Current node hat has keyboard focus if any. */
-  public focusNode: WunderbaumNode | null = null;
+  protected _activeNode: WunderbaumNode | null = null;
+  protected _focusNode: WunderbaumNode | null = null;
+
+  /** Currently active node if any.
+   * Use @link {WunderbaumNode.setActive|setActive} to modify.
+   */
+  public get activeNode() {
+    // Check for deleted node, i.e. node.tree === null
+    return this._activeNode?.tree ? this._activeNode : null;
+  }
+  /** Current node hat has keyboard focus if any.
+   * Use @link {WunderbaumNode.setFocus|setFocus()} to modify.
+   */
+  public get focusNode() {
+    // Check for deleted node, i.e. node.tree === null
+    return this._focusNode?.tree ? this._focusNode : null;
+  }
 
   /** Shared properties, referenced by `node.type`. */
   public types: NodeTypeDefinitionMap = {};
@@ -153,7 +168,7 @@ export class Wunderbaum {
   public filterMode: FilterModeType = null;
 
   // --- KEYNAV ---
-  /** @internal Use `setColumn()`/`getActiveColElem()`*/
+  /** @internal Use `setColumn()`/`getActiveColElem()` to access. */
   public activeColIdx = 0;
   /** @internal */
   public _cellNavMode = false;
@@ -366,6 +381,7 @@ export class Wunderbaum {
           } else {
             this.setNavigationOption(opts.navigationModeOption);
           }
+          this.update(ChangeType.structure, { immediate: true });
           readyDeferred.resolve();
         })
         .catch((error) => {
@@ -426,7 +442,7 @@ export class Wunderbaum {
           node.isActive() &&
           (!slowClickDelay || Date.now() - this.lastClickTime < slowClickDelay)
         ) {
-          this._callMethod("edit.startEditTitle", node);
+          node.startEditTitle();
         }
 
         if (info.colIdx >= 0) {
@@ -482,7 +498,7 @@ export class Wunderbaum {
 
       this._callEvent("focus", { flag: flag, event: e });
 
-      if (flag && this.isRowNav() && !this.isEditing()) {
+      if (flag && this.isRowNav() && !this.isEditingTitle()) {
         if ((opts.navigationModeOption as NavModeEnum) === NavModeEnum.row) {
           targetNode?.setActive();
         } else {
@@ -506,7 +522,7 @@ export class Wunderbaum {
    * getTree(1);        // Get second Wunderbaum instance on page
    * getTree(event);    // Get tree for this mouse- or keyboard event
    * getTree("foo");    // Get tree for this `tree.options.id`
-   * getTree("#tree");  // Get tree for this matching element
+   * getTree("#tree");  // Get tree for first matching element selector
    * ```
    */
   public static getTree(
@@ -614,37 +630,37 @@ export class Wunderbaum {
   /** Add node to tree's bookkeeping data structures. */
   _registerNode(node: WunderbaumNode): void {
     const key = node.key;
-    util.assert(
-      key != null && !this.keyMap.has(key),
-      `Missing or duplicate key: '${key}'.`
-    );
+    util.assert(key != null, `Missing key: '${node}'.`);
+    util.assert(!this.keyMap.has(key), `Duplicate key: '${key}': ${node}.`);
     this.keyMap.set(key, node);
     const rk = node.refKey;
-    if (rk) {
+    if (rk != null) {
       const rks = this.refKeyMap.get(rk); // Set of nodes with this refKey
       if (rks) {
         rks.add(node);
       } else {
-        this.refKeyMap.set(rk, new Set());
+        this.refKeyMap.set(rk, new Set([node]));
       }
     }
   }
 
   /** Remove node from tree's bookkeeping data structures. */
   _unregisterNode(node: WunderbaumNode): void {
+    // Remove refKey reference from map (if any)
     const rk = node.refKey;
-    if (rk) {
+    if (rk != null) {
       const rks = this.refKeyMap.get(rk);
       if (rks && rks.delete(node) && !rks.size) {
         // We just removed the last element
         this.refKeyMap.delete(rk);
       }
     }
-    // mark as disposed
+    // Remove key reference from map
+    this.keyMap.delete(node.key);
+    // Mark as disposed
     (node.tree as any) = null;
     (node.parent as any) = null;
-    // node.title = "DISPOSED: " + node.title
-    // this.viewNodes.delete(node);
+    // Remove HTML markup
     node.removeMarkup();
   }
 
@@ -894,7 +910,7 @@ export class Wunderbaum {
         this._callMethod("edit.createNode", "after");
         break;
       case "rename":
-        this._callMethod("edit.startEditTitle");
+        node.startEditTitle();
         break;
       // Simple clipboard simulation:
       // case "cut":
@@ -942,10 +958,9 @@ export class Wunderbaum {
     this.root.children = null;
     this.keyMap.clear();
     this.refKeyMap.clear();
-    // this.viewNodes.clear();
     this.treeRowCount = 0;
-    this.activeNode = null;
-    this.focusNode = null;
+    this._activeNode = null;
+    this._focusNode = null;
 
     // this.types = {};
     // this. columns =[];
@@ -1159,15 +1174,33 @@ export class Wunderbaum {
   /**
    * Find all nodes that match condition.
    *
+   * @param match title string to search for, or a
+   *     callback function that returns `true` if a node is matched.
    * @see {@link WunderbaumNode.findAll}
    */
   findAll(match: string | RegExp | MatcherCallback) {
     return this.root.findAll(match);
   }
 
+  /**
+   * Find all nodes with a given _refKey_ (aka a list of clones).
+   *
+   * @param refKey a `node.refKey` value to search for.
+   * @returns an array of matching nodes with at least two element or `[]`
+   * if nothing found.
+   *
+   * @see {@link WunderbaumNode.getCloneList}
+   */
+  findByRefKey(refKey: string): WunderbaumNode[] {
+    const clones = this.refKeyMap.get(refKey);
+    return clones ? Array.from(clones) : [];
+  }
+
   /**
    * Find first node that matches condition.
    *
+   * @param match title string to search for, or a
+   *     callback function that returns `true` if a node is matched.
    * @see {@link WunderbaumNode.findFirst}
    */
   findFirst(match: string | RegExp | MatcherCallback) {
@@ -1177,8 +1210,6 @@ export class Wunderbaum {
   /**
    * Find first node that matches condition.
    *
-   * @param match title string to search for, or a
-   *     callback function that returns `true` if a node is matched.
    * @see {@link WunderbaumNode.findFirst}
    *
    */
@@ -1189,6 +1220,7 @@ export class Wunderbaum {
   /**
    * Find the next visible node that starts with `match`, starting at `startNode`
    * and wrap-around at the end.
+   * Used by quicksearch and keyboard navigation.
    */
   findNextNode(
     match: string | MatcherCallback,
@@ -1371,7 +1403,13 @@ export class Wunderbaum {
   }
 
   /**
-   * Return the currently active node or null.
+   * Return the currently active node or null (alias for `tree.activeNode`).
+   * Alias for {@link Wunderbaum.activeNode}.
+   *
+   * @see {@link WunderbaumNode.setActive}
+   * @see {@link WunderbaumNode.isActive}
+   * @see {@link Wunderbaum.activeNode}
+   * @see {@link Wunderbaum.focusNode}
    */
   getActiveNode() {
     return this.activeNode;
@@ -1385,7 +1423,12 @@ export class Wunderbaum {
   }
 
   /**
-   * Return the currently active node or null.
+   * Return the node that currently has keyboard focus or null.
+   * Alias for {@link Wunderbaum.focusNode}.
+   * @see {@link WunderbaumNode.setFocus}
+   * @see {@link WunderbaumNode.hasFocus}
+   * @see {@link Wunderbaum.activeNode}
+   * @see {@link Wunderbaum.focusNode}
    */
   getFocusNode() {
     return this.focusNode;
@@ -1462,8 +1505,22 @@ export class Wunderbaum {
     return `Wunderbaum<'${this.id}'>`;
   }
 
-  /** Return true if any node is currently in edit-title mode. */
+  /** Return true if any node title or grid cell is currently beeing edited.
+   *
+   * See also {@link Wunderbaum.isEditingTitle}.
+   */
   isEditing(): boolean {
+    const focusElem = this.nodeListElement.querySelector(
+      "input:focus,select:focus"
+    );
+    return !!focusElem;
+  }
+
+  /** Return true if any node is currently in edit-title mode.
+   *
+   * See also {@link WunderbaumNode.isEditingTitle} and {@link Wunderbaum.isEditing}.
+   */
+  isEditingTitle(): boolean {
     return this._callMethod("edit.isEditingTitle");
   }
 
@@ -1483,26 +1540,33 @@ export class Wunderbaum {
     return res;
   }
 
-  /** Alias for {@link Wunderbaum.logDebug}.
-   * @alias Wunderbaum.logDebug
+  /** Write to `console.log` with tree name as prefix if opts.debugLevel >= 4.
+   * @see {@link Wunderbaum.logDebug}
    */
-  log = this.logDebug;
+  log(...args: any[]) {
+    if (this.options.debugLevel! >= 4) {
+      console.log(this.toString(), ...args); // eslint-disable-line no-console
+    }
+  }
 
-  /** Log to console if opts.debugLevel >= 4 */
+  /** 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}
+   */
   logDebug(...args: any[]) {
     if (this.options.debugLevel! >= 4) {
-      console.log(this.toString(), ...args); // eslint-disable-line no-console
+      console.debug(this.toString(), ...args); // eslint-disable-line no-console
     }
   }
 
-  /** Log error to console. */
+  /** Write to `console.error` with tree name as prefix. */
   logError(...args: any[]) {
     if (this.options.debugLevel! >= 1) {
       console.error(this.toString(), ...args); // eslint-disable-line no-console
     }
   }
 
-  /** Log to console if opts.debugLevel >= 3 */
+  /** Write to `console.info`  with tree name as prefix if opts.debugLevel >= 3. */
   logInfo(...args: any[]) {
     if (this.options.debugLevel! >= 3) {
       console.info(this.toString(), ...args); // eslint-disable-line no-console
@@ -1524,7 +1588,7 @@ export class Wunderbaum {
     }
   }
 
-  /** Log to console if opts.debugLevel >= 2 */
+  /** Write to `console.warn` with tree name as prefix with if opts.debugLevel >= 2. */
   logWarn(...args: any[]) {
     if (this.options.debugLevel! >= 2) {
       console.warn(this.toString(), ...args); // eslint-disable-line no-console
@@ -1622,11 +1686,24 @@ export class Wunderbaum {
   /**
    * Set column #colIdx to 'active'.
    *
-   * This higlights the column header and -cells by adding the `wb-active` class.
+   * This higlights the column header and -cells by adding the `wb-active`
+   * class to all grid cells of the active column. <br>
    * Available in cell-nav mode only.
+   *
+   * If _options.edit_ is true, the embedded input element is focused, or if
+   * colIdx is 0, the node title is put into edit mode.
    */
-  setColumn(colIdx: number) {
-    util.assert(this.isCellNav(), "Exected cellNav mode");
+  setColumn(colIdx: number | string, options?: SetColumnOptions) {
+    const edit = options?.edit;
+    const scroll = options?.scrollIntoView !== false;
+
+    util.assert(this.isCellNav(), "Expected cellNav mode");
+
+    if (typeof colIdx === "string") {
+      const cid = colIdx;
+      colIdx = this.columns.findIndex((c) => c.id === colIdx);
+      util.assert(colIdx >= 0, `Invalid colId: ${cid}`);
+    }
     util.assert(
       0 <= colIdx && colIdx < this.columns.length,
       `Invalid colIdx: ${colIdx}`
@@ -1652,18 +1729,34 @@ export class Wunderbaum {
         (colDiv as HTMLElement).classList.toggle("wb-active", i++ === colIdx);
       }
     }
-    // Vertical scroll into view
-    // if (this.options.fixedCol) {
-    this.scrollToHorz();
-    // }
+    // Horizontically scroll into view
+    if (scroll || edit) {
+      this.scrollToHorz();
+    }
+
+    if (edit && this.activeNode) {
+      // this.activeNode.setFocus(); // Blur prev. input if any
+      if (colIdx === 0) {
+        this.activeNode.startEditTitle();
+      } else {
+        this.getActiveColElem()
+          ?.querySelector<HTMLInputElement>("input,select")
+          ?.focus();
+      }
+    }
+  }
+
+  /* Set or remove keyboard focus to the tree container. @internal */
+  _setActiveNode(node: WunderbaumNode | null) {
+    this._activeNode = node;
   }
 
-  /** Set or remove keybaord focus to the tree container. */
+  /** Set or remove keyboard focus to the tree container. */
   setActiveNode(key: string, flag: boolean = true, options?: SetActiveOptions) {
     this.findKey(key)?.setActive(flag, options);
   }
 
-  /** Set or remove keybaord focus to the tree container. */
+  /** Set or remove keyboard focus to the tree container. */
   setFocus(flag = true) {
     if (flag) {
       this.element.focus();
@@ -1672,10 +1765,16 @@ export class Wunderbaum {
     }
   }
 
+  /* Set or remove keyboard focus to the tree container. @internal */
+  _setFocusNode(node: WunderbaumNode | null) {
+    this._focusNode = node;
+  }
+
   /**
    * Schedule an update request to reflect a tree change.
    * The render operation is async and debounced unless the `immediate` option
    * is set.
+   *
    * Use {@link WunderbaumNode.update()} if only a single node has changed,
    * or {@link WunderbaumNode._render()}) to pass special options.
    */
@@ -1694,26 +1793,27 @@ export class Wunderbaum {
 
   update(
     change: ChangeType,
-    node?: WunderbaumNode | any,
+    node?: WunderbaumNode | UpdateOptions,
     options?: UpdateOptions
   ): void {
-    if (this._disableUpdateCount) {
-      // Assuming that we redraw all when enableUpdate() is re-enabled.
-      // this.log(
-      //   `IGNORED update(${change}) node=${node} (disable level ${this._disableUpdateCount})`
-      // );
-      this._disableUpdateIgnoreCount++;
-      return;
-    }
     // this.log(`update(${change}) node=${node}`);
     if (!(node instanceof WunderbaumNode)) {
       options = node;
-      node = null;
+      node = undefined;
     }
+
     const immediate = !!util.getOption(options, "immediate");
     const RF = RenderFlag;
     const pending = this.pendingChangeTypes;
 
+    if (this._disableUpdateCount) {
+      // Assuming that we redraw all when enableUpdate() is re-enabled.
+      // this.log(
+      //   `IGNORED update(${change}) node=${node} (disable level ${this._disableUpdateCount})`
+      // );
+      this._disableUpdateIgnoreCount++;
+      return;
+    }
     switch (change) {
       case ChangeType.any:
       case ChangeType.colStructure:
@@ -1739,8 +1839,8 @@ export class Wunderbaum {
         util.assert(node, `Option '${change}' requires a node.`);
         // Single nodes are immediately updated if already inside the viewport
         // (otherwise we can ignore)
-        if (node._rowElem) {
-          node._render({ change: change });
+        if ((<WunderbaumNode>node)!._rowElem) {
+          (<WunderbaumNode>node)!._render({ change: change });
         }
         break;
       default:
@@ -2069,12 +2169,15 @@ export class Wunderbaum {
   protected _updateViewportImmediately() {
     if (this._disableUpdateCount) {
       this.log(
-        `_updateViewportImmediately() IGNORED (disable level: ${this._disableUpdateCount})`
+        `_updateViewportImmediately() IGNORED (disable level: ${this._disableUpdateCount}).`
       );
       this._disableUpdateIgnoreCount++;
       return;
     }
-
+    if (this._updateViewportThrottled.pending()) {
+      // this.logWarn(`_updateViewportImmediately() cancel pending timer.`);
+      this._updateViewportThrottled.cancel();
+    }
     // Shorten container height to avoid v-scrollbar
     const FIX_ADJUST_HEIGHT = 1;
     const RF = RenderFlag;
@@ -2189,9 +2292,6 @@ export class Wunderbaum {
     let endIdx = Math.max(0, (ofs + vp_height) / row_height + prefetch);
     endIdx = Math.ceil(endIdx);
 
-    // const obsoleteViewNodes = this.viewNodes;
-    // this.viewNodes = new Set();
-    // const viewNodes = this.viewNodes;
     // this.debug("render", opts);
     const obsoleteNodes = new Set<WunderbaumNode>();
     this.nodeListElement.childNodes.forEach((elem) => {
@@ -2485,7 +2585,7 @@ export class Wunderbaum {
    * FILTER
    * -------------------------------------------------------------------------*/
   /**
-   * [ext-filter] Dim or hide nodes.
+   * Dim or hide nodes.
    */
   filterNodes(
     filter: string | NodeFilterCallback,
@@ -2498,7 +2598,7 @@ export class Wunderbaum {
   }
 
   /**
-   * [ext-filter] Dim or hide whole branches.
+   * Dim or hide whole branches.
    */
   filterBranches(
     filter: string | NodeFilterCallback,
@@ -2511,25 +2611,19 @@ export class Wunderbaum {
   }
 
   /**
-   * [ext-filter] Reset the filter.
-   *
-   * @requires [[FilterExtension]]
+   * Reset the filter.
    */
   clearFilter() {
     return (this.extensions.filter as FilterExtension).clearFilter();
   }
   /**
-   * [ext-filter] Return true if a filter is currently applied.
-   *
-   * @requires [[FilterExtension]]
+   * Return true if a filter is currently applied.
    */
   isFilterActive() {
     return !!this.filterMode;
   }
   /**
-   * [ext-filter] Re-apply current filter.
-   *
-   * @requires [[FilterExtension]]
+   * Re-apply current filter.
    */
   updateFilter() {
     return (this.extensions.filter as FilterExtension).updateFilter();