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

package/CHANGELOG.md

@@ -1,12 +1,15 @@
 # @akinon/pz-theme
 
-## 2.0.68-beta.0
+## 2.0.68
 
 ### Patch Changes
 
-- Updated dependencies [cbbbfd75]
-  - @akinon/next@2.0.68-beta.0
-  - @akinon/theme-contract@2.0.68-beta.0
+- 3b8382c: ZERO-4833: Add line-level tracking and return code display to order-detail-block, make the order number heading tag configurable
+
+  Item rows can now show per-line tracking info (`showLineTracking`/`lineTrackingLabel`) and the active cancellation's return code (`showReturnCode`/`returnCodeLabel`). The order number can render as `h1`–`h3` via `numberTag` when it's the page's main heading. Removed the unused `packageLabel` and `quantityPrefix` properties in favor of the existing label/tag conventions used elsewhere in the block.
+
+  - @akinon/next@2.0.68
+  - @akinon/theme-contract@2.0.68
 
 ## 2.0.67
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.68-beta.0",
+  "version": "2.0.68",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.68-beta.0",
+    "@akinon/next": "2.0.68",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.68-beta.0",
+    "@akinon/theme-contract": "2.0.68",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.68-beta.0",
+    "@akinon/next": "2.0.68",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

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

@@ -25,6 +25,7 @@ interface OrderItemLike {
   tracking_number?: string;
   estimated_delivery_date?: string;
   price_currency?: { value?: string; label?: string };
+  active_cancellation_request?: unknown;
   product?: {
     pk?: number;
     name?: string;
@@ -90,6 +91,11 @@ const ORDER_PARAM_KEYS = [
   'order'
 ];
 
+// Same allow-list-then-cast pattern as product-title-block's heading tag —
+// span keeps every existing composition's layout unchanged; a designer
+// opts into h1/h2/h3 when the order number is the page's main heading.
+const NUMBER_TAGS = ['span', 'div', 'h1', 'h2', 'h3'];
+
 const firstString = (
   read: (key: string) => unknown,
   keys: string[]
@@ -146,8 +152,13 @@ const DESIGNER_SAMPLE_ORDER: OrderLike = {
       price: '2299.50',
       quantity: 1,
       total_amount: '2299.50',
-      status: { value: '10', label: 'Approved' },
+      status: { value: '80', label: 'Cancelled' },
       price_currency: { value: 'try', label: 'TRY' },
+      tracking_number: '1Z999AA10123456784',
+      tracking_url: '#',
+      active_cancellation_request: [
+        { easy_return: { code: '12345678912345' } }
+      ],
       product: {
         pk: 1,
         name: 'Sample Product',
@@ -224,6 +235,19 @@ const resolveAttribute = (
   return typeof value === 'string' ? value : '';
 };
 
+/**
+ * Shape varies by pz version — some payloads carry the active cancellation
+ * request as a single object, others as a one-item array — so both are
+ * probed rather than assuming either.
+ */
+const resolveReturnCode = (value: unknown): string => {
+  const entry = Array.isArray(value) ? value[0] : value;
+  const code = (entry as { easy_return?: { code?: string } } | null | undefined)
+    ?.easy_return?.code;
+
+  return typeof code === 'string' ? code : '';
+};
+
 const formatAddress = (address: AddressLike | null | undefined): string[] => {
   if (!address) return [];
   const name = [address.first_name, address.last_name]
@@ -248,22 +272,23 @@ 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.
- * Properties: packageLabel, numberLabel, dateLabel, headerTotalLabel,
+ * Properties: numberLabel, numberTag, dateLabel, headerTotalLabel,
  * showInvoiceLink, invoiceLinkLabel, showCancelLink, cancelLinkLabel,
  * cancelHrefBase, showShipmentStatus, showItems, showImage, imageWidth,
- * imageHeight, showQuantity, quantityLabel, quantityPrefix, showColor,
+ * imageHeight, showQuantity, quantityLabel, showColor,
  * colorLabel, colorAttributeKey, showSize, sizeLabel, sizeAttributeKey,
- * showShippingAddress, shippingAddressLabel, showBillingAddress,
- * billingAddressLabel, showTotals, showPieceCount, pieceCountLabel,
- * showDiscountItems, showInstallmentInfo, installmentInfoLabel,
- * subtotalLabel, discountLabel, shippingLabel, freeShippingLabel, totalLabel,
- * trackingLabel,
+ * showLineTracking, lineTrackingLabel, showReturnCode,
+ * returnCodeLabel, showShippingAddress, shippingAddressLabel,
+ * showBillingAddress, billingAddressLabel, showTotals, showPieceCount,
+ * pieceCountLabel, showDiscountItems, showInstallmentInfo,
+ * installmentInfoLabel, subtotalLabel, discountLabel, shippingLabel,
+ * freeShippingLabel, totalLabel, trackingLabel,
  * showPaymentInfo, paymentInfoLabel.
- * Parts: detail, header, package-label, number, date, header-total, status,
+ * Parts: detail, header, number, date, header-total, status,
  * invoice-link, cancel-link, list, item, image, name, quantity, color, size,
- * item-status, price, shipment, delivery, tracking, addresses, address,
- * address-label, totals, total-row, total-label, total-value, grand-total,
- * payment-info, payment-info-label.
+ * item-status, item-tracking, item-return-code, price, shipment,
+ * delivery, tracking, addresses, address, address-label, totals, total-row,
+ * total-label, total-value, grand-total, payment-info, payment-info-label.
  */
 const OrderDetailBlock = ({
   block,
@@ -310,7 +335,6 @@ const OrderDetailBlock = ({
     String(
       getResponsiveValue(block.properties?.[key], currentBreakpoint, fallback)
     );
-  const quantityPrefix = text('quantityPrefix', 'x');
   const quantityLabel = text('quantityLabel', '');
   const subtotalLabel = text('subtotalLabel', 'Subtotal');
   const discountLabel = text('discountLabel', 'Discount');
@@ -319,11 +343,16 @@ const OrderDetailBlock = ({
   const totalLabel = text('totalLabel', 'Total');
   const trackingLabel = text('trackingLabel', 'Track shipment');
 
-  // Header: empty keeps the original bare header (no package tag, no
-  // separate labelled total line, no invoice/cancel links) — every one of
-  // these is an opt-in addition, same as the order-list block's labels.
-  const packageLabel = text('packageLabel', '');
+  // Header: empty keeps the original bare header (no separate labelled
+  // total line, no invoice/cancel links) — every one of these is an opt-in
+  // addition, same as the order-list block's labels.
   const numberLabel = text('numberLabel', '');
+  const numberTagValue = String(
+    getResponsiveValue(block.properties?.numberTag, currentBreakpoint, 'span')
+  );
+  const NumberTag = (
+    NUMBER_TAGS.includes(numberTagValue) ? numberTagValue : 'span'
+  ) as React.ElementType;
   const dateLabel = text('dateLabel', '');
   const headerTotalLabel = text('headerTotalLabel', '');
   const showInvoiceLink = readToggle(
@@ -355,6 +384,19 @@ const OrderDetailBlock = ({
   const sizeLabel = text('sizeLabel', 'Size:');
   const sizeAttributeKey = text('sizeAttributeKey', '');
 
+  const showLineTracking = readToggle(
+    block.properties?.showLineTracking,
+    currentBreakpoint,
+    false
+  );
+  const lineTrackingLabel = text('lineTrackingLabel', 'Tracking:');
+  const showReturnCode = readToggle(
+    block.properties?.showReturnCode,
+    currentBreakpoint,
+    false
+  );
+  const returnCodeLabel = text('returnCodeLabel', 'Return code:');
+
   const showShippingAddress = readToggle(
     block.properties?.showShippingAddress,
     currentBreakpoint,
@@ -453,6 +495,13 @@ const OrderDetailBlock = ({
     gap: '12px'
   };
 
+  // Below the header, every block lines its content up under the item rows'
+  // text half rather than the page's own left edge — the image half stays
+  // empty air beside them, same as the reference layout.
+  const halfShift: React.CSSProperties = isMobile
+    ? {}
+    : { width: '50%', marginLeft: '50%' };
+
   const lineRows = groupedItems.map((line) => {
     const lineCurrency = line.item.price_currency?.value || currency;
 
@@ -572,23 +621,14 @@ const OrderDetailBlock = ({
         }}
       >
         <div style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
-          {packageLabel && (
-            <span
-              data-order-detail-package=""
-              {...partAttrs('package-label')}
-              style={{ opacity: 0.7 }}
-            >
-              {packageLabel}
-            </span>
-          )}
-          <span
+          <NumberTag
             data-order-detail-number=""
             {...partAttrs('number')}
             style={{ fontWeight: 600 }}
           >
             {numberLabel ? `${numberLabel} ` : ''}
             {order.number || orderKey}
-          </span>
+          </NumberTag>
         </div>
 
         <div
@@ -700,6 +740,12 @@ const OrderDetailBlock = ({
               const sizeValue = showSize
                 ? resolveAttribute(item.product?.attributes, sizeAttributeKey)
                 : '';
+              const trackingValue = showLineTracking
+                ? item.tracking_number || item.tracking_url || ''
+                : '';
+              const returnCodeValue = showReturnCode
+                ? resolveReturnCode(item.active_cancellation_request)
+                : '';
 
               return (
                 <li
@@ -708,6 +754,7 @@ const OrderDetailBlock = ({
                   {...partAttrs('item')}
                   style={{
                     display: 'flex',
+                    flexWrap: isMobile ? 'wrap' : 'nowrap',
                     alignItems: 'flex-start',
                     gap: '12px',
                     paddingBottom: '16px',
@@ -716,90 +763,161 @@ const OrderDetailBlock = ({
                   }}
                 >
                   {showImage && item.product?.image && (
-                    <NextLink
-                      href={isDesigner ? '#' : href || '#'}
-                      onClick={guard}
-                      style={{ flex: '0 0 auto', display: 'block' }}
+                    <div
+                      style={{
+                        flex: isMobile ? '1 1 auto' : '1 1 50%',
+                        display: 'flex',
+                        justifyContent: isMobile ? 'flex-start' : 'flex-end'
+                      }}
                     >
-                      {/* Plain img: order line thumbnails come from arbitrary
-                        commerce CDNs that the brand next.config may not allow. */}
-                      {/* eslint-disable-next-line @next/next/no-img-element */}
-                      <img
-                        src={item.product.image}
-                        alt={name}
-                        width={imageWidth}
-                        height={imageHeight}
-                        {...partAttrs('image')}
-                        style={{ objectFit: 'cover', display: 'block' }}
-                      />
-                    </NextLink>
+                      <NextLink
+                        href={isDesigner ? '#' : href || '#'}
+                        onClick={guard}
+                        style={{ display: 'block' }}
+                      >
+                        {/* Plain img: order line thumbnails come from arbitrary
+                          commerce CDNs that the brand next.config may not allow. */}
+                        {/* eslint-disable-next-line @next/next/no-img-element */}
+                        <img
+                          src={item.product.image}
+                          alt={name}
+                          width={imageWidth}
+                          height={imageHeight}
+                          {...partAttrs('image')}
+                          style={{ objectFit: 'cover', display: 'block' }}
+                        />
+                      </NextLink>
+                    </div>
                   )}
 
-                  <div style={{ flex: '1 1 auto', minWidth: 0 }}>
-                    <NextLink
-                      href={isDesigner ? '#' : href || '#'}
-                      onClick={guard}
-                      data-order-detail-item-name=""
-                      {...partAttrs('name')}
-                      style={{ textDecoration: 'none' }}
-                    >
-                      {name}
-                    </NextLink>
-
-                    {showColor && colorValue && (
-                      <div
-                        data-order-detail-item-color=""
-                        {...partAttrs('color')}
-                        style={{ marginTop: '4px' }}
+                  <div
+                    style={{
+                      flex: isMobile ? '1 1 100%' : '1 1 50%',
+                      display: 'flex',
+                      flexWrap: 'wrap',
+                      justifyContent: 'space-between',
+                      gap: '12px',
+                      minWidth: 0
+                    }}
+                  >
+                    <div style={{ flex: '1 1 auto', minWidth: 0 }}>
+                      <NextLink
+                        href={isDesigner ? '#' : href || '#'}
+                        onClick={guard}
+                        data-order-detail-item-name=""
+                        {...partAttrs('name')}
+                        style={{ textDecoration: 'none' }}
                       >
-                        {colorLabel} {colorValue}
-                      </div>
-                    )}
+                        {name}
+                      </NextLink>
 
-                    {showSize && sizeValue && (
-                      <div
-                        data-order-detail-item-size=""
-                        {...partAttrs('size')}
-                        style={{ marginTop: '4px' }}
-                      >
-                        {sizeLabel} {sizeValue}
-                      </div>
-                    )}
+                      {showColor && colorValue && (
+                        <div
+                          data-order-detail-item-color=""
+                          {...partAttrs('color')}
+                          style={{ marginTop: '4px' }}
+                        >
+                          {colorLabel} {colorValue}
+                        </div>
+                      )}
 
-                    {showQuantity && (
-                      <div
-                        data-order-detail-item-quantity=""
-                        {...partAttrs('quantity')}
-                        style={{ marginTop: '4px', opacity: 0.8 }}
-                      >
-                        {quantityLabel
-                          ? `${quantityLabel} ${line.quantity}`
-                          : `${quantityPrefix}${line.quantity}`}
-                      </div>
-                    )}
+                      {showSize && sizeValue && (
+                        <div
+                          data-order-detail-item-size=""
+                          {...partAttrs('size')}
+                          style={{ marginTop: '4px' }}
+                        >
+                          {sizeLabel} {sizeValue}
+                        </div>
+                      )}
+
+                      {showQuantity && (
+                        <div
+                          data-order-detail-item-quantity=""
+                          {...partAttrs('quantity')}
+                          style={{ marginTop: '4px', opacity: 0.8 }}
+                        >
+                          {quantityLabel
+                            ? `${quantityLabel} ${line.quantity}`
+                            : line.quantity}
+                        </div>
+                      )}
 
-                    {showShipmentStatus && item.status?.label && (
                       <div
-                        data-order-detail-item-status=""
-                        data-order-status-value={item.status.value}
-                        {...partAttrs('item-status')}
-                        style={{ marginTop: '4px', opacity: 0.8 }}
+                        data-order-detail-item-price=""
+                        {...partAttrs('price')}
+                        style={{ marginTop: '4px', fontWeight: 600 }}
                       >
-                        {item.status.label}
+                        {/* The row now stands for every unit of the product, so
+                          the group's summed line total is what it must price —
+                          the single line's total_amount would understate an
+                          "x3" row. For an ungrouped row this is the value
+                          printed before. */}
+                        {formatMoney(line.total, {
+                          locale,
+                          currency: lineCurrency
+                        })}
                       </div>
-                    )}
-                  </div>
+                    </div>
 
-                  <span data-order-detail-item-price="" {...partAttrs('price')}>
-                    {/* The row now stands for every unit of the product, so the
-                      group's summed line total is what it must price — the
-                      single line's total_amount would understate an "x3" row.
-                      For an ungrouped row this is the value printed before. */}
-                    {formatMoney(line.total, {
-                      locale,
-                      currency: lineCurrency
-                    })}
-                  </span>
+                    {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>
+                      )}
+                  </div>
                 </li>
               );
             })}
@@ -810,7 +928,12 @@ const OrderDetailBlock = ({
         <section
           data-order-detail-shipment=""
           {...partAttrs('shipment')}
-          style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '4px',
+            ...halfShift
+          }}
         >
           {items.some((item) => item.estimated_delivery_date) && (
             <span
@@ -854,7 +977,8 @@ const OrderDetailBlock = ({
           style={{
             display: 'flex',
             flexDirection: isMobile ? 'column' : 'row',
-            gap: isMobile ? '16px' : '40px'
+            gap: isMobile ? '16px' : '40px',
+            ...halfShift
           }}
         >
           {showShippingAddress &&
@@ -872,7 +996,12 @@ const OrderDetailBlock = ({
         <section
           data-order-detail-totals=""
           {...partAttrs('totals')}
-          style={{ display: 'flex', flexDirection: 'column', gap: '8px' }}
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '8px',
+            ...halfShift
+          }}
         >
           {showPieceCount &&
             totalRow(
@@ -923,7 +1052,12 @@ const OrderDetailBlock = ({
         <section
           data-order-detail-payment=""
           {...partAttrs('payment-info')}
-          style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}
+          style={{
+            display: 'flex',
+            flexDirection: 'column',
+            gap: '4px',
+            ...halfShift
+          }}
         >
           <div
             {...partAttrs('payment-info-label')}