feat: add support for new overlay position parameters xCenter, yCenter, and anchorPoint

Author: manu4543

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Version 5.3.0
+
+1. **Enhancement:**
+   - Added support for new overlay position parameters: `xCenter` (`lxc`), `yCenter` (`lyc`), and `anchorPoint` (`lap`) in overlay transformations
+
 ## Version 5.2.2
 
 1. Updated TypeScript types to allow string values for the `dpr` parameter in transformations, enabling support for arithmetic expressions and dynamic DPR values.

package-lock.json

@@ -1,6 +1,6 @@
 {
     "name": "@imagekit/javascript",
-    "version": "5.2.2",
+    "version": "5.3.0",
     "description": "ImageKit Javascript SDK",
     "main": "dist/imagekit.cjs.js",
     "module": "dist/imagekit.esm.js",

package.json

@@ -136,12 +136,6 @@ export namespace ExtensionConfig {
        */
       type: 'select_tags';
 
-      /**
-       * Array of possible tag values. Combined length of all strings must not exceed 500
-       * characters. Cannot contain the `%` character.
-       */
-      vocabulary: Array<string>;
-
       /**
        * Maximum number of tags to select from the vocabulary.
        */
@@ -151,6 +145,14 @@ export namespace ExtensionConfig {
        * Minimum number of tags to select from the vocabulary.
        */
       min_selections?: number;
+
+      /**
+       * Array of possible tag values. The combined length of all strings must not exceed
+       * 500 characters, and values cannot include the `%` character. When providing
+       * large vocabularies (more than 30 items), the AI may not follow the list
+       * strictly.
+       */
+      vocabulary?: Array<string>;
     }
 
     export interface SelectMetadata {
@@ -181,7 +183,10 @@ export namespace ExtensionConfig {
       min_selections?: number;
 
       /**
-       * Array of possible values matching the custom metadata field type.
+       * An array of possible values matching the custom metadata field type. If not
+       * provided for SingleSelect or MultiSelect field types, all values from the custom
+       * metadata field definition will be used. When providing large vocabularies (above
+       * 30 items), the AI may not strictly adhere to the list.
        */
       vocabulary?: Array<string | number | boolean>;
     }
@@ -457,12 +462,6 @@ export namespace Extensions {
        */
       type: 'select_tags';
 
-      /**
-       * Array of possible tag values. Combined length of all strings must not exceed 500
-       * characters. Cannot contain the `%` character.
-       */
-      vocabulary: Array<string>;
-
       /**
        * Maximum number of tags to select from the vocabulary.
        */
@@ -472,6 +471,14 @@ export namespace Extensions {
        * Minimum number of tags to select from the vocabulary.
        */
       min_selections?: number;
+
+      /**
+       * Array of possible tag values. The combined length of all strings must not exceed
+       * 500 characters, and values cannot include the `%` character. When providing
+       * large vocabularies (more than 30 items), the AI may not follow the list
+       * strictly.
+       */
+      vocabulary?: Array<string>;
     }
 
     export interface SelectMetadata {
@@ -502,7 +509,10 @@ export namespace Extensions {
       min_selections?: number;
 
       /**
-       * Array of possible values matching the custom metadata field type.
+       * An array of possible values matching the custom metadata field type. If not
+       * provided for SingleSelect or MultiSelect field types, all values from the custom
+       * metadata field definition will be used. When providing large vocabularies (above
+       * 30 items), the AI may not strictly adhere to the list.
        */
       vocabulary?: Array<string | number | boolean>;
     }
@@ -782,8 +792,25 @@ export type Overlay = TextOverlay | ImageOverlay | VideoOverlay | SubtitleOverla
 
 export interface OverlayPosition {
   /**
-   * Specifies the position of the overlay relative to the parent image or video.
-   * Maps to `lfo` in the URL.
+   * Sets the anchor point on the base asset from which the overlay offset is
+   * calculated. The default value is `top_left`. Maps to `lap` in the URL. Can only
+   * be used with one or more of `x`, `y`, `xCenter`, or `yCenter`.
+   */
+  anchorPoint?:
+    | 'top'
+    | 'left'
+    | 'right'
+    | 'bottom'
+    | 'top_left'
+    | 'top_right'
+    | 'bottom_left'
+    | 'bottom_right'
+    | 'center';
+
+  /**
+   * Specifies the position of the overlay relative to the parent image or video. If
+   * one or more of `x`, `y`, `xCenter`, or `yCenter` parameters are specified, this
+   * parameter is ignored. Maps to `lfo` in the URL.
    */
   focus?:
     | 'center'
@@ -805,6 +832,15 @@ export interface OverlayPosition {
    */
   x?: number | string;
 
+  /**
+   * Specifies the x-coordinate on the base asset where the overlay's center will be
+   * positioned. It also accepts arithmetic expressions such as `bw_mul_0.4` or
+   * `bw_sub_cw`. Maps to `lxc` in the URL. Cannot be used together with `x`, but can
+   * be used with `y`. Learn about
+   * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations).
+   */
+  xCenter?: number | string;
+
   /**
    * Specifies the y-coordinate of the top-left corner of the base asset where the
    * overlay's top-left corner will be positioned. It also accepts arithmetic
@@ -813,6 +849,15 @@ export interface OverlayPosition {
    * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations).
    */
   y?: number | string;
+
+  /**
+   * Specifies the y-coordinate on the base asset where the overlay's center will be
+   * positioned. It also accepts arithmetic expressions such as `bh_mul_0.4` or
+   * `bh_sub_ch`. Maps to `lyc` in the URL. Cannot be used together with `y`, but can
+   * be used with `x`. Learn about
+   * [Arithmetic expressions](https://imagekit.io/docs/arithmetic-expressions-in-transformations).
+   */
+  yCenter?: number | string;
 }
 
 export interface OverlayTiming {

src/interfaces/shared.ts

@@ -196,13 +196,22 @@ function processOverlay(overlay: Transformation["overlay"]): string | undefined
     entries.push(`lm-${layerMode}`);
   }
 
-  const { x, y, focus } = position;
+  const { x, y, xCenter, yCenter, anchorPoint, focus } = position;
   if (x) {
     entries.push(`lx-${x}`);
   }
   if (y) {
     entries.push(`ly-${y}`);
   }
+  if (xCenter) {
+    entries.push(`lxc-${xCenter}`);
+  }
+  if (yCenter) {
+    entries.push(`lyc-${yCenter}`);
+  }
+  if (anchorPoint) {
+    entries.push(`lap-${anchorPoint}`);
+  }
   if (focus) {
     entries.push(`lfo-${focus}`);
   }

src/url.ts

@@ -579,5 +579,25 @@ describe("Overlay encoding test cases", function () {
             });
             expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-overlay-image.jpg,lm-displace,lx-10,ly-10,l-end/base-image.jpg`);
         });
+
+        it('should generate correct URL with xCenter, yCenter and anchorPoint', function () {
+            const url = buildSrc({
+                transformationPosition: "path",
+                urlEndpoint: "https://ik.imagekit.io/test_url_endpoint",
+                src: "/base-image.jpg",
+                transformation: [{
+                    overlay: {
+                        type: "image",
+                        input: "overlay-image.jpg",
+                        position: {
+                            xCenter: 100,
+                            yCenter: 50,
+                            anchorPoint: "top_left"
+                        }
+                    }
+                }]
+            });
+            expect(url).equal(`https://ik.imagekit.io/test_url_endpoint/tr:l-image,i-overlay-image.jpg,lxc-100,lyc-50,lap-top_left,l-end/base-image.jpg`);
+        });
     });
 });