wunderbaum 0.12.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wunderbaum",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "title": "A treegrid control.",
   "description": "JavaScript tree/grid/treegrid control.",
   "homepage": "https://github.com/mar10/wunderbaum",

package/src/common.ts

@@ -4,7 +4,14 @@
  * @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";
 
@@ -42,7 +49,7 @@ export const TEST_IMG = new RegExp(/\.|\//);
  *  - '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",
@@ -140,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",

package/src/types.ts

@@ -173,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
  * ---------------------------------------------------------------------------*/
@@ -471,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).
  */
@@ -518,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;
@@ -607,6 +662,23 @@ export enum NavModeEnum {
   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
  * ---------------------------------------------------------------------------*/
@@ -693,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 */
@@ -897,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.
  *
@@ -905,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

package/src/util.ts

@@ -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_edit.ts

@@ -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);

package/src/wb_ext_filter.ts

@@ -13,6 +13,7 @@ import {
   onEvent,
 } from "./util";
 import {
+  FilterConnectType,
   FilterNodesOptions,
   FilterOptionsType,
   NodeFilterCallback,
@@ -29,7 +30,11 @@ const RE_START_MARKER = new RegExp(escapeRegex(START_MARKER), "g");
 const RE_END_MARTKER = new RegExp(escapeRegex(END_MARKER), "g");
 
 export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
-  public queryInput?: HTMLInputElement;
+  public queryInput: HTMLInputElement | null = null;
+  public prevButton: HTMLElement | HTMLAnchorElement | null = null;
+  public nextButton: HTMLElement | HTMLAnchorElement | null = null;
+  public modeButton: HTMLButtonElement | null = null;
+  public matchInfoElem: HTMLElement | null = null;
   public lastFilterArgs: IArguments | null = null;
 
   constructor(tree: Wunderbaum) {
@@ -37,7 +42,7 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
       autoApply: true, // Re-apply last filter if lazy data is loaded
       autoExpand: false, // Expand all branches that contain matches while filtered
       matchBranch: false, // Whether to implicitly match all children of matched nodes
-      connectInput: null, // Element or selector of an input control for filter query strings
+      connect: null, // Element or selector of an input control for filter query strings
       fuzzy: false, // Match single characters in order, e.g. 'fb' will match 'FooBar'
       hideExpanders: false, // Hide expanders if all child nodes are hidden by filter
       highlight: true, // Highlight matches by wrapping inside <mark> tags
@@ -49,35 +54,118 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
 
   init() {
     super.init();
-    const connectInput = this.getPluginOption("connectInput");
-    if (connectInput) {
-      this.queryInput = elemFromSelector(connectInput) as HTMLInputElement;
-      assert(
-        this.queryInput,
-        `Invalid 'filter.connectInput' option: ${connectInput}.`
-      );
-      onEvent(
-        this.queryInput,
-        "input",
-        debounce((e) => {
-          // this.tree.log("query", e);
-          this.filterNodes(this.queryInput!.value.trim(), {});
-        }, 700)
-      );
+    const connect: FilterConnectType = this.getPluginOption("connect");
+    if (connect) {
+      this._connectControls();
     }
   }
 
   setPluginOption(name: string, value: any): void {
-    // alert("filter opt=" + name + ", " + value)
     super.setPluginOption(name, value);
     switch (name) {
       case "mode":
-        this.tree.filterMode = value === "hide" ? "hide" : "dim";
+        this.tree.filterMode =
+          value === "hide" ? "hide" : value === "mark" ? "mark" : "dim";
         this.tree.updateFilter();
         break;
     }
   }
 
+  _updatedConnectedControls() {
+    const filterActive = this.tree.filterMode !== null;
+    const activeNode = this.tree.getActiveNode();
+    const matchCount = filterActive ? this.countMatches() : 0;
+    const strings = this.treeOpts.strings!;
+    let matchIdx: string | number = "?";
+
+    if (this.matchInfoElem) {
+      if (filterActive) {
+        let info;
+        if (matchCount === 0) {
+          info = strings.noMatch;
+        } else if (activeNode && activeNode.match! >= 1) {
+          matchIdx = activeNode.match ?? "?";
+          info = strings.matchIndex;
+        } else {
+          info = strings.queryResult;
+        }
+        info = info
+          .replace("${count}", this.tree.count().toLocaleString())
+          .replace("${match}", "" + matchIdx)
+          .replace("${matches}", matchCount.toLocaleString());
+        this.matchInfoElem.textContent = info;
+      } else {
+        this.matchInfoElem.textContent = "";
+      }
+    }
+
+    if (this.nextButton instanceof HTMLButtonElement) {
+      this.nextButton.disabled = !matchCount;
+    }
+    if (this.prevButton instanceof HTMLButtonElement) {
+      this.prevButton.disabled = !matchCount;
+    }
+    if (this.modeButton) {
+      this.modeButton.disabled = !filterActive;
+      this.modeButton.classList.toggle(
+        "wb-filter-hide",
+        this.tree.filterMode === "hide"
+      );
+    }
+  }
+  _connectControls() {
+    const tree = this.tree;
+    const connect: FilterConnectType = this.getPluginOption("connect");
+    if (!connect) {
+      return;
+    }
+    this.queryInput = elemFromSelector(connect.inputElem);
+    if (!this.queryInput) {
+      throw new Error(`Invalid 'filter.connect' option: ${connect.inputElem}.`);
+    }
+    this.prevButton = elemFromSelector(connect.prevButton!);
+    this.nextButton = elemFromSelector(connect.nextButton!);
+    this.modeButton = elemFromSelector(connect.modeButton!);
+    this.matchInfoElem = elemFromSelector(connect.matchInfoElem!);
+    if (this.prevButton) {
+      onEvent(this.prevButton, "click", () => {
+        tree.findRelatedNode(
+          tree.getActiveNode() || tree.getFirstChild()!,
+          "prevMatch"
+        );
+        this._updatedConnectedControls();
+      });
+    }
+    if (this.nextButton) {
+      onEvent(this.nextButton, "click", () => {
+        tree.findRelatedNode(
+          tree.getActiveNode() || tree.getFirstChild()!,
+          "nextMatch"
+        );
+        this._updatedConnectedControls();
+      });
+    }
+    if (this.modeButton) {
+      onEvent(this.modeButton, "click", (e) => {
+        if (!this.tree.filterMode) {
+          return;
+        }
+        this.setPluginOption(
+          "mode",
+          tree.filterMode === "dim" ? "hide" : "dim"
+        );
+      });
+    }
+    onEvent(
+      this.queryInput,
+      "input",
+      debounce((e) => {
+        this.filterNodes(this.queryInput!.value.trim(), {});
+      }, 700)
+    );
+    this._updatedConnectedControls();
+  }
+
   _applyFilterNoUpdate(
     filter: string | RegExp | NodeFilterCallback,
     _opts: FilterNodesOptions
@@ -98,7 +186,7 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
     const treeOpts = tree.options;
     const prevAutoCollapse = treeOpts.autoCollapse;
     // Use default options from `tree.options.filter`, but allow to override them
-    const opts = extend({}, treeOpts.filter, _opts);
+    const opts: FilterOptionsType = extend({}, treeOpts.filter, _opts);
     const hideMode = opts.mode === "hide";
     const matchBranch = !!opts.matchBranch;
     const leavesOnly = !!opts.leavesOnly && !matchBranch;
@@ -176,12 +264,12 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
       };
     }
 
-    tree.filterMode = opts.mode;
+    tree.filterMode = opts.mode ?? "dim";
     // eslint-disable-next-line prefer-rest-params
     this.lastFilterArgs = arguments;
 
     tree.element.classList.toggle("wb-ext-filter-hide", !!hideMode);
-    tree.element.classList.toggle("wb-ext-filter-dim", !hideMode);
+    tree.element.classList.toggle("wb-ext-filter-dim", opts.mode === "dim");
     tree.element.classList.toggle(
       "wb-ext-filter-hide-expanders",
       !!opts.hideExpanders
@@ -193,10 +281,6 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
       delete node.titleWithHighlight;
       node.subMatchCount = 0;
     });
-    // statusNode = tree.root.findDirectChild(KEY_NODATA);
-    // if (statusNode) {
-    //   statusNode.remove();
-    // }
     tree.setStatus(NodeStatusType.ok);
 
     // Adjust node.hide, .match, and .subMatchCount properties
@@ -210,7 +294,7 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
 
       if (res === "skip") {
         node.visit(function (c) {
-          c.match = false;
+          c.match = undefined;
         }, true);
         return "skip";
       }
@@ -223,7 +307,7 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
 
       if (res) {
         count++;
-        node.match = true;
+        node.match = count;
         node.visitParents((p) => {
           if (p !== node) {
             p.subMatchCount! += 1;
@@ -252,6 +336,8 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
     tree.logDebug(
       `Filter '${filter}' found ${count} nodes in ${Date.now() - start} ms.`
     );
+    this._updatedConnectedControls();
+
     return count;
   }
 
@@ -309,6 +395,7 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
     } else {
       tree.logWarn("updateFilter(): no filter active.");
     }
+    this._updatedConnectedControls();
   }
 
   /**
@@ -316,30 +403,17 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
    */
   clearFilter() {
     const tree = this.tree;
-    // statusNode = tree.root.findDirectChild(KEY_NODATA),
-    // escapeTitles = tree.options.escapeTitles;
     tree.enableUpdate(false);
 
-    // if (statusNode) {
-    //   statusNode.remove();
-    // }
     tree.setStatus(NodeStatusType.ok);
     // we also counted root node's subMatchCount
     delete tree.root.match;
     delete tree.root.subMatchCount;
 
     tree.visit((node) => {
-      // if (node.match && node._rowElem) {
-      //   let titleElem = node._rowElem.querySelector("span.wb-title")!;
-      //   node._callEvent("enhanceTitle", { titleElem: titleElem });
-      // }
       delete node.match;
       delete node.subMatchCount;
       delete node.titleWithHighlight;
-      // if (node.subMatchBadge) {
-      //   node.subMatchBadge.remove();
-      //   delete node.subMatchBadge;
-      // }
       if (node._filterAutoExpanded && node.expanded) {
         node.setExpanded(false, {
           noAnimation: true,
@@ -355,7 +429,8 @@ export class FilterExtension extends WunderbaumExtension<FilterOptionsType> {
       "wb-ext-filter-dim",
       "wb-ext-filter-hide"
     );
-    // tree._callHook("treeStructureChanged", this, "clearFilter");
+    this._updatedConnectedControls();
+
     tree.enableUpdate(true);
   }
 }

package/src/wb_extension_base.ts

@@ -5,6 +5,7 @@
  */
 
 import * as util from "./util";
+import { WunderbaumOptions } from "./wb_options";
 import { Wunderbaum } from "./wunderbaum";
 
 export type ExtensionsDict = { [key: string]: WunderbaumExtension<any> };
@@ -13,7 +14,7 @@ export abstract class WunderbaumExtension<TOptions> {
   public enabled = true;
   readonly id: string;
   readonly tree: Wunderbaum;
-  readonly treeOpts: any;
+  readonly treeOpts: WunderbaumOptions;
   readonly extensionOpts: any;
 
   constructor(tree: Wunderbaum, id: string, defaults: TOptions) {
@@ -23,7 +24,7 @@ export abstract class WunderbaumExtension<TOptions> {
 
     const opts = tree.options as any;
 
-    if (this.treeOpts[id] === undefined) {
+    if ((<any>this.treeOpts)[id] === undefined) {
       opts[id] = this.extensionOpts = util.extend({}, defaults);
     } else {
       // TODO: do we break existing object instance references here?