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

package/src/overlays/__tests__/responsive-chrome.test.tsx

@@ -0,0 +1,446 @@
+import { act, render } from '@testing-library/react';
+import React from 'react';
+
+jest.mock('next/navigation', () => ({
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams()
+}));
+
+jest.mock('next-auth/react', () => ({
+  useSession: () => ({ status: 'unauthenticated' })
+}));
+
+jest.mock('@akinon/next/hooks/use-localization', () => ({
+  useLocalization: () => ({ locale: 'en', currency: 'USD' })
+}));
+
+import ThemeModalMount from '../theme-modal-mount';
+import {
+  __resetOverlayBusForTests,
+  openModal,
+  registerModalHost
+} from '../overlay-bus';
+import { __resetModalPreviewForTests } from '../use-modal-preview';
+import { clearAutoOpenRecord } from '../modal-frequency';
+import {
+  readThemeModals,
+  resolveModalChrome,
+  ThemeModal
+} from '../modal-registry';
+import { resolveSheetHeight } from '../overlay-surface';
+
+/**
+ * Chrome values that differ with the device, and the sheet's grab bar.
+ *
+ * A sheet covering 92% of a phone is not the 60% a desktop gets, and a backdrop
+ * dark enough behind a small sheet is too heavy behind a centred dialog — so
+ * these three are answerable per breakpoint. Everything else stays
+ * single-valued on purpose: a control that can differ per device is a control a
+ * designer has to check three times.
+ */
+
+const mkModal = (overrides: Record<string, unknown> = {}): ThemeModal =>
+  readThemeModals([
+    {
+      id: 'sheet',
+      name: 'Sheet',
+      presentation: 'sheet',
+      chrome: { sheetHeight: 60, backdropOpacity: 50 },
+      ...overrides
+    }
+  ])[0];
+
+const atWidth = (width: number) => {
+  (window as unknown as { innerWidth: number }).innerWidth = width;
+};
+
+const openAt = (width: number, overrides: Record<string, unknown> = {}) => {
+  atWidth(width);
+
+  render(
+    <ThemeModalMount modal={mkModal(overrides)}>
+      <p>composed content</p>
+    </ThemeModalMount>
+  );
+
+  act(() => {
+    openModal('sheet');
+  });
+
+  return document.querySelector('[role="dialog"]') as HTMLElement;
+};
+
+beforeEach(() => {
+  __resetOverlayBusForTests();
+  __resetModalPreviewForTests();
+  registerModalHost();
+  clearAutoOpenRecord('sheet');
+  document.body.style.overflow = '';
+  atWidth(1440);
+});
+
+describe('resolving chrome for a breakpoint', () => {
+  const modal = {
+    chrome: { sheetHeight: 60, backdropOpacity: 50 } as ThemeModal['chrome'],
+    chromeByBreakpoint: { mobile: { sheetHeight: 92 } }
+  };
+
+  it('returns the very same object when nothing overrides', () => {
+    const plain = { chrome: modal.chrome };
+
+    // Identity, not equality: a new object per render would rerender the
+    // surface for every modal on the page.
+    expect(resolveModalChrome(plain, 'mobile')).toBe(plain.chrome);
+    expect(resolveModalChrome(modal, 'desktop')).toBe(modal.chrome);
+  });
+
+  it('applies only the fields the breakpoint answered', () => {
+    const resolved = resolveModalChrome(modal, 'mobile');
+
+    expect(resolved.sheetHeight).toBe(92);
+    // Untouched by an override that never mentioned it.
+    expect(resolved.backdropOpacity).toBe(50);
+  });
+
+  it('lets a phone inherit the tablet answer', () => {
+    const resolved = resolveModalChrome(
+      {
+        chrome: modal.chrome,
+        chromeByBreakpoint: { tablet: { backdropOpacity: 80 } }
+      },
+      'mobile'
+    );
+
+    expect(resolved.backdropOpacity).toBe(80);
+  });
+
+  it('keeps the phone answer over the tablet one', () => {
+    const resolved = resolveModalChrome(
+      {
+        chrome: modal.chrome,
+        chromeByBreakpoint: {
+          tablet: { sheetHeight: 70 },
+          mobile: { sheetHeight: 92 }
+        }
+      },
+      'mobile'
+    );
+
+    expect(resolved.sheetHeight).toBe(92);
+  });
+
+  it('leaves the desktop answer alone', () => {
+    expect(resolveModalChrome(modal, 'desktop').sheetHeight).toBe(60);
+  });
+});
+
+describe('the config parser', () => {
+  it('carries the overrides through', () => {
+    expect(
+      mkModal({ chromeByBreakpoint: { mobile: { sheetHeight: 92 } } })
+        .chromeByBreakpoint
+    ).toEqual({ mobile: { sheetHeight: 92 } });
+  });
+
+  it('validates an override exactly as it validates the base value', () => {
+    const parsed = mkModal({
+      chromeByBreakpoint: {
+        mobile: {
+          sheetHeight: 4000,
+          backdropColor: 'chartreuse',
+          backdropOpacity: -20
+        }
+      }
+    });
+
+    // Clamped, and the junk colour rejected rather than handed to the browser.
+    expect(parsed.chromeByBreakpoint?.mobile).toEqual({
+      sheetHeight: 100,
+      backdropOpacity: 0
+    });
+  });
+
+  it('drops a breakpoint whose every field was rejected', () => {
+    expect(
+      mkModal({ chromeByBreakpoint: { mobile: { sheetHeight: 'tall' } } })
+        .chromeByBreakpoint
+    ).toBeUndefined();
+  });
+});
+
+describe('the rendered sheet', () => {
+  it('takes its height from the breakpoint in force', () => {
+    const overrides = { chromeByBreakpoint: { mobile: { sheetHeight: 92 } } };
+
+    expect(openAt(1440, overrides).style.maxHeight).toBe('60vh');
+    document.body.innerHTML = '';
+    expect(openAt(480, overrides).style.maxHeight).toBe('92vh');
+  });
+
+  it('draws the grab bar by default, as every published sheet has', () => {
+    expect(openAt(1440).querySelector('[data-part="handle"]')).not.toBeNull();
+  });
+
+  it('drops the bar when the composition brings its own header', () => {
+    expect(
+      openAt(1440, { chrome: { showSheetHandle: false } }).querySelector(
+        '[data-part="handle"]'
+      )
+    ).toBeNull();
+  });
+});
+
+/**
+ * Writing the height out instead of picking a percentage.
+ *
+ * A sheet in a design is rarely "80% of the screen": it is "everything below
+ * the header", and no percentage can say that — the header is a fixed number of
+ * pixels. The measured symptom was a sheet whose composition (599px of banner,
+ * copy and CTA) did not fit the 60% it was given, so the logo scrolled out of
+ * view with no way to ask for more.
+ */
+describe('the sheet height as a written length', () => {
+  it('keeps a number meaning viewport percent, as every published sheet does', () => {
+    expect(resolveSheetHeight(80)).toBe('80vh');
+    expect(mkModal({ chrome: { sheetHeight: 80 } }).chrome.sheetHeight).toBe(
+      80
+    );
+  });
+
+  it('takes a calc() as written, which is the whole point', () => {
+    const written = 'calc(100dvh - 172px)';
+
+    expect(resolveSheetHeight(written)).toBe(written);
+    expect(
+      mkModal({ chrome: { sheetHeight: written } }).chrome.sheetHeight
+    ).toBe(written);
+  });
+
+  it.each([
+    'fit-content',
+    '92%',
+    '640px',
+    'min(90dvh, 720px)',
+    'clamp(320px, 80vh, 900px)'
+  ])('accepts %s', (written) => {
+    expect(resolveSheetHeight(written)).toBe(written);
+  });
+
+  it('reads a numeric string as the number, not as a length', () => {
+    // An editor text input hands back "80", and `80` alone is not valid CSS —
+    // applied verbatim it would leave the panel with no height at all.
+    expect(mkModal({ chrome: { sheetHeight: '80' } }).chrome.sheetHeight).toBe(
+      80
+    );
+  });
+
+  it.each([
+    'tall',
+    '80',
+    'calc(words)',
+    '80vh; position: fixed',
+    'url(x.png)',
+    'expression(alert(1))',
+    '80vh}'
+  ])('falls back rather than handing the browser %s', (written) => {
+    // A declaration the browser drops leaves the sheet with no height — the
+    // composition then spills out of a panel collapsed to nothing.
+    expect(resolveSheetHeight(written)).toBe('60vh');
+  });
+
+  it('applies the written length to the panel', () => {
+    const panel = openAt(480, {
+      chrome: { sheetHeight: 'calc(100dvh - 172px)' }
+    });
+
+    expect(panel.style.maxHeight).toBe('calc(100dvh - 172px)');
+  });
+
+  it('can be written for one breakpoint only', () => {
+    const parsed = mkModal({
+      chromeByBreakpoint: { mobile: { sheetHeight: 'calc(100dvh - 172px)' } }
+    });
+
+    expect(parsed.chromeByBreakpoint?.mobile?.sheetHeight).toBe(
+      'calc(100dvh - 172px)'
+    );
+    // And a junk override is dropped rather than falling back to 60, which
+    // would be an answer nobody gave.
+    expect(
+      mkModal({ chromeByBreakpoint: { mobile: { sheetHeight: 'tall' } } })
+        .chromeByBreakpoint
+    ).toBeUndefined();
+  });
+});
+
+/**
+ * Keeping the site header clear.
+ *
+ * A bottom sheet in the design does not ride over the header: the header stays
+ * visible AND clickable, and the dimming begins below it. No panel height can
+ * express that — the backdrop covers the header either way — so the inset is on
+ * the overlay LAYER, which the backdrop and the panel share.
+ */
+describe('the overlay top inset', () => {
+  it('is absent by default, so a published modal covers the viewport', () => {
+    const panel = openAt(1440);
+    const layer = panel.closest('[data-part="overlay"]') as HTMLElement | null;
+
+    expect(mkModal().chrome.topInset).toBeUndefined();
+    expect(layer?.style.top || '').toBe('');
+  });
+
+  it('moves the whole layer down, not just the panel', () => {
+    openAt(480, { chrome: { topInset: 96 } });
+
+    // The backdrop is inside this layer: insetting the panel alone would leave
+    // the header dimmed and unclickable, which is the actual complaint.
+    const layers = [...document.querySelectorAll('div')].filter(
+      (node) => node.style.position === 'fixed' && node.style.top === '96px'
+    );
+
+    expect(layers.length).toBeGreaterThan(0);
+  });
+
+  it('takes a number as px, the unit a header is measured in', () => {
+    expect(mkModal({ chrome: { topInset: 96 } }).chrome.topInset).toBe(96);
+    expect(mkModal({ chrome: { topInset: '96' } }).chrome.topInset).toBe(96);
+  });
+
+  it('takes a written length, including a theme variable', () => {
+    expect(
+      mkModal({ chrome: { topInset: 'var(--header-height)' } }).chrome.topInset
+    ).toBe('var(--header-height)');
+    expect(
+      mkModal({ chrome: { topInset: 'calc(48px + env(safe-area-inset-top))' } })
+        .chrome.topInset
+    ).toBe('calc(48px + env(safe-area-inset-top))');
+  });
+
+  it('drops junk rather than shifting the layer by a broken value', () => {
+    expect(mkModal({ chrome: { topInset: 'below' } }).chrome.topInset).toBe(
+      undefined
+    );
+    expect(
+      mkModal({ chrome: { topInset: '96px;left:0' } }).chrome.topInset
+    ).toBe(undefined);
+  });
+
+  it('can be answered per breakpoint, since a header is a different height', () => {
+    expect(
+      mkModal({ chromeByBreakpoint: { mobile: { topInset: 132 } } })
+        .chromeByBreakpoint?.mobile?.topInset
+    ).toBe(132);
+  });
+});
+
+/**
+ * Aligning the built-in close button with an authored title row.
+ *
+ * The button is chrome: it is positioned against the PANEL, while a title row
+ * authored in the composition flows with its own padding. Two coordinate
+ * systems, so they never line up by accident — and part styles cannot reach
+ * chrome, because a part rule hangs off a `[data-block-id]` and chrome has
+ * none. Hence three measures.
+ */
+describe('the close button’s position and size', () => {
+  const closeButton = () =>
+    document.querySelector('[data-part="close"]') as HTMLElement;
+
+  it('keeps 12 / 12 / 18 when nothing asks otherwise', () => {
+    openAt(1440);
+
+    // Every modal published before these settings existed renders here.
+    expect(closeButton().style.top).toBe('12px');
+    expect(closeButton().style.right).toBe('12px');
+    // Unitless, exactly as the markup live storefronts style has always been:
+    // this button is the legacy size-guide panel's too, and its golden pins it.
+    expect(closeButton().querySelector('svg')?.getAttribute('width')).toBe(
+      '18'
+    );
+    expect(closeButton().style.lineHeight).toBe('');
+  });
+
+  it('takes the offsets a design needs', () => {
+    openAt(1440, { chrome: { closeTop: 28, closeRight: 20 } });
+
+    expect(closeButton().style.top).toBe('28px');
+    expect(closeButton().style.right).toBe('20px');
+  });
+
+  it('takes a written length as readily as a number', () => {
+    openAt(1440, { chrome: { closeTop: 'calc(50% - 9px)' } });
+
+    expect(closeButton().style.top).toBe('calc(50% - 9px)');
+  });
+
+  it('grows the glyph and gives it a hit area worth aiming at', () => {
+    openAt(480, { chrome: { closeSize: 24 } });
+
+    expect(closeButton().querySelector('svg')?.getAttribute('width')).toBe(
+      '24px'
+    );
+    // The padding is what a thumb hits; the negative margin cancels its effect
+    // on where the glyph lands, so aligning the icon stays predictable.
+    expect(closeButton().style.padding).toBe('8px');
+    expect(closeButton().style.margin).toBe('-8px');
+  });
+
+  it('clamps a size that stopped being an icon', () => {
+    expect(mkModal({ chrome: { closeSize: 400 } }).chrome.closeSize).toBe(64);
+  });
+
+  it('drops junk rather than breaking the declaration', () => {
+    expect(
+      mkModal({ chrome: { closeTop: 'up a bit' } }).chrome.closeTop
+    ).toBeUndefined();
+  });
+
+  it('can be answered per breakpoint, as a padded row is', () => {
+    const parsed = mkModal({
+      chromeByBreakpoint: { mobile: { closeTop: 18, closeSize: 24 } }
+    });
+
+    expect(parsed.chromeByBreakpoint?.mobile).toEqual({
+      closeTop: 18,
+      closeSize: 24
+    });
+  });
+
+  it('uses the breakpoint’s answer on the panel', () => {
+    openAt(480, {
+      chrome: { closeTop: 12 },
+      chromeByBreakpoint: { mobile: { closeTop: 30 } }
+    });
+
+    expect(closeButton().style.top).toBe('30px');
+  });
+});
+
+/**
+ * The close button has to survive the composition drawn under it.
+ *
+ * Measured on the storefront: at the ✕'s own centre the element receiving the
+ * click was the `h2` of the shared title row. A composed modal fills its panel
+ * with authored blocks, a full-width one covers the corner the button sits in,
+ * and the button — positioned but unlayered — loses to a later sibling. The ✕
+ * looked present and did nothing.
+ */
+describe('the close button’s stacking', () => {
+  const closeButton = () =>
+    document.querySelector('[data-part="close"]') as HTMLElement;
+
+  it('is lifted above the panel’s authored content', () => {
+    openAt(1440);
+
+    // Beating static content is all it needs: the composition's blocks are
+    // static, so any layer at all puts the button back on top.
+    expect(closeButton().style.zIndex).toBe('2');
+  });
+
+  it('is lifted whatever the presentation', () => {
+    openAt(480, { presentationByBreakpoint: { mobile: 'sheet' } });
+
+    expect(closeButton().style.zIndex).toBe('2');
+  });
+});

