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

package/src/chrome/chrome-slot.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+import { getWidgetData } from '@akinon/next/data/server';
+import ThemePlaceholder from '../theme-placeholder';
+import {
+  readCompositionState,
+  warnAboutUncomposedSlot
+} from './composition-state';
+import { ChromeFallback } from './chrome-fallback';
+
+interface ChromeSlotProps {
+  /** Placeholder slug the editor composes into ('header', 'product-page-body', …) */
+  slug: string;
+  /** The brand's existing markup, rendered until a composition is published */
+  fallback?: React.ReactNode;
+  /**
+   * Commerce data the composed blocks read (product, listing, basket…).
+   * Build it with the helpers in ./page-context so the field names match
+   * what the blocks expect.
+   */
+  pageContext?: Record<string, unknown> | null;
+}
+
+/**
+ * Progressive chrome takeover slot. If the theme editor has published a
+ * composition for this slug, it fully replaces the brand markup; until
+ * then the brand's own chrome renders untouched. Inside the editor the
+ * fallback hides so the designer always composes into the placeholder.
+ */
+export default async function ChromeSlot({
+  slug,
+  fallback,
+  pageContext = null
+}: ChromeSlotProps) {
+  let hasComposition = false;
+
+  try {
+    // The generic is the widget's attributes bag, not the widget wrapper
+    const data = await getWidgetData<{
+      theme_editor_placeholder?: unknown;
+    }>({ slug });
+
+    const state = readCompositionState(data);
+    hasComposition = state.kind === 'composed';
+    // Explain a slot that kept the project markup — see composition-state.ts
+    // for why "missing" and "empty" must not read as the same thing.
+    warnAboutUncomposedSlot(slug, state);
+  } catch {
+    // No chrome widget published yet — brand fallback stays active
+  }
+
+  if (hasComposition) {
+    return (
+      <div data-chrome-slot={slug}>
+        <ThemePlaceholder slug={slug} pageContext={pageContext} />
+      </div>
+    );
+  }
+
+  return (
+    <div data-chrome-slot={slug}>
+      {fallback ? (
+        <ChromeFallback slug={slug}>{fallback}</ChromeFallback>
+      ) : null}
+      {/* Empty until the designer overrides this area from the editor */}
+      <ThemePlaceholder slug={slug} pageContext={pageContext} />
+    </div>
+  );
+}

package/src/chrome/composition-state.ts

@@ -0,0 +1,92 @@
+import { devWarn } from '../utils/dev-warn';
+
+/**
+ * Why a chrome slot decided to keep — or withdraw — the brand's own markup.
+ *
+ * The distinction matters because the data layer swallows a 404 and returns
+ * nothing, so "no widget exists for this slug" and "a widget exists with an
+ * empty layout" arrive at the renderer as the same `null`. They have opposite
+ * causes: the first usually means the editor is saving into a different store
+ * than the one this storefront reads, the second means nobody has composed the
+ * area yet. A slot that cannot tell them apart cannot explain itself, and the
+ * one time it mattered the absence of a warning was read as proof that the
+ * fetch had succeeded.
+ */
+export type CompositionState =
+  | { kind: 'missing' }
+  | { kind: 'empty' }
+  | { kind: 'malformed' }
+  | { kind: 'composed'; sectionCount: number };
+
+type WidgetLike = {
+  attributes?: { theme_editor_placeholder?: unknown } | null;
+} | null;
+
+/**
+ * Read a placeholder widget the way the render engine does: the layout may
+ * arrive as an array, as a JSON string, or wrapped in `{ value }` depending on
+ * which backend and which core version answered.
+ */
+export const readCompositionState = (data: WidgetLike): CompositionState => {
+  if (!data) return { kind: 'missing' };
+
+  let layout: unknown = data.attributes?.theme_editor_placeholder;
+
+  if (
+    layout &&
+    typeof layout === 'object' &&
+    !Array.isArray(layout) &&
+    'value' in (layout as Record<string, unknown>)
+  ) {
+    layout = (layout as { value: unknown }).value;
+  }
+
+  if (typeof layout === 'string') {
+    const trimmed = layout.trim();
+    if (!trimmed) return { kind: 'empty' };
+    try {
+      layout = JSON.parse(trimmed);
+    } catch {
+      return { kind: 'malformed' };
+    }
+  }
+
+  if (layout === undefined || layout === null) return { kind: 'empty' };
+  if (!Array.isArray(layout)) return { kind: 'malformed' };
+  if (layout.length === 0) return { kind: 'empty' };
+
+  return { kind: 'composed', sectionCount: layout.length };
+};
+
+/**
+ * Dev-only explanation of a slot that kept the brand markup. One line per slug
+ * per process (see `devWarn`), so a brand with no compositions at all does not
+ * flood the console.
+ */
+export const warnAboutUncomposedSlot = (
+  slug: string,
+  state: CompositionState
+): void => {
+  if (state.kind === 'composed') return;
+
+  if (state.kind === 'missing') {
+    devWarn(
+      'ChromeSlot',
+      `No widget answered for placeholder "${slug}", so the project's own markup stays. Either nothing has been published for this slug, or it was published to a different store than the one this storefront reads — compare the storefront's commerce backend with the Omnitron the theme editor is connected to.`
+    );
+    return;
+  }
+
+  if (state.kind === 'malformed') {
+    devWarn(
+      'ChromeSlot',
+      `Placeholder "${slug}" carries a layout that is neither a list of sections nor parseable JSON, so the project's own markup stays.`
+    );
+    return;
+  }
+
+  devWarn(
+    'ChromeSlot',
+    `Placeholder "${slug}" exists but its layout is empty, so the project's own markup stays. An empty layout is what the editor writes when it first creates the placeholder, and also what a placeholder holding only native sections persists.`
+  );
+};

