@designcrowd/library.brand-page 6.0.3 → 6.0.4

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

@@ -23,6 +23,12 @@ 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,
@@ -43,111 +49,117 @@ 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, index) => ({
+    items.map(async (item) => ({
+      id: item.item_id || generateItemId(),
       imageUrl: item.shape_url || item.icon_image_url || '',
       imageTitle: '',
       width: 0,
       height: 0,
-      mediaType: 'shape',
-      imageLink: '',
+      mediaType: 'shape' as const,
+      imageLink: '' as const,
       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 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[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
 ): Promise<void> => {
-  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,
-          );
-        }
-      }),
-    );
+  ensureItemIds(content.items as TextShapeItem[]);
+  content.items = removeItemsByIds(content.items as TextShapeItem[], removeIds);
 
-    return;
-  }
+  for (const item of items) {
+    if (item.item_id) {
+      const existing = (content.items as TextShapeItem[]).find(
+        (i) => i.id === item.item_id,
+      );
 
-  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,
-        ),
-      };
-    }),
-  );
+      // Unknown id — skip rather than guess at a position.
+      if (!existing) continue;
 
-  if (
-    !replaceAll &&
-    content.items &&
-    content.items.length > itemsToMerge.length
-  ) {
-    const remaining = content.items.slice(
-      itemsToMerge.length,
-    ) as typeof updatedItems;
+      const prevImageUrl = existing.imageUrl;
 
-    updatedItems.push(...remaining);
+      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,
+        );
+      }
+
+      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,
+      );
+    }
   }
 
-  content.items = updatedItems;
+  // Re-index itemsId after all mutations
+  (content.items as TextShapeItem[]).forEach((item, i) => {
+    item.itemsId = i;
+  });
 };
 
 export class ShapesSectionBuilder extends BaseSectionBuilder<ShapesSectionContent> {
@@ -233,90 +245,23 @@ export class ShapesSectionBuilder extends BaseSectionBuilder<ShapesSectionConten
       };
     }
 
-    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.
+      await applyShapeItemsAsync(content, args.items);
+    } else if (this.mode === 'create') {
+      if (args.items && Array.isArray(args.items)) {
         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.items && Array.isArray(args.items)) {
-      const insertItems = args.items.filter(
-        (item) => item.insert_at !== undefined && item.item_index === undefined,
+    } 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,
       );
-      // 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,12 +10,24 @@ 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,
@@ -25,26 +37,52 @@ 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[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
 ): void => {
-  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));
-  }
+  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;
 
-  content.links = updatedLinks;
+      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);
+    }
+  }
 };
 
 export class SocialLinksBuilder extends BaseSectionBuilder<SocialLinksContent> {
@@ -77,12 +115,19 @@ export class SocialLinksBuilder extends BaseSectionBuilder<SocialLinksContent> {
 
     const args = this.args as SocialLinksSectionArguments;
 
-    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 };