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

package/CHANGELOG.md

@@ -1,36 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.46-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea23]
-- Updated dependencies [324f97d5]
-- Updated dependencies [51ea0688]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08f]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f4]
-- Updated dependencies [57d7eb30]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a71]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d0]
-- Updated dependencies [4ac7b2a1]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a963]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b2]
-  - @akinon/next@2.0.46-rc.0
-  - @akinon/theme-contract@2.0.46-rc.0
+## 2.0.46
+
+### Patch Changes
+
+- fa20bf7: ZERO-4738: Emit part-scoped custom CSS rules from the part style panel
+  - @akinon/next@2.0.46
+  - @akinon/theme-contract@2.0.46
 
 ## 2.0.45
 

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.46-rc.0",
+  "version": "2.0.46",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.46-rc.0",
+    "@akinon/next": "2.0.46",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.46-rc.0",
+    "@akinon/theme-contract": "2.0.46",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.46-rc.0",
+    "@akinon/next": "2.0.46",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/custom-css.test.ts

@@ -179,3 +179,118 @@ describe('custom CSS across breakpoints', () => {
     expect(css).toContain('animation: pz-spin');
   });
 });
+
+/**
+ * The same hatch, scoped to one part instead of the whole block.
+ *
+ * A designer working inside a part previously had to climb back out to the
+ * block panel and write `& [data-part="x"] { … }` there, which also meant the
+ * two panels shared one value. `customCss/<part>` gives the part its own.
+ */
+describe('part-scoped custom CSS', () => {
+  const PART_SCOPE =
+    '[data-block-id="blk-1"] [data-part="dropdown"]:not(:where([data-block-id="blk-1"] [data-block-id] *))';
+
+  const sectionWithPartCustomCss = (
+    properties: Record<string, unknown>
+  ): Section[] =>
+    [
+      {
+        id: 'sec-1',
+        type: 'custom',
+        name: 'Section',
+        label: 'Section',
+        order: 0,
+        hidden: false,
+        properties: {},
+        styles: {},
+        blocks: [
+          {
+            id: 'blk-1',
+            type: 'variant-selector',
+            label: 'Variant selector',
+            order: 0,
+            hidden: false,
+            value: '',
+            properties,
+            styles: {},
+            blocks: []
+          }
+        ]
+      }
+    ] as unknown as Section[];
+
+  it('scopes the part hatch to the part, ownership guard included', () => {
+    const css = generateThemeCSS(
+      sectionWithPartCustomCss({
+        'customCss/dropdown': '& { clip-path: inset(0 0 20% 0); }'
+      })
+    );
+
+    expect(css).toContain(`${PART_SCOPE} {`);
+    expect(css).toContain('clip-path: inset(0 0 20% 0)');
+  });
+
+  it('wraps a bare declaration in the part scope', () => {
+    const css = generateThemeCSS(
+      sectionWithPartCustomCss({ 'customCss/dropdown': 'color: red;' })
+    );
+
+    expect(css).toContain(`${PART_SCOPE} {`);
+    expect(css).toContain('color: red');
+  });
+
+  it('adds no !important and passes a typed one through', () => {
+    // Part CONTROLS are forced !important; the hatch is not, exactly as at
+    // block level — typing it is how a designer beats an inline default.
+    const css = generateThemeCSS(
+      sectionWithPartCustomCss({
+        'customCss/dropdown': '& { color: red; border: 0 !important; }'
+      })
+    );
+
+    expect(css).toContain('color: red;');
+    expect(css).not.toContain('color: red !important');
+    expect(css).toContain('border: 0 !important');
+  });
+
+  it('emits the narrower bucket inside the mobile media query', () => {
+    const css = generateThemeCSS(
+      sectionWithPartCustomCss({
+        'customCss/dropdown': {
+          desktop: '& { gap: 24px; }',
+          mobile: '& { gap: 8px; }'
+        }
+      })
+    );
+
+    expect(css).toContain('gap: 24px');
+    expect(css).toContain('@media (max-width: 1023px)');
+    expect(css).toContain('gap: 8px');
+  });
+
+  it('drops a part name that could break out of the selector', () => {
+    const css = generateThemeCSS(
+      sectionWithPartCustomCss({ 'customCss/../evil': '& { color: red; }' })
+    );
+
+    // The sanitiser strips everything but [A-Za-z0-9_-], so the name survives
+    // only as `evil` — what must never appear is an unscoped or escaped rule.
+    expect(css).not.toContain('../evil');
+    expect(css).not.toContain('"] [data-part=".."');
+  });
+
+  it('leaves the block-level hatch alone', () => {
+    const css = generateThemeCSS(
+      sectionWithPartCustomCss({
+        customCss: '& { padding: 4px; }',
+        'customCss/dropdown': '& { padding: 8px; }'
+      })
+    );
+
+    expect(css).toContain(`${SCOPE} {`);
+    expect(css).toContain('padding: 4px');
+    expect(css).toContain(`${PART_SCOPE} {`);
+    expect(css).toContain('padding: 8px');
+  });
+});

