@designcrowd/library.brand-page 6.0.3 → 6.0.4

package/src/metadata-builder/builders/footer-builder.ts

@@ -10,22 +10,17 @@ import {
 import type {
   UpdateFooterArguments,
   ViewportFooterOverrides,
-  FooterSocialLinkItem,
 } from '../parsers/ai-toolcall-parser';
 import type { Logger } from '../logger';
-import type {
-  TextStyleDeclaration,
-  TextStyleOptions,
-} from '../../brand-page/models/styles.model';
+import type { TextStyleOptions } from '../../brand-page/models/styles.model';
 import { FOOTER_CHECKS } from './section-rules/footer.rules';
+import { applyDetachedStyleOverride } from './section-field-utils';
 import {
-  applyDetachedStyleOverride,
-  normalizeStyleValue,
-} from './section-field-utils';
-
-type FooterSocialLink = NonNullable<
-  AbstractPageFooterStyles['socialLinks']
->[number];
+  ensureItemIds,
+  generateItemId,
+  removeItemsByIds,
+  repositionItemByAnchor,
+} from './item-id-utils';
 
 const normaliseSocialUrl = (url: string): string => {
   for (const prefix of ['mailto:', 'tel:']) {
@@ -35,113 +30,6 @@ const normaliseSocialUrl = (url: string): string => {
   return url;
 };
 
-const makeSocialLink = (
-  icon: string | undefined,
-  url: string | undefined,
-): FooterSocialLink =>
-  ({
-    imageUrl: icon || '',
-    url: normaliseSocialUrl(url || ''),
-    imageTitle: '',
-    width: 0,
-    height: 0,
-    imageLink: '',
-  }) as FooterSocialLink;
-
-const hasSocialLinkMutation = (args: UpdateFooterArguments): boolean =>
-  args._replace_social_links === true ||
-  (args._remove_social_link_indices?.length ?? 0) > 0 ||
-  (args._reorder_social_links?.length ?? 0) > 0 ||
-  (args.social_links?.length ?? 0) > 0;
-
-/**
- * Social links are a GLOBAL footer concern — one logical list that both
- * viewports render identically. Derive the new list ONCE from the current one
- * WITHOUT mutating the input, so the caller can assign an independent copy to
- * each viewport.
- *
- * Why this can't mutate per-viewport in place: footers migrated from the legacy
- * single `footerStyles` model (migration-01) share ONE `socialLinks` array
- * reference across pageFooterDesktop and pageFooterMobile, and `cloneDeep`
- * preserves that shared reference. Running an in-place `splice` once per
- * viewport therefore applies it TWICE to the same array — e.g. one requested
- * removal index drops two links. Compute-once + assign-fresh is correct for
- * both shared (legacy) and independent (new-model) footers.
- */
-const computeSocialLinks = (
-  current: FooterSocialLink[] | undefined,
-  args: UpdateFooterArguments,
-): FooterSocialLink[] => {
-  // _replace_social_links: replace entire list (empty/absent social_links = clear all).
-  // A replacement supersedes every other social link mutation.
-  if (args._replace_social_links) {
-    return (args.social_links ?? []).map((l) =>
-      makeSocialLink(l.social_link_icon, l.url),
-    );
-  }
-
-  const links: FooterSocialLink[] = [...(current ?? [])];
-
-  // item_index-based updates for existing links — replace the item reference
-  // (never mutate the original object, which may be shared across viewports).
-  for (const link of args.social_links ?? []) {
-    if (link.item_index === undefined) continue;
-
-    const existing = links[link.item_index];
-
-    if (!existing) continue;
-
-    links[link.item_index] = {
-      ...existing,
-      ...(link.social_link_icon !== undefined
-        ? { imageUrl: link.social_link_icon }
-        : {}),
-      ...(link.url !== undefined ? { url: normaliseSocialUrl(link.url) } : {}),
-    };
-  }
-
-  // Remove by index (descending order to preserve indices during splice).
-  if (args._remove_social_link_indices?.length) {
-    const sorted = [...args._remove_social_link_indices].sort((a, b) => b - a);
-
-    for (const idx of sorted) {
-      if (idx >= 0 && idx < links.length) links.splice(idx, 1);
-    }
-  }
-
-  // Insert new links (descending insert_at order to preserve positions).
-  const insertLinks = (args.social_links ?? []).filter(
-    (l): l is FooterSocialLinkItem & { insert_at: number } =>
-      l.insert_at !== undefined && l.item_index === undefined,
-  );
-  const sortedInserts = [...insertLinks].sort(
-    (a, b) => b.insert_at - a.insert_at,
-  );
-
-  for (const link of sortedInserts) {
-    const pos = Math.max(0, Math.min(link.insert_at, links.length));
-
-    links.splice(pos, 0, makeSocialLink(link.social_link_icon, link.url));
-  }
-
-  // Reorder (requires ALL indices — partial reorder is not supported).
-  if (args._reorder_social_links?.length) {
-    const newOrder = args._reorder_social_links;
-    const unique = new Set(newOrder);
-
-    if (
-      unique.size === newOrder.length &&
-      newOrder.every((idx) => idx >= 0 && idx < links.length)
-    ) {
-      const reordered = newOrder.map((idx) => links[idx]);
-
-      if (reordered.length === links.length) return reordered;
-    }
-  }
-
-  return links;
-};
-
 const applyGlobalFooterChanges = (
   footer: AbstractPageFooterStyles,
   args: UpdateFooterArguments,
@@ -150,27 +38,85 @@ const applyGlobalFooterChanges = (
   if (args.copyright_text !== undefined)
     footer.copyrightText = args.copyright_text;
 
-  // copyright_text_style is the same text-style object sections use (typography
-  // + colour). Normalise each value the way section styles are normalised
-  // (letterSpacing int→em, lineHeight snap, null→''), then detach from the
-  // global preset via the override helper so a single call resolves the preset
-  // and clears textStyleType once — see resolveGlobalPresetIntoStyle (BP-5420).
-  if (args.copyright_text_style) {
-    const updates: Partial<TextStyleDeclaration> = {};
+  if (args.copyright_text_font_family !== undefined)
+    footer.copyrightStyle = applyDetachedStyleOverride(
+      footer.copyrightStyle,
+      { fontFamily: args.copyright_text_font_family },
+      textStyleOptions,
+    );
 
-    for (const [key, value] of Object.entries(args.copyright_text_style)) {
-      const normalized = normalizeStyleValue(key, value);
+  const links = args.social_links;
 
-      if (normalized !== undefined)
-        (updates as Record<string, unknown>)[key] = normalized;
-    }
+  // _replace_social_links: replace entire list (empty/absent social_links = clear all).
+  // When replacing, all other social link mutations (remove, insert, reorder) are skipped —
+  // they are superseded by the replacement and running them would cause duplicates.
+  if (args._replace_social_links) {
+    footer.socialLinks = (links ?? []).map((l) => ({
+      id: generateItemId(),
+      imageUrl: l.social_link_icon || '',
+      url: normaliseSocialUrl(l.url || ''),
+      imageTitle: '',
+      width: 0,
+      height: 0,
+      imageLink: '',
+    }));
+  } else {
+    // Targeted mutations — only run when NOT replacing the entire list.
+    // BP-5603: id-based contract (item_id / move_before_item_id / _remove_social_link_ids).
+    // Backfill ids on legacy links so they become referenceable after this call.
+    ensureItemIds(footer.socialLinks);
+
+    // Remove by id (order-independent — no index shifting needed).
+    footer.socialLinks = removeItemsByIds(
+      footer.socialLinks,
+      args._remove_social_link_ids,
+    );
 
-    if (Object.keys(updates).length > 0)
-      footer.copyrightStyle = applyDetachedStyleOverride(
-        footer.copyrightStyle,
-        updates,
-        textStyleOptions,
-      );
+    // Update existing links (item_id present) or insert new links (no item_id).
+    if (links?.length) {
+      footer.socialLinks = footer.socialLinks ?? [];
+
+      for (const link of links) {
+        if (link.item_id) {
+          // Update existing link in place; reposition if move_before_item_id set.
+          const existing = footer.socialLinks.find(
+            (l) => l.id === link.item_id,
+          );
+
+          // Unknown id — skip rather than guess at a position.
+          if (!existing) continue;
+
+          if (link.social_link_icon !== undefined)
+            existing.imageUrl = link.social_link_icon;
+
+          if (link.url !== undefined)
+            existing.url = normaliseSocialUrl(link.url);
+
+          repositionItemByAnchor(
+            footer.socialLinks,
+            existing,
+            link.move_before_item_id,
+          );
+        } else {
+          // New link — assign a stable id and position via move_before_item_id.
+          const newLink = {
+            id: generateItemId(),
+            imageUrl: link.social_link_icon || '',
+            url: normaliseSocialUrl(link.url || ''),
+            imageTitle: '',
+            width: 0,
+            height: 0,
+            imageLink: '' as string | false,
+          };
+
+          repositionItemByAnchor(
+            footer.socialLinks,
+            newLink,
+            link.move_before_item_id,
+          );
+        }
+      }
+    }
   }
 };
 
@@ -195,6 +141,12 @@ const applyViewportFooterChanges = (
       fill: overrides.icon_color,
     };
 
+  if (overrides.copyright_text_color !== undefined)
+    footer.copyrightStyle = {
+      ...footer.copyrightStyle,
+      color: overrides.copyright_text_color,
+    };
+
   if (overrides.is_logo_visible !== undefined)
     footer.isLogoVisible = overrides.is_logo_visible;
 
@@ -246,30 +198,13 @@ export class FooterBuilder extends BaseMetadataBuilder<UpdateFooterArguments> {
     const args = this.request.payload ?? {};
     const textStyleOptions = model.styles?.textStyles?.textStyleOptions;
 
-    // Global scalar/style fields (copyright text + font) apply to both
-    // viewports. These are idempotent assignments, safe to run per-viewport.
+    // Global fields (copyright_text, social links) always apply to both viewports.
     if (model.pageFooterDesktop)
       applyGlobalFooterChanges(model.pageFooterDesktop, args, textStyleOptions);
 
     if (model.pageFooterMobile)
       applyGlobalFooterChanges(model.pageFooterMobile, args, textStyleOptions);
 
-    // Social links are a single global list. Derive the new list ONCE, then
-    // assign an INDEPENDENT copy to each viewport — never mutate a (possibly
-    // shared) viewport array in place. See computeSocialLinks.
-    if (hasSocialLinkMutation(args)) {
-      const current =
-        model.pageFooterDesktop?.socialLinks ??
-        model.pageFooterMobile?.socialLinks;
-      const updated = computeSocialLinks(current, args);
-
-      if (model.pageFooterDesktop)
-        model.pageFooterDesktop.socialLinks = updated.map((l) => ({ ...l }));
-
-      if (model.pageFooterMobile)
-        model.pageFooterMobile.socialLinks = updated.map((l) => ({ ...l }));
-    }
-
     // Viewport-specific styling via explicit sub-objects.
     if (args.desktop && model.pageFooterDesktop)
       applyViewportFooterChanges(model.pageFooterDesktop, args.desktop);

package/src/metadata-builder/builders/item-id-utils.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect } from 'vitest';
+import {
+  END_ITEM_ANCHOR,
+  ensureBrandPageItemIds,
+  ensureItemIds,
+  generateItemId,
+  removeItemsByIds,
+  repositionItemByAnchor,
+} from './item-id-utils';
+import type { BrandPageModel } from '../../brand-page/models';
+
+type Item = { id?: string; label: string };
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const items = (...labels: string[]): Item[] =>
+  labels.map((label) => ({ id: label, label }));
+
+const labels = (list: Item[]): string[] => list.map((i) => i.label);
+
+describe('generateItemId', () => {
+  it('returns unique uuid-shaped ids', () => {
+    const a = generateItemId();
+    const b = generateItemId();
+
+    expect(a).not.toBe(b);
+    expect(a).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+  });
+});
+
+describe('ensureItemIds', () => {
+  it('backfills only the items missing an id, preserving existing ones', () => {
+    const list: Item[] = [
+      { id: 'keep', label: 'a' },
+      { label: 'b' },
+      { id: '', label: 'c' },
+    ];
+
+    ensureItemIds(list);
+
+    expect(list[0].id).toBe('keep');
+    expect(list[1].id).toBeTruthy();
+    expect(list[2].id).toBeTruthy();
+    expect(new Set(list.map((i) => i.id)).size).toBe(3);
+  });
+
+  it('is a no-op for undefined', () => {
+    expect(() => ensureItemIds(undefined)).not.toThrow();
+  });
+});
+
+describe('removeItemsByIds', () => {
+  it('removes by id regardless of order (no index shifting)', () => {
+    const result = removeItemsByIds(items('a', 'b', 'c', 'd'), ['c', 'a']);
+
+    expect(labels(result)).toEqual(['b', 'd']);
+  });
+
+  it('returns the list unchanged when no ids given', () => {
+    const list = items('a', 'b');
+
+    expect(removeItemsByIds(list, undefined)).toBe(list);
+    expect(removeItemsByIds(list, [])).toBe(list);
+  });
+
+  it('returns [] for undefined items', () => {
+    expect(removeItemsByIds(undefined, ['x'])).toEqual([]);
+  });
+});
+
+describe('repositionItemByAnchor', () => {
+  it('appends a new item when no anchor is given', () => {
+    const list = items('a', 'b');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, undefined);
+
+    expect(labels(list)).toEqual(['a', 'b', 'new']);
+  });
+
+  it('leaves an existing item in place when no anchor is given', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, list[1], undefined);
+
+    expect(labels(list)).toEqual(['a', 'b', 'c']);
+  });
+
+  it('inserts a new item before the anchor id', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, 'b');
+
+    expect(labels(list)).toEqual(['a', 'new', 'b', 'c']);
+  });
+
+  it('moves an existing item before the anchor id', () => {
+    const list = items('a', 'b', 'c', 'd');
+
+    // move 'd' before 'b'
+    repositionItemByAnchor(list, list[3], 'b');
+
+    expect(labels(list)).toEqual(['a', 'd', 'b', 'c']);
+  });
+
+  it('moves an existing item to the end with the __end__ sentinel', () => {
+    const list = items('a', 'b', 'c');
+
+    repositionItemByAnchor(list, list[0], END_ITEM_ANCHOR);
+
+    expect(labels(list)).toEqual(['b', 'c', 'a']);
+  });
+
+  it('falls through to the end when the anchor id is not found', () => {
+    const list = items('a', 'b');
+
+    repositionItemByAnchor(list, { id: 'new', label: 'new' }, 'missing');
+
+    expect(labels(list)).toEqual(['a', 'b', 'new']);
+  });
+});
+
+describe('ensureBrandPageItemIds', () => {
+  const makeModel = (): BrandPageModel =>
+    ({
+      pages: [
+        {
+          contents: [
+            {
+              type: 'image-gallery',
+              images: [{ imageUrl: 'a' }, { imageUrl: 'b' }],
+            },
+            {
+              type: 'testimonial-section',
+              items: [{ id: 'keep-me', name: 'X' }, { name: 'Y' }],
+            },
+            { type: 'text', textItems: [{ text: 'hi' }] },
+            { type: 'social-links', links: [{ url: 'u' }] },
+            { type: 'divider-section' }, // no item arrays — must not throw
+          ],
+        },
+      ],
+      pageFooterDesktop: { socialLinks: [{ url: 'f' }] },
+      pageFooterMobile: { socialLinks: [{ url: 'm' }] },
+    }) as unknown as BrandPageModel;
+
+  it('stamps a uuid id onto every id-less nested item across sections + footer', () => {
+    const model = makeModel();
+
+    ensureBrandPageItemIds(model);
+
+    const c = model.pages[0].contents as any[];
+
+    expect(c[0].images[0].id).toMatch(UUID_RE);
+    expect(c[0].images[1].id).toMatch(UUID_RE);
+    expect(c[1].items[1].id).toMatch(UUID_RE);
+    expect(c[2].textItems[0].id).toMatch(UUID_RE);
+    expect(c[3].links[0].id).toMatch(UUID_RE);
+    expect((model.pageFooterDesktop as any).socialLinks[0].id).toMatch(UUID_RE);
+    expect((model.pageFooterMobile as any).socialLinks[0].id).toMatch(UUID_RE);
+  });
+
+  it('preserves existing ids (idempotent)', () => {
+    const model = makeModel();
+
+    ensureBrandPageItemIds(model);
+    const first = (model.pages[0].contents as any[])[1].items[0].id;
+
+    ensureBrandPageItemIds(model);
+    const second = (model.pages[0].contents as any[])[1].items[0].id;
+
+    expect(first).toBe('keep-me');
+    expect(second).toBe('keep-me');
+  });
+
+  it('does not throw on an empty / partial model', () => {
+    expect(() => ensureBrandPageItemIds({} as BrandPageModel)).not.toThrow();
+    expect(() =>
+      ensureBrandPageItemIds({ pages: [] } as unknown as BrandPageModel),
+    ).not.toThrow();
+  });
+});

