@memberjunction/ng-trees 4.0.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +173 -0
  2. package/package.json +4 -4
package/README.md ADDED
@@ -0,0 +1,173 @@
1
+ # @memberjunction/ng-trees
2
+
3
+ Angular tree and tree-dropdown components for displaying and selecting from hierarchical entity data. Supports branch/leaf entity configurations, junction table relationships, keyboard navigation, and a BeforeX/AfterX event system.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @memberjunction/ng-trees
9
+ ```
10
+
11
+ ## Overview
12
+
13
+ The tree package provides two components: a standalone tree view (`mj-tree`) and a dropdown variant (`mj-tree-dropdown`). Both load data from MemberJunction entities using `RunView`, support branch (category/folder) and leaf (item) entity configurations, and handle many-to-many relationships through junction table configuration.
14
+
15
+ ```mermaid
16
+ flowchart TD
17
+ subgraph Config["Entity Configuration"]
18
+ A["TreeBranchConfig (categories)"]
19
+ B["TreeLeafConfig (items)"]
20
+ C["TreeJunctionConfig (M2M)"]
21
+ end
22
+ subgraph Components["Components"]
23
+ D["TreeComponent (mj-tree)"]
24
+ E["TreeDropdownComponent (mj-tree-dropdown)"]
25
+ end
26
+ subgraph Data["Data Loading"]
27
+ F["RunView API"]
28
+ G["Branch Hierarchy"]
29
+ H["Leaf Items"]
30
+ I["Junction Records"]
31
+ end
32
+
33
+ Config --> D
34
+ Config --> E
35
+ D --> F
36
+ F --> G
37
+ F --> H
38
+ F --> I
39
+
40
+ style Config fill:#2d6a9f,stroke:#1a4971,color:#fff
41
+ style Components fill:#7c5295,stroke:#563a6b,color:#fff
42
+ style Data fill:#2d8659,stroke:#1a5c3a,color:#fff
43
+ ```
44
+
45
+ ## Usage
46
+
47
+ ### Module Import
48
+
49
+ ```typescript
50
+ import { TreesModule } from '@memberjunction/ng-trees';
51
+
52
+ @NgModule({
53
+ imports: [TreesModule]
54
+ })
55
+ export class YourModule {}
56
+ ```
57
+
58
+ ### Basic Tree
59
+
60
+ ```html
61
+ <mj-tree
62
+ [BranchConfig]="{
63
+ EntityName: 'Query Categories',
64
+ DisplayField: 'Name',
65
+ ParentIDField: 'ParentID',
66
+ DefaultIcon: 'fa-solid fa-folder'
67
+ }"
68
+ [SelectionMode]="'single'"
69
+ (afterNodeSelect)="onNodeSelected($event)">
70
+ </mj-tree>
71
+ ```
72
+
73
+ ### Tree with Leaf Entities
74
+
75
+ ```html
76
+ <mj-tree
77
+ [BranchConfig]="{
78
+ EntityName: 'Query Categories',
79
+ DisplayField: 'Name',
80
+ ParentIDField: 'ParentID'
81
+ }"
82
+ [LeafConfig]="{
83
+ EntityName: 'Queries',
84
+ DisplayField: 'Name',
85
+ ParentForeignKey: 'CategoryID',
86
+ DefaultIcon: 'fa-solid fa-database'
87
+ }"
88
+ [SelectionMode]="'single'"
89
+ [SelectableTypes]="'leaves'"
90
+ (afterNodeSelect)="onQuerySelected($event)">
91
+ </mj-tree>
92
+ ```
93
+
94
+ ### Tree Dropdown
95
+
96
+ ```html
97
+ <mj-tree-dropdown
98
+ [BranchConfig]="categoryConfig"
99
+ [LeafConfig]="itemConfig"
100
+ [Placeholder]="'Select a category...'"
101
+ [AllowClear]="true"
102
+ (afterNodeSelect)="onSelected($event)">
103
+ </mj-tree-dropdown>
104
+ ```
105
+
106
+ ## Components
107
+
108
+ | Component | Selector | Purpose |
109
+ |-----------|----------|---------|
110
+ | `TreeComponent` | `mj-tree` | Standalone hierarchical tree view |
111
+ | `TreeDropdownComponent` | `mj-tree-dropdown` | Dropdown with tree popup |
112
+
113
+ ## Configuration Types
114
+
115
+ ### TreeBranchConfig
116
+
117
+ | Property | Type | Default | Description |
118
+ |----------|------|---------|-------------|
119
+ | `EntityName` | `string` | -- | Entity for branch nodes (required) |
120
+ | `DisplayField` | `string` | `'Name'` | Field to display as label |
121
+ | `IDField` | `string` | `'ID'` | Primary key field |
122
+ | `ParentIDField` | `string` | `'ParentID'` | Field for parent hierarchy |
123
+ | `IconField` | `string` | -- | Field for dynamic icons |
124
+ | `DefaultIcon` | `string` | `'fa-solid fa-folder'` | Fallback icon |
125
+ | `ExtraFilter` | `string` | -- | Optional RunView filter |
126
+ | `OrderBy` | `string` | `'Name ASC'` | Sort order |
127
+
128
+ ### TreeLeafConfig
129
+
130
+ | Property | Type | Default | Description |
131
+ |----------|------|---------|-------------|
132
+ | `EntityName` | `string` | -- | Entity for leaf nodes (required) |
133
+ | `DisplayField` | `string` | `'Name'` | Field to display as label |
134
+ | `ParentForeignKey` | `string` | -- | FK linking to branch entity |
135
+ | `DefaultIcon` | `string` | `'fa-solid fa-file'` | Fallback icon |
136
+
137
+ ### TreeJunctionConfig
138
+
139
+ For many-to-many relationships via junction tables:
140
+
141
+ | Property | Type | Description |
142
+ |----------|------|-------------|
143
+ | `EntityName` | `string` | Junction entity name |
144
+ | `LeafForeignKey` | `string` | FK referencing leaf entity |
145
+ | `BranchForeignKey` | `string` | FK referencing branch entity |
146
+
147
+ ## Key Inputs
148
+
149
+ | Input | Type | Default | Description |
150
+ |-------|------|---------|-------------|
151
+ | `BranchConfig` | `TreeBranchConfig` | -- | Branch entity config (required) |
152
+ | `LeafConfig` | `TreeLeafConfig` | -- | Optional leaf entity config |
153
+ | `JunctionConfig` | `TreeJunctionConfig` | -- | Optional junction config |
154
+ | `SelectionMode` | `'none' \| 'single' \| 'multiple'` | `'none'` | Selection behavior |
155
+ | `SelectableTypes` | `'all' \| 'branches' \| 'leaves'` | `'all'` | Which node types are selectable |
156
+ | `AutoLoad` | `boolean` | `true` | Load data on init |
157
+
158
+ ## Event System
159
+
160
+ Uses the BeforeX/AfterX cancelable pattern:
161
+
162
+ - `beforeNodeSelect` / `afterNodeSelect`
163
+ - `beforeNodeDeselect` / `afterNodeDeselect`
164
+ - `beforeNodeExpand` / `afterNodeExpand`
165
+ - `beforeNodeCollapse` / `afterNodeCollapse`
166
+ - `beforeNodeClick` / `afterNodeClick`
167
+ - `beforeNodeDoubleClick` / `afterNodeDoubleClick`
168
+ - `beforeDataLoad` / `afterDataLoad`
169
+
170
+ ## Dependencies
171
+
172
+ - [@memberjunction/core](../../MJCore/README.md) -- RunView for data loading
173
+ - [@memberjunction/core-entities](../../MJCoreEntities/README.md) -- Entity types
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memberjunction/ng-trees",
3
- "version": "4.0.0",
3
+ "version": "4.1.0",
4
4
  "description": "MemberJunction: Angular tree and tree dropdown components for hierarchical entity selection",
5
5
  "main": "./dist/public-api.js",
6
6
  "typings": "./dist/public-api.d.ts",
@@ -30,9 +30,9 @@
30
30
  "@angular/forms": "21.1.3"
31
31
  },
32
32
  "dependencies": {
33
- "@memberjunction/core": "4.0.0",
34
- "@memberjunction/core-entities": "4.0.0",
35
- "@memberjunction/global": "4.0.0",
33
+ "@memberjunction/core": "4.1.0",
34
+ "@memberjunction/core-entities": "4.1.0",
35
+ "@memberjunction/global": "4.1.0",
36
36
  "tslib": "^2.8.1",
37
37
  "rxjs": "^7.8.2"
38
38
  },