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

package/src/region/region-contract.ts

@@ -0,0 +1,184 @@
+/**
+ * ZERO-5391 — per-country ("region") content contract shared by the theme
+ * editor and pz-theme. Two byte-identical copies:
+ *   pz-next/packages/pz-theme/src/region/region-contract.ts
+ *   pz-dynamic-widget/src/services/region/region-contract.ts
+ * Parity tests in both repos compare them byte for byte, so change both
+ * together.
+ *
+ * What keeps one file valid in both repos: no imports; every arrow parameter
+ * typed (the repos' Prettier configs differ only in `arrowParens`); no `any`;
+ * no ES2022 APIs (no `Object.hasOwn`); clean under the editor's strict tsc.
+ */
+export const REGION_SLUG_INFIX = '-region-';
+export const REGION_REGISTRY_SLUG = 'theme-regions';
+export const REGION_REGISTRY_ATTRIBUTE = 'theme_regions';
+export const REGION_REGISTRY_VERSION = 1;
+export const REGION_CONTENT_CAPABILITY = 'region-content';
+
+/**
+ * Attribute of a LIVE region copy (`regionSlug(P, code)`): a JSON array of
+ * every data-source record the copy's sections and blocks reference, each
+ * tagged `region: code`. The copy carries its own records so it renders them
+ * even while the shared theme-config is still cached without them.
+ */
+export const REGION_DATA_SOURCES_ATTRIBUTE = 'theme_region_dataSources';
+
+const REGION_CODE_PATTERN = /^[a-z]{2}$/;
+const REGISTRY_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export const isValidRegionCode = (code: unknown): code is string =>
+  typeof code === 'string' && REGION_CODE_PATTERN.test(code);
+
+/**
+ * `<slug>-region-<code>`; a preview of it is
+ * previewSlug(regionSlug(slug, code), id).
+ */
+export const regionSlug = (slug: string, code: string): string =>
+  `${slug}${REGION_SLUG_INFIX}${code}`;
+
+/**
+ * Slugs carrying the infix are reserved for region copies (page slugs, modal
+ * ids).
+ */
+export const isRegionReservedSlug = (slug: string): boolean =>
+  slug.includes(REGION_SLUG_INFIX);
+
+/**
+ * Whether the registry can list this placeholder slug: `readRegionRegistry`
+ * drops every other one, so only these areas can be customised per region.
+ * Pass the placeholder slug — a custom page is `page-<slug>`, and
+ * 'region-days' passes where 'page-region-days' does not.
+ */
+export const isRegionRegistrableSlug = (slug: unknown): boolean =>
+  typeof slug === 'string' &&
+  REGISTRY_SLUG_PATTERN.test(slug) &&
+  !isRegionReservedSlug(slug);
+
+/**
+ * Last subtag when ≥2 subtags and it is 2 letters: 'en-ae'→'ae',
+ * 'AR-AE'→'ae', 'zh-hant-tw'→'tw'; 'en','zh-hant','es-419'→''. Never pass
+ * apiValue.
+ */
+export const regionFromLocale = (value: unknown): string => {
+  if (typeof value !== 'string') return '';
+  const subtags = value.trim().toLowerCase().split('-');
+  const last = subtags.length >= 2 ? subtags[subtags.length - 1] : '';
+  return isValidRegionCode(last) ? last : '';
+};
+
+export interface MarketPlaceholderEntry {
+  updatedAt?: string;
+}
+
+export interface RegionEntry {
+  placeholders: Record<string, MarketPlaceholderEntry>;
+}
+
+export interface RegionRegistry {
+  version: number;
+  regions: Record<string, RegionEntry>;
+}
+
+export type RegionRegistryUnreadableReason =
+  | 'malformed-json'
+  | 'not-an-object'
+  | 'bad-version'
+  | 'no-regions';
+
+export type RegionRegistryRead =
+  | { kind: 'found'; registry: RegionRegistry }
+  | { kind: 'absent' }
+  | { kind: 'unreadable'; reason: RegionRegistryUnreadableReason };
+
+export const emptyRegionRegistry = (): RegionRegistry => ({
+  version: REGION_REGISTRY_VERSION,
+  regions: {}
+});
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const hasOwn = (record: object, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(record, key);
+
+/**
+ * Accepts the raw attribute: JSON string, commerce {value,kwargs} wrapping,
+ * or a parsed object. Any numeric version >= 1 is read, so later versions may
+ * only ADD keys. Unknown entry keys, invalid codes and unregistrable slugs are
+ * dropped; own properties only.
+ */
+export const readRegionRegistry = (raw: unknown): RegionRegistryRead => {
+  let value: unknown = isRecord(raw) && 'value' in raw ? raw.value : raw;
+  if (value === undefined || value === null || value === '')
+    return { kind: 'absent' };
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return { kind: 'unreadable', reason: 'malformed-json' };
+    }
+  }
+  if (!isRecord(value)) return { kind: 'unreadable', reason: 'not-an-object' };
+  const { version, regions } = value;
+  if (typeof version !== 'number' || !(version >= 1))
+    return { kind: 'unreadable', reason: 'bad-version' };
+  if (!isRecord(regions)) return { kind: 'unreadable', reason: 'no-regions' };
+  const registry: RegionRegistry = { version, regions: {} };
+  for (const [code, entry] of Object.entries(regions)) {
+    const placeholders = isRecord(entry) ? entry.placeholders : undefined;
+    if (!isValidRegionCode(code) || !isRecord(placeholders)) continue;
+    const kept: Record<string, MarketPlaceholderEntry> = {};
+    for (const [slug, meta] of Object.entries(placeholders)) {
+      if (!isRegionRegistrableSlug(slug)) continue;
+      const updatedAt = isRecord(meta) ? meta.updatedAt : undefined;
+      kept[slug] = typeof updatedAt === 'string' ? { updatedAt } : {};
+    }
+    registry.regions[code] = { placeholders: kept };
+  }
+  return { kind: 'found', registry };
+};
+
+export const marketPlaceholderSlugs = (
+  registry: RegionRegistry,
+  code: string
+): string[] =>
+  hasOwn(registry.regions, code)
+    ? Object.keys(registry.regions[code].placeholders)
+    : [];
+
+export const regionHasPlaceholder = (
+  registry: RegionRegistry,
+  code: string,
+  slug: string
+): boolean =>
+  hasOwn(registry.regions, code) &&
+  hasOwn(registry.regions[code].placeholders, slug);
+
+export const isWritableRegionRegistry = (registry: RegionRegistry): boolean =>
+  registry.version <= REGION_REGISTRY_VERSION;
+
+export const serializeRegionRegistry = (registry: RegionRegistry): string =>
+  JSON.stringify({
+    version: REGION_REGISTRY_VERSION,
+    regions: registry.regions
+  });
+
+/**
+ * Reads `REGION_DATA_SOURCES_ATTRIBUTE`: a JSON string, the commerce
+ * {value,kwargs} wrapping of one, or an already parsed array. Anything else
+ * (absent, malformed JSON, not an array) reads as []. The elements are not
+ * validated; they come back in a new array, and each reader keeps the records
+ * it can use.
+ */
+export const readRegionDataSources = (raw: unknown): unknown[] => {
+  let value: unknown = isRecord(raw) && 'value' in raw ? raw.value : raw;
+  if (typeof value === 'string') {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return [];
+    }
+  }
+  return Array.isArray(value) ? value.slice() : [];
+};

