wunderbaum 0.8.0 → 0.8.2

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,7 +33,9 @@ import {
   WbNodeEventType,
   WbReceiveEventType,
   WbRenderEventType,
+  WbSelectEventType,
   WbTreeEventType,
+  WbIconBadgeEventResultType,
 } from "./types";
 
 /**
@@ -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.ts

@@ -119,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 = {};
@@ -617,10 +630,8 @@ 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 != null) {
@@ -948,8 +959,8 @@ export class Wunderbaum {
     this.keyMap.clear();
     this.refKeyMap.clear();
     this.treeRowCount = 0;
-    this.activeNode = null;
-    this.focusNode = null;
+    this._activeNode = null;
+    this._focusNode = null;
 
     // this.types = {};
     // this. columns =[];
@@ -1392,10 +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 WunderbaumNode.getFocusNode}
+   * @see {@link Wunderbaum.activeNode}
+   * @see {@link Wunderbaum.focusNode}
    */
   getActiveNode() {
     return this.activeNode;
@@ -1410,7 +1424,11 @@ export class Wunderbaum {
 
   /**
    * Return the node that currently has keyboard focus or null.
-   * @see {@link WunderbaumNode.getActiveNode}
+   * 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;
@@ -1522,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
@@ -1563,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
@@ -1721,6 +1746,11 @@ export class Wunderbaum {
     }
   }
 
+  /* Set or remove keyboard focus to the tree container. @internal */
+  _setActiveNode(node: WunderbaumNode | null) {
+    this._activeNode = node;
+  }
+
   /** Set or remove keyboard focus to the tree container. */
   setActiveNode(key: string, flag: boolean = true, options?: SetActiveOptions) {
     this.findKey(key)?.setActive(flag, options);
@@ -1735,6 +1765,11 @@ 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