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

package/src/blocks/nav-menu-block.tsx

@@ -5,8 +5,10 @@ import NextLink from 'next/link';
 import { usePathname } from 'next/navigation';
 import { useGetMenuQuery } from '@akinon/next/data/client/misc';
 import { getResponsiveValue, partAttrs, resolveForceOpen } from '../utils';
+import { useMenuSeed } from '../menu-seed-context';
 import { BlockRendererProps } from './block-renderer-registry';
 import { hasItemTemplate, ItemTemplateList } from './item-template';
+import { navMenuQueryArgs } from './menu-query-args';
 import {
   MenuSeparator,
   MenuTrailingFill,
@@ -53,12 +55,9 @@ const NavMenuBlock = ({
   const pathname = usePathname();
   const [openKey, setOpenKey] = useState<string | null>(null);
 
-  const depth = Number(
-    getResponsiveValue(block.properties?.depth, currentBreakpoint, 1)
-  );
-  const parent = block.properties?.parent
-    ? String(getResponsiveValue(block.properties.parent, currentBreakpoint, ''))
-    : undefined;
+  // Shared with the server's menu collector, so the key it seeded under is the
+  // key this block looks up (see menu-query-args.ts).
+  const menuArgs = navMenuQueryArgs(block.properties, currentBreakpoint);
   const orientation = String(
     getResponsiveValue(
       block.properties?.orientation,
@@ -143,10 +142,22 @@ const NavMenuBlock = ({
     return current === target;
   };
 
-  const { data: menu, isLoading } = useGetMenuQuery({
-    depth: Number.isFinite(depth) && depth > 0 ? depth : 1,
-    ...(parent ? { parent } : {})
-  } as Parameters<typeof useGetMenuQuery>[0]);
+  // A server-fetched menu is render input, not cache: the server HTML and the
+  // first client render both draw it, and the request is skipped. Without one
+  // (no server render, a failed fetch, a depth the server did not see) the
+  // block fetches on the client exactly as it always has.
+  //
+  // The seed wins whenever there is one. A skipped RTK query does not clear
+  // `data` (1.9.7 and 2.x alike): it keeps the last result of whatever args it
+  // ran with before. So a block moved from an unseeded key back to a seeded
+  // one (a designer undo, a breakpoint switch) would otherwise keep drawing
+  // the menu it fetched for the OTHER key.
+  const seeded = useMenuSeed(menuArgs);
+  const { data: fetched, isLoading } = useGetMenuQuery(
+    menuArgs as Parameters<typeof useGetMenuQuery>[0],
+    { skip: seeded !== undefined }
+  );
+  const menu = seeded !== undefined ? seeded : fetched;
 
   const allItems: MenuItemLike[] = Array.isArray(menu) ? menu : [];
   const items =

package/src/chrome/__tests__/chrome-mode.test.ts

@@ -1,6 +1,7 @@
 import {
   CHROME_MODE_ATTRIBUTE,
   CHROME_MODE_DOCKED,
+  chromeModeAttrs,
   setChromeMode
 } from '../chrome-mode';
 
@@ -45,8 +46,11 @@ describe('stamping', () => {
   });
 
   it('writes to body rather than to the chrome slot', () => {
-    // The selector is `body[data-chrome-mode~="docked"] &`. Stamping the slot
-    // instead would match nothing at all, silently.
+    // This is the selector's `body[data-chrome-mode~="docked"] &` branch — the
+    // one the designer pin, a browser without `:has` and hand-written CSS all
+    // match. The element attribute the `:has` branch reads is rendered by the
+    // header (`chromeModeAttrs`), never written here; stamping the slot from
+    // this function would leave the body branch matching nothing, silently.
     document.body.innerHTML = '<div data-chrome-slot="header"></div>';
 
     setChromeMode(CHROME_MODE_DOCKED);
@@ -172,3 +176,32 @@ describe('on the server', () => {
     expect(typeof document).toBe('object');
   });
 });
+
+describe('chromeModeAttrs', () => {
+  it('renders the docked token under the attribute the selector reads', () => {
+    expect(chromeModeAttrs(CHROME_MODE_DOCKED)).toEqual({
+      [CHROME_MODE_ATTRIBUTE]: 'docked'
+    });
+  });
+
+  it('renders nothing at all for overlay, not an empty attribute', () => {
+    // Absent is what overlay has always meant; an empty value would also fail
+    // the `~="docked"` token match, but it reads as a bug in devtools.
+    expect(chromeModeAttrs(null)).toEqual({});
+  });
+
+  it('never touches the document, so a server-rendered header may call it', () => {
+    chromeModeAttrs(CHROME_MODE_DOCKED);
+
+    expect(mode()).toBeNull();
+  });
+
+  it('hands back a fresh object per call', () => {
+    const first = chromeModeAttrs(CHROME_MODE_DOCKED);
+    first['data-extra'] = 'mine';
+
+    expect(chromeModeAttrs(CHROME_MODE_DOCKED)).toEqual({
+      [CHROME_MODE_ATTRIBUTE]: 'docked'
+    });
+  });
+});

package/src/chrome/__tests__/menu-seed-source.test.ts

@@ -0,0 +1,186 @@
+/**
+ * The server's menu fetch for nav-menu blocks: what it asks for, and that no
+ * failure of it can do worse than today's client fetch.
+ *
+ * A key the loader leaves out is not an error — the block finds no seed and
+ * requests the menu on the client, as it always did. So every failure mode
+ * here (a throw, a non-array answer, a core without `getMenu`) has to end as
+ * an ABSENT key, never as an empty row that would suppress that request.
+ */
+jest.mock('server-only', () => ({}), { virtual: true });
+
+const getMenu = jest.fn();
+// Flipped off to model an old core whose server data layer has no reader.
+let getMenuExported = true;
+
+jest.mock('@akinon/next/data/server', () => ({
+  get getMenu() {
+    return getMenuExported
+      ? (...args: unknown[]) =>
+          (getMenu as (...a: unknown[]) => unknown)(...args)
+      : undefined;
+  }
+}));
+
+import { loadMenuSeeds, MENU_SEED_TIMEOUT_MS } from '../menu-seed-source';
+
+const block = (
+  type: string,
+  properties: Record<string, unknown> = {},
+  over: Record<string, unknown> = {}
+): any => ({
+  id: `${type}-1`,
+  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 rows = [{ pk: 1, label: 'Women', url: '/women', children: [] }];
+
+beforeEach(() => {
+  getMenu.mockReset();
+  getMenuExported = true;
+});
+
+describe('loadMenuSeeds', () => {
+  it('makes no request for a composition without a nav-menu', async () => {
+    const seeds = await loadMenuSeeds([
+      section([block('text'), block('mega-menu'), block('hamburger-menu')])
+    ]);
+
+    expect(seeds).toEqual({});
+    expect(getMenu).not.toHaveBeenCalled();
+  });
+
+  it('makes no request for no sections', async () => {
+    expect(await loadMenuSeeds([])).toEqual({});
+    expect(await loadMenuSeeds(null)).toEqual({});
+    expect(getMenu).not.toHaveBeenCalled();
+  });
+
+  it('seeds each distinct menu under its key, asking with the block args', async () => {
+    getMenu.mockImplementation(async ({ depth }: { depth: number }) =>
+      depth === 1 ? rows : [{ pk: 2, label: 'Deep', url: '/deep' }]
+    );
+
+    const seeds = await loadMenuSeeds([
+      section([block('nav-menu', { depth: { desktop: 1, mobile: 2 } })])
+    ]);
+
+    expect(getMenu).toHaveBeenCalledTimes(2);
+    expect(getMenu).toHaveBeenCalledWith({ depth: 1 });
+    expect(getMenu).toHaveBeenCalledWith({ depth: 2 });
+    expect(seeds).toEqual({
+      '1|': rows,
+      '2|': [{ pk: 2, label: 'Deep', url: '/deep' }]
+    });
+  });
+
+  it('passes the parent through, and keys by it', async () => {
+    getMenu.mockResolvedValue(rows);
+
+    const seeds = await loadMenuSeeds([
+      section([block('nav-menu', { depth: 2, parent: 'women' })])
+    ]);
+
+    expect(getMenu).toHaveBeenCalledWith({ depth: 2, parent: 'women' });
+    expect(seeds).toEqual({ '2|women': rows });
+  });
+
+  it('keeps an empty menu — it is the answer the client would get too', async () => {
+    getMenu.mockResolvedValue([]);
+
+    expect(await loadMenuSeeds([section([block('nav-menu')])])).toEqual({
+      '1|': []
+    });
+  });
+
+  it('leaves a rejected request out, without failing the others', async () => {
+    getMenu.mockImplementation(async ({ depth }: { depth: number }) => {
+      if (depth === 2) throw new Error('menus down');
+      return rows;
+    });
+
+    const seeds = await loadMenuSeeds([
+      section([block('nav-menu', { depth: { desktop: 1, mobile: 2 } })])
+    ]);
+
+    expect(seeds).toEqual({ '1|': rows });
+    expect('2|' in seeds).toBe(false);
+  });
+
+  it.each([
+    ['undefined', undefined],
+    ['null', null],
+    ['an unwrapped response object', { menu: rows }],
+    ['a string', 'error']
+  ])('leaves the key out when the answer is %s', async (_name, answer) => {
+    getMenu.mockResolvedValue(answer);
+
+    const seeds = await loadMenuSeeds([section([block('nav-menu')])]);
+
+    expect(seeds).toEqual({});
+  });
+
+  it('gives up on a menu that outlasts the timeout, keeping the ones that answered', async () => {
+    jest.useFakeTimers();
+    try {
+      getMenu.mockImplementation(({ depth }: { depth: number }) =>
+        depth === 2 ? new Promise(() => undefined) : Promise.resolve(rows)
+      );
+
+      const pending = loadMenuSeeds([
+        section([block('nav-menu', { depth: { desktop: 1, mobile: 2 } })])
+      ]);
+      await jest.advanceTimersByTimeAsync(MENU_SEED_TIMEOUT_MS);
+
+      expect(await pending).toEqual({ '1|': rows });
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('keeps a menu that answers just inside the timeout', async () => {
+    jest.useFakeTimers();
+    try {
+      getMenu.mockImplementation(
+        () =>
+          new Promise((resolve) =>
+            setTimeout(() => resolve(rows), MENU_SEED_TIMEOUT_MS - 1)
+          )
+      );
+
+      const pending = loadMenuSeeds([section([block('nav-menu')])]);
+      await jest.advanceTimersByTimeAsync(MENU_SEED_TIMEOUT_MS);
+
+      expect(await pending).toEqual({ '1|': rows });
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
+  it('seeds nothing on a core without getMenu', async () => {
+    getMenuExported = false;
+
+    expect(await loadMenuSeeds([section([block('nav-menu')])])).toEqual({});
+  });
+});

package/src/chrome/__tests__/use-chrome-mode.test.tsx

@@ -0,0 +1,162 @@
+import React, { useLayoutEffect } from 'react';
+import { act, cleanup, render } from '@testing-library/react';
+import { renderToString } from 'react-dom/server';
+import { hydrateRoot } from 'react-dom/client';
+
+import { CHROME_MODE_ATTRIBUTE, CHROME_MODE_DOCKED } from '../chrome-mode';
+import type { ChromeMode } from '../chrome-mode';
+import { useChromeMode } from '../use-chrome-mode';
+
+/**
+ * The chrome mode on first paint.
+ *
+ * Before this hook the only writer was `setChromeMode`, called from a brand
+ * effect, so the mode reached the page after hydration and every inner page
+ * first painted the transparent overlay header. The hook keeps that `body`
+ * stamp and adds the half that can be in the server HTML: the attribute it
+ * returns, spread on the header's own root, which the `docked` selector's
+ * `body:has(…)` branch reads.
+ *
+ * So both halves are pinned: the markup the SERVER sends (no effect has run
+ * there), and the `body` stamp the client adds and takes away again.
+ */
+
+const mode = () => document.body.getAttribute(CHROME_MODE_ATTRIBUTE);
+
+/** A brand header written the way the README teaches. */
+function Header({ chromeMode }: { chromeMode: ChromeMode }) {
+  const attrs = useChromeMode(chromeMode);
+
+  return (
+    <header data-testid="header" {...attrs}>
+      Store
+    </header>
+  );
+}
+
+afterEach(() => {
+  // Unmount first, so each hook's cleanup restores before the reset below.
+  cleanup();
+  document.body.removeAttribute(CHROME_MODE_ATTRIBUTE);
+});
+
+describe('the server HTML', () => {
+  it('carries data-chrome-mode="docked" on the header root', () => {
+    const html = renderToString(<Header chromeMode={CHROME_MODE_DOCKED} />);
+
+    expect(html).toContain(
+      '<header data-testid="header" data-chrome-mode="docked">'
+    );
+  });
+
+  it('carries no attribute at all for overlay', () => {
+    // Absent is what overlay has always meant, so every page that never
+    // declared a mode renders byte for byte as it did.
+    const html = renderToString(<Header chromeMode={null} />);
+
+    expect(html).not.toContain(CHROME_MODE_ATTRIBUTE);
+  });
+
+  it('does not stamp body while rendering, because no effect runs there', () => {
+    // Which is exactly why the element attribute has to exist: on the server
+    // the body stamp never happens, and in the browser it waits for hydration.
+    renderToString(<Header chromeMode={CHROME_MODE_DOCKED} />);
+
+    expect(mode()).toBeNull();
+  });
+});
+
+describe('the body stamp', () => {
+  it('stamps body on mount and restores it on unmount', () => {
+    const { unmount } = render(<Header chromeMode={CHROME_MODE_DOCKED} />);
+
+    expect(mode()).toBe('docked');
+
+    unmount();
+
+    expect(mode()).toBeNull();
+  });
+
+  it('clears body when the header re-renders from docked to overlay', () => {
+    // A client-side navigation onto the home page: the header stays mounted
+    // and only its mode changes.
+    const { getByTestId, rerender } = render(
+      <Header chromeMode={CHROME_MODE_DOCKED} />
+    );
+
+    expect(mode()).toBe('docked');
+
+    rerender(<Header chromeMode={null} />);
+
+    expect(mode()).toBeNull();
+    expect(getByTestId('header').hasAttribute(CHROME_MODE_ATTRIBUTE)).toBe(
+      false
+    );
+  });
+
+  it('stamps in the layout phase, before the browser paints', () => {
+    // A later sibling's layout effect runs after the header's in the same
+    // commit. If the stamp were a passive effect it would still be missing
+    // here, and a client-side navigation would paint one frame with the
+    // previous route's body stamp.
+    let seenByLaterLayoutEffect: string | null = 'unset';
+
+    function LaterSibling() {
+      useLayoutEffect(() => {
+        seenByLaterLayoutEffect = mode();
+      }, []);
+
+      return null;
+    }
+
+    render(
+      <>
+        <Header chromeMode={CHROME_MODE_DOCKED} />
+        <LaterSibling />
+      </>
+    );
+
+    expect(seenByLaterLayoutEffect).toBe('docked');
+  });
+});
+
+describe('hydrating the server HTML', () => {
+  it('matches the server markup and then stamps body', () => {
+    // The render-time-inputs rule, end to end: the same mode on both sides
+    // hydrates without a mismatch, and the body half arrives afterwards.
+    const container = document.createElement('div');
+    container.innerHTML = renderToString(
+      <Header chromeMode={CHROME_MODE_DOCKED} />
+    );
+    document.body.appendChild(container);
+
+    const consoleError = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => undefined);
+
+    expect(mode()).toBeNull();
+
+    let root: ReturnType<typeof hydrateRoot> | undefined;
+
+    try {
+      act(() => {
+        root = hydrateRoot(
+          container,
+          <Header chromeMode={CHROME_MODE_DOCKED} />
+        );
+      });
+
+      expect(consoleError).not.toHaveBeenCalled();
+      expect(
+        container.querySelector('header')?.getAttribute(CHROME_MODE_ATTRIBUTE)
+      ).toBe('docked');
+      expect(mode()).toBe('docked');
+    } finally {
+      act(() => root?.unmount());
+      consoleError.mockRestore();
+      container.remove();
+    }
+
+    expect(mode()).toBeNull();
+  });
+});

package/src/chrome/chrome-mode.ts

@@ -15,8 +15,22 @@
  *
  * WHO STAMPS IT. The brand, from its own header, exactly as the mega menu
  * stamps `data-overlay-state`. pz-theme supplies the vocabulary and the
- * selector; only the brand knows which of its routes carry a hero. `setChromeMode`
- * below is the one writer, so no brand hand-types the attribute.
+ * selector; only the brand knows which of its routes carry a hero. The
+ * brand's header calls `useChromeMode` (chrome/use-chrome-mode.ts), which does
+ * both writes below, so no brand hand-types the attribute.
+ *
+ * Two writes, because only one of them can be in the server HTML:
+ *
+ *  - `chromeModeAttrs` renders the attribute on the brand's OWN chrome
+ *    element. That is the first-paint signal: it is in the markup the server
+ *    sends, and the selector's `body:has(…)` branch reads it from there, so an
+ *    inner page paints docked before any script has run.
+ *  - `setChromeMode` stamps `body`; the hook calls it from a layout effect,
+ *    so this half only exists once the page has hydrated. It stays because the
+ *    designer pin writes there, because a browser without `:has` only ever
+ *    matches the `body` branch, and because hand-written brand CSS written
+ *    against `body[data-chrome-mode]` has only ever had that element to key
+ *    on.
  *
  * DEFAULT IS OVERLAY, and that is deliberate: the attribute is absent until
  * something declares otherwise, so every composition that existed before this
@@ -31,6 +45,23 @@ export const CHROME_MODE_DOCKED = 'docked';
 
 export type ChromeMode = 'docked' | null;
 
+/**
+ * The attribute to spread on the brand's own chrome element for `mode`.
+ *
+ * Pure, and callable on the server as well as in a client component, which is
+ * the whole point: whatever renders the header puts `data-chrome-mode` in the
+ * server HTML, where the `docked` selector's `body:has(…)` branch finds it on
+ * first paint. Overlay renders NO attribute rather than an empty one — absent
+ * is what overlay has always meant (see DEFAULT IS OVERLAY above).
+ *
+ * A fresh object per call, so a caller may add to it without reaching into
+ * anyone else's.
+ */
+export const chromeModeAttrs = (mode: ChromeMode): Record<string, string> =>
+  mode === CHROME_MODE_DOCKED
+    ? { [CHROME_MODE_ATTRIBUTE]: CHROME_MODE_DOCKED }
+    : {};
+
 /**
  * Stamps or clears the mode on `<body>`.
  *

package/src/chrome/menu-seed-source.ts

@@ -0,0 +1,89 @@
+import 'server-only';
+
+import * as serverData from '@akinon/next/data/server';
+
+import type { Section } from '../theme-section';
+import { collectMenuSeedArgs, menuSeedKey } from '../blocks/menu-query-args';
+import type { MenuQueryArgs, MenuSeeds } from '../blocks/menu-query-args';
+
+export type { MenuSeeds } from '../blocks/menu-query-args';
+
+type GetMenu = (args: MenuQueryArgs) => Promise<unknown>;
+
+/**
+ * How long the page waits for one menu before it gives up and lets the block
+ * fetch it on the client.
+ *
+ * The seed is awaited by ThemePlaceholder, and a brand typically mounts the
+ * header slot in its root layout with no Suspense boundary around it, so every
+ * millisecond spent here is a millisecond before the first byte of EVERY page.
+ * A warm cache answers in a few milliseconds; a cold one is one round trip to
+ * the menu service. When that round trip is slow, a late category row is the
+ * better failure than a late page, and it is exactly today's behaviour. The
+ * request is not cancelled: it still lands in the core cache for the next page.
+ */
+export const MENU_SEED_TIMEOUT_MS = 1000;
+
+const TIMED_OUT = Symbol('menu-seed-timeout');
+
+const withinTimeout = async <T>(
+  pending: Promise<T>
+): Promise<T | undefined> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<typeof TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), MENU_SEED_TIMEOUT_MS);
+  });
+
+  try {
+    const answer = await Promise.race([pending, timeout]);
+    return answer === TIMED_OUT ? undefined : (answer as T);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * The menus a placeholder's nav-menu blocks will ask for, fetched on the
+ * server so the category row is in the served HTML.
+ *
+ * Why not seed the RTK cache instead: brands on the v1 core run RTK 1.9.7,
+ * where `upsertQueryData` is async and `upsertQueryEntries` does not exist.
+ * Nothing can fill the cache before the first render, so the entries travel
+ * as render input — a prop on the wrapper, then context (menu-seed-context.tsx).
+ *
+ * `getMenu` hits the same `/menus/generate/?depth_height=` endpoint as the
+ * client query and returns the same `.menu` array, on v1 and v2 alike, so a
+ * seed is exactly what the block would have fetched.
+ *
+ * Every failure degrades to today's behaviour, never to a broken row: a
+ * request that throws, outlasts MENU_SEED_TIMEOUT_MS or answers with anything
+ * but an array leaves its key out, and the block falls back to the client query for that key. A core
+ * without `getMenu` seeds nothing. A composition with no nav-menu block makes
+ * no request at all.
+ */
+export async function loadMenuSeeds(
+  sections: readonly Section[] | null | undefined
+): Promise<MenuSeeds> {
+  const wanted = collectMenuSeedArgs(sections);
+  if (wanted.length === 0) return {};
+
+  const getMenu = (serverData as unknown as { getMenu?: GetMenu }).getMenu;
+  if (typeof getMenu !== 'function') return {};
+
+  const answers = await Promise.all(
+    wanted.map(async (args): Promise<[string, unknown]> => {
+      try {
+        return [menuSeedKey(args), await withinTimeout(getMenu(args))];
+      } catch {
+        return [menuSeedKey(args), undefined];
+      }
+    })
+  );
+
+  const seeds: MenuSeeds = {};
+  answers.forEach(([key, menu]) => {
+    if (Array.isArray(menu)) seeds[key] = menu;
+  });
+
+  return seeds;
+}

package/src/chrome/use-chrome-mode.ts

@@ -0,0 +1,44 @@
+'use client';
+
+import { useEffect, useLayoutEffect } from 'react';
+
+import { chromeModeAttrs, setChromeMode } from './chrome-mode';
+import type { ChromeMode } from './chrome-mode';
+
+// `useLayoutEffect` warns during SSR under React 18, and every brand header
+// that calls this is server-rendered. On the server neither effect runs, so
+// the swap changes nothing but the warning.
+const useIsomorphicLayoutEffect =
+  typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+/**
+ * Declares the chrome mode from the brand's header, both halves at once.
+ *
+ * Returns the attribute for the header's own root element — spread it there —
+ * and stamps `body` with `setChromeMode` from a layout effect, handing the
+ * effect `setChromeMode`'s own cleanup. The returned attribute is what makes
+ * the first paint right: it is in the server HTML, and the `docked` selector's
+ * `body:has(…)` branch reads it before any script runs. The `body` stamp is the
+ * half the designer pin, a browser without `:has` and hand-written CSS rely on
+ * (see chrome/chrome-mode.ts).
+ *
+ * A LAYOUT effect rather than a plain one, so a client-side navigation cannot
+ * paint a frame with the previous route's `body` stamp still in place — the
+ * element attribute changes in the commit, and the stamp follows before paint.
+ *
+ * COMPUTE `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 hydration expects the
+ * client's first render to produce the same markup. React does not promise to
+ * patch a mismatched attribute while hydrating, so a mode the server could not
+ * compute can leave the server's answer stuck on the header while the effect
+ * writes the other one onto `body`.
+ *
+ * One owner, as with `setChromeMode`: the cleanup restores a snapshot rather
+ * than counting callers, so call this from the one header that owns the mode.
+ */
+export const useChromeMode = (mode: ChromeMode): Record<string, string> => {
+  useIsomorphicLayoutEffect(() => setChromeMode(mode), [mode]);
+
+  return chromeModeAttrs(mode);
+};