@designcrowd/library.brand-page 6.0.12 → 6.0.13

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

@@ -25,6 +25,12 @@ 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,
@@ -50,6 +56,7 @@ 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 || '',
@@ -60,101 +67,77 @@ 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[],
-  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];
-        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,
-          );
-        }
-      }),
-    );
+  ensureItemIds(content.items);
+  content.items = removeItemsByIds(content.items, removeIds);
 
-    return;
-  }
+  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 itemsToMerge = items.filter((item) => item.insert_at === undefined);
+      const prevImageUrl = existing.imageUrl;
 
-  const updatedItems = await Promise.all(
-    itemsToMerge.map(async (item, index) => {
-      const existing = content.items?.[index];
+      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';
+      }
 
-      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.name !== undefined) existing.name = item.name;
 
-      return {
-        ...(existing || {}),
-        imageUrl,
-        name: item.name ?? existing?.name ?? '',
-        position: item.position ?? existing?.position ?? '',
-        testimonials: item.testimonial ?? existing?.testimonials ?? '',
-        colorReplacements: await resolveItemColorsAsync(
+      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,
-          existing?.imageUrl,
-        ),
-        mediaType,
-      };
-    }),
-  );
+          existing.colorReplacements,
+          prevImageUrl,
+        );
+      }
 
-  if (
-    !replaceAll &&
-    content.items &&
-    content.items.length > itemsToMerge.length
-  ) {
-    updatedItems.push(...content.items.slice(itemsToMerge.length));
+      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);
+    }
   }
-
-  content.items = updatedItems;
 };
 
 export class TestimonialSectionBuilder extends BaseSectionBuilder<TestimonialSectionContent> {
@@ -228,75 +211,29 @@ export class TestimonialSectionBuilder extends BaseSectionBuilder<TestimonialSec
       };
     }
 
-    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 applyTestimonialItemsAsync(content, args.items);
+    } else if (this.mode === 'create') {
+      if (args.items && Array.isArray(args.items)) {
         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);
-        }
       }
-    }
-
-    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),
+    } 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,
       );
-
-      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 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.
+    // _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.
     // 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,6 +19,12 @@ 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 } => {
