@akinon/pz-theme 2.0.103-beta.0 → 2.0.103

package/CHANGELOG.md

@@ -1,12 +1,13 @@
 # @akinon/pz-theme
 
-## 2.0.103-beta.0
+## 2.0.103
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.103-beta.0
-  - @akinon/theme-contract@2.0.103-beta.0
+- 64407cc: ZERO-4829: add tests for iterator price shapes and enhance price formatting logic
+- af4e3ba: ZERO-4289: enhance group block logic to handle sized shapes and update property switch behavior
+  - @akinon/next@2.0.103
+  - @akinon/theme-contract@2.0.103
 
 ## 2.0.102
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.103-beta.0",
+  "version": "2.0.103",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.103-beta.0",
+    "@akinon/next": "2.0.103",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.103-beta.0",
+    "@akinon/theme-contract": "2.0.103",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.103-beta.0",
+    "@akinon/next": "2.0.103",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/collection-row-scope.test.tsx

@@ -0,0 +1,187 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+import ThemeBlock, { type Block } from '../theme-block';
+import { buildIteratorBlock } from '../utils/iterator-utils';
+import {
+  publishesProductRows,
+  resolveCollectionRowProduct
+} from '../blocks/item-template-utils';
+
+/**
+ * ZERO-4829 — the Product Card as a section for ANY page repeats over a
+ * collection data source. Its favourite and add-to-basket resolve the product
+ * through the item scope, and a custom section's repeat used to open none:
+ * every card rendered its name, price and picture and silently lost the heart.
+ *
+ * The rule is declared off the data source's type, not sniffed off the rows:
+ * a collection is a list of commerce products by definition, a static or API
+ * source says nothing about its rows and keeps behaving exactly as before.
+ */
+const product = (pk: number, name: string) => ({
+  pk,
+  name,
+  price: '3499.00',
+  retail_price: '',
+  absolute_url: `/p-${pk}/`,
+  productimage_set: [{ image: `/img-${pk}.jpg` }]
+});
+
+const collection = (products: Record<string, unknown>[]) => ({
+  id: 'ds-1',
+  name: 'Erkek',
+  type: 'collection',
+  details: { collection: { pk: 1, productLimit: 4, products } }
+});
+
+const cardTemplate = (): Block => ({
+  id: 'card',
+  type: 'group',
+  label: 'Product Card',
+  properties: { tag: 'div' },
+  styles: {},
+  blocks: [
+    {
+      id: 'name',
+      type: 'text',
+      label: 'Name',
+      value: '',
+      properties: { dataBinding: 'item.name' },
+      styles: {},
+      blocks: []
+    },
+    {
+      id: 'fav',
+      type: 'favorite-button',
+      label: 'Favourite',
+      properties: { icon: 'heart', iconSize: 8, showLabel: false },
+      styles: {},
+      blocks: []
+    }
+  ]
+});
+
+const iterator = (): Block => ({
+  id: 'it',
+  type: 'group',
+  label: 'Iterator',
+  isIterator: true,
+  properties: { tag: 'div', iteratorDataPath: 'products', iteratorCount: 4 },
+  styles: {},
+  blocks: [cardTemplate()]
+});
+
+describe('a collection repeat publishes its rows as products', () => {
+  it('is declared off the data source type', () => {
+    expect(publishesProductRows({ type: 'collection' })).toBe(true);
+    expect(publishesProductRows({ type: 'static' })).toBe(false);
+    expect(publishesProductRows({ type: 'api' })).toBe(false);
+    expect(publishesProductRows(null)).toBe(false);
+  });
+
+  it('stamps every clone with its row as the product', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iterator(),
+      sectionDataSource: collection([product(11, 'A'), product(12, 'B')]),
+      pageContext: null
+    } as never);
+
+    const scopes = (expanded.blocks || []).map(
+      (clone) => clone.itemScopeProduct
+    );
+    expect(scopes.map((scope) => scope && scope.pk)).toEqual([11, 12]);
+    expect(scopes[0]).toMatchObject({ name: 'A', absolute_url: '/p-11/' });
+  });
+
+  it('opens no scope for a static source, so those repeats are untouched', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: {
+        ...iterator(),
+        properties: { tag: 'div', iteratorDataPath: 'items', iteratorCount: 2 }
+      },
+      sectionDataSource: {
+        id: 'ds-2',
+        name: 'Static',
+        type: 'static',
+        details: { static: { name: 'x', data: [{ pk: 1, name: 'A' }] } }
+      },
+      pageContext: null
+    } as never);
+
+    for (const clone of expanded.blocks || []) {
+      expect('itemScopeProduct' in clone).toBe(false);
+    }
+  });
+
+  it('opens no second scope when the caller brought its own rows', () => {
+    // The product grid's ItemTemplateList wraps its clones itself.
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iterator(),
+      sectionDataSource: collection([product(11, 'A')]),
+      pageContext: null,
+      items: [product(11, 'A')]
+    } as never);
+
+    for (const clone of expanded.blocks || []) {
+      expect('itemScopeProduct' in clone).toBe(false);
+    }
+  });
+
+  it('a padding row (fewer products than the count) carries no product', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iterator(),
+      sectionDataSource: collection([product(11, 'A')]),
+      pageContext: null,
+      forceIteratorCount: 2
+    } as never);
+
+    // Whatever the count floor draws beyond the one real row is a padding
+    // row: it is stamped, but with null, so nothing inside it addresses a pk.
+    const padding = (expanded.blocks || []).slice(1);
+    for (const clone of padding) {
+      expect(clone.itemScopeProduct).toBeNull();
+    }
+  });
+
+  it('renders the favourite inside a scoped clone, for a guest as a login link', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iterator(),
+      sectionDataSource: collection([product(11, 'A')]),
+      pageContext: null
+    } as never);
+    const [clone] = expanded.blocks || [];
+
+    const { container } = render(
+      <ThemeBlock block={clone} placeholderId="home" sectionId="s1" />
+    );
+
+    const favourite = container.querySelector('[data-favorite-button]');
+    expect(favourite).not.toBeNull();
+    expect(favourite?.getAttribute('data-favorite-state')).toBe('guest');
+    expect(container.textContent).toContain('A');
+  });
+
+  it('renders no favourite for the same clone without the scope', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iterator(),
+      sectionDataSource: collection([product(11, 'A')]),
+      pageContext: null
+    } as never);
+    const [clone] = expanded.blocks || [];
+    const { itemScopeProduct: _scope, ...unscoped } = clone;
+
+    const { container } = render(
+      <ThemeBlock block={unscoped} placeholderId="home" sectionId="s1" />
+    );
+
+    expect(container.querySelector('[data-favorite-button]')).toBeNull();
+  });
+
+  it('resolves the row through the same pk rule as a grid row', () => {
+    expect(resolveCollectionRowProduct({ pk: '7', name: 'x' })).toMatchObject({
+      pk: 7
+    });
+    expect(resolveCollectionRowProduct({ name: 'no id' })).toBeNull();
+    expect(resolveCollectionRowProduct({})).toBeNull();
+  });
+});

package/src/__tests__/group-row-styles.test.tsx

@@ -0,0 +1,110 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+import ThemeBlock, { type Block } from '../theme-block';
+
+/**
+ * ZERO-4829 — the Product Card's colour-swatch chip is an EMPTY `<a>` group
+ * whose only appearance is a background its row resolved
+ * (`linear-gradient({{item.color}}, …)`). Two things the renderer never had to
+ * do before: inline a row-resolved style on a GROUP (whose styles live on the
+ * wrapper, its own element being `display: contents`), and give an empty
+ * anchor its href when the router link is the branch that would carry it.
+ */
+const chip = (overrides: Partial<Block> = {}): Block => ({
+  id: 'chip-clone-0',
+  styleSourceId: 'chip',
+  type: 'group',
+  label: 'Swatch',
+  properties: { tag: 'a', href: '/gant-erkek-bej-polo/' },
+  styles: {
+    width: { desktop: '8px' },
+    'background-color': { desktop: '#d9c8a9' },
+    'box-shadow': { desktop: 'inset 0 0 0 1px rgba(0, 0, 0, 0.08)' }
+  },
+  order: 0,
+  hidden: false,
+  blocks: [],
+  // The row resolved the colour (the template carried `{{item.color}}`);
+  // jsdom cannot hold a gradient in an inline style, so the test binds the
+  // plain colour the same way — the renderer does not care which property.
+  rowStyleKeys: ['background-color'],
+  ...overrides
+});
+
+describe('a group whose row resolved a style', () => {
+  it('inlines exactly the row-resolved keys on its wrapper', () => {
+    const { container } = render(
+      <ThemeBlock block={chip()} placeholderId="p" sectionId="s" isDesigner={false} />
+    );
+    const wrapper = container.querySelector('[data-block-id="chip"]') as HTMLElement;
+
+    expect(wrapper.style.backgroundColor).toBe('rgb(217, 200, 169)');
+    // Everything else stays on the shared rule.
+    expect(wrapper.style.width).toBe('');
+    expect(wrapper.style.boxShadow).toBe('');
+  });
+
+  it('inlines nothing on a group whose row resolved nothing', () => {
+    const { container } = render(
+      <ThemeBlock
+        block={chip({ rowStyleKeys: undefined })}
+        placeholderId="p"
+        sectionId="s"
+        isDesigner={false}
+      />
+    );
+    const wrapper = container.querySelector('[data-block-id="chip"]') as HTMLElement;
+    expect(wrapper.getAttribute('style')).toBeNull();
+  });
+});
+
+describe('an empty anchor group', () => {
+  it('keeps its internal href on the storefront — also when it is a sized shape', () => {
+    const { container } = render(
+      <ThemeBlock
+        block={chip({
+          styles: {
+            width: { desktop: '8px' },
+            height: { desktop: '12px' },
+            'background-color': { desktop: '#d9c8a9' }
+          },
+          rowStyleKeys: undefined
+        })}
+        placeholderId="p"
+        sectionId="s"
+        isDesigner={false}
+      />
+    );
+    const anchor = container.querySelector('a') as HTMLAnchorElement;
+    expect(anchor).not.toBeNull();
+    expect(anchor.getAttribute('href')).toBe('/gant-erkek-bej-polo/');
+    expect(anchor.className).toContain('contents');
+  });
+});
+
+describe('an empty group on the canvas', () => {
+  const render_ = (styles: Record<string, unknown>) =>
+    render(
+      <ThemeBlock
+        block={chip({ styles, properties: { tag: 'a', href: '' }, rowStyleKeys: undefined })}
+        placeholderId="p"
+        sectionId="s"
+        isDesigner
+      />
+    );
+
+  it('draws no "drop blocks here" chip when it is a sized shape (a swatch)', () => {
+    const { container } = render_({
+      width: { desktop: '8px' },
+      height: { desktop: '12px' },
+      'background-color': { desktop: '#c9c9c9' }
+    });
+    expect(container.querySelector('[data-group-placeholder]')).toBeNull();
+  });
+
+  it('still offers the drop target for an unsized empty group', () => {
+    const { container } = render_({ 'background-color': { desktop: '#c9c9c9' } });
+    expect(container.querySelector('[data-group-placeholder]')).not.toBeNull();
+  });
+});

package/src/__tests__/theme-typography-vars.test.tsx

@@ -0,0 +1,125 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import { renderToStaticMarkup } from 'react-dom/server.node';
+
+import ThemePlaceholderWrapper, {
+  buildThemeTypographyCss
+} from '../theme-placeholder-wrapper';
+import { readThemeTypographyFont, resolveThemeCssVariables } from '../utils';
+import type { Section } from '../theme-section';
+
+/**
+ * ZERO-4829 — a card dropped on a page whose body is not the brand face
+ * (the homepage body is Jost on GANT) rendered in that fallback, because a
+ * text block has no way to say "the theme's body face": the editor's
+ * typography settings only ever loaded fonts, never named them anywhere a
+ * template could point at.
+ *
+ * `--theme-font-<variant>` closes that. It is resolved from the settings on
+ * both sides of hydration, like the colour variables, so the server does not
+ * print the fallback while the client paints the brand face.
+ */
+const SETTINGS = {
+  backgroundColor: '#ffffff',
+  typography: [
+    {
+      key: 'heading01',
+      fontFamily: 'GantSerif-MediumCondensed',
+      fontWeight: '500'
+    },
+    { key: 'body', fontFamily: 'GantModernV2-Regular', fontWeight: '400' },
+    { key: 'subheading', fontFamily: 'inherit' }
+  ]
+};
+
+const section = {
+  id: 's1',
+  type: 'generic-section',
+  name: 's1',
+  label: 'S1',
+  order: 0,
+  hidden: false,
+  properties: {},
+  styles: {},
+  blocks: []
+} as unknown as Section;
+
+describe('the theme font variables', () => {
+  it('resolve from the settings, fallback only when the variant names no face', () => {
+    expect(readThemeTypographyFont(SETTINGS, 'body')).toBe(
+      'GantModernV2-Regular'
+    );
+    expect(readThemeTypographyFont(SETTINGS, 'subheading')).toBeUndefined();
+    expect(readThemeTypographyFont(SETTINGS, 'missing')).toBeUndefined();
+    expect(readThemeTypographyFont(null, 'body')).toBeUndefined();
+
+    expect(
+      resolveThemeCssVariables('var(--theme-font-body, inherit)', SETTINGS)
+    ).toBe('GantModernV2-Regular');
+    expect(
+      resolveThemeCssVariables(
+        'var(--theme-font-subheading, inherit)',
+        SETTINGS
+      )
+    ).toBe('inherit');
+    // A settings-less render keeps the fallback, so nothing paints a var()
+    // the document never defined.
+    expect(
+      resolveThemeCssVariables('var(--theme-font-body, inherit)', null)
+    ).toBe('inherit');
+  });
+
+  it('are emitted on :root with the markup', () => {
+    expect(buildThemeTypographyCss(SETTINGS)).toBe(
+      ':root{--theme-font-heading01:GantSerif-MediumCondensed;--theme-font-body:GantModernV2-Regular}'
+    );
+    expect(buildThemeTypographyCss({ backgroundColor: '#fff' })).toBe('');
+    expect(buildThemeTypographyCss(null)).toBe('');
+
+    const html = renderToStaticMarkup(
+      <ThemePlaceholderWrapper
+        slug="theme-homepage-body"
+        initialSections={[section]}
+        initialPlaceholderId="theme-homepage-body"
+        isDesignMode={false}
+        initialThemeSettings={SETTINGS}
+      />
+    );
+    expect(html).toContain('--theme-font-body:GantModernV2-Regular');
+  });
+
+  it('cannot break out of the style tag through a font name', () => {
+    expect(
+      buildThemeTypographyCss({
+        typography: [{ key: 'body', fontFamily: 'Evil</style><script>' }]
+      })
+    ).not.toMatch(/<\/style/i);
+    // A key that is not a plain token is not turned into a variable name.
+    expect(
+      buildThemeTypographyCss({
+        typography: [{ key: 'body;}*{', fontFamily: 'X' }]
+      })
+    ).toBe('');
+  });
+
+  it('are kept live on the document by the settings effect', () => {
+    document.documentElement.style.removeProperty('--theme-font-body');
+    const { unmount } = render(
+      <ThemePlaceholderWrapper
+        slug="theme-homepage-body"
+        initialSections={[section]}
+        initialPlaceholderId="theme-homepage-body"
+        isDesignMode={false}
+        initialThemeSettings={SETTINGS}
+      />
+    );
+
+    expect(
+      document.documentElement.style.getPropertyValue('--theme-font-body')
+    ).toBe('GantModernV2-Regular');
+    expect(
+      document.documentElement.style.getPropertyValue('--theme-font-subheading')
+    ).toBe('');
+    unmount();
+  });
+});

