@memberjunction/ng-link-directives 4.0.0 → 4.2.0

package/README.md

@@ -1,18 +1,37 @@
 # @memberjunction/ng-link-directives
 
-The `@memberjunction/ng-link-directives` package provides a set of Angular directives that transform text elements into different types of links based on MemberJunction entity field metadata. This makes it easy to display email addresses, URLs, and entity relationships as clickable links in your application.
+Angular directives for transforming elements into clickable email, web, or entity record links. Used throughout MemberJunction forms to make field values interactive.
+
+## Overview
+
+This package provides three directives that wrap elements in anchor tags based on the type of data they represent. A `BaseLink` abstract class handles the shared DOM manipulation logic. These directives are used automatically by MemberJunction's form system to make email addresses, URLs, and foreign key values clickable.
+
+```mermaid
+graph TD
+    BL["BaseLink\n(Abstract)"] --> EL["EmailLinkDirective\n[mjEmailLink]"]
+    BL --> WL["WebLinkDirective\n[mjWebLink]"]
+    BL --> FL["FieldLinkDirective\n[mjFieldLink]"]
+
+    EL --> MA["mailto: link"]
+    WL --> HA["http(s): link"]
+    FL --> RN["Router navigation\n(entity record)"]
+
+    style BL fill:#7c5295,stroke:#563a6b,color:#fff
+    style EL fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style WL fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style FL fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style MA fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style HA fill:#2d8659,stroke:#1a5c3a,color:#fff
+    style RN fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
 
 ## Features
 
-- **Email link directive** (`mjEmailLink`) - Converts fields with "email" extended type to mailto: links
-- **Web link directive** (`mjWebLink`) - Converts fields with "url" extended type to external links
-- **Field link directive** (`mjFieldLink`) - Creates navigable links to related entity records
-- **Automatic value resolution** - Field links can display the related entity's name instead of ID
-- **Smart navigation** - Field links use Angular Router for seamless in-app navigation
-- **Target control** - Web and email links open in new tabs by default
-- **CSS styling** - All links use the `link-text` class for consistent styling
-- **Type safety** - Full TypeScript support with strict typing
-- **Metadata integration** - Leverages MemberJunction's metadata system for field information
+- **Email links**: Wraps text in a `mailto:` anchor tag
+- **Web links**: Wraps text in an `http(s):` anchor tag (opens in new tab)
+- **Field/Record links**: Wraps entity foreign key values as router links to navigate to the referenced record
+- **Automatic styling**: Adds `link-text` CSS class with consistent font sizing
+- **Lightweight**: Minimal DOM manipulation using Angular `Renderer2`
 
 ## Installation
 
@@ -20,311 +39,61 @@ The `@memberjunction/ng-link-directives` package provides a set of Angular direc
 npm install @memberjunction/ng-link-directives
 ```
 
-## Requirements
+## Key Dependencies
 
-- Angular 21 or higher
-- @memberjunction/core 2.43.0 or higher
-- TypeScript 4.0 or higher
+| Dependency | Purpose |
+|---|---|
+| `@memberjunction/core` | EntityField metadata |
+| `@memberjunction/ng-shared` | SharedService, navigation |
+| `@angular/router` | Router for record navigation |
 
 ## Usage
 
-### Basic Setup
-
-Import the LinkDirectivesModule in your Angular module:
+### Import the Module
 
 ```typescript
-import { NgModule } from '@angular/core';
 import { LinkDirectivesModule } from '@memberjunction/ng-link-directives';
 
 @NgModule({
-  imports: [
-    // other imports...
-    LinkDirectivesModule
-  ],
+  imports: [LinkDirectivesModule]
 })
-export class YourModule { }
+export class AppModule {}
 ```
 
-### Email Link Directive
-
-The email link directive converts text into a mailto: link when the field has an extended type of "email".
+### Email Link
 
 ```html
-<span [mjEmailLink]="field">{{ field.Value }}</span>
-```
-
-```typescript
-// In your component
-import { EntityField } from '@memberjunction/core';
-
-export class YourComponent {
-  field: EntityField; // EntityField with ExtendedType = "email"
-}
+<span [mjEmailLink]="emailField">user@example.com</span>
 ```
 
-**Note**: The directive will log an error if the field's ExtendedType is not "email". There is a known issue where the error message incorrectly references "mjWebLink" instead of "mjEmailLink".
-
-### Web Link Directive
-
-The web link directive converts text into an external URL link when the field has an extended type of "url".
+### Web Link
 
 ```html
-<span [mjWebLink]="field">{{ field.Value }}</span>
-```
-
-```typescript
-// In your component
-import { EntityField } from '@memberjunction/core';
-
-export class YourComponent {
-  field: EntityField; // EntityField with ExtendedType = "url"
-}
+<span [mjWebLink]="urlField">https://example.com</span>
 ```
 
