@akinon/pz-theme 2.0.110-rc.0 → 2.0.110

package/src/__tests__/live-rows-parity.test.ts

@@ -0,0 +1,298 @@
+/**
+ * ZERO-5084 — the editor canvas and the storefront must pick the SAME answer
+ * for a collection-backed section.
+ *
+ * The server loader resolves a section's live rows in one order (the
+ * collection's own widget when the source carries its slug, then the
+ * section's own widget, taken only when it carries products). The canvas
+ * fetches them from the browser when the document holds none for the current
+ * binding. If the two orders drift, the canvas shows one set of rows and the
+ * site another, which is the bug this ticket exists to remove.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+jest.mock('server-only', () => ({}), { virtual: true });
+
+const getWidgetData = jest.fn();
+const getWidgetSchemaData = jest.fn();
+const getCollectionWidgetData = jest.fn();
+
+jest.mock('@akinon/next/data/server', () => ({
+  getWidgetData: (...args: unknown[]) => getWidgetData(...args),
+  getWidgetSchemaData: (...args: unknown[]) => getWidgetSchemaData(...args),
+  getCollectionWidgetData: (...args: unknown[]) =>
+    getCollectionWidgetData(...args),
+  getPreviewSnapshot: async () => null
+}));
+
+jest.mock(
+  '@akinon/next/utils/app-fetch',
+  () => ({ __esModule: true, default: jest.fn() }),
+  { virtual: true }
+);
+
+jest.mock(
+  '@akinon/next/utils/server-variables',
+  () => ({ ServerVariables: { locale: 'tr', currency: 'try' } }),
+  { virtual: true }
+);
+
+import { loadPlaceholderSections } from '../load-placeholder-sections';
+import { fetchDesignerLiveRows, liveRowsPaths } from '../utils/live-rows';
+
+const SLOT = 'homepage';
+const SECTION = 'rmd8i';
+const SOURCE_ID = 'ds-1';
+const COLLECTION_SLUG = 'summer-picks';
+
+interface Answers {
+  /** `/widgets/<collection slug>/` */
+  slugWidget: unknown | null;
+  /** `/product_collection_widgets/<collection slug>/` */
+  collectionWidget: unknown | null;
+  /** `/widgets/<section id>/` */
+  sectionWidget: unknown | null;
+}
+
+const collection = (slug?: string) => ({
+  pk: 7,
+  productLimit: 6,
+  products: [{ pk: 1, name: 'Snapshot' }],
+  ...(slug ? { slug } : {})
+});
+
+/** The rows the server loader writes into `collection.data`, or null. */
+const serverAnswer = async (slug: string | undefined, answers: Answers) => {
+  const dataSources = [
+    {
+      id: SOURCE_ID,
+      name: 'Picks',
+      type: 'collection',
+      details: { collection: collection(slug) }
+    }
+  ];
+
+  getWidgetData.mockImplementation(
+    async ({ slug: asked }: { slug: string }) => {
+      if (asked === SLOT) {
+        return {
+          slug: SLOT,
+          attributes: {
+            theme_editor_placeholder: {
+              value: JSON.stringify([{ section_slug: SECTION, order: 0 }])
+            }
+          }
+        };
+      }
+      if (asked === 'theme-config') {
+        return {
+          slug: 'theme-config',
+          attributes: {
+            theme_dataSources: { value: JSON.stringify(dataSources) }
+          }
+        };
+      }
+      if (asked === SECTION) return answers.sectionWidget;
+      if (asked === COLLECTION_SLUG) return answers.slugWidget;
+      return null;
+    }
+  );
+  getCollectionWidgetData.mockImplementation(
+    async ({ slug: asked }: { slug: string }) =>
+      asked === COLLECTION_SLUG ? answers.collectionWidget : null
+  );
+  getWidgetSchemaData.mockResolvedValue({
+    schema: {
+      [SECTION]: {
+        metadata: { name: 'Strip', dataSourceId: SOURCE_ID, blocks: [] }
+      }
+    }
+  });
+
+  const loaded = await loadPlaceholderSections(SLOT);
+  return loaded?.sections[0]?.dataSource?.details?.collection?.data ?? null;
+};
+
+/** The rows the canvas fetches from the browser, or null. */
+const canvasAnswer = async (slug: string | undefined, answers: Answers) => {
+  const byPath: Record<string, unknown | null> = {
+    [`/widgets/${COLLECTION_SLUG}/`]: answers.slugWidget,
+    [`/product_collection_widgets/${COLLECTION_SLUG}/`]:
+      answers.collectionWidget,
+    [`/widgets/${SECTION}/`]: answers.sectionWidget
+  };
+
+  (global as unknown as { fetch: unknown }).fetch = jest.fn(
+    async (url: string) => {
+      // The shared @akinon/next/utils mock hands the path back unchanged.
+      const answer = byPath[url.split('?')[0]] ?? null;
+      return answer === null
+        ? {
+            ok: false,
+            status: 404,
+            json: async () => ({ detail: 'Not found.' })
+          }
+        : { ok: true, status: 200, json: async () => answer };
+    }
+  );
+
+  return fetchDesignerLiveRows(SECTION, collection(slug));
+};
+
+const SLUG_ROWS = {
+  products: [{ pk: 10, name: 'From the collection widget' }]
+};
+const COLLECTION_ROWS = {
+  products: [{ pk: 20, name: 'From product_collection_widgets' }]
+};
+const SECTION_ROWS = {
+  slug: SECTION,
+  attributes: {},
+  products: [{ pk: 30, name: 'From the section widget' }]
+};
+const SECTION_WITHOUT_ROWS = { slug: SECTION, attributes: {}, products: [] };
+
+const CASES: Array<[string, string | undefined, Answers]> = [
+  [
+    'slug: the collection widget wins',
+    COLLECTION_SLUG,
+    {
+      slugWidget: SLUG_ROWS,
+      collectionWidget: COLLECTION_ROWS,
+      sectionWidget: SECTION_ROWS
+    }
+  ],
+  [
+    'slug: product_collection_widgets when the widget has none',
+    COLLECTION_SLUG,
+    {
+      slugWidget: null,
+      collectionWidget: COLLECTION_ROWS,
+      sectionWidget: SECTION_ROWS
+    }
+  ],
+  [
+    'slug: the section widget when neither collection endpoint answers',
+    COLLECTION_SLUG,
+    { slugWidget: null, collectionWidget: null, sectionWidget: SECTION_ROWS }
+  ],
+  [
+    'slug: nothing when the section widget carries no products either',
+    COLLECTION_SLUG,
+    {
+      slugWidget: null,
+      collectionWidget: null,
+      sectionWidget: SECTION_WITHOUT_ROWS
+    }
+  ],
+  [
+    'slug: a collection-widget answer is taken as it is',
+    COLLECTION_SLUG,
+    {
+      slugWidget: { slug: COLLECTION_SLUG, attributes: {} },
+      collectionWidget: null,
+      sectionWidget: SECTION_ROWS
+    }
+  ],
+  [
+    'no slug: the section widget',
+    undefined,
+    {
+      slugWidget: SLUG_ROWS,
+      collectionWidget: null,
+      sectionWidget: SECTION_ROWS
+    }
+  ],
+  [
+    'no slug: nothing for an empty product list',
+    undefined,
+    {
+      slugWidget: null,
+      collectionWidget: null,
+      sectionWidget: SECTION_WITHOUT_ROWS
+    }
+  ],
+  [
+    'no slug: nothing when the section widget does not answer',
+    undefined,
+    { slugWidget: null, collectionWidget: null, sectionWidget: null }
+  ]
+];
+
+beforeEach(() => {
+  getWidgetData.mockReset();
+  getWidgetSchemaData.mockReset();
+  getCollectionWidgetData.mockReset();
+});
+
+describe('the canvas asks in the loader order', () => {
+  it('lists the endpoints in the loader order', () => {
+    expect(liveRowsPaths(SECTION, collection(COLLECTION_SLUG))).toEqual([
+      { path: `/widgets/${COLLECTION_SLUG}/`, requireProducts: false },
+      {
+        path: `/product_collection_widgets/${COLLECTION_SLUG}/`,
+        requireProducts: false
+      },
+      { path: `/widgets/${SECTION}/`, requireProducts: true }
+    ]);
+    expect(liveRowsPaths(SECTION, collection())).toEqual([
+      { path: `/widgets/${SECTION}/`, requireProducts: true }
+    ]);
+  });
+
+  it.each(CASES)('%s', async (_name, slug, answers) => {
+    const server = await serverAnswer(slug, answers);
+    const canvas = await canvasAnswer(slug, answers);
+
+    expect(canvas).toEqual(server);
+  });
+});
+
+/**
+ * Every renderer that reads a collection's rows used to rank the snapshot
+ * first whenever it was framed by the editor. The canvas now gets live rows
+ * only when the wrapper put them there for a saved pick, so the readers rank
+ * them first everywhere. This pins all six against a branch coming back.
+ */
+describe('no reader ranks the snapshot above the live rows', () => {
+  const read = (relative: string) =>
+    fs
+      .readFileSync(path.join(__dirname, '..', relative), 'utf8')
+      .replace(/\s+/g, ' ');
+
+  const READERS: Array<[string, string]> = [
+    [
+      'theme-section.tsx',
+      'effectiveSection.dataSource.details.collection?.data || effectiveSection.dataSource.details.collection?.products'
+    ],
+    [
+      'utils/iterator-utils.ts',
+      'const candidates = [collection?.data, collection?.products];'
+    ],
+    [
+      'sections/posts-slider-section.tsx',
+      'details.collection?.data?.products, details.collection?.data, details.collection?.products,'
+    ],
+    [
+      'sections/featured-product-spotlight-section.tsx',
+      'collectionDetails?.data || collectionDetails?.products'
+    ],
+    [
+      'sections/installment-options-section.tsx',
+      'collectionDetails?.data || collectionDetails?.products'
+    ],
+    [
+      'sections/pre-order-launch-banner-section.tsx',
+      'collectionDetails?.data || collectionDetails?.products'
+    ]
+  ];
+
+  it.each(READERS)('%s', (file, liveFirst) => {
+    const source = read(file);
+
+    expect(source).toContain(liveFirst);
+    expect(source).not.toMatch(/collection\w*\?\.products \|\| \w+/);
+    expect(source).not.toMatch(/window\.parent !== window/);
+  });
+});

