✨ Added URL transform support for lexical card property arrays and nested object paths

closes TryGhost/Product#2722

Cards can have complex objects in their data properties that need URLs transformed. This commit adds support for handling deeply nested arrays of objects and paths.

Example card dataset :
```
{
    images: [{
        src: '/image.png',
        sizes: {
            small: {src: '/image-small.png'},
            large: {src: '/image-large.png'}
        }
    }]
}
```

and the corresponding transform map:
```
urlTransformMap() {
    return {
        images: [{
            src: 'url',
            sizes: {
                'small.src': 'url',
                'large.src': 'url'
            }
        }]
    }
}
```

Author: kevinansfield

packages/url-utils/lib/utils/_lexical-transform.js

@@ -1,3 +1,13 @@
+const _ = require('lodash');
+
+// options.transformMap = {
+//     relativeToAbsolute: {
+//         url: (url, siteUrl, itemPath, options) => 'transformedUrl',
+//         html: (html, siteUrl, itemPath, options) => 'transformedHtml',
+//     }
+// }
+// options.transformType = 'relativeToAbsolute'
+
 function lexicalTransform(serializedLexical, siteUrl, transformFunction, itemPath, _options = {}) {
     const defaultOptions = {assetsOnly: false, secure: false, nodes: [], transformMap: {}};
     const options = Object.assign({}, defaultOptions, _options, {siteUrl, itemPath});
@@ -14,21 +24,42 @@ function lexicalTransform(serializedLexical, siteUrl, transformFunction, itemPat
         return serializedLexical;
     }
 
+    // create a map of node types to urlTransformMap objects
+    // e.g. {'image': {src: 'url', caption: 'html'}
     const nodeMap = new Map();
     options.nodes.forEach(node => node.urlTransformMap && nodeMap.set(node.getType(), node.urlTransformMap));
 
+    const transformProperty = function (obj, propertyPath, transform) {
+        const propertyValue = _.get(obj, propertyPath);
+
+        if (Array.isArray(propertyValue)) {
+            propertyValue.forEach((item) => {
+                // arrays of objects need to be defined as a nested object in the urlTransformMap
+                // so the `transform` value is that nested object
+                Object.entries(transform).forEach(([itemPropertyPath, itemTransform]) => {
+                    transformProperty(item, itemPropertyPath, itemTransform);
+                });
+            });
+
+            return;
+        }
+
+        if (propertyValue) {
+            _.set(obj, propertyPath, options.transformMap[options.transformType][transform](propertyValue));
+        }
+    };
+
+    // recursively walk the Lexical node tree transforming any card data properties and links
     const transformChildren = function (children) {
         for (const child of children) {
-            // cards (nodes) have a `type` attribute in their node data
-            if (child.type && nodeMap.has(child.type)) {
-                Object.entries(nodeMap.get(child.type)).forEach(([property, transform]) => {
-                    if (child[property]) {
-                        child[property] = options.transformMap[options.transformType][transform](child[property]);
-                    }
+            const isCard = child.type && nodeMap.has(child.type);
+            const isLink = !!child.url;
+
+            if (isCard) {
+                Object.entries(nodeMap.get(child.type)).forEach(([propertyPath, transform]) => {
+                    transformProperty(child, propertyPath, transform);
                 });
-            } else if (child.url) {
-                // any lexical links will be a child object with a `url` attribute,
-                // recursively walk the tree transforming any `.url`s
+            } else if (isLink) {
                 child.url = transformFunction(child.url, siteUrl, itemPath, options);
             }
 

packages/url-utils/test/unit/utils/lexical-absolute-to-relative.test.js

@@ -389,6 +389,228 @@ describe('utils: lexicalAbsoluteToRelative()', function () {
         result.root.children[0].caption.should.equal('Captions are HTML with only <a href="/image-caption-link">links transformed</a> - this is a plaintext url: http://my-ghost-blog.com/plaintext-url');
     });
 
+    it('handles cards with array properties', function () {
+        const urlUtils = new UrlUtils({
+            getSubdir: function () {
+                return '';
+            },
+            getSiteUrl: function () {
+                return siteUrl;
+            }
+        });
+
+        Object.assign(options, {
+            nodes: [
+                class GalleryNode {
+                    static getType() {
+                        return 'gallery';
+                    }
+
+                    static get urlTransformMap() {
+                        return {
+                            images: {src: 'url'}
+                        };
+                    }
+                }
+            ],
+            transformMap: {
+                absoluteToRelative: {
+                    url: urlUtils.absoluteToRelative.bind(urlUtils),
+                    html: urlUtils.htmlAbsoluteToRelative.bind(urlUtils)
+                }
+            }
+        });
+
+        const lexical = JSON.stringify({
+            root: {
+                children: [{
+                    type: 'gallery',
+                    images: [
+                        {src: 'http://my-ghost-blog.com/image1.png'},
+                        {src: 'http://my-ghost-blog.com/image2.png'}
+                    ]
+                }]
+            }
+        });
+
+        const serializedResult = lexicalAbsoluteToRelative(lexical, siteUrl, options);
+        const result = JSON.parse(serializedResult);
+
+        result.root.children[0].images[0].src.should.equal('/image1.png');
+        result.root.children[0].images[1].src.should.equal('/image2.png');
+    });
+
+    it('handles cards with deeply nested properties', function () {
+        const urlUtils = new UrlUtils({
+            getSubdir: function () {
+                return '';
+            },
+            getSiteUrl: function () {
+                return siteUrl;
+            }
+        });
+
+        Object.assign(options, {
+            nodes: [
+                class TestNode {
+                    static getType() {
+                        return 'test';
+                    }
+
+                    static get urlTransformMap() {
+                        return {
+                            'meta.image.src': 'url'
+                        };
+                    }
+                }
+            ],
+            transformMap: {
+                absoluteToRelative: {
+                    url: urlUtils.absoluteToRelative.bind(urlUtils),
+                    html: urlUtils.htmlAbsoluteToRelative.bind(urlUtils)
+                }
+            }
+        });
+
+        const lexical = JSON.stringify({
+            root: {
+                children: [{
+                    type: 'test',
+                    meta: {
+                        image: {
+                            src: 'http://my-ghost-blog.com/image.png'
+                        }
+                    }
+                }]
+            }
+        });
+
+        const serializedResult = lexicalAbsoluteToRelative(lexical, siteUrl, options);
+        const result = JSON.parse(serializedResult);
+
+        result.root.children[0].meta.image.src.should.equal('/image.png');
+    });
+
+    it('handles cards with arrays of deeply nested properties', function () {
+        const urlUtils = new UrlUtils({
+            getSubdir: function () {
+                return '';
+            },
+            getSiteUrl: function () {
+                return siteUrl;
+            }
+        });
+
+        Object.assign(options, {
+            nodes: [
+                class GalleryNode {
+                    static getType() {
+                        return 'gallery';
+                    }
+
+                    static get urlTransformMap() {
+                        return {
+                            images: {
+                                'srcs.main': 'url'
+                            }
+                        };
+                    }
+                }
+            ],
+            transformMap: {
+                absoluteToRelative: {
+                    url: urlUtils.absoluteToRelative.bind(urlUtils),
+                    html: urlUtils.htmlAbsoluteToRelative.bind(urlUtils)
+                }
+            }
+        });
+
+        const lexical = JSON.stringify({
+            root: {
+                children: [{
+                    type: 'gallery',
+                    images: [
+                        {srcs: {main: 'http://my-ghost-blog.com/image1.png'}},
+                        {srcs: {main: 'http://my-ghost-blog.com/image2.png'}}
+                    ]
+                }]
+            }
+        });
+
+        const serializedResult = lexicalAbsoluteToRelative(lexical, siteUrl, options);
+        const result = JSON.parse(serializedResult);
+
+        result.root.children[0].images[0].srcs.main.should.equal('/image1.png');
+        result.root.children[0].images[1].srcs.main.should.equal('/image2.png');
+    });
+
+    it('handles cards with arrays of arrays', function () {
+        const urlUtils = new UrlUtils({
+            getSubdir: function () {
+                return '';
+            },
+            getSiteUrl: function () {
+                return siteUrl;
+            }
+        });
+
+        Object.assign(options, {
+            nodes: [
+                class GalleryNode {
+                    static getType() {
+                        return 'gallery';
+                    }
+
+                    static get urlTransformMap() {
+                        return {
+                            images: {
+                                sizes: {
+                                    src: 'url'
+                                }
+                            }
+                        };
+                    }
+                }
+            ],
+            transformMap: {
+                absoluteToRelative: {
+                    url: urlUtils.absoluteToRelative.bind(urlUtils),
+                    html: urlUtils.htmlAbsoluteToRelative.bind(urlUtils)
+                }
+            }
+        });
+
+        const lexical = JSON.stringify({
+            root: {
+                children: [{
+                    type: 'gallery',
+                    images: [
+                        {
+                            sizes: [
+                                {src: 'http://my-ghost-blog.com/image1.png'},
+                                {src: 'http://my-ghost-blog.com/image2.png'}
+                            ]
+                        },
+                        {
+                            sizes: [
+                                {src: 'http://my-ghost-blog.com/image3.png'},
+                                {src: 'http://my-ghost-blog.com/image4.png'}
+                            ]
+                        }
+                    ]
+                }]
+            }
+        });
+
+        const serializedResult = lexicalAbsoluteToRelative(lexical, siteUrl, options);
+        const result = JSON.parse(serializedResult);
+
+        result.root.children[0].images[0].sizes[0].src.should.equal('/image1.png');
+        result.root.children[0].images[0].sizes[1].src.should.equal('/image2.png');
+        result.root.children[0].images[1].sizes[0].src.should.equal('/image3.png');
+        result.root.children[0].images[1].sizes[1].src.should.equal('/image4.png');
+    });
+
     it('does not transform unknown cards', function () {
         const urlUtils = new UrlUtils({
             getSubdir: function () {