@akinon/pz-theme 2.0.154-beta.0 → 2.0.154-rc.6

package/CHANGELOG.md

@@ -1,12 +1,51 @@
 # @akinon/pz-theme
 
-## 2.0.154-beta.0
-
-### Patch Changes
-
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.154-beta.0
-  - @akinon/theme-contract@2.0.154-beta.0
+## 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
+
+- ad5240c4: ZERO-5254: add custom render and theme editor support to pz-rate-review
+- Updated dependencies [219164a3]
+- Updated dependencies [86187b1c2]
+- Updated dependencies [0cf9ea239]
+- Updated dependencies [97d29893]
+- Updated dependencies [324f97d55]
+- Updated dependencies [51ea06888]
+- Updated dependencies
+- Updated dependencies [2fea41430]
+- Updated dependencies [b55acb768]
+- Updated dependencies [760258c1c]
+- Updated dependencies [143be2b9d]
+- Updated dependencies [7889b08fe]
+- Updated dependencies [9f8cd3bc5]
+- Updated dependencies [bfafa3f49]
+- Updated dependencies [57d7eb305]
+- Updated dependencies [d99a6a7d5]
+- Updated dependencies [9db81a714]
+- Updated dependencies [591e345e1]
+- Updated dependencies [4de5303c5]
+- Updated dependencies [95b139dc1]
+- Updated dependencies [1d00f2d06]
+- Updated dependencies [4ac7b2a1e]
+- Updated dependencies [4998a9631]
+- Updated dependencies [804d2bd6c]
+- Updated dependencies [3909d3224]
+- Updated dependencies [6a3d8a631]
+- Updated dependencies [e18836b20]
+- Updated dependencies [b1111d7b1]
+- Updated dependencies [1595d458e]
+- Updated dependencies [dca128112]
+- Updated dependencies [9c778307]
+  - @akinon/next@2.0.154-rc.5
+  - @akinon/theme-contract@2.0.154-rc.5
 
 ## 2.0.153
 

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-beta.0",
+  "version": "2.0.154-rc.6",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.154-beta.0",
+    "@akinon/next": "2.0.154-rc.6",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.154-beta.0",
+    "@akinon/theme-contract": "2.0.154-rc.6",
     "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-beta.0",
+    "@akinon/next": "2.0.154-rc.6",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/row-scope.test.tsx

@@ -0,0 +1,118 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { ItemTemplateList } from '../blocks/item-template';
+import { useThemeProduct } from '../blocks/product-block-utils';
+import { useThemeRowScope } from '../blocks/row-scope';
+import blockRendererRegistry from '../blocks/block-renderer-registry';
+import { resetCustomCatalog } from '../custom/catalog';
+import { resetCustomCollection } from '../custom/collect';
+import { isCustomThemeType, registerCustomBlocks } from '../custom';
+import type { Block } from '../theme-block';
+
+const READER = 'custom:acme:row-reader';
+
+function RowReader() {
+  const scope = useThemeRowScope();
+  const product = useThemeProduct();
+
+  return (
+    <span
+      data-testid="reader"
+      data-list={scope?.listType ?? ''}
+      data-index={scope?.index ?? ''}
+      data-number={String(scope?.row.number ?? '')}
+      data-product={String(product?.pk ?? '')}
+    />
+  );
+}
+
+const template = (): Block =>
+  ({
+    id: 'tpl',
+    type: 'group',
+    label: 'Row',
+    order: 0,
+    hidden: false,
+    value: '',
+    properties: { role: { desktop: 'item-template' } },
+    styles: {},
+    blocks: [
+      {
+        id: 'tpl-reader',
+        type: READER,
+        label: 'Reader',
+        order: 0,
+        hidden: false,
+        value: '',
+        properties: {},
+        styles: {},
+        blocks: []
+      }
+    ]
+  } as Block);
+
+const list = (type: string): Block =>
+  ({
+    id: 'list',
+    type,
+    label: 'List',
+    order: 0,
+    hidden: false,
+    value: '',
+    properties: {},
+    styles: {},
+    blocks: [template()]
+  } as Block);
+
+const renderRows = (type: string, items: Record<string, unknown>[]) =>
+  render(
+    <ItemTemplateList
+      block={list(type)}
+      items={items}
+      placeholderId="p1"
+      sectionId="s1"
+    />
+  );
+
+beforeAll(() => {
+  registerCustomBlocks('acme', { 'row-reader': RowReader });
+});
+
+afterAll(() => {
+  const map = (
+    blockRendererRegistry as unknown as { renderers: Map<string, unknown> }
+  ).renderers;
+  Array.from(map.keys())
+    .filter(isCustomThemeType)
+    .forEach((key) => map.delete(key));
+  resetCustomCatalog();
+  resetCustomCollection();
+});
+
+describe('the row scope', () => {
+  it('hands every repeated row to the blocks inside it, on any list', () => {
+    renderRows('order-list', [{ number: 'ORD-1' }, { number: 'ORD-2' }]);
+
+    const readers = screen.getAllByTestId('reader');
+    expect(readers).toHaveLength(2);
+    expect(readers[0]).toHaveAttribute('data-list', 'order-list');
+    expect(readers[0]).toHaveAttribute('data-index', '0');
+    expect(readers[0]).toHaveAttribute('data-number', 'ORD-1');
+    expect(readers[1]).toHaveAttribute('data-number', 'ORD-2');
+    expect(readers[0]).toHaveAttribute('data-product', '');
+  });
+
+  it('keeps the product scope on product lists next to the row scope', () => {
+    renderRows('product-grid', [{ pk: 7, name: 'Sneaker' }]);
+
+    const reader = screen.getByTestId('reader');
+    expect(reader).toHaveAttribute('data-list', 'product-grid');
+    expect(reader).toHaveAttribute('data-product', '7');
+  });
+
+  it('is closed outside a repeated row', () => {
+    render(<RowReader />);
+
+    expect(screen.getByTestId('reader')).toHaveAttribute('data-list', '');
+  });
+});

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/__tests__/order-list-rows.test.tsx

