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

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

@@ -25,12 +25,6 @@ import {
   validateTestimonialSection,
   TESTIMONIAL_ITEM_CAP,
 } from '../section-rules/testimonial-section.rules';
-import {
-  ensureItemIds,
-  generateItemId,
-  removeItemsByIds,
-  repositionItemByAnchor,
-} from '../item-id-utils';
 
 const resolveItemColorsAsync = async (
   item: TestimonialItem,
@@ -56,7 +50,6 @@ const applyTestimonialItemsAsync = async (
 ): Promise<void> => {
   content.items = await Promise.all(
     items.map(async (item) => ({
-      id: item.item_id || generateItemId(),
       imageUrl: item.avatar_shape_url || item.avatar_image_url || '',
       name: item.name || '',
       position: item.position || '',
@@ -67,77 +60,101 @@ const applyTestimonialItemsAsync = async (
   );
 };
 
-/**
- * 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 mergeTestimonialItemsAsync = async (
   content: TestimonialSectionContent,
   items: TestimonialItem[],
-  removeIds: string[] | undefined,
+  replaceAll: boolean,
 ): Promise<void> => {
-  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;
+  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];
+        const prevImageUrl = existing.imageUrl;
+
+        if (item.avatar_shape_url !== undefined) {
+          existing.imageUrl = item.avatar_shape_url;
+          existing.mediaType = 'shape';
+        } else if (item.avatar_image_url !== undefined) {
+          existing.imageUrl = item.avatar_image_url;
+          existing.mediaType = 'image';
+        }
+
+        if (item.name !== undefined) existing.name = item.name;
+
+        if (item.position !== undefined) existing.position = item.position;
+
+        if (item.testimonial !== undefined)
+          existing.testimonials = item.testimonial;
+
+        if (
+          item.avatar_shape_url !== undefined ||
+          item.color_theme !== undefined
+        ) {
+          existing.colorReplacements = await resolveItemColorsAsync(
+            item,
+            existing.colorReplacements,
+            prevImageUrl,
+          );
+        }
+      }),
+    );
 
-      if (item.avatar_shape_url !== undefined) {
-        existing.imageUrl = item.avatar_shape_url;
-        existing.mediaType = 'shape';
-      } else if (item.avatar_image_url !== undefined) {
-        existing.imageUrl = item.avatar_image_url;
-        existing.mediaType = 'image';
-      }
+    return;
+  }
 
-      if (item.name !== undefined) existing.name = item.name;
+  const itemsToMerge = items.filter((item) => item.insert_at === undefined);
 
-      if (item.position !== undefined) existing.position = item.position;
+  const updatedItems = await Promise.all(
+    itemsToMerge.map(async (item, index) => {
+      const existing = content.items?.[index];
 
-      if (item.testimonial !== undefined)
-        existing.testimonials = item.testimonial;
+      const imageUrl =
+        item.avatar_shape_url ??
+        item.avatar_image_url ??
+        existing?.imageUrl ??
+        '';
+      const mediaType = item.avatar_shape_url
+        ? 'shape'
+        : item.avatar_image_url
+          ? 'image'
+          : existing?.mediaType ?? 'image';
 
-      if (
-        item.avatar_shape_url !== undefined ||
-        item.color_theme !== undefined
-      ) {
-        existing.colorReplacements = await resolveItemColorsAsync(
+      return {
+        ...(existing || {}),
+        imageUrl,
+        name: item.name ?? existing?.name ?? '',
+        position: item.position ?? existing?.position ?? '',
+        testimonials: item.testimonial ?? existing?.testimonials ?? '',
+        colorReplacements: await resolveItemColorsAsync(
           item,
-          existing.colorReplacements,
-          prevImageUrl,
-        );
-      }
+          existing?.colorReplacements,
+          existing?.imageUrl,
+        ),
+        mediaType,
+      };
+    }),
+  );
 
-      repositionItemByAnchor(content.items, existing, item.move_before_item_id);
-    } else {
-      const newItem = {
-        id: generateItemId(),
-        imageUrl: item.avatar_shape_url ?? item.avatar_image_url ?? '',
-        name: item.name ?? '',
-        position: item.position ?? '',
-        testimonials: item.testimonial ?? '',
-        colorReplacements: await resolveItemColorsAsync(item, [], undefined),
-        mediaType: item.avatar_shape_url ? 'shape' : 'image',
-      } as TestimonialSectionContent['items'][number];
-
-      repositionItemByAnchor(content.items, newItem, item.move_before_item_id);
-    }
+  if (
+    !replaceAll &&
+    content.items &&
+    content.items.length > itemsToMerge.length
+  ) {
+    updatedItems.push(...content.items.slice(itemsToMerge.length));
   }
+
+  content.items = updatedItems;
 };
 
 export class TestimonialSectionBuilder extends BaseSectionBuilder<TestimonialSectionContent> {
@@ -211,29 +228,75 @@ export class TestimonialSectionBuilder extends BaseSectionBuilder<TestimonialSec
       };
     }
 
-    if (args._replace_items && args.items && Array.isArray(args.items)) {
-      // Full replacement: discard existing items and rebuild from the payload.
-      await applyTestimonialItemsAsync(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 applyTestimonialItemsAsync(content, args.items);
+      } else {
+        await mergeTestimonialItemsAsync(
+          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 mergeTestimonialItemsAsync(
-        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,
+      );
+      const sortedInserts = [...insertItems].sort(
+        (a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0),
       );
+
+      for (const item of sortedInserts) {
+        const pos = Math.max(
+          0,
+          Math.min(item.insert_at ?? 0, content.items?.length ?? 0),
+        );
+        const newItem = {
+          imageUrl: item.avatar_shape_url ?? item.avatar_image_url ?? '',
+          name: item.name ?? '',
+          position: item.position ?? '',
+          testimonials: item.testimonial ?? '',
+          colorReplacements: await resolveItemColorsAsync(item, [], undefined),
+          mediaType: item.avatar_shape_url ? 'shape' : 'image',
+        };
+
+        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;
+        }
+      }
     }
 
     // Post-merge cap check. itemCapCheck only fires for create / update with
-    // _replace_items, so adding new items to an already-full section silently
-    // bloats the array. Surface as an error so the AI retry loop gets a signal
-    // and can reissue with _remove_item_ids or fewer additions.
+    // _replace_items, so insert_at on an already-full section silently bloats
+    // the array. Surface as an error so the AI retry loop gets a signal and
+    // can reissue with _remove_item_indices or fewer inserts.
     // brandSite key mirrors base-section-builder's hardcoded brandPageType.
     const cap = TESTIMONIAL_ITEM_CAP.brandSite;
 

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

@@ -19,12 +19,6 @@ import {
 } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateTextSection } from '../section-rules/text-section.rules';
-import {
-  ensureItemIds,
-  generateItemId,
-  removeItemsByIds,
-  repositionItemByAnchor,
-} from '../item-id-utils';
 
 /** Resolve a RichTextField (string or TiptapDocument) to a plain HTML string. */
 const resolveText = (value: unknown): { html: string; wasTiptap: boolean } => {
@@ -58,7 +52,6 @@ const createTextItem = (
   const { html, wasTiptap } = resolveText(item.text);
 
   return {
-    id: item.item_id || generateItemId(),
     text: html,
     textStyle: clearTextStyleTypeIfTiptap(
       textStyle,
@@ -68,10 +61,6 @@ const createTextItem = (
   };
 };
 
-/**
- * Full replacement: discard existing items and rebuild from the payload,
- * assigning a stable id to each new item.
- */
 const applyTextItems = (
   content: TextContent,
   items: TextSectionItem[],
@@ -82,33 +71,26 @@ const applyTextItems = (
   );
 };
 
-/**
- * Id-based merge (BP-5603): mirrors the section-level id contract one level
- * deeper.
- *   - item with `item_id` matching an existing item → update in place and
- *     reposition if `move_before_item_id` is set; unknown id is skipped.
- *   - item without `item_id`                        → add a new item,
- *     positioned by `move_before_item_id`.
- *   - `removeIds`                                   → delete by id.
- *
- * Existing items are id-backfilled first so legacy sections without ids
- * become referenceable the moment this builder processes them.
- */
 const mergeTextItems = (
   content: TextContent,
   items: TextSectionItem[],
-  removeIds: string[] | undefined,
+  replaceAll: boolean,
   textStyleOptions: TextStyleOptions | undefined,
 ): void => {
-  ensureItemIds(content.textItems);
-  content.textItems = removeItemsByIds(content.textItems, removeIds);
+  const hasIndexedItems = items.some((item) => item.item_index !== undefined);
+
+  if (hasIndexedItems) {
+    for (const item of items) {
+      const targetIndex = item.item_index;
 
-  for (const item of items) {
-    if (item.item_id) {
-      const existing = content.textItems?.find((i) => i.id === item.item_id);
+      if (
+        targetIndex === undefined ||
+        targetIndex < 0 ||
+        !content.textItems?.[targetIndex]
+      )
+        continue;
 
-      // Unknown id — skip rather than guess at a position.
-      if (!existing) continue;
+      const existing = content.textItems[targetIndex];
 
       if (item.text !== undefined) {
         const { html, wasTiptap } = resolveText(item.text);
@@ -122,32 +104,51 @@ const mergeTextItems = (
       }
 
       if (item.text_style && typeof item.text_style === 'object') {
-        existing.textStyle = {
-          ...(existing.textStyle || {}),
-          ...item.text_style,
-        } as TextStyleDeclaration;
+        const mergedStyle = (
+          item.text_style
+            ? { ...(existing.textStyle || {}), ...item.text_style }
+            : existing.textStyle || {}
+        ) as TextStyleDeclaration;
+
+        existing.textStyle = mergedStyle;
       }
+    }
 
-      repositionItemByAnchor(
-        content.textItems!,
-        existing,
-        item.move_before_item_id,
-      );
-    } else {
-      const newItem = createTextItem(
-        item,
-        content.textStyle || {},
+    return;
+  }
+
+  const itemsToMerge = items.filter((item) => item.insert_at === undefined);
+
+  const updatedItems = itemsToMerge.map((item, index) => {
+    const existing = content.textItems?.[index];
+    const baseStyle = existing?.textStyle || content.textStyle || {};
+
+    const mergedStyle = (
+      item.text_style ? { ...baseStyle, ...item.text_style } : baseStyle
+    ) as TextStyleDeclaration;
+
+    const resolved = item.text !== undefined ? resolveText(item.text) : null;
+    const text = resolved ? resolved.html : existing?.text ?? '';
+
+    return {
+      text,
+      textStyle: clearTextStyleTypeIfTiptap(
+        mergedStyle,
+        resolved?.wasTiptap ?? false,
         textStyleOptions,
-      );
+      ),
+    };
+  });
 
-      content.textItems = content.textItems ?? [];
-      repositionItemByAnchor(
-        content.textItems,
-        newItem,
-        item.move_before_item_id,
-      );
-    }
+  if (
+    !replaceAll &&
+    content.textItems &&
+    content.textItems.length > itemsToMerge.length
+  ) {
+    updatedItems.push(...content.textItems.slice(itemsToMerge.length));
   }
+
+  content.textItems = updatedItems;
 };
 
 /**
@@ -235,31 +236,82 @@ export class TextSectionBuilder extends BaseSectionBuilder<TextContent> {
 
     const args = this.args as TextSectionArguments;
 
-    if (args._replace_items && args.items && Array.isArray(args.items)) {
-      // Full replacement: discard existing items and rebuild from the payload.
-      applyTextItems(content, args.items, textStyleOptions);
-    } else if (this.mode === 'create') {
-      if (args.items && Array.isArray(args.items)) {
+    if (args.items && Array.isArray(args.items)) {
+      if (this.mode === 'create') {
         applyTextItems(content, args.items, textStyleOptions);
       } else {
-        applySingleTextField(content, args, textStyleOptions);
+        mergeTextItems(
+          content,
+          args.items,
+          !!args._replace_items,
+          textStyleOptions,
+        );
       }
-    } else if (
-      (args.items && Array.isArray(args.items)) ||
-      args._remove_item_ids?.length
-    ) {
-      // Update: id-based add / edit / move / remove in a single pass.
-      mergeTextItems(
-        content,
-        args.items ?? [],
-        args._remove_item_ids,
-        textStyleOptions,
-      );
     } else {
-      // No items array: apply the single text/text_style shorthand fields.
       applySingleTextField(content, args, textStyleOptions);
     }
 
+    // Phase 2: Item operations (remove, insert, reorder)
+    if (args._remove_item_indices?.length && content.textItems) {
+      const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
+
+      for (const idx of sorted) {
+        if (idx >= 0 && idx < content.textItems.length) {
+          content.textItems.splice(idx, 1);
+        }
+      }
+    }
+
+    if (args.items && Array.isArray(args.items)) {
+      const insertItems = args.items.filter(
+        (item) => item.insert_at !== undefined && item.item_index === undefined,
+      );
+      const sortedInserts = [...insertItems].sort(
+        (a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0),
+      );
+
+      for (const item of sortedInserts) {
+        const pos = Math.max(
+          0,
+          Math.min(item.insert_at ?? 0, content.textItems?.length ?? 0),
+        );
+        const baseStyle = content.textStyle || {};
+        const textStyle = (
+          item.text_style
+            ? { ...baseStyle, ...item.text_style }
+            : { ...baseStyle }
+        ) as TextStyleDeclaration;
+
+        const { html, wasTiptap } = resolveText(item.text);
+        const newItem: TextItem = {
+          text: html,
+          textStyle: clearTextStyleTypeIfTiptap(
+            textStyle,
+            wasTiptap,
+            textStyleOptions,
+          ),
+        };
+
+        content.textItems = content.textItems ?? [];
+        content.textItems.splice(pos, 0, newItem);
+      }
+    }
+
+    if (args._reorder_items?.length && content.textItems) {
+      const newOrder = args._reorder_items;
+      const unique = new Set(newOrder);
+
+      if (unique.size === newOrder.length) {
+        const reordered = newOrder
+          .filter((idx) => idx >= 0 && idx < content.textItems!.length)
+          .map((idx) => content.textItems![idx]);
+
+        if (reordered.length === content.textItems.length) {
+          content.textItems = reordered;
+        }
+      }
+    }
+
     if (args.background_color !== undefined) {
       content.backgroundColor = {
         ...content.backgroundColor,

package/src/metadata-builder/parsers/ai-toolcall-parser.ts

@@ -202,17 +202,8 @@ export interface ReorderPagesArguments {
 export interface UndoArguments {}
 
 export interface FooterSocialLinkItem {
-  /**
-   * Stable id of the existing link to update or move. Omit to ADD a new link.
-   * Mirrors the section-level item_id convention (BP-5603).
-   */
-  item_id?: string;
-  /**
-   * Id of an existing link to position this link before (insert for new links,
-   * move for existing ones). Use "__end__" for the end of the list. Omit to
-   * leave an existing link in place / append a new link.
-   */
-  move_before_item_id?: string;
+  item_index?: number;
+  insert_at?: number;
   social_link_icon?: string;
   url?: string;
 }
@@ -236,8 +227,8 @@ export interface UpdateFooterArguments {
   copyright_text_font_family?: string;
   social_links?: FooterSocialLinkItem[];
   _replace_social_links?: boolean;
-  /** Stable ids of social links to remove. Order-independent (replaces index-based _remove_social_link_indices). */
-  _remove_social_link_ids?: string[];
+  _remove_social_link_indices?: number[];
+  _reorder_social_links?: number[];
   /** Desktop-only styling (display_style, background_color, icon_color, is_logo_visible, logo sizes). */
   desktop?: ViewportFooterOverrides;
   /** Mobile-only styling (display_style, background_color, icon_color, is_logo_visible, logo sizes). */