wunderbaum 0.3.2 → 0.3.4

package/src/types.ts

@@ -6,6 +6,7 @@
 
 import { WunderbaumNode } from "./wb_node";
 import { Wunderbaum } from "./wunderbaum";
+import { WunderbaumOptions } from "./wb_options";
 
 /** Passed to `find...()` methods. Should return true if node matches. */
 export type MatcherCallback = (node: WunderbaumNode) => boolean;
@@ -17,14 +18,34 @@ export type BoolOptionResolver = (node: WunderbaumNode) => boolean;
 export type BoolOrStringOptionResolver = (
   node: WunderbaumNode
 ) => boolean | string;
-
+/** A callback that receives a node instance and returns an arbitrary value type. */
 export type NodeAnyCallback = (node: WunderbaumNode) => any;
+/** A callback that receives a node instance and returns a string value. */
 export type NodeStringCallback = (node: WunderbaumNode) => string;
-
-export type NodeVisitResponse = "skip" | boolean | void;
+/** A callback that receives a node instance and returns an iteration modifier. */
 export type NodeVisitCallback = (node: WunderbaumNode) => NodeVisitResponse;
+/** A callback that receives a node instance and returns a string value. */
+export type NodeVisitResponse = "skip" | boolean | void;
+/** A callback that receives a node-data dictionary and a node instance and returns an iteration modifier. */
+export type NodeToDictCallback = (
+  dict: WbNodeData,
+  node: WunderbaumNode
+) => NodeVisitResponse;
 
 // type WithWildcards<T> = T & { [key: string]: unknown };
+/** A plain object (dictionary) that represents a node instance. */
+export interface WbNodeData {
+  title: string;
+  key?: string;
+  refKey?: string;
+  expanded?: boolean;
+  selected?: boolean;
+  checkbox?: boolean | string;
+  colspan?: boolean;
+  children?: Array<WbNodeData>;
+  treeId?: string;
+  // ...any?: Any;
+}
 
 /* -----------------------------------------------------------------------------
  * EVENT CALLBACK TYPES
@@ -99,7 +120,7 @@ export interface WbKeydownEventType extends WbTreeEventType {
   event: KeyboardEvent;
   node: WunderbaumNode;
   info: WbEventInfo;
-  /** Canical name of the key including modifiers. @see {@link eventToString} */
+  /** Canical name of the key including modifiers. @see {@link util.eventToString} */
   eventName: string;
 }
 
