@limble/limble-tree 1.0.0-alpha.1 → 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() {
@@ -27,7 +26,7 @@ class TreeCollapser {
             branch.graftTo(treeBranch);
         });
         this.tempStorage.delete(treeBranch);
-        treeBranch.getContents().changeDetectorRef.detectChanges();
+        treeBranch.detectChanges();
     }
     isCollapsed(treeBranch) {
         return this.tempStorage.has(treeBranch);
@@ -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,119 +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;
-        if (!(dataTransfer instanceof DataTransfer)) {
-            throw new Error("bad drag event");
-        }
-        const nativeElement = treeBranch.getContents().location.nativeElement;
-        const [xOffset, yOffset] = this.getDragImageOffsets(event, nativeElement);
-        dataTransfer.setDragImage(nativeElement, xOffset, yOffset);
-    }
-    watchForDragend(treeBranch, event) {
-        const oldParent = treeBranch.parent();
-        const oldIndex = treeBranch.index();
-        if (oldParent === undefined || oldIndex === undefined) {
-            throw new Error("branch must have a parent");
-        }
-        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())?.allowDragging ??
-            (() => true);
-        return allowDragging(treeBranch);
-    }
-    graftDraggedBranch(treeBranch, parent, index) {
-        treeBranch.graftTo(parent, index);
-        treeBranch.getContents().location.nativeElement.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);
             });
         });
@@ -303,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
             }] } });
 
