@designcrowd/library.brand-page 5.19.1-id-based-items-1 → 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/lib/src/metadata-builder/builders/item-id-utils.d.ts

@@ -1,41 +0,0 @@
-/**
- * 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;
-/**
- * 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,68 +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();
-/**
- * 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,118 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import {
-  END_ITEM_ANCHOR,
-  ensureItemIds,
-  generateItemId,
-  removeItemsByIds,
-  repositionItemByAnchor,
-} from './item-id-utils';
-
-type Item = { id?: string; label: string };
-
-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']);
-  });
-});

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

@@ -1,85 +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 = (): string => uuidv4();
-
-/**
- * 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);
-  }
-};