diff --git a/docs.json b/docs.json index 40eea0779..60d74eb3b 100644 --- a/docs.json +++ b/docs.json @@ -2589,6 +2589,7 @@ "group": "Chat", "pages": [ "ui-kit/angular/core-features", + "ui-kit/angular/offline-support", "ui-kit/angular/extensions", "ui-kit/angular/ai-features" ] diff --git a/ui-kit/angular/angular-conversation.mdx b/ui-kit/angular/angular-conversation.mdx index d9e1f2327..87de3b8b3 100644 --- a/ui-kit/angular/angular-conversation.mdx +++ b/ui-kit/angular/angular-conversation.mdx @@ -42,7 +42,7 @@ Three sections working together: Wire the conversation list and message components together in your root component. The UIKit's `ChatStateService` handles all the wiring — when a user clicks a conversation, `cometchat-conversations` updates the service, and the message components automatically react to the change. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```ts title="src/app/app.ts" expandable @@ -128,7 +128,7 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; }) export class App implements OnInit { chatStateService = inject(ChatStateService); - isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (Angular 21 default) + isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (the default since Angular 21) ngOnInit(): void { CometChatUIKit.getLoggedinUser().then((user: CometChat.User | null) => { diff --git a/ui-kit/angular/angular-one-to-one-chat.mdx b/ui-kit/angular/angular-one-to-one-chat.mdx index b51973c6c..c2480ec71 100644 --- a/ui-kit/angular/angular-one-to-one-chat.mdx +++ b/ui-kit/angular/angular-one-to-one-chat.mdx @@ -44,7 +44,7 @@ Everything goes in the root component (`App` in `src/app/app.ts`) — no extra f The app fetches a user (or group) on mount, sets it as the active entity via `ChatStateService`, and renders the three message components. The components auto-subscribe to the service — no prop passing needed. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```ts title="src/app/app.ts" expandable diff --git a/ui-kit/angular/angular-tab-based-chat.mdx b/ui-kit/angular/angular-tab-based-chat.mdx index 2c0e6c76d..5b89a27da 100644 --- a/ui-kit/angular/angular-tab-based-chat.mdx +++ b/ui-kit/angular/angular-tab-based-chat.mdx @@ -42,7 +42,7 @@ Three sections working together: Wire everything together. `ChatStateService` handles the state — `cometchat-conversations` and `cometchat-users` automatically update the service when an item is clicked, and the message components auto-subscribe. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```ts title="src/app/app.ts" expandable @@ -190,7 +190,7 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; }) export class App implements OnInit { chatStateService = inject(ChatStateService); - isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (Angular 21 default) + isLoggedIn = signal(false); // a signal so the view updates in zoneless apps (the default since Angular 21) activeTab: "chats" | "calls" | "users" = "chats"; ngOnInit(): void { diff --git a/ui-kit/angular/api-reference/formatter-config-service.mdx b/ui-kit/angular/api-reference/formatter-config-service.mdx index e4013d464..5a159f946 100644 --- a/ui-kit/angular/api-reference/formatter-config-service.mdx +++ b/ui-kit/angular/api-reference/formatter-config-service.mdx @@ -97,7 +97,7 @@ Replaces the built-in default formatters with custom formatters. **Use Case:** When you want complete control over which formatters are used globally. **Example:** -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable // In app initialization (main.ts or app.ts) diff --git a/ui-kit/angular/api-reference/introduction.mdx b/ui-kit/angular/api-reference/introduction.mdx index 306fcbe13..56bb29146 100644 --- a/ui-kit/angular/api-reference/introduction.mdx +++ b/ui-kit/angular/api-reference/introduction.mdx @@ -10,7 +10,7 @@ description: "Reference for CometChat UIKit Angular injectable services." | Purpose | Index of the Angular UI Kit's injectable services — start here to find the right one | | Package | `@cometchat/chat-uikit-angular` v5.x | | Services | `ChatStateService` · `FormatterConfigService` · `MessageBubbleConfigService` · `RichTextEditorService` · `SearchConversationsService` · `SearchMessagesService` · `CometChatTemplatesService` | -| Injected with | `inject()` — all are `providedIn: 'root'` | +| Injected with | `inject()` — all are `providedIn: 'root'` except `SearchConversationsService` and `SearchMessagesService`, which are component-provided (add them to your component's `providers`) | | Full list | See [Services](#services) | diff --git a/ui-kit/angular/api-reference/search-conversations-service.mdx b/ui-kit/angular/api-reference/search-conversations-service.mdx index 7581e143f..6380c8b0e 100644 --- a/ui-kit/angular/api-reference/search-conversations-service.mdx +++ b/ui-kit/angular/api-reference/search-conversations-service.mdx @@ -11,7 +11,7 @@ description: Signal-based service for conversation search state, SDK queries, pa | Class | `SearchConversationsService` | | Package | `@cometchat/chat-uikit-angular` v5.x | | Import | `import { SearchConversationsService } from "@cometchat/chat-uikit-angular";` | -| Injected with | `private svc = inject(SearchConversationsService);` — `providedIn: 'root'`, no module wiring | +| Injected with | `private svc = inject(SearchConversationsService);` — add `providers: [SearchConversationsService]` to your component. Not root-provided: `CometChatSearch` provides its own instance. | | Key methods | `search` · `loadMore` · `attachListeners` · `detachListeners` · `reset` | | Full API | See [Methods](#methods) | | Usage | See [Usage](#usage) | @@ -134,6 +134,7 @@ import { SearchConversationsService } from '@cometchat/chat-uikit-angular'; import { CometChatSearchFilter, States } from '@cometchat/chat-uikit-angular'; @Component({ + providers: [SearchConversationsService], selector: 'app-custom-search', template: ` @switch (service.fetchState()) { diff --git a/ui-kit/angular/api-reference/search-messages-service.mdx b/ui-kit/angular/api-reference/search-messages-service.mdx index 3f6f35cf7..cba00314c 100644 --- a/ui-kit/angular/api-reference/search-messages-service.mdx +++ b/ui-kit/angular/api-reference/search-messages-service.mdx @@ -11,7 +11,7 @@ description: Signal-based service for message search state, SDK queries, attachm | Class | `SearchMessagesService` | | Package | `@cometchat/chat-uikit-angular` v5.x | | Import | `import { SearchMessagesService } from "@cometchat/chat-uikit-angular";` | -| Injected with | `private svc = inject(SearchMessagesService);` — `providedIn: 'root'`, no module wiring | +| Injected with | `private svc = inject(SearchMessagesService);` — add `providers: [SearchMessagesService]` to your component. Not root-provided: `CometChatSearch` provides its own instance. | | Key methods | `search` · `loadMore` · `reset` | | Full API | See [Methods](#methods) | | Usage | See [Usage](#usage) | @@ -110,6 +110,7 @@ import { SearchMessagesService } from '@cometchat/chat-uikit-angular'; import { CometChatSearchFilter, States } from '@cometchat/chat-uikit-angular'; @Component({ + providers: [SearchMessagesService], selector: 'app-message-search', template: ` @if (service.fetchState() === States.loaded) { diff --git a/ui-kit/angular/api-reference/templates-service.mdx b/ui-kit/angular/api-reference/templates-service.mdx index 1ced859bc..1fbbf6e1e 100644 --- a/ui-kit/angular/api-reference/templates-service.mdx +++ b/ui-kit/angular/api-reference/templates-service.mdx @@ -261,7 +261,7 @@ interface MessageListTemplates { ### Shared Loading + Component-Specific Override -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable @Component({ diff --git a/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx b/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx index 6b26fbfb0..77f51cc65 100644 --- a/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx +++ b/ui-kit/angular/components/cometchat-ai-assistant-chat.mdx @@ -74,7 +74,7 @@ import { `, }) export class AiChatComponent implements OnInit { - // A signal so the view updates when the fetch resolves — required in zoneless apps (Angular 21 default) + // A signal so the view updates when the fetch resolves — required in zoneless apps (the default since Angular 21) agentUser = signal(undefined); constructor(private streamingService: CometChatAIStreamingService) {} diff --git a/ui-kit/angular/components/cometchat-conversations.mdx b/ui-kit/angular/components/cometchat-conversations.mdx index 056d7a26e..f542d1a85 100644 --- a/ui-kit/angular/components/cometchat-conversations.mdx +++ b/ui-kit/angular/components/cometchat-conversations.mdx @@ -44,6 +44,7 @@ The component follows a **Hybrid Approach** architecture where: - **Context Menu**: Customizable actions for each conversation - **Sound Notifications**: Optional notification sounds for new messages - **Error Handling**: Comprehensive error handling with retry logic +- **Offline Support**: With offline support on, saved chats show at once and the list shows **Connect to load chats** offline with nothing saved. See [Offline Support](/ui-kit/angular/offline-support) ## Keyboard Accessibility @@ -177,6 +178,7 @@ export class ChatComponent { |----------|------|---------|-------------| | `hideReceipts` | `boolean` | `false` | Hide message read receipts in conversation items | | `hideError` | `boolean` | `false` | Hide error views when errors occur | +| `hideOfflineNotices` | `boolean` | `false` | Hide the notice shown when the offline cache was reset and unsent messages were lost. No effect while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#hide-the-offline-notices) | | `hidePinConversation` | `boolean` | `false` | Hide the pin/unpin option in the row context menu. See [Pinned Conversations](#pinned-conversations) | | `hideDeleteConversation` | `boolean` | `false` | Hide delete option in context menu | | `hideUserStatus` | `boolean` | `false` | Hide online/offline status indicators | @@ -1127,7 +1129,7 @@ The component supports both service-level and component-level configuration. Ser Configure the ConversationsService to set defaults for all component instances: -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable import { Component, OnInit } from '@angular/core'; @@ -1433,6 +1435,8 @@ The service includes automatic retry logic with exponential backoff for recovera - Timeout errors: Retries with increasing delays (1s, 2s, 4s) - Authentication errors: No retry (requires user action) +With [offline support](/ui-kit/angular/offline-support) on, this retry does not run. A load that fails offline with nothing on screen shows **Connect to load chats** and loads once by itself when the connection is back; a real error shows the error view with Retry. + ### Custom Error View Provide a custom error view with retry functionality: diff --git a/ui-kit/angular/components/cometchat-message-composer.mdx b/ui-kit/angular/components/cometchat-message-composer.mdx index 725ce80dd..aaaa144b4 100644 --- a/ui-kit/angular/components/cometchat-message-composer.mdx +++ b/ui-kit/angular/components/cometchat-message-composer.mdx @@ -46,6 +46,7 @@ The component follows a **Service-Based Architecture** where: - **Full Accessibility**: WCAG 2.1 Level AA compliant with keyboard navigation and screen reader support - **Extensive Customization**: Template inputs for all UI sections - **Lightweight**: No external rich text editor dependencies (100KB+ smaller bundle) +- **Offline Support**: With offline support on, text messages sent offline are queued and sent on reconnect. Edits are never queued: a failed edit leaves edit mode and reaches the `(error)` output. See [Offline Support](/ui-kit/angular/offline-support#composer-and-sending) diff --git a/ui-kit/angular/components/cometchat-message-list.mdx b/ui-kit/angular/components/cometchat-message-list.mdx index 114a2e633..f224ab7e1 100644 --- a/ui-kit/angular/components/cometchat-message-list.mdx +++ b/ui-kit/angular/components/cometchat-message-list.mdx @@ -46,6 +46,7 @@ The component follows a **Hybrid Approach** architecture where: - **Text Formatters**: Extensible text formatting for mentions, links, and custom patterns - **Keyboard Navigation**: Full keyboard accessibility (WCAG 2.1 Level AA compliant) - **Sound Notifications**: notification sounds for new messages +- **Offline Support**: With offline support on, saved messages show at once, a **Connect to load more** row marks the end of what is saved, and unsent messages show **Not sent yet** or **Not sent. Tap to retry** with Retry and Delete. See [Offline Support](/ui-kit/angular/offline-support) @@ -87,7 +88,7 @@ import { CometChatMessageListComponent } from '@cometchat/chat-uikit-angular'; ` }) export class ChatComponent implements OnInit { - // A signal so the view updates when the fetch resolves — required in zoneless apps (Angular 21 default) + // A signal so the view updates when the fetch resolves — required in zoneless apps (the default since Angular 21) chatUser = signal(undefined); async ngOnInit(): Promise { @@ -375,6 +376,7 @@ This section provides a complete reference of all @Input properties, @Output eve | `hideAvatar` | `boolean` | `false` | Hides user avatars next to messages. | | `hideGroupActionMessages` | `boolean` | `false` | Hides system messages for group actions (member joined, left, etc.). | | `hideError` | `boolean` | `false` | Hides error views when errors occur during message loading. | +| `hideOfflineNotices` | `boolean` | `false` | Hides the offline notices about unsent messages (removed, not sent, outbox full, send under way, cache reset, and the other notices listed on the Offline Support page). No effect while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#hide-the-offline-notices). | | `hideReplyInThreadOption` | `boolean` | `false` | Hides the "Reply in Thread" option from message context menu. | | `hideThreadSubscriptionOption` | `boolean` | `false` | Hides the thread follow/unfollow option from the message context menu, without turning the feature off. See [Thread Subscription](#thread-subscription). | | `hidePinMessageOption` | `boolean` | `false` | Hides "Pin message" from the Organise flyout. See [Pin and Save](#pin-and-save). | @@ -591,6 +593,7 @@ if (this.messageList.isMessageTranslated(messageId)) { | `getMessageOptions` | `message: CometChat.BaseMessage` | `CometChatActionsIcon[]` | Returns the available context menu options for a message based on hide* inputs. | | `handleKeydown` | `event: KeyboardEvent` | `void` | Handles keyboard navigation events. Called automatically but can be triggered manually. | | `handleRetryClick` | none | `void` | Retries loading messages after an error. | +| `retryOfflineRead` | none | `void` | Offline support: reads the page behind the **Connect to load more** row, as tapping the row does. See [Offline Support](/ui-kit/angular/offline-support#your-own-connect-to-load-more-control). | | `copyMessageToClipboard` | `message: CometChat.BaseMessage` | `Promise` | Copies the text content of a message to the clipboard. | ### CalendarObject Interface @@ -4569,7 +4572,7 @@ Mobile devices require additional optimization considerations: |--------|---------|--------|--------------| | CPU | Fast | Limited | Reduce JS execution time | | Memory | 8-16GB | 2-4GB | Limit message history | -| Network | Fast | Variable | Implement offline support | +| Network | Fast | Variable | Turn on [offline support](/ui-kit/angular/offline-support) | | Battery | N/A | Critical | Reduce background processing | | Touch | N/A | Primary | Optimize touch handlers | @@ -4673,7 +4676,7 @@ Follow this checklist to ensure optimal performance: #### Mobile Optimization - [ ] Reduce page size for mobile devices - [ ] Implement touch-optimized interactions -- [ ] Consider offline support for poor connectivity +- [ ] Consider [offline support](/ui-kit/angular/offline-support) for poor connectivity - [ ] Test on actual mobile devices #### Monitoring @@ -4708,7 +4711,7 @@ This section provides comprehensive, copy-paste ready code examples for common u This example demonstrates the complete setup process for integrating CometChatMessageList into your Angular application, including CometChat initialization, user login, and component configuration. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name in `main.ts` instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name in `main.ts` instead. diff --git a/ui-kit/angular/components/cometchat-search.mdx b/ui-kit/angular/components/cometchat-search.mdx index b293a2099..72b912e84 100644 --- a/ui-kit/angular/components/cometchat-search.mdx +++ b/ui-kit/angular/components/cometchat-search.mdx @@ -312,6 +312,8 @@ When both conversation and message sections are active, the component coordinate When only one scope is active (via `searchIn`, `uid`, or `guid`), that section handles its own empty/error states independently. +With [offline support](/ui-kit/angular/offline-support#search) on, a keyword search that cannot reach the server, with no saved match, shows **Connect to search** instead of an error when every failed request was a not-connected one, and runs again once when the connection is back. Errors still reach `(searchError)`. + ## Advanced Usage @@ -861,5 +863,5 @@ export class SearchDemoComponent implements OnInit { - [SearchConversationsService](/ui-kit/angular/api-reference/search-conversations-service) — Conversation search state, SDK queries, real-time listeners - [SearchMessagesService](/ui-kit/angular/api-reference/search-messages-service) — Message search state, attachment-type filtering, scoped queries - [CometChatTemplatesService](/ui-kit/angular/api-reference/templates-service) — Template resolution priority chain and global template overrides -- [Accessibility](/ui-kit/angular/accessibility#search) — Cross-component keyboard accessibility reference +- [Accessibility](/ui-kit/angular/accessibility) — Cross-component keyboard accessibility reference - [Events](/ui-kit/angular/events) — UIKit event bus for decoupled component communication diff --git a/ui-kit/angular/core-features.mdx b/ui-kit/angular/core-features.mdx index 912129e70..ff7b3496b 100644 --- a/ui-kit/angular/core-features.mdx +++ b/ui-kit/angular/core-features.mdx @@ -9,7 +9,7 @@ description: "Review CometChat Angular UI Kit core features for messaging, media | --- | --- | | Package | `@cometchat/chat-uikit-angular` | | Required setup | `CometChatUIKit.init(UIKitSettings)` then `CometChatUIKit.login("UID")` — must complete before rendering any component | -| Core features | Instant Messaging, Media Sharing, Read Receipts, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Pin & Save Messages, Search, Threaded Conversations, Thread Subscription, Moderation, Report Message, Group Chat | +| Core features | Instant Messaging, Media Sharing, Read Receipts, Typing Indicator, User Presence, Reactions, Mentions, Rich Text Formatting, Quoted Reply, Pin & Save Messages, Search, Threaded Conversations, Thread Subscription, Moderation, Report Message, Group Chat, Offline Support | | Key components | `CometChatConversations` → [Conversations](/ui-kit/angular/components/cometchat-conversations), `CometChatMessageList` → [Message List](/ui-kit/angular/components/cometchat-message-list), `CometChatMessageComposer` → [Message Composer](/ui-kit/angular/components/cometchat-message-composer), `CometChatMessageHeader` → [Message Header](/ui-kit/angular/components/cometchat-message-header), `CometChatUsers` → [Users](/ui-kit/angular/components/cometchat-users), `CometChatGroups` → [Groups](/ui-kit/angular/components/cometchat-groups), `CometChatGroupMembers` → [Group Members](/ui-kit/angular/components/cometchat-group-members) | | CSS class prefix | `.cometchat-` | | Theming | Override CSS variables on `.cometchat` class. See [Theming](/ui-kit/angular/customization/theming) | @@ -276,6 +276,19 @@ Conversation and Advanced Search enables users to quickly find conversations, me See the [Search Messages Guide](/ui-kit/angular/guides/search-messages) for detailed implementation instructions. +## Offline Support + +Offline Support keeps the chat usable when the network drops. Chats and messages the user has already loaded appear at once from the device, text messages sent offline are queued and go out by themselves on reconnect, and unsent messages can be retried or deleted. It is available from v5.3.0 with Chat SDK 4.3.0 or later, and is **off by default**. Turn it on with `setOfflineConfig({ enabled: true })` on the `UIKitSettingsBuilder`. + +| Component | Functionality | +| --- | --- | +| [cometchat-conversations](/ui-kit/angular/components/cometchat-conversations) | Shows saved chats first, then merges the server page; shows **Connect to load chats** offline with nothing saved. | +| [cometchat-message-list](/ui-kit/angular/components/cometchat-message-list) | Shows saved messages, a **Connect to load more** row past them, **Not sent yet** on queued messages and **Not sent. Tap to retry** on failed ones, with Retry and Delete. | +| [cometchat-message-composer](/ui-kit/angular/components/cometchat-message-composer) | Queues text messages sent while offline. | +| [cometchat-search](/ui-kit/angular/components/cometchat-search) | Shows **Connect to search** for a keyword search that cannot run offline. | + +See the [Offline Support guide](/ui-kit/angular/offline-support). + --- ## Next Steps diff --git a/ui-kit/angular/customization/date-time-formatting.mdx b/ui-kit/angular/customization/date-time-formatting.mdx index afd1b72b0..5482bf2b3 100644 --- a/ui-kit/angular/customization/date-time-formatting.mdx +++ b/ui-kit/angular/customization/date-time-formatting.mdx @@ -201,7 +201,7 @@ const tz = CometChatLocalize.getTimezone(); -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable import { Component, OnInit, signal } from '@angular/core'; diff --git a/ui-kit/angular/customization/localization.mdx b/ui-kit/angular/customization/localization.mdx index ee81e9301..27a3a0a68 100644 --- a/ui-kit/angular/customization/localization.mdx +++ b/ui-kit/angular/customization/localization.mdx @@ -65,6 +65,8 @@ CometChatLocalize.addTranslation({ Existing keys are replaced; new keys are added. All other translations remain unchanged. +The texts of the offline states (**Connect to load chats**, **Not sent yet**, and so on) are keys like any other. See [Offline States and Texts](/ui-kit/angular/offline-support#offline-states-and-texts) for the list. + --- ## Using the Translate Pipe diff --git a/ui-kit/angular/customization/migration-guide.mdx b/ui-kit/angular/customization/migration-guide.mdx index 9dd66af92..17b5a3e64 100644 --- a/ui-kit/angular/customization/migration-guide.mdx +++ b/ui-kit/angular/customization/migration-guide.mdx @@ -106,7 +106,7 @@ To ensure consistency and scalability, the new theming system adheres to the **B } ``` -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript app.ts import { Component, OnInit, signal } from '@angular/core'; @@ -121,7 +121,7 @@ import { Component, OnInit, signal } from '@angular/core'; ` }) export class App implements OnInit { - // A signal, so the template refreshes from the media-query listener on zoneless Angular 21 + // A signal, so the template refreshes from the media-query listener on zoneless Angular 21+ theme = signal<'light' | 'dark'>('light'); ngOnInit(): void { diff --git a/ui-kit/angular/events.mdx b/ui-kit/angular/events.mdx index eb8163113..4b27a76da 100644 --- a/ui-kit/angular/events.mdx +++ b/ui-kit/angular/events.mdx @@ -40,6 +40,8 @@ Events provide decoupled communication between UIKit components using a publish/ | **ccGroupMemberAdded** | Triggered when a user is added to the group. | | **ccOwnershipChanged** | Triggered when the group ownership is assigned to another group member. | +With [offline support](/ui-kit/angular/offline-support) on, `ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberScopeChanged` and `ccGroupLeft` also fire for group actions that happened while the user was away, when they arrive in the SDK's catch-up. Check `kickedBy` or `message.getActionBy()` before you treat one as the signed-in user's own action. + ## CometChatMessageEvents `CometChatMessageEvents` emits events when the logged-in user acts on a message object. This category includes both UIKit-level events and CometChat SDK listener events. @@ -53,6 +55,8 @@ Events provide decoupled communication between UIKit components using a publish/ | **ccReplyToMessage** | Triggered when the user successfully replies to a message. | | **ccMessageDeleted** | Triggered when the user successfully deletes a message. | | **ccMessageRead** | Triggered when the sent message is read by the receiver. | +| **ccMessageSendStateChanged** | Offline support only. Fires once per send-state change of an own message, with `IMessageSendStateChanged`: `{ message, state, reason? }`, where `state` is `'sending'`, `'sent'`, `'failed'` or `'discarded'`. Never fires while offline support is off. See [Offline Support](/ui-kit/angular/offline-support#events). | +| **ccOfflineCacheReset** | Offline support only. Fires when the SDK rebuilt its offline cache, with `IOfflineCacheReset`: `{ reason, pendingMessagesLost }` (`null` when the SDK cannot know). The lists reload. See [Offline Support](/ui-kit/angular/offline-support#events). | | **ccCardActionClicked** | Triggered when a user taps an interactive element on a card (developer card or nested agent card). Carries an `ICardActionEvent` with the owning `message` (or `null` for a streaming card), the raw renderer `action`, and the originating `elementId`/`cardJson`. The UIKit forwards the action untouched and runs no behavior. See the [Card Messages guide](/ui-kit/angular/guides/card-messages#handling-card-actions). | ### SDK Listener Events diff --git a/ui-kit/angular/guides/custom-message-types.mdx b/ui-kit/angular/guides/custom-message-types.mdx index aee824546..cb418a7c2 100644 --- a/ui-kit/angular/guides/custom-message-types.mdx +++ b/ui-kit/angular/guides/custom-message-types.mdx @@ -106,7 +106,7 @@ Use `ConversationSubtitleService` to control the last message text shown in the ### Register a Subtitle Formatter -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name instead. ```typescript expandable import { inject } from '@angular/core'; diff --git a/ui-kit/angular/integration.mdx b/ui-kit/angular/integration.mdx index dc9fc019d..67fa48b10 100644 --- a/ui-kit/angular/integration.mdx +++ b/ui-kit/angular/integration.mdx @@ -9,8 +9,8 @@ description: "Add CometChat to an Angular app in 6 steps: create project, instal | Field | Value | | --- | --- | | Package | `@cometchat/chat-uikit-angular` v5 | -| Angular | 17–21 (`@angular/core` / `@angular/common` `>=17.0.0 <22.0.0`). Angular 22 is not supported yet — scaffold with `npx @angular/cli@21 new` | -| Peer deps | `@cometchat/chat-sdk-javascript` ^4.2.0, `@cometchat/cards-angular` ^1.0.0, `dompurify` ^3.0.0; optional `@cometchat/calls-sdk-javascript` ^5.0.3 (calling only) | +| Angular | 18–22 (`@angular/core` / `@angular/common` `>=18.0.0 <23.0.0`, UI Kit 5.3.0 and later). UI Kit 5.2.x supports up to Angular 21 | +| Peer deps | `@cometchat/chat-sdk-javascript` ^4.2.0, `@cometchat/cards-angular` ^1.0.0, `dompurify` ^3.4.17; optional `@cometchat/calls-sdk-javascript` ^5.0.3 (calling only) | | Init | `CometChatUIKit.init(UIKitSettings)` — must resolve before `login()` | | Login | `CometChatUIKit.login("UID")` — must resolve before rendering components | | Order | `init()` → `login()` → render. Breaking this order = blank screen | @@ -35,8 +35,8 @@ You need three things from the [CometChat Dashboard](https://app.cometchat.com/) | Region | Dashboard → Your App → Credentials (e.g. `us`, `eu`, `in`) | You also need: -- Node.js 20.19+, 22.12+ or 24+ (what Angular 21 requires) and npm installed -- Angular 17–21. The UI Kit declares `@angular/core` `>=17.0.0 <22.0.0`, so Angular 22 — what an unversioned `ng new` / `@angular/cli@latest` now creates — fails `npm install` with `ERESOLVE` +- The Node.js version your Angular major requires (Angular 22: 22.22.3+, 24.15+ or 26+; Angular 21: 20.19+, 22.12+ or 24+) and npm installed +- Angular 18–22. UI Kit 5.3.0 and later declare `@angular/core` `>=18.0.0 <23.0.0`. UI Kit 5.2.x declares `<22.0.0`, so with 5.2.x an Angular 22 app fails `npm install` with `ERESOLVE` Auth Key is for development only. In production, generate Auth Tokens server-side via the [REST API](/rest-api/chat-apis) and use `loginWithAuthToken()`. Never ship Auth Keys in client code. @@ -47,11 +47,11 @@ Auth Key is for development only. In production, generate Auth Tokens server-sid ## Step 1 — Create an Angular Project ```bash -npx @angular/cli@21 new my-app --style css --ssr false +npx @angular/cli@22 new my-app --style css --ssr false cd my-app ``` -This creates a new Angular 21 project with CSS styling and no server-side rendering. CometChat UIKit components require a browser environment. Pin the CLI major (`@21`) — the latest CLI scaffolds Angular 22, which the UI Kit does not support yet. For an existing app, check the major with `npx ng version`. +This creates a new Angular 22 project with CSS styling and no server-side rendering. CometChat UIKit components require a browser environment. Pin the CLI major (`@22`), so a future CLI doesn't scaffold an Angular major the UI Kit doesn't support yet. For an existing app, check the major with `npx ng version`. --- @@ -110,6 +110,7 @@ const UIKitSettings = new UIKitSettingsBuilder() .setAuthKey(environment.cometchat.authKey) .subscribePresenceForAllUsers() // .setCallingEnabled(true) // uncomment to enable voice/video calling + // .setOfflineConfig({ enabled: true }) // uncomment for offline support (UI Kit 5.3.0+, Chat SDK 4.3.0+) .build(); // init() is typed Promise | undefined (it returns undefined only for null settings), hence ?. @@ -129,6 +130,10 @@ CometChatUIKit.init(UIKitSettings) `init()` must resolve before you call `login()`. If you call `login()` before init completes, it will fail silently. + +Offline support is off by default. To show cached chats without a network and queue messages sent offline, add `.setOfflineConfig({ enabled: true })` to the builder. It needs UI Kit 5.3.0 or later and Chat SDK 4.3.0 or later. See [Offline Support](/ui-kit/angular/offline-support). + + --- ## Step 4 — Login @@ -141,7 +146,7 @@ After init resolves, log the user in. For development, use one of the pre-create Add the login logic to your root component — replace the contents of `src/app/app.ts`. The component below uses an inline template, so the generated `app.html` and `app.css` are no longer used; you can delete them. Use `CometChatUIKit.getLoggedinUser()` to check for an existing session before calling `login()`. -Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 17–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name here and in `main.ts` instead. +Angular 20+ names the root component `App` in `src/app/app.ts`, as below. A project created with Angular 18–19 uses `AppComponent` in `src/app/app.component.ts` — use that file and class name here and in `main.ts` instead. ```ts title="src/app/app.ts" expandable @@ -164,7 +169,7 @@ import { CometChat } from "@cometchat/chat-sdk-javascript"; `, }) export class App implements OnInit { - // A signal, not a plain boolean: Angular 21 apps are zoneless by default, so a + // A signal, not a plain boolean: Angular 21 and later apps are zoneless by default, so a // plain field changed inside a promise callback never re-renders the view. isLoggedIn = signal(false); @@ -192,7 +197,7 @@ Key points: - `getLoggedinUser()` checks for an existing session so you don't re-login unnecessarily. - `login(uid)` skips the API call if a session already exists and returns the cached user. - Components must not render until login resolves — gate rendering with `@if` on a signal. -- Keep state that changes in a promise or subscription callback in a `signal()`. New Angular 21 projects are zoneless (no `zone.js`), so assigning a plain field there (`this.isLoggedIn = true`) doesn't refresh the view — the app stays on "Loading..." and dev mode can throw `NG0100: ExpressionChangedAfterItHasBeenChecked`. Signals work the same with and without `zone.js`, so this code also runs on Angular 17–20. +- Keep state that changes in a promise or subscription callback in a `signal()`. New Angular 21+ projects are zoneless (no `zone.js`), so assigning a plain field there (`this.isLoggedIn = true`) doesn't refresh the view — the app stays on "Loading..." and dev mode can throw `NG0100: ExpressionChangedAfterItHasBeenChecked`. Signals work the same with and without `zone.js`, so this code also runs on Angular 17–20. For production, use `loginWithAuthToken()` instead of Auth Key. Generate tokens server-side via the REST API. @@ -272,7 +277,7 @@ The UIKit ships icons, images, and audio files that Angular's build system won't } ``` -Keep the entries the CLI generated (`public` on Angular 18+; `src/favicon.ico` and `src/assets` on Angular 17) — replacing the array instead of appending to it stops your own static files from being served. +Keep the entries the CLI generated (such as `public`) — replacing the array instead of appending to it stops your own static files from being served. Skipping this step will cause all UIKit icons, empty-state images, and notification sounds to fail with 404 errors. diff --git a/ui-kit/angular/llms-angular-v5.mdx b/ui-kit/angular/llms-angular-v5.mdx index 4be4c090f..11422b874 100644 --- a/ui-kit/angular/llms-angular-v5.mdx +++ b/ui-kit/angular/llms-angular-v5.mdx @@ -48,6 +48,7 @@ exhaustive inputs, long-tail components, theming tokens, or feature enablement. ## Core & configuration - [Core Features](/ui-kit/angular/core-features) +- [Offline Support](/ui-kit/angular/offline-support) - [Methods](/ui-kit/angular/methods) - [Events](/ui-kit/angular/events) - [Sound Manager](/ui-kit/angular/sound-manager) diff --git a/ui-kit/angular/methods.mdx b/ui-kit/angular/methods.mdx index e2d0acec9..09e461d40 100644 --- a/ui-kit/angular/methods.mdx +++ b/ui-kit/angular/methods.mdx @@ -30,6 +30,7 @@ Auth Key is for development/testing only. In production, generate Auth Tokens on | `setAdminHost(adminHost)` | `string` | Override the admin API host (custom/on-premise deployments) | | `setClientHost(clientHost)` | `string` | Override the client API host (custom/on-premise deployments) | | `setStorageMode(storageMode)` | `CometChat.StorageMode` | Set the storage mode for SDK data persistence | +| `setOfflineConfig(config)` | `CometChatOfflineConfig` | Turn on offline support: cached chats and messages, and queued sends. Off unless `config.enabled` is `true`. Needs UI Kit 5.3.0+ and Chat SDK 4.3.0+. See [Offline Support](#offline-support) | | `build()` | — | Returns the configured `UIKitSettings` instance | ```typescript expandable @@ -44,6 +45,24 @@ const UIKitSettings = new UIKitSettingsBuilder() .build(); ``` +### Offline Support + +`setOfflineConfig()` turns on the Chat SDK's offline support and the UI Kit's offline states. It is **off by default**, and stays off unless the config has `enabled: true`. The UI Kit passes the object to the Chat SDK's `AppSettingsBuilder.setOfflineConfig()` unchanged. It needs UI Kit 5.3.0 or later and Chat SDK 4.3.0 or later; with an older SDK the setting is ignored and the UI Kit works online only. + +```typescript +import { UIKitSettingsBuilder } from '@cometchat/chat-uikit-angular'; + +const UIKitSettings = new UIKitSettingsBuilder() + .setAppId('APP_ID') + .setRegion('REGION') + .setAuthKey('AUTH_KEY') + .subscribePresenceForFriends() + .setOfflineConfig({ enabled: true }) + .build(); +``` + +The config is typed as `CometChatOfflineConfig`, which lists the SDK's offline options (for example `maxPendingMessages`, `mediaCaching` and `encryption`). See [Offline Support](/ui-kit/angular/offline-support) for what changes in the components, and [OfflineConfig options](/sdk/javascript/offline-reference#offlineconfig-options) for every option and its default. + --- ## Methods @@ -159,6 +178,8 @@ import { CometChatUIKit } from '@cometchat/chat-uikit-angular'; CometChatUIKit.logout(); ``` +With [offline support](/ui-kit/angular/offline-support) on, logging out deletes the user's offline cache on this device, including messages that were not sent yet. Open `sendTextMessage()` and `sendCustomMessage()` promises for those messages reject with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. Logging in as a different user does the same for the previous user's cache. + --- ### Create User diff --git a/ui-kit/angular/offline-support.mdx b/ui-kit/angular/offline-support.mdx new file mode 100644 index 000000000..dc0744f11 --- /dev/null +++ b/ui-kit/angular/offline-support.mdx @@ -0,0 +1,481 @@ +--- +title: "Offline Support" +sidebarTitle: "Offline Support" +description: "Show cached chats and messages without a network and queue messages to send on reconnect with the CometChat Angular UI Kit." +--- + + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-uikit-angular` 5.3.0 or later | +| Chat SDK | `@cometchat/chat-sdk-javascript` 4.3.0 or later | +| Default | Off. Nothing changes until you turn it on | +| Enable | `new UIKitSettingsBuilder().setOfflineConfig({ enabled: true })` before `CometChatUIKit.init(UIKitSettings)` | +| Config type | `CometChatOfflineConfig`. Passed to the Chat SDK unchanged. Options: [OfflineConfig options](/sdk/javascript/offline-reference#offlineconfig-options) | +| Runtime check | `CometChat.isOfflineEnabled()`. The UI Kit reads it every time, not your config | +| Inputs | `hideOfflineNotices` on `cometchat-message-list` and `cometchat-conversations` | +| Events | `CometChatMessageEvents.ccMessageSendStateChanged`, `CometChatMessageEvents.ccOfflineCacheReset` | +| Service signals | `connectToSearch`, `searchFailed`, `reconnectSearchError$` on `SearchConversationsService` and `SearchMessagesService` | +| Component method | `CometChatMessageListComponent.retryOfflineRead()` | +| Option ids | `CometChatUIKitConstants.MessageOption.retryMessage`, `CometChatUIKitConstants.MessageOption.discardMessage` | +| Quiet rejection | `CometChatUIKit.sendTextMessage()` / `sendCustomMessage()` for a queued message rejects with code `ERROR_OFFLINE_MESSAGE_DISCARDED` on logout or cache reset | + + + +## Overview + +With offline support on, the UI Kit keeps working when the network drops. The [JavaScript Chat SDK](/sdk/javascript/offline-overview) keeps a cache on the device and an outbox of unsent messages. The UI Kit components read from that cache first, show each message's send state, and catch up when the connection returns. + +**Works offline:** + +- Conversations, users, groups, group members, messages, threads, reactions, the notification feed, and pinned and saved messages that the user has already loaded appear at once from the device. +- Text messages can be sent. They are queued and go out by themselves when the connection returns. +- Unsent messages can be retried or deleted. +- Media the SDK has saved on the device plays and opens from the device. + +**Needs a connection:** + +- The first load of anything the user has never opened while online. +- A keyword search with no saved match. +- Editing, deleting, reacting to, pinning or saving a sent message. These are not queued. +- Message information, calls, and AI agent streamed replies. + +## Requirements + +| Requirement | Version | +| --- | --- | +| Angular UI Kit | `@cometchat/chat-uikit-angular` **5.3.0** or later (v5 only) | +| Chat SDK | `@cometchat/chat-sdk-javascript` **4.3.0** or later | + +The UI Kit's peer dependency on the Chat SDK stays `^4.2.0`, so upgrading the UI Kit does not force an SDK upgrade. With SDK 4.2.x, `setOfflineConfig()` is ignored and the UI Kit works online only. Install SDK 4.3.0 or later to use offline support: + +```bash +npm install @cometchat/chat-uikit-angular@^5.3.0 @cometchat/chat-sdk-javascript@^4.3.0 +``` + +The browser needs IndexedDB for the cache. Where it is missing or blocked (for example, in some private-browsing modes), offline support stays off for that session. See [Supported runtimes](/sdk/javascript/offline-enable#supported-runtimes). + + +UI Kit v4 has no offline support. Turning on the SDK's offline support under UI Kit v4 is not supported. + + +## Enable Offline Support + +Offline support is **off by default**. Call `setOfflineConfig()` on the `UIKitSettingsBuilder` with `enabled: true`, before `CometChatUIKit.init()`. The UI Kit passes the object to the Chat SDK's `AppSettingsBuilder.setOfflineConfig()` unchanged. + +```ts title="src/main.ts" expandable +import { bootstrapApplication } from "@angular/platform-browser"; +import { App } from "./app/app"; +import { appConfig } from "./app/app.config"; +import { CometChatUIKit, UIKitSettingsBuilder } from "@cometchat/chat-uikit-angular"; + +const UIKitSettings = new UIKitSettingsBuilder() + .setAppId("APP_ID") + .setRegion("REGION") + .setAuthKey("AUTH_KEY") + .subscribePresenceForAllUsers() + .setOfflineConfig({ + enabled: true, + // Any other OfflineConfig option, for example: + // encryption: true, + // maxPendingMessages: 50, + }) + .build(); + +CometChatUIKit.init(UIKitSettings) + ?.then(() => { + bootstrapApplication(App, appConfig).catch((err) => console.error(err)); + }) + .catch((error) => { + console.error("CometChat UI Kit initialization failed:", error); + }); +``` + +The config is typed as `CometChatOfflineConfig`. It lists exactly the SDK's options, so a misspelled key such as `enable` is a compile error. For what each option does and its default, see [OfflineConfig options](/sdk/javascript/offline-reference#offlineconfig-options). For encryption and media caching, see [Encrypt the Cache](/sdk/javascript/offline-encryption) and [Media Caching](/sdk/javascript/offline-media-caching). + + +Offline support turns on only with an explicit `enabled: true`. A config without `enabled` leaves it off. + + +Whether offline support is running can change after init: it is off before anyone logs in, and the SDK can turn it off, for example when the encrypted cache cannot open. The components check `CometChat.isOfflineEnabled()` each time they need to. Do the same in your own code instead of reading back the config you passed. See [Verify it is active](/sdk/javascript/offline-enable). + +## How the Components Behave Offline + +### Lists + +This applies to [Conversations](/ui-kit/angular/components/cometchat-conversations), [Users](/ui-kit/angular/components/cometchat-users), [Groups](/ui-kit/angular/components/cometchat-groups), [Group Members](/ui-kit/angular/components/cometchat-group-members), [Reaction List](/ui-kit/angular/components/cometchat-reaction-list), [Notification Feed](/ui-kit/angular/components/notification-feed), [Pinned Messages](/ui-kit/angular/components/cometchat-pinned-messages) and [Saved Messages](/ui-kit/angular/components/cometchat-saved-messages). + +- **Saved rows first.** The list paints the rows saved on the device straight away, then merges in the server page when it arrives. +- **Offline with nothing saved.** The list shows its offline state: an icon and **Connect to load chats** (or users, groups, members, reactions, notifications, messages), with no Retry button. It loads once by itself when the connection is back. +- **Rows on screen stay.** If a load fails while rows are showing, the rows stay and nothing is drawn over them. +- **Reaction counts.** Offline with no reactions loaded, the Reaction List shows **Connect to load reactions** and keeps its tabs, with the counts the message already carries. +- **Reconnect.** The SDK catches every list up. The components make no refresh fetch of their own, apart from the one-time reads above, and messages that arrived meanwhile appear without a sound and without extra unread counts. + +### Search + +- **Keyword search.** A search with a keyword that cannot reach the server, and has no saved match, shows **Connect to search** with a second line, **Search needs an internet connection.** It runs again once by itself when the connection is back. +- **Filters only.** A list opened with a filter and no keyword (online users, tags, a request builder with no search term) is a plain list, not a search. Offline with nothing saved, it shows that list's **Connect to load …** text. +- **The [Search](/ui-kit/angular/components/cometchat-search) component** searches conversations and messages together: + - It shows **Connect to search** only when every failed request was a not-connected one. + - A search by filters alone is answered from the device. When nothing is saved, it shows the plain empty state (**No Results**), not **Connect to search**. + - It waits for both scopes before it treats a failure as an error. See [Errors and Callbacks](#errors-and-callbacks). + +### Message List and Threads + +[Message List](/ui-kit/angular/components/cometchat-message-list) behaves as follows: + +- **Cached history.** A chat opens with the messages saved on the device, then updates with the server page. A chat opened offline with nothing saved shows **Connect to load messages**. +- **Connect to load more.** Offline, scrolling past the saved messages shows a tappable **Connect to load more** row at that edge: at the top for older messages, at the bottom for newer ones. The list never ends there. When the connection is back, the page behind the row loads once by itself, older edge first. Tapping the row or scrolling to that end also loads it. +- **Jump to a message.** A saved target opens with the saved messages around it. + - When the chat opens on a target (`goToMessageId`, or the unread anchor) that is neither saved nor reachable offline, it opens on its newest saved page as a normal offline open, with no error. + - From messages already on screen (a quoted reply, a search result), the messages on screen stay until the target is found. If it cannot be read offline, nothing changes and nothing is reported. + - If the target cannot be read for another reason, for example it was deleted, `(error)` fires once. The messages on screen stay, or an opening chat shows its newest page; with nothing to show, the error view shows. +- **Start from unread.** With `startFromUnreadMessages`, the chat opens on its newest page from the device, then moves to the unread divider. +- **Threads.** A thread view shows the same offline states as the main list. See [Limitations](#limitations) for what is saved for threads. + + +The message list's default request lets the SDK save each page for offline use. If you pass your own `messagesRequestBuilder` with extra filters, the request is sent exactly as you built it. The SDK may then not save its pages, so that chat has less to show offline. See [Cache-supported filters](/sdk/javascript/offline-reference#cache-supported-filters). + + +### Composer and Sending + +[Message Composer](/ui-kit/angular/components/cometchat-message-composer) and Message List handle sends as follows: + +- **Queued sends.** A message sent offline appears at once with a clock icon and **Not sent yet**. It is queued, not failed, and sends by itself when the connection returns. +- **Failed sends.** A message the server refuses shows the error mark and **Not sent. Tap to retry**, whatever the reason. A failed message stays failed until the user taps it or chooses **Retry**. +- **Retry and Delete.** Every own message that is waiting, sending, or failed offers only **Retry** and **Delete** in its menu. Reply, thread, react, edit, pin, save, info and copy all need a sent message, so they are hidden until it is sent. + - **Delete** shows the usual confirmation, then removes the message from this device for good, offline too, and it stays removed after a restart. + - Retry or Delete on a message whose send is already under way changes nothing, and a short **Sending… try again in a moment** notice shows. + - If the SDK no longer holds an unsent message (for example, its chat was removed from the cache), Retry or Delete removes it from the screen. +- **Queue limits.** When the outbox is full (`maxPendingMessages`), the message shows as not sent with the notice **Too many messages waiting to send**. Retry sends it once there is room. +- **Editing.** An edit is sent straight to the server and is never queued. When it fails, for example offline, the composer has already left edit mode and cleared, and the error goes to the composer's `(error)` output. + +For how the SDK queues sends, see [Send While Offline](/sdk/javascript/offline-send). + +### Media + +- Images, videos, audio, voice notes and files the SDK has saved open and play from the device when offline. By default the SDK saves incoming media as it arrives; with `mediaCaching` set to `OFF` it saves none and the UI Kit loads media from its URL. See [Media Caching](/sdk/javascript/offline-media-caching). +- An image, video, audio file or file with no saved copy shows **Available when online** while offline. +- Online, tapping an image, video or file the device has no copy of downloads and caches it. Playing an audio file does the same; the audio plays from its URL and uses the saved copy next time. + +### Edits, Deletes and Reactions + +Editing, deleting, reacting to, pinning and saving a **sent** message need a connection. They are not queued: offline, each one fails with the SDK's not-connected error. Edits, deletes and reactions made on other devices sync in when the connection returns. + +### Presence + +Nobody shows as online while the connection is down, in any list or header, and screen readers do not announce anyone as online. Presence comes back with the connection. + +### Logout and Switching Users + +The cache belongs to one user. Logging out, a session expiring, or logging in as a different user deletes the cache, including any unsent messages. You don't clear anything yourself. See [One cache per user](/sdk/javascript/offline-overview#one-cache-per-user). + +## Offline States and Texts + +These are the texts the components show in their offline states. Each one is a localization key, so you can change the text with `CometChatLocalize.addTranslation()`, as for any other string. See [Localization](/ui-kit/angular/customization/localization). + +| Text | Where it appears | Key | +| --- | --- | --- | +| Connect to load chats | Conversations | `conversations_connect_to_load` | +| Connect to load users | Users | `users_connect_to_load` | +| Connect to load groups | Groups | `groups_connect_to_load` | +| Connect to load members | Group Members | `group_members_connect_to_load` | +| Connect to load messages | Message List, threads, Pinned Messages, Saved Messages | `message_list_connect_to_load` | +| Connect to load reactions | Reaction List | `reaction_list_connect_to_load` | +| Connect to load notifications | Notification Feed | `notification_feed_connect_to_load` | +| Connect to search | Searchable lists | `conversations_connect_to_search` | +| Connect to search | Search component | `search_connect_to_search_messages` | +| Search needs an internet connection. | Second line under **Connect to search** | `list_connect_to_search_subtitle` | +| Connect to load more | Message List edge row | `message_list_connect_to_load_more` | +| Not sent yet | Unsent own message | `message_list_not_sent_yet` | +| Not sent. Tap to retry | Failed own message | `message_list_not_sent_tap_to_retry` | +| Sending… try again in a moment | Retry or Delete during a send | `message_list_send_in_flight` | +| Too many messages waiting to send | Outbox full | `message_list_queue_full` | +| Available when online | Image, video, audio or file with no saved copy | `message_bubble_media_available_when_online` | +| 1 unsent message was removed | Message List notice | `message_list_unsent_message_removed` | +| `{{count}}` message wasn't sent | Message List notice | `message_list_messages_not_sent_one`, `message_list_messages_not_sent_other` | +| `{{count}}` unsent message couldn't be recovered | Cache reset notice | `message_list_unsent_messages_lost_one`, `message_list_unsent_messages_lost_other` | +| Some unsent messages may not have been sent | Cache reset notice | `message_list_unsent_messages_maybe_lost` | + +The counted notices use plural keys: `_one` and `_other`, plus `_few` and `_many` in languages that need them. The UI Kit picks the form for the current language and falls back to `_other`, replacing `{{count}}` with the number. + +```typescript +import { CometChatLocalize } from "@cometchat/chat-uikit-angular"; + +CometChatLocalize.addTranslation({ + "en-US": { + "conversations_connect_to_load": "You're offline. Reconnect to see your chats.", + "message_list_connect_to_load_more": "Reconnect to load more", + }, +}); +``` + +## Errors and Callbacks + +### The error output + +The list components' `(error)` output follows one rule while offline support is on: + +| Situation | What shows | `(error)` | +| --- | --- | --- | +| Offline, nothing on screen | The offline state (**Connect to load …**), or your `errorView` if you passed one | Fires once | +| Keyword search offline, no saved match | **Connect to search** | Does not fire | +| Online, a real error, nothing on screen | The error view with Retry, or your `errorView`. Not reloaded by itself | Fires once | +| Rows on screen, offline | Rows stay | Does not fire | +| Rows on screen, online, a load the user or app started (opening, refresh, search, filter, paging, jump to a message, Retry) | Rows stay | Fires once | +| Rows on screen, online, a load the UI Kit started (reconnect, sync, cache reset) | Rows stay | Does not fire | +| The server answers with an empty list | The empty view, or your `emptyView` | Does not fire | + +The Search component reports through its `(searchError)` output instead. With both scopes: + +- If both scopes fail, at least one for a real reason, the error view shows and `(searchError)` fires once for each scope that failed for a real reason. +- If one scope fails and the other has results, the results stay and `(searchError)` fires once for the failed scope if it failed for a real reason. +- If one scope fails and nothing is shown, the plain empty state (**No Results**, or your own empty view) shows, with no `(searchError)` and no run on reconnect. + +### Send promises + +`CometChatUIKit.sendTextMessage()` and `sendCustomMessage()` behave as follows when offline support is on: + +- They resolve when the message is sent. +- They reject on a final failure. +- They never reject only because the message was queued. +- When the user logs out or switches user before a queued message is sent, or the offline cache resets and loses unsent messages, the promise rejects once, quietly, with the code `ERROR_OFFLINE_MESSAGE_DISCARDED`. The components show no error for it. Treat it as "dropped", not as a failure to report. + +```typescript +import { CometChat } from "@cometchat/chat-sdk-javascript"; +import { CometChatUIKit } from "@cometchat/chat-uikit-angular"; + +const message = new CometChat.TextMessage("UID", "Hello", CometChat.RECEIVER_TYPE.USER); + +CometChatUIKit.sendTextMessage(message) + .then((sent) => console.log("Sent", sent)) + .catch((error) => { + if (error?.code === "ERROR_OFFLINE_MESSAGE_DISCARDED") return; // logout or cache reset + console.error("Send failed", error); + }); +``` + +See [Error codes](/sdk/javascript/offline-reference#error-codes) for the other offline codes. + +### Events + +Two events on `CometChatMessageEvents` fire only while offline support is on: + +| Event | Payload | When | +| --- | --- | --- | +| `ccMessageSendStateChanged` | `IMessageSendStateChanged`: `{ message, state, reason? }`, where `state` is `MessageSendState`: `'sending'`, `'sent'`, `'failed'` or `'discarded'`. `reason` is the SDK's failure reason for `failed` and `discarded` | Once per send-state change of an own message | +| `ccOfflineCacheReset` | `IOfflineCacheReset`: `{ reason, pendingMessagesLost }`, where `pendingMessagesLost` is `null` when the SDK cannot know | The SDK rebuilt its offline cache. The lists reload | + +```typescript +import { Component, DestroyRef, OnInit, inject } from "@angular/core"; +import { takeUntilDestroyed } from "@angular/core/rxjs-interop"; +import { + CometChatMessageEvents, + IMessageSendStateChanged, + IOfflineCacheReset, +} from "@cometchat/chat-uikit-angular"; + +@Component({ selector: "app-offline-log", standalone: true, template: "" }) +export class OfflineLogComponent implements OnInit { + private destroyRef = inject(DestroyRef); + + ngOnInit(): void { + CometChatMessageEvents.ccMessageSendStateChanged + .pipe(takeUntilDestroyed(this.destroyRef)) + .subscribe(({ message, state, reason }: IMessageSendStateChanged) => { + console.log("Send state", message.getMuid(), state, reason); + }); + + CometChatMessageEvents.ccOfflineCacheReset + .pipe(takeUntilDestroyed(this.destroyRef)) + .subscribe(({ reason, pendingMessagesLost }: IOfflineCacheReset) => { + console.log("Cache reset", reason, pendingMessagesLost); + }); + } +} +``` + +`ccMessageSent` keeps its contract: one `inprogress`, then one `success` or `error` per message. A queued message stays `inprogress` until it is sent. + + +**Group events can come from catch-up.** With offline support on, group actions that happened while the user was away (a kick, a ban, a scope change, or the user leaving from another device) arrive in the SDK's catch-up. The UI Kit then also emits `CometChatGroupEvents.ccGroupMemberKicked`, `ccGroupMemberBanned`, `ccGroupMemberScopeChanged` and `ccGroupLeft`, with the same payload as before. These events no longer always mean "this user just did it". Check `kickedBy` or `message.getActionBy()` before you show a toast for the user's own action, and handle the case where the kicked user is the signed-in user, for example by closing the chat. + + +### Search service signals + +[`SearchConversationsService`](/ui-kit/angular/api-reference/search-conversations-service) and [`SearchMessagesService`](/ui-kit/angular/api-reference/search-messages-service) expose offline state as signals. Both are always `false` while offline support is off. + +| Member | Type | Meaning | +| --- | --- | --- | +| `connectToSearch` | `WritableSignal` | `true` when a keyword search could not reach the server and nothing saved matches. `fetchState` is `empty`, `search()` does not reject, and the search runs once more by itself when the connection is back. | +| `searchFailed` | `WritableSignal` | `true` when a search inside the Search component failed with a real error and nothing is shown. `fetchState` is `empty` and the Search component decides, once both scopes answer, whether to show the error view or the empty state. Always `false` when you use the service outside the Search component. | +| `reconnectSearchError$` | `Subject` | Emits when the search the service re-ran by itself on reconnect fails. A search you start rejects to you instead. | + +```typescript +import { Component, computed, inject } from "@angular/core"; +import { SearchConversationsService } from "@cometchat/chat-uikit-angular"; + +@Component({ + selector: "app-conversation-search", + standalone: true, + providers: [SearchConversationsService], + template: ` + + @if (offlineMiss()) { +

