@designcrowd/library.brand-page 6.0.12 → 6.0.13

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

@@ -10,6 +10,12 @@ 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,
@@ -21,11 +27,17 @@ 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,
@@ -35,84 +47,53 @@ 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[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
 ): void => {
-  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);
-  }
-
-  content.images = updatedImages;
-};
-
-const insertGalleryImages = (
-  content: ImageGalleryContent,
-  images: ImageGalleryItem[],
-): void => {
-  const inserts = images.filter((img) => img.insert_at !== undefined);
-
-  if (!inserts.length) return;
-
-  const sorted = [...inserts].sort(
-    (a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0),
-  );
+  ensureItemIds(content.images);
+  content.images = removeItemsByIds(content.images, removeIds);
 
-  for (const img of sorted) {
-    if (!isValidUrl(img.image_url)) continue;
+  for (const img of images) {
+    if (img.item_id) {
+      const existing = content.images.find((i) => i.id === img.item_id);
 
-    if (content.images?.some((existing) => existing.imageUrl === img.image_url))
-      continue;
+      // Unknown id — skip rather than guess at a position.
+      if (!existing) continue;
 
-    content.images = content.images ?? [];
-
-    const pos = Math.max(
-      0,
-      Math.min(img.insert_at ?? 0, content.images.length),
-    );
+      if (img.image_url !== undefined) {
+        existing.imageUrl = isValidUrl(img.image_url) ? img.image_url! : '';
+      }
 
-    content.images.splice(pos, 0, {
-      imageUrl: img.image_url!,
-      imageTitle: img.caption ?? '',
-      width: 0,
-      height: 0,
-      mediaType: 'image',
-      imageLink: '',
-      colorReplacements: [],
-    });
+      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);
+    }
   }
 };
 
@@ -144,26 +125,19 @@ export class ImageGalleryBuilder extends BaseSectionBuilder<ImageGalleryContent>
       applyGalleryType(content, args.gallery_type);
     }
 
-    if (args.images && Array.isArray(args.images)) {
-      if (this.mode === 'create') {
+    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)) {
         applyGalleryImages(content, args.images);
-      } else {
-        mergeGalleryImages(content, args.images, !!args._replace_items);
       }
-    }
-
-    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);
+    } 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);
     }
 
     return { request: this.request, model };

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

@@ -18,12 +18,24 @@ 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,
@@ -38,25 +50,33 @@ 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[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
 ): void => {
-  const hasIndexedItems = items.some((item) => item.item_index !== undefined);
+  ensureItemIds(content.items);
+  content.items = removeItemsByIds(content.items, removeIds);
 
-  if (hasIndexedItems) {
-    for (const item of items) {
-      const targetIndex = item.item_index;
+  for (const item of items) {
+    if (item.item_id) {
+      const existing = content.items.find((i) => i.id === item.item_id);
 
-      if (
-        targetIndex === undefined ||
-        targetIndex < 0 ||
-        !content.items?.[targetIndex]
-      )
-        continue;
-
-      const existing = content.items[targetIndex];
+      // Unknown id — skip rather than guess at a position.
+      if (!existing) continue;
 
       if (isValidUrl(item.image_url)) existing.imageUrl = item.image_url!;
 
@@ -66,47 +86,27 @@ const mergeImageItems = (
 
       if (item.button_text !== undefined)
         existing.buttonText = item.button_text || false;
-    }
-
-    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);
+      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);
+    }
   }
-
-  content.items = updatedItems;
 };
 
 export class ImagesSectionBuilder extends BaseSectionBuilder<ImagesSectionContent> {
@@ -192,86 +192,23 @@ export class ImagesSectionBuilder extends BaseSectionBuilder<ImagesSectionConten
       };
     }
 
