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

package/src/utils/__tests__/part-ownership-guard.test.tsx

@@ -0,0 +1,298 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import ThemeBlock from '../../theme-block';
+import { generateThemeCSS } from '../index';
+import { buildPartSelectors } from '../part-styles';
+import { buildIteratorBlock } from '../iterator-utils';
+import type { Section } from '../../theme-section';
+
+/**
+ * The part-ownership guard, pushed past the two-block case.
+ *
+ * A part rule is confined to its declaring block by excluding anything sitting
+ * inside a nested block. That is only safe while two things hold, and neither
+ * is obvious by reading the selector:
+ *
+ *   1. no renderer draws its own part inside a child block's wrapper — if one
+ *      did, the guard would delete a style the block legitimately owns;
+ *   2. the exclusion reaches all the way down, not just one level.
+ *
+ * Both are asserted here against shipped renderers and against repeated rows,
+ * where clones deliberately share one style identity.
+ */
+
+const group = (id: string, label: string, children: unknown[] = []) => ({
+  id,
+  type: 'group',
+  label,
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false,
+  blocks: children
+});
+
+const text = (id: string) => ({
+  id,
+  type: 'text',
+  label: 'Text',
+  value: '<p>copy</p>',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false
+});
+
+const accordion = (
+  id: string,
+  styles: Record<string, unknown> = {},
+  inner?: unknown[]
+) => ({
+  id,
+  type: 'accordion',
+  label: 'Accordion',
+  value: '',
+  properties: { defaultOpen: true },
+  styles,
+  order: 0,
+  hidden: false,
+  blocks: [
+    group(`${id}-heading`, 'Accordion Heading', [text(`${id}-title`)]),
+    group(`${id}-content`, 'Accordion Content', inner || [text(`${id}-copy`)])
+  ]
+});
+
+const sectionOf = (root: unknown): Section[] =>
+  [
+    {
+      id: 'sec-1',
+      type: 'custom',
+      name: 'Section',
+      label: 'Section',
+      order: 0,
+      hidden: false,
+      properties: {},
+      styles: {},
+      blocks: [root]
+    }
+  ] as unknown as Section[];
+
+const renderRoot = (root: unknown) =>
+  render(
+    <ThemeBlock
+      block={root as never}
+      placeholderId="p"
+      sectionId="sec-1"
+      isDesigner={false}
+    />
+  );
+
+/** Every selector the generated stylesheet aims at the given part. */
+const selectorsFor = (css: string, part: string): string[] =>
+  css
+    .split('}')
+    .map((chunk) => chunk.slice(0, chunk.indexOf('{')))
+    .filter((selector) => selector.includes(`[data-part="${part}"]`))
+    .flatMap((selector) => selector.split(',').map((one) => one.trim()))
+    .filter(Boolean);
+
+const ownersOf = (root: HTMLElement, selectors: string[]): string[] => {
+  const owners = new Set<string>();
+
+  selectors.forEach((selector) => {
+    root.querySelectorAll<HTMLElement>(selector).forEach((element) => {
+      owners.add(
+        element.closest('[data-block-id]')?.getAttribute('data-block-id') || '?'
+      );
+    });
+  });
+
+  return Array.from(owners).sort();
+};
+
+const partSelector = (blockId: string, part: string): string =>
+  buildPartSelectors(`[data-block-id="${blockId}"]`, {
+    part,
+    state: null,
+    styles: {}
+  })[0];
+
+/**
+ * Every `data-part` element in the tree, checked against the rule its OWN
+ * block would generate. A non-empty result means the guard deleted a style the
+ * block owns — the one way this fix could be worse than the leak it replaces.
+ */
+const partsTheirOwnBlockCannotReach = (root: HTMLElement): string[] => {
+  const broken: string[] = [];
+
+  root.querySelectorAll<HTMLElement>('[data-part]').forEach((element) => {
+    const owner = element.closest('[data-block-id]');
+    if (!owner) return;
+
+    const ownerId = owner.getAttribute('data-block-id') as string;
+    const part = element.getAttribute('data-part') as string;
+    const selector = partSelector(ownerId, part);
+
+    if (selector && !element.matches(selector)) {
+      broken.push(`${ownerId}/${part}`);
+    }
+  });
+
+  return Array.from(new Set(broken)).sort();
+};
+
+describe('the guard reaches every level, not just the first', () => {
+  const nest = (styled: string) =>
+    accordion(
+      'lvl1',
+      styled === 'lvl1' ? { 'header/color': { desktop: '#f00' } } : {},
+      [
+        accordion(
+          'lvl2',
+          styled === 'lvl2' ? { 'header/color': { desktop: '#f00' } } : {},
+          [
+            accordion(
+              'lvl3',
+              styled === 'lvl3' ? { 'header/color': { desktop: '#f00' } } : {}
+            )
+          ]
+        )
+      ]
+    );
+
+  it.each(['lvl1', 'lvl2', 'lvl3'])(
+    'a header style on %s reaches that block and no other',
+    (level) => {
+      const css = generateThemeCSS(sectionOf(nest(level)));
+      const { container } = renderRoot(nest('none'));
+
+      // Premise: three blocks really do name a header the same way.
+      expect(container.querySelectorAll('[data-part="header"]')).toHaveLength(3);
+      expect(ownersOf(container, selectorsFor(css, 'header'))).toEqual([level]);
+    }
+  );
+
+  it('holds on every breakpoint, not only the one that was tested', () => {
+    const styled = accordion(
+      'outer',
+      { 'header/color': { desktop: '#f00', mobile: '#0f0' } },
+      [accordion('inner')]
+    );
+
+    ['desktop', 'mobile', undefined].forEach((breakpoint) => {
+      const css = generateThemeCSS(sectionOf(styled), breakpoint);
+      const { container, unmount } = renderRoot(
+        accordion('outer', {}, [accordion('inner')])
+      );
+      const selectors = selectorsFor(css, 'header');
+
+      expect(selectors.length).toBeGreaterThan(0);
+      expect(ownersOf(container, selectors)).toEqual(['outer']);
+      unmount();
+    });
+  });
+});
+
+describe('the guard never costs a block a part it owns', () => {
+  // The breadth case — one tree built from many part-stamped renderers — lands
+  // with the renderer vocabulary itself. Only a handful of renderers name their
+  // internals at this point, so asserting a wide sweep here would either be
+  // vacuous or force the whole block catalogue into this change.
+
+  it('across repeated rows, which share one style identity', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: {
+        id: 'it-1',
+        type: 'group',
+        label: 'Repeat',
+        isIterator: true,
+        blocks: [accordion('tpl')]
+      } as never,
+      items: [{ a: 1 }, { a: 2 }, { a: 3 }]
+    });
+
+    const { container } = renderRoot(
+      accordion('shell', {}, (expanded.blocks || []) as unknown[])
+    );
+
+    // One authored rule, three rows: the clones keep the template's identity,
+    // so the rule has to keep matching all of them.
+    expect(container.querySelectorAll(partSelector('tpl', 'header'))).toHaveLength(3);
+    expect(container.querySelectorAll(partSelector('shell', 'header'))).toHaveLength(1);
+    expect(partsTheirOwnBlockCannotReach(container)).toEqual([]);
+  });
+
+  it('across a repeat inside a repeat', () => {
+    const inner = buildIteratorBlock({
+      iteratorBlock: {
+        id: 'it-inner',
+        type: 'group',
+        label: 'Repeat',
+        isIterator: true,
+        blocks: [accordion('tpl-inner')]
+      } as never,
+      items: [{ a: 1 }, { a: 2 }]
+    });
+    const outer = buildIteratorBlock({
+      iteratorBlock: {
+        id: 'it-outer',
+        type: 'group',
+        label: 'Repeat',
+        isIterator: true,
+        blocks: [accordion('tpl-outer', {}, (inner.blocks || []) as unknown[])]
+      } as never,
+      items: [{ a: 1 }, { a: 2 }]
+    });
+
+    const { container } = renderRoot(
+      accordion('shell', {}, (outer.blocks || []) as unknown[])
+    );
+
+    expect(container.querySelectorAll(partSelector('tpl-outer', 'header'))).toHaveLength(2);
+    expect(container.querySelectorAll(partSelector('tpl-inner', 'header'))).toHaveLength(4);
+    expect(partsTheirOwnBlockCannotReach(container)).toEqual([]);
+  });
+});
+
+describe('a composition that names no part', () => {
+  it('is generated without a guard anywhere in it', () => {
+    // The feature is off until a designer types a part key; the stylesheet a
+    // published composition already ships must come out exactly as before.
+    const css = generateThemeCSS(
+      sectionOf(
+        accordion(
+          'outer',
+          { backgroundColor: { desktop: '#fff' }, padding: { desktop: '8px' } },
+          [accordion('inner')]
+        )
+      )
+    );
+
+    expect(css).toContain('[data-block-id="outer"]');
+    expect(css).not.toContain(':where(');
+    expect(css).not.toContain(':not(');
+  });
+});
+
+describe('a block id that did not come from us', () => {
+  it('stays inside the quoted value on both copies of the selector', () => {
+    // The guard repeats the block selector, so a crafted id gets two chances
+    // to break out of the quoted value instead of one.
+    const css = generateThemeCSS(
+      sectionOf({
+        ...accordion('safe', { 'header/color': { desktop: '#f00' } }),
+        styleSourceId: 'a"] , * { color: red } [x="'
+      })
+    );
+
+    // Whatever escaping the block selector received, the guard's copy of it is
+    // the identical string — so the guard cannot be the weaker of the two and
+    // the id gets no second chance at breaking out.
+    const blockSelector = css.slice(0, css.indexOf(' [data-part='));
+
+    expect(blockSelector).toContain('\\"');
+    expect(css).toContain(
+      `:not(:where(${blockSelector} [data-block-id] *))`
+    );
+  });
+});

