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

package/src/chrome/composition-source.ts

@@ -0,0 +1,34 @@
+import * as React from 'react';
+import { getWidgetData } from '@akinon/next/data/server';
+
+import { CompositionState, readCompositionState } from './composition-state';
+
+/**
+ * The one server-side answer to "is this slug composed?".
+ *
+ * Two things now ask it for the same slug in one render — the ChromeSlot that
+ * decides whether to render the composition, and the ComposableRegion that
+ * decides whether to still offer the takeover — and asking twice would mean two
+ * requests for one placeholder on every checkout render. Memoizing per request
+ * also guarantees the two cannot reach opposite conclusions from two answers.
+ */
+const load = async (slug: string): Promise<CompositionState> => {
+  try {
+    // The generic is the widget's attributes bag, not the widget wrapper
+    const data = await getWidgetData<{
+      theme_editor_placeholder?: unknown;
+    }>({ slug });
+
+    return readCompositionState(data);
+  } catch {
+    // No chrome widget answered — the caller keeps the project's own markup.
+    return { kind: 'missing' };
+  }
+};
+
+// `React.cache` exists on the RSC-capable React this package renders under;
+// fall back to the raw function on older cores, where correctness is identical
+// and the only cost is a second fetch.
+const cache = (React as { cache?: <T>(fn: T) => T }).cache;
+
+export const getSlugCompositionState = cache ? cache(load) : load;

package/src/chrome/composition-state.ts

@@ -58,6 +58,55 @@ export const readCompositionState = (data: WidgetLike): CompositionState => {
   return { kind: 'composed', sectionCount: layout.length };
 };
 
