@limble/limble-tree 1.0.0-alpha.2 → 1.0.0-beta.1

package/fesm2020/limble-limble-tree.mjs

@@ -1,9 +1,8 @@
 import * as i0 from '@angular/core';
-import { Injectable, NgModule, EventEmitter, Directive, Input, Output, Component, NgZone, ViewContainerRef, ViewChild, ViewChildren, createComponent, EnvironmentInjector, HostListener } from '@angular/core';
-import { BehaviorSubject, Subject, fromEvent, merge, map, filter, first } from 'rxjs';
+import { Injectable, NgModule, EventEmitter, Directive, Output, Component, Input, NgZone, ViewContainerRef, ViewChild, ViewChildren, createComponent, EnvironmentInjector, HostListener } from '@angular/core';
+import { BehaviorSubject, fromEvent, merge, map, Subject, filter, first } from 'rxjs';
 import * as i1 from '@angular/common';
 import { CommonModule } from '@angular/common';
-import { throttleTime } from 'rxjs/operators';
 
 class TreeCollapser {
     constructor() {
@@ -38,13 +37,38 @@ class TreeCollapser {
 }
 const treeCollapser = new TreeCollapser();
 
+/** A service that collapses and expands tree branches */
 class TreeCollapseService {
+    /**
+     * Causes a TreeBranch to collapse, temporarily pruning all of its children
+     * from the tree.
+     *
+     * @param treeBranch - The branch to collapse.
+     */
     collapse(treeBranch) {
         treeCollapser.collapse(treeBranch);
     }
+    /**
+     * Causes a TreeBranch to expand, restoring all of its children which were
+     * previously pruned by a call to `collapse()`.
+     *
+     * @param treeBranch - The branch to expand.
+     */
     expand(treeBranch) {
         treeCollapser.expand(treeBranch);
     }
+    /**
+     * Determines whether a TreeBranch currently has any children which are
+     * pruned from the tree due to a call to  the `collapse()` method.
+     *
+     * @remarks
+     * Child branches which are pruned manually from the tree, rather than
+     * through the `collapse()` method, will not be considered.
+     *
+     * @param treeBranch - The branch to check.
+     *
+     * @returns `true` if the branch is currently collapsed; `false` if it is not.
+     */
     isCollapsed(treeBranch) {
         return treeCollapser.isCollapsed(treeBranch);
     }
@@ -55,6 +79,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
             type: Injectable
         }] });
 
+/** A module containing the entities which provide collapse functionality */
 class TreeCollapseModule {
 }
 TreeCollapseModule.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: TreeCollapseModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
@@ -67,66 +92,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
                 }]
         }] });
 