package/src/chrome/page-context.ts

@@ -0,0 +1,387 @@
+/**
+ * Page context builders for the composable pages.
+ *
+ * These used to live in the brand app, which meant every storefront kept
+ * its own copy in step with the block contract. They ship with the render
+ * engine instead: a brand hands the raw commerce payload to a slot and the
+ * blocks read normalised fields from the context.
+ *
+ * Route defaults are overridable because brands rename these paths.
+ */
+export interface PageContextRoutes {
+  home?: string;
+  basket?: string;
+  checkout?: string;
+  account?: string;
+}
+
+const DEFAULT_ROUTES: Required<PageContextRoutes> = {
+  home: '/',
+  basket: '/basket',
+  checkout: '/orders/checkout',
+  account: '/account'
+};
+
+let routes: Required<PageContextRoutes> = DEFAULT_ROUTES;
+
+/** Lets a brand align the context defaults with its own ROUTES table */
+export const configurePageContextRoutes = (overrides: PageContextRoutes) => {
+  routes = { ...DEFAULT_ROUTES, ...overrides };
+};
+
+const ROUTES = {
+  get HOME() {
+    return routes.home;
+  },
+  get BASKET() {
+    return routes.basket;
+  },
+  get CHECKOUT() {
+    return routes.checkout;
+  },
+  get ACCOUNT() {
+    return routes.account;
+  }
+};
+import type {
+  Basket,
+  BreadcrumbResultType,
+  GetCategoryResponse,
+  Product,
+  ProductResult
+} from '@akinon/next/types';
+
+type UnknownRecord = Record<string, unknown>;
+
+const toRecord = (value: unknown): UnknownRecord =>
+  value && typeof value === 'object' ? (value as UnknownRecord) : {};
+
+const toStringValue = (value: unknown, fallback = ''): string =>
+  typeof value === 'string' ? value : fallback;
+
+const humanizeSlug = (value: string) =>
+  value
+    .split('-')
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+
+const normalizeProductImages = (
+  product?: Product | null
+): Array<Record<string, unknown>> =>
+  (product?.productimage_set || []).map((item, index) => ({
+    ...item,
+    url: item.image,
+    alt: `${product?.name || 'Product'} ${index + 1}`
+  }));
+
+/**
+ * The commerce attribute key travels with the row: it is what the editor's
+ * includeKeys/excludeKeys match on, and dropping it left those controls dead
+ * because the block could only fall back to a positional `attribute-<index>`.
+ */
+const normalizeAttributeEntries = (
+  attributes: unknown
+): Array<Record<string, string>> => {
+  const record = toRecord(attributes);
+
+  return Object.entries(record)
+    .map(([recordKey, entry]) => {
+      const typedEntry = toRecord(entry);
+      const label = toStringValue(typedEntry.label);
+      const value = toStringValue(typedEntry.value);
+
+      if (!label && !value) {
+        return null;
+      }
+
+      // `attributes_kwargs` is keyed by the attribute key, so the record key is
+      // authoritative. An array payload only yields positional indices, and
+      // there the entry's own key is the only real one.
+      const key = /^\d+$/.test(recordKey)
+        ? toStringValue(typedEntry.key, recordKey)
+        : recordKey;
+
+      return { key, label, value };
+    })
+    .filter(
+      (entry): entry is { key: string; label: string; value: string } =>
+        entry !== null
+    );
+};
+
+export const normalizeProductEntry = (
+  product?: Product | null
+): Record<string, unknown> | null => {
+  if (!product) {
+    return null;
+  }
+
+  const activePrice = toRecord((product as Product & UnknownRecord).active_price);
+  const images = normalizeProductImages(product);
+
+  return {
+    ...product,
+    title: product.name,
+    name: product.name,
+    url: product.absolute_url,
+    image: product.image || images[0]?.url || '',
+    images,
+    price: activePrice.price ?? product.price,
+    retailPrice: activePrice.retail_price ?? product.retail_price,
+    currency: activePrice.currency_type ?? product.currency_type ?? '',
+    description: product.description || '',
+    attributes: normalizeAttributeEntries(product.attributes_kwargs)
+  };
+};
+
+/**
+ * `breadcrumbData` is fetched next to the product by `getProductData()` and was
+ * previously handed only to the brand's own PDP layout, which left the PDP the
+ * one page type with no trail on the context. It is published under the same
+ * `breadcrumbs` key, in the same raw shape, as `buildListingPageContext()`.
+ */
+export const buildProductPageContext = (
+  data: ProductResult,
+  breadcrumbData?: BreadcrumbResultType[]
+) => {
+  const normalizedProduct = normalizeProductEntry(data.product);
+  const normalizedSelectedVariant = normalizeProductEntry(data.selected_variant);
+
+  return {
+    page: {
+      type: 'product',
+      title: normalizedProduct?.title || 'Product',
+      path: normalizedProduct?.url || ''
+    },
+    // Emitted only when a brand hands the trail over, so a call site that has
+    // not been updated publishes exactly the context it publishes today.
+    ...(breadcrumbData ? { breadcrumbs: breadcrumbData } : {}),
+    product: {
+      ...normalizedProduct,
+      selectedVariant: normalizedSelectedVariant,
+      selected_variant: normalizedSelectedVariant,
+      variants: data.variants || []
+    }
+  };
+};
+
+export const buildHomepagePageContext = () => ({
+  page: {
+    type: 'homepage',
+    title: 'Homepage',
+    slug: 'homepage',
+    path: ROUTES.HOME
+  },
+  homepage: {
+    title: 'Homepage',
+    slug: 'homepage',
+    path: ROUTES.HOME
+  }
+});
+
+export const buildCustomPageContext = (slug: string) => {
+  const title = humanizeSlug(slug) || 'Custom Page';
+  const path = `/pages/${slug}`;
+
+  return {
+    page: {
+      type: 'custom-page',
+      title,
+      slug,
+      path
+    },
+    customPage: {
+      title,
+      slug,
+      path
+    }
+  };
+};
+
+export const buildListingPageContext = ({
+  data,
+  breadcrumbData,
+  pageType,
+  path,
+  title: titleOverride
+}: {
+  data: GetCategoryResponse;
+  breadcrumbData?: BreadcrumbResultType[];
+  /**
+   * `special` covers campaign/collection pages: same listing shape, but the
+   * heading comes from the special page rather than from a category.
+   */
+  pageType: 'category' | 'search' | 'plp' | 'special';
+  path?: string;
+  title?: string;
+}) => {
+  const normalizedProducts = (data.products || [])
+    .map(product => normalizeProductEntry(product))
+    .filter((product): product is Record<string, unknown> => product !== null);
+  const categorySeoTitle = toStringValue(
+    data.category?.attributes?.category_seo_title?.value?.text
+  );
+  const effectivePath = path || data.category?.absolute_url || ROUTES.HOME;
+  const totalProducts =
+    Number(toRecord(data.pagination).count) || normalizedProducts.length;
+  const title =
+    titleOverride ||
+    (pageType === 'search'
+      ? data.search_text
+        ? `Search results for ${data.search_text}`
+        : 'Search Results'
+      : data.category?.name || 'Product Listing');
+
+  const category = {
+    ...(data.category || {}),
+    title: data.category?.name || '',
+    name: data.category?.name || '',
+    url: data.category?.absolute_url || '',
+    description: categorySeoTitle,
+    seoTitle: categorySeoTitle,
+    facets: data.facets || [],
+    products: normalizedProducts
+  };
+
+  const listingBase = {
+    title,
+    path: effectivePath,
+    query: data.search_text || '',
+    products: normalizedProducts,
+    totalProducts,
+    resultCount: totalProducts,
+    facets: data.facets || [],
+    sorters: data.sorters || [],
+    pagination: data.pagination || {},
+    category
+  };
+
+  return {
+    page: {
+      type: pageType,
+      title,
+      path: effectivePath
+    },
+    category,
+    listing: {
+      ...listingBase,
+      breadcrumbs: breadcrumbData || []
+    },
+    search: {
+      ...listingBase,
+      title: data.search_text
+        ? `Search results for ${data.search_text}`
+        : 'Search Results'
+    },
+    plp: {
+      ...listingBase,
+      title: data.category?.name || 'Product Listing'
+    },
+    breadcrumbs: breadcrumbData || []
+  };
+};
+
+export const buildBasketPageContext = ({
+  basket,
+  path
+}: {
+  basket?: Basket | null;
+  path?: string;
+}) => {
+  const normalizedItems = (basket?.basketitem_set || []).map(item => {
+    const normalizedProduct = normalizeProductEntry(item.product);
+
+    return {
+      ...item,
+      title: normalizedProduct?.title || item.product?.name || '',
+      name: normalizedProduct?.name || item.product?.name || '',
+      url: normalizedProduct?.url || item.product?.absolute_url || '',
+      image:
+        item.image ||
+        (typeof normalizedProduct?.image === 'string'
+          ? normalizedProduct.image
+          : ''),
+      price: item.price || normalizedProduct?.price || '',
+      retailPrice: item.retail_price || normalizedProduct?.retailPrice || '',
+      totalAmount: item.total_amount || '',
+      unitPrice: item.unit_price || '',
+      currency: item.currency_type || normalizedProduct?.currency || '',
+      quantity: item.quantity,
+      attributes: normalizeAttributeEntries(
+        item.attributes_kwargs || item.product?.attributes_kwargs
+      ),
+      product: normalizedProduct
+    };
+  });
+
+  return {
+    page: {
+      type: 'basket',
+      title: 'Basket',
+      path: path || ROUTES.BASKET
+    },
+    basket: {
+      id: basket?.pk || null,
+      path: path || ROUTES.BASKET,
+      checkoutUrl: ROUTES.CHECKOUT,
+      continueShoppingUrl: ROUTES.HOME,
+      isEmpty: normalizedItems.length === 0,
+      itemCount: normalizedItems.length,
+      totalQuantity: basket?.total_quantity || 0,
+      totalAmount: basket?.total_amount || '',
+      totalProductAmount: basket?.total_product_amount || '',
+      totalDiscountAmount: basket?.total_discount_amount || '',
+      voucherCode: basket?.voucher_code || '',
+      discounts: basket?.discounts || [],
+      items: normalizedItems
+    }
+  };
+};
+
+export const buildAccountPageContext = ({
+  path,
+  profileInfo,
+  sessionUser
+}: {
+  path?: string;
+  profileInfo?: UnknownRecord | null;
+  sessionUser?: UnknownRecord | null;
+}) => {
+  const normalizedPath = path || ROUTES.ACCOUNT;
+  const firstName =
+    toStringValue(profileInfo?.first_name) ||
+    toStringValue(sessionUser?.firstName) ||
+    toStringValue(sessionUser?.name).split(' ')[0] ||
+    '';
+  const lastName =
+    toStringValue(profileInfo?.last_name) ||
+    toStringValue(sessionUser?.lastName) ||
+    toStringValue(sessionUser?.name).split(' ').slice(1).join(' ') ||
+    '';
+  const email =
+    toStringValue(profileInfo?.email) || toStringValue(sessionUser?.email);
+  const fullName =
+    [firstName, lastName].filter(Boolean).join(' ') ||
+    toStringValue(sessionUser?.name);
+
+  return {
+    page: {
+      type: 'account',
+      title: 'Account',
+      path: normalizedPath
+    },
+    account: {
+      path: normalizedPath,
+      route: normalizedPath,
+      user: {
+        firstName,
+        lastName,
+        fullName,
+        email,
+        phone: toStringValue(profileInfo?.phone),
+        gender: toStringValue(profileInfo?.gender)
+      }
+    }
+  };
+};

