@memberjunction/ng-file-storage 2.43.0 → 2.44.0

package/README.md

@@ -1,6 +1,6 @@
-# File Storage Components
+# @memberjunction/ng-file-storage
 
-A set of Angular components for managing file storage in MemberJunction applications. This package provides a complete file management system with categories, file upload, and grid display.
+Angular components for managing file storage in MemberJunction applications. This package provides a complete file management system with categories, file upload, and grid display capabilities integrated with MemberJunction's file storage providers.
 
 ## Features
 
@@ -8,10 +8,12 @@ A set of Angular components for managing file storage in MemberJunction applicat
 - **File Grid**: Display files with sorting, filtering and pagination
 - **File Upload**: Easy file uploading with progress tracking
 - **File Operations**: Download, delete, and edit file metadata
-- **Drag and Drop**: Move files between categories with drag and drop
+- **Drag and Drop**: Move files between categories with drag and drop support
 - **Integration**: Seamless integration with MemberJunction's file storage system
-- **Provider Support**: Works with multiple file storage providers
+- **Provider Support**: Works with multiple file storage providers (Azure Blob, AWS S3, etc.)
 - **Overwrite Protection**: Confirmation dialog when overwriting existing files
+- **Status Management**: Track file upload status (Pending, Uploaded, Failed)
+- **Type Safety**: Full TypeScript support with MemberJunction entities
 
 ## Installation
 
@@ -19,6 +21,20 @@ A set of Angular components for managing file storage in MemberJunction applicat
 npm install @memberjunction/ng-file-storage
 ```
 
+**Note**: This package requires Angular 18.0.2 or later and the following MemberJunction packages:
+- `@memberjunction/core` (^2.43.0)
+- `@memberjunction/core-entities` (^2.43.0)
+- `@memberjunction/global` (^2.43.0)
+- `@memberjunction/graphql-dataprovider` (^2.43.0)
+
+## Prerequisites
+
+Before using this package, ensure your MemberJunction database has:
+- File Storage Providers configured and active
+- File Categories entity permissions for users
+- Files entity permissions for users
+- Proper GraphQL endpoints configured
+
 ## Usage
 
 ### Import the Module
@@ -137,58 +153,112 @@ export class DocumentManagerComponent {
 }
 ```
 
-## API Reference
+## Component Reference
 
-### CategoryTreeComponent
+### CategoryTreeComponent (`mj-files-category-tree`)
 
 A tree view component for managing file categories.
 
+#### Selector
+```typescript
+selector: 'mj-files-category-tree'
+```
+
 #### Outputs
 
-- `categorySelected`: EventEmitter<string | undefined> - Emitted when a category is selected in the tree
+| Output | Type | Description |
+|--------|------|-------------|
+| `categorySelected` | `EventEmitter<string \| undefined>` | Emitted when a category is selected in the tree |
+
+#### Public Methods
 
-#### Methods
+| Method | Description | Parameters | Returns |
+|--------|-------------|------------|----------|
+| `createNewCategory()` | Opens dialog to create a new category | None | `Promise<void>` |
+| `deleteCategory(fileCategory: FileCategoryEntity)` | Deletes a category with error handling | `fileCategory: FileCategoryEntity` | `Promise<void>` |
+| `handleDrop(e: TreeItemAddRemoveArgs)` | Handles drag and drop to move categories | `e: TreeItemAddRemoveArgs` | `Promise<void>` |
+| `Refresh()` | Refreshes the category tree data | None | `Promise<void>` |
+| `clearSelection()` | Clears the current selection | None | `void` |
+| `saveNewCategory()` | Saves a new category | None | `Promise<void>` |
+| `saveRename()` | Saves category rename | None | `Promise<void>` |
+| `cancelRename()` | Cancels category rename | None | `void` |
 
-- `createNewCategory()`: Opens dialog to create a new category
-- `deleteCategory(fileCategory: FileCategoryEntity)`: Deletes a category
-- `handleDrop(e: TreeItemAddRemoveArgs)`: Handles drag and drop of categories
-- `Refresh()`: Refreshes the category tree data
+### FilesGridComponent (`mj-files-grid`)
 
-### FilesGridComponent
+A grid component for displaying and managing files with support for inline editing and file operations.
 
-A grid component for displaying and managing files.
+#### Selector
+```typescript
+selector: 'mj-files-grid'
+```
 
 #### Inputs
 
-- `CategoryID`: string | undefined - The ID of the category to filter files by
+| Input | Type | Description | Default |
+|-------|------|-------------|----------|
+| `CategoryID` | `string \| undefined` | The ID of the category to filter files by | `undefined` |
 
-#### Methods
+#### Public Methods
 