@@ -336,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: [{
@@ -359,22 +223,14 @@ class BranchComponent {
         this.showLateralDropzone = false;
     }
     ngAfterViewInit() {
-        if (this.contentContainer === undefined) {
-            throw new TreeError("Cannot get contentContainer");
-        }
-        if (this.contentToHost === undefined) {
-            throw new TreeError("'content' is a required input");
-        }
+        assert(this.contentContainer !== undefined);
+        assert(this.contentToHost !== undefined);
         this.hostedContent = this.contentContainer.createComponent(this.contentToHost);
         this.contentCreated.emit(this.hostedContent.instance);
-        if (this.dropzones === undefined) {
-            throw new Error("querylist not defined");
-        }
+        assert(this.dropzones !== undefined);
         const inner = this.dropzones.get(0);
         const lateral = this.dropzones.get(1);
-        if (inner === undefined || lateral == undefined) {
-            throw new Error("dropzones not defined");
-        }
+        assert(inner !== undefined && lateral !== undefined);
         merge(inner.dropped.pipe(map(() => "inner")), lateral.dropped.pipe(map(() => "lateral"))).subscribe(this.dropped);
         this.hostedContent.changeDetectorRef.detectChanges();
     }
@@ -403,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"] }]
@@ -426,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;
@@ -436,9 +448,6 @@ class GraftEvent {
     child() {
         return this._child;
     }
-    type() {
-        return "graft";
-    }
     index() {
         return this._index;
     }
@@ -450,6 +459,7 @@ class GraftEvent {
     }
 }
 
+/** Emitted when a branch is pruned from its parent branch */
 class PruneEvent {
     constructor(source, relationship) {
         this._source = source;
@@ -460,9 +470,6 @@ class PruneEvent {
     child() {
         return this._child;
     }
-    type() {
-        return "prune";
-    }
     index() {
         return this._index;
     }
@@ -476,6 +483,7 @@ class PruneEvent {
 
 class TreeNodeBase {
     constructor() {
+        this.destroyed = false;
         this._branches = [];
         this.events$ = new Subject();
         this.subscriptions = [
@@ -490,17 +498,14 @@ class TreeNodeBase {
     branches() {
         return [...this._branches];
     }
-    deleteBranch(index) {
-        if (index === undefined) {
-            this._branches.pop();
-            return;
-        }
-        this._branches.splice(index, 1);
-    }
     destroy() {
+        this.branches().forEach((branch) => {
+            branch.destroy();
+        });
         this.subscriptions.forEach((sub) => {
             sub.unsubscribe();
         });
+        this.destroyed = true;
     }
     dispatch(event) {
         this.events$.next(event);
@@ -511,6 +516,9 @@ class TreeNodeBase {
     getBranch(index) {
         return this._branches[index];
     }
+    isDestroyed() {
+        return this.destroyed;
+    }
     plot() {
         return new Map(this.branches().map((branch, index) => [index, branch.plot()]));
     }
@@ -521,7 +529,7 @@ class TreeNodeBase {
     }
     deregisterChildRelationship(child) {
         const index = this.branches().findIndex((branch) => branch === child);
-        this.deleteBranch(index);
+        this._branches.splice(index, 1);
     }
     graftsToSelf() {
         return this.events().pipe(filter((event) => event instanceof GraftEvent), filter((event) => event.parent().events() === this.events$));
@@ -538,6 +546,16 @@ class TreeNodeBase {
     }
 }
 
+/** Emitted when a node is destroyed */
+class DestructionEvent {
+    constructor(source) {
+        this._source = source;
+    }
+    source() {
+        return this._source;
+    }
+}
+
 class RootComponent {
     constructor() {
         this.branchesContainer = undefined;
@@ -548,9 +566,7 @@ class RootComponent {
     }
     ngAfterViewInit() {
         this.afterViewInit.emit();
-        if (this.dropzone === undefined) {
-            throw new Error("dropzone is not defined");
-        }
+        assert(this.dropzone !== undefined);
         this.dropzone.dropped.subscribe(this.dropped);
     }
 }
@@ -571,71 +587,225 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
                 type: Output
             }] } });
 
-class TreeRoot {
-    constructor(viewContainerRef) {
-        this.viewContainerRef = viewContainerRef;
-        this.treeNodeBase = new TreeNodeBase();
-        this.rootComponentRef =
-            this.viewContainerRef.createComponent(RootComponent);
+/**
+ * A wrapper around the BranchComponent that helps instantiate it and handles its events.
+ */
+class RootController {
+    constructor(treeRoot, viewContainerRef) {
+        this.treeRoot = treeRoot;
+        this.rootComponentRef = viewContainerRef.createComponent(RootComponent);
         const viewInitSub = this.rootComponentRef.instance.afterViewInit.subscribe(() => {
             const dropzone = this.rootComponentRef.instance.dropzone;
-            if (!dropzone) {
-                throw new Error("dropzone not defined");
-            }
-            dropzoneRenderer.registerDropzone(dropzone, this);
+            assert(dropzone !== undefined);
+            dropzoneRenderer.registerDropzone(dropzone, this.treeRoot);
         });
         const droppedSub = this.rootComponentRef.instance.dropped.subscribe(() => {
-            dropzoneRenderer.handleDrop(this, "inner");
+            dropzoneRenderer.handleDrop(this.treeRoot, "inner");
         });
         this.instanceSubscriptions = [viewInitSub, droppedSub];
+    }
+    destroy() {
+        this.instanceSubscriptions.forEach((sub) => {
+            sub.unsubscribe();
+        });
+    }
+    detectChanges() {
         this.rootComponentRef.changeDetectorRef.detectChanges();
     }
+    getBranchesContainer() {
+        return this.rootComponentRef.instance.branchesContainer;
+    }
+    getComponentInstance() {
+        return this.rootComponentRef.instance;
+    }
+    getHostView() {
+        return this.rootComponentRef.hostView;
+    }
+    getNativeElement() {
+        return this.rootComponentRef.location.nativeElement;
+    }
+}
+
+/**
+ * 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;
+        this.treeNodeBase = new TreeNodeBase();
+        this.rootController = new RootController(this, viewContainerRef);
+        this.detectChanges();
+    }
+    /** @returns All child branches as an array of TreeBranch instances */
     branches() {
         return this.treeNodeBase.branches();
     }
-    deleteBranch(index) {
-        this.treeNodeBase.deleteBranch(index);
-    }
+    /**
+     * 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");
+        }
         dropzoneRenderer.clearTreeFromRegistry(this);
-        this.branches().forEach((branch) => {
-            branch.destroy();
-        });
         this.treeNodeBase.destroy();
-        this.instanceSubscriptions.forEach((sub) => {
-            sub.unsubscribe();
-        });
+        this.rootController.destroy();
         this.viewContainerRef.clear();
         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);
     }
-    getContents() {
-        return this.rootComponentRef;
+    /** @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);
@@ -650,29 +820,126 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
             args: [{ providedIn: "root" }]
         }] });
 
+/**
+ * A wrapper around the BranchComponent that helps instantiate it and handles its events.
+ */
+class BranchController {
+    constructor(treeBranch, parentBranchesContainer) {
+        this.treeBranch = treeBranch;
+        this.outputBindingSubscriptions = [];
+        this.branchComponentRef = createComponent(BranchComponent, {
+            environmentInjector: parentBranchesContainer.injector.get(EnvironmentInjector)
+        });
+        this.branchComponentRef.instance.contentToHost =
+            this.treeBranch.branchOptions.component;
+        this.instanceSubscriptions = this.getInstanceSubscriptions(this.branchComponentRef.instance);
+    }
+    destroy() {
+        this.instanceSubscriptions.forEach((sub) => {
+            sub.unsubscribe();
+        });
+        this.outputBindingSubscriptions.forEach((sub) => {
+            sub.unsubscribe();
+        });
+    }
+    detectChanges() {
+        this.branchComponentRef.changeDetectorRef.detectChanges();
+    }
+    getBranchesContainer() {
+        return this.branchComponentRef.instance.branchesContainer;
+    }
+    getComponentInstance() {
+        return this.branchComponentRef.instance;
+    }
+    getHostView() {
+        return this.branchComponentRef.hostView;
+    }
+    getNativeElement() {
+        return this.branchComponentRef.location.nativeElement;
+    }
+    getUserlandComponentRef() {
+        return this.branchComponentRef.instance.getHostedContent();
+    }
+    getContentCreatedSub(instance) {
+        return instance.contentCreated.subscribe((userlandComponentInstance) => {
+            const component = userlandComponentInstance;
+            Object.entries(this.treeBranch.branchOptions.inputBindings ?? {}).forEach(([key, value]) => {
+                component[key] = value;
+            });
+            Object.entries(this.treeBranch.branchOptions.outputBindings ?? {}).forEach(([key, value]) => {
+                this.outputBindingSubscriptions.push(component[key].subscribe(value));
+            });
+            component.treeBranch = this.treeBranch;
+            const dropzones = instance.dropzones;
+            assert(dropzones !== undefined);
+            dropzoneRenderer.registerDropzones(dropzones, this.treeBranch);
+        });
+    }
+    getInstanceSubscriptions(instance) {
+        const droppedSub = instance.dropped.subscribe((placement) => {
+            dropzoneRenderer.handleDrop(this.treeBranch, placement);
+        });
+        return [
+            this.getContentCreatedSub(instance),
+            this.getShowLowerZonesSub(instance),
+            this.getShowUpperZonesSub(instance),
+            droppedSub
+        ];
+    }
+    getShowLowerZonesSub(instance) {
+        return instance.showDropzones
+            .pipe(filter((direction) => direction === "lower"))
+            .subscribe(() => {
+            const currentDropzoneDisplayed = dropzoneRenderer.getCurrentDisplay();
+            if (currentDropzoneDisplayed?.treeBranch === this.treeBranch &&
+                currentDropzoneDisplayed.direction === "lower") {
+                return;
+            }
+            dropzoneRenderer.showLowerZones(this.treeBranch);
+            instance.triggerChangeDetection();
+        });
+    }
+    getShowUpperZonesSub(instance) {
+        return instance.showDropzones
+            .pipe(filter((direction) => direction === "upper"))
+            .subscribe(() => {
+            const currentDropzoneDisplayed = dropzoneRenderer.getCurrentDisplay();
+            if (currentDropzoneDisplayed?.treeBranch === this.treeBranch &&
+                currentDropzoneDisplayed.direction === "upper") {
+                return;
+            }
+            dropzoneRenderer.showUpperZones(this.treeBranch);
+            instance.triggerChangeDetection();
+        });
+    }
+}
+
+/** 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;
         this.detachedView = null;
         this.treeNodeBase = new TreeNodeBase();
-        this.userlandComponent = this.branchOptions.component;
-        const parentBranchesContainer = parent.getContents().instance.branchesContainer;
+        const parentBranchesContainer = parent.getBranchesContainer();
         assert(parentBranchesContainer !== undefined);
-        this.contents = createComponent(BranchComponent, {
-            environmentInjector: parentBranchesContainer.injector.get(EnvironmentInjector)
-        });
-        this.contents.instance.contentToHost = this.userlandComponent;
+        this.branchController = new BranchController(this, parentBranchesContainer);
         this.setIndentation(parent);
-        this.outputBindingSubscriptions = [];
-        this.instanceSubscriptions = this.getInstanceSubscriptions();
         if (parent instanceof TreeBranch &&
-            parent.branchOptions.startCollapsed === true) {
+            parent.branchOptions.defaultCollapsed === true) {
             treeCollapser.storePrecollapsedNode(parent, this);
-            this.detachedView = this.contents.hostView;
+            this.detachedView = this.branchController.getHostView();
         }
         else {
-            parentBranchesContainer.insert(this.contents.hostView);
-            this.contents.changeDetectorRef.detectChanges();
+            parentBranchesContainer.insert(this.branchController.getHostView());
+            this.detectChanges();
             this._parent = parent;
             this.dispatch(new GraftEvent(this, {
                 parent: this._parent,
@@ -681,50 +948,127 @@ class TreeBranch {
             }));
         }
     }
+    /** @returns All child branches as an array of TreeBranch instances, in order. */
     branches() {
         return this.treeNodeBase.branches();
     }
-    deleteBranch(index) {
-        this.treeNodeBase.deleteBranch(index);
-    }
+    /**
+     * 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 (treeCollapser.isCollapsed(this)) {
-            treeCollapser.expand(this);
-            dropzoneRenderer.clearTreeFromRegistry(this);
-        }
-        this.branches().forEach((branch) => {
-            branch.destroy();
-        });
-        const parent = this._parent;
-        const index = this.index();
-        if (index !== undefined && parent !== undefined) {
-            const container = parent.getContents().instance.branchesContainer;
-            assert(container !== undefined);
-            container.remove(index);
-            parent.deleteBranch(index);
+        if (this.isDestroyed()) {
+            throw new TreeError("Cannot destroy a destroyed tree branch");
         }
+        this.prune();
+        treeCollapser.expand(this);
+        dropzoneRenderer.clearTreeFromRegistry(this);
+        this.branchController.getHostView().destroy();
         this.treeNodeBase.destroy();
-        this.instanceSubscriptions.forEach((sub) => {
-            sub.unsubscribe();
-        });
-        this.outputBindingSubscriptions.forEach((sub) => {
-            sub.unsubscribe();
-        });
-    }
+        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);
     }
-    getContents() {
-        return this.contents;
+    /** @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();
         if (ownIndex !== undefined) {
             this.prune();
@@ -739,9 +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;
@@ -752,15 +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) {
@@ -772,12 +1203,28 @@ 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");
+        }
         const parent = this._parent;
         const index = this.index();
         if (index === undefined || parent === undefined)
             return;
-        const container = parent.getContents().instance.branchesContainer;
+        const container = parent.getBranchesContainer();
         assert(container !== undefined);
         this.detachedView = container.detach(index);
         assert(this.detachedView !== null);
@@ -790,83 +1237,56 @@ 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 === undefined) {
-            return undefined;
-        }
         if (parent instanceof TreeBranch) {
             return parent.root();
         }
-        if (parent instanceof TreeRoot) {
-            return parent;
-        }
-        throw new Error("unexpected parent type");
-    }
+        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);
     }
-    getContentCreatedSub() {
-        const instance = this.contents.instance;
-        return instance.contentCreated.subscribe((userlandComponentInstance) => {
-            for (const [key, value] of Object.entries(this.branchOptions.inputBindings ?? {})) {
-                userlandComponentInstance[key] = value;
-            }
-            for (const [key, value] of Object.entries(this.branchOptions.outputBindings ?? {})) {
-                this.outputBindingSubscriptions.push(userlandComponentInstance[key].subscribe(value));
-            }
-            userlandComponentInstance.treeBranch = this;
-            const dropzones = instance.dropzones;
-            if (!dropzones) {
-                throw new Error("dropzones not defined");
-            }
-            dropzoneRenderer.registerDropzones(dropzones, this);
-        });
-    }
-    getInstanceSubscriptions() {
-        const droppedSub = this.contents.instance.dropped.subscribe((placement) => {
-            dropzoneRenderer.handleDrop(this, placement);
-        });
-        return [
-            this.getContentCreatedSub(),
-            this.getShowLowerZonesSub(),
-            this.getShowUpperZonesSub(),
-            droppedSub
-        ];
-    }
-    getShowLowerZonesSub() {
-        const instance = this.contents.instance;
-        return instance.showDropzones
-            .pipe(filter((direction) => direction === "lower"))
-            .subscribe(() => {
-            const currentDropzoneDisplayed = dropzoneRenderer.getCurrentDisplay();
-            if (currentDropzoneDisplayed?.treeBranch === this &&
-                currentDropzoneDisplayed.direction === "lower") {
-                return;
+    checkGraftLocationValidity(newParent, index) {
+        if (this.isDestroyed()) {
+            throw new TreeError("Cannot graft a destroyed tree branch");
+        }
+        if (newParent.isDestroyed()) {
+            throw new TreeError("Cannot graft to a destroyed tree branch");
+        }
+        if (typeof index === "number" &&
+            this.indexIsOutOfRange(newParent, index)) {
+            throw new TreeError(`Cannot graft branch at index ${index} of the parent. Out of range.`);
+        }
+        this.traverse((node) => {
+            if (node === newParent) {
+                throw new TreeError("Cannot graft a branch to itself or any of its own descendants");
             }
-            dropzoneRenderer.showLowerZones(this);
-            instance.triggerChangeDetection();
         });
     }
-    getShowUpperZonesSub() {
-        const instance = this.contents.instance;
-        return instance.showDropzones
-            .pipe(filter((direction) => direction === "upper"))
-            .subscribe(() => {
-            const currentDropzoneDisplayed = dropzoneRenderer.getCurrentDisplay();
-            if (currentDropzoneDisplayed?.treeBranch === this &&
-                currentDropzoneDisplayed.direction === "upper") {
-                return;
-            }
-            dropzoneRenderer.showUpperZones(this);
-            instance.triggerChangeDetection();
-        });
+    indexIsOutOfRange(parent, index) {
+        return index < 0 || index > parent.branches().length;
     }
     reattachView(index) {
         assert(this._parent !== undefined);
         assert(this.detachedView !== null);
-        const container = this._parent.getContents().instance.branchesContainer;
+        const container = this._parent.getBranchesContainer();
         assert(container !== undefined);
         this.detachedView.reattach();
         container.insert(this.detachedView, index);
@@ -876,7 +1296,8 @@ class TreeBranch {
         const root = parent.root();
         assert(root !== undefined);
         const options = config.getConfig(root);
-        const branchesContainerEl = this.contents.location.nativeElement
+        const branchesContainerEl = this.branchController
+            .getNativeElement()
             .getElementsByClassName("branches-container")
             .item(0);
         assert(branchesContainerEl instanceof HTMLElement);
@@ -916,7 +1337,7 @@ class DropzoneRenderer {
         if (this.currentDisplay === null)
             return;
         for (const branch of this.registry.values()) {
-            const instance = branch.getContents().instance;
+            const instance = branch.getComponentInstance();
             instance.showInnerDropzone = false;
             if (instance instanceof BranchComponent) {
                 instance.showLateralDropzone = false;
@@ -1017,7 +1438,7 @@ class DropzoneRenderer {
             return true;
         }
         if (treeNode instanceof TreeBranch) {
-            const allowNesting = config.getConfig(treeNode.root())?.allowNesting ??
+            const allowNesting = config.getConfig(treeNode.root())?.dragAndDrop?.allowNesting ??
                 (() => true);
             return allowNesting(treeNode);
         }
@@ -1027,11 +1448,13 @@ class DropzoneRenderer {
         const sourceNode = dragState.getDragData();
         assert(sourceNode instanceof TreeBranch);
         if (parent instanceof TreeRoot) {
-            const allowDrop = config.getConfig(parent)?.allowDrop ?? (() => true);
+            const allowDrop = config.getConfig(parent)?.dragAndDrop?.allowDrop ??
+                (() => true);
             return allowDrop(sourceNode, parent, index);
         }
         if (parent instanceof TreeBranch) {
-            const allowDrop = config.getConfig(parent.root())?.allowDrop ?? (() => true);
+            const allowDrop = config.getConfig(parent.root())?.dragAndDrop?.allowDrop ??
+                (() => true);
             return allowDrop(sourceNode, parent, index);
         }
         throw new Error("unsupported treeNode type");
@@ -1039,31 +1462,48 @@ class DropzoneRenderer {
     showInnerZone(treeNode) {
         if (!this.nestingAllowed(treeNode) || !this.dropAllowed(treeNode, 0))
             return;
-        treeNode.getContents().instance.showInnerDropzone = true;
+        treeNode.getComponentInstance().showInnerDropzone = true;
     }
     showLateralZone(treeBranch) {
         const index = treeBranch.index();
         assert(index !== undefined);
         if (!this.dropAllowed(treeBranch.parent(), index + 1))
             return;
-        treeBranch.getContents().instance.showLateralDropzone = true;
+        treeBranch.getComponentInstance().showLateralDropzone = true;
     }
 }
 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();
     }
@@ -1074,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,
@@ -1094,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 });
@@ -1132,32 +1576,34 @@ class LegacyTree {
     upgradeOptions(legacyOptions) {
         return {
             indentation: legacyOptions.indent,
-            allowNesting: (branch) => {
-                if (legacyOptions.listMode === true) {
-                    return false;
+            dragAndDrop: {
+                allowNesting: (branch) => {
+                    if (legacyOptions.listMode === true) {
+                        return false;
+                    }
+                    if (legacyOptions.allowNesting === undefined) {
+                        return true;
+                    }
+                    if (typeof legacyOptions.allowNesting === "boolean") {
+                        return legacyOptions.allowNesting;
+                    }
+                    return legacyOptions.allowNesting(branch);
+                },
+                allowDragging: (branch) => {
+                    if (legacyOptions.allowDragging === undefined) {
+                        return true;
+                    }
+                    if (typeof legacyOptions.allowDragging === "boolean") {
+                        return legacyOptions.allowDragging;
+                    }
+                    return legacyOptions.allowDragging(branch);
+                },
+                allowDrop: (source, parent, index) => {
+                    if (legacyOptions.allowDrop === undefined) {
+                        return true;
+                    }
+                    return legacyOptions.allowDrop(source, parent, index);
                 }
-                if (legacyOptions.allowNesting === undefined) {
-                    return true;
-                }
-                if (typeof legacyOptions.allowNesting === "boolean") {
-                    return legacyOptions.allowNesting;
-                }
-                return legacyOptions.allowNesting(branch);
-            },
-            allowDragging: (branch) => {
-                if (legacyOptions.allowDragging === undefined) {
-                    return true;
-                }
-                if (typeof legacyOptions.allowDragging === "boolean") {
-                    return legacyOptions.allowDragging;
-                }
-                return legacyOptions.allowDragging(branch);
-            },
-            allowDrop: (source, parent, index) => {
-                if (legacyOptions.allowDrop === undefined) {
-                    return true;
-                }
-                return legacyOptions.allowDrop(source, parent, index);
             }
         };
     }
@@ -1170,9 +1616,6 @@ class LegacyTree {
             options.defaultComponent?.bindings ??
             {});
         const nodeData = node;
-        delete nodeData.nodes;
-        delete nodeData.collapsed;
-        delete nodeData.component;
         const branch = parent.grow(component, {
             inputBindings: bindings,
             meta: { nodeData }
@@ -1273,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 });
@@ -1296,5 +1743,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "14.2.12", ngImpo
  * Generated bundle index. Do not edit.
  */
 
-export { 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