wunderbaum 0.2.0 → 0.3.0

package/src/types.ts

@@ -1,14 +1,16 @@
 /*!
  * Wunderbaum - types
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
 import { WunderbaumNode } from "./wb_node";
 import { Wunderbaum } from "./wunderbaum";
 
-/** Passed to find... methods. Should return true if node matches. */
+/** Passed to `find...()` methods. Should return true if node matches. */
 export type MatcherCallback = (node: WunderbaumNode) => boolean;
+/** Passed to `sortChildren()` methods. Should return -1, 0, or 1. */
+export type SortCallback = (a: WunderbaumNode, b: WunderbaumNode) => number;
 /** When set as option, called when the value is needed (e.g. `colspan` type definition). */
 export type BoolOptionResolver = (node: WunderbaumNode) => boolean;
 /** When set as option, called when the value is needed (e.g. `icon` type definition). */
@@ -33,9 +35,11 @@ export interface WbTreeEventType {
   type: string;
   /** The affected tree instance. */
   tree: Wunderbaum;
-  /** Exposed utility module methods. */
+  /** Exposed utility module methods
+   * (see [API docs](https://mar10.github.io/wunderbaum/api/modules/util.html)).
+   */
   util: any;
-  /** Originating HTML event, e.g. `click` if any. */
+  /** Originating HTML event if any (e.g. `click`). */
   event?: Event;
   // [key: string]: unknown;
 }
