tree-element 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "tree-element",
-  "version": "0.4.0",
+  "version": "0.4.1",
+  "packageManager": "pnpm@12.16.1",
   "description": "Tree widget in plain javascript",
   "keywords": [
     "tree"
@@ -43,6 +44,7 @@
     "vitest": "pnpm build-debug && vitest run --coverage --config config/vitest.config.mjs",
     "vitest-watch": "vitest --config config/vitest.config.mjs",
     "lint": "eslint css src playwright test",
+    "lint-docs": "pnpm docs-api && vale --glob='!docs/.vitepress/**' README.md CHANGELOG.md docs",
     "production": "./config/production",
     "devserver": "SERVE=true rollup --config config/rollup.config.mjs --watch",
     "docs-api": "typedoc && node docs/scripts/fixApiLinks.mjs",
@@ -58,66 +60,70 @@
     "release": "node config/release.mjs",
     "playwright": "pnpm build-with-coverage && playwright test --config config/playwright.config.js",
     "test": "pnpm vitest && pnpm playwright",
-    "docs-check": "kiira check"
+    "docs-check": "kiira check",
+    "mutation": "stryker run config/stryker.config.mjs"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.14.0",
-    "@babel/cli": "^8.0.6",
-    "@babel/core": "^8.0.7",
+    "@babel/cli": "^8.1.0",
+    "@babel/core": "^8.1.2",
     "@babel/preset-env": "^8.0.7",
     "@babel/preset-typescript": "^8.0.7",
-    "@cspell/eslint-plugin": "^10.4.0",
+    "@cspell/eslint-plugin": "^10.4.1",
     "@eslint/css": "^2.0.1",
     "@eslint/js": "^10.0.1",
-    "@playwright/test": "^1.64.1",
+    "@playwright/test": "^1.65.0",
     "@rollup/plugin-babel": "^7.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-terser": "^1.0.0",
+    "@rollup/plugin-terser": "^1.0.2",
+    "@stryker-mutator/core": "^10.1.1",
+    "@stryker-mutator/typescript-checker": "^10.1.1",
+    "@stryker-mutator/vitest-runner": "^10.1.1",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/jest-dom": "^7.0.1",
-    "@testing-library/user-event": "^14.6.8",
+    "@testing-library/user-event": "^14.6.10",
     "@types/debug": "^4.1.13",
-    "@types/node": "^26.6.5",
-    "@vitest/coverage-istanbul": "^5.0.5",
-    "@vitest/eslint-plugin": "^1.6.27",
+    "@types/node": "^26.6.6",
+    "@vitest/coverage-istanbul": "^5.1.0",
+    "@vitest/eslint-plugin": "^1.6.28",
     "axe-core": "^4.14.0",
     "babel-plugin-istanbul": "^8.0.0",
     "babel-plugin-prefix-private-members": "^0.3.1",
-    "eslint": "^10.13.0",
+    "eslint": "^10.14.0",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-compat": "^7.0.2",
-    "eslint-plugin-import-x": "^4.17.1",
-    "eslint-plugin-jest-dom": "^5.10.1",
+    "eslint-plugin-import-x": "^4.18.1",
+    "eslint-plugin-jest-dom": "^5.10.2",
     "eslint-plugin-jest-extended": "github:mbraak/eslint-plugin-jest-extended#modernize",
     "eslint-plugin-no-unsanitized": "^4.1.5",
-    "eslint-plugin-perfectionist": "^5.12.1",
-    "eslint-plugin-playwright": "^2.12.1",
+    "eslint-plugin-perfectionist": "^5.13.0",
+    "eslint-plugin-playwright": "^2.12.2",
     "eslint-plugin-testing-library": "^7.16.2",
     "eslint-plugin-tsdoc": "^0.5.4",
-    "eslint-plugin-unicorn": "^78.0.0",
+    "eslint-plugin-unicorn": "^79.0.0",
     "jest-extended": "^7.0.0",
-    "jsdom": "^30.1.3",
+    "jsdom": "^31.0.1",
     "jsdom-testing-mocks": "^1.16.0",
     "jsonfile": "^6.2.1",
-    "kiira": "^0.7.0",
-    "kiira-core": "^0.7.0",
+    "kiira": "^0.7.1",
+    "kiira-core": "^0.7.1",
     "lodash": "^4.18.1",
-    "msw": "^3.0.3",
-    "postcss": "^8.5.30",
+    "msw": "^3.0.5",
+    "postcss": "^8.5.32",
     "postcss-cli": "^12.0.0",
     "postcss-import": "^17.0.1",
     "postcss-load-config": "^6.0.1",
-    "postcss-nested": "^9.0.0",
-    "prettier": "^3.9.10",
-    "rollup": "^4.64.7",
+    "postcss-nested": "^9.0.1",
+    "prettier": "^3.10.1",
+    "rollup": "^4.68.2",
     "rollup-plugin-serve": "^3.0.0",
     "rollup-plugin-tsconfig-paths": "^1.5.2",
-    "tslib": "^2.8.1",
+    "tslib": "^2.9.1",
     "typedoc": "^0.28.20",
-    "typedoc-plugin-markdown": "^4.14.0",
+    "typedoc-plugin-markdown": "^4.14.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.71.2",
+    "typescript-eslint": "^8.72.2",
     "vitepress": "^1.6.4",
-    "vitest": "^5.0.5"
+    "vitest": "^5.1.0"
   }
 }