@@ -0,0 +1,112 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import OrderListBlock from '../order-list-block';
+
+const captured: { items: Record<string, unknown>[] } = { items: [] };
+
+jest.mock('../item-template', () => ({
+  __esModule: true,
+  hasItemTemplate: () => true,
+  ItemTemplateList: ({ items }: { items: Record<string, unknown>[] }) => {
+    captured.items = items;
+    return <div data-testid="item-template-list" />;
+  }
+}));
+
+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/redux/hooks', () => ({
+  __esModule: true,
+  useAppSelector: () => undefined,
+  useAppDispatch: () => jest.fn()
+}));
+
+jest.mock('@akinon/next/data/client/account', () => ({
+  __esModule: true,
+  useGetOrdersQuery: () => ({
+    data: {
+      count: 1,
+      results: [
+        {
+          id: 42,
+          number: 'ORD-42',
+          amount: '100.00',
+          created_date: '2026-09-01T10:00:00Z',
+          status: { value: '550', label: 'Delivered' },
+          orderitem_set: [
+            {
+              id: 7,
+              status: { value: 550, label: 'Delivered' },
+              product: {
+                sku: 'SKU-1',
+                base_code: 'BASE-1',
+                name: 'Sneaker',
+                image: '/s.jpg'
+              }
+            },
+            {
+              status: { value: '400', label: 'Approved' },
+              product: { name: 'Boot' }
+            }
+          ]
+        }
+      ]
+    },
+    isLoading: false
+  })
+}));
+
+describe('order list rows', () => {
+  it('publishes the order items with their product codes and status code', () => {
+    render(
+      <OrderListBlock
+        block={{
+          id: 'order-list-1',
+          type: 'order-list',
+          properties: {},
+          styles: {},
+          blocks: []
+        }}
+        placeholderId="p1"
+        sectionId="s1"
+      />
+    );
+
+    expect(captured.items).toHaveLength(1);
+    expect(captured.items[0]).toMatchObject({
+      id: 42,
+      number: 'ORD-42',
+      createdDate: '2026-09-01T10:00:00Z'
+    });
+    expect(captured.items[0].items).toEqual([
+      {
+        id: 7,
+        name: 'Sneaker',
+        image: '/s.jpg',
+        status: 'Delivered',
+        statusValue: '550',
+        product: {
+          sku: 'SKU-1',
+          base_code: 'BASE-1',
+          name: 'Sneaker',
+          image: '/s.jpg'
+        }
+      },
+      {
+        id: 1,
+        name: 'Boot',
+        image: '',
+        status: 'Approved',
+        statusValue: '400',
+        product: { sku: '', base_code: '', name: 'Boot', image: '' }
+      }
+    ]);
+  });
+});

package/src/blocks/item-template.tsx

