@akinon/pz-theme 2.0.154-rc.5 → 2.0.154-rc.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @akinon/pz-theme
 
+## 2.0.154-rc.7
+
+### Patch Changes
+
+- 51a88b89: ZERO-5183: Give the order cancellation screen its own placeholder (`account-order-cancellation-body`) so it can be composed in the theme editor. The `order-detail` block gains an "Easy return" link for orders that can be returned and, per returned line, the return method (scheduled pickup or standard), the carrier and the pickup date, each behind its own switch. Order rows now keep units of one product together only while they share a status and cancellation/return request, so returning one of two units no longer reads as both returned.
+  - @akinon/next@2.0.154-rc.7
+  - @akinon/theme-contract@2.0.154-rc.7
+
+## 2.0.154-rc.6
+
+### Patch Changes
+
+- 8e040731: ZERO-5235: let brands hang actions on order detail lines
+  - @akinon/next@2.0.154-rc.6
+  - @akinon/theme-contract@2.0.154-rc.6
+
 ## 2.0.154-rc.5
 
 ### Patch Changes

package/package.json

@@ -1,19 +1,19 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.154-rc.5",
+  "version": "2.0.154-rc.7",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.154-rc.5",
+    "@akinon/next": "2.0.154-rc.7",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.154-rc.5",
+    "@akinon/theme-contract": "2.0.154-rc.7",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "react-multi-carousel": "2.8.4",
@@ -21,7 +21,7 @@
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.154-rc.5",
+    "@akinon/next": "2.0.154-rc.7",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/account-slot-coverage.test.ts