-- `downloadFile(file: FileEntity)`: Downloads the specified file
-- `deleteFile(file: FileEntity)`: Deletes the specified file
-- `saveEditFile()`: Saves changes to a file's metadata
-- `resetEditFile()`: Cancels editing a file's metadata
-- `Refresh()`: Refreshes the files grid data
+| Method | Description | Parameters | Returns |
+|--------|-------------|------------|----------|
+| `downloadFile(file: FileEntity)` | Downloads file using provider's download URL | `file: FileEntity` | `Promise<void>` |
+| `deleteFile(file: FileEntity)` | Deletes file with confirmation | `file: FileEntity` | `Promise<void>` |
+| `saveEditFile()` | Saves changes to file metadata | None | `Promise<void>` |
+| `resetEditFile()` | Cancels editing file metadata | None | `void` |
+| `handleFileUpload(e: FileUploadEvent)` | Handles file upload events | `e: FileUploadEvent` | `void` |
+| `canBeDeleted(file: FileEntity)` | Checks if file can be deleted | `file: FileEntity` | `boolean` |
+| `Refresh()` | Refreshes the files grid data | None | `Promise<void>` |
 
-### FileUploadComponent
+### FileUploadComponent (`mj-files-file-upload`)
 
-A component for uploading files.
+A component for uploading files with provider integration and overwrite protection.
+
+#### Selector
+```typescript
+selector: 'mj-files-file-upload'
+```
 
 #### Inputs
 
-- `disabled`: boolean - Whether the upload component is disabled
-- `CategoryID`: string | undefined - The category ID to assign to uploaded files
+| Input | Type | Description | Default |
+|-------|------|-------------|----------|
+| `disabled` | `boolean` | Whether the upload component is disabled | `false` |
+| `CategoryID` | `string \| undefined` | The category ID to assign to uploaded files | `undefined` |
 
 #### Outputs
 
-- `uploadStarted`: EventEmitter<void> - Emitted when file upload starts
-- `fileUpload`: EventEmitter<FileUploadEvent> - Emitted when a file is uploaded (success or failure)
+| Output | Type | Description |
+|--------|------|-------------|
+| `uploadStarted` | `EventEmitter<void>` | Emitted when file upload starts |
+| `fileUpload` | `EventEmitter<FileUploadEvent>` | Emitted when a file is uploaded (success or failure) |
+
+#### Public Methods
+
+| Method | Description | Parameters | Returns |
+|--------|-------------|------------|----------|
+| `Confirm()` | Confirms file overwrite and proceeds with upload | None | `void` |
+| `CancelConfirm()` | Cancels file overwrite and deletes pending record | None | `Promise<void>` |
+| `Refresh()` | Loads default file storage provider | None | `Promise<void>` |
+| `SelectEventHandler(e: SelectEvent)` | Handles file selection | `e: SelectEvent` | `Promise<void>` |
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `IsUploading` | `boolean` | Indicates if files are currently being uploaded |
+
+## Types
 
-#### Methods
+### FileUploadEvent
 
-- `Confirm()`: Confirms file overwrite
-- `CancelConfirm()`: Cancels file overwrite
-- `Refresh()`: Refreshes the file upload component state
+```typescript
+export type FileUploadEvent = 
+  | { success: true; file: FileEntity }
+  | { success: false; file: FileInfo };
+```
+
+This type represents the result of a file upload operation, containing either a successful FileEntity or a failed FileInfo object.
 
 ## File Upload Flow
 
@@ -203,12 +273,143 @@ A component for uploading files.
 
 The components use Kendo UI components for consistent styling and include basic CSS that can be overridden in your application.
 
