@akinon/pz-theme 2.0.104 → 2.0.105-rc.0

package/CHANGELOG.md

@@ -1,10 +1,46 @@
 # @akinon/pz-theme
 
+## 2.0.105-rc.0
+
+### Patch Changes
+
+- Updated dependencies [86187b1c]
+- Updated dependencies [0cf9ea239]
+- Updated dependencies [324f97d55]
+- Updated dependencies [51ea06888]
+- Updated dependencies
+- Updated dependencies [2fea41430]
+- Updated dependencies [b55acb768]
+- Updated dependencies [760258c1c]
+- Updated dependencies [143be2b9d]
+- Updated dependencies [7889b08fe]
+- Updated dependencies [9f8cd3bc5]
+- Updated dependencies [bfafa3f49]
+- Updated dependencies [57d7eb305]
+- Updated dependencies [d99a6a7d5]
+- Updated dependencies [9db81a714]
+- Updated dependencies [591e345e1]
+- Updated dependencies [4de5303c5]
+- Updated dependencies [95b139dc1]
+- Updated dependencies [1d00f2d06]
+- Updated dependencies [4ac7b2a1e]
+- Updated dependencies [e9598c71d]
+- Updated dependencies [4998a9631]
+- Updated dependencies [804d2bd6c]
+- Updated dependencies [3909d3224]
+- Updated dependencies [6a3d8a631]
+- Updated dependencies [e18836b20]
+- Updated dependencies [b1111d7b1]
+- Updated dependencies [1595d45]
+- Updated dependencies [dca1281]
+  - @akinon/next@2.0.105-rc.0
+  - @akinon/theme-contract@2.0.105-rc.0
+
 ## 2.0.104
 
 ### Patch Changes
 
-- Updated dependencies [cf621e2]
+- 31d4df3: ZERO-5066: Run the add-to-cart block's action only after the product is added to the basket
   - @akinon/next@2.0.104
   - @akinon/theme-contract@2.0.104
 

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.104",
+  "version": "2.0.105-rc.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.104",
+    "@akinon/next": "2.0.105-rc.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.104",
+    "@akinon/theme-contract": "2.0.105-rc.0",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.104",
+    "@akinon/next": "2.0.105-rc.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/custom-catalog-announce.test.ts

@@ -4,13 +4,15 @@
  * `getCustomCatalog()` had no caller: a brand could register a custom block
  * and the editor could never learn the type existed. The announce is the only
  * channel, and it is shared with the placeholder slugs — which is what makes
- * the gating interesting. Three answers have to hold at once:
+ * the gating interesting. Four answers have to hold at once:
  *
  *   - no placeholders, no frame (the editor's subscriber reloads the theme
  *     against whatever slugs a frame carries, so an empty one is destructive)
  *   - no proven designer, no catalog (a storefront is framed in production by
  *     payment providers, and the catalog is brand IP)
  *   - every frame carries the catalog whole, so the receiver can replace
+ *   - every frame, gated or not, carries the action capabilities (a fact about
+ *     the theme version, and for most builds the gated frame is the only one)
  */
 
 const EDITOR_ORIGIN = 'http://editor.example';
@@ -318,6 +320,52 @@ describe('PLACEHOLDERS_AVAILABLE announce', () => {
     expect(postMessage).toHaveBeenCalledTimes(1);
   });
 
