Reassure users about what was just verified, given the active stock availability mode

Author: mirekm

.changeset/curly-doves-dance.md

@@ -0,0 +1,5 @@
+---
+"saleor-dashboard": patch
+---
+
+ProductDoctor: Add mode-aware reassurance under public-API verification badge and tighten ambiguous diagnostic copy

locale/defaultMessages.json

@@ -2841,6 +2841,10 @@
     "context": "Warning when warehouse with stock not in shipping zone",
     "string": "Stock unreachable in \"{channelName}\""
   },
+  "EURyYW": {
+    "context": "Reassurance under verification badge when product is purchasable in direct mode",
+    "string": "Storefront API confirms the product is purchasable. Stock availability is taken directly from the warehouse-channel link, regardless of shipping zones."
+  },
   "EXqb2l": {
     "string": "Go to Saleor Cloud"
   },
@@ -5141,10 +5145,6 @@
     "context": "years after label",
     "string": "years after issue"
   },
-  "QfK+5Q": {
-    "context": "Description for warehouse not in zone warning",
-    "string": "Warehouses with stock are not assigned to any shipping zone in this channel."
-  },
   "Qhb89u": {
     "context": "Warning when no countries covered",
     "string": "No countries covered"
@@ -5545,10 +5545,6 @@
     "context": "header",
     "string": "Create Variant"
   },
-  "T7r26L": {
-    "context": "Description for no warehouses warning",
-    "string": "Products in this channel cannot be fulfilled without warehouses."
-  },
   "T83iU7": {
     "string": "Search categories..."
   },
@@ -5952,6 +5948,10 @@
   "VNX4fn": {
     "string": "Proceed"
   },
+  "VNXfqA": {
+    "context": "Reassurance under verification badge when product is purchasable in legacy mode",
+    "string": "Storefront API confirms the product is purchasable for customers covered by the channel's shipping zones."
+  },
   "VOiUXQ": {
     "string": "Used to calculate rates for shipping for products of this product type, when specific weight is not given"
   },
@@ -6733,6 +6733,10 @@
   "ZdCdo5": {
     "string": "Last updated: {date}"
   },
+  "ZemrGW": {
+    "context": "Reassurance under verification badge when product is not visible to public API",
+    "string": "The storefront API cannot find this product. Confirm it is published and listed in this channel."
+  },
   "ZepEWY": {
     "context": "Dry run item",
     "string": "Item"
@@ -8264,6 +8268,10 @@
     "context": "tooltip",
     "string": "Stock allocations occur when:"
   },
+  "icyljC": {
+    "context": "Description for no warehouses warning",
+    "string": "Without an assigned warehouse, this product will appear unavailable to customers in this channel and orders cannot be fulfilled."
+  },
   "icz/jb": {
     "context": "customer",
     "string": "Join Date"
@@ -8708,6 +8716,10 @@
   "krer6Z": {
     "string": "Features preview"
   },
+  "ksIgHn": {
+    "context": "Description for warehouse-not-in-zone warning (only fires in legacy stock availability mode)",
+    "string": "Warehouses with stock are not covered by any shipping zone in this channel. In legacy stock availability mode this hides the product from customers; assign the warehouse to a shipping zone or switch to direct stock availability."
+  },
   "kuo4fW": {
     "context": "dialog title",
     "string": "Capture manual transaction"
@@ -10847,6 +10859,10 @@
     "context": "relative time",
     "string": "just now"
   },
+  "wPODVm": {
+    "context": "Reassurance under verification badge when product is not purchasable",
+    "string": "The storefront API does not return this product as purchasable. Review the issues listed above to resolve."
+  },
   "wQdR8M": {
     "string": "Add search engine title and description to make this category easier to find"
   },

src/products/components/ProductDoctor/AvailabilityCard.test.tsx

@@ -1,7 +1,8 @@
 import Wrapper from "@test/wrapper";
 import { fireEvent, render, screen } from "@testing-library/react";
 
-import { AvailabilityCard } from "./AvailabilityCard";
+import { AvailabilityCard, PublicApiVerificationBadge } from "./AvailabilityCard";
+import { type ChannelVerificationResult } from "./hooks/usePublicApiVerification";
 import { type AvailabilityIssue, type DiagnosticsResult } from "./utils/types";
 
 // usePublicApiVerification hits the live API; stub it for isolated UI tests.
@@ -206,3 +207,116 @@ describe("AvailabilityCard channel header severity gating", () => {
     expect(badge).toHaveAttribute("data-test-count", "2");
   });
 });