@@ -27,6 +27,7 @@ const EXPECTED_MOUNTS: Record<string, string> = {
   accountDashboard: '(dashboard)/layout.tsx',
   accountOrders: 'orders/(list)/layout.tsx',
   accountOrderDetail: 'orders/[id]/(detail)/layout.tsx',
+  accountOrderCancellation: 'orders/[id]/cancellation/layout.tsx',
   accountAddresses: 'address/layout.tsx',
   accountProfile: 'profile/layout.tsx',
   accountChangePassword: 'change-password/layout.tsx',

package/src/__tests__/custom-css.test.ts

@@ -61,6 +61,18 @@ describe('scoped custom CSS', () => {
     expect(css).toContain(`${SCOPE} button`);
   });
 
+  it('leaves commas inside :has(), :is() and attribute values alone', () => {
+    // ZERO-5183: the second half of `:has(a, b)` used to come out as
+    // `:has(a, <scope> b)` — a selector that can never match.
+    const css = scopeCustomCss(
+      '& li:has([data-a], [data-b]) { display: flex; }\n& :is(p, span)[title="x, y"], em { color: red; }',
+      SCOPE
+    );
+
+    expect(css).toContain(`${SCOPE} li:has([data-a], [data-b]) {`);
+    expect(css).toContain(`${SCOPE} :is(p, span)[title="x, y"], ${SCOPE} em {`);
+  });
+
   it('scopes inside a media query and keeps the condition', () => {
     const css = scopeCustomCss(
       '@media (max-width: 768px) { & [data-part="option"] { flex: 1 1 100%; } }',

package/src/__tests__/route-slug.test.ts

@@ -80,6 +80,13 @@ describe('resolveBodySlug', () => {
       PLACEHOLDER_SLUGS.accountAddresses
     );
     expect(resolveBodySlug('/users/orders/5/cancellation')).toBe(
+      PLACEHOLDER_SLUGS.accountOrderCancellation
+    );
+    expect(resolveBodySlug('/account/orders/5/cancellation/')).toBe(
+      PLACEHOLDER_SLUGS.accountOrderCancellation
+    );
+    // Any other screen under an order stays on the detail body.
+    expect(resolveBodySlug('/account/orders/5/invoice')).toBe(
       PLACEHOLDER_SLUGS.accountOrderDetail
     );
   });

package/src/blocks/__tests__/group-order-items.test.ts

@@ -0,0 +1,87 @@
+import { groupOrderItems } from '../product-block-utils';
+
+/**
+ * ZERO-5183 — pz writes one order line per unit and the order blocks collapse
+ * the units of a product into one row. A row shows its first unit's status and
+ * return details, so units only share it while they are in the same state:
+ * returning 1 of 2 must not read as both returned.
+ */
+const product = { pk: 7, name: 'Gömlek', image: '/x.jpg', absolute_url: '#' };
+
+const unit = (id: number, extra: Record<string, unknown> = {}) => ({
+  id,
+  price: '100.00',
+  quantity: 1,
+  status: { value: '550', label: 'Teslim Edildi' },
+  active_cancellation_request: null,
+  product,
+  ...extra
+});
+
+describe('groupOrderItems', () => {
+  it('still collapses units of a product that share a state', () => {
+    const rows = groupOrderItems([unit(1), unit(2), unit(3)]);
+
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ key: '7', quantity: 3, total: 300 });
+  });
+
+  it('gives a returned unit its own row', () => {
+    const returned = unit(2, {
+      status: { value: '600', label: 'İade Edildi' },
+      active_cancellation_request: { easy_return: { code: 'R1' } }
+    });
+    const rows = groupOrderItems([unit(1), returned]);
+
+    expect(rows.map((row) => [row.key, row.quantity, row.item.id])).toEqual([
+      ['7', 1, 1],
+      ['7-2', 1, 2]
+    ]);
+  });
+
+  it('splits on a pending request even before the status moves', () => {
+    const requested = unit(2, {
+      active_cancellation_request: [{ id: 31, easy_return: { code: 'R1' } }]
+    });
+
+    expect(groupOrderItems([unit(1), requested])).toHaveLength(2);
+  });
+
+  it('keeps units returned under the same request together, and separate requests apart', () => {
+    const returned = (id: number, code: string) =>
+      unit(id, {
+        status: { value: '600', label: 'İade Edildi' },
+        active_cancellation_request: { easy_return: { code } }
+      });
+
+    expect(
+      groupOrderItems([returned(1, 'R1'), returned(2, 'R1')]).map(
+        (row) => row.quantity
+      )
+    ).toEqual([2]);
+    expect(
+      groupOrderItems([returned(1, 'R1'), returned(2, 'R2')]).map(
+        (row) => row.key
+      )
+    ).toEqual(['7', '7-2']);
+  });
+
+  it('merges a later unit back into the row of its state', () => {
+    const cancelled = unit(2, { status: { value: '100', label: 'İptal' } });
+    const rows = groupOrderItems([unit(1), cancelled, unit(3)]);
+
+    expect(rows.map((row) => [row.key, row.quantity])).toEqual([
+      ['7', 2],
+      ['7-2', 1]
+    ]);
+  });
+
+  it('never merges lines without a product pk', () => {
+    const rows = groupOrderItems([
+      { id: 1, price: '1', quantity: 1, product: { name: 'A' } },
+      { id: 2, price: '1', quantity: 1, product: { name: 'A' } }
+    ]);
+
+    expect(rows.map((row) => row.key)).toEqual(['1', '2']);
+  });
+});

package/src/blocks/__tests__/order-detail-return.test.tsx

@@ -0,0 +1,208 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import OrderDetailBlock from '../order-detail-block';
+
+/**
+ * ZERO-5183 — the order detail is where an easy return starts and where a
+ * returned line says how it goes back: a "Kolay iade" link on an order that
+ * can be returned, and per line the method (a booked pickup or a standard
+ * drop-off), the carrier and the pickup day, each behind its own switch.
+ */
+let order: Record<string, unknown> | null = null;
+
+jest.mock('next/navigation', () => ({
+  useParams: () => ({ id: '42' }),
+  useSearchParams: () => null
+}));
+
+jest.mock('next-auth/react', () => ({
+  useSession: () => ({ data: null, status: 'authenticated' })
+}));
+
+jest.mock('@akinon/next/hooks', () => ({
+  __esModule: true,
+  useLocalization: () => ({ locale: 'tr', currency: 'try' })
+}));
+
+jest.mock('@akinon/next/data/client/account', () => ({
+  __esModule: true,
+  useGetOrderQuery: () => ({ data: order, isLoading: false })
+}));
+
+const line = (id: number, request: unknown) => ({
+  id,
+  price: '5499.00',
+  quantity: 1,
+  status: { value: '600', label: 'İade Edildi' },
+  active_cancellation_request: request,
+  product: { pk: id, name: `Gömlek ${id}`, image: '/x.jpg', absolute_url: '#' }
+});
+
+const blockOf = (properties: Record<string, unknown>) => ({
+  id: 'order-detail-1',
+  type: 'order-detail',
+  properties,
+  styles: {},
+  blocks: []
+});
+
+const ALL_ON = {
+  showReturnLink: { desktop: true },
+  returnLinkLabel: { desktop: 'Kolay iade' },
+  showReturnMethod: { desktop: true },
+  returnMethodLabel: { desktop: 'İade yöntemi:' },
+  appointmentReturnLabel: { desktop: 'Randevulu' },
+  standardReturnLabel: { desktop: 'Standart' },
+  showReturnCarrier: { desktop: true },
+  returnCarrierLabel: { desktop: 'Kargo:' },
+  showPickupDate: { desktop: true },
+  pickupDateLabel: { desktop: 'Randevu tarihi:' }
+};
+
+const texts = (root: ParentNode, part: string) =>
+  Array.from(root.querySelectorAll(`[data-part="${part}"]`)).map((e) =>
+    (e.textContent || '').replace(/\s+/g, ' ').trim()
+  );
+
+beforeEach(() => {
+  order = {
+    id: 42,
+    number: 'G-42',
+    amount: '10998.00',
+    is_cancellable: false,
+    is_refundable: true,
+    status: { value: '550', label: 'Teslim edildi' },
+    orderitem_set: [
+      line(1, [
+        {
+          pickup_date: { date: '2026-04-11' },
+          easy_return: {
+            code: 'R-1',
+            shipping_company: { label: 'Hepsijet' }
+          }
+        }
+      ]),
+      line(2, {
+        easy_return: {
+          code: 'R-2',
+          shipping_company: { label: 'Yurtiçi Kargo' }
+        }
+      }),
+      { ...line(3, null), status: { value: '550', label: 'Teslim edildi' } }
+    ]
+  };
+});
+
+describe('order detail — easy returns', () => {
+  it('links a returnable order to the easy-return screen', () => {
+    const { container } = render(
+      <OrderDetailBlock
+        block={blockOf(ALL_ON) as never}
+        placeholderId="p1"
+        sectionId="s1"
+        isDesigner={false}
+      />
+    );
+    const link = container.querySelector('[data-part="return-link"]');
+
+    expect(link?.textContent).toContain('Kolay iade');
+    expect(link?.getAttribute('href')).toBe('/account/orders/42/cancellation');
+    // The cancel link stays for orders that can still be cancelled.
+    expect(container.querySelector('[data-part="cancel-link"]')).toBeNull();
+  });
+
+  it('says how each returned line goes back', () => {
+    const { container } = render(
+      <OrderDetailBlock
+        block={blockOf(ALL_ON) as never}
+        placeholderId="p1"
+        sectionId="s1"
+        isDesigner={false}
+      />
+    );
+
+    expect(texts(container, 'item-return-method')).toEqual([
+      'İade yöntemi: Randevulu',
+      'İade yöntemi: Standart'
+    ]);
+    expect(texts(container, 'item-return-carrier')).toEqual([
+      'Kargo: Hepsijet',
+      'Kargo: Yurtiçi Kargo'
+    ]);
+    expect(texts(container, 'item-pickup-date')).toEqual([
+      'Randevu tarihi: 11.04.2026'
+    ]);
+  });
+
+  it('keeps every new line behind its switch', () => {
+    const { container } = render(
+      <OrderDetailBlock
+        block={blockOf({}) as never}
+        placeholderId="p1"
+        sectionId="s1"
+        isDesigner={false}
+      />
+    );
+
+    expect(container.querySelector('[data-part="return-link"]')).toBeNull();
+    expect(texts(container, 'item-return-method')).toEqual([]);
+    expect(texts(container, 'item-return-carrier')).toEqual([]);
+    expect(texts(container, 'item-pickup-date')).toEqual([]);
+  });
+
+  it('offers no return link on an order that cannot be returned', () => {
+    order = { ...order, is_refundable: false };
+    const { container } = render(
+      <OrderDetailBlock
+        block={blockOf(ALL_ON) as never}
+        placeholderId="p1"
+        sectionId="s1"
+        isDesigner={false}
+      />
+    );
+
+    expect(container.querySelector('[data-part="return-link"]')).toBeNull();
+  });
+
+  it('links only a delivered line that has no request yet', () => {
+    // As commerce answers after a return: the order and its lines stay
+    // refundable while the request is open.
+    const flagged: Record<string, unknown>[] = (
+      order.orderitem_set as Record<string, unknown>[]
+    ).map((item) => ({ ...item, is_refundable: true }));
+    const returnLink = () =>
+      render(
+        <OrderDetailBlock
+          block={blockOf(ALL_ON) as never}
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+        />
+      ).container.querySelector('[data-part="return-link"]');
+
+    // Line 3 has no request yet: it can still be returned.
+    order = { ...order, orderitem_set: flagged };
+    expect(returnLink()).not.toBeNull();
+
+    order = {
+      ...order,
+      orderitem_set: flagged.map((item) =>
+        item.id === 3
+          ? { ...item, active_cancellation_request: { id: 54766 } }
+          : item
+      )
+    };
+    expect(returnLink()).toBeNull();
+
+    // Commerce calls a shipped line refundable too; it is not returned yet.
+    order = {
+      ...order,
+      orderitem_set: flagged.map((item) =>
+        item.id === 3
+          ? { ...item, status: { value: '500', label: 'Gönderildi' } }
+          : item
+      )
+    };
+    expect(returnLink()).toBeNull();
+  });
+});

package/src/blocks/__tests__/order-line-actions.test.tsx

@@ -0,0 +1,54 @@
+import React from 'react';
+import {
+  registerOrderLineActions,
+  renderOrderLineActions
+} from '../order-line-actions';
+
+const context = {
+  order: { id: 7, number: '20920397829', created_date: '2026-10-01' },
+  line: {
+    key: '1',
+    name: 'Product',
+    image: '',
+    href: '',
+    price: '100',
+    total: 100,
+    quantity: 1,
+    item: { id: 1, status: { value: '550', label: 'Delivered' } }
+  },
+  isDesigner: false
+};
+
+describe('order line actions registry', () => {
+  it('renders nothing until a brand registers', () => {
+    expect(renderOrderLineActions(context)).toBeNull();
+  });
+
+  it('hands the line and order to the registered renderer', () => {
+    const renderer = jest.fn(() => <span>action</span>);
+    const unregister = registerOrderLineActions(renderer);
+
+    expect(renderOrderLineActions(context)).toEqual(<span>action</span>);
+    expect(renderer).toHaveBeenCalledWith(context);
+
+    unregister();
+    expect(renderOrderLineActions(context)).toBeNull();
+  });
+
+  it('swallows a throwing renderer so a brand bug cannot break the line', () => {
+    const unregister = registerOrderLineActions(() => {
+      throw new Error('boom');
+    });
+
+    expect(renderOrderLineActions(context)).toBeNull();
+    unregister();
+  });
+
+  it('only forgets the renderer it was asked to forget', () => {
+    const first = registerOrderLineActions(() => 'first');
+    registerOrderLineActions(() => 'second');
+
+    first();
+    expect(renderOrderLineActions(context)).toBe('second');
+  });
+});

package/src/blocks/order-detail-block.tsx

@@ -9,6 +9,7 @@ import { getResponsiveValue, partAttrs } from '../utils';
 import { formatDate, formatMoney } from './commerce-format';
 import { readMoneyStyle } from './money-style';
 import { hasItemTemplate, ItemTemplateList } from './item-template';
+import { renderOrderLineActions } from './order-line-actions';
 import { BlockRendererProps } from './block-renderer-registry';
 import {
   DesignerPlaceholder,
@@ -16,7 +17,7 @@ import {
   readToggle
 } from './product-block-utils';
 
-interface OrderItemLike {
+type OrderItemLike = {
   id?: number;
   price?: string;
   quantity?: string | number;
@@ -26,6 +27,7 @@ interface OrderItemLike {
   tracking_number?: string;
   estimated_delivery_date?: string;
   price_currency?: { value?: string; label?: string };
+  is_refundable?: boolean;
   active_cancellation_request?: unknown;
   product?: {
     pk?: number;
@@ -34,7 +36,7 @@ interface OrderItemLike {
     absolute_url?: string;
     attributes?: Record<string, unknown>;
   } | null;
-}
+};
 
 interface AddressLike {
   first_name?: string;
@@ -65,6 +67,7 @@ interface OrderLike {
   orderitem_set?: OrderItemLike[];
   discountitem_set?: DiscountItemLike[];
   is_cancellable?: boolean;
+  is_refundable?: boolean;
   e_archive_url?: string | null;
   shipping_address?: AddressLike | null;
   billing_address?: AddressLike | null;
@@ -112,6 +115,37 @@ const firstString = (
   return '';
 };
 
+const hasOpenRequest = (request: unknown): boolean =>
+  Array.isArray(request) ? request.length > 0 : Boolean(request);
+
+/** Commerce's "Teslim edildi". */
+const DELIVERED = '550';
+
+/**
+ * Whether the order still has a line to return: delivered, refundable, with
+ * no request open on it. Commerce also marks a shipped line refundable, and
+ * keeps `is_refundable` true on the order and the line while a return request
+ * is open, so the order flag alone would offer a return before the parcel
+ * arrives and again after the shopper has asked. Lines that carry no flag at
+ * all (an older payload) leave the decision to the order's flag and status.
+ */
+const hasReturnableLine = (order: OrderLike): boolean => {
+  if (!order.is_refundable) return false;
+
+  const lines = order.orderitem_set ?? [];
+
+  if (!lines.some((item) => item && 'is_refundable' in item)) {
+    return String(order.status?.value ?? '') === DELIVERED;
+  }
+
+  return lines.some(
+    (item) =>
+      String(item?.status?.value ?? '') === DELIVERED &&
+      item?.is_refundable &&
+      !hasOpenRequest(item.active_cancellation_request)
+  );
+};
+
 /** Positive integers only; anything else falls back to the shipped size. */
 const readSize = (value: unknown, fallback: number): number => {
   const numeric = Math.round(Number(value));
@@ -145,6 +179,7 @@ const DESIGNER_SAMPLE_ORDER: OrderLike = {
   status: { value: '10', label: 'Approved' },
   currency: { value: 'try', label: 'TRY' },
   is_cancellable: true,
+  is_refundable: true,
   e_archive_url: '#',
   installment_count: 3,
   orderitem_set: [
@@ -158,7 +193,16 @@ const DESIGNER_SAMPLE_ORDER: OrderLike = {
       tracking_number: '1Z999AA10123456784',
       tracking_url: '#',
       active_cancellation_request: [
-        { easy_return: { code: '12345678912345' } }
+        {
+          easy_return: {
+            code: '12345678912345',
+            shipping_company: { value: 'carrier', label: 'Carrier' }
+          },
+          pickup_date: {
+            date: '2026-04-11',
+            hour_range: { start: '09:00:00', end: '18:00:00' }
+          }
+        }
       ],
       product: {
         pk: 1,
@@ -249,6 +293,63 @@ const resolveReturnCode = (value: unknown): string => {
   return typeof code === 'string' ? code : '';
 };
 
+interface ReturnRequestLike {
+  pickup_date?: { date?: string } | null;
+  easy_return?: {
+    code?: string;
+    shipping_company?: { label?: string } | null;
+  } | null;
+}
+
+/**
+ * How a returned line goes back: `appointment` when the request booked a
+ * pickup (it carries a pickup day), `standard` for an easy return dropped off
+ * at a branch, nothing for a plain cancellation. The carrier and the pickup
+ * day come from the same request; both shapes of the field are probed, as
+ * for the return code.
+ */
+const resolveReturnDetails = (
+  value: unknown
+): {
+  method: 'appointment' | 'standard' | null;
+  carrier: string;
+  pickupDate: string;
+} => {
+  const entry = (Array.isArray(value) ? value[0] : value) as
+    | ReturnRequestLike
+    | null
+    | undefined;
+  const pickupDate = entry?.pickup_date?.date;
+  const carrier = entry?.easy_return?.shipping_company?.label;
+
+  return {
+    method: pickupDate ? 'appointment' : entry?.easy_return ? 'standard' : null,
+    carrier: typeof carrier === 'string' ? carrier : '',
+    pickupDate: typeof pickupDate === 'string' ? pickupDate : ''
+  };
+};
+
+/** "2026-04-11" read as a calendar day in the page's locale (no time zone shift). */
+const formatPickupDate = (value: string, locale?: string): string => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+  if (!match) return value;
+
+  try {
+    return new Intl.DateTimeFormat(locale || undefined, {
+      timeZone: 'UTC',
+      day: '2-digit',
+      month: '2-digit',
+      year: 'numeric'
+    }).format(
+      new Date(
+        Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]), 12)
+      )
+    );
+  } catch {
+    return value;
+  }
+};
+
 const formatAddress = (address: AddressLike | null | undefined): string[] => {
   if (!address) return [];
   const name = [address.first_name, address.last_name]
@@ -272,14 +373,18 @@ const formatAddress = (address: AddressLike | null | undefined): string[] => {
  * order key is read from the URL; the editor owns which sections are exposed,
  * every caption and the styling.
  * A designer can mark one child as the row layout for the order lines; without
- * one the built-in line renders.
+ * one the built-in line renders. A brand may hang per-line actions on the
+ * built-in line through `registerOrderLineActions`; they render inside the
+ * line's `item-actions` part.
  * Properties: numberLabel, numberTag, dateLabel, headerTotalLabel,
  * showInvoiceLink, invoiceLinkLabel, showCancelLink, cancelLinkLabel,
- * cancelHrefBase, showShipmentStatus, showItems, showImage, imageWidth,
+ * showReturnLink, returnLinkLabel, cancelHrefBase, showShipmentStatus, showItems, showImage, imageWidth,
  * imageHeight, showQuantity, quantityLabel, showColor,
  * colorLabel, colorAttributeKey, showSize, sizeLabel, sizeAttributeKey,
  * showLineTracking, lineTrackingLabel, showReturnCode,
- * returnCodeLabel, showShippingAddress, shippingAddressLabel,
+ * returnCodeLabel, showReturnMethod, returnMethodLabel,
+ * appointmentReturnLabel, standardReturnLabel, showReturnCarrier,
+ * returnCarrierLabel, showPickupDate, pickupDateLabel, showShippingAddress, shippingAddressLabel,
  * showBillingAddress, billingAddressLabel, showTotals, showPieceCount,
  * pieceCountLabel, showDiscountItems, showInstallmentInfo,
  * installmentInfoLabel, subtotalLabel, discountLabel, shippingLabel,
@@ -287,9 +392,10 @@ const formatAddress = (address: AddressLike | null | undefined): string[] => {
  * showPaymentInfo, paymentInfoLabel, decimals, currencyDisplay,
  * currencyText, currencyPosition.
  * Parts: detail, header, number, date, header-total, status,
- * invoice-link, cancel-link, list, item, image, name, quantity, color, size,
- * item-status, item-tracking, item-return-code, price, shipment,
- * delivery, tracking, addresses, address, address-label, totals, total-row,
+ * invoice-link, cancel-link, return-link, list, item, image, name, quantity,
+ * color, size, item-status, item-tracking, item-return-code,
+ * item-return-method, item-return-carrier, item-pickup-date, item-actions,
+ * price, shipment, delivery, tracking, addresses, address, address-label, totals, total-row,
  * total-label, total-value, grand-total, payment-info, payment-info-label.
  */
 const OrderDetailBlock = ({
@@ -399,6 +505,38 @@ const OrderDetailBlock = ({
     false
   );
   const returnCodeLabel = text('returnCodeLabel', 'Return code:');
+  // ZERO-5183: the easy-return screens start from here, and a returned line
+  // says how it goes back. The cancel link only shows while the order can
+  // still be cancelled; a delivered order needs its own way in.
+  const showReturnLink = readToggle(
+    block.properties?.showReturnLink,
+    currentBreakpoint,
+    false
+  );
+  const returnLinkLabel = text('returnLinkLabel', 'Easy return');
+  const showReturnMethod = readToggle(
+    block.properties?.showReturnMethod,
+    currentBreakpoint,
+    false
+  );
+  const returnMethodLabel = text('returnMethodLabel', 'Return method:');
+  const appointmentReturnLabel = text(
+    'appointmentReturnLabel',
+    'Scheduled pickup'
+  );
+  const standardReturnLabel = text('standardReturnLabel', 'Standard');
+  const showReturnCarrier = readToggle(
+    block.properties?.showReturnCarrier,
+    currentBreakpoint,
+    false
+  );
+  const returnCarrierLabel = text('returnCarrierLabel', 'Carrier:');
+  const showPickupDate = readToggle(
+    block.properties?.showPickupDate,
+    currentBreakpoint,
+    false
+  );
+  const pickupDateLabel = text('pickupDateLabel', 'Pickup date:');
 
   const showShippingAddress = readToggle(
     block.properties?.showShippingAddress,
@@ -486,6 +624,12 @@ const OrderDetailBlock = ({
   const money = (value: unknown) =>
     formatMoney(value, { locale, currency, ...moneyStyle });
 
+  // The sample order is not a delivered one; it shows the link for styling.
+  const offersReturn =
+    order === DESIGNER_SAMPLE_ORDER
+      ? Boolean(order.is_refundable)
+      : hasReturnableLine(order);
+
   // Navigating inside the designer iframe would drop the author out of the page
   // they are editing, so every link is inert there.
   const guard = (event: React.MouseEvent) => {
@@ -664,7 +808,7 @@ const OrderDetailBlock = ({
                 {headerTotalLabel} {money(order.amount)}
               </span>
             )}
-            {(showInvoiceLink || showCancelLink) && (
+            {(showInvoiceLink || showCancelLink || showReturnLink) && (
               <div
                 style={{
                   display: 'flex',
@@ -704,6 +848,21 @@ const OrderDetailBlock = ({
                     → {cancelLinkLabel}
                   </NextLink>
                 )}
+                {showReturnLink && offersReturn && cancelHref && (
+                  <NextLink
+                    href={isDesigner ? '#' : cancelHref}
+                    onClick={guard}
+                    data-order-detail-return-link=""
+                    {...partAttrs('return-link')}
+                    style={{
+                      color: 'inherit',
+                      textDecoration: 'none',
+                      whiteSpace: 'nowrap'
+                    }}
+                  >
+                    → {returnLinkLabel}
+                  </NextLink>
+                )}
               </div>
             )}
           </div>
@@ -758,6 +917,37 @@ const OrderDetailBlock = ({
               const returnCodeValue = showReturnCode
                 ? resolveReturnCode(item.active_cancellation_request)
                 : '';
+              const returnDetails = resolveReturnDetails(
+                item.active_cancellation_request
+              );
+              const returnMethodValue =
+                showReturnMethod && returnDetails.method
+                  ? returnDetails.method === 'appointment'
+                    ? appointmentReturnLabel
+                    : standardReturnLabel
+                  : '';
+              const returnCarrierValue = showReturnCarrier
+                ? returnDetails.carrier
+                : '';
+              const pickupDateValue =
+                showPickupDate && returnDetails.pickupDate
+                  ? formatPickupDate(returnDetails.pickupDate, locale)
+                  : '';
+              const lineActions = renderOrderLineActions({
+                order,
+                line,
+                isDesigner
+              });
+              const showLineMeta =
+                showShipmentStatus &&
+                Boolean(
+                  item.status?.label ||
+                    trackingValue ||
+                    returnCodeValue ||
+                    returnMethodValue ||
+                    returnCarrierValue ||
+                    pickupDateValue
+                );
 
               return (
                 <li
@@ -873,63 +1063,100 @@ const OrderDetailBlock = ({
                       </div>
                     </div>
 
-                    {showShipmentStatus &&
-                      (item.status?.label ||
-                        trackingValue ||
-                        returnCodeValue) && (
-                        <div
-                          style={{
-                            display: 'flex',
-                            flexDirection: 'column',
-                            alignItems: isMobile ? 'flex-start' : 'flex-end',
-                            textAlign: isMobile ? 'left' : 'right',
-                            gap: '4px',
-                            flex: isMobile ? '1 1 100%' : '0 0 auto'
-                          }}
-                        >
-                          {item.status?.label && (
-                            <span
-                              data-order-detail-item-status=""
-                              data-order-status-value={item.status.value}
-                              {...partAttrs('item-status')}
-                              style={{ display: 'inline-block' }}
-                            >
-                              {item.status.label}
-                            </span>
-                          )}
-                          {trackingValue && (
-                            <span
-                              data-order-detail-item-tracking=""
-                              {...partAttrs('item-tracking')}
-                              style={{ opacity: 0.8 }}
-                            >
-                              {lineTrackingLabel}{' '}
-                              {item.tracking_url ? (
-                                <a
-                                  href={isDesigner ? '#' : item.tracking_url}
-                                  onClick={guard}
-                                  target={isDesigner ? undefined : '_blank'}
-                                  rel="noreferrer"
-                                  style={{ color: 'inherit' }}
-                                >
-                                  {item.tracking_number || item.tracking_url}
-                                </a>
-                              ) : (
-                                trackingValue
-                              )}
-                            </span>
-                          )}
-                          {returnCodeValue && (
-                            <span
-                              data-order-detail-item-return-code=""
-                              {...partAttrs('item-return-code')}
-                              style={{ opacity: 0.8 }}
-                            >
-                              {returnCodeLabel} {returnCodeValue}
-                            </span>
-                          )}
-                        </div>
-                      )}
+                    {(showLineMeta || lineActions) && (
+                      <div
+                        style={{
+                          display: 'flex',
+                          flexDirection: 'column',
+                          alignItems: isMobile ? 'flex-start' : 'flex-end',
+                          textAlign: isMobile ? 'left' : 'right',
+                          gap: '4px',
+                          flex: isMobile ? '1 1 100%' : '0 0 auto'
+                        }}
+                      >
+                        {lineActions && (
+                          <div
+                            data-order-detail-item-actions=""
+                            {...partAttrs('item-actions')}
+                          >
+                            {lineActions}
+                          </div>
+                        )}
+                        {showLineMeta && item.status?.label && (
+                          <span
+                            data-order-detail-item-status=""
+                            data-order-status-value={item.status.value}
+                            {...partAttrs('item-status')}
+                            style={{ display: 'inline-block' }}
+                          >
+                            {item.status.label}
+                          </span>
+                        )}
+                        {/* Label and value in their own spans, so a
+                            composition can colour them apart. */}
+                        {showLineMeta && returnMethodValue && (
+                          <span
+                            data-order-detail-item-return-method=""
+                            {...partAttrs('item-return-method')}
+                            style={{ opacity: 0.8 }}
+                          >
+                            <span data-label="">{returnMethodLabel}</span>{' '}
+                            <span data-value="">{returnMethodValue}</span>
+                          </span>
+                        )}
+                        {showLineMeta && returnCarrierValue && (
+                          <span
+                            data-order-detail-item-return-carrier=""
+                            {...partAttrs('item-return-carrier')}
+                            style={{ opacity: 0.8 }}
+                          >
+                            <span data-label="">{returnCarrierLabel}</span>{' '}
+                            <span data-value="">{returnCarrierValue}</span>
+                          </span>
+                        )}
+                        {showLineMeta && pickupDateValue && (
+                          <span
+                            data-order-detail-item-pickup-date=""
+                            {...partAttrs('item-pickup-date')}
+                            style={{ opacity: 0.8 }}
+                          >
+                            <span data-label="">{pickupDateLabel}</span>{' '}
+                            <span data-value="">{pickupDateValue}</span>
+                          </span>
+                        )}
+                        {showLineMeta && trackingValue && (
+                          <span
+                            data-order-detail-item-tracking=""
+                            {...partAttrs('item-tracking')}
+                            style={{ opacity: 0.8 }}
+                          >
+                            {lineTrackingLabel}{' '}
+                            {item.tracking_url ? (
+                              <a
+                                href={isDesigner ? '#' : item.tracking_url}
+                                onClick={guard}
+                                target={isDesigner ? undefined : '_blank'}
+                                rel="noreferrer"
+                                style={{ color: 'inherit' }}
+                              >
+                                {item.tracking_number || item.tracking_url}
+                              </a>
+                            ) : (
+                              trackingValue
+                            )}
+                          </span>
+                        )}
+                        {showLineMeta && returnCodeValue && (
+                          <span
+                            data-order-detail-item-return-code=""
+                            {...partAttrs('item-return-code')}
+                            style={{ opacity: 0.8 }}
+                          >
+                            {returnCodeLabel} {returnCodeValue}
+                          </span>
+                        )}
+                      </div>
+                    )}
                   </div>
                 </li>
               );

package/src/blocks/order-line-actions.ts

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+import type { GroupedOrderLine, OrderLineLike } from './product-block-utils';
+
+export interface OrderLineActionsOrder {
+  id?: number;
+  number?: string;
+  created_date?: string;
+}
+
+export type OrderLineActionsItem = OrderLineLike & {
+  status?: { value?: string; label?: string };
+  [key: string]: unknown;
+};
+
+export interface OrderLineActionsContext {
+  order: OrderLineActionsOrder;
+  line: GroupedOrderLine<OrderLineActionsItem>;
+  isDesigner: boolean;
+}
+
+export type OrderLineActionsRenderer = (
+  context: OrderLineActionsContext
+) => ReactNode;
+
+let renderer: OrderLineActionsRenderer | null = null;
+
+export const registerOrderLineActions = (
+  fn: OrderLineActionsRenderer
+): (() => void) => {
+  renderer = fn;
+  return () => {
+    if (renderer === fn) renderer = null;
+  };
+};
+
+export const renderOrderLineActions = (
+  context: OrderLineActionsContext
+): ReactNode => {
+  if (!renderer) return null;
+  try {
+    return renderer(context) ?? null;
+  } catch {
+    return null;
+  }
+};

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

@@ -240,6 +240,8 @@ export interface OrderLineLike {
   price?: string | number;
   quantity?: string | number;
   total_amount?: string | number;
+  status?: { value?: string | number; label?: string } | null;
+  active_cancellation_request?: unknown;
   product?: {
     pk?: number;
     name?: string;
@@ -278,7 +280,10 @@ export const getLineImage = (
 };
 
 export interface GroupedOrderLine<T extends OrderLineLike> {
-  /** Stable React key: the product pk when the payload carries one. */
+  /**
+   * Stable React key: the product pk when the payload carries one (with a
+   * `-2`, `-3`… suffix for the product's further rows, see groupOrderItems).
+   */
   key: string;
   name: string;
   image: string;
@@ -301,21 +306,28 @@ export interface GroupedOrderLine<T extends OrderLineLike> {
  * `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.
+ *
+ * Units of one product only share a row while nothing sets them apart: once
+ * one of them is cancelled or returned (its status moves on, or it carries a
+ * cancellation / return request) it gets a row of its own. A shared row shows
+ * its first unit's status and return details, so "return 1 of 2" would
+ * otherwise read as both units returned.
  */
 export const groupOrderItems = <T extends OrderLineLike>(
   items: T[] | null | undefined
 ): GroupedOrderLine<T>[] => {
   const source = Array.isArray(items) ? items : [];
+  const groups: GroupedOrderLine<T>[] = [];
+  const byIdentity = new Map<string, GroupedOrderLine<T>>();
+  const rowsPerKey = new Map<string, number>();
 
-  return source.reduce<GroupedOrderLine<T>[]>((accumulator, item) => {
+  source.forEach((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 identity =
+      pk === undefined || pk === null ? null : `${pk}#${lineState(item)}`;
+    const existing = identity === null ? undefined : byIdentity.get(identity);
     const quantity = parseAmount(item.quantity) ?? 1;
     const lineTotal = parseAmount(item.total_amount || item.price);
 
@@ -324,11 +336,15 @@ export const groupOrderItems = <T extends OrderLineLike>(
       existing.total =
         lineTotal === null ? existing.total : (existing.total ?? 0) + lineTotal;
 
-      return accumulator;
+      return;
     }
 
-    accumulator.push({
-      key,
+    const baseKey = String(pk ?? item.id ?? groups.length);
+    const rows = (rowsPerKey.get(baseKey) ?? 0) + 1;
+    rowsPerKey.set(baseKey, rows);
+
+    const group: GroupedOrderLine<T> = {
+      key: rows === 1 ? baseKey : `${baseKey}-${rows}`,
       name: item.product?.name || '',
       image: getLineImage(item),
       href: item.product?.absolute_url || '',
@@ -336,10 +352,30 @@ export const groupOrderItems = <T extends OrderLineLike>(
       total: lineTotal,
       quantity,
       item
-    });
+    };
+    groups.push(group);
+    if (identity !== null) byIdentity.set(identity, group);
+  });
+
+  return groups;
+};
+
+/**
+ * What tells one unit of a product apart from another in the same order: its
+ * status and the cancellation / return request it carries (one object or a
+ * one-item array, depending on the pz version).
+ */
+const lineState = (item: OrderLineLike): string => {
+  const value = item.active_cancellation_request;
+  const request = (Array.isArray(value) ? value[0] : value) as
+    | { id?: unknown; easy_return?: { code?: unknown } | null }
+    | null
+    | undefined;
+  const requestKey = request
+    ? String(request.id ?? request.easy_return?.code ?? 'request')
+    : '';
 
-    return accumulator;
-  }, []);
+  return `${item.status?.value ?? ''}|${requestKey}`;
 };
 
 /**

package/src/chrome/placeholder-slugs.ts

@@ -29,6 +29,10 @@ export const PLACEHOLDER_SLUGS = {
   accountDashboard: 'account-dashboard-body',
   accountOrders: 'account-orders-body',
   accountOrderDetail: 'account-order-detail-body',
+  // The easy-return / cancellation screen under one order. It used to resolve
+  // to the detail slug and stay code-owned; its own slug lets a brand compose
+  // it without the detail composition swallowing it.
+  accountOrderCancellation: 'account-order-cancellation-body',
   accountAddresses: 'account-address-body',
   accountProfile: 'account-profile-body',
   accountChangePassword: 'account-change-password-body',

package/src/chrome/route-slug.ts

@@ -19,9 +19,12 @@ export type RouteSlugRule = [RegExp, string];
  * resolves to the order detail body and not to the order list.
  */
 const DEFAULT_RULES: RouteSlugRule[] = [
-  // Account — deepest first. The detail rule also matches deeper order
-  // screens (e.g. cancellation); the reference app only mounts the slot on
-  // the detail screen itself, so those stay code-owned.
+  // Account — deepest first. The cancellation screen under an order has its
+  // own body; the detail rule still matches any other deeper order screen.
+  [
+    /^\/(account|users)\/orders\/[^/]+\/cancellation(\/|$)/,
+    PLACEHOLDER_SLUGS.accountOrderCancellation
+  ],
   [
     /^\/(account|users)\/orders\/[^/]+/,
     PLACEHOLDER_SLUGS.accountOrderDetail
@@ -130,6 +133,7 @@ const PAGE_MOUNTED_SLUGS = new Set<string>([
   PLACEHOLDER_SLUGS.accountDashboard,
   PLACEHOLDER_SLUGS.accountOrders,
   PLACEHOLDER_SLUGS.accountOrderDetail,
+  PLACEHOLDER_SLUGS.accountOrderCancellation,
   PLACEHOLDER_SLUGS.accountAddresses,
   PLACEHOLDER_SLUGS.accountProfile,
   PLACEHOLDER_SLUGS.accountChangePassword,

package/src/utils/custom-css.ts

@@ -77,9 +77,42 @@ const splitTopLevelRules = (css: string): string[] => {
   return rules.map(rule => rule.trim()).filter(Boolean);
 };
 
+/**
+ * Splits a selector list on its top-level commas only. A comma inside
+ * `:has()`, `:is()`, `:not()`, `:where()`, an attribute selector or a string
+ * belongs to that one selector — splitting there scoped the second half of
+ * `:has(a, b)` as if it were a selector of its own, so it never matched.
+ */
+const splitSelectorList = (selectors: string): string[] => {
+  const parts: string[] = [];
+  let depth = 0;
+  let quote: string | null = null;
+  let start = 0;
+
+  for (let i = 0; i < selectors.length; i++) {
+    const char = selectors[i];
+
+    if (quote) {
+      if (char === '\\') i += 1;
+      else if (char === quote) quote = null;
+      continue;
+    }
+
+    if (char === '"' || char === "'") quote = char;
+    else if (char === '(' || char === '[') depth += 1;
+    else if (char === ')' || char === ']') depth = Math.max(0, depth - 1);
+    else if (char === ',' && depth === 0) {
+      parts.push(selectors.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(selectors.slice(start));
+
+  return parts;
+};
+
 const scopeSelectorList = (selectors: string, scope: string): string =>
-  selectors
-    .split(',')
+  splitSelectorList(selectors)
     .map(selector => selector.trim())
     .filter(Boolean)
     .map(selector =>