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

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;

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

@@ -23,12 +23,6 @@ import {
 } 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: ShapesSectionItem,
@@ -49,117 +43,111 @@ const resolveItemColorsAsync = async (
   return colors;
 };
 
-/**
- * Full replacement: discard existing items and rebuild from the payload.
- * Used for create mode and _replace_items: true.
- */
 const applyShapeItemsAsync = async (
   content: ShapesSectionContent,
   items: ShapesSectionItem[],
 ): Promise<void> => {
   content.items = await Promise.all(
-    items.map(async (item) => ({
-      id: item.item_id || generateItemId(),
+    items.map(async (item, index) => ({
       imageUrl: item.shape_url || item.icon_image_url || '',
       imageTitle: '',
       width: 0,
       height: 0,
-      mediaType: 'shape' as const,
-      imageLink: '' as const,
+      mediaType: 'shape',
+      imageLink: '',
       title: item.heading || '',
       paragraph: item.text || '',
-      itemsId: 0,
+      itemsId: index,
       colorReplacements: await resolveItemColorsAsync(item, [], undefined),
     })),
   );
-
-  // Re-index itemsId after build
-  content.items.forEach((item, i) => {
-    (item as TextShapeItem).itemsId = i;
-  });
 };
 
-/**
- * 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: ShapesSectionContent,
   items: ShapesSectionItem[],
-  removeIds: string[] | undefined,
+  replaceAll: boolean,
 ): Promise<void> => {
-  ensureItemIds(content.items as TextShapeItem[]);
-  content.items = removeItemsByIds(content.items as TextShapeItem[], removeIds);
-
-  for (const item of items) {
-    if (item.item_id) {
-      const existing = (content.items as TextShapeItem[]).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 =
-          item.shape_url ?? item.icon_image_url ?? existing.imageUrl;
-      }
-
-      if (item.heading !== undefined) existing.title = item.heading;
+  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] as TextShapeItem;
+        const prevImageUrl = existing.imageUrl;
+
+        if (item.shape_url !== undefined || item.icon_image_url !== undefined) {
+          existing.imageUrl =
+            item.shape_url ?? item.icon_image_url ?? existing.imageUrl;
+        }
+
+        if (item.heading !== undefined) existing.title = item.heading;
+
+        if (item.text !== undefined) existing.paragraph = item.text;
+
+        if (item.shape_url !== undefined || item.color_theme !== undefined) {
+          existing.colorReplacements = await resolveItemColorsAsync(
+            item,
+            existing.colorReplacements,
+            prevImageUrl,
+          );
+        }
+      }),
+    );
 
-      if (item.text !== undefined) existing.paragraph = item.text;
+    return;
+  }
 
-      if (item.shape_url !== undefined || item.color_theme !== undefined) {
-        existing.colorReplacements = await resolveItemColorsAsync(
+  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,
-          prevImageUrl,
-        );
-      }
+          existing?.colorReplacements,
+          existing?.imageUrl,
+        ),
+      };
+    }),
+  );
 
-      repositionItemByAnchor(
-        content.items as TextShapeItem[],
-        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' as const,
-        imageLink: '' as const,
-        title: item.heading ?? '',
-        paragraph: item.text ?? '',
-        itemsId: 0,
-        colorReplacements: await resolveItemColorsAsync(item, [], undefined),
-      } as TextShapeItem;
-
-      repositionItemByAnchor(
-        content.items as TextShapeItem[],
-        newItem,
-        item.move_before_item_id,
-      );
-    }
+  if (
+    !replaceAll &&
+    content.items &&
+    content.items.length > itemsToMerge.length
+  ) {
+    const remaining = content.items.slice(
+      itemsToMerge.length,
+    ) as typeof updatedItems;
+
+    updatedItems.push(...remaining);
   }
 
-  // Re-index itemsId after all mutations
-  (content.items as TextShapeItem[]).forEach((item, i) => {
-    item.itemsId = i;
-  });
+  content.items = updatedItems;
 };
 
 export class ShapesSectionBuilder extends BaseSectionBuilder<ShapesSectionContent> {
@@ -245,23 +233,90 @@ export class ShapesSectionBuilder extends BaseSectionBuilder<ShapesSectionConten
       };
     }
 
-    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);
-    } else if (this.mode === 'create') {
-      if (args.items && Array.isArray(args.items)) {
+    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);
+        }
       }
-    } 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,
+    }
+
+    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: any) => 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 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;
+        }
+      }
+    }
+
+    // Re-index itemsId after any item operations
+    if (content.items) {
+      content.items.forEach((item, i) => {
+        item.itemsId = i;
+      });
     }
 
     return { request: this.request, model };

package/src/metadata-builder/builders/section-builders/social-links-builder.ts

@@ -10,24 +10,12 @@ import type { BuilderResult } from '../../models';
 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: SocialLinksContent,
   links: SocialLink[],
 ): void => {
   content.links = links.map((link) => ({
-    id: link.item_id || generateItemId(),
     imageUrl: link.platform || '',
     imageTitle: '',
     width: 0,
@@ -37,52 +25,26 @@ const applySocialLinks = (
   }));
 };
 
-/**
- * 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: SocialLinksContent,
   links: SocialLink[],
-  removeIds: string[] | undefined,
+  replaceAll: boolean,
 ): void => {
-  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: '' as const,
-        url: link.url ?? '',
-      };
-
-      repositionItemByAnchor(content.links, newLink, link.move_before_item_id);
-    }
+  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));
   }
+
+  content.links = updatedLinks;
 };
 
 export class SocialLinksBuilder extends BaseSectionBuilder<SocialLinksContent> {
@@ -115,19 +77,12 @@ export class SocialLinksBuilder extends BaseSectionBuilder<SocialLinksContent> {
 
     const args = this.args as SocialLinksSectionArguments;
 
-    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)) {
+    if (args.links && Array.isArray(args.links)) {
+      if (this.mode === 'create') {
         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 };