Connect to search

+ } + `, +}) +export class ConversationSearchComponent { + private search = inject(SearchConversationsService); + offlineMiss = computed(() => this.search.connectToSearch()); + + run(keyword: string): void { + this.search.search(keyword, []).catch((error) => console.error(error)); + } +} +``` + +## Customization + +### Hide the offline notices + +`cometchat-message-list` and `cometchat-conversations` take a `hideOfflineNotices` input (default `false`): + +| Component | Notices it hides | +| --- | --- | +| `cometchat-message-list` | All of its offline notices, including a message removed, messages not sent, the outbox full, **Sending… try again in a moment**, and a cache reset (the message list shows cache reset notices only when no `cometchat-conversations` is on screen) | +| `cometchat-conversations` | The notice shown when the offline cache was reset and unsent messages were, or may have been, lost | + +```html + + +``` + +The input has no effect while offline support is off. + +### Your own empty and error views + +Your own views win over the built-in offline states: + +- An `errorView` you pass to a list shows instead of **Connect to load …** (on the Notification Feed, `errorStateView`). +- An `emptyView` you pass to Conversations, Users, Groups or Group Members shows instead of **Connect to search**. It also shows when the server answers with an empty list, and in the Search component's plain empty state. +- On Conversations, Users, Groups, Group Members and Message List, `hideError` hides **Connect to load …** along with the error view. + +### Your own "Connect to load more" control + +The built-in **Connect to load more** row calls the message list's public `retryOfflineRead()` method, which reads the page behind the blocked edge. To trigger it from your own control, call it on a `viewChild` reference: + +```typescript +import { Component, viewChild } from "@angular/core"; +import { CometChat } from "@cometchat/chat-sdk-javascript"; +import { CometChatMessageListComponent } from "@cometchat/chat-uikit-angular"; + +@Component({ + selector: "app-chat", + standalone: true, + imports: [CometChatMessageListComponent], + template: ` + + + `, +}) +export class ChatComponent { + user!: CometChat.User; + private list = viewChild.required("list"); + + loadMore(): void { + this.list().retryOfflineRead(); + } +} +``` + +### Message options on unsent messages + +The **Retry** and **Delete** options on an unsent message use the ids `CometChatUIKitConstants.MessageOption.retryMessage` and `CometChatUIKitConstants.MessageOption.discardMessage`. Use them to find these options when you customize the message menu. `hideDeleteMessageOption` also hides **Delete** on unsent messages. + +### Theming + +The offline states use the theme's existing colors and fonts. Override them with these CSS variables: + +| Variable | Default | Used for | +| --- | --- | --- | +| `--cometchat-message-bubble-offline-pending-color` | `var(--cometchat-text-color-secondary)` | **Not sent yet** next to the clock | +| `--cometchat-message-bubble-offline-pending-font` | `var(--cometchat-font-caption1-regular)` | **Not sent yet** | +| `--cometchat-message-bubble-offline-retry-color` | `var(--cometchat-error-color)` | **Not sent. Tap to retry** | +| `--cometchat-message-bubble-offline-retry-font` | `var(--cometchat-font-caption1-regular)` | **Not sent. Tap to retry** | +| `--cometchat-message-bubble-offline-retry-focus-outline-color` | `var(--cometchat-primary-color)` | Keyboard focus ring on **Not sent. Tap to retry** | +| `--cometchat-message-bubble-offline-failed-tint` | `transparent` | Background of a failed unsent message | +| `--cometchat-message-bubble-offline-failed-icon-color` | `var(--cometchat-error-color)` | Failed mark on an unsent message | +| `--cometchat-message-list-offline-footer-color` | `var(--cometchat-primary-color)` | **Connect to load more** | +| `--cometchat-message-list-offline-footer-font` | `var(--cometchat-font-caption1-medium)` | **Connect to load more** | +| `--cometchat-message-list-offline-notice-background` | `var(--cometchat-background-color-02)` | Message list notices | +| `--cometchat-message-list-offline-notice-border` | `1px solid var(--cometchat-border-color-light)` | Message list notices | +| `--cometchat-message-list-offline-notice-color` | `var(--cometchat-text-color-primary)` | Message list notices | +| `--cometchat-message-list-offline-notice-font` | `var(--cometchat-font-caption1-regular)` | Message list notices | +| `--cometchat-conversations-offline-notice-background` | `var(--cometchat-background-color-02)` | Conversation list notice | +| `--cometchat-conversations-offline-notice-border` | `1px solid var(--cometchat-border-color-light)` | Conversation list notice | +| `--cometchat-conversations-offline-notice-color` | `var(--cometchat-text-color-primary)` | Conversation list notice | +| `--cometchat-conversations-offline-notice-font` | `var(--cometchat-font-caption1-regular)` | Conversation list notice | +| `--cometchat-conversations-receipt-error-color` | `var(--cometchat-error-color)` | Failed mark on a conversation's last-message preview | +| `--cometchat-image-bubble-offline-placeholder-color` | `var(--cometchat-text-color-secondary)` | **Available when online** on an image | +| `--cometchat-image-bubble-offline-placeholder-font` | `var(--cometchat-font-caption1-regular)` | **Available when online** on an image | +| `--cometchat-video-bubble-offline-placeholder-color` | `var(--cometchat-text-color-secondary)` | **Available when online** on a video | +| `--cometchat-video-bubble-offline-placeholder-font` | `var(--cometchat-font-caption1-regular)` | **Available when online** on a video | + +```css +.cometchat { + --cometchat-message-list-offline-footer-color: #0b7bff; + --cometchat-message-bubble-offline-failed-tint: rgba(244, 70, 73, 0.06); +} +``` + +See [Theming](/ui-kit/angular/customization/theming) for where to put overrides. + +## With Offline Support Turned Off + +Apps that don't turn offline support on keep today's behavior: no cache, no outbox, no offline states, and neither offline event fires. UI Kit 5.3.0 still includes a few changes that apply with offline support off: + +- **Fixes.** On reconnect, the conversation list keeps the freshly fetched copy of a row. A failed send shows the error mark instead of the clock. The server copy of your own message keeps its quote and thread-subscribed flag. A `messagesRequestBuilder` you pass is no longer changed by the UI Kit. +- **Send error metadata.** When `CometChatUIKit.sendTextMessage()`, `sendMediaMessage()` or `sendCustomMessage()` fails, `metadata.error` is merged into the message's existing metadata instead of replacing it, so your own metadata keys survive. +- **Test identifiers.** Message rows, the message menu, conversation rows, notices, the list footer, the composer input, attachment tray tiles, and the empty and error views carry `data-testid` and `data-cc-*` attributes. They hold no message text and are not read by screen readers, but DOM snapshot tests may change. +- **Bundle size.** Chat SDK 4.3 adds about 0.54 MB to an app's initial bundle, and UI Kit 5.3.0 about 0.12 MB, whether offline support is on or off. +- **Reconnect.** As in 5.2.x, the message list makes no fetch of its own on reconnect. Messages missed during a drop appear when the chat is reopened. + +## Limitations + +- The cache holds only what the user has loaded while online, plus what syncs on reconnect. A user who has never used the app online has nothing to show offline. +- Keyword search, message information, calls and AI agent streamed replies need a connection. +- Chat SDK 4.3.0 does not save a page of thread replies for offline use, so a thread opened online may have little or nothing to show offline. Later SDK versions save thread replies like the rest of the chat. +- After a quick reconnect, missed messages can take up to about 10 seconds to appear. +- After a restart, the reason a message failed may be unknown. It is still offered Retry. +- If a send got no answer while the device was connected, that chat can stall until the next reconnect. +- If a send acknowledgement is lost, the message can be stored twice on the server. +- With the app open in several tabs, rebuilding the cache in one tab can drop another tab's unsent messages. That tab's rows update to match. +- The browser cache encrypts message content but not lookup metadata, and downloaded media is stored unencrypted. See [What is and isn't encrypted](/sdk/javascript/offline-encryption#what-is-and-isnt-encrypted). + +--- + +## Next Steps + + + + How the JavaScript SDK caches, queues and syncs + + + Every OfflineConfig option, listener and error code + + + The outbox, retry, discard and queue limits + + + Catch-up on reconnect and cache resets + + + Inputs, outputs and custom views + + + All UI Kit events, including the offline ones + + diff --git a/ui-kit/angular/overview.mdx b/ui-kit/angular/overview.mdx index aaee7d875..d87dca3fd 100644 --- a/ui-kit/angular/overview.mdx +++ b/ui-kit/angular/overview.mdx @@ -11,7 +11,7 @@ description: "Use CometChat Angular UI Kit to add standalone chat components, vo | Package | `@cometchat/chat-uikit-angular` v5.x | | Peer deps | `@cometchat/chat-sdk-javascript`, `@cometchat/cards-angular`, `dompurify` | | Calling | Optional — `@cometchat/calls-sdk-javascript` | -| Angular | v17, v18, v19, v20, v21 (peer range `>=17 <22`; Angular 22 is not supported yet) | +| Angular | v18, v19, v20, v21, v22 (peer range `>=18 <23` from UI Kit 5.3.0; UI Kit 5.2.x supports up to Angular 21) | | Localization | 19 languages built-in | | Source | [GitHub](https://github.com/cometchat/cometchat-uikit-angular/tree/v5) | | AI Skills | `npx @cometchat/skills add` — [GitHub](https://github.com/cometchat/cometchat-skills) | diff --git a/ui-kit/angular/quickstart.mdx b/ui-kit/angular/quickstart.mdx index 5672e5e18..94b068651 100644 --- a/ui-kit/angular/quickstart.mdx +++ b/ui-kit/angular/quickstart.mdx @@ -6,12 +6,12 @@ Follow these steps to integrate CometChat UIKit into your Angular application. ## Prerequisites -- Node.js 20.19+, 22.12+ or 24+ (what Angular 21 requires) -- Angular 17, 18, 19, 20 or 21 — the UI Kit declares `@angular/core` `>=17.0.0 <22.0.0` +- The Node.js version your Angular major requires (Angular 22: 22.22.3+, 24.15+ or 26+; Angular 21: 20.19+, 22.12+ or 24+) +- Angular 18, 19, 20, 21 or 22 — UI Kit 5.3.0 and later declare `@angular/core` `>=18.0.0 <23.0.0` - A CometChat account with App ID and Auth Key -Angular 22 is not supported yet: installing the UI Kit into an Angular 22 app fails with `ERESOLVE`. The latest Angular CLI scaffolds Angular 22, so create new apps with a pinned CLI: `npx @angular/cli@21 new my-app --style css --ssr false`. +Angular 22 needs UI Kit 5.3.0 or later: UI Kit 5.2.x declares `<22.0.0`, so installing it into an Angular 22 app fails with `ERESOLVE`. Create new apps with a pinned CLI major: `npx @angular/cli@22 new my-app --style css --ssr false`. ## Step 1: Install the Package @@ -85,7 +85,7 @@ The UIKit ships icons, images, and audio files that Angular's build system won't } ``` -Keep the entries the CLI generated (`public` on Angular 18+; `src/favicon.ico` and `src/assets` on Angular 17) — replacing the array instead of appending to it stops your own static files from being served. +Keep the entries the CLI generated (such as `public`) — replacing the array instead of appending to it stops your own static files from being served. Skipping this step will cause all UIKit icons, empty-state images, and notification sounds to fail with 404 errors. @@ -120,6 +120,9 @@ CometChatUIKit.init(uiKitSettings) To enable voice and video calling, install `@cometchat/calls-sdk-javascript` and add `.setCallingEnabled(true)` to the builder. Without this, call buttons are hidden across all components. See [Call Features](/ui-kit/angular/call-features) for details. + + Offline support is off by default. To turn it on, add `.setOfflineConfig({ enabled: true })` to the builder (UI Kit 5.3.0+ and Chat SDK 4.3.0+). See [Offline Support](/ui-kit/angular/offline-support). + ## Step 5: Login a User diff --git a/ui-kit/angular/troubleshooting.mdx b/ui-kit/angular/troubleshooting.mdx index 3f4f03e02..5c7782a10 100644 --- a/ui-kit/angular/troubleshooting.mdx +++ b/ui-kit/angular/troubleshooting.mdx @@ -23,7 +23,7 @@ description: "Common failure modes and fixes for the CometChat Angular UIKit." | Login fails with "UID not found" | UID doesn't exist in your CometChat app | Create the user via Dashboard, SDK, or API first | | Blank screen after login | Component mounted before init/login completes | Use state to conditionally render after login resolves | | Console warns "The 'allowSignalWrites' flag is deprecated" on Angular 19+ | Emitted by the UI Kit's own code; Angular 19 made the flag a no-op | Harmless — it doesn't affect behavior and needs no change in your app | -| Stuck on "Loading..." after login succeeds, or `NG0100: ExpressionChangedAfterItHasBeenChecked` (Angular 21) | New Angular 21 apps are zoneless, so a plain field set in a promise, `await` or subscription callback (`this.isLoggedIn = true`) doesn't re-render | Keep that state in a `signal()` and update it with `.set()`, as in [Integration](/ui-kit/angular/integration) Step 4. Works with and without `zone.js` | +| Stuck on "Loading..." after login succeeds, or `NG0100: ExpressionChangedAfterItHasBeenChecked` (Angular 21+) | New Angular 21+ apps are zoneless, so a plain field set in a promise, `await` or subscription callback (`this.isLoggedIn = true`) doesn't re-render | Keep that state in a `signal()` and update it with `.set()`, as in [Integration](/ui-kit/angular/integration) Step 4. Works with and without `zone.js` | | `getLoggedinUser()` returns null | User not logged in or session expired | Call `login()` or `loginWithAuthToken()` first | | `sendTextMessage()` fails | User not logged in or invalid receiver | Ensure login completes before sending messages | | Auth Key exposed in production | Using Auth Key instead of Auth Token | Switch to [Auth Token](/ui-kit/angular/methods#login-using-auth-token) for production | @@ -779,7 +779,7 @@ import { CometChat } from '@cometchat/chat-sdk-javascript'; template: `` }) export class ChatHeaderComponent implements OnInit { - // A signal so the view updates after the promise resolves (required on zoneless Angular 21) + // A signal so the view updates after the promise resolves (required on zoneless Angular 21+) selectedUser = signal(undefined); ngOnInit(): void { @@ -2200,7 +2200,7 @@ import { CometChat } from '@cometchat/chat-sdk-javascript'; template: `` }) export class ChatComposerComponent implements OnInit { - // A signal so the view updates after the promise resolves (required on zoneless Angular 21) + // A signal so the view updates after the promise resolves (required on zoneless Angular 21+) selectedUser = signal(undefined); ngOnInit(): void {