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

package/CHANGELOG.md

@@ -1,12 +1,12 @@
 # @akinon/pz-theme
 
-## 2.0.167-beta.0
+## 2.0.167
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd757]
-  - @akinon/next@2.0.167-beta.0
-  - @akinon/theme-contract@2.0.167-beta.0
+- e0fc41c3: ZERO-5511: Native empty state for the order-list block. A child group marked with role `order-list-empty` is drawn in place of the whole block (title included) once a signed-in shopper turns out to have no orders, so the heading, the explanation, the call-to-action links and product suggestions are authored in the panel instead of being switched on with custom CSS. `previewEmptyState` draws it on the canvas (editor only). The empty message (`emptyLabel`) and the `data-order-list-state="empty"` wrapper stay as they were, and the storefront now shows them for an empty list even when a row layout is set.
+  - @akinon/next@2.0.167
+  - @akinon/theme-contract@2.0.167
 
 ## 2.0.166
 

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

package/src/blocks/__tests__/order-list-empty-state.test.tsx

@@ -0,0 +1,195 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import OrderListBlock from '../order-list-block';
+
+const state: {
+  status: string;
+  query: { data?: unknown; isLoading: boolean };
+  hasTemplate: boolean;
+} = {
+  status: 'authenticated',
+  query: { data: { count: 0, results: [] }, isLoading: false },
+  hasTemplate: false
+};
+
+jest.mock('../item-template', () => ({
+  __esModule: true,
+  hasItemTemplate: () => state.hasTemplate,
+  // Like the real list on the storefront: nothing to repeat, nothing drawn.
+  ItemTemplateList: ({ items }: { items: unknown[] }) =>
+    items.length > 0 ? <li data-testid="template-row" /> : null
+}));
+
+jest.mock('../../theme-block', () => ({
+  __esModule: true,
+  default: ({ block }: { block: { id: string } }) => (
+    <div data-testid="theme-block" data-block-id={block.id} />
+  )
+}));
+
+jest.mock('next-auth/react', () => ({
+  useSession: () => ({ data: null, status: state.status })
+}));
+
+jest.mock('@akinon/next/hooks', () => ({
+  __esModule: true,
+  useLocalization: () => ({ locale: 'tr', currency: 'try' })
+}));
+
+jest.mock('@akinon/next/data/client/account', () => ({
+  __esModule: true,
+  useGetOrdersQuery: () => state.query
+}));
+
+const ORDER = {
+  id: 42,
+  number: 'ORD-42',
+  amount: '100.00',
+  created_date: '2026-09-01T10:00:00Z',
+  status: { value: '550', label: 'Delivered' },
+  orderitem_set: []
+};
+
+const emptyLayout = (overrides: Record<string, unknown> = {}) => ({
+  id: 'empty-layout',
+  type: 'group',
+  properties: { role: { desktop: 'order-list-empty' } },
+  styles: {},
+  blocks: [],
+  ...overrides
+});
+
+const block = (
+  properties: Record<string, unknown> = {},
+  blocks: unknown[] = [emptyLayout()]
+) =>
+  ({
+    id: 'order-list-1',
+    type: 'order-list',
+    properties: {
+      showTitle: { desktop: true },
+      title: { desktop: 'My orders' },
+      ...properties
+    },
+    styles: {},
+    blocks
+  } as never);
+
+const renderBlock = (
+  props: Record<string, unknown> = {},
+  isDesigner = false,
+  blocks?: unknown[]
+) =>
+  render(
+    <OrderListBlock
+      block={block(props, blocks)}
+      placeholderId="p1"
+      sectionId="s1"
+      isDesigner={isDesigner}
+    />
+  );
+
+beforeEach(() => {
+  state.status = 'authenticated';
+  state.query = { data: { count: 0, results: [] }, isLoading: false };
+  state.hasTemplate = false;
+});
+
+describe('order list empty state', () => {
+  it('draws the empty-orders layout in place of the block for a shopper without orders', () => {
+    const { container } = renderBlock();
+
+    expect(screen.getByTestId('theme-block')).toHaveAttribute(
+      'data-block-id',
+      'empty-layout'
+    );
+    expect(
+      container.querySelector('[data-order-list-state="empty"]')
+    ).not.toBeNull();
+    // The layout carries its own heading; the block title gives way.
+    expect(container.textContent).not.toContain('My orders');
+  });
+
+  it('keeps the list when the shopper has orders', () => {
+    state.query = { data: { count: 1, results: [ORDER] }, isLoading: false };
+    const { container } = renderBlock();
+
+    expect(screen.queryByTestId('theme-block')).toBeNull();
+    expect(container.querySelector('[data-order-list-item]')).not.toBeNull();
+  });
+
+  it('claims nothing while the orders are loading or for a guest', () => {
+    state.query = { data: undefined, isLoading: true };
+    renderBlock();
+    expect(screen.queryByTestId('theme-block')).toBeNull();
+
+    state.status = 'unauthenticated';
+    state.query = { data: undefined, isLoading: false };
+    renderBlock();
+    expect(screen.queryByTestId('theme-block')).toBeNull();
+  });
+
+  it('leaves a hidden layout off the storefront and falls back to the empty message', () => {
+    const { container } = renderBlock(
+      { emptyLabel: { desktop: 'No orders yet' } },
+      false,
+      [emptyLayout({ hidden: true })]
+    );
+
+    expect(screen.queryByTestId('theme-block')).toBeNull();
+    expect(
+      container.querySelector('[data-order-list-state="empty"]')?.textContent
+    ).toBe('No orders yet');
+  });
+
+  it('shows the empty message on the storefront even when a row layout is set', () => {
+    state.hasTemplate = true;
+    const { container } = renderBlock(
+      { emptyLabel: { desktop: 'No orders yet' } },
+      false,
+      []
+    );
+
+    expect(container.querySelector('[data-order-list]')?.tagName).toBe('DIV');
+    expect(
+      container.querySelector('[data-order-list-state="empty"]')?.textContent
+    ).toBe('No orders yet');
+  });
+
+  it('draws the empty-orders layout on the storefront even when a row layout is set', () => {
+    state.hasTemplate = true;
+    renderBlock();
+
+    expect(screen.getByTestId('theme-block')).toHaveAttribute(
+      'data-block-id',
+      'empty-layout'
+    );
+  });
+
+  it('previews the layout on the canvas only when asked, even with orders', () => {
+    state.query = { data: { count: 1, results: [ORDER] }, isLoading: false };
+
+    renderBlock({}, true);
+    expect(screen.queryByTestId('theme-block')).toBeNull();
+
+    renderBlock({ previewEmptyState: { desktop: true } }, true);
+    expect(screen.getByTestId('theme-block')).toHaveAttribute(
+      'data-block-id',
+      'empty-layout'
+    );
+  });
+
+  it('never lets the preview toggle empty a live list', () => {
+    state.query = { data: { count: 1, results: [ORDER] }, isLoading: false };
+    renderBlock({ previewEmptyState: { desktop: true } }, false);
+
+    expect(screen.queryByTestId('theme-block')).toBeNull();
+  });
+
+  it('keeps sample rows on the canvas when a row layout is there to design', () => {
+    state.hasTemplate = true;
+    renderBlock({}, true);
+
+    expect(screen.queryByTestId('theme-block')).toBeNull();
+  });
+});

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

