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

package/src/utils/property-switches.ts

@@ -37,11 +37,46 @@
  * Pure, run once over the section tree before anything expands: the iterator
  * copies a template's children as they are, so a child dropped here is absent
  * from every clone and a marked one is marked on every clone.
+ *
+ * THE SAME CHAIN CARRIES THE CARD LIST'S SETTINGS (ZERO-5173): the zoom on
+ * hover is resolved for the card's picture and written as `cardZoom`; the
+ * slider — its title among its settings — is resolved for the repeat that
+ * holds a section's cards and written as `cardsSlider`, and the listing's grid
+ * views, for a repeat that is not sliding, as `cardsViews`
+ * (utils/card-media.ts).
  */
 
 import type { Block } from '../theme-block';
 import type { Section } from '../theme-section';
 import { fallbackChainOf } from './breakpoints';
+import {
+  CARD_LIST_PROPERTIES,
+  type CardsSliderSettings,
+  type CardsSliderTitle,
+  type CardViewSettings,
+  DEFAULT_CARD_VIEW,
+  DEFAULT_CARD_VIEW_TOGGLES,
+  readCardView,
+  readCardViewTogglesAlign,
+  readCardViewTogglesColor,
+  readCardViewTogglesGap,
+  readCardViewTogglesPadding,
+  readCardViewTogglesSize,
+  DEFAULT_CARDS_PER_VIEW,
+  DEFAULT_CARDS_PER_VIEW_MOBILE,
+  DEFAULT_CARDS_SLIDER_TITLE,
+  isCardPictureBlock,
+  MAX_CARDS_PER_VIEW,
+  MAX_CARDS_PER_VIEW_MOBILE,
+  readCardsPerView,
+  readCardsSliderArrows,
+  readCardsSliderTitleColor,
+  readCardsSliderTitleFont,
+  readCardsSliderTitleSize,
+  readCardsSliderTitleText,
+  readCardsSliderTitleTransform,
+  readCardsSliderTitleWeight
+} from './card-media';
 
 export const VISIBLE_WHEN_PROPERTY = 'visibleWhenProperty';
 export const HOVER_REVEAL_WHEN_PROPERTY = 'hoverRevealWhenProperty';
@@ -162,6 +197,202 @@ const findHoverScope = (scopes: Scope[], definer: Scope): Scope | null => {
   return definer.isSection ? null : definer;
 };
 
