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

package/src/blocks/__tests__/checkout-outlet-blocks.test.tsx

@@ -0,0 +1,623 @@
+import React, { useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { act, fireEvent, render, screen } from '@testing-library/react';
+import CheckoutFlowOutletBlock from '../checkout-flow-outlet-block';
+import CheckoutStepsOutletBlock from '../checkout-steps-outlet-block';
+import CheckoutSummaryOutletBlock from '../checkout-summary-outlet-block';
+import {
+  getCheckoutFlowVariantOverride,
+  getCheckoutOutletClaim,
+  registerCheckoutOutlet,
+  resetCheckoutPiecesForTests,
+  updateCheckoutOutletFlowVariant
+} from '../../chrome/checkout-pieces';
+import { postToEditor } from '../../editor-bridge';
+
+jest.mock('../../editor-bridge', () => ({
+  postToEditor: jest.fn()
+}));
+
+const postToEditorMock = postToEditor as jest.Mock;
+
+/**
+ * The outlet blocks are positioning targets for the checkout pieces bridge.
+ * These tests lock the three properties the feature stands on:
+ *
+ * - SEALED (I1): an outlet never emits anything interactive — no inputs, no
+ *   buttons, no forms, no iframes. It cannot render payment surfaces and it
+ *   cannot synthesize a place-order trigger.
+ * - STABLE TARGET: the portal target div exists unconditionally and its DOM
+ *   identity never changes across re-renders, so iframes portaled into it by
+ *   the flow piece are never remounted mid-payment.
+ * - ZONE GATE: an outlet only registers inside the `checkout-page-body`
+ *   placeholder. Anywhere else (trailing checkout zones, other pages) it is
+ *   inert on live AND on the canvas, and its designer band says so — the
+ *   canvas must never teleport into a spot the storefront would ignore.
+ */
+
+const props = (over: Record<string, unknown> = {}) =>
+  ({
+    block: {
+      id: 'outlet-1',
+      type: 'checkout-flow-outlet',
+      label: 'Checkout Flow Outlet',
+      value: '',
+      properties: {},
+      styles: {},
+      order: 0,
+      hidden: false
+    },
+    placeholderId: 'checkout-page-body',
+    sectionId: 's',
+    isDesigner: false,
+    ...over
+  }) as any;
+
+const flowProps = (
+  properties: Record<string, unknown>,
+  over: Record<string, unknown> = {}
+) => props({ block: { ...props().block, properties }, ...over });
+
+const detachedNodes: HTMLElement[] = [];
+
+const createDetachedOutletNode = () => {
+  const node = document.createElement('div');
+  document.body.appendChild(node);
+  detachedNodes.push(node);
+
+  return node;
+};
+
+beforeEach(() => {
+  resetCheckoutPiecesForTests();
+  postToEditorMock.mockClear();
+});
+
+afterEach(() => {
+  detachedNodes.forEach((node) => node.remove());
+  detachedNodes.length = 0;
+});
+
+describe('checkout outlet blocks — sealed live output (I1)', () => {
+  it('renders exactly one empty target div on live, nothing else', () => {
+    const { container } = render(<CheckoutFlowOutletBlock {...props()} />);
+
+    expect(container.innerHTML).toBe('<div data-checkout-outlet="flow"></div>');
+  });
+
+  it('never emits interactive elements, for any of the three outlets', () => {
+    const { container } = render(
+      <>
+        <CheckoutFlowOutletBlock {...props()} />
+        <CheckoutStepsOutletBlock {...props()} />
+        <CheckoutSummaryOutletBlock {...props()} />
+      </>
+    );
+
+    expect(
+      container.querySelector(
+        'input, button, form, iframe, select, textarea, [role="button"]'
+      )
+    ).toBeNull();
+    expect(container.querySelectorAll('[data-checkout-outlet]')).toHaveLength(
+      3
+    );
+  });
+});
+
+describe('checkout outlet blocks — registration lifecycle', () => {
+  it('registers its target on mount and unregisters on unmount', () => {
+    const { container, unmount } = render(
+      <CheckoutSummaryOutletBlock {...props()} />
+    );
+
+    const claim = getCheckoutOutletClaim('summary');
+    expect(claim).not.toBeNull();
+    expect(claim!.node).toBe(
+      container.querySelector('[data-checkout-outlet="summary"]')
+    );
+
+    unmount();
+
+    expect(getCheckoutOutletClaim('summary')).toBeNull();
+  });
+
+  it('keeps the target node identity stable across re-renders', () => {
+    const { rerender } = render(
+      <CheckoutStepsOutletBlock {...props({ isSelected: false })} />
+    );
+
+    const before = getCheckoutOutletClaim('steps');
+    expect(before).not.toBeNull();
+
+    rerender(<CheckoutStepsOutletBlock {...props({ isSelected: true })} />);
+
+    const after = getCheckoutOutletClaim('steps');
+    expect(after).not.toBeNull();
+    expect(after!.node).toBe(before!.node);
+    expect(after!.id).toBe(before!.id);
+  });
+});
+
+describe('checkout outlet blocks — designer bands', () => {
+  it('shows the "renders here" band in the designer while the piece is absent', () => {
+    render(<CheckoutFlowOutletBlock {...props({ isDesigner: true })} />);
+
+    expect(
+      screen.getByText('Checkout flow renders here on the storefront')
+    ).toBeInTheDocument();
+  });
+
+  it('shows no band on live', () => {
+    const { container } = render(<CheckoutFlowOutletBlock {...props()} />);
+
+    expect(
+      container.querySelector('[data-theme-block-placeholder]')
+    ).toBeNull();
+  });
+
+  it('marks the second outlet for the same piece as a duplicate (first-wins)', () => {
+    render(
+      <>
+        <CheckoutFlowOutletBlock {...props({ isDesigner: true })} />
+        <CheckoutFlowOutletBlock {...props({ isDesigner: true })} />
+      </>
+    );
+
+    expect(
+      screen.getAllByText(
+        'Checkout flow — already placed in another outlet on this page'
+      )
+    ).toHaveLength(1);
+    expect(
+      screen.getAllByText('Checkout flow renders here on the storefront')
+    ).toHaveLength(1);
+  });
+});
+
+describe('checkout outlet blocks — zone gate', () => {
+  // The flow latches one-shot at page mount and only the body slot hydrates
+  // before that latch; a trailing-zone outlet would register too late and be
+  // silently dead on live while the canvas teleported into it. The gate makes
+  // canvas and storefront agree: outside checkout-page-body an outlet never
+  // registers, anywhere.
+  it.each([
+    ['checkout-bottom-body'],
+    ['checkout-top-body'],
+    ['theme-homepage-body']
+  ])('never registers from the %s placeholder', (placeholderId) => {
+    const { container } = render(
+      <CheckoutFlowOutletBlock {...props({ placeholderId })} />
+    );
+
+    expect(getCheckoutOutletClaim('flow')).toBeNull();
+    // Live output stays the sealed empty div, nothing else.
+    expect(container.innerHTML).toBe('<div data-checkout-outlet="flow"></div>');
+  });
+
+  it('applies the gate to all three outlets', () => {
+    render(
+      <>
+        <CheckoutFlowOutletBlock
+          {...props({ placeholderId: 'checkout-bottom-body' })}
+        />
+        <CheckoutStepsOutletBlock
+          {...props({ placeholderId: 'checkout-bottom-body' })}
+        />
+        <CheckoutSummaryOutletBlock
+          {...props({ placeholderId: 'checkout-bottom-body' })}
+        />
+      </>
+    );
+
+    expect(getCheckoutOutletClaim('flow')).toBeNull();
+    expect(getCheckoutOutletClaim('steps')).toBeNull();
+    expect(getCheckoutOutletClaim('summary')).toBeNull();
+  });
+
+  it('explains itself in the designer instead of promising a render', () => {
+    render(
+      <CheckoutFlowOutletBlock
+        {...props({ placeholderId: 'checkout-bottom-body', isDesigner: true })}
+      />
+    );
+
+    expect(
+      screen.getByText(
+        'Checkout flow outlet only works inside the Checkout Body zone — the storefront ignores it here'
+      )
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText('Checkout flow renders here on the storefront')
+    ).toBeNull();
+    expect(
+      screen.queryByText(
+        'Checkout flow — already placed in another outlet on this page'
+      )
+    ).toBeNull();
+  });
+});
+
+describe('checkout flow outlet — composed variant channel', () => {
+  it('registers a valid flowVariant with its claim', () => {
+    render(
+      <CheckoutFlowOutletBlock {...flowProps({ flowVariant: 'one-page' })} />
+    );
+
+    expect(getCheckoutOutletClaim('flow')?.flowVariant).toBe('one-page');
+    expect(getCheckoutFlowVariantOverride()).toBe('one-page');
+  });
+
+  it('is breakpoint-invariant: the desktop value is authoritative', () => {
+    render(
+      <CheckoutFlowOutletBlock
+        {...flowProps({
+          flowVariant: { desktop: 'step-by-step', mobile: 'one-page' }
+        })}
+      />
+    );
+
+    expect(getCheckoutFlowVariantOverride()).toBe('step-by-step');
+  });
+
+  it.each([
+    ['inherit'],
+    ['accordion'],
+    ['basket-and-checkout'],
+    [42],
+    [null],
+    [{ desktop: 'accordion' }],
+    [undefined]
+  ])('treats %p as inherit and registers no preference', (value) => {
+    render(<CheckoutFlowOutletBlock {...flowProps({ flowVariant: value })} />);
+
+    expect(getCheckoutOutletClaim('flow')).not.toBeNull();
+    expect(getCheckoutOutletClaim('flow')?.flowVariant).toBeUndefined();
+    expect(getCheckoutFlowVariantOverride()).toBeNull();
+  });
+
+  it('applies a designer property edit in place, never re-registering', () => {
+    const { rerender } = render(
+      <CheckoutFlowOutletBlock {...flowProps({ flowVariant: 'one-page' })} />
+    );
+
+    const before = getCheckoutOutletClaim('flow');
+    expect(before?.flowVariant).toBe('one-page');
+
+    rerender(
+      <CheckoutFlowOutletBlock
+        {...flowProps({ flowVariant: 'step-by-step' })}
+      />
+    );
+
+    const after = getCheckoutOutletClaim('flow');
+    // Same registration — same queue slot, same target node identity.
+    expect(after?.id).toBe(before?.id);
+    expect(after?.node).toBe(before?.node);
+    expect(after?.flowVariant).toBe('step-by-step');
+  });
+});
+
+describe('checkout outlets — designer canvas click capture', () => {
+  const renderFlowInWrapper = (over: Record<string, unknown> = {}) => {
+    const rendered = render(
+      <div data-block-id="outlet-1">
+        <CheckoutFlowOutletBlock {...props(over)} />
+      </div>
+    );
+    const target = rendered.container.querySelector<HTMLElement>(
+      '[data-checkout-outlet="flow"]'
+    )!;
+
+    return { ...rendered, target };
+  };
+
+  // The teleported markup is code-owned and full of live handlers; the tests
+  // simulate it by appending plain DOM under the portal target.
+  const appendPartButton = (target: HTMLElement, part: string) => {
+    const button = document.createElement('button');
+    button.setAttribute('data-part', part);
+    const liveHandler = jest.fn();
+    button.addEventListener('click', liveHandler);
+    target.appendChild(button);
+
+    return { button, liveHandler };
+  };
+
+  it('selects the clicked part and never lets the live handler fire (designer)', () => {
+    const { target } = renderFlowInWrapper({ isDesigner: true });
+    const { button, liveHandler } = appendPartButton(target, 'payment-option');
+
+    const notPrevented = fireEvent.click(button);
+
+    expect(liveHandler).not.toHaveBeenCalled();
+    expect(notPrevented).toBe(false);
+    expect(postToEditorMock).toHaveBeenCalledTimes(1);
+    expect(postToEditorMock).toHaveBeenCalledWith({
+      type: 'SELECT_BLOCK',
+      data: {
+        placeholderId: 'checkout-page-body',
+        sectionId: 's',
+        blockId: 'outlet-1',
+        blockType: 'checkout-flow-outlet',
+        blockLabel: 'Checkout Flow Outlet',
+        partName: 'payment-option'
+      }
+    });
+  });
+
+  it('does not claim a part owned by a nested block', () => {
+    const { target } = renderFlowInWrapper({ isDesigner: true });
+    const nested = document.createElement('div');
+    nested.setAttribute('data-block-id', 'nested-block');
+    target.appendChild(nested);
+    const { button, liveHandler } = appendPartButton(nested, 'header');
+
+    fireEvent.click(button);
+
+    // Still neutralized (the click is inside checkout markup on the canvas),
+    // but the part belongs to the nested block — only the outlet is selected.
+    expect(liveHandler).not.toHaveBeenCalled();
+    expect(postToEditorMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'SELECT_BLOCK',
+        data: expect.objectContaining({
+          blockId: 'outlet-1',
+          partName: undefined
+        })
+      })
+    );
+  });
+
+  it('attaches nothing on live: clicks reach their own handlers untouched', () => {
+    const { target } = renderFlowInWrapper();
+    const { button, liveHandler } = appendPartButton(target, 'payment-option');
+
+    const notPrevented = fireEvent.click(button);
+
+    expect(liveHandler).toHaveBeenCalledTimes(1);
+    expect(notPrevented).toBe(true);
+    expect(postToEditorMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('checkout outlets — capture against a REAL React portal', () => {
+  /**
+   * The plain-DOM harness above proves the listener runs; it cannot prove
+   * anything about React's synthetic dispatch, which is what every real
+   * checkout handler uses. `createPortal` makes React attach its own
+   * delegated capture AND bubble listeners to the very node the outlet's
+   * capture listener sits on, so the ordering has to be verified with a real
+   * portal — including the case where `isDesigner` arrives late (it rides a
+   * postMessage) and the outlet re-registers AFTER the portal mounted.
+   */
+  const Portaled = ({ children }: { children: React.ReactNode }) => {
+    const [node, setNode] = useState<HTMLElement | null>(null);
+
+    useEffect(() => {
+      setNode(
+        document.querySelector<HTMLElement>('[data-checkout-outlet="flow"]')
+      );
+    }, []);
+
+    return node ? createPortal(children, node) : null;
+  };
+
+  const renderWithPortal = (
+    isDesigner: boolean,
+    children: React.ReactNode
+  ) => {
+    const tree = (designer: boolean) => (
+      <div data-block-id="outlet-1">
+        <CheckoutFlowOutletBlock {...props({ isDesigner: designer })} />
+        <Portaled>{children}</Portaled>
+      </div>
+    );
+
+    const rendered = render(tree(isDesigner));
+
+    return { ...rendered, rerenderAsDesigner: () => rendered.rerender(tree(true)) };
+  };
+
+  it('never lets a React onClick fire on the canvas', () => {
+    const onClick = jest.fn();
+    const { container } = renderWithPortal(
+      true,
+      <button data-part="payment-option" onClick={onClick}>
+        Credit Card
+      </button>
+    );
+
+    fireEvent.click(container.querySelector('[data-part]')!);
+
+    expect(onClick).not.toHaveBeenCalled();
+    expect(postToEditorMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        data: expect.objectContaining({ partName: 'payment-option' })
+      })
+    );
+  });
+
+  it('still holds when isDesigner arrives AFTER the portal mounted', () => {
+    const onClick = jest.fn();
+    const { container, rerenderAsDesigner } = renderWithPortal(
+      false,
+      <button data-part="payment-option" onClick={onClick}>
+        Credit Card
+      </button>
+    );
+
+    rerenderAsDesigner();
+    fireEvent.click(container.querySelector('[data-part]')!);
+
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it('blocks the submit a keystroke produces without any click', () => {
+    // Enter inside a card-number field triggers IMPLICIT form submission: the
+    // form gets a `submit` event and no click ever happens, so a click-only
+    // guard would let a canvas keystroke place a real order.
+    const onSubmit = jest.fn((event: React.FormEvent) =>
+      event.preventDefault()
+    );
+    const { container } = renderWithPortal(
+      true,
+      <form onSubmit={onSubmit}>
+        <input data-part="card-number" />
+        <button type="submit" data-part="place-order-button">
+          Pay
+        </button>
+      </form>
+    );
+
+    fireEvent.submit(container.querySelector('form')!);
+
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('cancels the Enter default action, leaving propagation for editor shortcuts', () => {
+    const onKeyDown = jest.fn();
+    const { container } = renderWithPortal(
+      true,
+      <input data-part="card-number" onKeyDown={onKeyDown} />
+    );
+
+    const notPrevented = fireEvent.keyDown(
+      container.querySelector('[data-part]')!,
+      { key: 'Enter' }
+    );
+
+    expect(notPrevented).toBe(false);
+    // Propagation is deliberately NOT stopped — the editor still needs keys.
+    expect(onKeyDown).toHaveBeenCalledTimes(1);
+  });
+
+  it('leaves the live page completely untouched', () => {
+    const onClick = jest.fn();
+    const onSubmit = jest.fn((event: React.FormEvent) =>
+      event.preventDefault()
+    );
+    const { container } = renderWithPortal(
+      false,
+      <form onSubmit={onSubmit}>
+        <button type="button" data-part="payment-option" onClick={onClick}>
+          Credit Card
+        </button>
+      </form>
+    );
+
+    fireEvent.click(container.querySelector('[data-part]')!);
+    fireEvent.submit(container.querySelector('form')!);
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+    expect(postToEditorMock).not.toHaveBeenCalled();
+  });
+});
+
+describe('checkout outlets — the hidden flag stops the claim', () => {
+  // Live drops a hidden block before it mounts; the designer deliberately
+  // keeps it mounted under a display:none wrapper. Without this gate the
+  // hidden outlet still won the claim on the canvas and the piece portaled
+  // the real flow into an invisible subtree — checkout vanished from the
+  // canvas while the storefront rendered it in its default position.
+  const hidden = (over: Record<string, unknown> = {}) =>
+    props({ block: { ...props().block, hidden: true }, ...over });
+
+  it('never registers, on the canvas or on live', () => {
+    render(<CheckoutFlowOutletBlock {...hidden({ isDesigner: true })} />);
+    expect(getCheckoutOutletClaim('flow')).toBeNull();
+
+    render(<CheckoutSummaryOutletBlock {...hidden()} />);
+    expect(getCheckoutOutletClaim('summary')).toBeNull();
+  });
+
+  it('hands the claim to the next outlet instead of swallowing it', () => {
+    render(
+      <>
+        <CheckoutFlowOutletBlock {...hidden({ isDesigner: true })} />
+        <CheckoutFlowOutletBlock {...props({ isDesigner: true })} />
+      </>
+    );
+
+    expect(getCheckoutOutletClaim('flow')).not.toBeNull();
+    expect(
+      screen.getByText('Checkout flow renders here on the storefront')
+    ).toBeInTheDocument();
+    expect(
+      screen.queryByText(
+        'Checkout flow — already placed in another outlet on this page'
+      )
+    ).toBeNull();
+  });
+
+  it('registers again when the flag is cleared', () => {
+    const { rerender } = render(
+      <CheckoutFlowOutletBlock {...hidden({ isDesigner: true })} />
+    );
+    expect(getCheckoutOutletClaim('flow')).toBeNull();
+
+    rerender(<CheckoutFlowOutletBlock {...props({ isDesigner: true })} />);
+    expect(getCheckoutOutletClaim('flow')).not.toBeNull();
+  });
+});
+
+describe('checkout steps outlet — one-page honesty note', () => {
+  const NOTE =
+    'Step indicator only renders with the Step by step checkout — the One page checkout draws its own section numbers';
+
+  it('explains itself when the composition prefers the one-page checkout', () => {
+    registerCheckoutOutlet('flow', {
+      id: 'flow-outlet',
+      node: createDetachedOutletNode(),
+      flowVariant: 'one-page'
+    });
+
+    render(<CheckoutStepsOutletBlock {...props({ isDesigner: true })} />);
+
+    expect(screen.getByText(NOTE)).toBeInTheDocument();
+  });
+
+  it('stays quiet for step-by-step and inherit compositions', () => {
+    registerCheckoutOutlet('flow', {
+      id: 'flow-outlet',
+      node: createDetachedOutletNode(),
+      flowVariant: 'step-by-step'
+    });
+
+    render(<CheckoutStepsOutletBlock {...props({ isDesigner: true })} />);
+
+    expect(screen.queryByText(NOTE)).toBeNull();
+  });
+
+  it('reacts to a designer-time variant edit', () => {
+    registerCheckoutOutlet('flow', {
+      id: 'flow-outlet',
+      node: createDetachedOutletNode(),
+      flowVariant: 'step-by-step'
+    });
+
+    render(<CheckoutStepsOutletBlock {...props({ isDesigner: true })} />);
+    expect(screen.queryByText(NOTE)).toBeNull();
+
+    act(() => {
+      updateCheckoutOutletFlowVariant('flow', 'flow-outlet', 'one-page');
+    });
+
+    expect(screen.getByText(NOTE)).toBeInTheDocument();
+  });
+
+  it('never renders the note on live', () => {
+    registerCheckoutOutlet('flow', {
+      id: 'flow-outlet',
+      node: createDetachedOutletNode(),
+      flowVariant: 'one-page'
+    });
+
+    const { container } = render(<CheckoutStepsOutletBlock {...props()} />);
+
+    expect(container.innerHTML).toBe(
+      '<div data-checkout-outlet="steps"></div>'
+    );
+  });
+});

package/src/blocks/block-renderer-registry.tsx

@@ -58,6 +58,9 @@ import SocialLinksBlock from './social-links-block';
 import PaymentBadgesBlock from './payment-badges-block';
 import CheckoutSummaryBlock from './checkout-summary-block';
 import CheckoutStepsBlock from './checkout-steps-block';
+import CheckoutFlowOutletBlock from './checkout-flow-outlet-block';
+import CheckoutStepsOutletBlock from './checkout-steps-outlet-block';
+import CheckoutSummaryOutletBlock from './checkout-summary-outlet-block';
 import OrderSuccessBlock from './order-success-block';
 import OrderTrackingBlock from './order-tracking-block';
 import ProductBreadcrumbBlock from './product-breadcrumb-block';
@@ -176,6 +179,9 @@ blockRendererRegistry.register('checkout-summary', CheckoutSummaryBlock);
 blockRendererRegistry.register('checkout-steps', CheckoutStepsBlock);
 blockRendererRegistry.register('order-success', OrderSuccessBlock);
 blockRendererRegistry.register('order-tracking', OrderTrackingBlock);
+blockRendererRegistry.register('checkout-flow-outlet', CheckoutFlowOutletBlock);
+blockRendererRegistry.register('checkout-steps-outlet', CheckoutStepsOutletBlock);
+blockRendererRegistry.register('checkout-summary-outlet', CheckoutSummaryOutletBlock);
 
 // Catalog extras
 blockRendererRegistry.register('product-breadcrumb', ProductBreadcrumbBlock);