+
+const makeVerification = (
+  overrides: Partial<ChannelVerificationResult["result"]> & {
+    status?: ChannelVerificationResult["status"];
+  } = {},
+): ChannelVerificationResult => {
+  const { status = "success", ...resultOverrides } = overrides;
+
+  return {
+    channelId: "channel-1",
+    channelSlug: "default-channel",
+    status,
+    error: null,
+    result:
+      status === "success"
+        ? {
+            productFound: true,
+            isAvailable: true,
+            isAvailableForPurchase: true,
+            availableForPurchaseAt: "2024-01-01T00:00:00Z",
+            variantsWithStock: 2,
+            totalVariants: 2,
+            variants: [],
+            ...resultOverrides,
+          }
+        : null,
+  };
+};
+
+describe("PublicApiVerificationBadge reassurance", () => {
+  it("shows the legacy-mode reassurance when product is purchasable in legacy mode", () => {
+    // Arrange
+    const result = makeVerification({ isAvailable: true, variantsWithStock: 2 });
+
+    // Act
+    render(
+      <PublicApiVerificationBadge result={result} useLegacyShippingZoneStockAvailability={true} />,
+      { wrapper: Wrapper },
+    );
+
+    // Assert
+    const reassurance = screen.getByTestId("verification-reassurance");
+
+    expect(reassurance).toHaveAttribute("data-test-reassurance", "purchasable-legacy");
+    // Legacy reassurance must reference shipping zones explicitly so the user
+    // understands what was verified.
+    expect(reassurance).toHaveTextContent(/shipping zones/i);
+    expect(reassurance).toHaveTextContent(/purchasable/i);
+  });
+
+  it("shows the direct-mode reassurance when product is purchasable in direct mode", () => {
+    // Arrange
+    const result = makeVerification({ isAvailable: true, variantsWithStock: 2 });
+
+    // Act
+    render(
+      <PublicApiVerificationBadge result={result} useLegacyShippingZoneStockAvailability={false} />,
+      { wrapper: Wrapper },
+    );
+
+    // Assert
+    const reassurance = screen.getByTestId("verification-reassurance");
+
+    expect(reassurance).toHaveAttribute("data-test-reassurance", "purchasable-direct");
+    // Direct-mode reassurance must call out the direct warehouse-channel link
+    // so the user knows shipping zones don't gate availability in this mode.
+    expect(reassurance).toHaveTextContent(/warehouse-channel link/i);
+    expect(reassurance).toHaveTextContent(/regardless of shipping zones/i);
+  });
+
+  it("points to the issue list when verification reports not purchasable", () => {
+    // Arrange
+    const result = makeVerification({ isAvailable: false, variantsWithStock: 0 });
+
+    // Act
+    render(<PublicApiVerificationBadge result={result} />, { wrapper: Wrapper });
+
+    // Assert
+    const reassurance = screen.getByTestId("verification-reassurance");
+
+    expect(reassurance).toHaveAttribute("data-test-reassurance", "not-purchasable");
+    expect(reassurance).toHaveTextContent(/review the issues listed above/i);
+  });
+
+  it("points to publish/listing config when product is not visible to the API", () => {
+    // Arrange
+    const result = makeVerification({ productFound: false });
+
+    // Act
+    render(<PublicApiVerificationBadge result={result} />, { wrapper: Wrapper });
+
+    // Assert
+    const reassurance = screen.getByTestId("verification-reassurance");
+
+    expect(reassurance).toHaveAttribute("data-test-reassurance", "not-visible");
+    expect(reassurance).toHaveTextContent(/published and listed/i);
+  });
+
+  it("does not render reassurance during loading or after errors", () => {
+    // Arrange / Act / Assert - loading state
+    const { rerender } = render(
+      <PublicApiVerificationBadge result={makeVerification({ status: "loading" })} />,
+      { wrapper: Wrapper },
+    );
+
+    expect(screen.queryByTestId("verification-reassurance")).toBeNull();
+
+    // Error state
+    rerender(<PublicApiVerificationBadge result={makeVerification({ status: "error" })} />);
+
+    expect(screen.queryByTestId("verification-reassurance")).toBeNull();
+  });
+});

src/products/components/ProductDoctor/AvailabilityCard.tsx

@@ -267,6 +267,9 @@ export const AvailabilityCard = ({
                               ? () => verification.verifyChannel(summary.id, summary.slug)
                               : undefined
                           }
+                          useLegacyShippingZoneStockAvailability={
+                            useLegacyShippingZoneStockAvailability
+                          }
                         />
                       );
                     })}
