wunderbaum 0.13.0 → 0.14.0

package/src/wb_options.ts

@@ -1,5 +1,5 @@
 /*!
- * Wunderbaum - utils
+ * Wunderbaum - options
  * Copyright (c) 2021-2025, Martin Wendt. Released under the MIT license.
  * @VERSION, @DATE (https://github.com/mar10/wunderbaum)
  */
@@ -20,6 +20,7 @@ import {
   NavModeEnum,
   NodeTypeDefinitionMap,
   SelectModeType,
+  SourceType,
   TranslationsType,
   WbActivateEventType,
   WbButtonClickEventType,
@@ -33,7 +34,6 @@ import {
   WbIconBadgeEventResultType,
   WbInitEventType,
   WbKeydownEventType,
-  WbNodeData,
   WbNodeEventType,
   WbReceiveEventType,
   WbRenderEventType,
@@ -42,121 +42,73 @@ import {
 } from "./types";
 
 /**
- * Available options for {@link wunderbaum.Wunderbaum}.
- *
- * Options are passed to the constructor as plain object:
+ * Properties of {@link wunderbaum.Wunderbaum.options}.
  *
- * ```js
- * const tree = new mar10.Wunderbaum({
- *   id: "demo",
- *   element: document.getElementById("demo-tree"),
- *   source: "url/of/data/request",
- *   ...
- * });
- * ```
- *
- * Event handlers are also passed as callbacks
- *
- * ```js
- * const tree = new mar10.Wunderbaum({
- *   ...
- *   init: (e) => {
- *     console.log(`Tree ${e.tree} was initialized and loaded.`)
- *   },
- *   activate: (e) => {
- *     console.log(`Node ${e.node} was activated.`)
- *   },
- *   ...
- * });
- * ```
+ * This is similar, but not identical, to the options that can be passed to the
+ * constructor(@see {@link InitWunderbaumOptions}).
  */
 export interface WunderbaumOptions {
-  /**
-   * The target `div` element (or selector) that shall become a Wunderbaum.
-   */
-  element: string | HTMLDivElement;
-  /**
-   * The identifier of this tree. Used to reference the instance, especially
-   * when multiple trees are present (e.g. `tree = mar10.Wunderbaum.getTree("demo")`).
-   *
-   * Default: `"wb_" + COUNTER`.
-   */
-  id?: string;
-  /**
-   * Define the initial tree data. Typically a URL of an endpoint that serves
-   * a JSON formatted structure, but also a callback, Promise, or static data
-   * is allowed.
-   *
-   * Default: `{}`.
-   */
-  source?: string | Array<WbNodeData>;
-  /**
-   * Define shared attributes for multiple nodes of the same type.
-   * This allows for more compact data models. Type definitions can be passed
-   * as tree option, or be part of a `source` response.
-   *
-   * Default: `{}`.
-   */
-  types?: NodeTypeDefinitionMap;
-  /**
-   * A list of maps that define column headers. If this option is set,
-   * Wunderbaum becomes a treegrid control instead of a plain tree.
-   * Column definitions can be passed as tree option, or be part of a `source`
-   * response.
-   * Default: `[]` meaning this is a plain tree.
-   */
-  columns?: ColumnDefinitionList;
   /**
    * If true, add a `wb-skeleton` class to all nodes, that will result in a
    * 'glow' effect. Typically used with initial dummy nodes, while loading the
    * real data.
-   * Default: false.
+   * @default false.
    */
-  skeleton?: boolean;
+  skeleton: boolean;
   /**
    * Translation map for some system messages.
    */
-  strings?: TranslationsType;
+  strings: TranslationsType;
   /**
    * 0:quiet, 1:errors, 2:warnings, 3:info, 4:verbose
-   * Default: 3 (4 in local debug environment)
+   * @default 3 (4 in local debug environment)
    */
-  debugLevel?: number;
+  debugLevel: number;
   /**
    * Number of levels that are forced to be expanded, and have no expander icon.
    * E.g. 1 would keep all toplevel nodes expanded.
-   * Default: 0
+   * @default 0
    */
-  minExpandLevel?: number;
+  minExpandLevel: number;
   /**
    * If true, allow to expand parent nodes, even if `node.children` conatains
    * an empty array (`[]`). This is the the behavior of macOS Finder, for example.
-   * Default: false
+   * @default false
    */
-  emptyChildListExpandable?: boolean;
+  emptyChildListExpandable: boolean;
   // escapeTitles: boolean;
   // /**
   //  * Height of the header row div.
-  //  * Default: 22
+  //  * @default 22
   //  */
   // headerHeightPx: number;
   /**
    * Height of a node row div.
-   * Default: 22
+   * @default 22
    */
-  rowHeightPx?: number;
+  rowHeightPx: number;
   /**
    * Icon font definition. May be a string (e.g. "fontawesome6" or "bootstrap")
    * or a map of `iconName: iconClass` pairs.
    * Note: the icon font must be loaded separately.
-   * Default: "bootstrap"
+   * In order to only override some defauöt icons, use this pattern:
+   * ```js
+   * const tree = new mar10.Wunderbaum({
+   *   ...
+   *   iconMap: Object.assign(Wunderbaum.iconMaps.bootstrap, {
+   *     folder: "bi bi-archive",
+   *   }),
+   * });
+   * ```
+
+   * @default "bootstrap"
    */
-  iconMap?: string | IconMapType;
+  iconMap: string | IconMapType;
   /**
    * Collapse siblings when a node is expanded.
-   * Default: false
+   * @default false
    */
-  autoCollapse?: boolean;
+  autoCollapse: boolean;
   /**
    * If true, the tree will automatically adjust its height to fit the parent
    * container. This is useful when the tree is embedded in a container with
@@ -170,16 +122,16 @@ export interface WunderbaumOptions {
    *
    * @default: true
    */
-  adjustHeight?: boolean;
+  adjustHeight: boolean;
   /**
    * HTMLElement or selector that receives the top nodes breadcrumb.
-   * Default: undefined
+   * @default undefined
    */
-  connectTopBreadcrumb?: HTMLElement | string;
+  connectTopBreadcrumb: HTMLElement | string | null;
   /**
-   * Default:  NavModeEnum.startRow
+   * @default  NavModeEnum.startRow
    */
-  navigationModeOption?: NavModeEnum;
+  navigationModeOption: NavModeEnum;
   /**
    * Show/hide header (default: null)
    * null: assume false for plain tree and true for grids.
@@ -187,17 +139,27 @@ export interface WunderbaumOptions {
    * true: display a header (use tree's id as text for plain trees)
    * false: do not display a header
    */
-  header?: boolean | string | null;
+  header: boolean | string | null;
   /**
-   *
+   * Show a `<progress>` element while loading data.
+   * @default false.
+   */
+  showSpinner: boolean;
+  /**
+   * Generate missing keys by hashing a combination of refKey (or title) and
+   * the parent key. This is useful when the source data does not contain unique
+   * keys but we want stable keys for persisting the active node, selection or
+   * expansion state. Note that this still assumes that the same refKey must not
+   * appear twice in the same parent node.
+   * @default false.
    */
-  showSpinner?: boolean;
+  autoKeys: boolean;
   /**
    * If true, render a checkbox before the node tile to allow selection with the
    * mouse. Pass `"radio"` to render a radio button instead.
-   * Default: false.
+   * @default false.
    */
-  checkbox?: DynamicCheckboxOption;
+  checkbox: DynamicCheckboxOption;
   /** Optional callback to render icons per node. */
   icon?: DynamicIconOption;
   /** Optional callback to render a tooltip for the icon. */
@@ -209,65 +171,79 @@ export interface WunderbaumOptions {
   /** Optional callback to make a node unselectable. */
   unselectable?: DynamicBoolOption;
   // /**
-  //  * Default: 200
+  //  * @default 200
   //  */
   // updateThrottleWait?: number;
   /**
-   * Default: true
+   * @default true
    */
-  enabled?: boolean;
+  enabled: boolean;
   /**
-   * Default: false
+   *
+   * @default false
    */
-  fixedCol?: boolean;
+  fixedCol: boolean;
   /**
    * Default value for ColumnDefinition.filterable option.
-   * Default: false
+   * @default false
    * @since 0.11.0
    */
-  columnsFilterable?: boolean;
+  columnsFilterable: boolean;
   /**
    * Default value for ColumnDefinition.menu option.
-   * Default: false
+   * @default false
    * @since 0.11.0
    */
-  columnsMenu?: boolean;
+  columnsMenu: boolean;
   /**
    * Default value for ColumnDefinition.resizable option.
-   * Default: false
+   * @default false
    * @since 0.10.0
    */
   columnsResizable?: boolean;
   /**
    * Default value for ColumnDefinition.sortable option.
-   * Default: false
+   * @default false
    * @since 0.11.0
    */
   columnsSortable?: boolean;
+  /**
+   * Group nodes with children or of `type: 'folder'` at the top when sorting.
+   * If a function is passed, it is called with the node as argument to determine
+   * whether the node is a folder or not. The function should return `true` for
+   * folders.
+   * and should return `true` for folders.
+   * @default false
+   * @since 0.14.0
+   */
+  sortFoldersFirst?: DynamicBoolOption;
 
   // --- Selection ---
   /**
-   * Default: "multi"
+   * @default "multi"
    */
-  selectMode?: SelectModeType;
+  selectMode: SelectModeType;
 
   // --- KeyNav ---
   /**
-   * Default: true
+   * @default true
    */
-  quicksearch?: boolean;
+  quicksearch: boolean;
 
   /**
    * Scroll Node into view on Expand Click
    * @default true
    */
-  scrollIntoViewOnExpandClick?: boolean;
+  scrollIntoViewOnExpandClick: boolean;
 
   // --- Extensions ------------------------------------------------------------
 
-  dnd?: DndOptionsType;
-  edit?: EditOptionsType;
-  filter?: FilterOptionsType;
+  /** Configuration options for the drag-and-drop extension. */
+  dnd: DndOptionsType;
+  /** Configuration options for the edit-title extension. */
+  edit: EditOptionsType;
+  /** Configuration options for the node-filter extension. */
+  filter: FilterOptionsType;
   // grid?: GridOptionsType;
   // keynav?: KeynavOptionsType;
   // logger?: LoggerOptionsType;
@@ -418,3 +394,88 @@ export interface WunderbaumOptions {
    */
   update?: (e: WbTreeEventType) => void;
 }
+
+/**
+ * Available options for {@link wunderbaum.Wunderbaum}.
+ *
+ * Options are passed to the constructor as plain object:
+ *
+ * ```js
+ * const tree = new mar10.Wunderbaum({
+ *   id: "demo",
+ *   element: document.getElementById("demo-tree"),
+ *   source: "url/of/data/request",
+ *   ...
+ * });
+ * ```
+ *
+ * Event handlers are also passed as callbacks
+ *
+ * ```js
+ * const tree = new mar10.Wunderbaum({
+ *   ...
+ *   init: (e) => {
+ *     console.log(`Tree ${e.tree} was initialized and loaded.`)
+ *   },
+ *   activate: (e) => {
+ *     console.log(`Node ${e.node} was activated.`)
+ *   },
+ *   ...
+ * });
+ * ```
+ *
+ * Most of the properties are optional and have resonable default.
+ * They are then available as {@link Wunderbaum.options} property and can be
+ * changed at runtime. <br>
+ * Only the `element` option is mandatory.
+ *
+ * Note that some options passed here, are *not* available as {@link Wunderbaum.options}.
+ * They are moved to the `tree` instance instead:
+ * - `tree.element`
+ * - `tree.id`
+ * - `tree.columns`
+ * - `tree.types`
+ * - ...
+ *
+ * Some options are only used during initialization and are not stored in the
+ * tree instance:
+ * - `source`
+ *
+ */
+export interface InitWunderbaumOptions extends Partial<WunderbaumOptions> {
+  /**
+   * The target `div` element (or selector) that shall become a Wunderbaum.
+   */
+  element: string | HTMLDivElement;
+  /**
+   * The identifier of this tree. Used to reference the instance, especially
+   * when multiple trees are present (e.g. `tree = mar10.Wunderbaum.getTree("demo")`).
+   *
+   * @default `"wb_" + COUNTER`.
+   */
+  id?: string;
+  /**
+   * A list of maps that define column headers. If this option is set,
+   * Wunderbaum becomes a treegrid control instead of a plain tree.
+   * Column definitions can be passed as tree option, or be part of a `source`
+   * response.
+   * @default `[]` meaning this is a plain tree.
+   */
+  columns?: ColumnDefinitionList;
+  /**
+   * Define shared attributes for multiple nodes of the same type.
+   * This allows for more compact data models. Type definitions can be passed
+   * as tree option, or be part of a `source` response.
+   *
+   * @default `{}`.
+   */
+  types?: NodeTypeDefinitionMap;
+  /**
+   * Define the initial tree data. Typically a URL of an endpoint that serves
+   * a JSON formatted structure, but also a callback, Promise, or static data
+   * is allowed.
+   *
+   * @default `[]`.
+   */
+  source?: SourceType;
+}