wunderbaum 0.12.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wunderbaum",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "title": "A treegrid control.",
   "description": "JavaScript tree/grid/treegrid control.",
   "homepage": "https://github.com/mar10/wunderbaum",
@@ -52,6 +52,7 @@
     "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
+    "@types/firebase": "^2.4.32",
     "@types/jest": "^29.5.14",
     "@typescript-eslint/eslint-plugin": "^8.24.0",
     "@typescript-eslint/parser": "^8.24.0",
@@ -104,7 +105,7 @@
   "scripts": {
     "test": "npm run lint && npm run build:js && grunt ci --verbose",
     "api_docs": "typedoc && touch docs/api/.nojekyll && rm docs/unittest/*.*; cp test/unit/*.* docs/unittest",
-    "format": "eslint src --fix && prettier src docs/demo -w && npm run lint",
+    "format": "eslint src docs/demo --fix && prettier src docs/demo -w && npm run lint",
     "lint": "prettier src docs/demo --check && eslint src docs/demo && tsc -t esnext --moduleResolution node --noEmit src/wunderbaum.ts",
     "build:minjs:umd": "terser build/wunderbaum.umd.js --compress --mangle --source-map \"base='build',url='wunderbaum.umd.min.js.map',filename='wunderbaum.umd.js'\" --output build/wunderbaum.umd.min.js",
     "build:minjs:esm": "terser build/wunderbaum.esm.js --compress --mangle --source-map \"base='build',url='wunderbaum.esm.min.js.map',filename='wunderbaum.esm.js'\" --output build/wunderbaum.esm.min.js",

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";
 
@@ -28,13 +35,23 @@ export const RENDER_MAX_PREFETCH = 5;
 export const RENDER_MIN_PREFETCH = 5;
 /** Minimum column width if not set otherwise. */
 export const DEFAULT_MIN_COL_WIDTH = 4;
+/**
+ * A value for `node.type` that by convention may be used to mark a node as directory.
+ * It may be used to sort 'directories' to the top.
+ */
+export const NODE_TYPE_FOLDER = "folder";
 /** Regular expression to detect if a string describes an image URL (in contrast
  * to a class name). Strings are considered image urls if they contain '.' or '/'.
+ * `<` is ignored, because it is probably an html tag.
  */
-export const TEST_IMG = new RegExp(/\.|\//);
+export const TEST_FILE_PATH = /^(?!.*<).*[/.]/;
+/** Regular expression to detect if a string describes an HTML element. */
+export const TEST_HTML = /</;
 // export const RECURSIVE_REQUEST_ERROR = "$recursive_request";
 // export const INVALID_REQUEST_TARGET_ERROR = "$request_target_invalid";
 
+/** Currently supported default icon maps. */
+type IconLibrary = "bootstrap" | "fontawesome6";
 /**
  * Default node icons for icon libraries
  *
@@ -42,7 +59,7 @@ export const TEST_IMG = new RegExp(/\.|\//);
  *  - 'fontawesome6' {@link https://fontawesome.com/icons}
  *
  */
-export const iconMaps: { [key: string]: { [key: string]: string } } = {
+export const defaultIconMaps: { [key in IconLibrary]: IconMapType } = {
   bootstrap: {
     error: "bi bi-exclamation-triangle",
     // loading: "bi bi-hourglass-split wb-busy",
@@ -90,7 +107,7 @@ export const iconMaps: { [key: string]: { [key: string]: string } } = {
     radioChecked: "fa-solid fa-circle",
     radioUnchecked: "fa-regular fa-circle",
     radioUnknown: "fa-regular fa-circle-question",
-    folder: "fa-solid fa-folder-closed",
+    folder: "fa-regular fa-folder-closed",
     folderOpen: "fa-regular fa-folder-open",
     folderLazy: "fa-solid fa-folder-plus",
     doc: "fa-regular fa-file",
@@ -140,7 +157,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",
@@ -197,7 +231,9 @@ export function makeNodeTitleStartMatcher(s: string): MatcherCallback {
   };
 }
 
-/** Compare two nodes by title (case-insensitive). */
+/** Compare two nodes by title (case-insensitive).
+ * @deprecated Use `key` option instead of `cmp` in sort methods.
+ */
 export function nodeTitleSorter(a: WunderbaumNode, b: WunderbaumNode): number {
   const x = a.title.toLowerCase();
   const y = b.title.toLowerCase();
@@ -205,6 +241,13 @@ export function nodeTitleSorter(a: WunderbaumNode, b: WunderbaumNode): number {
   return x === y ? 0 : x > y ? 1 : -1;
 }
 
+// /** Compare nodes by title (case-insensitive). */
+// export function nodeTitleKeyGetter(
+//   node: WunderbaumNode
+// ): string | number | Array<any> {
+//   return node.title.toLowerCase();
+// }
+
 /**
  * Convert 'flat' to 'nested' format.
  *

package/src/types.ts

@@ -60,8 +60,13 @@ export type MatcherCallback = (node: WunderbaumNode) => boolean;
 export type WbIconBadgeCallback = (
   e: WbIconBadgeEventType
 ) => WbIconBadgeEventResultType;
-/** Passed to `sortChildren()` methods. Should return -1, 0, or 1. */
+/**
+ * Passed to `sort()` methods. Should return -1, 0, or 1.
+ * @deprecated Use SortKeyCallback instead
+ */
 export type SortCallback = (a: WunderbaumNode, b: WunderbaumNode) => number;
+/** Passed to `sort()` methods. Should return a representation that can be compared using `<`. */
+export type SortKeyCallback = (node: WunderbaumNode) => string | number | any[];
 /** 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). */
@@ -99,6 +104,12 @@ export type NodeToDictCallback = (
  */
 export type NodeSelectCallback = (node: WunderbaumNode) => boolean | void;
 
+/** @internal */
+export type DeprecationOptions = {
+  since?: string;
+  hint?: string;
+};
+
 /**
  * See also {@link WunderbaumNode.getOption|WunderbaumNode.getOption()}
  * to evaluate `node.NAME` setting and `tree.types[node.type].NAME`.
@@ -163,7 +174,7 @@ export interface WbNodeData {
   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}. */
+  /** Inherit shared settings from the matching entry in `InitWunderbaumOptions.types`. */
   type?: string;
   /** Set to `true` to prevent selection. Defaults to {@link WunderbaumOptions.unselectable}. */
   unselectable?: boolean;
@@ -173,11 +184,37 @@ 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
  * ---------------------------------------------------------------------------*/
 
-/** A callback that receives a node instance and returns a string value. */
+/** Retuen value of an event handler that can return `false` to prevent the default action. */
 export type WbCancelableEventResultType = false | void;
 
 export interface WbTreeEventType {
@@ -518,29 +555,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 +658,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
  * ---------------------------------------------------------------------------*/
@@ -681,8 +749,7 @@ export interface FilterNodesOptions {
   /**Hide expanders if all child nodes are hidden by filter @default false */
   hideExpanders?: boolean;
   /** Highlight matches by wrapping inside `<mark>` tags.
-   * Does not work for filter callbacks.
-   *  @default true
+   * Does not work for filter callbacks.  @default true
    */
   highlight?: boolean;
   /** Match end nodes only @default false */
@@ -693,6 +760,44 @@ export interface FilterNodesOptions {
   noData?: boolean | string;
 }
 
+/** Possible values for {@link Wunderbaum.getState}. */
+export interface GetStateOptions {
+  /** Include the active node's key (and expand its parents). @default true */
+  activeKey?: boolean;
+  /** Include the expanded keys. @default false */
+  expandedKeys?: boolean;
+  /** Include the selected keys. @default false */
+  selectedKeys?: boolean;
+}
+
+/** Possible values for {@link Wunderbaum.setState}. */
+export interface SetStateOptions {
+  /** Recursively load lazy nodes as needed. @default false */
+  expandLazy?: boolean;
+}
+
+/** Used by {@link Wunderbaum.getState} and {@link Wunderbaum.setState}. */
+export interface TreeStateDefinition {
+  /** List of expanded node's keys. */
+  expandedKeys: Array<string> | undefined;
+  /** 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;
+}
+
+/** Possible values for {@link Wunderbaum.loadLazyNodes} `options` argument. */
+export interface LoadLazyNodesOptions {
+  /** Expand node (otherwise load, but keep collapsed). @default true */
+  expand?: boolean;
+  /** Force reloading even if already loaded. @default false */
+  force?: boolean;
+  /** Do not send events. @default false */
+  noEvents?: boolean;
+}
+
 /** Possible values for {@link WunderbaumNode.makeVisible}. */
 export interface MakeVisibleOptions {
   /** Do not animate expand (currently not implemented). @default false */
@@ -830,7 +935,17 @@ export interface SetStatusOptions {
 }
 
 /**
- * Possible values for {@link WunderbaumNode.sortByProperty} `options` argument.
+ * Possible values for {@link Wunderbaum.reload} `options` argument.
+ */
+export interface ReloadOptions {
+  /** Load this source instead. @default initial source (if loaded via ajax) */
+  source?: SourceType;
+  /** Reactivate currently active node if any. @default true */
+  reactivate?: boolean;
+}
+
+/**
+ * Possible values for {@link WunderbaumNode.resetNativeChildOrder} `options` argument.
  */
 export interface ResetOrderOptions {
   /** Sort descendants recursively. @default true */
@@ -842,31 +957,37 @@ export interface ResetOrderOptions {
 }
 
 /**
- * Possible values for {@link WunderbaumNode.sortByProperty} `options` argument.
+ * Possible values for {@link Wunderbaum.sort} and {@link WunderbaumNode.sort}
+ * `options` argument.
  */
-export interface SortByPropertyOptions {
-  /** Column ID as defined in `tree.columns` definition. Required if updateColInfo is true.*/
-  colId?: string;
+export interface SortOptions {
   /** The name of the node property that will be used for sorting.
-   * @default use the `colId` as property name.
+   * Mandatory, unless  {@link key} or  {@link colId} are given.
    */
   propName?: string;
-  // /** If defined, this callback is used to extract the value to be sorted. */
-  // vallueGetter?: NodePropertyGetterCallback;
-  /** Sort order. @default Use value from column definition (rotated).*/
+  /** Callback that determines a node representation for comparison.
+   * @default {@link common.nodeTitleKeyGetter} */
+  key?: SortKeyCallback;
+  /** Callback that determines the order. @default {@link common.nodeTitleSorter}
+   * @deprecated use {@link key} instead
+   */
+  cmp?: SortCallback;
+  /** Sort order 'asc' or 'desc'.
+   * @default 'asc' (or if `updateColInfo` is true, the rotated status of the
+   * column definition.
+   * See also {@link WunderbaumOptions.sortFoldersFirst}.
+   */
   order?: SortOrderType;
+  /** Sort descendants recursively. @default true */
+  deep?: boolean;
+  /** Sort string values case insensitive. @default false */
+  caseInsensitive?: boolean;
   /**
    * Sort by this property if order is `undefined`.
    * See also {@link WunderbaumNode.resetNativeChildOrder}.
    * @default `_nativeIndex`.
    */
   nativeOrderPropName?: string;
-  /** Sort string values case insensitive. @default false */
-  caseInsensitive?: boolean;
-  /** Sort descendants recursively. @default true */
-  deep?: boolean;
-  // /** Rotate sort order (asc -> desc -> none) before sorting. @default false */
-  // rotateOrder?: boolean;
   /**
    * Rotate sort order (asc -> desc -> none) before sorting.
    * Update the sort icons in the column header
@@ -877,8 +998,16 @@ export interface SortByPropertyOptions {
    * @default false
    */
   updateColInfo?: boolean;
+  /** Column ID as defined in `tree.columns` definition. Required if updateColInfo is true.*/
+  colId?: string;
 }
 
+/**
+ * Possible values for {@link WunderbaumNode.sortByProperty} `options` argument.
+ * @deprecated
+ */
+export type SortByPropertyOptions = SortOptions;
+
 /** Options passed to {@link Wunderbaum.visitRows}. */
 export interface VisitRowsOptions {
   /** Skip filtered nodes and children of collapsed nodes. @default false */
@@ -897,6 +1026,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 +1047,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
@@ -1019,6 +1163,7 @@ export type DropEffectAllowedType =
 
 export type DropRegionType = "over" | "before" | "after";
 export type DropRegionTypeSet = Set<DropRegionType>;
+export type DropRegionTypeList = Array<DropRegionType>;
 // type AllowedDropRegionType =
 //   | "after"
 //   | "afterBefore"
@@ -1044,6 +1189,8 @@ export interface DropEventType extends WbNodeEventType {
   node: WunderbaumNode;
   /** The source node if any. */
   sourceNode: WunderbaumNode;
+  /** The DataTransfer object. */
+  dataTransfer: DataTransfer;
 }
 
 export type DndOptionsType = {
@@ -1189,7 +1336,9 @@ export type DndOptionsType = {
    */
   dragEnter?:
     | null
-    | ((e: DropEventType) => DropRegionType | DropRegionTypeSet | boolean);
+    | ((
+        e: DropEventType
+      ) => DropRegionType | DropRegionTypeSet | DropRegionTypeList | boolean);
   /**
    * Callback(targetNode, data)
    * @default null

package/src/util.ts

@@ -36,6 +36,8 @@ const ENTITY_MAP: { [key: string]: string } = {
   "/": "/",
 };
 
+export type NotPromise<T> = T extends Promise<any> ? never : T;
+
 export type FunctionType = (...args: any[]) => any;
 export type EventCallbackType = (e: Event) => boolean | void;
 type PromiseCallbackType = (val: any) => void;
@@ -175,7 +177,7 @@ export function each(
   return obj;
 }
 
-/** Shortcut for `throw new Error(msg)`.*/
+/** Shortcut for `throw new Error(msg)`. */
 export function error(msg: string) {
   throw new Error(msg);
 }
@@ -424,19 +426,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.
  *
@@ -796,6 +785,11 @@ export function toPixel(
   throw new Error(`Expected a string like '123px': ${defaults}`);
 }
 
+/** Cast any value to <T>. */
+export function unsafeCast<T>(value: any): T {
+  return value as T;
+}
+
 /** Return the the boolean value of the first non-null element.
  * Example:
  * ```js
@@ -887,7 +881,7 @@ export function adaptiveThrottle(
   const throttledFn = (...args: any[]) => {
     if (waiting) {
       pendingArgs = args;
-      // console.log(`adaptiveThrottle() queing request #${waiting}...`, args);
+      // console.log(`adaptiveThrottle() queueing request #${waiting}...`, args);
       waiting += 1;
     } else {
       // Prevent invocations while running or blocking
@@ -945,3 +939,69 @@ export function adaptiveThrottle(
   };
   return throttledFn;
 }
+
+/**
+ * MurmurHash3 implementation for strings.
+ * @param key The input string to hash.
+ * @param asString Optional convert result to zero-padded string of 8 characters.
+ * @param seed Optional seed value.
+ * @returns A 32-bit hash as a number or string.
+ */
+export function murmurHash3(
+  key: string,
+  asString = true,
+  seed: number = 0
+): number | string {
+  let h1 = seed;
+  const remainder = key.length & 3; // key.length % 4
+  const bytes = key.length - remainder;
+  const c1 = 0xcc9e2d51;
+  const c2 = 0x1b873593;
+
+  let i = 0;
+  while (i < bytes) {
+    let k1 =
+      (key.charCodeAt(i) & 0xff) |
+      ((key.charCodeAt(++i) & 0xff) << 8) |
+      ((key.charCodeAt(++i) & 0xff) << 16) |
+      ((key.charCodeAt(++i) & 0xff) << 24);
+    ++i;
+
+    k1 = Math.imul(k1, c1);
+    k1 = (k1 << 15) | (k1 >>> 17);
+    k1 = Math.imul(k1, c2);
+
+    h1 ^= k1;
+    h1 = (h1 << 13) | (h1 >>> 19);
+    h1 = Math.imul(h1, 5) + 0xe6546b64;
+  }
+
+  let k1 = 0;
+  switch (remainder) {
+    case 3:
+      k1 ^= (key.charCodeAt(i + 2) & 0xff) << 16;
+    // fall through
+    case 2:
+      k1 ^= (key.charCodeAt(i + 1) & 0xff) << 8;
+    // fall through
+    case 1:
+      k1 ^= key.charCodeAt(i) & 0xff;
+      k1 = Math.imul(k1, c1);
+      k1 = (k1 << 15) | (k1 >>> 17);
+      k1 = Math.imul(k1, c2);
+      h1 ^= k1;
+  }
+
+  h1 ^= key.length;
+  h1 ^= h1 >>> 16;
+  h1 = Math.imul(h1, 0x85ebca6b);
+  h1 ^= h1 >>> 13;
+  h1 = Math.imul(h1, 0xc2b2ae35);
+  h1 ^= h1 >>> 16;
+
+  if (asString) {
+    // Convert to 8 digit hex string
+    return (h1 >>> 0).toString(16).padStart(8, "0");
+  }
+  return h1 >>> 0; // Convert to unsigned 32-bit integer
+}