-class Configuration {
-    constructor() {
-        this.configStorage = new Map();
-        this.configStorage = new Map();
-    }
-    setConfig(root, options) {
-        this.configStorage.set(root, options);
-    }
-    getConfig(root) {
-        return this.configStorage.get(root);
-    }
-    delete(root) {
-        this.configStorage.delete(root);
-    }
-}
-const config = new Configuration();
-
-class TreeError extends Error {
-}
-
-class DragEndEvent {
-    constructor(source, endpoints) {
-        this._source = source;
-        this._oldParent = endpoints.oldParent;
-        this._oldIndex = endpoints.oldIndex;
-        this._newParent = endpoints.newParent;
-        this._newIndex = endpoints.newIndex;
-    }
-    type() {
-        return "drag end";
-    }
-    source() {
-        return this._source;
-    }
-    newIndex() {
-        return this._newIndex;
-    }
-    newParent() {
-        return this._newParent;
-    }
-    oldIndex() {
-        return this._oldIndex;
-    }
-    oldParent() {
-        return this._oldParent;
-    }
-}
-
-class DragStartEvent {
-    constructor(source) {
-        this._source = source;
-    }
-    type() {
-        return "drag start";
-    }
-    source() {
-        return this._source;
-    }
-}
-
 function assert(condition) {
     if (condition) {
         return;
@@ -179,115 +144,20 @@ class DragState {
 }
 const dragState = new DragState();
 
-class DropEvent {
-    constructor(source, parent, index) {
-        this._source = source;
-        this._parent = parent;
-        this._index = index;
-    }
-    type() {
-        return "drag end";
-    }
-    source() {
-        return this._source;
-    }
-    index() {
-        return this._index;
-    }
-    parent() {
-        return this._parent;
-    }
-}
-
-class DragAndDrop {
-    constructor() {
-        this.dragAborted$ = new Subject();
-    }
-    dragStart(treeBranch, event) {
-        if (!this.draggingAllowed(treeBranch)) {
-            event.preventDefault();
-            return;
-        }
-        treeBranch.dispatch(new DragStartEvent(treeBranch));
-        this.setDragEffects(treeBranch, event);
-        this.watchForDragend(treeBranch, event);
-        // We have to do a setTimeout because DOM changes are not allowed during a
-        // dragstart event.
-        setTimeout(() => {
-            dragState.starting(treeBranch);
-            treeBranch.prune();
-            dragState.dragging();
-        });
-    }
-    drop(parent, index) {
-        const treeBranch = dragState.getDragData();
-        if (treeBranch === undefined) {
-            throw new TreeError("Cannot get dragged branch");
-        }
-        this.graftDraggedBranch(treeBranch, parent, index);
-        treeBranch.dispatch(new DropEvent(treeBranch, parent, index));
-    }
-    getDragImageOffsets(event, element) {
-        const bounds = element.getBoundingClientRect();
-        const xOffset = event.clientX - bounds.left;
-        const yOffset = event.clientY - bounds.top;
-        return [xOffset, yOffset];
-    }
-    setDragEffects(treeBranch, event) {
-        const dataTransfer = event.dataTransfer;
-        assert(dataTransfer instanceof DataTransfer);
-        const nativeElement = treeBranch.getNativeElement();
-        const [xOffset, yOffset] = this.getDragImageOffsets(event, nativeElement);
-        dataTransfer.setDragImage(nativeElement, xOffset, yOffset);
-    }
-    watchForDragend(treeBranch, event) {
-        const oldParent = treeBranch.parent();
-        const oldIndex = treeBranch.index();
-        assert(oldParent !== undefined && oldIndex !== undefined);
-        event.target?.addEventListener("dragend", (dragend) => {
-            if (dragState.state() !== DragStates.Dropped) {
-                //The drag ended but a drop never occurred, so put the dragged branch back where it started.
-                this.dragAborted$.next(dragend);
-                this.graftDraggedBranch(treeBranch, oldParent, oldIndex);
-            }
-            dragState.restart();
-            const newParent = treeBranch.parent();
-            assert(newParent !== undefined);
-            const newIndex = treeBranch.index();
-            assert(newIndex !== undefined);
-            treeBranch.dispatch(new DragEndEvent(treeBranch, {
-                oldParent,
-                oldIndex,
-                newParent,
-                newIndex
-            }));
-        }, { once: true });
-    }
-    draggingAllowed(treeBranch) {
-        const allowDragging = config.getConfig(treeBranch.root())?.dragAndDrop?.allowDragging ??
-            (() => true);
-        return allowDragging(treeBranch);
-    }
-    graftDraggedBranch(treeBranch, parent, index) {
-        treeBranch.graftTo(parent, index);
-        treeBranch.getNativeElement().style.display = "block";
-        dragState.dropped();
-    }
-}
-const dragAndDrop = new DragAndDrop();
-
+/**
+ * Works just like Angular's built-in `(dragover)` event binding, but is much
+ * more performant. It throttles the event to a configurable rate (default once
+ * every 25ms) and runs outside of Angular's change detection.
+ */
 class DragoverNoChangeDetectDirective {
     constructor(ngZone, el) {
         this.ngZone = ngZone;
         this.el = el;
         this.dragoverNoChangeDetect = new EventEmitter();
-        this.dragoverEventThrottle = 25;
     }
     ngOnInit() {
         this.ngZone.runOutsideAngular(() => {
-            this.eventSubscription = fromEvent(this.el.nativeElement, "dragover")
-                .pipe(throttleTime(this.dragoverEventThrottle))
-                .subscribe(($event) => {
+            this.eventSubscription = fromEvent(this.el.nativeElement, "dragover").subscribe(($event) => {
                 this.dragoverNoChangeDetect.emit($event);
             });
         });
@@ -299,16 +169,14 @@ class DragoverNoChangeDetectDirective {
     }
 }
 DragoverNoChangeDetectDirective.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: DragoverNoChangeDetectDirective, deps: [{ token: i0.NgZone }, { token: i0.ElementRef }], target: i0.ɵɵFactoryTarget.Directive });
-DragoverNoChangeDetectDirective.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "14.2.12", type: DragoverNoChangeDetectDirective, isStandalone: true, selector: "[dragoverNoChangeDetect]", inputs: { dragoverEventThrottle: "dragoverEventThrottle" }, outputs: { dragoverNoChangeDetect: "dragoverNoChangeDetect" }, ngImport: i0 });
+DragoverNoChangeDetectDirective.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "14.2.12", type: DragoverNoChangeDetectDirective, isStandalone: true, selector: "[dragoverNoChangeDetect]", outputs: { dragoverNoChangeDetect: "dragoverNoChangeDetect" }, ngImport: i0 });
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: DragoverNoChangeDetectDirective, decorators: [{
             type: Directive,
             args: [{
                     standalone: true,
                     selector: "[dragoverNoChangeDetect]"
                 }]
-        }], ctorParameters: function () { return [{ type: i0.NgZone }, { type: i0.ElementRef }]; }, propDecorators: { dragoverEventThrottle: [{
-                type: Input
-            }], dragoverNoChangeDetect: [{
+        }], ctorParameters: function () { return [{ type: i0.NgZone }, { type: i0.ElementRef }]; }, propDecorators: { dragoverNoChangeDetect: [{
                 type: Output
             }] } });
 
@@ -332,10 +200,10 @@ class DropzoneComponent {
     }
 }
 DropzoneComponent.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: DropzoneComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