package/src/__tests__/part-style-scope.test.tsx

@@ -53,12 +53,17 @@ const text = (id: string) => ({
   hidden: false
 });
 
-const accordion = (id: string, styles: Record<string, unknown>, inner?: unknown) => ({
+const accordion = (
+  id: string,
+  styles: Record<string, unknown>,
+  inner?: unknown,
+  properties: Record<string, unknown> = {}
+) => ({
   id,
   type: 'accordion',
   label: 'Accordion',
   value: '',
-  properties: { defaultOpen: true },
+  properties: { defaultOpen: true, ...properties },
   styles,
   order: 0,
   hidden: false,
@@ -69,10 +74,15 @@ const accordion = (id: string, styles: Record<string, unknown>, inner?: unknown)
 });
 
 /** The outer accordion carries the styles; the inner one carries the same parts. */
-const composition = (styles: Record<string, unknown>) =>
-  accordion('outer', styles, accordion('inner', {}));
-
-const sectionWith = (styles: Record<string, unknown>): Section[] =>
+const composition = (
+  styles: Record<string, unknown>,
+  properties: Record<string, unknown> = {}
+) => accordion('outer', styles, accordion('inner', {}), properties);
+
+const sectionWith = (
+  styles: Record<string, unknown>,
+  properties: Record<string, unknown> = {}
+): Section[] =>
   [
     {
       id: 'sec-1',
@@ -83,7 +93,7 @@ const sectionWith = (styles: Record<string, unknown>): Section[] =>
       hidden: false,
       properties: {},
       styles: {},
-      blocks: [composition(styles)]
+      blocks: [composition(styles, properties)]
     }
   ] as unknown as Section[];
 
@@ -227,3 +237,19 @@ describe('the selector shape published compositions already rely on', () => {
     });
   });
 });
+
+describe('the part-scoped hatch is confined exactly as a part control is', () => {
+  it('does not reach the nested block that names its header the same way', () => {
+    // The hatch inherits buildPartSelectors, so it inherits the ownership
+    // guard. Written as a real composition because that is where the leak
+    // the guard exists for actually appears.
+    const css = generateThemeCSS(
+      sectionWith({}, { 'customCss/header': '& { color: red; }' })
+    );
+    const { container } = renderComposition({});
+    const selectors = selectorsFor(css, 'header');
+
+    expect(selectors.length).toBeGreaterThan(0);
+    expect(matchIds(container, selectors)).toEqual(['outer']);
+  });
+});

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

@@ -266,6 +266,39 @@ describe('generateThemeCSS — checkout flow can never be hidden', () => {
     expect(ancestorCss).not.toContain('visibility: hidden');
   });
 
