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

package/src/blocks/product-block-utils.tsx

@@ -0,0 +1,639 @@
+'use client';
+
+import React from 'react';
+import { getResponsiveValue } from '../utils';
+import { useThemePageContext } from '../theme-page-context';
+import {
+  formatMoney,
+  MoneyStyleOptions,
+  parseAmount
+} from './commerce-format';
+
+export interface ThemeProductImage {
+  pk?: number | string;
+  url?: string;
+  image?: string;
+  alt?: string;
+  order?: number;
+}
+
+/**
+ * Commerce sends a whole `Product` under every variant option, not the four
+ * fields the theme used to declare. The extra ones are what a swatch needs:
+ * the option's own image, its numeric `stock` for a low-stock marker, and the
+ * attribute record a colour code lives in.
+ */
+export interface ThemeVariantOptionProduct {
+  pk?: number;
+  name?: string;
+  image?: string;
+  absolute_url?: string;
+  in_stock?: boolean;
+  stock?: number;
+  sku?: string;
+  price?: string | number;
+  retail_price?: string | number;
+  currency_type?: string;
+  productimage_set?: ThemeProductImage[];
+  attributes?: Record<string, unknown>;
+  attributes_kwargs?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface ThemeVariantOption {
+  label?: string;
+  value?: string;
+  order?: string;
+  in_stock?: boolean;
+  is_selected?: boolean;
+  is_selectable?: boolean;
+  is_selectable_without_stock?: boolean;
+  /** Some payloads put the swatch image and stock on the option itself. */
+  image?: string;
+  stock?: number;
+  attributes?: Record<string, unknown>;
+  attributes_kwargs?: Record<string, unknown>;
+  product?: ThemeVariantOptionProduct;
+  [key: string]: unknown;
+}
+
+export interface ThemeVariantGroup {
+  attribute_key?: string;
+  attribute_name?: string;
+  options?: ThemeVariantOption[];
+}
+
+export interface ThemeProduct {
+  pk?: number;
+  title?: string;
+  name?: string;
+  url?: string;
+  image?: string;
+  images?: ThemeProductImage[];
+  price?: string | number;
+  retailPrice?: string | number;
+  currency?: string;
+  description?: string;
+  /** `key` is the commerce attribute key, kept for includeKeys/excludeKeys. */
+  attributes?: Array<{ key?: string; label?: string; value?: string }>;
+  selectedVariant?: ThemeProduct | null;
+  variants?: ThemeVariantGroup[];
+  in_stock?: boolean;
+  stock?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * The product a repeated row is currently rendering.
+ *
+ * Commerce blocks read "the product" off the page context, which on a PDP is
+ * the viewed product and on a listing is nothing at all. A favourite button
+ * dropped into a product card therefore acted on nothing — and the same card
+ * inside a recommendations row on a PDP acted on the *page's* product, so
+ * every heart in the row toggled the same wrong item.
+ *
+ * The context value is an object wrapping the product rather than the product
+ * itself, so "inside a row that has no product" (the empty rows the designer
+ * draws against) stays distinguishable from "not inside a row at all". Only
+ * the second may fall through to the page's product.
+ */
+interface ThemeItemScopeValue {
+  product: ThemeProduct | null;
+}
+
+const ThemeItemScopeContext = React.createContext<ThemeItemScopeValue | null>(
+  null
+);
+
+export const ThemeItemScopeProvider = ({
+  product,
+  children
+}: {
+  product: ThemeProduct | null;
+  children: React.ReactNode;
+}) => {
+  const value = React.useMemo(() => ({ product }), [product]);
+
+  return (
+    <ThemeItemScopeContext.Provider value={value}>
+      {children}
+    </ThemeItemScopeContext.Provider>
+  );
+};
+
+/** Non-null while a repeated product row renders; null everywhere else. */
+export const useThemeItemScope = (): ThemeItemScopeValue | null =>
+  React.useContext(ThemeItemScopeContext);
+
+/**
+ * The ambient product: the row's item while a repeated product row renders,
+ * otherwise the product `buildProductPageContext()` publishes on the page
+ * context. Returning null instead of throwing keeps every block droppable on
+ * non-product pages without breaking the render.
+ */
+export const useThemeProduct = (): ThemeProduct | null => {
+  const itemScope = React.useContext(ThemeItemScopeContext);
+  const pageContext = useThemePageContext();
+
+  // Outside a row — which is every composition that exists today — the page
+  // context is read exactly as it was before the scope existed. A scope that
+  // resolved no product falls through for the same reason: shadowing the page
+  // product with nothing would silence blocks that render correctly today, on
+  // a PDP whose recommendations row has not loaded yet or in the designer,
+  // where placeholder rows carry no data at all.
+  if (itemScope?.product) return itemScope.product;
+
+  const product = (pageContext as Record<string, unknown> | null)?.product;
+
+  return product && typeof product === 'object'
+    ? (product as ThemeProduct)
+    : null;
+};
+
+const isEmptyValue = (value: unknown) =>
+  value === undefined || value === null || value === '';
+
+/**
+ * The same field under the two names that reach these blocks. A page-context
+ * product carries the raw commerce names (`in_stock`, `retail_price`,
+ * `absolute_url`); a normalised listing row carries the camel-case ones
+ * (`inStock`, `retailPrice`, `url`). Resolving the pair here is what lets a
+ * block ask for one name and work on both, instead of every block growing its
+ * own second lookup.
+ */
+const PRODUCT_FIELD_ALIASES: Record<string, string[]> = {
+  title: ['name'],
+  name: ['title'],
+  url: ['absolute_url'],
+  absolute_url: ['url'],
+  in_stock: ['inStock'],
+  inStock: ['in_stock'],
+  retail_price: ['retailPrice'],
+  retailPrice: ['retail_price'],
+  currency: ['currency_type'],
+  currency_type: ['currency']
+};
+
+/**
+ * The viewed product already matches the PDP URL, so it wins. `selectedVariant`
+ * is only consulted for fields the base payload leaves empty — group products
+ * carry price/stock on the variant rather than on the parent.
+ *
+ * Aliases are consulted LAST, only where the requested name resolved to
+ * nothing on both. A commerce payload always carries the canonical name, so
+ * this cannot move any value a PDP block reads today.
+ */
+export const pickProductField = <T,>(
+  product: ThemeProduct | null,
+  key: string
+): T | undefined => {
+  if (!product) return undefined;
+
+  const base = product[key];
+  if (!isEmptyValue(base)) return base as T;
+
+  const variant = product.selectedVariant;
+  if (variant && !isEmptyValue(variant[key])) return variant[key] as T;
+
+  for (const alias of PRODUCT_FIELD_ALIASES[key] || []) {
+    if (!isEmptyValue(product[alias])) return product[alias] as T;
+    if (variant && !isEmptyValue(variant[alias])) return variant[alias] as T;
+  }
+
+  return undefined;
+};
+
+/**
+ * Editor toggles arrive as booleans, as the strings a select would store, or
+ * as a per-breakpoint object. Resolving the breakpoint here is what lets every
+ * commerce block — PDP and listing alike — share a single toggle reader
+ * instead of two exports with the same name and different signatures.
+ */
+export const readToggle = (
+  value: unknown,
+  currentBreakpoint: string,
+  fallback: boolean
+): boolean => {
+  const raw = getResponsiveValue(value, currentBreakpoint, fallback);
+  if (isEmptyValue(raw)) return fallback;
+  if (typeof raw === 'boolean') return raw;
+  if (typeof raw === 'number') return raw !== 0;
+
+  const normalized = String(raw).trim().toLowerCase();
+  if (normalized === 'true' || normalized === '1' || normalized === 'yes') {
+    return true;
+  }
+  if (normalized === 'false' || normalized === '0' || normalized === 'no') {
+    return false;
+  }
+
+  return fallback;
+};
+
+/** Kept for existing callers; the parsing itself lives in commerce-format. */
+export const parsePriceValue = (value: unknown): number | null =>
+  parseAmount(value);
+
+export interface OrderLineLike {
+  id?: number;
+  price?: string | number;
+  quantity?: string | number;
+  total_amount?: string | number;
+  product?: {
+    pk?: number;
+    name?: string;
+    image?: string;
+    absolute_url?: string;
+  } | null;
+}
+
+export interface GroupedOrderLine<T extends OrderLineLike> {
+  /** Stable React key: the product pk when the payload carries one. */
+  key: string;
+  name: string;
+  image: string;
+  href: string;
+  /** Unit price of the first line in the group, as it came from commerce. */
+  price: string;
+  /** Sum of the group's line totals; null when nothing in it parses. */
+  total: number | null;
+  quantity: number;
+  /** First line of the group — status, currency and shipment fields live on it. */
+  item: T;
+}
+
+/**
+ * pz writes ONE order line per unit, so three of the same product arrive as
+ * three lines. Every order block has to collapse them the same way, otherwise
+ * the same order reads as one "x3" row on the thank-you page and three "x1"
+ * rows in the account. Grouping lives here so the payload is read one way.
+ *
+ * `quantity` is summed rather than counted so a payload that does carry a line
+ * quantity (older commerce versions, and brands that merge lines server-side)
+ * is respected instead of being flattened back to one.
+ */
+export const groupOrderItems = <T extends OrderLineLike>(
+  items: T[] | null | undefined
+): GroupedOrderLine<T>[] => {
+  const source = Array.isArray(items) ? items : [];
+
+  return source.reduce<GroupedOrderLine<T>[]>((accumulator, item) => {
+    const pk = item.product?.pk;
+    const key = String(pk ?? item.id ?? accumulator.length);
+    // Lines without a product pk cannot be proven identical, so they stay
+    // separate rows instead of collapsing into an arbitrary neighbour.
+    const existing =
+      pk === undefined || pk === null
+        ? undefined
+        : accumulator.find((entry) => entry.key === key);
+    const quantity = parseAmount(item.quantity) ?? 1;
+    const lineTotal = parseAmount(item.total_amount || item.price);
+
+    if (existing) {
+      existing.quantity += quantity;
+      existing.total =
+        lineTotal === null ? existing.total : (existing.total ?? 0) + lineTotal;
+
+      return accumulator;
+    }
+
+    accumulator.push({
+      key,
+      name: item.product?.name || '',
+      image: item.product?.image || '',
+      href: item.product?.absolute_url || '',
+      price: String(item.price ?? ''),
+      total: lineTotal,
+      quantity,
+      item
+    });
+
+    return accumulator;
+  }, []);
+};
+
+/**
+ * Every money string in the theme goes through commerce-format so the PDP, the
+ * product grid and the basket agree on separators and currency placement. The
+ * locale must be handed in by the caller (from `useLocalization()`): an
+ * implicit Intl locale resolves to the Node default on the server and to the
+ * browser locale on the client, which hydrates as a mismatch.
+ *
+ * `money` carries the brand's own format (digits, currency token, its side).
+ * Omitting it formats exactly as before, so callers that never learned about
+ * it are unaffected.
+ */
+export const formatPrice = (
+  value: unknown,
+  currency: unknown,
+  showCurrency = true,
+  locale?: string,
+  money?: MoneyStyleOptions
+): string | null => {
+  if (isEmptyValue(value)) return null;
+
+  const formatted = formatMoney(value, {
+    ...money,
+    locale,
+    currency: String(currency || ''),
+    showCurrency
+  });
+  if (formatted) return formatted;
+
+  // Unparseable but non-empty values ("Call for price") stay visible as-is.
+  const text = String(value).trim();
+  return text || null;
+};
+
+export const isProductInStock = (product: ThemeProduct | null): boolean => {
+  if (!product) return false;
+
+  const inStock = pickProductField<boolean>(product, 'in_stock');
+  if (typeof inStock === 'boolean') return inStock;
+
+  const stock = Number(pickProductField(product, 'stock'));
+  if (Number.isFinite(stock)) return stock > 0;
+
+  // Unknown stock must not block the CTA — commerce still validates on add.
+  return true;
+};
+
+const toRecord = (value: unknown): Record<string, unknown> =>
+  value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+
+const toText = (value: unknown): string =>
+  typeof value === 'string'
+    ? value.trim()
+    : typeof value === 'number' && Number.isFinite(value)
+    ? String(value)
+    : '';
+
+/**
+ * The image a variant option should show in a swatch. The option product is
+ * NOT run through `normalizeProductEntry()`, so `image` can be empty while the
+ * gallery holds the shot — both places are read here rather than in a renderer.
+ */
+export const getVariantOptionImage = (
+  option: ThemeVariantOption | null | undefined
+): string => {
+  const product = option?.product;
+  const direct = toText(option?.image) || toText(product?.image);
+  if (direct) return direct;
+
+  const first = (product?.productimage_set || [])[0];
+
+  return toText(first?.image) || toText(first?.url);
+};
+
+/**
+ * The option's numeric stock, or null when the payload does not carry one.
+ * Null and 0 must stay distinguishable: a low-stock marker may only appear on
+ * a number commerce actually sent, never on an unknown.
+ */
+export const getVariantOptionStock = (
+  option: ThemeVariantOption | null | undefined
+): number | null => {
+  const candidates = [option?.stock, option?.product?.stock];
+
+  for (const candidate of candidates) {
+    if (isEmptyValue(candidate)) continue;
+
+    const numeric = Number(candidate);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+
+  return null;
+};
+
+/**
+ * Sold out, for one variant option — the package's single answer to that
+ * question.
+ *
+ * Commerce spells the same fact three ways across payloads, so all three are
+ * read: the option's own `in_stock`, the `is_selectable` commerce computed for
+ * it, and a numeric `stock` that reached zero. Every block that decides
+ * whether a LEAF can be sold has to give the same answer, because they are
+ * deciding about the same basket — the quick-view overlay in the
+ * recommendations strip held its own opinion and posted a sold-out leaf to the
+ * add endpoint.
+ *
+ * `variant-selector-block.tsx` still keeps a local `isOptionSoldOut` with
+ * exactly this body; collapse it onto this export the next time that file is
+ * opened, so the count of answers goes to one.
+ */
+export const isVariantOptionSoldOut = (
+  option: ThemeVariantOption | null | undefined
+): boolean =>
+  option?.in_stock === false ||
+  option?.is_selectable === false ||
+  getVariantOptionStock(option) === 0;
+
+const isColorKey = (key: string): boolean => {
+  const normalized = key.toLowerCase();
+
+  return (
+    normalized.includes('hex') ||
+    normalized.includes('color') ||
+    normalized.includes('colour') ||
+    normalized.includes('swatch') ||
+    normalized.includes('rgb')
+  );
+};
+
+/**
+ * Colour attributes hold either a machine colour ("#0A1F44", "0a1f44") or the
+ * shopper-facing name of one ("Kırmızı", "Navy Blue"). Only the first is usable
+ * as a CSS colour, so anything else resolves to '' and the renderer can fall
+ * back to a text swatch instead of painting an invalid value.
+ */
+const asCssColor = (value: unknown): string => {
+  const text = toText(value);
+  if (!text) return '';
+
+  if (/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(text)) return text;
+  if (/^([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(text)) return `#${text}`;
+  if (/^(rgb|rgba|hsl|hsla)\([^()]*\)$/i.test(text)) return text;
+  // A bare ASCII word may still be a CSS named colour; a browser drops it
+  // harmlessly when it is not. Anything with spaces or accents is a label.
+  if (/^[a-z]+$/i.test(text)) return text.toLowerCase();
+
+  return '';
+};
+
+/** Attribute records arrive as `{ key: value }` or as `{ key: { label, value } }`. */
+const readColorFromRecord = (source: unknown): string => {
+  for (const [key, entry] of Object.entries(toRecord(source))) {
+    if (!isColorKey(key)) continue;
+
+    const nested = entry && typeof entry === 'object' ? toRecord(entry) : null;
+    const color = asCssColor(
+      nested ? nested.value ?? nested.hex ?? nested.label : entry
+    );
+    if (color) return color;
+  }
+
+  return '';
+};
+
+/**
+ * A CSS colour for the option's swatch, or '' when the payload has none.
+ * Probed from most to least specific: the option's own fields, its attribute
+ * record, then the same two on the product behind it.
+ */
+export const getVariantOptionColor = (
+  option: ThemeVariantOption | null | undefined
+): string => {
+  if (!option) return '';
+
+  const sources = [
+    option,
+    option.attributes,
+    option.attributes_kwargs,
+    option.product?.attributes,
+    option.product?.attributes_kwargs,
+    option.product
+  ];
+
+  for (const source of sources) {
+    const color = readColorFromRecord(source);
+    if (color) return color;
+  }
+
+  return '';
+};
+
+/**
+ * The prior price commerce publishes for the price-history caption several
+ * markets require ("son 30 günün en düşük fiyatı", EU Omnibus).
+ *
+ * The payload field is `price_extra_field.previous_price` — that is what the
+ * PDP product carries and what brand storefronts read today. A row that came
+ * through `normalizeListingProduct()` has already flattened and formatted the
+ * same value onto `previousPrice`, so both spellings resolve here rather than
+ * in a block: the price block is dropped on a PDP and inside a product card,
+ * and one control has to work in both places.
+ *
+ * Nothing is derived: when commerce sends no previous price this returns
+ * undefined and the caller prints no caption. A price-history line is a legal
+ * claim, so an invented one is worse than a missing one.
+ */
+export const getPreviousPrice = (
+  product: ThemeProduct | null
+): string | number | undefined => {
+  if (!product) return undefined;
+
+  for (const source of [product, product.selectedVariant]) {
+    if (!source) continue;
+
+    const nested = toRecord(source.price_extra_field).previous_price;
+    if (!isEmptyValue(nested)) return nested as string | number;
+
+    const flat = source.previousPrice ?? source.previous_price;
+    if (!isEmptyValue(flat)) return flat as string | number;
+  }
+
+  return undefined;
+};
+
+export interface ProductPriceRange {
+  min: number;
+  max: number;
+}
+
+/**
+ * The spread of a group product's variant prices, or null when there is none.
+ * Every variant option carries a whole product (see
+ * `ThemeVariantOptionProduct`), so the range is read off the payload the block
+ * already has instead of being fetched.
+ *
+ * Options commerce cannot sell are skipped: a sold-out variant's price is not
+ * a price a shopper can pay, and it is usually the one anchoring the low end.
+ * Null unless two prices actually differ, so a card falls back to the single
+ * price it shows today rather than printing "₺1.299 – ₺1.299".
+ */
+export const getVariantPriceRange = (
+  product: ThemeProduct | null
+): ProductPriceRange | null => {
+  if (!product) return null;
+
+  const amounts: number[] = [];
+
+  (product.variants || []).forEach((group) => {
+    (group?.options || []).forEach((option) => {
+      if (option?.is_selectable === false) return;
+
+      const amount = parseAmount(option?.product?.price ?? option?.price);
+      if (amount !== null) amounts.push(amount);
+    });
+  });
+
+  if (amounts.length < 2) return null;
+
+  const min = Math.min(...amounts);
+  const max = Math.max(...amounts);
+
+  return max > min ? { min, max } : null;
+};
+
+export const getProductName = (product: ThemeProduct | null): string =>
+  String(
+    pickProductField<string>(product, 'title') ||
+      pickProductField<string>(product, 'name') ||
+      ''
+  );
+
+export const stripHtml = (html: unknown): string =>
+  String(html || '')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#39;/gi, "'")
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/** Truncates on a word boundary so the excerpt never cuts mid-word. */
+export const truncateText = (text: string, maxLength: number): string => {
+  if (!text || text.length <= maxLength) return text;
+
+  const sliced = text.slice(0, maxLength);
+  const lastSpace = sliced.lastIndexOf(' ');
+  const safe = lastSpace > maxLength * 0.6 ? sliced.slice(0, lastSpace) : sliced;
+
+  return `${safe.trimEnd()}…`;
+};
+
+/**
+ * Neutral, non-shipping hint so authors can still see and select a block that
+ * has no data behind it. Never rendered on the storefront.
+ *
+ * `attribute` carries the block's own root data-* attribute onto the
+ * placeholder: tooling (and the designer selection layer) keys on selectors
+ * like `[data-product-title]`, which would otherwise stop matching the moment
+ * the block has no data.
+ */
+export const DesignerPlaceholder = ({
+  label,
+  attribute
+}: {
+  label: string;
+  attribute?: string;
+}) => (
+  <span
+    data-theme-block-placeholder=""
+    {...(attribute ? { [attribute]: '' } : {})}
+    style={{
+      display: 'inline-block',
+      padding: '6px 10px',
+      border: '1px dashed #d1d5db',
+      borderRadius: '4px',
+      color: '#6b7280',
+      fontSize: '12px',
+      lineHeight: 1.4
+    }}
+  >
+    {label}
+  </span>
+);