package/src/metadata-builder/builders/item-id-utils.ts

@@ -0,0 +1,117 @@
+import { v4 as uuidv4 } from 'uuid';
+import type { BrandPageModel } from '../../brand-page/models';
+
+/**
+ * Sentinel anchor meaning "the end of the list", mirroring the section-level
+ * `move_before_content_id: "__end__"` convention used in base-section-builder.
+ */
+export const END_ITEM_ANCHOR = '__end__';
+
+/** Generate a stable item id. Mirrors section-level `uuid.v4()` id generation. */
+export const generateItemId = (): string => uuidv4();
+
+/**
+ * Walk an entire BrandPageModel and backfill a stable uuid `id` onto every
+ * nested array item that lacks one (gallery images, images/shapes/testimonial
+ * items, text items, social links, and footer social links).
+ *
+ * BP-5603: this must run BEFORE the model is minified for the AI, so the same
+ * id the AI is shown (and copies into `item_id`) is the one the executor later
+ * matches. The maker holds a single live model instance for both the minify
+ * and the apply step, so mutating it here makes the ids round-trip; they then
+ * persist on the next save. Idempotent — existing ids are preserved.
+ */
+export const ensureBrandPageItemIds = (model: BrandPageModel): void => {
+  const ensureContentItemIds = (content: Record<string, unknown>): void => {
+    // Every array field that the minifier surfaces as a list of items.
+    for (const field of ['images', 'items', 'textItems', 'links'] as const) {
+      const arr = content[field];
+
+      if (Array.isArray(arr)) ensureItemIds(arr as { id?: string }[]);
+    }
+  };
+
+  for (const page of model.pages ?? []) {
+    for (const content of page.contents ?? []) {
+      ensureContentItemIds(content as unknown as Record<string, unknown>);
+    }
+  }
+
+  ensureItemIds(model.pageFooterDesktop?.socialLinks);
+  ensureItemIds(model.pageFooterMobile?.socialLinks);
+};
+
+/**
+ * Backfill ids onto any items missing one. Per BP-5603 this runs in the
+ * metadata builder when a section is processed, so the persisted metadata
+ * returned to the client gains stable ids that subsequent AI tool calls can
+ * reference. Mutates in place.
+ */
+export const ensureItemIds = <T extends { id?: string }>(
+  items: T[] | undefined,
+): void => {
+  if (!items) return;
+
+  for (const item of items) {
+    if (!item.id) item.id = generateItemId();
+  }
+};
+
+/**
+ * Remove items whose id appears in `ids`. Order-independent (no descending
+ * index sort needed) — the whole point of the id-based migration. Items
+ * without an id are never removed by id.
+ */
+export const removeItemsByIds = <T extends { id?: string }>(
+  items: T[] | undefined,
+  ids: string[] | undefined,
+): T[] => {
+  if (!items?.length) return items ?? [];
+
+  if (!ids?.length) return items;
+
+  const toRemove = new Set(ids);
+
+  return items.filter((item) => !item.id || !toRemove.has(item.id));
+};
+
+/**
+ * Position `item` within `items` relative to an anchor id — the item-level
+ * mirror of base-section-builder's `moveContent`:
+ *
+ * - `moveBeforeItemId === undefined`  → leave an existing item where it is;
+ *   append a new (not-yet-present) item to the end.
+ * - `moveBeforeItemId === "__end__"`  → move/insert at the very end.
+ * - anchor id found                   → insert immediately before it.
+ * - anchor id not found               → fall through to the end (same
+ *   forgiving behaviour as `moveContent`).
+ *
+ * Mutates `items` in place. `item` may be an existing element of `items`
+ * (a move) or a brand-new object (an insert).
+ */
+export const repositionItemByAnchor = <T extends { id?: string }>(
+  items: T[],
+  item: T,
+  moveBeforeItemId: string | undefined,
+): void => {
+  const currentIndex = items.indexOf(item);
+
+  if (moveBeforeItemId === undefined) {
+    if (currentIndex === -1) items.push(item);
+
+    return;
+  }
+
+  if (currentIndex !== -1) items.splice(currentIndex, 1);
+
+  const anchorIndex =
+    moveBeforeItemId === END_ITEM_ANCHOR
+      ? -1
+      : items.findIndex((i) => i.id === moveBeforeItemId);
+
+  if (anchorIndex !== -1) {
+    items.splice(anchorIndex, 0, item);
+  } else {
+    items.push(item);
+  }
+};