@@ -15,6 +15,7 @@ import {
   resolveItemProduct
 } from './item-template-utils';
 import { ThemeItemScopeProvider } from './product-block-utils';
+import { ThemeRowScopeProvider } from './row-scope';
 
 export {
   findItemTemplate,
@@ -120,20 +121,15 @@ export const ItemTemplateList = ({
   const scopesProducts = publishesProductItems(block.type);
   // The same slice the iterator applied, so clone N is handed the row it
   // was built from rather than row N.
-  const scopedRows = scopesProducts
-    ? sliceIteratorItems(block, rows).items
-    : rows;
+  const slicedRows = sliceIteratorItems(block, rows).items;
 
   return (
     <>
       {clones.map((clone, index) => {
         const key = clone.id || `${template.id}-item-${index}`;
+        const rowData = slicedRows[index] ?? {};
         const row = (
           <ThemeBlock
-            // Keyed here so the non-scoped branch is the element it always
-            // was: wrapping it in anything, even a fragment, would change the
-            // element type at this position and remount every existing row.
-            key={key}
             block={clone}
             placeholderId={placeholderId}
             sectionId={sectionId}
@@ -143,22 +139,32 @@ export const ItemTemplateList = ({
             currentBreakpoint={currentBreakpoint}
           />
         );
+        const scoped = scopesProducts
+          ? resolveItemProduct(block.type, rowData)
+          : null;
 
-        if (!scopesProducts) return row;
-
-        const scoped = resolveItemProduct(block.type, scopedRows[index]);
-
-        // Context only — the provider renders no element, so the markup a
-        // published row produces is unchanged.
+        // Context only — the providers render no element, so the markup a
+        // published row produces is unchanged. Every list opens the row
+        // scope; only product lists open the product scope on top of it.
         return (
-          <ThemeItemScopeProvider
+          <ThemeRowScopeProvider
             key={key}
-            product={
-              scoped ?? (isDesigner ? DESIGNER_SAMPLE_PRODUCT : null)
-            }
+            listType={block.type}
+            row={rowData}
+            index={index}
           >
-            {row}
-          </ThemeItemScopeProvider>
+            {scopesProducts ? (
+              <ThemeItemScopeProvider
+                product={
+                  scoped ?? (isDesigner ? DESIGNER_SAMPLE_PRODUCT : null)
+                }
+              >
+                {row}
+              </ThemeItemScopeProvider>
+            ) : (
+              row
+            )}
+          </ThemeRowScopeProvider>
         );
       })}
     </>

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;
@@ -34,7 +35,7 @@ interface OrderItemLike {
     absolute_url?: string;
     attributes?: Record<string, unknown>;
   } | null;
-}
+};
 
 interface AddressLike {
   first_name?: string;
@@ -272,7 +273,9 @@ 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,
@@ -288,7 +291,7 @@ const formatAddress = (address: AddressLike | null | undefined): string[] => {
  * 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,
+ * item-status, item-tracking, item-return-code, item-actions, price, shipment,
  * delivery, tracking, addresses, address, address-label, totals, total-row,
  * total-label, total-value, grand-total, payment-info, payment-info-label.
  */
@@ -758,6 +761,14 @@ const OrderDetailBlock = ({
               const returnCodeValue = showReturnCode
                 ? resolveReturnCode(item.active_cancellation_request)
                 : '';
+              const lineActions = renderOrderLineActions({
+                order,
+                line,
+                isDesigner
+              });
+              const showLineMeta =
+                showShipmentStatus &&
+                Boolean(item.status?.label || trackingValue || returnCodeValue);
 
               return (
                 <li
@@ -873,63 +884,68 @@ 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>
+                        )}
+                        {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/order-list-block.tsx

@@ -13,7 +13,14 @@ import { readToggle } from './product-block-utils';
 import { BlockRendererProps } from './block-renderer-registry';
 
 interface OrderItemLike {
-  product?: { image?: string; name?: string } | null;
+  id?: number;
+  status?: { value?: string | number; label?: string };
+  product?: {
+    image?: string;
+    name?: string;
+    sku?: string;
+    base_code?: string;
+  } | null;
 }
 
 interface OrderLike {
@@ -248,7 +255,23 @@ const OrderListBlock = ({
         maxImages
     ),
     url: hrefFor(order),
-    href: hrefFor(order)
+    href: hrefFor(order),
+    createdDate: order.created_date || '',
+    items: (Array.isArray(order.orderitem_set) ? order.orderitem_set : []).map(
+      (item, itemIndex) => ({
+        id: item?.id ?? itemIndex,
+        name: item?.product?.name || '',
+        image: item?.product?.image || '',
+        status: item?.status?.label || '',
+        statusValue: String(item?.status?.value ?? ''),
+        product: {
+          sku: item?.product?.sku || '',
+          base_code: item?.product?.base_code || '',
+          name: item?.product?.name || '',
+          image: item?.product?.image || ''
+        }
+      })
+    )
   }));
 
   // A designer who marked a child as the row layout gets that layout repeated

package/src/blocks/row-scope.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import React from 'react';
+
+export interface ThemeRowScopeValue {
+  listType: string;
+  row: Record<string, unknown>;
+  index: number;
+}
+
+const ThemeRowScopeContext = React.createContext<ThemeRowScopeValue | null>(
+  null
+);
+
+export const ThemeRowScopeProvider = ({
+  listType,
+  row,
+  index,
+  children
+}: ThemeRowScopeValue & { children: React.ReactNode }) => {
+  const value = React.useMemo(
+    () => ({ listType, row, index }),
+    [listType, row, index]
+  );
+
+  return (
+    <ThemeRowScopeContext.Provider value={value}>
+      {children}
+    </ThemeRowScopeContext.Provider>
+  );
+};
+
+/** Non-null while a repeated row of any list renders; null everywhere else. */
+export const useThemeRowScope = (): ThemeRowScopeValue | null =>
+  React.useContext(ThemeRowScopeContext);

package/src/chrome/__tests__/page-context-builders.test.ts

@@ -41,7 +41,7 @@ const orderPayload = {
   orderitem_set: [
     {
       price: '649.95',
-      status: { label: 'Shipped' },
+      status: { value: '500', label: 'Shipped' },
       product: {
         name: 'Spring Sneaker',
         image: '/i.jpg',
@@ -63,6 +63,19 @@ describe('buildOrderPageContext', () => {
     expect(context.order.currency).toBe('TRY');
     expect(context.order.items).toHaveLength(1);
     expect(context.order.items[0].title).toBe('Spring Sneaker');
+    expect(context.order.items[0].status).toBe('Shipped');
+    expect(context.order.items[0].statusValue).toBe('500');
+  });
+
+  it('stringifies a numeric order item status code', () => {
+    const context = buildOrderPageContext({
+      order: {
+        ...orderPayload,
+        orderitem_set: [{ status: { value: 550, label: 'Delivered' } }]
+      }
+    });
+
+    expect(context.order.items[0].statusValue).toBe('550');
   });
 
   it('does not publish the identity fields the raw payload carries', () => {

package/src/chrome/page-context.ts

@@ -59,6 +59,9 @@ const toRecord = (value: unknown): UnknownRecord =>
 const toStringValue = (value: unknown, fallback = ''): string =>
   typeof value === 'string' ? value : fallback;
 
+const toCodeValue = (value: unknown): string =>
+  typeof value === 'number' ? String(value) : toStringValue(value);
+
 const humanizeSlug = (value: string) =>
   value
     .split('-')
@@ -479,6 +482,7 @@ export const buildOrderPageContext = ({
       unitPrice: toStringValue(item.price),
       quantity: 1,
       status: toStringValue(toRecord(item.status).label),
+      statusValue: toCodeValue(toRecord(item.status).value),
       currency
     };
   });

package/src/custom/README.md

@@ -303,6 +303,26 @@ attached". The editor's **Use preview** toggle turns it off while the editor
 stays open, so the canvas behaves like the live site: whatever you held open
 closes and links navigate again.
 
+## Reading the row a block is placed in
+
+A block dropped into a list's row layout (the child a designer marked as the
+row template of an order list, a product grid, an address list, …) renders once
+per row. The product lists open the product scope `useThemeProduct()` reads;
+every list also opens a row scope that carries the row itself:
+
+```ts
+import { useThemeRowScope } from '@akinon/pz-theme/src/blocks/row-scope';
+
+const scope = useThemeRowScope();
+```
+
+Inside a row it returns `{ listType, row, index }`, for example
+`listType: 'order-list'` with the order's `number` and `items` on `row`; anywhere
+else it returns `null`. `row` is the same record the row's bindings resolve
+against, so whatever a text block can bind to (`item.number`), code can read.
+Import it from that deep path for the same reason as `useThemePageContext`: the
+package root is not importable from a client module.
+
 ## Reporting what happened
 
 A custom unit can report a moment — a strip was seen, a lookbook was opened, a