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

package/src/blocks/slider-block.tsx

@@ -10,6 +10,7 @@ import {
   applyFirstSlideImageLoading,
   getCSSStyles,
   getResponsiveValue,
+  partAttrs,
   resolveThemeCssVariables
 } from '../utils';
 import { DESKTOP_MIN_WIDTH, isNarrowBreakpoint } from '../utils/breakpoints';
@@ -44,6 +45,51 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
   const themeSettings = useThemeSettingsContext();
   const carouselRef = React.useRef<Carousel>(null);
   const containerRef = React.useRef<HTMLDivElement>(null);
+  /**
+   * Whether the pointer (or the keyboard) is inside the slider, for the
+   * arrows-on-hover option below.
+   *
+   * REACT STATE RATHER THAN A `group-hover:` CLASS, FOR TWO REASONS THAT BOTH
+   * END WITH THE ARROWS NEVER COMING BACK.
+   *
+   * Tailwind 4 compiles `group-hover:` inside `@media (hover: hover)` while the
+   * `opacity-0` it pairs with is unconditional — so a phone would get the
+   * hiding half of the rule and never the revealing half. State can ask about
+   * hover capability directly, which is what `canHover` below does.
+   *
+   * And scanning is not guaranteed: the reference app lists this package in its
+   * Tailwind `content` (apps/projectzeronext/tailwind.config.js), but a brand
+   * whose config only lists `@akinon/next` plus its payment plugins does not —
+   * so a class only this file writes may never be generated there. The static
+   * classes the arrows already rely on (`left-4`, `-translate-y-1/2`) come from
+   * the brand's own source using them too.
+   */
+  const [pointerInside, setPointerInside] = React.useState(false);
+  /**
+   * AND WHETHER THIS DEVICE CAN HOVER AT ALL.
+   *
+   * A phone never sends the pointer event that brings the arrows back, so
+   * "arrows on hover" would mean "no arrows, ever" there — the option is
+   * therefore ignored wherever the pointer cannot hover. Assumed true until the
+   * client answers: the server has no media queries, and a desktop flashing its
+   * arrows before hiding them reads worse than a phone showing them a frame
+   * late.
+   */
+  const [canHover, setCanHover] = React.useState(true);
+
+  React.useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+
+    const query = window.matchMedia('(hover: hover)');
+    setCanHover(query.matches);
+
+    const handleChange = (event: MediaQueryListEvent) =>
+      setCanHover(event.matches);
+
+    // A mouse plugged into a tablet flips this mid-session.
+    query.addEventListener?.('change', handleChange);
+    return () => query.removeEventListener?.('change', handleChange);
+  }, []);
 
   const leftArrowIconBlock = block.blocks?.find(
     (b: any) => b.type === 'icon' && b.label === 'Left Arrow Icon'
@@ -164,6 +210,11 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
     currentBreakpoint,
     false
   );
+  // Arrows that only appear while the slider is hovered. Off by default, so a
+  // slider that never authored it renders exactly as before.
+  const arrowsOnHover = Boolean(
+    getResponsiveValue(getConfigEntry('arrows-on-hover'), currentBreakpoint, false)
+  );
   const useAutoPlay = getResponsiveValue(
     getConfigEntry('autoplay'),
     currentBreakpoint,
@@ -437,6 +488,66 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
       )
     ) || 1;
 
