@akinon/pz-theme 2.0.43 → 2.0.44

package/CHANGELOG.md

@@ -1,10 +1,17 @@
 # @akinon/pz-theme
 
+## 2.0.44
+
+### Patch Changes
+
+- @akinon/next@2.0.44
+- @akinon/theme-contract@2.0.44
+
 ## 2.0.43
 
 ### Patch Changes
 
-- 0e384d73: ZERO-4730: Make the checkout page composable with a checkout pieces bridge, outlet blocks and a body takeover region
+- 0e384d73c: ZERO-4730: Make the checkout page composable with a checkout pieces bridge, outlet blocks and a body takeover region
   - @akinon/next@2.0.43
   - @akinon/theme-contract@2.0.43
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.43",
+  "version": "2.0.44",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.43",
+    "@akinon/next": "2.0.44",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.43",
+    "@akinon/theme-contract": "2.0.44",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.43",
+    "@akinon/next": "2.0.44",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/checkout-slot-coverage.test.ts

@@ -0,0 +1,181 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * The checkout wiring carries invariants that live in the source text rather
+ * than in exported code:
+ *
+ * - the `checkout-page-body` slot must mount BEFORE the flow's subtree, so
+ *   outlet targets register in their `useLayoutEffect` before the flow's
+ *   mount latch runs (the teleport decision is made pre-first-paint);
+ * - no checkout slot may take `fallback={children}`, or a published
+ *   composition could REPLACE the payment flow instead of arranging it;
+ * - the body's takeover affordance sits on the flow itself, and exactly one
+ *   thing offers it — the slot's dashed band stands down for the region.
+ *
+ * They are checked against BOTH checkout layouts in the repo: the reference
+ * app and the CLI scaffold every new brand is generated from. The two must
+ * agree, because the route tables that decide which placeholder `/orders/
+ * checkout` composes (`route-slug.ts` here, `route-placeholder-scope.ts` in
+ * the editor) are global: the editor offers the four checkout templates on
+ * that route for EVERY brand. A scaffold that mounts no `checkout-page-body`
+ * slot would let a designer compose, publish, and watch the storefront render
+ * nothing — with the flow still claiming to be code-owned underneath.
+ *
+ * Like `account-slot-coverage`, this suite fs-reads the sources and skips
+ * whichever tree is not checked out next to the package.
+ */
+
+const REPO_ROOT = path.resolve(__dirname, '../../../..');
+
+const CHECKOUT_DIRS = {
+  'the reference app': path.join(
+    REPO_ROOT,
+    'apps/projectzeronext/src/app/[pz]/orders/checkout'
+  ),
+  'the CLI scaffold': path.join(
+    REPO_ROOT,
+    'packages/projectzero/app-template/src/app/[pz]/orders/checkout'
+  )
+};
+
+const countMatches = (source: string, pattern: RegExp) =>
+  (source.match(pattern) ?? []).length;
+
+describe.each(Object.entries(CHECKOUT_DIRS))(
+  'checkout slot coverage in %s',
+  (_name, checkoutDir) => {
+    const maybeIt = fs.existsSync(checkoutDir) ? it : it.skip;
+
+    const layoutPath = path.join(checkoutDir, 'layout.tsx');
+    const pagePath = path.join(checkoutDir, 'page.tsx');
+    const readLayout = () => fs.readFileSync(layoutPath, 'utf8');
+
+    maybeIt(
+      'mounts each of the four checkout zones exactly once in the layout',
+      () => {
+        const layout = readLayout();
+
+        // Counted per SLOT, not per slug mention: the body slug is named twice on
+        // purpose — once by its slot, once by the region that offers its takeover
+        // — while "one slot per zone" is the invariant that actually matters.
+        expect(countMatches(layout, /<ChromeSlot\b/g)).toBe(3);
+
+        (['checkoutTop', 'checkoutBody', 'checkoutBottom'] as const).forEach(
+          (key) => {
+          expect(
+            countMatches(
+              layout,
+              // `[^>]` spans newlines, so a prettier reflow of the props cannot
+              // break this.
+              new RegExp(
+                `<ChromeSlot[^>]*PLACEHOLDER_SLUGS\\.${key}\\b[^>]*>`,
+                'g'
+              )
+            )
+          ).toBe(1);
+        });
+      }
+    );
+
+    maybeIt('wraps the checkout subtree in the pieces provider', () => {
+      expect(readLayout()).toContain('CheckoutPiecesProvider');
+    });
+
+    maybeIt(
+      'mounts the body slot before the flow (pre-paint latch ordering)',
+      () => {
+        const layout = readLayout();
+        const bodyMountIndex = layout.indexOf('PLACEHOLDER_SLUGS.checkoutBody');
+        const flowIndex = layout.indexOf('<ComposableRegion');
+
+        expect(bodyMountIndex).toBeGreaterThan(-1);
+        expect(flowIndex).toBeGreaterThan(-1);
+        // Ordering is load-bearing: outlets must register before the flow's
+        // mount latch decides where the flow renders.
+        expect(bodyMountIndex).toBeLessThan(flowIndex);
+      }
+    );
+
+    maybeIt('never hands children to a slot as fallback', () => {
+      // A slot with `fallback={children}` would let a composition replace the
+      // payment flow instead of positioning it.
+      expect(readLayout()).not.toContain('fallback={children}');
+    });
+
+    maybeIt('wires the flow piece in the checkout page', () => {
+      // The flow-never-lost guarantee is enforced by the runtime piece wrapper —
+      // this pins that the page actually mounts it. Without it every outlet a
+      // composition places is a dead target: the editor happily accepts the
+      // composition and the flow never moves.
+      expect(fs.readFileSync(pagePath, 'utf8')).toContain('piece="flow"');
+    });
+
+    maybeIt(
+      'gives the checkout body a takeover affordance instead of an empty-zone band',
+      () => {
+        // The point of the region: the designer hovers the REAL checkout content
+        // and gets the same "Edit in theme editor" affordance every other page
+        // has, rather than a dashed band floating above content that answers a
+        // hover with nothing.
+        const layout = readLayout();
+
+        const regionOpen = layout.indexOf('<ComposableRegion');
+        const regionClose = layout.indexOf('</ComposableRegion>');
+        const childrenIndex = layout.indexOf('{children}');
+
+        expect(regionOpen).toBeGreaterThan(-1);
+        expect(regionClose).toBeGreaterThan(-1);
+        // The region takes the live flow, not a copy of it.
+        expect(childrenIndex).toBeGreaterThan(regionOpen);
+        expect(childrenIndex).toBeLessThan(regionClose);
+        expect(layout).toMatch(
+          /<ComposableRegion[^>]*slug=\{PLACEHOLDER_SLUGS\.checkoutBody\}/
+        );
+
+        // One slug, one CTA: the slot's own band steps aside for it.
+        expect(layout).toMatch(
+          /<ChromeSlot[^>]*PLACEHOLDER_SLUGS\.checkoutBody\b[^>]*emptyZoneBand=\{false\}[^>]*>/
+        );
+      }
+    );
+
+    maybeIt(
+      'keeps the dashed band on the two zones that have no live content',
+      () => {
+        // Nothing else renders in those zones, so removing their band would make
+        // them undiscoverable again — the exact problem the band exists for.
+        const layout = readLayout();
+
+        (['checkoutTop', 'checkoutBottom'] as const).forEach(
+          (key) => {
+            const slot = layout.match(
+              new RegExp(`<ChromeSlot[^>]*PLACEHOLDER_SLUGS\\.${key}\\b[^>]*>`)
+            );
+
+            expect(slot).not.toBeNull();
+            expect(slot![0]).not.toContain('emptyZoneBand');
+          }
+        );
+      }
+    );
+
+    maybeIt(
+      'no longer tells the designer the checkout body cannot be composed',
+      () => {
+        // The code-owned explainer said the flow "cannot be composed — use the
+        // zones above and below it". The body is composable now, so that sentence
+        // must not survive anywhere in this layout.
+        expect(readLayout()).not.toContain('CodeOwnedRegion');
+      }
+    );
+
+    maybeIt('explains the area it makes inert once it is composed', () => {
+      // The canvas click guard is keyed on being in the designer, not on the
+      // area being uncomposed. A composition that places no flow outlet leaves
+      // the real checkout visible and unclickable, so the region has to keep
+      // saying why.
+      expect(readLayout()).toMatch(/<ComposableRegion[^>]*composedNote=/);
+    });
+  }
+);

