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

package/src/blocks/checkout-flow-outlet-block.tsx

@@ -0,0 +1,104 @@
+'use client';
+
+import React from 'react';
+import { BlockRendererProps } from './block-renderer-registry';
+import { CheckoutOutletBlock } from './checkout-outlet-base';
+import { CheckoutFlowVariantPreference } from '../chrome/checkout-pieces';
+
+/**
+ * Parts HOSTED by this outlet: stamped (`partAttrs`) by the code-owned
+ * checkout flow that teleports here, never rendered by the outlet itself.
+ * The editor's descriptor conformance reads this literal, and
+ * `checkout-hosted-parts.test.ts` verifies every name is honestly stamped in
+ * the app's checkout views — extend both sides together or the tests fail.
+ *
+ * The `summary-*` names exist here AND on the summary outlet on purpose, and
+ * the flow outlet declares the WHOLE summary vocabulary, not a subset:
+ *
+ * - `MobileSummarySheet` re-renders the full `OnePageSummary` inside the flow
+ *   subtree, and part rules are block-scoped, so the summary outlet's rules
+ *   can never reach the sheet;
+ * - when a composition places no summary outlet, the unclaimed summary piece
+ *   renders in its default in-place position — which is inside the flow — so
+ *   the desktop rail lands in this subtree too.
+ *
+ * Declaring only some of the names left the rest with no reachable control at
+ * all in those compositions, and made a click on the sheet's card fall back
+ * to the block panel with nothing explaining why.
+ */
+export const HOSTED_PARTS = [
+  'section',
+  'section-header',
+  'section-number',
+  'section-title',
+  'edit-button',
+  'payment-options',
+  'payment-option',
+  'payment-option-icon',
+  'payment-panel',
+  'continue-button',
+  'place-order-button',
+  'agreement',
+  'summary',
+  'summary-header',
+  'summary-title',
+  'summary-item',
+  'summary-row',
+  'summary-row-label',
+  'summary-row-value',
+  'summary-total',
+  'summary-total-label',
+  'summary-total-value',
+  'summary-edit'
+] as const;
+
+/**
+ * The only values a composition may steer the checkout layout to. The
+ * unified basket-and-checkout / accordion experiences are settings-only —
+ * a composition can never change unified-ness. Anything else (including
+ * 'inherit', absent, non-strings) means inherit and registers no preference.
+ */
+const FLOW_VARIANT_VALUES = new Set(['one-page', 'step-by-step']);
+
+/**
+ * `flowVariant` is breakpoint-invariant (outlet claims and the live latch
+ * are breakpoint-unaware): plain strings are taken as-is, per-breakpoint
+ * objects read the authoritative desktop value.
+ */
+const resolveFlowVariant = (
+  raw: unknown
+): CheckoutFlowVariantPreference | undefined => {
+  const candidate =
+    typeof raw === 'string'
+      ? raw
+      : (raw as { desktop?: unknown } | null | undefined)?.desktop;
+
+  return typeof candidate === 'string' && FLOW_VARIANT_VALUES.has(candidate)
+    ? (candidate as CheckoutFlowVariantPreference)
+    : undefined;
+};
+
+/**
+ * Outlet for the ENTIRE checkout flow — auth gate, error and loading states,
+ * and the mounted variant with its payment steps, providers and modals. The
+ * flow is atomic: no finer granularity exists, and this block only decides
+ * WHERE the code-owned flow renders — plus, via `flowVariant`, WHICH of the
+ * two standalone layouts the composition prefers — never what the flow does.
+ * When no outlet claims the flow, it renders in its default in-place
+ * position, so ordering is never impossible.
+ */
+const CheckoutFlowOutletBlock = (props: BlockRendererProps) => {
+  const { block } = props;
+  const flowVariant = resolveFlowVariant(block.properties?.flowVariant);
+
+  return (
+    <CheckoutOutletBlock
+      {...props}
+      piece="flow"
+      designerLabel="Checkout flow"
+      flowVariant={flowVariant}
+    />
+  );
+};
+
+export default CheckoutFlowOutletBlock;

package/src/blocks/checkout-outlet-base.tsx

