@memberjunction/ng-record-selector 2.42.1 → 2.44.0

package/README.md

@@ -1,17 +1,22 @@
-# Record Selector Component
+# @memberjunction/ng-record-selector
 
-An Angular component for selecting records from a list of available items in MemberJunction applications. This package provides both a standalone selection component and a dialog wrapper component for easy integration.
+An Angular component library for selecting records from dual lists in MemberJunction applications. This package provides both a standalone selection component and a dialog wrapper component for easy integration.
+
+## Overview
+
+The `@memberjunction/ng-record-selector` package provides Angular components that allow users to select and deselect items from a possible set using a dual listbox interface. It's designed to work seamlessly with MemberJunction's BaseEntity objects and provides a clean, intuitive UI for managing selections.
 
 ## Features
 
-- **Dual Listbox Interface**: Easy selection between available and selected items
-- **Drag and Drop**: Intuitive item movement between lists
-- **Double-Click Support**: Quickly move items by double-clicking
-- **Icon Support**: Display icons alongside item text
-- **Configurable Toolbar**: Customize available toolbar actions
-- **Dialog Integration**: Optional dialog wrapper for modal usage
-- **Entity Integration**: Works with MemberJunction BaseEntity objects
-- **Memory Management**: Maintains selection state within dialog sessions
+- **Dual Listbox Interface**: Side-by-side lists for available and selected items
+- **Drag and Drop**: Intuitive item movement between lists using Kendo UI's drag and drop functionality
+- **Double-Click Support**: Quickly move items between lists by double-clicking
+- **Icon Support**: Display icons alongside item text using CSS classes from entity fields
+- **Configurable Toolbar**: Customize available toolbar actions (move up/down, transfer items, transfer all)
+- **Dialog Integration**: Optional dialog wrapper for modal usage with OK/Cancel functionality
+- **Entity Integration**: Works natively with MemberJunction BaseEntity objects
+- **State Management**: Dialog component maintains selection state and can revert changes on cancel
+- **Responsive Design**: Uses MemberJunction's container directives for proper layout
 
 ## Installation
 
@@ -19,6 +24,8 @@ An Angular component for selecting records from a list of available items in Mem
 npm install @memberjunction/ng-record-selector
 ```
 
+Note: This package has peer dependencies on Angular 18.0.2 and Kendo UI Angular components. Ensure these are installed in your project.
+
 ## Usage
 
 ### Import the Module
@@ -42,8 +49,8 @@ export class YourModule { }
 <!-- Standalone selector component -->
 <mj-record-selector
   [EntityName]="'Users'"
-  [DisplayField]="'UserName'"
-  [DisplayIconField]="'UserIcon'"
+  [DisplayField]="'Name'"
+  [DisplayIconField]="'IconCSSClass'"
   [AvailableRecords]="allUsers"
   [SelectedRecords]="selectedUsers"
   [UnselectedRecords]="unselectedUsers"
@@ -52,6 +59,8 @@ export class YourModule { }
 </mj-record-selector>
 ```
 
+**Note**: The component accesses entity field values directly using bracket notation (e.g., `dataItem[DisplayField]`), so ensure your DisplayField and DisplayIconField names match the actual property names in your BaseEntity objects.
+
 ### Dialog Component Usage
 
 ```html
@@ -63,7 +72,8 @@ export class YourModule { }
 <mj-record-selector-dialog
   *ngIf="showSelectorDialog"
   [EntityName]="'Users'"
-  [DisplayField]="'UserName'"
+  [DisplayField]="'Name'"
+  [DisplayIconField]="'IconCSSClass'"
   [AvailableRecords]="allUsers"
   [SelectedRecords]="selectedUsers"
   [UnselectedRecords]="unselectedUsers"
@@ -80,6 +90,7 @@ export class YourModule { }
 ```typescript
 import { Component, OnInit } from '@angular/core';
 import { BaseEntity, Metadata, RunView } from '@memberjunction/core';
