@akinon/pz-theme 2.0.103-rc.0 → 2.0.104-beta.0

package/src/blocks/listing-context.ts

@@ -3,8 +3,22 @@
 import { useMemo } from 'react';
 import { useLocalization } from '@akinon/next/hooks';
 import { useThemePageContext } from '../theme-page-context';
-import { MoneyStyleOptions } from './commerce-format';
-import { formatPrice, parsePriceValue } from './product-block-utils';
+import {
+  ListingLocalizationOptions,
+  ListingProduct,
+  ListingValueLookups,
+  MoneyStyleOptions,
+  normalizeListingProduct,
+  toArray,
+  toBoolean,
+  toRecord,
+  toText
+} from './listing-row';
+
+// The row model and its normaliser live in listing-row.ts (pure, so the
+// collection iterator can share them); everything is re-exported so the
+// blocks that import them from here keep compiling.
+export * from './listing-row';
 
 type UnknownRecord = Record<string, unknown>;
 
@@ -41,204 +55,6 @@ export interface ListingBreadcrumb {
   url: string;
 }
 
-/** One buyable colour of a product, as a card swatch needs it. */
-export interface ListingProductColor {
-  label: string;
-  value: string;
-  /** Swatch/preview image of that colour's variant, when commerce sends one. */
-  image?: string;
-  url?: string;
-  isSelected: boolean;
-  /**
-   * Hex a circular swatch can be filled with. Commerce sends the colour as a
-   * bare value ("kirmizi") and no colour at all, so this is only present when
-   * the author mapped that value in `lookups.swatch`.
-   */
-  color?: string;
-}
-
-/**
- * What a value resolves INTO once an author has mapped it.
- *
- * Every part is optional because the three brands' designs disagree: one draws
- * a badge as an image, one as text on a colour, one as both.
- */
-export interface ListingLookupEntry {
-  label?: string;
-  image?: string;
-  color?: string;
-}
-
-/**
- * A designer-authored value -> presentation table.
- *
- * Commerce sends a badge as a bare key ("new_season") and carries NO resolved
- * form of it — no label, no image, no colour. Nothing in the payload can be
- * bound to draw the chip both brands draw, so the resolution has to be
- * authored. This is an editor-side table standing in for a commerce field that
- * does not exist, and it is deliberately not a fallback: a value the table does
- * not list resolves to nothing rather than leaking the raw key onto a card.
- */
-export interface ListingBadgeLookup {
-  /** Which keyed attribute the raw value is read from (`attributes.<key>`). */
-  attribute: string;
-  entries: Record<string, ListingLookupEntry>;
-}
-
-export interface ListingValueLookups {
-  badge?: ListingBadgeLookup;
-  /** Colour value -> hex, for the swatch circles on a card. */
-  swatch?: Record<string, string>;
-}
-
-/**
- * The plain-text form of the tables above, as the editor panel offers them.
- *
- * One mapping per line, fields separated by `|` — the same shape the payment
- * badges block already asks a designer for, so the panel does not invent a
- * second syntax for the same job. JSON was the alternative and it is not one a
- * merchandiser can be handed: a missing brace silently empties the table.
- *
- * Returns `undefined` rather than an empty table when nothing usable was
- * authored: the caller memoises on this value, and every lookup-fed field on
- * the row stays absent either way.
- */
-export const parseListingLookups = (
-  badgeAttribute: string,
-  badgeTable: string,
-  swatchTable: string
-): ListingValueLookups | undefined => {
-  const rows = (raw: string): string[][] =>
-    raw
-      .split(/\r?\n/)
-      .map((line) => line.split('|').map((field) => field.trim()))
-      .filter((fields) => fields[0]);
-
-  // Prototype-less, because the keys are authored: a line beginning
-  // `__proto__|` would otherwise rewrite the table's prototype instead of
-  // adding a mapping, and the row it described would silently do nothing.
-  const entries: Record<string, ListingLookupEntry> = Object.create(null);
-  for (const [key, label, image, color] of rows(badgeTable)) {
-    if (!label && !image && !color) continue;
-    entries[key] = {
-      ...(label ? { label } : null),
-      ...(image ? { image } : null),
-      ...(color ? { color } : null)
-    };
-  }
-
-  const swatch: Record<string, string> = Object.create(null);
-  for (const [value, color] of rows(swatchTable)) {
-    if (color) swatch[value] = color;
-  }
-
-  // Without the attribute name there is nothing to read the raw value from, so
-  // a half-filled badge table maps nothing rather than guessing a key.
-  const badge =
-    badgeAttribute && Object.keys(entries).length > 0
-      ? { attribute: badgeAttribute, entries }
-      : undefined;
-  const hasSwatch = Object.keys(swatch).length > 0;
-
-  if (!badge && !hasSwatch) return undefined;
-
-  return {
-    ...(badge ? { badge } : null),
-    ...(hasSwatch ? { swatch } : null)
-  };
-};
-
-/** A campaign line commerce attaches to the product ("2 for 3", …). */
-export interface ListingBasketOffer {
-  label?: string;
-  /** `listing_kwargs.discounted_total_price`, already formatted. */
-  price?: string;
-}
-
-export interface ListingProduct {
-  key: string;
-  /**
-   * The commerce product id. `key` is a React key with an index fallback, so
-   * it cannot be used to call an endpoint (wishlist, add-to-cart) — this can.
-   * Absent when the payload carried no usable pk.
-   */
-  pk?: number;
-  name: string;
-  url: string;
-  image: string;
-  /**
-   * Every image commerce sent, in order. `image` stays the first one; the
-   * second is what a hover-swap card needs and there was no way to reach it.
-   */
-  images?: string[];
-  price: string;
-  retailPrice: string;
-  /**
-   * The same two prices as plain numbers, for consumers that compute rather
-   * than display — analytics items, sort keys. Absent when unparseable.
-   */
-  priceAmount?: number;
-  retailPriceAmount?: number;
-  /**
-   * `price_extra_field.previous_price` — the price-history line several
-   * markets require by law. Absent when commerce did not send one.
-   */
-  previousPrice?: string;
-  hasDiscount: boolean;
-  /**
-   * Rounded saving off the retail price; absent when there is no discount.
-   * Kept under its original, basis-less name so every published card that
-   * binds it keeps the number it has always shown.
-   */
-  discountPercent?: number;
-  /**
-   * The same number under a name that states its basis. A card that strikes
-   * the retail price binds this one.
-   */
-  discountPercentFromRetail?: number;
-  /**
-   * Saving off `previousPrice` instead. A brand whose card strikes
-   * `price_extra_field.previous_price` was showing a chip computed off a price
-   * it never displayed; this is the number that matches what it struck.
-   *
-   * Both bases are published rather than one being switched between, because
-   * only the card's own design says which price it struck — guessing that from
-   * the payload would move published cards.
-   */
-  discountPercentFromPrevious?: number;
-  /**
-   * A raw commerce value resolved through the author's lookup table (see
-   * `ListingBadgeLookup`). Absent when no table was authored, when the product
-   * carries no value for it, or when the value is not in the table.
-   */
-  badge?: ListingLookupEntry;
-  /** Absent when the payload says nothing about stock. */
-  inStock?: boolean;
-  /** Keyed, so a card can bind one named attribute (`attributes.badge_text`). */
-  attributes?: Record<string, string>;
-  basketOffers?: ListingBasketOffer[];
-  colors?: ListingProductColor[];
-  colorCount?: number;
-}
-
-/** Locale/currency resolved once at the hook boundary and passed down. */
-export interface ListingLocalizationOptions {
-  locale?: string;
-  currency?: string;
-  /**
-   * The brand's money format, when the block that asked for the listing has
-   * one. Every price on the row is formatted with it, so a designer-authored
-   * card reads the same as the built-in one. Absent = the format the theme
-   * always used.
-   */
-  money?: MoneyStyleOptions;
-  /**
-   * Author-supplied resolution tables. Absent = every lookup-fed field on the
-   * row stays absent, which is the shape the row has always had.
-   */
-  lookups?: ListingValueLookups;
-}
-
 export interface ListingContextData {
   title: string;
   path: string;
@@ -259,21 +75,6 @@ export interface ListingContextData {
  */
 const LISTING_ROOT_KEYS = ['listing', 'plp', 'search', 'category'];
 
-const toRecord = (value: unknown): UnknownRecord =>
-  value && typeof value === 'object' && !Array.isArray(value)
-    ? (value as UnknownRecord)
-    : {};
-
-const toArray = (value: unknown): unknown[] =>
-  Array.isArray(value) ? value : [];
-
-const toText = (value: unknown, fallback = ''): string => {
-  if (typeof value === 'string') return value;
-  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
-  return fallback;
-};
-
-const toBoolean = (value: unknown): boolean => value === true || value === 'true';
 
 const firstNumber = (candidates: unknown[], fallback: number): number => {
   for (const candidate of candidates) {
@@ -286,412 +87,6 @@ const firstNumber = (candidates: unknown[], fallback: number): number => {
   return fallback;
 };
 
-/**
- * Grid prices go through the same formatter as the PDP price block, so the
- * same product reads identically in both places. The locale is threaded in
- * from `useLocalization()` rather than left implicit: these blocks render on
- * the server and hydrate on the client, and an implicit Intl locale resolves
- * differently in the two runtimes.
- */
-export const formatListingPrice = (
-  value: unknown,
-  currency: string,
-  locale?: string,
-  money?: MoneyStyleOptions
-): string => formatPrice(value, currency, true, locale, money) ?? '';
-
-const isMissing = (value: unknown): boolean =>
-  value === null || value === undefined || value === '';
-
-/**
- * Percentage off ONE named basis, rounded the way the built-in badge rounds.
- *
- * Undefined unless the basis is a real amount above the price: a "0% off" chip
- * and a chip computed off a basis commerce did not send are both worse than no
- * chip at all.
- */
-const percentOff = (
-  basis: number | null,
-  price: number | null
-): number | undefined =>
-  basis !== null && price !== null && basis > 0 && basis > price
-    ? Math.round(((basis - price) / basis) * 100)
-    : undefined;
-
-const SCRIPT_SCHEME = /^(?:javascript|vbscript|data):/;
-
-/**
- * A lookup image ends up in an `<img src>` the moment a row binds
- * `item.badge.image`, so the authored value is judged before it reaches the
- * row rather than at every binding that might read it.
- *
- * Browsers strip whitespace and control characters while parsing a url, so a
- * tab wedged into "javascript:" still resolves to a live handler; the value is
- * normalised the same way before it is judged. `data:` goes with them because
- * an SVG document served from one is same-origin with the page that framed it.
- */
-const safeLookupImage = (value: string): string =>
-  SCRIPT_SCHEME.test(value.replace(/[\u0000-\u0020]/g, '').toLowerCase())
-    ? ''
-    : value;
-
-/**
- * A lookup colour is bindable into a style value, and style values are emitted
- * into the theme's `<style>` element — so a value carrying `;` or `}` would
- * close the rule it landed in and write its own. Only the shapes a colour can
- * legitimately take are accepted; anything else publishes no colour, which is
- * the same thing an unmapped value does.
- */
-const SAFE_CSS_COLOR =
-  /^(#[0-9a-f]{3,8}|[a-z]+|(?:rgb|rgba|hsl|hsla)\([0-9a-z%.,\s/+-]*\)|var\(--[a-z0-9_-]+\))$/i;
-
-const safeLookupColor = (value: string): string =>
-  SAFE_CSS_COLOR.test(value.trim()) ? value.trim() : '';
-
-/**
- * Table lookup for a raw commerce value.
- *
- * Matched case-insensitively as a second pass: commerce values arrive in
- * whatever case the brand's integration wrote them ("New_Season" and
- * "new_season" are the same badge), and an author cannot be asked to enumerate
- * both. An entry with nothing in it counts as no match, so an empty row in the
- * table does not publish an empty badge.
- */
-const resolveLookupEntry = (
-  entries: Record<string, ListingLookupEntry> | undefined,
-  value: string
-): ListingLookupEntry | undefined => {
-  if (!entries || !value) return undefined;
-
-  // Own keys only. A table is indexed by a value that came from the catalogue,
-  // and `entries['toString']` on a plain object answers with a function the
-  // rest of this walk would treat as an entry.
-  const direct = Object.prototype.hasOwnProperty.call(entries, value)
-    ? entries[value]
-    : undefined;
-  const normalized = value.trim().toLowerCase();
-  const entry =
-    direct ??
-    Object.entries(entries).find(
-      ([key]) => key.trim().toLowerCase() === normalized
-    )?.[1];
-
-  if (!entry) return undefined;
-
-  const label = toText(entry.label);
-  // Both of these leave the row for a url and for a stylesheet, so the
-  // authored value is judged here rather than at every binding that reads it.
-  const image = safeLookupImage(toText(entry.image));
-  const color = safeLookupColor(toText(entry.color));
-  if (!label && !image && !color) return undefined;
-
-  return {
-    ...(label ? { label } : null),
-    ...(image ? { image } : null),
-    ...(color ? { color } : null)
-  };
-};
-
-const resolveBadge = (
-  attributes: Record<string, string> | undefined,
-  lookup: ListingBadgeLookup | undefined
-): ListingLookupEntry | undefined => {
-  if (!lookup || !attributes) return undefined;
-
-  // The attribute name is free text a merchandiser types into the panel, and
-  // it indexes an object. `constructor`, `toString` and every other
-  // Object.prototype member answer with a function rather than an attribute
-  // value, and the table lookup below would then read `.trim()` off it and
-  // take the whole category page down. Own keys only, and read as text.
-  const raw = Object.prototype.hasOwnProperty.call(
-    attributes,
-    lookup.attribute
-  )
-    ? attributes[lookup.attribute]
-    : '';
-
-  return resolveLookupEntry(lookup.entries, toText(raw));
-};
-
-/**
- * Attributes are republished KEYED rather than as the positional
- * `{ label, value }` list the page context builds: a card design targets a
- * *named* attribute (`attributes.badge_text`), and a positional list cannot be
- * addressed by name — position moves as the attribute set changes.
- *
- * `attributes_kwargs` is the keyed source commerce always sends. The raw
- * `attributes` map wins where it survived, because that is the value the
- * hand-coded brand cards read.
- */
-const normalizeProductAttributes = (
-  product: UnknownRecord
-): Record<string, string> | undefined => {
-  const keyed: Record<string, string> = {};
-
-  for (const [key, entry] of Object.entries(
-    toRecord(product.attributes_kwargs)
-  )) {
-    const value = toText(toRecord(entry).value);
-    if (value) keyed[key] = value;
-  }
-
-  // `attributes` only reaches here as a keyed map when the payload skipped the
-  // page-context normaliser, which replaces it with the positional list.
-  const raw = product.attributes;
-  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
-    for (const [key, value] of Object.entries(raw as UnknownRecord)) {
-      const text = toText(value);
-      if (text) keyed[key] = text;
-    }
-  }
-
-  return Object.keys(keyed).length > 0 ? keyed : undefined;
-};
-
-const normalizeProductImages = (
-  product: UnknownRecord
-): string[] | undefined => {
-  // `images` is what the page context normalised; `productimage_set` is the
-  // raw commerce field, for payloads handed straight to the resolver.
-  const source = toArray(product.images).length
-    ? toArray(product.images)
-    : toArray(product.productimage_set);
-
-  const urls = source
-    .map((entry) => {
-      if (typeof entry === 'string') return entry;
-      const image = toRecord(entry);
-      return toText(image.url) || toText(image.image);
-    })
-    .filter((url) => url.length > 0);
-
-  return urls.length > 0 ? urls : undefined;
-};
-
-const normalizeBasketOffers = (
-  product: UnknownRecord,
-  currency: string,
-  locale?: string,
-  money?: MoneyStyleOptions
-): ListingBasketOffer[] | undefined => {
-  const offers = toArray(product.basket_offers)
-    .map((entry): ListingBasketOffer | null => {
-      const offer = toRecord(entry);
-      const label = toText(offer.label);
-      const rawPrice = toRecord(offer.listing_kwargs).discounted_total_price;
-      const price = isMissing(rawPrice)
-        ? ''
-        : formatListingPrice(rawPrice, currency, locale, money);
-
-      if (!label && !price) return null;
-
-      return {
-        ...(label ? { label } : null),
-        ...(price ? { price } : null)
-      };
-    })
-    .filter((offer): offer is ListingBasketOffer => offer !== null);
-
-  return offers.length > 0 ? offers : undefined;
-};
-
-/**
- * Commerce has no single colour attribute: every integration names its own
- * (`mp_color`, `integration_renk`, …), which is why hand-coded brand cards
- * carry a hardcoded list of keys. The known names are matched first, then any
- * key ending in colour/renk, so a brand on a fourth spelling still gets
- * swatches. Only selectable options are published — the rest cannot be bought.
- */
-const COLOR_ATTRIBUTE_KEYS = [
-  'mp_color',
-  'integration_color',
-  'integration_renk'
-];
-const COLOR_ATTRIBUTE_PATTERN = /(^|_)(color|colour|renk)$/;
-
-const isColorAttributeKey = (key: string): boolean => {
-  // Commerce keys arrive in whatever case the brand configured
-  // (`integration_Renk` is real), so the comparison is lowercased.
-  const normalized = key.trim().toLowerCase();
-  return (
-    COLOR_ATTRIBUTE_KEYS.includes(normalized) ||
-    COLOR_ATTRIBUTE_PATTERN.test(normalized)
-  );
-};
-
-const normalizeProductColors = (
-  product: UnknownRecord,
-  swatch?: Record<string, string>
-): ListingProductColor[] | undefined => {
-  const groups = toArray(toRecord(product.extra_data).variants);
-  // A known key wins over the loose suffix match: a payload carrying both
-  // `integration_color` and, say, `secondary_colour` must pick the real one.
-  const group =
-    groups.find((entry) =>
-      COLOR_ATTRIBUTE_KEYS.includes(
-        toText(toRecord(entry).attribute_key).trim().toLowerCase()
-      )
-    ) ??
-    groups.find((entry) =>
-      isColorAttributeKey(toText(toRecord(entry).attribute_key))
-    );
-
-  if (!group) return undefined;
-
-  // Reshaped once rather than per option, so this table gets the same
-  // case-insensitive matching the badge table gets.
-  const swatchEntries = swatch
-    ? Object.fromEntries(
-        Object.entries(swatch).map(([key, color]) => [key, { color }])
-      )
-    : undefined;
-
-  const colors = toArray(toRecord(group).options)
-    .map((entry): ListingProductColor | null => {
-      const option = toRecord(entry);
-      if (!toBoolean(option.is_selectable)) return null;
-
-      const value = toText(option.value);
-      const label = toText(option.label) || value;
-      if (!value && !label) return null;
-
-      const variant = toRecord(option.product);
-      const image =
-        toText(variant.image) ||
-        toText(toRecord(toArray(variant.productimage_set)[0]).image);
-      const url = toText(variant.absolute_url);
-      // The swatch table is keyed by the colour VALUE, which is the stable
-      // integration key; the label is the shopper-facing text and is
-      // translated, so it cannot key a table a brand authors once.
-      const hex = resolveLookupEntry(swatchEntries, value)?.color;
-
-      return {
-        label,
-        value,
-        ...(image ? { image } : null),
-        ...(url ? { url } : null),
-        isSelected: toBoolean(option.is_selected),
-        ...(hex ? { color: hex } : null)
-      };
-    })
-    .filter((color): color is ListingProductColor => color !== null);
-
-  return colors.length > 0 ? colors : undefined;
-};
-
-const readInStock = (product: UnknownRecord): boolean | undefined => {
-  if (typeof product.in_stock === 'boolean') return product.in_stock;
-
-  const stock = Number(product.stock);
-  if (!isMissing(product.stock) && Number.isFinite(stock)) return stock > 0;
-
-  // Unknown stock is published as unknown rather than guessed: a card that
-  // binds it should show nothing, not "out of stock".
-  return undefined;
-};
-
-const normalizeProduct = (
-  entry: unknown,
-  index: number,
-  options: ListingLocalizationOptions
-): ListingProduct | null => {
-  const product = toRecord(entry);
-  const name = toText(product.title) || toText(product.name);
-  const url = toText(product.url) || toText(product.absolute_url);
-
-  if (!name && !url) return null;
-
-  // Commerce sends the currency per product; the active currency is only the
-  // fallback for payloads that omit it.
-  const currency =
-    toText(product.currency) ||
-    toText(product.currency_type) ||
-    (options.currency || '');
-  const price = formatListingPrice(
-    product.price,
-    currency,
-    options.locale,
-    options.money
-  );
-  const retailPrice = formatListingPrice(
-    product.retailPrice ?? product.retail_price,
-    currency,
-    options.locale,
-    options.money
-  );
-  // Parsed with the shared parser, not Number(): "1.299,90" is NaN to Number()
-  // and would silently drop the discount flag the PDP block still shows.
-  const numericPrice = parsePriceValue(product.price);
-  const numericRetail = parsePriceValue(
-    product.retailPrice ?? product.retail_price
-  );
-  const hasDiscount =
-    numericPrice !== null &&
-    numericRetail !== null &&
-    numericRetail > numericPrice;
-
-  const rawPreviousPrice = toRecord(product.price_extra_field).previous_price;
-  const numericPrevious = parsePriceValue(rawPreviousPrice);
-  const numericPk = Number(product.pk);
-  const colors = normalizeProductColors(product, options.lookups?.swatch);
-  const attributes = normalizeProductAttributes(product);
-  const percentFromRetail = percentOff(numericRetail, numericPrice);
-
-  return {
-    key: toText(product.pk, '') || `product-${index}`,
-    pk:
-      !isMissing(product.pk) && Number.isFinite(numericPk)
-        ? numericPk
-        : undefined,
-    name,
-    url: url || '#',
-    image: toText(product.image),
-    images: normalizeProductImages(product),
-    price,
-    retailPrice,
-    previousPrice: isMissing(rawPreviousPrice)
-      ? undefined
-      : formatListingPrice(
-          rawPreviousPrice,
-          currency,
-          options.locale,
-          options.money
-        ) || undefined,
-    hasDiscount,
-    ...(numericPrice !== null ? { priceAmount: numericPrice } : null),
-    ...(numericRetail !== null ? { retailPriceAmount: numericRetail } : null),
-    // The grid already derived this to draw its badge; publishing it means a
-    // designer-authored card does not have to re-derive it from two strings.
-    discountPercent: percentFromRetail,
-    discountPercentFromRetail: percentFromRetail,
-    discountPercentFromPrevious: percentOff(numericPrevious, numericPrice),
-    inStock: readInStock(product),
-    attributes,
-    badge: resolveBadge(attributes, options.lookups?.badge),
-    basketOffers: normalizeBasketOffers(
-      product,
-      currency,
-      options.locale,
-      options.money
-    ),
-    colors,
-    colorCount: colors ? colors.length : undefined
-  };
-};
-
-/**
- * The row model above, for lists that are not listings. The favourites grid
- * publishes its wishlist entries through this so a card designed against a
- * product-grid row (`attributes.*`, `discountPercent`, `basketOffers`,
- * `colors`) binds identically over a favourites row — one card design, both
- * grids.
- */
-export const normalizeListingProduct = (
-  entry: unknown,
-  index: number,
-  options: ListingLocalizationOptions
-): ListingProduct | null => normalizeProduct(entry, index, options);
-
 const normalizeFacet = (entry: unknown, index: number): ListingFacet | null => {
   const facet = toRecord(entry);
   const data = toRecord(facet.data);
@@ -773,7 +168,7 @@ export const resolveListingContext = (
   if (!source) return null;
 
   const products = toArray(source.products)
-    .map((entry, index) => normalizeProduct(entry, index, options))
+    .map((entry, index) => normalizeListingProduct(entry, index, options))
     .filter((product): product is ListingProduct => product !== null);
 
   const pagination = toRecord(source.pagination);