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

package/src/utils/__tests__/iterator-bindings.test.tsx

@@ -0,0 +1,1178 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import { buildIteratorBlock, resolveBlockBindings } from '../iterator-utils';
+import { generateThemeCSS, getCSSStyles } from '../index';
+import TextBlock from '../../blocks/text-block';
+import type { Block } from '../../theme-block';
+
+/**
+ * Per-row appearance, nested repeats and interpolated bindings.
+ *
+ * The first block of tests is the important one: a composition that carries no
+ * binding token must come out of the iterator and out of the CSS generator
+ * exactly as it does today — same object, same bytes.
+ */
+
+const block = (overrides: Partial<Block>): Block =>
+  ({
+    id: 'block',
+    type: 'text',
+    label: 'Block',
+    value: '',
+    order: 0,
+    hidden: false,
+    properties: {},
+    styles: {},
+    blocks: [],
+    ...overrides
+  } as Block);
+
+const iteratorOf = (template: Block, overrides: Partial<Block> = {}): Block =>
+  block({
+    id: 'iterator',
+    type: 'group',
+    label: 'Iterator',
+    isIterator: true,
+    blocks: [template],
+    ...overrides
+  });
+
+describe('a composition with no bindings is untouched', () => {
+  const cardStyles = {
+    'background-color': '#e63946',
+    color: '#ffffff',
+    'background-opacity': '40',
+    padding: { desktop: '12px', mobile: '4px' },
+    'badge/border-color': '#00ff00'
+  };
+
+  const template = block({
+    id: 'card',
+    type: 'group',
+    label: 'Card',
+    styles: cardStyles,
+    blocks: [
+      block({
+        id: 'card-title',
+        properties: { dataBinding: 'item.name' },
+        styles: { 'font-size': 16 },
+        value: 'Fallback'
+      })
+    ]
+  });
+
+  const expanded = buildIteratorBlock({
+    iteratorBlock: iteratorOf(template),
+    items: [{ name: 'Sneaker' }, { name: 'Boot' }]
+  });
+
+  it('hands every clone the template style object itself, not a copy of it', () => {
+    // Reference identity is the strongest available proof that nothing about
+    // the style set changed: no re-serialization, no key reordering, no value
+    // rewritten — the clone points at exactly what the template holds.
+    (expanded.blocks || []).forEach((clone) => {
+      expect(clone.styles).toBe(cardStyles);
+      expect((clone.blocks || [])[0].styles).toBe(template.blocks?.[0].styles);
+    });
+  });
+
+  it('keeps the template style identity, so one rule still serves every row', () => {
+    (expanded.blocks || []).forEach((clone) => {
+      expect(clone.styleSourceId).toBe('card');
+    });
+  });
+
+  it('still resolves the row values', () => {
+    expect(
+      (expanded.blocks || []).map((clone) => clone.blocks?.[0].value)
+    ).toEqual(['Sneaker', 'Boot']);
+  });
+
+  it('emits byte-identical CSS', () => {
+    // Frozen against the output of the committed generator, captured before
+    // this feature existed. Any drift in spacing, ordering, alpha maths or
+    // part handling breaks this line.
+    const section = [
+      {
+        id: 'sec-1',
+        styles: { 'background-color': '#101010' },
+        blocks: [{ id: 'card', styleSourceId: 'tpl', styles: cardStyles }]
+      }
+    ];
+
+    expect(generateThemeCSS(section as any)).toBe(
+      '[data-section-id="sec-1"] {\n' +
+        '  background-color: rgba(16, 16, 16, 1);\n' +
+        '}\n' +
+        '[data-block-id="tpl"] {\n' +
+        '  background-color: rgba(230, 57, 70, 0.4);\n' +
+        '  color: #ffffff;\n' +
+        '  padding: 12px;\n' +
+        '}\n' +
+        '@media (max-width: 1023px) {\n' +
+        '  [data-block-id="tpl"] {\n' +
+        '    padding: 4px;\n' +
+        '  }\n' +
+        '}\n' +
+        // The part rule carries an ownership guard so it cannot reach a part
+        // of the same name inside a nested block (utils/part-styles.ts). The
+        // guard sits in :where(), so the rule's specificity is unchanged.
+        '[data-block-id="tpl"] [data-part="badge"]' +
+        ':not(:where([data-block-id="tpl"] [data-block-id] *)) {\n' +
+        '  border-color: #00ff00 !important;\n' +
+        '}\n'
+    );
+
+    expect(generateThemeCSS(section as any, 'mobile')).toBe(
+      '[data-section-id="sec-1"] {\n' +
+        '  background-color: rgba(16, 16, 16, 1);\n' +
+        '}\n' +
+        '[data-block-id="tpl"] {\n' +
+        '  background-color: rgba(230, 57, 70, 0.4);\n' +
+        '  color: #ffffff;\n' +
+        '  padding: 4px;\n' +
+        '}\n' +
+        // The part rule carries an ownership guard so it cannot reach a part
+        // of the same name inside a nested block (utils/part-styles.ts). The
+        // guard sits in :where(), so the rule's specificity is unchanged.
+        '[data-block-id="tpl"] [data-part="badge"]' +
+        ':not(:where([data-block-id="tpl"] [data-block-id] *)) {\n' +
+        '  border-color: #00ff00 !important;\n' +
+        '}\n'
+    );
+  });
+});
+
+describe('a style value can carry a binding', () => {
+  const badgeStyles = {
+    'background-color': '{{item.badgeColor}}',
+    color: '{{item.badgeTextColor}}',
+    'background-opacity': '{{item.badgeOpacity}}',
+    'border-radius': '4px'
+  };
+
+  const expandFor = (rows: Record<string, unknown>[]) =>
+    buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({
+          id: 'card',
+          type: 'group',
+          label: 'Card',
+          blocks: [block({ id: 'badge', label: 'Badge', styles: badgeStyles })]
+        })
+      ),
+      items: rows
+    });
+
+  const badgeOf = (expanded: Block, index: number) =>
+    (expanded.blocks || [])[index].blocks?.[0];
+
+  it('resolves the bound properties per clone', () => {
+    const expanded = expandFor([
+      { badgeColor: '#00a86b', badgeTextColor: '#ffffff', badgeOpacity: 40 },
+      {
+        badgeColor: 'rgb(230 57 70)',
+        badgeTextColor: '#101010',
+        badgeOpacity: 100
+      }
+    ]);
+
+    expect(badgeOf(expanded, 0)?.styles).toEqual({
+      'background-color': '#00a86b',
+      color: '#ffffff',
+      'background-opacity': '40',
+      'border-radius': '4px'
+    });
+    expect(badgeOf(expanded, 1)?.styles).toEqual({
+      'background-color': 'rgb(230 57 70)',
+      color: '#101010',
+      'background-opacity': '100',
+      'border-radius': '4px'
+    });
+  });
+
+  it('leaves the unbound properties alone, so the shared rule still applies', () => {
+    const expanded = expandFor([{ badgeColor: '#00a86b' }]);
+
+    expect(badgeOf(expanded, 0)?.styles['border-radius']).toBe('4px');
+  });
+
+  it('never writes back onto the template', () => {
+    expandFor([{ badgeColor: '#00a86b' }]);
+
+    expect(badgeStyles['background-color']).toBe('{{item.badgeColor}}');
+  });
+
+  it('leaves the property unset when the binding resolves to nothing', () => {
+    const styles = badgeOf(expandFor([{ badgeTextColor: '#fff' }]), 0)?.styles;
+
+    expect('background-color' in styles).toBe(false);
+    expect(JSON.stringify(styles)).not.toContain('undefined');
+  });
+
+  it('resolves per breakpoint and keeps the literal breakpoints', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({
+          id: 'card',
+          styles: {
+            'font-size': { desktop: '{{item.size}}', mobile: '12px' }
+          }
+        })
+      ),
+      items: [{ size: '18px' }]
+    });
+
+    expect((expanded.blocks || [])[0].styles['font-size']).toEqual({
+      desktop: '18px',
+      mobile: '12px'
+    });
+  });
+
+  it('interpolates a binding inside a longer CSS value', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({
+          id: 'card',
+          styles: { padding: '{{item.gap}}px {{item.gap}}px' }
+        })
+      ),
+      items: [{ gap: 8 }]
+    });
+
+    expect((expanded.blocks || [])[0].styles.padding).toBe('8px 8px');
+  });
+
+  it('drops a value where only some tokens resolve', () => {
+    // Half a CSS value can change what the shorthand around it means.
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({ id: 'card', styles: { margin: '{{item.top}} {{item.side}}' } })
+      ),
+      items: [{ top: '4px' }]
+    });
+
+    expect('margin' in (expanded.blocks || [])[0].styles).toBe(false);
+  });
+
+  it('leaves the token in place on the designer canvas, where there is no row', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: iteratorOf(block({ id: 'card', styles: badgeStyles })),
+      items: [],
+      isDesigner: true
+    });
+
+    expect((expanded.blocks || [])[0].styles['background-color']).toBe(
+      '{{item.badgeColor}}'
+    );
+  });
+
+  describe('and the resolved value reaches the element', () => {
+    const paintBadges = (rows: Record<string, unknown>[]) => {
+      const expanded = buildIteratorBlock({
+        iteratorBlock: iteratorOf(
+          block({
+            id: 'badge',
+            type: 'text',
+            value: 'SALE',
+            styles: {
+              'background-color': '{{item.badgeColor}}',
+              'background-opacity': '{{item.badgeOpacity}}',
+              'border-radius': '4px'
+            }
+          })
+        ),
+        items: rows
+      });
+
+      return (expanded.blocks || []).map(
+        (clone) =>
+          render(<TextBlock block={clone as any} />).container.querySelector(
+            'div'
+          ) as HTMLDivElement
+      );
+    };
+
+    it('paints each row its own colour', () => {
+      const painted = paintBadges([
+        { badgeColor: '#00a86b', badgeOpacity: 40 },
+        { badgeColor: '#e63946', badgeOpacity: 100 }
+      ]);
+
+      // The bound opacity feeds the same alpha maths a typed colour goes
+      // through, so the row gets a real rgba rather than a flat swatch.
+      expect(painted[0].style.backgroundColor).toBe('rgba(0, 168, 107, 0.4)');
+      expect(painted[1].style.backgroundColor).toMatch(/230, 57, 70/);
+      // The unbound property is still on every row.
+      expect(painted[0].style.borderRadius).toBe('4px');
+    });
+
+    it('paints nothing where the row carries no colour', () => {
+      const [painted] = paintBadges([{ name: 'No badge' }]);
+
+      expect(painted.style.backgroundColor).toBe('');
+      expect(painted.getAttribute('style')).not.toContain('undefined');
+    });
+  });
+});
+
+describe('a bound style value is merchant data, so it is treated as untrusted', () => {
+  const resolveBadge = (badgeColor: unknown) =>
+    (buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({
+          id: 'card',
+          styles: { 'background-color': '{{item.badgeColor}}' }
+        })
+      ),
+      items: [{ badgeColor }]
+    }).blocks || [])[0].styles;
+
+  it.each([
+    ['a second declaration', '#fff; color: red'],
+    ['a second rule', 'red} body { display: none'],
+    ['a style tag breakout', '</style><script>alert(1)</script>'],
+    ['an escaped breakout', '\\3c /style\\3e '],
+    ['an important hijack', '#fff !important'],
+    ['a comment', '#fff /* hidden'],
+    ['a remote fetch', 'url(//tracker.test/p.gif)'],
+    ['a fetch behind a gradient', 'image-set(//tracker.test/p.gif)'],
+    ['a legacy script value', 'expression(alert(1))'],
+    ['a quoted value', '"#fff"'],
+    ['an at-rule', '@import "x"']
+  ])('rejects %s', (_label, payload) => {
+    expect('background-color' in resolveBadge(payload)).toBe(false);
+  });
+
+  it('accepts the values a colour actually needs', () => {
+    expect(resolveBadge('#00a86b')['background-color']).toBe('#00a86b');
+    expect(resolveBadge('rebeccapurple')['background-color']).toBe(
+      'rebeccapurple'
+    );
+    expect(resolveBadge('rgb(230, 57, 70)')['background-color']).toBe(
+      'rgb(230, 57, 70)'
+    );
+    expect(resolveBadge('rgb(230 57 70 / 40%)')['background-color']).toBe(
+      'rgb(230 57 70 / 40%)'
+    );
+  });
+
+  it('rejects a value long enough to be a payload rather than a colour', () => {
+    expect('background-color' in resolveBadge(`#${'a'.repeat(200)}`)).toBe(
+      false
+    );
+  });
+
+  it('never lets an unresolved token reach the stylesheet', () => {
+    const css = generateThemeCSS([
+      {
+        id: 'sec',
+        styles: {},
+        blocks: [
+          {
+            id: 'badge',
+            styles: {
+              'background-color': '{{item.badgeColor}}',
+              'badge/color': '{{item.badgeTextColor}}',
+              padding: { desktop: '{{item.pad}}', mobile: '4px' }
+            }
+          }
+        ]
+      }
+    ] as any);
+
+    expect(css).not.toContain('{{');
+    expect(css).not.toContain('background-color');
+    expect(css).not.toContain('undefined');
+    // The breakpoint that is real CSS still lands.
+    expect(css).toContain('padding: 4px');
+  });
+});
+
+describe('a repeat inside a row iterates the row', () => {
+  const swatchStrip = block({
+    id: 'swatches',
+    type: 'group',
+    label: 'Swatches',
+    isIterator: true,
+    iteratorDataPath: 'item.colors',
+    properties: { iteratorDataPath: 'item.colors' },
+    blocks: [block({ id: 'swatch', properties: { dataBinding: 'item.label' } })]
+  });
+
+  const card = block({
+    id: 'card',
+    type: 'group',
+    label: 'Card',
+    blocks: [swatchStrip]
+  });
+
+  // What the section renderer does: expand the outer repeat, then walk into
+  // each clone and expand the repeats it finds there.
+  const expandNested = (rows: Record<string, unknown>[]) => {
+    const outer = buildIteratorBlock({
+      iteratorBlock: iteratorOf(card),
+      items: rows
+    });
+
+    return (outer.blocks || []).map((clone) =>
+      buildIteratorBlock({ iteratorBlock: (clone.blocks || [])[0] })
+    );
+  };
+
+  it('draws one element per entry of the row it lives in', () => {
+    const nested = expandNested([
+      { colors: [{ label: 'Red' }, { label: 'Blue' }, { label: 'Black' }] },
+      { colors: [{ label: 'Sand' }] }
+    ]);
+
+    expect(nested[0].blocks).toHaveLength(3);
+    expect(nested[1].blocks).toHaveLength(1);
+  });
+
+  it('resolves the nested bindings against the nested entry', () => {
+    const nested = expandNested([
+      { colors: [{ label: 'Red' }, { label: 'Blue' }] }
+    ]);
+
+    expect((nested[0].blocks || []).map((clone) => clone.value)).toEqual([
+      'Red',
+      'Blue'
+    ]);
+  });
+
+  it('leaves a top-level repeat resolving exactly where it did', () => {
+    // No row to stand in: `item.colors` is not a section path, so this is the
+    // single placeholder clone it has always produced.
+    const topLevel = buildIteratorBlock({
+      iteratorBlock: iteratorOf(block({ id: 'swatch' }), {
+        iteratorDataPath: 'item.colors'
+      }),
+      sectionDataSource: {
+        type: 'page-context',
+        details: { pageContext: { pageType: 'product', rootPath: 'product' } }
+      },
+      pageContext: { colors: [{ label: 'Red' }, { label: 'Blue' }] }
+    });
+
+    expect(topLevel.blocks).toHaveLength(1);
+  });
+
+  it('leaves a nested repeat that points at a section path alone', () => {
+    const outer = buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({
+          id: 'card',
+          type: 'group',
+          blocks: [
+            block({
+              id: 'campaigns',
+              type: 'group',
+              isIterator: true,
+              iteratorDataPath: 'campaigns',
+              properties: { iteratorDataPath: 'campaigns' },
+              blocks: [block({ id: 'chip' })]
+            })
+          ]
+        })
+      ),
+      items: [{ campaigns: [{ label: 'A' }, { label: 'B' }] }]
+    });
+
+    const nestedProperties = (outer.blocks || [])[0].blocks?.[0].properties;
+    expect(nestedProperties.iteratorScopedItems).toBeUndefined();
+    // Nothing from the row travels with it either.
+    expect(JSON.stringify(nestedProperties)).not.toContain('label');
+  });
+});
+
+describe('a colour strip inside a card', () => {
+  // The design case the whole feature exists for: a card repeats products, and
+  // inside each card a strip repeats THAT product's colours with each swatch
+  // painted its own hex. The strip's template is a descendant of the card, so
+  // the outer expansion walks straight through it — and a style token, unlike
+  // a `dataBinding`, is consumed the moment it is resolved: whatever the outer
+  // row makes of it is final. The nested repeat has to be the one that
+  // resolves it.
+  const swatch = block({
+    id: 'swatch',
+    label: 'Swatch',
+    properties: { dataBinding: 'item.label' },
+    styles: { 'background-color': '{{item.hex}}', 'border-radius': '2px' }
+  });
+
+  const strip = block({
+    id: 'strip',
+    type: 'group',
+    label: 'Colours',
+    isIterator: true,
+    iteratorDataPath: 'item.colors',
+    properties: { iteratorDataPath: 'item.colors' },
+    styles: { 'background-color': '{{item.stripBg}}', gap: '4px' },
+    blocks: [swatch]
+  });
+
+  const card = block({
+    id: 'card',
+    type: 'group',
+    label: 'Card',
+    blocks: [strip]
+  });
+
+  // What the section renderer does: expand the outer repeat, then walk into
+  // each clone and expand the repeats it finds there.
+  const expandCards = (rows: Record<string, unknown>[]) => {
+    const outer = buildIteratorBlock({
+      iteratorBlock: iteratorOf(card),
+      items: rows
+    });
+
+    return (outer.blocks || []).map((clone) => ({
+      unexpandedStrip: (clone.blocks || [])[0],
+      strip: buildIteratorBlock({ iteratorBlock: (clone.blocks || [])[0] })
+    }));
+  };
+
+  const swatchColours = (expandedStrip: Block) =>
+    (expandedStrip.blocks || []).map(
+      (clone) => (clone.styles as Record<string, unknown>)['background-color']
+    );
+
+  const colours = [
+    { label: 'Red', hex: '#ff0000' },
+    { label: 'Blue', hex: '#0000ff' }
+  ];
+
+  it('paints every swatch the colour of its own entry', () => {
+    const [{ strip: expanded }] = expandCards([{ colors: colours }]);
+
+    expect(swatchColours(expanded)).toEqual(['#ff0000', '#0000ff']);
+  });
+
+  it('does not paint the strip with the product row that happens to carry the same field', () => {
+    // A dominant-colour attribute on the product is ordinary catalogue data.
+    // Resolved by the outer repeat it silently paints every swatch the same
+    // wrong colour, which is worse than painting none.
+    const [{ strip: expanded }] = expandCards([
+      { hex: '#123456', colors: colours }
+    ]);
+
+    expect(swatchColours(expanded)).toEqual(['#ff0000', '#0000ff']);
+    expect(JSON.stringify(expanded)).not.toContain('#123456');
+  });
+
+  it('still resolves the strip container against the product row it is drawn in', () => {
+    // The strip itself is drawn once per product, so its own styles belong to
+    // the outer repeat. Only what is INSIDE it belongs to the nested one.
+    const [{ strip: expanded }] = expandCards([
+      { stripBg: '#eeeeee', colors: colours }
+    ]);
+
+    expect((expanded.styles as Record<string, unknown>)['background-color']).toBe(
+      '#eeeeee'
+    );
+    expect((expanded.styles as Record<string, unknown>).gap).toBe('4px');
+  });
+
+  it('keeps the per-swatch text the nested repeat already resolved correctly', () => {
+    const [{ strip: expanded }] = expandCards([{ colors: colours }]);
+
+    expect((expanded.blocks || []).map((clone) => clone.value)).toEqual([
+      'Red',
+      'Blue'
+    ]);
+  });
+
+  it('leaves the unbound property on the shared rule', () => {
+    const [{ strip: expanded }] = expandCards([{ colors: colours }]);
+
+    (expanded.blocks || []).forEach((clone) => {
+      expect((clone.styles as Record<string, unknown>)['border-radius']).toBe(
+        '2px'
+      );
+    });
+  });
+
+  it('resolves a repeat inside a repeat inside a repeat by its own owner', () => {
+    const sizeChip = block({
+      id: 'size',
+      label: 'Size',
+      styles: { color: '{{item.tint}}' }
+    });
+
+    const sizes = block({
+      id: 'sizes',
+      type: 'group',
+      label: 'Sizes',
+      isIterator: true,
+      iteratorDataPath: 'item.sizes',
+      properties: { iteratorDataPath: 'item.sizes' },
+      blocks: [sizeChip]
+    });
+
+    const deepStrip = block({
+      id: 'strip',
+      type: 'group',
+      label: 'Colours',
+      isIterator: true,
+      iteratorDataPath: 'item.colors',
+      properties: { iteratorDataPath: 'item.colors' },
+      blocks: [
+        block({ id: 'swatch', type: 'group', label: 'Swatch', blocks: [sizes] })
+      ]
+    });
+
+    const outer = buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({ id: 'card', type: 'group', label: 'Card', blocks: [deepStrip] })
+      ),
+      items: [
+        {
+          tint: '#123456',
+          colors: [
+            { tint: '#654321', sizes: [{ tint: '#00a86b' }, { tint: '#e63946' }] }
+          ]
+        }
+      ]
+    });
+
+    const expandedStrip = buildIteratorBlock({
+      iteratorBlock: ((outer.blocks || [])[0].blocks || [])[0]
+    });
+    const expandedSizes = buildIteratorBlock({
+      iteratorBlock: ((expandedStrip.blocks || [])[0].blocks || [])[0]
+    });
+
+    expect(
+      (expandedSizes.blocks || []).map(
+        (clone) => (clone.styles as Record<string, unknown>).color
+      )
+    ).toEqual(['#00a86b', '#e63946']);
+  });
+
+  it('draws the row colours and carries nothing else from the row into the page', () => {
+    // Whatever the outer row hands the nested iterator rides along in the
+    // rendered tree until that iterator expands, and is serialized to the
+    // client with it. The strip must draw the colours and ship nothing the
+    // composition never displays — cost prices, warehouse notes, internal SKUs.
+    const [{ unexpandedStrip, strip: expanded }] = expandCards([
+      {
+        colors: colours,
+        sku: 'ABC-1',
+        cost_price: 42.5,
+        internal_note: 'do-not-ship'
+      }
+    ]);
+
+    expect(swatchColours(expanded)).toEqual(['#ff0000', '#0000ff']);
+    expect((expanded.blocks || []).map((clone) => clone.value)).toEqual([
+      'Red',
+      'Blue'
+    ]);
+
+    const shipped = JSON.stringify(unexpandedStrip);
+    expect(shipped).not.toContain('cost_price');
+    expect(shipped).not.toContain('do-not-ship');
+    expect(shipped).not.toContain('ABC-1');
+  });
+
+  it('never prints an outer-row field the swatch itself cannot answer', () => {
+    // `internal_note` is a product field, not a colour field. Resolved by the
+    // outer repeat it sticks: the nested repeat has nothing to overwrite it
+    // with, so a warehouse note the composition never meant to show is printed
+    // in every swatch.
+    const noteStrip = block({
+      id: 'strip',
+      type: 'group',
+      label: 'Colours',
+      isIterator: true,
+      iteratorDataPath: 'item.colors',
+      properties: { iteratorDataPath: 'item.colors' },
+      blocks: [
+        block({
+          id: 'swatch',
+          label: 'Swatch',
+          value: 'Colour',
+          properties: { dataBinding: 'item.internal_note' }
+        })
+      ]
+    });
+
+    const outer = buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({ id: 'card', type: 'group', label: 'Card', blocks: [noteStrip] })
+      ),
+      items: [{ internal_note: 'do-not-ship', colors: colours }]
+    });
+
+    const expanded = buildIteratorBlock({
+      iteratorBlock: ((outer.blocks || [])[0].blocks || [])[0]
+    });
+
+    expect((expanded.blocks || []).map((clone) => clone.value)).toEqual([
+      'Colour',
+      'Colour'
+    ]);
+    expect(JSON.stringify(expanded)).not.toContain('do-not-ship');
+  });
+
+  it('draws no swatch for a product whose colour list is empty', () => {
+    const [{ strip: expanded }] = expandCards([{ colors: [] }]);
+
+    expect(expanded.blocks).toEqual([]);
+  });
+
+  it('draws no swatch for a product that has no colours at all', () => {
+    // Next to cards that do have colours, one empty swatch is a visible
+    // artefact — the shopper reads it as a colour.
+    const [{ strip: expanded }] = expandCards([{ sku: 'ABC-1' }]);
+
+    expect(expanded.blocks).toEqual([]);
+  });
+
+  it('still draws the placeholder swatch on the canvas, where no row answered', () => {
+    // A card with no data behind it: the strip is inside a row that knows
+    // nothing, so nothing has said "this product has no colours" and the
+    // designer still needs a swatch to arrange.
+    const [{ strip: expanded }] = expandCards([{}]);
+
+    expect(expanded.blocks).toHaveLength(1);
+  });
+
+  it('still draws the placeholder row where there is no row to ask', () => {
+    // The canvas and a page whose data has not landed both reach the iterator
+    // with an empty list and no row behind it. That is not "this product has
+    // no colours", and it still owes the designer something to arrange.
+    const canvas = buildIteratorBlock({
+      iteratorBlock: iteratorOf(block({ id: 'swatch' }), {
+        iteratorDataPath: 'item.colors'
+      }),
+      items: []
+    });
+
+    expect(canvas.blocks).toHaveLength(1);
+  });
+
+  it('drops what it handed over once the nested repeat has expanded', () => {
+    const [{ strip: expanded }] = expandCards([{ colors: colours }]);
+
+    expect(JSON.stringify(expanded.properties)).not.toContain('#ff0000');
+    expect(expanded.properties.iteratorDataPath).toBe('item.colors');
+  });
+});
+
+describe('a repeat over a list of plain values', () => {
+  // `tags: ['new','sale']` is an ordinary catalogue shape. The repeat draws one
+  // clone per entry, so the entry has to be addressable — otherwise every clone
+  // prints the authored fallback and the surface is a dead end.
+  const expandChips = (
+    chip: Block,
+    row: Record<string, unknown>,
+    dataPath = 'item.tags'
+  ) => {
+    const chipStrip = block({
+      id: 'chips',
+      type: 'group',
+      label: 'Chips',
+      isIterator: true,
+      iteratorDataPath: dataPath,
+      properties: { iteratorDataPath: dataPath },
+      blocks: [chip]
+    });
+
+    const outer = buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({ id: 'card', type: 'group', label: 'Card', blocks: [chipStrip] })
+      ),
+      items: [row]
+    });
+
+    return buildIteratorBlock({
+      iteratorBlock: ((outer.blocks || [])[0].blocks || [])[0]
+    });
+  };
+
+  it('addresses the entry itself with a bare item binding', () => {
+    const expanded = expandChips(
+      block({ id: 'chip', value: 'Tag', properties: { dataBinding: 'item' } }),
+      { tags: ['new', 'sale'] }
+    );
+
+    expect((expanded.blocks || []).map((clone) => clone.value)).toEqual([
+      'new',
+      'sale'
+    ]);
+  });
+
+  it('reads the entry inside a longer string', () => {
+    const expanded = expandChips(
+      block({
+        id: 'chip',
+        value: 'Tag',
+        properties: { dataBinding: '#{{item}}' }
+      }),
+      { tags: ['new', 'sale'] }
+    );
+
+    expect((expanded.blocks || []).map((clone) => clone.value)).toEqual([
+      '#new',
+      '#sale'
+    ]);
+  });
+
+  it('reads a numeric entry, which carries no keys to count', () => {
+    const expanded = expandChips(
+      block({ id: 'chip', value: 'Size', properties: { dataBinding: 'item' } }),
+      { sizes: [38, 40] },
+      'item.sizes'
+    );
+
+    expect((expanded.blocks || []).map((clone) => clone.value)).toEqual([
+      '38',
+      '40'
+    ]);
+  });
+
+  it('paints the entry when it is the colour itself', () => {
+    const expanded = expandChips(
+      block({ id: 'chip', styles: { 'background-color': '{{item}}' } }),
+      { swatches: ['#ff0000', '#0000ff'] },
+      'item.swatches'
+    );
+
+    expect(
+      (expanded.blocks || []).map(
+        (clone) => (clone.styles as Record<string, unknown>)['background-color']
+      )
+    ).toEqual(['#ff0000', '#0000ff']);
+  });
+});
+
+describe('an iterator keeps the shape it was given', () => {
+  it('does not grow a properties key it never had', () => {
+    const iteratorBlock = {
+      id: 'iterator',
+      type: 'group',
+      label: 'Iterator',
+      order: 0,
+      isIterator: true,
+      blocks: [{ id: 'row', type: 'text', label: 'Row', order: 0, value: 'x' }]
+    } as unknown as Block;
+
+    const expanded = buildIteratorBlock({ iteratorBlock, items: [{}] });
+
+    expect('properties' in expanded).toBe(false);
+  });
+});
+
+describe('a breakpoint never inherits another breakpoint row value', () => {
+  const expandBadge = (
+    responsiveValue: Record<string, unknown>,
+    row: Record<string, unknown>
+  ) =>
+    (buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({ id: 'badge', styles: { 'background-color': responsiveValue } })
+      ),
+      items: [row]
+    }).blocks || [])[0];
+
+  it('unsets the whole property when one breakpoint cannot resolve', () => {
+    // `getResponsiveValue` answers a missing breakpoint with the desktop
+    // value, so leaving desktop behind paints mobile with the desktop row's
+    // colour — the wrong colour, not the unset the author would expect.
+    const clone = expandBadge(
+      {
+        desktop: '{{item.badgeColor}}',
+        mobile: '{{item.badgeColorMobile}}'
+      },
+      { badgeColor: '#00a86b' }
+    );
+
+    expect('background-color' in (clone.styles as Record<string, unknown>)).toBe(
+      false
+    );
+    expect(
+      getCSSStyles(clone.styles as Record<string, unknown>, undefined, 'mobile')
+        .backgroundColor
+    ).toBeUndefined();
+    expect(
+      getCSSStyles(clone.styles as Record<string, unknown>, undefined, 'desktop')
+        .backgroundColor
+    ).toBeUndefined();
+  });
+
+  it('keeps a fully resolved responsive value', () => {
+    const clone = expandBadge(
+      { desktop: '{{item.badgeColor}}', mobile: '{{item.badgeColorMobile}}' },
+      { badgeColor: '#00a86b', badgeColorMobile: '#e63946' }
+    );
+
+    expect((clone.styles as Record<string, unknown>)['background-color']).toEqual(
+      {
+        desktop: '#00a86b',
+        mobile: '#e63946'
+      }
+    );
+  });
+});
+
+describe('a style token addresses the row only when it says so', () => {
+  it('leaves a token that does not address the row to the layer that owns it', () => {
+    // `{{brandColor}}` is a section-level spelling. Resolving it off the row
+    // means a field that happens to share the name decides a site-wide colour.
+    const styles = { 'background-color': '{{brandColor}}' };
+    const clone = (buildIteratorBlock({
+      iteratorBlock: iteratorOf(block({ id: 'card', styles })),
+      items: [{ brandColor: '#00a86b' }]
+    }).blocks || [])[0];
+
+    expect(clone.styles).toBe(styles);
+    expect((clone.styles as Record<string, unknown>)['background-color']).toBe(
+      '{{brandColor}}'
+    );
+  });
+
+  it('unsets a value that mixes a row token with one it cannot resolve', () => {
+    const clone = (buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({ id: 'card', styles: { padding: '{{item.gap}}px {{siteGap}}' } })
+      ),
+      items: [{ gap: 8, siteGap: '12px' }]
+    }).blocks || [])[0];
+
+    expect('padding' in (clone.styles as Record<string, unknown>)).toBe(false);
+  });
+});
+
+describe('a binding can sit inside a longer string', () => {
+  const expandText = (
+    dataBinding: string,
+    row: Record<string, unknown>,
+    overrides: Partial<Block> = {}
+  ) =>
+    (buildIteratorBlock({
+      iteratorBlock: iteratorOf(
+        block({
+          id: 'label',
+          value: 'Authored',
+          properties: { dataBinding },
+          ...overrides
+        })
+      ),
+      items: [row]
+    }).blocks || [])[0];
+
+  it('keeps the literal text around each binding', () => {
+    expect(
+      expandText('Ürün Kodu {{item.base_code}}.{{item.color_code}}', {
+        base_code: 'ABC123',
+        color_code: '42'
+      }).value
+    ).toBe('Ürün Kodu ABC123.42');
+  });
+
+  it('reads a binding followed by literal text', () => {
+    expect(
+      expandText('{{item.colorCount}} Renk', { colorCount: 5 }).value
+    ).toBe('5 Renk');
+  });
+
+  it('writes an empty string for the token that has no data', () => {
+    expect(
+      expandText('{{item.brand}} {{item.model}}', { brand: 'Lacoste' }).value
+    ).toBe('Lacoste ');
+  });
+
+  it('keeps the authored value when nothing at all resolves', () => {
+    expect(
+      expandText('{{item.brand}} {{item.model}}', { other: 1 }).value
+    ).toBe('Authored');
+  });
+
+  it('interpolates into a link target too', () => {
+    const link = expandText(
+      '/p/{{item.slug}}-{{item.pk}}',
+      {
+        slug: 'sneaker',
+        pk: 42
+      },
+      { type: 'link' }
+    );
+
+    expect(link.properties.href).toBe('/p/sneaker-42');
+  });
+});
+
+describe('a value that is exactly one binding still returns the raw value', () => {
+  const expandBoth = (
+    path: string,
+    row: Record<string, unknown>,
+    type = 'text'
+  ) => {
+    const run = (dataBinding: string) =>
+      (buildIteratorBlock({
+        iteratorBlock: iteratorOf(
+          block({ id: 'target', type, properties: { dataBinding } })
+        ),
+        items: [row]
+      }).blocks || [])[0];
+
+    // The binding string itself is kept verbatim on the clone, so it is the
+    // one thing that legitimately differs between the two spellings.
+    const withoutBinding = (clone: Block) => ({
+      ...clone,
+      properties: { ...clone.properties, dataBinding: undefined }
+    });
+
+    return {
+      bare: withoutBinding(run(path)),
+      wrapped: withoutBinding(run(`{{${path}}}`))
+    };
+  };
+
+  it.each([
+    ['a string', 'item.name', { name: 'Sneaker' }, 'text'],
+    ['a number', 'item.stock', { stock: 0 }, 'text'],
+    ['a boolean', 'item.inStock', { inStock: false }, 'text'],
+    [
+      'an image object',
+      'item.image',
+      { image: { url: 'https://cdn.example.com/a.jpg' } },
+      'image'
+    ],
+    ['a price', 'item.price', { price: 199.9, currency_type: 'TRY' }, 'text']
+  ])('%s behaves the same wrapped as bare', (_label, path, row, type) => {
+    const { bare, wrapped } = expandBoth(
+      path as string,
+      row as Record<string, unknown>,
+      type as string
+    );
+
+    expect(wrapped).toEqual(bare);
+  });
+});
+
+describe('section-level bindings interpolate too', () => {
+  const sectionDataSource = {
+    type: 'page-context',
+    details: { pageContext: { pageType: 'product', rootPath: 'product' } }
+  };
+
+  it('mixes literal text with page-context values', () => {
+    const resolved = resolveBlockBindings({
+      block: block({
+        id: 'greeting',
+        value: 'Fallback',
+        properties: {
+          dataBinding: '{{customer.firstName}} için {{product.title}}'
+        }
+      }),
+      sectionDataSource,
+      pageContext: {
+        customer: { firstName: 'Esma' },
+        product: { title: 'Sneaker' }
+      }
+    });
+
+    expect(resolved.value).toBe('Esma için Sneaker');
+  });
+
+  it('leaves a row-scoped template to the iterator', () => {
+    // The iterator has already written the row's value; re-resolving against
+    // the section would blank it back out.
+    const resolved = resolveBlockBindings({
+      block: block({
+        id: 'code',
+        value: 'Ürün Kodu ABC123',
+        properties: { dataBinding: 'Ürün Kodu {{item.base_code}}' }
+      }),
+      sectionDataSource,
+      pageContext: { base_code: 'WRONG' }
+    });
+
+    expect(resolved.value).toBe('Ürün Kodu ABC123');
+  });
+});
+
+describe('a mistyped row-scoped list path is diagnosable', () => {
+  const warnSpy = () => jest.spyOn(console, 'warn').mockImplementation(() => undefined);
+
+  const productWithScalarColour = {
+    type: 'collection',
+    details: { collection: { data: [{ title: 'Tee', colour: 'red' }] } }
+  };
+
+  const stripBoundTo = (path: string): Block =>
+    iteratorOf(
+      block({
+        id: 'card',
+        type: 'group',
+        blocks: [
+          block({
+            id: 'strip',
+            type: 'group',
+            isIterator: true,
+            iteratorDataPath: path,
+            blocks: [block({ id: 'swatch', value: 'Colour' })]
+          })
+        ]
+      })
+    );
+
+  /** Same two-pass expansion theme-section performs. */
+  const expand = (root: Block): Block => {
+    const resolved = root.isIterator
+      ? buildIteratorBlock({
+          iteratorBlock: root,
+          sectionDataSource: productWithScalarColour
+        })
+      : root;
+    if (!resolved.blocks?.length) return resolved;
+    return { ...resolved, blocks: resolved.blocks.map(expand) };
+  };
+
+  it('warns when the row answers the path with something that is not a list', () => {
+    // `item.colour` is a string, not `item.colours`. The repeat now draws no
+    // rows at all, so without a warning the author sees an empty strip and no
+    // clue that the path is the problem — the same typo against a SECTION path
+    // has always been reported.
+    const warn = warnSpy();
+    try {
+      expand(stripBoundTo('item.colour'));
+      expect(warn).toHaveBeenCalledWith(
+        expect.stringContaining('item.colour')
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('stays silent when the row simply has no such field yet', () => {
+    // Absent is ambiguous with data that has not landed, exactly as the
+    // section-scoped path treats an unresolved lookup.
+    const warn = warnSpy();
+    try {
+      expand(stripBoundTo('item.not_here'));
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('stays silent when the row answers with a real list', () => {
+    const warn = warnSpy();
+    try {
+      buildIteratorBlock({
+        iteratorBlock: stripBoundTo('item.colours'),
+        sectionDataSource: {
+          type: 'collection',
+          details: { collection: { data: [{ colours: [{ hex: '#ff0000' }] }] } }
+        }
+      });
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});