+/**
+ * Whether the theme the editor just pushed composes this slug.
+ *
+ * The server decides takeover once, at request time, from the persisted order;
+ * the designer has to keep deciding it as the theme changes under the preview.
+ * Two components now ask that question — the fallback that steps aside and the
+ * region that offers the takeover — and they must never disagree about one
+ * slug, so the rule lives here rather than in either of them.
+ *
+ * Returns `null` when the frame says nothing about placeholders at all: that is
+ * not "uncomposed", it is "no answer", and the caller must leave its state
+ * alone rather than withdraw on an unrelated message.
+ */
+export const isSlugComposedInFrame = (
+  frameData: unknown,
+  slug: string
+): boolean | null => {
+  const placeholders = (
+    frameData as { theme?: { placeholders?: unknown } } | undefined
+  )?.theme?.placeholders;
+
+  if (!Array.isArray(placeholders)) return null;
+
+  const placeholder = placeholders.find(
+    (item: { slug?: string; id?: string }) =>
+      item?.slug === slug || item?.id === slug
+  );
+  const sections = placeholder?.sections;
+
+  // Mirror the server's takeover rule exactly: only a *composed* section
+  // replaces the project markup, and a composed section is one that reached
+  // the saved order.
+  //
+  // The `native` exclusion guards against the retired native widget path
+  // rather than supporting it. That path styled a project component in place
+  // instead of replacing it, so its sections never entered the order; the
+  // runtime is gone, but the editor can still hold such a section in a stored
+  // theme and push it here, and withdrawing the project markup for one would
+  // show the designer an empty area no visitor ever sees. It goes when the
+  // editor-side machinery does.
+  return (
+    Array.isArray(sections) &&
+    sections.some(
+      (section: { hidden?: boolean; type?: string }) =>
+        !section?.hidden && section?.type !== 'native'
+    )
+  );
+};
+
 /**
  * Dev-only explanation of a slot that kept the brand markup. One line per slug
  * per process (see `devWarn`), so a brand with no compositions at all does not

package/src/chrome/live-checkout-page-context.tsx

@@ -14,8 +14,9 @@ import { buildCheckoutPageContext } from './page-context';
  * composition authored on the basket page keeps resolving here and the
  * shipping/total figures that live only on the pre-order become bindable.
  *
- * The flow itself stays code-owned — this provider gives the zones data, it
- * does not hand the payment steps over.
+ * The flow's internals stay code-owned — this provider gives the zones data;
+ * placement of the flow is composed via checkout outlet blocks, never its
+ * behavior.
  */
 export const LiveCheckoutPageContext = ({
   path,

package/src/chrome/placeholder-slugs.ts

@@ -40,12 +40,22 @@ export const PLACEHOLDER_SLUGS = {
   accountNotifications: 'account-notifications-body',
   accountStockAlerts: 'account-stock-alerts-body',
 
-  // Order flow. Checkout itself stays code-owned — payment, 3DS and the step
-  // machine are not composable — so the editor only gets the zones above and
-  // below the flow, never the flow.
+  // Order flow. Checkout internals stay sealed — payment forms, 3DS, agreements
+  // and place-order exist only in code — but PLACEMENT is composable: the body
+  // composition arranges where the real flow, steps and summary render via
+  // checkout outlet blocks.
+  //
+  // Two zones only, and they mean exactly what they say: a band above the flow
+  // and a band below it, for a brand that wants trust content without
+  // rebuilding the page. A third "summary" zone existed briefly and was
+  // removed: it rendered as a second full-width band under the flow (the
+  // summary column is client-owned, so a slot could never land inside it), so
+  // it was indistinguishable from the bottom band — and anything meant to sit
+  // beside the summary now belongs in the body composition, around the
+  // summary outlet.
+  checkoutBody: 'checkout-page-body',
   checkoutTop: 'checkout-top-body',
   checkoutBottom: 'checkout-bottom-body',
-  checkoutSummary: 'checkout-summary-body',
   orderSuccess: 'order-success-body',
   orderTracking: 'order-tracking-body',
 

package/src/chrome/route-slug.ts

@@ -66,9 +66,9 @@ const DEFAULT_RULES: RouteSlugRule[] = [
 
   // Order flow
   [/^\/orders\/completed/, PLACEHOLDER_SLUGS.orderSuccess],
-  // Checkout is code-owned; the designer composes the zone above the flow
-  // (the zone below shares the page and is added by the editor's scope).
-  [/^\/orders\/checkout/, PLACEHOLDER_SLUGS.checkoutTop],
+  // Checkout body: the composition arranges WHERE the code-owned flow renders
+  // (via checkout outlet blocks); it can never replace the flow itself.
+  [/^\/orders\/checkout/, PLACEHOLDER_SLUGS.checkoutBody],
   [/^\/anonymous-(orders|tracking)/, PLACEHOLDER_SLUGS.orderTracking],
 
   // Commerce
@@ -99,6 +99,9 @@ const PAGE_MOUNTED_SLUGS = new Set<string>([
   PLACEHOLDER_SLUGS.productListing,
   PLACEHOLDER_SLUGS.basket,
   PLACEHOLDER_SLUGS.orderSuccess,
+  // The checkout layout mounts this slot itself. A root catch-all must skip it:
+  // mounting it with fallback={children} would make the payment flow replaceable.
+  PLACEHOLDER_SLUGS.checkoutBody,
   PLACEHOLDER_SLUGS.accountShell,
   PLACEHOLDER_SLUGS.accountMenu,
   PLACEHOLDER_SLUGS.accountDashboard,

package/src/hooks/use-designer-features.tsx

@@ -18,6 +18,40 @@ interface UseDesignerFeaturesProps {
   blockInfo?: BlockInfo;
 }
 
+/**
+ * Posts the canvas's block/part selection to the editor. Extracted so
+ * renderers that manage their own designer click handling (the checkout
+ * outlet blocks select parts inside TELEPORTED code-owned markup, where no
+ * React handler of ours exists) reuse the exact message the wrapper sends.
+ */
+export function postBlockSelection({
+  placeholderId,
+  sectionId,
+  blockId,
+  blockType,
+  blockLabel,
+  partName
+}: {
+  placeholderId: string;
+  sectionId: string;
+  blockId: string;
+  blockType?: string;
+  blockLabel?: string;
+  partName?: string | null;
+}) {
+  postToEditor({
+    type: 'SELECT_BLOCK',
+    data: {
+      placeholderId,
+      sectionId,
+      blockId,
+      blockType,
+      blockLabel,
+      partName: partName || undefined
+    }
+  });
+}
+
 export function useDesignerFeatures({
   blockId,
   placeholderId,
@@ -46,16 +80,13 @@ export function useDesignerFeatures({
             : null;
 
         if (window.parent) {
-          postToEditor({
-            type: 'SELECT_BLOCK',
-            data: {
-              placeholderId,
-              sectionId,
-              blockId,
-              blockType: blockInfo?.type,
-              blockLabel: blockInfo?.label,
-              partName: partName || undefined
-            }
+          postBlockSelection({
+            placeholderId,
+            sectionId,
+            blockId,
+            blockType: blockInfo?.type,
+            blockLabel: blockInfo?.label,
+            partName
           });
         }
       }

package/src/index.ts

@@ -21,6 +21,7 @@ export type { Section } from './theme-section';
 export type { Block } from './theme-block';
 
 export { default as ChromeSlot } from './chrome/chrome-slot';
+export { default as ComposableRegion } from './chrome/composable-region';
 export { ChromeFallback } from './chrome/chrome-fallback';
 export { CodeOwnedRegion } from './chrome/code-owned-region';
 export { PreviewAuthStateReporter } from './chrome/preview-auth-state';
@@ -60,3 +61,8 @@ export {
   normalizePath
 } from './chrome/route-slug';
 export type { RouteSlugRule } from './chrome/route-slug';
+
+export { CheckoutPiecesProvider } from './chrome/checkout-pieces-provider';
+export { CheckoutPiece } from './chrome/checkout-piece';
+export { CHECKOUT_PIECE_KEYS } from './chrome/checkout-pieces';
+export type { CheckoutPieceKey } from './chrome/checkout-pieces';

package/src/utils/__tests__/checkout-safety.test.ts

@@ -0,0 +1,374 @@
+import { generateThemeCSS } from '../index';
+import {
+  containsCheckoutFlowOutlet,
+  containsCheckoutOutlet,
+  isHidingDeclaration,
+  stripHidingCustomCss,
+  stripHidingStyles
+} from '../checkout-safety';
+import { applyVisibilityRulesToSections } from '../visibility-rules';
+
+/**
+ * I1, enforced where every authoring route converges.
+ *
+ * The editor's descriptors refuse to offer a hide-capable control on the flow
+ * outlet, but that guards one surface. Three routes go around it: an ANCESTOR
+ * block (the flow is portaled inside every parent's wrapper), the scoped
+ * CUSTOM CSS hatch, and a composition authored outside this repo entirely
+ * (the AI generator, the legacy widget editor, a direct API write). The CSS
+ * generator and the visibility-rule pass see all of them, so the rule lives
+ * there: styling may change how checkout looks, never whether it works.
+ */
+
+const section = (blocks: unknown[]) =>
+  [{ id: 'sec', blocks }] as unknown as Parameters<typeof generateThemeCSS>[0];
+
+const flowOutlet = (over: Record<string, unknown> = {}) => ({
+  id: 'flow-outlet',
+  type: 'checkout-flow-outlet',
+  ...over
+});
+
+describe('isHidingDeclaration', () => {
+  it.each([
+    ['display', 'none'],
+    ['display', 'NONE'],
+    ['display', 'none !important'],
+    ['visibility', 'hidden'],
+    ['visibility', 'collapse'],
+    ['pointer-events', 'none'],
+    ['content-visibility', 'hidden'],
+    ['opacity', '0'],
+    ['opacity', '0.0'],
+    ['opacity', '.02'],
+    ['opacity', '0%']
+  ])('treats %s: %s as hiding', (property, value) => {
+    expect(isHidingDeclaration(property, value)).toBe(true);
+  });
+
+  it.each([
+    ['display', 'flex'],
+    ['display', 'grid'],
+    ['visibility', 'visible'],
+    ['pointer-events', 'auto'],
+    ['opacity', '0.9'],
+    ['opacity', '1'],
+    // Values we cannot read are left alone rather than guessed at.
+    ['opacity', 'var(--fade)'],
+    ['color', 'transparent'],
+    ['width', '0']
+  ])('leaves %s: %s alone', (property, value) => {
+    expect(isHidingDeclaration(property, value)).toBe(false);
+  });
+});
+
+describe('subtree detection', () => {
+  it('finds the flow outlet at any depth, and the block itself', () => {
+    expect(containsCheckoutFlowOutlet(flowOutlet())).toBe(true);
+    expect(
+      containsCheckoutFlowOutlet({
+        type: 'group',
+        blocks: [{ type: 'group', blocks: [flowOutlet()] }]
+      })
+    ).toBe(true);
+    expect(containsCheckoutFlowOutlet({ type: 'group', blocks: [] })).toBe(
+      false
+    );
+  });
+
+  it('separates "any outlet" from "the flow outlet"', () => {
+    const summaryOutlet = { type: 'checkout-summary-outlet' };
+
+    expect(containsCheckoutOutlet(summaryOutlet)).toBe(true);
+    expect(containsCheckoutFlowOutlet(summaryOutlet)).toBe(false);
+  });
+
+  it('survives the shapes the three call sites actually pass', () => {
+    expect(containsCheckoutOutlet(null)).toBe(false);
+    expect(containsCheckoutOutlet(undefined)).toBe(false);
+    expect(containsCheckoutOutlet({ blocks: null })).toBe(false);
+    expect(containsCheckoutOutlet({ type: 42, blocks: 'nope' })).toBe(false);
+  });
+});
+
+describe('stripHidingStyles', () => {
+  it('drops only the offending breakpoint, so the flow stays on the page', () => {
+    expect(
+      stripHidingStyles(
+        { display: { desktop: 'flex', mobile: 'none' } },
+        'root-only'
+      )
+    ).toEqual({ display: { desktop: 'flex' } });
+  });
+
+  it('drops the key entirely when every breakpoint hides', () => {
+    expect(
+      stripHidingStyles(
+        { visibility: { desktop: 'hidden', mobile: 'hidden' } },
+        'root-only'
+      )
+    ).toEqual({});
+  });
+
+  it('keeps every layout value untouched', () => {
+    const styles = {
+      display: { desktop: 'flex' },
+      opacity: { desktop: '0.9' },
+      'flex-direction': { desktop: 'column' },
+      width: { desktop: '64%' }
+    };
+
+    expect(stripHidingStyles(styles, 'root-only')).toEqual(styles);
+  });
+
+  it('guards critical parts but leaves the informational summary hideable', () => {
+    const styles = {
+      'place-order-button/display': { desktop: 'none' },
+      'payment-option/pointer-events': { desktop: 'none' },
+      'agreement/opacity': { desktop: '0' },
+      'summary-row/display': { desktop: 'none' },
+      'summary-total/opacity': { desktop: '0' }
+    };
+
+    expect(stripHidingStyles(styles, 'critical-parts')).toEqual({
+      'summary-row/display': { desktop: 'none' },
+      'summary-total/opacity': { desktop: '0' }
+    });
+  });
+
+  it('leaves an ancestor part key alone — it addresses the ancestor own markup', () => {
+    const styles = { 'title/display': { desktop: 'none' } };
+
+    expect(stripHidingStyles(styles, 'root-only')).toEqual(styles);
+  });
+
+  it('reaches a state-qualified part key', () => {
+    expect(
+      stripHidingStyles(
+        { 'payment-option/selected/display': { desktop: 'none' } },
+        'critical-parts'
+      )
+    ).toEqual({});
+  });
+});
+
+describe('stripHidingCustomCss', () => {
+  it('removes the hiding declaration and keeps the rest of the rule', () => {
+    const css = stripHidingCustomCss(
+      '[data-block-id="x"] [data-part="place-order-button"] { display: none; border-radius: 4px; }'
+    );
+
+    expect(css).not.toContain('display: none');
+    expect(css).toContain('border-radius: 4px');
+  });
+
+  it('handles consecutive hiding declarations', () => {
+    const css = stripHidingCustomCss(
+      '.a { display:none;visibility:hidden;pointer-events:none;color:red }'
+    );
+
+    expect(css).not.toMatch(/display\s*:\s*none/);
+    expect(css).not.toMatch(/visibility\s*:\s*hidden/);
+    expect(css).not.toMatch(/pointer-events\s*:\s*none/);
+    expect(css).toContain('color:red');
+  });
+
+  it('leaves legitimate custom CSS alone', () => {
+    const css = '.a { display: flex; opacity: 0.85; visibility: visible }';
+
+    expect(stripHidingCustomCss(css)).toBe(css);
+  });
+});
+
+describe('generateThemeCSS — checkout flow can never be hidden', () => {
+  it('drops a display:none seeded onto a submit-critical part', () => {
+    const css = generateThemeCSS(
+      section([
+        flowOutlet({
+          styles: {
+            'place-order-button/display': { desktop: 'none' },
+            'payment-option/pointer-events': { desktop: 'none' },
+            'payment-option/border-radius': { desktop: '8px' }
+          }
+        })
+      ])
+    );
+
+    expect(css).not.toContain('display: none');
+    expect(css).not.toContain('pointer-events: none');
+    // The style that only changes how it LOOKS still lands.
+    expect(css).toContain('border-radius: 8px !important');
+  });
+
+  it('drops a hide from an ANCESTOR block wrapping the outlet', () => {
+    const css = generateThemeCSS(
+      section([
+        {
+          id: 'flow-column',
+          type: 'group',
+          styles: {
+            visibility: { desktop: 'hidden' },
+            'pointer-events': { desktop: 'none' },
+            display: { desktop: 'flex', mobile: 'none' },
+            width: { desktop: '64%' }
+          },
+          blocks: [flowOutlet()]
+        }
+      ])
+    );
+
+    expect(css).not.toContain('visibility: hidden');
+    expect(css).not.toContain('pointer-events: none');
+    expect(css).not.toContain('display: none');
+    // The column is still a column.
+    expect(css).toContain('display: flex');
+    expect(css).toContain('width: 64%');
+  });
+
+  it('drops a hide from the SECTION wrapping the outlet', () => {
+    const css = generateThemeCSS([
+      {
+        id: 'sec',
+        styles: { display: { desktop: 'none' } },
+        blocks: [flowOutlet()]
+      }
+    ] as never);
+
+    expect(css).not.toContain('display: none');
+  });
+
+  it('closes the custom-CSS hatch on the outlet and on an ancestor', () => {
+    const outletCss = generateThemeCSS(
+      section([
+        flowOutlet({
+          properties: {
+            customCss:
+              '& [data-part="place-order-button"] { display: none } & { border: 1px solid red }'
+          }
+        })
+      ])
+    );
+
+    expect(outletCss).not.toContain('display: none');
+    expect(outletCss).toContain('border: 1px solid red');
+
+    const ancestorCss = generateThemeCSS(
+      section([
+        {
+          id: 'flow-column',
+          type: 'group',
+          properties: { customCss: '& { visibility: hidden }' },
+          blocks: [flowOutlet()]
+        }
+      ])
+    );
+
+    expect(ancestorCss).not.toContain('visibility: hidden');
+  });
+
+  it('leaves an unrelated block free to hide itself', () => {
+    const css = generateThemeCSS(
+      section([
+        {
+          id: 'promo',
+          type: 'group',
+          styles: { display: { mobile: 'none' } },
+          properties: { customCss: '& { visibility: hidden }' }
+        }
+      ])
+    );
+
+    expect(css).toContain('display: none');
+    expect(css).toContain('visibility: hidden');
+  });
+});
+
+describe('visibility rules never gate a checkout outlet', () => {
+  // The claim latches once at page mount and both rule inputs are wrong at
+  // that instant (session 'loading', breakpoint defaulted to desktop), so a
+  // rule-hidden outlet misses the latch and the composed placement is dead
+  // for the whole page load — while the canvas shows it working.
+  const mobileOnly = {
+    visibilityRules: { enabled: true, allowedBreakpoints: ['mobile'] }
+  };
+
+  const context = { authState: 'loading', breakpoint: 'desktop' } as never;
+
+  it('keeps the outlet mounted despite an unsatisfied rule', () => {
+    const [applied] = applyVisibilityRulesToSections(
+      [
+        {
+          id: 'sec',
+          blocks: [{ id: 'o', type: 'checkout-flow-outlet', properties: mobileOnly }]
+        }
+      ] as never,
+      context
+    );
+
+    expect(applied.blocks[0].hidden).toBe(false);
+  });
+
+  it('keeps an ANCESTOR of the outlet mounted too', () => {
+    const [applied] = applyVisibilityRulesToSections(
+      [
+        {
+          id: 'sec',
+          blocks: [
+            {
+              id: 'col',
+              type: 'group',
+              properties: mobileOnly,
+              blocks: [{ id: 'o', type: 'checkout-flow-outlet' }]
+            }
+          ]
+        }
+      ] as never,
+      context
+    );
+
+    expect(applied.blocks[0].hidden).toBe(false);
+  });
+
+  it('keeps the SECTION holding the outlet mounted', () => {
+    const [applied] = applyVisibilityRulesToSections(
+      [
+        {
+          id: 'sec',
+          properties: mobileOnly,
+          blocks: [{ id: 'o', type: 'checkout-summary-outlet' }]
+        }
+      ] as never,
+      context
+    );
+
+    expect(applied.hidden).toBe(false);
+  });
+
+  it('still honours the explicit hidden flag — that one is deliberate', () => {
+    const [applied] = applyVisibilityRulesToSections(
+      [
+        {
+          id: 'sec',
+          blocks: [{ id: 'o', type: 'checkout-flow-outlet', hidden: true }]
+        }
+      ] as never,
+      context
+    );
+
+    expect(applied.blocks[0].hidden).toBe(true);
+  });
+
+  it('leaves every other block ruled as before', () => {
+    const [applied] = applyVisibilityRulesToSections(
+      [
+        {
+          id: 'sec',
+          blocks: [{ id: 'promo', type: 'group', properties: mobileOnly }]
+        }
+      ] as never,
+      context
+    );
+
+    expect(applied.blocks[0].hidden).toBe(true);
+  });
+});