+/**
+ * The innermost value a scope defines for a setting — `findDefiningScope` for
+ * values that are not switches. `read` answers undefined for "not defined
+ * here", which is what lets the search walk past a card left on Inherit.
+ */
+const findDefinedValue = <T>(
+  scopes: Scope[],
+  key: string,
+  breakpoint: string,
+  read: (raw: unknown) => T | undefined
+): T | undefined => {
+  for (let index = scopes.length - 1; index >= 0; index -= 1) {
+    const raw = readResponsive(scopes[index].properties[key], breakpoint);
+    const value = read(raw);
+    if (value !== undefined) return value;
+  }
+
+  return undefined;
+};
+
+/** What a repeated card's root is marked with, whichever host it repeats in. */
+const isCardRoot = (block: Block | undefined): boolean =>
+  Boolean(block) &&
+  (readKey(block?.properties, 'role') === 'item-template' ||
+    readKey(block?.properties, 'dataSourceSlot') === 'item-template' ||
+    readKey(block?.properties, 'blockTemplate') === 'product-card');
+
+/**
+ * The repeat that holds a list of cards: the generated iterator a collection
+ * wraps around the Product Cards section's card. Its first child is the card
+ * it repeats (the iterator's positional contract).
+ */
+const isCardListRepeat = (block: Block): boolean =>
+  block.isIterator === true && isCardRoot((block.blocks || [])[0]);
+
+const readBoolean = (raw: unknown) => readSwitch(raw);
+
+/** The zoom the card's picture answers to, from the card and the list around it. */
+const resolveCardZoom = (chain: Scope[], breakpoint: string): boolean =>
+  findDefinedValue(
+    chain,
+    CARD_LIST_PROPERTIES.hoverZoom,
+    breakpoint,
+    readBoolean
+  ) === true;
+
+/**
+ * The view a list that is not sliding is drawn in, and the toggles when the
+ * shopper is offered them — or undefined for the list as authored: the
+ * classic view and no toggles, which is every list nobody configured.
+ */
+const resolveCardsViews = (
+  chain: Scope[],
+  breakpoint: string
+): CardViewSettings | undefined => {
+  const setting = <T>(key: string, read: (raw: unknown) => T | undefined) =>
+    findDefinedValue(chain, key, breakpoint, read);
+
+  const view =
+    setting(CARD_LIST_PROPERTIES.view, readCardView) ?? DEFAULT_CARD_VIEW;
+  const offered = setting(CARD_LIST_PROPERTIES.viewModes, readBoolean) === true;
+  if (!offered && view === DEFAULT_CARD_VIEW) return undefined;
+  if (!offered) return { view };
+
+  return {
+    view,
+    toggles: {
+      align:
+        setting(
+          CARD_LIST_PROPERTIES.viewTogglesAlign,
+          readCardViewTogglesAlign
+        ) ?? DEFAULT_CARD_VIEW_TOGGLES.align,
+      color:
+        setting(
+          CARD_LIST_PROPERTIES.viewTogglesColor,
+          readCardViewTogglesColor
+        ) ?? DEFAULT_CARD_VIEW_TOGGLES.color,
+      size:
+        setting(
+          CARD_LIST_PROPERTIES.viewTogglesSize,
+          readCardViewTogglesSize
+        ) ?? DEFAULT_CARD_VIEW_TOGGLES.size,
+      gap:
+        setting(CARD_LIST_PROPERTIES.viewTogglesGap, readCardViewTogglesGap) ??
+        DEFAULT_CARD_VIEW_TOGGLES.gap,
+      padding:
+        setting(
+          CARD_LIST_PROPERTIES.viewTogglesPadding,
+          readCardViewTogglesPadding
+        ) ?? DEFAULT_CARD_VIEW_TOGGLES.padding
+    }
+  };
+};
+
+/**
+ * The slider's title, when the list shows one: on (unless switched off) and
+ * with text. Each part of its type falls back to the rail's own default.
+ */
+const resolveCardsSliderTitle = (
+  chain: Scope[],
+  breakpoint: string
+): CardsSliderTitle | undefined => {
+  const setting = <T>(key: string, read: (raw: unknown) => T | undefined) =>
+    findDefinedValue(chain, key, breakpoint, read);
+
+  if (setting(CARD_LIST_PROPERTIES.sliderShowTitle, readBoolean) === false) {
+    return undefined;
+  }
+
+  const text = (
+    setting(CARD_LIST_PROPERTIES.sliderTitle, readCardsSliderTitleText) ?? ''
+  ).trim();
+  if (!text) return undefined;
+
+  return {
+    text,
+    color:
+      setting(
+        CARD_LIST_PROPERTIES.sliderTitleColor,
+        readCardsSliderTitleColor
+      ) ?? DEFAULT_CARDS_SLIDER_TITLE.color,
+    size:
+      setting(CARD_LIST_PROPERTIES.sliderTitleSize, readCardsSliderTitleSize) ??
+      DEFAULT_CARDS_SLIDER_TITLE.size,
+    weight:
+      setting(
+        CARD_LIST_PROPERTIES.sliderTitleWeight,
+        readCardsSliderTitleWeight
+      ) ?? DEFAULT_CARDS_SLIDER_TITLE.weight,
+    font:
+      setting(CARD_LIST_PROPERTIES.sliderTitleFont, readCardsSliderTitleFont) ??
+      DEFAULT_CARDS_SLIDER_TITLE.font,
+    transform:
+      setting(
+        CARD_LIST_PROPERTIES.sliderTitleTransform,
+        readCardsSliderTitleTransform
+      ) ?? DEFAULT_CARDS_SLIDER_TITLE.transform
+  };
+};
+
+/**
+ * The slider the list answers to, or undefined while it is off — so a list
+ * that names a count but no slider stays the grid it was.
+ */
+const resolveCardsSlider = (
+  chain: Scope[],
+  breakpoint: string
+): CardsSliderSettings | undefined => {
+  const setting = <T>(key: string, read: (raw: unknown) => T | undefined) =>
+    findDefinedValue(chain, key, breakpoint, read);
+
+  if (setting(CARD_LIST_PROPERTIES.slider, readBoolean) !== true) {
+    return undefined;
+  }
+
+  const title = resolveCardsSliderTitle(chain, breakpoint);
+
+  return {
+    perView:
+      setting(CARD_LIST_PROPERTIES.perView, (raw) =>
+        readCardsPerView(raw, MAX_CARDS_PER_VIEW)
+      ) ?? DEFAULT_CARDS_PER_VIEW,
+    perViewMobile:
+      setting(CARD_LIST_PROPERTIES.perViewMobile, (raw) =>
+        readCardsPerView(raw, MAX_CARDS_PER_VIEW_MOBILE)
+      ) ?? DEFAULT_CARDS_PER_VIEW_MOBILE,
+    arrows:
+      setting(CARD_LIST_PROPERTIES.sliderArrows, readCardsSliderArrows) ??
+      'top-right',
+    ...(title ? { title } : {})
+  };
+};
+
+const ownScope = (properties: Record<string, unknown> | undefined): Scope => ({
+  properties: (properties || {}) as Properties,
+  isSection: false,
+  declaresHoverScope: false,
+  hoverScope: false
+});
+
+/**
+ * The slider a block defines for itself, read exactly as a section's repeat
+ * reads it — for the product grid, which draws its own list.
+ */
+export const resolveOwnCardsSlider = (
+  properties: Record<string, unknown> | undefined,
+  breakpoint = 'desktop'
+): CardsSliderSettings | undefined =>
+  resolveCardsSlider([ownScope(properties)], breakpoint);
+
+/** The zoom a block defines for itself — for the grid's built-in card. */
+export const resolveOwnCardZoom = (
+  properties: Record<string, unknown> | undefined,
+  breakpoint = 'desktop'
+): boolean => resolveCardZoom([ownScope(properties)], breakpoint);
+
 const applyToBlocks = (
   blocks: Block[] | undefined,
   scopes: Scope[],
@@ -196,13 +427,28 @@ const applyToBlocks = (
         readSwitch(block.properties?.[HOVER_SCOPE_PROPERTY], breakpoint) === true,
       hoverScope: false
     };
-    const children = applyToBlocks(block.blocks, [...scopes, own], breakpoint);
+    const chain = [...scopes, own];
+    const cardZoom = isCardPictureBlock(block)
+      ? resolveCardZoom(chain, breakpoint)
+      : false;
+    const cardsSlider = isCardListRepeat(block)
+      ? resolveCardsSlider(chain, breakpoint)
+      : undefined;
+    // The listing's grid views belong to a list that is not sliding.
+    const cardsViews =
+      isCardListRepeat(block) && !cardsSlider
+        ? resolveCardsViews(chain, breakpoint)
+        : undefined;
+    const children = applyToBlocks(block.blocks, chain, breakpoint);
 
     next.push({
       ...block,
       ...(children !== block.blocks ? { blocks: children } : {}),
       ...(revealOnHover ? { revealOnHover: true } : {}),
-      ...(own.hoverScope ? { hoverScope: true } : {})
+      ...(own.hoverScope ? { hoverScope: true } : {}),
+      ...(cardZoom ? { cardZoom: true } : {}),
+      ...(cardsSlider ? { cardsSlider } : {}),
+      ...(cardsViews ? { cardsViews } : {})
     });
   }
 