package/src/overlays/__tests__/responsive-presentation.test.tsx

@@ -0,0 +1,192 @@
+import { act, render } from '@testing-library/react';
+import React from 'react';
+
+jest.mock('next/navigation', () => ({
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams()
+}));
+
+jest.mock('next-auth/react', () => ({
+  useSession: () => ({ status: 'unauthenticated' })
+}));
+
+jest.mock('@akinon/next/hooks/use-localization', () => ({
+  useLocalization: () => ({ locale: 'en', currency: 'USD' })
+}));
+
+import ThemeModalMount from '../theme-modal-mount';
+import {
+  __resetOverlayBusForTests,
+  openModal,
+  registerModalHost
+} from '../overlay-bus';
+import { __resetModalPreviewForTests } from '../use-modal-preview';
+import { clearAutoOpenRecord } from '../modal-frequency';
+import {
+  readThemeModals,
+  resolveModalPresentation,
+  ThemeModal
+} from '../modal-registry';
+import { resolveOverlayPanelGeometry } from '../overlay-surface';
+
+/**
+ * A modal that changes shape with the viewport.
+ *
+ * A centred dialog is simply the wrong object on a phone: the pattern every
+ * storefront uses there is a sheet that comes up from the bottom edge, fills
+ * the screen and carries its CTA on a bar at the bottom. One `presentation`
+ * scalar could not say both, so a designer had no way to ask for it.
+ */
+
+const mkModal = (overrides: Record<string, unknown> = {}): ThemeModal =>
+  readThemeModals([
+    { id: 'drawer', name: 'Drawer', presentation: 'modal', ...overrides }
+  ])[0];
+
+const atWidth = (width: number) => {
+  (window as unknown as { innerWidth: number }).innerWidth = width;
+};
+
+const openAt = (width: number, overrides: Record<string, unknown> = {}) => {
+  atWidth(width);
+
+  render(
+    <ThemeModalMount modal={mkModal(overrides)}>
+      <p>composed content</p>
+    </ThemeModalMount>
+  );
+
+  act(() => {
+    openModal('drawer');
+  });
+
+  return document.querySelector('[role="dialog"]') as HTMLElement;
+};
+
+beforeEach(() => {
+  __resetOverlayBusForTests();
+  __resetModalPreviewForTests();
+  registerModalHost();
+  clearAutoOpenRecord('drawer');
+  document.body.style.overflow = '';
+  atWidth(1440);
+});
+
+describe('resolving the presentation for a breakpoint', () => {
+  const modal = {
+    presentation: 'modal' as const,
+    presentationByBreakpoint: { mobile: 'sheet' as const }
+  };
+
+  it('uses the desktop choice where nothing overrides it', () => {
+    expect(resolveModalPresentation(modal, 'desktop')).toBe('modal');
+    expect(resolveModalPresentation(modal, 'tablet')).toBe('modal');
+  });
+
+  it('uses the override at the breakpoint it names', () => {
+    expect(resolveModalPresentation(modal, 'mobile')).toBe('sheet');
+  });
+
+  it('lets a phone inherit the tablet answer rather than the desktop one', () => {
+    // Overrides fall UP the chain: a modal told to be a sheet on tablet should
+    // still be one on the narrower device, or a designer would set two
+    // controls to say a single thing.
+    expect(
+      resolveModalPresentation(
+        {
+          presentation: 'modal',
+          presentationByBreakpoint: { tablet: 'sheet' }
+        },
+        'mobile'
+      )
+    ).toBe('sheet');
+  });
+
+  it('keeps a phone-specific answer over the tablet one', () => {
+    expect(
+      resolveModalPresentation(
+        {
+          presentation: 'modal',
+          presentationByBreakpoint: { tablet: 'drawer', mobile: 'sheet' }
+        },
+        'mobile'
+      )
+    ).toBe('sheet');
+  });
+
+  it('is the desktop choice when no overrides exist at all', () => {
+    expect(resolveModalPresentation({ presentation: 'drawer' }, 'mobile')).toBe(
+      'drawer'
+    );
+  });
+});
+
+describe('the config parser', () => {
+  it('carries the overrides through', () => {
+    expect(
+      mkModal({ presentationByBreakpoint: { mobile: 'sheet' } })
+        .presentationByBreakpoint
+    ).toEqual({ mobile: 'sheet' });
+  });
+
+  it('drops a presentation it does not know', () => {
+    expect(
+      mkModal({ presentationByBreakpoint: { mobile: 'fullscreen' } })
+        .presentationByBreakpoint
+    ).toBeUndefined();
+  });
+
+  it('leaves absence absent, so an old modal presents as it always did', () => {
+    expect(mkModal().presentationByBreakpoint).toBeUndefined();
+  });
+});
+
+describe('the mounted modal', () => {
+  it('is the centred dialog on a desktop viewport', () => {
+    const panel = openAt(1440, {
+      presentationByBreakpoint: { mobile: 'sheet' }
+    });
+
+    // The negatives matter as much as the sheet's positives below: without
+    // them a pair of assertions that never discriminate would pass either way.
+    expect(panel.style.bottom).not.toBe('0px');
+    expect(panel.querySelector('[data-part="handle"]')).toBeNull();
+  });
+
+  it('is a bottom sheet on a phone viewport', () => {
+    const panel = openAt(480, {
+      presentationByBreakpoint: { mobile: 'sheet' }
+    });
+
+    expect(panel.style.bottom).toBe('0px');
+    expect(panel.style.width).toBe('100%');
+    // The grab handle only the sheet draws.
+    expect(panel.querySelector('[data-part="handle"]')).not.toBeNull();
+  });
+});
+
+describe('a stretched sheet', () => {
+  it('is told its height, so the composition has room to hand out', () => {
+    // maxHeight alone leaves the panel content-tall: the stretch turns on with
+    // no free space and a CTA set to `margin-top: auto` does not move.
+    expect(
+      resolveOverlayPanelGeometry({
+        presentation: 'sheet',
+        width: 640,
+        sheetHeight: 92,
+        panelStretch: true
+      })
+    ).toMatchObject({ height: '92vh' });
+  });
+
+  it('still only caps an unstretched one, which should hug its content', () => {
+    const geometry = resolveOverlayPanelGeometry({
+      presentation: 'sheet',
+      width: 640,
+      sheetHeight: 60
+    });
+
+    expect(geometry).toMatchObject({ maxHeight: '60vh' });
+    expect(geometry.height).toBeUndefined();
+  });
+});

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

