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

package/src/auth/form-submit-bus.ts

@@ -0,0 +1,93 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Which named forms are mid-request, for the CTA that submits them from
+ * somewhere else on the page.
+ *
+ * A form's own submit button knows when to disable itself: the state is right
+ * there. A DETACHED CTA — the Button carrying `submitFormId`, which is how a
+ * drawer pins "Continue" to its bottom bar — is outside that form, often
+ * outside its React subtree, so it had no way to know and stayed bright and
+ * clickable while the request ran. Pressing it again did nothing (every submit
+ * handler guards on its own busy flag), but "nothing" is exactly what reads as
+ * broken.
+ *
+ * Module state rather than context, for the same reason `overlay-bus` and
+ * `auth-flow-bus` use it: the CTA and the form can be in different
+ * placeholders, and every placeholder mounts its own React root. The key is the
+ * form's HTML id, which is already the contract the two sides share.
+ */
+const busyForms = new Set<string>();
+
+const listeners = new Set<() => void>();
+
+const notify = (): void => {
+  listeners.forEach((listener) => listener());
+};
+
+const subscribe = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+/**
+ * A form says whether it is working. Called from an effect so the publish
+ * happens after render — writing to module state during one would make two
+ * components disagree about the same tick.
+ */
+export const publishFormSubmitState = (
+  formHtmlId: string,
+  isBusy: boolean
+): void => {
+  if (!formHtmlId) return;
+
+  const wasBusy = busyForms.has(formHtmlId);
+  if (wasBusy === isBusy) return;
+
+  if (isBusy) {
+    busyForms.add(formHtmlId);
+  } else {
+    busyForms.delete(formHtmlId);
+  }
+
+  notify();
+};
+
+/** A form that leaves the page cannot be busy — an unmount says so. */
+export const clearFormSubmitState = (formHtmlId: string): void => {
+  publishFormSubmitState(formHtmlId, false);
+};
+
+export const isFormSubmitting = (formHtmlId: string): boolean =>
+  busyForms.has(formHtmlId);
+
+/**
+ * Nothing is in flight during SSR, so the server snapshot must always say so
+ * or the markup would differ from the client's first paint and hydration would
+ * tear. (Same rule as the other buses.)
+ */
+const falseOnServer = () => false;
+
+/** Subscription for a caller with no form to watch — costs no listener. */
+const neverNotifies = () => () => undefined;
+
+const alwaysFalse = () => false;
+
+/** Pass an empty id for "nothing to watch". */
+export const useFormSubmitState = (formHtmlId: string): boolean =>
+  useSyncExternalStore(
+    formHtmlId ? subscribe : neverNotifies,
+    formHtmlId ? () => isFormSubmitting(formHtmlId) : alwaysFalse,
+    falseOnServer
+  );
+
+/** Test hook: module state outlives a render, so it has to be resettable. */
+export const __resetFormSubmitBusForTests = (): void => {
+  busyForms.clear();
+  listeners.clear();
+};