+import { UserEntity } from '@memberjunction/core-entities';
 import { ListBoxToolbarConfig } from '@progress/kendo-angular-listbox';
 
 @Component({
@@ -92,7 +103,7 @@ import { ListBoxToolbarConfig } from '@progress/kendo-angular-listbox';
       <h4>Selected Users ({{ selectedUsers.length }}):</h4>
       <ul>
         <li *ngFor="let user of selectedUsers">
-          {{ user.Get('UserName') }} - {{ user.Get('Email') }}
+          {{ user.Name }} - {{ user.Email }}
         </li>
       </ul>
       <button kendoButton (click)="saveUserAssignments()">Save Assignments</button>
@@ -101,8 +112,8 @@ import { ListBoxToolbarConfig } from '@progress/kendo-angular-listbox';
     <mj-record-selector-dialog
       *ngIf="selectorDialogVisible"
       [EntityName]="'Users'"
-      [DisplayField]="'UserName'"
-      [DisplayIconField]="'UserIcon'"
+      [DisplayField]="'Name'"
+      [DisplayIconField]="'IconCSSClass'"
       [AvailableRecords]="allUsers"
       [SelectedRecords]="selectedUsers"
       [UnselectedRecords]="unselectedUsers"
@@ -116,9 +127,9 @@ import { ListBoxToolbarConfig } from '@progress/kendo-angular-listbox';
   `
 })
 export class UserRoleAssignmentComponent implements OnInit {
-  allUsers: BaseEntity[] = [];
-  selectedUsers: BaseEntity[] = [];
-  unselectedUsers: BaseEntity[] = [];
+  allUsers: UserEntity[] = [];
+  selectedUsers: UserEntity[] = [];
+  unselectedUsers: UserEntity[] = [];
   selectorDialogVisible = false;
   
   toolbarSettings: ListBoxToolbarConfig = {
@@ -133,9 +144,9 @@ export class UserRoleAssignmentComponent implements OnInit {
   }
   
   async loadUsers() {
-    // Load all users
+    // Load all users using MemberJunction's recommended pattern
     const rv = new RunView();
-    const result = await rv.RunView({
+    const result = await rv.RunView<UserEntity>({
       EntityName: 'Users',
       ResultType: 'entity_object'
     });
@@ -159,14 +170,19 @@ export class UserRoleAssignmentComponent implements OnInit {
     
     if (confirmed) {
       console.log('User selection confirmed:', this.selectedUsers);
+      // The selectedUsers array has been updated by the dialog component
     } else {
       console.log('User selection cancelled');
+      // The dialog component has already reverted any changes
     }
   }
   
-  saveUserAssignments() {
-    // Logic to save user role assignments
-    console.log('Saving role assignments for users:', this.selectedUsers);
+  async saveUserAssignments() {
+    // Example: Save user role assignments
+    for (const user of this.selectedUsers) {
+      // Create role assignment records or update user roles
+      console.log(`Assigning role to user: ${user.Name} (${user.ID})`);
+    }
   }
 }
 ```
@@ -175,39 +191,72 @@ export class UserRoleAssignmentComponent implements OnInit {
 
 ### RecordSelectorComponent
 
-Standalone component for selecting records.
+The base component that provides the dual listbox functionality for selecting records.
+
+**Selector**: `mj-record-selector`
 
 #### Inputs
 
-- `EntityName`: string - The name of the entity to show records for
-- `DisplayField`: string - The field name to display in the list items
-- `DisplayIconField`: string - The field name containing CSS class for icons (optional)
-- `AvailableRecords`: BaseEntity[] - List of all available records
-- `SelectedRecords`: BaseEntity[] - List of selected records
-- `UnselectedRecords`: BaseEntity[] - List of unselected records
-- `ToolbarSettings`: ListBoxToolbarConfig - Configuration for the listbox toolbar
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `EntityName` | `string` | `''` | The name of the entity to show records for |
+| `DisplayField` | `string` | `''` | The field name to display in the list items |
+| `DisplayIconField` | `string` | `''` | The field name containing CSS class for icons (optional) |
+| `AvailableRecords` | `BaseEntity[]` | `[]` | List of all available records |
+| `SelectedRecords` | `BaseEntity[]` | `[]` | List of currently selected records |
+| `UnselectedRecords` | `BaseEntity[]` | `[]` | List of currently unselected records |
+| `ToolbarSettings` | `ListBoxToolbarConfig` | See below | Configuration for the listbox toolbar |
+
+Default toolbar settings:
+```typescript
+{
+  position: "right",
+  tools: ["moveUp", "transferFrom", "transferAllFrom", "transferAllTo", "transferTo", "moveDown"]
+}
+```
 
 #### Outputs
 
-- `RecordSelected`: EventEmitter<BaseEntity[]> - Emitted when records are selected
-- `RecordUnselected`: EventEmitter<BaseEntity[]> - Emitted when records are unselected
+| Output | Type | Description |
+|--------|------|-------------|
+| `RecordSelected` | `EventEmitter<BaseEntity[]>` | Emitted when records are moved to the selected list |
+| `RecordUnselected` | `EventEmitter<BaseEntity[]>` | Emitted when records are moved to the unselected list |
+
+#### Methods
+
+The component handles double-click events internally to move items between lists. No public methods are exposed.
 
 ### RecordSelectorDialogComponent
 
-Dialog wrapper for the RecordSelectorComponent.
+A dialog wrapper that contains the RecordSelectorComponent with OK/Cancel functionality.
+
+**Selector**: `mj-record-selector-dialog`
 
 #### Inputs
 
-- All inputs from RecordSelectorComponent, plus:
-- `DialogTitle`: string - Title of the dialog (default: 'Select Records')
-- `DialogWidth`: string - Width of the dialog (default: '700px')
-- `DialogHeight`: string - Height of the dialog (default: '450px')
-- `DialogVisible`: boolean - Controls the visibility of the dialog
+Inherits all inputs from `RecordSelectorComponent`, plus:
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `DialogTitle` | `string` | `'Select Records'` | Title displayed in the dialog header |
+| `DialogWidth` | `string` | `'700px'` | Width of the dialog |
+| `DialogHeight` | `string` | `'450px'` | Height of the dialog |
+| `DialogVisible` | `boolean` | `false` | Controls the visibility of the dialog |
 
 #### Outputs
 
-- All outputs from RecordSelectorComponent, plus:
-- `DialogClosed`: EventEmitter<boolean> - Emitted when the dialog is closed (true if confirmed, false if canceled)
+Inherits all outputs from `RecordSelectorComponent`, plus:
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `DialogClosed` | `EventEmitter<boolean>` | Emitted when the dialog is closed. `true` if OK was clicked, `false` if Cancel was clicked or dialog was closed by other means |
+
+#### Behavior
+
+- When the dialog is opened, it saves the initial state of selected/unselected records
+- Clicking OK commits the changes and closes the dialog
+- Clicking Cancel or closing the dialog by other means reverts all changes to the initial state
+- The component maintains references to the same arrays passed in as inputs, modifying them in place
 
 ## Toolbar Configuration
 
@@ -229,22 +278,100 @@ const toolbarSettings: ListBoxToolbarConfig = {
 
 ## Selection Behavior
 
-The component uses Kendo UI ListBox components with the following behavior:
+The component uses Kendo UI ListBox components with the following interaction patterns:
 
-1. Items can be moved between lists using the toolbar buttons
-2. Items can be dragged and dropped between lists
-3. Double-clicking an item moves it to the other list
-4. When used in a dialog, changes are only committed when the OK button is clicked; Cancel reverts to the previous state
+1. **Toolbar Actions**: Use the toolbar buttons to move items between lists
+2. **Drag and Drop**: Items can be dragged from one list to another
+3. **Double-Click**: Double-clicking an item instantly moves it to the opposite list
+4. **Multi-Select**: Hold Ctrl/Cmd to select multiple items, or Shift to select a range
+5. **Dialog State Management**: When using the dialog wrapper:
+   - Changes are held in memory until confirmed
+   - OK button commits all changes
+   - Cancel button reverts to the initial state
 
 ## Styling
 
-The component uses Kendo UI ListBox component styles and includes basic CSS that can be overridden in your application.
+The component uses Kendo UI ListBox styles with additional custom styling:
+
+- `.list-box`: Applied to each listbox container
+- `.item-icon`: Applied to icon spans when DisplayIconField is used
+
+You can override these styles in your application's CSS:
+
+```css
+/* Example: Custom styling for the record selector */
+mj-record-selector .list-box {
+  min-height: 300px;
+}
+
+mj-record-selector .item-icon {
+  margin-right: 8px;
+  color: #666;
+}
+```
 
 ## Dependencies
 
-- `@memberjunction/core`: For metadata and entity types
-- `@memberjunction/core-entities`: For entity types
-- `@memberjunction/global`: For global utilities
-- `@progress/kendo-angular-listbox`: For the list box component
-- `@progress/kendo-angular-buttons`: For UI buttons
-- `@progress/kendo-angular-dialog`: For dialog wrapper
+### Runtime Dependencies
+- `@memberjunction/core`: ^2.43.0 - Core MemberJunction functionality
+- `@memberjunction/core-entities`: ^2.43.0 - Entity type definitions
+- `@memberjunction/global`: ^2.43.0 - Global utilities and types
+- `@memberjunction/ng-container-directives`: ^2.43.0 - Layout directives
+- `@memberjunction/ng-shared`: ^2.43.0 - Shared Angular utilities
+
+### Peer Dependencies
+- `@angular/common`: 18.0.2
+- `@angular/core`: 18.0.2
+- `@angular/forms`: 18.0.2
+- `@angular/router`: 18.0.2
+- `@progress/kendo-angular-buttons`: 16.2.0
+- `@progress/kendo-angular-dialog`: 16.2.0
+- `@progress/kendo-angular-listbox`: 16.2.0
+
+## Integration with Other MemberJunction Packages
+
+This package integrates seamlessly with other MemberJunction components:
+
+- **Entity Framework**: Works with any BaseEntity subclass from `@memberjunction/core`
+- **Metadata System**: Compatible with entities loaded through the MJ metadata system
+- **Container Directives**: Uses `mjFillContainer` directive for proper layout integration
+- **RunView**: Designed to work with records loaded via RunView queries
+
+## Common Use Cases
+
+1. **User Role Assignment**: Select users to assign to specific roles
+2. **Permission Management**: Choose permissions to grant to users or roles
+3. **Category Assignment**: Assign items to multiple categories
+4. **Team Membership**: Manage team member selections
+5. **Feature Selection**: Enable/disable features for specific tenants
+
+## Best Practices
+
+1. **Data Loading**: Always use the MemberJunction RunView pattern with `ResultType: 'entity_object'` for optimal performance
+2. **Memory Management**: The dialog component maintains state internally, so you don't need to manage temporary arrays
+3. **Field Names**: Ensure DisplayField matches actual property names in your entities (not the Get() method parameters)
+4. **Icon Fields**: If using DisplayIconField, ensure the field contains valid CSS class names (e.g., 'fa-user', 'fas fa-star')
+5. **Array References**: The component modifies the input arrays in place, so use the same array references throughout your component's lifecycle
+
+## Troubleshooting
+
+### Records not displaying
+- Verify that DisplayField matches an actual property name in your BaseEntity objects
+- Check that AvailableRecords is populated with valid BaseEntity instances
+- Ensure SelectedRecords and UnselectedRecords are subsets of AvailableRecords
+
+### Icons not showing
+- Confirm DisplayIconField contains valid CSS class names
+- Ensure required icon fonts (Font Awesome, etc.) are loaded in your application
+
+### Dialog state issues
+- Make sure DialogVisible is properly bound and updated
+- Handle the DialogClosed event to update your component's state
+
+## Version History
+
+See [CHANGELOG.md](./CHANGELOG.md) for detailed version history.
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-record-selector",
-  "version": "2.42.1",
+  "version": "2.44.0",
   "description": "MemberJunction: Angular Components to allow a user to select/deselect items from a possible set",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -28,11 +28,11 @@
     "@progress/kendo-angular-listbox": "16.2.0"
   },
   "dependencies": {
-    "@memberjunction/core-entities": "2.42.1",
-    "@memberjunction/global": "2.42.1",
-    "@memberjunction/core": "2.42.1",
-    "@memberjunction/ng-container-directives": "2.42.1",
-    "@memberjunction/ng-shared": "2.42.1",
+    "@memberjunction/core-entities": "2.44.0",
+    "@memberjunction/global": "2.44.0",
+    "@memberjunction/core": "2.44.0",
+    "@memberjunction/ng-container-directives": "2.44.0",
+    "@memberjunction/ng-shared": "2.44.0",
     "tslib": "^2.3.0"
   },
   "sideEffects": false