@akinon/pz-theme 2.0.100-beta.0 → 2.0.100

package/src/blocks/collapsible-block.tsx

@@ -0,0 +1,595 @@
+'use client';
+
+import React, {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState
+} from 'react';
+import { useLocalization } from '@akinon/next/hooks';
+import { getResponsiveValue, partAttrs, resolveOption } from '../utils';
+import {
+  MOBILE_MEDIA_QUERY_COMPACT,
+  TABLET_MEDIA_QUERY_COMPACT
+} from '../utils/breakpoints';
+import { escapeCssAttributeValue } from '../utils/css-safety';
+import { BlockRendererProps } from './block-renderer-registry';
+import { readToggle } from './product-block-utils';
+import { renderComposedChildren } from './render-composed-children';
+
+/**
+ * Collapsible: clamps whatever is composed inside it to N lines, fades the last
+ * lines out, and offers a read-more trigger underneath.
+ *
+ * It has no content of its own. The article, its headings, the inline link and
+ * the FAQ accordion of a category page's SEO block are all ordinary child
+ * blocks, so each one keeps its own style panel — which is the thing a single
+ * rich-text blob cannot give you: an `<h2>` inside a `dangerouslySetInnerHTML`
+ * payload is unreachable from the inspector.
+ *
+ * THE HIDDEN HALF IS NEVER UNMOUNTED. Expanded and collapsed differ only in
+ * CSS. No `{isExpanded && …}`, no truncated string, no gated payload:
+ * `theme-placeholder.tsx` is `server-only` and hands `initialSections` straight
+ * into the client tree with no `mounted` gate, so the whole composition ships
+ * in the server HTML — which is the entire SEO requirement. `display:none`,
+ * the `hidden` attribute, `content-visibility:hidden` and `inert` are all
+ * forbidden on the clipped region for the same reason: each removes the text
+ * from the accessibility tree and from find-in-page as well as from the paint.
+ *
+ * Two mechanism choices that are load-bearing rather than stylistic:
+ *
+ * - `max-height` in `lh`, NOT `-webkit-line-clamp`. The clamp has to survive
+ *   arbitrary composed children — headings, paragraphs, a nested FAQ list —
+ *   and `-webkit-line-clamp` only counts line boxes of ONE inline formatting
+ *   context. `display:-webkit-box` turns block children into box items, so
+ *   there is nothing to count: the ellipsis silently never renders, the clamp
+ *   lands on a child boundary, and the nested list loses block layout. `1lh`
+ *   is one line of the clip box itself, so "8 lines" tracks whatever
+ *   line-height the designer authored, with no duplicated constant.
+ *   (`product-description-block.tsx` still does the `-webkit-line-clamp`
+ *   thing; it survives only because a PDP description is usually one flat
+ *   paragraph. Retiring it in favour of this block is a follow-up.)
+ *
+ * - `overflow: clip`, NOT `overflow: hidden`. A `hidden` box IS a scroll
+ *   container, so focusing a link forty lines down scrolls the visible lines
+ *   away and strands the shopper mid-paragraph with no way back. A `clip` box
+ *   physically cannot scroll.
+ *
+ * Properties: collapsedLines, fadeLines, fadeStyle, fadeColor, moreLabel,
+ * lessLabel, duration, defaultExpanded, expandOnFocus, showToggleIcon,
+ * toggleAlign, emptyLabel.
+ * Parts: viewport, clip, content, fade, toggle, toggle-label, toggle-icon,
+ * empty.
+ */
+
+/**
+ * Last-resort captions. These MIRROR the editor descriptor defaults in
+ * pz-dynamic-widget/src/config/blocks/collapsible-block-config.ts
+ * (`COLLAPSIBLE_TRIGGER_DEFAULTS`), and that repo's collapsible-block.test.ts
+ * pins the two to each other. The authored property always wins; this only
+ * covers JSON written before the property existed, or emitted without it.
+ */
+export const COLLAPSIBLE_FALLBACK_LABELS = {
+  more: 'Devamını Gör',
+  less: 'Devamını Gizle'
+} as const;
+
+const FADE_STYLES = ['mask', 'color'] as const;
+type FadeStyle = (typeof FADE_STYLES)[number];
+
+const ALIGNMENTS = ['start', 'center', 'end'] as const;
+type Alignment = (typeof ALIGNMENTS)[number];
+
+/** `margin`, not `text-align`: the trigger is a flex box, not an inline run. */
+const TRIGGER_MARGIN: Record<Alignment, string> = {
+  start: '0 auto 0 0',
+  center: '0 auto',
+  end: '0 0 0 auto'
+};
+
+const DEFAULT_COLLAPSED_LINES = 8;
+const DEFAULT_FADE_LINES = 3;
+const DEFAULT_DURATION = 320;
+const DEFAULT_EMPTY_LABEL = 'Collapsible (add the blocks to clamp)';
+
+/**
+ * A clamped integer read off a responsive property.
+ *
+ * Clamped rather than trusted because the value reaches the renderer from
+ * stored JSON, and a `max-height` of `calc(-4 * 1lh)` is an invalid
+ * declaration that drops the whole rule — i.e. no clamp at all, silently.
+ */
+const readNumber = (
+  value: unknown,
+  breakpoint: string,
+  fallback: number,
+  min: number,
+  max: number
+): number => {
+  const raw = getResponsiveValue(value, breakpoint, fallback);
+  const parsed = typeof raw === 'number' ? raw : parseFloat(String(raw));
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.round(parsed)));
+};
+
+/**
+ * A `localetext` property is stored raw — a plain string, a locale map, or a
+ * JSON string holding one.
+ *
+ * Third copy of a reader that already exists in `text-block.tsx` and
+ * `button-block.tsx`. Deliberate: unifying them means touching two shipped
+ * blocks, which is its own ticket. Kept byte-compatible with theirs so the
+ * eventual extraction is a move, not a rewrite.
+ */
+const readLocaleText = (
+  value: unknown,
+  locale: string,
+  defaultLocale: string,
+  fallback: string
+): string => {
+  let candidate: unknown = value;
+
+  if (typeof candidate === 'string' && candidate.trim().startsWith('{')) {
+    try {
+      candidate = JSON.parse(candidate);
+    } catch {
+      return candidate as string;
+    }
+  }
+
+  if (candidate && typeof candidate === 'object') {
+    const map = candidate as Record<string, unknown>;
+    const hit = map[locale] ?? map[defaultLocale] ?? Object.values(map)[0];
+    return typeof hit === 'string' && hit.trim() !== '' ? hit : fallback;
+  }
+
+  if (typeof candidate === 'string' && candidate.trim() !== '') {
+    return candidate;
+  }
+
+  return fallback;
+};
+
+const CollapsibleBlock: React.FC<BlockRendererProps> = ({
+  block,
+  placeholderId,
+  sectionId,
+  isDesigner = false,
+  selectedBlockId,
+  currentBreakpoint = 'desktop'
+}) => {
+  const { locale } = useLocalization();
+  const defaultLocale = process.env.NEXT_PUBLIC_DEFAULT_LOCALE || 'en';
+  const properties = block.properties;
+
+  const fadeStyle = resolveOption<FadeStyle>(
+    properties?.fadeStyle,
+    currentBreakpoint,
+    'mask',
+    [...FADE_STYLES]
+  );
+  const toggleAlign = resolveOption<Alignment>(
+    properties?.toggleAlign,
+    currentBreakpoint,
+    'start',
+    [...ALIGNMENTS]
+  );
+  const fadeColor = String(
+    getResponsiveValue(properties?.fadeColor, currentBreakpoint, '') || ''
+  );
+  const duration = readNumber(
+    properties?.duration,
+    currentBreakpoint,
+    DEFAULT_DURATION,
+    0,
+    800
+  );
+  const defaultExpanded = readToggle(
+    properties?.defaultExpanded,
+    currentBreakpoint,
+    false
+  );
+  const expandOnFocus = readToggle(
+    properties?.expandOnFocus,
+    currentBreakpoint,
+    true
+  );
+  const showToggleIcon = readToggle(
+    properties?.showToggleIcon,
+    currentBreakpoint,
+    true
+  );
+  const emptyLabel = String(
+    getResponsiveValue(
+      properties?.emptyLabel,
+      currentBreakpoint,
+      DEFAULT_EMPTY_LABEL
+    )
+  );
+
+  // Merchant copy, from config. The constant is only reached when the stored
+  // composition carries no caption at all.
+  const moreLabel = readLocaleText(
+    properties?.moreLabel,
+    locale,
+    defaultLocale,
+    COLLAPSIBLE_FALLBACK_LABELS.more
+  );
+  const lessLabel = readLocaleText(
+    properties?.lessLabel,
+    locale,
+    defaultLocale,
+    COLLAPSIBLE_FALLBACK_LABELS.less
+  );
+
+  // Expanded in the canvas, so children below the clip line stay selectable.
+  const [isExpanded, setIsExpanded] = useState(defaultExpanded || isDesigner);
+  /*
+   * Presentation, not truth. SSR assumes the common case (the content DOES
+   * overflow) and the observer only ever takes the affordance AWAY, so a long
+   * article — what this block exists for — costs no layout shift, and a short
+   * one loses a button one frame after hydration.
+   */
+  const [overflows, setOverflows] = useState(true);
+
+  const panelId = useId();
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const clipRef = useRef<HTMLDivElement | null>(null);
+  const contentRef = useRef<HTMLDivElement | null>(null);
+
+  // Lands in a selector, so it is escaped the way every other scoped sheet in
+  // the package escapes an id (see `escapeCssAttributeValue`).
+  const scopeId = escapeCssAttributeValue(String(block.id || 'collapsible'));
+
+  const css = useMemo(() => {
+    const scope = `[data-pz-collapsible="${scopeId}"]`;
+    const clip = `${scope} [data-part="clip"]`;
+
+    const vars = (band: string) =>
+      `${scope}{` +
+      `--pz-collapse-lines:${readNumber(
+        properties?.collapsedLines,
+        band,
+        DEFAULT_COLLAPSED_LINES,
+        2,
+        40
+      )};` +
+      `--pz-collapse-fade:${readNumber(
+        properties?.fadeLines,
+        band,
+        DEFAULT_FADE_LINES,
+        0,
+        12
+      )};` +
+      `--pz-collapse-duration:${duration}ms}`;
+
+    /*
+     * The canvas draws a phone layout inside a desktop-wide frame, so a real
+     * media query would answer for the FRAME and the designer would author a
+     * mobile line count while seeing the desktop one. One resolved band in the
+     * designer, real queries on the storefront — the same split
+     * `buildLineBreakCss` makes for the same reason.
+     */
+    const bands = isDesigner
+      ? vars(currentBreakpoint)
+      : vars('desktop') +
+        `${MOBILE_MEDIA_QUERY_COMPACT}{${vars('mobile')}}` +
+        `${TABLET_MEDIA_QUERY_COMPACT}{${vars('tablet')}}`;
+
+    /*
+     * A mask, not a coloured gradient. This block sits INSIDE an authored
+     * section, and sections carry their own background colour or image — so
+     * even the correct page-level variable is the wrong colour half the time,
+     * and over a background image no solid colour is right at all. Masking
+     * fades the text itself, so whatever is painted behind shows through and
+     * is always correct. `fadeStyle: 'color'` is the escape hatch for brands
+     * that want an opaque band over a busy photo.
+     */
+    const mask =
+      'linear-gradient(to bottom,#000 calc(100% - var(--pz-collapse-fade) * 1lh),transparent 100%)';
+
+    return (
+      // Registered so the fade band is interpolable; re-registering the same
+      // descriptor from a second instance on the page is a no-op.
+      `@property --pz-collapse-fade{syntax:'<number>';inherits:true;initial-value:0}` +
+      bands +
+      `${clip}{` +
+      // The `em` line is the pre-`lh` fallback; the `lh` line overrides it
+      // wherever it parses, so declaration order here matters.
+      `max-height:calc(var(--pz-collapse-lines) * 1.5em);` +
+      `max-height:calc(var(--pz-collapse-lines) * 1lh);` +
+      `overflow:hidden;overflow:clip;` +
+      (fadeStyle === 'mask'
+        ? `-webkit-mask-image:${mask};mask-image:${mask};` +
+          `-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat;`
+        : '') +
+      `transition:max-height var(--pz-collapse-duration) cubic-bezier(.4,0,.2,1),` +
+      `--pz-collapse-fade var(--pz-collapse-duration) linear}` +
+      // Open: the measured natural height, with the fade band shrinking to
+      // zero in step with it instead of popping off on frame one.
+      `${clip}[data-state~="open"]{max-height:var(--pz-collapse-full,none);--pz-collapse-fade:0}` +
+      `${scope}[data-overflowing="false"] [data-part="clip"]{max-height:none;-webkit-mask-image:none;mask-image:none}` +
+      `${scope}[data-overflowing="false"] [data-part="toggle"]{display:none}` +
+      /*
+       * In the canvas an expanded clip box must not clip AT ALL: a clipping
+       * ancestor makes the editor's ActionToolbar flip inward, and a child one
+       * pixel past the box would be unselectable.
+       */
+      `${scope}[data-designer-open="true"] [data-part="clip"]{max-height:none;overflow:visible;-webkit-mask-image:none;mask-image:none}` +
+      /*
+       * The colour band, declared here rather than inline so a merchant's
+       * `fade/*` part styles (which the generator rewrites `!important`) are
+       * not fighting an inline rule, and so the authored colour reaches CSS as
+       * a custom property VALUE on the root — it is never concatenated into
+       * this string, which is what keeps a crafted colour from closing the
+       * rule and writing its own.
+       */
+      (fadeStyle === 'color'
+        ? `${scope} [data-part="fade"]{position:absolute;left:0;right:0;bottom:0;` +
+          `height:calc(var(--pz-collapse-fade) * 1lh);pointer-events:none;` +
+          `background-image:linear-gradient(to bottom,transparent,var(--pz-collapse-fade-color,var(--theme-background,#fff)))}`
+        : '') +
+      `${scope} [data-part="toggle-icon"]{display:inline-block;transition:transform var(--pz-collapse-duration) ease}` +
+      `${scope} [data-part="toggle"][data-state~="open"] [data-part="toggle-icon"]{transform:rotate(180deg)}` +
+      `@media (prefers-reduced-motion:reduce){${clip},${scope} [data-part="toggle-icon"]{transition:none}}`
+    );
+  }, [currentBreakpoint, duration, fadeStyle, isDesigner, properties, scopeId]);
+
+  /*
+   * With JS off the button is inert, so a unit that exists to be READ would be
+   * permanently truncated for text-mode and proxy clients. SSR-ing expanded
+   * and collapsing on hydration would trade that for a guaranteed layout shift
+   * on every load for every user; this costs nothing, and it also removes the
+   * button that would not work.
+   */
+  const noScriptCss = useMemo(
+    () =>
+      // `dangerouslySetInnerHTML` rather than a `<style>` child: `<noscript>`
+      // is a raw-text element, so a React element child does not survive the
+      // round trip through the DOM. The string carries no authored value —
+      // only the escaped id — so there is nothing here to escape further.
+      `<style>` +
+      `[data-pz-collapsible="${scopeId}"] [data-part="clip"]{max-height:none;-webkit-mask-image:none;mask-image:none}` +
+      `[data-pz-collapsible="${scopeId}"] [data-part="toggle"]{display:none}` +
+      `</style>`,
+    [scopeId]
+  );
+
+  useEffect(() => {
+    const root = rootRef.current;
+    const clip = clipRef.current;
+    const content = contentRef.current;
+    if (!root || !clip || !content) return undefined;
+    if (typeof ResizeObserver === 'undefined') return undefined;
+
+    const measure = () => {
+      /*
+       * The CONTENT box, never `clip.scrollHeight`: an `overflow:clip` box is
+       * not a scroll container, so its scrollHeight is just its padding box
+       * and would always report "it fits".
+       */
+      const natural = content.getBoundingClientRect().height;
+
+      const clipStyle = window.getComputedStyle(clip);
+      const parsedLine = parseFloat(clipStyle.lineHeight);
+      const line = Number.isFinite(parsedLine)
+        ? parsedLine
+        : parseFloat(clipStyle.fontSize) * 1.5 || 24;
+
+      /*
+       * The budget comes from the RESOLVED custom property, not from
+       * `currentBreakpoint`: on the storefront the first client render still
+       * says 'desktop' (the wrapper corrects it in a post-mount effect) while
+       * the media query above has already answered for the real viewport.
+       */
+      const lines =
+        parseFloat(
+          window.getComputedStyle(root).getPropertyValue('--pz-collapse-lines')
+        ) || DEFAULT_COLLAPSED_LINES;
+
+      setOverflows(natural > lines * line + 1);
+
+      /*
+       * Kept live, so the box grows when a child faq-accordion row opens
+       * inside it instead of clipping its own children. The cost is two nested
+       * easings on the same pixels while that happens; the alternative
+       * (`max-height:none` on transitionend) removes it but `none` is not
+       * interpolable, so collapsing would then need a pin-and-reflow.
+       */
+      const full = `${Math.ceil(natural)}px`;
+      if (root.style.getPropertyValue('--pz-collapse-full') !== full) {
+        root.style.setProperty('--pz-collapse-full', full);
+      }
+    };
+
+    measure();
+
+    /*
+     * Only the content box. Observing the clip box would re-enter on every
+     * frame of the max-height transition.
+     */
+    const observer = new ResizeObserver(measure);
+    observer.observe(content);
+    // Webfonts land after first paint and change every line count.
+    document.fonts?.ready.then(measure).catch(() => undefined);
+
+    return () => observer.disconnect();
+  }, [currentBreakpoint]);
+
+  /*
+   * A fragment link — an authored htmlId, a skip link, a shared deep link —
+   * can target a heading inside the clipped area, and the browser would
+   * happily scroll to a box that is not painted.
+   */
+  useEffect(() => {
+    if (isExpanded || typeof window === 'undefined') return undefined;
+
+    const reveal = () => {
+      const hash = window.location.hash.slice(1);
+      if (!hash) return;
+      let target: HTMLElement | null = null;
+      try {
+        target = document.getElementById(decodeURIComponent(hash));
+      } catch {
+        target = document.getElementById(hash);
+      }
+      if (target && contentRef.current?.contains(target)) setIsExpanded(true);
+    };
+
+    reveal();
+    window.addEventListener('hashchange', reveal);
+    return () => window.removeEventListener('hashchange', reveal);
+  }, [isExpanded]);
+
+  const prefersReducedMotion = () =>
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+  const collapse = useCallback(() => {
+    setIsExpanded(false);
+    const root = rootRef.current;
+    if (!root) return;
+    /*
+     * Collapsing removes thousands of pixels from above the shopper, who is
+     * then left looking at the footer. Focus stays on the trigger — only the
+     * viewport moves, and only if the block has already scrolled off the top.
+     */
+    requestAnimationFrame(() => {
+      if (root.getBoundingClientRect().top >= 0) return;
+      root.scrollIntoView({
+        block: 'start',
+        behavior: prefersReducedMotion() ? 'auto' : 'smooth'
+      });
+    });
+  }, []);
+
+  /*
+   * Capture phase, so it runs before any child's own focus handler. A keyboard
+   * user reaching hidden content is doing exactly what a pointer user does by
+   * clicking the trigger, so do it for them — and because it goes through the
+   * same state, `aria-expanded` stays truthful. The trigger is a SIBLING of
+   * the viewport, so it can never self-trigger.
+   */
+  const handleFocusCapture = useCallback(() => {
+    if (expandOnFocus) setIsExpanded(true);
+  }, [expandOnFocus]);
+
+  const children = renderComposedChildren({
+    blocks: block.blocks,
+    placeholderId,
+    sectionId,
+    isDesigner,
+    selectedBlockId,
+    currentBreakpoint
+  });
+
+  if (children.length === 0) {
+    if (!isDesigner) return null;
+    return (
+      <div
+        {...partAttrs('empty')}
+        className="p-4 text-gray-400 border border-dashed border-gray-300 rounded"
+      >
+        {emptyLabel}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={rootRef}
+      data-pz-collapsible={scopeId}
+      data-overflowing={overflows ? 'true' : 'false'}
+      data-designer-open={isDesigner && isExpanded ? 'true' : 'false'}
+      style={
+        fadeColor
+          ? ({ '--pz-collapse-fade-color': fadeColor } as React.CSSProperties)
+          : undefined
+      }
+    >
+      <style>{css}</style>
+      <noscript dangerouslySetInnerHTML={{ __html: noScriptCss }} />
+
+      <div
+        {...partAttrs('viewport')}
+        style={{ position: 'relative' }}
+        onFocusCapture={handleFocusCapture}
+      >
+        <div ref={clipRef} {...partAttrs('clip', { open: isExpanded })}>
+          {/*
+            `flow-root`, because `overflow: clip` — unlike `hidden` — does NOT
+            establish a block formatting context. Without it the first child's
+            top margin collapses straight out of the clip box and the clamp
+            starts one margin too low: exactly the kind of drift a wrapper
+            around arbitrary composed children invites.
+          */}
+          <div
+            ref={contentRef}
+            id={panelId}
+            {...partAttrs('content')}
+            style={{ display: 'flow-root' }}
+          >
+            {children}
+          </div>
+        </div>
+
+        {fadeStyle === 'color' && (
+          <div
+            aria-hidden="true"
+            {...partAttrs('fade', { open: isExpanded })}
+          />
+        )}
+      </div>
+
+      <button
+        type="button"
+        {...partAttrs('toggle', { open: isExpanded })}
+        aria-expanded={isExpanded}
+        aria-controls={panelId}
+        onClick={() => (isExpanded ? collapse() : setIsExpanded(true))}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 6,
+          width: 'fit-content',
+          margin: TRIGGER_MARGIN[toggleAlign]
+        }}
+      >
+        {/*
+          No `aria-label`: the visible caption already changes between the two
+          states, and an aria-label on top would shadow it — breaking voice
+          control, where "click Devamını Gör" has to match the accessible name.
+          No `aria-live` either; every screen reader announces the
+          `aria-expanded` flip, and a live region would double-announce it.
+        */}
+        <span {...partAttrs('toggle-label')}>
+          {isExpanded ? lessLabel : moreLabel}
+        </span>
+        {showToggleIcon && (
+          <span aria-hidden="true" {...partAttrs('toggle-icon')}>
+            <svg
+              width="10"
+              height="6"
+              viewBox="0 0 10 6"
+              fill="none"
+              xmlns="http://www.w3.org/2000/svg"
+            >
+              <path
+                d="M1 1L5 5L9 1"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+            </svg>
+          </span>
+        )}
+      </button>
+    </div>
+  );
+};
+
+export default CollapsibleBlock;