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

package/src/overlays/modal-preview-host.tsx

@@ -3,6 +3,7 @@
 import React from 'react';
 
 import ThemePlaceholderWrapper from '../theme-placeholder-wrapper';
+import { buildModalChromeCss } from './modal-chrome-css';
 import {
   CentredModalSurface,
   LayeredOverlaySurface,
@@ -120,6 +121,13 @@ export const ModalPreviewHost = ({
    */
   const presentation = resolveModalPresentation(modal, breakpoint);
 
+  /**
+   * The designer's chrome styles. Always pinned to the editor's chosen
+   * breakpoint: this host only ever runs inside the canvas, where the iframe's
+   * own width answers a different question than the viewport buttons do.
+   */
+  const chromeCss = buildModalChromeCss(modal, breakpoint);
+
   // Every dismissal is inert: the designer has to be able to click the close
   // button and the backdrop they are colouring without the surface vanishing.
   const noop = () => undefined;
@@ -132,6 +140,8 @@ export const ModalPreviewHost = ({
       right={chrome.closeRight}
       size={chrome.closeSize}
       elevate
+      text={chrome.closeText}
+      textSide={chrome.closeTextSide}
     />
   ) : null;
 
@@ -154,6 +164,7 @@ export const ModalPreviewHost = ({
         panelPadding={chrome.padding}
         panelStretch={chrome.stretchContent}
         topInset={chrome.topInset}
+        chromeCss={chromeCss}
         header={header}
       >
         {composition(modal.slug)}
@@ -179,6 +190,7 @@ export const ModalPreviewHost = ({
         sheetHeight={chrome.sheetHeight}
         showSheetHandle={chrome.showSheetHandle}
         topInset={chrome.topInset}
+        chromeCss={chromeCss}
         header={header}
       >
         {composition(modal.slug)}

package/src/overlays/modal-registry.ts

@@ -140,6 +140,18 @@ export interface ModalChrome {
    * turns on.
    */
   stretchContent?: boolean;
+  /**
+   * Visible text beside the built-in close button, and which side of the icon
+   * it sits on.
+   *
+   * `closeLabel` stays the ACCESSIBLE name — it is what a screen reader says,
+   * and it has to keep saying it whether or not sighted text exists. This is
+   * markup rather than a style, which is why no CSS control could supply it:
+   * absent, the button renders the icon alone, exactly as every modal
+   * published before this does.
+   */
+  closeText?: string;
+  closeTextSide?: 'before' | 'after';
 }
 
 /**
@@ -181,6 +193,19 @@ export interface ThemeModal {
     Record<'tablet' | 'mobile', ModalPresentation>
   >;
   chrome: ModalChrome;
+  /**
+   * The designer's own styles for the modal's CHROME — the panel, the backdrop,
+   * the close button, its text and a sheet's grab bar.
+   *
+   * Same shape as a block's `styles`, so the editor drives it with the control
+   * vocabulary it already has: `styles[cssKey][breakpoint]`. The key grammar is
+   * the one thing to keep straight — a BARE css key targets the panel, and a
+   * `part/property` (or `part/state/property`) key targets a named chrome part.
+   * `buildModalChromeCss` in `modal-chrome-css.ts` is what turns this into CSS,
+   * and it emits `!important` because the elements it dresses carry the
+   * renderer's own inline defaults.
+   */
+  styles?: Record<string, unknown>;
   /**
    * Chrome values that differ at a narrower breakpoint.
    *
@@ -572,7 +597,12 @@ const readChrome = (value: unknown, name: string): ModalChrome => {
     closeRight: asChromeLength(raw.closeRight, 200),
     // A tap target below ~24px is hard to hit and above ~64px is not an icon.
     closeSize: asChromeLength(raw.closeSize, 64),
-    stretchContent: asToggle(raw.stretchContent, false)
+    stretchContent: asToggle(raw.stretchContent, false),
+    // Absence-preserving, per the doctrine above: a modal that never authored
+    // a close text must not come out of here claiming an empty one, and the
+    // side only means something once the text exists.
+    closeText: asString(raw.closeText) || undefined,
+    closeTextSide: raw.closeTextSide === 'before' ? 'before' : undefined
   };
 };
 
@@ -620,6 +650,14 @@ export const readThemeModal = (value: unknown): ThemeModal | null => {
     visibilityRules:
       raw.visibilityRules && typeof raw.visibilityRules === 'object'
         ? (raw.visibilityRules as VisibilityRules)
+        : undefined,
+    // The one gate every chrome style passes through. Left out, the editor
+    // saves, the panel looks alive and nothing renders — in the canvas OR in
+    // production. `undefined` rather than `{}` so "never authored" stays
+    // distinguishable from "authored empty".
+    styles:
+      raw.styles && typeof raw.styles === 'object' && !Array.isArray(raw.styles)
+        ? (raw.styles as Record<string, unknown>)
         : undefined
   };
 };

package/src/overlays/overlay-surface.tsx

@@ -312,6 +312,17 @@ export interface OverlayCloseButtonProps {
    * hosts ask.
    */
   elevate?: boolean;
+  /**
+   * Visible text beside the glyph, and which side of it that text sits on.
+   *
+   * `label` stays the accessible name whether or not this is set — a screen
+   * reader must still be told what the button does, and the two can legitimately
+   * differ ("Close" vs. "Skip for now"). Absent leaves the button's markup and
+   * style object byte-identical to what it has always rendered, which is what
+   * `panel-legacy-golden.json` pins for the legacy size-guide panel.
+   */
+  text?: string;
+  textSide?: 'before' | 'after';
   /** Legacy marker attribute, e.g. `{ 'data-size-guide-close': '' }`. */
   markerAttrs?: Record<string, string>;
 }
@@ -336,6 +347,8 @@ export const OverlayCloseButton = ({
   right,
   size,
   elevate,
+  text,
+  textSide,
   markerAttrs
 }: OverlayCloseButtonProps) => (
   <button
@@ -365,7 +378,20 @@ export const OverlayCloseButton = ({
         : { padding: '8px', margin: '-8px', lineHeight: 0 }),
       // Only has to beat static content, which is what the composition's
       // blocks are; the panel's own layer sits at 1000 above the page.
-      ...(elevate ? { zIndex: 2 } : null)
+      ...(elevate ? { zIndex: 2 } : null),
+      // Nothing at all without a text: the glyph-only button is pinned byte
+      // for byte by the legacy golden fixture.
+      ...(text
+        ? {
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: '8px',
+            flexDirection:
+              textSide === 'before'
+                ? ('row-reverse' as const)
+                : ('row' as const)
+          }
+        : null)
     }}
   >
     <svg
@@ -379,6 +405,7 @@ export const OverlayCloseButton = ({
     >
       <path d="M6 6l12 12M18 6L6 18" />
     </svg>
+    {text ? <span {...partAttrs('close-text')}>{text}</span> : null}
   </button>
 );
 
@@ -440,6 +467,15 @@ export interface OverlaySurfaceProps extends OverlayGeometryInput {
    * which is what every published modal does.
    */
   topInset?: number | string;
+  /**
+   * The designer's chrome styles for THIS modal, already compiled to CSS by
+   * `buildModalChromeCss`. Rendered as a `<style>` inside the surface, next to
+   * the stretch rules, so it travels with the panel it dresses.
+   *
+   * A prop the panel block never passes, deliberately: an empty string must
+   * render no tag at all, or `panel-legacy-golden.json` moves.
+   */
+  chromeCss?: string;
   /** Rendered inside the panel, above the authored content. */
   header?: React.ReactNode;
   children: React.ReactNode;
@@ -492,6 +528,7 @@ export const CentredModalSurface = ({
   panelPadding,
   panelStretch,
   topInset,
+  chromeCss,
   header,
   children,
   markers
@@ -552,6 +589,9 @@ export const CentredModalSurface = ({
       }}
     >
       {panelStretch && <PanelStretchStyles />}
+      {chromeCss ? (
+        <style dangerouslySetInnerHTML={{ __html: chromeCss }} />
+      ) : null}
       {header}
       {children}
     </div>
@@ -584,6 +624,7 @@ export const LayeredOverlaySurface = ({
   panelStretch,
   showSheetHandle,
   topInset,
+  chromeCss,
   header,
   children,
   markers
@@ -637,6 +678,9 @@ export const LayeredOverlaySurface = ({
       }}
     >
       {panelStretch && <PanelStretchStyles />}
+      {chromeCss ? (
+        <style dangerouslySetInnerHTML={{ __html: chromeCss }} />
+      ) : null}
       {presentation === 'sheet' && showSheetHandle !== false && (
         <OverlaySheetHandle markerAttrs={markers?.handle} />
       )}

package/src/overlays/theme-modal-mount.tsx

@@ -12,6 +12,7 @@ import {
   resolveModalChrome,
   resolveModalPresentation
 } from './modal-registry';
+import { buildModalChromeCss } from './modal-chrome-css';
 import {
   CentredModalSurface,
   LayeredOverlaySurface,
@@ -121,6 +122,18 @@ const ThemeModalMount = ({
   const presentation = resolveModalPresentation(modal, breakpoint);
   const isCentred = presentation === 'modal';
 
+  /**
+   * The designer's chrome styles, compiled here so both surfaces get the same
+   * string. In the canvas it is FORCED to one breakpoint — the iframe's width
+   * is not the device's, so real media queries would answer the wrong
+   * question; on a storefront the queries are emitted, which also spares the
+   * server render a flash while `useOverlayBreakpoint` starts at `desktop`.
+   */
+  const chromeCss = buildModalChromeCss(
+    modal,
+    isDesigner ? breakpoint : undefined
+  );
+
   /**
    * In the canvas the overlay is fully inert: it never steals focus into the
    * page the designer is styling, never freezes it, never claims `aria-modal`
@@ -151,6 +164,8 @@ const ThemeModalMount = ({
       right={chrome.closeRight}
       size={chrome.closeSize}
       elevate
+      text={chrome.closeText}
+      textSide={chrome.closeTextSide}
     />
   ) : null;
 
@@ -169,6 +184,7 @@ const ThemeModalMount = ({
       panelPadding={chrome.padding}
       panelStretch={chrome.stretchContent}
       topInset={chrome.topInset}
+      chromeCss={chromeCss}
       header={header}
     >
       {children}
@@ -191,6 +207,7 @@ const ThemeModalMount = ({
       topInset={chrome.topInset}
       panelPadding={chrome.padding}
       panelStretch={chrome.stretchContent}
+      chromeCss={chromeCss}
       header={header}
     >
       {children}

package/src/utils/__tests__/inner-root-ownership.test.tsx

@@ -0,0 +1,334 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import ThemeBlock from '../../theme-block';
+import { generateThemeCSS } from '../index';
+import { buildInnerRootSelectors, buildPartSelectors } from '../part-styles';
+import { buildIteratorBlock } from '../iterator-utils';
+import type { Section } from '../../theme-section';
+
+/**
+ * The routed root rule, confined to the block that owns the root.
+ *
+ * Three renderers draw their own root and mark it `data-part="root"` (text,
+ * link, button — see INNER_ROOT_BLOCK_TYPES), and the sheet routes the block's
+ * rule to that element. The routed selector is a DESCENDANT one, so on a card
+ * built the way every collection grid is built — a link wrapping a label — the
+ * link's rule also matched the label's root.
+ *
+ * It was the worst possible part name to leak. `root` is not an internal a
+ * designer occasionally reaches for: those three renderers mark one every time,
+ * and so do several functional blocks that are not in the routed set at all
+ * (auth-error, auth-step-title, basket-summary, checkout-steps,
+ * checkout-summary, order-success), so the leak fired on the most ordinary
+ * composition there is and its victims were not limited to the routed types.
+ * The keys a card carries are layout keys, which is what made it loud: the
+ * label inherited the card's `aspect-ratio: 1/1` and `flex: 1 1 0`, went square
+ * at the card's full width, and left the image beside it a 4px sliver — plus a
+ * second border and radius drawn inside the first.
+ *
+ * The fix is the guard that already confines every other part rule.
+ */
+
+const text = (id: string, styles: Record<string, unknown> = {}) => ({
+  id,
+  type: 'text',
+  label: 'Label',
+  value: '<p>SOLID</p>',
+  properties: {},
+  styles,
+  order: 0,
+  hidden: false
+});
+
+const group = (id: string, children: unknown[]) => ({
+  id,
+  type: 'group',
+  label: 'Group',
+  properties: {},
+  styles: {},
+  order: 0,
+  hidden: false,
+  blocks: children
+});
+
+const link = (
+  id: string,
+  styles: Record<string, unknown> = {},
+  children: unknown[] = []
+) => ({
+  id,
+  type: 'link',
+  label: 'Card',
+  value: '',
+  properties: { href: '/collections' },
+  styles,
+  order: 0,
+  hidden: false,
+  blocks: children
+});
+
+const button = (id: string, styles: Record<string, unknown> = {}) => ({
+  id,
+  type: 'button',
+  label: 'CTA',
+  value: 'Shop',
+  // `tag: 'button'` so the renderer draws a <button>; its default is an <a>,
+  // which inside the card's own <a> is markup no theme can produce.
+  properties: { text: 'Shop', tag: 'button' },
+  styles,
+  order: 0,
+  hidden: false
+});
+
+const image = (id: string) => ({
+  id,
+  type: 'image',
+  label: 'Image',
+  value: '',
+  properties: { src: '/a.png' },
+  styles: { flex: { desktop: '1 1 0' } },
+  order: 0,
+  hidden: false
+});
+
+/** The card that broke: a link, a label inside a group, an image beside it. */
+const card = (cardStyles: Record<string, unknown>, extra: unknown[] = []) =>
+  link('card', cardStyles, [
+    image('media'),
+    group('caption', [text('label')]),
+    ...extra
+  ]);
+
+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 a `root` part.
+ *
+ * At-rule preludes are dropped with the chunk they open, so a rule that only
+ * exists inside `@media` is not seen here. That is why the breakpoint case
+ * below reads the TARGETED output, which `generateElementCSS` emits unwrapped.
+ */
+const rootSelectors = (css: string): string[] =>
+  css
+    .split('}')
+    .map((chunk) => chunk.slice(0, chunk.indexOf('{')))
+    .filter((selector) => selector.includes('[data-part="root"]'))
+    .flatMap((selector) => selector.split(',').map((one) => one.trim()))
+    .filter(Boolean);
+
+/** Which blocks' roots those selectors actually reach in the rendered card. */
+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 boxStyles = {
+  'aspect-ratio': { desktop: '1/1' },
+  flex: { desktop: '1 1 0' },
+  'border-radius': { desktop: '20px' },
+  'border-width': { desktop: '1px' }
+};
+
+describe('a card whose link carries the box', () => {
+  it('paints the link root and not the label root', () => {
+    const css = generateThemeCSS(sectionOf(card(boxStyles)));
+    const { container } = renderRoot(card({}));
+
+    // Premise: both blocks really do mark a root, one inside the other.
+    expect(container.querySelectorAll('[data-part="root"]').length).toBe(2);
+    expect(ownersOf(container, rootSelectors(css))).toEqual(['card']);
+  });
+
+  it('leaves the label reachable by its own rule', () => {
+    // The other way this could go wrong: a guard that also deletes the style
+    // the nested block itself declares.
+    const styledLabel = generateThemeCSS(
+      sectionOf(
+        link('card', boxStyles, [
+          image('media'),
+          group('caption', [text('label', { 'font-size': { desktop: '18px' } })])
+        ])
+      )
+    );
+    const { container } = renderRoot(card({}));
+
+    expect(ownersOf(container, rootSelectors(styledLabel))).toEqual([
+      'card',
+      'label'
+    ]);
+  });
+
+  it('confines a hover rule to the link root as well', () => {
+    const css = generateThemeCSS(
+      sectionOf(card({ ':hover/border-color': { desktop: '#000000' } }))
+    );
+    const { container } = renderRoot(card({}));
+
+    // The canvas pins a state by stamping it, which is why every state also
+    // matches `[data-state~="…"]` — and it is the only one of the emitted
+    // expressions a test can put on an element. Stamped on BOTH roots, so the
+    // rule gets its chance to leak.
+    container
+      .querySelectorAll<HTMLElement>('[data-part="root"]')
+      .forEach((element) => element.setAttribute('data-state', 'hover'));
+
+    const stamped = rootSelectors(css).filter((selector) =>
+      selector.includes('[data-state~="hover"]')
+    );
+
+    expect(stamped.length).toBeGreaterThan(0);
+    expect(ownersOf(container, stamped)).toEqual(['card']);
+  });
+
+  it('holds on every breakpoint', () => {
+    ['desktop', 'mobile', 'tablet'].forEach((breakpoint) => {
+      const css = generateThemeCSS(
+        sectionOf(
+          card({
+            'aspect-ratio': { desktop: '1/1', tablet: '3/4', mobile: '4/5' }
+          })
+        ),
+        breakpoint
+      );
+      const { container, unmount } = renderRoot(card({}));
+      const selectors = rootSelectors(css);
+
+      // Targeted output is emitted unwrapped, so the value resolved for THIS
+      // breakpoint is the one carried by the selectors read here.
+      expect(selectors.length).toBeGreaterThan(0);
+      expect(ownersOf(container, selectors)).toEqual(['card']);
+      unmount();
+    });
+  });
+});
+
+describe('the other shapes that nest a root inside a root', () => {
+  /**
+   * Only a link nests another block's root among the three routed types: a text
+   * renders its copy and a button renders its own label, neither takes children
+   * (see button-block.tsx, which draws `{content}`). So a link is the outer
+   * block in every shape below — and `<a>` inside `<a>` is not markup a theme
+   * can produce, which leaves a button, a text, and the functional blocks named
+   * at the top of this file as the roots a card can contain.
+   */
+  it('a button inside a link', () => {
+    const withCta = (styles: Record<string, unknown>) =>
+      card(styles, [button('cta')]);
+    const css = generateThemeCSS(sectionOf(withCta(boxStyles)));
+    const { container } = renderRoot(withCta({}));
+
+    expect(ownersOf(container, rootSelectors(css))).toEqual(['card']);
+  });
+
+  it('a repeated card, whose clones share one style identity', () => {
+    const expanded = buildIteratorBlock({
+      iteratorBlock: {
+        id: 'it-1',
+        type: 'group',
+        label: 'Repeat',
+        isIterator: true,
+        blocks: [card(boxStyles)]
+      } as never,
+      items: [{ a: 1 }, { a: 2 }, { a: 3 }]
+    });
+    const composition = group('grid', (expanded.blocks || []) as unknown[]);
+
+    const css = generateThemeCSS(sectionOf(composition));
+    const { container } = renderRoot(composition);
+    const [guarded] = buildInnerRootSelectors('[data-block-id="card"]');
+
+    // One authored rule, three rows: it has to keep matching every clone's own
+    // root, and none of their labels.
+    expect(container.querySelectorAll(guarded)).toHaveLength(3);
+    expect(ownersOf(container, rootSelectors(css))).toEqual(['card']);
+  });
+
+  it('a block whose style identity is not its id', () => {
+    const shape = (styles: Record<string, unknown>) => ({
+      ...link('instance', styles, [group('caption', [text('label')])]),
+      styleSourceId: 'template'
+    });
+    const css = generateThemeCSS(sectionOf(shape(boxStyles)));
+    const { container } = renderRoot(shape({}));
+
+    // Rule and guard are keyed on the same identity, or the guard would exclude
+    // the element the rule is aimed at.
+    expect(css).toContain('[data-block-id="template"] [data-part="root"]');
+    expect(ownersOf(container, rootSelectors(css))).toEqual(['template']);
+  });
+
+  it('a block type that opts into the routing explicitly', () => {
+    // `stylesTargetRoot` overrides the type list, so the flag path has to reach
+    // the guarded builder too.
+    const css = generateThemeCSS(
+      sectionOf({
+        ...group('opted-in', [text('label')]),
+        styles: boxStyles,
+        stylesTargetRoot: true
+      })
+    );
+
+    expect(css).toContain(
+      '[data-block-id="opted-in"] [data-part="root"]' +
+        ':not(:where([data-block-id="opted-in"] [data-block-id] *))'
+    );
+  });
+});
+
+describe('the selector builder', () => {
+  it('delegates to the part builder, so root cannot drift from every part', () => {
+    // Asserted against the part builder itself rather than a copy of its
+    // output: the point of the fix is that `root` is not special-cased.
+    ['[data-block-id="c"]', '[data-block-id="a\\"] , * {}"]'].forEach(
+      (blockSelector) => {
+        expect(buildInnerRootSelectors(blockSelector)).toEqual(
+          buildPartSelectors(blockSelector, {
+            part: 'root',
+            state: null,
+            styles: {}
+          })
+        );
+
+        expect(buildInnerRootSelectors(blockSelector, 'hover')).toEqual(
+          buildPartSelectors(blockSelector, {
+            part: 'root',
+            state: 'hover',
+            styles: {}
+          })
+        );
+      }
+    );
+  });
+});

package/src/utils/__tests__/inner-root-styles.test.tsx

@@ -54,7 +54,12 @@ describe('a renderer that draws its own root', () => {
       sectionWith({ id: 'txt', type: 'text', styles: { padding: '24px' } })
     );
 
-    expect(css).toContain('[data-block-id="txt"] [data-part="root"] {');
+    // Guarded, so the rule cannot also paint the root a nested block marks —
+    // that containment is covered in inner-root-ownership.test.tsx.
+    expect(css).toContain(
+      '[data-block-id="txt"] [data-part="root"]' +
+        ':not(:where([data-block-id="txt"] [data-block-id] *)) {'
+    );
     // The wrapper must NOT also carry it: that second application is the bug.
     expect(css).not.toContain('[data-block-id="txt"] {');
   });

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

@@ -283,6 +283,12 @@ 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.
+    //
+    // Read the scope literally: it is a composition of blocks whose styles land
+    // on the WRAPPER. A text, link or button root rule is routed to
+    // `data-part="root"` and therefore carries the guard whether or not a part
+    // key was typed — see inner-root-ownership.test.tsx. Accordions are used
+    // here precisely because they are not one of those three.
     const css = generateThemeCSS(
       sectionOf(
         accordion(

package/src/utils/__tests__/scrolled-state-styles.test.ts

@@ -174,8 +174,12 @@ describe('the block and section root rules', () => {
 
     // The state has to land on the same element the stateless root rule does,
     // or it would style the transparent designer wrapper the block sits in.
+    // Ownership guard included: a routed root rule is a descendant selector,
+    // and a nested block marks a root of its own.
     expect(css).toContain(
-      `${SLOT} [data-block-id="blk-1"] [data-part="root"] {\n  color: #111111;\n}`
+      `${SLOT} [data-block-id="blk-1"] [data-part="root"]` +
+        `:not(:where([data-block-id="blk-1"] [data-block-id] *))` +
+        ` {\n  color: #111111;\n}`
     );
   });