feat: enhance transformation handling with nested layer support and child key validation

Author: manu4543

packages/imagekit-editor-dev/src/backward-compatibility.test.ts

@@ -1468,6 +1468,196 @@ describe("Backward Compatibility - V1 Templates", () => {
       expect(findTransformationDeep(tree, "deep")?.name).toBe("Deep")
       expect(findTransformationDeep(tree, "missing")).toBeUndefined()
     })
+
+    it("non-layer child (ai-removedotbg) is appended as a chained step inside the parent layer", async () => {
+      const { buildSrc } = await import("@imagekit/javascript")
+      const { convertTransformationToIK } = await import(
+        "./transformationConverter"
+      )
+      // Parent has multiple own-params (image url + width + trim) so the SDK
+      // serializes the child with an explicit `:` chain separator. With a
+      // single-param parent the SDK collapses to a `,` joiner — equivalent
+      // ImageKit syntax, but less obvious that the child is a chained step.
+      const parent: Transformation = {
+        id: "p",
+        key: "layers-image",
+        name: "Image Layer",
+        type: "transformation",
+        value: {
+          imageUrl: "photo.jpg",
+          width: "13",
+          trimEnabled: true,
+          trimThreshold: 10,
+        },
+        children: [
+          {
+            id: "c",
+            key: "ai-removedotbg",
+            name: "Remove Background",
+            type: "transformation",
+            value: { removedotbg: true },
+          },
+        ],
+      }
+      const url = buildSrc({
+        urlEndpoint: "https://ik.imagekit.io/demo",
+        src: "/base.jpg",
+        transformation: [convertTransformationToIK(parent)],
+      })
+      expect(url).toBe(
+        "https://ik.imagekit.io/demo/base.jpg?tr=l-image,i-photo.jpg,w-13,t-10:e-removedotbg,l-end",
+      )
+    })
+
+    it("mixes non-layer and nested-layer children in declaration order", async () => {
+      const { buildSrc } = await import("@imagekit/javascript")
+      const { convertTransformationToIK } = await import(
+        "./transformationConverter"
+      )
+      const parent: Transformation = {
+        id: "p",
+        key: "layers-image",
+        name: "Image Layer",
+        type: "transformation",
+        value: { imageUrl: "photo.jpg" },
+        children: [
+          {
+            id: "c1",
+            key: "adjust-blur",
+            name: "Blur",
+            type: "transformation",
+            value: { blur: 5 },
+          },
+          {
+            id: "c2",
+            key: "layers-text",
+            name: "Caption",
+            type: "transformation",
+            value: { text: "Sale", radius: 0 },
+          },
+        ],
+      }
+      const url = buildSrc({
+        urlEndpoint: "https://ik.imagekit.io/demo",
+        src: "/base.jpg",
+        transformation: [convertTransformationToIK(parent)],
+      })
+      expect(url).toBe(
+        "https://ik.imagekit.io/demo/base.jpg?tr=l-image,i-photo.jpg,bl-5:l-text,i-Sale,r-0,l-end,l-end",
+      )
+    })
+
+    it("hidden non-layer child is skipped from the URL", async () => {
+      const { buildSrc } = await import("@imagekit/javascript")
+      const { convertTransformationToIK } = await import(
+        "./transformationConverter"
+      )
+      const parent: Transformation = {
+        id: "p",
+        key: "layers-image",
+        name: "Image Layer",
+        type: "transformation",
+        value: { imageUrl: "photo.jpg" },
+        children: [
+          {
+            id: "c1",
+            key: "adjust-blur",
+            name: "Blur",
+            type: "transformation",
+            value: { blur: 5 },
+            enabled: false,
+          },
+        ],
+      }
+      const url = buildSrc({
+        urlEndpoint: "https://ik.imagekit.io/demo",
+        src: "/base.jpg",
+        transformation: [convertTransformationToIK(parent)],
+      })
+      expect(url).toBe(
+        "https://ik.imagekit.io/demo/base.jpg?tr=l-image,i-photo.jpg,l-end",
+      )
+    })
+
+    it("isAllowedChildKey enforces per-parent allow lists", async () => {
+      const { isAllowedChildKey } = await import("./store")
+
+      // Image layer: liberal allow list including AI + adjust + nested layers.
+      expect(isAllowedChildKey("layers-image", "ai-removedotbg")).toBe(true)
+      expect(isAllowedChildKey("layers-image", "adjust-blur")).toBe(true)
+      expect(isAllowedChildKey("layers-image", "layers-text")).toBe(true)
+      // Delivery transforms are output-only; never valid inside a layer block.
+      expect(isAllowedChildKey("layers-image", "delivery-format")).toBe(false)
+
+      // Canvas layer: tighter list (no blur/AI), but layers still allowed.
+      expect(isAllowedChildKey("layers-canvas", "adjust-radius")).toBe(true)
+      expect(isAllowedChildKey("layers-canvas", "adjust-blur")).toBe(false)
+      expect(isAllowedChildKey("layers-canvas", "ai-removedotbg")).toBe(false)
+      expect(isAllowedChildKey("layers-canvas", "layers-image")).toBe(true)
+
+      // Text layers are leaves: nothing is allowed, including other layers.
+      expect(isAllowedChildKey("layers-text", "adjust-blur")).toBe(false)
+      expect(isAllowedChildKey("layers-text", "adjust-shadow")).toBe(false)
+      expect(isAllowedChildKey("layers-text", "layers-image")).toBe(true)
+      // ^ Note: the layer-keys short-circuit returns true here. The picker
+      // additionally gates on canHostLayerChildren, which excludes text.
+    })
+
+    it("canHostLayerChildren only lets image/canvas host children", async () => {
+      const { canHostLayerChildren } = await import("./store")
+      expect(canHostLayerChildren("layers-image")).toBe(true)
+      expect(canHostLayerChildren("layers-canvas")).toBe(true)
+      expect(canHostLayerChildren("layers-text")).toBe(false)
+      expect(canHostLayerChildren("adjust-blur")).toBe(false)
+    })
+
+    it("getLayerDepth counts only layer ancestors, not non-layer ones", async () => {
+      const { getLayerDepth } = await import("./store")
+      const tree: Transformation[] = [
+        {
+          id: "root",
+          key: "layers-image",
+          name: "Root",
+          type: "transformation",
+          value: { imageUrl: "a.png" },
+          children: [
+            {
+              // Non-layer child of root layer — itself at depth 0 (it has
+              // zero *layer* ancestors above its parent slot).
+              id: "blur",
+              key: "adjust-blur",
+              name: "Blur",
+              type: "transformation",
+              value: { blur: 4 },
+            },
+            {
+              // Nested layer — depth 1.
+              id: "child",
+              key: "layers-image",
+              name: "Child",
+              type: "transformation",
+              value: { imageUrl: "b.png" },
+              children: [
+                {
+                  id: "grand",
+                  key: "layers-text",
+                  name: "Grand",
+                  type: "transformation",
+                  value: { text: "hi", radius: 0 },
+                },
+              ],
+            },
+          ],
+        },
+      ]
+      expect(getLayerDepth(tree, "root")).toBe(0)
+      // Non-layer children inherit the parent's depth (they don't open a
+      // new l-...,l-end scope).
+      expect(getLayerDepth(tree, "blur")).toBe(1)
+      expect(getLayerDepth(tree, "child")).toBe(1)
+      expect(getLayerDepth(tree, "grand")).toBe(2)
+      expect(getLayerDepth(tree, "missing")).toBeUndefined()
+    })
   })
 
   describe("Resize & Crop Complex Validations", () => {

packages/imagekit-editor-dev/src/components/sidebar/sortable-transformation-item.tsx

@@ -32,8 +32,7 @@ import { RiCloseFill } from "@react-icons/all-files/ri/RiCloseFill"
 import { RxTransform } from "@react-icons/all-files/rx/RxTransform"
 import { useEffect, useMemo, useRef, useState } from "react"
 import {
-  isLayerKey,
-  MAX_LAYER_NEST_DEPTH,
+  canHostLayerChildren,
   type Transformation,
   useEditorStore,
 } from "../../store"
@@ -86,12 +85,10 @@ export const SortableTransformationItem = ({
   } = useEditorStore()
 
   const isRoot = depth === 0
-  // Text layers cannot nest anything (per docs). Image and canvas layers can
-  // host nested image/text/canvas children up to MAX_LAYER_NEST_DEPTH.
-  const canHostChildren =
-    isLayerKey(transformation.key) &&
-    transformation.key !== "layers-text" &&
-    depth < MAX_LAYER_NEST_DEPTH
+  // Image and canvas layers can host children (nested layers gated by
+  // MAX_LAYER_NEST_DEPTH inside the type picker, plus per-parent allow-listed
+  // non-layer transforms). Text layers are leaves per ImageKit docs.
+  const canHostChildren = canHostLayerChildren(transformation.key)
 
   const style = transform
     ? {
@@ -283,7 +280,11 @@ export const SortableTransformationItem = ({
               <Text
                 as="span"
                 position="absolute"
-                right={4}
+                // Compensate for the HStack's `ml` indent on nested rows: it
+                // shifts the HStack's right edge past the parent panel by the
+                // same amount, so the badge would otherwise clip. `right` is
+                // relative to the HStack, so add the indent back here.
+                right={depth > 0 ? 8 : 4}
                 top="50%"
                 transform="translateY(-50%)"
                 fontSize="xs"

packages/imagekit-editor-dev/src/components/sidebar/transformation-type-sidebar.tsx

@@ -20,7 +20,14 @@ import { PiX } from "@react-icons/all-files/pi/PiX"
 import { RiImageEditLine } from "@react-icons/all-files/ri/RiImageEditLine"
 import * as React from "react"
 import { transformationSchema } from "../../schema"
-import { useEditorStore } from "../../store"
+import {
+  findTransformationDeep,
+  getLayerDepth,
+  isAllowedChildKey,
+  isLayerKey,
+  MAX_LAYER_NEST_DEPTH,
+  useEditorStore,
+} from "../../store"
 import { SidebarBody } from "./sidebar-body"
 import { SidebarHeader } from "./sidebar-header"
 import { SidebarRoot } from "./sidebar-root"
@@ -36,10 +43,28 @@ export const TransformationTypeSidebar: React.FC = () => {
   const [searchQuery, setSearchQuery] = React.useState("")
 
   // When the user opened the picker via the "+" on a layer row, the next
-  // pick must be added as a nested child of that layer. In that mode we
-  // restrict the picker to layer transformations only \u2014 nothing else can
-  // legally nest inside a layer\u2019s transformation chain.
-  const isChildAddMode = _internalState.parentForChild !== null
+  // pick must be added as a nested child of that layer. In that mode the
+  // picker shows: (a) other layer types, gated by MAX_LAYER_NEST_DEPTH, plus
+  // (b) the parent layer's allow list of non-layer transformations (e.g.
+  // adjust-*, ai-*) that the SDK accepts inside that layer's URL block.
+  const parentForChildId = _internalState.parentForChild
+  const isChildAddMode = parentForChildId !== null
+
+  const parentForChild = React.useMemo(
+    () =>
+      parentForChildId
+        ? findTransformationDeep(transformations, parentForChildId)
+        : undefined,
+    [transformations, parentForChildId],
+  )
+
+  // Layer depth of the *parent* (root layer = 0). A new nested-layer child
+  // would land at parentDepth + 1, so layer items are only offered while
+  // `parentDepth + 1 <= MAX_LAYER_NEST_DEPTH`.
+  const parentLayerDepth = React.useMemo(() => {
+    if (!parentForChildId) return undefined
+    return getLayerDepth(transformations, parentForChildId)
+  }, [transformations, parentForChildId])
 
   const onClose = () => {
     _setSidebarState("none")
@@ -55,19 +80,22 @@ export const TransformationTypeSidebar: React.FC = () => {
   )
 
   const filteredTransformationSchema = React.useMemo(() => {
-    const base = isChildAddMode
-      ? transformationSchema
-          .map((category) => ({
-            ...category,
-            items: category.items.filter(
-              (item) =>
-                item.key === "layers-text" ||
-                item.key === "layers-image" ||
-                item.key === "layers-canvas",
-            ),
-          }))
-          .filter((category) => category.items.length > 0)
-      : transformationSchema
+    let base = transformationSchema
+    if (isChildAddMode && parentForChild) {
+      const parentKey = parentForChild.key
+      const canHostMoreLayers =
+        parentLayerDepth !== undefined &&
+        parentLayerDepth + 1 <= MAX_LAYER_NEST_DEPTH
+      base = transformationSchema
+        .map((category) => ({
+          ...category,
+          items: category.items.filter((item) => {
+            if (isLayerKey(item.key)) return canHostMoreLayers
+            return isAllowedChildKey(parentKey, item.key)
+          }),
+        }))
+        .filter((category) => category.items.length > 0)
+    }
 
     if (!searchQuery.trim()) {
       return base
@@ -81,7 +109,7 @@ export const TransformationTypeSidebar: React.FC = () => {
         ),
       }))
       .filter((category) => category.items.length > 0)
-  }, [searchQuery, isChildAddMode])
+  }, [searchQuery, isChildAddMode, parentForChild, parentLayerDepth])
 
   const handleSelectTransformation = (key: string) => {
     const transformation = transformationSchema
@@ -100,7 +128,7 @@ export const TransformationTypeSidebar: React.FC = () => {
     <SidebarRoot>
       <SidebarHeader justifyContent="space-between">
         <Text fontSize="md" fontWeight="normal" mt={0}>
-          {isChildAddMode ? "Add Nested Layer" : "Add Transformation"}
+          {isChildAddMode ? "Add Nested Transformation" : "Add Transformation"}
         </Text>
         {hasTransformations && (
           <IconButton