package/src/__tests__/section-live-rows.test.ts

@@ -147,8 +147,8 @@ describe('collection-backed sections on the server', () => {
       sectionWidget: { products: LIVE_ROWS }
     });
 
-    // The designer reads `products` first, so the editor keeps showing the
-    // collection exactly as it was picked.
+    // The editor canvas falls back to `products` while a pick is unsaved
+    // (ZERO-5084), so the snapshot has to survive next to the live rows.
     expect(section?.dataSource.details.collection.products).toEqual(
       SNAPSHOT_ROWS
     );

package/src/custom/README-sections.md

@@ -279,6 +279,17 @@ import fails the brand's build with "cannot be imported from a Client Component
 module". `@akinon/pz-theme/src/custom` does not re-export it either; the deep
 module is the one route.
 
+**A section that draws its collection's rows itself** reads them off its node,
+the way the built-in renderers do: `dataSource.details.collection.data` (the
+section widget's live answer, what the storefront shows) first, then
+`dataSource.details.collection.products` (the snapshot taken when the merchant
+picked the collection). On the editor canvas `data` is only present while the
+editor reports the pick as saved, and the node then carries
+`dataSourceSaved: true`. Without that flag the pick is not published yet, the
+section's widget still answers for the previous collection, and the snapshot is
+the right thing to draw. A section that fetches its own widget on the canvas
+should do so only when `dataSourceSaved` is `true`.
+
 ## Parts must live on YOUR markup
 
 Part rules are generated with an ownership guard that excludes anything inside a

package/src/load-placeholder-sections.ts

@@ -13,6 +13,9 @@ import {
   PreviewSnapshot
 } from './chrome/preview-snapshot-source';
 import { getThemeConfig, ThemeConfig } from './chrome/theme-config-source';
+// One acceptance rule for this loader and the designer canvas's client fetch
+// (utils/live-rows.ts), so the two cannot take different answers.
+import { carriesProducts } from './utils/live-rows';
 
 const { getWidgetData } = serverData;
 
@@ -74,18 +77,6 @@ const withCollectionData = (dataSource: any, collectionData: unknown): any => ({
   }
 });
 