-**Note**: The directive will log an error if the field's ExtendedType is not "url". Links open in a new tab by default.
-
-### Field Link Directive
-
-The field link directive creates a link to another entity record when the field is a foreign key to another entity.
+### Field/Record Link
 
 ```html
-<!-- Basic usage -->
-<span [mjFieldLink]="true" [record]="customerRecord" [fieldName]="'AssignedUserID'">
-  {{ customerRecord.Get('AssignedUserID') }}
-</span>
-
-<!-- With text replacement disabled -->
-<span [mjFieldLink]="true" [record]="customerRecord" [fieldName]="'AssignedUserID'" [replaceText]="false">
-  {{ customerRecord.Get('AssignedUserID') }}
-</span>
-```
-
-```typescript
-// In your component
-import { BaseEntity } from '@memberjunction/core';
-
-export class YourComponent {
-  customerRecord: BaseEntity; // Entity record containing the foreign key field
-}
-```
-
-The directive:
-- Navigates to `/resource/record/{primaryKey}?Entity={EntityName}` when clicked
-- Automatically replaces the ID with the related entity's name (when `replaceText=true`)
-- Uses `RelatedEntityNameFieldMap` metadata for efficient name resolution
-- Falls back to server lookup if name mapping is not available
-
-## API Reference
-
-### EmailLink Directive
-
-**Selector**: `[mjEmailLink]`
-
-| Input | Type | Required | Description |
-|-------|------|----------|-------------|
-| `field` | `EntityField` | Yes | The entity field object containing email data. Must have ExtendedType = "email" |
-
-### WebLink Directive
-
-**Selector**: `[mjWebLink]`
-
-| Input | Type | Required | Description |
-|-------|------|----------|-------------|
-| `field` | `EntityField` | Yes | The entity field object containing URL data. Must have ExtendedType = "url" |
-
-### FieldLink Directive
-
-**Selector**: `[mjFieldLink]`
-
-| Input | Type | Default | Required | Description |
-|-------|------|---------|----------|-------------|
-| `mjFieldLink` | `boolean` | - | Yes | Enable the directive (must be set to true) |
-| `record` | `BaseEntity` | - | Yes | The entity record object containing the field |
-| `fieldName` | `string` | - | Yes | The name of the field that contains the foreign key |
-| `replaceText` | `boolean` | `true` | No | Whether to replace the field value with the related entity's name |
-
-**Events**: The directive handles click events internally to navigate using Angular Router.
-
-## Implementation Details
-
-### Base Link Class
-
-All directives extend the `BaseLink` abstract class, which provides a common `CreateLink` method:
-
-```typescript
-protected CreateLink(
-  el: ElementRef, 
-  field: EntityField, 
-  renderer: Renderer2, 
-  href: string, 
-  newTab: boolean = false
-): void
-```
-
-This method:
-- Creates an `<a>` element using Angular's Renderer2
-- Wraps the original element with the link
-- Adds the `link-text` CSS class
-- Sets `target="_blank"` for new tab behavior
-
-### Email Links
-
-The `EmailLink` directive:
-1. Validates that the field has ExtendedType = "email"
-2. Prepends "mailto:" to the field value
-3. Creates a link that opens the user's default email client
-4. Always opens in a new tab
-
-### Web Links
-
-The `WebLink` directive:
-1. Validates that the field has ExtendedType = "url"
-2. Uses the field value directly as the href
-3. Creates an external link that opens in a new tab
-4. Logs an error if the ExtendedType validation fails
-
-### Field Links
-
-The `FieldLink` directive provides the most complex functionality:
-
-1. **Metadata Resolution**: Uses MemberJunction's metadata to find the related entity
-2. **Navigation Setup**: Constructs the route as `/resource/record/{primaryKey}?Entity={EntityName}`
-3. **Name Resolution**: 
-   - First checks `RelatedEntityNameFieldMap` for local field mapping
-   - Falls back to `GetEntityRecordName()` API call if needed
-4. **Click Handling**: Intercepts clicks and uses Angular Router for navigation
-5. **Error Handling**: Includes navigation event monitoring for debugging
-
-**Note**: Currently supports only single-value primary keys for foreign key relationships.
-
-## Styling
-
-All generated links include the CSS class `link-text` for consistent styling across your application:
-
-```css
-.link-text {
-  color: #0066cc;
-  text-decoration: underline;
-  cursor: pointer;
-}
-
-.link-text:hover {
-  color: #0052a3;
-  text-decoration: none;
-}
-
-.link-text:visited {
-  color: #551a8b;
-}
+<span [mjFieldLink]="foreignKeyField" [record]="entityRecord">Related Record</span>
 ```
 
