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

package/src/custom/README-sections.md

@@ -310,7 +310,7 @@ way a composition learns something it cannot see from where it sits.
 |---|---|---|---|
 | `scrolled` | the page has moved under the chrome | the chrome slot, `data-scroll-state` | pz-theme (`chrome/scroll-state.tsx`) |
 | `overlay-open` | some overlay is open | `body`, `data-overlay-state` | pz-theme (`hooks/use-overlay.ts`) |
-| `docked` | the chrome sits **above** the page, not over it | `body`, `data-chrome-mode` | **you**, via `setChromeMode` |
+| `docked` | the chrome sits **above** the page, not over it | your header's root element and `body`, `data-chrome-mode` | **you**, via `useChromeMode` |
 
 All three work as a root state on the section itself, `:<state>/<property>`, and
 as a part state, `<part>/<state>/<property>`.
@@ -318,7 +318,7 @@ as a part state, `<part>/<state>/<property>`.
 **The one rule: pz-theme owns the vocabulary, the brand owns the signal.** The
 attribute names, the tokens and the selectors that read them live here. Nothing
 in pz-theme can know which of your routes carry a hero, so nothing in pz-theme
-stamps `docked`. You do — and through `setChromeMode`, never by hand-writing the
+stamps `docked`. You do — and through `useChromeMode`, never by hand-writing the
 attribute, because a typo there raises no error and simply produces a header
 that never changes appearance.
 
@@ -335,18 +335,13 @@ and lose the second appearance.
 'use client';
 
 import { usePathname } from 'next/navigation';
