@ethora/chat-component 26.7.4 → 26.7.6

package/README.md

@@ -53,6 +53,7 @@ The package exports:
 - `useInAppNotifications`
 - `usePushNotifications`
 - `resendMessage`
+- `useRoomMute`
 
 ## Why Ethora
 
@@ -333,7 +334,6 @@ Below is a grouped reference for all `config` options.
 | `customAppToken` | `string` | Custom app token for API initialization. |
 | `xmppSettings` | `{ devServer; host; conference?; xmppPingOnSendEnabled? }` | XMPP connectivity settings. |
 | `initBeforeLoad` | `boolean` | Initialize XMPP before normal chat load flow. |
-| `clearStoreBeforeInit` | `boolean` | Clear local store before initialization. |
 | `newArch` | `boolean` | Defaults to `true`; set `false` to explicitly force legacy/old architecture paths. |
 | `useStoreConsoleEnabled` | `boolean` | Enable verbose internal logging in console. |
 
@@ -343,28 +343,30 @@ Below is a grouped reference for all `config` options.
 | --- | --- | --- |
 | `disableHeader` | `boolean` | Hide chat header. |
 | `disableMedia` | `boolean` | Disable media sending/processing paths. |
+| `attachments` | `{ maxFiles?; maxFileSizeMb?; accept? }` | Composer attachment limits. `maxFiles` defaults to `5` (hard cap `10`, the stanza payload size); `maxFileSizeMb` adds a client-side per-file check (omit for none); `accept` is passed straight to the file picker. Picking several files sends them as **one** message. |
+| `pdfPreview` | `{ enabled?; workerSrc?; maxFileSizeMb? }` | First-page PDF thumbnails inside bubbles and in the composer tray. On by default; `enabled: false` keeps the static document card. pdf.js is code-split and only fetched when a PDF actually shows up. By default it runs on the main thread, which needs no bundler asset wiring: set `workerSrc` to a pdf.js worker URL you host to move parsing off it. `maxFileSizeMb` (default `25`) is the size past which a document is not auto-rendered. |
 | `disableRooms` | `boolean` | Hide/disable room list area. |
 | `disableRoomMenu` | `boolean` | Disable room menu controls. |
-| `disableRoomConfig` | `boolean` | Disable room configuration actions. |
+| `disableRoomMute` | `boolean` | Hide the "Mute/Unmute notifications" toggle from the chat header menu and room profile, even on a backend that supports it. |
+| `disableRoomConfig` | `boolean` | Hide every control that mutates a room's configuration, leaving the chat-details panel read-only: room avatar upload/remove, the "Delete chat" menu entry, the add-members action, and the per-member moderator menu (appoint as admin / remove member). |
 | `disableNewChatButton` | `boolean` | Hide new chat/create room action. |
-| `disableUserCount` | `boolean` | Hide user count in header/UI. |
+| `disableUserCount` | `boolean` | Hide the member-count subtitle in the chat header ("N users", plus the online-users popover attached to it). The 1:1 online/offline line is a presence state, not a count, so it stays. |
 | `disableChatInfo` | `{ disableHeader?; disableDescription?; disableType?; disableMembers?; hideMembers?; disableChatHeaderMenu? }` | Fine-grained chat info panel toggles. |
 | `chatHeaderBurgerMenu` | `boolean` | Toggle burger menu in chat header. |
 | `chatHeaderSettings` | `{ hide?; disableCreate?; disableMenu?; hideSearch? }` | Additional header-level controls. |
 | `chatHeaderAdditional` | `{ enabled: boolean; element: any }` | Inject custom element into header area. |
