wunderbaum 0.0.2 → 0.0.5

package/dist/wunderbaum.d.ts

@@ -4,6 +4,7 @@ declare module "util" {
      * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
      * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
      */
+    /** @module util */
     /** Readable names for `MouseEvent.button` */
     export const MOUSE_BUTTONS: {
         [key: number]: string;
@@ -62,7 +63,7 @@ declare module "util" {
      *
      * If a `<span class="wb-col">` is passed, the first child input is used.
      * Depending on the target element type, `value` is interpreted accordingly.
-     * For example for a checkbox, a value of true, false, or null is returned if the
+     * For example for a checkbox, a value of true, false, or null is returned if
      * the element is checked, unchecked, or indeterminate.
      * For datetime input control a numerical value is assumed, etc.
      *
@@ -164,7 +165,7 @@ declare module "util" {
       */
     export function overrideMethod(instance: any, methodName: string, handler: FunctionType, ctx?: any): void;
     /** Run function after ms milliseconds and return a promise that resolves when done. */
-    export function setTimeoutPromise(callback: (...args: any[]) => void, ms: number): Promise<unknown>;
+    export function setTimeoutPromise(this: unknown, callback: (...args: any[]) => void, ms: number): Promise<unknown>;
     /**
      * Wait `ms` microseconds.
      *
@@ -197,8 +198,21 @@ declare module "util" {
     export function getOption(opts: any, name: string, defaultValue?: any): any;
     /** Convert an Array or space-separated string to a Set. */
     export function toSet(val: any): Set<string>;
-    /**Return a canonical string representation for an object's type (e.g. 'array', 'number', ...) */
+    /** Return a canonical string representation for an object's type (e.g. 'array', 'number', ...). */
     export function type(obj: any): string;
+    /**
+     * Return a function that can be called instead of `callback`, but guarantees
+     * a limited execution rate.
+     * The execution rate is calculated based on the runtime duration of the
+     * previous call.
+     * Example:
+     * ```js
+     * throttledFoo = util.adaptiveThrottle(foo.bind(this), {});
+     * throttledFoo();
+     * throttledFoo();
+     * ```
+     */
+    export function adaptiveThrottle(this: unknown, callback: (...args: any[]) => void, options: any): (...args: any[]) => void;
 }
 declare module "deferred" {
     /*!
@@ -209,9 +223,19 @@ declare module "deferred" {
     type PromiseCallbackType = (val: any) => void;
     type finallyCallbackType = () => void;
     /**
-     * Deferred is a ES6 Promise, that exposes the resolve() and reject()` method.
+     * Implement a ES6 Promise, that exposes a resolve() and reject() method.
      *
-     * Loosely mimics [`jQuery.Deferred`](https://api.jquery.com/category/deferred-object/).
+     * Loosely mimics {@link https://api.jquery.com/category/deferred-object/ | jQuery.Deferred}.
+     * Example:
+     * ```js
+     * function foo() {
+     *   let dfd = new Deferred(),
+     *   ...
+     *   dfd.resolve('foo')
+     *   ...
+     *   return dfd.promise();
+     * }
+     * ```
      */
     export class Deferred {
         private _promise;
@@ -409,6 +433,39 @@ declare module "wb_options" {
         checkbox?: boolean | string;
         children?: Array<WbNodeData>;
     }
+    export interface ColumnDefinition {
+        /** Column ID (pass "*" for the main tree nodes column ) */
+        id: string;
+        /** Column header (defaults to id) */
+        title: string;
+        /** Column width or weight.
+         * Either an absolute pixel value (e.g. `"50px"`) or a relative weight (e.g. `1`)
+         * that is used to calculate the width  inside the remaining available space.
+         * Default: `"*"`, which is interpreted as `1`.
+         */
+        width?: string | number;
+        /** Only used for columns with a relative weight.
+         * Default: `4px`.
+         */
+        minWidth?: string | number;
+        /** Optional class names that are added to all `span.wb-col` elements of that column.*/
+        classes?: string;
+        /** Optional HTML content that is rendered into all `span.wb-col` elements of that column.*/
+        html: string;
+    }
+    export interface TypeDefinition {
+        /** En/disable checkbox for matching nodes.*/
+        checkbox?: boolean | BoolOptionResolver;
+        /** Optional class names that are added to all `div.wb-row` elements of matching nodes.*/
+        classes?: string;
+        /**Default icon for matching nodes.*/
+        icon?: boolean | string | BoolOptionResolver;
+        /**
+         * See also {@link WunderbaumNode.getOption|WunderbaumNode.getOption()}
+         * to evaluate `node.NAME` setting and `tree.types[node.type].NAME`.
+         */
+        _any: any;
+    }
     /**
      * Available options for [[Wunderbaum]].
      *
@@ -422,6 +479,21 @@ declare module "wb_options" {
      *   ...
      * });
      * ```
+     *
+     * Event handlers are also passed as callbacks
+     *
+     * ```js
+     * const tree = new mar10.Wunderbaum({
+     *   ...
+     *   init: (e) => {
+     *     console.log(`Tree ${e.tree} was initialized and loaded.`)
+     *   },
+     *   activate: (e) => {
+     *     console.log(`Node ${e.node} was activated.`)
+     *   },
+     *   ...
+     * });
+     * ```
      */
     export interface WunderbaumOptions {
         /**
@@ -450,7 +522,9 @@ declare module "wb_options" {
          *
          * Default: `{}`.
          */
-        types?: any;
+        types?: {
+            [key: string]: TypeDefinition;
+        };
         /**
          * A list of maps that define column headers. If this option is set,
          * Wunderbaum becomes a treegrid control instead of a plain tree.
@@ -458,7 +532,7 @@ declare module "wb_options" {
          * response.
          * Default: `[]` meaning this is a plain tree.
          */
-        columns?: Array<any>;
+        columns?: Array<ColumnDefinition>;
         /**
          * If true, add a `wb-skeleton` class to all nodes, that will result in a
          * 'glow' effect. Typically used with initial dummy nodes, while loading the
@@ -477,7 +551,7 @@ declare module "wb_options" {
         debugLevel: number;
         /**
          * Number of levels that are forced to be expanded, and have no expander icon.
-         *  Default: 0
+         * Default: 0
          */
         minExpandLevel?: number;
         /**
@@ -495,6 +569,11 @@ declare module "wb_options" {
          * Default: false
          */
         autoCollapse?: boolean;
+        /**
+         * HTMLElement that receives the top nodes breadcrumb.
+         * Default: undefined
+         */
+        attachBreadcrumb?: HTMLElement;
         /**
          * Default:  NavigationModeOption.startRow
          */
@@ -515,29 +594,38 @@ declare module "wb_options" {
          * Default: 200
          */
         updateThrottleWait?: number;
+        /**
+         * Default: true
+         */
+        enabled?: boolean;
+        /**
+         * Default: false
+         */
+        fixedCol?: boolean;
         /**
          * Default: true
          */
         quicksearch?: boolean;
         dnd?: DndOptionsType;
+        edit: any;
         filter: any;
         grid: any;
         /**
-         * Called after initial data was loaded and tree markup was rendered.
-         * Check `e.error` for status.
+         *
          * @category Callback
          */
-        init?: (e: WbTreeEventType) => void;
+        activate?: (e: WbNodeEventType) => void;
         /**
          *
          * @category Callback
          */
-        update?: (e: WbTreeEventType) => void;
+        change?: (e: WbNodeEventType) => void;
         /**
          *
+         * Return `false` to prevent default handling, e.g. activating the node.
          * @category Callback
          */
-        activate?: (e: WbNodeEventType) => void;
+        click?: (e: WbTreeEventType) => void;
         /**
          *
          * @category Callback
@@ -547,40 +635,47 @@ declare module "wb_options" {
          *
          * @category Callback
          */
-        change?: (e: WbNodeEventType) => void;
+        discard?: (e: WbNodeEventType) => void;
         /**
          *
          * @category Callback
          */
-        click?: (e: WbTreeEventType) => void;
+        enhanceTitle?: (e: WbNodeEventType) => void;
         /**
          *
          * @category Callback
          */
-        discard?: (e: WbNodeEventType) => void;
+        error?: (e: WbTreeEventType) => void;
         /**
          *
+         * Check `e.flag` for status.
          * @category Callback
          */
-        error?: (e: WbTreeEventType) => void;
+        focus?: (e: WbTreeEventType) => void;
         /**
-         *
+         * 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.
          * @category Callback
          */
-        enhanceTitle?: (e: WbNodeEventType) => void;
+        init?: (e: WbTreeEventType) => void;
         /**
          *
-         * Check `e.flag` for status.
          * @category Callback
          */
-        focus?: (e: WbTreeEventType) => void;
+        keydown?: (e: WbNodeEventType) => void;
         /**
-         *
+         * 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
+         * provides a (potentially nested) list of child nodes.
          * @category Callback
          */
-        keydown?: (e: WbNodeEventType) => void;
+        lazyLoad?: (e: WbNodeEventType) => void;
         /**
-         * Called after data was loaded from local storage.
+         * Fires when data was loaded (initial request, reload, or lazy loading),
+         * after the data is applied and rendered.
+         * @category Callback
          */
         load?: (e: WbNodeEventType) => void;
         /**
@@ -588,12 +683,19 @@ declare module "wb_options" {
          */
         modifyChild?: (e: WbNodeEventType) => void;
         /**
-         *
+         * Fires when data was fetched (initial request, reload, or lazy loading),
+         * but before the data is applied and rendered.
+         * Here we can modify and adjust the received data, for example to convert an
+         * external response to native Wunderbaum syntax.
          * @category Callback
          */
         receive?: (e: WbNodeEventType) => void;
         /**
-         *
+         * Fires when a node is about to be displayed.
+         * The default HTML markup is already created, but not yet added to the DOM.
+         * Now we can tweak the markup, create HTML elements in this node's column
+         * cells, etc.
+         * See also `Custom Rendering` for details.
          * @category Callback
          */
         render?: (e: WbNodeEventType) => void;
@@ -608,6 +710,11 @@ declare module "wb_options" {
          * @category Callback
          */
         select?: (e: WbNodeEventType) => void;
+        /**
+         * Fires when the viewport content was updated, after scroling, expanding etc.
+         * @category Callback
+         */
+        update?: (e: WbTreeEventType) => void;
     }
 }
 declare module "wb_node" {
@@ -618,28 +725,48 @@ declare module "wb_node" {
      */
     import "./wunderbaum.scss";
     import { Wunderbaum } from "wunderbaum";
-    import { ChangeType, MatcherType, NodeAnyCallback, NodeStatusType, NodeVisitCallback, NodeVisitResponse, ApplyCommandType, AddNodeType } from "common";
+    import { ChangeType, MatcherType, NodeAnyCallback, NodeStatusType, NodeVisitCallback, NodeVisitResponse, ApplyCommandType, AddNodeType, SetActiveOptions, SetExpandedOptions, SetSelectedOptions } from "common";
     import { WbNodeData } from "wb_options";
+    /**
+     * A single tree node.
+     *
+     * **NOTE:** <br>
+     * Generally you should not modify properties directly, since this may break
+     * the internal bookkeeping.
+     */
     export class WunderbaumNode {
         static sequence: number;
         /** Reference to owning tree. */
         tree: Wunderbaum;
         /** Parent node (null for the invisible root node `tree.root`). */
         parent: WunderbaumNode;
+        /** Name of the node.
+         * @see Use {@link setTitle} to modify. */
         title: string;
+        /** Unique key. Passed with constructor or defaults to `SEQUENCE`.
+         * @see Use {@link setKey} to modify. */
         readonly key: string;
+        /** Reference key. Unlike {@link key}, a `refKey` may occur multiple
+         * times within a tree (in this case we have 'clone nodes').
+         * @see Use {@link setKey} to modify.
+         */
         readonly refKey: string | undefined;
         children: WunderbaumNode[] | null;
         checkbox?: boolean;
         colspan?: boolean;
         icon?: boolean | string;
         lazy: boolean;
+        /** Expansion state.
+         * @see {@link isExpandable}, {@link isExpanded}, {@link setExpanded}. */
         expanded: boolean;
+        /** Selection state.
+         * @see {@link isSelected}, {@link setSelected}. */
         selected: boolean;
         type?: string;
         tooltip?: string;
-        /** Additional classes added to `div.wb-row`. */
-        extraClasses: Set<string>;
+        /** Additional classes added to `div.wb-row`.
+         * @see {@link hasClass}, {@link setClass}. */
+        classes: Set<string> | null;
         /** Custom data that was passed to the constructor */
         data: any;
         statusNodeType?: string;
@@ -651,6 +778,7 @@ declare module "wb_node" {
         match?: boolean;
         subMatchCount?: number;
         subMatchBadge?: HTMLElement;
+        /** @internal */
         titleWithHighlight?: string;
         _filterAutoExpanded?: boolean;
         _rowIdx: number | undefined;
@@ -667,7 +795,7 @@ declare module "wb_node" {
          * node._callEvent("edit.beforeEdit", {foo: 42})
          * ```
          */
-        _callEvent(name: string, extra?: any): any;
+        _callEvent(type: string, extra?: any): any;
         /**
          * Append (or insert) a list of child nodes.
          *
@@ -690,12 +818,19 @@ declare module "wb_node" {
         addNode(nodeData: WbNodeData, mode?: string): WunderbaumNode;
         /**
          * Apply a modification (or navigation) operation.
-         * @see Wunderbaum#applyCommand
+         *
+         * @see {@link Wunderbaum.applyCommand}
          */
         applyCommand(cmd: ApplyCommandType, opts: any): any;
-        addClass(className: string | string[] | Set<string>): void;
-        removeClass(className: string | string[] | Set<string>): void;
-        toggleClass(className: string | string[] | Set<string>, flag: boolean): void;
+        /**
+         * Add/remove one or more classes to `<div class='wb-row'>`.
+         *
+         * This also maintains `node.classes`, so the class will survive a re-render.
+         *
+         * @param className one or more class names. Multiple classes can be passed
+         *     as space-separated string, array of strings, or set of strings.
+         */
+        setClass(className: string | string[] | Set<string>, flag?: boolean): void;
         /** */
         expandAll(flag?: boolean): Promise<void>;
         /**Find all nodes that match condition (excluding self).
@@ -714,8 +849,7 @@ declare module "wb_node" {
         findFirst(match: string | MatcherType): WunderbaumNode | null;
         /** Find a node relative to self.
          *
-         * @param where The keyCode that would normally trigger this move,
-         *		or a keyword ('down', 'first', 'last', 'left', 'parent', 'right', 'up').
+         * @see {@link Wunderbaum.findRelatedNode|tree.findRelatedNode()}
          */
         findRelatedNode(where: string, includeHidden?: boolean): any;
         /** Return the `<span class='wb-col'>` element with a given index or id.
@@ -753,6 +887,8 @@ declare module "wb_node" {
          * Return undefined if not sure, i.e. the node is lazy and not yet loaded.
          */
         hasChildren(): boolean;
+        /** Return true if node has className set. */
+        hasClass(className: string): boolean;
         /** Return true if this node is the currently active tree node. */
         isActive(): boolean;
         /** Return true if this node is a *direct* child of `other`.
@@ -852,8 +988,34 @@ declare module "wb_node" {
             [key: string]: any;
         };
         protected _createIcon(parentElem: HTMLElement, replaceChild?: HTMLElement): HTMLElement | null;
-        /** Create HTML markup for this node, i.e. the whole row. */
-        render(opts?: any): void;
+        /**
+         * Create a whole new `<div class="wb-row">` element.
+         * @see {@link Wunderbaumode.render}
+         */
+        protected _render_markup(opts: any): void;
+        /**
+         * Render `node.title`, `.icon` into an existing row.
+         *
+         * @see {@link Wunderbaumode.render}
+         */
+        protected _render_data(opts: any): void;
+        /**
+         * Update row classes to reflect active, focuses, etc.
+         * @see {@link Wunderbaumode.render}
+         */
+        protected _render_status(opts: any): void;
+        /**
+         * Create or update node's markup.
+         *
+         * `options.change` defaults to ChangeType.data, which updates the title,
+         * icon, and status. It also triggers the `render` event, that lets the user
+         * create or update the content of embeded cell elements.<br>
+         *
+         * If only the status or other class-only modifications have changed,
+         * `options.change` should be set to ChangeType.status instead for best
+         * efficiency.
+         */
+        render(options?: any): void;
         /**
          * Remove all children, collapse, and set the lazy-flag, so that the lazyLoad
          * event is triggered on next expand.
@@ -876,26 +1038,51 @@ declare module "wb_node" {
          *
          * Evaluation sequence:
          *
-         * If `tree.options.<name>` is a callback that returns something, use that.
-         * Else if `node.<name>` is defined, use that.
-         * Else if `tree.types[<node.type>]` is a value, use that.
-         * Else if `tree.options.<name>` is a value, use that.
-         * Else use `defaultValue`.
+         * - If `tree.options.<name>` is a callback that returns something, use that.
+         * - Else if `node.<name>` is defined, use that.
+         * - Else if `tree.types[<node.type>]` is a value, use that.
+         * - Else if `tree.options.<name>` is a value, use that.
+         * - Else use `defaultValue`.
          *
          * @param name name of the option property (on node and tree)
          * @param defaultValue return this if nothing else matched
+         * {@link Wunderbaum.getOption|Wunderbaum.getOption()}
          */
         getOption(name: string, defaultValue?: any): any;
+        /** Make sure that this node is visible in the viewport.
+         * @see {@link Wunderbaum.scrollTo|Wunderbaum.scrollTo()}
+         */
         scrollIntoView(options?: any): Promise<void>;
-        setActive(flag?: boolean, options?: any): Promise<void>;
-        setModified(change?: ChangeType): void;
-        setExpanded(flag?: boolean, options?: any): Promise<void>;
-        setIcon(): void;
+        /**
+         * Activate this node, deactivate previous, send events, activate column and scroll int viewport.
+         */
+        setActive(flag?: boolean, options?: SetActiveOptions): Promise<void>;
+        /**
+         * Expand or collapse this node.
+         */
+        setExpanded(flag?: boolean, options?: SetExpandedOptions): Promise<void>;
+        /**
+         * Set keyboard focus here.
+         * @see {@link setActive}
+         */
         setFocus(flag?: boolean, options?: any): void;
-        setSelected(flag?: boolean, options?: any): void;
-        /** Show node status (ok, loading, error, noData) using styles and a dummy child node.
+        /** Set a new icon path or class. */
+        setIcon(): void;
+        /** Change node's {@link key} and/or {@link refKey}.  */
+        setKey(key: string | null, refKey: string | null): void;
+        /**
+         * Schedule a render, typically called to update after a status or data change.
+         *
+         * `change` defaults to 'data', which handles modifcations of title, icon,
+         * and column content. It can be reduced to 'ChangeType.status' if only
+         * active/focus/selected state has changed.
          */
+        setModified(change?: ChangeType): void;
+        /** Modify the check/uncheck state. */
+        setSelected(flag?: boolean, options?: SetSelectedOptions): void;
+        /** Display node status (ok, loading, error, noData) using styles and a dummy child node. */
         setStatus(status: NodeStatusType, message?: string, details?: string): WunderbaumNode | null;
+        /** Rename this node. */
         setTitle(title: string): void;
         /**
          * Trigger `modifyChild` event on a parent to signal that a child was modified.
@@ -907,9 +1094,12 @@ declare module "wb_node" {
          * @param {string} operation Type of change: 'add', 'remove', 'rename', 'move', 'data', ...
          * @param {object} [extra]
          */
-        triggerModify(operation: string, extra: any): void;
-        /** Call fn(node) for all child nodes in hierarchical order (depth-first).<br>
-         * Stop iteration, if fn() returns false. Skip current branch, if fn() returns "skip".<br>
+        triggerModify(operation: string, extra?: any): void;
+        /**
+         * Call fn(node) for all child nodes in hierarchical order (depth-first).
+         *
+         * Stop iteration, if fn() returns false. Skip current branch, if fn()
+         * returns "skip".<br>
          * Return false if iteration was stopped.
          *
          * @param {function} callback the callback function.
@@ -924,7 +1114,8 @@ declare module "wb_node" {
          * @param callback the callback function. Return false to stop iteration
          */
         visitParents(callback: (node: WunderbaumNode) => boolean | void, includeSelf?: boolean): boolean;
-        /** Call fn(node) for all sibling nodes.<br>
+        /**
+         * Call fn(node) for all sibling nodes.<br>
          * Stop iteration, if fn() returns false.<br>
          * Return false if iteration was stopped.
          *
@@ -954,7 +1145,7 @@ declare module "common" {
     export type NodeVisitResponse = "skip" | boolean | void;
     export type NodeVisitCallback = (node: WunderbaumNode) => NodeVisitResponse;
     export type WbTreeEventType = {
-        name: string;
+        type: string;
         event: Event;
         tree: Wunderbaum;
         [key: string]: unknown;
@@ -970,21 +1161,31 @@ declare module "common" {
     export type NodeFilterCallback = (node: WunderbaumNode) => NodeFilterResponse;
     export type AddNodeType = "before" | "after" | "prependChild" | "appendChild";
     export type DndModeType = "before" | "after" | "over";
+    /** Possible values for `setModified()`. */
     export enum ChangeType {
+        /** Re-render the whole viewport, headers, and all rows. */
         any = "any",
+        /** Update current row title, icon, columns, and status. */
+        data = "data",
+        /** Redraw the header and update the width of all row columns. */
+        header = "header",
+        /** Re-render the whole current row. */
         row = "row",
+        /** Alias for 'any'. */
         structure = "structure",
+        /** Update current row's classes, to reflect active, selected, ... */
         status = "status",
-        vscroll = "vscroll",
-        header = "header"
+        /** Update the 'top' property of all rows. */
+        vscroll = "vscroll"
     }
+    /** Possible values for `setStatus()`. */
     export enum NodeStatusType {
         ok = "ok",
         loading = "loading",
         error = "error",
         noData = "noData"
     }
-    /**Define the subregion of a node, where an event occurred. */
+    /** Define the subregion of a node, where an event occurred. */
     export enum TargetType {
         unknown = "",
         checkbox = "checkbox",
@@ -1012,19 +1213,21 @@ declare module "common" {
         doc: string;
     };
     export const KEY_NODATA = "__not_found__";
+    /** Initial navigation mode and possible transition. */
     export enum NavigationModeOption {
         startRow = "startRow",
         cell = "cell",
         startCell = "startCell",
         row = "row"
     }
+    /** Tree's current navigation mode (see `tree.setNavigationMode()`). */
     export enum NavigationMode {
         row = "row",
         cellNav = "cellNav",
         cellEdit = "cellEdit"
     }
     /** Define which keys are handled by embedded <input> control, and should
-     * *not* be passed to tree navigation handler in cell-edit mode: */
+     * *not* be passed to tree navigation handler in cell-edit mode. */
     export const INPUT_KEYS: {
         text: string[];
         number: string[];
@@ -1036,13 +1239,42 @@ declare module "common" {
     };
     /** Key codes that trigger grid navigation, even when inside an input element. */
     export const NAVIGATE_IN_INPUT_KEYS: Set<string>;
+    /** Possible values for `node.setActive()`. */
+    export type SetActiveOptions = {
+        /** Generate (de)activate event, even if node already has this status. */
+        retrigger?: boolean;
+        /** Do not generate (de)activate event. */
+        noEvents?: boolean;
+        /** Optional original event that will be passed to the (de)activate handler. */
+        event?: Event;
+        /** Call {@link setColumn}. */
+        colIdx?: number;
+    };
+    /** Possible values for `node.setExpanded()`. */
+    export type SetExpandedOptions = {
+        /** Ignore {@link minExpandLevel}. @default false */
+        force?: boolean;
+        /** Avoid smooth scrolling. @default false */
+        noAnimation?: boolean;
+        /** Do not send events. @default false */
+        noEvents?: boolean;
+        /** Scroll to bring expanded nodes into viewport. @default false */
+        scrollIntoView?: boolean;
+    };
+    /** Possible values for `node.setSelected()`. */
+    export type SetSelectedOptions = {
+        /** Ignore restrictions. @default false */
+        force?: boolean;
+        /** Do not send events. @default false */
+        noEvents?: boolean;
+    };
     /** Map `KeyEvent.key` to navigation action. */
     export const KEY_TO_ACTION_DICT: {
         [key: string]: string;
     };
-    /** */
+    /** Return a callback that returns true if the node title contains a substring (case-insensitive). */
     export function makeNodeTitleMatcher(s: string): MatcherType;
-    /** */
+    /** Return a callback that returns true if the node title starts with a string (case-insensitive). */
     export function makeNodeTitleStartMatcher(s: string): MatcherType;
 }
 declare module "debounce" {
@@ -1188,6 +1420,7 @@ declare module "wb_ext_filter" {
         lastFilterArgs: IArguments | null;
         constructor(tree: Wunderbaum);
         init(): void;
+        setPluginOption(name: string, value: any): void;
         _applyFilterNoUpdate(filter: string | NodeFilterCallback, branchMode: boolean, _opts: any): void;
         _applyFilterImpl(filter: string | NodeFilterCallback, branchMode: boolean, _opts: any): number;
         /**
@@ -1217,6 +1450,7 @@ declare module "wb_ext_keynav" {
     import { WunderbaumExtension } from "wb_extension_base";
     export class KeynavExtension extends WunderbaumExtension {
         constructor(tree: Wunderbaum);
+        protected _getEmbeddedInputElem(elem: any, setFocus?: boolean): HTMLInputElement | null;
         onKeyEvent(data: any): boolean | undefined;
     }
 }
@@ -1343,20 +1577,20 @@ declare module "wunderbaum" {
     /*!
      * wunderbaum.ts
      *
-     * A tree control.
+     * A treegrid control.
      *
      * Copyright (c) 2021-2022, Martin Wendt (https://wwWendt.de).
-     * Released under the MIT license.
+     * https://github.com/mar10/wunderbaum
      *
+     * Released under the MIT license.
      * @version @VERSION
      * @date @DATE
      */
     import "./wunderbaum.scss";
     import * as util from "util";
     import { ExtensionsDict, WunderbaumExtension } from "wb_extension_base";
-    import { NavigationMode, ChangeType, FilterModeType, MatcherType, NodeStatusType, TargetType as NodeRegion, ApplyCommandType } from "common";
+    import { NavigationMode, ChangeType, FilterModeType, MatcherType, NodeStatusType, TargetType as NodeRegion, ApplyCommandType, SetActiveOptions } from "common";
     import { WunderbaumNode } from "wb_node";
-    import { DebouncedFunction } from "debounce";
     import { WunderbaumOptions } from "wb_options";
     /**
      * A persistent plain object or array.
@@ -1364,68 +1598,80 @@ declare module "wunderbaum" {
      * See also [[WunderbaumOptions]].
      */
     export class Wunderbaum {
+        protected static sequence: number;
+        protected enabled: boolean;
+        /** Wunderbaum release version number "MAJOR.MINOR.PATCH". */
         static version: string;
-        static sequence: number;
         /** The invisible root node, that holds all visible top level nodes. */
         readonly root: WunderbaumNode;
+        /** Unique tree ID as passed to constructor. Defaults to `"wb_SEQUENCE"`. */
         readonly id: string;
+        /** The `div` container element that was passed to the constructor. */
         readonly element: HTMLDivElement;
+        /** The `div.wb-header` element if any. */
         readonly headerElement: HTMLDivElement | null;
-        readonly scrollContainer: HTMLDivElement;
+        /** The `div.wb-scroll-container` element that contains the `nodeListElement`. */
+        readonly scrollContainerElement: HTMLDivElement;
+        /** The `div.wb-node-list` element that contains all visible div.wb-row child elements. */
         readonly nodeListElement: HTMLDivElement;
-        readonly _updateViewportThrottled: DebouncedFunction<(...args: any) => void>;
+        protected readonly _updateViewportThrottled: (...args: any) => void;
         protected extensionList: WunderbaumExtension[];
         protected extensions: ExtensionsDict;
         /** Merged options from constructor args and tree- and extension defaults. */
         options: WunderbaumOptions;
         protected keyMap: Map<string, WunderbaumNode>;
         protected refKeyMap: Map<string, Set<WunderbaumNode>>;
-        protected viewNodes: Set<WunderbaumNode>;
+        protected treeRowCount: number;
+        protected _disableUpdateCount: number;
+        /** Currently active node if any. */
         activeNode: WunderbaumNode | null;
+        /** Current node hat has keyboard focus if any. */
         focusNode: WunderbaumNode | null;
-        _disableUpdate: number;
-        _disableUpdateCount: number;
         /** Shared properties, referenced by `node.type`. */
         types: {
             [key: string]: any;
         };
         /** List of column definitions. */
         columns: any[];
-        _columnsById: {
+        protected _columnsById: {
             [key: string]: any;
         };
-        protected resizeObserver: any;
-        protected changedSince: number;
-        protected changes: Set<ChangeType>;
-        protected changedNodes: Set<WunderbaumNode>;
-        protected changeRedrawPending: boolean;
+        protected resizeObserver: ResizeObserver;
+        protected changeRedrawRequestPending: boolean;
+        /** A Promise that is resolved when the tree was initialized (similar to `init(e)` event). */
+        readonly ready: Promise<any>;
+        /** Expose some useful methods of the util.ts module as `Wunderbaum.util`. */
+        static util: typeof util;
+        /** Expose some useful methods of the util.ts module as `tree._util`. */
+        _util: typeof util;
         filterMode: FilterModeType;
+        /** @internal Use `setColumn()`/`getActiveColElem()`*/
         activeColIdx: number;
+        /** @internal */
         navMode: NavigationMode;
+        /** @internal */
         lastQuicksearchTime: number;
+        /** @internal */
         lastQuicksearchTerm: string;
         protected lastClickTime: number;
-        readonly ready: Promise<any>;
-        static util: typeof util;
-        _util: typeof util;
         constructor(options: WunderbaumOptions);
-        /** */
-        /** Return a Wunderbaum instance, from element, index, or event.
+        /**
+         * Return a Wunderbaum instance, from element, id, index, or event.
          *
-         * @example
-         * getTree();  // Get first Wunderbaum instance on page
-         * 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`
+         * ```js
+         * getTree();         // Get first Wunderbaum instance on page
+         * 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
+         * ```
          */
         static getTree(el?: Element | Event | number | string | WunderbaumNode): Wunderbaum | null;
-        /** Return a WunderbaumNode instance from element, event.
-         *
-         * @param  el
+        /**
+         * Return a WunderbaumNode instance from element or event.
          */
         static getNode(el: Element | Event): WunderbaumNode | null;
-        /** */
+        /** @internal */
         protected _registerExtension(extension: WunderbaumExtension): void;
         /** Called on tree (re)init after markup is created, before loading. */
         protected _initExtensions(): void;
@@ -1435,37 +1681,47 @@ declare module "wunderbaum" {
         _unregisterNode(node: WunderbaumNode): void;
         /** Call all hook methods of all registered extensions.*/
         protected _callHook(hook: keyof WunderbaumExtension, data?: any): any;
-        /** Call tree method or extension method if defined.
+        /**
+         * Call tree method or extension method if defined.
+         *
          * Example:
          * ```js
          * tree._callMethod("edit.startEdit", "arg1", "arg2")
          * ```
          */
         _callMethod(name: string, ...args: any[]): any;
-        /** Call event handler if defined in tree.options.
+        /**
+         * Call event handler if defined in tree or tree.EXTENSION options.
+         *
          * Example:
          * ```js
          * tree._callEvent("edit.beforeEdit", {foo: 42})
          * ```
          */
-        _callEvent(name: string, extra?: any): any;
-        /** Return the topmost visible node in the viewport */
-        protected _firstNodeInView(complete?: boolean): WunderbaumNode;
-        /** Return the lowest visible node in the viewport */
-        protected _lastNodeInView(complete?: boolean): WunderbaumNode;
-        /** Return preceeding visible node in the viewport */
+        _callEvent(type: string, extra?: any): any;
+        /** Return the node for  given row index. */
+        protected _getNodeByRowIdx(idx: number): WunderbaumNode | null;
+        /** Return the topmost visible node in the viewport. */
+        getTopmostVpNode(complete?: boolean): WunderbaumNode;
+        /** Return the lowest visible node in the viewport. */
+        getLowestVpNode(complete?: boolean): WunderbaumNode;
+        /** Return preceeding visible node in the viewport. */
         protected _getPrevNodeInView(node?: WunderbaumNode, ofs?: number): WunderbaumNode;
-        /** Return following visible node in the viewport */
+        /** Return following visible node in the viewport. */
         protected _getNextNodeInView(node?: WunderbaumNode, ofs?: number): WunderbaumNode;
+        /**
+         * Append (or insert) a list of toplevel nodes.
+         *
+         * @see {@link WunderbaumNode.addChildren}
+         */
         addChildren(nodeData: any, options?: any): WunderbaumNode;
         /**
-         * Apply a modification (or navigation) operation on the tree or active node.
-         * @returns
+         * Apply a modification (or navigation) operation on the **tree or active node**.
          */
         applyCommand(cmd: ApplyCommandType, opts?: any): any;
         /**
-         * Apply a modification (or navigation) operation on a node.
-         * @returns
+         * Apply a modification (or navigation) operation on a **node**.
+         * @see {@link WunderbaumNode.applyCommand}
          */
         applyCommand(cmd: ApplyCommandType, node: WunderbaumNode, opts?: any): any;
         /** Delete all nodes. */
@@ -1481,10 +1737,11 @@ declare module "wunderbaum" {
         /**
          * Return `tree.option.NAME` (also resolving if this is a callback).
          *
-         * See also [[WunderbaumNode.getOption()]] to consider `node.NAME` setting and
-         * `tree.types[node.type].NAME`.
+         * See also {@link WunderbaumNode.getOption|WunderbaumNode.getOption()}
+         * to evaluate `node.NAME` setting and `tree.types[node.type].NAME`.
          *
-         * @param name option name (use dot notation to access extension option, e.g. `filter.mode`)
+         * @param name option name (use dot notation to access extension option, e.g.
+         * `filter.mode`)
          */
         getOption(name: string, defaultValue?: any): any;
         /**
@@ -1499,28 +1756,46 @@ declare module "wunderbaum" {
         runWithoutUpdate(func: () => any, hint?: any): void;
         /** Recursively expand all expandable nodes (triggers lazy load id needed). */
         expandAll(flag?: boolean): Promise<void>;
+        /** Recursively select all nodes. */
+        selectAll(flag?: boolean): void;
         /** Return the number of nodes in the data model.*/
         count(visible?: boolean): number;
+        /** @internal sanity check. */
         _check(): void;
-        /**Find all nodes that matches condition.
+        /**
+         * Find all nodes that matches condition.
          *
          * @param match title string to search for, or a
          *     callback function that returns `true` if a node is matched.
-         * @see [[WunderbaumNode.findAll]]
+         *
+         * @see {@link WunderbaumNode.findAll}
          */
         findAll(match: string | MatcherType): WunderbaumNode[];
-        /**Find first node that matches condition.
+        /**
+         * 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 [[WunderbaumNode.findFirst]]
+         * @see {@link WunderbaumNode.findFirst}
+         *
          */
         findFirst(match: string | MatcherType): WunderbaumNode;
-        /** Find the next visible node that starts with `match`, starting at `startNode`
+        /**
+         * 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}
+         *
+         */
+        findKey(key: string): WunderbaumNode | undefined;
+        /**
+         * Find the next visible node that starts with `match`, starting at `startNode`
          * and wrap-around at the end.
          */
         findNextNode(match: string | MatcherType, startNode?: WunderbaumNode | null): WunderbaumNode | null;
-        /** Find a node relative to another node.
+        /**
+         * Find a node relative to another node.
          *
          * @param node
          * @param where 'down', 'first', 'last', 'left', 'parent', 'right', or 'up'.
@@ -1530,7 +1805,7 @@ declare module "wunderbaum" {
          */
         findRelatedNode(node: WunderbaumNode, where: string, includeHidden?: boolean): any;
         /**
-         * Return the active cell of the currently active node or null.
+         * Return the active cell (`span.wb-col`) of the currently active node or null.
          */
         getActiveColElem(): HTMLSpanElement;
         /**
@@ -1567,15 +1842,19 @@ declare module "wunderbaum" {
         toString(): string;
         /** Return true if any node is currently in edit-title mode. */
         isEditing(): boolean;
-        /** Return true if any node is currently beeing loaded, i.e. a Ajax request is pending.
+        /**
+         * Return true if any node is currently beeing loaded, i.e. a Ajax request is pending.
          */
         isLoading(): boolean;
-        /** Alias for `logDebug` */
+        /** Alias for {@link Wunderbaum.logDebug}.
+         * @alias Wunderbaum.logDebug
+         */
         log: (...args: any[]) => void;
         /** Log to console if opts.debugLevel >= 4 */
         logDebug(...args: any[]): void;
         /** Log error to console. */
         logError(...args: any[]): void;
+        /** Log to console if opts.debugLevel >= 3 */
         logInfo(...args: any[]): void;
         /** @internal */
         logTime(label: string): string;
@@ -1583,43 +1862,86 @@ declare module "wunderbaum" {
         logTimeEnd(label: string): void;
         /** Log to console if opts.debugLevel >= 2 */
         logWarn(...args: any[]): void;
-        /** */
-        protected render(opts?: any): boolean;
-        /**Recalc and apply header columns from `this.columns`. */
-        renderHeader(): void;
         /**
-         * Make sure that this node is scrolled into the viewport.
+         * Make sure that this node is vertically scrolled into the viewport.
          *
-         * @param {boolean | PlainObject} [effects=false] animation options.
          * @param {object} [options=null] {topNode: null, effects: ..., parent: ...}
          *     this node will remain visible in
          *     any case, even if `this` is outside the scroll pane.
          */
         scrollTo(opts: any): void;
-        /** */
-        setCellMode(mode: NavigationMode): void;
-        /** */
+        /**
+         * Make sure that this node is horizontally scrolled into the viewport.
+         *
+         * Used for `fixedCol` mode.
+         *
+         * @param {boolean | PlainObject} [effects=false] animation options.
+         * @param {object} [options=null] {topNode: null, effects: ..., parent: ...}
+         *     this node will remain visible in
+         *     any case, even if `this` is outside the scroll pane.
+         */
+        scrollToHorz(opts: any): void;
+        /**
+         * Set column #colIdx to 'active'.
+         *
+         * This higlights the column header and -cells by adding the `wb-active` class.
+         * Available in cell-nav and cell-edit mode, not in row-mode.
+         */
         setColumn(colIdx: number): void;
-        /** */
+        /** Set or remove keybaord focus to the tree container. */
+        setActiveNode(key: string, flag?: boolean, options?: SetActiveOptions): void;
+        /** Set or remove keybaord focus to the tree container. */
         setFocus(flag?: boolean): void;
-        /** */
+        /** Schedule an update request to reflect a tree change. */
         setModified(change: ChangeType, options?: any): void;
-        /** */
+        /** Schedule an update request to reflect a single node modification. */
         setModified(change: ChangeType, node: WunderbaumNode, options?: any): void;
+        /** Get the tree's navigation mode. */
+        getNavigationMode(): NavigationMode;
+        /** Set the tree's navigation mode. */
+        setNavigationMode(mode: NavigationMode): void;
+        /** Disable mouse and keyboard interaction (return prev. state). */
+        setEnabled(flag?: boolean): boolean;
+        /** Return false if tree is disabled. */
+        isEnabled(): boolean;
+        /** Return true if tree has one or more data columns in addition to the plain nodes. */
+        isGrid(): boolean;
+        /** Display tree status (ok, loading, error, noData) using styles and a dummy root node. */
         setStatus(status: NodeStatusType, message?: string, details?: string): WunderbaumNode | null;
+        /** Add or redefine node type definitions. */
+        setTypes(types: any, replace?: boolean): void;
         /** Update column headers and width. */
-        updateColumns(opts: any): void;
-        /** Render all rows that are visible in the viewport. */
+        updateColumns(opts?: any): void;
+        /** Create/update header markup from `this.columns` definition.
+         * @internal
+         */
+        protected _renderHeaderMarkup(): void;
+        /** Render header and all rows that are visible in the viewport (async, throttled). */
         updateViewport(immediate?: boolean): void;
+        /**
+         * This is the actual update method, which is wrapped inside a throttle method.
+         * This protected method should not be called directly but via
+         * `tree.updateViewport()` or `tree.setModified()`.
+         * It calls `updateColumns()` and `_updateRows()`.
+         * @internal
+         */
         protected _updateViewport(): void;
-        /** Call callback(node) for all nodes in hierarchical order (depth-first).
+        protected _updateRows(opts?: any): boolean;
+        /**
+         * Call callback(node) for all nodes in hierarchical order (depth-first).
          *
          * @param {function} callback the callback function.
-         *     Return false to stop iteration, return "skip" to skip this node and children only.
+         *     Return false to stop iteration, return "skip" to skip this node and
+         *     children only.
          * @returns {boolean} false, if the iterator was stopped.
          */
         visit(callback: (node: WunderbaumNode) => any): import("common").NodeVisitResponse;
-        /** Call fn(node) for all nodes in vertical order, top down (or bottom up).<br>
+        /**
+         * Call fn(node) for all nodes in vertical order, top down (or bottom up).
+         *
+         * Note that this considers expansion state, i.e. children of collapsed nodes
+         * are skipped.
+         *
          * Stop iteration, if fn() returns false.<br>
          * Return false if iteration was stopped.
          *
@@ -1631,14 +1953,32 @@ declare module "wunderbaum" {
          * @returns {boolean} false if iteration was canceled
          */
         visitRows(callback: (node: WunderbaumNode) => any, opts?: any): boolean;
-        /** Call fn(node) for all nodes in vertical order, bottom up.
+        /**
+         * Call fn(node) for all nodes in vertical order, bottom up.
          * @internal
          */
         protected _visitRowsUp(callback: (node: WunderbaumNode) => any, opts: any): boolean;
-        /** . */
-        load(source: any, options?: any): Promise<void>;
         /**
+         * Reload the tree with a new source.
          *
+         * Previous data is cleared. Note that also column- and type defintions may
+         * be passed with the `source` object.
+         */
+        load(source: any): Promise<void>;
+        /**
+         * Disable render requests during operations that would trigger many updates.
+         *
+         * ```js
+         * try {
+         *   tree.enableUpdate(false);
+         *   // ... (long running operation that would trigger many updates)
+         *   foo();
+         *   // ... NOTE: make sure that async operations have finished, e.g.
+         *   await foo();
+         * } finally {
+         *   tree.enableUpdate(true);
+         * }
+         * ```
          */
         enableUpdate(flag: boolean): void;
         /**