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

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

@@ -0,0 +1,923 @@
+'use client';
+
+import React from 'react';
+import NextLink from 'next/link';
+import { usePathname, useSearchParams } from 'next/navigation';
+import { useLocalization } from '@akinon/next/hooks';
+import { getResponsiveValue, partAttrs, resolveOption } from '../utils';
+import { hasItemTemplate, ItemTemplateList } from './item-template';
+import { BlockRendererProps } from './block-renderer-registry';
+import {
+  buildListingHref,
+  listingPlaceholderStyle,
+  readToggle,
+  useListingContext
+} from './listing-context';
+
+const linkStyle = (isCurrent: boolean): React.CSSProperties => ({
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  minWidth: '32px',
+  padding: '4px 8px',
+  color: 'inherit',
+  textDecoration: 'none',
+  border: '1px solid currentColor',
+  borderRadius: 'inherit',
+  opacity: isCurrent ? 1 : 0.7,
+  fontWeight: isCurrent ? 600 : 400
+});
+
+type AppendTrigger = 'button' | 'scroll';
+const APPEND_TRIGGERS: AppendTrigger[] = ['button', 'scroll'];
+
+type StatusPosition = 'before' | 'after';
+const STATUS_POSITIONS: StatusPosition[] = ['before', 'after'];
+
+/**
+ * A brand can type any selector into "List Container", so every lookup is
+ * wrapped: an unfinished selector throws a SyntaxError that would otherwise
+ * take the whole listing down while they are still typing it.
+ */
+const safeQuery = (scope: ParentNode, selector: string): Element | null => {
+  try {
+    return scope.querySelector(selector);
+  } catch {
+    return null;
+  }
+};
+
+const safeQueryAll = (scope: ParentNode, selector: string): Element[] => {
+  try {
+    return Array.from(scope.querySelectorAll(selector));
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * The list this pagination belongs to: the nearest ancestor that contains a
+ * match wins, so a page carrying two listings appends into the one the block
+ * actually sits under rather than into whichever grid happens to be first in
+ * the document.
+ */
+const findAppendTarget = (
+  from: Element | null,
+  selector: string
+): Element | null => {
+  let scope: Element | null = from ? from.parentElement : null;
+
+  while (scope) {
+    const match = safeQuery(scope, selector);
+    if (match) return match;
+    scope = scope.parentElement;
+  }
+
+  return safeQuery(document, selector);
+};
+
+/** Which of the page's lists the target is, so the fetched page is read the same way. */
+const indexOfTarget = (target: Element, selector: string): number => {
+  const index = safeQueryAll(document, selector).indexOf(target);
+  return index < 0 ? 0 : index;
+};
+
+/**
+ * What may cross from a fetched page into the live document.
+ *
+ * An allowlist, not a skip list. A skip list only ever excludes what somebody
+ * thought of, and it is checked one level deep while `importNode(node, true)`
+ * copies the entire subtree: a `<script>` two levels down inside a card rode
+ * straight through. That script is cloned out of a `DOMParser` document, where
+ * scripting is off and it therefore never started, so it RUNS the moment it is
+ * inserted here. A nested `<style>` is the same problem the top level always
+ * had — a lottie, an announcement bar or a recommendation strip inside a card
+ * emits one, and rules re-declared after the live ones outrank them and undo
+ * the shopper's density choice.
+ *
+ * Everything below is inert: it draws, it does not execute and it does not
+ * pull in a document of its own. What is absent is as much the point — script,
+ * style, link, template, iframe, object, embed, noscript, slot, and anything a
+ * brand invented, since a custom element runs a constructor on upgrade.
+ */
+const GRAFT_ALLOWED_TAGS = new Set([
+  // Flow and text.
+  'a', 'abbr', 'address', 'article', 'aside', 'b', 'bdi', 'bdo', 'blockquote',
+  'br', 'caption', 'cite', 'code', 'col', 'colgroup', 'data', 'dd', 'del',
+  'details', 'dfn', 'div', 'dl', 'dt', 'em', 'figcaption', 'figure', 'footer',
+  'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hgroup', 'hr', 'i', 'ins',
+  'kbd', 'li', 'main', 'mark', 'nav', 'ol', 'p', 'pre', 'q', 'rp', 'rt',
+  'ruby', 's', 'samp', 'section', 'small', 'span', 'strong', 'sub', 'summary',
+  'sup', 'table', 'tbody', 'td', 'tfoot', 'th', 'thead', 'time', 'tr', 'u',
+  'ul', 'var', 'wbr',
+  // Media. The card's image is the whole point of grafting the row at all.
+  'audio', 'canvas', 'img', 'picture', 'source', 'track', 'video',
+  // Controls a card can draw. They arrive inert whatever happens — React owns
+  // none of this DOM — but dropping them would leave an appended card looking
+  // unlike the one directly above it.
+  'button', 'fieldset', 'form', 'input', 'label', 'legend', 'meter',
+  'optgroup', 'option', 'output', 'progress', 'select', 'textarea',
+  // SVG: icons, badges, ratings. Lower-cased on both sides, so `clipPath` and
+  // `linearGradient` are compared the same way an HTML tag name is.
+  'circle', 'clippath', 'defs', 'desc', 'ellipse', 'feblend', 'fecolormatrix',
+  'fecomposite', 'fedropshadow', 'feflood', 'fegaussianblur', 'femerge',
+  'femergenode', 'feoffset', 'filter', 'g', 'image', 'line', 'lineargradient',
+  'marker', 'mask', 'path', 'pattern', 'polygon', 'polyline',
+  'radialgradient', 'rect', 'stop', 'svg', 'symbol', 'text', 'textpath',
+  'title', 'tspan', 'use'
+]);
+
+const SCRIPT_SCHEME = /^(?:javascript|vbscript):/;
+
+/**
+ * Browsers strip whitespace and control characters while parsing a url, so a
+ * tab wedged into "javascript:" still resolves to a live handler; the value
+ * is normalised the same way before it is judged.
+ */
+const isScriptUrl = (value: string): boolean =>
+  SCRIPT_SCHEME.test(value.replace(/[\u0000-\u0020]/g, '').toLowerCase());
+
+/**
+ * Attributes carrying text a shopper reads rather than something the browser
+ * resolves.
+ *
+ * "JavaScript: The Good Parts" is a product a bookshop really sells, and it
+ * normalises to a script scheme: judging EVERY attribute took the `alt` off
+ * that card — the only description a screen reader has for it — and took it on
+ * the appended page only, so the same product read differently above and below
+ * the fold. Nothing named here is ever fetched, navigated or executed, so no
+ * scheme can act from inside one. Everything not named here is still judged,
+ * which keeps this deny-by-default: an attribute nobody thought of is scrubbed,
+ * and that is the property that caught the script url in the first place.
+ */
+const TEXT_ONLY_ATTRIBUTES = new Set(['alt', 'title', 'placeholder']);
+
+const isTextOnlyAttribute = (name: string): boolean =>
+  TEXT_ONLY_ATTRIBUTES.has(name) || name.startsWith('aria-');
+
+/**
+ * Strips what executes out of a subtree while it is still in the inert parsed
+ * document, so the clone that reaches the live DOM never carried it.
+ */
+const sanitizeGraft = (element: Element) => {
+  Array.from(element.attributes).forEach((attribute) => {
+    const name = attribute.name.toLowerCase();
+    // `on*` is a handler; `is` upgrades a plain tag into a custom element and
+    // runs its constructor; a `javascript:` url is one click or one load from
+    // the same thing.
+    if (
+      name.startsWith('on') ||
+      name === 'is' ||
+      (!isTextOnlyAttribute(name) && isScriptUrl(attribute.value))
+    ) {
+      element.removeAttribute(attribute.name);
+    }
+  });
+
+  Array.from(element.children).forEach((child) => {
+    if (GRAFT_ALLOWED_TAGS.has(child.tagName.toLowerCase())) {
+      sanitizeGraft(child);
+      return;
+    }
+
+    child.remove();
+  });
+};
+
+/**
+ * Reads the rows of page N out of that page's own server response.
+ *
+ * Returns null when the response carried no list at all (a redirect, an error
+ * page, a login wall) — that is a failure the shopper has to be told about.
+ * An empty array means the page rendered but held no rows, which is the end of
+ * the list, not an error.
+ */
+const extractAppendNodes = (
+  html: string,
+  selector: string,
+  targetIndex: number
+): Element[] | null => {
+  const parsed = new DOMParser().parseFromString(html, 'text/html');
+  const matches = safeQueryAll(parsed, selector);
+  const source = matches[targetIndex] || matches[0];
+
+  if (!source) return null;
+
+  return Array.from(source.children)
+    .filter((node) => GRAFT_ALLOWED_TAGS.has(node.tagName.toLowerCase()))
+    .map((node) => {
+      sanitizeGraft(node);
+      return node;
+    });
+};
+
+/**
+ * How many of the grafted cells are products.
+ *
+ * A grid cell is not always one: a merchandising tile is a first-class child
+ * of the grid and marks itself as such. Counting NODES put "showing 5 of 6"
+ * under four cards and let {to} run past {total} — precisely what the readout
+ * was built to stop doing. A list that emits no tiles counts every node, which
+ * is what it always did.
+ */
+const countProducts = (nodes: Element[]): number =>
+  nodes.filter((node) => !node.hasAttribute('data-product-grid-insert')).length;
+
+/**
+ * Next patches `history.replaceState`, so this also re-syncs `useSearchParams`
+ * for every block on the page without triggering a navigation.
+ */
+const replaceListingUrl = (href: string) => {
+  try {
+    window.history.replaceState(null, '', href);
+  } catch {
+    // A blocked history call only costs the deep link, never the products.
+  }
+};
+
+const fillTemplate = (
+  template: string,
+  values: Record<string, string>
+): string =>
+  template.replace(
+    /\{(shown|total|from|to|page|pages)\}/g,
+    (match, key: string) => (key in values ? values[key] : match)
+  );
+
+/**
+ * Functional listing block: pagination. Page counts are commerce-driven (the
+ * `pagination` payload of the category API); the editor owns the mode, how
+ * many page links are shown, which affordances appear and the labels.
+ *
+ * APPEND ('loadmore' + Append In Place, off by default). The first page is
+ * still whatever the server rendered — a crawler and a cold visit see products
+ * with no javascript at all, and the "load more" anchor is still a real link
+ * to page N+1, so the whole listing stays reachable. Append is layered on top
+ * of that: the click is intercepted only once a target list is actually found.
+ *
+ * The next page is taken from ITS OWN SERVER RESPONSE and its rows are moved
+ * into the live list, rather than fetching JSON and re-rendering cards here.
+ * That is the only way the appended cards can be *identical* to the first
+ * page's: they were produced by the same grid block, the same properties, the
+ * same money format and — the part a JSON path cannot reach at all — the same
+ * designer-authored row layout, iterator bindings and item scope. Grafting is
+ * kept strictly additive (nothing existing is touched) and every grafted node
+ * is tracked so a later navigation can take it back out; React never removes
+ * DOM it did not create, so leaving them would strand stale products in a
+ * freshly sorted list.
+ *
+ * Additive means visually additive too, not just "appended to the end of the
+ * children". A grid pins a merchandising tile by a cell rule, and page two's
+ * tiles carry page two's key, so no rule the live page wrote can move them on
+ * top of a card the shopper already saw. What comes back is markup off the
+ * wire either way, so it is scrubbed against an allowlist before it is cloned.
+ *
+ * URL: each appended page is written with `replaceState`, never `pushState`.
+ * pushState would stack one history entry per append, so "back" would walk the
+ * shopper through every batch instead of leaving the listing; replaceState
+ * keeps a single entry. A click inside the list re-writes it to the page the
+ * clicked row came from, so following a product and coming back lands on what
+ * the shopper was looking at rather than on page 1. The cost, deliberately
+ * accepted: the restored URL renders that one page rather than re-fetching the
+ * whole appended run.
+ *
+ * Parts: list, page, prev, next, first, last, ellipsis, load-more, status,
+ * end, error, retry.
+ * Properties: mode, maxLinks, prevLabel, nextLabel, loadMoreLabel,
+ * showPrevNext, showFirstLast, firstLabel, lastLabel, showEllipsis,
+ * ellipsisLabel, navLabel, queryParam, append, appendTrigger, appendTarget,
+ * prefetchOffset, loadingLabel, errorLabel, retryLabel, endLabel, showStatus,
+ * statusTemplate, statusPosition, groupThousands.
+ */
+const ListingPaginationBlock = ({
+  block,
+  placeholderId,
+  sectionId,
+  selectedBlockId = null,
+  currentBreakpoint = 'desktop',
+  isDesigner = false
+}: BlockRendererProps) => {
+  const listing = useListingContext();
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+  const { locale } = useLocalization();
+
+  const mode = String(
+    getResponsiveValue(block.properties?.mode, currentBreakpoint, 'pages')
+  );
+  const maxLinksRaw = Math.round(
+    Number(getResponsiveValue(block.properties?.maxLinks, currentBreakpoint, 5))
+  );
+  const maxLinks = Number.isFinite(maxLinksRaw)
+    ? Math.min(9, Math.max(3, maxLinksRaw))
+    : 5;
+  const prevLabel = String(
+    getResponsiveValue(block.properties?.prevLabel, currentBreakpoint, 'Previous')
+  );
+  const nextLabel = String(
+    getResponsiveValue(block.properties?.nextLabel, currentBreakpoint, 'Next')
+  );
+  const loadMoreLabel = String(
+    getResponsiveValue(
+      block.properties?.loadMoreLabel,
+      currentBreakpoint,
+      'Load more'
+    )
+  );
+  const showPrevNext = readToggle(
+    block.properties?.showPrevNext,
+    currentBreakpoint,
+    true
+  );
+  const showFirstLast = readToggle(
+    block.properties?.showFirstLast,
+    currentBreakpoint,
+    false
+  );
+  const firstLabel = String(
+    getResponsiveValue(block.properties?.firstLabel, currentBreakpoint, 'First')
+  );
+  const lastLabel = String(
+    getResponsiveValue(block.properties?.lastLabel, currentBreakpoint, 'Last')
+  );
+  const showEllipsis = readToggle(
+    block.properties?.showEllipsis,
+    currentBreakpoint,
+    false
+  );
+  const ellipsisLabel = String(
+    getResponsiveValue(block.properties?.ellipsisLabel, currentBreakpoint, '…')
+  );
+  const navLabel = String(
+    getResponsiveValue(block.properties?.navLabel, currentBreakpoint, 'Pagination')
+  );
+  // Commerce normally paginates on `page`, but a brand running a custom
+  // listing route can move it; the filter blocks reset the same key.
+  const queryParam = String(
+    getResponsiveValue(block.properties?.queryParam, currentBreakpoint, 'page')
+  );
+
+  const append = readToggle(block.properties?.append, currentBreakpoint, false);
+  const appendTrigger = resolveOption<AppendTrigger>(
+    block.properties?.appendTrigger,
+    currentBreakpoint,
+    'button',
+    APPEND_TRIGGERS
+  );
+  const appendTarget = String(
+    getResponsiveValue(
+      block.properties?.appendTarget,
+      currentBreakpoint,
+      '[data-product-grid]'
+    )
+  );
+  const prefetchOffsetRaw = Math.round(
+    Number(
+      getResponsiveValue(block.properties?.prefetchOffset, currentBreakpoint, 200)
+    )
+  );
+  const prefetchOffset = Number.isFinite(prefetchOffsetRaw)
+    ? Math.min(2000, Math.max(0, prefetchOffsetRaw))
+    : 200;
+  const loadingLabel = String(
+    getResponsiveValue(block.properties?.loadingLabel, currentBreakpoint, 'Loading…')
+  );
+  const errorLabel = String(
+    getResponsiveValue(
+      block.properties?.errorLabel,
+      currentBreakpoint,
+      'Could not load more products.'
+    )
+  );
+  const retryLabel = String(
+    getResponsiveValue(block.properties?.retryLabel, currentBreakpoint, 'Try again')
+  );
+  const endLabel = String(
+    getResponsiveValue(block.properties?.endLabel, currentBreakpoint, '')
+  );
+  const showStatus = readToggle(
+    block.properties?.showStatus,
+    currentBreakpoint,
+    false
+  );
+  const statusTemplate = String(
+    getResponsiveValue(
+      block.properties?.statusTemplate,
+      currentBreakpoint,
+      'Showing {shown} of {total}'
+    )
+  );
+  const statusPosition = resolveOption<StatusPosition>(
+    block.properties?.statusPosition,
+    currentBreakpoint,
+    'before',
+    STATUS_POSITIONS
+  );
+  const groupThousands = readToggle(
+    block.properties?.groupThousands,
+    currentBreakpoint,
+    false
+  );
+
+  const navRef = React.useRef<HTMLElement | null>(null);
+  const sentinelRef = React.useRef<HTMLDivElement | null>(null);
+  /** Every node this block grafted, so a later navigation can take them back. */
+  const appendedNodesRef = React.useRef<Element[]>([]);
+  /** Synchronous, unlike state: the sentinel must not queue a second request. */
+  const inFlightRef = React.useRef(false);
+  const abortRef = React.useRef<AbortController | null>(null);
+  const [appendedPage, setAppendedPage] = React.useState(0);
+  const [appendedCount, setAppendedCount] = React.useState(0);
+  const [loadState, setLoadState] = React.useState<'idle' | 'loading' | 'error'>(
+    'idle'
+  );
+
+  const currentPage = listing?.pagination.currentPage ?? 1;
+  const totalPages = listing?.pagination.totalPages ?? 1;
+  const pageSize = listing?.pagination.pageSize ?? 0;
+  const totalCount = listing?.pagination.totalCount ?? 0;
+  const pageProducts = listing?.products.length ?? 0;
+  const products = listing?.products;
+  // 0 means nothing has been appended, so the block is still on the page the
+  // server rendered.
+  const loadedPage = appendedPage > 0 ? appendedPage : currentPage;
+  const appendEnabled = append && mode === 'loadmore';
+
+  const hrefForPage = React.useCallback(
+    (page: number) => {
+      const params = new URLSearchParams(
+        searchParams ? searchParams.toString() : ''
+      );
+
+      if (page <= 1) {
+        params.delete(queryParam);
+      } else {
+        params.set(queryParam, String(page));
+      }
+
+      return buildListingHref(pathname || listing?.path || '', params);
+    },
+    [searchParams, queryParam, pathname, listing?.path]
+  );
+
+  const loadNextPage = React.useCallback(async () => {
+    // Fetching inside the canvas would drop real product markup into the page
+    // the author is composing, where it cannot be selected or styled.
+    if (isDesigner || inFlightRef.current) return;
+    if (loadedPage >= totalPages) return;
+
+    const target = findAppendTarget(navRef.current, appendTarget);
+    // No list to append into: the anchor is left to navigate instead.
+    if (!target) return;
+
+    const nextPage = loadedPage + 1;
+    const controller = new AbortController();
+
+    inFlightRef.current = true;
+    abortRef.current = controller;
+    setLoadState('loading');
+
+    try {
+      const response = await fetch(hrefForPage(nextPage), {
+        signal: controller.signal,
+        credentials: 'same-origin',
+        headers: { Accept: 'text/html' }
+      });
+
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+
+      const nodes = extractAppendNodes(
+        await response.text(),
+        appendTarget,
+        indexOfTarget(target, appendTarget)
+      );
+
+      if (!nodes) throw new Error('No list in the response');
+
+      const fragment = document.createDocumentFragment();
+      nodes.forEach((node) => {
+        const clone = document.importNode(node, true);
+        // Which page a row came from, so a click on it can restore that page.
+        clone.setAttribute('data-listing-appended', String(nextPage));
+        appendedNodesRef.current.push(clone);
+        fragment.appendChild(clone);
+      });
+      target.appendChild(fragment);
+
+      setAppendedPage(nextPage);
+      setAppendedCount((count) => count + countProducts(nodes));
+      setLoadState('idle');
+      replaceListingUrl(hrefForPage(nextPage));
+    } catch {
+      // An abort is this block unmounting or a navigation, not a failure the
+      // shopper should be shown.
+      if (!controller.signal.aborted) setLoadState('error');
+    } finally {
+      inFlightRef.current = false;
+      if (abortRef.current === controller) abortRef.current = null;
+    }
+  }, [isDesigner, loadedPage, totalPages, appendTarget, hrefForPage]);
+
+  React.useEffect(() => {
+    // A sort, a filter or a page link re-renders the list from the server.
+    // React only owns the children it created, so the rows grafted from the
+    // previous URL would survive that render as stale products.
+    if (appendedNodesRef.current.length > 0) {
+      appendedNodesRef.current.forEach((node) => node.remove());
+      appendedNodesRef.current = [];
+    }
+
+    if (abortRef.current) abortRef.current.abort();
+    inFlightRef.current = false;
+    setAppendedPage(0);
+    setAppendedCount(0);
+    setLoadState('idle');
+  }, [products]);
+
+  React.useEffect(
+    () => () => {
+      if (abortRef.current) abortRef.current.abort();
+      appendedNodesRef.current.forEach((node) => node.remove());
+      appendedNodesRef.current = [];
+    },
+    []
+  );
+
+  React.useEffect(() => {
+    if (!appendEnabled || isDesigner) return undefined;
+    if (appendTrigger !== 'scroll') return undefined;
+    // The end of the list: an observer that stays armed here fires forever
+    // against a request that can never be made.
+    if (loadedPage >= totalPages) return undefined;
+    // 'loading' keeps a second request from being queued behind the first;
+    // 'error' keeps a failed page from being hammered on every scroll frame —
+    // the shopper re-arms it through the retry button.
+    if (loadState !== 'idle') return undefined;
+    if (typeof IntersectionObserver === 'undefined') return undefined;
+
+    const sentinel = sentinelRef.current;
+    if (!sentinel) return undefined;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return;
+        if (inFlightRef.current) return;
+        // Re-armed by this effect once the page number moves; leaving it
+        // connected would re-fire while the request is still in flight.
+        observer.disconnect();
+        loadNextPage();
+      },
+      { rootMargin: `${prefetchOffset}px 0px` }
+    );
+
+    observer.observe(sentinel);
+    return () => observer.disconnect();
+  }, [
+    appendEnabled,
+    isDesigner,
+    appendTrigger,
+    loadedPage,
+    totalPages,
+    loadState,
+    prefetchOffset,
+    loadNextPage
+  ]);
+
+  React.useEffect(() => {
+    if (!appendEnabled || isDesigner) return undefined;
+
+    const target = findAppendTarget(navRef.current, appendTarget);
+    if (!target) return undefined;
+
+    // Capture phase, so the page is recorded before a client-side Link
+    // navigation takes over.
+    const handleClick = (event: Event) => {
+      if (appendedNodesRef.current.length === 0) return;
+
+      const origin = event.target as Element | null;
+      const link = origin && origin.closest ? origin.closest('a[href]') : null;
+      if (!link || !target.contains(link)) return;
+
+      const batch = link.closest('[data-listing-appended]');
+      const page = batch
+        ? Number(batch.getAttribute('data-listing-appended'))
+        : currentPage;
+
+      if (!Number.isFinite(page) || page < 1) return;
+      replaceListingUrl(hrefForPage(page));
+    };
+
+    target.addEventListener('click', handleClick, true);
+    return () => target.removeEventListener('click', handleClick, true);
+  }, [appendEnabled, isDesigner, appendTarget, hrefForPage, currentPage]);
+
+  // Navigating inside the designer iframe would drop the author out of the
+  // page they are editing, so links are inert there.
+  const guard = (event: React.MouseEvent) => {
+    if (isDesigner) event.preventDefault();
+  };
+
+  const handleLoadMore = (event: React.MouseEvent) => {
+    if (isDesigner) {
+      event.preventDefault();
+      return;
+    }
+
+    if (!appendEnabled || event.defaultPrevented) return;
+    // A modified click is the shopper asking for a new tab: the href is theirs.
+    if (
+      event.metaKey ||
+      event.ctrlKey ||
+      event.shiftKey ||
+      event.altKey ||
+      event.button !== 0
+    ) {
+      return;
+    }
+
+    // Only once there is somewhere to append; otherwise the link navigates,
+    // which is what it does with no javascript at all.
+    if (!findAppendTarget(navRef.current, appendTarget)) return;
+
+    event.preventDefault();
+    loadNextPage();
+  };
+
+  const formatCount = (value: number): string => {
+    if (!groupThousands) return String(value);
+
+    // Explicit locale: an implicit one resolves to the Node default on the
+    // server and the browser's on the client, so the grouped number would
+    // differ between SSR and hydration.
+    try {
+      return new Intl.NumberFormat(locale || 'tr-TR').format(value);
+    } catch {
+      return String(value);
+    }
+  };
+
+  // How many rows are on screen right now: what the server rendered for this
+  // page plus whatever has been appended to it. Counting what is there rather
+  // than multiplying the page size keeps the readout honest for a shopper who
+  // deep-linked into the middle of the listing.
+  const shownCount = pageProducts + appendedCount;
+  const firstIndex = pageSize > 0 ? (currentPage - 1) * pageSize + 1 : 1;
+  const statusText = fillTemplate(statusTemplate, {
+    shown: formatCount(shownCount),
+    total: formatCount(totalCount),
+    from: formatCount(shownCount > 0 ? firstIndex : 0),
+    to: formatCount(shownCount > 0 ? firstIndex + shownCount - 1 : 0),
+    page: formatCount(loadedPage),
+    pages: formatCount(totalPages)
+  });
+
+  const statusNode = showStatus ? (
+    <p
+      data-listing-pagination-status=""
+      data-listing-shown={shownCount}
+      data-listing-total={totalCount}
+      {...partAttrs('status', { empty: shownCount === 0 })}
+      // The count changes on append without any navigation, so a screen reader
+      // is told rather than left on the number it read at page load.
+      aria-live="polite"
+      style={{ margin: 0 }}
+    >
+      {statusText}
+    </p>
+  ) : null;
+
+  // With no status the block returns exactly the element it always has; the
+  // fragment is only introduced once a designer asks for the readout.
+  const withStatus = (node: React.ReactNode): React.ReactElement => {
+    if (!statusNode) return node as React.ReactElement;
+
+    return (
+      <>
+        {statusPosition === 'after' ? null : statusNode}
+        {node}
+        {statusPosition === 'after' ? statusNode : null}
+      </>
+    );
+  };
+
+  if (!listing || totalPages <= 1) {
+    if (listing && statusNode) return statusNode;
+
+    return isDesigner ? (
+      <div data-listing-pagination="" style={listingPlaceholderStyle}>
+        Pagination (single page)
+      </div>
+    ) : null;
+  }
+
+  if (mode === 'loadmore') {
+    if (loadedPage >= totalPages) {
+      const endNode =
+        appendEnabled && endLabel ? (
+          <p
+            data-listing-load-end=""
+            {...partAttrs('end')}
+            style={{ margin: 0 }}
+          >
+            {endLabel}
+          </p>
+        ) : null;
+
+      if (!statusNode && !endNode) {
+        return isDesigner ? (
+          <div data-listing-pagination="" style={listingPlaceholderStyle}>
+            Load more (last page)
+          </div>
+        ) : null;
+      }
+
+      return withStatus(endNode);
+    }
+
+    return withStatus(
+      <nav
+        ref={navRef}
+        data-listing-pagination=""
+        data-pagination-mode="loadmore"
+        {...partAttrs('list')}
+      >
+        <NextLink
+          href={hrefForPage(loadedPage + 1)}
+          rel="next"
+          onClick={handleLoadMore}
+          data-listing-load-more=""
+          {...partAttrs(
+            'load-more',
+            appendEnabled ? { loading: loadState === 'loading' } : undefined
+          )}
+          style={linkStyle(false)}
+          aria-busy={
+            appendEnabled && loadState === 'loading' ? true : undefined
+          }
+        >
+          {appendEnabled && loadState === 'loading' ? loadingLabel : loadMoreLabel}
+        </NextLink>
+
+        {appendEnabled && loadState === 'error' && (
+          <>
+            <span data-listing-load-error="" {...partAttrs('error')} role="alert">
+              {errorLabel}
+            </span>
+            {/* A failed page is a dead end without this: the sentinel has
+                stood down and the anchor's own click is intercepted. */}
+            <button
+              type="button"
+              data-listing-load-retry=""
+              {...partAttrs('retry')}
+              onClick={() => loadNextPage()}
+              style={{ ...linkStyle(false), background: 'none', cursor: 'pointer' }}
+            >
+              {retryLabel}
+            </button>
+          </>
+        )}
+
+        {appendEnabled && appendTrigger === 'scroll' && (
+          <div
+            ref={sentinelRef}
+            data-listing-load-sentinel=""
+            aria-hidden="true"
+            style={{ width: '1px', height: '1px' }}
+          />
+        )}
+      </nav>
+    );
+  }
+
+  const half = Math.floor(maxLinks / 2);
+  const end = Math.min(totalPages, Math.max(currentPage + half, maxLinks));
+  const start = Math.max(1, Math.min(currentPage - half, end - maxLinks + 1));
+  const pages: number[] = [];
+  for (let page = start; page <= end; page += 1) {
+    pages.push(page);
+  }
+
+  // A designer who marked a child as the page-link layout gets that layout
+  // repeated per page; otherwise the built-in links render unchanged. Prev,
+  // next and the edge affordances stay built in either way.
+  const pageItems = pages.map((page) => ({
+    page,
+    name: String(page),
+    label: String(page),
+    url: hrefForPage(page),
+    current: page === currentPage
+  }));
+  const customPages = hasItemTemplate(block, currentBreakpoint) ? (
+    <ItemTemplateList
+      block={block}
+      items={pageItems as unknown as Record<string, unknown>[]}
+      placeholderId={placeholderId}
+      sectionId={sectionId}
+      isDesigner={isDesigner}
+      selectedBlockId={selectedBlockId}
+      currentBreakpoint={currentBreakpoint}
+    />
+  ) : null;
+
+  return withStatus(
+    <nav
+      data-listing-pagination=""
+      data-pagination-mode="pages"
+      aria-label={navLabel}
+      {...partAttrs('list')}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 'var(--listing-pagination-gap, 8px)',
+        flexWrap: 'wrap'
+      }}
+    >
+      {showPrevNext && currentPage > 1 && (
+        <NextLink
+          href={hrefForPage(currentPage - 1)}
+          rel="prev"
+          onClick={guard}
+          data-pagination-prev=""
+          {...partAttrs('prev')}
+          style={linkStyle(false)}
+        >
+          {prevLabel}
+        </NextLink>
+      )}
+
+      {showFirstLast && start > 1 && (
+        <NextLink
+          href={hrefForPage(1)}
+          onClick={guard}
+          data-pagination-first=""
+          {...partAttrs('first')}
+          style={linkStyle(false)}
+        >
+          {firstLabel}
+        </NextLink>
+      )}
+
+      {showEllipsis && start > 1 && (
+        <span
+          data-pagination-ellipsis="start"
+          aria-hidden="true"
+          {...partAttrs('ellipsis')}
+        >
+          {ellipsisLabel}
+        </span>
+      )}
+
+      {customPages ??
+        pages.map((page) => (
+          <NextLink
+            key={page}
+            href={hrefForPage(page)}
+            onClick={guard}
+            data-pagination-page={page}
+            aria-current={page === currentPage ? 'page' : undefined}
+            {...partAttrs('page', { selected: page === currentPage })}
+            style={linkStyle(page === currentPage)}
+          >
+            {page}
+          </NextLink>
+        ))}
+
+      {showEllipsis && end < totalPages && (
+        <span
+          data-pagination-ellipsis="end"
+          aria-hidden="true"
+          {...partAttrs('ellipsis')}
+        >
+          {ellipsisLabel}
+        </span>
+      )}
+
+      {showFirstLast && end < totalPages && (
+        <NextLink
+          href={hrefForPage(totalPages)}
+          onClick={guard}
+          data-pagination-last=""
+          {...partAttrs('last')}
+          style={linkStyle(false)}
+        >
+          {lastLabel}
+        </NextLink>
+      )}
+
+      {showPrevNext && currentPage < totalPages && (
+        <NextLink
+          href={hrefForPage(currentPage + 1)}
+          rel="next"
+          onClick={guard}
+          data-pagination-next=""
+          {...partAttrs('next')}
+          style={linkStyle(false)}
+        >
+          {nextLabel}
+        </NextLink>
+      )}
+    </nav>
+  );
+};
+
+export default ListingPaginationBlock;