feat: add Matrix federation support — federated room detection, Matrix user badges, initials avatars, and Storybook demo

deepak0x · deepak0x · commit ec37e1d936bf · 2026-03-28T05:20:47.000+05:30
diff --git a/packages/api/src/EmbeddedChatApi.ts b/packages/api/src/EmbeddedChatApi.ts
@@ -491,6 +491,29 @@ export default class EmbeddedChatApi {
     }
   }
 
+  /**
+   * Returns federation metadata for the current room.
+   * @returns {{ isFederated: boolean, homeserver: string | null }}
+   */
+  async isFederatedRoom(): Promise<{ isFederated: boolean; homeserver: string | null }> {
+    try {
+      const info = await this.channelInfo();
+      const room = info?.room;
+      if (!room) return { isFederated: false, homeserver: null };
+
+      const federated =
+        room.federated === true ||
+        room.federation != null;
+
+      const homeserver: string | null =
+        room.federation?.origin ?? null;
+
+      return { isFederated: federated, homeserver };
+    } catch {
+      return { isFederated: false, homeserver: null };
+    }
+  }
+
   async getRoomInfo() {
     try {
       const { userId, authToken } = (await this.auth.getCurrentUser()) || {};
diff --git a/packages/react/src/context/FederationContext.js b/packages/react/src/context/FederationContext.js
@@ -0,0 +1,67 @@
+import React, { createContext, useContext, useEffect, useState } from 'react';
+
+/**
+ * Exposes federation state to the component tree.
+ * @property {boolean} isFederated - true when the active room is Matrix-bridged
+ * @property {string|null} matrixHomeserver - the homeserver origin (e.g. "matrix.org")
+ * @property {boolean} federationLoading - true while room info is being fetched
+ */
+const FederationContext = createContext({
+  isFederated: false,
+  matrixHomeserver: null,
+  federationLoading: false,
+});
+
+export const FederationProvider = ({ children, RCInstance }) => {
+  const [isFederated, setIsFederated] = useState(false);
+  const [matrixHomeserver, setMatrixHomeserver] = useState(null);
+  const [federationLoading, setFederationLoading] = useState(true);
+
+  useEffect(() => {
+    if (!RCInstance) {
+      setFederationLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+
+    const detectFederation = async () => {
+      try {
+        setFederationLoading(true);
+        const info = await RCInstance.channelInfo();
+        if (cancelled) return;
+
+        const room = info?.room;
+        const federated =
+          room?.federated === true || room?.federation != null;
+
+        setIsFederated(federated);
+
+        if (federated && room?.federation?.origin) {
+          setMatrixHomeserver(room.federation.origin);
+        }
+      } catch {
+        if (!cancelled) setIsFederated(false);
+      } finally {
+        if (!cancelled) setFederationLoading(false);
+      }
+    };
+
+    detectFederation();
+    return () => {
+      cancelled = true;
+    };
+  }, [RCInstance]);
+
+  return (
+    <FederationContext.Provider
+      value={{ isFederated, matrixHomeserver, federationLoading }}
+    >
+      {children}
+    </FederationContext.Provider>
+  );
+};
+
+export const useFederation = () => useContext(FederationContext);
+
+export default FederationContext;
diff --git a/packages/react/src/lib/federationUtils.js b/packages/react/src/lib/federationUtils.js
@@ -0,0 +1,68 @@
+/**
+ * Returns true if the username looks like a Matrix user ID (@localpart:homeserver.tld).
+ * @param {string} username
+ * @returns {boolean}
+ */
+export const isMatrixUser = (username) => {
+  if (!username) return false;
+  return /^@[^:]+:[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(username);
+};
+
+/**
+ * Parses a Matrix user ID into localpart and homeserver.
+ * @param {string} matrixId  e.g. "@alice:matrix.org"
+ * @returns {{ localpart: string, homeserver: string } | null}
+ */
+export const parseMatrixUserId = (matrixId) => {
+  if (!isMatrixUser(matrixId)) return null;
+  const withoutAt = matrixId.slice(1);
+  const colonIdx = withoutAt.indexOf(':');
+  return {
+    localpart: withoutAt.slice(0, colonIdx),
+    homeserver: withoutAt.slice(colonIdx + 1),
+  };
+};
+
+/**
+ * Returns a display-friendly label, truncating long homeservers.
+ * @param {string} matrixId
+ * @returns {string}
+ */
+export const getMatrixDisplayLabel = (matrixId) => {
+  const parsed = parseMatrixUserId(matrixId);
+  if (!parsed) return matrixId;
+  const { localpart, homeserver } = parsed;
+  const shortHost =
+    homeserver.length > 20 ? homeserver.slice(0, 18) + '…' : homeserver;
+  return `@${localpart}:${shortHost}`;
+};
+
+/**
+ * Returns 1-2 char initials for avatar fallback.
+ * @param {string} matrixId
+ * @returns {string}
+ */
+export const getMatrixInitials = (matrixId) => {
+  const parsed = parseMatrixUserId(matrixId);
+  if (!parsed) return '?';
+  return parsed.localpart.slice(0, 2).toUpperCase();
+};
+
+/**
+ * Generates a deterministic background color from a string.
+ * @param {string} str
+ * @returns {string}
+ */
+export const getAvatarColor = (str) => {
+  const COLORS = [
+    '#e57373', '#f06292', '#ba68c8', '#9575cd',
+    '#7986cb', '#64b5f6', '#4fc3f7', '#4dd0e1',
+    '#4db6ac', '#81c784', '#aed581', '#ffd54f',
+    '#ffb74d', '#ff8a65', '#a1887f', '#90a4ae',
+  ];
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return COLORS[Math.abs(hash) % COLORS.length];
+};
diff --git a/packages/react/src/stories/EmbeddedChatFederated.stories.js b/packages/react/src/stories/EmbeddedChatFederated.stories.js
@@ -0,0 +1,33 @@
+import { EmbeddedChat } from '..';
+
+export default {
+  title: 'EmbeddedChat/Federated (Matrix)',
+  component: EmbeddedChat,
+};
+
+export const FederatedRoom = {
+  args: {
+    host: process.env.STORYBOOK_RC_HOST || 'http://localhost:3000',
+    roomId: process.env.STORYBOOK_FEDERATED_ROOM_ID || 'GENERAL',
+    channelName: 'federated-room',
+    anonymousMode: false,
+    toastBarPosition: 'bottom right',
+    showRoles: true,
+    showUsername: true,
+    enableThreads: true,
+    hideHeader: false,
+    auth: {
+      flow: 'PASSWORD',
+    },
+    dark: false,
+    federation: true,
+  },
+};
+
+export const FederatedRoomDark = {
+  args: {
+    ...FederatedRoom.args,
+    dark: true,
+    channelName: 'federated-room (dark)',
+  },
+};
diff --git a/packages/react/src/views/EmbeddedChat.js b/packages/react/src/views/EmbeddedChat.js
@@ -18,6 +18,7 @@ import {
 import { ChatLayout } from './ChatLayout';
 import { ChatHeader } from './ChatHeader';
 import { RCInstanceProvider } from '../context/RCInstance';
+import { FederationProvider } from '../context/FederationContext';
 import { useUserStore, useLoginStore, useMessageStore } from '../store';
 import DefaultTheme from '../theme/DefaultTheme';
 import { getTokenStorage } from '../lib/auth';
@@ -58,6 +59,8 @@ const EmbeddedChat = (props) => {
     secure = false,
     dark = false,
     remoteOpt = false,
+    /** Enable Matrix federation support — detects federated rooms and renders Matrix user identities correctly */
+    federation = false,
   } = config;
 
   const hasMounted = useRef(false);
@@ -227,6 +230,7 @@ const EmbeddedChat = (props) => {
   return (
     <ThemeProvider theme={theme || DefaultTheme} mode={dark ? 'dark' : 'light'}>
       <RCInstanceProvider value={RCContextValue}>
+      <FederationProvider RCInstance={federation ? RCInstance : null}>
         <Box
           css={[
             styles.embeddedchat(theme || DefaultTheme, dark),
@@ -256,6 +260,7 @@ const EmbeddedChat = (props) => {
             <div id="overlay-items" />
           </ToastBarProvider>
         </Box>
+      </FederationProvider>
       </RCInstanceProvider>
     </ThemeProvider>
   );
@@ -288,6 +293,7 @@ EmbeddedChat.propTypes = {
   style: PropTypes.object,
   hideHeader: PropTypes.bool,
   dark: PropTypes.bool,
+  federation: PropTypes.bool,
 };
 
 export default memo(EmbeddedChat);
diff --git a/packages/react/src/views/Message/MatrixAvatar.js b/packages/react/src/views/Message/MatrixAvatar.js
@@ -0,0 +1,42 @@
+import React from 'react';
+import { getMatrixInitials, getAvatarColor } from '../../lib/federationUtils';
+
+/**
+ * Coloured initials avatar for Matrix-federated users.
+ * Used as a fallback when the user has no Rocket.Chat avatar.
+ */
+const MatrixAvatar = ({ matrixId, size = '2.25em', onClick }) => {
+  const initials = getMatrixInitials(matrixId);
+  const bg = getAvatarColor(matrixId);
+
+  const style = {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    width: size,
+    height: size,
+    borderRadius: '50%',
+    backgroundColor: bg,
+    color: '#fff',
+    fontSize: `calc(${size} * 0.4)`,
+    fontWeight: 700,
+    flexShrink: 0,
+    cursor: onClick ? 'pointer' : 'default',
+    userSelect: 'none',
+  };
+
+  return (
+    <span
+      style={style}
+      onClick={onClick}
+      aria-label={`Avatar for ${matrixId}`}
+      role={onClick ? 'button' : 'img'}
+      tabIndex={onClick ? 0 : undefined}
+      onKeyDown={onClick ? (e) => e.key === 'Enter' && onClick() : undefined}
+    >
+      {initials}
+    </span>
+  );
+};
+
+export default MatrixAvatar;
diff --git a/packages/react/src/views/Message/MessageAvatarContainer.js b/packages/react/src/views/Message/MessageAvatarContainer.js
@@ -10,6 +10,9 @@ import RCContext from '../../context/RCInstance';
 import { getMessageAvatarContainerStyles } from './Message.styles';
 import useSetExclusiveState from '../../hooks/useSetExclusiveState';
 import { useUserStore } from '../../store';
+import { useFederation } from '../../context/FederationContext';
+import { isMatrixUser } from '../../lib/federationUtils';
+import MatrixAvatar from './MatrixAvatar';
 
 const MessageAvatarContainer = ({
   message,
@@ -20,6 +23,8 @@ const MessageAvatarContainer = ({
   const { RCInstance } = useContext(RCContext);
   const { theme } = useTheme();
   const styles = getMessageAvatarContainerStyles(theme);
+  const { isFederated } = useFederation();
+
   const getUserAvatarUrl = (username) => {
     const host = RCInstance.getHost();
     const URL = `${host}/avatar/${username}`;
@@ -40,20 +45,32 @@ const MessageAvatarContainer = ({
   return (
     <Box css={styles.container}>
       {!sequential ? (
-        <Avatar
-          url={getUserAvatarUrl(message.u.username)}
-          alt="avatar"
-          size={
-            window.matchMedia('(max-width: 768px)').matches
-              ? message.t
-                ? '1.2em'
-                : '1.5em'
-              : message.t
-              ? '1.5em'
-              : '2.25em'
-          }
-          onClick={handleAvatarClick}
-        />
+        isFederated && isMatrixUser(message.u.username) ? (
+          <MatrixAvatar
+            matrixId={message.u.username}
+            size={
+              window.matchMedia('(max-width: 768px)').matches
+                ? message.t ? '1.2em' : '1.5em'
+                : message.t ? '1.5em' : '2.25em'
+            }
+            onClick={handleAvatarClick}
+          />
+        ) : (
+          <Avatar
+            url={getUserAvatarUrl(message.u.username)}
+            alt="avatar"
+            size={
+              window.matchMedia('(max-width: 768px)').matches
+                ? message.t
+                  ? '1.2em'
+                  : '1.5em'
+                : message.t
+                ? '1.5em'
+                : '2.25em'
+            }
+            onClick={handleAvatarClick}
+          />
+        )
       ) : null}
       {isStarred && sequential ? (
         <Tooltip text="Starred" position="top">
diff --git a/packages/react/src/views/Message/MessageHeader.js b/packages/react/src/views/Message/MessageHeader.js