-import { useEffect } from 'react';
-import {
-  CHROME_MODE_DOCKED,
-  setChromeMode
-} from '@akinon/pz-theme/src/custom';
+import { CHROME_MODE_DOCKED, useChromeMode } from '@akinon/pz-theme/src/custom';
 
 function StoreHeader() {
   const isHome = usePathname() === '/';
+  const attrs = useChromeMode(isHome ? null : CHROME_MODE_DOCKED);
 
-  useEffect(() => setChromeMode(isHome ? null : CHROME_MODE_DOCKED), [isHome]);
-
-  // ...the header markup
+  return <header {...attrs}>{/* ...the header markup */}</header>;
 }
 ```
 
@@ -354,11 +349,32 @@ Import both from `@akinon/pz-theme/src/custom`, like the rest of the section
 API. The package root exports them too, but it pulls in `server-only`, so a
 client header cannot import them from there.
 
-`setChromeMode` returns a cleanup, which is why it is returned straight from the
-effect. **Give the signal one owner.** The cleanup restores the value that call
+**Spread what the hook returns on the header's root element.** That attribute is
+what the first paint uses: it is in the HTML the server sends, and the `docked`
+selector reads it through `body:has(…)`, so an inner page arrives docked instead
+of showing the transparent overlay header until hydration. The hook also stamps
+`body` from a layout effect — the editor's docked preview, browsers without
+`:has` and any CSS of your own written against `body[data-chrome-mode]` all rely
+on that half. Leave the spread out and the header still docks, but only after
+hydration, which is exactly the flash this exists to remove.
+
+**Compute the mode from render-time inputs only** — `usePathname()`, settings,
+props. Never from `window`, `localStorage` or state an effect sets. The server
+renders the attribute from what it knows, and the client's first render has to
+produce the same markup: React does not promise to patch a mismatched attribute
+while hydrating, so a mode only the browser could compute can leave the server's
+answer on the header while `body` says the opposite.
+
+**Give the signal one owner.** The hook's cleanup restores the value its stamp
 displaced — a snapshot, not a counted stack — so it unwinds correctly as one
-component mounts, re-stamps and unmounts, and does *not* compose if two
-components both stamp during a route transition.
+component mounts, changes mode and unmounts, and does *not* compose if two
+components both declare a mode during a route transition.
+
+The two halves are exported too, for a header that cannot call a hook:
+`chromeModeAttrs(mode)` returns the attribute and is pure, so a server-rendered
+header can call it, and `setChromeMode(mode)` is the `body` stamp, called from an
+effect with the cleanup it returns handed straight back. Prefer the hook — it is
+both, in the right order.
 
 The section then styles all three appearances, and no descriptor changes:
 
@@ -386,7 +402,8 @@ did.
 **`docked` outranks `scrolled` on purpose.** On an inner page both are true at
 once — a docked header is scrolled the moment the shopper moves — and both set
 the same property on the same band. The `docked` selector is qualified with
-`body`, which makes it (0,2,1) against `scrolled` at (0,2,0), so the mode wins
+`body` — both of its branches, the `body` stamp and `body:has(…)`, weigh the
+same — which makes it (0,2,1) against `scrolled` at (0,2,0), so the mode wins
 on specificity rather than on whichever rule happened to be emitted last. That
 is the right answer and not an arbitrary one: `scrolled` describes how far the
 page has slid under a bar that floats over it, and once the bar is docked the

package/src/custom/__tests__/custom-entry-exports.test.tsx

@@ -4,6 +4,7 @@ import React from 'react';
 import { render, screen } from '@testing-library/react';
 
 import * as chromeMode from '../../chrome/chrome-mode';
+import * as chromeModeHook from '../../chrome/use-chrome-mode';
 import * as blockContext from '../block-context';
 import * as overlay from '../../hooks/use-overlay';
 import { resetCustomCollection } from '../collect';
@@ -15,8 +16,10 @@ import type { Section } from '../../theme-section';
 // `server-only`, so a client module cannot reach them there.
 import {
   CHROME_MODE_DOCKED,
+  chromeModeAttrs,
   defineCustomSection,
   setChromeMode,
+  useChromeMode,
   useCustomBlockContext,
   useOverlay
 } from '../index';
@@ -147,6 +150,53 @@ describe('useCustomBlockContext', () => {
   });
 });
 
+describe('the chrome mode exports for first paint', () => {
+  it('re-exports the same bindings rather than second copies', () => {
+    expect(chromeModeAttrs).toBe(chromeMode.chromeModeAttrs);
+    expect(useChromeMode).toBe(chromeModeHook.useChromeMode);
+  });
+
+  it('keeps use-chrome-mode.ts client-safe: a client directive, and react and chrome-mode as its only imports', () => {
+    const source = fs.readFileSync(
+      path.resolve(__dirname, '../../chrome/use-chrome-mode.ts'),
+      'utf8'
+    );
+    const sources = Array.from(
+      source.matchAll(/^import[\s\S]*?from\s+['"]([^'"]+)['"]/gm)
+    ).map((match) => match[1]);
+
+    expect(source.trimStart()).toMatch(/^['"]use client['"]/);
+    expect(source).not.toMatch(/server-only/);
+    expect(sources.length).toBeGreaterThan(0);
+    sources.forEach((from) => {
+      expect(['react', './chrome-mode']).toContain(from);
+    });
+  });
+});
+
+describe('useChromeMode from the custom entry', () => {
+  function StoreHeader({ mode }: { mode: ChromeMode }) {
+    return <header data-testid="store-header" {...useChromeMode(mode)} />;
+  }
+
+  afterEach(() => {
+    document.body.removeAttribute('data-chrome-mode');
+  });
+
+  it('puts the mode on the header root and on body, and takes body back on unmount', () => {
+    const { unmount } = render(<StoreHeader mode={CHROME_MODE_DOCKED} />);
+
+    expect(
+      screen.getByTestId('store-header').getAttribute('data-chrome-mode')
+    ).toBe('docked');
+    expect(document.body.getAttribute('data-chrome-mode')).toBe('docked');
+
+    unmount();
+
+    expect(document.body.hasAttribute('data-chrome-mode')).toBe(false);
+  });
+});
+
 describe('setChromeMode from the custom entry', () => {
   afterEach(() => {
     document.body.removeAttribute('data-chrome-mode');

package/src/custom/index.ts

@@ -239,12 +239,28 @@ export { findRegionChild, isRegionNode, regionNodeName } from './region-nodes';
 export { partAttrs } from '../utils/part-styles';
 
 /**
- * The chrome mode writer, re-exported so a custom header section can declare
- * its docked appearance from this module. The package root exports the same
+ * The chrome mode, re-exported so a custom header section can declare its
+ * docked appearance from this module. The package root exports the same
  * symbols but pulls in `server-only`, which a client module cannot import.
- * `chrome/chrome-mode.ts` has no imports and no directive, and `setChromeMode`
- * is a no-op without a `document`, so it is safe on either graph. Call it from
- * an effect and return the cleanup it hands back.
+ *
+ * `useChromeMode` is the one to reach for: call it in the header with a mode
+ * computed from render-time inputs (`usePathname()`, settings, props) and
+ * spread what it returns on the header's root element. That attribute is the
+ * first-paint signal; the hook also stamps `body` from a layout effect.
+ * `chrome/use-chrome-mode.ts` is 'use client' and imports only react and
+ * `chrome-mode.ts`, so it is safe to re-export here.
+ *
+ * `chromeModeAttrs` and `setChromeMode` are its two halves, for a header that
+ * cannot use the hook — `chromeModeAttrs` is pure, so a server-rendered header
+ * can call it. `chrome/chrome-mode.ts` has no imports and no directive, and
+ * `setChromeMode` is a no-op without a `document`, so both are safe on either
+ * graph. Call `setChromeMode` from an effect and return the cleanup it hands
+ * back.
  */
-export { CHROME_MODE_DOCKED, setChromeMode } from '../chrome/chrome-mode';
+export {
+  CHROME_MODE_DOCKED,
+  chromeModeAttrs,
+  setChromeMode
+} from '../chrome/chrome-mode';
 export type { ChromeMode } from '../chrome/chrome-mode';
+export { useChromeMode } from '../chrome/use-chrome-mode';

package/src/index.ts

@@ -66,9 +66,11 @@ export {
 export {
   CHROME_MODE_ATTRIBUTE,
   CHROME_MODE_DOCKED,
+  chromeModeAttrs,
   setChromeMode
 } from './chrome/chrome-mode';
 export type { ChromeMode } from './chrome/chrome-mode';
+export { useChromeMode } from './chrome/use-chrome-mode';
 export { PreviewAuthStateReporter } from './chrome/preview-auth-state';
 export { LiveBasketPageContext } from './chrome/live-basket-page-context';
 export { LiveWishlistPageContext } from './chrome/live-wishlist-page-context';

package/src/menu-seed-context.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import React, { createContext, ReactNode, useContext } from 'react';
+import { menuSeedKey } from './blocks/menu-query-args';
+import type { MenuQueryArgs, MenuSeeds } from './blocks/menu-query-args';
+
+/**
+ * Server-fetched menus for the nav-menu blocks of one placeholder
+ * (chrome/menu-seed-source.ts). `null` wherever no server answered: the
+ * designer's modal preview host, a brand that mounts the wrapper itself.
+ * Blocks then fetch on the client exactly as they always have.
+ *
+ * Read straight from the prop, no state: the server and the first client
+ * render must see the same value or hydration would not match.
+ */
+export const MenuSeedContext = createContext<MenuSeeds | null>(null);
+
+export function MenuSeedProvider({
+  value,
+  children
+}: {
+  value: MenuSeeds | null;
+  children?: ReactNode;
+}) {
+  return (
+    <MenuSeedContext.Provider value={value}>
+      {children}
+    </MenuSeedContext.Provider>
+  );
+}
+
+/** The seeded entries for these args, or `undefined` when none were seeded. */
+export function useMenuSeed(args: MenuQueryArgs): unknown[] | undefined {
+  const seeds = useContext(MenuSeedContext);
+  const seeded = seeds?.[menuSeedKey(args)];
+
+  return Array.isArray(seeded) ? seeded : undefined;
+}

package/src/theme-placeholder-wrapper.tsx

@@ -16,6 +16,8 @@ import {
 import { useThemePageContext } from './theme-page-context';
 import { ThemePageContextProvider } from './theme-page-context';
 import { ThemeSettingsProvider } from './theme-settings-context';
+import { MenuSeedProvider } from './menu-seed-context';
+import type { MenuSeeds } from './blocks/menu-query-args';
 import { generateThemeCSS, readThemeTypographyFont } from './utils';
 import { breakpointForWidth } from './utils/breakpoints';
 import { PartStatePreview } from './components/part-state-preview';
@@ -221,6 +223,13 @@ interface ThemePlaceholderWrapperProps {
   dataSources?: any[];
   initialThemeSettings?: Record<string, unknown> | null;
   initialPageContext?: Record<string, unknown> | null;
+  /**
+   * Menus the server fetched for this placeholder's nav-menu blocks
+   * (chrome/menu-seed-source.ts), so the category row is in the served HTML.
+   * Absent for callers without a server render; the blocks then fetch on the
+   * client as before.
+   */
+  initialMenuSeeds?: MenuSeeds | null;
 }
 
 declare global {
@@ -357,7 +366,8 @@ export default function ThemePlaceholderWrapper({
   isDesignMode,
   dataSources: initialDataSources = [],
   initialThemeSettings = null,
-  initialPageContext = null
+  initialPageContext = null,
+  initialMenuSeeds = null
 }: ThemePlaceholderWrapperProps) {
   const inheritedPageContext = useThemePageContext();
   const [sections, setSections] = useState<Section[]>(initialSections);
@@ -1058,96 +1068,98 @@ export default function ThemePlaceholderWrapper({
     // falls back to its empty state.
     <ThemePageContextProvider value={resolvedPageContext}>
       <ThemeSettingsProvider value={themeSettings}>
-        {/*
-        Pins are released while browsing — a button frozen in its hover state
-        is not what the live site looks like. The editor re-sends the pinned
-        state when the designer comes back, so the panel and the canvas agree.
-      */}
-        <PartStatePreview isDesigner={isEditing} />
-        {/*
-        Tells the editor which languages this storefront has and follows its
-        language switch. Every placeholder renders one; they share a single
-        listener and a single announcement (see editor-locale-bridge.tsx).
-      */}
-        <EditorLocaleBridge />
-        {themeBackgroundCSS && (
-          <style dangerouslySetInnerHTML={{ __html: themeBackgroundCSS }} />
-        )}
-        {dynamicCSS && (
-          <style dangerouslySetInnerHTML={{ __html: dynamicCSS }} />
-        )}
-        {/*
-        Deliberately unpainted. This wrapper sits behind every section of the
-        slot, so any colour on it showed through a section that asked for
-        `background-color: transparent` — the shipped default. That is why a
-        composed header could not sit over a hero: the section was transparent
-        and the wrapper behind it was not. The page colour belongs to `body`
-        (see buildThemeBackgroundCss), which paints the same pixels everywhere
-        the slot does not overlap something else.
-      */}
-        <div data-placeholder={slug} className="theme-placeholder">
-          {renderedSections
-            .sort((a, b) => a.order - b.order)
-            .filter(
-              (section) =>
-                !section.hidden &&
-                (isEditing ||
-                  isPublishWindowVisible(
-                    section.properties?.['publish-window']
-                  ))
-            )
-            .map((section) => (
-              <SectionErrorBoundary key={section.id} sectionId={section.id}>
-                <ThemeSection
-                  section={section}
-                  placeholderId={placeholderSlug}
-                  pageContext={resolvedPageContext}
-                  isDesigner={isEditing}
-                  isSelected={selectedSectionId === section.id}
-                  selectedBlockId={selectedBlockId}
-                  currentBreakpoint={currentBreakpoint}
-                  onSelect={setSelectedSectionId}
-                  onMoveUp={() =>
-                    sendAction('MOVE_SECTION_UP', {
-                      placeholderId: placeholderSlug,
-                      sectionId: section.id
-                    })
-                  }
-                  onMoveDown={() =>
-                    sendAction('MOVE_SECTION_DOWN', {
-                      placeholderId: placeholderSlug,
-                      sectionId: section.id
-                    })
-                  }
-                  onDuplicate={() =>
-                    sendAction('DUPLICATE_SECTION', {
-                      placeholderId: placeholderSlug,
-                      sectionId: section.id
-                    })
-                  }
-                  onToggleVisibility={() =>
-                    sendAction('TOGGLE_SECTION_VISIBILITY', {
-                      placeholderId: placeholderSlug,
-                      sectionId: section.id
-                    })
-                  }
-                  onDelete={() =>
-                    sendAction('DELETE_SECTION', {
-                      placeholderId: placeholderSlug,
-                      sectionId: section.id
-                    })
-                  }
-                  onRename={(newLabel) =>
-                    sendAction('RENAME_SECTION', {
-                      placeholderId: placeholderSlug,
-                      sectionId: section.id,
-                      label: newLabel
-                    })
-                  }
-                />
-              </SectionErrorBoundary>
-            ))}
-        </div>
+        <MenuSeedProvider value={initialMenuSeeds}>
+          {/*
+          Pins are released while browsing — a button frozen in its hover state
+          is not what the live site looks like. The editor re-sends the pinned
+          state when the designer comes back, so the panel and the canvas agree.
+        */}
+          <PartStatePreview isDesigner={isEditing} />
+          {/*
+          Tells the editor which languages this storefront has and follows its
+          language switch. Every placeholder renders one; they share a single
+          listener and a single announcement (see editor-locale-bridge.tsx).
+        */}
+          <EditorLocaleBridge />
+          {themeBackgroundCSS && (
+            <style dangerouslySetInnerHTML={{ __html: themeBackgroundCSS }} />
+          )}
+          {dynamicCSS && (
+            <style dangerouslySetInnerHTML={{ __html: dynamicCSS }} />
+          )}
+          {/*
+          Deliberately unpainted. This wrapper sits behind every section of the
+          slot, so any colour on it showed through a section that asked for
+          `background-color: transparent` — the shipped default. That is why a
+          composed header could not sit over a hero: the section was transparent
+          and the wrapper behind it was not. The page colour belongs to `body`
+          (see buildThemeBackgroundCss), which paints the same pixels everywhere
+          the slot does not overlap something else.
+        */}
+          <div data-placeholder={slug} className="theme-placeholder">
+            {renderedSections
+              .sort((a, b) => a.order - b.order)
+              .filter(
+                (section) =>
+                  !section.hidden &&
+                  (isEditing ||
+                    isPublishWindowVisible(
+                      section.properties?.['publish-window']
+                    ))
+              )
+              .map((section) => (
+                <SectionErrorBoundary key={section.id} sectionId={section.id}>
+                  <ThemeSection
+                    section={section}
+                    placeholderId={placeholderSlug}
+                    pageContext={resolvedPageContext}
+                    isDesigner={isEditing}
+                    isSelected={selectedSectionId === section.id}
+                    selectedBlockId={selectedBlockId}
+                    currentBreakpoint={currentBreakpoint}
+                    onSelect={setSelectedSectionId}
+                    onMoveUp={() =>
+                      sendAction('MOVE_SECTION_UP', {
+                        placeholderId: placeholderSlug,
+                        sectionId: section.id
+                      })
+                    }
+                    onMoveDown={() =>
+                      sendAction('MOVE_SECTION_DOWN', {
+                        placeholderId: placeholderSlug,
+                        sectionId: section.id
+                      })
+                    }
+                    onDuplicate={() =>
+                      sendAction('DUPLICATE_SECTION', {
+                        placeholderId: placeholderSlug,
+                        sectionId: section.id
+                      })
+                    }
+                    onToggleVisibility={() =>
+                      sendAction('TOGGLE_SECTION_VISIBILITY', {
+                        placeholderId: placeholderSlug,
+                        sectionId: section.id
+                      })
+                    }
+                    onDelete={() =>
+                      sendAction('DELETE_SECTION', {
+                        placeholderId: placeholderSlug,
+                        sectionId: section.id
+                      })
+                    }
+                    onRename={(newLabel) =>
+                      sendAction('RENAME_SECTION', {
+                        placeholderId: placeholderSlug,
+                        sectionId: section.id,
+                        label: newLabel
+                      })
+                    }
+                  />
+                </SectionErrorBoundary>
+              ))}
+          </div>
+        </MenuSeedProvider>
       </ThemeSettingsProvider>
     </ThemePageContextProvider>
   );

package/src/theme-placeholder.tsx

@@ -4,6 +4,7 @@ import ThemePlaceholderWrapper from './theme-placeholder-wrapper';
 import { ThemeFontsLink } from './chrome/theme-fonts-link';
 import { ThemeGoogleFontsLinks } from './chrome/theme-google-fonts-links';
 import { loadPlaceholderSections } from './load-placeholder-sections';
+import { loadMenuSeeds } from './chrome/menu-seed-source';
 import { generateThemeCSS } from './utils';
 
 interface ThemePlaceholderProps {
@@ -23,6 +24,9 @@ export default async function ThemePlaceholder({
 
   const { sections, placeholderId, dataSources, themeSettings } = loaded;
   const themeCSS = generateThemeCSS(sections);
+  // The live and the preview-snapshot loads both arrive here, so both get the
+  // menus their nav-menu blocks would otherwise fetch after hydration.
+  const menuSeeds = await loadMenuSeeds(sections);
 
   return (
     <>
@@ -37,6 +41,7 @@ export default async function ThemePlaceholder({
         dataSources={dataSources}
         initialThemeSettings={themeSettings}
         initialPageContext={pageContext}
+        initialMenuSeeds={menuSeeds}
       />
     </>
   );