@@ -474,9 +477,15 @@ const StockAvailabilityModeIndicator = ({
 
 interface PublicApiVerificationBadgeProps {
   result: ChannelVerificationResult;
+  /** Active stock-availability mode. Drives the reassurance line so users know
+   *  what was just verified given the shop's mode. Defaults to legacy. */
+  useLegacyShippingZoneStockAvailability?: boolean;
 }
 
-export const PublicApiVerificationBadge = ({ result }: PublicApiVerificationBadgeProps) => {
+export const PublicApiVerificationBadge = ({
+  result,
+  useLegacyShippingZoneStockAvailability = true,
+}: PublicApiVerificationBadgeProps) => {
   const intl = useIntl();
 
   if (result.status === "loading") {
@@ -511,43 +520,95 @@ export const PublicApiVerificationBadge = ({ result }: PublicApiVerificationBadg
 
   if (!productFound) {
     return (
-      <Box display="flex" alignItems="center" gap={1}>
-        <XCircle size={14} color="var(--mu-colors-text-default2)" />
-        <Text size={1} color="default2">
-          {intl.formatMessage(messages.publicApiNotVisible)}
-        </Text>
-      </Box>
+      <PublicApiVerificationBadgeShell
+        icon={<XCircle size={14} color="var(--mu-colors-text-default2)" />}
+        statusColor="default2"
+        status={intl.formatMessage(messages.publicApiNotVisible)}
+        reassurance={intl.formatMessage(messages.verificationReassurance_notVisible)}
+        reassuranceTestId="not-visible"
+      />
     );
   }
 
   if (isAvailable && variantsWithStock > 0) {
     return (
-      <Box display="flex" alignItems="center" gap={1}>
-        <CheckCircle size={14} color="var(--mu-colors-text-success1)" />
-        <Text size={1} color="success1">
-          {intl.formatMessage(messages.publicApiPurchasable)}
-        </Text>
-        <Text size={1} color="default2">
-          · {intl.formatMessage(messages.publicApiVariantsInStock, { count: variantsWithStock })}
-        </Text>
-      </Box>
+      <PublicApiVerificationBadgeShell
+        icon={<CheckCircle size={14} color="var(--mu-colors-text-success1)" />}
+        statusColor="success1"
+        status={intl.formatMessage(messages.publicApiPurchasable)}
+        statusSuffix={intl.formatMessage(messages.publicApiVariantsInStock, {
+          count: variantsWithStock,
+        })}
+        reassurance={intl.formatMessage(
+          useLegacyShippingZoneStockAvailability
+            ? messages.verificationReassurance_purchasableLegacy
+            : messages.verificationReassurance_purchasableDirect,
+        )}
+        reassuranceTestId={
+          useLegacyShippingZoneStockAvailability ? "purchasable-legacy" : "purchasable-direct"
+        }
+      />
     );
   }
 
   return (
+    <PublicApiVerificationBadgeShell
+      icon={<XCircle size={14} color="var(--mu-colors-text-warning1)" />}
+      statusColor="warning1"
+      status={intl.formatMessage(messages.publicApiNotPurchasable)}
+      statusSuffix={
+        variantsWithStock === 0
+          ? intl.formatMessage(messages.publicApiNoVariantsInStock)
+          : undefined
+      }
+      reassurance={intl.formatMessage(messages.verificationReassurance_notPurchasable)}
+      reassuranceTestId="not-purchasable"
+    />
+  );
+};
+
+interface PublicApiVerificationBadgeShellProps {
+  icon: React.ReactNode;
+  statusColor: "success1" | "warning1" | "default2";
+  status: string;
+  /** Optional secondary status fragment (e.g. variants-in-stock count). */
+  statusSuffix?: string;
+  /** Mode-aware explanatory line that reassures the user about what was just
+   *  verified given the active stock-availability mode. */
+  reassurance: string;
+  reassuranceTestId: string;
+}
+
+const PublicApiVerificationBadgeShell = ({
+  icon,
+  statusColor,
+  status,
+  statusSuffix,
+  reassurance,
+  reassuranceTestId,
+}: PublicApiVerificationBadgeShellProps) => (
+  <Box display="flex" flexDirection="column" gap={0.5}>
     <Box display="flex" alignItems="center" gap={1}>
-      <XCircle size={14} color="var(--mu-colors-text-warning1)" />
-      <Text size={1} color="warning1">
-        {intl.formatMessage(messages.publicApiNotPurchasable)}
+      {icon}
+      <Text size={1} color={statusColor}>
+        {status}
       </Text>
-      {variantsWithStock === 0 && (
+      {statusSuffix && (
         <Text size={1} color="default2">
-          · {intl.formatMessage(messages.publicApiNoVariantsInStock)}
+          · {statusSuffix}
         </Text>
       )}
     </Box>
-  );
-};
+    <Text
+      size={1}
+      color="default2"
+      data-test-id="verification-reassurance"
+      data-test-reassurance={reassuranceTestId}
+    >
+      {reassurance}
+    </Text>
+  </Box>
+);
 
 interface ChannelSearchInputProps {
   value: string;