@@ -168,7 +189,7 @@ export type NodeTypeDefinitionMap = { [type: string]: NodeTypeDefinition };
 
 /**
  * Column type definitions.
- * @see {@link `Wunderbaum.columns`}
+ * @see {@link Wunderbaum.columns}
  */
 export interface ColumnDefinition {
   /** Column ID as defined in `tree.columns` definition ("*" for title column). */
@@ -380,7 +401,7 @@ export interface MakeVisibleOptions {
   noEvents?: boolean;
 }
 
-/** Possible values for {@link Wunderbaum.navigate()}. */
+/** Possible values for {@link WunderbaumNode.navigate()}. */
 export interface NavigateOptions {
   /** Activate the new node (otherwise focus only). @default true */
   activate?: boolean;
@@ -406,7 +427,7 @@ export interface RenderOptions {
   resizeCols?: boolean;
 }
 
-/** Possible values for {@link scrollIntoView()} `options` argument. */
+/** Possible values for {@link WunderbaumNode.scrollIntoView()} `options` argument. */
 export interface ScrollIntoViewOptions {
   /** Do not animate (currently not implemented). @default false */
   noAnimation?: boolean;
@@ -436,13 +457,13 @@ export interface SetActiveOptions {
   focusTree?: boolean;
   /** Optional original event that will be passed to the (de)activate handler. */
   event?: Event;
-  /** Call {@link setColumn}. */
+  /** Call {@link Wunderbaum.setColumn}. */
   colIdx?: number;
 }
 
 /** Possible values for {@link WunderbaumNode.setExpanded()} `options` argument. */
 export interface SetExpandedOptions {
-  /** Ignore {@link minExpandLevel}. @default false */
+  /** Ignore {@link WunderbaumOptions.minExpandLevel}. @default false */
   force?: boolean;
   /** Immediately update viewport (async otherwise). @default false */
   immediate?: boolean;

package/src/wb_ext_edit.ts

@@ -17,8 +17,7 @@ import {
 } from "./util";
 import { debounce } from "./debounce";
 import { WunderbaumNode } from "./wb_node";
-import { InsertNodeType } from "./types";
-import { WbNodeData } from "./wb_options";
+import { InsertNodeType, WbNodeData } from "./types";
 
 // const START_MARKER = "\uFFF7";
 

package/src/wb_node.ts

@@ -31,6 +31,8 @@ import {
   SetSelectedOptions,
   SetStatusOptions,
   SortCallback,
+  NodeToDictCallback,
+  WbNodeData,
 } from "./types";
 import {
   iconMap,
@@ -45,7 +47,6 @@ import {
   nodeTitleSorter,
 } from "./common";
 import { Deferred } from "./deferred";
-import { WbNodeData } from "./wb_options";
 
 /** Top-level properties that can be passed with `data`. */
 const NODE_PROPS = new Set<string>([
@@ -330,7 +331,7 @@ export class WunderbaumNode {
    *
    * This a convenience function that calls addChildren()
    *
-   * @param {NodeData} node node definition
+   * @param nodeData node definition
    * @param [mode=child] 'before', 'after', 'firstChild', or 'child' ('over' is a synonym for 'child')
    * @returns new node
    */
@@ -1857,9 +1858,9 @@ export class WunderbaumNode {
    *     modifications.
    *     Return `false` to ignore this node or `"skip"` to include this node
    *     without its children.
-   * @returns {NodeData}
+   * @see {@link Wunderbaum.toDictArray}.
    */
-  toDict(recursive = false, callback?: any): any {
+  toDict(recursive = false, callback?: NodeToDictCallback): WbNodeData {
     const dict: any = {};
 
     NODE_ATTRS.forEach((propName: string) => {
@@ -1883,7 +1884,8 @@ export class WunderbaumNode {
     if (callback) {
       const res = callback(dict, this);
       if (res === false) {
-        return false; // Don't include this node nor its children
+        // Note: a return value of `false` is only used internally
+        return <any>false; // Don't include this node nor its children
       }
       if (res === "skip") {
         recursive = false; // Include this node, but not the children
@@ -1895,7 +1897,8 @@ export class WunderbaumNode {
         for (let i = 0, l = this.children!.length; i < l; i++) {
           const node = this.children![i];
           if (!node.isStatusNode()) {
-            const res = node.toDict(true, callback);
+            // Note: a return value of `false` is only used internally
+            const res = <any>node.toDict(true, callback);
             if (res !== false) {
               dict.children.push(res);
             }
@@ -2281,7 +2284,7 @@ export class WunderbaumNode {
    * @param {function} callback the callback function.
    *     Return false to stop iteration, return "skip" to skip this node and
    *     its children only.
-   * @see {@link WunderbaumNode.*[Symbol.iterator]}, {@link Wunderbaum.visit}.
+   * @see {@link IterableIterator<WunderbaumNode>}, {@link Wunderbaum.visit}.
    */
   visit(
     callback: NodeVisitCallback,

package/src/wb_options.ts

@@ -18,24 +18,13 @@ import {
   WbErrorEventType,
   WbInitEventType,
   WbKeydownEventType,
+  WbNodeData,
   WbNodeEventType,
   WbReceiveEventType,
   WbRenderEventType,
   WbTreeEventType,
 } from "./types";
 
-export interface WbNodeData {
-  title: string;
-  key?: string;
-  refKey?: string;
-  expanded?: boolean;
-  selected?: boolean;
-  checkbox?: boolean | string;
-  colspan?: boolean;
-  children?: Array<WbNodeData>;
-  // ...any?: Any;
-}
-
 /**
  * Available options for [[Wunderbaum]].
  *