@akinon/pz-theme 2.0.136-rc.0 → 2.0.137-beta.0

package/src/blocks/listing-density-store.ts

@@ -0,0 +1,303 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import {
+  DESKTOP_MIN_WIDTH,
+  TABLET_MEDIA_QUERY_COMPACT,
+  TABLET_MIN_WIDTH
+} from '../utils/breakpoints';
+
+/**
+ * The shopper's grid density, shared between whoever offers it and the grid
+ * that draws it (ZERO-5151).
+ *
+ * The switcher used to live inside the product grid, so a piece of React state
+ * was all it needed. Brands draw it in the listing toolbar instead — next to
+ * the filter and sort controls, well away from the grid — so it is now a block
+ * of its own, and two blocks that never see each other need one answer to
+ * "how many across". A module store read through `useSyncExternalStore` is the
+ * same shape `browse-mode.ts` and the auth flow bus already use.
+ *
+ * The choice is kept per band, not as one number. A phone offered 1 or 2 and a
+ * desktop offered 2, 3 or 4 are different questions, and a desktop answer of 4
+ * must not follow the shopper onto a phone — or onto the same tablet turned
+ * sideways.
+ *
+ * Nothing here runs on the server: every write happens in an event handler or
+ * an effect, and the server snapshot is always empty. A module-level store on
+ * the server would otherwise be shared by every request the process serves.
+ */
+
+export type DensityBand = 'desktop' | 'tablet' | 'mobile';
+
+/** Widest first, the order the editor authors them in. */
+export const DENSITY_BANDS: readonly DensityBand[] = [
+  'desktop',
+  'tablet',
+  'mobile'
+];
+
+export type DensityCounts = Partial<Record<DensityBand, number>>;
+
+export type DensityOptionSets = Record<DensityBand, number[]>;
+
+/**
+ * One media query per band, and unlike the theme's mobile query they do not
+ * overlap: a choice made on a phone is a statement about phones only. Written
+ * compact to sit beside the grid's own compact queries.
+ */
+export const DENSITY_BAND_MEDIA_QUERIES: Record<DensityBand, string> = {
+  desktop: `@media (min-width:${DESKTOP_MIN_WIDTH}px)`,
+  tablet: TABLET_MEDIA_QUERY_COMPACT,
+  mobile: `@media (max-width:${TABLET_MIN_WIDTH - 1}px)`
+};
+
+/**
+ * Who a choice belongs to.
+ *
+ * The standalone block speaks for the page: every grid on it that carries no
+ * switcher of its own follows it. A grid that does carry its own switcher
+ * answers only to that switcher, under its own scope — which is how that
+ * switcher always behaved, so a page with two grids does not find one
+ * rearranging the other.
+ */
+export const LISTING_DENSITY_SCOPE = 'listing';
+
+export const gridDensityScope = (gridId: string) => `grid:${gridId}`;
+
+export interface ListingDensitySnapshot {
+  /**
+   * The shopper's choice per band, but only where a mounted switcher of the
+   * same scope still offers it. A count remembered from another page, or from
+   * a switcher the designer has since removed, applies nowhere.
+   */
+  applied: DensityCounts;
+  /** What the grid shows per band before any choice — its authored counts. */
+  authored: DensityCounts;
+}
+
+/**
+ * Remembered for the session: a shopper who chose a denser grid expects it to
+ * survive paging through the category, and to be forgotten by the time they
+ * come back tomorrow.
+ */
+const STORAGE_KEY = 'pz-listing-density';
+
+const EMPTY_SNAPSHOT: ListingDensitySnapshot = Object.freeze({
+  applied: Object.freeze({}),
+  authored: Object.freeze({})
+});
+
+interface ScopedEntry<T> {
+  scope: string;
+  value: T;
+}
+
+let choice: Record<string, DensityCounts> = {};
+let hasLoaded = false;
+
+const offered = new Map<symbol, ScopedEntry<DensityOptionSets>>();
+const authoredByGrid = new Map<symbol, ScopedEntry<DensityCounts>>();
+const listeners = new Set<() => void>();
+
+/**
+ * Built on first read after each change and kept until the next one, so every
+ * read in between returns the same object — what `useSyncExternalStore`
+ * requires of a snapshot.
+ */
+let snapshots = new Map<string, ListingDensitySnapshot>();
+
+const isCount = (value: unknown): value is number =>
+  typeof value === 'number' &&
+  Number.isInteger(value) &&
+  value >= 1 &&
+  value <= 6;
+
+const readCounts = (raw: unknown): DensityCounts => {
+  const counts: DensityCounts = {};
+  if (!raw || typeof raw !== 'object') return counts;
+
+  DENSITY_BANDS.forEach((band) => {
+    const value = (raw as Record<string, unknown>)[band];
+    if (isCount(value)) counts[band] = value;
+  });
+
+  return counts;
+};
+
+const readStoredChoice = (): Record<string, DensityCounts> => {
+  // sessionStorage throws in Safari private mode.
+  try {
+    const parsed = JSON.parse(
+      window.sessionStorage.getItem(STORAGE_KEY) || '{}'
+    ) as Record<string, unknown>;
+    const stored: Record<string, DensityCounts> = {};
+
+    Object.keys(parsed || {}).forEach((scope) => {
+      const counts = readCounts(parsed[scope]);
+      if (Object.keys(counts).length > 0) stored[scope] = counts;
+    });
+
+    return stored;
+  } catch {
+    return {};
+  }
+};
+
+const writeStoredChoice = () => {
+  try {
+    window.sessionStorage.setItem(STORAGE_KEY, JSON.stringify(choice));
+  } catch {
+    // A storage failure only costs the shopper the memory of the choice.
+  }
+};
+
+const buildSnapshot = (scope: string): ListingDensitySnapshot => {
+  const scoped = choice[scope] || {};
+  const applied: DensityCounts = {};
+
+  DENSITY_BANDS.forEach((band) => {
+    const count = scoped[band];
+    if (count === undefined) return;
+
+    for (const entry of Array.from(offered.values())) {
+      if (entry.scope === scope && entry.value[band].includes(count)) {
+        applied[band] = count;
+        return;
+      }
+    }
+  });
+
+  // The grid mounted last is the one on screen; there is normally just one.
+  let authored: DensityCounts = {};
+  authoredByGrid.forEach((entry) => {
+    if (entry.scope === scope) authored = entry.value;
+  });
+
+  return { applied, authored };
+};
+
+const publish = () => {
+  snapshots = new Map();
+  listeners.forEach((listener) => listener());
+};
+
+/**
+ * The stored choice is read on first subscription rather than at import: the
+ * module is evaluated on the server too, where there is no storage to read.
+ */
+const loadOnce = () => {
+  if (hasLoaded || typeof window === 'undefined') return;
+
+  hasLoaded = true;
+  const stored = readStoredChoice();
+
+  Object.keys(choice).forEach((scope) => {
+    stored[scope] = { ...stored[scope], ...choice[scope] };
+  });
+  choice = stored;
+};
+
+const subscribe = (listener: () => void): (() => void) => {
+  listeners.add(listener);
+
+  if (!hasLoaded) {
+    loadOnce();
+    publish();
+  }
+
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+const readSnapshot = (scope: string): ListingDensitySnapshot => {
+  let snapshot = snapshots.get(scope);
+
+  if (!snapshot) {
+    snapshot = buildSnapshot(scope);
+    snapshots.set(scope, snapshot);
+  }
+
+  return snapshot;
+};
+
+const readServerSnapshot = (): ListingDensitySnapshot => EMPTY_SNAPSHOT;
+
+export const useListingDensity = (scope: string): ListingDensitySnapshot =>
+  useSyncExternalStore(
+    subscribe,
+    () => readSnapshot(scope),
+    readServerSnapshot
+  );
+
+/**
+ * A switcher announcing what it offers, from an effect. The returned function
+ * withdraws the offer, and with it any choice only this switcher allowed.
+ */
+export const registerDensityOptions = (
+  scope: string,
+  sets: DensityOptionSets
+): (() => void) => {
+  const token = Symbol('density-options');
+
+  offered.set(token, { scope, value: sets });
+  publish();
+
+  return () => {
+    offered.delete(token);
+    publish();
+  };
+};
+
+/** A grid announcing the counts it draws before any choice, from an effect. */
+export const registerAuthoredColumns = (
+  scope: string,
+  counts: DensityCounts
+): (() => void) => {
+  const token = Symbol('density-authored');
+
+  authoredByGrid.set(token, { scope, value: counts });
+  publish();
+
+  return () => {
+    authoredByGrid.delete(token);
+    publish();
+  };
+};
+
+/**
+ * The shopper picking a count for the band they are looking at. `persist` is
+ * off when the choice should not outlive the page.
+ */
+export const chooseDensity = (
+  scope: string,
+  band: DensityBand,
+  count: number,
+  persist = true
+) => {
+  if (!isCount(count)) return;
+
+  loadOnce();
+  if (choice[scope]?.[band] === count) return;
+
+  choice = { ...choice, [scope]: { ...choice[scope], [band]: count } };
+  if (persist) writeStoredChoice();
+  publish();
+};
+
+/** Test-only: forget every choice, registration and subscriber. */
+export const __resetListingDensityForTests = () => {
+  choice = {};
+  hasLoaded = false;
+  snapshots = new Map();
+  offered.clear();
+  authoredByGrid.clear();
+  listeners.clear();
+
+  try {
+    window.sessionStorage.removeItem(STORAGE_KEY);
+  } catch {
+    // Nothing to forget.
+  }
+};

package/src/blocks/product-grid-block.tsx

@@ -8,7 +8,6 @@ import {
   emitCommerceEvent
 } from '../utils/analytics';
 import {
-  DESKTOP_MIN_WIDTH,
   MOBILE_MEDIA_QUERY_COMPACT,
   TABLET_MEDIA_QUERY_COMPACT
 } from '../utils/breakpoints';
@@ -16,6 +15,20 @@ import { neutralizeStyleTagBreakout } from '../utils/css-safety';
 import ThemeBlock, { Block } from '../theme-block';
 import { hasItemTemplate, ItemTemplateList } from './item-template';
 import { BlockRendererProps } from './block-renderer-registry';
+import DensitySwitcher, {
+  DENSITY_GLYPH_STYLES,
+  DensityGlyphStyle,
+  parseDensityOptions
+} from './density-switcher';
+import {
+  DENSITY_BAND_MEDIA_QUERIES,
+  DENSITY_BANDS,
+  DensityCounts,
+  gridDensityScope,
+  LISTING_DENSITY_SCOPE,
+  registerAuthoredColumns,
+  useListingDensity
+} from './listing-density-store';
 import {
   MoneyCurrencyDisplay,
   MoneyCurrencyPosition,
@@ -42,75 +55,8 @@ const readCount = (value: unknown, fallback: number): number => {
   return Number.isFinite(numeric) && numeric > 0 ? numeric : fallback;
 };
 
-/**
- * Remembered per block for the session: a shopper who chose a denser grid
- * expects it to survive paging through the category, and to be forgotten by
- * the time they come back tomorrow.
- */
-const DENSITY_KEY_PREFIX = 'pz-grid-density:';
-
-const readStoredDensity = (key: string): number | null => {
-  // sessionStorage throws in Safari private mode and is absent during SSR.
-  try {
-    const numeric = Math.round(Number(window.sessionStorage.getItem(key)));
-    return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
-  } catch {
-    return null;
-  }
-};
-
-const writeStoredDensity = (key: string, value: number) => {
-  try {
-    window.sessionStorage.setItem(key, String(value));
-  } catch {
-    // A storage failure only costs the shopper the memory of the choice.
-  }
-};
-
-/** The column counts the designer allows, as an ascending, deduped list. */
-const parseDensityOptions = (raw: string): number[] => {
-  const counts = new Set<number>();
-
-  raw.split(',').forEach((entry) => {
-    const numeric = Math.round(Number(entry.trim()));
-    if (!Number.isFinite(numeric) || numeric < 1 || numeric > 6) return;
-    counts.add(numeric);
-  });
-
-  return Array.from(counts).sort((a, b) => a - b);
-};
-
-/**
- * The switcher's mark: as many bars as the layout has columns, which is how
- * both audited designs draw it — the shopper reads the density rather than a
- * number.
- */
-const DensityGlyph = ({ columns }: { columns: number }) => {
-  const gap = 2;
-  const cell = (16 - gap * (columns - 1)) / columns;
-
-  return (
-    <svg
-      width="16"
-      height="16"
-      viewBox="0 0 16 16"
-      fill="currentColor"
-      aria-hidden="true"
-      {...partAttrs('density-icon')}
-    >
-      {Array.from({ length: columns }, (_, index) => (
-        <rect
-          key={index}
-          x={index * (cell + gap)}
-          y={0}
-          width={cell}
-          height={16}
-          rx={1}
-        />
-      ))}
-    </svg>
-  );
-};
+/** The designer's canvas shows the authored counts, never a choice. */
+const NO_CHOICE: DensityCounts = Object.freeze({});
 
 /**
  * Two things a grid child can be besides a product card.
@@ -325,10 +271,11 @@ const readOption = <T extends string>(
  * context built server side); the editor owns column counts, which card
  * fields appear, the image frame and styling.
  *
- * An optional shopper-facing density switcher (off by default) lets the
- * column count be changed on the page and remembers it for the session; the
- * server always renders the count the designer authored, so the markup is
- * complete before any script runs.
+ * A shopper's density choice — made on the standalone `listing-density` block
+ * or on the switcher this block can carry itself (off by default) — reaches
+ * the grid through `listing-density-store`, per band and remembered for the
+ * session. The server always renders the count the designer authored, so the
+ * markup is complete before any script runs.
  *
  * Two kinds of authored child extend what the grid can express: a child marked
  * `grid-insertion` is a merchandiser tile that takes a cell of the grid, and a
@@ -502,8 +449,11 @@ const ProductGridBlock = ({
       '1,2,4'
     )
   );
-  const densityStyle = String(
-    getResponsiveValue(block.properties?.densityStyle, currentBreakpoint, 'icon')
+  const densityStyle = readOption<DensityGlyphStyle>(
+    block.properties?.densityStyle,
+    currentBreakpoint,
+    DENSITY_GLYPH_STYLES,
+    'icon'
   );
   const densityPosition = String(
     getResponsiveValue(
@@ -535,49 +485,35 @@ const ProductGridBlock = ({
     [densityOptionsRaw]
   );
 
-  // null until the shopper picks one, which is what keeps the server markup and
-  // the first client render identical.
-  const [chosenColumns, setChosenColumns] = React.useState<number | null>(null);
-  // false on the server and on the first client render, for the same reason.
-  const [isNarrowViewport, setIsNarrowViewport] = React.useState(false);
-  const densityKey = `${DENSITY_KEY_PREFIX}${block.id || 'grid'}`;
   const hasSwitcher = showDensitySwitcher && densityOptions.length > 1;
+  const gridId = String(block.id || 'grid').replace(/[^a-zA-Z0-9_-]/g, '');
 
-  React.useEffect(() => {
-    // Read after mount only: the server has no session storage, so deciding
-    // during render would hydrate as a mismatch. The designer always sees the
-    // authored count — a remembered choice there would look like a bug.
-    if (!hasSwitcher || isDesigner) return;
-
-    const stored = readStoredDensity(densityKey);
-    if (stored !== null && densityOptions.includes(stored)) {
-      setChosenColumns(stored);
-    }
-  }, [hasSwitcher, isDesigner, densityKey, densityOptions]);
-
-  React.useEffect(() => {
-    // A real phone gets its column count from the media query the block emits,
-    // never from currentBreakpoint — which is 'desktop' on the storefront no
-    // matter how narrow the viewport is. The switcher has to read the same
-    // cascade to mark the option the shopper is actually looking at, so it
-    // watches the identical cutoff, taken from the same constant the emitted
-    // media query is built from rather than retyped.
-    if (!hasSwitcher || typeof window.matchMedia !== 'function') return;
-
-    const query = window.matchMedia(`(max-width: ${DESKTOP_MIN_WIDTH - 1}px)`);
-    const sync = () => setIsNarrowViewport(query.matches);
-
-    sync();
-
-    // Safari below 14 only carries the deprecated listener pair.
-    if (typeof query.addEventListener === 'function') {
-      query.addEventListener('change', sync);
-      return () => query.removeEventListener('change', sync);
-    }
-
-    query.addListener(sync);
-    return () => query.removeListener(sync);
-  }, [hasSwitcher]);
+  // A grid carrying its own switcher answers only to it, as it always has;
+  // every other grid follows the page's standalone Density Switcher block.
+  const densityScope = hasSwitcher
+    ? gridDensityScope(gridId)
+    : LISTING_DENSITY_SCOPE;
+  // Empty on the server and on the first client render — the store's server
+  // snapshot — which is what keeps the two identical. The designer always
+  // sees the authored count; a remembered choice there would look like a bug.
+  const density = useListingDensity(densityScope);
+  const appliedColumns = isDesigner ? NO_CHOICE : density.applied;
+  // What each band shows before any choice, so a switcher anywhere on the page
+  // can mark the count the shopper is actually looking at.
+  const authoredTablet = columnsTablet ?? columnsMobile;
+  const authoredCounts = React.useMemo<DensityCounts>(
+    () => ({
+      desktop: columnsDesktop,
+      tablet: authoredTablet,
+      mobile: columnsMobile
+    }),
+    [columnsDesktop, authoredTablet, columnsMobile]
+  );
+
+  React.useEffect(
+    () => registerAuthoredColumns(densityScope, authoredCounts),
+    [densityScope, authoredCounts]
+  );
 
   const allProducts = listing?.products || [];
   const products = limit > 0 ? allProducts.slice(0, limit) : allProducts;
@@ -686,7 +622,6 @@ const ProductGridBlock = ({
   // designer breakpoint only — on the live storefront currentBreakpoint is
   // always 'desktop'. A scoped rule with the same 1023px cutoff the theme CSS
   // generator uses keeps real mobile viewports in sync with the editor.
-  const gridId = String(block.id || 'grid').replace(/[^a-zA-Z0-9_-]/g, '');
   const baseColumns =
     currentBreakpoint === 'tablet'
       ? columnsTablet ?? columnsMobile
@@ -706,18 +641,25 @@ const ProductGridBlock = ({
         }
       : { fontSize: 'inherit' };
 
-  // The three rules below in the order the browser applies them: the authored
-  // base, the mobile override, then an explicit choice. Deriving the mark from
-  // baseColumns alone highlighted the desktop count on every phone.
-  const activeColumns =
-    chosenColumns ?? (isNarrowViewport ? columnsMobile : baseColumns);
-
+  // One set for every band: this switcher predates per-device counts, which
+  // are the standalone block's to offer. The marks are still per band, so a
+  // tablet no longer highlights the phone's count.
   const densitySwitcher = hasSwitcher ? (
-    <div
-      data-product-grid-density=""
-      {...partAttrs('density')}
-      role="group"
-      aria-label={densityAriaLabel}
+    <DensitySwitcher
+      host="product-grid"
+      scope={densityScope}
+      defaultCounts={authoredCounts}
+      switcherId={`${gridId}-density`}
+      optionSets={{
+        desktop: densityOptions,
+        tablet: densityOptions,
+        mobile: densityOptions
+      }}
+      glyph={densityStyle}
+      label={densityLabel}
+      ariaLabel={densityAriaLabel}
+      isDesigner={isDesigner}
+      currentBreakpoint={currentBreakpoint}
       style={{
         display: 'flex',
         alignItems: 'center',
@@ -725,49 +667,7 @@ const ProductGridBlock = ({
         marginBottom: densityPosition === 'after' ? undefined : '12px',
         marginTop: densityPosition === 'after' ? '12px' : undefined
       }}
-    >
-      {densityLabel && (
-        <span
-          data-product-grid-density-label=""
-          {...partAttrs('density-label')}
-        >
-          {densityLabel}
-        </span>
-      )}
-      {densityOptions.map((count) => {
-        const isActive = count === activeColumns;
-
-        return (
-          <button
-            key={count}
-            type="button"
-            data-product-grid-density-option={String(count)}
-            {...partAttrs('density-option', { selected: isActive })}
-            aria-pressed={isActive}
-            aria-label={String(count)}
-            onClick={() => {
-              setChosenColumns(count);
-              // Writing the author's canvas experiments into their own session
-              // would follow them onto the storefront.
-              if (!isDesigner) writeStoredDensity(densityKey, count);
-            }}
-            style={{
-              display: 'inline-flex',
-              alignItems: 'center',
-              background: 'none',
-              border: 'none',
-              padding: '4px',
-              cursor: 'pointer',
-              color: 'inherit',
-              font: 'inherit',
-              opacity: isActive ? 1 : 0.45
-            }}
-          >
-            {densityStyle === 'number' ? count : <DensityGlyph columns={count} />}
-          </button>
-        );
-      })}
-    </div>
+    />
   ) : null;
 
   const insertionTiles = placedInsertions.map((insertion, index) => (
@@ -976,17 +876,24 @@ const ProductGridBlock = ({
                   ) +
                   `}`
                 : '') +
-              // Last and unconditional, so an explicit choice outranks both the
-              // authored count and the mobile override above it.
-              (chosenColumns !== null
-                ? `[data-product-grid-id="${gridId}"]{grid-template-columns:repeat(${chosenColumns},minmax(0,1fr));}` +
+              // Last, so an explicit choice outranks the authored count and
+              // the overrides above it — each inside its own band, so a
+              // choice made on a phone never reaches a tablet or a desktop.
+              DENSITY_BANDS.map((band) => {
+                const chosen = appliedColumns[band];
+                if (chosen === undefined) return '';
+
+                return (
+                  `${DENSITY_BAND_MEDIA_QUERIES[band]}{[data-product-grid-id="${gridId}"]{grid-template-columns:repeat(${chosen},minmax(0,1fr));}` +
                   buildInsertionRules(
                     gridId,
                     placedInsertions,
-                    chosenColumns,
+                    chosen,
                     currentPage
-                  )
-                : '')
+                  ) +
+                  `}`
+                );
+              }).join('')
           )
         }}
       />