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

package/CHANGELOG.md

@@ -1,40 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.115-rc.0
-
-### Patch Changes
-
-- Updated dependencies [86187b1c2]
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea41430]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71d]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6c]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a631]
-- Updated dependencies [e18836b20]
-- Updated dependencies [b1111d7b1]
-- Updated dependencies [1595d45]
-- Updated dependencies [dca1281]
-  - @akinon/next@2.0.115-rc.0
-  - @akinon/theme-contract@2.0.115-rc.0
+## 2.0.115
+
+### Patch Changes
+
+- 9ce1787: ZERO-5092: Render the header on first paint as it will settle: seed nav-menu entries on the server so the category row is in the served HTML, and add useChromeMode / chromeModeAttrs so a docked header is docked before hydration
+  - @akinon/next@2.0.115
+  - @akinon/theme-contract@2.0.115
 
 ## 2.0.114
 

package/package.json

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

package/src/blocks/__tests__/menu-query-args.test.tsx

@@ -0,0 +1,239 @@
+/**
+ * The server seeds a nav-menu's entries under a key; the block looks them up
+ * under a key. If the two ever computed different keys the seed would be
+ * silently ignored — the block would fall back to its client fetch and the
+ * server HTML would carry an empty row again, with nothing saying why.
+ *
+ * So the args live in one function both sides call, and these pin it: what
+ * it resolves for the shapes compositions actually store, which blocks the
+ * collector visits, and — against the rendered block itself — that every
+ * request the block makes is one the collector would have seeded.
+ */
+import React from 'react';
+import { render } from '@testing-library/react';
+
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: jest.fn() }),
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams('')
+}));
+
+const mockUseGetMenuQuery = jest.fn((_args: unknown, _options?: unknown) => ({
+  data: [],
+  isLoading: false
+}));
+
+jest.mock('@akinon/next/data/client/misc', () => ({
+  useGetMenuQuery: (...args: unknown[]) =>
+    (mockUseGetMenuQuery as (...a: unknown[]) => unknown)(...args)
+}));
+
+import NavMenuBlock from '../nav-menu-block';
+import {
+  collectMenuSeedArgs,
+  menuSeedKey,
+  navMenuQueryArgs
+} from '../menu-query-args';
+import { BREAKPOINTS } from '../../utils/breakpoints';
+
+const block = (
+  type: string,
+  properties: Record<string, unknown> = {},
+  over: Record<string, unknown> = {}
+): any => ({
+  id: `${type}-${Math.random().toString(36).slice(2, 7)}`,
+  type,
+  label: type,
+  order: 0,
+  hidden: false,
+  value: '',
+  properties,
+  styles: {},
+  blocks: [],
+  ...over
+});
+
+const section = (blocks: any[], over: Record<string, unknown> = {}): any => ({
+  id: 'header-main',
+  type: 'default',
+  name: 'header',
+  label: 'header',
+  properties: {},
+  styles: {},
+  blocks,
+  order: 0,
+  hidden: false,
+  ...over
+});
+
+const keys = (sections: any[]) =>
+  collectMenuSeedArgs(sections).map(menuSeedKey).sort();
+
+describe('navMenuQueryArgs', () => {
+  it.each([
+    ['nothing authored', {}, 'desktop', { depth: 1 }],
+    ['a numeric string', { depth: '2' }, 'desktop', { depth: 2 }],
+    ['zero', { depth: 0 }, 'desktop', { depth: 1 }],
+    ['a negative depth', { depth: -3 }, 'desktop', { depth: 1 }],
+    ['a non-number', { depth: 'deep' }, 'desktop', { depth: 1 }],
+    [
+      'a per-breakpoint depth on mobile',
+      { depth: { desktop: 1, mobile: 3 } },
+      'mobile',
+      { depth: 3 }
+    ],
+    [
+      'a tablet with nothing of its own (falls through to mobile)',
+      { depth: { desktop: 1, mobile: 3 } },
+      'tablet',
+      { depth: 3 }
+    ],
+    ['an empty parent', { parent: '' }, 'desktop', { depth: 1 }],
+    [
+      'a parent',
+      { depth: 2, parent: 'women' },
+      'desktop',
+      { depth: 2, parent: 'women' }
+    ],
+    [
+      'a parent cleared on mobile',
+      { parent: { desktop: 'women', mobile: '' } },
+      'mobile',
+      { depth: 1 }
+    ],
+    ['a numeric parent', { parent: 42 }, 'desktop', { depth: 1, parent: '42' }]
+  ])('resolves %s', (_name, properties, breakpoint, expected) => {
+    expect(navMenuQueryArgs(properties, breakpoint)).toEqual(expected);
+  });
+
+  it('omits the parent key rather than sending it empty', () => {
+    // RTK derives the cache entry from these args; the shape is the one the
+    // block always sent.
+    expect('parent' in navMenuQueryArgs({ parent: '' }, 'desktop')).toBe(false);
+  });
+
+  it('tolerates missing properties', () => {
+    expect(navMenuQueryArgs(undefined)).toEqual({ depth: 1 });
+    expect(navMenuQueryArgs(null, 'mobile')).toEqual({ depth: 1 });
+  });
+});
+
+describe('menuSeedKey', () => {
+  it('is depth and parent, with an absent parent written empty', () => {
+    expect(menuSeedKey({ depth: 1 })).toBe('1|');
+    expect(menuSeedKey({ depth: 2, parent: 'women' })).toBe('2|women');
+  });
+});
+
+describe('collectMenuSeedArgs', () => {
+  it('seeds every breakpoint a nav-menu asks for, once per distinct menu', () => {
+    expect(
+      keys([section([block('nav-menu', { depth: { desktop: 1, mobile: 2 } })])])
+    ).toEqual(['1|', '2|']);
+  });
+
+  it('collapses a block that asks for one menu everywhere to one key', () => {
+    expect(keys([section([block('nav-menu')])])).toEqual(['1|']);
+  });
+
+  it('dedupes the same menu across blocks and sections', () => {
+    expect(
+      keys([
+        section([block('nav-menu'), block('nav-menu', { depth: 1 })]),
+        section([block('nav-menu')], { id: 'footer' })
+      ])
+    ).toEqual(['1|']);
+  });
+
+  it('finds a nav-menu nested inside groups', () => {
+    const nested = block(
+      'group',
+      {},
+      {
+        blocks: [
+          block(
+            'container',
+            {},
+            {
+              blocks: [block('nav-menu', { depth: 2, parent: 'women' })]
+            }
+          )
+        ]
+      }
+    );
+
+    expect(keys([section([nested])])).toEqual(['2|women']);
+  });
+
+  it('skips hidden sections', () => {
+    expect(keys([section([block('nav-menu')], { hidden: true })])).toEqual([]);
+  });
+
+  it('skips hidden blocks, and whatever they contain', () => {
+    const hiddenGroup = block(
+      'group',
+      {},
+      { hidden: true, blocks: [block('nav-menu', { depth: 3 })] }
+    );
+
+    expect(
+      keys([section([block('nav-menu', {}, { hidden: true }), hiddenGroup])])
+    ).toEqual([]);
+  });
+
+  it('only seeds nav-menu — not the mega or hamburger menus', () => {
+    expect(
+      keys([
+        section([
+          block('mega-menu'),
+          block('hamburger-menu'),
+          block('text'),
+          block('link')
+        ])
+      ])
+    ).toEqual([]);
+  });
+
+  it('answers nothing for no sections', () => {
+    expect(collectMenuSeedArgs([])).toEqual([]);
+    expect(collectMenuSeedArgs(null)).toEqual([]);
+    expect(collectMenuSeedArgs(undefined)).toEqual([]);
+  });
+});
+
+describe('parity with the rendered block', () => {
+  beforeEach(() => mockUseGetMenuQuery.mockClear());
+
+  it.each([
+    ['nothing authored', {}],
+    ['a per-breakpoint depth', { depth: { desktop: 1, mobile: 2 } }],
+    ['a three-way depth', { depth: { desktop: 3, tablet: 2, mobile: 1 } }],
+    ['a parent', { depth: '2', parent: 'women' }],
+    ['a per-breakpoint parent', { parent: { desktop: 'women', mobile: '' } }],
+    ['an invalid depth', { depth: 'x' }]
+  ])(
+    'every request the block makes for %s is one the server seeded',
+    (_name, properties) => {
+      const navMenu = block('nav-menu', properties);
+      const seeded = keys([section([navMenu])]);
+
+      BREAKPOINTS.forEach((breakpoint) => {
+        mockUseGetMenuQuery.mockClear();
+        const { unmount } = render(
+          <NavMenuBlock
+            block={navMenu}
+            placeholderId="header"
+            sectionId="header-main"
+            currentBreakpoint={breakpoint}
+            isDesigner={false}
+          />
+        );
+
+        const [args] = mockUseGetMenuQuery.mock.calls[0];
+        expect(args).toEqual(navMenuQueryArgs(properties, breakpoint));
+        expect(seeded).toContain(menuSeedKey(args as never));
+        unmount();
+      });
+    }
+  );
+});