+  it('closes the PART-scoped hatch on the outlet and on an ancestor', () => {
+    // The part hatch is a second free-form channel into the same stylesheet,
+    // so it has to be filtered on its generated text exactly as the block
+    // hatch is — otherwise the outlet gained a way to hide itself the day the
+    // part panel got its own box.
+    const outletCss = generateThemeCSS(
+      section([
+        flowOutlet({
+          properties: {
+            'customCss/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/panel': '& { visibility: hidden }' },
+          blocks: [flowOutlet()]
+        }
+      ])
+    );
+
+    expect(ancestorCss).not.toContain('visibility: hidden');
+  });
+
   it('leaves an unrelated block free to hide itself', () => {
     const css = generateThemeCSS(
       section([

package/src/utils/custom-css.ts

@@ -16,6 +16,7 @@
  */
 
 import { MOBILE_MEDIA_QUERY, TABLET_MEDIA_QUERY } from './breakpoints';
+import { buildPartScopeSelector } from './part-styles';
 
 /** Nothing here is a legitimate need in a block's scoped CSS, and each is a way out of it. */
 const FORBIDDEN = [
@@ -231,3 +232,44 @@ export const buildCustomCss = (
 
   return css;
 };
+
+/** A property key of the form `customCss/<part>` carries a part-scoped hatch. */
+export const PART_CUSTOM_CSS_PREFIX = 'customCss/';
+
+/**
+ * The hatch, one level in.
+ *
+ * The block hatch reaches a part already (`& [data-part="x"] { … }`), but only
+ * from the block's own box — so a designer working inside a part had to climb
+ * back out to the block panel, and both boxes wrote the one `customCss` value,
+ * where either could silently overwrite the other. A `customCss/<part>`
+ * property is scoped to that part's selector instead, ownership guard
+ * included, so it is confined exactly as a part control is.
+ *
+ * No `!important` is added, exactly as at block level: a hand-typed one passes
+ * through, which is the documented way to beat a renderer's inline default.
+ */
+export const buildPartCustomCss = (
+  properties: Record<string, unknown> | undefined | null,
+  blockSelector: string,
+  targetBreakpoint?: string
+): string => {
+  let css = '';
+
+  Object.entries(properties || {}).forEach(([key, value]) => {
+    if (!key.startsWith(PART_CUSTOM_CSS_PREFIX)) return;
+
+    const scope = buildPartScopeSelector(
+      blockSelector,
+      key.slice(PART_CUSTOM_CSS_PREFIX.length)
+    );
+    if (!scope) return;
+
+    // The synthetic bag reuses the whole block-level path: the forbidden
+    // patterns, the brace balance, the responsive fall-through and the
+    // media-query emission all behave as they do for the block hatch.
+    css += buildCustomCss({ customCss: value }, scope, targetBreakpoint);
+  });
+
+  return css;
+};

package/src/utils/index.ts

@@ -6,7 +6,7 @@ import {
   escapeCssAttributeValue
 } from './css-safety';
 import { buildPartSelectors, splitPartStyles } from './part-styles';
-import { buildCustomCss } from './custom-css';
+import { buildCustomCss, buildPartCustomCss } from './custom-css';
 import {
   CHECKOUT_FLOW_OUTLET_TYPE,
   containsCheckoutFlowOutlet,
@@ -1211,6 +1211,19 @@ const collectBlockCSS = (
       );
 
       css += guardsCheckoutFlow ? stripHidingCustomCss(customCss) : customCss;
+
+      // After the part RULES on purpose: same selector, same specificity, so
+      // source order settles a tie and a hand-written `!important` in the
+      // hatch is the designer's way to beat the generated part rule.
+      const partCustomCss = buildPartCustomCss(
+        block.properties as Record<string, unknown>,
+        selector,
+        targetBreakpoint
+      );
+
+      css += guardsCheckoutFlow
+        ? stripHidingCustomCss(partCustomCss)
+        : partCustomCss;
     }
 
     if (block.blocks && block.blocks.length > 0) {
@@ -1260,6 +1273,9 @@ export const generateThemeCSS = (
     }
 
     if (section.properties) {
+      // No part hatch here on purpose: no editor surface writes
+      // `customCss/<part>` on a section — the part panel opens on a selected
+      // BLOCK — so the asymmetry is intentional, not an omission.
       const customCss = buildCustomCss(
         section.properties as Record<string, unknown>,
         sectionSelector,

package/src/utils/part-styles.ts

@@ -231,3 +231,17 @@ export const buildPartSelectors = (
 
   return suffixes.map((suffix) => `${base}${suffix}${owned}`);
 };
+
+/**
+ * The scope a part-scoped custom CSS block is written against.
+ *
+ * It is the part's own base selector, ownership guard included, so the hatch
+ * can no more leak into a nested block than a part control can — the sanitiser
+ * and the guard are reused verbatim rather than re-derived.
+ */
+export const buildPartScopeSelector = (
+  blockSelector: string,
+  part: string
+): string | null =>
+  buildPartSelectors(blockSelector, { part, state: null, styles: {} })[0] ??
+  null;