@@ -52,6 +58,7 @@ const createTextItem = (
   const { html, wasTiptap } = resolveText(item.text);
 
   return {
+    id: item.item_id || generateItemId(),
     text: html,
     textStyle: clearTextStyleTypeIfTiptap(
       textStyle,
@@ -61,6 +68,10 @@ 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[],
@@ -71,26 +82,33 @@ 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[],
-  replaceAll: boolean,
+  removeIds: string[] | undefined,
   textStyleOptions: TextStyleOptions | undefined,
 ): void => {
-  const hasIndexedItems = items.some((item) => item.item_index !== undefined);
-
-  if (hasIndexedItems) {
-    for (const item of items) {
-      const targetIndex = item.item_index;
+  ensureItemIds(content.textItems);
+  content.textItems = removeItemsByIds(content.textItems, removeIds);
 
-      if (
-        targetIndex === undefined ||
-        targetIndex < 0 ||
-        !content.textItems?.[targetIndex]
-      )
-        continue;
+  for (const item of items) {
+    if (item.item_id) {
+      const existing = content.textItems?.find((i) => i.id === item.item_id);
 
-      const existing = content.textItems[targetIndex];
+      // Unknown id — skip rather than guess at a position.
+      if (!existing) continue;
 
       if (item.text !== undefined) {
         const { html, wasTiptap } = resolveText(item.text);
@@ -104,51 +122,32 @@ const mergeTextItems = (
       }
 
       if (item.text_style && typeof item.text_style === 'object') {
-        const mergedStyle = (
-          item.text_style
-            ? { ...(existing.textStyle || {}), ...item.text_style }
-            : existing.textStyle || {}
-        ) as TextStyleDeclaration;
-
-        existing.textStyle = mergedStyle;
+        existing.textStyle = {
+          ...(existing.textStyle || {}),
+          ...item.text_style,
+        } as TextStyleDeclaration;
       }
-    }
-
-    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,
+      repositionItemByAnchor(
+        content.textItems!,
+        existing,
+        item.move_before_item_id,
+      );
+    } else {
+      const newItem = createTextItem(
+        item,
+        content.textStyle || {},
         textStyleOptions,
-      ),
-    };
-  });
+      );
 
-  if (
-    !replaceAll &&
-    content.textItems &&
-    content.textItems.length > itemsToMerge.length
-  ) {
-    updatedItems.push(...content.textItems.slice(itemsToMerge.length));
+      content.textItems = content.textItems ?? [];
+      repositionItemByAnchor(
+        content.textItems,
+        newItem,
+        item.move_before_item_id,
+      );
+    }
   }
-
-  content.textItems = updatedItems;
 };
 
 /**
@@ -176,6 +175,7 @@ const applySingleTextField = (
     } else {
       content.textItems = [
         {
+          id: generateItemId(),
           text: html,
           textStyle: clearTextStyleTypeIfTiptap(
             { ...(content.textStyle || {}) },
@@ -236,82 +236,31 @@ export class TextSectionBuilder extends BaseSectionBuilder<TextContent> {
 
     const args = this.args as TextSectionArguments;
 
-    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.
+      applyTextItems(content, args.items, textStyleOptions);
+    } else if (this.mode === 'create') {
+      if (args.items && Array.isArray(args.items)) {
         applyTextItems(content, args.items, textStyleOptions);
       } else {
-        mergeTextItems(
-          content,
-          args.items,
-          !!args._replace_items,
-          textStyleOptions,
-        );
+        applySingleTextField(content, args, 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/builders/section-field-maps.ts

@@ -37,6 +37,13 @@ function defineFieldMap<C extends Content>(
   return map;
 }
 
+// BP-5687: vertical padding fields shared by all sections that render
+// contentPaddingStyle (see src/brand-page/utils/content-padding.util.ts).
+const PADDING_FIELDS = {
+  padding_top: 'topPadding',
+  padding_bottom: 'bottomPadding',
+} as const;
+
 const bannerFields = defineFieldMap<BannerSectionContent>({
   title: 'title',
   description: 'description',
@@ -45,6 +52,7 @@ const bannerFields = defineFieldMap<BannerSectionContent>({
   background_image_url: 'imageUrl',
   background_shape_url: 'imageUrl',
   display_style: 'displayStyle',
+  ...PADDING_FIELDS,
 });
 
 const bookingFields = defineFieldMap<BookingSectionContent>({
@@ -52,6 +60,7 @@ const bookingFields = defineFieldMap<BookingSectionContent>({
   description: 'description',
   button_text: 'buttonText',
   button_url: 'url',
+  ...PADDING_FIELDS,
 });
 
 const aboutFields = defineFieldMap<AboutSectionContent>({
@@ -60,12 +69,14 @@ const aboutFields = defineFieldMap<AboutSectionContent>({
   about_image_url: 'imageUrl',
   about_shape_url: 'imageUrl',
   display_style: 'displayStyle',
+  ...PADDING_FIELDS,
 });
 
 const testimonialFields = defineFieldMap<TestimonialSectionContent>({
   title: 'title',
   display_style: 'displayStyle',
   // items handled separately
+  ...PADDING_FIELDS,
 });
 
 const imagesSectionFields = defineFieldMap<ImagesSectionContent>({
@@ -75,6 +86,7 @@ const imagesSectionFields = defineFieldMap<ImagesSectionContent>({
   aspect_ratio: 'aspectRatio',
   are_images_full_width: 'areImagesFullWidth',
   // items handled separately
+  ...PADDING_FIELDS,
 });
 
 const shapesSectionFields = defineFieldMap<ShapesSectionContent>({
@@ -83,11 +95,13 @@ const shapesSectionFields = defineFieldMap<ShapesSectionContent>({
   display_style: 'displayStyle',
   size: 'size',
   // items handled separately
+  ...PADDING_FIELDS,
 });
 
 const textFields = defineFieldMap<TextContent>({
   text: 'text',
   column_style: 'columnStyle',
+  ...PADDING_FIELDS,
 });
 
 const profileFields = defineFieldMap<ProfileContent>({
@@ -106,17 +120,20 @@ const contactFormFields = defineFieldMap<ContactFormContent>({
   header_image_url: 'imageUrl',
   display_style: 'displayStyle',
   layout_style: 'layoutStyle',
+  ...PADDING_FIELDS,
 });
 
 const mailingListFields = defineFieldMap<MailingListContent>({
   button_text: 'buttonText',
   accepted_fields: 'acceptedFields',
+  ...PADDING_FIELDS,
 });
 
 const socialLinksFields = defineFieldMap<SocialLinksContent>({
   title: 'title',
   icon_style: 'iconDisplayStyle',
   // links handled separately
+  ...PADDING_FIELDS,
 });
 
 const dividerFields = defineFieldMap<DividerSectionContent>({
@@ -132,6 +149,7 @@ const imageFields = defineFieldMap<ImageContent>({
 const imageGalleryFields = defineFieldMap<ImageGalleryContent>({
   is_full_width: 'isFullWidth',
   // images handled separately
+  ...PADDING_FIELDS,
 });
 
 const buttonWithIconFields = defineFieldMap<ButtonContent>({