Merge pull request #1773 from GetStream/cdn-integration-review-proposals

feat: new CDN integration

Author: szuperaz

.env.example

@@ -5,6 +5,7 @@ E2E_TEST_USER_1_TOKEN='test-user-1-jwt'
 E2E_TEST_USER_2='test-user-2'
 E2E_TEST_USER_2_TOKEN='test-user-2-jwt'
 E2E_JUMP_TO_MESSAGE_CHANNEL='jump-to-message'
+E2E_ATTACHMENT_SIZING_CHANNEL='attachment-sizing'
 E2E_ADD_MESSAGE_CHANNEL='add-message'
 E2E_ADDITIONAL_CHANNELS="mr-channel-1,mr-channel-2,edit-message-channel,pin-message-channel"
 E2E_LONG_MESSAGE_LISTS_CHANNEL='navigate-long-message-lists'

.github/workflows/ci.yml

@@ -56,6 +56,7 @@ jobs:
           E2E_TEST_USER_2_TOKEN: ${{ secrets.E2E_TEST_USER_2_TOKEN }}
           E2E_ADDITIONAL_CHANNELS: mr-channel-1, mr-channel-2, edit-message-channel, pin-message-channel
           E2E_LONG_MESSAGE_LISTS_CHANNEL: navigate-long-message-lists
+          E2E_ATTACHMENT_SIZING_CHANNEL: attachment-sizing
 
       - name: 🎥 Upload Artifacts
         uses: actions/upload-artifact@v3

docusaurus/docs/React/assets/AttachmentSizeWarning.png

@@ -69,9 +69,17 @@ Error object (if any) in loading the `channel`, otherwise null.
 
 The giphy version to use when displaying giphies.
 
-| Type                                                                                                                                                |
-| --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `'original' | 'fixed_height' | 'fixed_height_still' | 'fixed_height_downsampled' | 'fixed_width' | 'fixed_width_still' | 'fixed_width_downsampled'` |
+| Type                                                                                                                                                                  |
+| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'original'` \| `'fixed_height'` \| `'fixed_height_still'` \| `'fixed_height_downsampled'` \| `'fixed_width'` \| `'fixed_width_still'` \| `'fixed_width_downsampled'` |
+
+### imageAttachmentSizeHandler
+
+A custom function to provide size configuration for image attachments
+
+| Type                                                             |
+| ---------------------------------------------------------------- |
+| `(a: Attachment, e: HTMLElement) => ImageAttachmentConfigration` |
 
 ### hasMore
 
@@ -202,6 +210,13 @@ Flag signalling whether the scroll to the bottom is prevented. Used internally b
 | Type    |
 |---------|
 | boolean |
+### shouldGenerateVideoThumbnail
+
+You can turn on/off thumbnail generation for video attachments
+
+| Type      |
+| --------- |
+| `boolean` |
 
 ### thread
 
@@ -242,6 +257,13 @@ Flag signalling whether the scroll to the bottom is prevented in thread. Used in
 | Type    |
 |---------|
 | boolean |
+### videoAttachmentSizeHandler
+
+A custom function to provide size configuration for video attachments
+
+| Type                                                              |
+| ----------------------------------------------------------------- |
+| `(a: Attachment, e: HTMLElement) => VideoAttachmentConfiguration` |
 
 ### watcherCount
 

docusaurus/docs/React/assets/ImageSizing1.png

@@ -300,9 +300,17 @@ Custom UI component to render a Giphy preview in the `VirtualizedMessageList`.
 The Giphy version to render - check the keys of the [Image Object](https://developers.giphy.com/docs/api/schema#image-object) for possible values.
 
 | Type   | Default        |
-|--------|----------------|
+| ------ | -------------- |
 | string | 'fixed_height' |
 
+### imageAttachmentSizeHandler
+
+A custom function to provide size configuration for image attachments
+
+| Type                                                             |
+| ---------------------------------------------------------------- |
+| `(a: Attachment, e: HTMLElement) => ImageAttachmentConfigration` |
+
 ### HeaderComponent
 
 Custom UI component to render at the top of the `MessageList`.
@@ -503,6 +511,14 @@ Custom UI component for send button.
 |-----------|---------------------------------------------------------------------|
 | component | <GHComponentLink text='SendButton' path='/MessageInput/icons.tsx'/> |
 
+### shouldGenerateVideoThumbnail
+
+You can turn on/off thumbnail generation for video attachments
+
+| Type     |
+| -------- |
+| `boolean` |
+
 ### skipMessageDataMemoization
 
 If true, skips the message data string comparison used to memoize the current channel messages (helpful for channels with 1000s of messages).
@@ -560,6 +576,14 @@ Custom UI component for the typing indicator.
 |-----------|---------------------------------------------------------------------------------------|
 | component | <GHComponentLink text='TypingIndicator' path='/TypingIndicator/TypingIndicator.tsx'/> |
 
+### videoAttachmentSizeHandler
+
+A custom function to provide size configuration for video attachments
+
+| Type                                                              |
+| ----------------------------------------------------------------- |
+| `(a: Attachment, e: HTMLElement) => VideoAttachmentConfiguration` |
+
 ### VirtualMessage
 
 Custom UI component to display a message in the `VirtualizedMessageList`.

docusaurus/docs/React/assets/ImageSizing2.png

@@ -6,7 +6,10 @@ title: Attachments
 
 import GHComponentLink from '../_docusaurus-components/GHComponentLink';
 import ReviewNote from '../_docusaurus-components/ReviewNote';
-
+import ImageSizingScreenshot1 from '../assets/ImageSizing1.png';
+import ImageSizingScreenshot2 from '../assets/ImageSizing2.png';
+import ImageSizingScreenshot3 from '../assets/ImageSizing3.png';
+import AttachmentSizeWarning from '../assets/AttachmentSizeWarning.png';
 
 The `Attachment` component takes a list of message attachments and conditionally renders the UI of each individual attachment based
 upon its type. The following table shows the attachment UI components that will be rendered for various attachment types:
@@ -36,7 +39,7 @@ const CustomMessage = () => {
 
   return (
     <div>
-      { hasAttachments && <Attachment attachments={message.attachments} />}
+      {hasAttachments && <Attachment attachments={message.attachments} />}
       // render remaining custom Message UI
     </div>
   );
@@ -103,6 +106,58 @@ const CustomAttachment = (props) => {
 </Chat>;
 ```
 