-DropzoneComponent.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "14.2.12", type: DropzoneComponent, isStandalone: true, selector: "dropzone", inputs: { placement: "placement" }, outputs: { dropped: "dropped" }, ngImport: i0, template: "<div\n   class=\"dropzone\"\n   [ngClass]=\"{ active: active }\"\n   (dragenter)=\"dragenterHandler()\"\n   (dragleave)=\"dragleaveHandler()\"\n   (dragoverNoChangeDetect)=\"dragoverHandler($event)\"\n   (drop)=\"dropHandler($event)\"\n></div>\n", styles: [".dropzone{border-radius:8px;border:1px dashed #727374;background-color:#ededed;height:20px;margin:8px 0;transition:height .2s ease-out;animation:animation .2s ease-out}.dropzone.active{border-color:#289e49;border-width:2px;background-color:#d0e8d6;height:48px}@keyframes animation{0%{height:0px;opacity:0}to{height:20px;opacity:1}}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i1.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: DragoverNoChangeDetectDirective, selector: "[dragoverNoChangeDetect]", inputs: ["dragoverEventThrottle"], outputs: ["dragoverNoChangeDetect"] }] });
+DropzoneComponent.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "14.2.12", type: DropzoneComponent, isStandalone: true, selector: "dropzone", inputs: { placement: "placement" }, outputs: { dropped: "dropped" }, ngImport: i0, template: "<div\n   class=\"dropzone\"\n   [ngClass]=\"{ active: active }\"\n   (dragenter)=\"dragenterHandler()\"\n   (dragleave)=\"dragleaveHandler()\"\n   (dragoverNoChangeDetect)=\"dragoverHandler($event)\"\n   (drop)=\"dropHandler($event)\"\n></div>\n", styles: [".dropzone{border-radius:8px;border:1px dashed #727374;background-color:#ededed;height:36px;margin:8px 0;transition:height .3s ease-out;animation:animation .3s ease-out}.dropzone.active{border-color:#289e49;border-width:2px;background-color:#d0e8d6;height:72px}@keyframes animation{0%{height:0px;opacity:0}to{height:36px;opacity:1}}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "directive", type: i1.NgClass, selector: "[ngClass]", inputs: ["class", "ngClass"] }, { kind: "directive", type: DragoverNoChangeDetectDirective, selector: "[dragoverNoChangeDetect]", outputs: ["dragoverNoChangeDetect"] }] });
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: DropzoneComponent, decorators: [{
             type: Component,
-            args: [{ standalone: true, selector: "dropzone", imports: [CommonModule, DragoverNoChangeDetectDirective], template: "<div\n   class=\"dropzone\"\n   [ngClass]=\"{ active: active }\"\n   (dragenter)=\"dragenterHandler()\"\n   (dragleave)=\"dragleaveHandler()\"\n   (dragoverNoChangeDetect)=\"dragoverHandler($event)\"\n   (drop)=\"dropHandler($event)\"\n></div>\n", styles: [".dropzone{border-radius:8px;border:1px dashed #727374;background-color:#ededed;height:20px;margin:8px 0;transition:height .2s ease-out;animation:animation .2s ease-out}.dropzone.active{border-color:#289e49;border-width:2px;background-color:#d0e8d6;height:48px}@keyframes animation{0%{height:0px;opacity:0}to{height:20px;opacity:1}}\n"] }]
+            args: [{ standalone: true, selector: "dropzone", imports: [CommonModule, DragoverNoChangeDetectDirective], template: "<div\n   class=\"dropzone\"\n   [ngClass]=\"{ active: active }\"\n   (dragenter)=\"dragenterHandler()\"\n   (dragleave)=\"dragleaveHandler()\"\n   (dragoverNoChangeDetect)=\"dragoverHandler($event)\"\n   (drop)=\"dropHandler($event)\"\n></div>\n", styles: [".dropzone{border-radius:8px;border:1px dashed #727374;background-color:#ededed;height:36px;margin:8px 0;transition:height .3s ease-out;animation:animation .3s ease-out}.dropzone.active{border-color:#289e49;border-width:2px;background-color:#d0e8d6;height:72px}@keyframes animation{0%{height:0px;opacity:0}to{height:36px;opacity:1}}\n"] }]
         }], propDecorators: { placement: [{
                 type: Input
             }], dropped: [{
@@ -391,7 +259,7 @@ class BranchComponent {
     }
 }
 BranchComponent.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: BranchComponent, deps: [{ token: i0.ApplicationRef }], target: i0.ɵɵFactoryTarget.Component });
-BranchComponent.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "14.2.12", type: BranchComponent, isStandalone: true, selector: "branch", inputs: { contentToHost: "contentToHost" }, outputs: { contentCreated: "contentCreated", showDropzones: "showDropzones", dropped: "dropped" }, viewQueries: [{ propertyName: "branchesContainer", first: true, predicate: ["branchesContainer"], descendants: true, read: ViewContainerRef }, { propertyName: "contentContainer", first: true, predicate: ["contentContainer"], descendants: true, read: ViewContainerRef }, { propertyName: "dropzones", predicate: DropzoneComponent, descendants: true }], ngImport: i0, template: "<div class=\"content\" (dragoverNoChangeDetect)=\"dragoverHandler($event)\">\n   <div #contentContainer></div>\n</div>\n<div class=\"branches-container\">\n   <dropzone placement=\"inner\" [hidden]=\"!showInnerDropzone\"></dropzone>\n   <div #branchesContainer></div>\n</div>\n<dropzone placement=\"lateral\" [hidden]=\"!showLateralDropzone\"></dropzone>\n", styles: [".branches-container{margin-left:16px}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "component", type: DropzoneComponent, selector: "dropzone", inputs: ["placement"], outputs: ["dropped"] }, { kind: "directive", type: DragoverNoChangeDetectDirective, selector: "[dragoverNoChangeDetect]", inputs: ["dragoverEventThrottle"], outputs: ["dragoverNoChangeDetect"] }] });
+BranchComponent.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "14.2.12", type: BranchComponent, isStandalone: true, selector: "branch", inputs: { contentToHost: "contentToHost" }, outputs: { contentCreated: "contentCreated", showDropzones: "showDropzones", dropped: "dropped" }, viewQueries: [{ propertyName: "branchesContainer", first: true, predicate: ["branchesContainer"], descendants: true, read: ViewContainerRef }, { propertyName: "contentContainer", first: true, predicate: ["contentContainer"], descendants: true, read: ViewContainerRef }, { propertyName: "dropzones", predicate: DropzoneComponent, descendants: true }], ngImport: i0, template: "<div class=\"content\" (dragoverNoChangeDetect)=\"dragoverHandler($event)\">\n   <div #contentContainer></div>\n</div>\n<div class=\"branches-container\">\n   <dropzone placement=\"inner\" [hidden]=\"!showInnerDropzone\"></dropzone>\n   <div #branchesContainer></div>\n</div>\n<dropzone placement=\"lateral\" [hidden]=\"!showLateralDropzone\"></dropzone>\n", styles: [".branches-container{margin-left:16px}\n"], dependencies: [{ kind: "ngmodule", type: CommonModule }, { kind: "component", type: DropzoneComponent, selector: "dropzone", inputs: ["placement"], outputs: ["dropped"] }, { kind: "directive", type: DragoverNoChangeDetectDirective, selector: "[dragoverNoChangeDetect]", outputs: ["dragoverNoChangeDetect"] }] });
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: BranchComponent, decorators: [{
             type: Component,
             args: [{ standalone: true, selector: "branch", imports: [CommonModule, DropzoneComponent, DragoverNoChangeDetectDirective], template: "<div class=\"content\" (dragoverNoChangeDetect)=\"dragoverHandler($event)\">\n   <div #contentContainer></div>\n</div>\n<div class=\"branches-container\">\n   <dropzone placement=\"inner\" [hidden]=\"!showInnerDropzone\"></dropzone>\n   <div #branchesContainer></div>\n</div>\n<dropzone placement=\"lateral\" [hidden]=\"!showLateralDropzone\"></dropzone>\n", styles: [".branches-container{margin-left:16px}\n"] }]
@@ -414,6 +282,162 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
                 type: Output
             }] } });
 
