@limble/limble-tree 0.13.0 → 1.0.0-alpha.2

package/README.md

@@ -1,149 +1,471 @@
 # Limble Tree
 
-An Angular library for creating highly dynamic drag-and-drop tree structures
+This library is currently a work in progress. It may not be suitable for production environments yet.
 
-## About
+## Description
 
-### Limble
+An Angular library for building visual tree structures. Built and used by the team at [Limble](https://limblecmms.com/);
 
-Limble is a CMMS SaaS company providing great software to customers around the world. See [limblecmms.com](https://limblecmms.com) for more information. The `limble-tree` library is built by the Limble team and used in Limble's web applications.
+Features:
 
-### Status
+-  Allows any number of different components to be rendered in the same tree.
+-  Collapsible tree branches
+-  Move branches around both programmatically and with built-in drag-and-drop.
+-  Branches can be moved between trees.
+-  No limit on tree depth or size.
+-  Recently redesigned to allow better performance with large/complex trees.
 
-This library is currently in **beta** development. It may not be ready for use in a production environment.
+## Installation
 
-### Features
+```bash
+   npm install @limble/limble-tree
+```
 
--  Unlimited tree depth
--  Can have a different component rendered for each node in the tree
--  Can drag nodes from one location in the tree to other locations
--  Dragging can be turned off for all or some of the nodes
--  Easy nesting of nodes
--  Nesting can be turned off for all or some of the nodes
--  Nodes can be dropped into other limble trees
--  Supports drag handles
--  Catchable events are fired when the tree renders and when a drop occurs
--  Pagination available for flat trees
+## Basic Usage
 
-### Warning
+A basic tree is very easy to set up.
 
-This library is compiled using Angular IVY, and therefore will not work in applications that do not also use IVY. IVY has been the default compiler for Angular since Angular 9.
+### Step 1
 
-### Versioning
+Import the limble-tree module into your own Angular module or standalone component.
 
-To the best of our ability, this library follows the [Semantic Versioning](https://semver.org/) standard.
+```typescript
+import { NgModule } from "@angular/core";
+import { LimbleTreeModule } from "@limble/limble-tree";
 
-## Installation
+@NgModule({
+   imports: [LimbleTreeModule]
+})
+export class AppModule {}
+```
+
+or
+
+```typescript
+import { Component } from "@angular/core";
+import { LimbleTreeModule } from "@limble/limble-tree";
+
+@Component({
+   standalone: true,
+   imports: [LimbleTreeModule],
+   template: `<div></div>`
+})
+export class MyComponent {}
+```
+
+### Step 2
+
+Add a template variable to the HTML element in which the tree should be rendered.
+
+```html
+<div #treeContainer></div>
+```
+
+### Step 3
+
+Use `@ViewChild` to get the `ViewContainerRef` of that element.
+
+```typescript
+@ViewChild("treeContainer", { read: ViewContainerRef }) treeContainer?: ViewContainerRef;
+```
+
+### Step 4
+
+Inject TreeService into your component.
+
+```typescript
+constructor(private readonly treeService: TreeService) {}
+```
+
+### Step 5
+
+In the `ngAfterViewInit` lifecycle hook, call `createEmptyTree()`, passing in the ViewContainerRef obtained in step 3.
+
+```typescript
+protected tree?: TreeRoot<MyTreeContentComponent>;
 
-`npm install @limble/limble-tree`
+public ngAfterViewInit(): void {
+   this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(this.treeContainer);
+}
+```
+
+### Step 6
+
+Render components in the tree by calling `grow()`.
+
+```typescript
+//Renders four instances of the MyTreeContentComponent; the fourth is nested under the third.
+const branch1 = this.tree.grow(MyTreeContentComponent);
+const branch2 = this.tree.grow(MyTreeContentComponent);
+const branch3 = this.tree.grow(MyTreeContentComponent);
+const branch3a = branch3.grow(MyTreContentComponent);
+```
+
+### Step 7
+
+That's it, you've built your first limble-tree. Here is the full component code we just built:
+
+```typescript
+import {
+   Component,
+   AfterViewInit,
+   ViewChild,
+   ViewContainerRef
+} from "@angular/core";
+import { LimbleTreeModule, TreeRoot } from "@limble/limble-tree";
+import { MyTreeContentComponent } from "somewhere in your filesystem";
+
+@Component({
+   standalone: true,
+   imports: [LimbleTreeModule],
+   template: `<div #treeContainer></div>`
+})
+export class MyComponent implements AfterViewInit {
+   @ViewChild("treeContainer", { read: ViewContainerRef })
+   treeContainer?: ViewContainerRef;
+
+   protected tree?: TreeRoot<MyTreeContentComponent>;
+
+   public constructor(private readonly treeService: TreeService) {}
+
+   public ngAfterViewInit(): void {
+      this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(
+         this.treeContainer
+      );
+      // Renders four instances of the MyTreeContentComponent;
+      // the fourth is nested under the third.
+      const branch1 = this.tree.grow(MyTreeContentComponent);
+      const branch2 = this.tree.grow(MyTreeContentComponent);
+      const branch3 = this.tree.grow(MyTreeContentComponent);
+      const branch3a = branch3.grow(MyTreContentComponent);
+   }
+}
+```
+
+## Communicating With Your Components
 
-## Usage
+### Inputs and Outputs
 
-### Basic Setup
+If the components passed to `grow()` require inputs, or if you want to watch for output events, you can pass those things into the optional second parameter.
 
-1. Add the `LimbleTreeModule` to the `imports` array of one of your own modules.
+```typescript
+tree.grow(MyTreeContentComponent, {
+   inputBindings: { myInput1: "hello world", myInput2: 1000 },
+   outputBindings: {
+      myOutput: (event) => {
+         /* Do stuff */
+      }
+   }
+});
+```
+
+The inputBindings object tells the tree to pass "hello world" into the component field named `myInput1`. Similarly, the tree will pass 1000 into the component field named "myInput2".
+
+The outputBindings object works similarly, but instead of passing values, it registers callbacks to run when the specified outputs emit events. In the example, the arrow function will be run each time the field named `myOutput` emits a value.
+
+### Special `treeBranch` Input
+
+No matter what you decide to pass through inputs, if anything, the tree will always automatically pass a TreeBranch object into the component. That object can be accessed within the component by declaring a `treeBranch` Input property.
+
+```typescript
+@Input() treeBranch?: TreeBranch<MyTreeContentComponent>;
+```
+
+This treeBranch object can be very useful for determining things like where the component lives in the tree, if it has any child branches, etc. It is also used for many of the more advanced features described elsewhere in this document.
+
+### Passing Custom Data Through The `treeBranch` Input Using `meta`
 
-2. Create an array where each element in the array represents an item in the tree (called a "node"). Children can be assigned to a node via the "nodes" property:
+If desired, you can add custom data to the treeBranch object associated with your rendered components. You can do this using another property of the second parameter of `grow()`, called `meta`.
 
 ```typescript
-const treeData: LimbleTreeData = [
-   {
-      myValue: "abc",
-      mySecondValue: 10,
-      nodes: [
-         { myValue: "def", mySecondValue: 20 },
-         {
-            myValue: "ghi",
-            mySecondValue: 30,
-            nodes: [
-               { myValue: "jkl", mySecondValue: 40 },
-               { myOtherValue: { prop1: "mno", prop2: "pqr" } }
-            ]
-         }
-      ]
-   },
-   { myOtherValue: { prop1: "stu", prop2: "vwx" } }
-];
+tree.grow(MyTreeContentComponent, {
+   meta: { myCustomDataField: "Hello World!" }
+});
 ```
 
-3. Create an object describing the tree's options.
+The value of `meta` can be accessed within your rendered component by calling `this.treeBranch.meta()`.
 
 ```typescript
-const treeOptions: LimbleTreeOptions = {
-   defaultComponent: {
-      class: MyComponentClass,
-      bindings: { binding1: value1, binding2: value2 }
-   },
-   indent: 60
-};
+@Input() treeBranch?: TreeBranch<MyTreeContentComponent>;
+
+public ngOnInit(): void {
+   console.log(this.treeBranch?.meta()) // outputs `{ myCustomDataField: "Hello World!" }`
+}
 ```
 
-4. Add a `<limble-tree-root>` component to one of your components' templates and pass it the data array and the options object:
+## Indentation
+
+By default, each level of the tree beyond the first will be indented an additional 16px. This value is configurable:
+
+```typescript
+treeService.createEmptyTree(this.treeContainer, { indentation: 32 });
+```
+
+## Collapsing Branches
+
+Tree branches which have descendant branches can be collapsed, temporarily removing its descendants from the tree. The descendants can be grafted back into the tree later, as if they were never removed.
+
+To collapse a branch, simply inject the TreeCollapseService into your component and call `collapse()`, passing in the branch to be collapsed. To restore the hidden branches, call `expand()`, passing in the same branch that was passed to `collapse()`
+
+```typescript
+constructor(private readonly collapseService: TreeCollapseService) {}
+
+public ngAfterViewInit(): void {
+   this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(
+      this.treeContainer
+   );
+   // Renders four instances of the MyTreeContentComponent;
+   // the fourth is nested under the third.
+   const branch1 = this.tree.grow(MyTreeContentComponent);
+   const branch2 = this.tree.grow(MyTreeContentComponent);
+   const branch3 = this.tree.grow(MyTreeContentComponent);
+   const branch3a = branch3.grow(MyTreContentComponent);
+
+   //Hides the fourth branch
+   this.collapseService.collapse(branch3);
+
+   //restores the fourth branch to its original place after 2 seconds have passed.
+   setTimeout(() => {
+      this.collapseService.expand(branch3);
+   }, 2000);
+}
+```
+
+A branch can be configured to be collapsed by default, which means that any children grown onto it will not be visible until `expand()` is called.
+
+```typescript
+constructor(private readonly collapseService: TreeCollapseService) {}
+
+public ngAfterViewInit(): void {
+   this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(
+      this.treeContainer
+   );
+   // Renders four instances of the MyTreeContentComponent;
+   // the fourth is nested under the third.
+   const branch1 = this.tree.grow(MyTreeContentComponent);
+   const branch2 = this.tree.grow(MyTreeContentComponent);
+   const branch3 = this.tree.grow(MyTreeContentComponent, {defaultCollapsed: true});
+   const branch3a = branch3.grow(MyTreContentComponent); // this branch will be created but not rendered
+
+   //renders the fourth branch after 2 seconds have passed.
+   setTimeout(() => {
+      this.collapseService.expand(branch3);
+   }, 2000);
+}
+```
+
+You can check if a branch can be expanded using the collapse service's `isCollapsed()` method.
+
+## Moving Branches Programmatically
+
+Branches can be moved around, both within a single tree and between different trees.
+
+```typescript
+public ngAfterViewInit(): void {
+   this.tree1 = this.treeService.createEmptyTree<MyTreeContentComponent>(
+      this.treeContainer1
+   );
+   // Renders four instances of the MyTreeContentComponent;
+   // the fourth is nested under the third.
+   const branch1 = this.tree1.grow(MyTreeContentComponent);
+   const branch2 = this.tree1.grow(MyTreeContentComponent);
+   const branch3 = this.tree1.grow(MyTreeContentComponent);
+   const branch3a = branch3.grow(MyTreContentComponent);
+
+   setTimeout(() => {
+      //moves branch1 so it is now the second child of branch3
+      branch1.graftTo(branch3);
+   }, 2000);
+
+   setTimeout(() => {
+      // moves branch1 back to its original position.
+      branch1.graftTo(this.tree1, 0);
+   }, 4000);
+
+   setTimeout(() => {
+      this.tree2 = this.treeService.createEmptyTree<MyTreeContentComponent>(
+         this.treeContainer2
+      );
+      // moves branch1 to a different tree
+      branch1.graftTo(this.tree2);
+   }, 8000);
+}
+```
+
+A branch can also be removed from a tree without immediately grafting it to a new position.
+
+```typescript
+public ngAfterViewInit(): void {
+   this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(
+      this.treeContainer
+   );
+   // Renders four instances of the MyTreeContentComponent;
+   // the fourth is nested under the third.
+   const branch1 = this.tree.grow(MyTreeContentComponent);
+   const branch2 = this.tree.grow(MyTreeContentComponent);
+   const branch3 = this.tree.grow(MyTreeContentComponent);
+   const branch3a = branch3.grow(MyTreContentComponent);
+
+   //removes branch1 from the tree after 2 seconds
+   setTimeout(() => {
+      branch1.prune();
+   }, 2000);
+
+   //restores branch1 to its original position after an additional 2 seconds
+   setTimeout(() => {
+      branch1.graftTo(this.tree, 0);
+   }, 4000);
+```
+
+Both the `prune()` and `graftTo()` methods will include all of the children of the branch as well. For example, pruning a branch that has 3 child branches will remove the parent as well as all three children; grafting the parent back into a tree will also graft the children into that tree, retaining their position as children of the moved parent.
+
+Note: use `destroy()` rather than `prune()` when you wish to completely delete a branch. See "Destroying Trees and Branches" below.
+
+## Moving Branches With Drag-And-Drop
+
+Drag and drop functionality is easy to use. Simply add the `[limbleTreeDraggable]` directive to an element of your rendered component, and pass it that component's associated TreeBranch. When the user clicks and drags the element, the branch will be pruned from the tree and dragged with the mouse.
 
 ```html
-<limble-tree-root [data]="treeData" [options]="treeOptions"></limble-tree-root>
+<div [limbleTreeDraggable]="treeBranch">Drag Me!</div>
 ```
 
-This should render the tree, producing an instance of `MyComponentClass` for each node in the tree data.
+As the user drags the branch over other branches of the tree, dropzones will appear to indicate where the dragged branch may be placed. Dropping into a dropzone will graft the dragged branch at that location.
 
-### The LimbleTreeData Array
+### Configurable Restrictions For Drag-And-Drop
 
-The LimbleTreeData array can have objects of any configuration. There are two properties that the library looks for on these objects:
+A tree can be configured to disallow certain branches from...
 
--  `nodes`: This property is an array of objects just like LimbleTreeData. Objects in this array are considered children of that object, and will cause a component to be rendered for each element in the array. The children will be rendered on a new branch "under" the parent.
--  `component`: This property is an object in the form of `{class: <ComponentClass>, bindings: {bindingName: bindingValue, ...}}`. It is optional as long as there is a `defaultComponent` declared in the tree options object. If this property is found on a node, it will be used instead of the `defaultComponent` for rendering that node. See the `defaultComponent` option below for more information.
+1. being dragged at all
+2. being dropped at specific locations in the tree
 
-### The LimbleTreeOptions Object
+When calling `createEmptyTree()`, there are three options that can be passed to the second parameter to control these restrictions. There are no restrictions by default.
 
-The LimbleTreeOptions object is used to configure the tree's general settings. Options include:
+```typescript
+public ngAfterViewInit(): void {
+   this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(
+      this.treeContainer,
+      {
+         // Prevents dragging branches which have less than three children
+         allowDragging: (treeBranch) => treeBranch.branches().length < 3,
+         // Prevents drops on first-level branches
+         allowDrop: (source, parent, index) => parent.parent() !== undefined,
+         // Does not allow any branches to be dropped under a branch whose metaData property `noChildren` is set to `false`
+         allowNesting: (treeBranch) => treeBranch.meta().noChildren === false
+      }
+   );
+```
 
--  `defaultComponent`: This property is an object in the form of `{class: <ComponentClass>, bindings: {bindingName: bindingValue, ...}}`. For each node in the data array, the component described by this object will be rendered. The tree node object will be passed in to the component as an input called `nodeData`. The component's inputs and outputs will be initialized using the bindings object. If a tree node contains a `component` property, that component information will be used instead of the `defaultComponent`. An error will be thrown if (1) the `defaultComponent` is not defined; and (2) the library encounters a tree node that does not have a `component` property.
--  `indent`: The number of pixels to indent for each level of the tree. Defaults to 45.
--  `allowNesting`: Whether to allow "nesting" (placing a node one level deeper than currently exists on the branch) under a node. May be a boolean or a callback function that returns a boolean. If it is a callback, the callback will be called for each node when another node is attempting to nest under it. The parent node (the one which is potentially being nested under) will be passed in to the callback. Defaults to true.
--  `allowDragging`: Whether to allow drag-and-drop functionality. May be a boolean or a callback function that returns a boolean. If it is a callback, the callback will be called for each node when a drag is attempted on it, and that node will be passed in to the callback. Defaults to true.
--  `allowDrop`: A callback that determines whether a sourceNode can be dropped at a particular location. If it returns true, the drop is allowed; if it returns false, the drop is not allowed. This function takes three parameters: the node being dragged, the proposed parent node, and the proposed index under that parent. Defaults to `() => true`.
--  `listMode`: When set to true, list mode will enforce a flat tree structure, meaning there can only be one level of the tree. `allowNesting` is automatically set to `false` and any children will be deleted. This mode can be used when the same dynamic drag and drop functionality of the tree is desired, but the tree structure itself is not necessary. This also opens up the pagination API on the limble-tree-root component. See the pagination section below for details about pagination.
+These options only apply to drag-and-drop functionality. They do not restrict programmatic movement of branches, such as when using the `prune()` or `graftTo()` methods.
 
-### The LimbleTreeRoot Component
+More details about these configuration options can be found in `tree-options.interface.ts`.
 
-Here are the inputs and outputs of the `<limble-tree-root>` component:
+## Watching For Tree Events
 
--  input `data` -- a LimbleTreeData array. Required.
--  input `options` -- a LimbleTreeOptions object.
--  input `itemsPerPage` -- A number indicating how many many items to display at a time. See the "Pagination" section below.
--  input `page` -- A number indicating the current page og items. See the "Pagination" section below.
--  output `treeChange` -- an event that fires whenever the tree is rendered or re-rendered.
--  output `treeDrop` -- an event that fires after a node is dropped in the tree. The event contains data described by the TreeDrop interface, given here:
+Both the TreeBranch and TreeRoot objects will emit information when certain events occur. These events can be captured by subscribing to the observable returned by the `events()` method.
 
 ```typescript
-export interface TreeDrop {
-   /** The node that was dropped */
-   target: LimbleTreeNode;
-   /** the target's parent before the drag and drop, or null if it was a top-level node */
-   oldParent: LimbleTreeNode | null;
-   /** the index of the node before the drag and drop relative to its old siblings */
-   oldIndex: number;
-   /** the target's parent after the drag and drop, or null if it is now a top-level node */
-   newParent: LimbleTreeNode | null;
-   /** the index of the node after the drag and drop relative to its new siblings */
-   newIndex: number;
+public ngAfterViewInit(): void {
+   this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(
+      this.treeContainer
+   );
+   this.tree.events().subscribe((event) => {
+      console.log(event.type());
+   });
+   const branch1 = this.tree.grow(MyTreeContentComponent); // will output "graft"
+   const branch2 = this.tree.grow(MyTreeContentComponent); // will output "graft"
+   const branch3 = branch2.grow(MyTreeContentComponent); //will output "graft"
+   this.tree.destroy(); //will output "destruction" four times; one for each branch, and one for the root.
 }
 ```
 
-### Drag Handles
+Events bubble up the tree. So subscribing to the root's `events()` observable will capture all tree events for that tree. Subscribing to the `events()` observable of a branch will capture all tree events for that branch and its descendants.
+
+Below is a list of event types that are currently emitted by the tree.
+
+-  drag start
+-  drop
+-  drag end
+-  prune
+-  graft
+-  destruction
+
+Each event contains applicable information about the event, such as the nodes involved, position in the tree, etc.
+
+## Traversing The Tree
+
+### Parents and Children
+
+Trees are doubly-linked, meaning that each node in the tree holds a pointer to its parent and a pointer to each of its children. These pointers are accessed using the `parent()` and `branches()` methods, respectively. The order of child branches is maintained. The `getBranch()` method takes an index as an argument and returns the branch at that index. A branch's position relative to its siblings is obtained using the `index()` method.
+
+Unlike TreeBranch instances, a TreeRoot does not have a `parent()` or `index()` method, but it does have a `branches()` and `getBranch()` methods.
+
+TreeBranch instances have a method `root()`, which returns the root of their current tree. TreeRoot instances also have this method, and in that case it always returns itself.
+
+```typescript
+public ngAfterViewInit(): void {
+   this.tree = this.treeService.createEmptyTree<MyTreeContentComponent>(
+      this.treeContainer
+   );
+   this.tree.events().subscribe((event) => {
+      console.log(event.type());
+   });
+   const branch1 = this.tree.grow(MyTreeContentComponent);
+   const branch2 = this.tree.grow(MyTreeContentComponent);
+   const branch2a = branch2.grow(MyTreeContentComponent);
+   const branch2b = branch2.grow(MyTreeContentComponent);
+   const branch2a1 = branch2a.grow(MyTreeContentComponent);
+   const branch2a1 = branch2a.grow(MyTreeContentComponent);
+
+   //All of these expressions are true
+   assert(branch2b.parent() === branch2);
+   assert(branch2b.index() === 1);
+   assert(branch2.branches()[1] === branch2b);
+   assert(branch2a1.branches().length === 0);
+   assert(branch1.parent() === this.tree);
+   assert(this.tree.getBranch(2) === branch2);
+   assert(branch2a1.root() === this.tree);
+}
+```
+
+### Traversal Utility Methods
+
+There are a couple other methods used to traverse the tree.
+
+-  `traverse()` traverses the tree in [depth-first pre-order](https://en.wikipedia.org/wiki/Tree_traversal#Pre-order,_NLR) and executes a provided callback on each node.
+-  `plot()` traverses the tree and returns a many-dimensional [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)representing the shape of the tree.
+
+### Get Branch's Current Location in the Tree
+
+You can call `position()` on a TreeBranch to get an array of indexes, indicating the path from the root to that branch.
+
+Example: If `position()` returns [2, 2, 4], that means the branch is a great-grandchild of the root (three elements == three levels deep), and the branch could be accessed like so:
+
+```typescript
+root.getBranch(2).getBranch(2).getBranch(4);
+```
+
+## Destroying Trees And Branches
+
+The `destroy()` method must be called on a TreeRoot in order for its resources to be properly released. Failing to do so will cause memory leaks and other performance problems.
 
-Adding the `limble-tree-handle` css class to an element in a node component will designate that element as the drag handle, making it so the node can only be dragged by clicking on that element.
+Branches also have a `destroy()` method. Calling `destroy()` on the TreeRoot will automatically call the `destroy()` method of each branch in the tree, including branches that have been collapsed.
 
-### Pagination
+Branches that have been otherwise pruned are not part of any tree; their `destroy()` method must be called manually in order to release their resources. Calling a branch's `destroy()` method will automatically call the `destroy()` method of each descendant branch, including descendants that are collapsed.
 
-When the `listMode` option is set to true, the pagination API is made available. Pagination is accomplished using two of the inputs of the `limble-tree-root` component: the `itemsPerPage` input and the `page` input. These inputs will not do anything unless `listMode` is turned on. When in `listMode`, the list will split into pages, where each page contains `itemsPerPage` number of items. (Note that the last page may have fewer items than the `itemsPerPage` number.) Only one page will be displayed at a time. The `page` input indicates which page to show: When `page` is 1, the first page will display, and so on.
+Destroyed roots and branches have very limited functionality. Many methods will simply throw an error if the instance has been previously destroyed. You can check if a node is destroyed with the `isDestroyed()` method.
 
-### Demo App
+## Accessing Underlying Structures
 
-A demo app can be run by following the instructions on our [github repo](https://github.com/LimbleCMMS/limble-tree).
+There are methods on TreeBranch and TreeRoot instances which grant access to underlying structures. We recommend only using these in advanced scenarios. They are not fully documented here at this time.
 
-## Issues, Feature Requests, Etc
+-  detectChanges()
+-  dispatch()
+-  getBranchesContainer()
+-  getComponentInstance()
+-  getHostView()
+-  getNativeElement()
+-  getUserlandComponentRef()
 
-If you find an issue or you would like to see an improvement, you may create an "issue" or start a "discussion" on our [github repo](https://github.com/LimbleCMMS/limble-tree).
+## Development and Contributions
 
-We truly appreciate feedback; but keep in mind that we, the Limble team, built this library for our own needs, and requests from outside our organization may not always be a high priority.
+See the readme in our [Github repository](https://github.com/LimbleCMMS/limble-tree).