@designcrowd/library.brand-page 5.19.1-id-based-items-1 → 5.19.1

package/src/metadata-builder/builders/footer-builder.ts

@@ -10,17 +10,12 @@ import {
 import type {
   UpdateFooterArguments,
   ViewportFooterOverrides,
+  FooterSocialLinkItem,
 } from '../parsers/ai-toolcall-parser';
 import type { Logger } from '../logger';
 import type { TextStyleOptions } from '../../brand-page/models/styles.model';
 import { FOOTER_CHECKS } from './section-rules/footer.rules';
 import { applyDetachedStyleOverride } from './section-field-utils';
-import {
-  ensureItemIds,
-  generateItemId,
-  removeItemsByIds,
-  repositionItemByAnchor,
-} from './item-id-utils';
 
 const normaliseSocialUrl = (url: string): string => {
   for (const prefix of ['mailto:', 'tel:']) {
@@ -52,7 +47,6 @@ const applyGlobalFooterChanges = (
   // they are superseded by the replacement and running them would cause duplicates.
   if (args._replace_social_links) {
     footer.socialLinks = (links ?? []).map((l) => ({
-      id: generateItemId(),
       imageUrl: l.social_link_icon || '',
       url: normaliseSocialUrl(l.url || ''),
       imageTitle: '',
@@ -62,59 +56,74 @@ const applyGlobalFooterChanges = (
     }));
   } else {
     // Targeted mutations — only run when NOT replacing the entire list.
-    // BP-5603: id-based contract (item_id / move_before_item_id / _remove_social_link_ids).
-    // Backfill ids on legacy links so they become referenceable after this call.
-    ensureItemIds(footer.socialLinks);
-
-    // Remove by id (order-independent — no index shifting needed).
-    footer.socialLinks = removeItemsByIds(
-      footer.socialLinks,
-      args._remove_social_link_ids,
-    );
 
-    // Update existing links (item_id present) or insert new links (no item_id).
+    // item_index-based updates for existing links
     if (links?.length) {
+      for (const link of links) {
+        if (link.item_index === undefined) continue;
+
+        const existing = footer.socialLinks?.[link.item_index];
+
+        if (!existing) continue;
+
+        if (link.social_link_icon !== undefined)
+          existing.imageUrl = link.social_link_icon;
+
+        if (link.url !== undefined) existing.url = normaliseSocialUrl(link.url);
+      }
+    }
+
+    // Remove by index (descending order to preserve indices during splice)
+    if (args._remove_social_link_indices?.length && footer.socialLinks) {
+      const sorted = [...args._remove_social_link_indices].sort(
+        (a, b) => b - a,
+      );
+
+      for (const idx of sorted) {
+        if (idx >= 0 && idx < footer.socialLinks.length)
+          footer.socialLinks.splice(idx, 1);
+      }
+    }
+
+    // Insert new links (descending insert_at order to preserve positions during splice)
+    const insertLinks = (links ?? []).filter(
+      (l): l is FooterSocialLinkItem & { insert_at: number } =>
+        l.insert_at !== undefined && l.item_index === undefined,
+    );
+    const sortedInserts = [...insertLinks].sort(
+      (a, b) => b.insert_at - a.insert_at,
+    );
+
+    for (const link of sortedInserts) {
+      const pos = Math.max(
+        0,
+        Math.min(link.insert_at, footer.socialLinks?.length ?? 0),
+      );
+
       footer.socialLinks = footer.socialLinks ?? [];
+      footer.socialLinks.splice(pos, 0, {
+        imageUrl: link.social_link_icon || '',
+        url: normaliseSocialUrl(link.url || ''),
+        imageTitle: '',
+        width: 0,
+        height: 0,
+        imageLink: '',
+      });
+    }
 
-      for (const link of links) {
-        if (link.item_id) {
-          // Update existing link in place; reposition if move_before_item_id set.
-          const existing = footer.socialLinks.find(
-            (l) => l.id === link.item_id,
-          );
-
-          // Unknown id — skip rather than guess at a position.
-          if (!existing) continue;
-
-          if (link.social_link_icon !== undefined)
-            existing.imageUrl = link.social_link_icon;
-
-          if (link.url !== undefined)
-            existing.url = normaliseSocialUrl(link.url);
-
-          repositionItemByAnchor(
-            footer.socialLinks,
-            existing,
-            link.move_before_item_id,
-          );
-        } else {
-          // New link — assign a stable id and position via move_before_item_id.
-          const newLink = {
-            id: generateItemId(),
-            imageUrl: link.social_link_icon || '',
-            url: normaliseSocialUrl(link.url || ''),
-            imageTitle: '',
-            width: 0,
-            height: 0,
-            imageLink: '' as string | false,
-          };
-
-          repositionItemByAnchor(
-            footer.socialLinks,
-            newLink,
-            link.move_before_item_id,
-          );
-        }
+    // Reorder (requires ALL indices — partial reorder is not supported)
+    if (args._reorder_social_links?.length && footer.socialLinks) {
+      const newOrder = args._reorder_social_links;
+      const unique = new Set(newOrder);
+
+      if (
+        unique.size === newOrder.length &&
+        newOrder.every((idx) => idx >= 0 && idx < footer.socialLinks!.length)
+      ) {
+        const reordered = newOrder.map((idx) => footer.socialLinks![idx]);
+
+        if (reordered.length === footer.socialLinks.length)
+          footer.socialLinks = reordered;
       }
     }
   }

package/src/metadata-builder/builders/section-builders/image-gallery-builder.ts

@@ -10,12 +10,6 @@ import type { BuilderResult } from '../../models';
 import { applyScalarFields, isValidUrl } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateImageGallery } from '../section-rules/image-gallery.rules';
-import {
-  ensureItemIds,
-  generateItemId,
-  removeItemsByIds,
-  repositionItemByAnchor,
-} from '../item-id-utils';
 
 const applyGalleryType = (
   content: ImageGalleryContent,
@@ -27,17 +21,11 @@ const applyGalleryType = (
   };
 };
 
-/**
- * Full rebuild: discard existing images and map the payload directly.
- * Used on create and when `_replace_items` is set. Each item gets a fresh id
- * (or keeps the caller-supplied `item_id` when provided).
- */
 const applyGalleryImages = (
   content: ImageGalleryContent,
   images: ImageGalleryItem[],
 ): void => {
   content.images = images.map((img) => ({
-    id: img.item_id || generateItemId(),
     imageUrl: isValidUrl(img.image_url) ? img.image_url! : '',
     imageTitle: img.caption || '',
     width: 0,
@@ -47,53 +35,84 @@ const applyGalleryImages = (
   }));
 };
 
-/**
- * Id-based merge (BP-5603), mirroring testimonial-section-builder one level
- * deeper into `content.images`:
- *   - `item_id` matches existing item  → update in place; reposition if
- *     `move_before_item_id` is set.
- *   - no `item_id`                     → add new item, positioned by
- *     `move_before_item_id`.
- *   - `removeIds`                      → delete by id (order-independent).
- *
- * Existing items are id-backfilled first so legacy galleries become
- * referenceable as soon as the metadata builder touches them.
- */
 const mergeGalleryImages = (
   content: ImageGalleryContent,
   images: ImageGalleryItem[],
-  removeIds: string[] | undefined,
+  replaceAll: boolean,
 ): void => {
-  ensureItemIds(content.images);
-  content.images = removeItemsByIds(content.images, removeIds);
+  const itemsToMerge = images.filter((img) => img.insert_at === undefined);
+
+  const updatedImages = itemsToMerge.map((img, index) => {
+    const existing = content.images?.[index];
+    const imageUrl = isValidUrl(img.image_url)
+      ? img.image_url!
+      : existing?.imageUrl ?? '';
+
+    return {
+      ...(existing || {}),
+      imageUrl,
+      imageTitle: img.caption ?? existing?.imageTitle ?? '',
+      width: existing?.width ?? 0,
+      height: existing?.height ?? 0,
+      mediaType: existing?.mediaType ?? 'image',
+      imageLink: existing?.imageLink ?? '',
+    };
+  });
+
+  if (
+    !replaceAll &&
+    content.images &&
+    content.images.length > itemsToMerge.length
+  ) {
+    const extras = content.images.slice(itemsToMerge.length).map((img) => ({
+      imageUrl: img.imageUrl ?? '',
+      imageTitle: img.imageTitle ?? '',
+      width: img.width ?? 0,
+      height: img.height ?? 0,
+      mediaType: img.mediaType ?? ('image' as const),
+      imageLink: img.imageLink ?? '',
+    }));
+
+    updatedImages.push(...extras);
+  }
 
-  for (const img of images) {
-    if (img.item_id) {
-      const existing = content.images.find((i) => i.id === img.item_id);
+  content.images = updatedImages;
+};
 
-      // Unknown id — skip rather than guess at a position.
-      if (!existing) continue;
+const insertGalleryImages = (
+  content: ImageGalleryContent,
+  images: ImageGalleryItem[],
+): void => {
+  const inserts = images.filter((img) => img.insert_at !== undefined);
 
-      if (img.image_url !== undefined) {
-        existing.imageUrl = isValidUrl(img.image_url) ? img.image_url! : '';
-      }
+  if (!inserts.length) return;
 
-      if (img.caption !== undefined) existing.imageTitle = img.caption;
-
-      repositionItemByAnchor(content.images, existing, img.move_before_item_id);
-    } else {
-      const newItem = {
-        id: generateItemId(),
-        imageUrl: isValidUrl(img.image_url) ? img.image_url! : '',
-        imageTitle: img.caption ?? '',
-        width: 0,
-        height: 0,
-        mediaType: 'image' as const,
-        imageLink: '',
-      };
-
-      repositionItemByAnchor(content.images, newItem, img.move_before_item_id);
-    }
+  const sorted = [...inserts].sort(
+    (a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0),
+  );
+
+  for (const img of sorted) {
+    if (!isValidUrl(img.image_url)) continue;
+
+    if (content.images?.some((existing) => existing.imageUrl === img.image_url))
+      continue;
+
+    content.images = content.images ?? [];
+
+    const pos = Math.max(
+      0,
+      Math.min(img.insert_at ?? 0, content.images.length),
+    );
+
+    content.images.splice(pos, 0, {
+      imageUrl: img.image_url!,
+      imageTitle: img.caption ?? '',
+      width: 0,
+      height: 0,
+      mediaType: 'image',
+      imageLink: '',
+      colorReplacements: [],
+    });
   }
 };
 
@@ -125,19 +144,26 @@ export class ImageGalleryBuilder extends BaseSectionBuilder<ImageGalleryContent>
       applyGalleryType(content, args.gallery_type);
     }
 
-    if (args._replace_items && args.images && Array.isArray(args.images)) {
-      // Full replacement: discard existing images and rebuild from the payload.
-      applyGalleryImages(content, args.images);
-    } else if (this.mode === 'create') {
-      if (args.images && Array.isArray(args.images)) {
+    if (args.images && Array.isArray(args.images)) {
+      if (this.mode === 'create') {
         applyGalleryImages(content, args.images);
+      } else {
+        mergeGalleryImages(content, args.images, !!args._replace_items);
       }
-    } else if (
-      (args.images && Array.isArray(args.images)) ||
-      args._remove_item_ids?.length
-    ) {
-      // Update: id-based add / edit / move / remove in a single pass.
-      mergeGalleryImages(content, args.images ?? [], args._remove_item_ids);
+    }
+
+    if (args._remove_item_indices?.length && content.images) {
+      const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
+
+      for (const idx of sorted) {
+        if (idx >= 0 && idx < content.images.length) {
+          content.images.splice(idx, 1);
+        }
+      }
+    }
+
+    if (args.images && Array.isArray(args.images) && this.mode === 'update') {
+      insertGalleryImages(content, args.images);
     }
 
     return { request: this.request, model };

package/src/metadata-builder/builders/section-builders/images-section-builder.ts

@@ -18,24 +18,12 @@ import {
 } 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: ImagesSectionContent,
   items: ImagesSectionItem[],
 ): void => {
   content.items = items.map((item, index) => ({
-    id: item.item_id || generateItemId(),
     imageUrl: isValidUrl(item.image_url) ? item.image_url! : '',
     imageTitle: '',
     width: 0,
@@ -50,33 +38,25 @@ const applyImageItems = (
   }));
 };
 
-/**
- * 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: ImagesSectionContent,
   items: ImagesSectionItem[],
-  removeIds: string[] | undefined,
+  replaceAll: boolean,
 ): void => {
-  ensureItemIds(content.items);
-  content.items = removeItemsByIds(content.items, removeIds);
+  const hasIndexedItems = items.some((item) => item.item_index !== undefined);
 
-  for (const item of items) {
-    if (item.item_id) {
-      const existing = content.items.find((i) => i.id === item.item_id);
+  if (hasIndexedItems) {
+    for (const item of items) {
+      const targetIndex = item.item_index;
 
-      // Unknown id — skip rather than guess at a position.
-      if (!existing) continue;
+      if (
+        targetIndex === undefined ||
+        targetIndex < 0 ||
+        !content.items?.[targetIndex]
+      )
+        continue;
+
+      const existing = content.items[targetIndex];
 
       if (isValidUrl(item.image_url)) existing.imageUrl = item.image_url!;
 
@@ -86,27 +66,47 @@ const mergeImageItems = (
 
       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: [],
-      } as ImagesSectionContent['items'][number];
-
-      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,
+    ) as typeof updatedItems;
+
+    updatedItems.push(...remaining);
+  }
+
+  content.items = updatedItems;
 };
 
 export class ImagesSectionBuilder extends BaseSectionBuilder<ImagesSectionContent> {
@@ -192,23 +192,86 @@ export class ImagesSectionBuilder extends BaseSectionBuilder<ImagesSectionConten
       };
     }
 
-    if (args._replace_items && args.items && Array.isArray(args.items)) {
-      // Full replacement: discard existing items and rebuild from the payload.
-      applyImageItems(content, args.items);
-    } else if (this.mode === 'create') {
-      if (args.items && Array.isArray(args.items)) {
+    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.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: any) => 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 as any);
+      }
+    }
+
+    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 all id-based item operations (render concern —
-    // separate from the stable `id` used for targeting).
+    // Re-index itemsId after any item operations
     if (content.items) {
       content.items.forEach((item, i) => {
         item.itemsId = i;