+class Configuration {
+    constructor() {
+        this.configStorage = new Map();
+        this.configStorage = new Map();
+    }
+    setConfig(root, options) {
+        this.configStorage.set(root, options);
+    }
+    getConfig(root) {
+        return this.configStorage.get(root);
+    }
+    delete(root) {
+        this.configStorage.delete(root);
+    }
+}
+const config = new Configuration();
+
+class TreeError extends Error {
+}
+
+/** Emitted when a drag-and-drop operation has completed */
+class DragEndEvent {
+    constructor(source, endpoints) {
+        this._source = source;
+        this._oldParent = endpoints.oldParent;
+        this._oldIndex = endpoints.oldIndex;
+        this._newParent = endpoints.newParent;
+        this._newIndex = endpoints.newIndex;
+    }
+    /** @returns The new index of the dropped branch */
+    newIndex() {
+        return this._newIndex;
+    }
+    /** @returns The new parent of the dropped branch */
+    newParent() {
+        return this._newParent;
+    }
+    /** @returns The index of the dropped branch before it was dragged */
+    oldIndex() {
+        return this._oldIndex;
+    }
+    /** @returns The parent of the dropped branch before it was dragged */
+    oldParent() {
+        return this._oldParent;
+    }
+    source() {
+        return this._source;
+    }
+}
+
+/** Emitted when a TreeBranch begins being dragged */
+class DragStartEvent {
+    constructor(source) {
+        this._source = source;
+    }
+    source() {
+        return this._source;
+    }
+}
+
+/** Emitted when a TreeBranch is dropped into a valid Dropzone */
+class DropEvent {
+    constructor(source, parent, index) {
+        this._source = source;
+        this._parent = parent;
+        this._index = index;
+    }
+    source() {
+        return this._source;
+    }
+    index() {
+        return this._index;
+    }
+    parent() {
+        return this._parent;
+    }
+}
+
+class DragAndDrop {
+    constructor() {
+        this.dragAborted$ = new Subject();
+    }
+    dragStart(treeBranch, event) {
+        if (!this.draggingAllowed(treeBranch)) {
+            event.preventDefault();
+            return;
+        }
+        treeBranch.dispatch(new DragStartEvent(treeBranch));
+        this.setDragEffects(treeBranch, event);
+        this.watchForDragend(treeBranch, event);
+        // We have to do a setTimeout because DOM changes are not allowed during a
+        // dragstart event.
+        setTimeout(() => {
+            dragState.starting(treeBranch);
+            treeBranch.prune();
+            dragState.dragging();
+        });
+    }
+    drop(parent, index) {
+        const treeBranch = dragState.getDragData();
+        if (treeBranch === undefined) {
+            throw new TreeError("Cannot get dragged branch");
+        }
+        this.graftDraggedBranch(treeBranch, parent, index);
+        treeBranch.dispatch(new DropEvent(treeBranch, parent, index));
+    }
+    getDragImageOffsets(event, element) {
+        const bounds = element.getBoundingClientRect();
+        const xOffset = event.clientX - bounds.left;
+        const yOffset = event.clientY - bounds.top;
+        return [xOffset, yOffset];
+    }
+    setDragEffects(treeBranch, event) {
+        const dataTransfer = event.dataTransfer;
+        assert(dataTransfer instanceof DataTransfer);
+        const nativeElement = treeBranch.getNativeElement();
+        const [xOffset, yOffset] = this.getDragImageOffsets(event, nativeElement);
+        dataTransfer.setDragImage(nativeElement, xOffset, yOffset);
+    }
+    watchForDragend(treeBranch, event) {
+        const oldParent = treeBranch.parent();
+        const oldIndex = treeBranch.index();
+        assert(oldParent !== undefined && oldIndex !== undefined);
+        event.target?.addEventListener("dragend", (dragend) => {
+            if (dragState.state() !== DragStates.Dropped) {
+                //The drag ended but a drop never occurred, so put the dragged branch back where it started.
+                this.dragAborted$.next(dragend);
+                this.graftDraggedBranch(treeBranch, oldParent, oldIndex);
+            }
+            dragState.restart();
+            const newParent = treeBranch.parent();
+            assert(newParent !== undefined);
+            const newIndex = treeBranch.index();
+            assert(newIndex !== undefined);
+            treeBranch.dispatch(new DragEndEvent(treeBranch, {
+                oldParent,
+                oldIndex,
+                newParent,
+                newIndex
+            }));
+        }, { once: true });
+    }
+    draggingAllowed(treeBranch) {
+        const allowDragging = config.getConfig(treeBranch.root())?.dragAndDrop?.allowDragging ??
+            (() => true);
+        return allowDragging(treeBranch);
+    }
+    graftDraggedBranch(treeBranch, parent, index) {
+        treeBranch.graftTo(parent, index);
+        treeBranch.getNativeElement().style.display = "block";
+        dragState.dropped();
+    }
+}
+const dragAndDrop = new DragAndDrop();
+
+/** Emits when a branch is grafted to another tree node */
 class GraftEvent {
     constructor(source, relationship) {
         this._source = source;
@@ -424,9 +448,6 @@ class GraftEvent {
     child() {
         return this._child;
     }
-    type() {
-        return "graft";
-    }
     index() {
         return this._index;
     }
@@ -438,6 +459,7 @@ class GraftEvent {
     }
 }
 
+/** Emitted when a branch is pruned from its parent branch */
 class PruneEvent {
     constructor(source, relationship) {
         this._source = source;
@@ -448,9 +470,6 @@ class PruneEvent {
     child() {
         return this._child;
     }
-    type() {
-        return "prune";
-    }
     index() {
         return this._index;
     }
@@ -527,13 +546,11 @@ class TreeNodeBase {
     }
 }
 
+/** Emitted when a node is destroyed */
 class DestructionEvent {
     constructor(source) {
         this._source = source;
     }
-    type() {
-        return "destruction";
-    }
     source() {
         return this._source;
     }
@@ -609,6 +626,11 @@ class RootController {
     }
 }
 
+/**
+ * Represents the base of the tree. It renders a very simple container for child
+ * branches. It has methods for creating and accessing those branches. It emits
+ * events when things happen in the tree.
+ */
 class TreeRoot {
     constructor(viewContainerRef) {
         this.viewContainerRef = viewContainerRef;
@@ -616,9 +638,19 @@ class TreeRoot {
         this.rootController = new RootController(this, viewContainerRef);
         this.detectChanges();
     }
+    /** @returns All child branches as an array of TreeBranch instances */
     branches() {
         return this.treeNodeBase.branches();
     }
+    /**
+     * Recursively destroys all branches of the tree, as well as itself.
+     *
+     * @remarks
+     * This releases all resources held or consumed by the tree.
+     *
+     * It is important to call this method when a tree is discarded, otherwise
+     * the tree will remain in memory and continue to consume resources.
+     */
     destroy() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot destroy a destroyed tree root");
@@ -630,64 +662,150 @@ class TreeRoot {
         config.delete(this);
         this.dispatch(new DestructionEvent(this));
     }
+    /** Run Angular change detection on the root of the tree */
     detectChanges() {
         this.rootController.detectChanges();
     }
+    /**
+     * Emits the specified TreeEvent.
+     *
+     * @remarks
+     * Caution: It is not recommended to manually emit TreeEvents that are already
+     * provided by the library. For example, it is not recommended to emit a
+     * `GraftEvent`, `DestructionEvent`, etc. These events may be used by the tree,
+     * and emitting them manually may cause unexpected behavior. Instead, we
+     * recommend implementing the TreeEvent interface with your own custom events
+     * and dispatching those.
+     *
+     * @param event - The TreeEvent that will be emitted.
+     */
     dispatch(event) {
         this.treeNodeBase.dispatch(event);
     }
+    /**
+     * @returns
+     * An observable that emits TreeEvents whenever an event is dispatched
+     * in the root or any of its descendant branches.
+     */
     events() {
         return this.treeNodeBase.events();
     }
+    /**
+     * @returns
+     * The child branch at the specified index, or undefined if there is
+     * no child branch at the specified index.
+     */
     getBranch(index) {
         return this.treeNodeBase.getBranch(index);
     }
+    /** @returns The ViewContainerRef in which child branches are rendered */
     getBranchesContainer() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get branches container from a destroyed tree root");
         }
         return this.rootController.getBranchesContainer();
     }
+    /**
+     * Retrieves the RootComponent.
+     *
+     * @remarks
+     * The RootComponent holds the BranchesContainer, as well as a single Dropzone
+     * for drag-and-drop operations.
+     *
+     * @returns The instance of RootComponent that is rendered by this class.
+     */
     getComponentInstance() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get component instance from a destroyed tree root");
         }
         return this.rootController.getComponentInstance();
     }
+    /** @returns The Host View in which the RootComponent is rendered */
     getHostView() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get component host view from a destroyed tree root");
         }
         return this.rootController.getHostView();
     }