package/src/blocks/__tests__/nav-menu-ssr.test.tsx

@@ -0,0 +1,260 @@
+/**
+ * The category row is in the SERVER HTML — it used to arrive after hydration.
+ *
+ * The nav-menu block loads its entries with a client-only RTK hook, so the
+ * server rendered an empty `<nav>` and the row popped in once the client
+ * fetch landed. The server now fetches the menu ahead of the render and hands
+ * it down through `MenuSeedProvider`; RTK's cache cannot be filled
+ * synchronously on the v1 core (RTK 1.9.7), so the seed is render input.
+ *
+ * What these pin: the seeded entries are in `renderToString`'s output, the
+ * client request is skipped for a seeded key and made for any other, the
+ * client's first render agrees with the server's (no hydration error), and a
+ * tree with no provider behaves exactly as before.
+ */
+import React from 'react';
+import { act, render, screen } from '@testing-library/react';
+import { renderToString } from 'react-dom/server';
+import { hydrateRoot } from 'react-dom/client';
+
+jest.mock('next/navigation', () => ({
+  useRouter: () => ({ push: jest.fn() }),
+  usePathname: () => '/women',
+  useSearchParams: () => new URLSearchParams('')
+}));
+
+const seededRows = [
+  { pk: 1, label: 'Women', url: '/women', children: [] },
+  { pk: 2, label: 'Men', url: '/men', children: [] },
+  { pk: 3, label: 'Home', url: '/home', children: [] }
+];
+
+const fetchedRows = [
+  { pk: 9, label: 'Fetched', url: '/fetched', children: [] }
+];
+
+/** What the client fetch answers; a parent menu names its parent. */
+const fetchedFor = (args: unknown) => {
+  const parent = (args as { parent?: string } | undefined)?.parent;
+
+  return parent
+    ? [{ pk: 8, label: `Fetched ${parent}`, url: `/${parent}`, children: [] }]
+    : fetchedRows;
+};
+
+// Behaves like the real hook where it matters: a skipped query is not
+// loading, and it does NOT clear its data. RTK (1.9.7 and 2.x alike) keeps
+// returning the last result this hook instance got for the args it ran with
+// before; only a hook that was skipped from its first render has nothing.
+const mockUseGetMenuQuery = jest.fn(
+  (args: unknown, options?: { skip?: boolean }) => {
+    const last = React.useRef<unknown>(undefined);
+    if (!options?.skip) last.current = fetchedFor(args);
+
+    return { data: last.current, isLoading: false };
+  }
+);
+
+jest.mock('@akinon/next/data/client/misc', () => ({
+  useGetMenuQuery: (...args: unknown[]) =>
+    (mockUseGetMenuQuery as (...a: unknown[]) => unknown)(...args)
+}));
+
+import NavMenuBlock from '../nav-menu-block';
+import { MenuSeedProvider } from '../../menu-seed-context';
+import type { MenuSeeds } from '../menu-query-args';
+
+const navBlock = (properties: Record<string, unknown> = {}) =>
+  ({
+    id: 'main-nav',
+    type: 'nav-menu',
+    label: 'nav-menu',
+    order: 0,
+    hidden: false,
+    value: '',
+    properties,
+    styles: {},
+    blocks: []
+  } as never);
+
+const tree = (
+  seeds: MenuSeeds | null,
+  properties: Record<string, unknown> = {}
+) => (
+  <MenuSeedProvider value={seeds}>
+    <NavMenuBlock
+      block={navBlock(properties)}
+      placeholderId="header"
+      sectionId="header-main"
+      currentBreakpoint="desktop"
+      isDesigner={false}
+    />
+  </MenuSeedProvider>
+);
+
+/** The server's markup, parsed so it can be queried the way a browser would. */
+const serverDom = (element: React.ReactElement): HTMLElement => {
+  const host = document.createElement('div');
+  host.innerHTML = renderToString(element);
+  return host;
+};
+
+const labels = (root: ParentNode) =>
+  Array.from(root.querySelectorAll('nav[data-nav-menu] a')).map(
+    (anchor) => anchor.textContent
+  );
+
+beforeEach(() => {
+  mockUseGetMenuQuery.mockClear();
+});
+
+describe('a seeded nav-menu on the server', () => {
+  it('renders its entries into the server HTML', () => {
+    const dom = serverDom(tree({ '1|': seededRows }));
+
+    expect(labels(dom)).toEqual(['Women', 'Men', 'Home']);
+    expect(dom.querySelector('a[href="/men"]')).not.toBeNull();
+  });
+
+  it('skips the client request for the seeded key', () => {
+    renderToString(tree({ '1|': seededRows }));
+
+    expect(mockUseGetMenuQuery).toHaveBeenCalledWith(
+      { depth: 1 },
+      { skip: true }
+    );
+  });
+
+  it('still requests a menu the server did not seed', () => {
+    const dom = serverDom(tree({ '1|': seededRows }, { depth: 2 }));
+
+    expect(mockUseGetMenuQuery).toHaveBeenCalledWith(
+      { depth: 2 },
+      { skip: false }
+    );
+    expect(labels(dom)).toEqual(['Fetched']);
+  });
+
+  it('keys by parent too, so a seeded parent menu is found', () => {
+    const dom = serverDom(
+      tree({ '2|women': seededRows }, { depth: 2, parent: 'women' })
+    );
+
+    expect(mockUseGetMenuQuery).toHaveBeenCalledWith(
+      { depth: 2, parent: 'women' },
+      { skip: true }
+    );
+    expect(labels(dom)).toEqual(['Women', 'Men', 'Home']);
+  });
+});
+
+describe('the client agrees with the server', () => {
+  const hydrate = (serverTree: React.ReactElement, clientTree = serverTree) => {
+    const host = document.createElement('div');
+    host.innerHTML = renderToString(serverTree);
+    document.body.appendChild(host);
+
+    const recoverable: unknown[] = [];
+    const logged: string[] = [];
+    const spy = jest
+      .spyOn(console, 'error')
+      .mockImplementation((...args: unknown[]) => {
+        logged.push(args.map(String).join(' '));
+      });
+
+    let root: ReturnType<typeof hydrateRoot>;
+    act(() => {
+      root = hydrateRoot(host, clientTree, {
+        onRecoverableError: (error) => {
+          recoverable.push(error);
+        }
+      });
+    });
+
+    spy.mockRestore();
+    return {
+      host,
+      recoverable,
+      mismatches: logged.filter((message) =>
+        /hydrat|did not match/i.test(message)
+      ),
+      unmount: () => {
+        act(() => root.unmount());
+        host.remove();
+      }
+    };
+  };
+
+  it('hydrates the seeded row with no recoverable error', () => {
+    const seeded = tree({ '1|': seededRows });
+    const { host, recoverable, mismatches, unmount } = hydrate(seeded);
+
+    expect(recoverable).toEqual([]);
+    expect(mismatches).toEqual([]);
+    expect(labels(host)).toEqual(['Women', 'Men', 'Home']);
+    unmount();
+  });
+
+  it('would report one if the client did not see the seed (the detector works)', () => {
+    // Control: the same server HTML hydrated by a client that fetches instead.
+    // Proves the check above can fail, rather than trivially passing.
+    const { recoverable, unmount } = hydrate(
+      tree({ '1|': seededRows }),
+      tree(null)
+    );
+
+    expect(recoverable.length).toBeGreaterThan(0);
+    unmount();
+  });
+});
+
+describe('a block that leaves a seeded key and comes back', () => {
+  // The designer points the row at an unseeded parent, which the client
+  // fetches, then undoes it. The query is skipped again but still holds the
+  // menu it fetched for the other parent; the seed has to win over it.
+  it('draws the seed again, not the menu fetched for the other key', () => {
+    const seeds = { '2|women': seededRows };
+    const { container, rerender } = render(
+      tree(seeds, { depth: 2, parent: 'women' })
+    );
+    expect(labels(container)).toEqual(['Women', 'Men', 'Home']);
+
+    rerender(tree(seeds, { depth: 2, parent: 'men' }));
+    expect(labels(container)).toEqual(['Fetched men']);
+
+    rerender(tree(seeds, { depth: 2, parent: 'women' }));
+
+    const lastCall = mockUseGetMenuQuery.mock.calls.length - 1;
+    expect(mockUseGetMenuQuery.mock.calls[lastCall]).toEqual([
+      { depth: 2, parent: 'women' },
+      { skip: true }
+    ]);
+    // The precondition that makes this a real check: the skipped hook is
+    // still answering with the men menu.
+    expect(
+      (mockUseGetMenuQuery.mock.results[lastCall].value as { data: unknown })
+        .data
+    ).toEqual(fetchedFor({ parent: 'men' }));
+    expect(labels(container)).toEqual(['Women', 'Men', 'Home']);
+  });
+});
+
+describe('without a provider', () => {
+  it('fetches on the client exactly as before', () => {
+    render(
+      <NavMenuBlock
+        block={navBlock()}
+        placeholderId="header"
+        sectionId="header-main"
+        currentBreakpoint="desktop"
+        isDesigner={false}
+      />
+    );
+
+    expect(mockUseGetMenuQuery).toHaveBeenCalledWith(
+      { depth: 1 },
+      { skip: false }
+    );
+    expect(screen.getByText('Fetched')).toBeInTheDocument();
+  });
+});

