Enhance documentation for Image and Video components; update transformation handling in snapshots

Author: manu4543

src/components/Image.tsx

@@ -5,13 +5,18 @@ import { ImageKitContext } from "../provider/ImageKit";
 
 export type IKImageProps = Omit<JSX.IntrinsicElements["img"], "src" | "srcSet" | "width"> & SrcProps & {
   /**
-   * Set to `false` to disable responsive srcset generation. By default, this is `true`.
+   * Set to `false` to disable automatic responsive `srcSet` generation.
+   * Defaults to `true`.
    */
   responsive?: boolean;
 
   /**
-   * The width of the image. This is used to calculate the srcset for responsive images. Provide in number or string format e.g. 100, "100".
-   * If values like "100px" or "100%" are provided, srcset calculation will ignore the value of width and generate a much larger srcset to cater to all possible widths.
+   * The intended display width of the image.
+   *
+   * - Accepts a number (e.g. `100`) or a numeric string (e.g. `"100"`).
+   * - If you pass units such as `"100px"` or a percentage like `"100%"`, the value
+   *   is ignored when generating the `srcSet`. In that case, a broad range of
+   *   widths is produced to cover all possible viewport sizes.
    */
   width?: number | `${number}`;
 }
@@ -32,30 +37,36 @@ function getInt(x: unknown): number {
 
 
 /**
- * The Image component is a wrapper around the React Image component. It supports all the features of the React Image component, along with additional features provided by ImageKit.
- * 
+ * A React wrapper around the native `<img>` element that adds ImageKit's
+ * optimization and transformation capabilities.
+ *
+ * All native `<img>` props are supported, in addition to the ImageKit‑specific props.
+ *
  * @example
  * ```jsx
  * import { Image } from "@imagekit/react";
+ *
  * <Image
- *  urlEndpoint="https://ik.imagekit.io/your_imagekit_id" // You can also set this in a parent ImageKitProvider component
- *  src="/default-image.jpg" // The path to the image in your ImageKit account
- *  alt="Default Image"
- *  width={500}
- *  height={500}
- *  transformation={[{ width: 500, height: 500 }]} // Add ImageKit transformations
+ *   urlEndpoint="https://ik.imagekit.io/your_imagekit_id" // Can also be set on a parent <ImageKitProvider />
+ *   src="/default-image.jpg"                               // Path in your ImageKit account
+ *   alt="Default image"
+ *   width={500}
+ *   height={500}
+ *   transformation={[{ width: 500, height: 500 }]}         // Optional ImageKit transformations
  * />
  * ```
  */
 export const Image = (props: IKImageProps) => {
   const contextValues = useContext(ImageKitContext);
 
-  // Its important to extract the ImageKit specific props from the props, so that we can use the rest of the props as is in the img element
+  // It's important to extract the ImageKit‑specific props so we can spread the
+  // remaining props directly onto the `<img>` element.
   const { transformation = [], src = "", loading = "lazy", queryParameters, urlEndpoint, transformationPosition, sizes, responsive = true, ...nonIKParams } = {
     ...contextValues, // Default values from context
     ...props // Override with props
   };
 
+  // Fail fast in development if the mandatory urlEndpoint is missing.
   if (!urlEndpoint || urlEndpoint.trim() === "") {
     if (process.env.NODE_ENV !== "production") {
       console.error("urlEndpoint is neither provided in this component nor in the ImageKitContext.");

src/components/Video.tsx

@@ -25,12 +25,13 @@ export type IKVideoProps = Omit<JSX.IntrinsicElements["video"], "src"> & SrcProp
 export const Video = (props: IKVideoProps) => {
   const contextValues = useContext(ImageKitContext);
 
-  // Its important to extract the ImageKit specific props from the props, so that we can use the rest of the props as is in the video element
+  // Extract ImageKit‑specific props so we can spread the rest directly onto <video>.
   const { transformation = [], src = "", queryParameters, urlEndpoint, transformationPosition, ...nonIKParams } = {
     ...contextValues, // Default values from context
     ...props // Override with props
   };
 
+  // Fail fast in development if the mandatory urlEndpoint is missing.
   if (!urlEndpoint || urlEndpoint.trim() === "") {
     if (process.env.NODE_ENV !== "production") {
       console.error("urlEndpoint is neither provided in this component nor in the ImageKitContext.");
@@ -43,7 +44,8 @@ export const Video = (props: IKVideoProps) => {
     urlEndpoint,
     src,
     transformation: [...transformation], // Do not mutate original transformation array from the props
-    queryParameters
+    queryParameters,
+    transformationPosition,
   });
 
   return (

test-app/app/components/basic.tsx

@@ -192,6 +192,17 @@ export const Basic = () => {
                     transformation={[{ height: 100, width: 100 }]}
                     controls={true}
                 />
+
+                {/* transformationPosition="path" */}
+                <Video
+                    src="sample-video.mp4"
+                    title="Video with path transformation"
+                    transformationPosition="path"
+                    height={300}
+                    width={300}
+                    transformation={[{ height: 100, width: 100 }]}
+                />
+
             </ImageKitProvider>
         </div>
     )

test-app/e2e/__snapshot__/csr.spec.ts/CSR-test-case-1.txt

@@ -1 +1 @@
-<div class="container"><div><h1>Image</h1><img alt="Image without ImageKit provider" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with ImageKit provider" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with width not number, should produce larger srcset" width="300px" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 640w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-750,c-at_max 750w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-828,c-at_max 828w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1080,c-at_max 1080w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1200,c-at_max 1200w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1920,c-at_max 1920w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-2048,c-at_max 2048w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max 3840w" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max"><img alt="With transformation" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=h-100,w-100:w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=h-100,w-100:w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=h-100,w-100:w-640,c-at_max"><img alt="Image with queryParameters" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?version=v1&amp;tr=h-100,w-100:w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?version=v1&amp;tr=h-100,w-100:w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?version=v1&amp;tr=h-100,w-100:w-640,c-at_max"><img alt="Responsive image with sizes" height="300" width="300" loading="lazy" sizes="(max-width: 600px) 100vw, 50vw" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 384w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 640w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-750,c-at_max 750w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-828,c-at_max 828w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1080,c-at_max 1080w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1200,c-at_max 1200w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1920,c-at_max 1920w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-2048,c-at_max 2048w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max 3840w" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max"><img alt="Responsive image with sizes - should have very large srcset for all breakpoints" height="300" width="300" loading="lazy" sizes="300px" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-16,c-at_max 16w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-32,c-at_max 32w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-48,c-at_max 48w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-64,c-at_max 64w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-96,c-at_max 96w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-128,c-at_max 128w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-256,c-at_max 256w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 384w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 640w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-750,c-at_max 750w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-828,c-at_max 828w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1080,c-at_max 1080w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1200,c-at_max 1200w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1920,c-at_max 1920w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-2048,c-at_max 2048w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max 3840w" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max"><img alt="Image with urlEndpoint override" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo2/default-image.jpg?tr=h-100,w-100:w-384,c-at_max 1x, https://ik.imagekit.io/demo2/default-image.jpg?tr=h-100,w-100:w-640,c-at_max 2x" src="https://ik.imagekit.io/demo2/default-image.jpg?tr=h-100,w-100:w-640,c-at_max"><img alt="Image with className" class="custom-class" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with lazy loading eager" height="300" width="300" loading="eager" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with path transformation" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/tr:w-384,c-at_max/default-image.jpg 1x, https://ik.imagekit.io/demo/tr:w-640,c-at_max/default-image.jpg 2x" src="https://ik.imagekit.io/demo/tr:w-640,c-at_max/default-image.jpg"><img alt="Image with path transformation + custom transformations" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/tr:h-100,w-100:w-384,c-at_max/default-image.jpg 1x, https://ik.imagekit.io/demo/tr:h-100,w-100:w-640,c-at_max/default-image.jpg 2x" src="https://ik.imagekit.io/demo/tr:h-100,w-100:w-640,c-at_max/default-image.jpg"><img alt="path not respected with absolute url" height="300" width="300" loading="lazy" srcset="https://ik.imagekit/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with responsive off" height="300" width="300" loading="lazy" src="https://ik.imagekit.io/demo/default-image.jpg?tr=n-restrict-unnamed:w-3840,c-at_max"><h1>Video</h1><video title="Video without ImageKit provider" height="300" width="300" controls="" src="https://ik.imagekit.io/demo/sample-video.mp4"></video><video title="Video with ImageKit provider" height="300" width="300" controls="" src="https://ik.imagekit.io/demo/sample-video.mp4"></video><video title="Video with transformations" height="300" width="300" controls="" src="https://ik.imagekit.io/demo/sample-video.mp4?tr=h-100,w-100"></video><video title="Video with all props" height="300" width="300" controls="" autoplay="" loop="" playsinline="" preload="none" poster="https://ik.imagekit.io/demo/default-image.jpg" src="https://ik.imagekit.io/demo/sample-video.mp4"></video><video title="Video with urlEndpoint override" height="300" width="300" controls="" src="https://ik.imagekit.io/demo2/sample-video.mp4?tr=h-100,w-100"></video></div></div>
+<div class="container"><div><h1>Image</h1><img alt="Image without ImageKit provider" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with ImageKit provider" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with width not number, should produce larger srcset" width="300px" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 640w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-750,c-at_max 750w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-828,c-at_max 828w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1080,c-at_max 1080w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1200,c-at_max 1200w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1920,c-at_max 1920w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-2048,c-at_max 2048w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max 3840w" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max"><img alt="With transformation" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=h-100,w-100:w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=h-100,w-100:w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=h-100,w-100:w-640,c-at_max"><img alt="Image with queryParameters" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?version=v1&amp;tr=h-100,w-100:w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?version=v1&amp;tr=h-100,w-100:w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?version=v1&amp;tr=h-100,w-100:w-640,c-at_max"><img alt="Responsive image with sizes" height="300" width="300" loading="lazy" sizes="(max-width: 600px) 100vw, 50vw" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 384w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 640w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-750,c-at_max 750w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-828,c-at_max 828w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1080,c-at_max 1080w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1200,c-at_max 1200w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1920,c-at_max 1920w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-2048,c-at_max 2048w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max 3840w" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max"><img alt="Responsive image with sizes - should have very large srcset for all breakpoints" height="300" width="300" loading="lazy" sizes="300px" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-16,c-at_max 16w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-32,c-at_max 32w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-48,c-at_max 48w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-64,c-at_max 64w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-96,c-at_max 96w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-128,c-at_max 128w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-256,c-at_max 256w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 384w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 640w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-750,c-at_max 750w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-828,c-at_max 828w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1080,c-at_max 1080w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1200,c-at_max 1200w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-1920,c-at_max 1920w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-2048,c-at_max 2048w, https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max 3840w" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-3840,c-at_max"><img alt="Image with urlEndpoint override" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo2/default-image.jpg?tr=h-100,w-100:w-384,c-at_max 1x, https://ik.imagekit.io/demo2/default-image.jpg?tr=h-100,w-100:w-640,c-at_max 2x" src="https://ik.imagekit.io/demo2/default-image.jpg?tr=h-100,w-100:w-640,c-at_max"><img alt="Image with className" class="custom-class" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with lazy loading eager" height="300" width="300" loading="eager" srcset="https://ik.imagekit.io/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit.io/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with path transformation" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/tr:w-384,c-at_max/default-image.jpg 1x, https://ik.imagekit.io/demo/tr:w-640,c-at_max/default-image.jpg 2x" src="https://ik.imagekit.io/demo/tr:w-640,c-at_max/default-image.jpg"><img alt="Image with path transformation + custom transformations" height="300" width="300" loading="lazy" srcset="https://ik.imagekit.io/demo/tr:h-100,w-100:w-384,c-at_max/default-image.jpg 1x, https://ik.imagekit.io/demo/tr:h-100,w-100:w-640,c-at_max/default-image.jpg 2x" src="https://ik.imagekit.io/demo/tr:h-100,w-100:w-640,c-at_max/default-image.jpg"><img alt="path not respected with absolute url" height="300" width="300" loading="lazy" srcset="https://ik.imagekit/demo/default-image.jpg?tr=w-384,c-at_max 1x, https://ik.imagekit/demo/default-image.jpg?tr=w-640,c-at_max 2x" src="https://ik.imagekit/demo/default-image.jpg?tr=w-640,c-at_max"><img alt="Image with responsive off" height="300" width="300" loading="lazy" src="https://ik.imagekit.io/demo/default-image.jpg?tr=n-restrict-unnamed:w-3840,c-at_max"><h1>Video</h1><video title="Video without ImageKit provider" height="300" width="300" controls="" src="https://ik.imagekit.io/demo/sample-video.mp4"></video><video title="Video with ImageKit provider" height="300" width="300" controls="" src="https://ik.imagekit.io/demo/sample-video.mp4"></video><video title="Video with transformations" height="300" width="300" controls="" src="https://ik.imagekit.io/demo/sample-video.mp4?tr=h-100,w-100"></video><video title="Video with all props" height="300" width="300" controls="" autoplay="" loop="" playsinline="" preload="none" poster="https://ik.imagekit.io/demo/default-image.jpg" src="https://ik.imagekit.io/demo/sample-video.mp4"></video><video title="Video with urlEndpoint override" height="300" width="300" controls="" src="https://ik.imagekit.io/demo2/sample-video.mp4?tr=h-100,w-100"></video><video title="Video with path transformation" height="300" width="300" src="https://ik.imagekit.io/demo/tr:h-100,w-100/sample-video.mp4"></video></div></div>