@limble/limble-tree - npm Package Compare versions

Comparing version 1.0.0-alpha.2 to 1.0.0-beta.1

lib/core/configuration/configuration.d.ts

@@ -1,3 +0,3 @@
-import { TreeRoot } from "../tree-root/tree-root";
-import { TreeOptions } from "./tree-options.interface";
+import type { TreeRoot } from "../tree-root/tree-root";
+import type { TreeOptions } from "./tree-options.interface";
 declare class Configuration {
@@ -4,0 +4,0 @@ private readonly configStorage;

lib/core/configuration/tree-options.interface.d.ts

@@ -1,24 +0,44 @@
-import { TreeBranch } from "../tree-branch/tree-branch";
-import { TreeRoot } from "../tree-root/tree-root";
+import type { TreeBranch } from "../tree-branch/tree-branch";
+import type { TreeRoot } from "../tree-root/tree-root";
+/** The configuration options for a tree, as identified by a TreeRoot */
 export interface TreeOptions {
     dragAndDrop?: {
         /**
-         * A function to indicate whether to allow a node to be dragged. The node in
-         * question is passed in. Defaults to a function that always returns true. This
-         * function runs when DragAndDropService.dragStart runs, and before the branch
-         * is pruned from the tree.
+         * A function that determines whether to allow a node to be dragged.
+         *
+         * @remarks
+         * Runs when a drag begins, but before the branch is pruned from the tree.
+         *
+         * @param treeBranch - The node of the tree that is about to be dragged.
+         *
+         * @defaultValue A function that always returns true.
+         *
+         * @returns `true` if the node can be dragged; `false` if it cannot.
          */
         allowDragging?: <T>(treeBranch: TreeBranch<T>) => boolean;
         /**
-         * A function to determine whether a sourceNode can be dropped at a particular location.
-         * The sourceNode, the new proposedParent for the sourceNode, and the new proposedIndex
-         * for the source node are passed in. This function runs just before displaying a
-         * family of dropzones.
+         * A function to determine whether a sourceNode can be dropped at a
+         * particular location.
+         *
+         * @remarks
+         * This function runs just before displaying a family of dropzones.
+         *
+         * @param sourceBranch - The branch that is being dragged.
+         * @param proposedParent - The proposed new parent of the sourceBranch.
+         * @param proposedIndex - The proposed new index of the sourceBranch.
+         *
+         * @defaultValue A function that always returns true.
          */
-        allowDrop?: <T>(sourceNode: TreeBranch<T>, proposedParent: TreeBranch<T> | TreeRoot<T>, proposedIndex: number) => boolean;
+        allowDrop?: <T>(sourceBranch: TreeBranch<T>, proposedParent: TreeBranch<T> | TreeRoot<T>, proposedIndex: number) => boolean;
         /**
-         * A function to indicate whether to allow "nesting" (placing a branch one level
-         * deeper than its parent). The node in question is passed in. Defaults to a function
-         * that always returns true. This function runs just before displaying a family of
-         * dropzones.
+         * A function to indicate whether to allow "nesting" (placing a branch as
+         * a child) of a particular branch.
+         *
+         * @remarks
+         * This function runs just before displaying a family of dropzones.
+         *
+         * @param treeBranch - The node of the tree whose nesting capability is being
+         * checked.
+         *
+         * @defaultValue A function that always returns true.
          */
@@ -29,5 +49,7 @@ allowNesting?: <T>(treeBranch: TreeBranch<T>) => boolean;
      * The number of pixels each level of the tree will be indented relative to
-     * its parent. Defaults to 16.
+     * its parent.
+     *
+     * @defaultValue 16
      */
     indentation?: number;
 }

lib/core/index.d.ts

@@ -5,2 +5,1 @@ export * from "./tree-service/tree.service";
 export * from "./configuration/tree-options.interface";
-export * from "./configuration/configuration";

lib/core/tree-branch/tree-branch.d.ts

@@ -1,11 +0,17 @@
-import { TreePlot } from "../../structure/tree-plot";
-import { Observable } from "rxjs";
-import { TreeEvent } from "../../structure/tree-event.interface";
-import { TreeBranchNode } from "../../structure/tree-branch-node.interface";
-import { ComponentRef, Type, ViewContainerRef, ViewRef } from "@angular/core";
+import type { Observable } from "rxjs";
+import type { ComponentRef, Type, ViewContainerRef, ViewRef } from "@angular/core";
 import { BranchComponent } from "../../components/branch/branch.component";
-import { NodeComponent } from "../../components/node-component.interface";
-import { BranchOptions, FullBranchOptions } from "../branch-options.interface";
+import type { NodeComponent } from "../../components/node-component.interface";
+import type { BranchOptions, FullBranchOptions } from "../branch-options.interface";
 import { TreeRoot } from "..";
-import { TreeNode } from "../../structure";
+import type { TreeNode, TreePlot, TreeEvent, TreeBranchNode } from "../../structure";
+/** 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.
+ */
 export declare class TreeBranch<UserlandComponent> implements TreeBranchNode<BranchComponent<UserlandComponent>, TreeBranch<UserlandComponent>, NodeComponent> {
@@ -18,23 +24,192 @@ readonly branchOptions: FullBranchOptions<UserlandComponent>;
     constructor(parent: TreeNode<TreeBranch<UserlandComponent>, NodeComponent>, branchOptions: FullBranchOptions<UserlandComponent>);
+    /** @returns All child branches as an array of TreeBranch instances, in order. */
     branches(): Array<TreeBranch<UserlandComponent>>;
+    /**
+     * 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(): void;
+    /** Run Angular change detection on this branch */
     detectChanges(): void;
+    /**
+     * 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: TreeEvent): void;
+    /**
+     * @returns
+     * An observable that emits TreeEvents whenever an event is dispatched
+     * in this branch or any of its descendant branches.
+     */
     events(): Observable<TreeEvent>;
+    /**
+     * @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: number): TreeBranch<UserlandComponent> | undefined;
+    /** @returns The ViewContainerRef in which child branches are rendered */
     getBranchesContainer(): ViewContainerRef | undefined;
+    /** @returns The instance of BranchComponent that is rendered by this class. */
     getComponentInstance(): BranchComponent<UserlandComponent>;
+    /** @returns The Host View in which the BranchComponent is rendered */
     getHostView(): ViewRef;
+    /** @returns The BranchComponent as a native HTML Element */
     getNativeElement(): HTMLElement;
+    /**
+     * @returns
+     * A ComponentRef containing the instance of the user-provided
+     * component which is rendered by this branch.
+     */
     getUserlandComponentRef(): ComponentRef<UserlandComponent> | undefined;
+    /**
+     * 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: TreeNode<TreeBranch<UserlandComponent>, NodeComponent>, index?: number): number;
+    /**
+     * 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: Type<UserlandComponent>, options?: BranchOptions<UserlandComponent>): TreeBranch<UserlandComponent>;
+    /**
+     * 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(): number | undefined;
+    /** @returns `true` if the branch is destroyed, `false` otherwise */
     isDestroyed(): boolean;
+    /**
+     * @returns
+     * The data that was passed into the `branchOptions`' `meta` property
+     * at construction.
+     */
     meta(): Record<string, any>;
+    /**
+     * @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(): TreeNode<TreeBranch<UserlandComponent>, NodeComponent> | undefined;
+    /**
+     * 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(): TreePlot;
+    /**
+     * 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(): Array<number>;
+    /**
+     * 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(): this | undefined;
+    /**
+     * 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(): TreeRoot<UserlandComponent> | undefined;
+    /**
+     * 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: (node: TreeNode<TreeBranch<UserlandComponent>, NodeComponent>) => void): void;
@@ -41,0 +216,0 @@ private checkGraftLocationValidity;

lib/core/tree-root/tree-root.d.ts

@@ -1,10 +0,13 @@
-import { TreePlot } from "../../structure/tree-plot";
-import { Observable } from "rxjs";
-import { TreeEvent } from "../../structure/tree-event.interface";
+import type { Observable } from "rxjs";
 import { TreeBranch } from "../tree-branch/tree-branch";
-import { Type, ViewContainerRef, ViewRef } from "@angular/core";
+import type { Type, ViewContainerRef, ViewRef } from "@angular/core";
 import { RootComponent } from "../../components/root/root.component";
-import { NodeComponent } from "../../components/node-component.interface";
-import { BranchOptions } from "../branch-options.interface";
-import { TreeNode } from "../../structure";
+import type { NodeComponent } from "../../components/node-component.interface";
+import type { BranchOptions } from "../branch-options.interface";
+import type { TreeNode, TreePlot, TreeEvent } from "../../structure";
+/**
+ * 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.
+ */
 export declare class TreeRoot<UserlandComponent> implements TreeNode<TreeBranch<UserlandComponent>, RootComponent> {
@@ -15,17 +18,107 @@ private readonly viewContainerRef;
     constructor(viewContainerRef: ViewContainerRef);
+    /** @returns All child branches as an array of TreeBranch instances */
     branches(): Array<TreeBranch<UserlandComponent>>;
+    /**
+     * 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(): void;
+    /** Run Angular change detection on the root of the tree */
     detectChanges(): void;
+    /**
+     * 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: TreeEvent): void;
+    /**
+     * @returns
+     * An observable that emits TreeEvents whenever an event is dispatched
+     * in the root or any of its descendant branches.
+     */
     events(): Observable<TreeEvent>;
+    /**
+     * @returns
+     * The child branch at the specified index, or undefined if there is
+     * no child branch at the specified index.
+     */
     getBranch(index: number): TreeBranch<UserlandComponent> | undefined;
+    /** @returns The ViewContainerRef in which child branches are rendered */
     getBranchesContainer(): ViewContainerRef | undefined;
+    /**
+     * 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(): RootComponent;
+    /** @returns The Host View in which the RootComponent is rendered */
     getHostView(): ViewRef;
+    /** @returns The RootComponent as a native HTML Element */
     getNativeElement(): HTMLElement;
+    /**
+     * 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: Type<UserlandComponent>, options?: BranchOptions<UserlandComponent>): TreeBranch<UserlandComponent>;
+    /** @returns `true` if the tree is destroyed, `false` otherwise */
     isDestroyed(): boolean;
+    /**
+     * 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(): TreePlot;
+    /** @returns Itself */
     root(): 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: (node: TreeNode<TreeBranch<UserlandComponent>, NodeComponent>) => void): void;
 }

lib/core/tree-service/tree.service.d.ts

@@ -1,6 +0,12 @@
-import { ViewContainerRef } from "@angular/core";
-import { TreeOptions } from "../configuration/tree-options.interface";
+import { type ViewContainerRef } from "@angular/core";
+import type { TreeOptions } from "../configuration/tree-options.interface";
 import { TreeRoot } from "../tree-root/tree-root";
 import * as i0 from "@angular/core";
+/** Responsible for the creation of new trees. */
 export declare class TreeService {
+    /**
+     * Creates a new, empty tree structure inside the provided container.
+     *
+     * @returns A `TreeRoot` representing the base of the new tree.
+     */
     createEmptyTree<Component>(container: ViewContainerRef, options?: TreeOptions): TreeRoot<Component>;
@@ -7,0 +13,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<TreeService, never>;

lib/events/drag/drag-end-event.d.ts

@@ -1,6 +0,6 @@
-import { NodeComponent } from "../../components/node-component.interface";
-import { TreeBranch } from "../../core";
-import { TreeNode } from "../../structure";
-import { EventConduit } from "../../structure/event-conduit.interface";
-import { TreeEvent } from "../../structure/tree-event.interface";
+import type { NodeComponent } from "../../components/node-component.interface";
+import type { TreeBranch } from "../../core";
+import type { TreeNode } from "../../structure";
+import type { TreeEvent } from "../../structure/tree-event.interface";
+/** Emitted when a drag-and-drop operation has completed */
 export declare class DragEndEvent<T> implements TreeEvent {
@@ -12,3 +12,3 @@ private readonly _source;
     private readonly _oldIndex;
-    constructor(source: EventConduit, endpoints: {
+    constructor(source: TreeNode<TreeBranch<T>, NodeComponent>, endpoints: {
         oldParent: TreeNode<TreeBranch<T>, NodeComponent>;
@@ -19,8 +19,11 @@ oldIndex: number;
     });
-    type(): "drag end";
-    source(): EventConduit;
+    /** @returns The new index of the dropped branch */
     newIndex(): number;
+    /** @returns The new parent of the dropped branch */
     newParent(): TreeNode<TreeBranch<T>, NodeComponent>;
+    /** @returns The index of the dropped branch before it was dragged */
     oldIndex(): number;
+    /** @returns The parent of the dropped branch before it was dragged */
     oldParent(): TreeNode<TreeBranch<T>, NodeComponent>;
+    source(): TreeNode<TreeBranch<T>, NodeComponent>;
 }

lib/events/drag/drag-start-event.d.ts

@@ -1,8 +0,9 @@
-import { EventConduit } from "../../structure/event-conduit.interface";
-import { TreeEvent } from "../../structure/tree-event.interface";
+import type { NodeComponent } from "../../components/node-component.interface";
+import type { TreeNode } from "../../structure";
+import type { TreeEvent } from "../../structure/tree-event.interface";
+/** Emitted when a TreeBranch begins being dragged */
 export declare class DragStartEvent implements TreeEvent {
     private readonly _source;
-    constructor(source: EventConduit);
-    type(): "drag start";
-    source(): EventConduit;
+    constructor(source: TreeNode<unknown, NodeComponent>);
+    source(): TreeNode<unknown, NodeComponent>;
 }

lib/events/drag/drop-event.d.ts

@@ -1,4 +0,5 @@
-import { NodeComponent } from "../../components/node-component.interface";
-import { TreeBranch } from "../../core";
-import { TreeNode, EventConduit, TreeEvent } from "../../structure";
+import type { NodeComponent } from "../../components/node-component.interface";
+import type { TreeBranch } from "../../core";
+import type { TreeNode, TreeEvent } from "../../structure";
+/** Emitted when a TreeBranch is dropped into a valid Dropzone */
 export declare class DropEvent<T> implements TreeEvent {
@@ -8,7 +9,6 @@ private readonly _source;
     private readonly _index;
-    constructor(source: EventConduit, parent: TreeNode<TreeBranch<T>, NodeComponent>, index: number);
-    type(): "drag end";
-    source(): EventConduit;
+    constructor(source: TreeNode<TreeBranch<T>, NodeComponent>, parent: TreeNode<TreeBranch<T>, NodeComponent>, index: number);
+    source(): TreeNode<TreeBranch<T>, NodeComponent>;
     index(): number;
     parent(): TreeNode<TreeBranch<T>, NodeComponent>;
 }

lib/events/general/destruction-event.d.ts

@@ -1,8 +0,8 @@
-import { EventConduit } from "../../structure/event-conduit.interface";
-import { TreeEvent } from "../../structure/tree-event.interface";
+import type { NodeComponent } from "../../components/node-component.interface";
+import type { TreeNode, TreeEvent } from "../../structure";
+/** Emitted when a node is destroyed */
 export declare class DestructionEvent implements TreeEvent {
     private readonly _source;
-    constructor(source: EventConduit);
-    type(): "destruction";
-    source(): EventConduit;
+    constructor(source: TreeNode<unknown, NodeComponent>);
+    source(): TreeNode<unknown, NodeComponent>;
 }

lib/events/relational/graft-event.d.ts

@@ -1,4 +0,4 @@
-import { EventConduit } from "../../structure/event-conduit.interface";
-import { RelationalTreeEvent } from "./relational-tree-event.interface";
-import { TreeRelationship } from "../../structure/tree-relationship.interface";
+import type { RelationalTreeEvent } from "./relational-tree-event.interface";
+import type { TreeRelationship } from "../../structure/tree-relationship.interface";
+/** Emits when a branch is grafted to another tree node */
 export declare class GraftEvent<T extends TreeRelationship<any, any>> implements RelationalTreeEvent<T["parent"], T["child"]> {
@@ -9,8 +9,7 @@ private readonly _source;
     private readonly _index;
-    constructor(source: EventConduit, relationship: T);
+    constructor(source: T["child"], relationship: T);
     child(): T["child"];
-    type(): "graft";
     index(): number;
     parent(): T["parent"];
-    source(): EventConduit;
+    source(): T["child"];
 }

lib/events/relational/prune-event.d.ts

@@ -1,4 +0,4 @@
-import { EventConduit } from "../../structure/event-conduit.interface";
-import { RelationalTreeEvent } from "./relational-tree-event.interface";
-import { TreeRelationship } from "../../structure/tree-relationship.interface";
+import type { RelationalTreeEvent } from "./relational-tree-event.interface";
+import type { TreeRelationship } from "../../structure/tree-relationship.interface";
+/** Emitted when a branch is pruned from its parent branch */
 export declare class PruneEvent<T extends TreeRelationship<any, any>> implements RelationalTreeEvent<T["parent"], T["child"]> {
@@ -9,8 +9,7 @@ private readonly _source;
     private readonly _index;
-    constructor(source: EventConduit, relationship: T);
+    constructor(source: T["child"], relationship: T);
     child(): T["child"];
-    type(): "prune";
     index(): number;
     parent(): T["parent"];
-    source(): EventConduit;
+    source(): T["child"];
 }

lib/events/relational/relational-tree-event.interface.d.ts

@@ -1,6 +0,10 @@
-import { TreeEvent } from "../../structure/tree-event.interface";
+import type { TreeEvent } from "../../structure/tree-event.interface";
+/** A TreeEvent which involves a parent/child relationship */
 export interface RelationalTreeEvent<Parent, Child> extends TreeEvent {
+    /** @returns The parent branch of the relationship */
     parent: () => Parent;
+    /** @returns The child branch of the relationship */
     child: () => Child;
+    /** @returns The index location of the child */
     index: () => number;
 }

lib/extras/collapse/collapse.module.d.ts

 import * as i0 from "@angular/core";
+/** A module containing the entities which provide collapse functionality */
 export declare class TreeCollapseModule {
@@ -3,0 +4,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<TreeCollapseModule, never>;

lib/extras/collapse/collapse.service.d.ts

 import { TreeBranch } from "../../core";
 import * as i0 from "@angular/core";
+/** A service that collapses and expands tree branches */
 export declare class TreeCollapseService {
+    /**
+     * Causes a TreeBranch to collapse, temporarily pruning all of its children
+     * from the tree.
+     *
+     * @param treeBranch - The branch to collapse.
+     */
     collapse<T>(treeBranch: TreeBranch<T>): void;
+    /**
+     * 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<T>(treeBranch: TreeBranch<T>): void;
+    /**
+     * 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<T>(treeBranch: TreeBranch<T>): boolean;
@@ -7,0 +32,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<TreeCollapseService, never>;

lib/extras/drag-and-drop/drag-and-drop.module.d.ts

 import * as i0 from "@angular/core";
 import * as i1 from "./draggable.directive";
 import * as i2 from "./dragover-no-change-detect";
+/**
+ * An Angular module containing all of the entities which provide Drag-And-Drop
+ * functionality.
+ */
 export declare class TreeDragAndDropModule {
@@ -5,0 +9,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<TreeDragAndDropModule, never>;

lib/extras/drag-and-drop/drag-and-drop.service.d.ts

@@ -1,8 +0,12 @@
-import { Observable } from "rxjs";
-import { TreeBranch, TreeRoot } from "../../core";
+import type { Observable } from "rxjs";
+import type { TreeBranch, TreeRoot } from "../../core";
 import { DragStates } from "./drag-state";
 import * as i0 from "@angular/core";
 export declare class TreeDragAndDropService {
+    /** Hides all Dropzones */
     clearDropzones(): void;
-    dragStart<T>(treeBranch: TreeBranch<T>, event: DragEvent): void;
+    /**
+     * @returns An object that indicates which dropzones are currently being displayed.
+     * If no dropzones are being displayed, then null is returned.
+     */
     getCurrentlyDisplayedDropzoneFamily(): {
@@ -12,3 +16,18 @@ treeBranch: TreeRoot<any> | TreeBranch<any>;
     } | null;
+    /**
+     * 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<T>(root: TreeRoot<T>): void;
+    /**
+     * @returns An observable that emits a number whenever the drag state changes.
+     *
+     * @remarks
+     * See the `DragStates` enum for a list of possible states.
+     */
     state(): Observable<DragStates>;
@@ -15,0 +34,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<TreeDragAndDropService, never>;

lib/extras/drag-and-drop/draggable.directive.d.ts

 import { ElementRef, Renderer2 } from "@angular/core";
-import { TreeBranch } from "../../core";
-import { TreeDragAndDropService } from "./drag-and-drop.service";
+import type { TreeBranch } from "../../core";
 import * as i0 from "@angular/core";
+/** Makes an TreeBranch draggable when the host element is dragged */
 export declare class DraggableDirective {
-    private readonly dragAndDropService;
     limbleTreeDraggable?: TreeBranch<any> | undefined;
-    constructor(dragAndDropService: TreeDragAndDropService, renderer: Renderer2, hostElement: ElementRef<HTMLElement>);
+    constructor(renderer: Renderer2, hostElement: ElementRef<HTMLElement>);
     onDragstart(event: DragEvent): void;
@@ -10,0 +9,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<DraggableDirective, never>;

lib/extras/drag-and-drop/dragover-no-change-detect.d.ts

@@ -1,7 +0,11 @@
-import { ElementRef, EventEmitter, NgZone, OnDestroy, OnInit } from "@angular/core";
+import { ElementRef, EventEmitter, NgZone, type OnDestroy, type OnInit } from "@angular/core";
 import * as i0 from "@angular/core";
+/**
+ * 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.
+ */
 export declare class DragoverNoChangeDetectDirective implements OnInit, OnDestroy {
     private readonly ngZone;
     private readonly el;
-    dragoverEventThrottle: number;
     readonly dragoverNoChangeDetect: EventEmitter<DragEvent>;
@@ -13,3 +17,3 @@ private eventSubscription;
     static ɵfac: i0.ɵɵFactoryDeclaration<DragoverNoChangeDetectDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<DragoverNoChangeDetectDirective, "[dragoverNoChangeDetect]", never, { "dragoverEventThrottle": "dragoverEventThrottle"; }, { "dragoverNoChangeDetect": "dragoverNoChangeDetect"; }, never, never, true>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<DragoverNoChangeDetectDirective, "[dragoverNoChangeDetect]", never, {}, { "dragoverNoChangeDetect": "dragoverNoChangeDetect"; }, never, never, true>;
 }

lib/legacy/legacy-component-obj.interface.d.ts

@@ -1,2 +0,2 @@
-import { Type } from "@angular/core";
+import type { Type } from "@angular/core";
 /**
@@ -3,0 +3,0 @@ * An object that references the component to be rendered and its bindings

lib/legacy/legacy-tree-data.interface.d.ts

@@ -1,2 +0,2 @@
-import { ComponentObj } from "./legacy-component-obj.interface";
+import type { ComponentObj } from "./legacy-component-obj.interface";
 /**
@@ -3,0 +3,0 @@ * An object describing a node of the tree

lib/legacy/legacy-tree-options.interface.d.ts

@@ -1,3 +0,3 @@
-import { TreeBranch, TreeRoot } from "../core";
-import { ComponentObj } from "./legacy-component-obj.interface";
+import type { TreeBranch, TreeRoot } from "../core";
+import type { ComponentObj } from "./legacy-component-obj.interface";
 /**
@@ -4,0 +4,0 @@ * A group of settings for changing the functionality of the tree

lib/legacy/legacy-tree.d.ts

@@ -1,5 +0,5 @@
-import { ViewContainerRef } from "@angular/core";
-import { TreeRoot, TreeOptions } from "../core";
-import { LimbleTreeOptions as LegacyLimbleTreeOptions } from "./legacy-tree-options.interface";
-import { LimbleTreeData } from "./legacy-tree-data.interface";
+import type { ViewContainerRef } from "@angular/core";
+import { TreeRoot, type TreeOptions } from "../core";
+import type { LimbleTreeOptions as LegacyLimbleTreeOptions } from "./legacy-tree-options.interface";
+import type { LimbleTreeData } from "./legacy-tree-data.interface";
 /**
@@ -6,0 +6,0 @@ * A shim to help with the transition from v0 to v1.

lib/legacy/limble-tree-root/limble-tree-root.component.d.ts

@@ -1,5 +0,5 @@
-import { AfterViewInit, EventEmitter, OnChanges, OnDestroy, ViewContainerRef } from "@angular/core";
-import { LimbleTreeData } from "../legacy-tree-data.interface";
-import { LimbleTreeOptions } from "../legacy-tree-options.interface";
-import { TreeRoot } from "../../core";
+import { type AfterViewInit, EventEmitter, type OnChanges, type OnDestroy, ViewContainerRef } from "@angular/core";
+import type { LimbleTreeData } from "../legacy-tree-data.interface";
+import type { LimbleTreeOptions } from "../legacy-tree-options.interface";
+import type { TreeRoot } from "../../core";
 import { DragEndEvent } from "../../events";
@@ -6,0 +6,0 @@ import * as i0 from "@angular/core";

lib/limble-tree.module.d.ts

@@ -5,2 +5,6 @@ import * as i0 from "@angular/core";
 import * as i3 from "./extras/drag-and-drop/drag-and-drop.module";
+/**
+ * Import this Angular module into your application to gain access to the
+ * components, directives, and services provided by Limble Tree.
+ */
 export declare class LimbleTreeModule {
@@ -7,0 +11,0 @@ static ɵfac: i0.ɵɵFactoryDeclaration<LimbleTreeModule, never>;

lib/structure/component-container.interface.d.ts

@@ -1,2 +0,2 @@
-import { ViewContainerRef, ViewRef } from "@angular/core";
+import type { ViewContainerRef, ViewRef } from "@angular/core";
 export interface ComponentContainer<Component> {
@@ -3,0 +3,0 @@ detectChanges: () => void;

lib/structure/index.d.ts

 export * from "./branchable.interface";
 export * from "./component-container.interface";
-export * from "./event-conduit.interface";
 export * from "./graftable.interface";
@@ -5,0 +4,0 @@ export * from "./tree-branch-node.interface";

lib/structure/tree-branch-node.interface.d.ts

@@ -1,5 +0,5 @@
-import { Graftable } from "./graftable.interface";
-import { TreeNode } from "./tree-node.interface";
+import type { Graftable } from "./graftable.interface";
+import type { TreeNode } from "./tree-node.interface";
 export declare type TreeBranchNode<Contents, Children, ParentContents> = TreeNode<Children, Contents> & Graftable<TreeNode<Children, ParentContents>> & {
     position: () => Array<number>;
 };

lib/structure/tree-event.interface.d.ts

@@ -1,5 +0,5 @@
-import { EventConduit } from "./event-conduit.interface";
+import type { TreeNode } from "./tree-node.interface";
+/** An event emitted by a node in the tree */
 export interface TreeEvent {
-    type: () => string;
-    source: () => EventConduit;
+    source: () => TreeNode<unknown, unknown>;
 }

lib/structure/tree-node.interface.d.ts

@@ -1,11 +0,14 @@
-import { Branchable } from "./branchable.interface";
-import { EventConduit } from "./event-conduit.interface";
-import { TreePlot } from "./tree-plot";
-import { TreeRoot } from "../core";
-import { ComponentContainer } from "./component-container.interface";
-export interface TreeNode<Children, Component> extends EventConduit, Branchable<Children>, ComponentContainer<Component> {
+import type { Branchable } from "./branchable.interface";
+import type { TreePlot } from "./tree-plot";
+import type { TreeRoot } from "../core";
+import type { ComponentContainer } from "./component-container.interface";
+import type { Observable } from "rxjs";
+import type { TreeEvent } from "./tree-event.interface";
+export interface TreeNode<Children, Component> extends Branchable<Children>, ComponentContainer<Component> {
+    dispatch: (event: TreeEvent) => void;
+    events: () => Observable<TreeEvent>;
+    isDestroyed: () => boolean;
     plot: () => TreePlot;
+    root: () => TreeRoot<any> | undefined;
     traverse: (callback: (node: Branchable<Children>) => void) => void;
-    root: () => TreeRoot<any> | undefined;
-    isDestroyed: () => boolean;
 }

lib/structure/tree-relationship.interface.d.ts

@@ -1,3 +0,3 @@
-import { Branchable } from "./branchable.interface";
-import { Graftable } from "./graftable.interface";
+import type { Branchable } from "./branchable.interface";
+import type { Graftable } from "./graftable.interface";
 export interface TreeRelationship<Parent extends Branchable<Child>, Child extends Graftable<Parent>> {
@@ -4,0 +4,0 @@ parent: Parent;

package.json

 {
   "name": "@limble/limble-tree",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-beta.1",
   "peerDependencies": {
@@ -5,0 +5,0 @@ "@angular/common": "^14.2.0",

README.md

@@ -334,2 +334,6 @@ # Limble Tree
 
+### Dragging Into Empty Trees
+
+Dropzones appear automatically as a branch is dragged over other branches. But what if the target tree has no other branches? In this case, a dropzone will not appear automatically. You will have to manually tell the tree when to render its dropzone using the `TreeDragAndDropService`.
+
 ### Configurable Restrictions For Drag-And-Drop
@@ -336,0 +340,0 @@

No alert changes

Improved metrics

Total package byte prevSize

755957

increased by14.36%

Lines of code

6469

increased by25.42%

Number of lines in readme file

476

increased by0.85%

Worsened metrics

Number of package files

128

decreased by-1.54%

No dependency changes