package/src/dataLoader.ts

@@ -80,8 +80,10 @@ export default class DataLoader {
     const signal = this.abortController.signal;
     url.setSearchParam("_", Date.now().toString());
 
+    // Accept, not Content-Type: the request has no body. A cross-origin request
+    // with only an Accept header also needs no CORS preflight.
     return fetch(url.value(), {
-      headers: { "Content-Type": "application/json" },
+      headers: { Accept: "application/json" },
       signal,
     })
       .then(handleResponse)

package/src/dragAndDropHandler/generateHitAreas.ts

@@ -31,8 +31,9 @@ export const generateHitPositions = (
   };
 
   const handleAfterOpenFolder = (node: Node, nextNode: Node | null) => {
-    if (node === currentNode || nextNode === currentNode) {
-      // Cannot move before or after current item
+    // Not called for the current node: handleOpenFolder stops iterating there
+    if (nextNode === currentNode) {
+      // Dropping the current node after this folder would leave it where it is
       addHitPosition(node, null, lastTop);
     } else {
       addHitPosition(node, "after", lastTop);

package/src/dragAndDropHandler/index.ts

@@ -44,7 +44,6 @@ interface DragAndDropHandlerParams {
   openFolderDelay: false | number;
   openNode: OpenNode;
   refreshElements: RefreshElements;
-  slide: boolean;
   treeElement: HTMLElement;
   triggerEvent: TriggerEvent;
 }
@@ -75,7 +74,6 @@ export class DragAndDropHandler {
   private openNode: OpenNode;
   private previousGhost: DropHint | null;
   private refreshElements: RefreshElements;
-  private slide: boolean;
   private treeElement: HTMLElement;
   private triggerEvent: TriggerEvent;
 
@@ -94,7 +92,6 @@ export class DragAndDropHandler {
     openFolderDelay,
     openNode,
     refreshElements,
-    slide,
     treeElement,
     triggerEvent,
   }: DragAndDropHandlerParams) {
@@ -112,7 +109,6 @@ export class DragAndDropHandler {
     this.openFolderDelay = openFolderDelay;
     this.openNode = openNode;
     this.refreshElements = refreshElements;
-    this.slide = slide;
     this.treeElement = treeElement;
     this.triggerEvent = triggerEvent;
 
@@ -157,10 +153,6 @@ export class DragAndDropHandler {
     const area = this.findHoveredArea(positionInfo.pageX, positionInfo.pageY);
 
     if (area && this.canMoveToArea(area, this.currentItem)) {
-      if (!area.node.isFolder()) {
-        this.stopOpenFolderTimer();
-      }
-
       if (this.hoveredArea !== area) {
         this.hoveredArea = area;
 
@@ -212,7 +204,7 @@ export class DragAndDropHandler {
     return true;
   }
 
-  public mouseStop(positionInfo: PositionInfo): boolean {
+  public mouseStop(positionInfo: PositionInfo): void {
     this.moveItem(positionInfo);
     this.clear();
     this.removeHover();
@@ -231,8 +223,6 @@ export class DragAndDropHandler {
     if (!this.hoveredArea && currentItem && this.onDragStop) {
       this.onDragStop(currentItem.node, positionInfo.originalEvent);
     }
-
-    return false;
   }
 
   public refresh(): void {
@@ -360,11 +350,7 @@ export class DragAndDropHandler {
   }
 
   private mustCaptureElement(element: HTMLElement): boolean {
-    const nodeName = element.nodeName;
-
-    return (
-      nodeName !== "INPUT" && nodeName !== "SELECT" && nodeName !== "TEXTAREA"
-    );
+    return !["INPUT", "SELECT", "TEXTAREA"].includes(element.nodeName);
   }
 
   private mustOpenFolderTimer(area: HitArea): boolean {
@@ -389,7 +375,7 @@ export class DragAndDropHandler {
 
   private startOpenFolderTimer(folder: Node): void {
     const openFolder = (): void => {
-      void this.openNode(folder, this.slide).then(() => {
+      void this.openNode(folder).then(() => {
         this.refresh();
         this.updateDropHint();
       });

package/src/elementsRenderer.ts

@@ -1,9 +1,10 @@
 import type { ClassNames } from "./classNames";
+import type { FolderIcons } from "./folderOpenState";
 import type { GetTree, IsNodeSelected } from "./methodTypes";
 import type { Node } from "./node";
 import type { IconElement, OnCreateLi } from "./options";
 
-import { getBoolString } from "./util";
+import { setFolderLiOpenState, setTogglerOpenState } from "./folderOpenState";
 
 interface ElementsRendererParams {
   ariaLabel?: string;
@@ -37,8 +38,7 @@ interface ElementsRendererParams {
  * selected and loading classes.
  */
 export default class ElementsRenderer {
-  public closedIconElement?: globalThis.Node;
-  public openedIconElement?: globalThis.Node;
+  public icons: FolderIcons;
   private ariaLabel?: string;
   private ariaLabelledBy?: string;
   private autoEscape: boolean;
@@ -94,14 +94,17 @@ export default class ElementsRenderer {
     this.setNodeElement = setNodeElement;
     this.showEmptyFolder = showEmptyFolder;
     this.tabIndex = tabIndex;
-    this.openedIconElement = this.createButtonElement(openedIcon);
-    this.closedIconElement = this.createButtonElement(closedIcon);
-
-    this.rootUlTemplate = this.createUlTemplate(true);
-    this.groupUlTemplate = this.createUlTemplate(false);
-    this.nodeTemplate = this.createNodeTemplate();
-    this.openedFolderTemplate = this.createFolderTemplate(true);
-    this.closedFolderTemplate = this.createFolderTemplate(false);
+    this.icons = {
+      closed: this.createButtonElement(closedIcon),
+      opened: this.createButtonElement(openedIcon),
+    };
+
+    const templates = this.createTemplates();
+    this.closedFolderTemplate = templates.closedFolderTemplate;
+    this.groupUlTemplate = templates.groupUlTemplate;
+    this.nodeTemplate = templates.nodeTemplate;
+    this.openedFolderTemplate = templates.openedFolderTemplate;
+    this.rootUlTemplate = templates.rootUlTemplate;
   }
 
   public render(fromNode: Node | null): void {
@@ -150,6 +153,50 @@ export default class ElementsRenderer {
     }
   }
 
+  /* Change dragAndDrop after construction. The rendered lists and the
+   * templates for new lists get or lose the dnd class.
+   */
+  public setDragAndDrop(dragAndDrop: boolean): void {
+    this.dragAndDrop = dragAndDrop;
+    this.updateTemplates();
+
+    for (const ul of this.htmlElement.querySelectorAll(
+      `ul.${this.classNames.common}`,
+    )) {
+      ul.classList.toggle(this.classNames.dnd, dragAndDrop);
+    }
+  }
+
+  /* Change multiSelect after construction. Only the templates are updated;
+   * the tree must be rendered again.
+   */
+  public setMultiSelect(multiSelect: boolean): void {
+    this.multiSelect = multiSelect;
+    this.updateTemplates();
+  }
+
+  /* Change tabIndex after construction. The rendered nodes and the
+   * templates for new nodes get the new tabindex. The tab stop is updated by
+   * TreeElement.updateTabStop.
+   */
+  public setTabIndex(tabIndex: number | undefined): void {
+    this.tabIndex = tabIndex;
+    this.updateTemplates();
+
+    for (const li of this.htmlElement.querySelectorAll("li[role=treeitem]")) {
+      if (tabIndex === undefined) {
+        li.removeAttribute("tabindex");
+      } else if (
+        !this.multiSelect &&
+        li.getAttribute("aria-selected") === "true"
+      ) {
+        li.setAttribute("tabindex", String(tabIndex));
+      } else {
+        li.setAttribute("tabindex", "-1");
+      }
+    }
+  }
+
   private attachNodeData(node: Node, li: HTMLElement): void {
     node.element = li;
     this.setNodeElement(li, node);
@@ -228,35 +275,24 @@ export default class ElementsRenderer {
    * state, so there is a template for each.
    */
   private createFolderTemplate(isOpen: boolean): HTMLLIElement {
-    const liClasses = [this.classNames.common, this.classNames.folder];
-
-    if (!isOpen) {
-      liClasses.push(this.classNames.closed);
-    }
+    const li = this.createLiTemplate(
+      `${this.classNames.common} ${this.classNames.folder}`,
+    );
+    setFolderLiOpenState(li, isOpen, this.classNames);
 
-    const li = this.createLiTemplate(liClasses.join(" "));
     const div = li.firstChild as HTMLDivElement;
 
     // The toggler is hidden from screen readers: the icon is decoration, and
     // aria-expanded on the treeitem has the open state.
     const toggler = document.createElement("span");
-    toggler.className = this.getButtonClasses(isOpen);
+    toggler.className = this.getButtonClasses();
     toggler.setAttribute("aria-hidden", "true");
-
-    const iconElement = isOpen
-      ? this.openedIconElement
-      : this.closedIconElement;
-
-    if (iconElement) {
-      toggler.append(iconElement.cloneNode(true));
-    }
+    setTogglerOpenState(toggler, isOpen, this.classNames, this.icons);
 
     if (this.buttonLeft) {
       div.append(toggler);
     }
 
-    li.setAttribute("aria-expanded", getBoolString(isOpen));
-
     // title span
     div.append(this.createTitleSpanTemplate(true));
 
@@ -350,6 +386,16 @@ export default class ElementsRenderer {
     return li;
   }
 
+  private createTemplates() {
+    return {
+      closedFolderTemplate: this.createFolderTemplate(false),
+      groupUlTemplate: this.createUlTemplate(false),
+      nodeTemplate: this.createNodeTemplate(),
+      openedFolderTemplate: this.createFolderTemplate(true),
+      rootUlTemplate: this.createUlTemplate(true),
+    };
+  }
+
   private createTitleSpanTemplate(isFolder: boolean): HTMLSpanElement {
     const titleSpan = document.createElement("span");
 
@@ -443,13 +489,9 @@ export default class ElementsRenderer {
     li.setAttribute("aria-label", titleSpan.textContent);
   }
 
-  private getButtonClasses(isOpen: boolean): string {
+  private getButtonClasses(): string {
     const classes = [this.classNames.toggler, this.classNames.common];
 
-    if (!isOpen) {
-      classes.push(this.classNames.closed);
-    }
-
     if (this.buttonLeft) {
       classes.push(this.classNames.togglerLeft);
     } else {
@@ -465,4 +507,13 @@ export default class ElementsRenderer {
   private mustRenderChildren(node: Node): boolean {
     return node.hasChildren() && node.is_open === true;
   }
+
+  private updateTemplates(): void {
+    const templates = this.createTemplates();
+    this.closedFolderTemplate = templates.closedFolderTemplate;
+    this.groupUlTemplate = templates.groupUlTemplate;
+    this.nodeTemplate = templates.nodeTemplate;
+    this.openedFolderTemplate = templates.openedFolderTemplate;
+    this.rootUlTemplate = templates.rootUlTemplate;
+  }
 }

package/src/events.ts

@@ -25,7 +25,7 @@ export interface TreeEvents {
   /**
    * Dispatched once, after the tree is rendered for the first time. With
    * `dataUrl` this is after the data has arrived, so it is the moment the
-   * api is safe to use:
+   * API is safe to use:
    *
    * ```js
    * element.addEventListener("tree.init", () => {
@@ -85,7 +85,7 @@ export interface TreeEvents {
     originalEvent: MouseEvent;
   };
   /**
-   * Dispatched on a right click on a node, unless `useContextMenu` is
+   * Dispatched when a node is right-clicked, unless `useContextMenu` is
    * `false`. The browser's own menu is suppressed.
    *
    * @group Mouse
@@ -96,7 +96,7 @@ export interface TreeEvents {
   };
   /**
    * Dispatched when `Enter` is pressed on the selected node, or on the
-   * focused node when no node is selected. Use it for what a click on a
+   * focused node when no node is selected. Use it for what clicking a
    * link would do, like opening the edit page of the node:
    *
    * ```js
@@ -142,7 +142,9 @@ export interface TreeEvents {
    */
   "tree.select": {
     /**
-    The node that was selected before, if any.
+    The node that was selected before, if any. When several nodes were
+    selected, this is the first, and the others get a `tree.deselect`,
+    dispatched before this event.
     */
     deselectedNode: Node | null;
     /**
@@ -155,13 +157,17 @@ export interface TreeEvents {
    * is clicked again or passed to `selectNode` again with
    * `mustToggle: true`. No `tree.select` is dispatched for it.
    *
+   * When several nodes are selected and a click or `selectNode` selects just
+   * one node, it is dispatched for each node that loses the selection, except
+   * the one in the `deselectedNode` of `tree.select`.
+   *
    * ```js
    * element.addEventListener("tree.deselect", (e) => {
    *   console.log("deselected", e.detail.node.name);
    * });
    * ```
    *
-   * Selecting another node does not dispatch it — that is a `tree.select`
+   * Selecting another node does not dispatch it—that is a `tree.select`
    * with the previous node in `deselectedNode`. It is also not dispatched
    * by `selectNode` without `mustToggle: true`, `selectNode(null)`,
    * `removeFromSelection`, `removeNode`, `loadData` and restoring a saved
@@ -198,7 +204,7 @@ export interface TreeEvents {
   };
   /**
    * Dispatched when data is set on the tree, both from the `data` option
-   * and from a url.
+   * and from a URL.
    *
    * @group Loading data
    */
@@ -223,7 +229,7 @@ export interface TreeEvents {
   };
   /**
    * Dispatched when a request finishes. It is dispatched when the request
-   * fails too; a [`tree.load_failed`](#tree-load-failed) follows it.
+   * fails too, and a [`tree.load_failed`](#tree-load-failed) follows it.
    *
    * @group Loading data
    */

package/src/folderOpenState.ts

@@ -0,0 +1,38 @@
+import type { ClassNames } from "./classNames";
+
+import { getBoolString } from "./util";
+
+export interface FolderIcons {
+  closed?: globalThis.Node;
+  opened?: globalThis.Node;
+}
+
+/* The open state of a folder is shown on the toggler and on the <li>.
+ * These are used both when a folder is rendered and when it is opened or
+ * closed, so a rendered folder looks the same as a toggled one.
+ */
+
+export const setTogglerOpenState = (
+  toggler: HTMLElement,
+  isOpen: boolean,
+  classNames: ClassNames,
+  icons: FolderIcons,
+): void => {
+  toggler.classList.toggle(classNames.closed, !isOpen);
+  toggler.replaceChildren();
+
+  const iconElement = isOpen ? icons.opened : icons.closed;
+
+  if (iconElement) {
+    toggler.append(iconElement.cloneNode(true));
+  }
+};
+
+export const setFolderLiOpenState = (
+  li: HTMLElement,
+  isOpen: boolean,
+  classNames: ClassNames,
+): void => {
+  li.classList.toggle(classNames.closed, !isOpen);
+  li.setAttribute("aria-expanded", getBoolString(isOpen));
+};