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

package/src/utils/__tests__/breakpoint-cascade.test.ts

@@ -0,0 +1,351 @@
+/**
+ * The third breakpoint.
+ *
+ * Two things have to be true at once and they pull against each other: a
+ * composition that never heard of a tablet must emit the bytes it emitted
+ * before, and a composition that authors one must actually get it — at the
+ * device, at the canvas and in the stylesheet, all saying the same thing.
+ *
+ * The tests below are ordered by what they protect. First that nothing moved.
+ * Then that the cascade resolves the same way whichever of the three readers
+ * you ask. Then the media-query order, which is the only reason a tablet rule
+ * beats the mobile rule it sits inside — equal specificity, so source position
+ * decides, and asserting it is cheaper than rediscovering it in production.
+ */
+import {
+  generateThemeCSS,
+  getResponsiveValue,
+  buildCustomCss,
+  DESKTOP_MIN_WIDTH,
+  TABLET_MIN_WIDTH,
+  MOBILE_MEDIA_QUERY,
+  TABLET_MEDIA_QUERY,
+  breakpointForWidth,
+  isNarrowBreakpoint
+} from '../index';
+import { isBreakpointAllowed } from '../visibility-rules';
+
+const section = (styles: Record<string, unknown>, id = 's1') => [
+  { id, styles } as never
+];
+
+/**
+ * The declarations that actually apply at `width`, in cascade order, for a
+ * stylesheet this generator produced. Every rule it emits carries the same
+ * selector and therefore the same specificity, so the last matching
+ * declaration for a property wins — which makes "later in the string" the
+ * whole tie-break, and lets this read the CSS the way a browser would.
+ */
+const computedAt = (css: string, width: number): Record<string, string> => {
+  const applied: Record<string, string> = {};
+
+  const queryMatches = (prelude: string): boolean => {
+    const max = prelude.match(/max-width:\s*(\d+)px/);
+    const min = prelude.match(/min-width:\s*(\d+)px/);
+    if (max && width > Number(max[1])) return false;
+    if (min && width < Number(min[1])) return false;
+    return true;
+  };
+
+  const readDeclarations = (body: string) => {
+    body.split(';').forEach((declaration) => {
+      const [property, ...rest] = declaration.split(':');
+      if (rest.length === 0) return;
+      const name = property.trim();
+      if (!name || name.startsWith('@')) return;
+      applied[name] = rest.join(':').trim();
+    });
+  };
+
+  // Walk top level: either `@media (...) { <rules> }` or `selector { ... }`.
+  let index = 0;
+  while (index < css.length) {
+    const open = css.indexOf('{', index);
+    if (open === -1) break;
+
+    const prelude = css.slice(index, open).trim();
+    let depth = 0;
+    let close = open;
+    for (let i = open; i < css.length; i++) {
+      if (css[i] === '{') depth += 1;
+      else if (css[i] === '}') {
+        depth -= 1;
+        if (depth === 0) {
+          close = i;
+          break;
+        }
+      }
+    }
+
+    const body = css.slice(open + 1, close);
+
+    if (prelude.startsWith('@media')) {
+      if (queryMatches(prelude)) {
+        // One nested rule per band in this generator's output.
+        const innerOpen = body.indexOf('{');
+        if (innerOpen !== -1) {
+          readDeclarations(body.slice(innerOpen + 1, body.lastIndexOf('}')));
+        }
+      }
+    } else if (!prelude.includes(':hover')) {
+      readDeclarations(body);
+    }
+
+    index = close + 1;
+  }
+
+  return applied;
+};
+
+describe('the two boundaries', () => {
+  it('keeps the existing line at 1023/1024 and puts the new one at 767/768', () => {
+    expect(DESKTOP_MIN_WIDTH).toBe(1024);
+    expect(TABLET_MIN_WIDTH).toBe(768);
+    expect(MOBILE_MEDIA_QUERY).toBe('@media (max-width: 1023px)');
+    expect(TABLET_MEDIA_QUERY).toBe(
+      '@media (min-width: 768px) and (max-width: 1023px)'
+    );
+  });
+
+  it('classifies a width on each side of both lines, and exactly on them', () => {
+    expect(breakpointForWidth(1440)).toBe('desktop');
+    expect(breakpointForWidth(1024)).toBe('desktop');
+    expect(breakpointForWidth(1023)).toBe('tablet');
+    expect(breakpointForWidth(768)).toBe('tablet');
+    expect(breakpointForWidth(767)).toBe('mobile');
+    expect(breakpointForWidth(390)).toBe('mobile');
+  });
+
+  it('counts a tablet as narrower than desktop, which is what the old code asked', () => {
+    expect(isNarrowBreakpoint('tablet')).toBe(true);
+    expect(isNarrowBreakpoint('mobile')).toBe(true);
+    expect(isNarrowBreakpoint('desktop')).toBe(false);
+    expect(isNarrowBreakpoint(undefined)).toBe(false);
+  });
+});
+
+describe('nothing authored at the new breakpoint changes anything', () => {
+  it('emits the exact stylesheet it emitted before, with no tablet rule', () => {
+    const css = generateThemeCSS(
+      section({
+        'font-size': { desktop: '20px', mobile: '14px' },
+        color: { desktop: '#111', mobile: '#111' }
+      })
+    );
+
+    expect(css).toBe(
+      '[data-section-id="s1"] {\n' +
+        '  font-size: 20px;\n' +
+        '  color: #111;\n' +
+        '}\n' +
+        '@media (max-width: 1023px) {\n' +
+        '  [data-section-id="s1"] {\n' +
+        '    font-size: 14px;\n' +
+        '  }\n' +
+        '}\n'
+    );
+    expect(css).not.toContain('min-width');
+  });
+
+  it('leaves a tablet reading the mobile value, exactly as the old query did', () => {
+    const css = generateThemeCSS(
+      section({ 'font-size': { desktop: '20px', mobile: '14px' } })
+    );
+
+    expect(computedAt(css, 1440)['font-size']).toBe('20px');
+    expect(computedAt(css, 900)['font-size']).toBe('14px');
+    expect(computedAt(css, 500)['font-size']).toBe('14px');
+  });
+
+  it('does not write a rule for a tablet value equal to what it would inherit', () => {
+    const redundantAgainstMobile = generateThemeCSS(
+      section({ gap: { desktop: '24px', tablet: '12px', mobile: '12px' } })
+    );
+    expect(redundantAgainstMobile).not.toContain('min-width');
+
+    const redundantAgainstDesktop = generateThemeCSS(
+      section({ gap: { desktop: '24px', tablet: '24px' } })
+    );
+    expect(redundantAgainstDesktop).not.toContain('min-width');
+  });
+});
+
+describe('a value authored only at tablet', () => {
+  const css = generateThemeCSS(
+    section({
+      'grid-template-columns': {
+        desktop: 'repeat(4, 1fr)',
+        tablet: 'repeat(3, 1fr)',
+        mobile: 'repeat(2, 1fr)'
+      }
+    })
+  );
+
+  it('applies at each of the three widths', () => {
+    expect(computedAt(css, 1440)['grid-template-columns']).toBe(
+      'repeat(4, 1fr)'
+    );
+    expect(computedAt(css, 900)['grid-template-columns']).toBe('repeat(3, 1fr)');
+    expect(computedAt(css, 500)['grid-template-columns']).toBe('repeat(2, 1fr)');
+  });
+
+  it('applies exactly on each boundary, on both sides', () => {
+    expect(computedAt(css, 1024)['grid-template-columns']).toBe(
+      'repeat(4, 1fr)'
+    );
+    expect(computedAt(css, 1023)['grid-template-columns']).toBe(
+      'repeat(3, 1fr)'
+    );
+    expect(computedAt(css, 768)['grid-template-columns']).toBe('repeat(3, 1fr)');
+    expect(computedAt(css, 767)['grid-template-columns']).toBe('repeat(2, 1fr)');
+  });
+
+  it('reaches the tablet band even when no mobile value was authored', () => {
+    const noMobile = generateThemeCSS(
+      section({ padding: { desktop: '40px', tablet: '20px' } })
+    );
+
+    expect(computedAt(noMobile, 1440).padding).toBe('40px');
+    expect(computedAt(noMobile, 900).padding).toBe('20px');
+    // Nothing narrower was authored, so a phone keeps the desktop value —
+    // the same answer the reader gives, and the same one it gave before.
+    expect(computedAt(noMobile, 500).padding).toBe('40px');
+  });
+});
+
+describe('media query order is the mechanism, so it is asserted not assumed', () => {
+  it('writes the tablet query after the mobile one', () => {
+    const css = generateThemeCSS(
+      section({ gap: { desktop: '24px', tablet: '16px', mobile: '8px' } })
+    );
+
+    const mobileAt = css.indexOf(MOBILE_MEDIA_QUERY);
+    const tabletAt = css.indexOf(TABLET_MEDIA_QUERY);
+
+    expect(mobileAt).toBeGreaterThan(-1);
+    expect(tabletAt).toBeGreaterThan(-1);
+    expect(tabletAt).toBeGreaterThan(mobileAt);
+  });
+
+  it('keeps that order for every block in a composition, not just the first', () => {
+    const css = generateThemeCSS([
+      {
+        id: 'sec',
+        styles: { gap: { desktop: '4px', tablet: '3px', mobile: '2px' } },
+        blocks: [
+          {
+            id: 'b1',
+            styles: { gap: { desktop: '8px', tablet: '6px', mobile: '4px' } }
+          },
+          {
+            id: 'b2',
+            styles: { gap: { desktop: '9px', tablet: '7px', mobile: '5px' } }
+          }
+        ]
+      } as never
+    ]);
+
+    // Each selector's own mobile rule must precede its own tablet rule.
+    ['sec', 'b1', 'b2'].forEach((id) => {
+      const attribute = id === 'sec' ? 'data-section-id' : 'data-block-id';
+      const selector = `[${attribute}="${id}"]`;
+      const mobileAt = css.indexOf(`${MOBILE_MEDIA_QUERY} {\n  ${selector}`);
+      const tabletAt = css.indexOf(`${TABLET_MEDIA_QUERY} {\n  ${selector}`);
+
+      expect(mobileAt).toBeGreaterThan(-1);
+      expect(tabletAt).toBeGreaterThan(mobileAt);
+    });
+  });
+
+  it('orders the scoped custom-CSS hatch the same way', () => {
+    const css = buildCustomCss(
+      {
+        customCss: {
+          desktop: 'color: red;',
+          tablet: 'color: green;',
+          mobile: 'color: blue;'
+        }
+      },
+      '[data-block-id="b"]'
+    );
+
+    expect(css.indexOf(TABLET_MEDIA_QUERY)).toBeGreaterThan(
+      css.indexOf(MOBILE_MEDIA_QUERY)
+    );
+    expect(computedAt(css, 900).color).toBe('green');
+    expect(computedAt(css, 500).color).toBe('blue');
+    expect(computedAt(css, 1440).color).toBe('red');
+  });
+});
+
+describe('the readers agree with the stylesheet', () => {
+  const authored = { desktop: '20px', tablet: '16px', mobile: '12px' };
+  const noTablet = { desktop: '20px', mobile: '12px' };
+
+  it('resolves the same value the cascade produces, at every breakpoint', () => {
+    const css = generateThemeCSS(section({ 'font-size': authored }));
+
+    ([
+      ['desktop', 1440],
+      ['tablet', 900],
+      ['mobile', 500]
+    ] as const).forEach(([breakpoint, width]) => {
+      expect(getResponsiveValue(authored, breakpoint)).toBe(
+        computedAt(css, width)['font-size']
+      );
+    });
+  });
+
+  it('falls through tablet -> mobile -> desktop, matching the cascade', () => {
+    const css = generateThemeCSS(section({ 'font-size': noTablet }));
+
+    expect(getResponsiveValue(noTablet, 'tablet')).toBe('12px');
+    expect(getResponsiveValue(noTablet, 'tablet')).toBe(
+      computedAt(css, 900)['font-size']
+    );
+
+    expect(getResponsiveValue({ desktop: '20px' }, 'tablet')).toBe('20px');
+  });
+
+  it('leaves desktop and mobile resolving exactly as they always did', () => {
+    expect(getResponsiveValue(noTablet, 'desktop')).toBe('20px');
+    expect(getResponsiveValue(noTablet, 'mobile')).toBe('12px');
+    // A tablet value must not leak into the mobile answer.
+    expect(getResponsiveValue({ desktop: '20px', tablet: '16px' }, 'mobile')).toBe(
+      '20px'
+    );
+    expect(getResponsiveValue(undefined, 'tablet', 'fallback')).toBe('fallback');
+  });
+
+  it('shows the canvas the value the device will render', () => {
+    // The designer path asks for one breakpoint and gets a single flat rule;
+    // it has to be the same declaration the storefront cascade lands on.
+    const storefront = generateThemeCSS(section({ 'font-size': noTablet }));
+    const canvas = generateThemeCSS(section({ 'font-size': noTablet }), 'tablet');
+
+    expect(canvas).toContain('font-size: 12px');
+    expect(computedAt(canvas, 900)['font-size']).toBe(
+      computedAt(storefront, 900)['font-size']
+    );
+  });
+});
+
+describe('visibility rules survive the third breakpoint', () => {
+  it('keeps a published mobile-only rule showing on a tablet', () => {
+    // This is the regression that a literal read would cause on compositions
+    // nobody touched: `mobile` meant everything below 1024 when it was saved.
+    expect(isBreakpointAllowed(['mobile'], 'tablet')).toBe(true);
+    expect(isBreakpointAllowed(['mobile'], 'mobile')).toBe(true);
+    expect(isBreakpointAllowed(['mobile'], 'desktop')).toBe(false);
+  });
+
+  it('keeps a desktop-only rule hidden on a tablet', () => {
+    expect(isBreakpointAllowed(['desktop'], 'tablet')).toBe(false);
+    expect(isBreakpointAllowed(['desktop'], 'desktop')).toBe(true);
+  });
+
+  it('reads a rule that names the tablet literally', () => {
+    expect(isBreakpointAllowed(['desktop', 'tablet'], 'tablet')).toBe(true);
+    expect(isBreakpointAllowed(['desktop', 'tablet'], 'mobile')).toBe(false);
+  });
+});