package/src/region/region-source.ts

@@ -0,0 +1,360 @@
+import * as React from 'react';
+import * as serverData from '@akinon/next/data/server';
+import appFetch from '@akinon/next/utils/app-fetch';
+import { ServerVariables } from '@akinon/next/utils/server-variables';
+import { draftMode } from 'next/headers';
+
+import { getWidgetDataWithRetry } from '../chrome/retrying-widget-data';
+import {
+  emptyRegionRegistry,
+  REGION_DATA_SOURCES_ATTRIBUTE,
+  REGION_REGISTRY_ATTRIBUTE,
+  REGION_REGISTRY_SLUG,
+  regionFromLocale,
+  regionHasPlaceholder,
+  regionSlug,
+  readRegionDataSources,
+  readRegionRegistry,
+  type RegionRegistry,
+  type RegionRegistryRead
+} from './region-contract';
+
+/**
+ * ZERO-5391 — per-country ("region") placeholder content, server side.
+ *
+ * A storefront locale that names a country (`en-ae` → `ae`) renders a
+ * placeholder from that country's own copy (`<slug>-region-<cc>`) when the
+ * theme editor's `theme-regions` registry lists the placeholder for the
+ * country. Everything else — a language-only locale, an unlisted placeholder,
+ * a registry nobody can read, a copy that does not answer — reads the shared
+ * default exactly as before. Failing closed to the default is deliberate: it
+ * is what the country's visitors saw before the area was customised.
+ *
+ * Two choke points consult this module: composition-source's placeholder read
+ * and preview-snapshot-source's blob read. Every surface that renders a
+ * placeholder (ChromeSlot, ComposableRegion, ThemePlaceholder, the error
+ * prefetch, custom pages, modals) goes through one of them.
+ *
+ * Server only, like the readers that import it: it reaches the request
+ * through `next/headers` and the core data layer. It must never import
+ * composition-source or preview-snapshot-source, because both import it.
+ */
+
+// `React.cache` exists on the RSC-capable React this package renders under;
+// fall back to the raw function on older cores, where correctness is identical
+// and the only cost is a second read.
+const cache = (React as { cache?: <T>(fn: T) => T }).cache;
+
+/**
+ * How long a found registry is reused across requests — and how long a locale
+ * that has never had one remembers the miss. Misses are never cached by Redis
+ * or the fetch cache, so without this a country-locale brand with no registry
+ * would ask commerce on every render.
+ */
+export const REGION_REGISTRY_MEMO_MS = 60_000;
+
+/**
+ * Redis TTL of the live registry read. The registry decides which copy every
+ * customised area renders, so a fork or a revert should show within about a
+ * minute, not the 900 s widget default.
+ */
+export const REGION_REGISTRY_CACHE_SECONDS = 60;
+
+/**
+ * A failed read of a registry this locale has already found is answered from
+ * the last found one — and remembered only this long, so the next request
+ * soon checks again.
+ */
+export const REGION_REGISTRY_FALLBACK_MEMO_MS = 10_000;
+
+/** The last found registry stands in for failing reads at most this long. */
+export const REGION_REGISTRY_LAST_FOUND_MAX_AGE_MS = 15 * 60_000;
+
+/**
+ * Backoff before the one extra attempt a locale that has found a registry
+ * gets (the first step of retrying-widget-data's backoff).
+ */
+export const REGION_REGISTRY_RETRY_DELAY_MS = 100;
+
+type MemoEntry = { registry: RegionRegistry; expires: number };
+type LastFound = { registry: RegionRegistry; readAt: number };
+
+let memo = new Map<string, MemoEntry>();
+let lastFound = new Map<string, LastFound>();
+
+const readRequestRegion = (): string =>
+  regionFromLocale(ServerVariables.locale);
+
+/**
+ * The region (country code) the request's locale names, or '' for a
+ * language-only locale. Never derived from the locale's `apiValue`.
+ */
+export const getRequestRegion = cache
+  ? cache(readRequestRegion)
+  : readRequestRegion;
+
+/**
+ * A named-preview render: a preview id AND draft mode, the two signals core's
+ * widget reads require as well. `ServerVariables` is a module global shared by
+ * concurrent requests, so the id alone may belong to someone else's render;
+ * draft mode is this request's own. The id is '' for ordinary traffic and
+ * undefined on v1 cores before 1.126.15.
+ */
+const isPreviewRequest = async (): Promise<boolean> => {
+  const previewId = (ServerVariables as { previewId?: unknown }).previewId;
+  if (typeof previewId !== 'string' || previewId === '') return false;
+  try {
+    return (await draftMode()).isEnabled === true;
+  } catch {
+    // No request scope (e.g. a build-time prerender): never a preview.
+    return false;
+  }
+};
+
+const readRegistryWidget = (
+  preview: boolean,
+  locale: string
+): Promise<unknown> =>
+  preview
+    ? // Uncached, and straight to the live slug: core's getWidgetData would
+      // first probe `theme-regions-preview-<id>` (a guaranteed miss) and then
+      // answer from Redis, which may predate the designer's last fork.
+      appFetch<unknown>({
+        url: `/widgets/${REGION_REGISTRY_SLUG}/`,
+        locale,
+        currency: ServerVariables.currency,
+        init: { next: { revalidate: 0 } }
+      })
+    : serverData.getWidgetData<unknown>({
+        slug: REGION_REGISTRY_SLUG,
+        locale,
+        cacheOptions: { expire: REGION_REGISTRY_CACHE_SECONDS }
+      });
+
+/**
+ * The raw registry attribute, read the way retrying-widget-data reads chrome:
+ * an empty answer or a throw is retried after a short backoff, and a throw on
+ * the last attempt propagates. `attempts` is 2 only for a locale that has
+ * found a registry before — there "nothing" means a failure, while a brand
+ * that never had a registry would otherwise pay the retry on every miss.
+ */
+const fetchRegistryAttribute = async (
+  preview: boolean,
+  locale: string,
+  attempts: number
+): Promise<unknown> => {
+  for (let attempt = 1; ; attempt++) {
+    const lastAttempt = attempt >= attempts;
+    try {
+      const widget = await readRegistryWidget(preview, locale);
+      if (widget) {
+        return (widget as { attributes?: Record<string, unknown> | null })
+          .attributes?.[REGION_REGISTRY_ATTRIBUTE];
+      }
+    } catch (error) {
+      if (lastAttempt) throw error;
+    }
+    if (lastAttempt) return undefined;
+    await new Promise((resolve) =>
+      setTimeout(resolve, REGION_REGISTRY_RETRY_DELAY_MS)
+    );
+  }
+};
+
+/**
+ * The registry for the request's locale.
+ *
+ * Live renders go through Redis (60 s) and a per-locale process memo; a named
+ * preview reads commerce directly every time and is never memoised, so the
+ * designer sees a fork the moment it is registered.
+ *
+ * Only a FOUND read replaces what a locale knows. The editor never deletes the
+ * registry (it prunes it down to no regions), so once a locale has found one,
+ * an absent, unreadable or failed read is a failure — a commerce blip that
+ * would otherwise turn every customised area back to the default for the memo
+ * window and could be frozen into an ISR page for minutes. Such a read gets
+ * one extra attempt and then serves the last found registry for at most
+ * REGION_REGISTRY_LAST_FOUND_MAX_AGE_MS, memoised only briefly. A locale that
+ * has never found a registry treats a miss as "no customised areas".
+ */
+const loadRegionRegistry = async (): Promise<RegionRegistry> => {
+  const preview = await isPreviewRequest();
+  const locale = ServerVariables.locale;
+
+  if (!preview) {
+    const hit = memo.get(locale);
+    if (hit && hit.expires > Date.now()) return hit.registry;
+  }
+
+  const last = lastFound.get(locale);
+  let read: RegionRegistryRead | null = null;
+  try {
+    read = readRegionRegistry(
+      await fetchRegistryAttribute(preview, locale, last ? 2 : 1)
+    );
+  } catch {
+    // Transport failure: settled below like any other read that found nothing.
+  }
+
+  const now = Date.now();
+  if (read?.kind === 'found') {
+    lastFound.set(locale, { registry: read.registry, readAt: now });
+    if (!preview) {
+      memo.set(locale, {
+        registry: read.registry,
+        expires: now + REGION_REGISTRY_MEMO_MS
+      });
+    }
+    return read.registry;
+  }
+
+  const fallback =
+    last && now - last.readAt <= REGION_REGISTRY_LAST_FOUND_MAX_AGE_MS
+      ? last.registry
+      : null;
+
+  if (read?.kind === 'unreadable') {
+    console.warn(
+      fallback
+        ? `[pz-theme] "${REGION_REGISTRY_SLUG}" is unreadable (${read.reason}); serving the last readable registry for now.`
+        : `[pz-theme] "${REGION_REGISTRY_SLUG}" is unreadable (${read.reason}); every region renders the default content.`
+    );
+  }
+
+  const registry = fallback ?? emptyRegionRegistry();
+  if (!preview) {
+    memo.set(locale, {
+      registry,
+      expires:
+        now +
+        (last ? REGION_REGISTRY_FALLBACK_MEMO_MS : REGION_REGISTRY_MEMO_MS)
+    });
+  }
+  return registry;
+};
+
+/** One registry per request, whichever reader asks first. */
+export const getRegionRegistry = cache
+  ? cache(loadRegionRegistry)
+  : loadRegionRegistry;
+
+/**
+ * The slug this request reads for placeholder `slug`: the region's own copy
+ * when the registry lists it for the request's region, otherwise `slug`
+ * itself. A language-only locale answers without any I/O.
+ */
+export const resolveRegionSlug = async (slug: string): Promise<string> => {
+  const region = getRequestRegion();
+  if (!region) return slug;
+  return regionHasPlaceholder(await getRegionRegistry(), region, slug)
+    ? regionSlug(slug, region)
+    : slug;
+};
+
+/** A placeholder widget as the data layer hands it over. */
+export type MarketPlaceholderCopy = {
+  slug?: string;
+  attributes?: Record<string, unknown> | null;
+};
+
+/** Commerce wraps every widget attribute as `{ value, kwargs }`. */
+const unwrapAttribute = (raw: unknown): unknown =>
+  typeof raw === 'object' &&
+  raw !== null &&
+  !Array.isArray(raw) &&
+  'value' in raw
+    ? (raw as { value?: unknown }).value
+    : raw;
+
+/**
+ * The region's own copy of placeholder `slug`, or null when the request reads
+ * the shared default: no region, an unlisted placeholder (never probed), or a
+ * listed copy that answers nothing after the chrome retries, throws, or comes
+ * without a layout.
+ *
+ * A copy counts only when it carries a `theme_editor_placeholder` value — an
+ * empty layout ('[]') included, so a country that emptied an area keeps it
+ * empty. An answer without one (a truthy 404 body, an attribute-less shell)
+ * must never stand in for the default.
+ */
+export const readMarketPlaceholderCopy = async (
+  slug: string
+): Promise<MarketPlaceholderCopy | null> => {
+  try {
+    const target = await resolveRegionSlug(slug);
+    if (target === slug) return null;
+
+    const copy = await getWidgetDataWithRetry<MarketPlaceholderCopy>(target);
+    return unwrapAttribute(copy?.attributes?.theme_editor_placeholder) != null
+      ? copy
+      : null;
+  } catch {
+    return null;
+  }
+};
+
+const recordId = (record: unknown): string | null => {
+  if (typeof record !== 'object' || record === null) return null;
+  const { id } = record as { id?: unknown };
+  return typeof id === 'string' && id !== '' ? id : null;
+};
+
+/**
+ * The data sources a placeholder's sections resolve against: theme-config's
+ * list, plus the records a region copy carries itself for ids theme-config
+ * LACKS, appended in the copy's order. Theme-config's record wins whenever it
+ * has the id.
+ *
+ * A fork points the copy's sections at fresh records tagged for the region
+ * and adds them to theme-config too, but theme-config is cached for up to
+ * 900 s while the registry is re-read every minute: without its own records
+ * a freshly registered copy would render sections bound to ids the cached
+ * theme-config does not know yet (no products). The copy also covers a record
+ * an editor running an older bundle dropped from theme-config.
+ *
+ * The copy does NOT win over theme-config: a copy is only rewritten when its
+ * own page is published, so a record the region edited on another page would
+ * otherwise stay pinned to its old version there indefinitely.
+ *
+ * Returns `dataSources` itself (same reference) when nothing is added: every
+ * default placeholder, a copy whose attribute is missing, malformed or holds
+ * no record with an id, and a copy whose records theme-config already holds.
+ */
+export const withRegionDataSources = <T>(
+  dataSources: T[],
+  placeholderWidget: unknown
+): T[] => {
+  const attributes = (
+    placeholderWidget as {
+      attributes?: Record<string, unknown> | null;
+    } | null
+  )?.attributes;
+  const raw = attributes?.[REGION_DATA_SOURCES_ATTRIBUTE];
+  if (raw === undefined || raw === null) return dataSources;
+
+  const own = new Map<string, T>();
+  for (const record of readRegionDataSources(raw)) {
+    const id = recordId(record);
+    if (id !== null && !own.has(id)) own.set(id, record as T);
+  }
+  if (own.size === 0) return dataSources;
+
+  const base: T[] = Array.isArray(dataSources) ? dataSources : [];
+  const present = new Set<string>();
+  for (const record of base) {
+    const id = recordId(record);
+    if (id !== null) present.add(id);
+  }
+  const missing: T[] = [];
+  own.forEach((record, id) => {
+    if (!present.has(id)) missing.push(record);
+  });
+  if (missing.length === 0) return dataSources;
+  return [...base, ...missing];
+};
+
+/** Test hook: forgets every memoised and last-found registry. */
+export const __resetRegionSourceForTests = (): void => {
+  memo = new Map();
+  lastFound = new Map();
+};