+  it('announces the add-to-cart action capability before the editor proves itself', () => {
+    const { registry } = load();
+
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    // On the gated frame, not only the designer one. A build with no custom
+    // catalog never sends a second frame (see the test above), so for it this
+    // is the only frame the editor ever gets — and the editor reads a frame
+    // without the field as a renderer that still runs the action on the click,
+    // keeping "On Click" and every option on a block that no longer does.
+    //
+    // The literal string rather than the constant: the editor matches it by
+    // name and drops a name it does not know, so this pins the wire value a
+    // rename would silently break.
+    expect(frames()[0].actionCapabilities).toEqual(['add-to-cart-after-add']);
+  });
+
+  it('keeps the action capability on the designer re-announce too', () => {
+    const { registry, register } = load();
+
+    register.registerCustomBlocks('acme', { 'promo-strip': Promo });
+    registry.registerPlaceholder('header');
+    jest.advanceTimersByTime(100);
+
+    (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
+      true;
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        origin: EDITOR_ORIGIN,
+        source: window.parent as Window,
+        data: { type: 'SET_THEME_EDITOR_COOKIE', data: true }
+      })
+    );
+    jest.advanceTimersByTime(100);
+
+    // Every frame, not just the first. The editor replaces its capability set
+    // with each announce, so a later frame without the field would turn the
+    // panel back to "On Click" halfway through a session.
+    expect(postMessage).toHaveBeenCalledTimes(2);
+    expect(frames().map((frame) => frame.actionCapabilities)).toEqual([
+      ['add-to-cart-after-add'],
+      ['add-to-cart-after-add']
+    ]);
+  });
+
   it('sends the whole catalog every time, so a re-announce replaces', () => {
     (window as { __themeEditorDesigner?: boolean }).__themeEditorDesigner =
       true;

package/src/action-capabilities.ts

@@ -0,0 +1,38 @@
+/**
+ * What this build's block renderer does with an authored action beyond running
+ * it on the click, announced to the editor.
+ *
+ * The editor words a block's action panel after what the storefront in front
+ * of it will actually do, so it has to be told — one Omnitron serves channels
+ * whose storefronts pin their own theme version, and a v1 brand cannot build
+ * past the line it is on, so "the repo has it" is not a fact the editor may
+ * assume.
+ *
+ *  - `add-to-cart-after-add`  the Add to Cart block runs its stored action
+ *                             itself once the add succeeds, rather than leaving
+ *                             it to the wrapper to run on the click (see
+ *                             `NATIVELY_INTERACTIVE_BLOCK_TYPES`). The editor
+ *                             reads it to say "After Adding to Cart" instead of
+ *                             "On Click", to trim the option list, and to stop
+ *                             offering Focus and Pressed root chips on a
+ *                             wrapper that is no longer a control.
+ *
+ * Names rather than a version number, for the reason the state pins are: the
+ * editor must not have to know which release added what. A build that does not
+ * send the list is read as doing none of the above, which is exactly what
+ * every renderer shipped before this one did.
+ *
+ * The editor matches these strings exactly and silently drops a name it does
+ * not know, so a rename here narrows the panel back to the baseline instead of
+ * failing anywhere. Change one only together with `StorefrontActionCapability`
+ * in pz-dynamic-widget.
+ *
+ * Its own module rather than a constant beside the block that implements it:
+ * the placeholder registry announces this, and it must not have to pull a
+ * client component in to say one list of strings.
+ */
+export type ActionCapability = 'add-to-cart-after-add';
+
+export const ACTION_CAPABILITIES: readonly ActionCapability[] = [
+  'add-to-cart-after-add'
+];

package/src/blocks/__tests__/add-to-cart-action.test.tsx

@@ -0,0 +1,377 @@
+import React from 'react';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+
+import AddToCartBlock from '../add-to-cart-block';
+import { WithDesignerFeatures } from '../../components/with-designer-features';
+import { ThemePageContextProvider } from '../../theme-page-context';
+import { ModalHostIdProvider } from '../../overlays/modal-host-context';
+import {
+  __resetOverlayBusForTests,
+  getOpenModalIds,
+  isModalOpen,
+  openModal,
+  registerModalHost,
+  subscribeToModals
+} from '../../overlays/overlay-bus';
+import { applyVisibilityRulesToSections } from '../../utils/visibility-rules';
+import { Block } from '../../theme-block';
+import { Section } from '../../theme-section';
+
+/**
+ * "On Click: Open a modal / Modal: Added to basket" on the PDP add-to-cart.
+ *
+ * The designer means "once the product is in the basket". The wrapper every
+ * block renders inside used to run the action on the same click, before the
+ * add request had returned, so the modal opened on a failed add, the quantity
+ * stepper's +/- opened it too, and Enter on the real button opened it while
+ * the wrapper's keydown cancel swallowed the add itself.
+ *
+ * The block now runs the SAME saved action (no new property) itself, after the
+ * add succeeds — so every composition already published is fixed by the
+ * upgrade alone.
+ *
+ * Rendered the way a storefront renders it: the wrapper from `ThemeBlock`
+ * around the renderer, the product from the PDP's page context, and an add
+ * request the test holds open so "while pending" is a state it can look at.
+ */
+
+const mockAddProduct = jest.fn();
+
+// Every `@akinon/next/data/client/*` subpath maps to the same mock file, so
+// one factory has to serve the product client (the mutation) and the basket
+// client (`basketApi`) alike.
+jest.mock('@akinon/next/data/client/product', () => ({
+  __esModule: true,
+  useAddProductMutation: () => [
+    (payload: unknown) => mockAddProduct(payload),
+    { isLoading: false }
+  ],
+  basketApi: {
+    util: { invalidateTags: () => ({ type: 'basket/invalidateTags' }) }
+  }
+}));
+
+jest.mock('@akinon/next/redux/hooks', () => ({
+  __esModule: true,
+  useAppSelector: () => undefined,
+  useAppDispatch: () => () => undefined
+}));
+
+const MODAL = 'added-to-basket';
+const PAGE = { product: { pk: 101, name: 'Polo', in_stock: true } };
+
+const addToCartBlock = (properties: Record<string, unknown> = {}): Block =>
+  ({
+    id: 'atc-1',
+    type: 'add-to-cart',
+    label: 'Add to Cart',
+    value: '',
+    order: 0,
+    hidden: false,
+    properties: {
+      actionType: 'open-modal',
+      actionTarget: MODAL,
+      actionAudience: 'all',
+      ...properties
+    },
+    styles: {}
+  } as unknown as Block);
+
+const renderAddToCart = (
+  block: Block,
+  { isDesigner = false, hostModalId = '' } = {}
+) => {
+  const tree = (
+    <ThemePageContextProvider value={PAGE}>
+      <WithDesignerFeatures
+        block={block}
+        placeholderId="p"
+        sectionId="s"
+        isDesigner={isDesigner}
+      >
+        <AddToCartBlock
+          block={block}
+          placeholderId="p"
+          sectionId="s"
+          isDesigner={isDesigner}
+        />
+      </WithDesignerFeatures>
+    </ThemePageContextProvider>
+  );
+
+  const view = render(
+    hostModalId ? (
+      <ModalHostIdProvider value={hostModalId}>{tree}</ModalHostIdProvider>
+    ) : (
+      tree
+    )
+  );
+
+  return {
+    ...view,
+    button: view.container.querySelector(
+      '[data-add-to-cart]'
+    ) as HTMLButtonElement,
+    wrapper: view.container.querySelector(
+      '[data-block-id="atc-1"]'
+    ) as HTMLElement
+  };
+};
+
+/** The add request, held open until the test settles it. */
+const pendingAdd = () => {
+  let resolve!: (value: unknown) => void;
+  let reject!: (reason: unknown) => void;
+  const promise = new Promise((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  // The handler awaits it; this only keeps an unawaited rejection quiet.
+  promise.catch(() => undefined);
+
+  mockAddProduct.mockImplementation(() => ({ unwrap: () => promise }));
+
+  return { resolve, reject };
+};
+
+/** Settle the request and let the click handler run to its end. */
+const settle = async (finish: () => void) => {
+  await act(async () => {
+    finish();
+    await new Promise((done) => setTimeout(done, 0));
+  });
+};
+
+beforeEach(() => {
+  __resetOverlayBusForTests();
+  registerModalHost();
+  mockAddProduct.mockReset();
+});
+
+describe('add-to-cart with an "open modal" action', () => {
+  it('opens the modal only once the add has succeeded', async () => {
+    const request = pendingAdd();
+    const { button } = renderAddToCart(addToCartBlock());
+
+    act(() => {
+      fireEvent.click(button);
+    });
+
+    expect(mockAddProduct).toHaveBeenCalledTimes(1);
+    // The request is in flight: nothing is in the basket yet, so nothing may
+    // say it is.
+    expect(isModalOpen(MODAL)).toBe(false);
+
+    await settle(() => request.resolve({}));
+
+    expect(isModalOpen(MODAL)).toBe(true);
+    expect(button).toHaveAttribute('data-add-to-cart-state', 'added');
+  });
+
+  it('never opens it for an add that failed, and shows the error instead', async () => {
+    const request = pendingAdd();
+    const { button } = renderAddToCart(addToCartBlock());
+
+    act(() => {
+      fireEvent.click(button);
+    });
+    await settle(() => request.reject(new Error('out of stock')));
+
+    expect(isModalOpen(MODAL)).toBe(false);
+    expect(getOpenModalIds()).toEqual([]);
+    expect(button).toHaveAttribute('data-add-to-cart-state', 'error');
+  });
+
+  it('treats the quantity stepper as the stepper: no add, no modal', () => {
+    pendingAdd();
+    renderAddToCart(addToCartBlock({ showQuantitySelector: true }));
+
+    act(() => {
+      fireEvent.click(screen.getByLabelText('Increase quantity'));
+    });
+
+    // The click did land — the amount moved — it just is not an add.
+    expect(
+      document.querySelector('[data-part="quantity-input"]')
+    ).toHaveTextContent('2');
+    expect(mockAddProduct).not.toHaveBeenCalled();
+    expect(isModalOpen(MODAL)).toBe(false);
+  });
+
+  it('leaves Enter on the real button to the button', async () => {
+    const request = pendingAdd();
+    const { button } = renderAddToCart(addToCartBlock());
+
+    button.focus();
+    const notPrevented = fireEvent.keyDown(button, { key: 'Enter' });
+
+    // Cancelling this keydown is what used to swallow the add: the browser
+    // turns an uncancelled Enter on a <button> into its click.
+    expect(notPrevented).toBe(true);
+    expect(isModalOpen(MODAL)).toBe(false);
+
+    // jsdom does not synthesise that click, so play the browser's part.
+    act(() => {
+      fireEvent.click(button);
+    });
+    expect(isModalOpen(MODAL)).toBe(false);
+
+    await settle(() => request.resolve({}));
+
+    expect(mockAddProduct).toHaveBeenCalledTimes(1);
+    expect(isModalOpen(MODAL)).toBe(true);
+  });
+
+  it('does not turn the wrapper into a second control around the button', () => {
+    const { wrapper, button } = renderAddToCart(addToCartBlock());
+
+    expect(wrapper).not.toHaveAttribute('role');
+    expect(wrapper).not.toHaveAttribute('tabindex');
+    expect(wrapper).not.toHaveAttribute('aria-haspopup');
+    expect(wrapper).not.toHaveAttribute('aria-expanded');
+    // Nor does the button claim to open a dialog: pressing it adds a product,
+    // and only a successful add opens one.
+    expect(button).not.toHaveAttribute('aria-haspopup');
+    expect(button).not.toHaveAttribute('aria-expanded');
+    expect(screen.getAllByRole('button')).toEqual([button]);
+  });
+
+  it('neither adds nor opens in the designer, where a click selects', () => {
+    pendingAdd();
+    const { button } = renderAddToCart(addToCartBlock(), { isDesigner: true });
+
+    act(() => {
+      fireEvent.click(button);
+    });
+
+    expect(mockAddProduct).not.toHaveBeenCalled();
+    expect(isModalOpen(MODAL)).toBe(false);
+  });
+});
+
+describe('who the action runs for', () => {
+  const shopperContext = (authState: 'authenticated' | 'guest') => ({
+    authState,
+    breakpoint: 'desktop',
+    locale: 'tr',
+    currency: 'TRY',
+    pathname: '/product/101/',
+    searchParams: null
+  });
+
+  /** The block as the placeholder hands it to the renderer for this shopper. */
+  const resolvedFor = (block: Block, authState: 'authenticated' | 'guest') =>
+    applyVisibilityRulesToSections(
+      [
+        {
+          id: 's',
+          type: 'custom',
+          label: 'PDP',
+          order: 0,
+          hidden: false,
+          properties: {},
+          styles: {},
+          blocks: [block]
+        } as unknown as Section
+      ],
+      shopperContext(authState)
+    )[0].blocks[0];
+
+  const membersOnly = addToCartBlock({ actionAudience: 'authenticated' });
+
+  it('adds for a guest outside the audience, without opening the modal', async () => {
+    const request = pendingAdd();
+    const { button } = renderAddToCart(resolvedFor(membersOnly, 'guest'));
+
+    act(() => {
+      fireEvent.click(button);
+    });
+    await settle(() => request.resolve({}));
+
+    expect(mockAddProduct).toHaveBeenCalledTimes(1);
+    expect(button).toHaveAttribute('data-add-to-cart-state', 'added');
+    expect(isModalOpen(MODAL)).toBe(false);
+  });
+
+  it('opens it for a member, who is the audience', async () => {
+    const request = pendingAdd();
+    const { button } = renderAddToCart(
+      resolvedFor(membersOnly, 'authenticated')
+    );
+
+    act(() => {
+      fireEvent.click(button);
+    });
+    await settle(() => request.resolve({}));
+
+    expect(isModalOpen(MODAL)).toBe(true);
+  });
+});
+
+describe('an add-to-cart inside a quick-view modal', () => {
+  it('closes the quick view first, then opens the confirmation', async () => {
+    const request = pendingAdd();
+    const { button } = renderAddToCart(
+      addToCartBlock({ closeHostModalOnSuccess: true }),
+      { hostModalId: 'quick-view' }
+    );
+
+    act(() => {
+      openModal('quick-view');
+    });
+
+    const seen: string[][] = [];
+    subscribeToModals(() => seen.push([...getOpenModalIds()]));
+
+    act(() => {
+      fireEvent.click(button);
+    });
+    expect(isModalOpen('quick-view')).toBe(true);
+
+    await settle(() => request.resolve({}));
+
+    // One modal handing over to the next, never both at once.
+    expect(seen).toEqual([[], [MODAL]]);
+  });
+});
+
+describe('an add-to-cart inside a product card that is one big link', () => {
+  it.each([
+    ['with an action', addToCartBlock()],
+    ['without one', addToCartBlock({ actionType: 'none' })]
+  ])('keeps the shopper on the page while the add runs, %s', (_name, block) => {
+    pendingAdd();
+    const { container } = render(
+      <ThemePageContextProvider value={PAGE}>
+        <a href="/product/101/">
+          <WithDesignerFeatures
+            block={block}
+            placeholderId="p"
+            sectionId="s"
+            isDesigner={false}
+          >
+            <AddToCartBlock
+              block={block}
+              placeholderId="p"
+              sectionId="s"
+              isDesigner={false}
+            />
+          </WithDesignerFeatures>
+        </a>
+      </ThemePageContextProvider>
+    );
+    const button = container.querySelector(
+      '[data-add-to-cart]'
+    ) as HTMLButtonElement;
+
+    let notPrevented = true;
+    act(() => {
+      notPrevented = fireEvent.click(button);
+    });
+
+    // A cancelled click is what stops both a plain <a> and NextLink, which
+    // checks `defaultPrevented` before routing.
+    expect(notPrevented).toBe(false);
+    expect(mockAddProduct).toHaveBeenCalledTimes(1);
+  });
+});

package/src/blocks/add-to-cart-block.tsx

@@ -11,6 +11,7 @@ import {
   readItemsCurrency
 } from '../utils/analytics';
 import { useHostModalCloser } from '../overlays/modal-host-context';
+import { useBlockAction } from '../hooks/use-block-action';
 import { BlockRendererProps } from './block-renderer-registry';
 import {
   DesignerPlaceholder,
@@ -85,6 +86,10 @@ const readAvailableStock = (product: ThemeProduct | null): number | null => {
  * added, the optional icon, the width and — through named parts — the styling
  * of the button in every state.
  *
+ * The shared action (`actionType` / `actionTarget`, e.g. "open the Added to
+ * basket modal") runs after a SUCCESSFUL add rather than on the click: a
+ * failed add, the quantity stepper and the designer canvas never run it.
+ *
  * Parts: button, label, icon, row, quantity, quantity-button, quantity-input.
  * Properties: label, addingLabel, addedLabel, errorLabel, outOfStockLabel,
  * fullWidth, quantity, showIcon, icon, iconSize, iconGap, iconPosition,
@@ -131,6 +136,14 @@ const AddToCartBlock = ({
   );
   const closeHostModal = useHostModalCloser(closeHostModalOnSuccess);
 
+  /**
+   * The authored action ("open the Added to basket modal"), which this block
+   * runs itself once the add succeeds — see `NATIVELY_INTERACTIVE_BLOCK_TYPES`.
+   * Only `run` is used: nothing is spread onto the button, because pressing it
+   * does not open a dialog; a successful add does. Called above the early
+   * returns below, as every hook here must be.
+   */
+  const action = useBlockAction(block, { currentBreakpoint, isDesigner });
 
   const label = prop('label', 'Add to Cart');
   const addingLabel = prop('addingLabel', 'Adding…');
@@ -285,10 +298,18 @@ const AddToCartBlock = ({
     );
   };
 
-  const handleClick = async () => {
+  const handleClick = async (event: React.MouseEvent<HTMLButtonElement>) => {
+    // A product card is often one big link with this button inside it. The
+    // button has no default of its own (`type="button"`), so cancelling the
+    // click only stops the card from navigating away while the add is in
+    // flight — the wrapper used to do this by accident when it ran the action.
+    event.preventDefault();
+
     // A click inside the designer must never touch the shopper's real basket.
     if (isDesigner || disabled) return;
 
+    let added = false;
+
     try {
       await addProduct({
         product: productPk,
@@ -305,11 +326,18 @@ const AddToCartBlock = ({
         currency: readItemsCurrency(product),
         items: [buildCommerceItem(product, { quantity })]
       });
+      added = true;
     } catch {
       setFeedback('error');
     }
 
     scheduleReset();
+
+    // The authored action confirms the add, so a failed add never runs it. It
+    // runs after the host modal has closed, so a quick view can hand over to
+    // the "Added to basket" modal, and outside the try so an action that
+    // throws cannot relabel a product that IS in the basket as an error.
+    if (added) action.run();
   };
 
   const iconNode = showIcon ? (

package/src/components/__tests__/with-designer-features-keydown.test.tsx

@@ -0,0 +1,176 @@
+import React from 'react';
+import { act, fireEvent, render } from '@testing-library/react';
+
+import { WithDesignerFeatures } from '../with-designer-features';
+import {
+  __resetOverlayBusForTests,
+  isModalOpen,
+  registerModalHost
+} from '../../overlays/overlay-bus';
+
+/**
+ * The keyboard half of "an authored action makes any block a trigger".
+ *
+ * The wrapper claims `role="button"`, so Enter and Space on it must act — and
+ * it cancels them, or Space would scroll the page under the modal it opened.
+ * But keydown BUBBLES: a key pressed on a control inside the block reached the
+ * same handler and was cancelled too. Enter on a real button then opened the
+ * wrapper's modal instead of pressing the button, and a space could not be
+ * typed into a field. A key pressed on a native control inside the block is
+ * that control's; its own click still reaches the wrapper, exactly as a mouse
+ * click on it does.
+ */
+
+const MODAL = 'campaign';
+
+const blockOf = (type: string) => ({
+  id: 'blk-1',
+  type,
+  label: type,
+  properties: { actionType: 'open-modal', actionTarget: MODAL },
+  styles: {},
+  order: 0,
+  hidden: false
+});
+
+const renderBlock = (type: string, children: React.ReactNode) => {
+  const view = render(
+    <WithDesignerFeatures
+      block={blockOf(type)}
+      placeholderId="p"
+      sectionId="s"
+      isDesigner={false}
+    >
+      {children}
+    </WithDesignerFeatures>
+  );
+
+  return {
+    ...view,
+    wrapper: view.container.querySelector(
+      '[data-block-id="blk-1"]'
+    ) as HTMLElement
+  };
+};
+
+beforeEach(() => {
+  __resetOverlayBusForTests();
+  registerModalHost();
+});
+
+describe('a key pressed on the wrapper itself', () => {
+  it.each(['Enter', ' '])(
+    'runs the action on %p and cancels the key',
+    (key) => {
+      const { wrapper } = renderBlock(
+        'image',
+        // eslint-disable-next-line @next/next/no-img-element
+        <img src="/banner.jpg" alt="Sale" />
+      );
+
+      expect(wrapper).toHaveAttribute('role', 'button');
+      expect(wrapper).toHaveAttribute('tabindex', '0');
+
+      wrapper.focus();
+      let notPrevented = true;
+      act(() => {
+        notPrevented = fireEvent.keyDown(wrapper, { key });
+      });
+
+      expect(notPrevented).toBe(false);
+      expect(isModalOpen(MODAL)).toBe(true);
+    }
+  );
+
+  it('ignores every other key', () => {
+    const { wrapper } = renderBlock('text', <p>Free shipping</p>);
+
+    wrapper.focus();
+    const notPrevented = fireEvent.keyDown(wrapper, { key: 'Tab' });
+
+    expect(notPrevented).toBe(true);
+    expect(isModalOpen(MODAL)).toBe(false);
+  });
+});
+
+describe('a key pressed on a control inside the block', () => {
+  const card = (
+    <div>
+      <span>Summer sale</span>
+      <a href="#details">Details</a>
+      <button type="button">Notify me</button>
+      <input aria-label="E-mail" />
+    </div>
+  );
+
+  it.each([
+    ['link', 'a'],
+    ['button', 'button']
+  ])('leaves Enter on a nested %s to that control', (_name, selector) => {
+    const { container } = renderBlock('group', card);
+    const control = container.querySelector(selector) as HTMLElement;
+
+    control.focus();
+    const notPrevented = fireEvent.keyDown(control, { key: 'Enter' });
+
+    // Uncancelled, the browser turns it into the control's own click, which
+    // then bubbles to the wrapper like a mouse click on the control would.
+    // The keydown alone runs nothing.
+    expect(notPrevented).toBe(true);
+    expect(isModalOpen(MODAL)).toBe(false);
+  });
+
+  it('lets a space be typed into a nested field', () => {
+    const { container } = renderBlock('group', card);
+    const field = container.querySelector('input') as HTMLInputElement;
+
+    field.focus();
+    const notPrevented = fireEvent.keyDown(field, { key: ' ' });
+
+    expect(notPrevented).toBe(true);
+    expect(isModalOpen(MODAL)).toBe(false);
+  });
+
+  it('still answers a mouse click on the content, as it always has', () => {
+    const { getByText } = renderBlock('group', card);
+
+    act(() => {
+      fireEvent.click(getByText('Summer sale'));
+    });
+
+    expect(isModalOpen(MODAL)).toBe(true);
+  });
+});
+
+describe('a trigger inside a trigger', () => {
+  it('answers Enter on the inner one the way it answers a click: both run', () => {
+    const inner = {
+      ...blockOf('image'),
+      id: 'blk-inner',
+      properties: { actionType: 'open-modal', actionTarget: 'size-guide' }
+    };
+    const { container } = renderBlock(
+      'group',
+      <WithDesignerFeatures
+        block={inner}
+        placeholderId="p"
+        sectionId="s"
+        isDesigner={false}
+      >
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img src="/chart.jpg" alt="Size chart" />
+      </WithDesignerFeatures>
+    );
+    const innerWrapper = container.querySelector(
+      '[data-block-id="blk-inner"]'
+    ) as HTMLElement;
+
+    innerWrapper.focus();
+    act(() => {
+      fireEvent.keyDown(innerWrapper, { key: 'Enter' });
+    });
+
+    expect(isModalOpen('size-guide')).toBe(true);
+    expect(isModalOpen(MODAL)).toBe(true);
+  });
+});

package/src/components/with-designer-features.tsx

@@ -15,6 +15,11 @@ import {
   HOVER_SCOPE_ATTRIBUTE,
   REVEAL_ON_HOVER_ATTRIBUTE
 } from '../utils/property-switches';
+
+/** Elements that already act on Enter/Space themselves. */
+const NATIVE_KEYBOARD_CONTROLS =
+  'a[href], button, input, select, textarea, summary, [contenteditable]:not([contenteditable="false"])';
+
 interface WithDesignerFeaturesProps {
   block: any;
   placeholderId: string;
@@ -94,9 +99,11 @@ export function WithDesignerFeatures({
    * only element in the chain that already exists, so a block that becomes
    * clickable gains no extra box and its layout does not move.
    *
-   * `button` and `link` are excluded: they render a real `<button>`/`<a>` and
-   * wire the action onto it themselves. Handling it here too would nest a
-   * control inside a control, which is both invalid and double-fires.
+   * The `NATIVELY_INTERACTIVE_BLOCK_TYPES` are excluded because they run the
+   * action themselves: `button` and `link` wire it onto their real
+   * `<button>`/`<a>` (handling it here too would nest a control inside a
+   * control, which is both invalid and double-fires), and `add-to-cart` runs
+   * it once the add succeeds, which a click on this wrapper cannot know.
    */
   const action = useBlockAction(block, { currentBreakpoint, isDesigner });
   const ownsAction =
@@ -115,6 +122,21 @@ export function WithDesignerFeatures({
    */
   const handleRootKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
     if (!ownsAction) return;
+    // A key pressed on a native control inside the block — a real button,
+    // link or field — bubbles here too but belongs to that control: cancelling
+    // it swallowed the control's own activation (Enter on add-to-cart opened
+    // the modal and added nothing) and made a space impossible to type into a
+    // field. Left alone, the control's own click still bubbles up to
+    // `handleRootClick`, so the keyboard now does what the mouse does. A nested
+    // trigger wrapper is not a native control, so a key on it still reaches
+    // this one as well — again, as a click would.
+    if (
+      event.target !== event.currentTarget &&
+      event.target instanceof Element &&
+      event.target.matches(NATIVE_KEYBOARD_CONTROLS)
+    ) {
+      return;
+    }
     if (event.key !== 'Enter' && event.key !== ' ') return;
     // Space would scroll the page underneath the modal it just opened.
     event.preventDefault();

package/src/hooks/__tests__/use-block-action.test.tsx

@@ -0,0 +1,199 @@
+import React from 'react';
+import {
+  act,
+  fireEvent,
+  render,
+  renderHook,
+  screen
+} from '@testing-library/react';
+
+import {
+  __resetOverlayBusForTests,
+  getOpenModalIds,
+  isModalOpen,
+  openModal,
+  registerModalHost
+} from '../../overlays/overlay-bus';
+import {
+  BlockActionType,
+  NATIVELY_INTERACTIVE_BLOCK_TYPES,
+  useBlockAction
+} from '../use-block-action';
+
+/**
+ * `run()`: the action without the click.
+ *
+ * The add-to-cart block's action confirms an add, so it runs when the request
+ * succeeds — long after the click event is gone. `run` is that path, and it
+ * must be exactly as inert as `onClick` where `onClick` is inert: in the
+ * designer, and on a block with no action (which is also what an audience the
+ * shopper is outside of turns an action into).
+ */
+
+const mkBlock = (properties: Record<string, unknown>) => ({ properties });
+
+const openAction = {
+  actionType: 'open-modal',
+  actionTarget: 'added-to-basket'
+};
+
+beforeEach(() => {
+  __resetOverlayBusForTests();
+  registerModalHost();
+});
+
+describe('run()', () => {
+  it('performs the action with no event', () => {
+    const { result } = renderHook(() => useBlockAction(mkBlock(openAction)));
+
+    act(() => {
+      result.current.run();
+    });
+
+    expect(isModalOpen('added-to-basket')).toBe(true);
+  });
+
+  it('performs the targetless ones too', () => {
+    openModal('a');
+    openModal('b');
+
+    const { result } = renderHook(() =>
+      useBlockAction(mkBlock({ actionType: 'close-top-modal' }))
+    );
+
+    act(() => {
+      result.current.run();
+    });
+
+    expect(getOpenModalIds()).toEqual(['a']);
+  });
+
+  it('does nothing in the designer', () => {
+    const { result } = renderHook(() =>
+      useBlockAction(mkBlock(openAction), { isDesigner: true })
+    );
+
+    act(() => {
+      result.current.run();
+    });
+
+    expect(isModalOpen('added-to-basket')).toBe(false);
+  });
+
+  it('is present and does nothing when there is no action', () => {
+    const cases = [
+      {},
+      { actionType: 'none', actionTarget: 'added-to-basket' },
+      // An action with nowhere to go is no action.
+      { actionType: 'open-modal' },
+      { actionType: 'link', actionTarget: '/cart' }
+    ];
+
+    cases.forEach((properties) => {
+      const { result } = renderHook(() => useBlockAction(mkBlock(properties)));
+
+      expect(result.current.isActive).toBe(false);
+      expect(typeof result.current.run).toBe('function');
+
+      act(() => {
+        result.current.run();
+      });
+    });
+
+    expect(getOpenModalIds()).toEqual([]);
+  });
+
+  it('keeps its identity across renders, so it can sit in a dependency list', () => {
+    const block = mkBlock(openAction);
+    const { result, rerender } = renderHook(() => useBlockAction(block));
+    const first = result.current.run;
+
+    rerender();
+
+    expect(result.current.run).toBe(first);
+  });
+});
+
+describe('onClick, now that it shares the performer', () => {
+  const Trigger = ({
+    properties,
+    isDesigner = false
+  }: {
+    properties: Record<string, unknown>;
+    isDesigner?: boolean;
+  }) => {
+    const action = useBlockAction(mkBlock(properties), { isDesigner });
+
+    return (
+      <a href="#elsewhere" onClick={action.onClick}>
+        trigger
+      </a>
+    );
+  };
+
+  /** false when the click's default (the navigation) was cancelled. */
+  const clickIsLetThrough = () => fireEvent.click(screen.getByText('trigger'));
+
+  const interactive: Array<[BlockActionType, string]> = [
+    ['open-modal', 'm'],
+    ['close-modal', 'm'],
+    ['toggle-modal', 'm'],
+    ['close-top-modal', ''],
+    ['scroll-to', 'reviews'],
+    ['auth-step', 'login'],
+    ['auth-back', ''],
+    ['otp-resend', ''],
+    ['otp-change-number', '']
+  ];
+
+  it.each(interactive)(
+    'cancels the default for %s, as before',
+    (actionType, actionTarget) => {
+      render(<Trigger properties={{ actionType, actionTarget }} />);
+
+      // A trigger that also navigated would race what it just started.
+      expect(clickIsLetThrough()).toBe(false);
+    }
+  );
+
+  it.each([
+    ['none', ''],
+    ['link', '/elsewhere']
+  ])('lets the navigation through for %s', (actionType, actionTarget) => {
+    render(<Trigger properties={{ actionType, actionTarget }} />);
+
+    expect(clickIsLetThrough()).toBe(true);
+  });
+
+  it('cancels nothing in the designer, where the wrapper owns the click', () => {
+    render(
+      <Trigger
+        properties={{ actionType: 'open-modal', actionTarget: 'm' }}
+        isDesigner
+      />
+    );
+
+    expect(clickIsLetThrough()).toBe(true);
+    expect(isModalOpen('m')).toBe(false);
+  });
+
+  it('still performs the action it cancelled the default for', () => {
+    render(
+      <Trigger properties={{ actionType: 'open-modal', actionTarget: 'm' }} />
+    );
+
+    clickIsLetThrough();
+
+    expect(isModalOpen('m')).toBe(true);
+  });
+});
+
+describe('NATIVELY_INTERACTIVE_BLOCK_TYPES', () => {
+  it('holds the blocks that run their own action, add-to-cart included', () => {
+    expect(Array.from(NATIVELY_INTERACTIVE_BLOCK_TYPES).sort()).toEqual([
+      'add-to-cart',
+      'button',
+      'link'
+    ]);
+  });
+});

package/src/hooks/use-block-action.ts

@@ -17,7 +17,7 @@ import {
   resolveAuthStepTarget,
   setAuthStep
 } from '../auth/auth-flow-bus';
-import { useOtpForm } from '../auth/otp-form-context';
+import { OtpFormApi, useOtpForm } from '../auth/otp-form-context';
 
 /**
  * What a block does when it is clicked.
@@ -67,17 +67,23 @@ const MODAL_ACTIONS: BlockActionType[] = [
 ];
 
 /**
- * Blocks that render a real `<button>` or `<a>` and therefore wire the action
- * onto that element themselves.
+ * Blocks that run their authored action themselves, so the generic path in
+ * `WithDesignerFeatures` must leave it alone. Two reasons put a block here:
  *
- * The generic path in `WithDesignerFeatures` must skip them: a wrapper
- * claiming `role="button"` around a real button nests one control inside
- * another, which is invalid markup, announces twice, and fires the action
- * twice on one click.
+ *  - It renders a real `<button>` or `<a>` and wires the action onto that
+ *    element (`button`, `link`). A wrapper claiming `role="button"` around a
+ *    real button nests one control inside another, which is invalid markup,
+ *    announces twice, and fires the action twice on one click.
+ *  - Its action is the CONFIRMATION of something asynchronous it does itself
+ *    (`add-to-cart`). "Open the Added to basket modal" means "once the product
+ *    is in the basket", so it runs when the add succeeds, not on the click. Run
+ *    by the wrapper it fired before the request returned — the modal opened on
+ *    a failed add, and on the quantity stepper's own +/- buttons too.
  */
 export const NATIVELY_INTERACTIVE_BLOCK_TYPES: ReadonlySet<string> = new Set([
   'button',
-  'link'
+  'link',
+  'add-to-cart'
 ]);
 
 export interface BlockActionSource {
@@ -119,6 +125,14 @@ export interface UseBlockActionResult {
   isActive: boolean;
   /** Attach to the clickable element. `undefined` when there is no action. */
   onClick?: (event: React.MouseEvent<HTMLElement>) => void;
+  /**
+   * Perform the action with no event in hand, for a block whose action
+   * confirms something it did itself rather than answering a click — the
+   * add-to-cart block runs it once the add has succeeded. Always present and
+   * inert by the same rule as `onClick` (in the designer, or when the block has
+   * no action), so a caller can fire it unconditionally.
+   */
+  run: () => void;
   /**
    * Spread onto the same element. Announces a dialog trigger as one, which is
    * what turns a styled div into something a screen reader user can act on
@@ -143,6 +157,65 @@ const scrollToAnchor = (target: string) => {
   element?.scrollIntoView({ behavior: 'smooth', block: 'start' });
 };
 
+/** What an action reaches that only the rendering tree can supply. */
+export interface BlockActionScope {
+  /** The auth flow a trigger inside an `auth-flow` block belongs to. */
+  contextFlowId?: string;
+  /** The OTP form a trigger stands inside, for resend / change number. */
+  otpForm?: OtpFormApi | null;
+}
+
+/**
+ * Perform an authored action — the part of a click that is not the click.
+ *
+ * Split from the handler because not every action answers a click: the
+ * add-to-cart block's action is the confirmation of an add, so it runs when
+ * the request succeeds, long after the click event is gone. Both paths call
+ * this, so an action behaves the same whichever way it was reached.
+ */
+export const performBlockAction = (
+  { type, target }: BlockAction,
+  { contextFlowId = '', otpForm = null }: BlockActionScope = {}
+): void => {
+  switch (type) {
+    case 'open-modal':
+      openModal(target);
+      break;
+    case 'close-modal':
+      closeModal(target);
+      break;
+    case 'toggle-modal':
+      toggleModal(target);
+      break;
+    case 'close-top-modal':
+      closeTopModal();
+      break;
+    case 'scroll-to':
+      scrollToAnchor(target);
+      break;
+    case 'auth-step': {
+      const resolved = resolveAuthStepTarget(target, contextFlowId);
+      if (resolved) setAuthStep(resolved.flowId, resolved.stepKey);
+      break;
+    }
+    case 'otp-resend':
+      // No-ops while the countdown runs — the form owns that rule, so a
+      // resend placed anywhere obeys the same one.
+      otpForm?.resend();
+      break;
+    case 'otp-change-number':
+      otpForm?.changeNumber();
+      break;
+    case 'auth-back':
+      // The optional target names a flow; without one the nearest (or
+      // default) flow is walked back.
+      goBackAuthStep(target || contextFlowId || DEFAULT_AUTH_FLOW_ID);
+      break;
+    default:
+      break;
+  }
+};
+
 /**
  * Wire a block's authored action to the overlay bus.
  *
@@ -183,54 +256,12 @@ export const useBlockAction = (
     (event: React.MouseEvent<HTMLElement>) => {
       if (isDesigner) return;
 
-      switch (type) {
-        case 'open-modal':
-          // A trigger that also navigates would race its own modal.
-          event.preventDefault();
-          openModal(target);
-          break;
-        case 'close-modal':
-          event.preventDefault();
-          closeModal(target);
-          break;
-        case 'toggle-modal':
-          event.preventDefault();
-          toggleModal(target);
-          break;
-        case 'close-top-modal':
-          event.preventDefault();
-          closeTopModal();
-          break;
-        case 'scroll-to':
-          event.preventDefault();
-          scrollToAnchor(target);
-          break;
-        case 'auth-step': {
-          // A trigger that also navigates would race the step it opens.
-          event.preventDefault();
-          const resolved = resolveAuthStepTarget(target, contextFlowId);
-          if (resolved) setAuthStep(resolved.flowId, resolved.stepKey);
-          break;
-        }
-        case 'otp-resend':
-          event.preventDefault();
-          // No-ops while the countdown runs — the form owns that rule, so a
-          // resend placed anywhere obeys the same one.
-          otpForm?.resend();
-          break;
-        case 'otp-change-number':
-          event.preventDefault();
-          otpForm?.changeNumber();
-          break;
-        case 'auth-back':
-          event.preventDefault();
-          // The optional target names a flow; without one the nearest (or
-          // default) flow is walked back.
-          goBackAuthStep(target || contextFlowId || DEFAULT_AUTH_FLOW_ID);
-          break;
-        default:
-          break;
-      }
+      // Every action this hook performs cancels the element's default, and
+      // `none`/`link` keep it: a trigger that also navigates would race the
+      // modal, step or scroll it just started.
+      if (isInteractiveAction(type)) event.preventDefault();
+
+      performBlockAction({ type, target }, { contextFlowId, otpForm });
     },
     [isDesigner, type, target, contextFlowId, otpForm]
   );
@@ -247,8 +278,17 @@ export const useBlockAction = (
     isInteractiveAction(type) &&
     (TARGETLESS_ACTIONS.includes(type) || Boolean(target));
 
+  // Called before the early return below — a hook cannot sit on a branch — and
+  // guarded by the same two conditions `onClick` is, so the designer canvas and
+  // a block with no action stay inert whichever way the action is reached.
+  const run = useCallback(() => {
+    if (!isActive || isDesigner) return;
+
+    performBlockAction({ type, target }, { contextFlowId, otpForm });
+  }, [isActive, isDesigner, type, target, contextFlowId, otpForm]);
+
   if (!isActive) {
-    return { isActive: false, ariaProps: {} };
+    return { isActive: false, run, ariaProps: {} };
   }
 
   const opensDialog = type === 'open-modal' || type === 'toggle-modal';
@@ -269,6 +309,7 @@ export const useBlockAction = (
     return {
       isActive: true,
       onClick: handleClick,
+      run,
       ariaProps: { 'aria-disabled': true }
     };
   }
@@ -276,6 +317,7 @@ export const useBlockAction = (
   return {
     isActive: true,
     onClick: handleClick,
+    run,
     ariaProps: opensDialog
       ? {
           'aria-haspopup': 'dialog',

package/src/placeholder-registry.ts

@@ -1,5 +1,9 @@
 import { getCatalogVendor, getCustomCatalog } from './custom/catalog';
 import { getCustomSectionCatalog } from './custom/section-catalog';
+import {
+  ACTION_CAPABILITIES,
+  type ActionCapability
+} from './action-capabilities';
 import {
   STATE_PIN_CAPABILITIES,
   type StatePinCapability
@@ -72,6 +76,22 @@ interface PlaceholdersAvailablePayload {
    * listing it would make an old storefront look LESS capable than it is.
    */
   statePins?: readonly StatePinCapability[];
+
+  /**
+   * What THIS build's block renderer does with an authored action beyond
+   * running it on the click, so the editor can word the action panel after
+   * the storefront in front of it (see `action-capabilities.ts`).
+   *
+   * Additive and by name, on the same terms as `statePins`, and read the same
+   * way: a build that does not send it is taken to do none of it, which is the
+   * truth for every renderer shipped before the field existed.
+   *
+   * Unlike `statePins` it rides EVERY frame. The editor replaces what it holds
+   * with each frame, so a frame without it would put the panel back to "On
+   * Click" — and the only frame some documents ever send is the one that went
+   * out before the designer flag arrived (see `handleEditorMessage`).
+   */
+  actionCapabilities?: readonly ActionCapability[];
 }
 
 const isFramed = (): boolean =>
@@ -105,7 +125,14 @@ const flush = () => {
   if (!isFramed()) return;
 
   const data: PlaceholdersAvailablePayload = {
-    placeholders: Array.from(placeholderRegistry)
+    placeholders: Array.from(placeholderRegistry),
+    // Outside the designer gate below, on purpose. It says what this theme
+    // version does, not what this brand built — nothing a framing payment
+    // provider could not read off the bundle — so there is nothing to
+    // withhold. Gated, it would be lost for the life of the document on a slow
+    // handshake: the designer re-announce only fires for a build that
+    // registers a custom catalog, and most brands register none.
+    actionCapabilities: ACTION_CAPABILITIES
   };
 
   // Being framed is NOT enough to hand the catalog over. A storefront is