package/src/chrome/placeholder-slugs.ts

@@ -0,0 +1,86 @@
+/**
+ * The canonical placeholder slug table.
+ *
+ * Three repos had drifted apart on these names — the template app mounted
+ * `product-page-new`, a brand mounted `product-page-body`, and the editor's
+ * route map knew `list-page-body-new` — so a designer could publish a
+ * composition the storefront never looked for. Slugs are published content
+ * keys: once a brand saves against one, renaming it orphans that content.
+ * Everything that mounts or resolves a placeholder imports from here.
+ */
+export const PLACEHOLDER_SLUGS = {
+  // Chrome
+  header: 'header',
+  footer: 'footer',
+
+  // Page bodies — these names are already live in published themes, so the
+  // legacy "-new" suffixes stay until a migration moves the saved widgets.
+  homepage: 'theme-homepage-body',
+  productDetail: 'product-page-new',
+  productListing: 'list-page-body-new',
+  basket: 'basket-page-body',
+  auth: 'auth-page-body',
+
+  // Account: the layout-level slug renders on every account screen, so each
+  // subpage also gets its own body slug — otherwise one composition leaks
+  // across orders, addresses, profile and the rest.
+  accountShell: 'account-page-body',
+  accountMenu: 'account-menu',
+  accountOrders: 'account-orders-body',
+  accountOrderDetail: 'account-order-detail-body',
+  accountAddresses: 'account-address-body',
+  accountProfile: 'account-profile-body',
+  accountChangePassword: 'account-change-password-body',
+  accountChangeEmail: 'account-change-email-body',
+  accountCoupons: 'account-coupons-body',
+  accountFavourites: 'account-favourites-body',
+  accountFaq: 'account-faq-content',
+  accountNotifications: 'account-notifications-body',
+  accountStockAlerts: 'account-stock-alerts-body',
+
+  // Order flow. Checkout itself stays code-owned — payment, 3DS and the step
+  // machine are not composable — so the editor only gets the zones above and
+  // below the flow, never the flow.
+  checkoutTop: 'checkout-top-body',
+  checkoutBottom: 'checkout-bottom-body',
+  checkoutSummary: 'checkout-summary-body',
+  orderSuccess: 'order-success-body',
+  orderTracking: 'order-tracking-body',
+
+  // Auth
+  register: 'register-page-body',
+  forgotPassword: 'forgot-password-body',
+  guestLogin: 'guest-login-body',
+
+  // Content
+  stores: 'stores-page-body',
+  faq: 'faq-page-body',
+  sitemap: 'sitemap-page-body',
+  brands: 'brands-page-body',
+  flatPage: 'flat-page-body',
+  notFound: 'not-found-body'
+} as const;
+
+export type PlaceholderSlug =
+  (typeof PLACEHOLDER_SLUGS)[keyof typeof PLACEHOLDER_SLUGS];
+
+/** Custom pages created from the editor resolve to `page-<slug>` */
+export const customPageSlug = (slug: string) => `page-${slug}`;
+
+/**
+ * Slug for a brand page that has no canonical placeholder — every bespoke
+ * content route (about us, campaigns, returns policy…) gets one derived from
+ * its path, so a brand makes them all composable with a single slot in its
+ * root layout instead of one edit per page.
+ */
+export const customPageSlugFromPath = (pathname: string) => {
+  const cleaned = (pathname || '/')
+    .split('?')[0]
+    .split('#')[0]
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/[^a-zA-Z0-9/-]/g, '')
+    .replace(/\/+/g, '-')
+    .toLowerCase();
+
+  return cleaned ? customPageSlug(cleaned) : customPageSlug('home');
+};