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

package/src/metadata-builder/parsers/section-tool-arguments.ts

@@ -142,15 +142,10 @@ export interface ProfileSectionArguments {
 }
 
 export interface TextSectionItem {
-  /** Stable id of the existing item to update or move. Omit to ADD a new item. */
-  item_id?: string;
-  /**
-   * Id of an existing item to position this item before (insert for new items,
-   * move for existing ones). Use "__end__" for the end of the list. Omit to
-   * leave an existing item in place / append a new item. Mirrors the
-   * section-level move_before_content_id.
-   */
-  move_before_item_id?: string;
+  /** 0-based index of existing item to update in-place */
+  item_index?: number;
+  /** 0-based position to insert a new item at */
+  insert_at?: number;
   text?: RichTextField;
   text_style?: TextStyleArguments;
 }
@@ -164,8 +159,10 @@ export interface TextSectionArguments {
   /** Multiple text items (BrandSite) */
   items?: TextSectionItem[];
   _replace_items?: boolean;
-  /** Stable ids of items to remove. Order-independent (no index shifting). */
-  _remove_item_ids?: string[];
+  /** 0-based indices of items to remove */
+  _remove_item_indices?: number[];
+  /** New order as array of current 0-based indices */
+  _reorder_items?: number[];
   background_color?: string | null;
 }
 
@@ -175,15 +172,10 @@ export interface ImageSectionArguments {
 }
 
 export interface ImageGalleryItem {
-  /** Stable id of the existing item to update or move. Omit to ADD a new item. */
-  item_id?: string;
-  /**
-   * Id of an existing item to position this item before (insert for new items,
-   * move for existing ones). Use "__end__" for the end of the list. Omit to
-   * leave an existing item in place / append a new item. Mirrors the
-   * section-level move_before_content_id.
-   */
-  move_before_item_id?: string;
+  /** 0-based index of existing item to update in-place */
+  item_index?: number;
+  /** 0-based position to insert a new item at */
+  insert_at?: number;
   image_url?: string;
   caption?: string;
 }