package/src/blocks/__tests__/listing-row-swatches.test.ts

@@ -0,0 +1,111 @@
+import { normalizeListingProduct, parseListingLookups } from '../listing-row';
+
+/**
+ * ZERO-4829 — the colour swatches on the Product Card. GANT's listing payload
+ * nests the colours under `extra_data.variants[attribute_key=integration_renk]`
+ * and each option carries the colour CODE as its `label` — no `value`, no
+ * `is_selected`. The swatch table is authored against that code, so the
+ * lookup has to accept the label where the value is missing, and the current
+ * colour is the option whose product IS this row.
+ */
+const gantProduct = (pk: number) => ({
+  pk,
+  name: 'GANT Erkek Mavi Polo',
+  absolute_url: `/p-${pk}/`,
+  price: '3499.00',
+  retail_price: '3999.00',
+  currency_type: 'try',
+  attributes: { integration_renk: '457', badge2: 'YENİ SEZON' },
+  extra_data: {
+    variants: [
+      {
+        attribute_key: 'integration_renk',
+        options: [
+          {
+            label: '457',
+            in_stock: true,
+            is_selectable: true,
+            product: {
+              pk,
+              absolute_url: `/p-${pk}/`,
+              productimage_set: [{ image: '/blue.jpg' }]
+            }
+          },
+          {
+            label: '200',
+            in_stock: true,
+            is_selectable: true,
+            product: {
+              pk: pk + 1,
+              absolute_url: `/p-${pk + 1}/`,
+              productimage_set: [{ image: '/beige.jpg' }]
+            }
+          },
+          {
+            label: '999',
+            in_stock: false,
+            is_selectable: false,
+            product: { pk: pk + 2, absolute_url: `/p-${pk + 2}/` }
+          }
+        ]
+      },
+      { attribute_key: 'integration_beden', options: [{ label: 'M' }] }
+    ]
+  }
+});
+
+describe('colour swatches on a listing row', () => {
+  it('maps the swatch colour by the option label when the option has no value', () => {
+    const row = normalizeListingProduct(gantProduct(1), 0, {
+      currency: 'TRY',
+      lookups: parseListingLookups('', '', '457|#2d5da1\n200|#d9c8a9')
+    });
+
+    expect(row?.colors?.map((color) => color.color)).toEqual([
+      '#2d5da1',
+      '#d9c8a9'
+    ]);
+    expect(row?.colors?.map((color) => color.label)).toEqual(['457', '200']);
+    expect(row?.colorCount).toBe(2);
+  });
+
+  it('marks the colour whose product is this row as selected', () => {
+    const row = normalizeListingProduct(gantProduct(1), 0, { currency: 'TRY' });
+
+    expect(row?.colors?.map((color) => color.isSelected)).toEqual([true, false]);
+    expect(row?.colors?.[1]).toMatchObject({
+      url: '/p-2/',
+      image: '/beige.jpg'
+    });
+  });
+
+  it('still keys the table by value where a payload carries one', () => {
+    const product = gantProduct(1);
+    const [group] = product.extra_data.variants;
+    (group.options[0] as Record<string, unknown>).value = 'mavi';
+
+    const row = normalizeListingProduct(product, 0, {
+      currency: 'TRY',
+      lookups: parseListingLookups('', '', 'mavi|#0000ff\n457|#2d5da1')
+    });
+
+    expect(row?.colors?.[0].color).toBe('#0000ff');
+  });
+
+  it('publishes the badge attribute keyed, for a text bound straight to it', () => {
+    const row = normalizeListingProduct(gantProduct(1), 0, { currency: 'TRY' });
+    expect(row?.attributes?.badge2).toBe('YENİ SEZON');
+  });
+
+  it('reads the keyed attributes the page context publishes beside its positional list', () => {
+    // What a listing's own rows look like after chrome/page-context.ts:
+    // `attributes` is the positional list, the keyed map is `attributesKeyed`.
+    const pageContextRow = {
+      ...gantProduct(1),
+      attributes: [{ key: 'badge2', label: 'Badge', value: 'YENİ SEZON' }],
+      attributesKeyed: { badge2: 'YENİ SEZON', integration_renk: '457' }
+    };
+    const row = normalizeListingProduct(pageContextRow, 0, { currency: 'TRY' });
+    expect(row?.attributes).toEqual({ badge2: 'YENİ SEZON', integration_renk: '457' });
+  });
+});