+### Image and video sizing
+
+The following section details how the width and height of images and videos uploaded from files are computed.
+
+#### Maximum size
+
+You can control the maximum width and height of images and videos with the [`--str-chat__attachment-max-width`](../theming/component-variables.mdx) CSS variable (available only in [theme-v2](../theming/introduction.mdx)). The value of this variable must be a value that can be computed to a valid pixel value using the [`getComputedStyle`](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle) method (for example: `300px`, `10rem`, `calc(300px - var(--margin))`, but not `100%`). If you provide an invalid value, the image and video sizing can break, which can lead to scrolling issues inside the message list (for example the message list isn't scrolled to the bottom when you open a channel).
+
+If you set an invalid value to the variable, you'll see a warning on the browser's console:
+
+<img src={AttachmentSizeWarning} width='800' />
+
+#### File size optimization
+
+Based on the CSS settings provided for images and videos (see [Maximum size](#maximum-size) section), the SDK will load an image (or thumbnail image in case of a video file) with a reduced file size while still providing sufficient image quality for the given dimensions. This will result in less network traffic and faster image load for users.
+
+For example if an image has `max-width` and `max-height` set to `300px` and the original image has the following dimensions: `965 × 1280` it's enough to load an image with a reduced file size, file size reduction is done by Stream's CDN.
+
+#### Aspect ratio
+
+The following description is applicable for [theme-v2](../theming/introduction.mdx).
+
+The SDK will try to display images and videos with their original aspect ratio, however this isn't always guaranteed (in those cases a cropped image will be displayed). Three notable exceptions are:
+
+1. if a message contains multiple lines of texts and/or multiple attachments, the image/video might be stretched to its `max-width`
+
+**Example 1** - message with one line of text - image is displayed with original aspect ratio
+
+<img src={ImageSizingScreenshot1} width='200' />
+
+**Example 2** - message with multiple lines of text - image is cropped
+
+<img src={ImageSizingScreenshot2} width='200' />
+
+2. in Safari, images/videos with portrait orientation are stretched to `max-width`
+
+**Example 3** - portrait images in Safari - image is cropped
+
+<img src={ImageSizingScreenshot3} width='200' />
+
+3. if the image/video can't be rendered with the original aspect ratio given the `max-width` and `max-height` constraints of the host HTML element
+
+:::important
+**File size optimization** and maintaining **aspect ratio** uses features provided by Stream's CDN. If you're using your **own CDN** you'll likely have to provide your own implementation for this. You can do this using the [`imageAttachmentSizeHandler`](../core-components/channel.mdx/#imageattachmentsizehandler) and [`videoAttachmentSizeHandler`](../core-components/channel.mdx/#videoattachmentsizehandler) props.
+:::
+
+:::danger
+**If you're planning to rewrite attachment sizing with your own CSS code** it's important to note that:
+
+The sizing logic for images and videos (the [`imageAttachmentSizeHandler`](../core-components/channel.mdx/#imageattachmentsizehandler) and [`videoAttachmentSizeHandler`](../core-components/channel.mdx/#videoattachmentsizehandler)) requires that host elements of images and videos (ususally `img` and `video` elements) have `max-height`/`height` and `max-width` properties defined and that these values can be computed to a valid pixel value using the [`getComputedStyle`](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle) (for more information refer to the [Maximum size](#maximum-size) section).
+:::
+
 ## Props
 
 ### <div class="label required basic">Required</div> attachments
@@ -122,61 +177,57 @@ The handler function to call when an action is performed on an attachment, examp
 | ----------------------------------------------------------------------------------------------------- |
 | (dataOrName?: string \| FormData, value?: string, event?: React.BaseSyntheticEvent) => Promise<void\> |
 
-
-
-<ReviewNote
-  author='Martin Cupela'
-  id='04803878-3362-11ed-8912-a4bb6d26ac2f'
->
-  What are attachment actions, what is their use case / recipes? Missing concept explanation. It would be nice to have a link to a doc explaining these.
+<ReviewNote author='Martin Cupela' id='04803878-3362-11ed-8912-a4bb6d26ac2f'>
+  What are attachment actions, what is their use case / recipes? Missing concept explanation. It
+  would be nice to have a link to a doc explaining these.
 </ReviewNote>
 
 ### AttachmentActions
 
 Custom UI component for displaying attachment actions.
 
 | Type      | Default                                                                              |
-|-----------|--------------------------------------------------------------------------------------|
+| --------- | ------------------------------------------------------------------------------------ |
 | component | <GHComponentLink text='AttachmentActions' path='/Attachment/AttachmentActions.tsx'/> |
 
 ### Audio
 
 Custom UI component for displaying an audio type attachment.
 
 | Type      | Default                                                      |
-|-----------|--------------------------------------------------------------|
+| --------- | ------------------------------------------------------------ |
 | component | <GHComponentLink text='Audio' path='/Attachment/Audio.tsx'/> |
 
 ### Card
 
 Custom UI component for displaying a card type attachment.
 
 | Type      | Default                                                    |
-|-----------|------------------------------------------------------------|
+| --------- | ---------------------------------------------------------- |
 | component | <GHComponentLink text='Card' path='/Attachment/Card.tsx'/> |
 
 ### File
 
 Custom UI component for displaying a file type attachment.
 
 | Type      | Default                                                              |
-|-----------|----------------------------------------------------------------------|
+| --------- | -------------------------------------------------------------------- |
 | component | <GHComponentLink text='File' path='/Attachment/FileAttachment.tsx'/> |
 
 ### Gallery
 
 Custom UI component for displaying a gallery of image type attachments.
 
 | Type      | Default                                                       |
-|-----------|---------------------------------------------------------------|
+| --------- | ------------------------------------------------------------- |
 | component | <GHComponentLink text='Gallery' path='/Gallery/Gallery.tsx'/> |
 
 ### Image
 
 Custom UI component for displaying an image type attachment.
 
 | Type      | Default                                                   |
-|-----------|-----------------------------------------------------------|
+| --------- | --------------------------------------------------------- |
 | component | <GHComponentLink text='Image' path='/Gallery/Image.tsx'/> |
 
 ### Media

docusaurus/docs/React/assets/ImageSizing3.png

@@ -0,0 +1,66 @@
+import * as dotenv from 'dotenv';
+import { expect } from '@playwright/test';
+
+import selectors from './user/selectors';
+import { test } from './user/test';
+
+import ChannelPreview from './user/components/ChannelPreview';
+import MessageList from './user/components/MessageList/MessageList';
+
+dotenv.config();
+dotenv.config({ path: `.env.local` });
+
+const CHANNEL_NAME = 'attachment-sizing' as const;
+const user1Id = process.env.E2E_TEST_USER_1;
+const USER1_CHAT_VIEW_CLASSNAME = `.${user1Id}`;
+
+test.describe('add height to video and image attachments', () => {
+  test.beforeEach(async ({ controller, user }) => {
+    await controller.openStory('attachment-sizing--user1', selectors.channelPreviewButton);
+    await user.clicks(ChannelPreview).text(CHANNEL_NAME);
+  });
+
+  test('should add height for video attachments', async ({ page, user }) => {
+    const videoElementsLocator = page.locator('[data-testid="video-wrapper"]');
+    const result = await videoElementsLocator.evaluateAll<boolean>(
+      (videoElements) =>
+        videoElements.length > 0 &&
+        videoElements.every((element) => getComputedStyle(element).height.includes('px')),
+    );
+
+    expect(result).toBeTruthy();
+    await user
+      .sees(MessageList)
+      .isScrolledToBottom(`${USER1_CHAT_VIEW_CLASSNAME} ${selectors.messageList}`);
+  });
+
+  test('should add height for single image attachments', async ({ page, user }) => {
+    const imageElementsLocator = page.locator('[data-testid="image-test"]');
+    const result = await imageElementsLocator.evaluateAll(
+      (imageElements) =>
+        imageElements.length > 0 &&
+        imageElements.every((element) => getComputedStyle(element).height.includes('px')),
+    );
+
+    expect(result).toBe(true);
+    await user
+      .sees(MessageList)
+      .isScrolledToBottom(`${USER1_CHAT_VIEW_CLASSNAME} ${selectors.messageList}`);
+  });
+
+  test('should add height for gallery image attachments', async ({ page, user }) => {
+    const imageElementsLocator = page.locator(
+      '[data-testid="gallery-image-last"],[data-testid="gallery-image"]',
+    );
+    const result = await imageElementsLocator.evaluateAll(
+      (imageElements) =>
+        imageElements.length > 0 &&
+        imageElements.every((element) => getComputedStyle(element).height.includes('px')),
+    );
+
+    expect(result).toBe(true);
+    await user
+      .sees(MessageList)
+      .isScrolledToBottom(`${USER1_CHAT_VIEW_CLASSNAME} ${selectors.messageList}`);
+  });
+});