wunderbaum 0.6.0 → 0.8.0

package/src/common.ts

@@ -4,7 +4,7 @@
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
-import { MatcherCallback } from "./types";
+import { MatcherCallback, SourceListType, SourceObjectType } from "./types";
 import * as util from "./util";
 import { WunderbaumNode } from "./wb_node";
 
@@ -101,9 +101,10 @@ export const INPUT_KEYS: { [key: string]: Array<string> } = {
 /** Dict keys that are evaluated by source loader (others are added to `tree.data` instead). */
 export const RESERVED_TREE_SOURCE_KEYS: Set<string> = new Set([
   "_format", // reserved for future use
-  "_keyMap", // reserved for future use
-  "_positional", // reserved for future use
-  "_typeList", // reserved for future use
+  "_keyMap", // Used for compressed data format
+  "_positional", // Used for compressed data format
+  "_typeList", // Used for compressed data format @deprecated
+  "_valueMap", // Used for compressed data format
   "_version", // reserved for future use
   "children",
   "columns",
@@ -146,7 +147,7 @@ export const KEY_TO_ACTION_DICT: { [key: string]: string } = {
 
 /** Return a callback that returns true if the node title matches the string
  * or regular expression.
- * @see {@link WunderbaumNode.findAll}
+ * @see {@link WunderbaumNode.findAll()}
  */
 export function makeNodeTitleMatcher(match: string | RegExp): MatcherCallback {
   if (match instanceof RegExp) {
@@ -184,8 +185,20 @@ export function nodeTitleSorter(a: WunderbaumNode, b: WunderbaumNode): number {
   return x === y ? 0 : x > y ? 1 : -1;
 }
 
-function unflattenSource(source: any): void {
-  const { _format, _keyMap, _positional, children } = source;
+/**
+ * Convert 'flat' to 'nested' format.
+ *
+ *  Flat node entry format:
+ *    [PARENT_ID, [POSITIONAL_ARGS]]
+ *  or
+ *    [PARENT_ID, [POSITIONAL_ARGS], {KEY_VALUE_ARGS}]
+ *
+ * 1. Parent-referencing list is converted to a list of nested dicts with
+ *    optional `children` properties.
+ * 2. `[POSITIONAL_ARGS]` are added as dict attributes.
+ */
+function unflattenSource(source: SourceObjectType): void {
+  const { _format, _keyMap = {}, _positional = [], children } = source;
 
   if (_format !== "flat") {
     throw new Error(`Expected source._format: "flat", but got ${_format}`);
@@ -195,31 +208,35 @@ function unflattenSource(source: any): void {
       `source._positional must not include "children": ${_positional}`
     );
   }
-  // Inverse keyMap:
-  const longToShort: any = {};
-  if (_keyMap) {
+  let longToShort = _keyMap;
+  if (_keyMap.t) {
+    // Inverse keyMap was used (pre 0.7.0)
+    // TODO: raise Error on final 1.x release
+    const msg = `source._keyMap maps from long to short since v0.7.0. Flip key/value!`;
+    console.warn(msg); // eslint-disable-line no-console
+    longToShort = {};
     for (const [key, value] of Object.entries(_keyMap)) {
-      longToShort[<string>value] = key;
+      longToShort[value] = key;
     }
   }
   const positionalShort = _positional.map((e: string) => longToShort[e]);
-  const newChildren: any[] = [];
+  const newChildren: SourceListType = [];
   const keyToNodeMap: { [key: string]: number } = {};
   const indexToNodeMap: { [key: number]: any } = {};
   const keyAttrName = longToShort["key"] ?? "key";
   const childrenAttrName = longToShort["children"] ?? "children";
 
-  for (const [index, node] of children.entries()) {
+  for (const [index, nodeTuple] of children.entries()) {
     // Node entry format:
     //   [PARENT_ID, [POSITIONAL_ARGS]]
     // or
     //   [PARENT_ID, [POSITIONAL_ARGS], {KEY_VALUE_ARGS}]
-    const [parentId, args, kwargs = {}] = node;
+    const [parentId, args, kwargs = {}] = <any>nodeTuple;
 
     // Free up some memory as we go
-    node[1] = null;
-    if (node[2] != null) {
-      node[2] = null;
+    nodeTuple[1] = null;
+    if (nodeTuple[2] != null) {
+      nodeTuple[2] = null;
     }
     // console.log("flatten", parentId, args, kwargs)
 
@@ -262,13 +279,52 @@ function unflattenSource(source: any): void {
       newChildren.push(kwargs);
     }
   }
-
-  delete source.children;
   source.children = newChildren;
 }
 
-export function inflateSourceData(source: any): void {
-  const { _format, _keyMap, _typeList } = source;
+/**
+ * Decompresses the source data by
+ * - converting from 'flat' to 'nested' format
+ * - expanding short alias names to long names (if defined in _keyMap)
+ * - resolving value indexes to value strings (if defined in _valueMap)
+ *
+ * @param source - The source object to be decompressed.
+ * @returns void
+ */
+export function decompressSourceData(source: SourceObjectType): void {
+  let { _format, _version = 1, _keyMap, _valueMap } = source;
+
+  util.assert(_version === 1, `Expected file version 1 instead of ${_version}`);
+
+  let longToShort = _keyMap;
+  let shortToLong: { [key: string]: string } = {};
+
+  if (longToShort) {
+    for (const [key, value] of Object.entries(longToShort)) {
+      shortToLong[value] = key;
+    }
+  }
+
+  // Fallback for old format (pre 0.7.0, using _keyMap in reverse direction)
+  // TODO: raise Error on final 1.x release
+  if (longToShort && longToShort.t) {
+    const msg = `source._keyMap maps from long to short since v0.7.0. Flip key/value!`;
+    console.warn(msg); // eslint-disable-line no-console
+    [longToShort, shortToLong] = [shortToLong, longToShort];
+  }
+
+  // Fallback for old format (pre 0.7.0, using _typeList instead of _valueMap)
+  // TODO: raise Error on final 1.x release
+  if ((<any>source)._typeList != null) {
+    const msg = `source._typeList is deprecated since v0.7.0: use source._valueMap: {"type": [...]} instead.`;
+    if (_valueMap != null) {
+      throw new Error(msg);
+    } else {
+      console.warn(msg); // eslint-disable-line no-console
+      _valueMap = { type: (<any>source)._typeList };
+      delete (<any>source)._typeList;
+    }
+  }
 
   if (_format === "flat") {
     unflattenSource(source);
@@ -276,33 +332,40 @@ export function inflateSourceData(source: any): void {
   delete source._format;
   delete source._version;
   delete source._keyMap;
-  delete source._typeList;
+  delete source._valueMap;
   delete source._positional;
 
-  function _iter(childList: any[]) {
+  function _iter(childList: SourceListType) {
     for (const node of childList) {
-      // Expand short alias names
-      if (_keyMap) {
-        // Iterate over a list of names, because we modify inside the loop:
-        Object.getOwnPropertyNames(node).forEach((propName) => {
-          const long = _keyMap[propName] ?? propName;
-          if (long !== propName) {
-            node[long] = node[propName];
+      // Iterate over a list of names, because we modify inside the loop
+      // (for ... of ... does not allow this)
+      Object.getOwnPropertyNames(node).forEach((propName) => {
+        const value: any = node[propName];
+
+        // Replace short names with long names if defined in _keyMap
+        let longName = propName;
+        if (_keyMap && shortToLong[propName] != null) {
+          longName = shortToLong[propName];
+          if (longName !== propName) {
+            node[longName] = value;
             delete node[propName];
           }
-        });
-      }
-      // `node` now has long attribute names
-
-      // Resolve node type indexes
-      const type = node.type;
-      if (_typeList && type != null && typeof type === "number") {
-        const newType = _typeList[type];
-        if (newType == null) {
-          throw new Error(`Expected typeList[${type}] entry in [${_typeList}]`);
         }
-        node.type = newType;
-      }
+        // Replace type index with type name if defined in _valueMap
+        if (
+          _valueMap &&
+          typeof value === "number" &&
+          _valueMap[longName] != null
+        ) {
+          const newValue = _valueMap[longName][value];
+          if (newValue == null) {
+            throw new Error(
+              `Expected valueMap[${longName}][${value}] entry in [${_valueMap[longName]}]`
+            );
+          }
+          node[longName] = newValue;
+        }
+      });
 
       // Recursion
       if (node.children) {
@@ -310,5 +373,7 @@ export function inflateSourceData(source: any): void {
       }
     }
   }
-  _iter(source.children);
+  if (_keyMap || _valueMap) {
+    _iter(source.children);
+  }
 }

package/src/deferred.ts

@@ -22,38 +22,38 @@ type finallyCallbackType = () => void;
  * }
  * ```
  */
-export class Deferred {
-  private _promise: Promise<any>;
+export class Deferred<T> {
+  private _promise: Promise<T>;
   protected _resolve: any;
   protected _reject: any;
 
   constructor() {
-    this._promise = new Promise((resolve, reject) => {
+    this._promise = new Promise<T>((resolve, reject) => {
       this._resolve = resolve;
       this._reject = reject;
     });
   }
-  /** Resolve the [[Promise]]. */
+  /** Resolve the Promise. */
   resolve(value?: any) {
     this._resolve(value);
   }
-  /** Reject the [[Promise]]. */
+  /** Reject the Promise. */
   reject(reason?: any) {
     this._reject(reason);
   }
-  /** Return the native [[Promise]] instance.*/
+  /** Return the native Promise instance.*/
   promise() {
     return this._promise;
   }
-  /** Call [[Promise.then]] on the embedded promise instance.*/
+  /** Call Promise.then on the embedded promise instance.*/
   then(cb: PromiseCallbackType) {
     return this._promise.then(cb);
   }
-  /** Call [[Promise.catch]] on the embedded promise instance.*/
+  /** Call Promise.catch on the embedded promise instance.*/
   catch(cb: PromiseCallbackType) {
     return this._promise.catch(cb);
   }
-  /** Call [[Promise.finally]] on the embedded promise instance.*/
+  /** Call Promise.finally on the embedded promise instance.*/
   finally(cb: finallyCallbackType) {
     return this._promise.finally(cb);
   }

package/src/types.ts

@@ -33,12 +33,14 @@ export interface SourceAjaxType {
 export type SourceListType = Array<WbNodeData>;
 export interface SourceObjectType {
   _format?: "nested" | "flat";
+  _version?: number;
   types?: NodeTypeDefinitionMap;
   columns?: ColumnDefinitionList;
   children: SourceListType;
   _keyMap?: { [key: string]: string };
-  _typeList?: Array<string>;
   _positional?: Array<string>;
+  // _typeList?: Array<string>;
+  _valueMap?: { [key: string]: Array<string> };
 }
 
 /** Possible initilization for tree nodes. */
@@ -153,32 +155,67 @@ export interface WbActivateEventType extends WbNodeEventType {
 }
 
 export interface WbChangeEventType extends WbNodeEventType {
+  /** Additional information derived from the original change event. */
   info: WbEventInfo;
-  inputElem: HTMLInputElement;
+  /** The embedded element that fired the change event. */
+  inputElem: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+  /** The new value of the embedded element, depending on the input element type. */
   inputValue: any;
+  /** Result of `inputElem.checkValidity()`. */
+  inputValid: boolean;
 }
 
 export interface WbClickEventType extends WbTreeEventType {
   /** The original event. */
   event: MouseEvent;
+  /** The clicked node if any. */
   node: WunderbaumNode;
+  /** Additional information derived from the original mouse event. */
   info: WbEventInfo;
 }
 
-export interface WbErrorEventType extends WbNodeEventType {
-  error: any;
-}
-
 export interface WbDeactivateEventType extends WbNodeEventType {
   nextNode: WunderbaumNode;
   /** The original event. */
   event: Event;
 }
 
+export interface WbEditApplyEventType extends WbNodeEventType {
+  /** Additional information derived from the original change event. */
+  info: WbEventInfo;
+  /** The input element of the node title that fired the change event. */
+  inputElem: HTMLInputElement;
+  /** The previous node title. */
+  oldValue: string;
+  /** The new node title. */
+  newValue: string;
+  /** Result of `inputElem.checkValidity()`. */
+  inputValid: boolean;
+}
+
+export interface WbEditEditEventType extends WbNodeEventType {
+  /** The input element of the node title that was just created. */
+  inputElem: HTMLInputElement;
+}
+
 // export interface WbEnhanceTitleEventType extends WbNodeEventType {
 //   titleSpan: HTMLSpanElement;
 // }
 
+export interface WbErrorEventType extends WbNodeEventType {
+  error: any;
+}
+export interface WbExpandEventType extends WbNodeEventType {
+  flag: boolean;
+}
+
+export interface WbFocusEventType extends WbTreeEventType {
+  /** The original event. */
+  event: FocusEvent;
+  /** True if `focusin`, false if `focusout`. */
+  flag: boolean;
+}
+
 export interface WbIconBadgeEventType extends WbNodeEventType {
   iconSpan: HTMLElement;
 }
@@ -191,33 +228,32 @@ export interface WbIconBadgeEventResultType {
   badgeTooltip?: string;
 }
 
-export interface WbFocusEventType extends WbTreeEventType {
-  /** The original event. */
-  event: FocusEvent;
-  /** True if `focusin`, false if `focusout`. */
-  flag: boolean;
+export interface WbInitEventType extends WbTreeEventType {
+  error?: any;
 }
 
 export interface WbKeydownEventType extends WbTreeEventType {
   /** The original event. */
   event: KeyboardEvent;
   node: WunderbaumNode;
+  /** Additional information derived from the original keyboard event. */
   info: WbEventInfo;
 }
 
-export interface WbInitEventType extends WbTreeEventType {
-  error?: any;
-}
-
 export interface WbReceiveEventType extends WbNodeEventType {
   response: any;
 }
+export interface WbSelectEventType extends WbNodeEventType {
+  flag: boolean;
+}
 
 export interface WbRenderEventType extends WbNodeEventType {
   /**
    * True if the node's markup was not yet created. In this case the render
    * event should create embedded input controls (in addition to update the
-   * values according to to current node data).
+   * values according to to current node data). <br>
+   * False if the node's markup was already created. In this case the render
+   * event should only update the values according to to current node data.
    */
   isNew: boolean;
   /** The node's `<span class='wb-node'>` element. */
@@ -231,9 +267,20 @@ export interface WbRenderEventType extends WbNodeEventType {
    */
   allColInfosById: ColumnEventInfoMap;
   /**
-   * Array of node's `<span class='wb-node'>` elements, *that should be rendered*.
+   * Array of node's `<span class='wb-node'>` elements,
+   * *that should be rendered by the event handler*.
    * In contrast to `allColInfosById`, the node title is not part of this array.
    * If node.isColspan() is true, this array is empty (`[]`).
+   * This allows to iterate over all relevant in a simple loop:
+   * ```
+   * for (const col of Object.values(e.renderColInfosById)) {
+   *   switch (col.id) {
+   *     default:
+   *       // Assumption: we named column.id === node.data.NAME
+   *       col.elem.textContent = node.data[col.id];
+   *       break;
+   *   }
+   * }
    */
   renderColInfosById: ColumnEventInfoMap;
 }
@@ -290,15 +337,17 @@ export interface ColumnDefinition {
    * elements of that column.
    */
   classes?: string;
-  /** If `headerClasses` is a string, it will be used for the header element,
-   * while `classes` is used for data elements.
+  /** If `headerClasses` is a set, it will be used for the header element only
+   * (unlike `classes`, which is used for body and header cells).
    */
   headerClasses?: string;
   /** Optional HTML content that is rendered into all `span.wb-col` elements of that column.*/
   html?: string;
-  // Internal use:
+  /** @internal */
   _weight?: number;
+  /** @internal */
   _widthPx?: number;
+  /** @internal */
   _ofsPx?: number;
   // ... and more
   [key: string]: unknown;
@@ -323,7 +372,7 @@ export interface ColumnEventInfo {
 export type ColumnEventInfoMap = { [colId: string]: ColumnEventInfo };
 
 /**
- * Additional inforation derived from mouse or keyboard events.
+ * Additional information derived from mouse or keyboard events.
  * @see {@link Wunderbaum.getEventInfo}
  */
 export interface WbEventInfo {
@@ -540,23 +589,43 @@ export interface ScrollToOptions extends ScrollIntoViewOptions {
   node: WunderbaumNode;
 }
 
-/** Possible values for {@link WunderbaumNode.setActive()} `options` argument. */
+/** Possible values for {@link WunderbaumNode.setActive} `options` argument. */
 export interface SetActiveOptions {
-  /** Generate (de)activate event, even if node already has this status (default: false). */
+  /** Generate (de)activate event, even if node already has this status (@default: false). */
   retrigger?: boolean;
-  /** Do not generate (de)activate event  (default: false). */
+  /** Do not generate (de)activate event  (@default: false). */
   noEvents?: boolean;
-  /** Set node as focused node (default: true). */
-  focusNode?: boolean;
-  /** Set node as focused node (default: false). */
+  // /** Mark node as focused node (default: true).
+  //  * Combine with `focusTree: true` to set keyboard focus to tree container.
+  //  */
+  // focusNode?: boolean;
+  /** Call `tree.setFocus()` to acquire keyboard focus (@default: false). */
   focusTree?: boolean;
   /** Optional original event that will be passed to the (de)activate handler. */
   event?: Event;
-  /** Call {@link Wunderbaum.setColumn}. */
-  colIdx?: number;
+  /** Also call {@link Wunderbaum.setColumn()}. */
+  colIdx?: number | string;
+  /**
+   * Focus embedded input control of the grid cell if any (requires colIdx >= 0).
+   * If colIdx is 0 or '*', the node title is put into edit mode.
+   * Implies `focusTree: true`, requires `colIdx`.
+   */
+  edit?: boolean;
 }
 
-/** Possible values for {@link WunderbaumNode.setExpanded()} `options` argument. */
+/** Possible values for {@link WunderbaumNode.setColumn()} `options` argument. */
+export interface SetColumnOptions {
+  /**
+   * Focus embedded input control of the grid cell if any .
+   * If colIdx is 0 or '*', the node title is put into edit mode.
+   * @default false
+   */
+  edit?: boolean;
+  /** Horizontically scroll into view. @default: true */
+  scrollIntoView?: boolean;
+}
+
+/** Possible values for {@link WunderbaumNode.setExpanded} `options` argument. */
 export interface SetExpandedOptions {
   /** Ignore {@link WunderbaumOptions.minExpandLevel}. @default false */
   force?: boolean;
@@ -665,53 +734,70 @@ export type FilterOptionsType = {
    * Grayout unmatched nodes (pass "hide" to remove unmatched node instead)
    * @default 'dim'
    */
-  mode?: "dim" | "hide";
+  mode?: FilterModeType;
   /**
-   * Display a 'no data' status node if result is empty
+   * Display a 'no data' status node if result is empty (hide-mode only).
+   * Pass false to simply show an empy pane, or pass a string to customize the message.
    * @default true
    */
-  noData?: boolean;
+  noData?: boolean | string;
 };
 
+/**
+ * Note: <br>
+ * This options are used for renaming node titles. <br>
+ * There is also the `tree.change` event to handle modifying node data from
+ * input controls that are embedded in grid cells.
+ */
 export type EditOptionsType = {
   /**
+   * Used to debounce the `change` event handler for grid cells [ms].
    * @default 100
    */
   debounce?: number;
   /**
+   * Minimum number of characters required for node title input field.
    * @default 1
    */
   minlength?: number;
   /**
+   * Maximum number of characters allowed for node title input field.
    * @default null;
    */
   maxlength?: null | number;
   /**
-   * ["clickActive", "F2", "macEnter"],
+   * Array of strings to determine which user input should trigger edit mode.
+   * E.g. `["clickActive", "F2", "macEnter"]`: <br>
+   * 'clickActive': single click on active node title <br>
+   * 'F2': press F2 key <br>
+   * 'macEnter': press Enter (on macOS only) <br>
+   * Pass an empty array to disable edit mode.
    * @default []
    */
   trigger?: string[];
   /**
+   * Trim whitespace before saving a node title.
    * @default true
    */
   trim?: boolean;
   /**
+   * Select all text of a node title, so it can be overwritten by typing.
    * @default true
    */
   select?: boolean;
   /**
-   * Handle 'clickActive' only if last click is less than this old (0: always)
+   * Handle 'clickActive' only if last click is less than this ms old (0: always)
    * @default 1000
    */
   slowClickDelay?: number;
   /**
-   * Please enter a title",
+   * Permanently apply node title input validations (CSS and tooltip) on keydown.
    * @default true
    */
   validity?: boolean;
 
   // --- Events ---
-  // (note: there is also the `tree.change` event.)
+
   /**
    * `beforeEdit(e)` may return an input HTML string. Otherwise use a default.
    */