@@ -238,51 +242,61 @@ export interface WbEventInfo {
 
 export type FilterModeType = null | "dim" | "hide";
 export type ApplyCommandType =
-  | "moveUp"
-  | "moveDown"
-  | "indent"
-  | "outdent"
-  | "remove"
-  | "rename"
   | "addChild"
   | "addSibling"
-  | "cut"
   | "copy"
-  | "paste"
+  | "cut"
   | "down"
   | "first"
+  | "indent"
   | "last"
   | "left"
+  | "moveDown"
+  | "moveUp"
+  | "outdent"
   | "pageDown"
   | "pageUp"
   | "parent"
+  | "paste"
+  | "remove"
+  | "rename"
   | "right"
   | "up";
 
 export type NodeFilterResponse = "skip" | "branch" | boolean | void;
 export type NodeFilterCallback = (node: WunderbaumNode) => NodeFilterResponse;
-export type AddNodeType = "before" | "after" | "prependChild" | "appendChild";
-export type DndModeType = "before" | "after" | "over";
 
-/** Possible values for `setModified()`. */
+/**
+ * Possible values for {@link WunderbaumNode.setModified()} and {@link Wunderbaum.setModified()}.
+ */
 export enum ChangeType {
   /** Re-render the whole viewport, headers, and all rows. */
   any = "any",
-  /** Update current row title, icon, columns, and status. */
+  /** A node's title, icon, columns, or status have changed. Update the existing row markup. */
   data = "data",
-  /** Redraw the header and update the width of all row columns. */
-  header = "header",
-  /** Re-render the whole current row. */
+  /** The `tree.columns` definition has changed beyond simple width adjustments. */
+  colStructure = "colStructure",
+  /** The viewport/window was resized. Adjust layout attributes for all elements. */
+  resize = "resize",
+  /** A node's definition has changed beyond status and data. Re-render the whole row's markup. */
   row = "row",
-  /** Alias for 'any'. */
+  /** Nodes have been added, removed, etc. Update markup. */
   structure = "structure",
-  /** Update current row's classes, to reflect active, selected, ... */
+  /** A node's status has changed. Update current row's classes, to reflect active, selected, ... */
   status = "status",
-  /** Update the 'top' property of all rows. */
-  vscroll = "vscroll",
+  /** Vertical scroll event. Update the 'top' property of all rows. */
+  scroll = "scroll",
+}
+
+/* Internal use. */
+export enum RenderFlag {
+  clearMarkup = "clearMarkup",
+  header = "header",
+  redraw = "redraw",
+  scroll = "scroll",
 }
 
-/** Possible values for `setStatus()`. */
+/** Possible values for {@link WunderbaumNode.setStatus()}. */
 export enum NodeStatusType {
   ok = "ok",
   loading = "loading",
@@ -368,22 +382,31 @@ export interface MakeVisibleOptions {
 
 /** Possible values for {@link Wunderbaum.navigate()}. */
 export interface NavigateOptions {
+  /** Activate the new node (otherwise focus only). @default true */
   activate?: boolean;
+  /** Originating event (e.g. KeyboardEvent) if any. */
   event?: Event;
 }
 
 /** Possible values for {@link WunderbaumNode.render()}. */
 export interface RenderOptions {
+  /** Which parts need update? @default ChangeType.data */
   change?: ChangeType;
+  /** Where to append a new node. @default 'last' */
   after?: any;
+  /** @internal. @default false */
   isNew?: boolean;
+  /** @internal. @default false */
   preventScroll?: boolean;
+  /** @internal. @default false */
   isDataChange?: boolean;
+  /** @internal. @default false */
   top?: number;
+  /** @internal. @default true */
   resizeCols?: boolean;
 }
 
-/** Possible values for {@link scrollIntoView()}. */
+/** Possible values for {@link scrollIntoView()} `options` argument. */
 export interface ScrollIntoViewOptions {
   /** Do not animate (currently not implemented). @default false */
   noAnimation?: boolean;
@@ -395,13 +418,13 @@ export interface ScrollIntoViewOptions {
   ofsY?: number;
 }
 
-/** Possible values for {@link Wunderbaum.scrollTo()}. */
+/** Possible values for {@link Wunderbaum.scrollTo()} `options` argument. */
 export interface ScrollToOptions extends ScrollIntoViewOptions {
   /** Which node to scroll into the viewport.*/
   node: WunderbaumNode;
 }
 
-/** Possible values for `node.setActive()`. */
+/** Possible values for {@link WunderbaumNode.setActive()} `options` argument. */
 export interface SetActiveOptions {
   /** Generate (de)activate event, even if node already has this status (default: false). */
   retrigger?: boolean;
@@ -417,7 +440,7 @@ export interface SetActiveOptions {
   colIdx?: number;
 }
 
-/** Possible values for `node.setExpanded()`. */
+/** Possible values for {@link WunderbaumNode.setExpanded()} `options` argument. */
 export interface SetExpandedOptions {
   /** Ignore {@link minExpandLevel}. @default false */
   force?: boolean;
@@ -431,15 +454,15 @@ export interface SetExpandedOptions {
   scrollIntoView?: boolean;
 }
 
-/** Possible values for `node.setSetModified()`. */
+/** Possible values for {@link WunderbaumNode.setModified()} `options` argument. */
 export interface SetModifiedOptions {
   /** Force immediate redraw instead of throttled/async mode. @default false */
   immediate?: boolean;
-  /** Remove HTML markup of all rendered nodes before redraw. @default false */
-  removeMarkup?: boolean;
+  // /** Remove HTML markup of all rendered nodes before redraw. @default false */
+  // removeMarkup?: boolean;
 }
 
-/** Possible values for `node.setSelected()`. */
+/** Possible values for {@link WunderbaumNode.setSelected()} `options` argument. */
 export interface SetSelectedOptions {
   /** Ignore restrictions. @default false */
   force?: boolean;
@@ -447,7 +470,7 @@ export interface SetSelectedOptions {
   noEvents?: boolean;
 }
 
-/** Possible values for `node.setSetModified()`. */
+/** Possible values for {@link WunderbaumNode.setStatus()} `options` argument. */
 export interface SetStatusOptions {
   /** Displayed as status node title. */
   message?: string;
@@ -455,25 +478,31 @@ export interface SetStatusOptions {
   details?: string;
 }
 
-/** Possible values for {@link Wunderbaum.updateColumns()}. */
-export interface UpdateColumnsOptions {
-  calculateCols?: boolean;
-  updateRows?: boolean;
-}
-
-/** Possible values for {@link Wunderbaum.visitRows()} and {@link Wunderbaum.visitRowsUp()}. */
+/** Options passed to {@link Wunderbaum.visitRows()}. */
 export interface VisitRowsOptions {
-  reverse?: boolean;
-  includeSelf?: boolean;
+  /** Skip filtered nodes and children of collapsed nodes. @default false */
   includeHidden?: boolean;
-  wrap?: boolean;
+  /** Return the start node as first result. @default true */
+  includeSelf?: boolean;
+  /** Traverse in opposite direction, i.e. bottom up. @default false */
+  reverse?: boolean;
+  /** Start traversal at this node @default first (topmost) tree node */
   start?: WunderbaumNode | null;
+  /** Wrap around at last node and continue at the top,
+   * until the start node is reached again @default false */
+  wrap?: boolean;
 }
 
 /* -----------------------------------------------------------------------------
  * wb_ext_dnd
  * ---------------------------------------------------------------------------*/
 
+export type InsertNodeType =
+  | "before"
+  | "after"
+  | "prependChild"
+  | "appendChild";
+// export type DndModeType = "before" | "after" | "over";
 export type DropRegionType = "over" | "before" | "after";
 export type DropRegionTypeSet = Set<DropRegionType>;
 // type AllowedDropRegionType =
@@ -490,140 +519,140 @@ export type DropRegionTypeSet = Set<DropRegionType>;
 export type DndOptionsType = {
   /**
    * Expand nodes after n milliseconds of hovering
-   * Default: 1500
+   * @default 1500
    */
   autoExpandMS: 1500;
   // /**
   //  * Additional offset for drop-marker with hitMode = "before"/"after"
-  //  * Default:
+  //  * @default
   //  */
   // dropMarkerInsertOffsetX: -16;
   // /**
   //  * Absolute position offset for .fancytree-drop-marker relatively to ..fancytree-title (icon/img near a node accepting drop)
-  //  * Default:
+  //  * @default
   //  */
   // dropMarkerOffsetX: -24;
   // /**
   //  * Root Container used for drop marker (could be a shadow root)
   //  * (#1021 `document.body` is not available yet)
-  //  * Default:
+  //  * @default
   //  */
   // dropMarkerParent: "body";
   /**
    * true: Drag multiple (i.e. selected) nodes. Also a callback() is allowed
-   * Default: false
+   * @default false
    */
   multiSource: false;
   /**
    * Restrict the possible cursor shapes and modifier operations (can also be set in the dragStart event)
-   * Default: "all"
+   * @default "all"
    */
   effectAllowed: "all";
   // /**
   //  * 'copy'|'link'|'move'|'auto'(calculate from `effectAllowed`+modifier keys) or callback(node, data) that returns such string.
-  //  * Default:
+  //  * @default
   //  */
   // dropEffect: "auto";
   /**
    * Default dropEffect ('copy', 'link', or 'move') when no modifier is pressed (overide in dragDrag, dragOver).
-   * Default: "move"
+   * @default "move"
    */
   dropEffectDefault: string;
   /**
    * Prevent dropping nodes from different Wunderbaum trees
-   * Default: false
+   * @default false
    */
   preventForeignNodes: boolean;
   /**
    * Prevent dropping items on unloaded lazy Wunderbaum tree nodes
-   * Default: true
+   * @default true
    */
   preventLazyParents: boolean;
   /**
    * Prevent dropping items other than Wunderbaum tree nodes
-   * Default: false
+   * @default false
    */
   preventNonNodes: boolean;
   /**
    * Prevent dropping nodes on own descendants
-   * Default: true
+   * @default true
    */
   preventRecursion: boolean;
   /**
    * Prevent dropping nodes under same direct parent
-   * Default: false
+   * @default false
    */
   preventSameParent: false;
   /**
    * Prevent dropping nodes 'before self', etc. (move only)
-   * Default: true
+   * @default true
    */
   preventVoidMoves: boolean;
   /**
    * Enable auto-scrolling while dragging
-   * Default: true
+   * @default true
    */
   scroll: boolean;
   /**
    * Active top/bottom margin in pixel
-   * Default: 20
+   * @default 20
    */
   scrollSensitivity: 20;
   /**
    * Pixel per event
-   * Default: 5
+   * @default 5
    */
   scrollSpeed: 5;
   // /**
   //  * Allow dragging of nodes to different IE windows
-  //  * Default: false
+  //  * @default false
   //  */
   // setTextTypeJson: boolean;
   /**
    * Optional callback passed to `toDict` on dragStart @since 2.38
-   * Default: null
+   * @default null
    */
   sourceCopyHook: null;
   // Events (drag support)
   /**
    * Callback(sourceNode, data), return true, to enable dnd drag
-   * Default: null
+   * @default null
    */
   dragStart?: WbNodeEventType;
   /**
    * Callback(sourceNode, data)
-   * Default: null
+   * @default null
    */
   dragDrag: null;
   /**
    * Callback(sourceNode, data)
-   * Default: null
+   * @default null
    */
   dragEnd: null;
   // Events (drop support)
   /**
    * Callback(targetNode, data), return true, to enable dnd drop
-   * Default: null
+   * @default null
    */
   dragEnter: null;
   /**
    * Callback(targetNode, data)
-   * Default: null
+   * @default null
    */
   dragOver: null;
   /**
    * Callback(targetNode, data), return false to prevent autoExpand
-   * Default: null
+   * @default null
    */
   dragExpand: null;
   /**
    * Callback(targetNode, data)
-   * Default: null
+   * @default null
    */
   dragDrop: null;
   /**
    * Callback(targetNode, data)
-   * Default: null
+   * @default null
    */
   dragLeave: null;
 };

package/src/util.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - util
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 /** @module util */
@@ -202,17 +202,19 @@ export function extractHtmlText(s: string) {
  * the element is checked, unchecked, or indeterminate.
  * For datetime input control a numerical value is assumed, etc.
  *
- * Common use case: store the new user input in the `change` event:
+ * Common use case: store the new user input in a `change` event handler:
  *
  * ```ts
  *   change: (e) => {
+ *     const tree = e.tree;
+ *     const node = e.node;
  *     // Read the value from the input control that triggered the change event:
- *     let value = e.tree.getValueFromElem(e.element);
- *     //
- *     e.node.data[]
+ *     let value = tree.getValueFromElem(e.element);
+ *     // and store it to the node model (assuming the column id matches the property name)
+ *     node.data[e.info.colId] = value;
  *   },
  * ```
- * @param elem `<input>` or `<select>` element Also a parent `span.wb-col` is accepted.
+ * @param elem `<input>` or `<select>` element. Also a parent `span.wb-col` is accepted.
  * @param coerce pass true to convert date/time inputs to `Date`.
  * @returns the value
  */
@@ -280,6 +282,23 @@ export function getValueFromElem(elem: HTMLElement, coerce = false): any {
  * value is truethy, falsy, or `null`.
  * For datetime input control a numerical value is assumed, etc.
  *
+ * Common use case: update embedded input controls in a `render` event handler:
+ *
+ * ```ts
+ *   render: (e) => {
+ *     // e.node.log(e.type, e, e.node.data);
+ *
+ *     for (const col of Object.values(e.renderColInfosById)) {
+ *       switch (col.id) {
+ *         default:
+ *           // Assumption: we named column.id === node.data.NAME
+ *           util.setValueToElem(col.elem, e.node.data[col.id]);
+ *           break;
+ *       }
+ *     }
+ *   },
+ * ```
+ *
  * @param elem `<input>` or `<select>` element Also a parent `span.wb-col` is accepted.
  * @param value a value that matches the target element.
  */
@@ -313,7 +332,6 @@ export function setValueToElem(elem: HTMLElement, value: any): void {
       case "datetime":
       case "datetime-local":
         input.valueAsDate = new Date(value);
-        // input.valueAsDate = value;  // breaks in Edge?
         break;
       case "number":
       case "range":
@@ -324,7 +342,7 @@ export function setValueToElem(elem: HTMLElement, value: any): void {
         }
         break;
       case "radio":
-        error("Not implemented");
+        error(`Not yet implemented: ${type}`);
         // const name = input.name;
         // const checked = input.parentElement!.querySelector(
         //   `input[name="${name}"]:checked`
@@ -350,7 +368,7 @@ export function setValueToElem(elem: HTMLElement, value: any): void {
   }
 }
 
-/** Show/hide element by setting the `display`style to 'none'. */
+/** Show/hide element by setting the `display` style to 'none'. */
 export function setElemDisplay(elem: string | Element, flag: boolean): void {
   const style = (<HTMLElement>elemFromSelector(elem)).style;
   if (flag) {
@@ -401,7 +419,23 @@ export function eventTargetFromSelector(
  * The result also contains a prefix for modifiers if any, for example
  * `"x"`, `"F2"`, `"Control+Home"`, or `"Shift+clickright"`.
  * This is especially useful in `switch` statements, to make sure that modifier
- * keys are considered and handled correctly.
+ * keys are considered and handled correctly:
+ * ```ts
+ *   const eventName = util.eventToString(e);
+ *   switch (eventName) {
+ *     case "+":
+ *     case "Add":
+ *       ...
+ *       break;
+ *     case "Enter":
+ *     case "End":
+ *     case "Control+End":
+ *     case "Meta+ArrowDown":
+ *     case "PageDown":
+ *       ...
+ *       break;
+ *   }
+ * ```
  */
 export function eventToString(event: Event): string {
   let key = (<KeyboardEvent>event).key,
@@ -706,6 +740,23 @@ export function toSet(val: any): Set<string> {
   throw new Error("Cannot convert to Set<string>: " + val);
 }
 
+// /** Check if a string is contained in an Array or Set. */
+// export function isAnyOf(s: string, items: Array<string>|Set<string>): boolean {
+//   return Array.prototype.includes.call(items, s)
+// }
+
+// /** Check if an Array or Set has at least one matching entry. */
+// export function hasAnyOf(container: Array<string>|Set<string>, items: Array<string>): boolean {
+//   if (Array.isArray(container)) {
+//     return container.some(v => )
+//   }
+//   return container.some(v => {})
+//   // const container = toSet(items);
+//   // const itemSet = toSet(items);
+//   // Array.prototype.includes
+//   // throw new Error("Cannot convert to Set<string>: " + val);
+// }
+
 /** Return a canonical string representation for an object's type (e.g. 'array', 'number', ...). */
 export function type(obj: any): string {
   return Object.prototype.toString

package/src/wb_ext_dnd.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-dnd
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 import * as util from "./util";
@@ -137,7 +137,7 @@ export class DndExtension extends WunderbaumExtension {
       // Only 'before' and 'after':
       return dy > ROW_HEIGHT / 2 ? "after" : "before";
     }
-    return "over";
+    // return "over";
   }
 
   /* Implement auto scrolling when drag cursor is in top/bottom area of scroll parent. */
@@ -225,6 +225,8 @@ export class DndExtension extends WunderbaumExtension {
 
   protected onDropEvent(e: DragEvent) {
     // const isLink = event.dataTransfer.types.includes("text/uri-list");
+    const srcNode = this.srcNode;
+    const srcTree = srcNode ? srcNode.tree : null;
     const targetNode = Wunderbaum.getNode(e)!;
     const dndOpts = this.treeOpts.dnd;
     const dt = e.dataTransfer!;
@@ -233,7 +235,7 @@ export class DndExtension extends WunderbaumExtension {
       this._leaveNode();
       return;
     }
-    if (e.type !== "dragover") {
+    if (!["dragenter", "dragover", "dragleave"].includes(e.type)) {
       this.tree.logDebug(
         "onDropEvent." +
           e.type +
@@ -261,13 +263,29 @@ export class DndExtension extends WunderbaumExtension {
       this.lastEnterStamp = Date.now();
 
       if (
-        // Don't allow void operation ('drop on self')
-        (dndOpts.preventVoidMoves && targetNode === this.srcNode) ||
-        targetNode.isStatusNode()
+        // Don't drop on status node:
+        targetNode.isStatusNode() ||
+        // Prevent dropping nodes from different Wunderbaum trees:
+        (dndOpts.preventForeignNodes && targetNode.tree !== srcTree) ||
+        // Prevent dropping items on unloaded lazy Wunderbaum tree nodes:
+        (dndOpts.preventLazyParents && !targetNode.isLoaded()) ||
+        // Prevent dropping items other than Wunderbaum tree nodes:
+        (dndOpts.preventNonNodes && !srcNode) ||
+        // Prevent dropping nodes on own descendants:
+        (dndOpts.preventRecursion &&
+          srcNode &&
+          srcNode.isAncestorOf(targetNode)) ||
+        // Prevent dropping nodes under same direct parent:
+        (dndOpts.preventSameParent &&
+          srcNode &&
+          targetNode.parent === srcNode.parent) ||
+        // Don't allow void operation ('drop on self'): TODO: should be checke onn  move only
+        (dndOpts.preventVoidMoves && targetNode === srcNode)
       ) {
         dt.dropEffect = "none";
         return true; // Prevent drop operation
       }
+
       // User may return a set of regions (or `false` to prevent drop)
       let regionSet = targetNode._callEvent("dnd.dragEnter", { event: e });
       //
@@ -321,9 +339,11 @@ export class DndExtension extends WunderbaumExtension {
     } else if (e.type === "drop") {
       e.stopPropagation(); // prevent browser from opening links?
       this._leaveNode();
+      const region = this.lastDropRegion;
       targetNode._callEvent("dnd.drop", {
         event: e,
-        region: this.lastDropRegion,
+        region: region,
+        defaultDropMode: region === "over" ? "appendChild" : region,
         sourceNode: this.srcNode,
       });
     }

package/src/wb_ext_edit.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-edit
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
@@ -17,7 +17,7 @@ import {
 } from "./util";
 import { debounce } from "./debounce";
 import { WunderbaumNode } from "./wb_node";
-import { AddNodeType } from "./types";
+import { InsertNodeType } from "./types";
 import { WbNodeData } from "./wb_options";
 
 // const START_MARKER = "\uFFF7";
@@ -310,7 +310,7 @@ export class EditExtension extends WunderbaumExtension {
    * Create a new child or sibling node and start edit mode.
    */
   createNode(
-    mode: AddNodeType = "after",
+    mode: InsertNodeType = "after",
     node?: WunderbaumNode | null,
     init?: string | WbNodeData
   ) {

package/src/wb_ext_filter.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-filter
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 

package/src/wb_ext_grid.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-grid
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 import { Wunderbaum } from "./wunderbaum";

package/src/wb_ext_keynav.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-keynav
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 

package/src/wb_ext_logger.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-logger
- * Copyright (c) 2021-2022, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2023, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */