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

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

@@ -0,0 +1,131 @@
+import type { Block } from '../theme-block';
+import { getResponsiveValue } from '../utils';
+import type { ThemeProduct } from './product-block-utils';
+
+/**
+ * The marker and lookup for custom row layouts, kept free of React so a
+ * renderer (or a test) can ask "did the designer author their own row?"
+ * without pulling the whole block tree in.
+ */
+export const ITEM_TEMPLATE_ROLE = 'item-template';
+
+const readRole = (block: Block, currentBreakpoint = 'desktop'): string =>
+  String(
+    getResponsiveValue(block.properties?.role, currentBreakpoint, '') ?? ''
+  );
+
+/** The child a designer marked as the row layout, if any. */
+export const findItemTemplate = (
+  block: Block,
+  currentBreakpoint = 'desktop'
+): Block | null =>
+  (block.blocks || []).find(
+    child => readRole(child, currentBreakpoint) === ITEM_TEMPLATE_ROLE
+  ) ?? null;
+
+export const hasItemTemplate = (
+  block: Block,
+  currentBreakpoint = 'desktop'
+): boolean => findItemTemplate(block, currentBreakpoint) !== null;
+
+/**
+ * The lists whose rows ARE products.
+ *
+ * Which rows carry a product has to be declared per list, never sniffed off
+ * the row: an address row and a coupon row both carry `pk` and a `name`, and a
+ * heuristic that accepted them would point a wishlist toggle at an address id.
+ * A list not named here keeps behaving exactly as it does today — the blocks
+ * inside its rows go on reading the page's product.
+ */
+const PRODUCT_ITEM_LIST_TYPES = new Set([
+  'product-grid',
+  'favourites-grid',
+  'product-recommendations'
+]);
+
+export const publishesProductItems = (blockType?: string): boolean =>
+  typeof blockType === 'string' && PRODUCT_ITEM_LIST_TYPES.has(blockType);
+
+/**
+ * Where a row keeps the id of the product it shows. `productPk` is read first
+ * because a favourites row carries BOTH: `pk` is the favourite entry's own id
+ * (what removing it needs) and `productPk` is the product behind it. Reading
+ * `pk` there would favourite a wishlist entry id.
+ */
+const PRODUCT_PK_FIELDS = ['productPk', 'pk'];
+
+const readProductPk = (
+  item: Record<string, unknown>
+): number | undefined => {
+  for (const field of PRODUCT_PK_FIELDS) {
+    const value = item[field];
+    if (value === undefined || value === null || value === '') continue;
+
+    const numeric = Number(value);
+    // Commerce ids are positive integers; a row that key-fell-back to
+    // "product-3" must not resolve to a pk at all.
+    if (Number.isFinite(numeric) && numeric > 0) return numeric;
+  }
+
+  return undefined;
+};
+
+/**
+ * A row seen as the ambient product, or null when this list publishes no
+ * products or the row is one of the empty placeholders the designer draws
+ * against. `pk` is rewritten to the PRODUCT's id so a mutation started from
+ * inside the row (wishlist, add to basket) addresses the right thing; the
+ * row itself is left untouched, so `item.*` bindings still resolve as before.
+ */
+export const resolveItemProduct = (
+  blockType: string | undefined,
+  item: Record<string, unknown> | null | undefined
+): ThemeProduct | null => {
+  if (!publishesProductItems(blockType)) return null;
+  if (!item || Object.keys(item).length === 0) return null;
+
+  const pk = readProductPk(item);
+
+  // No id, no scope: a wishlist toggle or an add-to-basket started from this
+  // row would have nothing to address, and claiming the scope would only stop
+  // the block reading the page product it reads today.
+  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.
+ *
+ * Without it a designer laying out a card sees "Add to cart (no product)" and
+ * "Favourite button (no product)" boxes where the controls belong — different
+ * size, different weight — so the card cannot be judged as a card. The sample
+ * is designer-only and never reaches a storefront; mutations stay blocked by
+ * the `isDesigner` guard each block already has, and the pk is deliberately
+ * not a real one so nothing can be addressed with it.
+ */
+export const DESIGNER_SAMPLE_PRODUCT: ThemeProduct = {
+  pk: -1,
+  name: 'Sample product',
+  title: 'Sample product',
+  price: 499,
+  retailPrice: 799,
+  in_stock: true,
+  stock: 12,
+  // Enough shape for the optional pieces to draw themselves: a size row on a
+  // quick-add card, and the price-history caption. Without them a designer
+  // switches the feature on and the canvas answers with a hint instead of the
+  // element they are trying to place.
+  price_extra_field: { previous_price: 549 },
+  variants: [
+    {
+      attribute_key: 'size',
+      attribute_name: 'Size',
+      options: [
+        { label: 'S', value: 's', in_stock: true, is_selectable: true },
+        { label: 'M', value: 'm', in_stock: true, is_selectable: true, is_selected: true },
+        { label: 'L', value: 'l', in_stock: false, is_selectable: false }
+      ]
+    }
+  ]
+} as ThemeProduct;

package/src/blocks/item-template.tsx

@@ -0,0 +1,164 @@
+'use client';
+
+import React from 'react';
+import ThemeBlock, { Block } from '../theme-block';
+import {
+  buildIteratorBlock,
+  sliceIteratorItems
+} from '../utils/iterator-utils';
+import {
+  DESIGNER_SAMPLE_PRODUCT,
+  findItemTemplate,
+  ITEM_TEMPLATE_ROLE,
+  publishesProductItems,
+  resolveItemProduct
+} from './item-template-utils';
+import { ThemeItemScopeProvider } from './product-block-utils';
+
+export {
+  findItemTemplate,
+  hasItemTemplate,
+  ITEM_TEMPLATE_ROLE,
+  publishesProductItems,
+  resolveItemProduct
+} from './item-template-utils';
+
+/**
+ * Custom item layouts for functional lists.
+ *
+ * Every functional block that shows a list — the product grid, basket rows,
+ * order rows, address cards, store results — used to draw its row in TSX.
+ * A brand could change spacing around it and nothing inside it: no reordering
+ * the price above the title, no extra field, no removing an element. The
+ * editor's repeat mechanism existed but was offered for group blocks only.
+ *
+ * A list block can now carry one child marked as its item template. When it is
+ * there, the block hands its own data to the same iterator machinery the group
+ * block uses, and the designer's layout is repeated once per item with
+ * `item.*` bindings resolved. When it is not, the block draws its built-in row
+ * exactly as before — which is what keeps every published composition working.
+ *
+ * A PRODUCT row is also a SCOPE. Blocks like the favourite toggle or
+ * add-to-cart used to read the product off the page context, which on a
+ * listing is nothing and on a PDP is the wrong product for a recommendation
+ * card. Rows of a list that publishes products are wrapped in the item scope,
+ * so those blocks act on the row's own product; every other list is left
+ * alone, because its rows are not products and its blocks read the page.
+ */
+
+interface ItemTemplateListProps {
+  /** The functional block that owns the list. */
+  block: Block;
+  /** The rows to draw, already normalised by the block. */
+  items: Record<string, unknown>[];
+  placeholderId: string;
+  sectionId: string;
+  isDesigner?: boolean;
+  isSelected?: boolean;
+  selectedBlockId?: string | null;
+  currentBreakpoint?: string;
+  /**
+   * How many rows to draw in the editor when the page has no live data —
+   * an empty grid is impossible to design against.
+   */
+  designerPlaceholderCount?: number;
+}
+
+/**
+ * Renders the designer's row layout once per item. Returns null when there is
+ * no template, so a caller can fall back to its own markup with a plain
+ * `?? builtInRows`.
+ */
+export const ItemTemplateList = ({
+  block,
+  items,
+  placeholderId,
+  sectionId,
+  isDesigner = false,
+  selectedBlockId = null,
+  currentBreakpoint = 'desktop',
+  designerPlaceholderCount = 3
+}: ItemTemplateListProps): React.ReactElement | null => {
+  const template = findItemTemplate(block, currentBreakpoint);
+  if (!template) return null;
+
+  const rows =
+    items.length > 0
+      ? items
+      : isDesigner
+      ? Array.from({ length: designerPlaceholderCount }, () => ({}))
+      : [];
+
+  if (rows.length === 0) return null;
+
+  // The iterator is given the rows directly: a functional block fetched them
+  // itself (RTK, page context), they are not on the section's data source.
+  // The iterator repeats `blocks[0]` of whatever it is given, so the template
+  // is wrapped rather than passed directly — passing it directly would repeat
+  // only its first child and drop the rest of the card.
+  const expanded = buildIteratorBlock({
+    iteratorBlock: {
+      ...block,
+      id: `${block.id}-items`,
+      isIterator: true,
+      blocks: [template]
+    },
+    items: rows,
+    isDesigner
+  });
+
+  const clones = expanded.blocks || [];
+  // Only lists whose rows ARE products open a scope. An attribute row or a
+  // gallery thumbnail row must keep falling through to the page's product:
+  // those templates live on a PDP, and a scope there — even an empty one —
+  // would silence blocks that render correctly today.
+  const scopesProducts = publishesProductItems(block.type);
+  // The same slice the iterator applied, so clone N is handed the row it
+  // was built from rather than row N.
+  const scopedRows = scopesProducts
+    ? sliceIteratorItems(block, rows).items
+    : rows;
+
+  return (
+    <>
+      {clones.map((clone, index) => {
+        const key = clone.id || `${template.id}-item-${index}`;
+        const row = (
+          <ThemeBlock
+            // Keyed here so the non-scoped branch is the element it always
+            // was: wrapping it in anything, even a fragment, would change the
+            // element type at this position and remount every existing row.
+            key={key}
+            block={clone}
+            placeholderId={placeholderId}
+            sectionId={sectionId}
+            isDesigner={isDesigner}
+            isSelected={selectedBlockId === clone.id}
+            selectedBlockId={selectedBlockId}
+            currentBreakpoint={currentBreakpoint}
+          />
+        );
+
+        if (!scopesProducts) return row;
+
+        const scoped = resolveItemProduct(block.type, scopedRows[index]);
+
+        // Context only — the provider renders no element, so the markup a
+        // published row produces is unchanged.
+        return (
+          <ThemeItemScopeProvider
+            key={key}
+            product={
+              scoped ?? (isDesigner ? DESIGNER_SAMPLE_PRODUCT : null)
+            }
+          >
+            {row}
+          </ThemeItemScopeProvider>
+        );
+      })}
+    </>
+  );
+};
+
+/** Alias kept for call sites that read better as a marker than a role. */
+export const ITEM_TEMPLATE_MARKER = ITEM_TEMPLATE_ROLE;

package/src/blocks/listing-breadcrumb-block.tsx

@@ -0,0 +1,175 @@
+'use client';
+
+import React from 'react';
+import NextLink from 'next/link';
+import { getResponsiveValue, partAttrs } from '../utils';
+import { BlockRendererProps } from './block-renderer-registry';
+import {
+  listingPlaceholderStyle,
+  readToggle,
+  useListingContext
+} from './listing-context';
+
+interface BreadcrumbEntry {
+  label: string;
+  url: string;
+  /** A stand-in for the crumbs dropped by the max-items cap. */
+  collapsed?: boolean;
+}
+
+/**
+ * Functional listing block: the breadcrumb trail. Trail CONTENT is
+ * commerce-driven (the breadcrumb payload resolved server side); the editor
+ * owns the separator, the optional home entry, how long the trail may get
+ * and styling.
+ *
+ * Parts: list, item, link, current, separator, ellipsis.
+ * Properties: separator, showHome, homeLabel, homeHref, ariaLabel, maxItems,
+ * collapseLabel, maxLabelLength, ellipsis.
+ */
+const ListingBreadcrumbBlock = ({
+  block,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const listing = useListingContext();
+
+  const separator = String(
+    getResponsiveValue(block.properties?.separator, currentBreakpoint, '/')
+  );
+  const showHome = readToggle(
+    block.properties?.showHome,
+    currentBreakpoint,
+    true
+  );
+  const homeLabel = String(
+    getResponsiveValue(block.properties?.homeLabel, currentBreakpoint, 'Home')
+  );
+  const homeHref = String(
+    getResponsiveValue(block.properties?.homeHref, currentBreakpoint, '/')
+  );
+  const ariaLabel = String(
+    getResponsiveValue(block.properties?.ariaLabel, currentBreakpoint, 'Breadcrumb')
+  );
+  const maxItemsRaw = Math.round(
+    Number(getResponsiveValue(block.properties?.maxItems, currentBreakpoint, 0))
+  );
+  // 0 keeps the whole trail, which is what every published composition shows.
+  const maxItems =
+    Number.isFinite(maxItemsRaw) && maxItemsRaw >= 2 ? maxItemsRaw : 0;
+  const collapseLabel = String(
+    getResponsiveValue(block.properties?.collapseLabel, currentBreakpoint, '…')
+  );
+  const maxLabelLengthRaw = Math.round(
+    Number(
+      getResponsiveValue(block.properties?.maxLabelLength, currentBreakpoint, 0)
+    )
+  );
+  const maxLabelLength =
+    Number.isFinite(maxLabelLengthRaw) && maxLabelLengthRaw > 0
+      ? maxLabelLengthRaw
+      : 0;
+  const ellipsis = String(
+    getResponsiveValue(block.properties?.ellipsis, currentBreakpoint, '…')
+  );
+
+  const crumbs = listing?.breadcrumbs || [];
+
+  if (crumbs.length === 0) {
+    return isDesigner ? (
+      <div data-listing-breadcrumb="" style={listingPlaceholderStyle}>
+        Breadcrumb (no trail data)
+      </div>
+    ) : null;
+  }
+
+  const fullTrail: BreadcrumbEntry[] = showHome
+    ? [{ label: homeLabel, url: homeHref }].concat(crumbs)
+    : crumbs.slice();
+
+  // A long trail is folded from the middle: the root and the deepest crumbs
+  // are the ones a shopper navigates with.
+  const items: BreadcrumbEntry[] =
+    maxItems > 0 && fullTrail.length > maxItems
+      ? [
+          fullTrail[0],
+          { label: collapseLabel, url: '', collapsed: true },
+          ...fullTrail.slice(fullTrail.length - (maxItems - 1))
+        ]
+      : fullTrail;
+
+  const shorten = (label: string) =>
+    maxLabelLength > 0 && label.length > maxLabelLength
+      ? `${label.slice(0, maxLabelLength).trimEnd()}${ellipsis}`
+      : label;
+
+  return (
+    <nav data-listing-breadcrumb="" aria-label={ariaLabel}>
+      <ol
+        {...partAttrs('list')}
+        style={{
+          listStyle: 'none',
+          margin: 0,
+          padding: 0,
+          display: 'flex',
+          alignItems: 'center',
+          flexWrap: 'wrap',
+          gap: 'var(--listing-breadcrumb-gap, 8px)'
+        }}
+      >
+        {items.map((item, index) => {
+          const isLast = index === items.length - 1;
+          const label = item.collapsed ? item.label : shorten(item.label);
+
+          return (
+            <li
+              key={`${item.label}-${index}`}
+              data-breadcrumb-item={isLast ? 'current' : 'link'}
+              {...partAttrs('item', { selected: isLast })}
+              style={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}
+            >
+              {item.collapsed ? (
+                <span data-breadcrumb-collapsed="" {...partAttrs('ellipsis')}>
+                  {label}
+                </span>
+              ) : isLast || !item.url ? (
+                <span
+                  aria-current={isLast ? 'page' : undefined}
+                  {...partAttrs(isLast ? 'current' : 'link', {
+                    selected: isLast
+                  })}
+                >
+                  {label}
+                </span>
+              ) : (
+                <NextLink
+                  href={item.url}
+                  {...partAttrs('link')}
+                  // Navigating inside the designer iframe would drop the author
+                  // out of the page they are editing, so crumbs are inert there.
+                  onClick={(event) => {
+                    if (isDesigner) event.preventDefault();
+                  }}
+                  style={{ color: 'inherit', textDecoration: 'none' }}
+                >
+                  {label}
+                </NextLink>
+              )}
+              {!isLast && (
+                <span
+                  data-breadcrumb-separator=""
+                  aria-hidden="true"
+                  {...partAttrs('separator')}
+                >
+                  {separator}
+                </span>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </nav>
+  );
+};
+
+export default ListingBreadcrumbBlock;