@cdevhub/ngx-chat 1.0.8 → 1.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdevhub/ngx-chat",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "A pure presentational Angular 21 library for building chat interfaces",
   "publishConfig": {
     "access": "public"

package/types/cdevhub-ngx-chat.d.ts

@@ -1560,10 +1560,12 @@ interface ChatSendEvent {
     readonly replyTo?: string;
     /** Optional metadata to include with the message */
     readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Optional timestamp for message ordering (defaults to now if not provided) */
+    readonly timestamp?: Date;
 }
 /**
  * Reference to a pending attachment for send events.
- * The actual attachment data is managed by the parent.
+ * Contains the File object for the parent to upload.
  */
 interface PendingAttachmentRef {
     /** Unique identifier for this pending attachment */
@@ -1574,6 +1576,8 @@ interface PendingAttachmentRef {
     readonly mimeType: string;
     /** File size in bytes */
     readonly size: number;
+    /** The original File object for upload */
+    readonly file: File;
 }
 /**
  * Event emitted when the user's typing state changes.
@@ -2078,6 +2082,7 @@ declare const DEFAULT_GROUPING_THRESHOLD_MS = 60000;
  * @example
  * ```typescript
  * const group: MessageGroup = {
+ *   id: 'group-msg-1',
  *   senderId: 'self',
  *   senderName: undefined,
  *   avatar: '/avatar.png',
@@ -2087,6 +2092,11 @@ declare const DEFAULT_GROUPING_THRESHOLD_MS = 60000;
  * ```
  */
 interface MessageGroup {
+    /**
+     * Stable unique identifier for this group.
+     * Derived from the first message's ID for consistent tracking.
+     */
+    readonly id: string;
     /** The sender type of all messages in this group */
     readonly senderId: ChatMessage['sender'];
     /** Display name of the sender (from first message) */
@@ -2387,10 +2397,8 @@ declare class ChatMessagesComponent implements OnDestroy {
     private readonly loadMoreDebounced;
     /** Timestamp formatter cache */
     private timestampFormatter;
-    /** ResizeObserver for measuring message heights in virtual scroll mode */
+    /** Native ResizeObserver for measuring message heights in virtual scroll mode */
     private resizeObserver;
-    /** Map of message IDs to their indices for height measurement */
-    private readonly messageIndexMap;
     /**
      * Merged configuration from input and global config.
      */
@@ -2433,6 +2441,17 @@ declare class ChatMessagesComponent implements OnDestroy {
      * Start index of visible messages (for track by and height measurement).
      */
     readonly visibleStartIndex: _angular_core.Signal<number>;
+    /**
+     * Computed map of message IDs to their indices.
+     * Used for height measurement in virtual scroll mode.
+     * Uses computed() instead of effect() to avoid anti-pattern.
+     */
+    private readonly messageIndexMap;
+    /**
+     * Tracks the previous message count to detect changes.
+     * Used to sync virtual scroll service only when needed.
+     */
+    private lastSyncedMessageCount;
     constructor();
     /**
      * Handles scroll events from the scrollbar.
@@ -2442,6 +2461,7 @@ declare class ChatMessagesComponent implements OnDestroy {
     onScroll(event: Event): void;
     /**
      * Programmatically scrolls to the bottom of the message list.
+     * Uses requestAnimationFrame to ensure DOM is fully updated before scrolling.
      */
     scrollToBottom(): void;
     /**
@@ -4843,6 +4863,91 @@ declare class ChatErrorBoundaryComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChatErrorBoundaryComponent, "ngx-chat-error-boundary", never, { "fallbackMessage": { "alias": "fallbackMessage"; "required": false; "isSignal": true; }; }, { "retry": "retry"; }, never, ["*"], true, never>;
 }
 
+/**
+ * Directive that traps focus within its host element.
+ *
+ * This directive is used for accessibility compliance in modal dialogs,
+ * action panels, and other overlay content where keyboard focus should
+ * be constrained to the interactive elements within.
+ *
+ * Features:
+ * - Traps Tab/Shift+Tab navigation within the element
+ * - Auto-focuses the first focusable element when enabled
+ * - Restores focus to the previously focused element on destroy
+ * - Supports deferred focus for async content
+ *
+ * @example Basic usage
+ * ```html
+ * <div ngxChatFocusTrap>
+ *   <button>First</button>
+ *   <button>Second</button>
+ *   <button>Third</button>
+ * </div>
+ * ```
+ *
+ * @example Conditional focus trap
+ * ```html
+ * <div [ngxChatFocusTrap]="isOpen()">
+ *   <button>Close</button>
+ *   <div>Modal content</div>
+ * </div>
+ * ```
+ *
+ * @example With auto-focus disabled
+ * ```html
+ * <div ngxChatFocusTrap [ngxChatFocusTrapAutoFocus]="false">
+ *   <button>First</button>
+ * </div>
+ * ```
+ */
+declare class ChatFocusTrapDirective implements OnDestroy {
+    private readonly elementRef;
+    private readonly focusTrapFactory;
+    private readonly injector;
+    /**
+     * Whether the focus trap is enabled.
+     * When false, focus can move freely in and out of the element.
+     */
+    readonly ngxChatFocusTrap: _angular_core.InputSignal<boolean>;
+    /**
+     * Whether to auto-focus the first tabbable element when the trap is created.
+     */
+    readonly ngxChatFocusTrapAutoFocus: _angular_core.InputSignal<boolean>;
+    /**
+     * The underlying CDK FocusTrap instance.
+     */
+    private focusTrap;
+    /**
+     * Element that had focus before the trap was activated.
+     * Used to restore focus on destroy.
+     */
+    private previouslyFocusedElement;
+    constructor();
+    /**
+     * Initializes the focus trap after render.
+     */
+    private initializeFocusTrap;
+    /**
+     * Manually focuses the first tabbable element within the trap.
+     */
+    focusFirstTabbableElement(): void;
+    /**
+     * Manually focuses the last tabbable element within the trap.
+     */
+    focusLastTabbableElement(): void;
+    /**
+     * Checks if an element is focusable within the trap.
+     */
+    hasFocusableElements(): boolean;
+    /**
+     * Cleanup on destroy.
+     * Disables the trap and restores focus to the previous element.
+     */
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChatFocusTrapDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ChatFocusTrapDirective, "[ngxChatFocusTrap]", ["ngxChatFocusTrap"], { "ngxChatFocusTrap": { "alias": "ngxChatFocusTrap"; "required": false; "isSignal": true; }; "ngxChatFocusTrapAutoFocus": { "alias": "ngxChatFocusTrapAutoFocus"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 /**
  * @fileoverview Error constants and factory functions for ngx-chat.
  * Provides centralized error definitions and utilities for error handling.
@@ -5992,6 +6097,187 @@ declare function isSafeUrl(url: string): boolean;
  */
 declare function validateMessage(content: string, config: ChatValidationConfig): ValidationResult;
 
+/**
+ * @fileoverview Attachment utility functions for ngx-chat library.
+ * Pure functions for creating, validating, and transforming attachments.
+ * @module ngx-chat/utils
+ */
+
+/**
+ * Determines the attachment type from a MIME type string.
+ *
+ * @param mimeType - The MIME type to check (e.g., 'image/jpeg')
+ * @returns The attachment type, defaults to 'file' for unknown types
+ *
+ * @example
+ * ```typescript
+ * getAttachmentType('image/jpeg'); // 'image'
+ * getAttachmentType('video/mp4'); // 'video'
+ * getAttachmentType('application/pdf'); // 'file'
+ * ```
+ */
+declare function getAttachmentType(mimeType: string): AttachmentType;
+/**
+ * Determines the attachment type from a File object.
+ *
+ * @param file - The File object to check
+ * @returns The attachment type
+ *
+ * @example
+ * ```typescript
+ * const file = new File([''], 'photo.jpg', { type: 'image/jpeg' });
+ * getAttachmentTypeFromFile(file); // 'image'
+ * ```
+ */
+declare function getAttachmentTypeFromFile(file: File): AttachmentType;
+/**
+ * Checks if an attachment type supports preview generation.
+ *
+ * @param type - The attachment type to check
+ * @returns True if previews can be generated
+ */
+declare function isPreviewable(type: AttachmentType): boolean;
+/**
+ * Checks if a file extension supports preview generation.
+ *
+ * @param filename - The filename to check
+ * @returns True if the file extension supports previews
+ */
+declare function isPreviewableByExtension(filename: string): boolean;
+/**
+ * Creates a PendingAttachment from a File object.
+ *
+ * @param file - The File object to create an attachment from
+ * @param options - Optional configuration
+ * @returns A PendingAttachment ready for upload
+ *
+ * @example
+ * ```typescript
+ * const file = new File(['content'], 'document.pdf', { type: 'application/pdf' });
+ * const pending = createPendingAttachment(file);
+ * // { id: 'att-123', file, type: 'file', status: 'pending', progress: 0 }
+ * ```
+ */
+declare function createPendingAttachment(file: File, options?: {
+    id?: string;
+    createPreview?: boolean;
+}): PendingAttachment;
+/**
+ * Creates a MessageAttachment from upload result data.
+ *
+ * @param data - The attachment data from the server
+ * @returns A MessageAttachment object
+ */
+declare function createMessageAttachment(data: {
+    id: string;
+    url: string;
+    name: string;
+    size: number;
+    mimeType: string;
+    thumbnail?: string;
+    dimensions?: {
+        width: number;
+        height: number;
+    };
+    duration?: number;
+}): MessageAttachment;
+/**
+ * Validates a file against size and type constraints.
+ *
+ * @param file - The file to validate
+ * @param options - Validation options
+ * @returns Validation result with error message if invalid
+ *
+ * @example
+ * ```typescript
+ * const result = validateAttachment(file, {
+ *   maxSize: 5 * 1024 * 1024, // 5MB
+ *   allowedTypes: ['image/*', 'application/pdf']
+ * });
+ * if (!result.valid) {
+ *   console.error(result.error);
+ * }
+ * ```
+ */
+declare function validateAttachment(file: File, options?: {
+    maxSize?: number;
+    allowedTypes?: string[];
+    allowedExtensions?: string[];
+}): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Formats a file size in bytes to a human-readable string.
+ *
+ * @param bytes - The size in bytes
+ * @param decimals - Number of decimal places (default: 1)
+ * @returns Formatted string like "1.5 MB"
+ *
+ * @example
+ * ```typescript
+ * formatFileSize(1024); // "1 KB"
+ * formatFileSize(1536); // "1.5 KB"
+ * formatFileSize(1048576); // "1 MB"
+ * formatFileSize(1073741824); // "1 GB"
+ * ```
+ */
+declare function formatFileSize(bytes: number, decimals?: number): string;
+/**
+ * Formats a duration in seconds to a human-readable string.
+ *
+ * @param seconds - The duration in seconds
+ * @returns Formatted string like "1:23" or "1:23:45"
+ *
+ * @example
+ * ```typescript
+ * formatDuration(65); // "1:05"
+ * formatDuration(3665); // "1:01:05"
+ * ```
+ */
+declare function formatDuration(seconds: number): string;
+/**
+ * Extracts the file extension from a filename.
+ *
+ * @param filename - The filename to extract from
+ * @returns Lowercase extension without the dot, or empty string
+ *
+ * @example
+ * ```typescript
+ * getFileExtension('photo.JPG'); // 'jpg'
+ * getFileExtension('document.pdf'); // 'pdf'
+ * getFileExtension('noextension'); // ''
+ * ```
+ */
+declare function getFileExtension(filename: string): string;
+/**
+ * Gets a display-friendly file name, truncating if too long.
+ *
+ * @param filename - The full filename
+ * @param maxLength - Maximum length (default: 30)
+ * @returns Truncated filename with extension preserved
+ *
+ * @example
+ * ```typescript
+ * truncateFileName('very-long-file-name.pdf', 15); // 'very-lo...e.pdf'
+ * ```
+ */
+declare function truncateFileName(filename: string, maxLength?: number): string;
+/**
+ * Revokes a blob URL to free memory.
+ * Safe to call with undefined/null.
+ *
+ * @param url - The blob URL to revoke
+ */
+declare function revokePreviewUrl(url: string | undefined): void;
+/**
+ * Gets the appropriate icon name for an attachment type.
+ *
+ * @param type - The attachment type
+ * @returns Icon identifier
+ */
+declare function getAttachmentIcon(type: AttachmentType): string;
+
 /**
  * Service for accessing and merging chat configuration.
  *
@@ -7055,6 +7341,15 @@ interface VisibleRange {
  * }
  * ```
  */
+/**
+ * @Injectable without `providedIn` - must be provided at component level.
+ *
+ * This service maintains stateful data (scroll position, item heights, etc.)
+ * that must be scoped to each ChatMessagesComponent instance. If provided
+ * at root level, multiple chat instances would share state, causing bugs.
+ *
+ * @see ChatMessagesComponent which provides this service
+ */
 declare class ChatVirtualScrollService {
     private readonly configService;
     private readonly config;
@@ -7246,5 +7541,5 @@ declare const chatAnimations: {
     readonly fadeInOut: AnimationTriggerMetadata;
 };
 
-export { AttachmentPickerComponent, AttachmentPreviewComponent, AudioPreviewComponent, ButtonsActionComponent, CHAT_CONFIG, CHAT_CONFIG_OVERRIDES, CHAT_FEATURES, CHAT_I18N, CHAT_I18N_OVERRIDES, ChatA11yService, ChatAttachmentComponent, ChatAttachmentService, ChatComponent, ChatConfigService, ChatDropZoneDirective, ChatErrorBoundaryComponent, ChatErrorRecoveryService, ChatHeaderComponent, ChatHeaderContentDirective, ChatMarkdownComponent, ChatMarkdownService, ChatMessageActionsComponent, ChatMessageBubbleComponent, ChatMessagesComponent, ChatSenderComponent, ChatTypingIndicatorComponent, ChatVirtualScrollService, ConfirmActionComponent, DEFAULT_ATTACHMENT_CONFIG, DEFAULT_BEHAVIOR_CONFIG, DEFAULT_CHAT_CONFIG, DEFAULT_CHAT_I18N, DEFAULT_ERROR_RECOVERY_CONFIG, DEFAULT_GROUPING_THRESHOLD_MS, DEFAULT_KEYBOARD_CONFIG, DEFAULT_MARKDOWN_CONFIG, DEFAULT_VALIDATION_CONFIG, DEFAULT_VIRTUAL_SCROLL_CONFIG, ERROR_CODES, FilePreviewComponent, ImagePreviewComponent, MultiSelectActionComponent, SelectActionComponent, VideoPreviewComponent, allActionsResponded, appendMessageContent, breakLongWords, canRetry, chatAnimations, createButtonsAction, createConfirmAction, createError, createMultiSelectAction, createOtherMessage, createSelectAction, createSelfMessage, createSystemMessage, disableAllActions, errorShake, fadeInOut, findMessage, generateId, getActionById, getErrorMessages, getLastMessage, getMessagesByStatus, getPendingActions, getRetryDelay, getRetryableMessages, groupMessages, incrementRetryCount, isAuthError, isClientError, isNetworkError, isSafeUrl, isUngroupable, messageEnter, provideChat, removeMessage, resetIdCounter, sanitizeContent, shouldGroupMessages, stripInvisibleChars, typingPulse, updateActionResponse, updateMessageContent, updateMessageStatus, validateMessage };
+export { AttachmentPickerComponent, AttachmentPreviewComponent, AudioPreviewComponent, ButtonsActionComponent, CHAT_CONFIG, CHAT_CONFIG_OVERRIDES, CHAT_FEATURES, CHAT_I18N, CHAT_I18N_OVERRIDES, ChatA11yService, ChatAttachmentComponent, ChatAttachmentService, ChatComponent, ChatConfigService, ChatDropZoneDirective, ChatErrorBoundaryComponent, ChatErrorRecoveryService, ChatFocusTrapDirective, ChatHeaderComponent, ChatHeaderContentDirective, ChatMarkdownComponent, ChatMarkdownService, ChatMessageActionsComponent, ChatMessageBubbleComponent, ChatMessagesComponent, ChatSenderComponent, ChatTypingIndicatorComponent, ChatVirtualScrollService, ConfirmActionComponent, DEFAULT_ATTACHMENT_CONFIG, DEFAULT_BEHAVIOR_CONFIG, DEFAULT_CHAT_CONFIG, DEFAULT_CHAT_I18N, DEFAULT_ERROR_RECOVERY_CONFIG, DEFAULT_GROUPING_THRESHOLD_MS, DEFAULT_KEYBOARD_CONFIG, DEFAULT_MARKDOWN_CONFIG, DEFAULT_VALIDATION_CONFIG, DEFAULT_VIRTUAL_SCROLL_CONFIG, ERROR_CODES, FilePreviewComponent, ImagePreviewComponent, MultiSelectActionComponent, SelectActionComponent, VideoPreviewComponent, allActionsResponded, appendMessageContent, breakLongWords, canRetry, chatAnimations, createButtonsAction, createConfirmAction, createError, createMessageAttachment, createMultiSelectAction, createOtherMessage, createPendingAttachment, createSelectAction, createSelfMessage, createSystemMessage, disableAllActions, errorShake, fadeInOut, findMessage, formatDuration, formatFileSize, generateId, getActionById, getAttachmentIcon, getAttachmentType, getAttachmentTypeFromFile, getErrorMessages, getFileExtension, getLastMessage, getMessagesByStatus, getPendingActions, getRetryDelay, getRetryableMessages, groupMessages, incrementRetryCount, isAuthError, isClientError, isNetworkError, isPreviewable, isPreviewableByExtension, isSafeUrl, isUngroupable, messageEnter, provideChat, removeMessage, resetIdCounter, revokePreviewUrl, sanitizeContent, shouldGroupMessages, stripInvisibleChars, truncateFileName, typingPulse, updateActionResponse, updateMessageContent, updateMessageStatus, validateAttachment, validateMessage };
 export type { ActionButton, ActionOption, AttachmentClickEvent, AttachmentCompleteEvent, AttachmentErrorEvent, AttachmentEvent, AttachmentProgressEvent, AttachmentType, AttachmentUploadStatus, ButtonVariant, ButtonsAction, ButtonsActionEvent, ButtonsLayout, ChatAttachmentConfig, ChatBehaviorConfig, ChatConfig, ChatConfigInput, ChatDirection, ChatErrorCode, ChatErrorRecoveryConfig, ChatFeatures, ChatI18n, ChatKeyboardConfig, ChatLoadMoreEvent, ChatMarkdownConfig, ChatMessage, ChatMessageError, ChatMessageStatusEvent, ChatRetryEvent, ChatSendEvent, ChatTheme, ChatTypingEvent, ChatValidationConfig, ChatVirtualScrollConfig, ConfirmAction, ConfirmActionEvent, CreateButtonsActionOptions, CreateConfirmActionOptions, CreateMessageOptions, CreateMultiSelectActionOptions, CreateOtherMessageOptions, CreateSelectActionOptions, DeepPartial, Dimensions, FileValidationResult, MarkdownParseResult, MessageAction, MessageActionEvent, MessageActionType, MessageAttachment, MessageGroup, MessageSender, MessageStatus, MultiSelectAction, MultiSelectActionEvent, PendingAttachment, PendingAttachmentRef, ProvideChatOptions, QueuedMessage, SelectAction, SelectActionEvent, ValidationResult, VisibleRange };