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

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

@@ -14,6 +14,10 @@ import { FooterBuilder } from './footer-builder';
  * The fix routes copyright style writes through `applyDetachedStyleOverride`,
  * which resolves the preset in and clears `textStyleType` so the per-element
  * override sticks.
+ *
+ * BP-5603: social link mutations converted from index-based to id-based
+ * (item_id / move_before_item_id / _remove_social_link_ids), mirroring the
+ * section-level move_before_content_id contract one level deeper.
  */
 
 const textStyleOptions = {
@@ -42,6 +46,37 @@ const makeModel = (copyrightStyle: Record<string, unknown>): BrandPageModel =>
     pageFooterMobile: { copyrightStyle: { ...copyrightStyle } },
   }) as unknown as BrandPageModel;
 
+const makeModelWithLinks = (
+  links: { id?: string; imageUrl: string; url: string }[],
+): BrandPageModel =>
+  ({
+    styles: { textStyles: { textStyleOptions } },
+    pageFooterDesktop: {
+      copyrightStyle: {},
+      socialLinks: links.map((l) => ({
+        id: l.id,
+        imageUrl: l.imageUrl,
+        url: l.url,
+        imageTitle: '',
+        width: 0,
+        height: 0,
+        imageLink: '',
+      })),
+    },
+    pageFooterMobile: {
+      copyrightStyle: {},
+      socialLinks: links.map((l) => ({
+        id: l.id,
+        imageUrl: l.imageUrl,
+        url: l.url,
+        imageTitle: '',
+        width: 0,
+        height: 0,
+        imageLink: '',
+      })),
+    },
+  }) as unknown as BrandPageModel;
+
 const run = (args: UpdateFooterArguments, model: BrandPageModel) =>
   new FooterBuilder({
     id: 'f1',
@@ -49,6 +84,10 @@ const run = (args: UpdateFooterArguments, model: BrandPageModel) =>
     payload: args,
   }).buildAsync(model);
 
+// ---------------------------------------------------------------------------
+// Copyright font (BP-5420)
+// ---------------------------------------------------------------------------
+
 describe('FooterBuilder — copyright font vs global style', () => {
   it('detaches from the global preset: applies the font, clears textStyleType, retains preset values', async () => {
     const model = makeModel({
@@ -75,139 +114,261 @@ describe('FooterBuilder — copyright font vs global style', () => {
   });
 });
 
-type Link = { imageUrl: string; url: string };
+// ---------------------------------------------------------------------------
+// Social links — id-based mutations (BP-5603)
+// ---------------------------------------------------------------------------
 
-const link = (imageUrl: string): Link => ({
-  imageUrl,
-  url: `https://${imageUrl}.com`,
-});
+describe('FooterBuilder — social links id-based mutations', () => {
+  it('backfills ids on legacy links that have none', async () => {
+    // Links without ids (legacy persisted data)
+    const model = makeModelWithLinks([
+      { imageUrl: 'facebook', url: 'https://fb.com' },
+      { imageUrl: 'instagram', url: 'https://ig.com' },
+    ]);
 
-/**
- * Footers migrated from the legacy single `footerStyles` model
- * (migration-01) split into desktop + mobile via a shallow spread, leaving
- * both viewports' `socialLinks` pointing at ONE shared array. `cloneDeep`
- * preserves that shared reference. This factory reproduces that shape.
- */
-const makeSharedSocialModel = (links: Link[]): BrandPageModel => {
-  const shared = links.map((l) => ({ ...l }));
+    const { model: out } = await run({}, model);
 
-  return {
-    styles: { textStyles: { textStyleOptions } },
-    pageFooterDesktop: { socialLinks: shared },
-    pageFooterMobile: { socialLinks: shared },
-  } as unknown as BrandPageModel;
-};
+    const links = out.pageFooterDesktop!.socialLinks;
 
-const makeIndependentSocialModel = (links: Link[]): BrandPageModel =>
-  ({
-    styles: { textStyles: { textStyleOptions } },
-    pageFooterDesktop: { socialLinks: links.map((l) => ({ ...l })) },
-    pageFooterMobile: { socialLinks: links.map((l) => ({ ...l })) },
-  }) as unknown as BrandPageModel;
+    expect(links[0].id).toBeTruthy();
+    expect(links[1].id).toBeTruthy();
+    expect(links[0].id).not.toBe(links[1].id);
+  });
 
-const socialIcons = (footer: { socialLinks?: Link[] } | undefined) =>
-  (footer?.socialLinks ?? []).map((l) => l.imageUrl);
-
-describe('FooterBuilder — social link removal (shared-array regression)', () => {
-  // Reproduces the bug: a single requested removal index dropped TWO links
-  // because both viewports shared one array and the builder spliced it twice.
-  it('removes exactly one link per requested index even when viewports share the array', async () => {
-    const model = makeSharedSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
-      link('youtube'),
+  it('updates an existing link in place by item_id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
     ]);
 
     const { model: out } = await run(
-      { _remove_social_link_indices: [2] },
+      {
+        social_links: [
+          { item_id: 'link-1', url: 'https://facebook.com/mybrand' },
+        ],
+      },
       model,
     );
 
-    expect(socialIcons(out.pageFooterDesktop)).toEqual([
-      'facebook',
-      'instagram',
-      'youtube',
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(2);
+    expect(links[0].url).toBe('https://facebook.com/mybrand');
+    expect(links[0].id).toBe('link-1');
+    // untouched link unchanged
+    expect(links[1].id).toBe('link-2');
+    expect(links[1].url).toBe('https://ig.com');
+  });
+
+  it('updates social_link_icon on an existing link', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
     ]);
-    expect(socialIcons(out.pageFooterMobile)).toEqual([
-      'facebook',
-      'instagram',
-      'youtube',
+
+    const { model: out } = await run(
+      {
+        social_links: [{ item_id: 'link-1', social_link_icon: 'facebook-v2' }],
+      },
+      model,
+    );
+
+    expect(out.pageFooterDesktop!.socialLinks[0].imageUrl).toBe('facebook-v2');
+  });
+
+  it('skips unknown item_id silently', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
     ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [{ item_id: 'no-such-id', url: 'https://nowhere.com' }],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(1);
+    expect(links[0].url).toBe('https://fb.com');
   });
 
-  it('un-shares the viewport arrays so later in-place edits cannot cross-corrupt', async () => {
-    const model = makeSharedSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
+  it('inserts a new link (no item_id) appended by default', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
     ]);
 
     const { model: out } = await run(
-      { _remove_social_link_indices: [0] },
+      {
+        social_links: [
+          { social_link_icon: 'instagram', url: 'https://ig.com' },
+        ],
+      },
       model,
     );
 
-    expect(out.pageFooterDesktop!.socialLinks).not.toBe(
-      out.pageFooterMobile!.socialLinks,
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(2);
+    expect(links[1].imageUrl).toBe('instagram');
+    expect(links[1].id).toBeTruthy();
+  });
+
+  it('inserts a new link before an anchor via move_before_item_id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+    ]);
+
+    const { model: out } = await run(
+      {
+        social_links: [
+          {
+            social_link_icon: 'x',
+            url: 'https://x.com',
+            move_before_item_id: 'link-2',
+          },
+        ],
+      },
+      model,
     );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(3);
+    expect(links[0].id).toBe('link-1');
+    expect(links[1].imageUrl).toBe('x');
+    expect(links[2].id).toBe('link-2');
   });
 
-  it('handles multiple removal indices on a shared array (descending splice)', async () => {
-    const model = makeSharedSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
-      link('youtube'),
+  it('inserts a new link at end via move_before_item_id "__end__"', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
     ]);
 
     const { model: out } = await run(
-      { _remove_social_link_indices: [0, 2] },
+      {
+        social_links: [
+          {
+            social_link_icon: 'x',
+            url: 'https://x.com',
+            move_before_item_id: '__end__',
+          },
+        ],
+      },
       model,
     );
 
-    expect(socialIcons(out.pageFooterDesktop)).toEqual([
-      'instagram',
-      'youtube',
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(3);
+    expect(links[2].imageUrl).toBe('x');
+  });
+
+  it('moves an existing link before an anchor via move_before_item_id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+      { id: 'link-3', imageUrl: 'x', url: 'https://x.com' },
     ]);
-    expect(socialIcons(out.pageFooterMobile)).toEqual(['instagram', 'youtube']);
+
+    const { model: out } = await run(
+      {
+        social_links: [{ item_id: 'link-3', move_before_item_id: 'link-1' }],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links.map((l) => l.id)).toEqual(['link-3', 'link-1', 'link-2']);
   });
 
-  it('removes one link per index for independent viewport arrays (no regression)', async () => {
-    const model = makeIndependentSocialModel([
-      link('facebook'),
-      link('instagram'),
-      link('x'),
+  it('removes links by id', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
+      { id: 'link-2', imageUrl: 'instagram', url: 'https://ig.com' },
+      { id: 'link-3', imageUrl: 'x', url: 'https://x.com' },
     ]);
 
     const { model: out } = await run(
-      { _remove_social_link_indices: [1] },
+      { _remove_social_link_ids: ['link-1', 'link-3'] },
       model,
     );
 
-    expect(socialIcons(out.pageFooterDesktop)).toEqual(['facebook', 'x']);
-    expect(socialIcons(out.pageFooterMobile)).toEqual(['facebook', 'x']);
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(1);
+    expect(links[0].id).toBe('link-2');
   });
 
-  it('inserts exactly one link on a shared array (symmetric add guard)', async () => {
-    const model = makeSharedSocialModel([link('facebook'), link('instagram')]);
+  it('_replace_social_links rebuilds the entire list and assigns fresh ids', async () => {
+    const model = makeModelWithLinks([
+      { id: 'old-1', imageUrl: 'facebook', url: 'https://fb.com' },
+    ]);
 
     const { model: out } = await run(
       {
-        social_links: [{ insert_at: 1, social_link_icon: 'x', url: 'x.com' }],
+        _replace_social_links: true,
+        social_links: [
+          { social_link_icon: 'instagram', url: 'https://ig.com' },
+          { social_link_icon: 'x', url: 'https://x.com' },
+        ],
       },
       model,
     );
 
-    expect(socialIcons(out.pageFooterDesktop)).toEqual([
-      'facebook',
-      'x',
-      'instagram',
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links).toHaveLength(2);
+    expect(links[0].imageUrl).toBe('instagram');
+    expect(links[1].imageUrl).toBe('x');
+    // fresh ids assigned, not the old one
+    expect(links[0].id).toBeTruthy();
+    expect(links[0].id).not.toBe('old-1');
+  });
+
+  it('_replace_social_links with empty social_links clears all', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
     ]);
-    expect(socialIcons(out.pageFooterMobile)).toEqual([
-      'facebook',
-      'x',
-      'instagram',
+
+    const { model: out } = await run({ _replace_social_links: true }, model);
+
+    expect(out.pageFooterDesktop!.socialLinks).toHaveLength(0);
+  });
+
+  it('normalises mailto: and tel: prefixes on new links', async () => {
+    const model = makeModelWithLinks([]);
+
+    const { model: out } = await run(
+      {
+        social_links: [
+          { social_link_icon: 'email', url: 'mailto:me@example.com' },
+          { social_link_icon: 'phone', url: 'tel:+1234567890' },
+        ],
+      },
+      model,
+    );
+
+    const links = out.pageFooterDesktop!.socialLinks;
+
+    expect(links[0].url).toBe('me@example.com');
+    expect(links[1].url).toBe('+1234567890');
+  });
+
+  it('applies mutations to both desktop and mobile footers', async () => {
+    const model = makeModelWithLinks([
+      { id: 'link-1', imageUrl: 'facebook', url: 'https://fb.com' },
     ]);
+
+    const { model: out } = await run(
+      { _remove_social_link_ids: ['link-1'] },
+      model,
+    );
+
+    expect(out.pageFooterDesktop!.socialLinks).toHaveLength(0);
+    expect(out.pageFooterMobile!.socialLinks).toHaveLength(0);
   });
 });

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

@@ -10,16 +10,17 @@ import {
 import type {
   UpdateFooterArguments,
   ViewportFooterOverrides,
-  FooterSocialLinkItem,
 } from '../parsers/ai-toolcall-parser';
 import type { Logger } from '../logger';
 import type { TextStyleOptions } from '../../brand-page/models/styles.model';
 import { FOOTER_CHECKS } from './section-rules/footer.rules';
 import { applyDetachedStyleOverride } from './section-field-utils';
-
-type FooterSocialLink = NonNullable<
-  AbstractPageFooterStyles['socialLinks']
->[number];
+import {
+  ensureItemIds,
+  generateItemId,
+  removeItemsByIds,
+  repositionItemByAnchor,
+} from './item-id-utils';
 
 const normaliseSocialUrl = (url: string): string => {
   for (const prefix of ['mailto:', 'tel:']) {
@@ -29,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,6 +44,80 @@ const applyGlobalFooterChanges = (
       { fontFamily: args.copyright_text_font_family },
       textStyleOptions,
     );
+
+  const links = args.social_links;
+
+  // _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,
+    );
+
+    // 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,
+          );
+        }
+      }
+    }
+  }
 };
 
 const applyViewportFooterChanges = (
@@ -230,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);