@akinon/pz-theme 2.0.141-rc.0 → 2.0.142-beta.0

package/CHANGELOG.md

@@ -1,40 +1,20 @@
 # @akinon/pz-theme
 
-## 2.0.141-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 [1595d458e]
-- Updated dependencies [dca128112]
-  - @akinon/next@2.0.141-rc.0
-  - @akinon/theme-contract@2.0.141-rc.0
+## 2.0.142-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.142-beta.0
+  - @akinon/theme-contract@2.0.142-beta.0
+
+## 2.0.141
+
+### Patch Changes
+
+- cd9f6c4: ZERO-5190: Hide carousel arrows with CSS instead of removing them from the markup
+  - @akinon/next@2.0.141
+  - @akinon/theme-contract@2.0.141
 
 ## 2.0.140
 

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.141-rc.0",
+  "version": "2.0.142-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.141-rc.0",
+    "@akinon/next": "2.0.142-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.141-rc.0",
+    "@akinon/theme-contract": "2.0.142-beta.0",
     "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.141-rc.0",
+    "@akinon/next": "2.0.142-beta.0",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/blocks/slider-block.tsx

@@ -18,7 +18,11 @@ import {
   isNarrowBreakpoint,
   setAtAnyBreakpoint
 } from '../utils/breakpoints';
-import { useCarouselSsr } from '../utils/carousel-ssr';
+import {
+  buildCarouselArrowCss,
+  carouselSsrScopeId,
+  useCarouselSsr
+} from '../utils/carousel-ssr';
 import {
   authoredSlideIndex,
   TIMER_SLIDE_CHANGE_CEILING
@@ -306,6 +310,29 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
     currentBreakpoint,
     true
   );