+    /** @returns The RootComponent as a native HTML Element */
     getNativeElement() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get native element from a destroyed tree root");
         }
         return this.rootController.getNativeElement();
     }
+    /**
+     * Appends a new child branch to this branch. The child branch will render
+     * the specified component according to the (optional) configuration parameter.
+     *
+     * @param component - The component to render in the new child branch.
+     * @param options - Configuration options for the new child branch.
+     *
+     * @returns
+     * The newly-created child branch.
+     */
     grow(component, options) {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot grow a branch on a destroyed tree root");
         }
         return new TreeBranch(this, { component, ...options });
     }
+    /** @returns `true` if the tree is destroyed, `false` otherwise */
     isDestroyed() {
         return this.treeNodeBase.isDestroyed();
     }
+    /**
+     * Provides a model describing the shape of the tree.
+     *
+     * @returns A multi-dimensional Map which describes the shape of the tree.
+     *
+     * @example
+     * For example, an empty tree will return an empty Map. A tree with a single
+     * branch will return a Map with a single entry, where the key is the index
+     * of the branch (zero) and the value is an empty Map. A Tree like this:
+     *
+     * ```
+     *         ---Branch-------Branch
+     *        /
+     * Root-------Branch
+     *        \
+     *         ---Branch
+     * ```
+     * Will return a Map of matching shape:
+     * ```
+     * Map {
+     *    0: Map { 0: Map {}},
+     *    1: Map {},
+     *    2: Map {}
+     * }
+     * ```
+     */
     plot() {
         return this.treeNodeBase.plot();
     }
