@reblu/site-blocks 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
+import { ShopErrorCode, PageDetail, PageListItem, ShopProductListItem, ShopFacets, ShopOrder } from '@reblu/site-contracts';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { PageDetail, PageListItem, ShopProductListItem, ShopFacets, ShopOrder } from '@reblu/site-contracts';
 import { ReactNode, FormEvent } from 'react';
 
 declare function readingTime(content: string | null | undefined): number | null;
@@ -29,6 +29,30 @@ interface ShareUrls {
 }
 declare function buildShareUrls(url: string, title: string): ShareUrls;
 
+/**
+ * Default Spanish copy for every stable `ShopErrorCode` (REB-836) the shop
+ * write endpoints (`checkout`/`validateCart`/`applyDiscount`) may return in
+ * the error body's optional `code` field — see `ApiError.body.code` in
+ * `@reblu/site-client`. A SITE overrides any subset through
+ * {@link getShopErrorMessage}'s `overrides` parameter, or ignores `code`
+ * entirely and reads `ApiError.message` as before (REB-836 is additive).
+ */
+declare const DEFAULT_SHOP_ERROR_MESSAGES: Record<ShopErrorCode, string>;
+/** Fallback copy used when `code` is missing or not recognised. */
+declare const DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE = "No se ha podido completar la operaci\u00F3n. Int\u00E9ntalo de nuevo.";
+/**
+ * Resolves the user-facing message for a checkout/validate-cart/apply-discount
+ * error `code` (REB-836) — e.g. `ApiError.body?.code` from `@reblu/site-client`.
+ *
+ * @param code - The stable error code, or `null`/`undefined` when the response
+ *   carried none (an older base-api, or a non-shop error).
+ * @param overrides - Replaces any subset of {@link DEFAULT_SHOP_ERROR_MESSAGES}
+ *   without having to restate every other code — e.g. for a non-Spanish SITE.
+ * @param fallback - Used when `code` is missing or unrecognised.
+ *   Defaults to {@link DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE}.
+ */
+declare function getShopErrorMessage(code: string | null | undefined, overrides?: Partial<Record<ShopErrorCode, string>>, fallback?: string): string;
+
 /**
  * Canonical Blog markdown → **safe HTML** pipeline for the Reblu SITE SDK.
  *
@@ -384,47 +408,6 @@ interface ShopFiltersProps {
 declare function shouldRenderShopFilters(facets: ShopFacets, active?: ShopFiltersActive): boolean;
 declare function ShopFilters({ facets, hrefs, active, onChange, priceBands, labels, currencyCode, locale, className, }: ShopFiltersProps): react_jsx_runtime.JSX.Element | null;
 
-/**
- * `AddToCartButton` — presentational add-to-cart CTA (REB-829). RSC-safe by
- * construction (same contract as `ShopFilters`'s `OptionLink`): passing
- * `onAddToCart` only makes sense from a Client Component, but the component
- * itself carries no `'use client'` directive, so a Server Component may
- * still render it WITHOUT the prop (e.g. a disabled preview state).
- */
-interface AddToCartButtonLabels {
-    add: string;
-    adding: string;
-    outOfStock: string;
-}
-interface AddToCartButtonProps {
-    onAddToCart?: () => void;
-    disabled?: boolean;
-    outOfStock?: boolean;
-    /** True while the add-to-cart call (or a navigation it triggers) is in flight. */
-    pending?: boolean;
-    labels?: Partial<AddToCartButtonLabels>;
-    className?: string;
-}
-declare function AddToCartButton({ onAddToCart, disabled, outOfStock, pending, labels, className, }: AddToCartButtonProps): react_jsx_runtime.JSX.Element;
-
-/**
- * `CartIcon` — presentational cart badge/link (REB-829). RSC-safe (plain
- * `<a href>`, no hooks) — a Server Component can render it directly with a
- * value already computed server-side; a Client Component drives `itemCount`
- * from `@reblu/site-next/cart`'s `useCart().itemCount`.
- */
-interface CartIconLabels {
-    cart: string;
-    itemsSuffix: (count: number) => string;
-}
-interface CartIconProps {
-    itemCount: number;
-    href: string;
-    labels?: Partial<CartIconLabels>;
-    className?: string;
-}
-declare function CartIcon({ itemCount, href, labels, className }: CartIconProps): react_jsx_runtime.JSX.Element;
-
 /**
  * `CartLineList` — presentational cart lines (REB-829), container/
  * presentational split: it takes `items` + optional `onQuantityChange`/
@@ -454,6 +437,8 @@ interface CartLineListLabels {
     increase: string;
     remove: string;
     unitPriceSuffix: string;
+    /** REB-837 — default copy for `notice={true}`. */
+    cancelledNotice: string;
 }
 interface CartLineListProps {
     items: CartLineItemView[];
@@ -466,12 +451,18 @@ interface CartLineListProps {
      * only renders the live region.
      */
     liveMessage?: string;
+    /**
+     * REB-837 — a notice shown above the lines. `true` renders the default
+     * "pago cancelado" copy (`labels.cancelledNotice`); pass any other
+     * `ReactNode` for custom content, or omit/`false` to render nothing.
+     */
+    notice?: boolean | React.ReactNode;
     labels?: Partial<CartLineListLabels>;
     currencyCode?: string;
     locale?: string;
     className?: string;
 }
-declare function CartLineList({ items, onQuantityChange, onRemove, liveMessage, labels, currencyCode, locale, className, }: CartLineListProps): react_jsx_runtime.JSX.Element;
+declare function CartLineList({ items, onQuantityChange, onRemove, liveMessage, notice, labels, currencyCode, locale, className, }: CartLineListProps): react_jsx_runtime.JSX.Element;
 
 /**
  * `CartSummary` — presentational price breakdown (REB-829): subtotal,
@@ -492,6 +483,8 @@ interface CartSummaryLabels {
      */
     shippingCalculated: string;
     total: string;
+    /** REB-837 — default copy for `notice={true}`. */
+    cancelledNotice: string;
 }
 interface CartSummaryProps {
     /** Integer cents. */
@@ -506,12 +499,70 @@ interface CartSummaryProps {
     shippingEnabled?: boolean;
     /** Integer cents — the final charged amount. */
     total: number;
+    /**
+     * REB-837 — a notice shown above the breakdown. `true` renders the
+     * default "pago cancelado" copy (`labels.cancelledNotice`) — the standard
+     * message for a visitor returning from a cancelled Stripe Checkout
+     * session (`useCheckoutReturn().status === 'cancelled'`). Pass any other
+     * `ReactNode` for custom content, or omit/`false` to render nothing.
+     */
+    notice?: boolean | React.ReactNode;
     labels?: Partial<CartSummaryLabels>;
     currencyCode?: string;
     locale?: string;
     className?: string;
 }
-declare function CartSummary({ subtotal, discount, discountCode, shipping, shippingEnabled, total, labels, currencyCode, locale, className, }: CartSummaryProps): react_jsx_runtime.JSX.Element;
+declare function CartSummary({ subtotal, discount, discountCode, shipping, shippingEnabled, total, notice, labels, currencyCode, locale, className, }: CartSummaryProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * `AddedToCartToast` — add-to-cart feedback toast CONTENT (REB-837). Pure
+ * presentational, no hooks.
+ *
+ * Deliberately does NOT import `@reblu/site-ui`'s `Toast` (the root entry):
+ * that barrel also re-exports `Button`, which this package's own
+ * `test/rsc-safety.test.ts` bans from the RSC-safe root entry (a Radix
+ * `Slot` copy whose server-evaluability depends on a CONSUMER's resolution —
+ * see that test's docblock). `Toast`'s small shell is reproduced inline here
+ * with `cn` from the certified-React-free `@reblu/site-ui/utils`, same
+ * pattern as every other organism in this file's sibling components. A SITE
+ * that wants `@reblu/site-ui`'s standalone `Toast` directly still can — the
+ * two are independent, not layered.
+ *
+ * This is the CONTENT to pass into whatever toaster the consuming SITE
+ * already mounts (sonner's `toast.custom((id) => <AddedToCartToast ... />,
+ * { id: `cart-add-${productId}` })` — a stable per-product id lets a repeat
+ * add UPDATE the same toast instead of stacking a new one). It never renders
+ * its own `aria-live` region: the host toaster's live region owns
+ * announcement, so adding a second one here would double-announce.
+ *
+ * `imageUrl` only renders a thumbnail when it's a real, non-blank string —
+ * an empty/whitespace value (a product with no image) renders no `<img>`
+ * rather than a broken one.
+ *
+ * `cartHref` is a plain `href` the consumer builds, rendered as a real
+ * `<a>` — never a `useRouter().push(...)` call, which breaks outside the
+ * Next.js App Router and in non-router test renders.
+ */
+type AddedToCartToastStatus = 'success' | 'error' | 'outOfStock';
+interface AddedToCartToastLabels {
+    success: string;
+    error: string;
+    outOfStock: string;
+    viewCart: string;
+}
+interface AddedToCartToastProps {
+    status?: AddedToCartToastStatus;
+    productName: string;
+    /** The resulting line quantity, e.g. from `addItem`'s outcome. Only shown when > 1. */
+    quantity?: number;
+    /** Rendered as a thumbnail ONLY when non-empty after trimming. */
+    imageUrl?: string;
+    /** "Ver carrito" link target — a real href, not a router navigation. */
+    cartHref: string;
+    labels?: Partial<AddedToCartToastLabels>;
+    className?: string;
+}
+declare function AddedToCartToast({ status, productName, quantity, imageUrl, cartHref, labels, className, }: AddedToCartToastProps): react_jsx_runtime.JSX.Element;
 
 /**
  * `CheckoutLoginPrompt` — the "login prompt hook" the checkout flow needs
@@ -594,6 +645,14 @@ interface CheckoutFormProps {
     contact: CheckoutContactValues;
     onContactChange: (values: CheckoutContactValues) => void;
     contactErrors?: CheckoutContactErrors;
+    /** Country asserted by the SITE for national phone input; omit rather than guessing. */
+    phoneRegion?: string;
+    /** Optional raw checkout API error body; only INVALID_INPUT/customerPhone marks the phone field. */
+    checkoutError?: {
+        code?: unknown;
+        error?: unknown;
+        details?: unknown;
+    } | null;
     discountCode: string;
     onDiscountCodeChange: (value: string) => void;
     onApplyDiscount: () => void;
@@ -619,18 +678,23 @@ interface CheckoutFormProps {
     locale?: string;
     className?: string;
 }
-declare function CheckoutForm({ contact, onContactChange, contactErrors, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
+declare function CheckoutForm({ contact, onContactChange, contactErrors, phoneRegion, checkoutError, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
 
 /**
- * `OrderConfirmation` — presentational order-confirmation view (REB-829).
- * Pure data + status in, RSC-safe (no hooks). The consuming SITE owns the
- * actual lookup/polling (`client.shop.order(sessionId)` via a Route Handler
- * built from `createShopOrderRoute`, retried while `'polling'` — the Stripe
- * webhook that creates the order may not have landed yet) and passes the
- * resulting `status`/`order` in.
+ * `OrderConfirmation` — presentational order-confirmation view (REB-829,
+ * extended REB-837). Pure data + status in, RSC-safe (no hooks). The
+ * consuming SITE owns the actual lookup/polling — today via
+ * `@reblu/site-next/shop`'s `useShopOrderStatus(sessionId)` hook — and
+ * passes the resulting `status`/`order` straight through.
+ *
+ * Backward compatible: the original three states (`polling`, `found`,
+ * `timeout`) keep their EXACT existing copy and behavior. REB-837 adds
+ * `useShopOrderStatus`'s native vocabulary (`loading`/`paid` are drop-in
+ * aliases for `polling`/`found`) plus five new terminal states with their
+ * own default Spanish copy, all overridable via `labels`.
  */
 type OrderConfirmationOrder = ShopOrder;
-type OrderConfirmationStatus = 'polling' | 'found' | 'timeout';
+type OrderConfirmationStatus = 'polling' | 'found' | 'timeout' | 'loading' | 'paid' | 'pending_timeout' | 'failed' | 'refunded' | 'partially_refunded' | 'not_found' | 'error';
 interface OrderConfirmationLabels {
     pollingTitle: string;
     pollingDescription: string;
@@ -642,17 +706,38 @@ interface OrderConfirmationLabels {
     totalLabel: string;
     confirmationEmailPrefix: string;
     sessionReferenceLabel: string;
+    /** REB-837 */
+    failedTitle: string;
+    failedDescription: string;
+    backToCartLabel: string;
+    refundedTitle: string;
+    refundedDescription: string;
+    partiallyRefundedTitle: string;
+    partiallyRefundedDescription: string;
+    pendingTimeoutTitle: string;
+    pendingTimeoutDescription: string;
+    recheckLabel: string;
+    notFoundTitle: string;
+    notFoundDescription: string;
+    errorTitle: string;
+    errorDescription: string;
+    /** REB-837 review fix — label for the neutral order-number-only reference shown on refunded/pending_timeout. */
+    orderReferenceLabel: string;
 }
 interface OrderConfirmationProps {
     status: OrderConfirmationStatus;
     order: OrderConfirmationOrder | null;
-    /** Shown as a fallback reference when `status === 'timeout'` and no order was found. */
+    /** Shown as a fallback reference when there is no order to display. */
     sessionId?: string;
+    /** "Volver al carrito" target, shown on `status === 'failed'`. Omit to render no link. */
+    cartHref?: string;
+    /** Called by the "Volver a comprobar" button on `pending_timeout`/`error`. Omit to render no button. */
+    onRecheck?: () => void;
     labels?: Partial<OrderConfirmationLabels>;
     currencyCode?: string;
     locale?: string;
     className?: string;
 }
-declare function OrderConfirmation({ status, order, sessionId, labels, currencyCode, locale, className, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element;
+declare function OrderConfirmation({ status, order, sessionId, cartHref, onRecheck, labels, currencyCode, locale, className, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element;
 
-export { ALLOWED_YOUTUBE_HOSTS, AddToCartButton, type AddToCartButtonLabels, type AddToCartButtonProps, CartIcon, type CartIconLabels, type CartIconProps, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_PRICE_BANDS, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };
+export { ALLOWED_YOUTUBE_HOSTS, AddedToCartToast, type AddedToCartToastLabels, type AddedToCartToastProps, type AddedToCartToastStatus, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE, DEFAULT_SHOP_ERROR_MESSAGES, DEFAULT_SHOP_PRICE_BANDS, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, getShopErrorMessage, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
+import { ShopErrorCode, PageDetail, PageListItem, ShopProductListItem, ShopFacets, ShopOrder } from '@reblu/site-contracts';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { PageDetail, PageListItem, ShopProductListItem, ShopFacets, ShopOrder } from '@reblu/site-contracts';
 import { ReactNode, FormEvent } from 'react';
 
 declare function readingTime(content: string | null | undefined): number | null;
@@ -29,6 +29,30 @@ interface ShareUrls {
 }
 declare function buildShareUrls(url: string, title: string): ShareUrls;
 
+/**
+ * Default Spanish copy for every stable `ShopErrorCode` (REB-836) the shop
+ * write endpoints (`checkout`/`validateCart`/`applyDiscount`) may return in
+ * the error body's optional `code` field — see `ApiError.body.code` in
+ * `@reblu/site-client`. A SITE overrides any subset through
+ * {@link getShopErrorMessage}'s `overrides` parameter, or ignores `code`
+ * entirely and reads `ApiError.message` as before (REB-836 is additive).
+ */
+declare const DEFAULT_SHOP_ERROR_MESSAGES: Record<ShopErrorCode, string>;
+/** Fallback copy used when `code` is missing or not recognised. */
+declare const DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE = "No se ha podido completar la operaci\u00F3n. Int\u00E9ntalo de nuevo.";
+/**
+ * Resolves the user-facing message for a checkout/validate-cart/apply-discount
+ * error `code` (REB-836) — e.g. `ApiError.body?.code` from `@reblu/site-client`.
+ *
+ * @param code - The stable error code, or `null`/`undefined` when the response
+ *   carried none (an older base-api, or a non-shop error).
+ * @param overrides - Replaces any subset of {@link DEFAULT_SHOP_ERROR_MESSAGES}
+ *   without having to restate every other code — e.g. for a non-Spanish SITE.
+ * @param fallback - Used when `code` is missing or unrecognised.
+ *   Defaults to {@link DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE}.
+ */
+declare function getShopErrorMessage(code: string | null | undefined, overrides?: Partial<Record<ShopErrorCode, string>>, fallback?: string): string;
+
 /**
  * Canonical Blog markdown → **safe HTML** pipeline for the Reblu SITE SDK.
  *
@@ -384,47 +408,6 @@ interface ShopFiltersProps {
 declare function shouldRenderShopFilters(facets: ShopFacets, active?: ShopFiltersActive): boolean;
 declare function ShopFilters({ facets, hrefs, active, onChange, priceBands, labels, currencyCode, locale, className, }: ShopFiltersProps): react_jsx_runtime.JSX.Element | null;
 
-/**
- * `AddToCartButton` — presentational add-to-cart CTA (REB-829). RSC-safe by
- * construction (same contract as `ShopFilters`'s `OptionLink`): passing
- * `onAddToCart` only makes sense from a Client Component, but the component
- * itself carries no `'use client'` directive, so a Server Component may
- * still render it WITHOUT the prop (e.g. a disabled preview state).
- */
-interface AddToCartButtonLabels {
-    add: string;
-    adding: string;
-    outOfStock: string;
-}
-interface AddToCartButtonProps {
-    onAddToCart?: () => void;
-    disabled?: boolean;
-    outOfStock?: boolean;
-    /** True while the add-to-cart call (or a navigation it triggers) is in flight. */
-    pending?: boolean;
-    labels?: Partial<AddToCartButtonLabels>;
-    className?: string;
-}
-declare function AddToCartButton({ onAddToCart, disabled, outOfStock, pending, labels, className, }: AddToCartButtonProps): react_jsx_runtime.JSX.Element;
-
-/**
- * `CartIcon` — presentational cart badge/link (REB-829). RSC-safe (plain
- * `<a href>`, no hooks) — a Server Component can render it directly with a
- * value already computed server-side; a Client Component drives `itemCount`
- * from `@reblu/site-next/cart`'s `useCart().itemCount`.
- */
-interface CartIconLabels {
-    cart: string;
-    itemsSuffix: (count: number) => string;
-}
-interface CartIconProps {
-    itemCount: number;
-    href: string;
-    labels?: Partial<CartIconLabels>;
-    className?: string;
-}
-declare function CartIcon({ itemCount, href, labels, className }: CartIconProps): react_jsx_runtime.JSX.Element;
-
 /**
  * `CartLineList` — presentational cart lines (REB-829), container/
  * presentational split: it takes `items` + optional `onQuantityChange`/
@@ -454,6 +437,8 @@ interface CartLineListLabels {
     increase: string;
     remove: string;
     unitPriceSuffix: string;
+    /** REB-837 — default copy for `notice={true}`. */
+    cancelledNotice: string;
 }
 interface CartLineListProps {
     items: CartLineItemView[];
@@ -466,12 +451,18 @@ interface CartLineListProps {
      * only renders the live region.
      */
     liveMessage?: string;
+    /**
+     * REB-837 — a notice shown above the lines. `true` renders the default
+     * "pago cancelado" copy (`labels.cancelledNotice`); pass any other
+     * `ReactNode` for custom content, or omit/`false` to render nothing.
+     */
+    notice?: boolean | React.ReactNode;
     labels?: Partial<CartLineListLabels>;
     currencyCode?: string;
     locale?: string;
     className?: string;
 }
-declare function CartLineList({ items, onQuantityChange, onRemove, liveMessage, labels, currencyCode, locale, className, }: CartLineListProps): react_jsx_runtime.JSX.Element;
+declare function CartLineList({ items, onQuantityChange, onRemove, liveMessage, notice, labels, currencyCode, locale, className, }: CartLineListProps): react_jsx_runtime.JSX.Element;
 
 /**
  * `CartSummary` — presentational price breakdown (REB-829): subtotal,
@@ -492,6 +483,8 @@ interface CartSummaryLabels {
      */
     shippingCalculated: string;
     total: string;
+    /** REB-837 — default copy for `notice={true}`. */
+    cancelledNotice: string;
 }
 interface CartSummaryProps {
     /** Integer cents. */
@@ -506,12 +499,70 @@ interface CartSummaryProps {
     shippingEnabled?: boolean;
     /** Integer cents — the final charged amount. */
     total: number;
+    /**
+     * REB-837 — a notice shown above the breakdown. `true` renders the
+     * default "pago cancelado" copy (`labels.cancelledNotice`) — the standard
+     * message for a visitor returning from a cancelled Stripe Checkout
+     * session (`useCheckoutReturn().status === 'cancelled'`). Pass any other
+     * `ReactNode` for custom content, or omit/`false` to render nothing.
+     */
+    notice?: boolean | React.ReactNode;
     labels?: Partial<CartSummaryLabels>;
     currencyCode?: string;
     locale?: string;
     className?: string;
 }
-declare function CartSummary({ subtotal, discount, discountCode, shipping, shippingEnabled, total, labels, currencyCode, locale, className, }: CartSummaryProps): react_jsx_runtime.JSX.Element;
+declare function CartSummary({ subtotal, discount, discountCode, shipping, shippingEnabled, total, notice, labels, currencyCode, locale, className, }: CartSummaryProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * `AddedToCartToast` — add-to-cart feedback toast CONTENT (REB-837). Pure
+ * presentational, no hooks.
+ *
+ * Deliberately does NOT import `@reblu/site-ui`'s `Toast` (the root entry):
+ * that barrel also re-exports `Button`, which this package's own
+ * `test/rsc-safety.test.ts` bans from the RSC-safe root entry (a Radix
+ * `Slot` copy whose server-evaluability depends on a CONSUMER's resolution —
+ * see that test's docblock). `Toast`'s small shell is reproduced inline here
+ * with `cn` from the certified-React-free `@reblu/site-ui/utils`, same
+ * pattern as every other organism in this file's sibling components. A SITE
+ * that wants `@reblu/site-ui`'s standalone `Toast` directly still can — the
+ * two are independent, not layered.
+ *
+ * This is the CONTENT to pass into whatever toaster the consuming SITE
+ * already mounts (sonner's `toast.custom((id) => <AddedToCartToast ... />,
+ * { id: `cart-add-${productId}` })` — a stable per-product id lets a repeat
+ * add UPDATE the same toast instead of stacking a new one). It never renders
+ * its own `aria-live` region: the host toaster's live region owns
+ * announcement, so adding a second one here would double-announce.
+ *
+ * `imageUrl` only renders a thumbnail when it's a real, non-blank string —
+ * an empty/whitespace value (a product with no image) renders no `<img>`
+ * rather than a broken one.
+ *
+ * `cartHref` is a plain `href` the consumer builds, rendered as a real
+ * `<a>` — never a `useRouter().push(...)` call, which breaks outside the
+ * Next.js App Router and in non-router test renders.
+ */
+type AddedToCartToastStatus = 'success' | 'error' | 'outOfStock';
+interface AddedToCartToastLabels {
+    success: string;
+    error: string;
+    outOfStock: string;
+    viewCart: string;
+}
+interface AddedToCartToastProps {
+    status?: AddedToCartToastStatus;
+    productName: string;
+    /** The resulting line quantity, e.g. from `addItem`'s outcome. Only shown when > 1. */
+    quantity?: number;
+    /** Rendered as a thumbnail ONLY when non-empty after trimming. */
+    imageUrl?: string;
+    /** "Ver carrito" link target — a real href, not a router navigation. */
+    cartHref: string;
+    labels?: Partial<AddedToCartToastLabels>;
+    className?: string;
+}
+declare function AddedToCartToast({ status, productName, quantity, imageUrl, cartHref, labels, className, }: AddedToCartToastProps): react_jsx_runtime.JSX.Element;
 
 /**
  * `CheckoutLoginPrompt` — the "login prompt hook" the checkout flow needs
@@ -594,6 +645,14 @@ interface CheckoutFormProps {
     contact: CheckoutContactValues;
     onContactChange: (values: CheckoutContactValues) => void;
     contactErrors?: CheckoutContactErrors;
+    /** Country asserted by the SITE for national phone input; omit rather than guessing. */
+    phoneRegion?: string;
+    /** Optional raw checkout API error body; only INVALID_INPUT/customerPhone marks the phone field. */
+    checkoutError?: {
+        code?: unknown;
+        error?: unknown;
+        details?: unknown;
+    } | null;
     discountCode: string;
     onDiscountCodeChange: (value: string) => void;
     onApplyDiscount: () => void;
@@ -619,18 +678,23 @@ interface CheckoutFormProps {
     locale?: string;
     className?: string;
 }
-declare function CheckoutForm({ contact, onContactChange, contactErrors, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
+declare function CheckoutForm({ contact, onContactChange, contactErrors, phoneRegion, checkoutError, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
 
 /**
- * `OrderConfirmation` — presentational order-confirmation view (REB-829).
- * Pure data + status in, RSC-safe (no hooks). The consuming SITE owns the
- * actual lookup/polling (`client.shop.order(sessionId)` via a Route Handler
- * built from `createShopOrderRoute`, retried while `'polling'` — the Stripe
- * webhook that creates the order may not have landed yet) and passes the
- * resulting `status`/`order` in.
+ * `OrderConfirmation` — presentational order-confirmation view (REB-829,
+ * extended REB-837). Pure data + status in, RSC-safe (no hooks). The
+ * consuming SITE owns the actual lookup/polling — today via
+ * `@reblu/site-next/shop`'s `useShopOrderStatus(sessionId)` hook — and
+ * passes the resulting `status`/`order` straight through.
+ *
+ * Backward compatible: the original three states (`polling`, `found`,
+ * `timeout`) keep their EXACT existing copy and behavior. REB-837 adds
+ * `useShopOrderStatus`'s native vocabulary (`loading`/`paid` are drop-in
+ * aliases for `polling`/`found`) plus five new terminal states with their
+ * own default Spanish copy, all overridable via `labels`.
  */
 type OrderConfirmationOrder = ShopOrder;
-type OrderConfirmationStatus = 'polling' | 'found' | 'timeout';
+type OrderConfirmationStatus = 'polling' | 'found' | 'timeout' | 'loading' | 'paid' | 'pending_timeout' | 'failed' | 'refunded' | 'partially_refunded' | 'not_found' | 'error';
 interface OrderConfirmationLabels {
     pollingTitle: string;
     pollingDescription: string;
@@ -642,17 +706,38 @@ interface OrderConfirmationLabels {
     totalLabel: string;
     confirmationEmailPrefix: string;
     sessionReferenceLabel: string;
+    /** REB-837 */
+    failedTitle: string;
+    failedDescription: string;
+    backToCartLabel: string;
+    refundedTitle: string;
+    refundedDescription: string;
+    partiallyRefundedTitle: string;
+    partiallyRefundedDescription: string;
+    pendingTimeoutTitle: string;
+    pendingTimeoutDescription: string;
+    recheckLabel: string;
+    notFoundTitle: string;
+    notFoundDescription: string;
+    errorTitle: string;
+    errorDescription: string;
+    /** REB-837 review fix — label for the neutral order-number-only reference shown on refunded/pending_timeout. */
+    orderReferenceLabel: string;
 }
 interface OrderConfirmationProps {
     status: OrderConfirmationStatus;
     order: OrderConfirmationOrder | null;
-    /** Shown as a fallback reference when `status === 'timeout'` and no order was found. */
+    /** Shown as a fallback reference when there is no order to display. */
     sessionId?: string;
+    /** "Volver al carrito" target, shown on `status === 'failed'`. Omit to render no link. */
+    cartHref?: string;
+    /** Called by the "Volver a comprobar" button on `pending_timeout`/`error`. Omit to render no button. */
+    onRecheck?: () => void;
     labels?: Partial<OrderConfirmationLabels>;
     currencyCode?: string;
     locale?: string;
     className?: string;
 }
-declare function OrderConfirmation({ status, order, sessionId, labels, currencyCode, locale, className, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element;
+declare function OrderConfirmation({ status, order, sessionId, cartHref, onRecheck, labels, currencyCode, locale, className, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element;
 
-export { ALLOWED_YOUTUBE_HOSTS, AddToCartButton, type AddToCartButtonLabels, type AddToCartButtonProps, CartIcon, type CartIconLabels, type CartIconProps, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_PRICE_BANDS, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };
+export { ALLOWED_YOUTUBE_HOSTS, AddedToCartToast, type AddedToCartToastLabels, type AddedToCartToastProps, type AddedToCartToastStatus, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE, DEFAULT_SHOP_ERROR_MESSAGES, DEFAULT_SHOP_PRICE_BANDS, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, getShopErrorMessage, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };