@designcrowd/library.brand-page 6.0.3 → 6.0.4

package/lib/src/lib.js

@@ -31,18 +31,8 @@ export * as brandPageUtils from './brand-page/utils';
 export { getOptimalLogoSize, calculateOptimizedLogoDimensions, applyLogoImageBase64UrlToBrandPageTemplateModel, recalculateLogoContentDimensions, recalculateHeaderLogoSizes, } from './brand-page/utils/logo.util';
 export { sanitizeRTEHtml } from './brand-page-maker/utils';
 export { getPageSlugFromPageTitle } from './brand-page-maker/utils/slug.util';
-// AI-pipeline preview (longclaw per-turn snapshots): web-renderer's
-// /preview/ai-pipeline render page + manifest server route apply the agent's
-// tool calls to a brand-page metadata snapshot server-side and resolve the
-// target page by slug. These three symbols are otherwise internal to the
-// metadata-builder / route utils.
-export { executeToolCallsAsync } from './metadata-builder/ai-metadata-executor';
-export { findNavItemByPageSlug } from './brand-page/utils/route.util';
-// Tiptap-JSON RTE -> HTML (same converter the metadata builders use). Lets the
-// preview render the agent's raw Tiptap fields, which the renderer expects as HTML.
-export { tiptapJsonToHtml } from './metadata-builder/helpers/rte.helpers';
 // stores
-export { useBrandPageMakerStore, useBrandPageMakerUserStore, useUiStore, useBrandPageContainerStore, useEventManagerStore, useLocalisedRouteStore, useVideoStore, useRouteStore, } from './brand-page-maker/stores';
+export { useBrandPageMakerStore, useBrandPageMakerUserStore, useUiStore, useBrandPageContainerStore, useEventManagerStore, useLocalisedRouteStore, useVideoStore, } from './brand-page-maker/stores';
 export { useShopConfigStore } from './shared/ecommerce-settings/store/shop-settings-store';
 // for jest, need to set active pinia in library.brand-page as well
 import { createPinia, setActivePinia } from 'pinia';

package/lib/src/metadata-builder/builders/footer-builder.js

@@ -1,7 +1,8 @@
 import {} from '../../brand-page/models';
 import { BaseMetadataBuilder, } from '../models';
 import { FOOTER_CHECKS } from './section-rules/footer.rules';
-import { applyDetachedStyleOverride, normalizeStyleValue, } from './section-field-utils';
+import { applyDetachedStyleOverride } from './section-field-utils';
+import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from './item-id-utils';
 const normaliseSocialUrl = (url) => {
     for (const prefix of ['mailto:', 'tel:']) {
         if (url.startsWith(prefix))
@@ -9,100 +10,64 @@ const normaliseSocialUrl = (url) => {
     }
     return url;
 };
-const makeSocialLink = (icon, url) => ({
-    imageUrl: icon || '',
-    url: normaliseSocialUrl(url || ''),
-    imageTitle: '',
-    width: 0,
-    height: 0,
-    imageLink: '',
-});
-const hasSocialLinkMutation = (args) => 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, args) => {
-    // _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 = [...(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.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, args, textStyleOptions) => {
     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 = {};
-        for (const [key, value] of Object.entries(args.copyright_text_style)) {
-            const normalized = normalizeStyleValue(key, value);
-            if (normalized !== undefined)
-                updates[key] = normalized;
+    if (args.copyright_text_font_family !== undefined)
+        footer.copyrightStyle = applyDetachedStyleOverride(footer.copyrightStyle, { 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: '',
+                    };
+                    repositionItemByAnchor(footer.socialLinks, newLink, link.move_before_item_id);
+                }
+            }
         }