+    /** @returns Itself */
     root() {
         return this;
     }
+    /**
+     * Traverses the tree in depth-first pre-order, executing the provided
+     * callback function on each node. Traversal includes the Root.
+     *
+     * @param callback - A function to execute on each node.
+     */
     traverse(callback) {
         callback(this);
         this.treeNodeBase.traverse(callback);
     }
 }
 
+/** Responsible for the creation of new trees. */
 class TreeService {
+    /**
+     * Creates a new, empty tree structure inside the provided container.
+     *
+     * @returns A `TreeRoot` representing the base of the new tree.
+     */
     createEmptyTree(container, options = {}) {
         container.clear();
         const root = new TreeRoot(container);
@@ -796,6 +914,15 @@ class BranchController {
     }
 }
 
+/** Represents a standard node in a tree. Renders a BranchComponent.
+ *
+ * @remarks
+ * This class renders a branch component, which does the following:
+ * 1. Renders a component provided by the user
+ * 2. Provides a container in which child branches may be rendered
+ * 3. Contains two Dropzones: one for dropping branches below this branch (as a
+ * sibling), and one for dropping branches as a first child of this branch.
+ */
 class TreeBranch {
     constructor(parent, branchOptions) {
         this.branchOptions = branchOptions;
@@ -821,9 +948,18 @@ class TreeBranch {
             }));
         }
     }
+    /** @returns All child branches as an array of TreeBranch instances, in order. */
     branches() {
         return this.treeNodeBase.branches();
     }
+    /**
+     * Recursively destroys all descendant branches, as well as itself. This
+     * releases all resources held or consumed by this branch and its descendants.
+     *
+     * @remarks
+     * It is important to call this method when a branch is discarded, otherwise
+     * the branch will remain in memory and continue to consume resources.
+     */
     destroy() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot destroy a destroyed tree branch");
@@ -836,49 +972,101 @@ class TreeBranch {
         this.branchController.destroy();
         this.dispatch(new DestructionEvent(this));
     }
+    /** Run Angular change detection on this branch */
     detectChanges() {
         this.branchController.detectChanges();
     }
+    /**
+     * Emits the specified TreeEvent.
+     *
+     * @remarks
+     * Caution: It is not recommended to manually emit TreeEvents that are already
+     * provided by the library. For example, it is not recommended to emit a
+     * `GraftEvent`, `DestructionEvent`, etc. These events may be used by the tree,
+     * and emitting them manually may cause unexpected behavior. Instead, we
+     * recommend implementing the TreeEvent interface with your own custom events
+     * and dispatching those.
+     *
+     * @param event - The TreeEvent that will be emitted.
+     */
     dispatch(event) {
         this.treeNodeBase.dispatch(event);
         this._parent?.dispatch(event);
     }
+    /**
+     * @returns
+     * An observable that emits TreeEvents whenever an event is dispatched
+     * in this branch or any of its descendant branches.
+     */
     events() {
         return this.treeNodeBase.events();
     }
+    /**
+     * @param index - The index of the child branch to retrieve.
+     *
+     * @returns
+     * The child branch at the specified index, or undefined if there is
+     * no child branch at the specified index.
+     */
     getBranch(index) {
         return this.treeNodeBase.getBranch(index);
     }
+    /** @returns The ViewContainerRef in which child branches are rendered */
     getBranchesContainer() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get branches container from a destroyed tree branch");
         }
         return this.branchController.getBranchesContainer();
     }
+    /** @returns The instance of BranchComponent that is rendered by this class. */
     getComponentInstance() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get component instance from a destroyed tree branch");
         }
         return this.branchController.getComponentInstance();
     }
+    /** @returns The Host View in which the BranchComponent is rendered */
     getHostView() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get component host view from a destroyed tree branch");
         }
         return this.branchController.getHostView();
     }
+    /** @returns The BranchComponent as a native HTML Element */
     getNativeElement() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get native element from a destroyed tree branch");
         }
         return this.branchController.getNativeElement();
     }
