tree-element 0.3.2 → 0.4.1

package/src/options.ts

@@ -31,10 +31,32 @@ export type OnIsMoveHandle = (el: HTMLElement) => boolean;
 
 export type OnSetStateFromStorage = ((data: string) => void) | undefined;
 
+/* The options that setOption can change. The others are read once, in the
+ * constructor, so changing them later would have no effect or leave the tree
+ * in an inconsistent state.
+ */
+export const changeableOptions = [
+  "animationSpeed",
+  "dataUrl",
+  "dragAndDrop",
+  "keyboardSupport",
+  "multiSelect",
+  "onCanSelectNode",
+  "selectable",
+  "slide",
+  "startDndDelay",
+  "tabIndex",
+] as const;
+
+/**
+ * The options that `setOption` can change.
+ */
+export type ChangeableOption = (typeof changeableOptions)[number];
+
 export interface TreeElementOptions {
   /**
-   * The duration of the slide animation: `"fast"` is 200ms, `"slow"` is
-   * 600ms, a number is milliseconds.
+   * The duration of the slide animation: `"fast"` is 200 milliseconds,
+   * `"slow"` is 600, and a number is milliseconds.
    *
    * @defaultValue `"fast"`, or `0` when the user prefers reduced motion
    * (`prefers-reduced-motion: reduce`).
@@ -56,7 +78,7 @@ export interface TreeElementOptions {
    */
   ariaLabelledBy?: string;
   /**
-   * Escape node names. With `false`, names are inserted as html — only do
+   * Escape node names. With `false`, names are inserted as HTML—only do
    * that for data you control.
    *
    * @defaultValue `true`
@@ -81,10 +103,10 @@ export interface TreeElementOptions {
    */
   buttonLeft: boolean;
   /**
-   * The prefix of the css classes the widget puts on the elements it
+   * The prefix of the CSS classes the widget puts on the elements it
    * creates: with `"my-tree"` a title gets `my-tree-title` instead of
-   * `tree-element-title`. The bundled stylesheet uses the default prefix, so
-   * change it only if you bring your own css. See
+   * `tree-element-title`. The bundled style sheet uses the default prefix,
+   * so change it only if you bring your own CSS. See
    * [Styling](/guide/styling#changing-the-class-names).
    *
    * @defaultValue `"tree-element"`
@@ -92,12 +114,12 @@ export interface TreeElementOptions {
    */
   classPrefix: string;
   /**
-   * The icon of a closed folder. A string is inserted as html; an element is
-   * cloned for every node.
+   * The icon of a closed folder. A string is inserted as HTML, and an element
+   * is cloned for every node.
    *
    * Type: `HTMLElement | string`
    *
-   * @defaultValue An svg triangle pointing right, or left when `rtl` is
+   * @defaultValue An SVG triangle pointing right, or left when `rtl` is
    * true. It is sized in em and filled with `currentColor`.
    * @group Appearance
    */
@@ -125,7 +147,7 @@ export interface TreeElementOptions {
    */
   dataFilter?: DataFilter;
   /**
-   * A url to fetch the data from, or a function that returns one. The
+   * A URL to fetch the data from, or a function that returns one. The
    * function is called with the node that is being loaded, and without an
    * argument for the initial load. See
    * [Loading on demand](/guide/loading-on-demand).
@@ -151,6 +173,16 @@ export interface TreeElementOptions {
    * @group Selection
    */
   keyboardSupport: boolean;
+  /**
+   * Let the user select multiple nodes: a click adds a node to the
+   * selection, or removes it when it is selected. The arrow keys move the
+   * focus instead of the selection, and `Space` adds the focused node or
+   * removes it. See [Selection](/guide/selection#multiple-nodes).
+   *
+   * @defaultValue `false`
+   * @group Selection
+   */
+  multiSelect: boolean;
   /**
    * The class used to create nodes. Subclass [`Node`](/reference/node) to
    * add your own methods. The `Node` class is not exposed on the global
@@ -227,7 +259,7 @@ export interface TreeElementOptions {
    */
   onDragStop?: DragMethod;
   /**
-   * Read the saved state, as a json string, from somewhere other than
+   * Read the saved state, as a JSON string, from somewhere other than
    * `localStorage`.
    *
    * Type: `() => string`
@@ -245,7 +277,7 @@ export interface TreeElementOptions {
    */
   onIsMoveHandle?: OnIsMoveHandle;
   /**
-   * Write the state, as a json string, to somewhere other than
+   * Write the state, as a JSON string, to somewhere other than
    * `localStorage`.
    *
    * Type: `(state: string) => void`
@@ -258,7 +290,7 @@ export interface TreeElementOptions {
    *
    * Type: `HTMLElement | string`
    *
-   * @defaultValue An svg triangle pointing down, sized in em and filled with
+   * @defaultValue An SVG triangle pointing down, sized in em and filled with
    * `currentColor`.
    * @group Appearance
    */
@@ -280,7 +312,7 @@ export interface TreeElementOptions {
   rtl?: boolean;
   /**
    * Remember the open and selected nodes in `localStorage`. A string is used
-   * as the storage key; `true` uses `tree`. See
+   * as the storage key, and `true` uses `tree`. See
    * [Saving state](/guide/saving-state).
    *
    * @defaultValue `false`

package/src/saveStateHandler.ts

@@ -67,10 +67,7 @@ export default class SaveStateHandler {
   }
 
   public getNodeIdToBeSelected(): NodeId | null {
-    if (!this.saveStateOption) {
-      return null;
-    }
-
+    // Without the saveState option there is no state
     const state = this.getStateFromStorage();
 
     return state?.selected_node ? (state.selected_node[0] ?? null) : null;
@@ -243,8 +240,9 @@ export default class SaveStateHandler {
     }
   }
 
+  // result: is a node selected?
   private selectInitialNodes(nodeIds: NodeId[]): boolean {
-    let selectCount = 0;
+    let isNodeSelected = false;
 
     for (const nodeId of nodeIds) {
       const node = this.getNodeById(nodeId);
@@ -253,11 +251,10 @@ export default class SaveStateHandler {
         continue;
       }
 
-      selectCount += 1;
-
       this.addToSelection(node);
+      isNodeSelected = true;
     }
 
-    return selectCount !== 0;
+    return isNodeSelected;
   }
 }

package/src/selectNodeHandler.ts

@@ -128,9 +128,9 @@ export default class SelectNodeHandler {
       this.selectedNodes.delete(node.id);
 
       if (includeChildren) {
-        node.iterate(() => {
-          if (node.id != null) {
-            this.selectedNodes.delete(node.id);
+        node.iterate((child: Node) => {
+          if (child.id != null) {
+            this.selectedNodes.delete(child.id);
           }
           return true;
         });
@@ -149,43 +149,49 @@ export default class SelectNodeHandler {
    * mustToggle: support deselecting the selected node
    */
   public selectSingleNode(node: Node, optionsParam?: SelectNodeOptions) {
-    const defaultOptions = { mustSetFocus: true, mustToggle: true };
-    const selectOptions = { ...defaultOptions, ...optionsParam };
-
-    const canSelect = (): boolean => {
-      if (!this.getSelectable()) {
-        return false;
-      }
-
-      const onCanSelectNode = this.getOnCanSelectNode();
-      return onCanSelectNode ? onCanSelectNode(node) : true;
-    };
-
-    if (!canSelect()) {
+    if (!this.canSelect(node)) {
       return;
     }
 
-    const deselectCurrentNode = (deselectedNode: Node) => {
-      this.removeFromSelection(deselectedNode);
-      this.getNodeElementForNode(deselectedNode).deselect();
-    };
+    const defaultOptions = { mustSetFocus: true, mustToggle: true };
+    const selectOptions = { ...defaultOptions, ...optionsParam };
+
+    const otherSelectedNodes = this.getSelectedNodes().filter(
+      (selectedNode) => selectedNode !== node,
+    );
 
     if (this.isNodeSelected(node)) {
-      if (selectOptions.mustToggle) {
-        deselectCurrentNode(node);
+      if (otherSelectedNodes.length) {
+        // Part of a multiple selection: keep only this node selected
+        for (const otherNode of otherSelectedNodes) {
+          this.deselectNode(otherNode);
+        }
+
+        for (const otherNode of otherSelectedNodes) {
+          this.triggerEvent("tree.deselect", { node: otherNode });
+        }
+      } else if (selectOptions.mustToggle) {
+        this.deselectNode(node);
         this.triggerEvent("tree.deselect", { node });
       }
     } else {
-      const deselectedNode = this.getSelectedNode();
+      // tree.select reports the first deselected node; the others, from a
+      // multiple selection, get a tree.deselect.
+      const [deselectedNode = null, ...alsoDeselectedNodes] =
+        otherSelectedNodes;
 
-      if (deselectedNode) {
-        deselectCurrentNode(deselectedNode);
+      for (const otherNode of otherSelectedNodes) {
+        this.deselectNode(otherNode);
       }
 
       this.addToSelection(node);
       this.openParents(node);
       this.getNodeElementForNode(node).select(selectOptions.mustSetFocus);
 
+      for (const otherNode of alsoDeselectedNodes) {
+        this.triggerEvent("tree.deselect", { node: otherNode });
+      }
+
       this.triggerEvent("tree.select", {
         deselectedNode,
         node,
@@ -195,4 +201,42 @@ export default class SelectNodeHandler {
     this.updateTabStop();
     this.saveState();
   }
+
+  /* Add a node to the selection, or remove it when it is selected, without
+   * changing the other selected nodes.
+   * Checks if the node is selectable and saves the state.
+   */
+  public toggleNodeInSelection(node: Node, mustSetFocus = true): void {
+    if (!this.canSelect(node)) {
+      return;
+    }
+
+    if (this.isNodeSelected(node)) {
+      this.deselectNode(node);
+      this.triggerEvent("tree.deselect", { node });
+    } else {
+      this.addToSelection(node);
+      this.openParents(node);
+      this.getNodeElementForNode(node).select(mustSetFocus);
+
+      this.triggerEvent("tree.select", { deselectedNode: null, node });
+    }
+
+    this.updateTabStop();
+    this.saveState();
+  }
+
+  private canSelect(node: Node): boolean {
+    if (!this.getSelectable()) {
+      return false;
+    }
+
+    const onCanSelectNode = this.getOnCanSelectNode();
+    return onCanSelectNode ? onCanSelectNode(node) : true;
+  }
+
+  private deselectNode(node: Node): void {
+    this.removeFromSelection(node);
+    this.getNodeElementForNode(node).deselect();
+  }
 }

package/src/setDefaultOptions.ts

@@ -29,6 +29,7 @@ const defaults: TreeElementOptions = {
   // dataUrl: undefined,
   dragAndDrop: false,
   keyboardSupport: true,
+  multiSelect: false,
   nodeClass: Node,
   // onCanMove: undefined, // Can this node be moved?
   // onCanMoveTo: undefined, // Can this node be moved to this position? function(moved_node, target_node, position)

package/src/version.ts

@@ -1,4 +1,4 @@
 // Generated by config/generateVersion.mjs. Do not edit.
-const version = "0.3.2";
+const version = "0.4.1";
 
 export default version;

package/tree_element.css

@@ -2,6 +2,7 @@
   Colors. Override them on :root or on an element around the tree, for example
   for a dark theme. :where keeps the specificity at 0, so any rule wins.
   --tree-element-selected-color defaults to --tree-element-title-color.
+  Set --tree-element-line-color to transparent to hide the tree lines.
 */
 :where(:root) {
   --tree-element-title-color: #1c4257;
@@ -12,6 +13,19 @@
   --tree-element-drop-hint-color: #00f;
   --tree-element-dragging-color: #fff;
   --tree-element-dragging-background: #000;
+  --tree-element-line-color: #d5dbe1;
+}
+
+/*
+  The width of the toggler. The indentation and the tree lines follow it, so
+  the line stays under the center of the toggler. 1.5em is 24px at a 16px
+  font: above that the toggler grows with the font, so the space around the
+  0.8em icon, which separates it from the title, grows along. Set it to the
+  width of a custom icon that is wider. It is resolved where it is used, so em
+  is the font size of the tree.
+*/
+:where(:root) {
+  --tree-element-toggler-size: max(24px, 1.5em);
 }
 
 ul.tree-element {
@@ -27,11 +41,14 @@ ul.tree-element.tree-element-dnd {
 
 ul.tree-element ul.tree-element-common {
     list-style: none outside;
-    margin-left: 12px;
+    margin-left: calc(var(--tree-element-toggler-size) / 2);
     margin-right: 0;
     margin-bottom: 0;
     padding: 0;
     display: block;
+    /* The line down from the toggler of the folder: the indent is half the
+       width of the toggler, so the line is under its center. */
+    border-left: 1px solid var(--tree-element-line-color);
   }
 
 ul.tree-element li.tree-element-closed > ul.tree-element-common {
@@ -52,12 +69,16 @@ ul.tree-element .tree-element-toggler {
     align-items: center;
     justify-content: center;
     box-sizing: border-box;
-    min-width: 24px;
+    min-width: var(--tree-element-toggler-size);
     min-height: 24px;
     border-bottom: none;
     color: var(--tree-element-toggler-color);
     text-decoration: none;
     vertical-align: middle;
+    /* The line under the toggler is 1px wide, so its center is half a pixel
+       after the center of the toggler. Move the toggler along.
+       Margin or padding would be rounded to a whole pixel; translate isn't. */
+    translate: 0.5px;
   }
 
 ul.tree-element .tree-element-toggler:hover {
@@ -86,10 +107,26 @@ ul.tree-element .tree-element-title {
     vertical-align: middle;
   }
 
+/* The li is the treeitem, so it gets the focus. Show the focus ring around
+     the title, not around the li with all its children. */
+
+ul.tree-element li.tree-element-common:focus {
+    outline: none;
+  }
+
+ul.tree-element li.tree-element-common:focus-visible
+    > .tree-element-element
+    .tree-element-title {
+    /* Same as the default focus ring of the browser. Browsers without
+       -webkit-focus-ring-color ignore the second line. */
+    outline: auto;
+    outline-color: -webkit-focus-ring-color;
+  }
+
 /* Line up with the titles of folders, after the toggler */
 
 ul.tree-element .tree-element-title-button-left {
-    margin-left: 24px;
+    margin-left: var(--tree-element-toggler-size);
   }
 
 ul.tree-element .tree-element-title-button-left.tree-element-title-folder {
@@ -170,12 +207,18 @@ ul.tree-element.tree-element-rtl {
 
 ul.tree-element.tree-element-rtl ul.tree-element-common {
     margin-left: 0;
-    margin-right: 12px;
+    margin-right: calc(var(--tree-element-toggler-size) / 2);
+    border-left: none;
+    border-right: 1px solid var(--tree-element-line-color);
+  }
+
+ul.tree-element.tree-element-rtl .tree-element-toggler {
+    translate: -0.5px;
   }
 
 ul.tree-element.tree-element-rtl .tree-element-title {
     margin-left: 0;
-    margin-right: 24px;
+    margin-right: var(--tree-element-toggler-size);
   }
 
 ul.tree-element.tree-element-rtl .tree-element-title.tree-element-title-folder {