@@ -0,0 +1,241 @@
+'use client';
+
+import React, {
+  useEffect,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useSyncExternalStore
+} from 'react';
+import { BlockRendererProps } from './block-renderer-registry';
+import { DesignerPlaceholder } from './product-block-utils';
+import { PLACEHOLDER_SLUGS } from '../chrome/placeholder-slugs';
+import { postBlockSelection } from '../hooks/use-designer-features';
+import {
+  CheckoutFlowVariantPreference,
+  CheckoutPieceKey,
+  isCheckoutOutletWinner,
+  isCheckoutPieceMounted,
+  noPieceOnServer,
+  registerCheckoutOutlet,
+  subscribeCheckoutPieces,
+  unregisterCheckoutOutlet,
+  updateCheckoutOutletFlowVariant
+} from '../chrome/checkout-pieces';
+
+/**
+ * Shared base for the checkout outlet blocks — positioning targets for the
+ * checkout pieces bridge, and nothing more. An outlet renders one empty
+ * `div[data-checkout-outlet]` that the matching `CheckoutPiece` wrapper
+ * teleports the real, code-owned checkout component into via `createPortal`.
+ *
+ * SEALED BY DESIGN: this renderer emits no interactive elements, no
+ * callbacks, and no props that reach checkout internals. It cannot render
+ * payment inputs, agreement checkboxes, or a place-order trigger — the real
+ * flow keeps its own React tree and merely lands here in the DOM. Root styles
+ * still apply through the `[data-block-id]` wrapper, and scoped custom CSS may
+ * restyle the teleported markup; restyling is accepted — it cannot synthesize
+ * behavior.
+ *
+ * ZONE GATE: an outlet only registers when it renders inside the
+ * `checkout-page-body` placeholder. The flow piece latches its teleport
+ * decision one-shot at page mount, and only the body slot is guaranteed to
+ * hydrate before that latch — an outlet composed into a trailing zone
+ * (Summary Extras, Bottom) registers after the latch and would be silently
+ * dead on the live site while the designer canvas happily teleported into it.
+ * Refusing to register outside the body zone keeps the canvas and the
+ * storefront telling the same story everywhere (including non-checkout
+ * pages), and the designer band below explains why instead of promising a
+ * render that would never happen.
+ *
+ * Live behavior when the outlet is unclaimed, out of zone, or the piece is
+ * absent: the single empty div, nothing else (the piece then renders in its
+ * default in-place position, so ordering is never lost). Duplicate outlets
+ * for the same piece resolve first-wins. A composition re-publish applies to
+ * checkout on the next full page load — live pages never re-target a latched
+ * piece.
+ *
+ * The target div is rendered UNCONDITIONALLY and its identity never changes
+ * for the outlet's life: a portaled flow may host payment iframes and 3DS
+ * containers, and swapping the target node would remount them mid-payment.
+ *
+ * HIDDEN GATE: a hidden outlet never registers. Live already drops hidden
+ * blocks before they mount (theme-section filters them out), but the designer
+ * deliberately keeps them mounted under a `display:none` wrapper so a
+ * visibility toggle does not remount half the page. Without this gate the
+ * hidden outlet still won the first-wins 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. The
+ * descriptor promises the opposite ("its hidden flag stops it from claiming
+ * at all"), so the gate makes both sides tell that same story.
+ *
+ * DESIGNER INPUT CAPTURE: the teleported markup is code-owned — none of our
+ * React handlers exist inside it. When `isDesigner`, native capture listeners
+ * on the target div neutralize the interactions that could reach a live
+ * handler, so payment option POSTs, step navigation and order submits can
+ * never fire on the canvas:
+ *
+ * - `click` is neutralized (preventDefault + stopPropagation) and selects the
+ *   clicked `[data-part]` in the editor panel;
+ * - `submit` is neutralized too. A click guard alone does not cover it:
+ *   pressing Enter inside a card-number field triggers IMPLICIT form
+ *   submission, which dispatches `submit` without any click at all;
+ * - `keydown` of Enter is default-prevented (without stopping propagation, so
+ *   editor shortcuts still see it) — that is the default action implicit
+ *   submission rides on.
+ *
+ * The listeners exist ONLY in the designer: live pages get zero listeners and
+ * zero behavior change.
+ */
+export function CheckoutOutletBlock({
+  piece,
+  designerLabel,
+  flowVariant,
+  designerNote,
+  ...props
+}: BlockRendererProps & {
+  piece: CheckoutPieceKey;
+  designerLabel: string;
+  /** The flow outlet's validated composed layout preference (absent = inherit). */
+  flowVariant?: CheckoutFlowVariantPreference;
+  /** Extra designer-only band explaining outlet-specific caveats. */
+  designerNote?: string | null;
+}) {
+  const outletId = useId();
+  const targetRef = useRef<HTMLDivElement | null>(null);
+  const inBodyZone = props.placeholderId === PLACEHOLDER_SLUGS.checkoutBody;
+  // Live never even mounts a hidden block; the designer does, so the claim
+  // has to be refused here for the two sides to agree.
+  const isHidden = Boolean(props.block.hidden);
+  const canClaim = inBodyZone && !isHidden;
+
+  // Read at register time via a ref so a designer property edit never
+  // re-runs the register effect (re-registering would drop and re-queue the
+  // claim, churning first-wins order and the live latch).
+  const flowVariantRef = useRef(flowVariant);
+  flowVariantRef.current = flowVariant;
+
+  useLayoutEffect(() => {
+    if (!canClaim || !targetRef.current) return;
+
+    registerCheckoutOutlet(piece, {
+      id: outletId,
+      node: targetRef.current,
+      flowVariant: flowVariantRef.current
+    });
+    return () => unregisterCheckoutOutlet(piece, outletId);
+  }, [piece, outletId, canClaim]);
+
+  // Designer-time property edits update the registration in place (no
+  // re-register, no reorder) so the canvas previews the new variant
+  // immediately. On mount this runs after registration with the same value —
+  // a no-op by design.
+  useLayoutEffect(() => {
+    if (!canClaim) return;
+
+    updateCheckoutOutletFlowVariant(piece, outletId, flowVariant);
+  }, [piece, outletId, canClaim, flowVariant]);
+
+  useEffect(() => {
+    if (!props.isDesigner) return;
+
+    const node = targetRef.current;
+    if (!node) return;
+
+    const handleCanvasClick = (event: MouseEvent) => {
+      // Neutralize FIRST, unconditionally: no click inside teleported
+      // checkout markup may reach a live handler on the canvas.
+      event.preventDefault();
+      event.stopPropagation();
+
+      const partElement =
+        event.target instanceof Element
+          ? event.target.closest<HTMLElement>('[data-part]')
+          : null;
+      // A part is owned by its closest [data-block-id] ancestor — the same
+      // rule the CSS ownership guard applies. The teleported markup carries
+      // no nested block wrappers, so owned parts resolve to this outlet.
+      const ownerWrapper = node.closest('[data-block-id]');
+      const partName =
+        partElement && partElement.closest('[data-block-id]') === ownerWrapper
+          ? partElement.getAttribute('data-part')
+          : null;
+
+      postBlockSelection({
+        placeholderId: props.placeholderId,
+        sectionId: props.sectionId,
+        blockId: props.block.id,
+        blockType: props.block.type,
+        blockLabel: props.block.label,
+        partName
+      });
+    };
+
+    // Implicit form submission never produces a click: Enter inside a text
+    // field dispatches `submit` straight at the form. Neutralizing it here
+    // keeps a canvas keystroke from placing a real order.
+    const handleCanvasSubmit = (event: Event) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+
+    // The default action Enter carries IS implicit submission, so cancelling
+    // it closes the same hole one step earlier. Propagation is deliberately
+    // left alone — the editor's own keyboard shortcuts still need the event.
+    const handleCanvasKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Enter') event.preventDefault();
+    };
+
+    node.addEventListener('click', handleCanvasClick, true);
+    node.addEventListener('submit', handleCanvasSubmit, true);
+    node.addEventListener('keydown', handleCanvasKeyDown, true);
+
+    return () => {
+      node.removeEventListener('click', handleCanvasClick, true);
+      node.removeEventListener('submit', handleCanvasSubmit, true);
+      node.removeEventListener('keydown', handleCanvasKeyDown, true);
+    };
+  }, [
+    props.isDesigner,
+    props.placeholderId,
+    props.sectionId,
+    props.block.id,
+    props.block.type,
+    props.block.label
+  ]);
+
+  const isWinner = useSyncExternalStore(
+    subscribeCheckoutPieces,
+    () => isCheckoutOutletWinner(piece, outletId),
+    noPieceOnServer
+  );
+  const pieceMounted = useSyncExternalStore(
+    subscribeCheckoutPieces,
+    () => isCheckoutPieceMounted(piece),
+    noPieceOnServer
+  );
+
+  return (
+    <>
+      <div data-checkout-outlet={piece} ref={targetRef} />
+      {props.isDesigner && !inBodyZone && (
+        <DesignerPlaceholder
+          label={`${designerLabel} outlet only works inside the Checkout Body zone — the storefront ignores it here`}
+        />
+      )}
+      {props.isDesigner && canClaim && !isWinner && (
+        <DesignerPlaceholder
+          label={`${designerLabel} — already placed in another outlet on this page`}
+        />
+      )}
+      {props.isDesigner && canClaim && isWinner && !pieceMounted && (
+        <DesignerPlaceholder
+          label={`${designerLabel} renders here on the storefront`}
+        />
+      )}
+      {props.isDesigner && canClaim && isWinner && designerNote && (
+        <DesignerPlaceholder label={designerNote} />
+      )}
+    </>
+  );
+}

