🔗 Shared Module - TypeScript Functions

/**
 * Shows the global loading spinner
 * Updates loading state to true
 * Displays loading overlay across the application
 * Used for indicating async operations in progress
 * @returns {void}
 */
show(): void

/**
 * Hides the global loading spinner
 * Updates loading state to false
 * Removes loading overlay from the application
 * Called when async operations complete
 * @returns {void}
 */
hide(): void

/**
 * Returns observable of current loading state
 * Allows components to subscribe to loading changes
 * Provides reactive updates for loading indicators
 * Used by loading component and interceptors
 * @returns {Observable<boolean>} Loading state observable
 */
getLoadingState(): Observable<boolean>

/**
 * Displays success toast notification
 * Shows green-themed success message to user
 * Automatically dismisses after configured duration
 * Used for confirming successful operations
 * @param {string} message - Success message to display
 * @param {string} title - Optional toast title
 * @returns {void}
 */
showSuccess(message: string, title?: string): void

/**
 * Displays error toast notification
 * Shows red-themed error message to user
 * Longer display duration for error visibility
 * Used for notifying operation failures
 * @param {string} message - Error message to display
 * @param {string} title - Optional toast title
 * @returns {void}
 */
showError(message: string, title?: string): void

/**
 * Displays warning toast notification
 * Shows yellow-themed warning message to user
 * Used for cautionary messages and validation warnings
 * Intermediate display duration for user attention
 * @param {string} message - Warning message to display
 * @param {string} title - Optional toast title
 * @returns {void}
 */
showWarning(message: string, title?: string): void

/**
 * Displays informational toast notification
 * Shows blue-themed information message to user
 * Used for general information and status updates
 * Standard display duration for informational content
 * @param {string} message - Information message to display
 * @param {string} title - Optional toast title
 * @returns {void}
 */
showInfo(message: string, title?: string): void

/**
 * Formats date according to specified format string
 * Supports various date formats and localization
 * Handles timezone conversions and null safety
 * Used throughout application for consistent date display
 * @param {Date} date - Date object to format
 * @param {string} format - Format pattern (YYYY-MM-DD, etc.)
 * @returns {string} Formatted date string
 */
formatDate(date: Date, format: string): string

/**
 * Gets the current user's timezone
 * Detects browser timezone automatically
 * Returns timezone identifier string
 * Used for timezone-aware date operations
 * @returns {string} Timezone identifier (e.g., 'America/New_York')
 */
getCurrentTimezone(): string

/**
 * Creates a deep copy of an object
 * Handles nested objects and arrays recursively
 * Prevents reference sharing between objects
 * Used for immutable data operations
 * @param {T} obj - Object to clone
 * @returns {T} Deep cloned object
 */
deepClone<T>(obj: T): T

/**
 * Sorts array by specified property
 * Supports ascending and descending order
 * Handles string, number, and date comparisons
 * Returns new sorted array without mutating original
 * @param {T[]} array - Array to sort
 * @param {string} key - Property name to sort by
 * @param {'asc' | 'desc'} direction - Sort direction
 * @returns {T[]} Sorted array
 */
sortArray<T>(array: T[], key: string, direction: 'asc' | 'desc'): T[]

/**
 * Filters array by search term across multiple fields
 * Case-insensitive search across specified properties
 * Supports partial matching and multiple field search
 * Returns filtered array matching search criteria
 * @param {T[]} array - Array to filter
 * @param {string} searchTerm - Search term
 * @param {string[]} fields - Fields to search in
 * @returns {T[]} Filtered array
 */
filterArray<T>(array: T[], searchTerm: string, fields: string[]): T[]

/**
 * Truncates text to specified length with ellipsis
 * Adds '...' when text exceeds limit
 * Preserves word boundaries when possible
 * Used for consistent text display in tables and cards
 * @param {string} text - Text to truncate
 * @param {number} maxLength - Maximum length
 * @returns {string} Truncated text with ellipsis
 */
truncateText(text: string, maxLength: number): string

/**
 * Generates random alphanumeric string
 * Uses cryptographically secure random generation
 * Includes uppercase, lowercase, and numbers
 * Used for temporary IDs and unique identifiers
 * @param {number} length - Length of string to generate
 * @returns {string} Random alphanumeric string
 */
generateRandomString(length: number): string

/**
 * Validates email address format
 * Uses RFC-compliant email regex pattern
 * Checks for proper email structure and domain
 * Returns boolean validation result
 * @param {string} email - Email address to validate
 * @returns {boolean} True if email is valid
 */
validateEmail(email: string): boolean

/**
 * Validates phone number format
 * Supports international and domestic formats
 * Handles various phone number patterns
 * Used for form validation across modules
 * @param {string} phone - Phone number to validate
 * @returns {boolean} True if phone number is valid
 */
validatePhoneNumber(phone: string): boolean

/**
 * Pipe for truncating text with configurable length
 * Usage: {{ text | truncate:50 }}
 * Adds ellipsis when text exceeds limit
 * Preserves word boundaries when possible
 * @param {string} value - Text to truncate
 * @param {number} limit - Maximum character limit
 * @returns {string} Truncated text
 */
transform(value: string, limit: number = 100): string

/**
 * Pipe for safely rendering HTML content
 * Usage: {{ htmlContent | safeHtml }}
 * Sanitizes HTML to prevent XSS attacks
 * Allows safe HTML rendering in templates
 * @param {string} value - HTML content to sanitize
 * @returns {SafeHtml} Sanitized HTML content
 */
transform(value: string): SafeHtml

/**
 * Pipe for formatting phone numbers
 * Usage: {{ phone | phoneFormat }}
 * Formats numbers according to regional standards
 * Handles international and domestic formats
 * @param {string} value - Phone number to format
 * @param {string} format - Format type (international, domestic)
 * @returns {string} Formatted phone number
 */
transform(value: string, format: string = 'domestic'): string