package/src/blocks/menu-query-args.ts

@@ -0,0 +1,105 @@
+import type { Block } from '../theme-block';
+import type { Section } from '../theme-section';
+import { getResponsiveValue } from '../utils';
+import { BREAKPOINTS } from '../utils/breakpoints';
+
+/**
+ * The nav-menu block's menu request, readable by the server.
+ *
+ * The block loads its entries with the client-only RTK hook, so the server
+ * used to emit an empty category row that filled in after hydration. The
+ * server now fetches the same menus ahead of the render (chrome/
+ * menu-seed-source.ts) and hands them to the block through context
+ * (menu-seed-context.tsx); the block reads its seed by KEY and skips the
+ * client request when one is there.
+ *
+ * That only works if both sides compute the same key from the same
+ * properties. So the args logic lives here, once, and both the block and the
+ * server collector call it: a seed the block cannot find would silently fall
+ * back to the client fetch, and the row would be empty in the server HTML
+ * again with nothing in the output saying why.
+ *
+ * Directive-free on purpose: the server imports it, and a 'use client' module
+ * would hand the server a client reference instead of these functions.
+ */
+
+export interface MenuQueryArgs {
+  depth: number;
+  parent?: string;
+}
+
+/** Menu entries per `menuSeedKey`, as the server fetched them. */
+export type MenuSeeds = Record<string, unknown[]>;
+
+const NAV_MENU_BLOCK_TYPE = 'nav-menu';
+
+/**
+ * The args the nav-menu block hands `useGetMenuQuery` at `breakpoint`.
+ *
+ * The shape is the one the block has always sent, `parent` included only
+ * when set: RTK derives the cache entry from the args, so keeping it
+ * unchanged keeps the entry shared with every other caller asking for the
+ * same menu.
+ */
+export const navMenuQueryArgs = (
+  properties: Record<string, unknown> | null | undefined,
+  breakpoint = 'desktop'
+): MenuQueryArgs => {
+  const depth = Number(getResponsiveValue(properties?.depth, breakpoint, 1));
+  const parent = properties?.parent
+    ? String(getResponsiveValue(properties.parent, breakpoint, ''))
+    : undefined;
+
+  return {
+    depth: Number.isFinite(depth) && depth > 0 ? depth : 1,
+    ...(parent ? { parent } : {})
+  };
+};
+
+/** One seed per distinct request; an absent parent and an empty one agree. */
+export const menuSeedKey = ({ depth, parent }: MenuQueryArgs): string =>
+  `${depth}|${parent ?? ''}`;
+
+/**
+ * Every distinct menu request the nav-menu blocks of these sections can make.
+ *
+ * Per breakpoint, not just desktop: the wrapper renders at its initial
+ * breakpoint and then follows the viewport, and a block whose depth differs on
+ * a phone asks for a different menu there. Seeding every breakpoint's request
+ * means the switch finds its seed instead of starting a client fetch. They
+ * usually collapse to one key, so this costs a request only when the
+ * composition really asks for different menus.
+ *
+ * Hidden sections and hidden blocks are skipped, children included: the
+ * storefront does not render them. Anything they would have asked for is
+ * still answered by the client query if the designer shows them.
+ */
+export const collectMenuSeedArgs = (
+  sections: readonly Section[] | null | undefined
+): MenuQueryArgs[] => {
+  const found = new Map<string, MenuQueryArgs>();
+
+  const visit = (blocks: readonly Block[] | null | undefined) => {
+    if (!Array.isArray(blocks)) return;
+
+    for (const block of blocks) {
+      if (!block || block.hidden) continue;
+
+      if (block.type === NAV_MENU_BLOCK_TYPE) {
+        for (const breakpoint of BREAKPOINTS) {
+          const args = navMenuQueryArgs(block.properties, breakpoint);
+          const key = menuSeedKey(args);
+          if (!found.has(key)) found.set(key, args);
+        }
+      }
+
+      visit(block.blocks);
+    }
+  };
+
+  (Array.isArray(sections) ? sections : []).forEach((section) => {
+    if (section && !section.hidden) visit(section.blocks);
+  });
+
+  return Array.from(found.values());
+};