package/src/blocks/checkout-steps-outlet-block.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import React, { useSyncExternalStore } from 'react';
+import { BlockRendererProps } from './block-renderer-registry';
+import { CheckoutOutletBlock } from './checkout-outlet-base';
+import {
+  getCheckoutFlowVariantOverride,
+  noFlowVariantOnServer,
+  subscribeCheckoutPieces
+} from '../chrome/checkout-pieces';
+
+/**
+ * Parts HOSTED by this outlet: stamped (`partAttrs`) by the code-owned
+ * multi-step step indicator that teleports here, never rendered by the
+ * outlet itself. The editor's descriptor conformance reads this literal, and
+ * `checkout-hosted-parts.test.ts` verifies every name is honestly stamped in
+ * the app's checkout views — extend both sides together or the tests fail.
+ */
+export const HOSTED_PARTS = [
+  'steps',
+  'step',
+  'step-number',
+  'step-label',
+  'step-icon'
+] as const;
+
+/**
+ * Outlet for the checkout steps indicator. Multi-step variant only: the
+ * one-page family (one-page, accordion, basket-and-checkout) never mounts the
+ * steps piece, so on those storefronts this outlet stays an empty div on live
+ * and shows its labeled band in the designer. That is by design — a synthetic
+ * steps indicator is never fabricated for variants that have no steps. When
+ * the composition's flow outlet prefers the one-page layout, the designer
+ * band says so instead of promising a render that will never happen.
+ */
+const CheckoutStepsOutletBlock = (props: BlockRendererProps) => {
+  const flowVariantOverride = useSyncExternalStore(
+    subscribeCheckoutPieces,
+    getCheckoutFlowVariantOverride,
+    noFlowVariantOnServer
+  );
+
+  return (
+    <CheckoutOutletBlock
+      {...props}
+      piece="steps"
+      designerLabel="Checkout steps indicator"
+      designerNote={
+        flowVariantOverride === 'one-page'
+          ? 'Step indicator only renders with the Step by step checkout — the One page checkout draws its own section numbers'
+          : null
+      }
+    />
+  );
+};
+
+export default CheckoutStepsOutletBlock;