-/**
- * A widget answer counts as live rows only when it actually carries a
- * non-empty `products` array: a section with no data source attached answers
- * without the key at all, and an empty list must never replace the editor's
- * snapshot with nothing to render.
- */
-const carriesProducts = (widgetData: unknown): boolean =>
-  !!widgetData &&
-  typeof widgetData === 'object' &&
-  Array.isArray((widgetData as { products?: unknown }).products) &&
-  (widgetData as { products: unknown[] }).products.length > 0;
-
 /**
  * Resolves a section's data source reference into the object the renderer
  * expects, fetching collection data for collection-backed sources. Shared by
@@ -164,8 +155,14 @@ async function resolveSectionDataSource(
    * path they take.
    *
    * Only ever fills an ABSENT `data` — a source that already resolved keeps
-   * what it resolved to, and the editor reads `products` first either way, so
-   * the designer still sees the collection exactly as it was picked.
+   * what it resolved to.
+   *
+   * The editor canvas renders this same document. Its wrapper keeps this
+   * `data` only while the editor reports the section's pick as saved
+   * (`dataSourceSaved`, ZERO-5084): the widget is then bound to the collection
+   * the editor shows, so these rows are exactly the site's. While a pick is
+   * unsaved the wrapper drops them and the canvas shows the picked snapshot,
+   * `products`. See utils/live-rows.ts.
    */
   if (
     dataSource.details.collection &&

package/src/sections/featured-product-spotlight-section.tsx

@@ -146,17 +146,15 @@ const formatPriceWithCurrency = (
 };
 
 const getCollectionProducts = (
-  section: Section,
-  isDesigner: boolean
+  section: Section
 ): Record<string, unknown>[] => {
   const collectionDetails = section.dataSource?.details?.collection;
   const staticData = section.dataSource?.details?.static?.data;
-  const isEditorMode =
-    typeof window !== 'undefined' && isDesigner && window.parent !== window;
-
-  const collectionPayload = isEditorMode
-    ? collectionDetails?.products || collectionDetails?.data
-    : collectionDetails?.data || collectionDetails?.products;
+  // Live rows first in every mode. On the editor canvas the wrapper leaves
+  // `data` in place only for a saved pick, so an unsaved pick still shows its
+  // snapshot (utils/live-rows.ts).
+  const collectionPayload =
+    collectionDetails?.data || collectionDetails?.products;
 
   if (Array.isArray(collectionPayload)) {
     return collectionPayload as Record<string, unknown>[];
@@ -260,8 +258,8 @@ export default function FeaturedProductSpotlightSection({
   ]);
 
   const products = useMemo(
-    () => getCollectionProducts(section, isDesigner),
-    [section, isDesigner]
+    () => getCollectionProducts(section),
+    [section]
   );
   const fallbackProductPk = parsePositiveInt(
     getResponsiveValue(

package/src/sections/installment-options-section.tsx

@@ -259,17 +259,15 @@ const formatPriceWithCurrency = (
 };
 
 const getCollectionProducts = (
-  section: Section,
-  isDesigner: boolean
+  section: Section
 ): ProductLike[] => {
   const collectionDetails = section.dataSource?.details?.collection;
   const staticData = section.dataSource?.details?.static?.data;
-  const isEditorMode =
-    typeof window !== 'undefined' && isDesigner && window.parent !== window;
-
-  const collectionPayload = isEditorMode
-    ? collectionDetails?.products || collectionDetails?.data
-    : collectionDetails?.data || collectionDetails?.products;
+  // Live rows first in every mode. On the editor canvas the wrapper leaves
+  // `data` in place only for a saved pick, so an unsaved pick still shows its
+  // snapshot (utils/live-rows.ts).
+  const collectionPayload =
+    collectionDetails?.data || collectionDetails?.products;
 
   if (Array.isArray(collectionPayload)) {
     return collectionPayload as ProductLike[];
@@ -563,8 +561,8 @@ export default function InstallmentOptionsSection({
   );
 
   const sectionProducts = useMemo(
-    () => getCollectionProducts(section, isDesigner),
-    [section, isDesigner]
+    () => getCollectionProducts(section),
+    [section]
   );
   const collectionProduct =
     (sectionProducts[0] as ProductLike | undefined) || null;

package/src/sections/posts-slider-section.tsx

@@ -221,8 +221,7 @@ const replaceBlockValues = (
 
 const getIteratorProducts = (
   section: any,
-  iteratorBlock: any,
-  isDesigner: boolean
+  iteratorBlock: any
 ): Record<string, unknown>[] => {
   if (!section?.dataSource?.details) return [];
 
@@ -231,23 +230,17 @@ const getIteratorProducts = (
     iteratorBlock.properties?.iteratorDataPath;
 
   const details = section.dataSource.details;
-  const inEditor =
-    isDesigner && typeof window !== 'undefined' && window.parent !== window;
-
-  const candidates: unknown[] = inEditor
-    ? [
-        details.collection?.products,
-        details.static?.data,
-        details.collection?.data,
-        details
-      ]
-    : [
-        details.collection?.data?.products,
-        details.collection?.data,
-        details.collection?.products,
-        details.static?.data,
-        details
-      ];
+
+  // Live rows first in every mode. On the editor canvas the wrapper leaves
+  // `data` in place only for a saved pick, so an unsaved pick still shows its
+  // snapshot (utils/live-rows.ts).
+  const candidates: unknown[] = [
+    details.collection?.data?.products,
+    details.collection?.data,
+    details.collection?.products,
+    details.static?.data,
+    details
+  ];
 
   for (const candidate of candidates) {
     if (Array.isArray(candidate)) {
@@ -345,7 +338,7 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
     }
 
     const template = block.blocks[0];
-    const products = getIteratorProducts(section, block, isDesigner);
+    const products = getIteratorProducts(section, block);
     const fallbackCount = clampNumber(
       parseNumber(block.properties?.iteratorCount, 1),
       1,

package/src/sections/pre-order-launch-banner-section.tsx

@@ -237,17 +237,15 @@ const formatLaunchDate = (
 };
 
 const getCollectionProducts = (
-  section: Section,
-  isDesigner: boolean
+  section: Section
 ): Record<string, unknown>[] => {
   const collectionDetails = section.dataSource?.details?.collection;
   const staticData = section.dataSource?.details?.static?.data;
-  const isEditorMode =
-    typeof window !== 'undefined' && isDesigner && window.parent !== window;
-
-  const collectionPayload = isEditorMode
-    ? collectionDetails?.products || collectionDetails?.data
-    : collectionDetails?.data || collectionDetails?.products;
+  // Live rows first in every mode. On the editor canvas the wrapper leaves
+  // `data` in place only for a saved pick, so an unsaved pick still shows its
+  // snapshot (utils/live-rows.ts).
+  const collectionPayload =
+    collectionDetails?.data || collectionDetails?.products;
 
   if (Array.isArray(collectionPayload)) {
     return collectionPayload as Record<string, unknown>[];
@@ -363,8 +361,8 @@ export default function PreOrderLaunchBannerSection({
   ]);
 
   const products = useMemo(
-    () => getCollectionProducts(section, isDesigner),
-    [section, isDesigner]
+    () => getCollectionProducts(section),
+    [section]
   );
   const fallbackProductPk = parsePositiveInt(
     getResponsiveValue(

package/src/theme-placeholder-wrapper.tsx

@@ -27,6 +27,14 @@ import {
   HOVER_REVEAL_CSS
 } from './utils/property-switches';
 import { isPublishWindowVisible } from './utils/publish-window';
+import {
+  collectionBindingKey,
+  fetchDesignerLiveRows,
+  hangDesignerDataSource,
+  liveRowsEntryKey,
+  LiveRowsStore,
+  seedLiveRows
+} from './utils/live-rows';
 import { buildClientRequestUrl } from '@akinon/next/utils';
 import { PreviewToEditorMessageType } from '@akinon/theme-contract';
 import { parseEditorMessage, postToEditor } from './editor-bridge';
@@ -417,6 +425,24 @@ export default function ThemePlaceholderWrapper({
       true;
   }, []);
   const [dataSources, setDataSources] = useState<any[]>(initialDataSources);
+  // Live rows for collection-backed sections on the designer canvas, keyed by
+  // section and binding (utils/live-rows.ts). Seeded from the rows the server
+  // wrote into this document, so a saved section shows exactly what the
+  // storefront rendered without a request.
+  const [liveRowsSeed] = useState(() => seedLiveRows(initialSections));
+  const liveRowsRef = useRef<LiveRowsStore>(liveRowsSeed);
+  const liveRowsAttemptedRef = useRef<Set<string>>(new Set());
+  const liveRowsMountedRef = useRef(true);
+  const [liveRowsRevision, setLiveRowsRevision] = useState(0);
+  // Whether the editor has sent its theme for this placeholder yet. Only its
+  // sections say which picks are saved (`dataSourceSaved`).
+  const editorThemeHeardRef = useRef(false);
+  useEffect(() => {
+    liveRowsMountedRef.current = true;
+    return () => {
+      liveRowsMountedRef.current = false;
+    };
+  }, []);
   const [themeSettings, setThemeSettings] = useState<Record<
     string,
     unknown
@@ -720,8 +746,12 @@ export default function ThemePlaceholderWrapper({
     }
   }, []);
 
+  // Re-hangs the editor's data-source records over the sections, and again
+  // whenever live rows arrive (`liveRowsRevision`). Waits for the editor's
+  // theme: until it arrives nothing says which picks are unsaved, and the
+  // server-rendered rows are the ones the storefront shows.
   useEffect(() => {
-    if (!isDesigner) return;
+    if (!isDesigner || !editorThemeHeardRef.current) return;
     if (dataSources && dataSources.length > 0) {
       setSections((prevSections) => {
         return prevSections.map((section) => {
@@ -732,14 +762,56 @@ export default function ThemePlaceholderWrapper({
 
             return {
               ...section,
-              dataSource: dataSource || section.dataSource
+              dataSource: hangDesignerDataSource(
+                section,
+                dataSource || section.dataSource,
+                liveRowsRef.current
+              )
             };
           }
           return section;
         });
       });
     }
-  }, [dataSources, isDesigner]);
+  }, [dataSources, isDesigner, liveRowsRevision]);
+
+  // A section whose pick is saved but whose current binding has no rows yet —
+  // it was re-pointed and published in this session, the document is a draft
+  // preview (whose blob path writes no live rows), or the server could not
+  // resolve them — asks the storefront for them once. Until they arrive the
+  // picked snapshot stays on the canvas: it is the same collection.
+  useEffect(() => {
+    if (!isDesigner) return;
+
+    sections.forEach((section) => {
+      if (section.dataSourceSaved !== true || !section.id) return;
+
+      const bindingKey = collectionBindingKey(section.dataSource);
+      if (!bindingKey) return;
+
+      const entryKey = liveRowsEntryKey(section.id, bindingKey);
+      if (
+        liveRowsRef.current.has(entryKey) ||
+        liveRowsAttemptedRef.current.has(entryKey)
+      ) {
+        return;
+      }
+
+      liveRowsAttemptedRef.current.add(entryKey);
+
+      fetchDesignerLiveRows(
+        section.id,
+        section.dataSource?.details?.collection
+      ).then((answer) => {
+        if (answer === null || !liveRowsMountedRef.current) return;
+
+        liveRowsRef.current.set(entryKey, answer);
+        setLiveRowsRevision((revision) => revision + 1);
+      });
+    });
+    // `sections` already follows `dataSources`: every change to the records is
+    // hung over the sections before this runs.
+  }, [sections, isDesigner]);
 
   useEffect(() => {
     if (typeof window === 'undefined') {
@@ -818,6 +890,8 @@ export default function ThemePlaceholderWrapper({
               }
 
               if (placeholder.sections) {
+                editorThemeHeardRef.current = true;
+
                 // In editor mode: Complete override with theme editor's data
                 // This allows unsaved sections to render with editor's product data
                 setSections(() => {
@@ -842,7 +916,13 @@ export default function ThemePlaceholderWrapper({
                       properties: incomingSection.properties
                         ? { ...incomingSection.properties }
                         : {},
-                      dataSource: dataSource || null
+                      // Live rows only for a pick the editor reports as
+                      // saved; otherwise the picked snapshot.
+                      dataSource: hangDesignerDataSource(
+                        incomingSection,
+                        dataSource || null,
+                        liveRowsRef.current
+                      )
                     };
                   });
                 });