-    if (args.items && Array.isArray(args.items)) {
-      if (this.mode === 'create') {
+    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)) {
         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 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/src/metadata-builder/builders/section-builders/move-section-builder.ts

@@ -8,7 +8,12 @@ import type { Logger } from '../../logger';
 
 export interface MoveSectionPayload {
   contentId: string;
-  position: number;
+  /**
+   * Relative anchor on the destination page: the content_id to insert this section
+   * BEFORE (a page's first content_id moves it to the very top). Omit to append to the
+   * end — a move always relocates the section, so "no anchor" means "append".
+   */
+  moveBeforeContentId?: string;
   targetPageId?: string;
 }
 
@@ -22,16 +27,11 @@ export class MoveSectionBuilder extends BaseMetadataBuilder<MoveSectionPayload>
 
   async validateAsync(): Promise<{ errors: string[] }> {
     const errors: string[] = [];
-    const payload = this.request.payload;
 
-    if (!payload?.contentId) {
+    if (!this.request.payload?.contentId) {
       errors.push('contentId is required for move_section');
     }
 
-    if (payload?.position === undefined || payload.position < 0) {
-      errors.push('position must be a non-negative integer');
-    }
-
     return { errors };
   }
 
@@ -44,51 +44,55 @@ export class MoveSectionBuilder extends BaseMetadataBuilder<MoveSectionPayload>
       return { request: this.request, model, errors: validation.errors };
     }
 
-    const { contentId, position, targetPageId } = this.request.payload!;
+    const { contentId, moveBeforeContentId, targetPageId } =
+      this.request.payload!;
 
     for (const page of model.pages) {
       const currentIndex = page.contents.findIndex((c) => c.id === contentId);
 
-      if (currentIndex !== -1) {
-        const [section] = page.contents.splice(currentIndex, 1);
-
-        // Cross-page move: insert into target page
-        if (targetPageId && targetPageId !== page.id) {
-          const targetPage = model.pages.find((p) => p.id === targetPageId);
-
-          if (!targetPage) {
-            // Undo the splice and return an error
-            page.contents.splice(currentIndex, 0, section);
+      if (currentIndex === -1) continue;
 
-            return {
-              request: this.request,
-              model,
-              errors: [`Target page with ID "${targetPageId}" not found`],
-            };
-          }
+      const [section] = page.contents.splice(currentIndex, 1);
 
-          const targetIndex = Math.min(position, targetPage.contents.length);
+      // Cross-page move: insert into target page
+      if (targetPageId && targetPageId !== page.id) {
+        const targetPage = model.pages.find((p) => p.id === targetPageId);
 
-          targetPage.contents.splice(targetIndex, 0, section);
+        if (!targetPage) {
+          // Undo the splice and return an error
+          page.contents.splice(currentIndex, 0, section);
 
-          this.log({
-            message: `Moved section ${contentId} from page ${page.id} index ${currentIndex} to page ${targetPageId} index ${targetIndex}`,
-          });
-
-          return { request: this.request, model };
+          return {
+            request: this.request,
+            model,
+            errors: [`Target page with ID "${targetPageId}" not found`],
+          };
         }
 
-        // Within-page reorder
-        const targetIndex = Math.min(position, page.contents.length);
+        const targetIndex = this.resolveIndex(
+          targetPage.contents,
+          moveBeforeContentId,
+        );
 
-        page.contents.splice(targetIndex, 0, section);
+        targetPage.contents.splice(targetIndex, 0, section);
 
         this.log({
-          message: `Moved section ${contentId} from index ${currentIndex} to ${targetIndex} on page ${page.id}`,
+          message: `Moved section ${contentId} from page ${page.id} index ${currentIndex} to page ${targetPageId} index ${targetIndex}`,
         });
 
         return { request: this.request, model };
       }
+
+      // Within-page reorder
+      const targetIndex = this.resolveIndex(page.contents, moveBeforeContentId);
+
+      page.contents.splice(targetIndex, 0, section);
+
+      this.log({
+        message: `Moved section ${contentId} from index ${currentIndex} to ${targetIndex} on page ${page.id}`,
+      });
+
+      return { request: this.request, model };
     }
 
     return {
@@ -97,4 +101,23 @@ export class MoveSectionBuilder extends BaseMetadataBuilder<MoveSectionPayload>
       errors: [`Section with ID "${contentId}" not found`],
     };
   }
+
+  /**
+   * Resolve the insert index on a page from the relative anchor. `moveBeforeContentId`
+   * is the content_id to insert before; anything else — omitted, or an id not on the
+   * page — appends to the end. A move always relocates the section, so "no anchor"
+   * naturally means "append" (this also absorbs a legacy "__end__" token as append).
+   */
+  private resolveIndex<T extends { id: string }>(
+    contents: T[],
+    moveBeforeContentId: string | undefined,
+  ): number {
+    if (moveBeforeContentId) {
+      const idx = contents.findIndex((c) => c.id === moveBeforeContentId);
+
+      if (idx !== -1) return idx;
+    }
+
+    return contents.length;
+  }
 }