package/src/blocks/checkout-summary-outlet-block.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import React from 'react';
+import { BlockRendererProps } from './block-renderer-registry';
+import { CheckoutOutletBlock } from './checkout-outlet-base';
+
+/**
+ * Parts HOSTED by this outlet: stamped (`partAttrs`) by the code-owned
+ * summary (multi-step `Summary` or one-page desktop `OnePageSummary`) that
+ * teleports here, never rendered by the outlet itself. The editor's
+ * descriptor conformance reads this literal, and
+ * `checkout-hosted-parts.test.ts` verifies every name is honestly stamped in
+ * the app's checkout views — extend both sides together or the tests fail.
+ */
+export const HOSTED_PARTS = [
+  'summary',
+  'summary-header',
+  'summary-title',
+  'summary-item',
+  'summary-row',
+  'summary-row-label',
+  'summary-row-value',
+  'summary-total',
+  'summary-total-label',
+  'summary-total-value',
+  'summary-edit'
+] as const;
+
+/**
+ * Outlet for the checkout order summary — multi-step's `Summary` or the
+ * one-page family's `OnePageSummary`, whichever variant mounts. The mobile
+ * summary sheet is never wrapped as a piece (it is a fixed-position overlay
+ * that travels only as part of the flow), so it never lands here.
+ */
+const CheckoutSummaryOutletBlock = (props: BlockRendererProps) => (
+  <CheckoutOutletBlock
+    {...props}
+    piece="summary"
+    designerLabel="Checkout order summary"
+  />
+);
+
+export default CheckoutSummaryOutletBlock;