package/src/blocks/__tests__/checkout-hosted-parts.test.ts

@@ -0,0 +1,203 @@
+import fs from 'fs';
+import path from 'path';
+
+/**
+ * The checkout outlet blocks style parts they do not render: the code-owned
+ * checkout teleports its markup into them, and each outlet declares the parts
+ * it HOSTS via an exported `HOSTED_PARTS` literal that the editor's
+ * descriptor conformance also reads. A manifest nobody stamps would put dead
+ * entries in the editor panel; a stamp nobody declares would be unstylable —
+ * this suite keeps declaration and reality pointing at each other:
+ *
+ * - every manifest name is stamped (`partAttrs('…')`) somewhere in the app's
+ *   checkout views;
+ * - every stamped name is declared by at least one outlet manifest
+ *   (`summary-*` legitimately by two: the mobile summary sheet re-renders the
+ *   summary inside the flow subtree, and part rules are block-scoped);
+ * - the full vocabulary is pinned inline, so a rename fails loudly here
+ *   before it silently orphans published compositions;
+ * - stamps are INERT (I4): `partAttrs` is the only stamping route, and no
+ *   live runtime — app or pz-theme outside designer-only modules — queries
+ *   `[data-part` from the DOM.
+ */
+
+const repoRoot = path.resolve(__dirname, '../../../../..');
+const blocksDir = path.resolve(__dirname, '..');
+const pzThemeSrcDir = path.resolve(__dirname, '../..');
+const appSrcDir = path.join(repoRoot, 'apps', 'projectzeronext', 'src');
+const appCheckoutDir = path.join(appSrcDir, 'views', 'checkout');
+
+const OUTLET_MANIFEST_FILES = [
+  'checkout-flow-outlet-block.tsx',
+  'checkout-steps-outlet-block.tsx',
+  'checkout-summary-outlet-block.tsx'
+];
+
+/**
+ * The reserved checkout part vocabulary. Changing it is a contract change:
+ * update the outlet manifests, the app stamps, the editor part groups AND
+ * this pin together — published compositions reference these names.
+ */
+const RESERVED_PART_NAMES = [
+  'agreement',
+  'continue-button',
+  'edit-button',
+  'payment-option',
+  'payment-option-icon',
+  'payment-options',
+  'payment-panel',
+  'place-order-button',
+  'section',
+  'section-header',
+  'section-number',
+  'section-title',
+  'step',
+  'step-icon',
+  'step-label',
+  'step-number',
+  'steps',
+  'summary',
+  'summary-edit',
+  'summary-header',
+  'summary-item',
+  'summary-row',
+  'summary-row-label',
+  'summary-row-value',
+  'summary-title',
+  'summary-total',
+  'summary-total-label',
+  'summary-total-value'
+];
+
+const PART_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+const readManifest = (fileName: string): string[] => {
+  const source = fs.readFileSync(path.join(blocksDir, fileName), 'utf8');
+  const hosted = /HOSTED_PARTS\s*(?::[^=]*)?=\s*\[([\s\S]*?)\]/.exec(source);
+  if (!hosted) return [];
+
+  return Array.from(hosted[1].matchAll(/'([^']+)'/g), (match) => match[1]);
+};
+
+const walkSources = (dir: string): string[] => {
+  const files: string[] = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules') continue;
+      files.push(...walkSources(full));
+    } else if (/\.(ts|tsx)$/.test(entry.name)) {
+      files.push(full);
+    }
+  }
+
+  return files;
+};
+
+const isTestFile = (file: string): boolean =>
+  /__tests__/.test(file) || /\.test\.(ts|tsx)$/.test(file);
+
+const manifests = Object.fromEntries(
+  OUTLET_MANIFEST_FILES.map((file) => [file, readManifest(file)])
+) as Record<string, string[]>;
+
+const manifestNames = new Set(Object.values(manifests).flat());
+
+// Runtime sources only. A test may legitimately write a part name into a
+// string template or assert on a raw attribute; what this suite pins is what
+// the SHIPPED checkout markup stamps.
+const checkoutSources = walkSources(appCheckoutDir)
+  .filter((file) => !isTestFile(file))
+  .map((file) => ({
+    file: path.relative(repoRoot, file),
+    source: fs.readFileSync(file, 'utf8')
+  }));
+
+const stampedNames = new Set(
+  checkoutSources.flatMap(({ source }) =>
+    Array.from(source.matchAll(/partAttrs\(\s*'([^']+)'/g), (m) => m[1])
+  )
+);
+
+describe('checkout hosted-parts manifests', () => {
+  it('finds a non-empty HOSTED_PARTS literal in each outlet block', () => {
+    for (const file of OUTLET_MANIFEST_FILES) {
+      expect(manifests[file].length).toBeGreaterThan(0);
+    }
+  });
+
+  it('uses only well-formed kebab-case part names, everywhere', () => {
+    for (const name of [
+      ...Array.from(manifestNames),
+      ...Array.from(stampedNames)
+    ]) {
+      expect(name).toMatch(PART_NAME_PATTERN);
+    }
+  });
+
+  it('pins the full reserved vocabulary — renames fail loudly', () => {
+    expect(Array.from(manifestNames).sort()).toEqual(RESERVED_PART_NAMES);
+  });
+
+  it('declares every stamped part in at least one outlet manifest', () => {
+    const undeclared = Array.from(stampedNames).filter(
+      (name) => !manifestNames.has(name)
+    );
+
+    expect(undeclared).toEqual([]);
+  });
+
+  it('stamps every declared part at least once in the checkout views', () => {
+    const unstamped = Array.from(manifestNames).filter(
+      (name) => !stampedNames.has(name)
+    );
+
+    expect(unstamped).toEqual([]);
+  });
+});
+
+describe('checkout part stamps are inert (I4)', () => {
+  it('routes every app stamp through partAttrs — no raw data-part attribute', () => {
+    const offenders = checkoutSources
+      .filter(({ source }) => source.includes('data-part='))
+      .map(({ file }) => file);
+
+    expect(offenders).toEqual([]);
+  });
+
+  // The attributes are a styling contract, not a runtime signal: nothing on
+  // the live path may branch on them. Designer-only modules (the queries are
+  // gated behind the editor-proven designer flag) are the sole exemption.
+  const DESIGNER_ONLY_PZ_THEME_FILES = [
+    path.join('hooks', 'use-designer-features.tsx'),
+    path.join('components', 'part-state-preview.tsx'),
+    path.join('blocks', 'checkout-outlet-base.tsx')
+  ];
+
+  const PART_QUERY_PATTERN =
+    /(?:querySelectorAll|querySelector|closest|matches)\s*(?:<[^>\n]*>)?\s*\(\s*[`'"]\[data-part/;
+
+  it('never queries [data-part from the app runtime', () => {
+    const offenders = walkSources(appSrcDir)
+      .filter((file) => !isTestFile(file))
+      .filter((file) => PART_QUERY_PATTERN.test(fs.readFileSync(file, 'utf8')))
+      .map((file) => path.relative(repoRoot, file));
+
+    expect(offenders).toEqual([]);
+  });
+
+  it('never queries [data-part from pz-theme outside designer-only modules', () => {
+    const offenders = walkSources(pzThemeSrcDir)
+      .filter((file) => !isTestFile(file))
+      .filter((file) => {
+        const relative = path.relative(pzThemeSrcDir, file);
+        return !DESIGNER_ONLY_PZ_THEME_FILES.includes(relative);
+      })
+      .filter((file) => PART_QUERY_PATTERN.test(fs.readFileSync(file, 'utf8')))
+      .map((file) => path.relative(repoRoot, file));
+
+    expect(offenders).toEqual([]);
+  });
+});