+  /**
+   * The angle the panel's Rotate box holds. It stores a bare number, which is
+   * not valid CSS on its own, so a number becomes degrees and anything with a
+   * unit (deg/turn/rad/grad) is passed through untouched.
+   */
+  const arrowAngle = (value: unknown): string | undefined => {
+    let text = String(value ?? '').trim();
+    if (!text) return undefined;
+    // The panel's Rotate box is free text, so it invites the function spelling
+    // as readily as the value one. Left as typed it would emit
+    // `rotate: rotate(45deg)`, which the browser drops without a word.
+    const wrapped = /^rotate\(([^)]+)\)$/i.exec(text);
+    if (wrapped) text = wrapped[1].trim();
+    // A bare number is degrees — including the leading-dot spelling, which the
+    // earlier pattern rejected and then emitted as the invalid `rotate: .5`.
+    return /^-?(?:\d+(?:\.\d+)?|\.\d+)$/.test(text) ? `${text}deg` : text;
+  };
+
+  /**
+   * ON THE GLYPH, NOT ON THE BUTTON, AND VIA `rotate` RATHER THAN `transform`.
+   *
+   * The rotation a designer wants is the arrow pointing the other way, not the
+   * button's background box turning with it — the same SVG ships for both
+   * sides, so mirroring the left one is the whole point.
+   *
+   * `rotate` rather than `transform` because of the centring class it has to
+   * live beside. Tailwind 4 compiles `-translate-y-1/2` to the individual
+   * `translate` property, and the individual properties are composed in a fixed
+   * order — translate, then rotate, then scale, then `transform` — so a rotation
+   * written here cannot displace the centring, and it turns the glyph about its
+   * own centre. A raw `transform` would have to restate the translate (and did
+   * clobber it under Tailwind 3).
+   *
+   * NOTE THE DIVERGENCE, which is a real one: the section arrows in
+   * utils/slider-arrows.tsx put `data-block-id` on the BUTTON, so there the
+   * generated rule for this same `rotate` key turns the plate and the glyph
+   * together. Here only the glyph turns.
+   *
+   * A rule for this icon block's `rotate` is in fact already in the generated
+   * stylesheet — `collectBlockCSS` recurses into every child block — and
+   * matches nothing only because this button carries no `data-block-id`. If one
+   * is ever added (to let borders, shadows or part keys reach the plate), that
+   * rule and the inline value below would both apply and the glyph would sit at
+   * twice the authored angle; drop one of the two when that happens.
+   */
+  const leftArrowIconRotate = arrowAngle(
+    getResponsiveValue(
+      leftArrowIconBlock?.styles?.['rotate'],
+      currentBreakpoint,
+      ''
+    )
+  );
+  const rightArrowIconRotate = arrowAngle(
+    getResponsiveValue(
+      rightArrowIconBlock?.styles?.['rotate'],
+      currentBreakpoint,
+      ''
+    )
+  );
+
   // Process SVGs with color
   const processedLeftArrowUrl = isInlineSvg(leftArrowIconUrl)
     ? processInlineSVG(leftArrowIconUrl, leftArrowIconColor)
@@ -569,6 +680,25 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
   const leftArrowButtonStyle = arrowGeometry(leftArrowIconBlock);
   const rightArrowButtonStyle = arrowGeometry(rightArrowIconBlock);
 
+  /**
+   * What the arrows-on-hover option adds to every arrow button.
+   *
+   * The designer canvas is exempt: an arrow a merchant cannot see is an arrow
+   * they cannot select, and the panel is where the option is being switched on
+   * in the first place. `pointer-events` follows the opacity so an invisible
+   * arrow cannot be clicked, and the transition is inline for the same reason
+   * the state above is React — no class this package writes reaches the brand's
+   * stylesheet.
+   */
+  const arrowRevealStyle: React.CSSProperties =
+    arrowsOnHover && canHover && !isDesigner
+      ? {
+          opacity: pointerInside ? 1 : 0,
+          pointerEvents: pointerInside ? 'auto' : 'none',
+          transition: 'opacity 200ms ease'
+        }
+      : {};
+
   /**
    * The class defaults step aside per axis for whatever the author set.
    * An inline `left` already outranks the `left-4` class, but the pair that
@@ -633,7 +763,8 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
         alignItems: 'center',
         justifyContent: 'center',
         cursor: 'pointer',
-        padding: 0
+        padding: 0,
+        ...arrowRevealStyle
       }}
       aria-label="Previous"
     >
@@ -644,6 +775,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
           width: `${leftArrowIconSize}px`,
           height: `${leftArrowIconSize}px`,
           opacity: leftArrowIconOpacity,
+          rotate: leftArrowIconRotate,
           pointerEvents: 'none'
         }}
       />
@@ -673,7 +805,8 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
         alignItems: 'center',
         justifyContent: 'center',
         cursor: 'pointer',
-        padding: 0
+        padding: 0,
+        ...arrowRevealStyle
       }}
       aria-label="Next"
     >
@@ -684,6 +817,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
           width: `${rightArrowIconSize}px`,
           height: `${rightArrowIconSize}px`,
           opacity: rightArrowIconOpacity,
+          rotate: rightArrowIconRotate,
           pointerEvents: 'none'
         }}
       />
@@ -708,6 +842,16 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
       )}
       style={sectionStyles}
       {...carouselSsr.gateProps}
+      // Focus rides along with the pointer so the arrows are reachable by
+      // keyboard; both events bubble in React, so tabbing INTO an arrow counts.
+      onMouseEnter={
+        arrowsOnHover ? () => setPointerInside(true) : undefined
+      }
+      onMouseLeave={
+        arrowsOnHover ? () => setPointerInside(false) : undefined
+      }
+      onFocus={arrowsOnHover ? () => setPointerInside(true) : undefined}
+      onBlur={arrowsOnHover ? () => setPointerInside(false) : undefined}
     >
       <div style={{ position: 'relative' }}>
         <Carousel
@@ -794,8 +938,26 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
                 : childBlock;
 
             return (
+              /*
+               * THE ONLY BOX BETWEEN A SLIDE'S CARD AND THE TRACK, AND THE ONE
+               * LINK IN THE CHAIN THAT USED TO HAVE NO HEIGHT.
+               *
+               * react-multi-carousel stretches every `li` to the tallest slide,
+               * so a card asking for `height: 100%` has a definite height two
+               * levels up and an auto-height one directly above it — this
+               * wrapper. The card's own percentage therefore resolved to `auto`
+               * and every slide was as tall as its own text, which is what made
+               * a row of cards with a divider border look ragged.
+               *
+               * Named as a part so the panel can give it a height rather than
+               * a brand carrying scoped custom CSS per section. The inline
+               * padding stays: part declarations are emitted `!important`
+               * (generatePartCSS), so an authored `slide/padding-left` still
+               * wins over it.
+               */
               <div
                 key={childBlock.id}
