[Chat] File Sharing Refactor (#4464)

Author: jpeng-ms

change-beta/@azure-communication-react-7f8f9b0e-279a-4976-bf03-6a22f90ee4a1.json

@@ -0,0 +1,9 @@
+{
+  "type": "minor",
+  "area": "improvement",
+  "workstream": "File Sharing Refactor",
+  "comment": "Updated File Sharing Public APIs",
+  "packageName": "@azure/communication-react",
+  "email": "109105353+jpeng-ms@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

change/@azure-communication-react-7f8f9b0e-279a-4976-bf03-6a22f90ee4a1.json

@@ -0,0 +1,9 @@
+{
+  "type": "minor",
+  "area": "improvement",
+  "workstream": "File Sharing Refactor",
+  "comment": "Updated File Sharing Public APIs",
+  "packageName": "@azure/communication-react",
+  "email": "109105353+jpeng-ms@users.noreply.github.com",
+  "dependentChangeType": "patch"
+}

packages/communication-react/review/beta/communication-react.api.md

@@ -166,11 +166,15 @@ export interface AttachmentMetadata {
     extension?: string;
     id: string;
     name: string;
-    progress?: number;
-    uploadError?: AttachmentUploadStatus;
     url?: string;
 }
 
+// @beta
+export interface AttachmentMetadataWithProgress extends AttachmentMetadata {
+    error?: AttachmentProgressError;
+    progress?: number;
+}
+
 // @beta
 export interface AttachmentOptions {
     // (undocumented)
@@ -179,16 +183,28 @@ export interface AttachmentOptions {
     uploadOptions?: AttachmentUploadOptions;
 }
 
-// @beta (undocumented)
-export interface AttachmentUploadAdapter {
+// @beta
+export interface AttachmentProgressError {
+    // (undocumented)
+    message: string;
+}
+
+// @beta
+export type AttachmentRemovalHandler = (attachmentId: string) => void;
+
+// @beta
+export type AttachmentSelectionHandler = (attachmentUploads: AttachmentUploadTask[]) => void;
+
+// @internal (undocumented)
+export interface _AttachmentUploadAdapter {
     // (undocumented)
     cancelUpload: (id: string) => void;
     // (undocumented)
     clearUploads: () => void;
     // (undocumented)
-    registerActiveUploads: (files: File[]) => AttachmentUploadManager[];
+    registerActiveUploads: (files: File[]) => AttachmentUploadTask[];
     // (undocumented)
-    registerCompletedUploads: (metadata: AttachmentMetadata[]) => AttachmentUploadManager[];
+    registerCompletedUploads: (metadata: AttachmentMetadata[]) => AttachmentUploadTask[];
     // (undocumented)
     updateUploadMetadata: (id: string, metadata: AttachmentMetadata) => void;
     // (undocumented)
@@ -197,35 +213,25 @@ export interface AttachmentUploadAdapter {
     updateUploadStatusMessage: (id: string, errorMessage: string) => void;
 }
 
-// @beta
-export type AttachmentUploadHandler = (attachmentUploads: AttachmentUploadManager[]) => void;
-
-// @beta
-export interface AttachmentUploadManager {
-    file?: File;
-    id: string;
-    notifyCompleted: (metadata: AttachmentMetadata) => void;
-    notifyFailed: (message: string) => void;
-    notifyProgressChanged: (value: number) => void;
-}
-
 // @beta (undocumented)
 export interface AttachmentUploadOptions {
     disableMultipleUploads?: boolean;
-    handler: AttachmentUploadHandler;
+    handleAttachmentRemoval?: AttachmentRemovalHandler;
+    handleAttachmentSelection: AttachmentSelectionHandler;
     supportedMediaTypes?: string[];
 }
 
-// @beta
-export interface AttachmentUploadStatus {
-    // (undocumented)
-    message: string;
-    // (undocumented)
-    timestamp: number;
-}
+// @internal
+export type _AttachmentUploadsUiState = Record<string, AttachmentMetadataWithProgress>;
 
 // @beta
-export type AttachmentUploadsUiState = Record<string, AttachmentMetadata>;
+export interface AttachmentUploadTask {
+    file?: File;
+    notifyUploadCompleted: (id: string, url: string) => void;
+    notifyUploadFailed: (message: string) => void;
+    notifyUploadProgressChanged: (value: number) => void;
+    taskId: string;
+}
 
 // @public
 export type AvatarPersonaData = {
@@ -1078,9 +1084,9 @@ export interface CallWithChatAdapterManagement {
     addParticipant(participant: CommunicationUserIdentifier): Promise<void>;
     allowUnsupportedBrowserVersion(): void;
     askDevicePermission(constrain: PermissionConstraints): Promise<void>;
-    // @beta (undocumented)
+    // @internal (undocumented)
     cancelUpload: (id: string) => void;
-    // @beta (undocumented)
+    // @internal (undocumented)
     clearUploads: () => void;
     createStreamView(remoteUserId?: string, options?: VideoStreamOptions): Promise<void | CreateVideoStreamViewResult>;
     deleteMessage(messageId: string): Promise<void>;
@@ -1105,10 +1111,10 @@ export interface CallWithChatAdapterManagement {
     queryMicrophones(): Promise<AudioDeviceInfo[]>;
     querySpeakers(): Promise<AudioDeviceInfo[]>;
     raiseHand(): Promise<void>;
-    // @beta (undocumented)
-    registerActiveUploads: (files: File[]) => AttachmentUploadManager[];
-    // @beta (undocumented)
-    registerCompletedUploads: (metadata: AttachmentMetadata[]) => AttachmentUploadManager[];
+    // @internal (undocumented)
+    registerActiveUploads: (files: File[]) => AttachmentUploadTask[];
+    // @internal (undocumented)
+    registerCompletedUploads: (metadata: AttachmentMetadata[]) => AttachmentUploadTask[];
     removeParticipant(userId: string): Promise<void>;
     // @beta
     removeParticipant(participant: CommunicationIdentifier): Promise<void>;
@@ -1118,6 +1124,8 @@ export interface CallWithChatAdapterManagement {
     resumeCall: () => Promise<void>;
     sendDtmfTone: (dtmfTone: DtmfTone_2) => Promise<void>;
     sendMessage(content: string, options?: SendMessageOptions): Promise<void>;
+    // @beta
+    sendMessageWithAttachments(content: string, attachments: AttachmentMetadata[]): Promise<void>;
     sendReadReceipt(chatMessageId: string): Promise<void>;
     sendTypingIndicator(): Promise<void>;
     setCamera(sourceInfo: VideoDeviceInfo, options?: VideoStreamOptions): Promise<void>;
@@ -1143,11 +1151,11 @@ export interface CallWithChatAdapterManagement {
     updateBackgroundPickerImages(backgroundImages: VideoBackgroundImage[]): void;
     updateMessage(messageId: string, content: string, metadata?: Record<string, string>): Promise<void>;
     updateSelectedVideoBackgroundEffect(selectedVideoBackground: VideoBackgroundEffect): void;
-    // @beta (undocumented)
+    // @internal (undocumented)
     updateUploadMetadata: (id: string, metadata: AttachmentMetadata) => void;
-    // @beta (undocumented)
+    // @internal (undocumented)
     updateUploadProgress: (id: string, progress: number) => void;
-    // @beta (undocumented)
+    // @internal (undocumented)
     updateUploadStatusMessage: (id: string, errorMessage: string) => void;
 }
 
@@ -1261,8 +1269,8 @@ export interface CallWithChatAdapterSubscriptions {
 
 // @public
 export interface CallWithChatAdapterUiState {
-    // @beta
-    attachmentUploads?: AttachmentUploadsUiState;
+    // @internal
+    _attachmentUploads?: _AttachmentUploadsUiState;
     isLocalPreviewMicrophoneEnabled: boolean;
     page: CallCompositePage;
     // @beta
@@ -1677,7 +1685,7 @@ export type CaptionsReceivedListener = (event: {
 }) => void;
 
 // @public
-export type ChatAdapter = ChatAdapterThreadManagement & AdapterState<ChatAdapterState> & Disposable_2 & ChatAdapterSubscribers & AttachmentUploadAdapter;
+export type ChatAdapter = ChatAdapterThreadManagement & AdapterState<ChatAdapterState> & Disposable_2 & ChatAdapterSubscribers & _AttachmentUploadAdapter;
 
 // @public
 export type ChatAdapterState = ChatAdapterUiState & ChatCompositeClientState;
@@ -1713,6 +1721,7 @@ export interface ChatAdapterThreadManagement {
     removeParticipant(userId: string): Promise<void>;
     removeResourceFromCache(resourceDetails: ResourceDetails): void;
     sendMessage(content: string, options?: SendMessageOptions): Promise<void>;
+    sendMessageWithAttachments(content: string, attachments: AttachmentMetadata[]): Promise<void>;
     sendReadReceipt(chatMessageId: string): Promise<void>;
     sendTypingIndicator(): Promise<void>;
     setTopic(topicName: string): Promise<void>;
@@ -1724,7 +1733,7 @@ export interface ChatAdapterThreadManagement {
 // @public
 export type ChatAdapterUiState = {
     error?: Error;
-    attachmentUploads?: AttachmentUploadsUiState;
+    _attachmentUploads?: _AttachmentUploadsUiState;
 };
 
 // @public
@@ -3882,7 +3891,7 @@ export const RichTextSendBox: (props: RichTextSendBoxProps) => JSX.Element;
 
 // @beta
 export interface RichTextSendBoxProps {
-    activeAttachmentUploads?: AttachmentMetadata[];
+    attachmentsWithProgress?: AttachmentMetadataWithProgress[];
     autoFocus?: 'sendBoxTextField';
     disabled?: boolean;
     onCancelAttachmentUpload?: (attachmentId: string) => void;
@@ -3954,7 +3963,7 @@ export interface SendBoxErrorBarError {
 // @public
 export interface SendBoxProps {
     // @beta
-    activeAttachmentUploads?: AttachmentMetadata[];
+    attachmentsWithProgress?: AttachmentMetadataWithProgress[];
     autoFocus?: 'sendBoxTextField';
     disabled?: boolean;
     // @beta

packages/communication-react/src/index.ts

@@ -324,10 +324,12 @@ export type { AttachmentMetadata, AttachmentOptions } from '../../react-componen
 export type { SendBoxErrorBarError } from '../../react-components/src';
 /* @conditional-compile-remove(attachment-upload) */
 export type {
-  AttachmentUploadStatus,
-  AttachmentUploadHandler,
+  AttachmentProgressError,
+  AttachmentSelectionHandler,
+  AttachmentRemovalHandler,
   AttachmentUploadOptions,
-  AttachmentUploadManager
+  AttachmentUploadTask,
+  AttachmentMetadataWithProgress
 } from '../../react-components/src';
 
 /* @conditional-compile-remove(attachment-download) */

packages/react-components/src/components/AttachmentCard.tsx

@@ -26,7 +26,7 @@ import { Announcer } from './Announcer';
 import { useEffect, useState, useMemo } from 'react';
 import { _AttachmentUploadCardsStrings } from './AttachmentUploadCards';
 import { useLocaleAttachmentCardStringsTrampoline } from './utils/common';
-import { AttachmentMetadata, AttachmentMenuAction } from '../types/Attachment';
+import { AttachmentMetadata, AttachmentMenuAction, AttachmentMetadataWithProgress } from '../types/Attachment';
 import { useAttachmentCardStyles, attachmentNameContainerClassName } from './styles/AttachmentCard.styles';
 
 /**
@@ -37,7 +37,7 @@ export interface _AttachmentCardProps {
   /**
    * Attachment details including name, extension, url, etc.
    */
-  attachment: AttachmentMetadata;
+  attachment: AttachmentMetadata | AttachmentMetadataWithProgress;
   /**
    * An array of menu actions to be displayed in the attachment card.
    */
@@ -61,9 +61,11 @@ export interface _AttachmentCardProps {
 export const _AttachmentCard = (props: _AttachmentCardProps): JSX.Element => {
   const { attachment, menuActions, onActionHandlerFailed } = props;
   const attachmentCardStyles = useAttachmentCardStyles();
+
   const progress = useMemo(() => {
-    return attachment.progress;
-  }, [attachment.progress]);
+    return 'progress' in attachment ? attachment.progress : undefined;
+  }, [attachment]);
+
   const isUploadComplete = useMemo(() => {
     return progress !== undefined && progress > 0 && progress < 1;
   }, [progress]);

packages/react-components/src/components/AttachmentUploadCards.test.tsx

@@ -18,7 +18,7 @@ describe('AttachmentUploadCards should be rendered properly', () => {
 
   it('should render the component', async () => {
     const props = {
-      activeAttachmentUploads: [
+      attachmentsWithProgress: [
         {
           id: 'MockId',
           name: 'MockAttachmentUpload',
@@ -30,9 +30,9 @@ describe('AttachmentUploadCards should be rendered properly', () => {
     expect(await screen.findByText('MockAttachmentUpload')).toBeDefined();
   });
 
-  it('should not render the component with no activeAttachmentUploads', async () => {
+  it('should not render the component with no attachmentsWithProgress', async () => {
     const props = {
-      activeAttachmentUploads: undefined
+      attachmentsWithProgress: undefined
     } as AttachmentUploadCardsProps;
     renderAttachmentUploadCardWithDefaults(props);
     expect(screen.queryByText('MockAttachmentUpload')).toBeNull();
@@ -41,7 +41,7 @@ describe('AttachmentUploadCards should be rendered properly', () => {
 
 const renderAttachmentUploadCardWithDefaults = (props?: Partial<AttachmentUploadCardsProps>): void => {
   const mergedProps: AttachmentUploadCardsProps = {
-    activeAttachmentUploads: props?.activeAttachmentUploads ?? [],
+    attachmentsWithProgress: props?.attachmentsWithProgress ?? [],
     ...(props ?? {})
   };
 

packages/react-components/src/components/AttachmentUploadCards.tsx

@@ -5,7 +5,7 @@ import { Icon, mergeStyles } from '@fluentui/react';
 import React, { useMemo } from 'react';
 import { _AttachmentCard } from './AttachmentCard';
 import { _AttachmentCardGroup } from './AttachmentCardGroup';
-import { AttachmentMetadata } from '../types/Attachment';
+import { AttachmentMetadataWithProgress } from '../types/Attachment';
 import { useLocaleAttachmentCardStringsTrampoline } from './utils/common';
 
 /**
@@ -29,10 +29,9 @@ export interface _AttachmentUploadCardsStrings {
  */
 export interface AttachmentUploadCardsProps {
   /**
-   * Optional array of active attachment uploads where each object has attibutes
-   * of a attachment upload like name, progress, errormessage etc.
+   * Optional array of {@link AttachmentMetadataWithProgress}
    */
-  activeAttachmentUploads?: AttachmentMetadata[];
+  attachmentsWithProgress?: AttachmentMetadataWithProgress[];
   /**
    * Optional callback to remove the attachment upload before sending by clicking on
    * cancel icon.
@@ -50,7 +49,7 @@ const actionIconStyle = { height: '1rem' };
  * @internal
  */
 export const _AttachmentUploadCards = (props: AttachmentUploadCardsProps): JSX.Element => {
-  const attachments = props.activeAttachmentUploads;
+  const attachments = props.attachmentsWithProgress;
   const localeStrings = useLocaleAttachmentCardStringsTrampoline();
   const removeAttachmentButtonString = useMemo(
     () => () => {
@@ -67,7 +66,7 @@ export const _AttachmentUploadCards = (props: AttachmentUploadCardsProps): JSX.E
     <_AttachmentCardGroup>
       {attachments &&
         attachments
-          .filter((attachment) => !attachment.uploadError)
+          .filter((attachment) => !attachment.error)
           .map((attachment) => (
             <_AttachmentCard
               attachment={attachment}

packages/react-components/src/components/ChatMessage/MyMessageComponents/ChatMessageComponentAsEditBox.tsx

@@ -119,7 +119,7 @@ export const ChatMessageComponentAsEditBox = (props: ChatMessageComponentAsEditB
       attachmentMetadata.length > 0 && (
         <div style={{ margin: '0.25rem' }}>
           <_AttachmentUploadCards
-            activeAttachmentUploads={attachmentMetadata}
+            attachmentsWithProgress={attachmentMetadata}
             onCancelAttachmentUpload={(attachmentId) => {
               setAttachmentMetadata(attachmentMetadata?.filter((attachment) => attachment.id !== attachmentId));
             }}

packages/react-components/src/components/ChatMessage/MyMessageComponents/ChatMessageComponentAsRichTextEditBox.tsx

@@ -169,7 +169,7 @@ export const ChatMessageComponentAsRichTextEditBox = (
       <Stack className={attachmentUploadCardsStyles}>
         <FluentV9ThemeProvider v8Theme={theme}>
           <_AttachmentUploadCards
-            activeAttachmentUploads={attachmentMetadata}
+            attachmentsWithProgress={attachmentMetadata}
             onCancelAttachmentUpload={onCancelAttachmentUpload}
           />
         </FluentV9ThemeProvider>