Update type docs

docs/tutorial/tutorial_events.md

@@ -218,6 +218,13 @@ Common event handlers include:
   after the data is applied and rendered.
 </dd>
 
+<dt>
+  <code>modifyChild(<a href="https://mar10.github.io/wunderbaum/api/interfaces/types.WbNodeEventType.html">WbNodeEventType</a>)</code>
+  <small>- <i>node event</i></small>
+</dt> <dd>
+  TODO
+</dd>
+
 <dt>
   <code>receive(<a href="https://mar10.github.io/wunderbaum/api/interfaces/types.WbReceiveEventType.html">WbReceiveEventType</a>)</code>
   <small>- <i>node event</i></small>

src/types.ts

@@ -124,6 +124,9 @@ export interface WbNodeData {
  * EVENT CALLBACK TYPES
  * ---------------------------------------------------------------------------*/
 
+/** A callback that receives a node instance and returns a string value. */
+export type WbCancelableEventResultType = false | void;
+
 export interface WbTreeEventType {
   /** Name of the event. */
   type: string;
@@ -205,6 +208,7 @@ export interface WbEditEditEventType extends WbNodeEventType {
 export interface WbErrorEventType extends WbNodeEventType {
   error: any;
 }
+
 export interface WbExpandEventType extends WbNodeEventType {
   flag: boolean;
 }
@@ -219,6 +223,7 @@ export interface WbFocusEventType extends WbTreeEventType {
 export interface WbIconBadgeEventType extends WbNodeEventType {
   iconSpan: HTMLElement;
 }
+
 export interface WbIconBadgeEventResultType {
   /** Content of the badge `<span class='wb-badge'>` if any. */
   badge: string | number | HTMLSpanElement | null | false;
@@ -243,6 +248,7 @@ export interface WbKeydownEventType extends WbTreeEventType {
 export interface WbReceiveEventType extends WbNodeEventType {
   response: any;
 }
+
 export interface WbSelectEventType extends WbNodeEventType {
   flag: boolean;
 }
@@ -684,6 +690,9 @@ export interface VisitRowsOptions {
   wrap?: boolean;
 }
 
+/* -----------------------------------------------------------------------------
+ * wb_ext_filter
+ * ---------------------------------------------------------------------------*/
 export type FilterOptionsType = {
   /**
    * Element or selector of an input control for filter query strings
@@ -743,6 +752,9 @@ export type FilterOptionsType = {
   noData?: boolean | string;
 };
 
+/* -----------------------------------------------------------------------------
+ * wb_ext_edit
+ * ---------------------------------------------------------------------------*/
 /**
  * Note: <br>
  * This options are used for renaming node titles. <br>
@@ -800,25 +812,26 @@ export type EditOptionsType = {
 
   /**
    * `beforeEdit(e)` may return an input HTML string. Otherwise use a default.
+   * @category Callback
    */
   beforeEdit?: null | ((e: WbNodeEventType) => boolean) | string;
   /**
    *
+   * @category Callback
    */
   edit?:
     | null
     | ((e: WbNodeEventType & { inputElem: HTMLInputElement }) => void);
   /**
    *
+   * @category Callback
    */
   apply?:
     | null
     | ((e: WbNodeEventType & { inputElem: HTMLInputElement }) => any)
     | Promise<any>;
 };
 
-export type GridOptionsType = object;
-
 /* -----------------------------------------------------------------------------
  * wb_ext_dnd
  * ---------------------------------------------------------------------------*/
@@ -967,28 +980,33 @@ export type DndOptionsType = {
   /**
    * Optional callback passed to `toDict` on dragStart @since 2.38
    * @default null
+   * @category Callback
    */
   sourceCopyHook?: null;
   // Events (drag support)
   /**
    * Callback(sourceNode, data), return true, to enable dnd drag
    * @default null
+   * @category Callback
    */
   dragStart?: null | ((e: WbNodeEventType & { event: DragEvent }) => boolean);
   /**
    * Callback(sourceNode, data)
    * @default null
+   * @category Callback
    */
   drag?: null | ((e: WbNodeEventType & { event: DragEvent }) => void);
   /**
    * Callback(sourceNode, data)
    * @default null
+   * @category Callback
    */
   dragEnd?: null | ((e: WbNodeEventType & { event: DragEvent }) => void);
   // Events (drop support)
   /**
    * Callback(targetNode, data), return true, to enable dnd drop
    * @default null
+   * @category Callback
    */
   dragEnter?:
     | null
@@ -998,16 +1016,19 @@ export type DndOptionsType = {
   /**
    * Callback(targetNode, data)
    * @default null
+   * @category Callback
    */
   dragOver?: null | ((e: WbNodeEventType & { event: DragEvent }) => void);
   /**
    * Callback(targetNode, data), return false to prevent autoExpand
    * @default null
+   * @category Callback
    */
   dragExpand?: null | ((e: WbNodeEventType & { event: DragEvent }) => boolean);
   /**
    * Callback(targetNode, data)
    * @default null
+   * @category Callback
    */
   drop?:
     | null
@@ -1024,6 +1045,22 @@ export type DndOptionsType = {
   /**
    * Callback(targetNode, data)
    * @default null
+   * @category Callback
    */
   dragLeave?: null;
 };
+
+/* -----------------------------------------------------------------------------
+ * wb_ext_grid
+ * ---------------------------------------------------------------------------*/
+export type GridOptionsType = object;
+
+/* -----------------------------------------------------------------------------
+ * wb_ext_keynav
+ * ---------------------------------------------------------------------------*/
+export type KeynavOptionsType = object;
+
+/* -----------------------------------------------------------------------------
+ * wb_ext_loger
+ * ---------------------------------------------------------------------------*/
+export type LoggerOptionsType = object;

src/wb_ext_keynav.ts

@@ -4,15 +4,15 @@
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
-import { NavModeEnum } from "./types";
+import { KeynavOptionsType, NavModeEnum } from "./types";
 import { eventToString } from "./util";
 import { Wunderbaum } from "./wunderbaum";
 import { WunderbaumNode } from "./wb_node";
 import { WunderbaumExtension } from "./wb_extension_base";
 
 const QUICKSEARCH_DELAY = 500;
 
-export class KeynavExtension extends WunderbaumExtension<any> {
+export class KeynavExtension extends WunderbaumExtension<KeynavOptionsType> {
   constructor(tree: Wunderbaum) {
     super(tree, "keynav", {});
   }

src/wb_ext_logger.ts

@@ -4,11 +4,12 @@
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
+import { LoggerOptionsType } from "./types";
 import { overrideMethod } from "./util";
 import { WunderbaumExtension } from "./wb_extension_base";
 import { Wunderbaum } from "./wunderbaum";
 
-export class LoggerExtension extends WunderbaumExtension<any> {
+export class LoggerExtension extends WunderbaumExtension<LoggerOptionsType> {
   readonly prefix: string;
   protected ignoreEvents = new Set<string>([
     "iconBadge",

src/wb_options.ts

@@ -5,6 +5,7 @@
  */
 
 import {
+  WbCancelableEventResultType,
   ColumnDefinitionList,
   DndOptionsType,
   DynamicBoolOption,
@@ -13,6 +14,9 @@ import {
   DynamicIconOption,
   EditOptionsType,
   FilterOptionsType,
+  GridOptionsType,
+  KeynavOptionsType,
+  LoggerOptionsType,
   NavModeEnum,
   NodeTypeDefinitionMap,
   SelectModeType,
@@ -21,14 +25,17 @@ import {
   WbClickEventType,
   WbDeactivateEventType,
   WbErrorEventType,
+  WbExpandEventType,
   WbIconBadgeCallback,
   WbInitEventType,
   WbKeydownEventType,
   WbNodeData,
   WbNodeEventType,
   WbReceiveEventType,
   WbRenderEventType,
+  WbSelectEventType,
   WbTreeEventType,
+  WbIconBadgeEventResultType,
 } from "./types";
 
 /**
@@ -230,69 +237,87 @@ export interface WunderbaumOptions {
   scrollIntoViewOnExpandClick?: boolean;
 
   // --- Extensions ------------------------------------------------------------
-  dnd?: DndOptionsType; // = {};
-  edit?: EditOptionsType; // = {};
-  filter?: FilterOptionsType; // = {};
-  grid?: any; // = {};
+
+  dnd?: DndOptionsType;
+  edit?: EditOptionsType;
+  filter?: FilterOptionsType;
+  // grid?: GridOptionsType;
+  // keynav?: KeynavOptionsType;
+  // logger?: LoggerOptionsType;
 
   // --- Events ----------------------------------------------------------------
 
   /**
-   *
+   * `e.node` was activated.
    * @category Callback
    */
   activate?: (e: WbActivateEventType) => void;
+  /**
+   * `e.node` is about to be activated.
+   * Return `false` to prevent default handling, i.e. activating the node.
+   * See also `deactivate` event.
+   * @category Callback
+   */
+  beforeActivate?: (e: WbActivateEventType) => WbCancelableEventResultType;
+  /**
+   * `e.node` is about to be expanded/collapsed.
+   * Return `false` to prevent default handling, i.e. expanding/collapsing the node.
+   * @category Callback
+   */
+  beforeExpand?: (e: WbExpandEventType) => WbCancelableEventResultType;
   /**
    *
-   * Return `false` to prevent default handling, e.g. activating the node.
+   * Return `false` to prevent default handling, i.e. (de)selecting the node.
    * @category Callback
    */
-  beforeActivate?: (e: WbActivateEventType) => void;
+  beforeSelect?: (e: WbSelectEventType) => WbCancelableEventResultType;
   /**
    *
    * @category Callback
    */
   change?: (e: WbChangeEventType) => void;
   /**
    *
-   * Return `false` to prevent default handling, e.g. activating the node.
+   * Return `false` to prevent default behavior, e.g. expand/collapse, (de)selection, or activation.
    * @category Callback
    */
-  click?: (e: WbClickEventType) => void;
+  click?: (e: WbClickEventType) => WbCancelableEventResultType;
   /**
-   *
+   * Return `false` to prevent default behavior, e.g. expand/collapse.
    * @category Callback
    */
-  dblclick?: (e: WbClickEventType) => void;
+  dblclick?: (e: WbClickEventType) => WbCancelableEventResultType;
   /**
+   * `e.node` was deactivated.
    *
    * Return `false` to prevent default handling, e.g. deactivating the node
    * and activating the next.
+   * See also `activate` event.
    * @category Callback
    */
-  deactivate?: (e: WbDeactivateEventType) => void;
+  deactivate?: (e: WbDeactivateEventType) => WbCancelableEventResultType;
   /**
-   *
+   * `e.node` was discarded from the viewport and its HTML markup removed.
    * @category Callback
    */
   discard?: (e: WbNodeEventType) => void;
   /**
-   *
+   * `e.node` is about to be rendered. We can add a badge to the icon cell here.
    * @category Callback
    */
-  iconBadge?: WbIconBadgeCallback;
-  // /**
-  //  *
-  //  * @category Callback
-  //  */
-  // enhanceTitle?: (e: WbEnhanceTitleEventType) => void;
+  iconBadge?: (e: WbIconBadgeCallback) => WbIconBadgeEventResultType;
   /**
-   *
+   * An error occurred, e.g. during initialization or lazy loading.
    * @category Callback
    */
   error?: (e: WbErrorEventType) => void;
   /**
-   *
+   * `e.node` was expanded (`e.flag === true`) or collapsed (`e.flag === false`)
+   * @category Callback
+   */
+  expand?: (e: WbTreeEventType) => void;
+  /**
+   * The tree received or lost focus.
    * Check `e.flag` for status.
    * @category Callback
    */
@@ -301,15 +326,17 @@ export interface WunderbaumOptions {
    * Fires when the tree markup was created and the initial source data was loaded.
    * Typical use cases would be activating a node, setting focus, enabling other
    * controls on the page, etc.<br>
-   * Check `e.error` for status.
+   *  Also sent if an error occured during initialization (check `e.error` for status).
    * @category Callback
    */
   init?: (e: WbInitEventType) => void;
   /**
-   *
+   * Fires when a key was pressed while the tree has focus.
+   * `e.node` is set if a node is currently active.
+   * Return `false` to prevent default navigation.
    * @category Callback
    */
-  keydown?: (e: WbKeydownEventType) => void;
+  keydown?: (e: WbKeydownEventType) => WbCancelableEventResultType;
   /**
    * Fires when a node that was marked 'lazy', is expanded for the first time.
    * Typically we return an endpoint URL or the Promise of a fetch request that
@@ -345,13 +372,12 @@ export interface WunderbaumOptions {
    */
   render?: (e: WbRenderEventType) => void;
   /**
-   *
+   * Same as `render(e)`, but for the status nodes, i.e. `e.node.statusNodeType`.
    * @category Callback
    */
   renderStatusNode?: (e: WbRenderEventType) => void;
   /**
-   *
-   * Check `e.flag` for status.
+   *`e.node` was selected (`e.flag === true`) or deselected (`e.flag === false`)
    * @category Callback
    */
   select?: (e: WbNodeEventType) => void;