package/src/auth/otp-form-context.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import React from 'react';
+
+/**
+ * The live state of the OTP form a block is standing inside.
+ *
+ * The form's pieces became blocks the way an auth form's fields did — a phase
+ * wrapper, the code boxes, the resend and change-number controls — but unlike a
+ * field they cannot be dumb: a code box has to write into the ONE code the form
+ * verifies, and a resend has to know whether the countdown has run out. Those
+ * live in the form's own state, and the blocks that need them sit at any depth
+ * below it, so a context is the only way down.
+ *
+ * Outside a form the hook answers null and every block falls back to drawing
+ * itself statically, which is what makes them safe to drop on a page.
+ */
+export interface OtpFormApi {
+  /** Which half of the journey is on screen. */
+  phase: 'phone' | 'code';
+  /** How many boxes the code has — the form owns the number. */
+  codeLength: number;
+  /**
+   * What has been typed so far, at most `codeLength` characters. A box the
+   * shopper skipped over is a blank, so the digits after it keep the positions
+   * they were typed in; a box that draws it renders the blank as empty.
+   */
+  code: string;
+  /** Appends digits (a paste included), capped at `codeLength`. */
+  appendDigits: (digits: string) => void;
+  /**
+   * Writes ONE box. This is what typing into the row does: a code is a row of
+   * separate boxes, so a digit belongs where it was typed rather than at the
+   * end — which is what `appendDigits` alone could offer, and why correcting a
+   * wrong digit used to be impossible.
+   */
+  setDigitAt: (index: number, digit: string) => void;
+  /** Empties ONE box — what Backspace means in the box it was pressed in. */
+  clearDigitAt: (index: number) => void;
+  /** Drops the last digit. Kept for a control that means "undo the last one". */
+  removeLastDigit: () => void;
+  /**
+   * Hands a box to the form so it can keep the caret on the next empty one.
+   * Called with null on unmount, the way a ref callback is.
+   */
+  registerCodeInput: (index: number, element: HTMLInputElement | null) => void;
+  /** Seconds until another code may be asked for. */
+  secondsLeft: number;
+  /** What the countdown counts down FROM, for drawing a ring. */
+  timerSeconds: number;
+  canResend: boolean;
+  /** No-ops while the countdown is running, a request is in flight, or in the canvas. */
+  resend: () => void;
+  /** Back to the phone phase, forgetting the pending verification. */
+  changeNumber: () => void;
+  /**
+   * Whether that is something this form may do. False during a REGISTRATION's
+   * verification: the parked payload is the only copy of the sign-up, so
+   * collecting a new number would throw it away. A control wired to
+   * `changeNumber` should hide or disable itself on this.
+   */
+  canChangeNumber: boolean;
+  /** The number the code went to, for copy that names it. */
+  displayPhone: string;
+  /** True while a send or a verify is in flight. */
+  isBusy: boolean;
+  /**
+   * The canvas. Controls must not fire there (a resend would text a real
+   * shopper), and every phase has to be dressable whatever the state says.
+   */
+  isDesigner: boolean;
+}
+
+const OtpFormContext = React.createContext<OtpFormApi | null>(null);
+
+export const OtpFormProvider = OtpFormContext.Provider;
+
+/** The form in scope, or null for a block standing on its own. */
+export const useOtpForm = (): OtpFormApi | null =>
+  React.useContext(OtpFormContext);

package/src/blocks/__tests__/button-block.test.tsx

@@ -2,6 +2,34 @@ import React from 'react';
 import { render, screen } from '@testing-library/react';
 import ButtonBlock from '../button-block';
 
+/**
+ * The commerce `Modal` this block reaches for, faithful in the one way that
+ * matters here: it writes the PAGE's overflow from an effect that runs on
+ * mount, open or closed, and draws nothing while closed. The shared mock in
+ * `jest/__mocks__` leaves that side effect out, which is exactly what let a
+ * closed dialog mounted for every button on the page go unnoticed.
+ */
+jest.mock('@akinon/next/components/modal', () => {
+  const ReactModule = require('react');
+
+  return {
+    __esModule: true,
+    Modal: ({ open, children }: { open?: boolean; children?: unknown }) => {
+      ReactModule.useEffect(() => {
+        document.body.style.overflow = open ? 'hidden' : 'auto';
+
+        return () => {
+          document.body.style.overflow = 'auto';
+        };
+      }, [open]);
+
+      return open
+        ? ReactModule.createElement(ReactModule.Fragment, null, children)
+        : null;
+    }
+  };
+});
+
 // useLocalization is globally mocked to return locale: 'en-us'.
 // getResponsiveValue / colorToRgba / resolveThemeCssVariables come from the
 // real ../utils module (not mocked). The Modal mock renders nothing while
@@ -96,4 +124,31 @@ describe('ButtonBlock', () => {
       expect(anchor).toHaveAttribute('rel', 'noopener noreferrer');
     });
   });
+  describe('the newsletter feedback dialog', () => {
+    afterEach(() => {
+      document.body.style.overflow = '';
+    });
+
+    it('is not mounted while it has nothing to say, so the page keeps its own scrolling', () => {
+      // Every button used to carry a closed dialog whose mount effect handed
+      // the page its scrolling back. One button inside an open drawer — a step
+      // of an auth flow arriving in one — was enough to unfreeze the page
+      // behind it.
+      renderBlock({ id: 'feedback-1', properties: { text: 'Subscribe' } });
+
+      expect(document.body.style.overflow).toBe('');
+    });
+
+    it('leaves the page alone however many buttons a composition has', () => {
+      renderBlock({ id: 'feedback-2', properties: { text: 'One' } });
+      renderBlock({
+        id: 'feedback-3',
+        properties: { text: 'Two', tag: 'button' }
+      });
+      renderBlock({ id: 'feedback-4', properties: { text: 'Three' } });
+
+      expect(document.body.style.overflow).toBe('');
+      expect(screen.getByText('Two')).toBeInTheDocument();
+    });
+  });
 });

