@akinon/pz-theme 2.0.157 → 2.0.158-beta.0

package/CHANGELOG.md

@@ -1,10 +1,20 @@
 # @akinon/pz-theme
 
+## 2.0.158-beta.0
+
+### Patch Changes
+
+- Updated dependencies [cbbbfd757]
+  - @akinon/next@2.0.158-beta.0
+  - @akinon/theme-contract@2.0.158-beta.0
+
 ## 2.0.157
 
 ### Patch Changes
 
+- 3002c2cc: ZERO-5302: The order detail's return and cancel links offer what commerce allows and what a storefront's order-action rules let through (`registerOrderActionRules`: which lines a return may start from, whether an order may be cancelled). With no rules registered, commerce's `is_refundable` and `is_cancellable` flags decide; the block no longer limits returns to delivered lines on its own.
 - Updated dependencies [219164a3]
+- Updated dependencies [9c778307]
   - @akinon/next@2.0.157
   - @akinon/theme-contract@2.0.157
 

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.157",
+  "version": "2.0.158-beta.0",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.157",
+    "@akinon/next": "2.0.158-beta.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.157",
+    "@akinon/theme-contract": "2.0.158-beta.0",
     "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.157",
+    "@akinon/next": "2.0.158-beta.0",
     "@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-detail-return.test.tsx

@@ -1,6 +1,10 @@
 import React from 'react';
 import { render } from '@testing-library/react';
 import OrderDetailBlock from '../order-detail-block';
+import {
+  __resetOrderActionRulesForTests,
+  registerOrderActionRules
+} from '../../utils/order-action-rules';
 
 /**
  * ZERO-5183 — the order detail is where an easy return starts and where a
@@ -64,6 +68,8 @@ const texts = (root: ParentNode, part: string) =>
     (e.textContent || '').replace(/\s+/g, ' ').trim()
   );
 
+afterEach(() => __resetOrderActionRulesForTests());
+
 beforeEach(() => {
   order = {
     id: 42,
@@ -164,7 +170,7 @@ describe('order detail — easy returns', () => {
     expect(container.querySelector('[data-part="return-link"]')).toBeNull();
   });
 
-  it('links only a delivered line that has no request yet', () => {
+  it('links a refundable 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>[] = (
@@ -194,15 +200,74 @@ describe('order detail — easy returns', () => {
     };
     expect(returnLink()).toBeNull();
 
-    // Commerce calls a shipped line refundable too; it is not returned yet.
+    // Commerce calls a shipped line refundable too, and with no rule from
+    // the brand that is what decides (ZERO-5302).
     order = {
       ...order,
       orderitem_set: flagged.map((item) =>
-        item.id === 3
-          ? { ...item, status: { value: '500', label: 'Gönderildi' } }
-          : item
+        item.id === 3 ? { ...item, status: { value: '500' } } : item
       )
     };
+    expect(returnLink()).not.toBeNull();
+  });
+
+  it("asks the brand's rules about a line commerce lets go back (ZERO-5302)", () => {
+    const asked: string[] = [];
+    registerOrderActionRules({
+      returnLine: (item) => {
+        asked.push(String(item.status?.value));
+        return item.status?.value === '550';
+      }
+    });
+    const returnLink = () =>
+      render(
+        <OrderDetailBlock
+          block={blockOf(ALL_ON) as never}
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+        />
+      ).container.querySelector('[data-part="return-link"]');
+    const withLine3 = (status: string) => ({
+      ...order,
+      orderitem_set: (order?.orderitem_set as Record<string, unknown>[]).map(
+        (item) =>
+          item.id === 3
+            ? { ...item, is_refundable: true, status: { value: status } }
+            : { ...item, is_refundable: false }
+      )
+    });
+
+    order = withLine3('550');
+    expect(returnLink()).not.toBeNull();
+
+    order = withLine3('500');
     expect(returnLink()).toBeNull();
+    // Only the line commerce lets go back is put to the brand.
+    expect(new Set(asked)).toEqual(new Set(['550', '500']));
+  });
+
+  it('withholds the cancel link when the brand switches cancellation off (ZERO-5302)', () => {
+    order = { ...order, is_cancellable: true };
+    const cancelLink = () =>
+      render(
+        <OrderDetailBlock
+          block={
+            blockOf({
+              ...ALL_ON,
+              showCancelLink: { desktop: true },
+              cancelLinkLabel: { desktop: 'Cancel' }
+            }) as never
+          }
+          placeholderId="p1"
+          sectionId="s1"
+          isDesigner={false}
+        />
+      ).container.querySelector('[data-part="cancel-link"]');
+
+    expect(cancelLink()).not.toBeNull();
+
+    registerOrderActionRules({ cancelOrder: () => false });
+    expect(cancelLink()).toBeNull();
   });
 });

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

@@ -15,6 +15,14 @@ import {
   groupOrderItems,
   readToggle
 } from './product-block-utils';
+import {
+  allowsLineReturn,
+  allowsOrderCancel,
+  type OrderActionLine,
+  type OrderActionOrder,
+  type OrderActionRules,
+  useOrderActionRules
+} from '../utils/order-action-rules';
 
 interface OrderItemLike {
   id?: number;
@@ -117,31 +125,39 @@ const firstString = (
 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.
+ * Whether the order still has a line to return: one commerce flags
+ * refundable, with no request open on it, that the brand's rules let a return
+ * start from (`registerOrderActionRules`: from which statuses, for how long
+ * after the order — ZERO-5302). Commerce 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 again after the shopper has asked. Lines that carry no
+ * flag at all (an older payload) go by the order's flag, still through the
+ * brand's rules.
  */