@@ -22,6 +22,7 @@ import {
   openModal,
   registerModalHost
 } from '../overlay-bus';
+import { isScrollLocked } from '../../hooks/use-overlay';
 import { __resetModalPreviewForTests } from '../use-modal-preview';
 import { clearAutoOpenRecord } from '../modal-frequency';
 import { readThemeModals, ThemeModal } from '../modal-registry';
@@ -76,12 +77,21 @@ describe('ThemeModalMount', () => {
     });
 
     expect(screen.getByRole('dialog')).toHaveAttribute('aria-modal', 'true');
-    expect(document.body.style.overflow).toBe('hidden');
+
+    // Frozen means the lock attribute is on, not that an inline style was
+    // written: this composed mount is the surface where brand code — a
+    // commerce dialog rendered inside a step, say — writes
+    // `body.style.overflow` of its own accord while the modal is up, and an
+    // author rule cannot be overwritten by it. The page's inline slot stays
+    // the page's own the whole way through, locked or not.
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('');
 
     act(() => {
       closeModal('newsletter');
     });
 
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('');
   });
 
@@ -134,6 +144,7 @@ describe('ThemeModalMount', () => {
     // With the page behind still usable, `aria-modal` would be a lie and the
     // scroll lock would be a bug.
     expect(screen.getByRole('dialog')).not.toHaveAttribute('aria-modal');
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('');
   });