@designcrowd/library.brand-page 6.0.3 → 6.0.4

package/lib/src/metadata-builder/builders/section-builders/images-section-builder.js

@@ -3,8 +3,15 @@ import { isTiptapDocument, } from '../../parsers/section-tool-arguments';
 import { applyScalarFields, applyStyleFields, isValidUrl, resolveGlobalPresetIntoStyle, } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateImagesSection } from '../section-rules/images-section.rules';
+import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
+/**
+ * Full replacement: discard existing items and rebuild from the payload.
+ * Assigns a stable `id` to each item; `itemsId` is set positionally here
+ * but will be re-indexed at the end of buildAsync.
+ */
 const applyImageItems = (content, items) => {
     content.items = items.map((item, index) => ({
+        id: item.item_id || generateItemId(),
         imageUrl: isValidUrl(item.image_url) ? item.image_url : '',
         imageTitle: '',
         width: 0,
@@ -18,16 +25,28 @@ const applyImageItems = (content, items) => {
         colorReplacements: [],
     }));
 };
-const mergeImageItems = (content, items, replaceAll) => {
-    const hasIndexedItems = items.some((item) => item.item_index !== undefined);
-    if (hasIndexedItems) {
-        for (const item of items) {
-            const targetIndex = item.item_index;
-            if (targetIndex === undefined ||
-                targetIndex < 0 ||
-                !content.items?.[targetIndex])
+/**
+ * Apply a batch of item operations by id (BP-5603), mirroring the
+ * section-level id-based contract one level deeper:
+ *   - item with `item_id` matching an existing item  → update in place (and
+ *     reposition if `move_before_item_id` is set);
+ *   - item without `item_id`                          → add a new item,
+ *     positioned by `move_before_item_id`;
+ *   - `_remove_item_ids`                              → delete by id.
+ *
+ * Existing items are id-backfilled first so legacy sections become
+ * referenceable the moment the metadata builder touches them.
+ * Order-independent: there are no positional indices to shift between ops.
+ */
+const mergeImageItems = (content, items, removeIds) => {
+    ensureItemIds(content.items);
+    content.items = removeItemsByIds(content.items, removeIds);
+    for (const item of items) {
+        if (item.item_id) {
+            const existing = content.items.find((i) => i.id === item.item_id);
+            // Unknown id — skip rather than guess at a position.
+            if (!existing)
                 continue;
-            const existing = content.items[targetIndex];
             if (isValidUrl(item.image_url))
                 existing.imageUrl = item.image_url;
             if (item.heading !== undefined)
@@ -36,36 +55,26 @@ const mergeImageItems = (content, items, replaceAll) => {
                 existing.paragraph = item.text;
             if (item.button_text !== undefined)
                 existing.buttonText = item.button_text || false;
+            repositionItemByAnchor(content.items, existing, item.move_before_item_id);
+        }
+        else {
+            const newItem = {
+                id: generateItemId(),
+                imageUrl: isValidUrl(item.image_url) ? item.image_url : '',
+                imageTitle: '',
+                width: 0,
+                height: 0,
+                mediaType: 'image',
+                imageLink: '',
+                title: item.heading ?? '',
+                paragraph: item.text ?? '',
+                buttonText: item.button_text || false,
+                itemsId: 0, // re-indexed at the end of buildAsync
+                colorReplacements: [],
+            };
+            repositionItemByAnchor(content.items, newItem, item.move_before_item_id);
         }
-        return;
-    }
-    const itemsToMerge = items.filter((item) => item.insert_at === undefined);
-    const updatedItems = itemsToMerge.map((item, index) => {
-        const existing = content.items?.[index];
-        return {
-            ...(existing || {}),
-            imageUrl: isValidUrl(item.image_url)
-                ? item.image_url
-                : (existing?.imageUrl ?? ''),
-            imageTitle: existing?.imageTitle ?? '',
-            width: existing?.width ?? 0,
-            height: existing?.height ?? 0,
-            mediaType: existing?.mediaType ?? 'image',
-            imageLink: existing?.imageLink ?? '',
-            title: item.heading ?? existing?.title ?? '',
-            paragraph: item.text ?? existing?.paragraph ?? '',
-            buttonText: item.button_text ?? existing?.buttonText ?? '',
-            itemsId: existing?.itemsId ?? index,
-            colorReplacements: existing?.colorReplacements ?? [],
-        };
-    });
-    if (!replaceAll &&
-        content.items &&
-        content.items.length > itemsToMerge.length) {
-        const remaining = content.items.slice(itemsToMerge.length);
-        updatedItems.push(...remaining);
     }
-    content.items = updatedItems;
 };
 export class ImagesSectionBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -123,66 +132,22 @@ export class ImagesSectionBuilder extends BaseSectionBuilder {
                 ])),
             };
         }
-        if (args.items && Array.isArray(args.items)) {
-            if (this.mode === 'create') {
-                applyImageItems(content, args.items);
-            }
-            else {
-                mergeImageItems(content, args.items, !!args._replace_items);
-            }
-        }
-        // Phase 2: Item operations (remove, insert, reorder)
-        if (args._remove_item_indices?.length && content.items) {
-            const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
-            for (const idx of sorted) {
-                if (idx >= 0 && idx < content.items.length) {
-                    content.items.splice(idx, 1);
-                }
-            }
+        if (args._replace_items && args.items && Array.isArray(args.items)) {
+            // Full replacement: discard existing items and rebuild from the payload.
+            applyImageItems(content, args.items);
         }
-        if (args.items && Array.isArray(args.items)) {
-            const insertItems = args.items.filter((item) => item.insert_at !== undefined && item.item_index === undefined);
-            // Process inserts in reverse order of insert_at to preserve indices
-            const sortedInserts = [...insertItems].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
-            for (const item of sortedInserts) {
-                if (!isValidUrl(item.image_url))
-                    continue;
-                // Skip if this image_url already exists — defensive against duplicate
-                // tool call application
-                if (content.items?.some((existing) => existing.imageUrl === item.image_url)) {
-                    continue;
-                }
-                const pos = Math.max(0, Math.min(item.insert_at ?? 0, content.items?.length ?? 0));
-                const newItem = {
-                    imageUrl: item.image_url,
-                    imageTitle: '',
-                    width: 0,
-                    height: 0,
-                    mediaType: 'image',
-                    imageLink: '',
-                    title: item.heading ?? '',
-                    paragraph: item.text ?? '',
-                    buttonText: item.button_text || '',
-                    itemsId: pos,
-                    colorReplacements: [],
-                };
-                content.items = content.items ?? [];
-                content.items.splice(pos, 0, newItem);
+        else if (this.mode === 'create') {
+            if (args.items && Array.isArray(args.items)) {
+                applyImageItems(content, args.items);
             }
         }
-        if (args._reorder_items?.length && content.items) {
-            const newOrder = args._reorder_items;
-            const unique = new Set(newOrder);
-            if (unique.size === newOrder.length) {
-                const reordered = newOrder
-                    .filter((idx) => idx >= 0 && idx < content.items.length)
-                    .map((idx) => content.items[idx]);
-                if (reordered.length === content.items.length) {
-                    content.items = reordered;
-                }
-            }
+        else if ((args.items && Array.isArray(args.items)) ||
+            args._remove_item_ids?.length) {
+            // Update: id-based add / edit / move / remove in a single pass.
+            mergeImageItems(content, args.items ?? [], args._remove_item_ids);
         }
-        // Re-index itemsId after any item operations
+        // Re-index itemsId after all id-based item operations (render concern —
+        // separate from the stable `id` used for targeting).
         if (content.items) {
             content.items.forEach((item, i) => {
                 item.itemsId = i;

package/lib/src/metadata-builder/builders/section-builders/shapes-section-builder.js

@@ -4,6 +4,7 @@ import { applyScalarFields, applyStyleFields, resolveGlobalPresetIntoStyle, } fr
 import { applyColorThemeToReplacements, resolveShapeColorReplacementsAsync, } from '../shape-color-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateShapesSection } from '../section-rules/shapes-section.rules';
+import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
 const resolveItemColorsAsync = async (item, existing, prevImageUrl) => {
     let colors = existing ?? [];
     const newUrl = item.shape_url ?? item.icon_image_url;
@@ -15,8 +16,13 @@ const resolveItemColorsAsync = async (item, existing, prevImageUrl) => {
     }
     return colors;
 };
+/**
+ * Full replacement: discard existing items and rebuild from the payload.
+ * Used for create mode and _replace_items: true.
+ */
 const applyShapeItemsAsync = async (content, items) => {
-    content.items = await Promise.all(items.map(async (item, index) => ({
+    content.items = await Promise.all(items.map(async (item) => ({
+        id: item.item_id || generateItemId(),
         imageUrl: item.shape_url || item.icon_image_url || '',
         imageTitle: '',
         width: 0,
@@ -25,20 +31,36 @@ const applyShapeItemsAsync = async (content, items) => {
         imageLink: '',
         title: item.heading || '',
         paragraph: item.text || '',
-        itemsId: index,
+        itemsId: 0,
         colorReplacements: await resolveItemColorsAsync(item, [], undefined),
     })));
+    // Re-index itemsId after build
+    content.items.forEach((item, i) => {
+        item.itemsId = i;
+    });
 };
-const mergeShapeItemsAsync = async (content, items, replaceAll) => {
-    const hasIndexedItems = items.some((item) => item.item_index !== undefined);
-    if (hasIndexedItems) {
-        await Promise.all(items.map(async (item) => {
-            const targetIndex = item.item_index;
-            if (targetIndex === undefined ||
-                targetIndex < 0 ||
-                !content.items?.[targetIndex])
-                return;
-            const existing = content.items[targetIndex];
+/**
+ * Apply a batch of item operations by id (BP-5603), mirroring the section-level
+ * id-based contract one level deeper:
+ *   - item with `item_id` matching an existing item  → update in place (and
+ *     reposition if `move_before_item_id` is set);
+ *   - item without `item_id`                          → add a new item,
+ *     positioned by `move_before_item_id`;
+ *   - `_remove_item_ids`                              → delete by id.
+ *
+ * Existing items are id-backfilled first so legacy sections become referenceable
+ * the moment the metadata builder touches them. Order-independent: there are no
+ * positional indices to shift between operations.
+ */
+const mergeShapeItemsAsync = async (content, items, removeIds) => {
+    ensureItemIds(content.items);
+    content.items = removeItemsByIds(content.items, removeIds);
+    for (const item of items) {
+        if (item.item_id) {
+            const existing = content.items.find((i) => i.id === item.item_id);
+            // Unknown id — skip rather than guess at a position.
+            if (!existing)
+                continue;
             const prevImageUrl = existing.imageUrl;
             if (item.shape_url !== undefined || item.icon_image_url !== undefined) {
                 existing.imageUrl =
@@ -51,34 +73,29 @@ const mergeShapeItemsAsync = async (content, items, replaceAll) => {
             if (item.shape_url !== undefined || item.color_theme !== undefined) {
                 existing.colorReplacements = await resolveItemColorsAsync(item, existing.colorReplacements, prevImageUrl);
             }
-        }));
-        return;
-    }
-    const itemsToMerge = items.filter((item) => item.insert_at === undefined);
-    const updatedItems = await Promise.all(itemsToMerge.map(async (item, index) => {
-        const existing = content.items?.[index];
-        const imageUrl = item.shape_url ?? item.icon_image_url ?? existing?.imageUrl ?? '';
-        return {
-            ...(existing || {}),
-            imageUrl,
-            imageTitle: existing?.imageTitle ?? '',
-            width: existing?.width ?? 0,
-            height: existing?.height ?? 0,
-            mediaType: existing?.mediaType ?? 'shape',
-            imageLink: existing?.imageLink ?? '',
-            title: item.heading ?? existing?.title ?? '',
-            paragraph: item.text ?? existing?.paragraph ?? '',
-            itemsId: existing?.itemsId ?? index,
-            colorReplacements: await resolveItemColorsAsync(item, existing?.colorReplacements, existing?.imageUrl),
-        };
-    }));
-    if (!replaceAll &&
-        content.items &&
-        content.items.length > itemsToMerge.length) {
-        const remaining = content.items.slice(itemsToMerge.length);
-        updatedItems.push(...remaining);
+            repositionItemByAnchor(content.items, existing, item.move_before_item_id);
+        }
+        else {
+            const newItem = {
+                id: generateItemId(),
+                imageUrl: item.shape_url ?? item.icon_image_url ?? '',
+                imageTitle: '',
+                width: 0,
+                height: 0,
+                mediaType: 'shape',
+                imageLink: '',
+                title: item.heading ?? '',
+                paragraph: item.text ?? '',
+                itemsId: 0,
+                colorReplacements: await resolveItemColorsAsync(item, [], undefined),
+            };
+            repositionItemByAnchor(content.items, newItem, item.move_before_item_id);
+        }
     }
-    content.items = updatedItems;
+    // Re-index itemsId after all mutations
+    content.items.forEach((item, i) => {
+        item.itemsId = i;
+    });
 };
 export class ShapesSectionBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -136,69 +153,19 @@ export class ShapesSectionBuilder extends BaseSectionBuilder {
                 ])),
             };
         }
-        if (args.items && Array.isArray(args.items)) {
-            if (this.mode === 'create') {
-                await applyShapeItemsAsync(content, args.items);
-            }
-            else {
-                await mergeShapeItemsAsync(content, args.items, !!args._replace_items);
-            }
-        }
-        // Phase 2: Item operations (remove, insert, reorder)
-        if (args._remove_item_indices?.length && content.items) {
-            const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
-            for (const idx of sorted) {
-                if (idx >= 0 && idx < content.items.length) {
-                    content.items.splice(idx, 1);
-                }
-            }
+        if (args._replace_items && args.items && Array.isArray(args.items)) {
+            // Full replacement: discard existing items and rebuild from the payload.
+            await applyShapeItemsAsync(content, args.items);
         }
-        if (args.items && Array.isArray(args.items)) {
-            const insertItems = args.items.filter((item) => item.insert_at !== undefined && item.item_index === undefined);
-            // Process inserts in reverse order of insert_at to preserve indices
-            const sortedInserts = [...insertItems].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
-            for (const item of sortedInserts) {
-                const insertUrl = item.shape_url ?? item.icon_image_url ?? '';
-                // Skip if this shape/icon already exists — defensive against duplicate
-                // tool call application
-                if (insertUrl &&
-                    content.items?.some((existing) => existing.imageUrl === insertUrl)) {
-                    continue;
-                }
-                const pos = Math.max(0, Math.min(item.insert_at ?? 0, content.items?.length ?? 0));
-                const newItem = {
-                    imageUrl: insertUrl,
-                    imageTitle: '',
-                    width: 0,
-                    height: 0,
-                    mediaType: 'shape',
-                    imageLink: '',
-                    title: item.heading ?? '',
-                    paragraph: item.text ?? '',
-                    itemsId: pos,
-                    colorReplacements: await resolveItemColorsAsync(item, [], undefined),
-                };
-                content.items = content.items ?? [];
-                content.items.splice(pos, 0, newItem);
-            }
-        }
-        if (args._reorder_items?.length && content.items) {
-            const newOrder = args._reorder_items;
-            const unique = new Set(newOrder);
-            if (unique.size === newOrder.length) {
-                const reordered = newOrder
-                    .filter((idx) => idx >= 0 && idx < content.items.length)
-                    .map((idx) => content.items[idx]);
-                if (reordered.length === content.items.length) {
-                    content.items = reordered;
-                }
+        else if (this.mode === 'create') {
+            if (args.items && Array.isArray(args.items)) {
+                await applyShapeItemsAsync(content, args.items);
             }
         }
-        // Re-index itemsId after any item operations
-        if (content.items) {
-            content.items.forEach((item, i) => {
-                item.itemsId = i;
-            });
+        else if ((args.items && Array.isArray(args.items)) ||
+            args._remove_item_ids?.length) {
+            // Update: id-based add / edit / move / remove in a single pass.
+            await mergeShapeItemsAsync(content, args.items ?? [], args._remove_item_ids);
         }
         return { request: this.request, model };
     }

package/lib/src/metadata-builder/builders/section-builders/social-links-builder.js

@@ -1,8 +1,15 @@
 import { applyScalarFields, applyStyleFields } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateSocialLinks } from '../section-rules/social-links.rules';
+import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
+/**
+ * Create path: build the links array from scratch, assigning stable ids.
+ * `link.platform` is stored as `imageUrl` — the renderer resolves it to the
+ * actual SVG at display time.
+ */
 const applySocialLinks = (content, links) => {
     content.links = links.map((link) => ({
+        id: link.item_id || generateItemId(),
         imageUrl: link.platform || '',
         imageTitle: '',
         width: 0,
@@ -11,19 +18,46 @@ const applySocialLinks = (content, links) => {
         url: link.url || '',
     }));
 };
-const mergeSocialLinks = (content, links, replaceAll) => {
-    const updatedLinks = links.map((link, index) => {
-        const existing = content.links?.[index];
-        return {
-            ...(existing || {}),
-            imageUrl: link.platform ?? existing?.imageUrl ?? '',
-            url: link.url ?? existing?.url ?? '',
-        };
-    });
-    if (!replaceAll && content.links && content.links.length > links.length) {
-        updatedLinks.push(...content.links.slice(links.length));
+/**
+ * Merge path: id-based add / edit / move / remove in a single pass (BP-5603).
+ *
+ * - Existing items are id-backfilled first so legacy sections gain stable ids
+ *   the moment the metadata builder touches them.
+ * - `_remove_item_ids` deletes by id before the edit/add loop.
+ * - An item with `item_id` matching an existing link is updated in place and
+ *   optionally repositioned via `move_before_item_id`.
+ * - An item without `item_id` is added as a new link, positioned by
+ *   `move_before_item_id` (or appended when omitted).
+ * - An item with an unknown `item_id` is skipped rather than guessing position.
+ */
+const mergeSocialLinks = (content, links, removeIds) => {
+    ensureItemIds(content.links);
+    content.links = removeItemsByIds(content.links, removeIds);
+    for (const link of links) {
+        if (link.item_id) {
+            const existing = content.links.find((l) => l.id === link.item_id);
+            // Unknown id — skip rather than guess at a position.
+            if (!existing)
+                continue;
+            if (link.platform !== undefined)
+                existing.imageUrl = link.platform;
+            if (link.url !== undefined)
+                existing.url = link.url;
+            repositionItemByAnchor(content.links, existing, link.move_before_item_id);
+        }
+        else {
+            const newLink = {
+                id: generateItemId(),
+                imageUrl: link.platform ?? '',
+                imageTitle: '',
+                width: 0,
+                height: 0,
+                imageLink: '',
+                url: link.url ?? '',
+            };
+            repositionItemByAnchor(content.links, newLink, link.move_before_item_id);
+        }
     }
-    content.links = updatedLinks;
 };
 export class SocialLinksBuilder extends BaseSectionBuilder {
     get sectionValidate() {
@@ -42,13 +76,19 @@ export class SocialLinksBuilder extends BaseSectionBuilder {
         applyScalarFields(content, this.args, this.sectionType);
         applyStyleFields(content, this.args, this.sectionType, this.getGlobalTextStyles(model));
         const args = this.args;
-        if (args.links && Array.isArray(args.links)) {
-            if (this.mode === 'create') {
+        if (args._replace_items && args.links && Array.isArray(args.links)) {
+            // Full replacement: discard existing links and rebuild from the payload.
+            applySocialLinks(content, args.links);
+        }
+        else if (this.mode === 'create') {
+            if (args.links && Array.isArray(args.links)) {
                 applySocialLinks(content, args.links);
             }
-            else {
-                mergeSocialLinks(content, args.links, !!args._replace_items);
-            }
+        }
+        else if ((args.links && Array.isArray(args.links)) ||
+            args._remove_item_ids?.length) {
+            // Update: id-based add / edit / move / remove in a single pass.
+            mergeSocialLinks(content, args.links ?? [], args._remove_item_ids);
         }
         return { request: this.request, model };
     }