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

package/src/utils/iterator-utils.ts

@@ -1,16 +1,31 @@
-import { Block } from '../theme-block';
+// Type-only: the CSS generator imports the binding-token guard from here, and
+// a value import of the block module would close that loop at runtime.
+import type { Block } from '../theme-block';
 import { devWarn } from './dev-warn';
+import { isVisibleForItem, readRowVisibility } from './row-visibility';
 
 interface BindingContext {
   sectionDataSource?: any;
   pageContext?: Record<string, unknown> | null;
   isDesigner?: boolean;
+  /**
+   * Locale for the money a binding resolves to. Bound prices used to be
+   * formatted as tr-TR whatever the storefront's locale was, so a brand
+   * running in en-GB got Turkish grouping in every repeated row.
+   */
+  locale?: string;
 }
 
 interface IteratorOptions extends BindingContext {
   iteratorBlock: Block;
   forceIteratorCount?: number;
   forceIteratorOffset?: number;
+  /**
+   * Rows supplied by the caller instead of looked up on the section's data
+   * source. Functional blocks fetch their own list (basket, orders, stores),
+   * so they have the items in hand and no data-source path to point at.
+   */
+  items?: Record<string, unknown>[];
 }
 
 const PAGE_CONTEXT_DATA_SOURCE_TYPE = 'page-context';
