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

package/src/utils/checkout-safety.ts

@@ -0,0 +1,177 @@
+/**
+ * The last line of defence for "a composition may restyle checkout, never
+ * break it".
+ *
+ * The editor's descriptors already refuse to offer a hide-capable control on
+ * the checkout flow outlet. That guard covers exactly one authoring surface.
+ * Published compositions do not all come from it — the AI generator, the
+ * legacy widget editor and direct API writes all produce the same JSON, and
+ * two routes bypass the descriptors even inside the editor:
+ *
+ * - an ANCESTOR block. The flow is portaled into the outlet's wrapper, which
+ *   sits inside every parent block's wrapper, so `display:none` on the
+ *   surrounding column hides the real payment flow just as effectively.
+ * - the scoped CUSTOM CSS hatch, which by design emits whatever it is given
+ *   (`& [data-part="place-order-button"] { display: none }`).
+ *
+ * The CSS generator is the one place every route converges, so the rule is
+ * enforced here: a declaration that would remove the checkout flow from the
+ * page, or from the shopper's pointer, is dropped before it is emitted.
+ *
+ * SCOPE, stated honestly: this drops the declarations that unambiguously
+ * remove an element or its interactivity — `display:none`, `visibility`
+ * hidden/collapse, `pointer-events:none`, `content-visibility:hidden` and a
+ * effectively-zero `opacity`. It is not a general "can a designer make this
+ * hard to see" filter: nothing here stops a 1px-tall box or white-on-white
+ * text, and it is not meant to. Layout values a real composition needs
+ * (`display:flex`, `opacity:.9`) pass through untouched — this only ever
+ * subtracts the values that end ordering.
+ */
+
+import { parsePartStyleKey } from './part-styles';
+
+export const CHECKOUT_FLOW_OUTLET_TYPE = 'checkout-flow-outlet';
+
+export const CHECKOUT_OUTLET_BLOCK_TYPES = [
+  CHECKOUT_FLOW_OUTLET_TYPE,
+  'checkout-steps-outlet',
+  'checkout-summary-outlet'
+] as const;
+
+const OUTLET_TYPES = new Set<string>(CHECKOUT_OUTLET_BLOCK_TYPES);
+
+/**
+ * Parts whose disappearance is a LOOK change, not a broken order: the summary
+ * is informational and the flow outlet hosts it only because the mobile sheet
+ * re-renders it inside the flow subtree. Everything else the flow stamps —
+ * sections, payment options, the payment panel, continue and place-order, the
+ * agreement row, the step indicator — is on the path to a placed order.
+ */
+const INFORMATIONAL_PART_PREFIX = 'summary';
+
+const FLOW_OUTLET_TYPES = new Set<string>([CHECKOUT_FLOW_OUTLET_TYPE]);
+
+/**
+ * True when the node IS, or contains at any depth, one of the given types.
+ * Accepts `unknown` on purpose: sections and blocks come from three different
+ * shapes across the codebase (theme JSON, the editor's Block, the renderer's
+ * ThemeBlockData) and every caller only needs `type` plus `blocks`.
+ */
+const subtreeHasType = (node: unknown, types: Set<string>): boolean => {
+  if (!node || typeof node !== 'object') return false;
+
+  const { type, blocks } = node as { type?: unknown; blocks?: unknown };
+
+  if (typeof type === 'string' && types.has(type)) return true;
+
+  return Array.isArray(blocks)
+    ? blocks.some((child) => subtreeHasType(child, types))
+    : false;
+};
+
+export const containsCheckoutFlowOutlet = (node: unknown): boolean =>
+  subtreeHasType(node, FLOW_OUTLET_TYPES);
+
+export const containsCheckoutOutlet = (node: unknown): boolean =>
+  subtreeHasType(node, OUTLET_TYPES);
+
+/**
+ * A CSS declaration that takes the element off the page or out of reach.
+ * Values arrive as authored, so they are trimmed and lower-cased first; a
+ * value we cannot read as a number (a var(), a calc()) is left alone rather
+ * than guessed at.
+ */
+export const isHidingDeclaration = (
+  property: string,
+  value: unknown
+): boolean => {
+  if (typeof value !== 'string' && typeof value !== 'number') return false;
+
+  const name = String(property).trim().toLowerCase();
+  const raw = String(value).trim().toLowerCase().replace(/\s*!important$/, '');
+
+  switch (name) {
+    case 'display':
+      return raw === 'none';
+    case 'visibility':
+      return raw === 'hidden' || raw === 'collapse';
+    case 'pointer-events':
+      return raw === 'none';
+    case 'content-visibility':
+      return raw === 'hidden';
+    case 'opacity': {
+      const numeric = raw.endsWith('%')
+        ? Number.parseFloat(raw) / 100
+        : Number.parseFloat(raw);
+      return Number.isFinite(numeric) && numeric < 0.1;
+    }
+    default:
+      return false;
+  }
+};
+
+/** Responsive buckets are per breakpoint, so only the offending one is dropped. */
+const stripHidingFromValue = (property: string, value: unknown): unknown => {
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const kept = Object.entries(value as Record<string, unknown>).filter(
+      ([, breakpointValue]) => !isHidingDeclaration(property, breakpointValue)
+    );
+
+    // Dropping the mobile bucket makes it fall through to desktop, which is
+    // the safe direction: the flow stays on the page at every width.
+    return kept.length > 0 ? Object.fromEntries(kept) : undefined;
+  }
+
+  return isHidingDeclaration(property, value) ? undefined : value;
+};
+
+/**
+ * A block's styles with every order-breaking declaration removed.
+ *
+ * `partScope` decides how part keys are treated: 'critical-parts' keeps the
+ * informational `summary-*` groups hideable (the mobile sheet and the totals
+ * are not on the ordering path), 'root-only' leaves every part key alone and
+ * is what an ancestor block gets — an ancestor's part keys address its own
+ * markup, never the teleported flow.
+ */
+export const stripHidingStyles = (
+  styles: Record<string, unknown> | undefined | null,
+  partScope: 'root-only' | 'critical-parts'
+): Record<string, unknown> => {
+  const safe: Record<string, unknown> = {};
+
+  Object.entries(styles || {}).forEach(([key, value]) => {
+    const parsed = parsePartStyleKey(key);
+
+    const guarded = parsed
+      ? partScope === 'critical-parts' &&
+        !parsed.part.startsWith(INFORMATIONAL_PART_PREFIX)
+      : true;
+
+    if (!guarded) {
+      safe[key] = value;
+      return;
+    }
+
+    const property = parsed ? parsed.property : key;
+    const kept = stripHidingFromValue(property, value);
+
+    if (kept !== undefined) safe[key] = kept;
+  });
+
+  return safe;
+};
+
+/**
+ * The same rule for the custom-CSS hatch, applied to the generated text.
+ *
+ * The hatch is free-form, so this works declaration by declaration: the
+ * leading delimiter is preserved and only the declaration itself is removed,
+ * which keeps every surrounding rule and every other declaration intact.
+ */
+export const stripHidingCustomCss = (css: string): string =>
+  css.replace(
+    /(^|[;{])(\s*)(display|visibility|pointer-events|content-visibility|opacity)(\s*:\s*)([^;}]*)/gi,
+    (match, delimiter, space, property, colon, value) =>
+      isHidingDeclaration(property, value) ? delimiter : match
+  );

