@memberjunction/ng-export-service 4.0.0 → 4.1.0

package/README.md

@@ -0,0 +1,229 @@
+# @memberjunction/ng-export-service
+
+Angular service and dialog component for exporting data to Excel, CSV, and JSON formats, with configurable sampling, column selection, and browser-side file download.
+
+## Overview
+
+The `@memberjunction/ng-export-service` package wraps the [`@memberjunction/export-engine`](../../../ExportEngine/README.md) for Angular usage. It provides an injectable `ExportService` with format-specific convenience methods and an `ExportDialogComponent` that presents a progressive UI for format selection, row sampling, and one-click download.
+
+```mermaid
+flowchart LR
+    subgraph Dialog["ExportDialogComponent"]
+        FMT[Format Selection] --> SAMP[Sampling Options]
+        SAMP --> PREV[Row Estimate Preview]
+        PREV --> DL[Export & Download]
+    end
+
+    subgraph Service["ExportService"]
+        EXP[export / toExcel / toCSV / toJSON]
+        DOWN[downloadResult]
+        BOTH[exportAndDownload]
+    end
+
+    subgraph Engine["@memberjunction/export-engine"]
+        EE[ExportEngine]
+    end
+
+    Dialog --> Service
+    Service --> Engine
+
+    style Dialog fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Service fill:#7c5295,stroke:#563a6b,color:#fff
+    style Engine fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
+
+## Installation
+
+```bash
+npm install @memberjunction/ng-export-service
+```
+
+## Usage
+
+### Import the Module
+
+```typescript
+import { ExportServiceModule } from '@memberjunction/ng-export-service';
+
+@NgModule({
+  imports: [ExportServiceModule]
+})
+export class YourModule { }
+```
+
+### Using the Export Dialog
+
+```html
+@if (showExportDialog) {
+  <mj-export-dialog
+    [visible]="showExportDialog"
+    [config]="exportConfig"
+    (closed)="onExportDialogClosed($event)">
+  </mj-export-dialog>
+}
+```
+
+```typescript
+import { ExportDialogConfig, ExportDialogResult } from '@memberjunction/ng-export-service';
+
+@Component({ ... })
+export class MyComponent {
+  showExportDialog = false;
+  exportConfig: ExportDialogConfig | null = null;
+
+  openExport(data: Record<string, unknown>[]) {
+    this.exportConfig = {
+      data,
+      defaultFileName: 'contacts-export',
+      defaultFormat: 'excel',
+      showSamplingOptions: true,
+      dialogTitle: 'Export Contacts'
+    };
+    this.showExportDialog = true;
+  }
+
+  onExportDialogClosed(result: ExportDialogResult) {
+    this.showExportDialog = false;
+    if (result.exported) {
+      console.log('Exported successfully:', result.result?.fileName);
+    }
+  }
+}
+```
+
+### Using the Service Directly
+
+```typescript
+import { ExportService } from '@memberjunction/ng-export-service';
+import { ExportData } from '@memberjunction/export-engine';
+
+@Component({ ... })
+export class MyComponent {
+  private exportService = inject(ExportService);
+
+  async exportToExcel(data: ExportData) {
+    // Export and immediately trigger browser download
+    const result = await this.exportService.exportAndDownload(data, {
+      format: 'excel',
+      fileName: 'my-data',
+      includeHeaders: true
+    });
+
+    if (!result.success) {
+      console.error('Export failed:', result.error);
+    }
+  }
+
+  async exportToCSV(data: ExportData) {
+    // Export with sampling -- only first 500 rows
+    const result = await this.exportService.toCSV(data, {
+      fileName: 'sample-data',
+      sampling: { mode: 'top', count: 500 }
+    });
+
+    if (result.success) {
+      this.exportService.downloadResult(result);
+    }
+  }
+}
+```
+
+## API Reference
+
+### ExportService
+
+Root-provided Angular service wrapping `ExportEngine`.
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `export(data, options?)` | `Promise<ExportResult>` | Export data with full options |
+| `toExcel(data, options?)` | `Promise<ExportResult>` | Export to Excel format |
+| `toCSV(data, options?)` | `Promise<ExportResult>` | Export to CSV format |
+| `toJSON(data, options?)` | `Promise<ExportResult>` | Export to JSON format |
+| `getSupportedFormats()` | `ExportFormat[]` | List supported formats |
+| `downloadResult(result)` | `void` | Trigger browser file download |
+| `exportAndDownload(data, options?)` | `Promise<ExportResult>` | Export then download in one call |
+| `getSamplingModes()` | `SamplingModeInfo[]` | Get sampling modes with labels |
+| `getFormatInfo(format)` | `FormatInfo` | Get format label, icon, description |
+| `buildSamplingOptions(mode, count?, interval?)` | `SamplingOptions` | Build sampling config from user selections |
+
+### ExportDialogComponent (`mj-export-dialog`)
+
+Standalone export dialog with progressive UX.
+
+#### Inputs
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `visible` | `boolean` | `false` | Controls dialog visibility |
+| `config` | `ExportDialogConfig \| null` | `null` | Dialog configuration |
+
+#### Outputs
+
+| Output | Type | Description |
+|--------|------|-------------|
+| `closed` | `EventEmitter<ExportDialogResult>` | Emitted when dialog closes |
+
+### ExportDialogConfig
+
+```typescript
+interface ExportDialogConfig {
+  data: ExportData;
+  columns?: ExportColumn[];
+  defaultFileName?: string;
+  availableFormats?: ExportFormat[];
+  defaultFormat?: ExportFormat;
+  showSamplingOptions?: boolean;
+  defaultSamplingMode?: SamplingMode;
+  defaultSampleCount?: number;
+  dialogTitle?: string;
+}
+```
+
+### ExportDialogResult
+
+```typescript
+interface ExportDialogResult {
+  exported: boolean;
+  result?: ExportResult;
+  options?: ExportOptions;
+}
+```
+
+### Sampling Modes
+
+| Mode | Description |
+|------|-------------|
+| `all` | Export all data rows |
+| `top` | Export the first N rows |
+| `bottom` | Export the last N rows |
+| `every-nth` | Export every Nth row |
+| `random` | Export N random rows |
+
+## Dependencies
+
+### Runtime Dependencies
+
+| Package | Description |
+|---------|-------------|
+| `@memberjunction/export-engine` | Core export engine with format support |
+
+### Peer Dependencies
+
+- `@angular/common` ^21.x
+- `@angular/core` ^21.x
+- `@angular/forms` ^21.x
+- `@angular/cdk` ^21.x
+
+**Note:** For export types (`ExportFormat`, `ExportOptions`, `ExportResult`, etc.), import directly from `@memberjunction/export-engine`.
+
+## Build
+
+```bash
+cd packages/Angular/Generic/export-service
+npm run build
+```
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-export-service",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "MemberJunction: Angular export service and dialog for exporting data to Excel, CSV, and JSON",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -32,7 +32,7 @@
     "@angular/cdk": "21.1.3"
   },
   "dependencies": {
-    "@memberjunction/export-engine": "4.0.0",
+    "@memberjunction/export-engine": "4.1.0",
     "tslib": "^2.8.1"
   },
   "sideEffects": false,