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

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

@@ -39,6 +39,13 @@ import type { Section } from '../../theme-section';
  * by emission order. Nothing here asserts that pair; there is no right answer
  * to assert yet.
  *
+ * THE STATE HAS TWO EXPRESSIONS, emitted as one rule. The `body` stamp is
+ * written from a layout effect and so is missing from the server HTML; the
+ * brand's header also renders the attribute on its own root (`useChromeMode`),
+ * and `:is(body:has(…))` reads it there, which is what makes the first paint
+ * dock. Everything the ladder above promises has to hold for EACH expression,
+ * so each is asserted below.
+ *
  * 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`
  * resolves competing rules by SOURCE ORDER ALONE and ignores specificity
@@ -46,9 +53,17 @@ import type { Section } from '../../theme-section';
  * cascade test would therefore assert the opposite of what a browser does, pass
  * today for the wrong reason, and keep passing after someone deleted the very
  * qualifier it was written to protect. So the weight is asserted directly.
+ *
+ * NOR IS THE `:has` EXPRESSION EVER HANDED TO THE DOM. jsdom's selector engine
+ * answers `:has()` inside `:is()` with no match at all (measured: zero results
+ * on a document the expression plainly matches), so a DOM assertion on it
+ * would fail for a reason that has nothing to do with docked. It is asserted as
+ * text, and its weight is worked out by hand.
  */
 
 const DOCKED = 'body[data-chrome-mode~="docked"]';
+/** The first-paint expression: the attribute on the brand's own chrome root. */
+const DOCKED_HAS = ':is(body:has([data-chrome-mode~="docked"]))';
 const SCROLLED = '[data-scroll-state~="scrolled"]';
 const SECTION = '[data-section-id="sec-1"]';
 
@@ -79,18 +94,33 @@ const block = (id: string, styles: Record<string, unknown>, type = 'group') => (
 });
 
 /**
- * Weighs the two selectors this file is about, and nothing else.
+ * Weighs the selectors this file is about, and nothing else.
  *
  * Deliberately naive: 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 (see the note above).
+ * which is all the `body` and `scrolled` expressions contain. A general
+ * specificity parser would be a second implementation to get wrong, and the
+ * honest alternative — asking the DOM — does not exist here (see the note
+ * above). The `:has` expression is brought within its reach by `unwrap` below.
  */
 const weigh = (selector: string) => ({
   attributes: (selector.match(/\[/g) || []).length,
   types: (selector.match(/(^|[\s>+~])[a-z][a-z0-9-]*/g) || []).length
 });
 
+/**
+ * Removes `:is(` / `:has(` and their closing parens, leaving the arguments in
+ * place.
+ *
+ * Exact for weight, by the spec rather than by approximation: `:is()` and
+ * `:has()` take the specificity of their most specific argument and add
+ * nothing of their own, and each here has exactly one argument. So
+ * `:is(body:has([a]))` weighs what `body[a]` weighs — (0,1,1) — and unwrapping
+ * is the hand calculation written down. Only safe on selectors with no other
+ * parentheses, which is true of every one it is given.
+ */
+const unwrap = (selector: string) =>
+  selector.replace(/:(is|has)\(/g, '').replace(/\)/g, '');
+
 afterEach(() => {
   document.body.removeAttribute('data-chrome-mode');
   document.body.innerHTML = '';
@@ -105,14 +135,42 @@ describe('the `body` qualifier is load-bearing — do not tidy it away', () => {
     expect(selector).toBe(`${DOCKED} ${SECTION}`);
   });
 
-  it('outweighs the scrolled selector, which it ties with on attributes alone', () => {
-    const [docked] = buildRootStateSelectors(SECTION, 'docked');
-    const [scrolled] = buildRootStateSelectors(SECTION, 'scrolled');
+  it('keeps the first-paint expression second, wrapped in :is(), after the body stamp', () => {
+    // Literal text for the same reason as above, and for two more. The FIRST
+    // expression is grepped for by pz-dynamic-widget, so it must stay first and
+    // byte-identical. The `:is()` wrapper looks removable and is not: the two
+    // expressions share one comma-separated rule, and without the forgiving
+    // `:is()` a browser that cannot parse `:has` would drop the body branch
+    // along with it.
+    expect(buildRootStateSelectors(SECTION, 'docked')).toEqual([
+      `${DOCKED} ${SECTION}`,
+      `${DOCKED_HAS} ${SECTION}`
+    ]);
+  });
 
-    // Same attribute count: this is the tie, and it is why order would decide.
-    expect(weigh(docked).attributes).toBe(weigh(scrolled).attributes);
-    // The type selector is the entire margin of victory.
-    expect(weigh(docked).types).toBeGreaterThan(weigh(scrolled).types);
+  it('weighs the :has expression exactly as the body stamp, so the ladder holds either way', () => {
+    const [body, has] = buildRootStateSelectors(SECTION, 'docked');
+
+    // By hand: `:is(X)` and `:has(X)` each weigh X, so the prefix is `body`
+    // (0,0,1) plus one attribute (0,1,0) — (0,1,1), the body stamp's weight.
+    // Unwrapping lands on the body stamp's selector itself, which is the
+    // strongest form that equality can take.
+    expect(unwrap(has)).toBe(body);
+    expect(weigh(unwrap(has))).toEqual(weigh(body));
+    expect(weigh(unwrap(has))).toEqual({ attributes: 2, types: 1 });
+  });
+
+  it('outweighs the scrolled selector with every expression, tying on attributes alone', () => {
+    const [scrolled] = buildRootStateSelectors(SECTION, 'scrolled');
+    const dockedExpressions = buildRootStateSelectors(SECTION, 'docked');
+
+    expect(dockedExpressions).toHaveLength(2);
+    dockedExpressions.map(unwrap).forEach((docked) => {
+      // Same attribute count: this is the tie, and it is why order would decide.
+      expect(weigh(docked).attributes).toBe(weigh(scrolled).attributes);
+      // The type selector is the entire margin of victory.
+      expect(weigh(docked).types).toBeGreaterThan(weigh(scrolled).types);
+    });
   });
 
   it('matches the same band as scrolled on an inner page, so the tie is real', () => {
@@ -164,8 +222,11 @@ describe('the generated CSS', () => {
       })
     ]);
 
+    // Both expressions in ONE rule, the body stamp first — which is also why
+    // the second must be the forgiving `:is()` form (see above).
     expect(css).toContain(
-      `${DOCKED} ${SECTION} {\n  background-color: rgba(255, 255, 255, 1);\n}`
+      `${DOCKED} ${SECTION},\n${DOCKED_HAS} ${SECTION} {\n` +
+        '  background-color: rgba(255, 255, 255, 1);\n}'
     );
     expect(css).toContain(
       `${SCROLLED} ${SECTION} {\n  background-color: rgba(245, 245, 245, 1);\n}`
@@ -182,7 +243,8 @@ describe('the generated CSS', () => {
     ]);
 
     expect(css).toContain(
-      `${DOCKED} [data-block-id="bar"] {\n  color: #4a0e26;\n}`
+      `${DOCKED} [data-block-id="bar"],\n` +
+        `${DOCKED_HAS} [data-block-id="bar"] {\n  color: #4a0e26;\n}`
     );
   });
 
@@ -197,24 +259,28 @@ describe('the generated CSS', () => {
 
 describe('docked as a part state', () => {
   it('conditions a part on the page without losing the ownership guard', () => {
-    const [selector] = buildPartSelectors('[data-section-id="sec-1"]', {
+    const selectors = buildPartSelectors('[data-section-id="sec-1"]', {
       part: 'bar',
       state: 'docked',
       styles: {}
     });
+    const guarded =
+      '[data-section-id="sec-1"] [data-part="bar"]' +
+      ':not(:where([data-section-id="sec-1"] [data-block-id] *))';
 
     // The whole compound, guard included, is substituted into the ancestor
     // pattern — so a docked rule can no more reach into a nested block than the
-    // stateless one can.
+    // stateless one can. Into BOTH patterns: the first-paint expression gets
+    // the guard too.
     //
     // Asserted as text rather than by querying the DOM on purpose: the guard
     // uses `:where()`, and the nwsapi build in this workspace's node_modules
     // cannot parse it (it is the cause of the three known-red suites here). A
     // DOM assertion would fail for a reason that has nothing to do with docked.
-    expect(selector).toBe(
-      `${DOCKED} [data-section-id="sec-1"] [data-part="bar"]` +
-        ':not(:where([data-section-id="sec-1"] [data-block-id] *))'
-    );
+    expect(selectors).toEqual([
+      `${DOCKED} ${guarded}`,
+      `${DOCKED_HAS} ${guarded}`
+    ]);
   });
 
   it('parses `bar/docked/color` as a part key and buckets it', () => {
@@ -237,6 +303,9 @@ describe('docked as a part state', () => {
     expect(css).toContain(
       `${DOCKED} [data-section-id="sec-1"] [data-part="bar"]`
     );
+    expect(css).toContain(
+      `${DOCKED_HAS} [data-section-id="sec-1"] [data-part="bar"]`
+    );
   });
 });
 

package/src/utils/part-styles.ts

@@ -143,9 +143,9 @@ const STATE_SELECTORS: Record<string, string[]> = {
   '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.
+   * sitting over it. `data-chrome-mode` (see chrome/chrome-mode.ts) is rendered
+   * by the brand on its own chrome element and stamped on `body`, because only
+   * the brand knows which of its routes carry a hero.
    *
    * THE `body` QUALIFIER IS A DELIBERATE SPECIFICITY BUMP, not tidiness. On an
    * inner page this and `scrolled` BOTH match at once, and unqualified they
@@ -171,8 +171,40 @@ const STATE_SELECTORS: Record<string, string[]> = {
    * 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.
+   *
+   * THE SECOND EXPRESSION IS THE FIRST-PAINT SIGNAL. The `body` stamp is
+   * written from a layout effect, so it is not in the server HTML, and every
+   * inner page used to paint the transparent overlay header until hydration
+   * ran the effect. `useChromeMode` / `chromeModeAttrs` render the same
+   * attribute on the brand's own chrome element, which IS in the server HTML,
+   * and `body:has(…)` reads it from there. The first expression stays, byte for
+   * byte — pz-dynamic-widget greps for it, and it is what the designer pin, a
+   * browser without `:has` and hand-written brand CSS all match.
+   *
+   * SAME WEIGHT, so the ladder above holds whichever branch matched. `:is()`
+   * and `:has()` each weigh their most specific argument and add nothing of
+   * their own, so the prefix is `body` plus one attribute, (0,1,1), exactly
+   * the first expression's: `scrolled` < `docked` = `overlay-open` as before.
+   *
+   * WRAPPED IN `:is()` because a state's expressions are not separate rules:
+   * `generatePartCSS` and `generateRootStateCSS` (utils/index.ts) join them
+   * into ONE comma-separated selector list, and a browser drops a whole list
+   * when it cannot parse one member — one without `:has` would lose the `body`
+   * branch with it and never dock at all. `:is()` takes a forgiving selector
+   * list, so that browser discards only the `:has` branch (the `:is()` then
+   * matches nothing) and the `body` stamp still docks the header after
+   * hydration.
+   *
+   * A DESCENDANT MATCH, not `:has(> …)`: the chrome element sits inside the
+   * layout and the chrome slot, never directly under `body`. Emission is not a
+   * reason either way — pz-theme writes generated CSS through
+   * `dangerouslySetInnerHTML`, verbatim, which the quotes in both expressions
+   * already depend on — so the choice is about what matches.
    */
-  docked: ['body[data-chrome-mode~="docked"] &']
+  docked: [
+    'body[data-chrome-mode~="docked"] &',
+    ':is(body:has([data-chrome-mode~="docked"])) &'
+  ]
 };
 
 export const PART_STYLE_STATES = Object.keys(STATE_SELECTORS);