docs: Image sizing guide

Author: szuperaz

docusaurus/docs/Angular/assets/image-sizing-screenshot-1.png

@@ -1,6 +1,9 @@
 import AttachmentsScreenshot from "../assets/attachments-screenshot.png";
+import ImageSizingScreenshot1 from "../assets/image-sizing-screenshot-1.png";
+import ImageSizingScreenshot2 from "../assets/image-sizing-screenshot-2.png";
+import ImageSizingScreenshot3 from "../assets/image-sizing-screenshot-3.png";
 
-The `AttachmentList` compontent displays the attachments of a message. The following attachments are supported:
+The `AttachmentList` component displays the attachments of a message. The following attachments are supported:
 
 - Images (including GIFs) are displayed inline
 - Videos are displayed inline
@@ -40,5 +43,53 @@ You can use the [`AttachmentConfigurationService`](../services/AttachmentConfigu
 
 You can provide your own attachment list component by the [`CustomTemplatesService`](../services/CustomTemplatesService.mdx)
 
+### 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 size 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).
+
+:::tip
+If you're unsure about the value you provided for `--str-chat__attachment-max-width`, send an image/video to a channel, then inspect the `img`/`video` element inside the message list using your browser's development tools. Inside the **computed** properties of the element, you should see that `max-height` and `max-width` are set to a valid pixel value.
+:::
+
+#### File size optimization
+
+Based on the CSS settings provided for images and videos, 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.
+
+#### Aspect ratio
+
+The SDK will try to display images and videos with their original aspect ratio, however this isn't always guaranteed. 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
+
+<img src={ImageSizingScreenshot1} width="200" />
+
+**Example 2** - message with multiple lines of text
+
+<img src={ImageSizingScreenshot2} width="200" />
+
+2. in Safari, images/videos with portrait orientation are stretched to `max-width`
+
+**Example 3** - portrait images in Safari
+
+<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 [`AttachmentConfigurationService`](../services/AttachmentConfigurationService.mdx).
+:::
+
+:::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 inside the [`AttachmentConfigurationService`](../services/AttachmentConfigurationService.mdx) 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).
+:::
+
 [//]: # "Start of generated content"
 [//]: # "End of generated content"