-        if (Object.keys(updates).length > 0)
-            footer.copyrightStyle = applyDetachedStyleOverride(footer.copyrightStyle, updates, textStyleOptions);
     }
 };
 const applyViewportFooterChanges = (footer, overrides) => {
@@ -120,6 +85,11 @@ const applyViewportFooterChanges = (footer, overrides) => {
             color: overrides.icon_color,
             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;
     if (overrides.logo_image_height !== undefined)
@@ -156,24 +126,11 @@ export class FooterBuilder extends BaseMetadataBuilder {
         }
         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/lib/src/metadata-builder/builders/item-id-utils.d.ts

@@ -0,0 +1,54 @@
+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 declare const END_ITEM_ANCHOR = "__end__";
+/** Generate a stable item id. Mirrors section-level `uuid.v4()` id generation. */
+export declare const generateItemId: () => string;
+/**
+ * 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 declare const ensureBrandPageItemIds: (model: BrandPageModel) => void;
+/**
+ * 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 declare const ensureItemIds: <T extends {
+    id?: string | undefined;
+}>(items: T[] | undefined) => void;
+/**
+ * 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 declare const removeItemsByIds: <T extends {
+    id?: string | undefined;
+}>(items: T[] | undefined, ids: string[] | undefined) => T[];
+/**
+ * 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 declare const repositionItemByAnchor: <T extends {
+    id?: string | undefined;
+}>(items: T[], item: T, moveBeforeItemId: string | undefined) => void;

package/lib/src/metadata-builder/builders/item-id-utils.js

@@ -0,0 +1,96 @@
+import { v4 as uuidv4 } from 'uuid';
+/**
+ * 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 = () => 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) => {
+    const ensureContentItemIds = (content) => {
+        // Every array field that the minifier surfaces as a list of items.
+        for (const field of ['images', 'items', 'textItems', 'links']) {
+            const arr = content[field];
+            if (Array.isArray(arr))
+                ensureItemIds(arr);
+        }
+    };
+    for (const page of model.pages ?? []) {
+        for (const content of page.contents ?? []) {
+            ensureContentItemIds(content);
+        }
+    }
+    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 = (items) => {
+    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 = (items, ids) => {
+    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 = (items, item, moveBeforeItemId) => {
+    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);
+    }
+};

package/lib/src/metadata-builder/builders/section-builders/image-gallery-builder.js

@@ -1,14 +1,21 @@
 import { applyScalarFields, isValidUrl } from '../section-field-utils';
 import { BaseSectionBuilder } from './base-section-builder';
 import { validateImageGallery } from '../section-rules/image-gallery.rules';
+import { ensureItemIds, generateItemId, removeItemsByIds, repositionItemByAnchor, } from '../item-id-utils';
 const applyGalleryType = (content, galleryType) => {
     content.galleryStyles = {
         ...(content.galleryStyles || {}),
         galleryType: galleryType,
     };
 };
+/**
+ * Full rebuild: discard existing images and map the payload directly.
+ * Used on create and when `_replace_items` is set. Each item gets a fresh id
+ * (or keeps the caller-supplied `item_id` when provided).
+ */
 const applyGalleryImages = (content, images) => {
     content.images = images.map((img) => ({
+        id: img.item_id || generateItemId(),
         imageUrl: isValidUrl(img.image_url) ? img.image_url : '',
         imageTitle: img.caption || '',
         width: 0,
@@ -17,59 +24,46 @@ const applyGalleryImages = (content, images) => {
         imageLink: '',
     }));
 };
-const mergeGalleryImages = (content, images, replaceAll) => {
-    const itemsToMerge = images.filter((img) => img.insert_at === undefined);
-    const updatedImages = itemsToMerge.map((img, index) => {
-        const existing = content.images?.[index];
-        const imageUrl = isValidUrl(img.image_url)
-            ? img.image_url
-            : (existing?.imageUrl ?? '');
-        return {
-            ...(existing || {}),
-            imageUrl,
-            imageTitle: img.caption ?? existing?.imageTitle ?? '',
-            width: existing?.width ?? 0,
-            height: existing?.height ?? 0,
-            mediaType: existing?.mediaType ?? 'image',
-            imageLink: existing?.imageLink ?? '',
-        };
-    });
-    if (!replaceAll &&
-        content.images &&
-        content.images.length > itemsToMerge.length) {
-        const extras = content.images.slice(itemsToMerge.length).map((img) => ({
-            imageUrl: img.imageUrl ?? '',
-            imageTitle: img.imageTitle ?? '',
-            width: img.width ?? 0,
-            height: img.height ?? 0,
-            mediaType: img.mediaType ?? 'image',
-            imageLink: img.imageLink ?? '',
-        }));
-        updatedImages.push(...extras);
-    }
-    content.images = updatedImages;
-};
-const insertGalleryImages = (content, images) => {
-    const inserts = images.filter((img) => img.insert_at !== undefined);
-    if (!inserts.length)
-        return;
-    const sorted = [...inserts].sort((a, b) => (b.insert_at ?? 0) - (a.insert_at ?? 0));
-    for (const img of sorted) {
-        if (!isValidUrl(img.image_url))
-            continue;
-        if (content.images?.some((existing) => existing.imageUrl === img.image_url))
-            continue;
-        content.images = content.images ?? [];
-        const pos = Math.max(0, Math.min(img.insert_at ?? 0, content.images.length));
-        content.images.splice(pos, 0, {
-            imageUrl: img.image_url,
-            imageTitle: img.caption ?? '',
-            width: 0,
-            height: 0,
-            mediaType: 'image',
-            imageLink: '',
-            colorReplacements: [],
-        });
+/**
+ * Id-based merge (BP-5603), mirroring testimonial-section-builder one level
+ * deeper into `content.images`:
+ *   - `item_id` matches existing item  → update in place; reposition if
+ *     `move_before_item_id` is set.
+ *   - no `item_id`                     → add new item, positioned by
+ *     `move_before_item_id`.
+ *   - `removeIds`                      → delete by id (order-independent).
+ *
+ * Existing items are id-backfilled first so legacy galleries become
+ * referenceable as soon as the metadata builder touches them.
+ */
+const mergeGalleryImages = (content, images, removeIds) => {
+    ensureItemIds(content.images);
+    content.images = removeItemsByIds(content.images, removeIds);
+    for (const img of images) {
+        if (img.item_id) {
+            const existing = content.images.find((i) => i.id === img.item_id);
+            // Unknown id — skip rather than guess at a position.
+            if (!existing)
+                continue;
+            if (img.image_url !== undefined) {
+                existing.imageUrl = isValidUrl(img.image_url) ? img.image_url : '';
+            }
+            if (img.caption !== undefined)
+                existing.imageTitle = img.caption;
+            repositionItemByAnchor(content.images, existing, img.move_before_item_id);
+        }
+        else {
+            const newItem = {
+                id: generateItemId(),
+                imageUrl: isValidUrl(img.image_url) ? img.image_url : '',
+                imageTitle: img.caption ?? '',
+                width: 0,
+                height: 0,
+                mediaType: 'image',
+                imageLink: '',
+            };
+            repositionItemByAnchor(content.images, newItem, img.move_before_item_id);
+        }
     }
 };
 export class ImageGalleryBuilder extends BaseSectionBuilder {
@@ -91,24 +85,19 @@ export class ImageGalleryBuilder extends BaseSectionBuilder {
         if (args.gallery_type) {
             applyGalleryType(content, args.gallery_type);
         }
-        if (args.images && Array.isArray(args.images)) {
-            if (this.mode === 'create') {
-                applyGalleryImages(content, args.images);
-            }
-            else {
-                mergeGalleryImages(content, args.images, !!args._replace_items);
-            }
+        if (args._replace_items && args.images && Array.isArray(args.images)) {
+            // Full replacement: discard existing images and rebuild from the payload.
+            applyGalleryImages(content, args.images);
         }
-        if (args._remove_item_indices?.length && content.images) {
-            const sorted = [...args._remove_item_indices].sort((a, b) => b - a);
-            for (const idx of sorted) {
-                if (idx >= 0 && idx < content.images.length) {
-                    content.images.splice(idx, 1);
-                }
+        else if (this.mode === 'create') {
+            if (args.images && Array.isArray(args.images)) {
+                applyGalleryImages(content, args.images);
             }
         }
-        if (args.images && Array.isArray(args.images) && this.mode === 'update') {
-            insertGalleryImages(content, args.images);
+        else if ((args.images && Array.isArray(args.images)) ||
+            args._remove_item_ids?.length) {
+            // Update: id-based add / edit / move / remove in a single pass.
+            mergeGalleryImages(content, args.images ?? [], args._remove_item_ids);
         }
         return { request: this.request, model };
     }