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

package/src/utils/card-media.ts

@@ -0,0 +1,331 @@
+/**
+ * Product card list settings (ZERO-5173): the list of cards as a slider, how
+ * many cards it shows at once, and the card picture zooming in on hover.
+ *
+ * WHERE THE SETTINGS LIVE. On the same levels as the card's switches
+ * (property-switches.ts), nearest definer wins:
+ *
+ *  - the SLIDER belongs to the list — the product grid, or the Product Cards
+ *    section around its repeated cards — because only the list can lay its
+ *    cards out in one row. The grid reads its own properties; a section's
+ *    settings reach the generated repeat that holds its cards through the
+ *    property-switch pass, which writes them as `cardsSlider`. Its title
+ *    (CardsSliderTitle) travels with them.
+ *  - the ZOOM belongs to the card's picture, the image bound to `item.image`:
+ *    the list switches it for every card, a card may say otherwise. Every
+ *    Product Card ever inserted carries that binding, so a published card
+ *    gains the setting without being re-inserted.
+ *
+ * Nothing authored means nothing written onto any block, so an unconfigured
+ * list renders exactly what it rendered before.
+ *
+ * Pure: the pass and the renderers read from here, and none of them is
+ * imported back.
+ */
+
+const toText = (value: unknown): string =>
+  typeof value === 'string' ? value.trim() : '';
+
+/** Keyed `cards*` so a block's own settings up the chain are never mistaken for them. */
+export const CARD_LIST_PROPERTIES = {
+  slider: 'cardsSlider',
+  // The slider's title, carried the way the GANT rail (the flash deals
+  // slider) carries its own: the text, on or off, and its type — see
+  // CardsSliderTitle.
+  sliderShowTitle: 'cardsSliderShowTitle',
+  sliderTitle: 'cardsSliderTitle',
+  sliderTitleColor: 'cardsSliderTitleColor',
+  sliderTitleSize: 'cardsSliderTitleSize',
+  sliderTitleWeight: 'cardsSliderTitleWeight',
+  sliderTitleFont: 'cardsSliderTitleFont',
+  sliderTitleTransform: 'cardsSliderTitleTransform',
+  perView: 'cardsPerView',
+  perViewMobile: 'cardsPerViewMobile',
+  sliderArrows: 'cardsSliderArrows',
+  // The listing's grid views — see CardView: the view the list is drawn in,
+  // whether the shopper gets the toolbar's toggles, and the toggles' look.
+  view: 'cardsView',
+  viewModes: 'cardsViewModes',
+  viewTogglesAlign: 'cardsViewTogglesAlign',
+  viewTogglesColor: 'cardsViewTogglesColor',
+  viewTogglesSize: 'cardsViewTogglesSize',
+  viewTogglesGap: 'cardsViewTogglesGap',
+  viewTogglesPadding: 'cardsViewTogglesPadding',
+  hoverZoom: 'cardImageHoverZoom'
+} as const;
+
+/**
+ * The GANT listing's grid views (gant.co.uk, `utils/plp/grid-mode.ts` there)
+ * for a card list that is not sliding: catalogue — three across, one below
+ * 1024px; classic — the list's own grid (four across, two below), the
+ * default; archive — eight across, four below, pictures only.
+ *
+ * The designer picks the view the list is drawn in (`cardsView`). With the
+ * toolbar's toggles on (`cardsViewModes`) the shopper switches it, and the
+ * switch lives in the URL hash (`#catalogue` / `#classic` / `#archive`) as
+ * the listing's does, so a link opens the view it was shared in.
+ */
+export type CardView = 'catalogue' | 'classic' | 'archive';
+
+export const CARD_VIEWS: CardView[] = ['catalogue', 'classic', 'archive'];
+
+export const DEFAULT_CARD_VIEW: CardView = 'classic';
+
+/** Columns per view from 1024px up and below; classic keeps the list's grid. */
+export const CARD_VIEW_COLUMNS: Record<
+  Exclude<CardView, 'classic'>,
+  { desktop: number; mobile: number }
+> = {
+  catalogue: { desktop: 3, mobile: 1 },
+  archive: { desktop: 8, mobile: 4 }
+};
+
+/**
+ * What a part of the card says about the views: the Product Card's caption is
+ * `hideInCardView: 'archive'`, so the archive shows pictures only. Written on
+ * the block's wrapper, where its box is, so a hidden caption leaves no padding.
+ */
+export const HIDE_IN_CARD_VIEW_PROPERTY = 'hideInCardView';
+export const HIDE_IN_CARD_VIEW_ATTRIBUTE = 'data-hide-in-card-view';
+
+export const isCardView = (value: unknown): value is CardView =>
+  typeof value === 'string' && (CARD_VIEWS as string[]).includes(value);
+
+/** The view a hash names, or null — the list's own view then. */
+export const cardViewFromHash = (
+  hash: string | null | undefined
+): CardView | null => {
+  const value = (hash ?? '').replace(/^#/, '').toLowerCase();
+  return isCardView(value) ? value : null;
+};
+
+export type CardViewTogglesAlign = 'left' | 'center' | 'right';
+
+/** The toggles' row, as the listing's toolbar draws it by default. */
+export interface CardViewToggles {
+  align: CardViewTogglesAlign;
+  color: string;
+  /** The glyph, pixels; the button is 8px wider (44px squares below 1024px). */
+  size: number;
+  /** Between the buttons from 1024px up; flush below, as on the listing. */
+  gap: number;
+  /** The row's padding, a CSS shorthand of plain lengths. */
+  padding: string;
+}
+
+export const DEFAULT_CARD_VIEW_TOGGLES: CardViewToggles = {
+  align: 'right',
+  color: '#000000',
+  size: 24,
+  gap: 6,
+  padding: '6px 14px 6px 24px'
+};
+
+/** The list's views: the one it is drawn in, and the toggles when offered. */
+export interface CardViewSettings {
+  view: CardView;
+  toggles?: CardViewToggles;
+}
+
+export const readCardView = (raw: unknown): CardView | undefined =>
+  isCardView(toText(raw)) ? (toText(raw) as CardView) : undefined;
+
+export const readCardViewTogglesAlign = (
+  raw: unknown
+): CardViewTogglesAlign | undefined => {
+  const text = toText(raw);
+  return text === 'left' || text === 'center' || text === 'right'
+    ? text
+    : undefined;
+};
+
+const readPixels = (raw: unknown, min: number, max: number) => {
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  const value = parseFloat(String(raw));
+  return Number.isFinite(value) && value >= min && value <= max
+    ? value
+    : undefined;
+};
+
+export const readCardViewTogglesSize = (raw: unknown): number | undefined =>
+  readPixels(raw, 12, 48);
+
+export const readCardViewTogglesGap = (raw: unknown): number | undefined =>
+  readPixels(raw, 0, 48);
+
+/** One to four plain lengths — it lands in a style declaration. */
+export const readCardViewTogglesPadding = (
+  raw: unknown
+): string | undefined => {
+  const text = toText(raw);
+  return /^(\d+(\.\d+)?(px|rem|em|%)?)(\s+\d+(\.\d+)?(px|rem|em|%)?){0,3}$/.test(
+    text
+  )
+    ? text
+        .split(/\s+/)
+        .map((part) => (/^\d+(\.\d+)?$/.test(part) ? `${part}px` : part))
+        .join(' ')
+    : undefined;
+};
+
+export type CardsSliderTitleTransform = 'uppercase' | 'none' | 'capitalize';
+
+/**
+ * The title the slider draws on the left of its arrows. Settings of the list,
+ * beside its other "Cards:" settings, like the rail's own title settings — so
+ * a list that slides is titled from the same panel that made it slide, and
+ * there is no block to insert, find or lose. The canvas selects the list
+ * when the title is clicked.
+ */
+export interface CardsSliderTitle {
+  text: string;
+  color: string;
+  /** Pixels. */
+  size: number;
+  weight: string;
+  /** Empty = the theme's body font, the cards' own. */
+  font: string;
+  transform: CardsSliderTitleTransform;
+}
+
+/** The rail's title: regular 14px / 1.4, black, in capitals. */
+export const DEFAULT_CARDS_SLIDER_TITLE: Omit<CardsSliderTitle, 'text'> = {
+  color: '#000000',
+  size: 14,
+  weight: '400',
+  font: '',
+  transform: 'uppercase'
+};
+
+const TITLE_TRANSFORMS: CardsSliderTitleTransform[] = [
+  'uppercase',
+  'none',
+  'capitalize'
+];
+
+/** One colour value and nothing else — it lands in a style declaration. */
+const PLAIN_COLOR =
+  /^(#[0-9a-f]{3,8}|(rgb|rgba|hsl|hsla)\([\d\s.,%/]+\)|[a-z]+)$/i;
+
+/** The authored text; a non-string (an old on/off value) is no text at all. */
+export const readCardsSliderTitleText = (raw: unknown): string | undefined =>
+  typeof raw === 'string' ? raw : undefined;
+
+export const readCardsSliderTitleColor = (raw: unknown): string | undefined => {
+  const text = toText(raw);
+  return PLAIN_COLOR.test(text) ? text : undefined;
+};
+
+export const readCardsSliderTitleSize = (raw: unknown): number | undefined => {
+  if (raw === undefined || raw === null || raw === '') return undefined;
+  const size = parseFloat(String(raw));
+  return Number.isFinite(size) && size >= 8 && size <= 96 ? size : undefined;
+};
+
+export const readCardsSliderTitleWeight = (
+  raw: unknown
+): string | undefined => {
+  const text = toText(raw);
+  return /^[1-9]00$/.test(text) ? text : undefined;
+};
+
+/** A font stack; anything that could end the declaration it lands in is refused. */
+export const readCardsSliderTitleFont = (raw: unknown): string | undefined => {
+  const text = toText(raw);
+  return text && text.length <= 200 && !/[;{}<>]/.test(text) ? text : undefined;
+};
+
+export const readCardsSliderTitleTransform = (
+  raw: unknown
+): CardsSliderTitleTransform | undefined => {
+  const text = toText(raw);
+  return (TITLE_TRANSFORMS as string[]).includes(text)
+    ? (text as CardsSliderTitleTransform)
+    : undefined;
+};
+
+/**
+ * `top-right` is the GANT rail's placement — the two chevrons on the right of
+ * the row above the cards, where a title sits on the left — and the default;
+ * `sides` centres one on either edge of the cards; `none` leaves the row to
+ * the swipe.
+ */
+export type CardsSliderArrows = 'top-right' | 'sides' | 'none';
+
+export const CARDS_SLIDER_ARROW_POSITIONS: CardsSliderArrows[] = [
+  'top-right',
+  'sides',
+  'none'
+];
+
+/** Cards in view at once, desktop (1024px and up) and below it. */
+export const DEFAULT_CARDS_PER_VIEW = 4;
+export const DEFAULT_CARDS_PER_VIEW_MOBILE = 2;
+export const MAX_CARDS_PER_VIEW = 6;
+export const MAX_CARDS_PER_VIEW_MOBILE = 3;
+
+export interface CardsSliderSettings {
+  perView: number;
+  perViewMobile: number;
+  arrows: CardsSliderArrows;
+  /** Present only while the list shows a title: switched on, with text. */
+  title?: CardsSliderTitle;
+}
+
+/** `{{item.image}}` alone means the bare path, as it does for the iterator. */
+const normalizeBinding = (value: unknown): string => {
+  const text = toText(value);
+  const single = text.match(/^\{\{\s*([^{}]+?)\s*\}\}$/);
+  return single ? single[1].trim() : text;
+};
+
+/**
+ * The card's picture: the image block bound to the row's main image. Not a
+ * flag a template sets — the binding is what makes the block the product's
+ * picture, and it is what the cards inserted before this existed carry.
+ */
+export const isCardPictureBlock = (block: {
+  type?: string;
+  properties?: Record<string, unknown> | null;
+}): boolean =>
+  block?.type === 'image' &&
+  normalizeBinding(block.properties?.dataBinding) === 'item.image';
+
+/** A count as authored, capped, or undefined when nothing usable was. */
+export const readCardsPerView = (
+  raw: unknown,
+  max: number
+): number | undefined => {
+  if (raw === undefined || raw === null || raw === '') return undefined;
+
+  const numeric = Math.round(Number(raw));
+  if (!Number.isFinite(numeric) || numeric < 1) return undefined;
+
+  return Math.min(numeric, max);
+};
+
+export const readCardsSliderArrows = (
+  raw: unknown
+): CardsSliderArrows | undefined => {
+  const text = toText(raw);
+  return (CARDS_SLIDER_ARROW_POSITIONS as string[]).includes(text)
+    ? (text as CardsSliderArrows)
+    : undefined;
+};
+
+/**
+ * Hover rules for the zoom, injected once per document by the renderer. Only
+ * where a pointer can hover, so a tap on a phone never leaves a picture stuck
+ * enlarged.
+ */
+export const CARD_ZOOM_STYLE_ID = 'pz-card-zoom';
+
+export const CARD_ZOOM_CSS =
+  '@media (hover:hover){' +
+  '[data-card-zoom] img{transition:transform .5s ease}' +
+  '[data-card-zoom]:hover img{transform:scale(var(--card-zoom-scale,1.08))}' +
+  '}' +
+  '@media (prefers-reduced-motion:reduce){[data-card-zoom] img{transition:none}}';
+
+/** The toggles' colour: one colour value, as for the slider title. */
+export const readCardViewTogglesColor = readCardsSliderTitleColor;

package/src/utils/iterator-utils.ts

@@ -1504,7 +1504,12 @@ export const readRowLookups = (
 export const normalizeCollectionRow = (
   item: Record<string, unknown>,
   index: number,
-  options: { lookups?: ListingValueLookups; format?: RowMoneyFormat } = {}
+  options: {
+    lookups?: ListingValueLookups;
+    format?: RowMoneyFormat;
+    /** The repeat's rows, for a brand's swatch colours (utils/swatch-colors). */
+    rows?: unknown[];
+  } = {}
 ): Record<string, unknown> => {
   if (!isRecord(item) || Object.keys(item).length === 0) return item;
 
@@ -1525,7 +1530,8 @@ export const normalizeCollectionRow = (
     currency: typeof currency === 'string' ? currency : undefined,
     locale: options.format?.locale,
     money: options.format?.money,
-    lookups: options.lookups
+    lookups: options.lookups,
+    rows: options.rows
   });
   if (!normalized) return flat;
 
@@ -1688,7 +1694,8 @@ export const buildIteratorBlock = ({
     const item = scopesProducts
       ? normalizeCollectionRow(rawItem as Record<string, unknown>, index, {
           lookups: rowLookups,
-          format: rowFormat
+          format: rowFormat,
+          rows: displayItems
         })
       : rawItem;
 

package/src/utils/live-rows.ts

@@ -16,13 +16,19 @@ import { buildClientRequestUrl } from '@akinon/next/utils';
  * live rows at all: only while the editor reports the section's pick as
  * saved (`dataSourceSaved`). Until an unsaved pick is published, the section's
  * widget is still bound to the previous collection, so its live answer would
- * be the wrong rows — the picked snapshot is shown instead.
+ * be the wrong rows. An unsaved pick shows the rows of the collection's
+ * PREVIEW WIDGET instead, when the editor prepared one (see
+ * `collectionPreviewWidget`), and the picked snapshot otherwise.
  *
  * Client-safe: no server-only imports. The server loader imports
  * `carriesProducts` from here so both sides apply one acceptance rule.
  */
 
-/** Rows kept per `<sectionId>|<bindingKey>` for the designer canvas. */
+/**
+ * Rows kept for the designer canvas: a section's own answer per
+ * `<sectionId>|<bindingKey>`, a preview widget's per its slug (which holds no
+ * `|`, so the two can never collide).
+ */
 export type LiveRowsStore = Map<string, unknown>;
 
 /**
@@ -71,6 +77,68 @@ export const collectionBindingKey = (dataSource: unknown): string | null => {
 export const liveRowsEntryKey = (sectionId: string, bindingKey: string) =>
   `${sectionId}|${bindingKey}`;
 
+/**
+ * The hidden widget the theme editor keeps bound to one collection binding,
+ * so an UNSAVED pick can be shown with the rows the channel will give it once
+ * published (pz-dynamic-widget services/collection-preview-widget.ts builds
+ * the same slug — keep the two in step).
+ *
+ * WHY IT EXISTS. Before publish nothing else answers with the channel's rows
+ * for a collection: the section's widget is still bound to the previous one,
+ * the storefront lists a collection only through a widget, and the editor's
+ * snapshot comes from Omnitron's item list — the catalogue's rows, out-of-stock
+ * variants and old prices included, in its own order. So an unsaved pick
+ * showed different products from the ones the section showed once published.
+ * The preview widget is bound exactly as publishing binds the section
+ * (`product_collection` and `product_limit`) and sits in no placeholder, so no
+ * page ever renders it.
+ */
+export const COLLECTION_PREVIEW_WIDGET_PREFIX = 'theme-editor-collection-';
+
+const POSITIVE_INTEGER = /^[1-9]\d*$/;
+
+const integerText = (value: unknown): string | null => {
+  const text =
+    typeof value === 'number' || typeof value === 'string' ? String(value) : '';
+  return POSITIVE_INTEGER.test(text) ? text : null;
+};
+
+/**
+ * `theme-editor-collection-<pk>-<productLimit>`: one widget per binding, never
+ * re-pointed, so its slug alone says what it answers for. `null` for anything
+ * that is not a positive integer pair.
+ */
+export const collectionPreviewWidgetSlug = (
+  pk: unknown,
+  productLimit: unknown
+): string | null => {
+  const pkText = integerText(pk);
+  const limitText = integerText(productLimit);
+
+  return pkText && limitText
+    ? `${COLLECTION_PREVIEW_WIDGET_PREFIX}${pkText}-${limitText}`
+    : null;
+};
+
+/**
+ * The preview widget the canvas may ask for this source: the slug the editor
+ * stamped on it (`collection.previewWidget`) once that widget was in place,
+ * and only while it still names the source's current binding. A record
+ * re-pointed by anything that prepared no widget keeps the stamp of the
+ * binding it left, and that widget's rows are another collection's.
+ */
+export const collectionPreviewWidget = (dataSource: unknown): string | null => {
+  const collection = readCollection(dataSource);
+  if (!collection) return null;
+
+  const slug = collectionPreviewWidgetSlug(
+    collection.pk,
+    collection.productLimit
+  );
+
+  return slug && collection.previewWidget === slug ? slug : null;
+};
+
 export interface LiveRowsRequest {
   path: string;
   /**
@@ -114,42 +182,81 @@ export const liveRowsPaths = (
   return paths;
 };
 
+/**
+ * One endpoint's answer, or `null` when it gives none that is usable — also
+ * after `timeoutMs`, when one is given. Cache-busted, so an answer asked for
+ * right after a write is not a copy from before it. Never rejects.
+ */
+const askWidget = async (
+  { path, requireProducts }: LiveRowsRequest,
+  timeoutMs?: number
+): Promise<unknown | null> => {
+  let answer: unknown = null;
+  const controller =
+    timeoutMs && typeof AbortController !== 'undefined'
+      ? new AbortController()
+      : null;
+  const timer = controller
+    ? setTimeout(() => controller.abort(), timeoutMs)
+    : null;
+
+  try {
+    const response = await fetch(
+      buildClientRequestUrl(path, { cache: false }),
+      controller ? { signal: controller.signal } : undefined
+    );
+    if (response.ok) {
+      answer = await response.json();
+    }
+  } catch {
+    answer = null;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+
+  if (!answer || typeof answer !== 'object') return null;
+  if (requireProducts && !carriesProducts(answer)) return null;
+
+  return answer;
+};
+
 /**
  * Fetches a section's live rows from the browser, walking `liveRowsPaths` in
- * order. Cache-busted, so an answer asked for right after a publish is not a
- * copy from before it. Resolves `null` when no endpoint gives a usable answer;
- * never rejects.
+ * order. Resolves `null` when no endpoint gives a usable answer; never
+ * rejects.
  */
 export const fetchDesignerLiveRows = async (
   sectionId: string,
   collection: { slug?: unknown } | null | undefined
 ): Promise<unknown | null> => {
-  for (const { path, requireProducts } of liveRowsPaths(
-    sectionId,
-    collection
-  )) {
-    let answer: unknown = null;
-
-    try {
-      const response = await fetch(
-        buildClientRequestUrl(path, { cache: false })
-      );
-      if (response.ok) {
-        answer = await response.json();
-      }
-    } catch {
-      answer = null;
-    }
-
-    if (!answer || typeof answer !== 'object') continue;
-    if (requireProducts && !carriesProducts(answer)) continue;
-
-    return answer;
+  for (const request of liveRowsPaths(sectionId, collection)) {
+    const answer = await askWidget(request);
+    if (answer !== null) return answer;
   }
 
   return null;
 };
 
+/**
+ * How long the canvas waits for a preview widget before it lets the snapshot
+ * through: the section holds its previous rows meanwhile (see
+ * `hangDesignerDataSource`), and must not hold them forever.
+ */
+export const PREVIEW_ROWS_TIMEOUT_MS = 8000;
+
+/**
+ * A preview widget's rows (`collectionPreviewWidget`), taken only when it
+ * carries products: a collection the channel serves nothing from leaves the
+ * canvas on the snapshot, which is also what the storefront falls back to.
+ */
+export const fetchDesignerPreviewRows = (
+  previewWidget: string
+): Promise<unknown | null> =>
+  askWidget(
+    { path: `/widgets/${previewWidget}/`, requireProducts: true },
+    PREVIEW_ROWS_TIMEOUT_MS
+  );
+
 /**
  * The live rows the server already wrote into the document, keyed by the
  * binding the server resolved them for. Seeding from these is what lets a
@@ -177,11 +284,23 @@ export const seedLiveRows = (
  * The data source the designer canvas renders a section with.
  *
  * `raw` is the source record as the editor (or theme-config) holds it. Its
- * `details.collection.data` is dropped, and live rows are put back only when
- * the editor reports the section's pick as saved AND rows are held for the
- * binding the record names now. A late answer for a binding the section has
- * since left is stored under that binding's key, so it can never be attached
- * to the new one.
+ * `details.collection.data` is dropped, and live rows are put back only for
+ * the binding the record names now:
+ *
+ * - the section's own answer, when the editor reports the pick as saved;
+ * - otherwise the rows of the binding's preview widget, when the record names
+ *   one and they are held. They are the section's rows-to-be before publish,
+ *   and the same rows as its own answer after, until that answer is in.
+ *
+ * WHILE AN UNSAVED PICK'S PREVIEW ROWS ARE ON THEIR WAY, a caller that passes
+ * `hold` gets back `hold.previous` — what the section was drawn with until now
+ * (nothing, for a section that had no source) — so a pick changes the
+ * products once, straight to the right ones, instead of showing the snapshot
+ * first and swapping. A preview widget that gave no rows is held as `null`,
+ * which lets the snapshot through.
+ *
+ * A late answer for a binding the section has since left is stored under that
+ * binding's key, so it can never be attached to the new one.
  *
  * A record that carries no snapshot keeps the `data` it came with: there is
  * nothing to protect, and those rows are what the canvas showed before and
@@ -190,16 +309,32 @@ export const seedLiveRows = (
 export const hangDesignerDataSource = (
   section: { id?: string; dataSourceSaved?: unknown } | null | undefined,
   raw: any,
-  liveRows: LiveRowsStore
+  liveRows: LiveRowsStore,
+  hold?: { previous: unknown }
 ): any => {
   const collection = readCollection(raw);
   if (!collection) return raw;
 
+  const saved = section?.dataSourceSaved === true;
   const bindingKey = collectionBindingKey(raw);
-  const rows =
-    section?.dataSourceSaved === true && section.id && bindingKey
+  const sectionRows =
+    saved && section?.id && bindingKey
       ? liveRows.get(liveRowsEntryKey(section.id, bindingKey))
       : undefined;
+  const previewWidget = collectionPreviewWidget(raw);
+  // `undefined` until the preview widget answered, `null` if it gave nothing.
+  const previewRows = previewWidget ? liveRows.get(previewWidget) : undefined;
+  const rows = sectionRows !== undefined ? sectionRows : previewRows ?? undefined;
+
+  if (
+    rows === undefined &&
+    hold &&
+    !saved &&
+    previewWidget &&
+    previewRows === undefined
+  ) {
+    return hold.previous;
+  }
 
   if (rows !== undefined) {
     return {