+## Advanced Usage
+
+### Custom File Grid with Actions
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { FilesGridComponent, FileUploadEvent } from '@memberjunction/ng-file-storage';
+import { FileEntity } from '@memberjunction/core-entities';
+
+@Component({
+  template: `
+    <div class="file-manager">
+      <div class="toolbar">
+        <button (click)="refreshFiles()">Refresh</button>
+        <mj-files-file-upload 
+          [CategoryID]="categoryId"
+          (fileUpload)="onFileUploaded($event)">
+        </mj-files-file-upload>
+      </div>
+      
+      <mj-files-grid #filesGrid
+        [CategoryID]="categoryId">
+      </mj-files-grid>
+    </div>
+  `
+})
+export class CustomFileManagerComponent {
+  @ViewChild('filesGrid') filesGrid!: FilesGridComponent;
+  categoryId = 'some-category-id';
+  
+  refreshFiles() {
+    this.filesGrid.Refresh();
+  }
+  
+  onFileUploaded(event: FileUploadEvent) {
+    if (event.success) {
+      console.log('File uploaded:', event.file.Name);
+      // The grid automatically adds the file, no refresh needed
+    }
+  }
+}
+```
+
+### Programmatic Category Management
+
+```typescript
+import { Component, ViewChild } from '@angular/core';
+import { CategoryTreeComponent } from '@memberjunction/ng-file-storage';
+import { Metadata } from '@memberjunction/core';
+import { FileCategoryEntity } from '@memberjunction/core-entities';
+
+@Component({
+  template: `
+    <mj-files-category-tree #categoryTree
+      (categorySelected)="onCategorySelected($event)">
+    </mj-files-category-tree>
+  `
+})
+export class CategoryManagerComponent {
+  @ViewChild('categoryTree') categoryTree!: CategoryTreeComponent;
+  
+  async createCategoryProgrammatically(name: string, parentId?: string) {
+    const md = new Metadata();
+    const category = await md.GetEntityObject<FileCategoryEntity>('File Categories');
+    category.NewRecord();
+    category.Name = name;
+    category.ParentID = parentId;
+    
+    if (await category.Save()) {
+      // Refresh the tree to show new category
+      await this.categoryTree.Refresh();
+    }
+  }
+  
+  onCategorySelected(categoryId?: string) {
+    console.log('Selected category:', categoryId);
+  }
+}
+```
+
+## Module Exports
+
+The `FileStorageModule` exports the following components:
+- `CategoryTreeComponent`
+- `FilesGridComponent`
+- `FileUploadComponent`
+
 ## Dependencies
 
-- `@memberjunction/core`: For metadata and entity access
-- `@memberjunction/core-entities`: For file-related entity types
-- `@memberjunction/global`: For global utilities
-- `@memberjunction/graphql-dataprovider`: For GraphQL data operations
-- `@progress/kendo-angular-upload`: For file upload UI
-- `@progress/kendo-angular-grid`: For file grid display
-- `@progress/kendo-angular-treeview`: For category tree view
+### MemberJunction Dependencies
+- `@memberjunction/core` (^2.43.0): Core metadata and entity access
+- `@memberjunction/core-entities` (^2.43.0): File-related entity types
+- `@memberjunction/global` (^2.43.0): Global utilities
+- `@memberjunction/graphql-dataprovider` (^2.43.0): GraphQL data operations
+- `@memberjunction/ng-container-directives` (^2.43.0): Container directives
+- `@memberjunction/ng-shared` (^2.43.0): Shared Angular services
+
+### Kendo UI Dependencies
+- `@progress/kendo-angular-buttons` (^16.2.0)
+- `@progress/kendo-angular-dialog` (^16.2.0)
+- `@progress/kendo-angular-dropdowns` (^16.2.0)
+- `@progress/kendo-angular-grid` (^16.2.0)
+- `@progress/kendo-angular-indicators` (^16.2.0)
+- `@progress/kendo-angular-menu` (^16.2.0)
+- `@progress/kendo-angular-treeview` (^16.2.0)
+- `@progress/kendo-angular-upload` (^16.2.0)
+
+### Other Dependencies
+- `tslib` (^2.3.0)
+- `zod` (^3.23.4): Schema validation
+
+## Build and Development
+
+### Building the Package
+```bash
+cd packages/Angular/Generic/file-storage
+npm run build
+```
+
+### Watch Mode
+```bash
+npm run watch
+```
+
+### Integration with MemberJunction
+
+This package integrates with:
+- **File Storage Providers**: Automatically uses the highest priority active provider
+- **GraphQL API**: Uses MemberJunction's GraphQL layer for all operations
+- **Entity Framework**: Leverages MemberJunction's entity system for type safety
+- **Permissions**: Respects entity-level permissions for Files and File Categories
+
+## Notes
+
+- File deletion is restricted based on upload status and age (10 minutes for pending files)
+- The component automatically handles file overwrite scenarios with user confirmation
+- All file operations are tracked with status updates (Pending → Uploaded)
+- File download uses provider-specific signed URLs for security
+- Category operations support drag-and-drop reorganization
+- Components include loading states for all async operations

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/ng-file-storage",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "MemberJunction: Angular components for managing files, and related components.",
   "main": "./dist/public-api.js",
   "typings": "./dist/public-api.d.ts",
@@ -26,12 +26,12 @@
     "@angular/router": "18.0.2"
   },
   "dependencies": {
-    "@memberjunction/core": "2.43.0",
-    "@memberjunction/core-entities": "2.43.0",
-    "@memberjunction/global": "2.43.0",
-    "@memberjunction/graphql-dataprovider": "2.43.0",
-    "@memberjunction/ng-container-directives": "2.43.0",
-    "@memberjunction/ng-shared": "2.43.0",
+    "@memberjunction/core": "2.44.0",
+    "@memberjunction/core-entities": "2.44.0",
+    "@memberjunction/global": "2.44.0",
+    "@memberjunction/graphql-dataprovider": "2.44.0",
+    "@memberjunction/ng-container-directives": "2.44.0",
+    "@memberjunction/ng-shared": "2.44.0",
     "@progress/kendo-angular-buttons": "16.2.0",
     "@progress/kendo-angular-dialog": "16.2.0",
     "@progress/kendo-angular-dropdowns": "16.2.0",