+  /**
+   * Whether the arrow EXISTS is settled without the breakpoint; which widths
+   * it is visible at is settled in CSS below. Unauthored still means on, the
+   * same default `showArrows` carries.
+   */
+  const arrowsConfigured = getConfigEntry('show-arrows');
+  const arrowsAnywhere =
+    arrowsConfigured === undefined || arrowsConfigured === null
+      ? true
+      : setAtAnyBreakpoint(arrowsConfigured);
+  // Not `itemsShown`: that is breakpoint-derived, so it would put the flip
+  // back. One slide can never overflow at any width.
+  const canOverflow = visibleCount > 1;
+  const renderArrows = arrowsAnywhere && canOverflow;
+
+  const arrowCss = buildCarouselArrowCss(
+    carouselSsrScopeId(block.id) || '',
+    carouselResponsive,
+    (band) =>
+      getResponsiveValue(arrowsConfigured, band, true) === true &&
+      visibleCount > Number(carouselResponsive?.[band]?.items || 1)
+  );
+
   const showDots = getResponsiveValue(
     getConfigEntry('show-dots'),
     currentBreakpoint,
@@ -1257,13 +1284,7 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
            * `posts-slider-section` folds the same test into its own
            * `showArrows`.
            */
-          arrows={
-            isDesigner
-              ? false
-              : Boolean(showArrows) &&
-                !arrowsOutside &&
-                visibleCount > itemsShown
-          }
+          arrows={isDesigner ? false : renderArrows && !arrowsOutside}
           showDots={Boolean(showDots)}
           customDot={<CustomDot onSelect={handleDotSelect} />}
           renderDotsOutside={Boolean(showDots)}
@@ -1299,18 +1320,12 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
            */
           {...(useLeadIn ? { additionalTransfrom: edgeOffset } : {})}
           customLeftArrow={
-            !isDesigner &&
-            showArrows &&
-            !arrowsOutside &&
-            visibleCount > itemsShown ? (
+            !isDesigner && renderArrows && !arrowsOutside ? (
               <CustomLeftArrow />
             ) : undefined
           }
           customRightArrow={
-            !isDesigner &&
-            showArrows &&
-            !arrowsOutside &&
-            visibleCount > itemsShown ? (
+            !isDesigner && renderArrows && !arrowsOutside ? (
               <CustomRightArrow />
             ) : undefined
           }
@@ -1405,6 +1420,9 @@ const SliderBlock: React.FC<BlockRendererProps> = ({
         nothing.
       */}
       {carouselSsr.gateStyle}
+      {arrowCss ? (
+        <style dangerouslySetInnerHTML={{ __html: arrowCss }} />
+      ) : null}
     </div>
   );
 };

package/src/sections/posts-slider-section.tsx

@@ -25,7 +25,11 @@ import {
   TABLET_MIN_WIDTH,
   setAtAnyBreakpoint
 } from '../utils/breakpoints';
-import { useCarouselSsr } from '../utils/carousel-ssr';
+import {
+  buildCarouselArrowCss,
+  carouselSsrScopeId,
+  useCarouselSsr
+} from '../utils/carousel-ssr';
 import {
   authoredSlideIndex,
   TIMER_SLIDE_CHANGE_CEILING
@@ -492,12 +496,21 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
   const gap = parseNumber(gapValue, 16);
   const slidePadding = gap > 0 ? gap / 2 : 0;
 
-  const showArrows =
-    getResponsiveValue(
-      getConfigEntry('show-arrows'),
-      currentBreakpoint,
-      true
-    ) === true && visibleCount > itemsPerView;
+  /**
+   * Whether the arrow EXISTS is settled without the breakpoint; which widths
+   * it is visible at is settled in CSS. Reading it through
+   * `currentBreakpoint` meant three nodes arrived or vanished one commit
+   * after hydration — arrows a phone is not meant to have, flashed and then
+   * removed, and a tablet getting them late with a layout shift.
+   */
+  const arrowsConfigured = getConfigEntry('show-arrows');
+  const arrowsAnywhere =
+    arrowsConfigured === undefined || arrowsConfigured === null
+      ? true
+      : setAtAnyBreakpoint(arrowsConfigured);
+  // Not `itemsPerView`: that is breakpoint-derived and would put the flip
+  // back. One slide can never overflow at any width.
+  const showArrows = arrowsAnywhere && visibleCount > 1;
   const showDots =
     getResponsiveValue(
       getConfigEntry('show-dots'),
@@ -548,6 +561,16 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
 
   // Server-render the slides. Without this the strip ships an empty track and
   // occupies no height until hydration — see `utils/carousel-ssr`.
+  const arrowScopeId = carouselSsrScopeId(section.id) || '';
+  const arrowCss = buildCarouselArrowCss(
+    arrowScopeId,
+    carouselResponsive,
+    (band) =>
+      getResponsiveValue(arrowsConfigured, band, true) === true &&
+      visibleCount > Number(carouselResponsive?.[band]?.items || 1),
+    `[data-section-id="${arrowScopeId}"]`
+  );
+
   const carouselSsr = useCarouselSsr({
     id: section.id,
     remountKey: carouselKey,
@@ -1128,6 +1151,9 @@ const PostsSliderSection: React.FC<PostsSliderSectionProps> = ({
           from being early.
         */}
         {carouselSsr.gateStyle}
+        {arrowCss ? (
+          <style dangerouslySetInnerHTML={{ __html: arrowCss }} />
+        ) : null}
       </div>
 
       {/*

package/src/utils/__tests__/carousel-arrow-css.test.ts

@@ -0,0 +1,75 @@
+import { buildCarouselArrowCss } from '../carousel-ssr';
+
+/**
+ * Arrow visibility moved out of the markup and into CSS.
+ *
+ * Deciding whether the arrow EXISTS from `currentBreakpoint` meant three
+ * nodes appeared or disappeared one commit after hydration, because that
+ * value is seeded 'desktop' and corrected only once the viewport is measured.
+ * Rendered at every width and hidden per band, the markup is settled before
+ * the first paint.
+ */
+const RESPONSIVE = {
+  desktop: { items: 4, breakpoint: { min: 1024, max: 99999 } },
+  tablet: { items: 3, breakpoint: { min: 768, max: 1023 } },
+  mobile: { items: 1, breakpoint: { min: 0, max: 767 } }
+} as any;
+
+describe('buildCarouselArrowCss', () => {
+  it('emits nothing when the arrow is wanted at every band', () => {
+    expect(buildCarouselArrowCss('abc', RESPONSIVE, () => true)).toBe('');
+  });
+
+  it('hides only the bands that said no', () => {
+    const css = buildCarouselArrowCss(
+      'abc',
+      RESPONSIVE,
+      (band) => band !== 'mobile'
+    );
+
+    expect(css).toContain('(max-width:767px)');
+    expect(css).not.toContain('(min-width:1024px)');
+    expect(css).toContain('display:none !important');
+  });
+
+  it('scopes the library arrow to this carousel', () => {
+    const css = buildCarouselArrowCss('abc', RESPONSIVE, () => false);
+
+    // A slider nested inside another slider's slide must not be restyled by
+    // its parent's answer.
+    expect(css).toContain('.pz-carousel-ssr-abc .react-multi-carousel-arrow');
+  });
+
+  it('covers a section-rendered arrow only when given its scope', () => {
+    const without = buildCarouselArrowCss('abc', RESPONSIVE, () => false);
+    expect(without).not.toContain('data-slider-arrow');
+
+    const withOwner = buildCarouselArrowCss(
+      'abc',
+      RESPONSIVE,
+      () => false,
+      '[data-section-id="abc"]'
+    );
+    expect(withOwner).toContain('[data-section-id="abc"] [data-slider-arrow]');
+  });
+
+  it('skips a band with no width range rather than hiding everywhere', () => {
+    // Hiding the arrow at every width is the one outcome worse than showing
+    // it late, so a band that cannot be targeted is left alone.
+    const css = buildCarouselArrowCss(
+      'abc',
+      { odd: { items: 2, breakpoint: {} } } as any,
+      () => false
+    );
+
+    expect(css).toBe('');
+  });
+
+  it('gives the same answer however many times it is asked', () => {
+    const once = buildCarouselArrowCss('abc', RESPONSIVE, (b) => b === 'desktop');
+    const twice = buildCarouselArrowCss('abc', RESPONSIVE, (b) => b === 'desktop');
+
+    // Server and first client render build this string independently.
+    expect(once).toBe(twice);
+  });
+});

package/src/utils/carousel-ssr.tsx

@@ -186,6 +186,54 @@ export const buildCarouselSsrCss = (
   return css;
 };
 
+/**
+ * Arrow visibility for one carousel, as CSS instead of as markup.
+ *
+ * `show-arrows` is authored per breakpoint, but `currentBreakpoint` is
+ * seeded desktop and corrected only after the viewport is measured — so
+ * deciding whether the arrow EXISTS from it meant three nodes appeared or
+ * disappeared one commit after the page became interactive. A phone briefly
+ * showed arrows it is not meant to have, a tablet got them late with a layout
+ * shift, and anything holding a reference to one lost it.
+ *
+ * Rendered at every width and hidden per band, the answer is settled before
+ * the first paint and never changes. Anchored on the scope class rather than
+ * the gate attribute, because unlike the SSR stylesheet this one has to
+ * outlive hydration.
+ */
+export const buildCarouselArrowCss = (
+  scopeId: string,
+  responsive: CarouselResponsiveMap,
+  isOnAtBand: (bandName: string) => boolean,
+  /** Scope for arrows a section renders OUTSIDE the carousel box. */
+  ownerSelector?: string
+): string => {
+  const scope = `.${CAROUSEL_SSR_SCOPE_PREFIX}${scopeId}`;
+  // The library writes its own arrows; `data-slider-arrow` is the hook for
+  // the ones a section renders itself, outside the carousel box.
+  const targets = [
+    `${scope} .react-multi-carousel-arrow`,
+    ownerSelector ? `${ownerSelector} [data-slider-arrow]` : null
+  ]
+    .filter(Boolean)
+    .join(',');
+
+  let css = "";
+
+  Object.keys(responsive || {}).forEach((name) => {
+    if (isOnAtBand(name)) return;
+
+    const query = bandMediaQuery(responsive[name]);
+    // A band with no width range cannot be targeted without hiding the arrow
+    // everywhere, which is the one outcome worse than showing it late.
+    if (!query) return;
+
+    css += `${query}{${targets}{display:none !important;}}`;
+  });
+
+  return css;
+};
+
 export interface CarouselSsr {
   /**
    * Spread onto `<Carousel>`. Together these are what make the library emit

package/src/utils/slider-arrows.tsx

@@ -212,6 +212,10 @@ export const SliderArrow: React.FC<SliderArrowProps> = ({
       // The generated stylesheet finds the arrow through this, which is what
       // carries states, part keys and the custom-CSS hatch onto it.
       data-block-id={block?.id}
+      // Visibility is CSS, not markup: the arrow ships at every width and the
+      // carousel stylesheet hides it where it is not wanted, so nothing
+      // appears or disappears a commit after hydration.
+      data-slider-arrow=""
       onClick={(event) => {
         event.preventDefault();
         event.stopPropagation();