-## Complete Example
+## Exported API
 
-Here's a complete example showing all three directives in action:
+| Export | Type | Description |
+|---|---|---|
+| `LinkDirectivesModule` | NgModule | Module with all directive declarations |
+| `BaseLink` | Abstract Class | Shared link creation logic |
+| `EmailLinkDirective` | Directive | `[mjEmailLink]` - creates mailto links |
+| `WebLinkDirective` | Directive | `[mjWebLink]` - creates web links |
+| `FieldLinkDirective` | Directive | `[mjFieldLink]` - creates record navigation links |
 
-```typescript
-// component.ts
-import { Component, OnInit } from '@angular/core';
-import { BaseEntity, Metadata } from '@memberjunction/core';
-
-@Component({
-  selector: 'app-contact-details',
-  template: `
-    <div class="contact-info">
-      <!-- Email link -->
-      <div>
-        Email: <span [mjEmailLink]="emailField">{{ contact.Get('Email') }}</span>
-      </div>
-      
-      <!-- Web link -->
-      <div>
-        Website: <span [mjWebLink]="websiteField">{{ contact.Get('Website') }}</span>
-      </div>
-      
-      <!-- Field link with name replacement -->
-      <div>
-        Account Manager: 
-        <span [mjFieldLink]="true" [record]="contact" [fieldName]="'AccountManagerID'">
-          {{ contact.Get('AccountManagerID') }}
-        </span>
-      </div>
-    </div>
-  `
-})
-export class ContactDetailsComponent implements OnInit {
-  contact: BaseEntity;
-  
-  get emailField() {
-    return this.contact.Fields.find(f => f.Name === 'Email');
-  }
-  
-  get websiteField() {
-    return this.contact.Fields.find(f => f.Name === 'Website');
-  }
-  
-  async ngOnInit() {
-    const md = new Metadata();
-    this.contact = await md.GetEntityObject('Contacts');
-    await this.contact.Load(123); // Load specific contact
-  }
-}
-```
-
-## Build and Development
-
-This package uses the Angular CLI compiler (`ngc`) for building:
+## Build
 
 ```bash
-# Build the package
-npm run build
-
-# The compiled output will be in the ./dist directory
+cd packages/Angular/Explorer/link-directives && npm run build
 ```
 
-The package is configured with:
-- TypeScript strict mode
-- ES2015 target with ES2020 modules
-- Source maps and declaration files
-- Angular compiler optimizations
-
-## Integration with MemberJunction
-
-This package is designed to work seamlessly with the MemberJunction framework:
-
-- **Metadata Integration**: Leverages EntityField metadata for field type detection
-- **Navigation**: Integrates with MJ's standard routing patterns (`/resource/record/...`)
-- **Entity System**: Works with BaseEntity and EntityField objects
-- **Name Resolution**: Uses MJ's entity relationship mapping for efficient data display
-
-## Troubleshooting
-
-### Common Issues
-
-1. **"Entity Field must have ExtendedType of URL"** - Ensure your entity field metadata has the correct ExtendedType set
-2. **Links not appearing** - Verify the directive is properly applied and the field has a value
-3. **Navigation errors** - Check that the related entity exists in metadata and the route is configured
-
-### Debugging Tips
-
-- The FieldLink directive logs navigation events to the console
-- Use browser DevTools to inspect the generated link structure
-- Check that RelatedEntity metadata is properly configured for field links
-
 ## License
 
 ISC
-
-## Dependencies
-
-- **Runtime Dependencies:**
-  - @memberjunction/core: ^2.43.0
-  - tslib: ^2.3.0
-
-- **Peer Dependencies:**
-  - @angular/common: ^18.0.2
-  - @angular/core: ^18.0.2
-  - @angular/router: ^18.0.2
-
-- **Development Dependencies:**
-  - @angular/compiler: ^18.0.2
-  - @angular/compiler-cli: ^18.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-link-directives",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "MemberJunction: Angular Link Directives for turning an element in an angular app into an email, web, or record link",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -30,8 +30,8 @@
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@memberjunction/core": "4.0.0",
-    "@memberjunction/ng-shared": "4.0.0"
+    "@memberjunction/core": "4.2.0",
+    "@memberjunction/ng-shared": "4.2.0"
   },
   "sideEffects": false,
   "repository": {