package/src/utils/breakpoints.ts

@@ -0,0 +1,116 @@
+/**
+ * The breakpoints, and the two lines between them.
+ *
+ * There used to be one line. `1023px` was written out as a literal in the CSS
+ * generator, in the custom-CSS hatch and in six block renderers that emit their
+ * own scoped `<style>`; the number agreeing everywhere was a matter of nobody
+ * mistyping it. It lives here now, and the media-query strings are built from
+ * it rather than repeated.
+ *
+ * Where the second line sits was not invented. Every brand that ships a
+ * Tailwind config uses the same two stops — superstep_zero, whites-pz,
+ * occasion_next, lacostetr_next, minycenter-next-pz and next-barcin all
+ * declare `md: 768px` and `lg: 1024px`, and every hand-written tablet rule in
+ * those repos is written against one of them. The editor's own
+ * `DEFAULT_BREAKPOINTS` already listed a 768px tablet it had no way to author,
+ * and `posts-slider-section` already carried a `{ min: 768, max: 1023 }` band.
+ * So: desktop at 1024 and up, tablet 768-1023, mobile 767 and down.
+ *
+ * ## What a value at one breakpoint means for the others
+ *
+ * Desktop-first, because that is what the existing output already is: the
+ * desktop value is the unconditional rule and narrower breakpoints override it
+ * inside a `max-width` query. A third breakpoint does not get to introduce a
+ * second convention.
+ *
+ * `mobile` keeps the meaning it has always had — *narrower than desktop*,
+ * everything below 1024 — and `tablet` is a narrower override layered on top of
+ * it inside its own band. Read as a fall-through chain:
+ *
+ *   desktop -> (authored desktop)
+ *   mobile  -> mobile  ?? desktop
+ *   tablet  -> tablet  ?? mobile ?? desktop
+ *
+ * which is exactly what the emitted cascade produces at each width, given the
+ * query order in `generateElementCSS`. That equivalence is the whole point: the
+ * renderer, the editor canvas and the stylesheet cannot disagree because they
+ * are three readings of the same chain.
+ *
+ * It is also the only choice that leaves today's compositions alone. Every
+ * published composition authors desktop and mobile and nothing else, and on
+ * those, tablet resolves to the mobile value and no tablet rule is emitted —
+ * byte for byte the stylesheet it produced before.
+ */
+
+/** Narrowest width that is still "desktop". The existing line, unmoved. */
+export const DESKTOP_MIN_WIDTH = 1024;
+
+/** Narrowest width that is still "tablet". Below this is a phone. */
+export const TABLET_MIN_WIDTH = 768;
+
+export type BreakpointName = 'desktop' | 'tablet' | 'mobile';
+
+/** Widest first, which is also authoring order in the editor. */
+export const BREAKPOINTS: BreakpointName[] = ['desktop', 'tablet', 'mobile'];
+
+/**
+ * Where a breakpoint looks when it has nothing authored of its own. Absence
+ * falls through; it never resolves to an empty value.
+ *
+ * `desktop` and `mobile` are absent from this map on purpose — they behave
+ * exactly as they did before this file existed (`mobile` falls straight back to
+ * `desktop`, which the readers do unconditionally).
+ */
+export const BREAKPOINT_FALLBACKS: Record<string, BreakpointName[]> = {
+  tablet: ['mobile']
+};
+
+/**
+ * The mobile query, unchanged and deliberately still `max-width: 1023px`
+ * rather than being narrowed to 767. Narrowing it would hand the 768-1023 band
+ * back to the desktop rule, which is a different-looking tablet on every
+ * composition already published.
+ */
+export const MOBILE_MEDIA_QUERY = `@media (max-width: ${
+  DESKTOP_MIN_WIDTH - 1
+}px)`;
+
+/**
+ * The tablet query. Emitted *after* the mobile query and at equal specificity,
+ * so within 768-1023 it is source order that makes tablet win — see
+ * `generateElementCSS`, and `breakpoint-cascade.test.ts` which asserts the
+ * order rather than trusting it.
+ */
+export const TABLET_MEDIA_QUERY = `@media (min-width: ${TABLET_MIN_WIDTH}px) and (max-width: ${
+  DESKTOP_MIN_WIDTH - 1
+}px)`;
+
+/**
+ * The same two queries without the spaces, for the scoped `<style>` a handful
+ * of block renderers inline next to their markup. They were written compact and
+ * are asserted compact by tests that pin those blocks' HTML.
+ */
+export const MOBILE_MEDIA_QUERY_COMPACT = `@media (max-width:${
+  DESKTOP_MIN_WIDTH - 1
+}px)`;
+
+export const TABLET_MEDIA_QUERY_COMPACT = `@media (min-width:${TABLET_MIN_WIDTH}px) and (max-width:${
+  DESKTOP_MIN_WIDTH - 1
+}px)`;
+
+/** The breakpoint a viewport of this width is being read at. */
+export const breakpointForWidth = (width: number): BreakpointName => {
+  if (width >= DESKTOP_MIN_WIDTH) return 'desktop';
+  if (width >= TABLET_MIN_WIDTH) return 'tablet';
+  return 'mobile';
+};
+
+/**
+ * "Narrower than desktop" — the question the code that predates the tablet was
+ * actually asking whenever it compared against `'mobile'`. Answering it with a
+ * predicate rather than an equality check is what keeps those call sites
+ * behaving at 768-1023 exactly as they did when `'mobile'` was the only other
+ * value there was.
+ */
+export const isNarrowBreakpoint = (breakpoint?: string): boolean =>
+  breakpoint === 'mobile' || breakpoint === 'tablet';