package/src/utils/index.ts

@@ -7,6 +7,12 @@ import {
 } from './css-safety';
 import { buildPartSelectors, splitPartStyles } from './part-styles';
 import { buildCustomCss } from './custom-css';
+import {
+  CHECKOUT_FLOW_OUTLET_TYPE,
+  containsCheckoutFlowOutlet,
+  stripHidingCustomCss,
+  stripHidingStyles
+} from './checkout-safety';
 import { hasBindingToken } from './iterator-utils';
 import {
   BREAKPOINT_FALLBACKS,
@@ -18,6 +24,7 @@ export * from './publish-window';
 export * from './part-styles';
 export * from './custom-css';
 export * from './breakpoints';
+export * from './checkout-safety';
 
 export type ImageLoadingStrategy = 'eager' | 'lazy';
 export type ImageFetchPriority = 'high' | 'auto' | 'low';
@@ -490,6 +497,12 @@ const resolveEntryValue = (
 
 interface Block {
   id: string;
+  /**
+   * Read only to recognise the checkout outlets: a block that is or holds the
+   * flow outlet has the real payment flow portaled into its wrapper, so its
+   * hide-capable declarations are dropped (see utils/checkout-safety.ts).
+   */
+  type?: string;
   styleSourceId?: string;
   styles?: ResponsiveStyles;
   /** Set by blocks that name their real root with `data-part="root"`. */
@@ -1125,14 +1138,29 @@ const collectBlockCSS = (
   let css = '';
 
   blocks.forEach((block) => {
-    if (block.styles && Object.keys(block.styles).length > 0) {
+    // A block that IS or CONTAINS the checkout flow outlet has the real
+    // payment flow portaled into its wrapper, so anything that hides the
+    // wrapper hides checkout. The outlet itself additionally guards its part
+    // keys; an ancestor's part keys address its own markup and are left
+    // alone. See utils/checkout-safety.ts.
+    const guardsCheckoutFlow = containsCheckoutFlowOutlet(block);
+    const blockStyles = guardsCheckoutFlow
+      ? stripHidingStyles(
+          block.styles,
+          block.type === CHECKOUT_FLOW_OUTLET_TYPE
+            ? 'critical-parts'
+            : 'root-only'
+        )
+      : block.styles;
+
+    if (blockStyles && Object.keys(blockStyles).length > 0) {
       const selector = `[data-block-id="${escapeCssAttributeValue(
         block.styleSourceId || block.id
       )}"]`;
       // Root styles ignore part keys, so a part override never leaks onto the
       // block wrapper (a padding meant for the dropdown would otherwise
       // reposition the whole block).
-      const { root } = splitPartStyles(block.styles);
+      const { root } = splitPartStyles(blockStyles);
 
       if (Object.keys(root).length > 0) {
         // `data-block-id` sits on the designer wrapper, not on the element the
@@ -1148,18 +1176,20 @@ const collectBlockCSS = (
         css += generateElementCSS(rootSelector, root, targetBreakpoint);
       }
 
-      css += generatePartCSS(selector, block.styles, targetBreakpoint);
+      css += generatePartCSS(selector, blockStyles, targetBreakpoint);
     }
 
     if (block.properties) {
       const selector = `[data-block-id="${escapeCssAttributeValue(
         block.styleSourceId || block.id
       )}"]`;
-      css += buildCustomCss(
+      const customCss = buildCustomCss(
         block.properties as Record<string, unknown>,
         selector,
         targetBreakpoint
       );
+
+      css += guardsCheckoutFlow ? stripHidingCustomCss(customCss) : customCss;
     }
 
     if (block.blocks && block.blocks.length > 0) {
@@ -1181,10 +1211,17 @@ export const generateThemeCSS = (
       section.id
     )}"]`;
 
-    if (section.styles && Object.keys(section.styles).length > 0) {
+    // A section wrapping the flow outlet hides checkout exactly as an
+    // ancestor block does, and its own part keys are its own markup.
+    const guardsCheckoutFlow = containsCheckoutFlowOutlet(section);
+    const sectionStyles = guardsCheckoutFlow
+      ? stripHidingStyles(section.styles, 'root-only')
+      : section.styles;
+
+    if (sectionStyles && Object.keys(sectionStyles).length > 0) {
       // Sections went straight to generateElementCSS, so a part key on a
       // section was emitted as the invalid declaration `dropdown/color:`.
-      const { root: sectionRoot } = splitPartStyles(section.styles);
+      const { root: sectionRoot } = splitPartStyles(sectionStyles);
 
       if (Object.keys(sectionRoot).length > 0) {
         css += generateElementCSS(
@@ -1196,17 +1233,19 @@ export const generateThemeCSS = (
 
       css += generatePartCSS(
         sectionSelector,
-        section.styles,
+        sectionStyles,
         targetBreakpoint
       );
     }
 
     if (section.properties) {
-      css += buildCustomCss(
+      const customCss = buildCustomCss(
         section.properties as Record<string, unknown>,
         sectionSelector,
         targetBreakpoint
       );
+
+      css += guardsCheckoutFlow ? stripHidingCustomCss(customCss) : customCss;
     }
 
     if (section.blocks && section.blocks.length > 0) {

package/src/utils/part-styles.ts

@@ -45,6 +45,10 @@ const STATE_SELECTORS: Record<string, string[]> = {
   ],
   checked: [':checked', '[data-state~="checked"]', '[aria-checked="true"]'],
   open: ['[data-state~="open"]', '[aria-expanded="true"]'],
+  // A finished step/section in a flow (checkout steps, wizard sections).
+  // data-state only, on purpose: no ARIA attribute honestly means "completed",
+  // so inventing an ARIA analog here would let unrelated markup match.
+  completed: ['[data-state~="completed"]'],
   invalid: ['[aria-invalid="true"]', '[data-state~="invalid"]'],
   loading: ['[data-state~="loading"]'],
   empty: ['[data-state~="empty"]'],

package/src/utils/visibility-rules.ts

@@ -1,6 +1,7 @@
 import { Block } from '../theme-block';
 import { Section } from '../theme-section';
 import { BREAKPOINT_FALLBACKS } from './breakpoints';
+import { containsCheckoutOutlet } from './checkout-safety';
 import { devWarn } from './dev-warn';
 
 export type VisibilityAuthState = 'all' | 'authenticated' | 'guest';
@@ -507,15 +508,38 @@ export const evaluateVisibilityRules = (
   return true;
 };
 
+/**
+ * Checkout outlets are exempt from visibility rules — theirs, and those of
+ * every block or section wrapping them.
+ *
+ * An outlet is not content, it is a POSITION: the piece it claims latches
+ * once, at page mount, and never re-targets. Both context inputs a rule reads
+ * are wrong at exactly that moment — `useSession()` still reports 'loading'
+ * on the first client render, and the breakpoint is initialised to 'desktop'
+ * before the resize effect corrects it — so a rule that is genuinely
+ * satisfied on the shopper's device still hides the outlet through that first
+ * render. The outlet then misses the latch, and because late registration on
+ * live is ignored by design, the composed placement stays dead for the whole
+ * page load while the designer canvas (which follows the live claim instead
+ * of latching) shows it working.
+ *
+ * Rather than race the latch, the outlet is kept mounted. Little is lost:
+ * conditional placement was never expressible anyway (a claim is
+ * breakpoint-unaware and permanent), the steps and summary outlets stay
+ * hideable through their Visibility style, and the editor drops the
+ * Visibility Rules box for these blocks so the panel tells the same story.
+ */
+const isVisibilityRuleExempt = (node: Block | Section): boolean =>
+  containsCheckoutOutlet(node);
+
 const applyBlockVisibility = (
   block: Block,
   context: VisibilityRuleContext
 ): Block => {
   const blocks = block.blocks?.map(child => applyBlockVisibility(child, context));
-  const isVisibleByRules = evaluateVisibilityRules(
-    block.properties?.visibilityRules,
-    context
-  );
+  const isVisibleByRules =
+    isVisibilityRuleExempt(block) ||
+    evaluateVisibilityRules(block.properties?.visibilityRules, context);
 
   return {
     ...block,
@@ -530,10 +554,9 @@ export const applyVisibilityRulesToSections = (
 ): Section[] =>
   sections.map(section => {
     const blocks = section.blocks.map(block => applyBlockVisibility(block, context));
-    const isVisibleByRules = evaluateVisibilityRules(
-      section.properties?.visibilityRules,
-      context
-    );
+    const isVisibleByRules =
+      isVisibilityRuleExempt(section) ||
+      evaluateVisibilityRules(section.properties?.visibilityRules, context);
 
     return {
       ...section,