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

package/src/utils/carousel-ssr.tsx

@@ -0,0 +1,275 @@
+import React from 'react';
+
+import { devWarn } from './dev-warn';
+
+/**
+ * Making `react-multi-carousel` emit its slides on the server.
+ *
+ * ## The bug this exists to end
+ *
+ * The library only renders slides at all when it believes it can size them.
+ * `getInitialState` computes
+ *
+ *   shouldRenderOnSSR = ssr && deviceType && !domFullyLoaded && flexBisis
+ *   shouldRenderAtAll = shouldRenderOnSSR || domFullyLoaded
+ *
+ * and `CarouselItems` returns `null` unless `shouldRenderAtAll`. On the server
+ * `domFullyLoaded` is false — there is no container to measure — so without
+ * `ssr` and `deviceType` every slider shipped an empty
+ * `<ul class="react-multi-carousel-track">`. Measured on a live storefront at
+ * 1440x900: the hero band was 0px at `domcontentloaded` and 850px once
+ * hydrated, so the page opened on its SECOND section and five home-page
+ * carousels were blank at first paint. CLS 0.70 desktop, 1.03 on Fast 3G.
+ *
+ * ## Why the stylesheet below is the fix, not a detail
+ *
+ * Handing the library `ssr`/`deviceType` alone is not enough. It sizes SSR
+ * slides with `flex: 1 0 <100/items>%` — a PERCENTAGE of the track. But
+ * `.react-multi-carousel-list` is `display:flex` and the track is a flex item
+ * with the default `flex: 0 1 auto`, so the track's base size is its content,
+ * and its content is asking for a percentage of the track. Circular: the
+ * browser resolves the percentage against an indefinite basis and the whole
+ * thing collapses to the widest slide's intrinsic width. Measured with the
+ * `width:100%` rule below: track 1440, hero 1440. Without it: track 300,
+ * hero 300 — the original bug plus a broken hero.
+ *
+ * The library cannot fix this itself because it has no stylesheet of its own
+ * to gate; it reverts to measured pixel widths at mount, at which point
+ * `width:100%` is wrong (the track is wider than the viewport by design, it is
+ * what `translate3d` slides). So the rule has to exist for exactly the window
+ * between first paint and mount, and then stop existing. That is the gate
+ * attribute: it is written into the server markup, survives the client's first
+ * (hydrating) render unchanged, and is dropped in an effect once the library's
+ * own `componentDidMount` has measured.
+ *
+ * ## Why `deviceType` is a constant and never `currentBreakpoint`
+ *
+ * `deviceType` names a key of the responsive map, and the library reads
+ * `responsive[deviceType]` on paths that do not null-check it. It must be the
+ * same value on the server and in the client's first render, and there is
+ * exactly one such value: a literal.
+ *
+ * The `currentBreakpoint` prop is NOT that value. It moves on mount —
+ * `theme-placeholder-wrapper` measures `window.innerWidth` outside an iframe
+ * and calls `setCurrentBreakpoint`, and the editor drives it directly. Passing
+ * it would hand the library a `deviceType` that changes underneath it, and on
+ * a map that has no `tablet` band (`slider-block` has only `desktop` and
+ * `mobile`) `getPartialVisibilityGutter` then reads
+ * `responsive['tablet'].paritialVisibilityGutter` and throws — a blank section
+ * for any slider that authored a slide peek, on a tablet, in the editor.
+ * `carousel-ssr.test.tsx` fails if anyone substitutes the prop.
+ *
+ * ## Side effects that are real and deliberately not hidden
+ *
+ * - The library sets `overflow:hidden` on the track only while
+ *   `shouldRenderOnSSR`, reverting to `unset` at mount. In that window,
+ *   deliberately overflowing slide content — a peeking card, an absolutely
+ *   positioned badge — is clipped.
+ * - `shouldShowArrows` is gated on `shouldRenderAtAll`, so arrows now appear in
+ *   the SSR markup. Only the right one: `isInLeftEnd` is true at slide 0, so
+ *   the left arrow is suppressed exactly as it is after mount.
+ * - `Dots` computes `ceil((slides - slidesToShow) / slidesToSlide) + 1`, and
+ *   `slidesToShow` is 0 until mount, so the server emits one dot per slide and
+ *   the mounted carousel emits fewer. The dot list is `position:absolute`, so
+ *   this costs no layout — it is a count that settles, not a shift.
+ * - Every `<li>` carries `aria-hidden="true"` in the SSR markup, because
+ *   `getIfSlideIsVisbile` compares against a `slidesToShow` of 0. It settles at
+ *   mount, and it is the same markup the library ships for every SSR consumer.
+ */
+
+/** Where the carousel's `containerClass` scope is written. */
+export const CAROUSEL_SSR_SCOPE_PREFIX = 'pz-carousel-ssr-';
+
+/**
+ * The gate. Present in the server markup and in the client's first render,
+ * gone once mounted — which is what makes the stylesheet below stop applying
+ * without anything having to rewrite it.
+ */
+export const CAROUSEL_SSR_GATE_ATTRIBUTE = 'data-carousel-ssr';
+
+/**
+ * The `deviceType` every call site hands the library, and the responsive-map
+ * key it therefore has to name. A literal on purpose — see the header.
+ */
+export const CAROUSEL_SSR_DEVICE_TYPE = 'desktop';
+
+/** One band of a `react-multi-carousel` responsive map. */
+export interface CarouselResponsiveBand {
+  breakpoint: { min: number; max: number };
+  items: number;
+  slidesToSlide?: number;
+  partialVisibilityGutter?: number;
+}
+
+export type CarouselResponsiveMap = Record<string, CarouselResponsiveBand>;
+
+/**
+ * An id safe to sit inside an attribute selector and a class name, or null
+ * when there is nothing usable to scope with. Block ids are authored data, so
+ * they are sanitised rather than trusted — the same treatment
+ * `announcement-bar-block` gives the id it scopes its own inline `<style>`
+ * with.
+ *
+ * NULL RATHER THAN A SHARED CONSTANT. A literal fallback would hand every
+ * id-less carousel on a page the same gate value AND the same scope class, so
+ * each one's stylesheet would restyle the other's slides with the wrong item
+ * count — a wrong layout, which is worse than the empty track this module
+ * exists to remove. Refusing to scope is the safe failure: the carousel then
+ * behaves exactly as it did before this module existed.
+ */
+export const carouselSsrScopeId = (raw: unknown): string | null => {
+  const cleaned = String(raw ?? '').replace(/[^a-zA-Z0-9_-]/g, '');
+  return cleaned || null;
+};
+
+/**
+ * The library's own SSR width, formatted the way the library formats it, so
+ * the rule this module emits and the inline style the library writes cannot
+ * express the same number differently.
+ */
+const flexBasisForItems = (items: number): string => (100 / items).toFixed(1);
+
+/**
+ * A band's media query, built from the band itself.
+ *
+ * This is the whole reason the stylesheet is generated from the responsive map
+ * rather than from the breakpoint constants directly: a query written at one
+ * width while the library switches at another would apply the mobile item
+ * count across a range where the mounted carousel applies the desktop one, and
+ * the slides would visibly resize at hydration. Reading both from one object
+ * makes that disagreement unrepresentable.
+ */
+const bandMediaQuery = (band: CarouselResponsiveBand): string | null => {
+  const { min, max } = band.breakpoint || ({} as { min: number; max: number });
+  const parts: string[] = [];
+  if (Number.isFinite(min) && min > 0) parts.push(`(min-width:${min}px)`);
+  if (Number.isFinite(max)) parts.push(`(max-width:${max}px)`);
+  return parts.length > 0 ? `@media ${parts.join(' and ')}` : null;
+};
+
+/**
+ * The gated stylesheet for one carousel.
+ *
+ * Two selectors, both anchored on the gate attribute so the whole sheet dies
+ * at mount, and both narrowed by this carousel's own scope class so a slider
+ * nested inside another slider's slide is not restyled by its parent's item
+ * count. The `!important` on the flex override is not decoration: the value it
+ * overrides is an inline style the library writes on every `<li>`, and nothing
+ * short of `!important` outranks that.
+ */
+export const buildCarouselSsrCss = (
+  scopeId: string,
+  responsive: CarouselResponsiveMap,
+  deviceType: string = CAROUSEL_SSR_DEVICE_TYPE
+): string => {
+  const track = `[${CAROUSEL_SSR_GATE_ATTRIBUTE}="${scopeId}"] .${CAROUSEL_SSR_SCOPE_PREFIX}${scopeId}>.react-multi-carousel-track`;
+
+  let css = `${track}{width:100%;}`;
+
+  Object.keys(responsive || {}).forEach((name) => {
+    // The SSR band needs no rule: its width is the one the library already
+    // wrote inline on each slide.
+    if (name === deviceType) return;
+
+    const band = responsive[name];
+    const items = Number(band?.items);
+    if (!Number.isFinite(items) || items <= 0) return;
+
+    const query = bandMediaQuery(band);
+    if (!query) return;
+
+    css += `${query}{${track}>li{flex:1 0 ${flexBasisForItems(
+      items
+    )}% !important;}}`;
+  });
+
+  return css;
+};
+
+export interface CarouselSsr {
+  /**
+   * Spread onto `<Carousel>`. Together these are what make the library emit
+   * slides instead of `null` — and EMPTY when there is no id to scope the
+   * width rule with, because opting in without that rule collapses the strip.
+   */
+  carouselProps: { ssr: true; deviceType: string } | Record<string, never>;
+  /** Spread onto an ancestor of the carousel. Empty once mounted. */
+  gateProps: Record<string, string>;
+  /** Appended to the carousel's `containerClass`. Empty when unscoped. */
+  scopeClass: string;
+  /** The gated stylesheet, or `null` once mounted. */
+  gateStyle: React.ReactElement | null;
+}
+
+/**
+ * Everything one carousel call site needs, so the two of them cannot drift.
+ *
+ * `remountKey` must be the SAME string the call site hands `<Carousel key>`.
+ * That is not a convenience: `posts-slider-section` puts `currentBreakpoint`
+ * in its key, so switching device in the editor REMOUNTS the carousel, and a
+ * fresh mount is a fresh `domLoaded: false` — the library is back in its SSR
+ * state for one render. A gate that only tracked "has this component mounted
+ * once" would already be false by then, and the remounted carousel would paint
+ * desktop-basis slides for a frame at every breakpoint switch. Keying the gate
+ * to the same string means the gate comes back exactly when the SSR state
+ * does.
+ */
+export const useCarouselSsr = (options: {
+  id: unknown;
+  remountKey: string;
+  responsive: CarouselResponsiveMap;
+}): CarouselSsr => {
+  const { id, remountKey, responsive } = options;
+
+  const scopeId = carouselSsrScopeId(id);
+
+  // `null` rather than `false`, so the very first client render is compared
+  // against a key it cannot equal. That render has to match the server's
+  // byte for byte or React discards the markup it just hydrated — which would
+  // reintroduce the blank first paint this module exists to remove.
+  const [mountedKey, setMountedKey] = React.useState<string | null>(null);
+  React.useEffect(() => {
+    // A passive effect, deliberately: the library's `componentDidMount` runs
+    // during commit, before this, so by the time the gate is dropped the
+    // carousel has already measured its container and written real pixel
+    // widths. Dropping it in a layout effect would race that measurement.
+    setMountedKey(remountKey);
+  }, [remountKey]);
+
+  const gated = mountedKey !== remountKey;
+
+  if (gated && !responsive?.[CAROUSEL_SSR_DEVICE_TYPE]) {
+    // Not fatal — the library simply falls back to rendering nothing until
+    // mount, which is the behaviour that predates this module. Worth saying
+    // out loud, because the failure is silent and looks like the old bug.
+    devWarn(
+      'carousel-ssr',
+      `Responsive map has no "${CAROUSEL_SSR_DEVICE_TYPE}" band, so slides cannot be server-rendered`
+    );
+  }
+
+  if (scopeId === null) {
+    // No id to scope with, so the width rule cannot be written. Opting into
+    // the library's SSR path WITHOUT that rule is the worst of the three
+    // outcomes: the track is a flex item with an indefinite width, so the
+    // percentage basis the library writes on each slide collapses the whole
+    // strip to a few hundred pixels. Staying off the SSR path leaves the empty
+    // track this module exists to remove, which at least looks like the bug it
+    // is rather than a broken layout.
+    return {
+      carouselProps: {},
+      gateProps: {},
+      scopeClass: '',
+      gateStyle: null
+    };
+  }
+
+  return {
+    carouselProps: { ssr: true, deviceType: CAROUSEL_SSR_DEVICE_TYPE },
+    gateProps: gated ? { [CAROUSEL_SSR_GATE_ATTRIBUTE]: scopeId } : {},
+    scopeClass: `${CAROUSEL_SSR_SCOPE_PREFIX}${scopeId}`,
+    gateStyle: gated ? (
+      <style>{buildCarouselSsrCss(scopeId, responsive)}</style>
+    ) : null
+  };
+};