@memberjunction/ng-entity-viewer 0.0.1 → 2.121.0

package/README.md

@@ -1,45 +1,226 @@
 # @memberjunction/ng-entity-viewer
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/ng-entity-viewer`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Angular components for viewing MemberJunction entity data in multiple formats - grid and card views with filtering, selection, and shared data management.
+
+## Features
+
+- **Multiple View Modes**: Switch between grid (AG Grid) and card views
+- **Auto-Generated Layout**: Automatically structures columns/cards based on entity metadata
+- **Client-Side Filtering**: SQL-style wildcard support (`%`) for consistent behavior
+- **Selection Handling**: Configurable selection behavior with events
+- **Shared Data Layer**: Load data once, display in multiple ways
+- **Semantic Pills**: Auto-colored pills for status/type/category fields
+
+## Installation
+
+```bash
+npm install @memberjunction/ng-entity-viewer ag-grid-angular ag-grid-community
+```
+
+## Usage
+
+### Import the Module
+
+```typescript
+import { EntityViewerModule } from '@memberjunction/ng-entity-viewer';
+
+@NgModule({
+  imports: [EntityViewerModule]
+})
+export class MyModule { }
+```
+
+### EntityViewerComponent (Composite)
+
+The main component that combines grid/cards with built-in filtering and view switching.
+
+```html
+<!-- Basic usage - auto-loads data -->
+<mj-entity-viewer
+  [entity]="selectedEntity"
+  (recordSelected)="onRecordSelected($event)"
+  (recordOpened)="onRecordOpened($event)">
+</mj-entity-viewer>
+
+<!-- With pre-loaded data and configuration -->
+<mj-entity-viewer
+  [entity]="selectedEntity"
+  [records]="myRecords"
+  [config]="{
+    showFilter: true,
+    showViewModeToggle: true,
+    defaultViewMode: 'cards',
+    pageSize: 500
+  }">
+</mj-entity-viewer>
+```
+
+#### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `showFilter` | boolean | true | Show the filter input |
+| `showViewModeToggle` | boolean | true | Show grid/cards toggle |
+| `showRecordCount` | boolean | true | Show record count |
+| `defaultViewMode` | 'grid' \| 'cards' | 'grid' | Initial view mode |
+| `pageSize` | number | 1000 | Max records to load |
+| `filterPlaceholder` | string | 'Filter records...' | Filter input placeholder |
+| `filterDebounceMs` | number | 250 | Filter debounce time |
+| `selectionBehavior` | string | 'emit-only' | Selection behavior |
+
+### EntityGridComponent
+
+Standalone AG Grid-based table view.
+
+```html
+<mj-entity-grid
+  [entity]="selectedEntity"
+  [records]="filteredRecords"
+  [selectedRecordId]="selectedId"
+  [columns]="customColumns"
+  (recordSelected)="onRecordSelected($event)"
+  (recordOpened)="onRecordOpened($event)">
+</mj-entity-grid>
+```
+
+#### Inputs
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `entity` | EntityInfo | Entity metadata |
+| `records` | BaseEntity[] | Records to display |
+| `selectedRecordId` | string | Selected record's PK |
+| `columns` | GridColumnDef[] | Custom column definitions |
+| `height` | string | Grid height (CSS) |
+| `enableSelection` | boolean | Enable row selection |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `recordSelected` | RecordSelectedEvent | Single click on row |
+| `recordOpened` | RecordOpenedEvent | Double click on row |
+
+### EntityCardsComponent
+
+Standalone card-based view with auto-generated layout.
+
+```html
+<mj-entity-cards
+  [entity]="selectedEntity"
+  [records]="records"
+  [filterText]="searchFilter"
+  [selectedRecordId]="selectedId"
+  (recordSelected)="onRecordSelected($event)"
+  (recordOpened)="onRecordOpened($event)"
+  (filteredCountChanged)="onFilteredCountChanged($event)">
+</mj-entity-cards>
+```
+
+#### Inputs
+
+| Input | Type | Description |
+|-------|------|-------------|
+| `entity` | EntityInfo | Entity metadata |
+| `records` | BaseEntity[] | Records to display |
+| `selectedRecordId` | string | Selected record's PK |
+| `filterText` | string | Filter text (supports `%` wildcards) |
+| `cardTemplate` | CardTemplate | Custom card template |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `recordSelected` | RecordSelectedEvent | Click on card |
+| `recordOpened` | RecordOpenedEvent | Open button click |
+| `filteredCountChanged` | number | Filtered count changed |
+
+### PillComponent
+
+Semantic color pill for categorical values.
+
+```html
+<!-- Auto-color based on value -->
+<mj-pill [value]="record.Status"></mj-pill>
+
+<!-- Force specific color -->
+<mj-pill [value]="record.Type" color="info"></mj-pill>
+```
+
+Colors are auto-detected based on semantic meaning:
+- **success** (green): active, approved, complete, etc.
+- **warning** (yellow): pending, in progress, draft, etc.
+- **danger** (red): failed, error, rejected, etc.
+- **info** (blue): new, info, created, etc.
+- **neutral** (gray): default
+
+## Events
+
+### RecordSelectedEvent
+
+```typescript
+interface RecordSelectedEvent {
+  record: BaseEntity;      // The selected record
+  entity: EntityInfo;      // Entity metadata
+  compositeKey: CompositeKey; // Record's composite key
+}
+```
+
+### RecordOpenedEvent
+
+```typescript
+interface RecordOpenedEvent {
+  record: BaseEntity;
+  entity: EntityInfo;
+  compositeKey: CompositeKey;
+}
+```
+
+## Filtering
+
+The filter supports SQL-style `%` wildcards for consistency with server-side behavior:
+
+- `test` - matches "this is a test string"
+- `hub%updat%comp` - matches "hubspot update company"
+- `%comp` - matches "my company"
+
+## Custom Templates
+
+### Grid Columns
+
+```typescript
+const columns: GridColumnDef[] = [
+  { field: 'Name', headerName: 'Name', width: 200 },
+  { field: 'Status', headerName: 'Status', width: 120 },
+  { field: 'Amount', headerName: 'Amount', width: 100 }
+];
+```
+
+### Card Template
+
+```typescript
+const template: CardTemplate = {
+  titleField: 'Name',
+  subtitleField: 'Status',
+  descriptionField: 'Notes',
+  displayFields: [
+    { name: 'Amount', type: 'number', label: 'Amount' },
+    { name: 'IsActive', type: 'boolean', label: 'Active' }
+  ],
+  thumbnailField: 'ImageUrl',
+  badgeField: 'Priority'
+};
+```
+
+## Dependencies
+
+- `@angular/core` ^18.0.0
+- `@angular/common` ^18.0.0
+- `@angular/forms` ^18.0.0
+- `ag-grid-angular` ^34.0.0
+- `ag-grid-community` ^34.0.0
+- `@memberjunction/core` ^2.0.0
+
+## License
+
+ISC

package/dist/lib/entity-cards/entity-cards.component.d.ts

@@ -0,0 +1,163 @@
+import { EventEmitter, OnChanges, OnInit, SimpleChanges, ElementRef, AfterViewChecked, ChangeDetectorRef } from '@angular/core';
+import { EntityInfo, EntityFieldInfo } from '@memberjunction/core';
+import { BaseEntity } from '@memberjunction/core';
+import { CardTemplate, RecordSelectedEvent, RecordOpenedEvent } from '../types';
+import * as i0 from "@angular/core";
+/**
+ * EntityCardsComponent - Card-based view for entity records
+ *
+ * This component provides an auto-generated card layout for displaying
+ * entity records. Cards are automatically structured based on entity metadata.
+ *
+ * Supports two modes:
+ * 1. Parent-managed data: Records are passed in via [records] input
+ * 2. Standalone: Component loads its own data with pagination
+ *
+ * @example
+ * ```html
+ * <mj-entity-cards
+ *   [entity]="selectedEntity"
+ *   [records]="filteredRecords"
+ *   [selectedRecordId]="selectedId"
+ *   (recordSelected)="onRecordSelected($event)"
+ *   (recordOpened)="onRecordOpened($event)">
+ * </mj-entity-cards>
+ * ```
+ */
+export declare class EntityCardsComponent implements OnChanges, OnInit, AfterViewChecked {
+    private elementRef;
+    private cdr;
+    constructor(elementRef: ElementRef, cdr: ChangeDetectorRef);
+    /**
+     * The entity metadata for the records being displayed
+     */
+    entity: EntityInfo | null;
+    /**
+     * The records to display as cards (optional - component can load its own)
+     */
+    records: BaseEntity[] | null;
+    /**
+     * The currently selected record's primary key string
+     */
+    selectedRecordId: string | null;
+    /**
+     * Custom card template (optional - auto-generated if not provided)
+     */
+    cardTemplate: CardTemplate | null;
+    /**
+     * Map of record IDs to hidden field names that matched the filter
+     * Used to display an indicator when a match occurred in a non-visible field
+     */
+    hiddenFieldMatches: Map<string, string>;
+    /**
+     * Current filter text for highlighting matches
+     * Supports SQL-style % wildcards
+     */
+    filterText: string;
+    /**
+     * Page size for standalone data loading
+     * @default 100
+     */
+    pageSize: number;
+    /**
+     * Emitted when a record is selected (single click)
+     */
+    recordSelected: EventEmitter<RecordSelectedEvent>;
+    /**
+     * Emitted when a record should be opened (double click or open button)
+     */
+    recordOpened: EventEmitter<RecordOpenedEvent>;
+    /** Auto-generated card template */
+    autoCardTemplate: CardTemplate | null;
+    /** Internal records when loading standalone */
+    private internalRecords;
+    /** Track if we're in standalone mode */
+    private standaloneMode;
+    /** Loading state for standalone mode */
+    isLoading: boolean;
+    /** Flag to trigger scroll to selected card after view renders */
+    private pendingScrollToSelected;
+    ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngAfterViewChecked(): void;
+    /**
+     * Scroll the selected card into view
+     */
+    private scrollToSelectedCard;
+    /**
+     * Get effective records (external or internal)
+     */
+    get effectiveRecords(): BaseEntity[];
+    /**
+     * Load data in standalone mode
+     */
+    private loadData;
+    /**
+     * Get the effective card template (custom or auto-generated)
+     */
+    get effectiveTemplate(): CardTemplate | null;
+    /**
+     * Generate card template from entity metadata
+     */
+    private generateCardTemplate;
+    private findTitleField;
+    private findSubtitleField;
+    private findDescriptionField;
+    private findDisplayFields;
+    /**
+     * Find all potential thumbnail fields in priority order
+     * Returns an array so we can fall back per-record if one is empty
+     */
+    private findThumbnailFields;
+    private findBadgeField;
+    private getFieldType;
+    getFieldValue(record: BaseEntity, fieldName: string | null): string;
+    getNumericValue(record: BaseEntity, fieldName: string): string;
+    getBooleanValue(record: BaseEntity, fieldName: string): boolean;
+    getTextValue(record: BaseEntity, fieldName: string, maxLength?: number): string;
+    getDateValue(record: BaseEntity, fieldName: string): string;
+    /**
+     * Get display label for a field using EntityFieldInfo's built-in DisplayNameOrName property
+     */
+    getFieldLabel(field: EntityFieldInfo): string;
+    getRecordTrackId(record: BaseEntity, index: number): string;
+    isSelected(record: BaseEntity): boolean;
+    onCardClick(record: BaseEntity): void;
+    onOpenClick(event: Event, record: BaseEntity): void;
+    getInitials(record: BaseEntity): string;
+    /**
+     * Get the thumbnail type for a record, with per-record fallback through thumbnailFields
+     */
+    getThumbnailType(record: BaseEntity): 'image' | 'icon' | 'none';
+    /**
+     * Get the thumbnail URL/value for a record, with per-record fallback
+     */
+    getThumbnailUrl(record: BaseEntity): string;
+    /**
+     * Find the first thumbnail field that has a value for this record
+     * Returns both the field name and value for type determination
+     */
+    private getEffectiveThumbnailField;
+    private isImageValue;
+    private isIconClass;
+    getRecordColor(record: BaseEntity): string;
+    isEnumField(fieldName: string): boolean;
+    get subtitleIsPill(): boolean;
+    getPillColorType(value: string): string;
+    /**
+     * Check if a record matched on a hidden field
+     */
+    hasHiddenFieldMatch(record: BaseEntity): boolean;
+    /**
+     * Get the display name of the hidden field that matched
+     */
+    getHiddenMatchFieldName(record: BaseEntity): string;
+    /**
+     * Highlight matching text in a string based on the filter text
+     * Uses HighlightUtil which only highlights if the text actually matches the pattern
+     */
+    highlightMatch(text: string): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<EntityCardsComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EntityCardsComponent, "mj-entity-cards", never, { "entity": { "alias": "entity"; "required": false; }; "records": { "alias": "records"; "required": false; }; "selectedRecordId": { "alias": "selectedRecordId"; "required": false; }; "cardTemplate": { "alias": "cardTemplate"; "required": false; }; "hiddenFieldMatches": { "alias": "hiddenFieldMatches"; "required": false; }; "filterText": { "alias": "filterText"; "required": false; }; "pageSize": { "alias": "pageSize"; "required": false; }; }, { "recordSelected": "recordSelected"; "recordOpened": "recordOpened"; }, never, never, false, never>;
+}
+//# sourceMappingURL=entity-cards.component.d.ts.map

package/dist/lib/entity-cards/entity-cards.component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-cards.component.d.ts","sourceRoot":"","sources":["../../../src/lib/entity-cards/entity-cards.component.ts"],"names":[],"mappings":"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"}