package/src/utils/swatch-colors.ts

@@ -0,0 +1,81 @@
+/**
+ * Brand hook for the colour of a product card's swatch chips (ZERO-5173).
+ *
+ * A chip draws `item.colors[].color`, which the list's Colour Swatch Mapping
+ * fills — the grid's, or the card's over a collection — keyed by the colour's
+ * integration value. Commerce sends no hex, and which value means which colour
+ * is brand knowledge: GANT's listing turns a colour code into a tone and the
+ * tone into its palette's hex. A brand that already resolves it registers that
+ * resolver here from its client root (the same ownership pattern as the
+ * search-term transform), and every theme card colours its chips the way the
+ * brand's own listing does, without a table copied into every list.
+ *
+ * An authored mapping still wins over the brand's resolver. No registration
+ * and no mapping leaves the chip uncoloured, exactly as before.
+ */
+
+export interface SwatchColorRequest {
+  /**
+   * The colour's key: the option's value, or its label where the payload
+   * carries the code there and no value (GANT's `integration_renk`).
+   */
+  key: string;
+  /** The shopper-facing label. */
+  label: string;
+  /** The row's product, as commerce sent it. */
+  product: Record<string, unknown>;
+  /** The product in that colour — the option's — as commerce sent it. */
+  variant: Record<string, unknown>;
+  /**
+   * The products of the list the row is in, the row among them, as commerce
+   * sent them — a page's listing, a collection's rows. GANT's listing pairs a
+   * colour code with the tone of a product on the page that carries it before
+   * it falls back to its catalogue table; this is that page.
+   */
+  rows: Record<string, unknown>[];
+}
+
+type SwatchColorResolver = (
+  request: SwatchColorRequest
+) => string | null | undefined;
+
+let resolver: SwatchColorResolver | null = null;
+
+/**
+ * What a chip may be painted with. The colour lands in the chip's style, so
+ * anything that is not one plain colour value is dropped rather than written
+ * into a declaration it could break out of.
+ */
+const PLAIN_COLOR =
+  /^(#[0-9a-f]{3,8}|(rgb|rgba|hsl|hsla)\([\d\s.,%/]+\)|[a-z]+)$/i;
+
+/** Register the brand's resolver. Returns an unregister function. */
+export const registerSwatchColors = (fn: SwatchColorResolver): (() => void) => {
+  resolver = fn;
+  return () => {
+    if (resolver === fn) resolver = null;
+  };
+};
+
+/**
+ * The brand's colour for a chip, or undefined when no brand hooked in, it has
+ * no colour for this one, or it throws — a brand bug must never break a card.
+ */
+export const resolveSwatchColor = (
+  request: SwatchColorRequest
+): string | undefined => {
+  if (!resolver) return undefined;
+  try {
+    const color = resolver(request);
+    if (typeof color !== 'string') return undefined;
+    const text = color.trim();
+    return PLAIN_COLOR.test(text) ? text : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Test-only: reset the registry between cases. */
+export const __resetSwatchColorsForTests = (): void => {
+  resolver = null;
+};