wunderbaum 0.7.0 → 0.8.1

package/src/wb_ext_keynav.ts

@@ -4,7 +4,7 @@
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
-import { NavModeEnum } from "./types";
+import { KeynavOptionsType, NavModeEnum } from "./types";
 import { eventToString } from "./util";
 import { Wunderbaum } from "./wunderbaum";
 import { WunderbaumNode } from "./wb_node";
@@ -12,7 +12,7 @@ import { WunderbaumExtension } from "./wb_extension_base";
 
 const QUICKSEARCH_DELAY = 500;
 
-export class KeynavExtension extends WunderbaumExtension<any> {
+export class KeynavExtension extends WunderbaumExtension<KeynavOptionsType> {
   constructor(tree: Wunderbaum) {
     super(tree, "keynav", {});
   }
@@ -32,6 +32,14 @@ export class KeynavExtension extends WunderbaumExtension<any> {
     return input;
   }
 
+  // /* Return the current cell's embedded input that has keyboard focus. */
+  // protected _getFocusedInputElem(): HTMLInputElement | null {
+  //   const ace = this.tree
+  //     .getActiveColElem()
+  //     ?.querySelector<HTMLInputElement>("input:focus,select:focus");
+  //   return ace || null;
+  // }
+
   /* Return true if the current cell's embedded input has keyboard focus. */
   protected _isCurInputFocused(): boolean {
     const ace = this.tree
@@ -48,7 +56,6 @@ export class KeynavExtension extends WunderbaumExtension<any> {
     const curInput = this._getEmbeddedInputElem(event.target);
     const inputHasFocus = curInput && this._isCurInputFocused();
     const navModeOption = opts.navigationModeOption as NavModeEnum;
-    // isCellEditMode = tree.navMode === NavigationMode.cellEdit;
 
     let focusNode,
       eventName = eventToString(event),
@@ -215,23 +222,28 @@ export class KeynavExtension extends WunderbaumExtension<any> {
       // // Standard navigation (cell mode)
       // if (isCellEditMode && INPUT_BREAKOUT_KEYS.has(eventName)) {
       // }
-      const ENTER_EDITS = false;
-      const curInput = this._getEmbeddedInputElem(null);
+      // const curInput = this._getEmbeddedInputElem(null);
       const curInputType = curInput ? curInput.type || curInput.tagName : "";
-      const inputHasFocus = curInput && this._isCurInputFocused();
+      // const inputHasFocus = curInput && this._isCurInputFocused();
       const inputCanFocus = curInput && curInputType !== "checkbox";
 
       if (inputHasFocus) {
         if (eventName === "Escape") {
-          // Discard changes
+          node.logDebug(`Reset focused input on Escape`);
+          // Discard changes and reset input validation state
+          curInput.setCustomValidity("");
           node._render();
           // Keep cell-nav mode
-          node.logDebug(`Reset focused input`);
           tree.setFocus();
           tree.setColumn(tree.activeColIdx);
           return;
           // } else if (!INPUT_BREAKOUT_KEYS.has(eventName)) {
         } else if (eventName !== "Enter") {
+          if (curInput && curInput.checkValidity && !curInput.checkValidity()) {
+            // Invalid input: ignore all keys except Enter and Escape
+            node.logDebug(`Ignored ${eventName} inside invalid input`);
+            return false;
+          }
           // Let current `<input>` handle it
           node.logDebug(`Ignored ${eventName} inside focused input`);
           return;
@@ -245,9 +257,10 @@ export class KeynavExtension extends WunderbaumExtension<any> {
       } else if (curInput) {
         // On a cell that has an embedded, unfocused <input>
         if (eventName.length === 1 && inputCanFocus) {
+          // Typing a single char
           curInput.focus();
           curInput.value = "";
-          node.logDebug(`Focus imput: ${eventName}`);
+          node.logDebug(`Focus input: ${eventName}`);
           return false;
         }
       }
@@ -257,8 +270,6 @@ export class KeynavExtension extends WunderbaumExtension<any> {
       } else if (eventName === "Shift+Tab") {
         eventName = tree.activeColIdx > 0 ? "ArrowLeft" : "";
         handled = true;
-      } else if (ENTER_EDITS && eventName === "Enter") {
-        eventName = "F2";
       }
 
       switch (eventName) {

package/src/wb_ext_logger.ts

@@ -4,11 +4,12 @@
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
+import { LoggerOptionsType } from "./types";
 import { overrideMethod } from "./util";
 import { WunderbaumExtension } from "./wb_extension_base";
 import { Wunderbaum } from "./wunderbaum";
 
-export class LoggerExtension extends WunderbaumExtension<any> {
+export class LoggerExtension extends WunderbaumExtension<LoggerOptionsType> {
   readonly prefix: string;
   protected ignoreEvents = new Set<string>([
     "iconBadge",

package/src/wb_node.ts

@@ -420,6 +420,11 @@ export class WunderbaumNode {
     }
   }
 
+  /** Start editing this node's title. */
+  startEditTitle(): void {
+    this.tree._callMethod("edit.startEditTitle", this);
+  }
+
   /** Call `setExpanded()` on all descendant nodes. */
   async expandAll(flag: boolean = true, options?: ExpandAllOptions) {
     const tree = this.tree;
@@ -648,6 +653,22 @@ export class WunderbaumNode {
     const colElems = this._rowElem?.querySelectorAll("span.wb-col");
     return colElems ? (colElems[colIdx] as HTMLSpanElement) : null;
   }
+  /**
+   * Return all nodes with the same refKey.
+   *
+   * @param includeSelf Include this node itself.
+   * @see {@link Wunderbaum.findByRefKey}
+   */
+  getCloneList(includeSelf = false): WunderbaumNode[] {
+    if (!this.refKey) {
+      return [];
+    }
+    const clones = this.tree.findByRefKey(this.refKey);
+    if (includeSelf) {
+      return clones;
+    }
+    return [...clones].filter((n) => n !== this);
+  }
 
   /** Return the first child node or null.
    * @returns {WunderbaumNode | null}
@@ -771,19 +792,24 @@ export class WunderbaumNode {
   }
 
   /** Return true if this node is a direct or indirect parent of `other`.
-   * (See also [[isParentOf]].)
+   * @see {@link WunderbaumNode.isParentOf}
    */
   isAncestorOf(other: WunderbaumNode) {
     return other && other.isDescendantOf(this);
   }
 
   /** Return true if this node is a **direct** subnode of `other`.
-   * (See also [[isDescendantOf]].)
+   * @see {@link WunderbaumNode.isDescendantOf}
    */
   isChildOf(other: WunderbaumNode) {
     return other && this.parent === other;
   }
 
+  /** Return true if this node's refKey is used by at least one other node.
+   */
+  isClone() {
+    return !!this.refKey && this.tree.findByRefKey(this.refKey).length > 1;
+  }
   /** Return true if this node's title spans all columns, i.e. the node has no
    * grid cells.
    */
@@ -792,7 +818,7 @@ export class WunderbaumNode {
   }
 
   /** Return true if this node is a direct or indirect subnode of `other`.
-   * (See also [[isChildOf]].)
+   * @see {@link WunderbaumNode.isChildOf}
    */
   isDescendantOf(other: WunderbaumNode) {
     if (!other || other.tree !== this.tree) {
@@ -829,8 +855,11 @@ export class WunderbaumNode {
     return true;
   }
 
-  /** Return true if this node is currently in edit-title mode. */
-  isEditing(): boolean {
+  /** Return true if _this_ node is currently in edit-title mode.
+   *
+   * See {@link Wunderbaum.startEditTitle} to check if any node is currently edited.
+   */
+  isEditingTitle(): boolean {
     return this.tree._callMethod("edit.isEditingTitle", this);
   }
 
@@ -872,7 +901,7 @@ export class WunderbaumNode {
   }
 
   /** Return true if this node is a **direct** parent of `other`.
-   * (See also [[isAncestorOf]].)
+   * @see {@link WunderbaumNode.isAncestorOf}
    */
   isParentOf(other: WunderbaumNode) {
     return other && other.parent === this;
@@ -899,7 +928,7 @@ export class WunderbaumNode {
   }
 
   /** Return true if this node is the (invisible) system root node.
-   * (See also [[isTopLevel()]].)
+   * @see {@link WunderbaumNode.isTopLevel}
    */
   isRootNode(): boolean {
     return this.tree.root === this;
@@ -1152,14 +1181,22 @@ export class WunderbaumNode {
     }
   }
 
-  /**Load content of a lazy node. */
-  async loadLazy(forceReload = false) {
+  /**
+   * Load content of a lazy node.
+   * If the node is already loaded, nothing happens.
+   * @param [forceReload=false] If true, reload even if already loaded.
+   */
+  async loadLazy(forceReload: boolean = false) {
     const wasExpanded = this.expanded;
 
     util.assert(this.lazy, "load() requires a lazy node");
-    // _assert( forceReload || this.isUndefined(), "Pass forceReload=true to re-load a lazy node" );
+
     if (!forceReload && !this.isUnloaded()) {
-      return;
+      return; // Already loaded: nothing to do
+    }
+    if (this.isLoading()) {
+      this.logWarn("loadLazy() called while already loading: ignored.");
+      return; // Already loading: prevent duplicate requests
     }
     if (this.isLoaded()) {
       this.resetLazy(); // Also collapses if currently expanded
@@ -1180,7 +1217,7 @@ export class WunderbaumNode {
 
       await this.load(source);
 
-      this.setStatus(NodeStatusType.ok);
+      this.setStatus(NodeStatusType.ok); // Also resets `this._isLoading`
 
       if (wasExpanded) {
         this.expanded = true;
@@ -1191,38 +1228,46 @@ export class WunderbaumNode {
     } catch (e) {
       this.logError("Error during loadLazy()", e);
       this._callEvent("error", { error: e });
+      // Also resets `this._isLoading`:
       this.setStatus(NodeStatusType.error, { message: "" + e });
     }
     return;
   }
 
-  /** Alias for `logDebug` */
+  /** Write to `console.log` with node name as prefix if opts.debugLevel >= 4.
+   * @see {@link WunderbaumNode.logDebug}
+   */
   log(...args: any[]) {
-    this.logDebug(...args);
+    if (this.tree.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 node name as prefix if opts.debugLevel >= 4
+   * and browser console level includes debug/verbose messages.
+   * @see {@link WunderbaumNode.log}
+   */
   logDebug(...args: any[]) {
     if (this.tree.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 node name as prefix if opts.debugLevel >= 1. */
   logError(...args: any[]) {
     if (this.tree.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 node name as prefix if opts.debugLevel >= 3. */
   logInfo(...args: any[]) {
     if (this.tree.options.debugLevel! >= 3) {
       console.info(this.toString(), ...args); // eslint-disable-line no-console
     }
   }
 
-  /* Log warning to console if opts.debugLevel >= 2 */
+  /** Write to `console.warn` with node name as prefix if opts.debugLevel >= 2. */
   logWarn(...args: any[]) {
     if (this.tree.options.debugLevel! >= 2) {
       console.warn(this.toString(), ...args); // eslint-disable-line no-console
@@ -1425,11 +1470,11 @@ export class WunderbaumNode {
     if (!this.children) {
       return;
     }
-    if (tree.activeNode && tree.activeNode.isDescendantOf(this)) {
+    if (tree.activeNode?.isDescendantOf(this)) {
       tree.activeNode.setActive(false); // TODO: don't fire events
     }
-    if (tree.focusNode && tree.focusNode.isDescendantOf(this)) {
-      tree.focusNode = null;
+    if (tree.focusNode?.isDescendantOf(this)) {
+      tree._setFocusNode(null);
     }
     // TODO: persist must take care to clear select and expand cookies
     // Unlink children to support GC
@@ -1613,7 +1658,7 @@ export class WunderbaumNode {
     // Attach a node reference to the DOM Element:
     (<any>rowDiv)._wb_node = this;
 
-    const nodeElem: HTMLElement = document.createElement("span");
+    const nodeElem: HTMLSpanElement = document.createElement("span");
     nodeElem.classList.add("wb-node", "wb-col");
     rowDiv.appendChild(nodeElem);
 
@@ -1891,6 +1936,7 @@ export class WunderbaumNode {
       let i = 0;
       for (const colSpan of rowDiv.children) {
         colSpan.classList.toggle("wb-active", i++ === tree.activeColIdx);
+        colSpan.classList.remove("wb-error", "wb-invalid");
       }
       // Update icon (if not opts.isNew, which would rebuild markup anyway)
       const iconSpan = nodeElem.querySelector("i.wb-icon") as HTMLElement;
@@ -2081,16 +2127,22 @@ export class WunderbaumNode {
   }
 
   /**
-   * Activate this node, deactivate previous, send events, activate column and scroll int viewport.
+   * Activate this node, deactivate previous, send events, activate column and
+   * scroll into viewport.
    */
   async setActive(flag: boolean = true, options?: SetActiveOptions) {
     const tree = this.tree;
-    const prev = tree.activeNode;
+    const prev = tree.getActiveNode();
     const retrigger = options?.retrigger; // Default: false
     const focusTree = options?.focusTree; // Default: false
-    const focusNode = options?.focusNode !== false; // Default: true
+    // const focusNode = options?.focusNode !== false; // Default: true
     const noEvents = options?.noEvents; // Default: false
-    const orgEvent = options?.event; // Default: false
+    const orgEvent = options?.event; // Default: null
+    const colIdx = options?.colIdx; // Default: null
+    const edit = options?.edit; // Default: false
+
+    util.assert(!colIdx || tree.isCellNav(), "colIdx requires cellNav");
+    util.assert(!edit || colIdx != null, "edit requires colIdx");
 
     if (!noEvents) {
       if (flag) {
@@ -2107,7 +2159,7 @@ export class WunderbaumNode {
           ) {
             return;
           }
-          tree.activeNode = null;
+          tree._setActiveNode(null);
           prev?.update(ChangeType.status);
         }
       } else if (prev === this || retrigger) {
@@ -2117,29 +2169,30 @@ export class WunderbaumNode {
 
     if (prev !== this) {
       if (flag) {
-        tree.activeNode = this;
-        if (focusNode || focusTree) {
-          tree.focusNode = this;
-        }
-        if (focusTree) {
-          tree.setFocus();
-        }
+        tree._setActiveNode(this);
       }
       prev?.update(ChangeType.status);
       this.update(ChangeType.status);
     }
-    if (
-      options &&
-      options.colIdx != null &&
-      options.colIdx !== tree.activeColIdx &&
-      tree.isCellNav()
-    ) {
-      tree.setColumn(options.colIdx);
-    }
-    if (flag && !noEvents) {
-      this._callEvent("activate", { prevNode: prev, event: orgEvent });
-    }
-    return this.makeVisible();
+    return this.makeVisible().then(() => {
+      if (flag) {
+        if (focusTree || edit) {
+          tree.setFocus();
+          tree._setFocusNode(this);
+          tree.focusNode!.setFocus();
+        }
+        // if (focusNode || edit) {
+        //   tree.focusNode = this;
+        //   tree.focusNode.setFocus();
+        // }
+        if (colIdx != null && tree.isCellNav()) {
+          tree.setColumn(colIdx, { edit: edit });
+        }
+        if (!noEvents) {
+          this._callEvent("activate", { prevNode: prev, event: orgEvent });
+        }
+      }
+    });
   }
 
   /**
@@ -2147,18 +2200,26 @@ export class WunderbaumNode {
    */
   async setExpanded(flag: boolean = true, options?: SetExpandedOptions) {
     const { force, scrollIntoView, immediate } = options ?? {};
+    const sendEvents = !options?.noEvents; // Default: send events
     if (
       !flag &&
       this.isExpanded() &&
       this.getLevel() <= this.tree.getOption("minExpandLevel") &&
       !force
     ) {
-      this.logDebug("Ignored collapse request below expandLevel.");
+      this.logDebug("Ignored collapse request below minExpandLevel.");
       return;
     }
     if (!flag === !this.expanded) {
       return; // Nothing to do
     }
+    if (
+      sendEvents &&
+      this._callEvent("beforeExpand", { flag: flag }) === false
+    ) {
+      return;
+    }
+
     // this.log("setExpanded()");
     if (flag && this.getOption("autoCollapse")) {
       this.collapseSiblings(options);
@@ -2177,6 +2238,9 @@ export class WunderbaumNode {
         lastChild.scrollIntoView({ topNode: this });
       }
     }
+    if (sendEvents) {
+      this._callEvent("expand", { flag: flag });
+    }
   }
 
   /**
@@ -2184,9 +2248,9 @@ export class WunderbaumNode {
    * @see {@link setActive}
    */
   setFocus(flag: boolean = true) {
-    util.assert(!!flag, "blur is not yet implemented");
+    util.assert(!!flag, "Blur is not yet implemented");
     const prev = this.tree.focusNode;
-    this.tree.focusNode = this;
+    this.tree._setFocusNode(this);
     prev?.update();
     this.update();
   }

package/src/wb_options.ts

@@ -5,6 +5,7 @@
  */
 
 import {
+  WbCancelableEventResultType,
   ColumnDefinitionList,
   DndOptionsType,
   DynamicBoolOption,
@@ -13,6 +14,9 @@ import {
   DynamicIconOption,
   EditOptionsType,
   FilterOptionsType,
+  GridOptionsType,
+  KeynavOptionsType,
+  LoggerOptionsType,
   NavModeEnum,
   NodeTypeDefinitionMap,
   SelectModeType,
@@ -21,6 +25,7 @@ import {
   WbClickEventType,
   WbDeactivateEventType,
   WbErrorEventType,
+  WbExpandEventType,
   WbIconBadgeCallback,
   WbInitEventType,
   WbKeydownEventType,
@@ -28,11 +33,13 @@ import {
   WbNodeEventType,
   WbReceiveEventType,
   WbRenderEventType,
+  WbSelectEventType,
   WbTreeEventType,
+  WbIconBadgeEventResultType,
 } from "./types";
 
 /**
- * Available options for [[Wunderbaum]].
+ * Available options for {@link wunderbaum.Wunderbaum}.
  *
  * Options are passed to the constructor as plain object:
  *
@@ -230,24 +237,40 @@ export interface WunderbaumOptions {
   scrollIntoViewOnExpandClick?: boolean;
 
   // --- Extensions ------------------------------------------------------------
-  dnd?: DndOptionsType; // = {};
-  edit?: EditOptionsType; // = {};
-  filter?: FilterOptionsType; // = {};
-  grid?: any; // = {};
+
+  dnd?: DndOptionsType;
+  edit?: EditOptionsType;
+  filter?: FilterOptionsType;
+  // grid?: GridOptionsType;
+  // keynav?: KeynavOptionsType;
+  // logger?: LoggerOptionsType;
 
   // --- Events ----------------------------------------------------------------
 
   /**
-   *
+   * `e.node` was activated.
    * @category Callback
    */
   activate?: (e: WbActivateEventType) => void;
+  /**
+   * `e.node` is about to be activated.
+   * Return `false` to prevent default handling, i.e. activating the node.
+   * See also `deactivate` event.
+   * @category Callback
+   */
+  beforeActivate?: (e: WbActivateEventType) => WbCancelableEventResultType;
+  /**
+   * `e.node` is about to be expanded/collapsed.
+   * Return `false` to prevent default handling, i.e. expanding/collapsing the node.
+   * @category Callback
+   */
+  beforeExpand?: (e: WbExpandEventType) => WbCancelableEventResultType;
   /**
    *
-   * Return `false` to prevent default handling, e.g. activating the node.
+   * Return `false` to prevent default handling, i.e. (de)selecting the node.
    * @category Callback
    */
-  beforeActivate?: (e: WbActivateEventType) => void;
+  beforeSelect?: (e: WbSelectEventType) => WbCancelableEventResultType;
   /**
    *
    * @category Callback
@@ -255,44 +278,46 @@ export interface WunderbaumOptions {
   change?: (e: WbChangeEventType) => void;
   /**
    *
-   * Return `false` to prevent default handling, e.g. activating the node.
+   * Return `false` to prevent default behavior, e.g. expand/collapse, (de)selection, or activation.
    * @category Callback
    */
-  click?: (e: WbClickEventType) => void;
+  click?: (e: WbClickEventType) => WbCancelableEventResultType;
   /**
-   *
+   * Return `false` to prevent default behavior, e.g. expand/collapse.
    * @category Callback
    */
-  dblclick?: (e: WbClickEventType) => void;
+  dblclick?: (e: WbClickEventType) => WbCancelableEventResultType;
   /**
+   * `e.node` was deactivated.
    *
    * Return `false` to prevent default handling, e.g. deactivating the node
    * and activating the next.
+   * See also `activate` event.
    * @category Callback
    */
-  deactivate?: (e: WbDeactivateEventType) => void;
+  deactivate?: (e: WbDeactivateEventType) => WbCancelableEventResultType;
   /**
-   *
+   * `e.node` was discarded from the viewport and its HTML markup removed.
    * @category Callback
    */
   discard?: (e: WbNodeEventType) => void;
   /**
-   *
+   * `e.node` is about to be rendered. We can add a badge to the icon cell here.
    * @category Callback
    */
-  iconBadge?: WbIconBadgeCallback;
-  // /**
-  //  *
-  //  * @category Callback
-  //  */
-  // enhanceTitle?: (e: WbEnhanceTitleEventType) => void;
+  iconBadge?: (e: WbIconBadgeCallback) => WbIconBadgeEventResultType;
   /**
-   *
+   * An error occurred, e.g. during initialization or lazy loading.
    * @category Callback
    */
   error?: (e: WbErrorEventType) => void;
   /**
-   *
+   * `e.node` was expanded (`e.flag === true`) or collapsed (`e.flag === false`)
+   * @category Callback
+   */
+  expand?: (e: WbTreeEventType) => void;
+  /**
+   * The tree received or lost focus.
    * Check `e.flag` for status.
    * @category Callback
    */
@@ -301,15 +326,17 @@ export interface WunderbaumOptions {
    * Fires when the tree markup was created and the initial source data was loaded.
    * Typical use cases would be activating a node, setting focus, enabling other
    * controls on the page, etc.<br>
-   * Check `e.error` for status.
+   *  Also sent if an error occured during initialization (check `e.error` for status).
    * @category Callback
    */
   init?: (e: WbInitEventType) => void;
   /**
-   *
+   * Fires when a key was pressed while the tree has focus.
+   * `e.node` is set if a node is currently active.
+   * Return `false` to prevent default navigation.
    * @category Callback
    */
-  keydown?: (e: WbKeydownEventType) => void;
+  keydown?: (e: WbKeydownEventType) => WbCancelableEventResultType;
   /**
    * Fires when a node that was marked 'lazy', is expanded for the first time.
    * Typically we return an endpoint URL or the Promise of a fetch request that
@@ -345,13 +372,12 @@ export interface WunderbaumOptions {
    */
   render?: (e: WbRenderEventType) => void;
   /**
-   *
+   * Same as `render(e)`, but for the status nodes, i.e. `e.node.statusNodeType`.
    * @category Callback
    */
   renderStatusNode?: (e: WbRenderEventType) => void;
   /**
-   *
-   * Check `e.flag` for status.
+   *`e.node` was selected (`e.flag === true`) or deselected (`e.flag === false`)
    * @category Callback
    */
   select?: (e: WbNodeEventType) => void;

package/src/wunderbaum.scss

@@ -830,10 +830,16 @@ i.wb-icon {
 
 .wb-col input:invalid {
   // border-color: var(--wb-error-color);
-  color: var(--wb-error-color);
+  // color: var(--wb-error-color);
   background-color: var(--wb-error-background-color);
 }
 
+.wb-col.wb-invalid {
+  border: 1px dotted var(--wb-error-color);
+  // color: var(--wb-error-color);
+  // background-color: var(--wb-error-background-color);
+}
+
 @keyframes wb-spin-animation {
   0% {
     transform: rotate(0deg);