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

package/src/blocks/product-grid-block.tsx

@@ -0,0 +1,966 @@
+'use client';
+
+import React from 'react';
+import NextLink from 'next/link';
+import { getResponsiveValue, partAttrs } from '../utils';
+import {
+  DESKTOP_MIN_WIDTH,
+  MOBILE_MEDIA_QUERY_COMPACT,
+  TABLET_MEDIA_QUERY_COMPACT
+} from '../utils/breakpoints';
+import ThemeBlock, { Block } from '../theme-block';
+import { hasItemTemplate, ItemTemplateList } from './item-template';
+import { BlockRendererProps } from './block-renderer-registry';
+import {
+  MoneyCurrencyDisplay,
+  MoneyCurrencyPosition,
+  MoneyDecimals,
+  MoneyStyleOptions
+} from './commerce-format';
+import {
+  listingPlaceholderStyle,
+  ListingProduct,
+  ListingValueLookups,
+  parseListingLookups,
+  readToggle,
+  useListingContext
+} from './listing-context';
+
+const clampInt = (value: unknown, fallback: number, min: number, max: number) => {
+  const numeric = Math.round(Number(value));
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.min(max, Math.max(min, numeric));
+};
+
+const readCount = (value: unknown, fallback: number): number => {
+  const numeric = Math.round(Number(value));
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : fallback;
+};
+
+/**
+ * Remembered per block for the session: a shopper who chose a denser grid
+ * expects it to survive paging through the category, and to be forgotten by
+ * the time they come back tomorrow.
+ */
+const DENSITY_KEY_PREFIX = 'pz-grid-density:';
+
+const readStoredDensity = (key: string): number | null => {
+  // sessionStorage throws in Safari private mode and is absent during SSR.
+  try {
+    const numeric = Math.round(Number(window.sessionStorage.getItem(key)));
+    return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
+  } catch {
+    return null;
+  }
+};
+
+const writeStoredDensity = (key: string, value: number) => {
+  try {
+    window.sessionStorage.setItem(key, String(value));
+  } catch {
+    // A storage failure only costs the shopper the memory of the choice.
+  }
+};
+
+/** The column counts the designer allows, as an ascending, deduped list. */
+const parseDensityOptions = (raw: string): number[] => {
+  const counts = new Set<number>();
+
+  raw.split(',').forEach((entry) => {
+    const numeric = Math.round(Number(entry.trim()));
+    if (!Number.isFinite(numeric) || numeric < 1 || numeric > 6) return;
+    counts.add(numeric);
+  });
+
+  return Array.from(counts).sort((a, b) => a - b);
+};
+
+/**
+ * The switcher's mark: as many bars as the layout has columns, which is how
+ * both audited designs draw it — the shopper reads the density rather than a
+ * number.
+ */
+const DensityGlyph = ({ columns }: { columns: number }) => {
+  const gap = 2;
+  const cell = (16 - gap * (columns - 1)) / columns;
+
+  return (
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 16 16"
+      fill="currentColor"
+      aria-hidden="true"
+      {...partAttrs('density-icon')}
+    >
+      {Array.from({ length: columns }, (_, index) => (
+        <rect
+          key={index}
+          x={index * (cell + gap)}
+          y={0}
+          width={cell}
+          height={16}
+          rx={1}
+        />
+      ))}
+    </svg>
+  );
+};
+
+/**
+ * Two things a grid child can be besides a product card.
+ *
+ * Both are read off the same `role` property the row layout already uses, and
+ * a child carrying neither goes on rendering exactly what it renders today —
+ * nothing, because the grid only ever looked for the row layout.
+ *
+ * `grid-insertion` is the merchandiser tile both audited brands hand-code: a
+ * campaign panel that takes a cell of the grid instead of sitting above or
+ * below it. `listing-empty` is what the page shows in place of the grid when
+ * the filters return nothing — a composition, so it can carry the heading, the
+ * explanation, the applied filters and the suggestions the designs ask for.
+ */
+const GRID_INSERTION_ROLE = 'grid-insertion';
+const EMPTY_STATE_ROLE = 'listing-empty';
+
+const readChildRole = (child: Block, breakpoint: string): string =>
+  String(getResponsiveValue(child.properties?.role, breakpoint, '') ?? '');
+
+/**
+ * The same rule the group block applies to its children: a hidden child stays
+ * mounted on the canvas so it can be brought back, and is gone on the
+ * storefront.
+ */
+const isChildRendered = (child: Block, isDesigner: boolean): boolean =>
+  isDesigner || !child.hidden;
+
+interface GridInsertion {
+  block: Block;
+  /** 1-based cell the tile was authored into, before it is clamped. */
+  position: number;
+  columnSpan: number;
+  rowSpan: number;
+  /** A campaign tile is normally page one only; `true` repeats it on every page. */
+  everyPage: boolean;
+}
+
+const collectInsertions = (
+  block: Block,
+  breakpoint: string,
+  isDesigner: boolean
+): GridInsertion[] =>
+  (block.blocks || [])
+    .filter(
+      (child) =>
+        readChildRole(child, breakpoint) === GRID_INSERTION_ROLE &&
+        isChildRendered(child, isDesigner)
+    )
+    .map((child) => ({
+      block: child,
+      position: clampInt(
+        getResponsiveValue(child.properties?.insertPosition, breakpoint, 1),
+        1,
+        1,
+        96
+      ),
+      columnSpan: clampInt(
+        getResponsiveValue(child.properties?.insertColumnSpan, breakpoint, 1),
+        1,
+        1,
+        6
+      ),
+      rowSpan: clampInt(
+        getResponsiveValue(child.properties?.insertRowSpan, breakpoint, 1),
+        1,
+        1,
+        4
+      ),
+      everyPage:
+        String(
+          getResponsiveValue(child.properties?.insertPages, breakpoint, 'first')
+        ) === 'all'
+    }));
+
+interface PlacedInsertion extends GridInsertion {
+  /** 1-based cell the tile ends up in once the page is known. */
+  cell: number;
+}
+
+/**
+ * Where each tile actually lands.
+ *
+ * A filter combination that returns three products would otherwise leave a
+ * tile authored for cell 5 pinned to a cell nothing can reach, punching a hole
+ * through the row. Sorting first and then pulling each tile back to at most
+ * one cell past the products before it keeps the grid gapless, and keeps two
+ * tiles authored onto the same cell from landing on top of each other.
+ */
+export const placeInsertions = (
+  insertions: GridInsertion[],
+  productCount: number
+): PlacedInsertion[] => {
+  let previousCell = 0;
+
+  return [...insertions]
+    .sort((a, b) => a.position - b.position)
+    .map((insertion, index) => {
+      const lastReachableCell = productCount + index + 1;
+      const cell = Math.max(
+        previousCell + 1,
+        Math.min(insertion.position, lastReachableCell)
+      );
+
+      previousCell = cell;
+      return { ...insertion, cell };
+    });
+};
+
+/**
+ * A tile's cell has to be recomputed for every column count the block emits:
+ * cell 5 is the start of row 2 in a four-column grid and of row 3 in a
+ * two-column one, and a two-column tile in a one-column grid would hang off
+ * the edge. Written into the block's stylesheet rather than inline for the
+ * same reason the column template is — an inline style would outrank the
+ * mobile override and the shopper's density choice.
+ *
+ * Every rule names the page it was written for. "Cell 5" means the fifth cell
+ * of the page being read, so the rule is only true of that page's tiles — and
+ * Load More can put several pages in one grid, where the tile index restarts
+ * at 0 on each. Without the page in the selector, page one's rule also claims
+ * page two's tile: both are definitely placed in the same cell, stacked on
+ * each other and over a card the shopper was already looking at. An appended
+ * page's tiles carry a page nothing on the live page has a rule for, so they
+ * are auto-placed into their own run instead of moving anything.
+ */
+export const buildInsertionRules = (
+  gridId: string,
+  placed: PlacedInsertion[],
+  columns: number,
+  page: number
+): string =>
+  placed
+    .map((insertion, index) => {
+      const span = Math.min(insertion.columnSpan, columns);
+      const column = ((insertion.cell - 1) % columns) + 1;
+      const row = Math.floor((insertion.cell - 1) / columns) + 1;
+      // Pulled back inside the last track when the span would overhang it.
+      const start = Math.min(column, columns - span + 1);
+
+      return (
+        `[data-product-grid-id="${gridId}"] ` +
+        `[data-product-grid-page="${page}"][data-product-grid-insert="${index}"]` +
+        `{grid-column:${start}/span ${span};grid-row:${row}/span ${insertion.rowSpan};}`
+      );
+    })
+    .join('');
+
+/**
+ * Tiles are pinned by the stylesheet, so both card paths put them in the same
+ * cell whatever their DOM position. Where the grid draws its own cards it can
+ * also put them in DOM order, which is the order a keyboard and a screen
+ * reader follow; a designer-authored row layout renders as one unit, so there
+ * the tiles trail it and only the stylesheet places them.
+ */
+export const interleaveCells = (
+  cards: React.ReactNode[],
+  tiles: React.ReactNode[],
+  placed: PlacedInsertion[]
+): React.ReactNode[] => {
+  const cells: React.ReactNode[] = [];
+  let tileIndex = 0;
+  let cellNumber = 0;
+
+  const takeDueTiles = () => {
+    while (
+      tileIndex < placed.length &&
+      placed[tileIndex].cell === cellNumber + 1
+    ) {
+      cells.push(tiles[tileIndex]);
+      tileIndex += 1;
+      cellNumber += 1;
+    }
+  };
+
+  cards.forEach((card) => {
+    takeDueTiles();
+    cells.push(card);
+    cellNumber += 1;
+  });
+  takeDueTiles();
+
+  // Clamping should leave nothing behind; appending the remainder means a
+  // miscount would misplace a tile rather than delete the campaign.
+  while (tileIndex < placed.length) {
+    cells.push(tiles[tileIndex]);
+    tileIndex += 1;
+  }
+
+  return cells;
+};
+
+const IMAGE_RATIOS = ['auto', '1 / 1', '3 / 4', '2 / 3', '4 / 5', '16 / 9'];
+const DECIMALS = ['always', 'auto', 'never'];
+const CURRENCY_DISPLAYS = ['', 'symbol', 'code', 'custom', 'none'];
+const CURRENCY_POSITIONS = ['', 'before', 'after'];
+
+/** Reads one of a fixed set, so a hand-edited value cannot reach Intl. */
+const readOption = <T extends string>(
+  value: unknown,
+  breakpoint: string,
+  allowed: string[],
+  fallback: T
+): T => {
+  const raw = String(getResponsiveValue(value, breakpoint, fallback));
+  return (allowed.includes(raw) ? raw : fallback) as T;
+};
+
+/**
+ * Functional listing block: the product grid of a category/search/PLP page.
+ * Product CONTENT stays commerce-driven (it comes from the listing page
+ * context built server side); the editor owns column counts, which card
+ * fields appear, the image frame and styling.
+ *
+ * An optional shopper-facing density switcher (off by default) lets the
+ * column count be changed on the page and remembers it for the session; the
+ * server always renders the count the designer authored, so the markup is
+ * complete before any script runs.
+ *
+ * Two kinds of authored child extend what the grid can express: a child marked
+ * `grid-insertion` is a merchandiser tile that takes a cell of the grid, and a
+ * child marked `listing-empty` is the composition shown in place of the grid
+ * when the listing returns nothing. Neither exists until a designer marks one,
+ * so a published grid renders exactly what it rendered before.
+ *
+ * Parts: list, card, image, name, price, sale-price, list-price, badge,
+ * density, density-label, density-option, density-icon, insert, empty.
+ * Properties: columnsDesktop, columnsMobile, limit, showName, nameLines,
+ * imageRatio, imageFit, showPrice, showRetailPrice, showDiscountBadge,
+ * discountBadgeTemplate, badgePosition, decimals, currencyDisplay,
+ * currencyText, currencyPosition, showDensitySwitcher, densityOptions,
+ * densityStyle, densityPosition, densityLabel, densityAriaLabel,
+ * previewEmptyState, badgeAttribute, badgeMap, swatchMap.
+ * Child properties (on a `grid-insertion` child): insertPosition,
+ * insertColumnSpan, insertRowSpan, insertPages.
+ */
+const ProductGridBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  selectedBlockId = null,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  // The card's money format. Read before the listing is resolved because the
+  // listing formats every price on the row with it — the built-in card and a
+  // designer-authored one therefore read the same. Memoised on the values, or
+  // the listing would be rebuilt on every render.
+  const decimals = readOption<MoneyDecimals>(
+    block.properties?.decimals,
+    currentBreakpoint,
+    DECIMALS,
+    'always'
+  );
+  const currencyDisplay = readOption<MoneyCurrencyDisplay>(
+    block.properties?.currencyDisplay,
+    currentBreakpoint,
+    CURRENCY_DISPLAYS,
+    ''
+  );
+  const currencyPosition = readOption<MoneyCurrencyPosition>(
+    block.properties?.currencyPosition,
+    currentBreakpoint,
+    CURRENCY_POSITIONS,
+    ''
+  );
+  const currencyText = String(
+    getResponsiveValue(block.properties?.currencyText, currentBreakpoint, '')
+  );
+  const money = React.useMemo<MoneyStyleOptions>(
+    () => ({ decimals, currencyDisplay, currencyText, currencyPosition }),
+    [decimals, currencyDisplay, currencyText, currencyPosition]
+  );
+
+  // The author's value -> presentation tables. Commerce sends a badge as a bare
+  // key ("new_season") and a colour as a bare value ("kirmizi") and carries no
+  // label, image or hex for either, so `item.badge.*` and `item.colors[].color`
+  // can only carry anything once a designer maps them here. Nothing authored
+  // means no table, which is the row every published grid already has.
+  const badgeAttribute = String(
+    getResponsiveValue(block.properties?.badgeAttribute, currentBreakpoint, '')
+  );
+  const badgeMap = String(
+    getResponsiveValue(block.properties?.badgeMap, currentBreakpoint, '')
+  );
+  const swatchMap = String(
+    getResponsiveValue(block.properties?.swatchMap, currentBreakpoint, '')
+  );
+  const lookups = React.useMemo<ListingValueLookups | undefined>(
+    () => parseListingLookups(badgeAttribute, badgeMap, swatchMap),
+    [badgeAttribute, badgeMap, swatchMap]
+  );
+  const listing = useListingContext(money, lookups);
+
+  const columnsDesktop = clampInt(
+    getResponsiveValue(block.properties?.columnsDesktop, currentBreakpoint, 4),
+    4,
+    2,
+    6
+  );
+  const columnsMobile = clampInt(
+    getResponsiveValue(block.properties?.columnsMobile, currentBreakpoint, 2),
+    2,
+    1,
+    3
+  );
+  // The grid a tablet actually wants — three across, where a phone wants two
+  // and a desktop wants four or six. Left unset it is the mobile count, which
+  // is what the band has shown since there was only one media query, so a grid
+  // that never authored it emits exactly the CSS it emitted before.
+  const columnsTabletRaw = block.properties?.columnsTablet;
+  const columnsTabletResolved =
+    columnsTabletRaw === undefined ||
+    columnsTabletRaw === null ||
+    columnsTabletRaw === ''
+      ? null
+      : Number(getResponsiveValue(columnsTabletRaw, currentBreakpoint, 0));
+  // 0 is the descriptor's "keep the mobile count" setting, and so is a value
+  // that is missing or unparseable — all three mean no tablet rule.
+  const columnsTablet =
+    columnsTabletResolved === null ||
+    !Number.isFinite(columnsTabletResolved) ||
+    columnsTabletResolved < 1
+      ? null
+      : clampInt(
+          getResponsiveValue(columnsTabletRaw, currentBreakpoint, columnsMobile),
+          columnsMobile,
+          1,
+          6
+        );
+  // 0 renders every product the listing returned, which is today's behaviour.
+  const limit = readCount(
+    getResponsiveValue(block.properties?.limit, currentBreakpoint, 0),
+    0
+  );
+  const showName = readToggle(
+    block.properties?.showName,
+    currentBreakpoint,
+    true
+  );
+  const nameLines = readCount(
+    getResponsiveValue(block.properties?.nameLines, currentBreakpoint, 0),
+    0
+  );
+  const imageRatioRaw = String(
+    getResponsiveValue(block.properties?.imageRatio, currentBreakpoint, 'auto')
+  );
+  const imageRatio = IMAGE_RATIOS.includes(imageRatioRaw)
+    ? imageRatioRaw
+    : 'auto';
+  const imageFit = String(
+    getResponsiveValue(block.properties?.imageFit, currentBreakpoint, 'cover')
+  );
+  const showPrice = readToggle(
+    block.properties?.showPrice,
+    currentBreakpoint,
+    true
+  );
+  const showRetailPrice = readToggle(
+    block.properties?.showRetailPrice,
+    currentBreakpoint,
+    true
+  );
+  const showDiscountBadge = readToggle(
+    block.properties?.showDiscountBadge,
+    currentBreakpoint,
+    false
+  );
+  const discountBadgeTemplate = String(
+    getResponsiveValue(
+      block.properties?.discountBadgeTemplate,
+      currentBreakpoint,
+      '-{percent}%'
+    )
+  );
+  const badgePosition = String(
+    getResponsiveValue(block.properties?.badgePosition, currentBreakpoint, 'inline')
+  );
+
+  const showDensitySwitcher = readToggle(
+    block.properties?.showDensitySwitcher,
+    currentBreakpoint,
+    false
+  );
+  const densityOptionsRaw = String(
+    getResponsiveValue(
+      block.properties?.densityOptions,
+      currentBreakpoint,
+      '1,2,4'
+    )
+  );
+  const densityStyle = String(
+    getResponsiveValue(block.properties?.densityStyle, currentBreakpoint, 'icon')
+  );
+  const densityPosition = String(
+    getResponsiveValue(
+      block.properties?.densityPosition,
+      currentBreakpoint,
+      'before'
+    )
+  );
+  const densityLabel = String(
+    getResponsiveValue(block.properties?.densityLabel, currentBreakpoint, '')
+  );
+  const densityAriaLabel = String(
+    getResponsiveValue(
+      block.properties?.densityAriaLabel,
+      currentBreakpoint,
+      'Products per row'
+    )
+  );
+  // Editor-only: a category with stock never renders its no-results layout, so
+  // without this the designer has nothing to select and arrange. Guarded by
+  // isDesigner at the use site, so it can never empty a storefront listing.
+  const previewEmptyState = readToggle(
+    block.properties?.previewEmptyState,
+    currentBreakpoint,
+    false
+  );
+  const densityOptions = React.useMemo(
+    () => parseDensityOptions(densityOptionsRaw),
+    [densityOptionsRaw]
+  );
+
+  // null until the shopper picks one, which is what keeps the server markup and
+  // the first client render identical.
+  const [chosenColumns, setChosenColumns] = React.useState<number | null>(null);
+  // false on the server and on the first client render, for the same reason.
+  const [isNarrowViewport, setIsNarrowViewport] = React.useState(false);
+  const densityKey = `${DENSITY_KEY_PREFIX}${block.id || 'grid'}`;
+  const hasSwitcher = showDensitySwitcher && densityOptions.length > 1;
+
+  React.useEffect(() => {
+    // Read after mount only: the server has no session storage, so deciding
+    // during render would hydrate as a mismatch. The designer always sees the
+    // authored count — a remembered choice there would look like a bug.
+    if (!hasSwitcher || isDesigner) return;
+
+    const stored = readStoredDensity(densityKey);
+    if (stored !== null && densityOptions.includes(stored)) {
+      setChosenColumns(stored);
+    }
+  }, [hasSwitcher, isDesigner, densityKey, densityOptions]);
+
+  React.useEffect(() => {
+    // A real phone gets its column count from the media query the block emits,
+    // never from currentBreakpoint — which is 'desktop' on the storefront no
+    // matter how narrow the viewport is. The switcher has to read the same
+    // cascade to mark the option the shopper is actually looking at, so it
+    // watches the identical cutoff, taken from the same constant the emitted
+    // media query is built from rather than retyped.
+    if (!hasSwitcher || typeof window.matchMedia !== 'function') return;
+
+    const query = window.matchMedia(`(max-width: ${DESKTOP_MIN_WIDTH - 1}px)`);
+    const sync = () => setIsNarrowViewport(query.matches);
+
+    sync();
+
+    // Safari below 14 only carries the deprecated listener pair.
+    if (typeof query.addEventListener === 'function') {
+      query.addEventListener('change', sync);
+      return () => query.removeEventListener('change', sync);
+    }
+
+    query.addListener(sync);
+    return () => query.removeListener(sync);
+  }, [hasSwitcher]);
+
+  const allProducts = listing?.products || [];
+  const products = limit > 0 ? allProducts.slice(0, limit) : allProducts;
+
+  // A designer who marked a child as the card layout gets that layout
+  // repeated per product; otherwise the built-in card renders unchanged.
+  const customCards = hasItemTemplate(block, currentBreakpoint) ? (
+    <ItemTemplateList
+      block={block}
+      items={products as unknown as Record<string, unknown>[]}
+      placeholderId={placeholderId}
+      sectionId={sectionId}
+      isDesigner={isDesigner}
+      selectedBlockId={selectedBlockId}
+      currentBreakpoint={currentBreakpoint}
+      designerPlaceholderCount={4}
+    />
+  ) : null;
+
+  const childProps = {
+    placeholderId,
+    sectionId,
+    isDesigner,
+    selectedBlockId,
+    currentBreakpoint
+  };
+
+  // "The listing answered with nothing" is not the same as "there is no
+  // listing here": a grid dropped on a page that never had one keeps rendering
+  // nothing rather than announcing an empty search.
+  const isEmptyListing = listing !== null && allProducts.length === 0;
+  const emptyStateChild =
+    (block.blocks || []).find(
+      (child) =>
+        readChildRole(child, currentBreakpoint) === EMPTY_STATE_ROLE &&
+        isChildRendered(child, isDesigner)
+    ) ?? null;
+
+  // The authored no-results page replaces the grid entirely — the density
+  // switcher and the cards have nothing to act on once the listing is empty.
+  if (
+    emptyStateChild &&
+    (isEmptyListing || (isDesigner && previewEmptyState))
+  ) {
+    return (
+      <div data-product-grid-empty="" {...partAttrs('empty')}>
+        <ThemeBlock
+          block={emptyStateChild}
+          isSelected={selectedBlockId === emptyStateChild.id}
+          {...childProps}
+        />
+      </div>
+    );
+  }
+
+  const currentPage = listing?.pagination.currentPage ?? 1;
+  // A campaign tile is authored for the first page unless the designer says
+  // otherwise; repeating it every page is the exception, not the default.
+  const placedInsertions = placeInsertions(
+    collectInsertions(block, currentBreakpoint, isDesigner).filter(
+      (insertion) => insertion.everyPage || currentPage === 1
+    ),
+    products.length
+  );
+
+  // A grid with no products still draws its tiles when the listing itself came
+  // back empty and nothing was authored to replace it — the campaign is the
+  // only thing left to show. On the canvas they always draw, or a designer
+  // could not place one against a page with no live data.
+  const drawsInsertionsOnly =
+    placedInsertions.length > 0 && (isDesigner || isEmptyListing);
+
+  // With a custom card the designer still needs something to arrange, so the
+  // template draws its own placeholder rows rather than the "no data" notice.
+  if (products.length === 0 && !customCards && !drawsInsertionsOnly) {
+    return isDesigner ? (
+      <div data-product-grid="" style={listingPlaceholderStyle}>
+        Product grid (no listing data)
+      </div>
+    ) : null;
+  }
+
+  // Column counts are block PROPERTIES, and properties are resolved with the
+  // designer breakpoint only — on the live storefront currentBreakpoint is
+  // always 'desktop'. A scoped rule with the same 1023px cutoff the theme CSS
+  // generator uses keeps real mobile viewports in sync with the editor.
+  const gridId = String(block.id || 'grid').replace(/[^a-zA-Z0-9_-]/g, '');
+  const baseColumns =
+    currentBreakpoint === 'tablet'
+      ? columnsTablet ?? columnsMobile
+      : currentBreakpoint === 'mobile'
+      ? columnsMobile
+      : columnsDesktop;
+
+  const isOverlayBadge = badgePosition === 'overlay';
+  const nameStyle: React.CSSProperties =
+    nameLines > 0
+      ? {
+          fontSize: 'inherit',
+          display: '-webkit-box',
+          WebkitBoxOrient: 'vertical',
+          WebkitLineClamp: nameLines,
+          overflow: 'hidden'
+        }
+      : { fontSize: 'inherit' };
+
+  // The three rules below in the order the browser applies them: the authored
+  // base, the mobile override, then an explicit choice. Deriving the mark from
+  // baseColumns alone highlighted the desktop count on every phone.
+  const activeColumns =
+    chosenColumns ?? (isNarrowViewport ? columnsMobile : baseColumns);
+
+  const densitySwitcher = hasSwitcher ? (
+    <div
+      data-product-grid-density=""
+      {...partAttrs('density')}
+      role="group"
+      aria-label={densityAriaLabel}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--product-grid-density-gap, 8px)',
+        marginBottom: densityPosition === 'after' ? undefined : '12px',
+        marginTop: densityPosition === 'after' ? '12px' : undefined
+      }}
+    >
+      {densityLabel && (
+        <span
+          data-product-grid-density-label=""
+          {...partAttrs('density-label')}
+        >
+          {densityLabel}
+        </span>
+      )}
+      {densityOptions.map((count) => {
+        const isActive = count === activeColumns;
+
+        return (
+          <button
+            key={count}
+            type="button"
+            data-product-grid-density-option={String(count)}
+            {...partAttrs('density-option', { selected: isActive })}
+            aria-pressed={isActive}
+            aria-label={String(count)}
+            onClick={() => {
+              setChosenColumns(count);
+              // Writing the author's canvas experiments into their own session
+              // would follow them onto the storefront.
+              if (!isDesigner) writeStoredDensity(densityKey, count);
+            }}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              background: 'none',
+              border: 'none',
+              padding: '4px',
+              cursor: 'pointer',
+              color: 'inherit',
+              font: 'inherit',
+              opacity: isActive ? 1 : 0.45
+            }}
+          >
+            {densityStyle === 'number' ? count : <DensityGlyph columns={count} />}
+          </button>
+        );
+      })}
+    </div>
+  ) : null;
+
+  const insertionTiles = placedInsertions.map((insertion, index) => (
+    <div
+      key={`insert-${insertion.block.id || index}`}
+      // Indexed rather than keyed by block id: the stylesheet above addresses
+      // the same index, and a block id is not guaranteed to be selector-safe.
+      data-product-grid-insert={String(index)}
+      // The index restarts at 0 on every page, so the page is what makes the
+      // pair unique once Load More has appended one grid's pages into another.
+      data-product-grid-page={String(currentPage)}
+      {...partAttrs('insert')}
+      // A grid container with a single child stretches it over the whole
+      // spanned area, which is what a two-by-two campaign panel needs; a plain
+      // block wrapper would leave the panel its content height.
+      style={{ display: 'grid', minWidth: 0 }}
+    >
+      <ThemeBlock
+        block={insertion.block}
+        isSelected={selectedBlockId === insertion.block.id}
+        {...childProps}
+      />
+    </div>
+  ));
+
+  const renderProductCard = (product: ListingProduct) => {
+    // Taken from the row, which derived it from the raw amounts: reading
+    // it back out of the formatted string breaks the moment a brand
+    // formats money its own way ("1.599 TL" parses as 1.599).
+    const percent = product.discountPercent ?? 0;
+    const badgeLabel = discountBadgeTemplate.includes('{percent}')
+      ? discountBadgeTemplate.replace('{percent}', String(percent))
+      : discountBadgeTemplate;
+
+    return (
+      <NextLink
+        key={product.key}
+        href={product.url}
+        data-product-card=""
+        {...partAttrs('card')}
+        // Navigating inside the designer iframe would drop the author out of
+        // the page they are editing, so cards are inert there.
+        onClick={(event) => {
+          if (isDesigner) event.preventDefault();
+        }}
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: '8px',
+          color: 'inherit',
+          textDecoration: 'none',
+          // Only when a badge is asked to float over the image: a positioned
+          // ancestor is what makes that possible, and creating one by
+          // default would change every published card's containing block.
+          ...(isOverlayBadge && showDiscountBadge
+            ? { position: 'relative' }
+            : null)
+        }}
+      >
+        {product.image ? (
+          <img
+            src={product.image}
+            alt={product.name}
+            loading="lazy"
+            data-product-card-image=""
+            {...partAttrs('image')}
+            style={{
+              width: '100%',
+              height: 'auto',
+              display: 'block',
+              objectFit: imageFit as React.CSSProperties['objectFit'],
+              ...(imageRatio !== 'auto' ? { aspectRatio: imageRatio } : null)
+            }}
+          />
+        ) : (
+          <span
+            data-product-card-image=""
+            {...partAttrs('image', { empty: true })}
+            style={{
+              display: 'block',
+              width: '100%',
+              aspectRatio: imageRatio !== 'auto' ? imageRatio : '3 / 4',
+              background: '#f1f5f9'
+            }}
+          />
+        )}
+
+        {showDiscountBadge && product.hasDiscount && (
+          <span
+            data-product-card-badge=""
+            {...partAttrs('badge')}
+            style={{
+              alignSelf: 'flex-start',
+              padding: '2px 6px',
+              fontSize: '0.8em',
+              lineHeight: 1.4,
+              color: '#ffffff',
+              background: '#111827',
+              borderRadius: '2px',
+              ...(isOverlayBadge
+                ? { position: 'absolute', top: '8px', left: '8px' }
+                : null)
+            }}
+          >
+            {badgeLabel}
+          </span>
+        )}
+
+        {showName && (
+          <span
+            data-product-card-name=""
+            {...partAttrs('name')}
+            style={nameStyle}
+          >
+            {product.name}
+          </span>
+        )}
+
+        {showPrice && product.price && (
+          <span
+            data-product-card-price=""
+            {...partAttrs('price')}
+            style={{ display: 'flex', alignItems: 'center', gap: '8px' }}
+          >
+            {showRetailPrice && product.hasDiscount && product.retailPrice && (
+              <s
+                data-product-card-retail-price=""
+                {...partAttrs('list-price')}
+                style={{ opacity: 0.6, fontSize: '0.9em' }}
+              >
+                {product.retailPrice}
+              </s>
+            )}
+            <span {...partAttrs('sale-price')}>{product.price}</span>
+          </span>
+        )}
+      </NextLink>
+    );
+  };
+
+  const builtInCards = products.map(renderProductCard);
+
+  // With nothing authored this is the exact expression the block always used,
+  // element for element and key for key; the other two branches cannot be
+  // reached until a designer marks a child as a tile.
+  const gridChildren =
+    insertionTiles.length === 0 ? (
+      customCards ?? builtInCards
+    ) : customCards ? (
+      <>
+        {customCards}
+        {insertionTiles}
+      </>
+    ) : (
+      interleaveCells(builtInCards, insertionTiles, placedInsertions)
+    );
+
+  const grid = (
+    <div
+      data-product-grid=""
+      data-product-grid-id={gridId}
+      {...partAttrs('list')}
+      style={{ display: 'grid', gap: 'var(--product-grid-gap, 16px)' }}
+    >
+      <style>
+        {`[data-product-grid-id="${gridId}"]{grid-template-columns:repeat(${baseColumns},minmax(0,1fr));}` +
+          buildInsertionRules(gridId, placedInsertions, baseColumns, currentPage) +
+          `${MOBILE_MEDIA_QUERY_COMPACT}{[data-product-grid-id="${gridId}"]{grid-template-columns:repeat(${columnsMobile},minmax(0,1fr));}` +
+          // Inside the same query as the mobile template, so a tile is measured
+          // against the column count it actually sits in.
+          buildInsertionRules(
+            gridId,
+            placedInsertions,
+            columnsMobile,
+            currentPage
+          ) +
+          `}` +
+          // After the mobile query and only when a tablet count was authored,
+          // so a grid without one emits the two rules it always emitted.
+          (columnsTablet !== null
+            ? `${TABLET_MEDIA_QUERY_COMPACT}{[data-product-grid-id="${gridId}"]{grid-template-columns:repeat(${columnsTablet},minmax(0,1fr));}` +
+              buildInsertionRules(
+                gridId,
+                placedInsertions,
+                columnsTablet,
+                currentPage
+              ) +
+              `}`
+            : '') +
+          // Last and unconditional, so an explicit choice outranks both the
+          // authored count and the mobile override above it.
+          (chosenColumns !== null
+            ? `[data-product-grid-id="${gridId}"]{grid-template-columns:repeat(${chosenColumns},minmax(0,1fr));}` +
+              buildInsertionRules(
+                gridId,
+                placedInsertions,
+                chosenColumns,
+                currentPage
+              )
+            : '')}
+      </style>
+
+      {/* A designer who marked a child as the row layout gets their own card
+          repeated per product; otherwise the built-in card above renders. */}
+      {gridChildren}
+    </div>
+  );
+
+  // Without the switcher the block returns exactly the element it always has;
+  // with it, a fragment adds the toolbar without wrapping the grid in a node
+  // that would break the styles a brand already targets.
+  if (!densitySwitcher) return grid;
+
+  return (
+    <>
+      {densityPosition === 'after' ? null : densitySwitcher}
+      {grid}
+      {densityPosition === 'after' ? densitySwitcher : null}
+    </>
+  );
+};
+
+export default ProductGridBlock;