package/src/blocks/__tests__/link-block.test.tsx

@@ -186,13 +186,18 @@ describe('LinkBlock', () => {
 /**
  * The double-drawn card box.
  *
- * `data-block-id` rides the designer wrapper this anchor renders inside, and the
- * generated stylesheet paints the block's box on that wrapper. The wrapper is
- * the grid item, so it stretches to its row; the anchor only hugs its content.
- * A card with one border in the inspector therefore showed two on the page —
- * one closing under the label, one at the bottom of the row.
+ * `data-block-id` rides the designer wrapper this anchor renders inside. A card
+ * with one border in the inspector showed two on the page — one closing under
+ * the label, one at the bottom of the row — because the box was painted on the
+ * wrapper by the sheet AND inlined here by the renderer, and the wrapper is the
+ * grid item that stretches to its row while the anchor only hugs its content.
+ *
+ * The sheet now routes the block's rule to the anchor itself instead
+ * (`data-part="root"`, see INNER_ROOT_BLOCK_TYPES), so the box is declared in
+ * one place. What stays inline is only what a rule cannot express: a theme
+ * token the renderer resolves, and a value an iterator row resolved per clone.
  */
-describe('LinkBlock leaves the block box to the wrapper', () => {
+describe('LinkBlock leaves the block box to the sheet', () => {
   const boxStyles = {
     border: { desktop: '1px solid #d4d4d4' },
     'border-radius': { desktop: '12px' },
@@ -221,7 +226,12 @@ describe('LinkBlock leaves the block box to the wrapper', () => {
     );
   });
 
-  it('still writes the layout keys inline, since the wrapper has one child', () => {
+  /**
+   * The sheet's rule lands on the anchor itself now (`data-part="root"`), so the
+   * layout it declares reaches the element that lays out the card without a
+   * second inline copy shadowing the media queries emitted beside it.
+   */
+  it('leaves the layout keys to the sheet that now targets the anchor', () => {
     const { container } = render(
       <LinkBlock
         {...props({
@@ -240,32 +250,40 @@ describe('LinkBlock leaves the block box to the wrapper', () => {
       />
     );
     const el = anchor(container);
-    expect(el.style.display).toBe('flex');
-    expect(el.style.flexDirection).toBe('column');
-    expect(el.style.gap).toBe('8px');
+    expect(el.style.display).toBe('');
+    expect(el.style.flexDirection).toBe('');
+    expect(el.style.gap).toBe('');
   });
 
   /**
-   * Painting the same colour on the wrapper and on the anchor leaves no
-   * artifact, and an iterator resolves a bound colour per row into this inline
-   * copy — the one shared stylesheet rule cannot hold a value per row.
+   * The one thing the sheet cannot write, and so the only reason an inline copy
+   * survives at all: one rule serves every clone of an iterator, so a colour a
+   * row resolved for itself has nowhere else to live. A plain background, which
+   * the rule CAN hold, stays out of the inline copy.
    */
-  it('still writes background inline, which duplication cannot spoil', () => {
-    const { container } = render(
-      <LinkBlock
-        {...props({
-          block: {
-            id: 'l',
-            properties: { href: '/foo' },
-            styles: {
-              ...boxStyles,
-              'background-color': { desktop: 'rgb(255, 0, 0)' }
-            },
-            blocks: [child({ id: 'a', order: 0 })]
-          }
-        })}
-      />
-    );
-    expect(anchor(container).style.backgroundColor).toBe('rgb(255, 0, 0)');
+  it('inlines a background only when a row resolved it', () => {
+    const withStyles = (extra: Record<string, unknown>) =>
+      render(
+        <LinkBlock
+          {...props({
+            block: {
+              id: 'l',
+              properties: { href: '/foo' },
+              styles: {
+                ...boxStyles,
+                'background-color': { desktop: 'rgb(255, 0, 0)' }
+              },
+              blocks: [child({ id: 'a', order: 0 })],
+              ...extra
+            }
+          })}
+        />
+      );
+
+    expect(anchor(withStyles({}).container).style.backgroundColor).toBe('');
+    expect(
+      anchor(withStyles({ rowStyleKeys: ['background-color'] }).container).style
+        .backgroundColor
+    ).toBe('rgb(255, 0, 0)');
   });
 });

package/src/blocks/__tests__/overlay-sweep.test.tsx

@@ -28,7 +28,7 @@ import HamburgerMenuBlock from '../hamburger-menu-block';
 import SearchBoxBlock from '../search-box-block';
 import MegaMenuBlock from '../mega-menu-block';
 import SortSelectBlock from '../sort-select-block';
-import { useOverlay } from '../../hooks/use-overlay';
+import { isScrollLocked, useOverlay } from '../../hooks/use-overlay';
 import { ThemePageContextProvider } from '../../theme-page-context';
 
 /**
@@ -240,19 +240,25 @@ describe('the filter drawer next to an overlay already on the primitive', () =>
     expect(screen.getByRole('dialog', { name: 'Filters' })).toBeInTheDocument();
   });
 
-  it('counts its scroll lock with every other overlay and gives the page its own overflow back', () => {
+  it('counts its scroll lock with every other overlay and never takes the inline slot the page owns', () => {
     document.body.style.overflow = 'auto';
 
     const { rerender } = render(<Page />);
     openDrawer();
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    // The lock is an author rule keyed off the root, so `body.style.overflow`
+    // stays the page's to write: it reads back exactly what the page set even
+    // while the drawer has the page frozen.
+    expect(document.body.style.overflow).toBe('auto');
 
     rerender(<Page migratedOpen />);
     fireEvent.click(screen.getByRole('button', { name: 'Close' }));
     // One holder left: the page must stay frozen behind the panel still up.
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('auto');
 
     rerender(<Page migratedOpen={false} />);
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
   });
 
@@ -281,6 +287,7 @@ describe('the filter drawer next to an overlay already on the primitive', () =>
     // The canvas is the author's workspace: nothing may steal focus into it,
     // freeze the page being styled, or claim the page is hidden.
     expect(drawer.contains(document.activeElement)).toBe(false);
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
     expect(drawer).not.toHaveAttribute('aria-modal');
 
@@ -296,6 +303,7 @@ describe('the filter drawer next to an overlay already on the primitive', () =>
     render(<Page facetProperties={{ layout: 'panel', lockScroll: false }} />);
     openDrawer();
 
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
   });
 
@@ -527,6 +535,7 @@ describe('the search panel next to an overlay already on the primitive', () => {
     expect(screen.getByRole('dialog', { name: 'Search' })).not.toHaveAttribute(
       'aria-modal'
     );
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('');
   });
 
@@ -565,7 +574,10 @@ describe('the search panel next to an overlay already on the primitive', () => {
       />
     );
     openPanel();
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    // Two holders on one lock, and still not a byte written to the inline slot
+    // the page keeps for itself.
+    expect(document.body.style.overflow).toBe('auto');
 
     // The panel that froze the page first closes while the search panel is up.
     rerender(
@@ -574,9 +586,10 @@ describe('the search panel next to an overlay already on the primitive', () => {
         migratedOpen={false}
       />
     );
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
 
     fireEvent.click(document.querySelector('[data-search-close]') as HTMLElement);
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
   });
 
@@ -691,21 +704,30 @@ describe('the hamburger drawer next to an overlay already on the primitive', ()
    * `hidden` as "the page's own value", so the other panel closing thawed the
    * page under a drawer still up — and the drawer closing wrote `hidden` back
    * for good, leaving a storefront no one can scroll.
+   *
+   * Nothing captures anything now: every drawer on the page is one holder of a
+   * single counted lock, and the lock is an author rule on the root rather than
+   * a value borrowed out of the inline slot the page shares with brand code.
+   * So the two facts below are separate — whether the page is held still, and
+   * what the page itself has written — and the drawer decides only the first.
    */
   it('counts its scroll lock with every other overlay', () => {
     document.body.style.overflow = 'auto';
 
     const { rerender } = render(<HamburgerPage migratedOpen />);
     openDrawerMenu();
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('auto');
 
     // The panel that froze the page first closes while the drawer is still up.
     rerender(<HamburgerPage migratedOpen={false} />);
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('auto');
 
     fireEvent.click(
       document.querySelector('[data-hamburger-close]') as HTMLElement
     );
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
   });
 
@@ -714,6 +736,7 @@ describe('the hamburger drawer next to an overlay already on the primitive', ()
     render(<HamburgerPage properties={{ lockScroll: false }} />);
     openDrawerMenu();
 
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
   });
 });

package/src/blocks/__tests__/product-gallery-block.test.tsx

@@ -3,6 +3,7 @@ import path from 'path';
 import React from 'react';
 import { fireEvent, render } from '@testing-library/react';
 import ProductGalleryBlock from '../product-gallery-block';
+import { isScrollLocked } from '../../hooks/use-overlay';
 import { ThemePageContextProvider } from '../../theme-page-context';
 
 /**
@@ -360,24 +361,30 @@ describe('ProductGalleryBlock — full-screen viewer', () => {
     expect(container.querySelector('[role="dialog"]')).toBeNull();
   });
 
-  it('gives the page back its own scrolling on every visit', () => {
-    // A storefront that sets its own overflow has to get THAT value back.
+  it('lets the page scroll again after every visit, and never takes its overflow', () => {
+    // The overflow a storefront sets is the storefront's, and it stays that
+    // way throughout: the lock is an author rule switched on by an attribute,
+    // so it never borrows the inline slot and has nothing to put back.
     document.body.style.overflow = 'auto';
 
     const { container, unmount } = renderBlock({ enableViewer: true }, PRODUCT);
 
     openViewer(container);
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('auto');
 
     fireEvent.click(container.querySelector('[data-part="viewer-close"]')!);
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
 
     // A lock leaked on the first visit leaves the page frozen from here on.
     openViewer(container);
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    expect(document.body.style.overflow).toBe('auto');
 
     // Navigating away with the viewer up must not freeze what comes next.
     unmount();
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('auto');
 
     document.body.style.overflow = '';
@@ -389,6 +396,7 @@ describe('ProductGalleryBlock — full-screen viewer', () => {
     });
     openViewer(container);
 
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('');
   });
 

package/src/blocks/__tests__/product-recommendations-block.test.tsx

@@ -64,6 +64,7 @@ import {
   readRecentlyViewed,
   recordRecentlyViewed
 } from '../recently-viewed-store';
+import { isScrollLocked } from '../../hooks/use-overlay';
 
 const props = (properties: Record<string, unknown> = {}, over: Record<string, unknown> = {}) =>
   ({
@@ -564,18 +565,23 @@ describe('quick view overlay', () => {
     expect(document.activeElement).toBe(opener);
   });
 
-  it('gives the page its own overflow back when the overlay closes', () => {
+  it('freezes the page while the overlay is up and lets it scroll again on close', () => {
     const { container } = renderBlock(
       <ProductRecommendationsBlock {...props(QUICK_VIEW)} />
     );
     fireEvent.click(trigger(container));
-    expect(document.body.style.overflow).toBe('hidden');
+    expect(isScrollLocked()).toBe(true);
+    // The freeze is an author rule keyed off an attribute, so the inline
+    // overflow slot stays the page's own throughout: nothing was borrowed
+    // while the panel was up and nothing has to be given back after it.
+    expect(document.body.style.overflow).toBe('');
 
     fireEvent.click(
       container.querySelector(
         '[data-product-card-quick-view-close]'
       ) as HTMLElement
     );
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('');
   });
 
@@ -593,6 +599,7 @@ describe('quick view overlay', () => {
     expect(panel).not.toBeNull();
     // No focus stolen into the canvas, no frozen page, no `aria-modal` claim.
     expect(panel.contains(document.activeElement)).toBe(false);
+    expect(isScrollLocked()).toBe(false);
     expect(document.body.style.overflow).toBe('');
     expect(panel.getAttribute('aria-modal')).toBeNull();