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

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.92-beta.0
+## 2.0.92
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.92-beta.0
-  - @akinon/theme-contract@2.0.92-beta.0
+- abd46ed1: ZERO-4997: Let an open overlay outrank the scrolled state
+  - @akinon/next@2.0.92
+  - @akinon/theme-contract@2.0.92
 
 ## 2.0.91
 

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

package/src/utils/__tests__/docked-state-styles.test.ts

@@ -24,12 +24,20 @@ import type { Section } from '../../theme-section';
  * ON AN INNER PAGE BOTH STATES MATCH AT ONCE. The shopper scrolls a docked
  * header, so `[data-scroll-state~="scrolled"]` and `body[data-chrome-mode~=
  * "docked"]` are both true of the same band, and both rules set the same
- * property. Every other ancestor-matched state weighs (0,2,0) against an
- * element selector; the `body` makes this one (0,2,1), so the mode wins on
- * specificity rather than on whichever rule the generator happened to write
- * last. That is the right answer and not merely a chosen one: `scrolled`
- * describes how far the page has slid under a bar that floats over it, and once
- * the bar is docked the question has no meaning.
+ * property. Unqualified they would both weigh (0,2,0) against an element
+ * selector; the `body` makes this one (0,2,1), so the mode wins on specificity
+ * rather than on whichever rule the generator happened to write last. That is
+ * the right answer and not merely a chosen one: `scrolled` describes how far
+ * the page has slid under a bar that floats over it, and once the bar is docked
+ * the question has no meaning.
+ *
+ * `overlay-open` CARRIES THE SAME QUALIFIER, for the same reason and against
+ * the same opponent (ZERO-4997; see scrolled-state-styles.test.ts). So the
+ * ladder reads: `scrolled` at (0,2,0) on the bottom, unable to leave it because
+ * its attribute is not on `body`, and these two above it at (0,2,1) — TIED with
+ * each other, which means a docked header with an open panel is still settled
+ * by emission order. Nothing here asserts that pair; there is no right answer
+ * to assert yet.
  *
  * WHY THERE IS NO `getComputedStyle` TEST BELOW, and why adding one would make
  * this file worse: jsdom has no cascade worth the name. Its `getComputedStyle`
@@ -89,7 +97,7 @@ afterEach(() => {
 });
 
 describe('the `body` qualifier is load-bearing — do not tidy it away', () => {
-  it('keeps `body` in the docked selector, which is the only thing that outranks scrolled', () => {
+  it('keeps `body` in the docked selector, which is the only thing outranking scrolled here', () => {
     const [selector] = buildRootStateSelectors(SECTION, 'docked');
 
     // Asserted as literal text, because the qualifier reads like a redundant

package/src/utils/__tests__/scrolled-state-styles.test.ts

@@ -3,6 +3,7 @@ import { stripHidingStyles } from '../checkout-safety';
 import {
   buildPartSelectors,
   buildRootStateKey,
+  buildRootStateSelectors,
   parseRootStateKey,
   splitPartStyles
 } from '../part-styles';
@@ -210,7 +211,8 @@ describe('checkout safety', () => {
 });
 
 describe('the overlay-open state', () => {
-  const OPEN = '[data-overlay-state~="open"]';
+  // Carries `body` deliberately; the block at the end of this file is why.
+  const OPEN = 'body[data-overlay-state~="open"]';
 
   it('conditions a part on the page, exactly as scrolled does', () => {
     const [selector] = buildPartSelectors('[data-block-id="blk-1"]', {
@@ -259,3 +261,213 @@ describe('the overlay-open state', () => {
     expect(document.querySelectorAll(selector)).toHaveLength(0);
   });
 });
+
+/**
+ * `overlay-open` outranking `scrolled`, which is the whole point of the `body`
+ * in its selector.
+ *
+ * THE BUG IT CLOSES, reported from a live storefront: scroll the home page far
+ * enough that the header takes its scrolled paint, THEN open the mega menu, and
+ * the band stays scroll-dark. Open the menu without scrolling first and it
+ * turns white. Both states are true of the same band at the same moment and
+ * both set the same property, so one has to lose — and unqualified both weigh
+ * (0,2,0), which left the winner to whichever rule the generator wrote last.
+ * That order is not a decision made in this package: root states are bucketed
+ * as `splitPartStyles` iterates the style object, so it is the order the state
+ * keys happen to sit in the merchant's stored composition JSON.
+ *
+ * WHAT IS ASSERTED, THEREFORE, IS THE RELATIONSHIP AND NOT THE STRING: that the
+ * overlay colour is the one a browser would paint, with the keys stored in BOTH
+ * orders. A test that only checked the selector text would go green again the
+ * moment someone re-derived the same tie a different way, and a test that only
+ * used the failing order could not tell a fix from a lucky emission.
+ *
+ * WHY NOT `getComputedStyle`: jsdom has no cascade worth the name — it resolves
+ * competing rules by source order alone and ignores specificity entirely (this
+ * was measured; see docked-state-styles.test.ts). A cascade test here would
+ * assert the opposite of a browser, pass today for the wrong reason, and keep
+ * passing after someone deleted the qualifier it exists to protect.
+ */
+describe('an open overlay outranks the scrolled state', () => {
+  const SECTION = '[data-section-id="sec-1"]';
+  const OPEN_WHITE = 'rgba(255, 255, 255, 1)';
+  const SCROLLED_GREY = 'rgba(245, 245, 245, 1)';
+
+  // Read back out of the table rather than retyped. Only the first case below
+  // asserts the selector as text; everything after it is about the relationship
+  // between the two, and retyping either one would quietly turn those cases
+  // into assertions about this file instead of about the table.
+  const overlaySelector = () =>
+    buildRootStateSelectors(SECTION, 'overlay-open')[0];
+  const scrolledSelector = () =>
+    buildRootStateSelectors(SECTION, 'scrolled')[0];
+
+  /**
+   * Weighs the two selectors this block is about, and nothing else.
+   *
+   * Naive on purpose — it counts attribute selectors and leading type
+   * selectors, which is all either selector contains. A general specificity
+   * parser would be a second implementation to get wrong, and the honest
+   * alternative, asking the DOM, does not exist here.
+   */
+  const weigh = (selector: string) => ({
+    attributes: (selector.match(/\[/g) || []).length,
+    types: (selector.match(/(^|[\s>+~])[a-z][a-z0-9-]*/g) || []).length
+  });
+
+  const declaredBackground = (css: string, selector: string) => {
+    const at = css.indexOf(`${selector} {`);
+    if (at === -1) return null;
+
+    const rule = css.slice(at, css.indexOf('}', at));
+    const declaration = rule.match(/background-color: ([^;]+);/);
+
+    return declaration ? declaration[1] : null;
+  };
+
+  /**
+   * Which of the two competing declarations a browser would actually paint.
+   *
+   * A mini-cascade, and honest about being one: the heavier selector wins, and
+   * a TIE falls to whichever rule was written last. Modelling the tie-break is
+   * not decoration — without it, a build where the `body` had been deleted
+   * would still come out white in the overlay-last order below, and the pair of
+   * cases would stop proving order-independence.
+   */
+  const painted = (css: string) => {
+    const overlay = overlaySelector();
+    const scrolled = scrolledSelector();
+
+    if (weigh(overlay).types !== weigh(scrolled).types) {
+      return declaredBackground(
+        css,
+        weigh(overlay).types > weigh(scrolled).types ? overlay : scrolled
+      );
+    }
+
+    return declaredBackground(
+      css,
+      css.indexOf(`${overlay} {`) > css.indexOf(`${scrolled} {`)
+        ? overlay
+        : scrolled
+    );
+  };
+
+  const band = (styles: Record<string, unknown>) =>
+    generateThemeCSS([section('sec-1', styles)]);
+
+  it('keeps `body` in the overlay selector, which is the entire tie-break', () => {
+    // The one literal assertion here, because the qualifier reads like a
+    // redundant ancestor to anyone who has not read why it is there.
+    expect(overlaySelector()).toBe(
+      `body[data-overlay-state~="open"] ${SECTION}`
+    );
+  });
+
+  it('outweighs the scrolled selector, which it ties with on attributes alone', () => {
+    // Same attribute count: this is the tie, and it is why order would decide.
+    expect(weigh(overlaySelector()).attributes).toBe(
+      weigh(scrolledSelector()).attributes
+    );
+    // The type selector is the entire margin of victory.
+    expect(weigh(overlaySelector()).types).toBeGreaterThan(
+      weigh(scrolledSelector()).types
+    );
+  });
+
+  it('paints the overlay colour with the SCROLLED key stored last', () => {
+    // The order that failed in production: scrolled is emitted after overlay,
+    // so nothing about the emission is saving this — only the weight is.
+    const css = band({
+      'background-color': 'transparent',
+      ':overlay-open/background-color': '#ffffff',
+      ':scrolled/background-color': '#f5f5f5'
+    });
+
+    expect(css.indexOf(`${scrolledSelector()} {`)).toBeGreaterThan(
+      css.indexOf(`${overlaySelector()} {`)
+    );
+    expect(painted(css)).toBe(OPEN_WHITE);
+  });
+
+  it('paints the overlay colour with the OVERLAY key stored last too', () => {
+    // The mirror case, which a merchant reaches simply by editing the two
+    // controls in the other order. Same answer — which is what makes the pair
+    // proof rather than luck. On a build with the `body` deleted THIS case
+    // still comes out white, because emission order happens to favour the
+    // overlay here; only the case above turns red. Keep both, or the next
+    // reader has no way to tell a fix from a fortunate order.
+    const css = band({
+      'background-color': 'transparent',
+      ':scrolled/background-color': '#f5f5f5',
+      ':overlay-open/background-color': '#ffffff'
+    });
+
+    expect(css.indexOf(`${overlaySelector()} {`)).toBeGreaterThan(
+      css.indexOf(`${scrolledSelector()} {`)
+    );
+    expect(painted(css)).toBe(OPEN_WHITE);
+  });
+
+  it('still emits the scrolled rule, which the shopper sees before opening', () => {
+    // The overlay only outranks it WHILE a panel is open. Losing the scrolled
+    // rule entirely would be the opposite bug, and just as visible.
+    const css = band({
+      ':scrolled/background-color': '#f5f5f5',
+      ':overlay-open/background-color': '#ffffff'
+    });
+
+    expect(declaredBackground(css, scrolledSelector())).toBe(SCROLLED_GREY);
+  });
+
+  it('matches the same band as scrolled at once, so the tie is real', () => {
+    // Not hypothetical: this is the reported sequence — the page is scrolled
+    // and the panel is open, so both rules target one element and one property.
+    document.body.setAttribute('data-overlay-state', 'open');
+    document.body.innerHTML =
+      '<div data-chrome-slot="header" data-scroll-state="scrolled">' +
+      '<div data-section-id="sec-1"></div>' +
+      '</div>';
+
+    expect(document.querySelectorAll(overlaySelector())).toHaveLength(1);
+    expect(document.querySelectorAll(scrolledSelector())).toHaveLength(1);
+
+    document.body.removeAttribute('data-overlay-state');
+  });
+
+  it('matches nothing when no panel is open, so scrolled keeps the band', () => {
+    // Every composition that styled only `scrolled` has to render as it did.
+    document.body.removeAttribute('data-overlay-state');
+    document.body.innerHTML = '<div data-section-id="sec-1"></div>';
+
+    expect(document.querySelectorAll(overlaySelector())).toHaveLength(0);
+  });
+
+  /**
+   * THE OTHER HALF OF THE BUMP, pinned because it is a bargain rather than a
+   * free win. A page state already composes an ancestor selector on top of
+   * whatever an element-matched state weighs, so `overlay-open` and `hover` on
+   * one part used to TIE — order-dependent, i.e. a coin-flip. The qualifier
+   * settles it in the page state's favour, which is the same bargain `docked`
+   * has always made. The visible cost is a header link that stops answering the
+   * pointer while the panel is open, and it is asserted here so nobody
+   * rediscovers it as a bug.
+   */
+  it('outranks an element-matched state on the same part', () => {
+    const partSelector = (state: string) =>
+      buildPartSelectors('[data-block-id="blk-1"]', {
+        part: 'navLink',
+        state,
+        styles: {}
+      })[0];
+
+    const overlayPart = partSelector('overlay-open');
+    const hoverPart = partSelector('hover');
+
+    // The page state carries one ancestor selector the element state does not,
+    // and the `body` qualifier adds the type selector on top of it.
+    expect(overlayPart).toContain('body[data-overlay-state~="open"]');
+    expect(hoverPart).not.toContain('body[');
+    expect(hoverPart).toContain(':hover');
+  });
+});

package/src/utils/part-styles.ts

@@ -80,26 +80,81 @@ const STATE_SELECTORS: Record<string, string[]> = {
   // through an ancestor and no renderer has to stamp anything for them to
   // apply. That is what lets a header become opaque on scroll, which nothing in
   // a composition could previously say.
+  //
+  // THIS ONE IS THE BOTTOM RUNG of the page-state ladder, at (0,2,0), and it is
+  // left there on purpose. It COULD be lifted today — `chrome/scroll-state.tsx`
+  // only ever stamps the attribute on `div` elements, so `div[…] &` would be
+  // accurate this afternoon. It is not done because that pins the chrome slot's
+  // TAG NAME, which the slot is free to change and which nothing would fail
+  // loudly about; `body` is guaranteed by the document. Both states below
+  // deliberately outrank it — read them for why that is the right way round and
+  // not an accident.
   scrolled: ['[data-scroll-state~="scrolled"] &'],
-  // The same trick for the other half of that header: transparent over the
-  // hero, opaque while its menu panel is open. The panel cannot express it —
-  // the header is not inside the panel — and the header cannot know it without
-  // the page saying so.
-  'overlay-open': ['[data-overlay-state~="open"] &'],
+  /**
+   * The same trick for the other half of that header: transparent over the
+   * hero, opaque while its menu panel is open. The panel cannot express it —
+   * the header is not inside the panel — and the header cannot know it without
+   * the page saying so.
+   *
+   * THE `body` QUALIFIER IS A DELIBERATE SPECIFICITY BUMP, not tidiness — the
+   * same bump `docked` carries below, added for the same reason. A shopper who
+   * scrolls the home page and THEN opens the mega menu satisfies `scrolled` and
+   * `overlay-open` at once, on the same band, for the same property. Left
+   * unqualified both weigh (0,2,0), so the winner is whichever rule the
+   * generator emitted last — and that order is nobody's decision: root states
+   * are bucketed in iteration order, so it is the order the state keys happen
+   * to sit in the merchant's stored composition JSON. Reported as a header that
+   * stays scroll-dark behind an open menu, but only if you scrolled first.
+   * `body` makes this (0,2,1), which beats `scrolled` whatever that order is.
+   * The qualifier is accurate rather than hopeful: `hooks/use-overlay.ts` sets
+   * the attribute on `document.body`. And an open panel outranking a scroll
+   * position is the correct answer rather than an arbitrary one — the panel is
+   * the thing in front of the shopper, so it decides how the bar it hangs from
+   * is painted.
+   *
+   * IT ALSO OUTRANKS THE ELEMENT-MATCHED STATES on the same element — `hover`,
+   * `focus`, `selected` and the rest — because a page state composes an extra
+   * ancestor selector on top of whatever they weigh, and the qualifier adds one
+   * more rung to that. Unqualified it TIED with them, so this replaces a
+   * coin-flip with a rule rather than taking anything away that was reliable.
+   * The visible consequence: a header link that carries both an `overlay-open`
+   * colour and a `hover` colour keeps the overlay colour while the panel is
+   * open, and stops answering the pointer until it closes. That is the same
+   * bargain `docked` has always made, which is why it is spelled the same way
+   * — but it is a bargain, so an author who wants hover to survive an open
+   * panel must not author the property in both places.
+   */
+  'overlay-open': ['body[data-overlay-state~="open"] &'],
   /**
    * The third page-level state: the chrome is DOCKED above the page rather than
    * sitting over it. `body` carries `data-chrome-mode` (see
    * chrome/chrome-mode.ts), stamped by the brand, because only the brand knows
    * which of its routes carry a hero.
    *
-   * THE `body` QUALIFIER IS A DELIBERATE SPECIFICITY BUMP, not tidiness. Every
-   * other ancestor-matched state weighs (0,2,0) against an element selector,
-   * which ties with `scrolled` — and on an inner page BOTH match at once, so a
-   * tie would be settled by whichever declaration the generator happened to
-   * emit last. Adding the element name makes this (0,2,1), so the mode wins.
-   * That is the correct answer rather than an arbitrary one: `scrolled`
-   * describes how far the page has moved under a bar that floats over it, and
-   * once the bar is docked that question no longer has a meaning.
+   * THE `body` QUALIFIER IS A DELIBERATE SPECIFICITY BUMP, not tidiness. On an
+   * inner page this and `scrolled` BOTH match at once, and unqualified they
+   * would tie at (0,2,0), leaving the winner to whichever declaration the
+   * generator happened to emit last. Adding the element name makes this
+   * (0,2,1), so the mode wins. That is the correct answer rather than an
+   * arbitrary one: `scrolled` describes how far the page has moved under a bar
+   * that floats over it, and once the bar is docked that question no longer has
+   * a meaning.
+   *
+   * WHAT THIS LADDER STILL DOES NOT SETTLE: `docked` and `overlay-open` now
+   * weigh the same, so THEY tie with each other, and a docked header with an
+   * open panel is decided by emission order again — the composition's key
+   * order, exactly the coin-flip the qualifiers were added to remove. That is
+   * unexposed rather than fixed. In the brand this was traced from, both states
+   * paint the same background and the same text colour, so the tie lands on the
+   * same pixels either way; a brand that wants its docked header to look
+   * different with the menu open will meet it. A rung IS reachable without a
+   * new attribute — repeating an attribute selector
+   * (`body[data-overlay-state~="open"][data-overlay-state]`) weighs (0,3,1) —
+   * and it is left unspent deliberately: which of the two should win is a
+   * product question nobody has been asked, and spending the rung guesses at
+   * the answer. Whoever asks it should take that rung rather than dropping one
+   * of these two qualifiers, which only hands `scrolled` back a fight it should
+   * lose.
    */
   docked: ['body[data-chrome-mode~="docked"] &']
 };