package/src/chrome/checkout-piece.tsx

@@ -0,0 +1,145 @@
+'use client';
+
+import React, {
+  useEffect,
+  useLayoutEffect,
+  useState,
+  useSyncExternalStore
+} from 'react';
+import { createPortal } from 'react-dom';
+
+import {
+  announceCheckoutPiece,
+  CheckoutOutletRegistration,
+  CheckoutPieceKey,
+  getCheckoutOutletClaim,
+  noClaimOnServer,
+  retractCheckoutPiece,
+  subscribeCheckoutPieces
+} from './checkout-pieces';
+import { useCheckoutPiecesEnabled } from './checkout-pieces-provider';
+
+/**
+ * Wraps a real, code-owned checkout component (the flow, the steps indicator,
+ * the order summary) and teleports it — via `createPortal`, so the component
+ * keeps its React parents and its state — into a checkout outlet block when a
+ * composition placed one, or renders it in place otherwise.
+ *
+ * Behavior and its consequences, pinned:
+ *
+ * - SSR and the pre-latch render are in place, so hydration matches the server
+ *   HTML; with no composition the wrapper contributes ZERO wrapper elements
+ *   and zero attributes (bare fragments), keeping the uncomposed page
+ *   byte-identical to a build without the bridge.
+ * - The pending-to-portal flip remounts the children ONCE, at the piece's own
+ *   mount instant, when the subtree is stateless (page gates: spinner/null;
+ *   variant pieces: freshly mounted) and no payment surface exists yet. After
+ *   the latch, the render never flips between portal and fragment on live, so
+ *   iframes born inside the flow never move.
+ * - The latch works pre-first-paint because the checkout layout mounts the
+ *   `checkout-page-body` ChromeSlot as an EARLIER SIBLING of the flow: outlet
+ *   `useLayoutEffect` registrations flush before this latch runs, and the
+ *   latch's state update flushes synchronously before paint.
+ * - Late registration on live is IGNORED — an unclaimed latch is permanent
+ *   until navigation, so a composition publish applies to checkout on the
+ *   next full page load, never mid-session.
+ * - If the latched outlet disappears, the piece comes home (renders in place)
+ *   rather than chasing another outlet: ordering must never become impossible,
+ *   and a portaled flow hosting an iframe must never be re-targeted.
+ * - The `useSyncExternalStore` server snapshot is "unclaimed", so the piece
+ *   never portals during SSR.
+ * - Outside `CheckoutPiecesProvider` the wrapper is inert and always renders
+ *   its children in place — checkout components reused anywhere else can
+ *   never be teleported.
+ */
+export function CheckoutPiece({
+  piece,
+  children
+}: {
+  piece: CheckoutPieceKey;
+  children: React.ReactNode;
+}) {
+  const enabled = useCheckoutPiecesEnabled();
+
+  // Rendering the bridge as an inner component (instead of returning early
+  // past its hooks) keeps hook order legal for React while guaranteeing that
+  // nothing else runs when the bridge is disabled.
+  if (!enabled) return <>{children}</>;
+
+  return <CheckoutPieceBridge piece={piece}>{children}</CheckoutPieceBridge>;
+}
+
+function CheckoutPieceBridge({
+  piece,
+  children
+}: {
+  piece: CheckoutPieceKey;
+  children: React.ReactNode;
+}) {
+  const [isDesigner, setIsDesigner] = useState(false);
+
+  // Designer detection uses the editor-proven flag, NOT a framing check.
+  // `window.__themeEditorDesigner` is set only after a trusted
+  // SET_THEME_EDITOR_COOKIE arrives through the origin-guarded editor bridge
+  // (see theme-placeholder-client.tsx) — being framed is not the same as
+  // being edited. A production checkout page legitimately iframed (partner
+  // portal, kiosk shell) must keep live semantics: the one-shot latch and
+  // no claim-following, so a portaled flow hosting a payment iframe can
+  // never be re-targeted mid-3DS.
+  //
+  // The flag can arrive AFTER this mount (it rides a postMessage). Designer
+  // semantics only diverge from live when a claim appears or changes, and
+  // every claim change notifies the pieces store — so re-checking on store
+  // notifications picks the flag up before the difference can matter.
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    if (window.__themeEditorDesigner === true) {
+      setIsDesigner(true);
+      return;
+    }
+
+    return subscribeCheckoutPieces(() => {
+      if (window.__themeEditorDesigner === true) {
+        setIsDesigner(true);
+      }
+    });
+  }, []);
+
+  // Live subscription to the current first-wins claim for this piece.
+  const claim = useSyncExternalStore(
+    subscribeCheckoutPieces,
+    () => getCheckoutOutletClaim(piece),
+    noClaimOnServer
+  );
+
+  // The live site's one-shot decision: 'pending' until the mount latch runs,
+  // then either the outlet claimed at that instant or null forever.
+  const [decision, setDecision] = useState<
+    CheckoutOutletRegistration | null | 'pending'
+  >('pending');
+
+  useLayoutEffect(() => {
+    announceCheckoutPiece(piece);
+    setDecision(getCheckoutOutletClaim(piece));
+
+    return () => retractCheckoutPiece(piece);
+  }, [piece]);
+
+  if (isDesigner) {
+    // Designer canvas: follow the live claim so the author sees edits
+    // immediately. Retargeting remounts the piece and resets checkout state —
+    // acceptable on the canvas only.
+    return claim ? createPortal(children, claim.node) : <>{children}</>;
+  }
+
+  if (decision === 'pending' || decision === null) return <>{children}</>;
+
+  // Live site, latched to an outlet: honor it only while that exact outlet is
+  // still alive. Never chase a different outlet (no retargeting — iframe/3DS
+  // safety), and if the latched outlet disappears, come home so ordering is
+  // never impossible.
+  const alive = claim !== null && claim.id === decision.id;
+
+  return alive ? createPortal(children, decision.node) : <>{children}</>;
+}

package/src/chrome/checkout-pieces-provider.tsx

@@ -0,0 +1,28 @@
+'use client';
+
+import React, { createContext, useContext } from 'react';
+
+/**
+ * Opt-in gate for the checkout pieces bridge. The checkout layout wraps its
+ * subtree with this provider; a `CheckoutPiece` rendered OUTSIDE it always
+ * renders its children in place, as a bare fragment. That guarantee is the
+ * point: checkout components reused anywhere else in an app can never be
+ * teleported by a composition, because only the checkout layout enables the
+ * bridge.
+ */
+const CheckoutPiecesEnabledContext = createContext(false);
+
+export function CheckoutPiecesProvider({
+  children
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <CheckoutPiecesEnabledContext.Provider value={true}>
+      {children}
+    </CheckoutPiecesEnabledContext.Provider>
+  );
+}
+
+export const useCheckoutPiecesEnabled = () =>
+  useContext(CheckoutPiecesEnabledContext);