@@ -193,8 +185,10 @@ export interface ImageGallerySectionArguments {
   gallery_type?: 'grid' | 'carousel' | 'masonry';
   is_full_width?: boolean;
   _replace_items?: boolean;
-  /** Stable ids of items to remove. Order-independent (no index shifting). */
-  _remove_item_ids?: string[];
+  /** 0-based indices of items to remove */
+  _remove_item_indices?: number[];
+  /** New order as array of current 0-based indices */
+  _reorder_items?: number[];
 }
 
 export interface GeneralLinkSectionArguments {
@@ -262,15 +256,10 @@ export interface TiktokSectionArguments {
 }
 
 export interface SocialLink {
-  /** Stable id of the existing item to update or move. Omit to ADD a new item. */
-  item_id?: string;
-  /**
-   * Id of an existing item to position this item before (insert for new items,
-   * move for existing ones). Use "__end__" for the end of the list. Omit to
-   * leave an existing item in place / append a new item. Mirrors the
-   * section-level move_before_content_id.
-   */
-  move_before_item_id?: string;
+  /** 0-based index of existing item to update in-place */
+  item_index?: number;
+  /** 0-based position to insert a new item at */
+  insert_at?: number;
   platform?:
     | 'facebook'
     | 'x'
@@ -291,8 +280,10 @@ export interface SocialLinksSectionArguments {
   /** Style for the icon container background (used when icon_style is 'square' or 'circle'). */
   icon_background_style?: TextStyleArguments;
   _replace_items?: boolean;
-  /** Stable ids of items to remove. Order-independent (no index shifting). */
-  _remove_item_ids?: string[];
+  /** 0-based indices of items to remove */
+  _remove_item_indices?: number[];
+  /** New order as array of current 0-based indices */
+  _reorder_items?: number[];
 }
 
 export interface MailingListSectionArguments {
@@ -380,15 +371,10 @@ export interface AboutSectionArguments {
 }
 
 export interface ImagesSectionItem {
-  /** Stable id of the existing item to update or move. Omit to ADD a new item. */
-  item_id?: string;
-  /**
-   * Id of an existing item to position this item before (insert for new items,
-   * move for existing ones). Use "__end__" for the end of the list. Omit to
-   * leave an existing item in place / append a new item. Mirrors the
-   * section-level move_before_content_id.
-   */
-  move_before_item_id?: string;
+  /** 0-based index of existing item to update in-place */
+  item_index?: number;
+  /** 0-based position to insert a new item at */
+  insert_at?: number;
   image_url?: string;
   heading?: string;
   text?: string;
@@ -407,8 +393,10 @@ export interface ImagesSectionArguments {
     | 'center-card-aligned-image'
     | 'alternate-image';
   _replace_items?: boolean;
-  /** Stable ids of items to remove. Order-independent (no index shifting). */
-  _remove_item_ids?: string[];
+  /** 0-based indices of items to remove */
+  _remove_item_indices?: number[];
+  /** New order as array of current 0-based indices */
+  _reorder_items?: number[];
   title_style?: TextStyleArguments;
   description_style?: TextStyleArguments;
   heading_style?: TextStyleArguments;
@@ -421,15 +409,10 @@ export interface ImagesSectionArguments {
 }
 
 export interface TestimonialItem {
-  /** Stable id of the existing item to update or move. Omit to ADD a new item. */
-  item_id?: string;
-  /**
-   * Id of an existing item to position this item before (insert for new items,
-   * move for existing ones). Use "__end__" for the end of the list. Omit to
-   * leave an existing item in place / append a new item. Mirrors the
-   * section-level move_before_content_id.
-   */
-  move_before_item_id?: string;
+  /** 0-based index of existing item to update in-place */
+  item_index?: number;
+  /** 0-based position to insert a new item at */
+  insert_at?: number;
   testimonial?: string;
   name?: string;
   position?: string;
@@ -443,8 +426,10 @@ export interface TestimonialSectionArguments {
   items?: TestimonialItem[];
   display_style?: 'centered' | 'big-image' | 'columns';
   _replace_items?: boolean;
-  /** Stable ids of items to remove. Order-independent (no index shifting). */
-  _remove_item_ids?: string[];
+  /** 0-based indices of items to remove */
+  _remove_item_indices?: number[];
+  /** New order as array of current 0-based indices */
+  _reorder_items?: number[];
   title_style?: TextStyleArguments;
   testimonial_style?: TextStyleArguments;
   name_style?: TextStyleArguments;
@@ -454,15 +439,10 @@ export interface TestimonialSectionArguments {
 }
 
 export interface ShapesSectionItem {
-  /** Stable id of the existing item to update or move. Omit to ADD a new item. */
-  item_id?: string;
-  /**
-   * Id of an existing item to position this item before (insert for new items,
-   * move for existing ones). Use "__end__" for the end of the list. Omit to
-   * leave an existing item in place / append a new item. Mirrors the
-   * section-level move_before_content_id.
-   */
-  move_before_item_id?: string;
+  /** 0-based index of existing item to update in-place */
+  item_index?: number;
+  /** 0-based position to insert a new item at */
+  insert_at?: number;
   icon_image_url?: string;
   shape_url?: string;
   color_theme?: string;
@@ -482,8 +462,10 @@ export interface ShapesSectionArguments {
     | 'center-card-aligned-image'
     | 'alternate-image';
   _replace_items?: boolean;
-  /** Stable ids of items to remove. Order-independent (no index shifting). */
-  _remove_item_ids?: string[];
+  /** 0-based indices of items to remove */
+  _remove_item_indices?: number[];
+  /** New order as array of current 0-based indices */
+  _reorder_items?: number[];
   title_style?: TextStyleArguments;
   description_style?: TextStyleArguments;
   heading_style?: TextStyleArguments;

package/src/utils/minify-brand-page-metadata.ts

@@ -15,12 +15,7 @@ import { useExternalRichTextEditor } from '../brand-page-maker/composables/rich-
 import type { Editor, JSONContent } from '@tiptap/vue-3';
 import { type AssetEntry, resolveLogoData } from './build-asset-manifest';
 
-type MinifiedFooterSocialLink = {
-  position: number;
-  id?: string;
-  imageUrl: string;
-  url: string;
-};
+type MinifiedFooterSocialLink = { imageUrl: string; url: string };
 
 type MinifiedFooter = {
   displayStyle?: string;
@@ -297,7 +292,6 @@ const minifyContent = (
         ...(Array.isArray(c.items) && {
           items: c.items.map((item: any, index: number) => ({
             position: index + 1,
-            ...(item.id && { id: item.id }),
             ...st('name', item.name, editor),
             ...st('jobTitle', item.position, editor),
             ...st('testimonials', item.testimonials, editor),
@@ -326,7 +320,6 @@ const minifyContent = (
         ...(Array.isArray(c.items) && {
           items: c.items.map((item: any, index: number) => ({
             position: index + 1,
-            ...(item.id && { id: item.id }),
             ...includeImageWithKey(item.imageUrl),
             ...st('title', item.title, editor),
             ...st('paragraph', item.paragraph, editor),
@@ -357,7 +350,6 @@ const minifyContent = (
         ...(Array.isArray(c.textItems) && {
           textItems: c.textItems.map((item: any, index: number) => ({
             position: index + 1,
-            ...(item.id && { id: item.id }),
             ...st('text', item.text, editor),
             ...(includeStyle(item.textStyle) && { textStyle: item.textStyle }),
           })),
@@ -447,7 +439,6 @@ const minifyContent = (
         ...(Array.isArray(c.links) && {
           links: c.links.map((link: any, index: number) => ({
             position: index + 1,
-            ...(link.id && { id: link.id }),
             ...(includeString(link.url) && { url: link.url }),
             ...includeImageWithKey(link.imageUrl),
           })),
@@ -491,7 +482,6 @@ const minifyContent = (
         ...(Array.isArray(c.images) && {
           images: c.images.map((img: any, index: number) => ({
             position: index + 1,
-            ...(img.id && { id: img.id }),
             ...includeImageWithKey(img.imageUrl),
             ...st('imageTitle', img.imageTitle, editor),
           })),
@@ -541,9 +531,7 @@ const minifyFooter = (
     logoImageWidth: footer.logoImageWidth || undefined,
     ...(logoAssetKey && { logoAssetKey }),
     socialLinks: footer.socialLinks?.length
-      ? footer.socialLinks.map((l, index) => ({
-          position: index + 1,
-          ...(l.id && { id: l.id }),
+      ? footer.socialLinks.map((l) => ({
           imageUrl: l.imageUrl || '',
           url: l.url || '',
         }))

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

@@ -1,54 +0,0 @@
-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

@@ -1,96 +0,0 @@
-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/src/metadata-builder/builders/item-id-utils.test.ts

@@ -1,184 +0,0 @@
-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();
-  });
-});