+    /**
+     * @returns
+     * A ComponentRef containing the instance of the user-provided
+     * component which is rendered by this branch.
+     */
     getUserlandComponentRef() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot get userland component from a destroyed tree branch");
         }
         return this.branchController.getUserlandComponentRef();
     }
+    /**
+     * Attaches a branch to a new parent node.
+     *
+     * @remarks
+     * If not already pruned, this method prunes (removes) this branch from its
+     * current position in the tree; then grafts (reattaches) it as a child of the
+     * specified parent branch at the specified index. If no index is specified,
+     * the branch is appended as the last child of the parent. This causes this
+     * branch's associated BranchComponent to be re-rendered in the DOM at the
+     * new location.
+     *
+     * @param newParent - The new parent branch unto which this branch will be grafted.
+     * @param index - The index at which this branch will be grafted. If not specified,
+     * this branch will be appended as the last child of the new parent.
+     *
+     * @returns The index at which this branch was grafted.
+     */
     graftTo(newParent, index) {
         this.checkGraftLocationValidity(newParent, index);
         const ownIndex = this.index();
@@ -895,12 +1083,35 @@ class TreeBranch {
         }));
         return newIndex;
     }
+    /**
+     * Appends a new child branch to this branch. The child branch will render
+     * the specified component according to the (optional) configuration parameter.
+     *
+     * @param component - The component to render in the new child branch.
+     * @param options - Configuration options for the new child branch.
+     *
+     * @returns
+     * The newly-created child branch.
+     */
     grow(component, options) {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot grow a branch on a destroyed tree branch");
         }
         return new TreeBranch(this, { component, ...options });
     }