+                {...partAttrs('slide')}
                 style={
                   flushEdges
                     ? {
@@ -860,7 +1022,8 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
                 alignItems: 'center',
                 justifyContent: 'center',
                 cursor: 'pointer',
-                padding: 0
+                padding: 0,
+                ...arrowRevealStyle
               }}
               aria-label="Previous"
             >
@@ -871,6 +1034,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
                   width: `${leftArrowIconSize}px`,
                   height: `${leftArrowIconSize}px`,
                   opacity: leftArrowIconOpacity,
+                  rotate: leftArrowIconRotate,
                   pointerEvents: 'none'
                 }}
               />
@@ -891,7 +1055,8 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
                 alignItems: 'center',
                 justifyContent: 'center',
                 cursor: 'pointer',
-                padding: 0
+                padding: 0,
+                ...arrowRevealStyle
               }}
               aria-label="Next"
             >
@@ -902,6 +1067,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
                   width: `${rightArrowIconSize}px`,
                   height: `${rightArrowIconSize}px`,
                   opacity: rightArrowIconOpacity,
+                  rotate: rightArrowIconRotate,
                   pointerEvents: 'none'
                 }}
               />

package/src/chrome/__tests__/theme-config-source.test.ts

@@ -93,7 +93,8 @@ describe('readThemeConfig', () => {
             lockScroll: true,
             padding: undefined,
             showSheetHandle: true,
-            stretchContent: false
+            stretchContent: false,
+            showLoading: true
           },
           autoTrigger: undefined,
           visibilityRules: undefined

package/src/chrome/placeholder-slugs.ts

@@ -63,6 +63,9 @@ export const PLACEHOLDER_SLUGS = {
   // Auth
   register: 'register-page-body',
   forgotPassword: 'forgot-password-body',
+  // The screen the reset MAIL lands on — a different page from the one that
+  // ASKS for the mail. `reset-password-block` is what fills it.
+  resetPassword: 'reset-password-body',
   guestLogin: 'guest-login-body',
 
   // Content

package/src/chrome/route-slug.ts

@@ -71,6 +71,13 @@ const DEFAULT_RULES: RouteSlugRule[] = [
     PLACEHOLDER_SLUGS.forgotPassword
   ],
   [/^\/users\/password\/reset(\/|$)/, PLACEHOLDER_SLUGS.forgotPassword],
+  // The screen the reset MAIL lands on, which is a different page from the one
+  // above: that one ASKS for the mail, this one is where the link goes. The
+  // token rides in the path as a catch-all — and may itself contain slashes —
+  // so the rule stops at the first boundary and lets the block read the rest.
+  // Ordering is safe either way: `/users/password/reset` and `/users/reset`
+  // cannot both match a path.
+  [/^\/users\/reset(\/|$)/, PLACEHOLDER_SLUGS.resetPassword],
   [/^\/(users\/)?auth\/guest(\/|$)/, PLACEHOLDER_SLUGS.guestLogin],
   [/^\/(users\/)?auth\/?$/, PLACEHOLDER_SLUGS.auth],
 
@@ -143,6 +150,10 @@ const PAGE_MOUNTED_SLUGS = new Set<string>([
   PLACEHOLDER_SLUGS.auth,
   PLACEHOLDER_SLUGS.register,
   PLACEHOLDER_SLUGS.forgotPassword,
+  // Mounted by its own layout beside the catch-all page that reads the token,
+  // for the same reason the two above are: the page is a client component, so
+  // the handover cannot live in it.
+  PLACEHOLDER_SLUGS.resetPassword,
   PLACEHOLDER_SLUGS.guestLogin,
   PLACEHOLDER_SLUGS.flatPage,
   // Mounted by the not-found boundary itself, which renders on any unmatched

package/src/index.ts

@@ -99,6 +99,16 @@ export {
   useOpenModalIds
 } from './overlays/overlay-bus';
 
+/**
+ * Which modal the composition is inside, for a brand's OWN auth surface: a
+ * hand-written form composed into a drawer can now close the drawer the way
+ * the built-in ones do. See `overlays/modal-host-context.tsx`.
+ */
+export {
+  useModalHostId,
+  useHostModalCloser
+} from './overlays/modal-host-context';
+
 export {
   readThemeModals,
   MODAL_PRESENTATIONS

package/src/overlays/__tests__/modal-loading.test.tsx

@@ -0,0 +1,235 @@
+import { act, render, screen } 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 { clearAutoOpenRecord } from '../modal-frequency';
+import { buildModalChromeCss } from '../modal-chrome-css';
+import { readThemeModals, ThemeModal } from '../modal-registry';
+import {
+  __resetOverlayBusForTests,
+  openModal,
+  closeModal,
+  registerModalHost
+} from '../overlay-bus';
+import { OverlayLoadingLayer } from '../overlay-loading';
+import { LayeredOverlaySurface } from '../overlay-surface';
+import ThemeModalMount from '../theme-modal-mount';
+import { __resetModalPreviewForTests } from '../use-modal-preview';
+
+/**
+ * What a modal shows while its composition is still committing.
+ *
+ * The pause is the commit, not a fetch: a composed modal's content ships with
+ * the page, and a large one mounts ninety blocks at once. So the host draws
+ * the panel and a loading layer in an urgent commit and reveals the
+ * composition in a transition — which is also why nothing here has to fight
+ * the clock: `act()` flushes transitions, so the tests see the settled state
+ * unless they render a surface directly.
+ */
+
+const mkModal = (chrome: Record<string, unknown> = {}): ThemeModal =>
+  readThemeModals([{ id: 'login', name: 'Login', chrome }])[0];
+
+const openWith = (chrome: Record<string, unknown> = {}, isDesigner = false) => {
+  if (isDesigner) {
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+  }
+
+  render(
+    <ThemeModalMount modal={mkModal(chrome)}>
+      <p>composed content</p>
+    </ThemeModalMount>
+  );
+
+  act(() => {
+    openModal('login');
+  });
+};
+
+beforeEach(() => {
+  __resetOverlayBusForTests();
+  __resetModalPreviewForTests();
+  registerModalHost();
+  clearAutoOpenRecord('login');
+  delete (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner;
+});
+
+describe('the loading settings', () => {
+  it('is on for a modal that never mentioned it, and off when asked', () => {
+    expect(mkModal().chrome.showLoading).toBe(true);
+    expect(mkModal({ showLoading: false }).chrome.showLoading).toBe(false);
+  });
+
+  it('keeps an unauthored delay absent, so the surface default stands', () => {
+    expect(mkModal().chrome.loadingDelay).toBeUndefined();
+    // Zero is a real answer — "show it at once" — and must survive as one.
+    expect(mkModal({ loadingDelay: 0 }).chrome.loadingDelay).toBe(0);
+    expect(mkModal({ loadingDelay: 400 }).chrome.loadingDelay).toBe(400);
+    // A delay longer than the wait it explains is a typo.
+    expect(mkModal({ loadingDelay: 90000 }).chrome.loadingDelay).toBe(2000);
+    expect(mkModal({ loadingDelay: -5 }).chrome.loadingDelay).toBe(0);
+    expect(
+      mkModal({ loadingDelay: 'soon' }).chrome.loadingDelay
+    ).toBeUndefined();
+  });
+
+  it('keeps the label absence-preserving, since the package has no copy', () => {
+    expect(mkModal().chrome.loadingLabel).toBeUndefined();
+    expect(
+      mkModal({ loadingLabel: '   ' }).chrome.loadingLabel
+    ).toBeUndefined();
+    expect(mkModal({ loadingLabel: 'Yükleniyor' }).chrome.loadingLabel).toBe(
+      'Yükleniyor'
+    );
+  });
+});
+
+describe('the layer itself', () => {
+  const renderLayer = (props: { label?: string; delay?: number } = {}) => {
+    render(
+      <LayeredOverlaySurface
+        presentation="drawer"
+        overlayProps={{ ref: undefined, 'aria-modal': 'true' }}
+        ariaLabel="Login"
+        showBackdrop
+        closeOnOverlay={false}
+        onDismiss={() => undefined}
+        width={480}
+        widthUnit="px"
+        loading={<OverlayLoadingLayer {...props} />}
+        panelBusy
+      >
+        <p>composed content</p>
+      </LayeredOverlaySurface>
+    );
+
+    // The LAST one: a test that renders twice to compare two settings stacks
+    // two containers, and the first match would answer for the previous render.
+    return Array.from(
+      document.querySelectorAll('[data-part="loading"]')
+    ).pop() as HTMLElement;
+  };
+
+  it('starts invisible and fades in only after the delay', () => {
+    const layer = renderLayer({ delay: 400 });
+
+    expect(layer.style.opacity).toBe('0');
+    expect(layer.style.animation).toContain('400ms forwards');
+  });
+
+  it('falls back to the surface delay when the modal authored none', () => {
+    expect(renderLayer().style.animation).toContain('150ms forwards');
+  });
+
+  it('never takes a click meant for the panel underneath', () => {
+    expect(renderLayer().style.pointerEvents).toBe('none');
+  });
+
+  it('sizes itself in flow, so a scrolling panel cannot scroll it away', () => {
+    const layer = renderLayer();
+
+    expect(layer.style.position).toBe('');
+    // Fills a stretched panel's flex column; the min-height is what a centred
+    // dialog with nothing in it has to go on.
+    expect(layer.style.flex).toBe('1 1 auto');
+    expect(layer.style.minHeight).toBe('160px');
+  });
+
+  it('is silent for assistive tech until a designer gives it words', () => {
+    expect(renderLayer().getAttribute('aria-hidden')).toBe('true');
+
+    const labelled = renderLayer({ label: 'Yükleniyor' });
+
+    expect(labelled.getAttribute('aria-hidden')).toBeNull();
+    expect(
+      labelled.querySelector('[data-part="loading-text"]')?.textContent
+    ).toBe('Yükleniyor');
+  });
+
+  it('tells assistive tech the dialog is still filling', () => {
+    renderLayer();
+
+    expect(
+      document.querySelector('[role="dialog"]')?.getAttribute('aria-busy')
+    ).toBe('true');
+  });
+});
+
+describe('a modal that is holding one', () => {
+  it('has the composition and no layer left once the transition lands', () => {
+    openWith();
+
+    expect(screen.getByText('composed content')).toBeInTheDocument();
+    // Both halves go together: nothing drawn over the content, and no
+    // attribute left claiming the dialog is still filling.
+    expect(document.querySelector('[data-part="loading"]')).toBeNull();
+    expect(
+      document.querySelector('[role="dialog"]')?.getAttribute('aria-busy')
+    ).toBeNull();
+  });
+
+  it('draws no layer at all when the setting is off', () => {
+    openWith({ showLoading: false });
+
+    expect(screen.getByText('composed content')).toBeInTheDocument();
+    expect(document.querySelector('[data-part="loading"]')).toBeNull();
+  });
+
+  it('shows the composition at once in the canvas, where the wait is not real', () => {
+    openWith({}, true);
+
+    expect(screen.getByText('composed content')).toBeInTheDocument();
+    expect(document.querySelector('[data-part="loading"]')).toBeNull();
+  });
+
+  it('starts from the cheap commit again on the next open', () => {
+    openWith();
+
+    act(() => {
+      closeModal('login');
+    });
+
+    expect(document.querySelector('[role="dialog"]')).toBeNull();
+
+    act(() => {
+      openModal('login');
+    });
+
+    // The reopen is a fresh mount of the composition, so the reveal has to
+    // have been reset — a latched one would leave the second open with no
+    // layer to cover it.
+    expect(screen.getByText('composed content')).toBeInTheDocument();
+  });
+});
+
+describe('the designer styles', () => {
+  it('reach the layer, its mark and its words', () => {
+    const css = buildModalChromeCss({
+      id: 'login',
+      styles: {
+        'loading/background-color': '#ffffff',
+        'loading-mark/border-color': '#00321b',
+        'loading-text/font-size': '15px'
+      }
+    });
+
+    expect(css).toContain('[data-theme-modal="login"] [data-part="loading"]');
+    expect(css).toContain('[data-part="loading-mark"]');
+    expect(css).toContain('[data-part="loading-text"]');
+    // The panel's own inline styles would otherwise outrank every rule here.
+    expect(css).toContain('!important');
+  });
+});

package/src/overlays/__tests__/modal-registry.test.ts

@@ -63,7 +63,11 @@ describe('readThemeModals', () => {
           // surface, so an unauthored padding must stay unauthored here.
           padding: undefined,
           showSheetHandle: true,
-          stretchContent: false
+          stretchContent: false,
+          // On for a modal that never mentioned it, which is safe precisely
+          // because the layer waits: an unauthored delay leaves the surface's
+          // own 150ms, and nothing a small composition can outrun changes.
+          showLoading: true
         },
         autoTrigger: undefined,
         visibilityRules: undefined

package/src/overlays/modal-chrome-css.ts

@@ -41,7 +41,14 @@ export const MODAL_CHROME_PARTS = [
   'overlay',
   'close',
   'close-text',
-  'handle'
+  'handle',
+  // The layer shown while a composition is still committing, its mark, and the
+  // authored words beside it. Chrome rather than blocks for the usual reason:
+  // they are drawn by `overlay-loading.tsx` from inline styles and hang off no
+  // `[data-block-id]`, so no block part rule could ever reach them.
+  'loading',
+  'loading-mark',
+  'loading-text'
 ] as const;
 
 export type ModalChromePart = (typeof MODAL_CHROME_PARTS)[number];

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

@@ -0,0 +1,66 @@
+'use client';
+
+import React from 'react';
+
+import { closeModal } from './overlay-bus';
+
+/**
+ * Which modal the composition being rendered is INSIDE.
+ *
+ * A composed form had no way to know. The consequence a shopper met: signing
+ * in inside the auth drawer left the drawer open over the page, because the
+ * only close a form could perform was `closeAllModals()` behind an authored
+ * toggle — and that toggle defaults to off, deliberately, since "close every
+ * modal on the page" is not something a form on a plain page should ever do
+ * unasked. So the safe default and the useful one were in conflict, and the
+ * live GANT drawer's SAVED config shows exactly how that ends — measured off
+ * the storefront's own payload, not off the shipped template: the OTP form has
+ * the toggle on and the login and register forms do not, so signing in with an
+ * e-mail left the drawer covering the page while the phone path closed it. A
+ * designer had no way to know they had to tick three separate boxes.
+ *
+ * With the host's id in hand the conflict disappears: a form closes THE MODAL
+ * IT IS IN, which is never a surprise, and a form that is not in one closes
+ * nothing at all.
+ *
+ * Same shape and same reason as `AuthFlowIdContext` — a host telling its
+ * composed children which instance of itself they belong to, because they are
+ * blocks at any depth and the host has no reference to hand them.
+ */
+const ModalHostIdContext = React.createContext<string>('');
+
+export const ModalHostIdProvider = ModalHostIdContext.Provider;
+
+/** The id of the modal this block is inside, or '' when it is not in one. */
+export const useModalHostId = (): string =>
+  React.useContext(ModalHostIdContext);
+
+/**
+ * "My task is finished — close the surface I am on."
+ *
+ * One helper rather than the same three lines in every block that can finish,
+ * because the rule is the same everywhere and the mistakes would not be: a
+ * form that closes a modal it is not in, or that closes one while the shopper
+ * still has something to read.
+ *
+ * Which blocks turn it on by DEFAULT is a judgement about their success state,
+ * not about the mechanism:
+ *
+ *  - a sign-in leaves nothing to read — the shopper is in — so the auth forms
+ *    default to closing, and that is the bug this whole family exists to fix;
+ *  - "check your inbox", "thanks for subscribing", "your password has been
+ *    changed" are the point of the success state, so those forms default to
+ *    staying open and let the designer decide otherwise.
+ *
+ * Returns a stable no-op when the block is not in a modal, so a caller can
+ * fire it unconditionally.
+ */
+export const useHostModalCloser = (enabled: boolean): (() => void) => {
+  const hostModalId = useModalHostId();
+
+  return React.useCallback(() => {
+    if (!enabled || !hostModalId) return;
+
+    closeModal(hostModalId);
+  }, [enabled, hostModalId]);
+};