package/src/utils/__tests__/group-box-chrome.test.ts

@@ -0,0 +1,83 @@
+import { generateThemeCSS } from '../index';
+
+/**
+ * The Group descriptor in pz-dynamic-widget gained the box chrome a container
+ * needs — background colour, border, size, overflow, shadow. That was a
+ * descriptor-only change, and this is why: the group renderer draws
+ * `className="contents"` and styles nothing itself, while `collectBlockCSS`
+ * emits every root style key of a block onto its `[data-block-id]` wrapper.
+ *
+ * These lock that route. If someone later teaches the group renderer to consume
+ * styles itself, or narrows the CSS generator to a known-key allowlist, the
+ * controls the editor now offers would go quiet — and this fails first.
+ */
+const groupSection = (styles: Record<string, unknown>) => [
+  {
+    id: 'sec-1',
+    blocks: [{ id: 'grp-1', type: 'group', styles } as never]
+  }
+];
+
+describe('group box chrome reaches the stylesheet', () => {
+  it('emits every chrome key onto the block wrapper', () => {
+    const css = generateThemeCSS(
+      groupSection({
+        'background-color': '#ffffff',
+        'border-style': 'solid',
+        'border-width': '1px',
+        'border-color': '#e5e7eb',
+        'border-radius': '12px',
+        width: '320px',
+        height: '200px',
+        'min-height': '120px',
+        'max-width': '1200px',
+        overflow: 'hidden',
+        'box-shadow': '0 4px 6px -1px rgba(0, 0, 0, 0.1)'
+      }) as never
+    );
+
+    expect(css).toContain('[data-block-id="grp-1"]');
+    // Hex is normalised to rgba by the existing background-opacity maths.
+    expect(css).toContain('background-color: rgba(255, 255, 255, 1)');
+    expect(css).toContain('border-style: solid');
+    expect(css).toContain('border-width: 1px');
+    expect(css).toContain('border-color: #e5e7eb');
+    expect(css).toContain('border-radius: 12px');
+    expect(css).toContain('width: 320px');
+    expect(css).toContain('height: 200px');
+    expect(css).toContain('min-height: 120px');
+    expect(css).toContain('max-width: 1200px');
+    expect(css).toContain('overflow: hidden');
+    expect(css).toContain('box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1)');
+  });
+
+  it('honours a per-breakpoint chrome value', () => {
+    const css = generateThemeCSS(
+      groupSection({
+        'border-radius': { desktop: '12px', mobile: '0px' }
+      }) as never
+    );
+
+    expect(css).toContain('border-radius: 12px');
+    expect(css).toContain('@media (max-width: 1023px)');
+    expect(css).toContain('border-radius: 0px');
+  });
+
+  it('writes nothing for a group that was never given any chrome', () => {
+    // The controls all ship without a default, so this is the shape every
+    // existing composition still has: no chrome keys, no chrome CSS.
+    const css = generateThemeCSS(
+      groupSection({
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '0px'
+      }) as never
+    );
+
+    expect(css).not.toContain('background-color');
+    expect(css).not.toContain('border');
+    expect(css).not.toContain('overflow');
+    expect(css).not.toContain('box-shadow');
+    expect(css).not.toContain('max-width');
+  });
+});