@@ -11,6 +11,19 @@ import { readMoneyStyle } from './money-style';
 import { hasItemTemplate, ItemTemplateList } from './item-template';
 import { readToggle } from './product-block-utils';
 import { BlockRendererProps } from './block-renderer-registry';
+import ThemeBlock, { Block } from '../theme-block';
+
+/**
+ * A child group marked with this role is what a signed-in shopper without
+ * orders sees in place of the list — a composition, so the heading, the
+ * explanation, the call-to-action links and even product suggestions are
+ * authored in the panel instead of being switched on with custom CSS. Same
+ * idea as product-grid's `listing-empty` (ZERO-5511).
+ */
+const EMPTY_STATE_ROLE = 'order-list-empty';
+
+const readChildRole = (child: Block, breakpoint: string): string =>
+  String(getResponsiveValue(child.properties?.role, breakpoint, '') ?? '');
 
 interface OrderItemLike {
   id?: number;
@@ -62,10 +75,13 @@ const sortOrders = (orders: OrderLike[], sort: string): OrderLike[] => {
  * Properties: limit, orderHrefBase, sort, showDate, showStatus, showAmount,
  * showItemImages, imageWidth, imageHeight, imageGap, imageAlign, maxImages,
  * numberLabel, dateLabel, totalLabel, detailLinkLabel, showTitle, title,
- * showPagination, perPage, emptyLabel, decimals, currencyDisplay,
- * currencyText, currencyPosition.
+ * showPagination, perPage, emptyLabel, previewEmptyState, decimals,
+ * currencyDisplay, currencyText, currencyPosition.
  * Parts: title, list, item, images, image-overflow, link, date, total,
  * detail-link, status, pagination, empty.
+ * A child group with role `order-list-empty` replaces the whole block (title
+ * included) once the shopper turns out to have no orders; without one the
+ * Empty Message (`emptyLabel`) is shown as before.
  */
 const OrderListBlock = ({
   block,
@@ -142,6 +158,22 @@ const OrderListBlock = ({
   const emptyLabel = String(
     getResponsiveValue(block.properties?.emptyLabel, currentBreakpoint, '')
   );
+  // Editor-only: an author who has orders would otherwise never see the
+  // empty-orders layout on the canvas, so there would be nothing to select
+  // and arrange. Read behind isDesigner, so it can never empty a live list.
+  const previewEmptyState = readToggle(
+    block.properties?.previewEmptyState,
+    currentBreakpoint,
+    false
+  );
+  // Hidden children stay on the canvas (so they can be brought back) and are
+  // gone on the storefront — the same rule the group block applies.
+  const emptyStateChild =
+    (block.blocks || []).find(
+      (child) =>
+        readChildRole(child, currentBreakpoint) === EMPTY_STATE_ROLE &&
+        (isDesigner || !child.hidden)
+    ) ?? null;
   // Empty keeps the built-in row exactly as it always rendered — a brand
   // opts into labels and a standalone detail link by setting these.
   const numberLabel = String(
@@ -304,7 +336,49 @@ const OrderListBlock = ({
       </div>
     ) : null;
 
-  if (orders.length === 0 && !customRows) {
+  // "The shopper has no orders" is only known once the account query has
+  // answered for a signed-in shopper; until then nothing is claimed. A later
+  // page that comes back empty is not "no orders" either.
+  const hasNoOrders =
+    isAuthenticated &&
+    !isLoading &&
+    data !== undefined &&
+    orders.length === 0 &&
+    currentPage === 1;
+
+  // The authored empty-orders layout replaces the whole block, title
+  // included — it carries its own heading when the design wants one. On the
+  // canvas it also stands in for the "no orders" placeholder box, unless a
+  // row layout is there to be designed against its sample rows.
+  if (
+    emptyStateChild &&
+    (isDesigner
+      ? previewEmptyState || (hasNoOrders && !customRows)
+      : hasNoOrders)
+  ) {
+    return (
+      <div
+        data-order-list=""
+        data-order-list-state="empty"
+        style={{ width: '100%' }}
+      >
+        <ThemeBlock
+          block={emptyStateChild}
+          placeholderId={placeholderId}
+          sectionId={sectionId}
+          isDesigner={isDesigner}
+          isSelected={selectedBlockId === emptyStateChild.id}
+          selectedBlockId={selectedBlockId}
+          currentBreakpoint={currentBreakpoint}
+        />
+      </div>
+    );
+  }
+
+  // A row layout only stands in for the rows on the canvas (as sample rows);
+  // on the storefront it renders nothing for an empty list, so the empty
+  // message must not wait on it.
+  if (orders.length === 0 && !(isDesigner && customRows)) {
     if (isDesigner) {
       return (
         <>