package/src/blocks/group-block.tsx

@@ -20,6 +20,18 @@ import { renderComposedChildren } from './render-composed-children';
  */
 const isInternalHref = (href: unknown): href is string =>
   typeof href === 'string' && href.startsWith('/') && !href.startsWith('//');
+const hasOwnLength = (value: unknown, breakpoint: string): boolean => {
+  const raw = String(getResponsiveValue(value, breakpoint, '')).trim();
+  return raw !== '' && raw !== 'auto' && raw !== '0' && raw !== '0px';
+};
+
+/** Both dimensions authored: the group draws a box whether or not it has children. */
+const isSizedShape = (styles: unknown, breakpoint: string): boolean =>
+  Boolean(styles) &&
+  typeof styles === 'object' &&
+  hasOwnLength((styles as Record<string, unknown>).width, breakpoint) &&
+  hasOwnLength((styles as Record<string, unknown>).height, breakpoint);
+
 const GroupBlock = ({
   block,
   placeholderId,
@@ -75,10 +87,32 @@ const GroupBlock = ({
   const shippingRole = String(
     getResponsiveValue(block.properties?.shippingRole, currentBreakpoint, '')
   );
+  // A group with a width and a height of its own and nothing inside is a
+  // SHAPE — a colour-swatch chip, a progress marker — not a container waiting
+  // for children, so the canvas must not stamp "drop blocks here" over it
+  // (ZERO-4829: the chips of every card read "Group (drop blocks here)").
   const isVisualUtilityGroup =
-    shippingRole === 'progress-fill' || shippingRole === 'progress-marker';
+    shippingRole === 'progress-fill' ||
+    shippingRole === 'progress-marker' ||
+    isSizedShape(block.styles, currentBreakpoint);
 
   if (!block.blocks || block.blocks.length === 0) {
+    // An empty anchor is a legitimate element too — a colour-swatch chip is
+    // a link with nothing inside it but its background. It navigates the same
+    // way a filled one does; the plain-<a> branches below have no href when
+    // the router link was chosen, which is exactly the case an internal href
+    // is — so this comes first, before the shape branch a sized chip takes.
+    if (useRouterLink) {
+      return (
+        <NextLink
+          href={href as string}
+          prefetch={false}
+          className="contents"
+          onClick={handleAnchorAnalytics}
+        />
+      );
+    }
+
     if (isVisualUtilityGroup) {
       return <Tag {...tagProps} />;
     }

package/src/blocks/item-template-utils.ts

@@ -134,6 +134,40 @@ export const resolveSliderRowProduct = (
   return { ...item, pk } as ThemeProduct;
 };
 
+/**
+ * The section data sources whose rows are products.
+ *
+ * The same declared-not-sniffed rule as the two allow-lists above, applied to
+ * a section's own repeat: a custom section iterating a COLLECTION data source
+ * is, by the source's definition, a list of commerce products, so a card
+ * dropped into it (ZERO-4829's "Product Cards" on any page) gets the same
+ * product scope a product grid row gets — and its favourite and add-to-basket
+ * address the right product instead of rendering nothing for want of one.
+ * A static or API source says nothing about its rows and opens no scope.
+ */
+const PRODUCT_ROW_DATA_SOURCE_TYPES = new Set(['collection']);
+
+export const publishesProductRows = (
+  sectionDataSource: { type?: unknown } | null | undefined
+): boolean =>
+  typeof sectionDataSource?.type === 'string' &&
+  PRODUCT_ROW_DATA_SOURCE_TYPES.has(sectionDataSource.type);
+
+/**
+ * A collection row seen as the ambient product, or null for the padding rows
+ * the count floor draws when the source has answered with fewer products.
+ */
+export const resolveCollectionRowProduct = (
+  item: Record<string, unknown> | null | undefined
+): ThemeProduct | null => {
+  if (!item || Object.keys(item).length === 0) return null;
+
+  const pk = readProductPk(item);
+  if (pk === undefined) return null;
+
+  return { ...item, pk } as ThemeProduct;
+};
+
 /**
  * What a product row shows in the editor when the page has no live data.
  *