-const hasReturnableLine = (order: OrderLike): boolean => {
+const hasReturnableLine = (
+  order: OrderLike,
+  rules: OrderActionRules
+): boolean => {
   if (!order.is_refundable) return false;
 
   const lines = order.orderitem_set ?? [];
+  const allows = (item: OrderItemLike | null | undefined) =>
+    allowsLineReturn(
+      rules,
+      (item ?? {}) as OrderActionLine,
+      order as OrderActionOrder
+    );
 
   if (!lines.some((item) => item && 'is_refundable' in item)) {
-    return String(order.status?.value ?? '') === DELIVERED;
+    return lines.length === 0 ? allows(null) : lines.some(allows);
   }
 
   return lines.some(
     (item) =>
-      String(item?.status?.value ?? '') === DELIVERED &&
       item?.is_refundable &&
-      !hasOpenRequest(item.active_cancellation_request)
+      !hasOpenRequest(item.active_cancellation_request) &&
+      allows(item)
   );
 };
 
@@ -373,6 +389,8 @@ const formatAddress = (address: AddressLike | null | undefined): string[] => {
  * 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.
+ * The cancel and return links offer what commerce allows and the brand's
+ * `registerOrderActionRules` lets through (ZERO-5302).
  * Properties: numberLabel, numberTag, dateLabel, headerTotalLabel,
  * showInvoiceLink, invoiceLinkLabel, showCancelLink, cancelLinkLabel,
  * showReturnLink, returnLinkLabel, cancelHrefBase, showShipmentStatus, showItems, showImage, imageWidth,
@@ -588,6 +606,8 @@ const OrderDetailBlock = ({
   // Not gated on the session: brands expose the same endpoint for anonymous
   // order tracking. Without a key there is nothing to ask for at all.
   const { data, isLoading } = useGetOrderQuery(orderKey, { skip: !orderKey });
+  // The brand's say over the return and cancel links (ZERO-5302).
+  const actionRules = useOrderActionRules();
 
   const liveOrder = (data ?? null) as OrderLike | null;
   // See DESIGNER_SAMPLE_ORDER's own comment: the preview route's order id is
@@ -621,11 +641,16 @@ 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.
+  // The sample order shows both links for styling, whatever the brand's
+  // rules would make of it.
   const offersReturn =
     order === DESIGNER_SAMPLE_ORDER
       ? Boolean(order.is_refundable)
-      : hasReturnableLine(order);
+      : hasReturnableLine(order, actionRules);
+  const offersCancel =
+    Boolean(order.is_cancellable) &&
+    (order === DESIGNER_SAMPLE_ORDER ||
+      allowsOrderCancel(actionRules, order as OrderActionOrder));
 
   // Navigating inside the designer iframe would drop the author out of the page
   // they are editing, so every link is inert there.
@@ -830,7 +855,7 @@ const OrderDetailBlock = ({
                     → {invoiceLinkLabel}
                   </a>
                 )}
-                {showCancelLink && order.is_cancellable && cancelHref && (
+                {showCancelLink && offersCancel && cancelHref && (
                   <NextLink
                     href={isDesigner ? '#' : cancelHref}
                     onClick={guard}

package/src/utils/__tests__/order-action-rules.test.tsx

@@ -0,0 +1,96 @@
+import React from 'react';
+import { act, render, screen } from '@testing-library/react';
+
+import {
+  __resetOrderActionRulesForTests,
+  allowsLineReturn,
+  allowsOrderCancel,
+  registerOrderActionRules,
+  useOrderActionRules
+} from '../order-action-rules';
+
+/**
+ * The brand's say over the order actions a storefront offers (ZERO-5302):
+ * asked only about what commerce already allows; with no rule, commerce's
+ * flags decide.
+ */
+
+const line = (status: string) => ({ id: 1, status: { value: status } });
+const order = { id: 7, number: 'O-7' };
+
+afterEach(() => __resetOrderActionRulesForTests());
+
+describe('order action rules', () => {
+  it('leaves the decision to commerce when no brand registered rules', () => {
+    expect(allowsLineReturn({}, line('500'), order)).toBe(true);
+    expect(allowsOrderCancel({}, order)).toBe(true);
+  });
+
+  it('lets a brand narrow returns and cancellations', () => {
+    const rules = {
+      returnLine: (item: { status?: { value?: string } | null }) =>
+        item.status?.value === '550',
+      cancelOrder: () => false
+    };
+
+    expect(allowsLineReturn(rules, line('550'), order)).toBe(true);
+    expect(allowsLineReturn(rules, line('500'), order)).toBe(false);
+    expect(allowsOrderCancel(rules, order)).toBe(false);
+  });
+
+  it('gives a rule that throws no say', () => {
+    const rules = {
+      returnLine: () => {
+        throw new Error('brand bug');
+      },
+      cancelOrder: () => {
+        throw new Error('brand bug');
+      }
+    };
+
+    expect(allowsLineReturn(rules, line('550'), order)).toBe(true);
+    expect(allowsOrderCancel(rules, order)).toBe(true);
+  });
+
+  it('renders a reader again when the rules are registered or dropped', () => {
+    const Reader = () => {
+      const rules = useOrderActionRules();
+      return (
+        <span data-testid="reader">
+          {allowsLineReturn(rules, line('500'), order) ? 'offers' : 'withholds'}
+        </span>
+      );
+    };
+    render(<Reader />);
+    expect(screen.getByTestId('reader')).toHaveTextContent('offers');
+
+    let unregister = () => {};
+    act(() => {
+      unregister = registerOrderActionRules({ returnLine: () => false });
+    });
+    expect(screen.getByTestId('reader')).toHaveTextContent('withholds');
+
+    act(() => unregister());
+    expect(screen.getByTestId('reader')).toHaveTextContent('offers');
+  });
+
+  it('keeps rules registered later when an older registration unregisters', () => {
+    const first = registerOrderActionRules({ returnLine: () => false });
+    const second = { returnLine: () => true };
+    registerOrderActionRules(second);
+
+    first();
+
+    expect(allowsLineReturn(second, line('500'), order)).toBe(true);
+    const Reader = () => {
+      const rules = useOrderActionRules();
+      return (
+        <span data-testid="current">
+          {rules === second ? 'second' : 'other'}
+        </span>
+      );
+    };
+    render(<Reader />);
+    expect(screen.getByTestId('current')).toHaveTextContent('second');
+  });
+});

package/src/utils/order-action-rules.ts

@@ -0,0 +1,115 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * Brand hook for the order actions a storefront offers (ZERO-5302).
+ *
+ * Commerce says what it allows: a line it will take back is flagged
+ * `is_refundable`, an order it will cancel `is_cancellable`. Whether the
+ * storefront offers that return or that cancellation is a brand decision on
+ * top — from which statuses, for how long after the order, whether the action
+ * is switched on at all — so the order blocks never learn it. A brand
+ * registers its rules from its own code (the pattern of the search-term
+ * transform), and the blocks ask them only about what commerce already
+ * allows. No registration, or a rule left out, and commerce's flags decide.
+ * A rule that throws has no say: a brand bug must not take the page down.
+ *
+ * Rules may be registered again when what they depend on arrives (a brand
+ * reading its settings from a widget, say); every block reading them through
+ * `useOrderActionRules` renders again.
+ */
+
+export interface OrderActionLine {
+  id?: number | string;
+  status?: { value?: string; label?: string } | null;
+  created_date?: string | null;
+  is_refundable?: boolean;
+  is_cancellable?: boolean;
+  [key: string]: unknown;
+}
+
+export interface OrderActionOrder {
+  id?: number | string;
+  number?: string;
+  created_date?: string | null;
+  status?: { value?: string; label?: string } | null;
+  [key: string]: unknown;
+}
+
+export interface OrderActionRules {
+  /**
+   * Whether a return may start from this line. Asked only about a line
+   * commerce flags refundable and that has no request open on it.
+   */
+  returnLine?: (line: OrderActionLine, order: OrderActionOrder) => boolean;
+  /**
+   * Whether the order may be cancelled from the storefront. Asked only about
+   * an order commerce flags cancellable.
+   */
+  cancelOrder?: (order: OrderActionOrder) => boolean;
+}
+
+const NO_RULES: OrderActionRules = {};
+
+let current: OrderActionRules = NO_RULES;
+const listeners = new Set<() => void>();
+
+const notify = () => listeners.forEach((listener) => listener());
+
+/** Register the brand's rules. Returns an unregister function. */
+export const registerOrderActionRules = (
+  rules: OrderActionRules
+): (() => void) => {
+  current = rules;
+  notify();
+  return () => {
+    if (current !== rules) return;
+    current = NO_RULES;
+    notify();
+  };
+};
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+const getSnapshot = () => current;
+const getServerSnapshot = () => NO_RULES;
+
+/** The rules in force; the caller renders again when they are replaced. */
+export const useOrderActionRules = (): OrderActionRules =>
+  useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+/** Whether the brand lets a return start from a line commerce allows. */
+export const allowsLineReturn = (
+  rules: OrderActionRules,
+  line: OrderActionLine,
+  order: OrderActionOrder
+): boolean => {
+  if (!rules.returnLine) return true;
+  try {
+    return rules.returnLine(line, order) !== false;
+  } catch {
+    return true;
+  }
+};
+
+/** Whether the brand lets an order commerce allows be cancelled. */
+export const allowsOrderCancel = (
+  rules: OrderActionRules,
+  order: OrderActionOrder
+): boolean => {
+  if (!rules.cancelOrder) return true;
+  try {
+    return rules.cancelOrder(order) !== false;
+  } catch {
+    return true;
+  }
+};
+
+/** Test-only: drop the registered rules between cases. */
+export const __resetOrderActionRulesForTests = (): void => {
+  current = NO_RULES;
+};