package/src/utils/custom-css.ts

@@ -0,0 +1,233 @@
+/**
+ * The escape hatch.
+ *
+ * Named parts and state controls cover the cases we anticipated. They will
+ * never cover all of them — a brand will always turn up wanting the third
+ * facet chip on mobile to wrap differently. Rather than grow the descriptor
+ * list forever, a block can carry raw CSS scoped to itself, where `&` is the
+ * block and `data-part` names its internals:
+ *
+ *   & [data-part="dropdown"] { border-radius: 0; }
+ *   & [data-part="option"][data-state~="selected"] { outline: 2px solid; }
+ *
+ * The block selector is prepended to anything that does not already mention
+ * `&`, so a designer cannot accidentally restyle the rest of the page. That
+ * containment is the point: this is a scoped hatch, not a stylesheet.
+ */
+
+import { MOBILE_MEDIA_QUERY, TABLET_MEDIA_QUERY } from './breakpoints';
+
+/** Nothing here is a legitimate need in a block's scoped CSS, and each is a way out of it. */
+const FORBIDDEN = [
+  /@import\b/i,
+  /@charset\b/i,
+  /javascript\s*:/i,
+  /expression\s*\(/i,
+  /behavior\s*:/i,
+  /-moz-binding/i,
+  /<\s*\/?\s*style/i,
+  /<\s*script/i
+];
+
+const stripComments = (css: string): string =>
+  css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+const bracesBalance = (css: string): boolean => {
+  let depth = 0;
+
+  for (const char of css) {
+    if (char === '{') depth += 1;
+    if (char === '}') {
+      depth -= 1;
+      // A closing brace with nothing open means the author has already left
+      // their own block and is styling the page.
+      if (depth < 0) return false;
+    }
+  }
+
+  return depth === 0;
+};
+
+/**
+ * Splits top-level rules so each selector list can be scoped individually.
+ * At-rules that carry a body (`@media`, `@supports`, `@container`) keep their
+ * body and are scoped from the inside.
+ */
+const splitTopLevelRules = (css: string): string[] => {
+  const rules: string[] = [];
+  let depth = 0;
+  let start = 0;
+
+  for (let i = 0; i < css.length; i++) {
+    const char = css[i];
+    if (char === '{') depth += 1;
+    if (char === '}') {
+      depth -= 1;
+      if (depth === 0) {
+        rules.push(css.slice(start, i + 1));
+        start = i + 1;
+      }
+    }
+  }
+
+  const tail = css.slice(start).trim();
+  if (tail) rules.push(tail);
+
+  return rules.map(rule => rule.trim()).filter(Boolean);
+};
+
+const scopeSelectorList = (selectors: string, scope: string): string =>
+  selectors
+    .split(',')
+    .map(selector => selector.trim())
+    .filter(Boolean)
+    .map(selector =>
+      selector.includes('&')
+        ? selector.split('&').join(scope)
+        : `${scope} ${selector}`
+    )
+    .join(', ');
+
+const scopeRule = (rule: string, scope: string): string => {
+  const open = rule.indexOf('{');
+  if (open === -1) return '';
+
+  const prelude = rule.slice(0, open).trim();
+  const body = rule.slice(open + 1, rule.lastIndexOf('}'));
+
+  if (prelude.startsWith('@')) {
+    // `@keyframes` and `@font-face` have no selectors to scope — their bodies
+    // are keyframe stops and descriptors. Scoping them turned a working
+    // animation into a dead at-rule, which is why a spinner could not be
+    // authored at all.
+    if (/^@(keyframes|-\w+-keyframes|font-face|property)\b/i.test(prelude)) {
+      return rule;
+    }
+
+    // Conditional group rules: scope what is inside, keep the condition.
+    const inner = splitTopLevelRules(body)
+      .map(innerRule => scopeRule(innerRule, scope))
+      .filter(Boolean)
+      .join('\n');
+
+    return inner ? `${prelude} {\n${inner}\n}` : '';
+  }
+
+  return `${scopeSelectorList(prelude, scope)} {${body}}`;
+};
+
+/**
+ * Returns CSS scoped to `scope`, or an empty string when the input is unsafe.
+ * Silently dropping beats emitting something the author did not intend.
+ */
+export const scopeCustomCss = (raw: unknown, scope: string): string => {
+  if (typeof raw !== 'string') return '';
+
+  const css = stripComments(raw).trim();
+  if (!css) return '';
+
+  if (FORBIDDEN.some(pattern => pattern.test(css))) return '';
+  if (!bracesBalance(css)) return '';
+
+  // Bare declarations ("color: red") are the common case for "just this
+  // block", so they get wrapped rather than rejected.
+  if (!css.includes('{')) {
+    return `${scope} {\n${css}\n}\n`;
+  }
+
+  return (
+    splitTopLevelRules(css)
+      .map(rule => scopeRule(rule, scope))
+      .filter(Boolean)
+      .join('\n') + '\n'
+  );
+};
+
+/** Reads one breakpoint's custom CSS off a block. */
+export const readCustomCss = (
+  properties: Record<string, unknown> | undefined | null,
+  targetBreakpoint?: string
+): string => {
+  const entry = properties?.customCss ?? properties?.['custom-css'];
+  if (entry === undefined || entry === null) return '';
+
+  if (typeof entry === 'string') return entry;
+
+  if (typeof entry === 'object') {
+    const responsive = entry as {
+      desktop?: unknown;
+      tablet?: unknown;
+      mobile?: unknown;
+    };
+    // The same fall-through the styles use: a tablet with nothing of its own
+    // shows what the mobile bucket puts on screen at that width, not desktop.
+    const value =
+      targetBreakpoint === 'mobile'
+        ? responsive.mobile ?? responsive.desktop
+        : targetBreakpoint === 'tablet'
+        ? responsive.tablet ?? responsive.mobile ?? responsive.desktop
+        : responsive.desktop;
+    return typeof value === 'string' ? value : '';
+  }
+
+  return '';
+};
+
+/**
+ * All of a block's custom CSS, scoped.
+ *
+ * On the storefront there is no target breakpoint — the same stylesheet has
+ * to serve all of them — so reading a single bucket silently dropped
+ * everything a designer wrote for a narrower viewport. Each is emitted inside
+ * the same media query the rest of the generator uses, tablet after mobile so
+ * source order settles the 768-1023 band. In the designer a breakpoint IS
+ * given, and only that bucket is emitted, because the canvas is already
+ * showing one viewport.
+ */
+export const buildCustomCss = (
+  properties: Record<string, unknown> | undefined | null,
+  scope: string,
+  targetBreakpoint?: string
+): string => {
+  if (targetBreakpoint) {
+    return scopeCustomCss(readCustomCss(properties, targetBreakpoint), scope);
+  }
+
+  const desktop = scopeCustomCss(readCustomCss(properties), scope);
+
+  const entry = properties?.customCss ?? properties?.['custom-css'];
+  const responsive =
+    entry && typeof entry === 'object'
+      ? (entry as { desktop?: unknown; tablet?: unknown; mobile?: unknown })
+      : null;
+  const mobileRaw = responsive ? responsive.mobile : null;
+  const tabletRaw = responsive ? responsive.tablet : null;
+
+  // Only a value that differs from desktop is worth a second rule.
+  const desktopRaw = responsive ? responsive.desktop : entry;
+
+  let css = desktop;
+
+  if (typeof mobileRaw === 'string' && mobileRaw.trim()) {
+    if (mobileRaw !== desktopRaw) {
+      const mobile = scopeCustomCss(mobileRaw, scope);
+      if (mobile) css += `${MOBILE_MEDIA_QUERY} {\n${mobile}}\n`;
+    }
+  }
+
+  // A tablet rule earns its bytes only against what the band would already
+  // show: the mobile block when there is one, otherwise desktop.
+  const inheritedRaw =
+    typeof mobileRaw === 'string' && mobileRaw.trim() ? mobileRaw : desktopRaw;
+
+  if (
+    typeof tabletRaw === 'string' &&
+    tabletRaw.trim() &&
+    tabletRaw !== inheritedRaw
+  ) {
+    const tablet = scopeCustomCss(tabletRaw, scope);
+    if (tablet) css += `${TABLET_MEDIA_QUERY} {\n${tablet}}\n`;
+  }
+
+  return css;
+};