@@ -26,6 +41,97 @@ const DEFAULT_BINDING_TARGETS: Record<string, string> = {
 const isRecord = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
+/**
+ * Binding tokens: `{{item.badgeColor}}`.
+ *
+ * A binding used to be a bare path (`item.name`) that replaced the whole
+ * value, and a bare path still does exactly that — image URLs, booleans and
+ * numbers all depend on getting the RAW value back rather than its string
+ * form. A token is the additive spelling: several of them can sit inside one
+ * value next to literal text, which is what lets a single text block say
+ * "Ürün Kodu {{item.base_code}}.{{item.color}}" instead of three siblings
+ * fighting over the spacing, and what lets a style value carry a colour that
+ * comes from the row.
+ *
+ * `{{path}}` on its own is the bare path spelled differently, so it is
+ * normalized back to the bare path and keeps the raw-value contract.
+ */
+const BINDING_TOKEN_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
+const SINGLE_BINDING_TOKEN_PATTERN = /^\{\{\s*([^{}]+?)\s*\}\}$/;
+const CONTAINS_BINDING_TOKEN = /\{\{\s*[^{}]+?\s*\}\}/;
+
+/**
+ * True for a value that still carries an unresolved binding token. Exported
+ * because the CSS generator has to leave such a value out of the stylesheet:
+ * a token is an instruction, not a CSS value.
+ */
+export const hasBindingToken = (value: unknown): boolean =>
+  typeof value === 'string' && CONTAINS_BINDING_TOKEN.test(value);
+
+const readBindingTokens = (value: string): string[] =>
+  Array.from(value.matchAll(BINDING_TOKEN_PATTERN), (match) =>
+    String(match[1]).trim()
+  );
+
+/** `{{path}}` alone means the same as the bare `path` the editor writes today. */
+const normalizeBindingExpression = (binding: string): string => {
+  const single = binding.match(SINGLE_BINDING_TOKEN_PATTERN);
+  return single ? single[1].trim() : binding;
+};
+
+/**
+ * `item.colour` names a field of the row; a bare `item` names the row itself.
+ * The bare form is the only way to address an entry of a list of plain values
+ * (`tags: ['new','sale']`) — a repeat over one produces a clone per entry, and
+ * without this the entry has no spelling, so every clone prints the authored
+ * fallback. The empty path reads back as the row (see `getValueAtPath`).
+ */
+const stripItemPrefix = (path: string): string =>
+  path === 'item' ? '' : path.replace(/^item\./, '');
+
+/** A single token addresses the repeated row when it reads `item` or `item.*`. */
+const isRowScopedToken = (token: string): boolean =>
+  token === 'item' || token.startsWith('item.');
+
+/**
+ * Whether a binding addresses the repeated row rather than the section's data
+ * source. For a bare path this is the `item` test the tokens already use;
+ * a token expression is row-scoped as soon as one of its tokens is.
+ */
+const isRowScopedBinding = (binding: string): boolean => {
+  if (isRowScopedToken(binding)) return true;
+  if (!hasBindingToken(binding)) return false;
+
+  return readBindingTokens(binding).some(isRowScopedToken);
+};
+
+/**
+ * Replaces every token with its resolved text and keeps the literal text
+ * around it. Returns undefined when nothing resolved, so the block keeps the
+ * value the designer authored as a fallback — which is what an unresolved bare
+ * path does today.
+ */
+const interpolateBindingTemplate = (
+  template: string,
+  resolveToken: (path: string) => unknown,
+  toText: (value: unknown) => string | undefined
+): string | undefined => {
+  let resolvedCount = 0;
+
+  const text = template.replace(
+    BINDING_TOKEN_PATTERN,
+    (_match, rawPath: string) => {
+      const asText = toText(resolveToken(String(rawPath).trim()));
+      if (asText === undefined) return '';
+
+      resolvedCount += 1;
+      return asText;
+    }
+  );
+
+  return resolvedCount > 0 ? text : undefined;
+};
+
 const getValueAtPath = (source: unknown, path: string): unknown => {
   if (!path.trim()) return source;
 
@@ -239,10 +345,70 @@ const escapeHtml = (value: string): string =>
     .replace(/"/g, '&quot;')
     .replace(/'/g, '&#39;');
 
+/**
+ * Which items a repeat actually draws, and the count it falls back to when
+ * there are none.
+ *
+ * Exported because the product row scope has to hand clone N the row clone N
+ * was built from: with the count properties set, clone N is NOT items[N]. Two
+ * copies of this arithmetic drift the moment one of them learns a new
+ * property, and the symptom — every card showing the neighbouring product's
+ * price — is the kind nobody reads as an off-by-offset.
+ */
+export const sliceIteratorItems = (
+  iteratorBlock: Block,
+  items: Record<string, unknown>[],
+  overrides: {
+    forceIteratorCount?: number;
+    forceIteratorOffset?: number;
+  } = {}
+): { items: Record<string, unknown>[]; count: number; offset: number } => {
+  const { forceIteratorCount, forceIteratorOffset } = overrides;
+
+  const useIteratorCount =
+    forceIteratorCount !== undefined
+      ? true
+      : iteratorBlock.properties?.useIteratorCount === true ||
+        iteratorBlock.properties?.useIteratorCount === 'true';
+  const count =
+    forceIteratorCount !== undefined
+      ? Math.max(1, Math.floor(forceIteratorCount))
+      : parsePositiveNumber(iteratorBlock.properties?.iteratorCount, 1);
+  const offset =
+    forceIteratorOffset !== undefined
+      ? Math.max(0, Math.floor(forceIteratorOffset))
+      : parsePositiveNumber(iteratorBlock.properties?.iteratorOffset, 0);
+
+  return {
+    items:
+      items.length > 0
+        ? useIteratorCount
+          ? items.slice(offset, offset + count)
+          : items
+        : [],
+    count,
+    offset
+  };
+};
+
+/**
+ * The storefront's locale, set once per render pass by the section that owns
+ * the bindings. A module-level value rather than a parameter because the
+ * formatting sits deep inside a recursive value walk, and threading it
+ * through every call would touch a dozen signatures for one string.
+ */
+let bindingLocale = 'tr-TR';
+
+export const setBindingLocale = (locale?: string) => {
+  if (typeof locale === 'string' && locale.trim()) {
+    bindingLocale = locale.trim();
+  }
+};
+
 const formatDisplayPrice = (value: unknown): string => {
   if (typeof value === 'number' && Number.isFinite(value)) {
     const hasDecimals = Math.abs(value % 1) > 0.00001;
-    return value.toLocaleString('tr-TR', {
+    return value.toLocaleString(bindingLocale, {
       minimumFractionDigits: hasDecimals ? 2 : 0,
       maximumFractionDigits: 2
     });
@@ -255,7 +421,7 @@ const formatDisplayPrice = (value: unknown): string => {
 
   const parsed = parsePriceValue(raw);
   const hasDecimals = Math.abs(parsed % 1) > 0.00001;
-  return parsed.toLocaleString('tr-TR', {
+  return parsed.toLocaleString(bindingLocale, {
     minimumFractionDigits: hasDecimals ? 2 : 0,
     maximumFractionDigits: 2
   });
@@ -403,20 +569,41 @@ export const resolveBlockBindings = ({
         : sourceBlock.properties
     };
 
-    const bindingPath =
+    const bindingPath = normalizeBindingExpression(
       typeof nextBlock.properties?.dataBinding === 'string'
         ? nextBlock.properties.dataBinding.trim()
-        : '';
+        : ''
+    );
 
     let resolvedBlock = nextBlock;
-    if (bindingRoot && bindingPath && !bindingPath.startsWith('item.')) {
-      const resolvedValue = getValueAtPath(bindingRoot, bindingPath);
-      if (resolvedValue !== undefined) {
-        resolvedBlock = applyResolvedBinding(
-          nextBlock,
-          resolvedValue,
-          bindingPath
+    // A row-scoped binding is left alone here exactly as before: the iterator
+    // already resolved it against the row, and re-resolving it against the
+    // section would blank the value back out.
+    if (bindingRoot && bindingPath && !isRowScopedBinding(bindingPath)) {
+      if (hasBindingToken(bindingPath)) {
+        const target = getItemBindingTarget(nextBlock);
+        const interpolated = interpolateBindingTemplate(
+          bindingPath,
+          (path) => getValueAtPath(bindingRoot, path),
+          (value) => normalizeScalarValue(value, target, nextBlock.type)
         );
+
+        if (interpolated !== undefined) {
+          resolvedBlock = applyResolvedBinding(
+            nextBlock,
+            interpolated,
+            bindingPath
+          );
+        }
+      } else {
+        const resolvedValue = getValueAtPath(bindingRoot, bindingPath);
+        if (resolvedValue !== undefined) {
+          resolvedBlock = applyResolvedBinding(
+            nextBlock,
+            resolvedValue,
+            bindingPath
+          );
+        }
       }
     }
 
@@ -447,8 +634,20 @@ const getIteratorItems = ({
   sectionDataSource,
   dataPath,
   isDesigner = false,
-  pageContext
-}: BindingContext & { dataPath?: string }): Record<string, unknown>[] => {
+  pageContext,
+  scopedItems
+}: BindingContext & {
+  dataPath?: string;
+  scopedItems?: Record<string, unknown>[] | null;
+}): Record<string, unknown>[] => {
+  // A nested repeat draws the list the row it lives in handed it. Nothing else
+  // is redirected: a top-level iterator has no row, and a nested one pointing
+  // at a section path is handed nothing and keeps resolving exactly where it
+  // did before.
+  if (scopedItems) {
+    return scopedItems;
+  }
+
   const bindingRoot = getSectionBindingRoot({
     sectionDataSource,
     pageContext,
@@ -488,10 +687,279 @@ const getIteratorItems = ({
   return [];
 };
 
+/**
+ * Per-row appearance.
+ *
+ * Every clone is pinned to the template's style identity, so the generated
+ * stylesheet writes one rule that serves every row. That is deliberate — it is
+ * what keeps a repeated card cheap and what makes a style edit apply to the
+ * whole list. But a badge whose colour comes from the product itself cannot be
+ * built that way: the value differs per row.
+ *
+ * A style value may therefore carry a binding (`{{item.badgeColor}}`). Only the
+ * properties that actually carry one are resolved per clone; every other
+ * property is left on the shared rule, untouched and byte-identical. A bound
+ * property that does not resolve is dropped rather than emitted, so it stays
+ * unset instead of becoming `background-color: undefined`.
+ */
+
+/**
+ * What a resolved style value is allowed to contain.
+ *
+ * This value comes from merchant data — an attribute a shop owner typed into
+ * the catalogue — and ends up inside a CSS declaration, so it is untrusted.
+ * Only what a colour, a length, a number or a simple function needs is kept:
+ * letters, digits, space and `# % , . / + - _ ( )`. Everything else is
+ * rejected, which is what stops:
+ *   `;` `}` `{`  closing this declaration/rule and opening another one,
+ *   `<` `>`      the `</style` sequence that ends the raw-text element,
+ *   `"` `'` `\`  string context and CSS escapes (`\3c` re-creates `<`),
+ *   `:` `!` `@`  a second property, an `!important` hijack, an at-rule,
+ *   `*`          the `/*` comment that would swallow the rest of the rule.
+ * Asset-fetching functions are rejected on top of that: their characters are
+ * all legal, but they would let catalogue data pull a remote request (a
+ * tracking pixel) into every card on the page.
+ */
+const SAFE_BOUND_CSS_VALUE = /^[A-Za-z0-9 #%,./+\-_()]+$/;
+const FETCHING_CSS_FUNCTION =
+  /(?:url|image-set|image|cross-fade|element|expression|attr)\s*\(/i;
+const MAX_BOUND_CSS_VALUE_LENGTH = 120;
+
+const sanitizeBoundCssValue = (value: string): string | undefined => {
+  const trimmed = value.trim();
+
+  if (!trimmed || trimmed.length > MAX_BOUND_CSS_VALUE_LENGTH) {
+    return undefined;
+  }
+
+  if (!SAFE_BOUND_CSS_VALUE.test(trimmed)) return undefined;
+  if (FETCHING_CSS_FUNCTION.test(trimmed)) return undefined;
+
+  return trimmed;
+};
+
+/** Only text and finite numbers make a CSS value; anything else is "no value". */
+const toCssText = (value: unknown): string | undefined => {
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  return undefined;
+};
+
+const resolveBoundStyleValue = (
+  value: string,
+  itemData: unknown,
+  styleKey: string
+): string | undefined => {
+  let hasUnresolvedToken = false;
+
+  const text = value.replace(
+    BINDING_TOKEN_PATTERN,
+    (_match, rawPath: string) => {
+      const path = String(rawPath).trim();
+      // Only `item.*` addresses the row, the same rule a text binding follows.
+      // Stripping the prefix and reading the row regardless would let
+      // `{{brandColor}}` — a site-level spelling — be answered by whatever
+      // catalogue field happens to share the name, so a colour meant to be
+      // the same everywhere would change per product.
+      const resolved = isRowScopedToken(path)
+        ? getValueAtPath(itemData, stripItemPrefix(path))
+        : undefined;
+      const asText = toCssText(resolved);
+
+      if (asText === undefined) {
+        hasUnresolvedToken = true;
+        return '';
+      }
+
+      return asText;
+    }
+  );
+
+  // Half a CSS value ("rgb(255, , 0)") is worse than none: it can change what
+  // the shorthand around it means. All or nothing.
+  if (hasUnresolvedToken) return undefined;
+
+  const safe = sanitizeBoundCssValue(text);
+  if (safe === undefined) {
+    devWarn(
+      'iterator',
+      `bound style "${styleKey}" resolved to a value CSS cannot safely carry; leaving the property unset`
+    );
+  }
+
+  return safe;
+};
+
+/**
+ * Whether this row is the one that answers a style value: it carries a token
+ * and at least one of its tokens addresses the row. A value spelled entirely
+ * in site-level tokens is left exactly as authored — not this repeat's to
+ * resolve, and the CSS layer already leaves an unresolved token unset.
+ */
+const isRowBoundStyleValue = (value: unknown): value is string =>
+  hasBindingToken(value) && isRowScopedBinding(value as string);
+
+/**
+ * Resolves the bound values in one block's styles against a row. Returns the
+ * SAME object when nothing is bound, so a composition without style bindings
+ * is not merely equal but identical — no new object, no changed CSS.
+ */
+const resolveStyleBindingsForRow = (
+  styles: unknown,
+  itemData: unknown
+): unknown => {
+  if (!isRecord(styles)) return styles;
+
+  let changed = false;
+  const nextStyles: Record<string, unknown> = {};
+
+  Object.entries(styles).forEach(([key, value]) => {
+    if (typeof value === 'string') {
+      if (!isRowBoundStyleValue(value)) {
+        nextStyles[key] = value;
+        return;
+      }
+
+      changed = true;
+      const resolved = resolveBoundStyleValue(value, itemData, key);
+      if (resolved !== undefined) {
+        nextStyles[key] = resolved;
+      }
+      return;
+    }
+
+    // Responsive shape: one value per breakpoint, each bindable on its own.
+    if (isRecord(value)) {
+      const isBoundHere = Object.values(value).some(isRowBoundStyleValue);
+
+      if (!isBoundHere) {
+        nextStyles[key] = value;
+        return;
+      }
+
+      changed = true;
+      let hasUnresolvedBreakpoint = false;
+      const nextValue: Record<string, unknown> = {};
+
+      Object.entries(value).forEach(([breakpoint, breakpointValue]) => {
+        if (!hasBindingToken(breakpointValue)) {
+          nextValue[breakpoint] = breakpointValue;
+          return;
+        }
+
+        const resolved = isRowBoundStyleValue(breakpointValue)
+          ? resolveBoundStyleValue(breakpointValue, itemData, key)
+          : undefined;
+
+        if (resolved === undefined) {
+          hasUnresolvedBreakpoint = true;
+          return;
+        }
+
+        nextValue[breakpoint] = resolved;
+      });
+
+      // A breakpoint the row does not answer is unset AT EVERY breakpoint, so
+      // the property falls back to the shared rule. Keeping the breakpoints
+      // that did resolve would be worse than useless: a missing breakpoint is
+      // served the desktop value, so a mobile binding that resolved to nothing
+      // would be painted with the desktop row's colour rather than left alone.
+      if (!hasUnresolvedBreakpoint) {
+        nextStyles[key] = nextValue;
+      }
+      return;
+    }
+
+    nextStyles[key] = value;
+  });
+
+  return changed ? nextStyles : styles;
+};
+
+/**
+ * The list a nested iterator draws. Written onto the nested iterator's
+ * properties while its parent row is being built, and read back when that
+ * iterator expands — so the tree still has exactly one expansion point and no
+ * caller has to learn a new argument.
+ *
+ * The LIST, not the row it came from: whatever is written here rides along in
+ * the rendered tree until that iterator expands and is serialized to the
+ * client with it, so handing over the whole row would ship every field the API
+ * returned — cost prices, stock notes, internal codes — for a strip that draws
+ * three colours. A path that resolves to no list is not written at all.
+ */
+const SCOPED_ITEMS_PROPERTY = 'iteratorScopedItems';
+
+const readIteratorDataPath = (block: Block): string => {
+  const direct =
+    typeof block.iteratorDataPath === 'string' ? block.iteratorDataPath : '';
+  if (direct.trim()) return direct.trim();
+
+  const fromProperties =
+    typeof block.properties?.iteratorDataPath === 'string'
+      ? block.properties.iteratorDataPath
+      : '';
+
+  return fromProperties.trim();
+};
+
+const readScopedItems = (
+  properties: unknown
+): Record<string, unknown>[] | null => {
+  if (!isRecord(properties)) return null;
+
+  const scopedItems = properties[SCOPED_ITEMS_PROPERTY];
+  return Array.isArray(scopedItems)
+    ? (scopedItems as Record<string, unknown>[])
+    : null;
+};
+
+/** Returns the same object when there is no handed-over list to forget. */
+const forgetScopedItems = (properties: unknown): unknown => {
+  if (!isRecord(properties) || !(SCOPED_ITEMS_PROPERTY in properties)) {
+    return properties;
+  }
+
+  const { [SCOPED_ITEMS_PROPERTY]: _consumedItems, ...rest } = properties;
+  return rest;
+};
+
+/**
+ * A row with nothing behind it: the canvas draws these so a designer has
+ * something to arrange before any data exists.
+ *
+ * The test is "an object with no keys", not "no keys", because an entry of a
+ * list of plain values has none to count — `Object.keys(38)` is empty, and
+ * reading a real size as a blank canvas row prints the authored fallback.
+ */
+const isPlaceholderRow = (itemData: unknown): boolean => {
+  if (itemData === null || itemData === undefined) return true;
+  if (typeof itemData !== 'object') return false;
+  return Object.keys(itemData).length === 0;
+};
+
 const replaceBlockValues = (
   blockToReplace: Block,
-  itemData: Record<string, unknown>,
-  itemIndex: number
+  itemData: unknown,
+  itemIndex: number,
+  /**
+   * True once the walk has stepped inside a repeat of its own. Everything
+   * below that point is drawn once per entry of THAT repeat, so this row is
+   * not the one its appearance is resolved against.
+   *
+   * Nothing about this row is read below that point — not its styles, not its
+   * text, not its visibility rule.
+   *
+   * A style token is consumed the moment it resolves, so the outer row's
+   * reading of `{{item.hex}}` would be final. A text binding looks safer,
+   * because the block keeps its `dataBinding` and the owning repeat resolves it
+   * again — but only when the inner entry ANSWERS the path. When it does not,
+   * the outer row's value has nothing to overwrite it and stays: a swatch bound
+   * to `item.internal_note` prints the product's warehouse note in every
+   * swatch. A visibility rule is worse still: `hidden` is only ever set, never
+   * taken back, so one outer row decides every entry at once.
+   */
+  insideNestedRepeat = false
 ): Block => {
   const nextBlock: Block = {
     ...blockToReplace,
@@ -500,31 +968,144 @@ const replaceBlockValues = (
       : blockToReplace.properties
   };
 
-  const isPlaceholderMode = !itemData || Object.keys(itemData).length === 0;
-  const bindingPath =
+  const isPlaceholderMode = isPlaceholderRow(itemData);
+  // The children of a repeat belong to that repeat, not to this row. Read off
+  // this block rather than the parent so the rule holds at any depth: a repeat
+  // inside a repeat inside a repeat resolves its own template and no other.
+  const childInsideNestedRepeat =
+    insideNestedRepeat || nextBlock.isIterator === true;
+
+  // A badge that exists on three products out of forty, a campaign label on
+  // two: the row is the same for every item, so the element has to be able to
+  // remove itself. Written onto `hidden`, which the storefront already
+  // respects.
+  //
+  // Never in placeholder mode: with no data every field reads empty, so the
+  // rule would hide the element on the canvas and leave the designer with
+  // nothing to arrange.
+  if (!isPlaceholderMode) {
+    // All of this is this row's business only while the walk is still inside
+    // the repeat that owns this row.
+    if (!insideNestedRepeat) {
+      const visibility = readRowVisibility(nextBlock.properties);
+      if (visibility && !isVisibleForItem(visibility, itemData)) {
+        nextBlock.hidden = true;
+      }
+
+      // Only the bound properties are replaced; the rest of the block's styles
+      // stay on the shared rule, so a card with one bound colour keeps the
+      // whole stylesheet it had.
+      const resolvedStyles = resolveStyleBindingsForRow(
+        nextBlock.styles,
+        itemData
+      );
+      if (resolvedStyles !== nextBlock.styles) {
+        nextBlock.styles = resolvedStyles;
+      }
+
+      // A repeat inside a row means "the row's list": a colour-swatch strip
+      // iterates `item.colors` of THIS product. Resolved against the section's
+      // data source that path is nothing, which is why such a strip renders a
+      // single placeholder today. The list is handed to the nested iterator
+      // here and read back when it expands.
+      const nestedPath =
+        nextBlock.isIterator === true
+          ? normalizeBindingExpression(readIteratorDataPath(nextBlock))
+          : '';
+      if (nestedPath && isRowScopedBinding(nestedPath)) {
+        const nestedItems = getValueAtPath(
+          itemData,
+          stripItemPrefix(nestedPath)
+        );
+
+        // A defined-but-non-array answer means the path names the wrong shape
+        // (`item.colour`, a string, where `item.colours` was meant). Because
+        // the handover makes such a repeat draw nothing at all, staying quiet
+        // would leave the author with an empty strip and no clue why — while
+        // the section-scoped spelling of the same typo has always been
+        // reported. An absent field stays silent: it is ambiguous with data
+        // that has not landed yet.
+        if (nestedItems !== undefined && !Array.isArray(nestedItems)) {
+          devWarn(
+            'iterator',
+            `iteratorDataPath "${nestedPath}" resolved to a non-array value on the row; rendering no items`
+          );
+        }
+
+        // Written even when the row answers with nothing. An empty handover is
+        // the row saying "this product has no colours", which is a different
+        // statement from a repeat that was never given a list and still owes
+        // the canvas a placeholder row — and the difference is what keeps an
+        // empty swatch from appearing next to products that do have colours.
+        nextBlock.properties = {
+          ...(nextBlock.properties || {}),
+          [SCOPED_ITEMS_PROPERTY]: Array.isArray(nestedItems) ? nestedItems : []
+        };
+      }
+    }
+  }
+
+  const bindingPath = normalizeBindingExpression(
     typeof nextBlock.properties?.dataBinding === 'string'
       ? nextBlock.properties.dataBinding.trim()
-      : '';
+      : ''
+  );
 
-  if (bindingPath && !isPlaceholderMode) {
-    const itemBindingPath = bindingPath.replace(/^item\./, '');
-    const resolvedValue = getValueAtPath(itemData, itemBindingPath);
+  // `!insideNestedRepeat` for the same reason the styles carry it: the repeat
+  // that owns a binding is the one that reads it. Leaving the binding
+  // unresolved here costs nothing — the owning repeat resolves it against its
+  // own entry — while resolving it writes a value the inner entry may have no
+  // way to replace.
+  if (bindingPath && !isPlaceholderMode && !insideNestedRepeat) {
+    if (hasBindingToken(bindingPath)) {
+      const target = getItemBindingTarget(nextBlock);
+      const interpolated = interpolateBindingTemplate(
+        bindingPath,
+        (path) => getValueAtPath(itemData, stripItemPrefix(path)),
+        (value) => normalizeScalarValue(value, target, nextBlock.type)
+      );
 
-    if (resolvedValue !== undefined) {
-      if (
-        nextBlock.type === 'text' &&
-        bindingPath.startsWith('item.') &&
-        isPriceBinding(bindingPath)
-      ) {
-        nextBlock.value = buildProductPriceHtml(itemData);
-      } else {
+      if (interpolated !== undefined) {
         return {
-          ...applyResolvedBinding(nextBlock, resolvedValue, bindingPath),
+          ...applyResolvedBinding(nextBlock, interpolated, bindingPath),
           blocks: nextBlock.blocks?.map((childBlock) =>
-            replaceBlockValues(childBlock, itemData, itemIndex)
+            replaceBlockValues(
+              childBlock,
+              itemData,
+              itemIndex,
+              childInsideNestedRepeat
+            )
           )
         };
       }
+    } else {
+      const itemBindingPath = stripItemPrefix(bindingPath);
+      const resolvedValue = getValueAtPath(itemData, itemBindingPath);
+
+      if (resolvedValue !== undefined) {
+        if (
+          nextBlock.type === 'text' &&
+          bindingPath.startsWith('item.') &&
+          isPriceBinding(bindingPath) &&
+          // A price is read off the whole row (list price, currency, discount),
+          // so a row that is a plain value cannot answer one.
+          isRecord(itemData)
+        ) {
+          nextBlock.value = buildProductPriceHtml(itemData);
+        } else {
+          return {
+            ...applyResolvedBinding(nextBlock, resolvedValue, bindingPath),
+            blocks: nextBlock.blocks?.map((childBlock) =>
+              replaceBlockValues(
+                childBlock,
+                itemData,
+                itemIndex,
+                childInsideNestedRepeat
+              )
+            )
+          };
+        }
+      }
     }
   } else if (isPlaceholderMode && nextBlock.type === 'image') {
     const placeholderImages = [
@@ -547,7 +1128,12 @@ const replaceBlockValues = (
 
   if (nextBlock.blocks && nextBlock.blocks.length > 0) {
     nextBlock.blocks = nextBlock.blocks.map((childBlock) =>
-      replaceBlockValues(childBlock, itemData, itemIndex)
+      replaceBlockValues(
+        childBlock,
+        itemData,
+        itemIndex,
+        childInsideNestedRepeat
+      )
     );
   }
 
@@ -560,7 +1146,8 @@ export const buildIteratorBlock = ({
   pageContext,
   isDesigner = false,
   forceIteratorCount,
-  forceIteratorOffset
+  forceIteratorOffset,
+  items: providedItems
 }: IteratorOptions): Block => {
   if (
     !iteratorBlock.isIterator ||
@@ -574,43 +1161,59 @@ export const buildIteratorBlock = ({
   const dataPath =
     iteratorBlock.iteratorDataPath ||
     iteratorBlock.properties?.iteratorDataPath;
-  const items = getIteratorItems({
-    sectionDataSource,
-    pageContext,
-    dataPath,
-    isDesigner
-  });
-
-  const useIteratorCount =
-    forceIteratorCount !== undefined
-      ? true
-      : iteratorBlock.properties?.useIteratorCount === true ||
-        iteratorBlock.properties?.useIteratorCount === 'true';
-  const iteratorCount =
-    forceIteratorCount !== undefined
-      ? Math.max(1, Math.floor(forceIteratorCount))
-      : parsePositiveNumber(iteratorBlock.properties?.iteratorCount, 1);
-  const iteratorOffset =
-    forceIteratorOffset !== undefined
-      ? Math.max(0, Math.floor(forceIteratorOffset))
-      : parsePositiveNumber(iteratorBlock.properties?.iteratorOffset, 0);
+  // Only a repeat that resolves its own list can have been handed one; a
+  // caller that brought its items (a functional block's basket rows, orders,
+  // stores) speaks for itself.
+  const scopedItems =
+    providedItems === undefined
+      ? readScopedItems(iteratorBlock.properties)
+      : null;
+  const items =
+    providedItems ??
+    getIteratorItems({
+      sectionDataSource,
+      pageContext,
+      dataPath,
+      isDesigner,
+      scopedItems
+    });
 
-  const displayItems =
-    items.length > 0
-      ? useIteratorCount
-        ? items.slice(iteratorOffset, iteratorOffset + iteratorCount)
-        : items
-      : [];
+  const { count: iteratorCount, items: displayItems } = sliceIteratorItems(
+    iteratorBlock,
+    items,
+    { forceIteratorCount, forceIteratorOffset }
+  );
 
+  // The count floor draws a row where there is no data, which is what the
+  // canvas and a page whose fetch has not landed both need. A repeat handed
+  // its row's list is neither: the row has already answered, and an empty
+  // answer means this product has no colours — one empty swatch next to
+  // products that do have colours reads as a colour the shopper can pick.
   const actualCount =
-    displayItems.length > 0 ? displayItems.length : Math.max(iteratorCount, 1);
+    displayItems.length > 0
+      ? displayItems.length
+      : scopedItems
+      ? 0
+      : Math.max(iteratorCount, 1);
 
   const clonedBlocks = Array.from({ length: actualCount }, (_, index) => {
-    const item = displayItems[index] || {};
+    // `??`, not `||`: an entry of a list of plain values can be falsy (0, '')
+    // and is still the row, while a missing entry is the placeholder padding
+    // the count floor asked for.
+    const item = displayItems[index] ?? {};
 
     const templateCopy: Block = {
       ...template,
       id: `${template.id}-clone-${index}`,
+      // The clone needs its own id (React keys, selection), but the generated
+      // stylesheet only knows the template's id and the DOM writes
+      // `styleSourceId || id`. Without this, every style authored on a
+      // repeated item is emitted and then matches nothing. It stays pinned
+      // even when the row varies its appearance: giving a clone its own style
+      // identity would drop the shared rule for EVERY property, so a bound
+      // property is resolved onto the clone's own style set instead and only
+      // that property stops being shared.
+      styleSourceId: template.styleSourceId || template.id,
       properties: template.properties
         ? { ...template.properties }
         : template.properties,
@@ -622,8 +1225,18 @@ export const buildIteratorBlock = ({
     return replaceBlockValues(templateCopy, item, index);
   });
 
+  const nextProperties = forgetScopedItems(iteratorBlock.properties);
+
   return {
     ...iteratorBlock,
+    // The list a nested iterator was handed has now been consumed, so it is
+    // dropped again rather than riding along in the rendered tree. Written
+    // only when there was something to drop: writing it unconditionally gives
+    // an iterator that never had properties a `properties: undefined` key, and
+    // an object that gained a key is no longer the object it was.
+    ...(nextProperties !== iteratorBlock.properties
+      ? { properties: nextProperties }
+      : {}),
     blocks: clonedBlocks
   };
 };