wunderbaum 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wunderbaum",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "title": "A treegrid control.",
   "description": "JavaScript tree/grid/treegrid control.",
   "homepage": "https://github.com/mar10/wunderbaum",
@@ -47,40 +47,42 @@
     "control"
   ],
   "devDependencies": {
-    "@rollup/plugin-replace": "^5.0.2",
-    "@rollup/plugin-terser": "^0.4.3",
-    "@rollup/plugin-typescript": "^11.1.1",
-    "@types/jest": "^29.5.2",
-    "@typescript-eslint/eslint-plugin": "^6.7.5",
-    "@typescript-eslint/parser": "^6.7.5",
-    "concurrently": "^8.1.0",
-    "eslint": "^8.51.0",
-    "eslint-config-jquery": "^3.0.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-prettier": "^4.2.1",
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.20.0",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/jest": "^29.5.14",
+    "@typescript-eslint/eslint-plugin": "^8.24.0",
+    "@typescript-eslint/parser": "^8.24.0",
+    "concurrently": "^9.1.2",
+    "eslint": "^9.20.1",
+    "eslint-config-jquery": "^3.0.2",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.2.3",
     "grunt": "^1.6.1",
-    "grunt-contrib-connect": "^3.0.0",
+    "grunt-contrib-connect": "^5.0.1",
     "grunt-contrib-qunit": "^10.1.1",
     "grunt-contrib-watch": "^1.1.0",
     "grunt-exec": "^3.0.0",
     "grunt-yabs": "^1.3.0",
     "http-server": "^14.1.1",
-    "nodemon": "^2.0.22",
-    "postcss": "^8.2.24",
+    "nodemon": "^3.1.9",
+    "postcss": "^8.5.2",
     "postcss-url": "^10.1.3",
-    "prettier": "^2.8.8",
-    "pretty-quick": "^3.1.3",
-    "puppeteer": "^23.10.0",
-    "qunit": "^2.19.4",
-    "rollup": "^3.23.0",
-    "rollup-plugin-scss": "^4.0.0",
-    "sass": "^1.63.6",
-    "terser": "^5.17.7",
-    "ts-jest": "^29.1.0",
-    "ts-node": "^10.9.1",
-    "tslib": "^2.5.2",
-    "typedoc": "^0.25.2",
-    "typescript": "^5.2.2",
+    "prettier": "^3.5.1",
+    "pretty-quick": "^4.0.0",
+    "puppeteer": "^24.2.0",
+    "qunit": "^2.24.1",
+    "rollup": "^4.34.6",
+    "rollup-plugin-scss": "^4.0.1",
+    "sass": "^1.84.0",
+    "terser": "^5.39.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "tslib": "^2.8.1",
+    "typedoc": "^0.27.7",
+    "typescript": "^5.7",
     "yarn-audit-fix": "^10.1.1"
   },
   "nodemonConfig": {

package/src/common.ts

@@ -1,10 +1,17 @@
 /*!
  * Wunderbaum - common
- * Copyright (c) 2021-2024, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2025, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
-import { MatcherCallback, SourceListType, SourceObjectType } from "./types";
+import {
+  ApplyCommandType,
+  NavigationType,
+  SourceListType,
+  SourceObjectType,
+  IconMapType,
+  MatcherCallback,
+} from "./types";
 import * as util from "./util";
 import { WunderbaumNode } from "./wb_node";
 
@@ -36,10 +43,13 @@ export const TEST_IMG = new RegExp(/\.|\//);
 // export const INVALID_REQUEST_TARGET_ERROR = "$request_target_invalid";
 
 /**
- * Default node icons.
- * Requires bootstrap icons https://icons.getbootstrap.com
+ * Default node icons for icon libraries
+ *
+ *  - 'bootstrap': {@link https://icons.getbootstrap.com}
+ *  - 'fontawesome6' {@link https://fontawesome.com/icons}
+ *
  */
-export const iconMaps: { [key: string]: { [key: string]: string } } = {
+export const iconMaps: { [key: string]: IconMapType } = {
   bootstrap: {
     error: "bi bi-exclamation-triangle",
     // loading: "bi bi-hourglass-split wb-busy",
@@ -137,7 +147,24 @@ export const RESERVED_TREE_SOURCE_KEYS: Set<string> = new Set([
 // ]);
 
 /** Map `KeyEvent.key` to navigation action. */
-export const KEY_TO_ACTION_DICT: { [key: string]: string } = {
+export const KEY_TO_NAVIGATION_MAP: { [key: string]: NavigationType } = {
+  ArrowDown: "down",
+  ArrowLeft: "left",
+  ArrowRight: "right",
+  ArrowUp: "up",
+  Backspace: "parent",
+  End: "lastCol",
+  Home: "firstCol",
+  "Control+End": "last",
+  "Control+Home": "first",
+  "Meta+ArrowDown": "last", // macOs
+  "Meta+ArrowUp": "first", // macOs
+  PageDown: "pageDown",
+  PageUp: "pageUp",
+};
+
+/** Map `KeyEvent.key` to navigation action. */
+export const KEY_TO_COMMAND_MAP: { [key: string]: ApplyCommandType } = {
   " ": "toggleSelect",
   "+": "expand",
   Add: "expand",
@@ -205,10 +232,12 @@ export function nodeTitleSorter(a: WunderbaumNode, b: WunderbaumNode): number {
 /**
  * Convert 'flat' to 'nested' format.
  *
- *  Flat node entry format:
- *    [PARENT_ID, [POSITIONAL_ARGS]]
- *  or
- *    [PARENT_ID, [POSITIONAL_ARGS], {KEY_VALUE_ARGS}]
+ * Flat node entry format:
+ *    [PARENT_IDX, {KEY_VALUE_ARGS}]
+ * or, if N _positional re defined:
+ *    [PARENT_IDX, POSITIONAL_ARG_1, POSITIONAL_ARG_2, ..., POSITIONAL_ARG_N]
+ * Even if _positional additional are defined, KEY_VALUE_ARGS can be appended:
+ *    [PARENT_IDX, POSITIONAL_ARG_1, ..., {KEY_VALUE_ARGS}]
  *
  * 1. Parent-referencing list is converted to a list of nested dicts with
  *    optional `children` properties.
@@ -216,11 +245,12 @@ export function nodeTitleSorter(a: WunderbaumNode, b: WunderbaumNode): number {
  */
 function unflattenSource(source: SourceObjectType): void {
   const { _format, _keyMap = {}, _positional = [], children } = source;
+  const _positionalCount = _positional.length;
 
   if (_format !== "flat") {
     throw new Error(`Expected source._format: "flat", but got ${_format}`);
   }
-  if (_positional && _positional.includes("children")) {
+  if (_positionalCount && _positional.includes("children")) {
     throw new Error(
       `source._positional must not include "children": ${_positional}`
     );
@@ -236,7 +266,7 @@ function unflattenSource(source: SourceObjectType): void {
       longToShort[value] = key;
     }
   }
-  const positionalShort = _positional.map((e: string) => longToShort[e]);
+  const positionalShort = _positional.map((e: string) => longToShort[e] ?? e);
   const newChildren: SourceListType = [];
   const keyToNodeMap: { [key: string]: number } = {};
   const indexToNodeMap: { [key: number]: any } = {};
@@ -247,21 +277,33 @@ function unflattenSource(source: SourceObjectType): void {
     // Node entry format:
     //   [PARENT_ID, [POSITIONAL_ARGS]]
     // or
-    //   [PARENT_ID, [POSITIONAL_ARGS], {KEY_VALUE_ARGS}]
-    const [parentId, args, kwargs = {}] = <any>nodeTuple;
+    //   [PARENT_ID, POSITIONAL_ARG_1, POSITIONAL_ARG_2, ..., {KEY_VALUE_ARGS}]
+    let kwargs;
+    const [parentId, ...args] = <any>nodeTuple;
+    if (args.length === _positionalCount) {
+      kwargs = {};
+    } else if (args.length === _positionalCount + 1) {
+      kwargs = args.pop();
+      if (typeof kwargs !== "object") {
+        throw new Error(
+          `unflattenSource: Expected dict as last tuple element: ${nodeTuple}`
+        );
+      }
+    } else {
+      throw new Error(`unflattenSource: unexpected tuple length: ${nodeTuple}`);
+    }
 
     // Free up some memory as we go
     nodeTuple[1] = null;
     if (nodeTuple[2] != null) {
       nodeTuple[2] = null;
     }
-    // console.log("flatten", parentId, args, kwargs)
-
     // We keep `kwargs` as our new node definition. Then we add all positional
     // values to this object:
     args.forEach((val: string, positionalIdx: number) => {
       kwargs[positionalShort[positionalIdx]] = val;
     });
+    args.length = 0;
 
     // Find the parent node. `null` means 'toplevel'. PARENT_ID may be the numeric
     // index of the source.children list. If PARENT_ID is a string, we search

package/src/debounce.ts

@@ -1,4 +1,9 @@
 /*!
+ * Wunderbaum - debounce.ts
+ * Copyright (c) 2021-2025, Martin Wendt. Released under the MIT license.
+ * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
+ */
+/*
  * debounce & throttle, taken from https://github.com/lodash/lodash v4.17.21
  * MIT License: https://raw.githubusercontent.com/lodash/lodash/4.17.21-npm/LICENSE
  * Modified for TypeScript type annotations.

package/src/deferred.ts

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

package/src/drag_observer.ts

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

package/src/types.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - types
- * Copyright (c) 2021-2024, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2025, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
@@ -22,7 +22,7 @@ export type SortOrderType = "asc" | "desc" | undefined;
  * or a boolean value that indicates if the default icon should be used or hidden.
  */
 export type IconOption = boolean | string;
-/** Show/hide tooltip or display a string. */
+/** Show/hide default tooltip or display a string. */
 export type TooltipOption = boolean | string;
 
 /*
@@ -93,7 +93,10 @@ export type NodeToDictCallback = (
   dict: WbNodeData,
   node: WunderbaumNode
 ) => NodeVisitResponse;
-/** A callback that receives a node instance and returns a string value. */
+/**
+ * A callback that receives a node instance and may returnsa `false` to prevent
+ * (de)selection.
+ */
 export type NodeSelectCallback = (node: WunderbaumNode) => boolean | void;
 
 /**
@@ -113,23 +116,56 @@ export type DynamicTooltipOption = TooltipOption | BoolOrStringOptionResolver;
 // type WithWildcards<T> = T & { [key: string]: unknown };
 /** A plain object (dictionary) that represents a node instance. */
 export interface WbNodeData {
+  /** Defines if the `selected` state is displayed as checkbox, radio button,
+   * or hidden.
+   * Defaults to {@link WunderbaumOptions.checkbox}.
+   */
   checkbox?: CheckboxOption;
+  /** Optional list of child nodes.
+   * If `children` is an empty array, the node is considered a leaf.
+   * If `lazy` is true and `children is undefined or null, the node, is
+   * considered unloaded. Otherwise, the node is considered a leaf.
+   */
   children?: Array<WbNodeData>;
+  /** Additional classes that are added to `<div class='wb-row'>`. */
   classes?: string;
+  /** Only show title in a single, merged column. */
   colspan?: boolean;
+  /** Expand this node. */
   expanded?: boolean;
+  /** Defaults to standard icons (doc, folder, folderOpen, ...)
+   * from {@link WunderbaumOptions.iconMap}.
+   * Can be overridden by {@link WunderbaumOptions.icon}.
+   */
   icon?: IconOption;
+  /** Tooltip for the node icon only. Defaults to {@link WunderbaumOptions.iconTooltip}. */
   iconTooltip?: TooltipOption;
+  /** The node's key. Must be unique for the whole tree. Defaults to a sequence number. */
   key?: string;
+  /** If true (and children are undefined or null), the node is considered lazy
+   * and {@link WunderbaumOptions.lazyLoad} is called when expanded.
+   */
   lazy?: boolean;
   /** Make child nodes single-select radio buttons. */
   radiogroup?: boolean;
+  /** Node's reference key. Unlike {@link WunderbaumNode.key}, this value
+   * may be non-unique. Nodes within the tree that share the same refKey are considered
+   * clones.
+   */
   refKey?: string;
+  /** The node's selection status, typically displayed as a checkbox. */
   selected?: boolean;
+  /** The node's status, typically displayed as merged single row.
+   * @see {@link Wunderbaum.setStatus}
+   */
   statusNodeType?: NodeStatusType;
+  /** The node's title. Will be html escaped to prevent XSS. */
   title: string;
+  /** Pass true to set node tooltip to the node's title. Defaults to {@link WunderbaumOptions.tooltip}. */
   tooltip?: TooltipOption;
+  /** Inherit shared settings from the matching entry in {@link WunderbaumOptions.types}. */
   type?: string;
+  /** Set to `true` to prevent selection. Defaults to {@link WunderbaumOptions.unselectable}. */
   unselectable?: boolean;
   /** @internal */
   _treeId?: string;
@@ -137,6 +173,32 @@ export interface WbNodeData {
   [key: string]: unknown;
 }
 
+/** A plain object (dictionary) that defines node icons. */
+export interface IconMapType {
+  error: string;
+  loading: string;
+  noData: string;
+  expanderExpanded: string;
+  expanderCollapsed: string;
+  expanderLazy: string;
+  checkChecked: string;
+  checkUnchecked: string;
+  checkUnknown: string;
+  radioChecked: string;
+  radioUnchecked: string;
+  radioUnknown: string;
+  folder: string;
+  folderOpen: string;
+  folderLazy: string;
+  doc: string;
+  colSortable: string;
+  colSortAsc: string;
+  colSortDesc: string;
+  colFilter: string;
+  colFilterActive: string;
+  colMenu: string;
+  [key: string]: string;
+}
 /* -----------------------------------------------------------------------------
  * EVENT CALLBACK TYPES
  * ---------------------------------------------------------------------------*/
@@ -435,6 +497,21 @@ export interface ColumnDefinition {
 
 export type ColumnDefinitionList = Array<ColumnDefinition>;
 
+/**
+ * Used by {@link Wunderbaum.getState} and {@link Wunderbaum.setState}.
+ */
+export interface TreeStateDefinition {
+  /** The active node's key if any. */
+  activeKey: string | null;
+  /** The active column index if any. */
+  activeColIdx: number | null;
+  /** List of selected node's keys. */
+  selectedKeys: Array<string> | undefined;
+  /** List of expanded node's keys. */
+  expandedKeys: Array<string> | undefined;
+  /** List of checked node's keys. */
+}
+
 /**
  * Column information (passed to the `render` event).
  */
@@ -482,29 +559,43 @@ export interface WbEventInfo {
 // export type WbNodeCallbackType = (e: WbNodeEventType) => any;
 // export type WbRenderCallbackType = (e: WbRenderEventType) => void;
 
-export type FilterModeType = null | "dim" | "hide";
+export type FilterModeType = null | "mark" | "dim" | "hide";
 export type SelectModeType = "single" | "multi" | "hier";
+
+export type NavigationType =
+  | "down"
+  | "first"
+  | "firstCol"
+  | "last"
+  | "lastCol"
+  | "left"
+  | "nextMatch"
+  | "pageDown"
+  | "pageUp"
+  | "parent"
+  | "prevMatch"
+  | "right"
+  | "up";
+
 export type ApplyCommandType =
+  | NavigationType
   | "addChild"
   | "addSibling"
+  | "collapse"
+  | "collapseAll"
   | "copy"
   | "cut"
-  | "down"
-  | "first"
+  | "edit"
+  | "expand"
+  | "expandAll"
   | "indent"
-  | "last"
-  | "left"
   | "moveDown"
   | "moveUp"
   | "outdent"
-  | "pageDown"
-  | "pageUp"
-  | "parent"
   | "paste"
   | "remove"
   | "rename"
-  | "right"
-  | "up";
+  | "toggleSelect";
 
 export type NodeFilterResponse = "skip" | "branch" | boolean | void;
 export type NodeFilterCallback = (node: WunderbaumNode) => NodeFilterResponse;
@@ -531,7 +622,7 @@ export enum ChangeType {
   scroll = "scroll",
 }
 
-/* Internal use. */
+/** @internal */
 export enum RenderFlag {
   clearMarkup = "clearMarkup",
   header = "header",
@@ -561,12 +652,33 @@ export enum NodeRegion {
 
 /** Initial navigation mode and possible transition. */
 export enum NavModeEnum {
-  startRow = "startRow", // Start with row mode, but allow cell-nav mode
-  cell = "cell", // Cell-nav mode only
-  startCell = "startCell", // Start in cell-nav mode, but allow row mode
-  row = "row", // Row mode only
+  /** Start with row mode, but allow cell-nav mode */
+  startRow = "startRow",
+  /** Cell-nav mode only */
+  cell = "cell",
+  /** Start in cell-nav mode, but allow row mode */
+  startCell = "startCell",
+  /** Row mode only */
+  row = "row",
 }
 
+/** Translatable strings. */
+export type TranslationsType = {
+  /** @default "Loading..." */
+  loading: string;
+  /** @default "Error" */
+  loadError: string;
+  /** @default "No data" */
+  noData: string;
+  /** @default " » " */
+  breadcrumbDelimiter: string;
+  /** @default "Found ${matches} of ${count}" */
+  queryResult: string;
+  /** @default "No result" */
+  noMatch: string;
+  /** @default "${match} of ${matches}" */
+  matchIndex: string;
+};
 /* -----------------------------------------------------------------------------
  * METHOD OPTIONS TYPES
  * ---------------------------------------------------------------------------*/
@@ -653,6 +765,22 @@ export interface FilterNodesOptions {
   noData?: boolean | string;
 }
 
+/** Possible values for {@link Wunderbaum.getState}. */
+export interface GetStateOptions {
+  // /** Include the activated key. @default true */
+  // activeKey?: boolean;
+  /** Include the expanded keys. @default true */
+  expandedKeys?: boolean;
+  /** Include the selected keys. @default true */
+  selectedKeys?: boolean;
+}
+
+/** Possible values for {@link Wunderbaum.setState}. */
+export interface SetStateOptions {
+  /** Recursively load lazy nodes as needed. @default false */
+  expandLazy?: boolean;
+}
+
 /** Possible values for {@link WunderbaumNode.makeVisible}. */
 export interface MakeVisibleOptions {
   /** Do not animate expand (currently not implemented). @default false */
@@ -857,6 +985,19 @@ export interface VisitRowsOptions {
 /* -----------------------------------------------------------------------------
  * wb_ext_filter
  * ---------------------------------------------------------------------------*/
+
+/**
+ * Passed as tree option.filer.connect to configure automatic integration of
+ * filter UI controls. @experimental
+ */
+export interface FilterConnectType {
+  inputElem: string | HTMLInputElement | null;
+  modeButton?: string | HTMLButtonElement | null;
+  nextButton?: string | HTMLButtonElement | HTMLAnchorElement | null;
+  prevButton?: string | HTMLButtonElement | HTMLAnchorElement | null;
+  matchInfoElem?: string | HTMLElement | null;
+}
+
 /**
  * Passed as tree options to configure default filtering behavior.
  *
@@ -865,10 +1006,12 @@ export interface VisitRowsOptions {
  */
 export type FilterOptionsType = {
   /**
-   * Element or selector of an input control for filter query strings
+   * Element or selector of input controls and buttons for filter query strings.
+   * @experimental
+   * @since 0.13
    * @default null
    */
-  connectInput?: null | string | Element;
+  connect?: null | FilterConnectType;
   /**
    * Re-apply last filter if lazy data is loaded
    * @default true
@@ -965,7 +1108,6 @@ export type InsertNodeType =
   | "after"
   | "prependChild"
   | "appendChild";
-// export type DndModeType = "before" | "after" | "over";
 
 export type DropEffectType = "none" | "copy" | "link" | "move";
 export type DropEffectAllowedType =

package/src/util.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - util
- * Copyright (c) 2021-2024, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2025, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
@@ -424,19 +424,6 @@ export function elemFromSelector<T = HTMLElement>(obj: string | T): T | null {
   return obj as T;
 }
 
-// /** Return a EventTarget from selector or cast an existing element. */
-// export function eventTargetFromSelector(
-//   obj: string | EventTarget
-// ): EventTarget | null {
-//   if (!obj) {
-//     return null;
-//   }
-//   if (typeof obj === "string") {
-//     return document.querySelector(obj) as EventTarget;
-//   }
-//   return obj as EventTarget;
-// }
-
 /**
  * Return a canonical descriptive string for a keyboard or mouse event.
  *

package/src/wb_ext_dnd.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-dnd
- * Copyright (c) 2021-2024, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2025, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 import * as util from "./util";
@@ -143,8 +143,8 @@ export class DndExtension extends WunderbaumExtension<DndOptionsType> {
       return dy < 0.25 * rowHeight
         ? "before"
         : dy > 0.75 * rowHeight
-        ? "after"
-        : "over";
+          ? "after"
+          : "over";
     } else if (allowed.size === 1 && allowed.has("over")) {
       return "over";
     } else {

package/src/wb_ext_edit.ts

@@ -1,6 +1,6 @@
 /*!
  * Wunderbaum - ext-edit
- * Copyright (c) 2021-2024, Martin Wendt. Released under the MIT license.
+ * Copyright (c) 2021-2025, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
 
@@ -381,7 +381,7 @@ export class EditExtension extends WunderbaumExtension<EditOptionsType> {
     this.relatedNode = node;
 
     // Don't filter new nodes:
-    newNode.match = true;
+    newNode.match = -1;
 
     newNode.makeVisible({ noAnimation: true }).then(() => {
       this.startEditTitle(newNode);