-| `headerLogo` | `string \| React.ReactElement` | Custom logo in header. |
-| `headerMenu` | `() => void` | Custom menu handler. |
-| `headerChatMenu` | `() => void` | Custom room header menu handler. |
+| `headerLogo` | `string \| React.ReactElement` | Host logo rendered at the left of the chat header, before the back button / burger menu. A plain string is treated as an image URL and rendered as a 32px-tall `<img>` (aspect preserved); any other React element renders as-is. Same string-or-node duality as `fallbackScreens`. |
+| `headerMenu` | `() => void` | Takes over the room-list burger menu. When set, the built-in Profile/Settings/Logout dropdown is not rendered: the same burger button calls your handler instead, so you can open your own account menu or drawer. |
+| `headerChatMenu` | `() => void` | Same for the chat header's room menu (the "more" button carrying Report and Leave). When set, that dropdown is not rendered and the button calls your handler. |
 | `colors` | `{ primary; secondary; icons?; ownMessageBackground?; otherMessageBackground?; inputBackground? }` | Theme colours. `primary` drives icon colours and the sender name. `icons` themes every accent icon/icon-button (attach, mic, active send, new-chat, header, empty-state) — defaults to `primary`, so set a *distinct* value to decouple. `ownMessageBackground`/`otherMessageBackground`/`inputBackground` recolour the message bubbles and input bar. |
 | `backgroundChat` | `{ color?; image? }` | Background colour and/or image for the messages area. (`image` as a string URL; pass an object URL for a `File`.) |
 | `typography` | `TypographyConfig` | Font family + size for the chat UI: `fontFamily` (or just `googleFontsFamily`) is applied across all chat text incl. messages and sender names; `fontSize` (px) scales message text, sender names, timestamps, inputs, room names and badges. Plus loaders (`googleFontsUrl`/`fontFaces`) and weight tokens. |