+    /**
+     * Determines this branch's index in relation to its sibling branches.
+     *
+     * @remarks
+     * For example, if it is the first child of its parent, this method will return
+     * 0. If it is the second child of its parent, this method will return 1.
+     *
+     * If this branch has no parent, (eg, if this branch has been pruned) this
+     * method will return undefined.
+     *
+     * @returns
+     * The index of this branch in relation to its sibling branches, or undefined.
+     */
     index() {
         if (!this._parent) {
             return undefined;
@@ -911,18 +1122,76 @@ class TreeBranch {
         assert(index >= 0);
         return index;
     }
+    /** @returns `true` if the branch is destroyed, `false` otherwise */
     isDestroyed() {
         return this.treeNodeBase.isDestroyed();
     }
+    /**
+     * @returns
+     * The data that was passed into the `branchOptions`' `meta` property
+     * at construction.
+     */
     meta() {
         return this.branchOptions.meta ?? {};
     }
+    /**
+     * @returns
+     * This branch's parent node (which may be a TreeBranch or TreeRoot).
+     * If this branch has no parent, (eg, if this branch has been pruned) this
+     * method will return undefined.
+     */
     parent() {
         return this._parent;
     }
+    /**
+     * Provides a model describing this branch's descendants.
+     *
+     * @returns
+     * A multi-dimensional Map which describes the shape of this branch's
+     * descendants.
+     *
+     * @example
+     * A branch with no children will return an empty Map. A branch with
+     * a single child will return a Map with a single entry, where the key is the index
+     * of the branch (zero) and the value is an empty Map. A Tree like this:
+     *
+     * ```
+     *         ---Branch-------Branch
+     *        /
+     * Branch-------Branch
+     *        \
+     *         ---Branch
+     * ```
+     * Will return a Map of matching shape:
+     * ```
+     * Map {
+     *    0: Map { 0: Map {}},
+     *    1: Map {},
+     *    2: Map {}
+     * }
+     * ```
+     */
     plot() {
         return this.treeNodeBase.plot();
     }
+    /**
+     * Calculates the branch's position in the tree relative to the Root.
+     *
+     * @remarks
+     * The position is described as an array of numbers, where each number
+     * represents the index of the branch at that level of the tree.
+     *
+     * For example, if this branch is the first child of the Root, this method
+     * will return [0]. If this branch is the second child of the first child
+     * of the Root, this method will return [0, 1].
+     *
+     * If the branch is not related to a TreeRoot, (such as when it has been
+     * pruned,) this method will throw an error.
+     *
+     * @returns
+     * An array of numbers which describe the branch's position in the tree
+     * relative to the Root.
+     */
     position() {
         const index = this.index();
         if (index === undefined) {
@@ -934,6 +1203,19 @@ class TreeBranch {
         }
         return [index];
     }
+    /**
+     * Removes a branch from its tree without destroying it.
+     *
+     * @remarks
+     * Removes this branch from its parent and detaches its associated
+     * BranchComponent from the DOM. This puts the branch in a "pruned" state,
+     * which may affect the behavior of other methods.
+     *
+     * A pruned branch can be reattached to any other node using the `graftTo` method.
+     *
+     * @returns
+     * Itself, or undefined if it is already in a pruned state.
+     */
     prune() {
         if (this.isDestroyed()) {
             throw new TreeError("Cannot prune a destroyed tree branch");
@@ -955,6 +1237,14 @@ class TreeBranch {
         this._parent = undefined;
         return this;
     }
+    /**
+     * Get the root of the tree to which this Branch is attached.
+     *
+     * @returns
+     * The TreeRoot of the tree this branch is in. If this branch is
+     * does not have a root (such as when it has been pruned) this method will
+     * return undefined.
+     */
     root() {
         const parent = this.parent();
         if (parent instanceof TreeBranch) {
@@ -963,6 +1253,12 @@ class TreeBranch {
         assert(parent instanceof TreeRoot || parent === undefined);
         return parent;
     }
+    /**
+     * Traverses this branch's descendants in depth-first pre-order, executing
+     * the provided callback function on each node. Traversal includes this branch.
+     *
+     * @param callback - A function to execute on each node.
+     */
     traverse(callback) {
         callback(this);
         this.treeNodeBase.traverse(callback);
@@ -1179,18 +1475,35 @@ class DropzoneRenderer {
 const dropzoneRenderer = new DropzoneRenderer();
 
 class TreeDragAndDropService {
+    /** Hides all Dropzones */
     clearDropzones() {
         dropzoneRenderer.clearCurrentDisplay();
     }
-    dragStart(treeBranch, event) {
-        dragAndDrop.dragStart(treeBranch, event);
-    }
+    /**
+     * @returns An object that indicates which dropzones are currently being displayed.
+     * If no dropzones are being displayed, then null is returned.
+     */
     getCurrentlyDisplayedDropzoneFamily() {
         return dropzoneRenderer.getCurrentDisplay();
     }
+    /**
+     * Causes the dropzone of the TreeRoot to be displayed.
+     *
+     * @remarks
+     * This is a useful function when you want to show the dropzone of a TreeRoot
+     * that has no child branches.
+     *
+     * @param root - The TreeRoot whose dropzone you want to show.
+     */
     showRootDropzone(root) {
         dropzoneRenderer.showLowerZones(root);
     }
+    /**
+     * @returns An observable that emits a number whenever the drag state changes.
+     *
+     * @remarks
+     * See the `DragStates` enum for a list of possible states.
+     */
     state() {
         return dragState.events();
     }
@@ -1201,19 +1514,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
             type: Injectable
         }] });
 
+/** Makes an TreeBranch draggable when the host element is dragged */
 class DraggableDirective {
-    constructor(dragAndDropService, renderer, hostElement) {
-        this.dragAndDropService = dragAndDropService;
+    constructor(renderer, hostElement) {
         renderer.setAttribute(hostElement.nativeElement, "draggable", "true");
         renderer.setStyle(hostElement.nativeElement, "cursor", "grab");
     }
     onDragstart(event) {
         if (this.limbleTreeDraggable === undefined)
             return;
-        this.dragAndDropService.dragStart(this.limbleTreeDraggable, event);
+        dragAndDrop.dragStart(this.limbleTreeDraggable, event);
     }
 }
-DraggableDirective.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: DraggableDirective, deps: [{ token: TreeDragAndDropService }, { token: i0.Renderer2 }, { token: i0.ElementRef }], target: i0.ɵɵFactoryTarget.Directive });
+DraggableDirective.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: DraggableDirective, deps: [{ token: i0.Renderer2 }, { token: i0.ElementRef }], target: i0.ɵɵFactoryTarget.Directive });
 DraggableDirective.ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "14.2.12", type: DraggableDirective, isStandalone: true, selector: "[limbleTreeDraggable]", inputs: { limbleTreeDraggable: "limbleTreeDraggable" }, host: { listeners: { "dragstart": "onDragstart($event)" } }, ngImport: i0 });
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: DraggableDirective, decorators: [{
             type: Directive,
@@ -1221,13 +1534,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
                     selector: "[limbleTreeDraggable]",
                     standalone: true
                 }]
-        }], ctorParameters: function () { return [{ type: TreeDragAndDropService }, { type: i0.Renderer2 }, { type: i0.ElementRef }]; }, propDecorators: { limbleTreeDraggable: [{
+        }], ctorParameters: function () { return [{ type: i0.Renderer2 }, { type: i0.ElementRef }]; }, propDecorators: { limbleTreeDraggable: [{
                 type: Input
             }], onDragstart: [{
                 type: HostListener,
                 args: ["dragstart", ["$event"]]
             }] } });
 
+/**
+ * An Angular module containing all of the entities which provide Drag-And-Drop
+ * functionality.
+ */
 class TreeDragAndDropModule {
 }
 TreeDragAndDropModule.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: TreeDragAndDropModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
@@ -1399,6 +1716,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
                 }]
         }] });
 
+/**
+ * Import this Angular module into your application to gain access to the
+ * components, directives, and services provided by Limble Tree.
+ */
 class LimbleTreeModule {
 }
 LimbleTreeModule.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "14.2.12", ngImport: i0, type: LimbleTreeModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
@@ -1422,5 +1743,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { DestructionEvent, DragEndEvent, DragStartEvent, DraggableDirective, DragoverNoChangeDetectDirective, DropEvent, GraftEvent, LegacyTree, LimbleTreeLegacyModule, LimbleTreeModule, LimbleTreeRootComponent, PruneEvent, TreeBranch, TreeCollapseModule, TreeCollapseService, TreeDragAndDropModule, TreeDragAndDropService, TreeError, TreeRoot, TreeService, config };
+export { DestructionEvent, DragEndEvent, DragStartEvent, DraggableDirective, DragoverNoChangeDetectDirective, DropEvent, GraftEvent, LegacyTree, LimbleTreeLegacyModule, LimbleTreeModule, LimbleTreeRootComponent, PruneEvent, TreeBranch, TreeCollapseModule, TreeCollapseService, TreeDragAndDropModule, TreeDragAndDropService, TreeError, TreeRoot, TreeService };
 //# sourceMappingURL=limble-limble-tree.mjs.map