-| `fallbackScreens` | `{ noUser?; noConnection?; noRoom? }` | Replace the built-in screens (Ethora login form, "Connecting...", empty room state) with your own text or React nodes. A plain string is rendered as centered text. |
+| `fallbackScreens` | `{ noUser?; noConnection?; noRoom?; error? }` | Replace the built-in screens (Ethora login form, "Connecting...", empty room state, crash screen) with your own text or React nodes. A plain string is rendered as centered text. `error` also accepts a function `({ error, componentStack, scope, reset }) => ReactNode`, see [Error handling](#error-handling-and-crash-containment). |
 | `hiddenRooms` | `{ titles?: string[]; jids?: string[] }` | Hide specific rooms from the room list and unread counters (e.g. `{ titles: ['Main chat'] }` to suppress the auto-created default room). |
 | `roomListStyles` | `React.CSSProperties` | Styles for room list pane. |
 | `chatRoomStyles` | `React.CSSProperties` | Styles for chat pane. |
 | `noMessagesPlaceholder` | `React.ComponentType` | Replace empty-chat placeholder component (same render position as default placeholder). |
 | `backgroundChat` | `{ color?: string; image?: string \| File }` | Chat background customization. |
-| `bubleMessage` | `MessageBubble` | Bubble-level style overrides (as defined in types). |
 | `setRoomJidInPath` | `boolean` | Sync room JID to URL path. |
 | `qrUrl` | `string` | Base URL for QR deep link behavior. |
 
@@ -384,8 +386,6 @@ Below is a grouped reference for all `config` options.
 | Option | Type | Description |
 | --- | --- | --- |
 | `defaultRooms` | `ConfigRoom[]` | Seed/default rooms. |
-| `customRooms` | `{ rooms: PartialRoomWithMandatoryKeys[]; disableGetRooms?: boolean; singleRoom: boolean }` | Fully controlled room source. |
-| `forceSetRoom` | `boolean` | Force room setup path in init flow. |
 | `enableRoomsRetry` | `{ enabled: boolean; helperText: string }` | Enable retry UX when rooms fail to load. |
 
 ### Messaging and Interactions
@@ -396,10 +396,9 @@ Below is a grouped reference for all `config` options.
 | `disableProfilesInteractions` | `boolean` | Disable profile interactions from chat UI. |
 | `disableSentLogic` | `boolean` | Disable default sent-state logic when needed. |
 | `secondarySendButton` | `{ enabled: boolean; messageEdit: string; label?: React.ReactNode; buttonStyles?: React.CSSProperties; hideInputSendButton?: boolean; overwriteEnterClick?: true }` | Extra send action/button config. |
-| `botMessageAutoScroll` | `boolean` | Force auto-scroll behavior on bot messages. |
 | `messageTextFilter` | `{ enabled: boolean; filterFunction: (text: string) => string }` | Transform/filter outgoing message text. |
-| `eventHandlers` | `{ onMessageSent?; onMessageFailed?; onMessageEdited? }` | Lifecycle callbacks for message operations. |
-| `translates` | `{ enabled: boolean; translations?: Iso639_1Codes }` | Message translation-related options. |
+| `eventHandlers` | `{ onMessageSent?; onMessageFailed?; onMessageEdited?; onError? }` | Lifecycle callbacks for message operations, plus `onError` for uncaught render errors caught by the SDK's error boundary, see [Error handling](#error-handling-and-crash-containment). |
+| `translates` | `{ enabled: boolean; translations?: Iso639_1Codes; mode?: 'auto' \| 'manual'; forceType?: boolean; readerLocale?: string; showLanguageSelector?: boolean; showLanguageList?: boolean; onTranslate?: (text, ctx) => Promise<string>; showTranslateForMessage?: (message) => boolean; endpoint?: string }` | Message translation-related options. In manual mode, an on-demand translate click shows exactly what `mode: 'auto'` would have shown automatically - the same `message.translations` lookup, no network call - unless `onTranslate` is provided, in which case it wins and may do its own HTTP. The built-in translate-service fetch is strictly opt-in: it only runs when the host sets `endpoint` explicitly (there is no default derived from `config.baseUrl`), and the result is cached onto the message so a second click, or switching to 'auto', sees it for free. The call is made directly from the browser, so `endpoint` must respond with `Access-Control-Allow-Origin` for that origin (a self-hosted translate service needs its `CORS_ORIGIN` env var set) or the fetch is blocked with no error shown beyond the retry link; if you can't set that on the endpoint, use `onTranslate` and proxy the call through your own backend instead. When there is genuinely nothing to reveal (no attached translation, no `onTranslate`, no `endpoint`), no "Translate" link is shown at all. |
 | `whitelistSystemMessage` | `string[]` | Restrict/render only selected system message types. |
 | `customSystemMessage` | `React.ComponentType<MessageProps>` | Replace system message component renderer. |
 
@@ -431,6 +430,62 @@ Below is a grouped reference for all `config` options.
 | `pushNotifications.softAsk` | `boolean` | Do not immediately trigger browser permission prompt. |
 | `pushNotifications.onClick` | `(params) => void \| Promise<void>` | Callback invoked when the user clicks an OS push notification (including cold start via URL marker). |
 
+### Error handling and crash containment
+
+The SDK renders inside your application's React tree. Without a boundary, one
+uncaught render error inside the chat would propagate to your root and unmount
+your whole app, so `@ethora/chat-component` ships an error boundary of its own:
+
+- one boundary wraps everything `<Chat>` renders (it sits inside `<Chat>`'s
+  redux provider, above the persist gate and the whole chat tree);
+- a second one wraps the video/audio call overlay, which `<XmppProvider>`
+  renders as a sibling of your children so it can ring while the user is on
+  another page. A crash there disappears quietly instead of leaving a dead
+  panel over your UI, and is still logged and reported.
+
+The error is never swallowed: it is always written to the console together
+with React's component stack, regardless of `useStoreConsoleEnabled`.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `fallbackScreens.error` | `React.ReactNode \| ((ctx) => React.ReactNode)` | Replaces the built-in crash screen. A plain string renders as centered text, a React node renders as-is, a function receives `{ error, componentStack, scope, reset }`. |
+| `eventHandlers.onError` | `(event: ChatErrorInfo) => void` | Called with `{ error, componentStack, scope }` when the boundary catches a crash. Wire it to your crash reporter. A throw inside your handler is caught and logged, never rethrown. |
+
+`scope` is `'chat'` for the chat tree and `'call-overlay'` for the call
+overlay. The built-in screen is themed from your `colors` / `typography` and
+translated through the same `config.i18n` locale as the rest of the UI, and it
+offers a "try again" button that clears the error and re-mounts the chat, since
+most of these failures are transient state problems.
+
+```tsx
+<Chat
+  config={{
+    eventHandlers: {
+      onError: ({ error, componentStack, scope }) =>
+        Sentry.captureException(error, { extra: { componentStack, scope } }),
+    },
+    fallbackScreens: {
+      // Simplest form: replace it with your own text.
+      // error: 'Chat is temporarily unavailable',
+
+      // Or take full control, including your own retry action:
+      error: ({ error, reset }) => (
+        <MyErrorPanel message={error.message} onRetry={reset} />
+      ),
+    },
+  }}
+/>
+```
+
+A string or node fallback is only used for the chat pane: for a crashed call
+overlay the SDK renders nothing, and only the function form (which can inspect
+`scope`) is consulted.
+
+The call overlay is rendered by `<XmppProvider>`, so pass the same config
+object to the provider as to `<Chat>` (which the [single XMPP initialization
+contract](#single-xmpp-initialization-contract) already recommends) if you want
+`'call-overlay'` crashes to reach your `onError` too.
+
 ## Custom Widgets and Overrides
 
 You can replace key UI parts without forking the package.
@@ -606,13 +661,14 @@ function PushPermissionButton() {
 | --- | --- | --- |
 | `Chat` | React component | Main chat component. |
 | `XmppProvider` | React provider | Provides XMPP client context for internal hooks/state. |
-| `useUnread` | hook | Returns unread counters (`totalCount`, per-room maps) plus a `loading` flag that stays `true` until the room list has loaded at least once. |
+| `useUnread` | hook | Returns unread counters (`totalCount`, per-room maps) plus a `loading` flag that stays `true` until the room list has loaded at least once. `totalCount`/`hasUnread` exclude any room the caller has muted - a muted room still reports its own count in `unreadByRoom`/`displayByRoom`, it just doesn't inflate the aggregate. |
 | `logoutService` | service | Programmatic logout utility. |
 | `useQRCodeChat` | hook | Handle QR-based room links. |
 | `handleQRChatId` | function | Parse/process QR chat ID from URL. |
 | `useInAppNotifications` | hook | Enables and handles in-app notifications. |
 | `usePushNotifications` | hook | Push subscription + foreground handling workflow. |
 | `resendMessage` | function | Retry sending failed/pending messages. |
+| `useRoomMute` | hook | `useRoomMute(roomJid)` returns `{ muted, isSupported, isPending, toggleMute, setMuted }` for a room's mute preference - optimistic with rollback on failure. `isSupported` is only `true` once the backend has reported a `muted` boolean for that room (it hasn't shipped to prod yet), so hosts building their own UI should hide a mute control until then. |
 
 Basic hook usage:
 
@@ -680,7 +736,7 @@ This is a practical planning snapshot for cross-platform consumers. It is not a
 | Issue | Likely cause | Fix |
 | --- | --- | --- |
 | `useXmppClient must be used within an XmppProvider` | Using internal XMPP-dependent logic without provider context | Wrap the app tree with `XmppProvider` where needed. |
-| Chat loads but no rooms appear | Auth/app context mismatch or room fetching restrictions | Verify `appId`, user credentials/tokens, `baseUrl`, and `customRooms` settings. |
+| Chat loads but no rooms appear | Auth/app context mismatch or room fetching restrictions | Verify `appId`, user credentials/tokens, `baseUrl`, and `defaultRooms` settings. |
 | Push permission never appears | `softAsk: true` without manual trigger, insecure origin, or missing VAPID key | Trigger `requestPermission()`, use HTTPS/localhost, set valid VAPID key. |
 | Service worker not found | `firebase-messaging-sw.js` missing in public dir | Run `npx @ethora/chat-component ethora-chat` or copy file manually. |
 | Login loop / auth failure | Wrong token/user object shape | Validate `jwtLogin`, `userLogin.user`, and refresh token flow. |
@@ -780,4 +836,4 @@ from `src/test/testIds.ts` here.
 
 ## License
 
-AGPL. See [LICENSE.txt](./LICENSE.txt).
+MIT. See [LICENSE](./LICENSE).