@reblu/site-blocks 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+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 } from '@reblu/site-contracts';
+import { ReactNode, FormEvent } from 'react';
 
 declare function readingTime(content: string | null | undefined): number | null;
 
@@ -28,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.
  *
@@ -383,4 +408,328 @@ 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;
 
-export { ALLOWED_YOUTUBE_HOSTS, DEFAULT_SHOP_PRICE_BANDS, MarkdownRenderer, type MarkdownRendererProps, 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 };
+/**
+ * `CartLineList` — presentational cart lines (REB-829), container/
+ * presentational split: it takes `items` + optional `onQuantityChange`/
+ * `onRemove` callbacks, never fetches or owns cart state itself. The
+ * consuming SITE wires these to `@reblu/site-next/cart`'s `useCart()`.
+ *
+ * RSC-safe by construction (same `OptionLink` contract as `ShopFilters`):
+ * the quantity stepper/remove buttons only do anything when `onQuantityChange`/
+ * `onRemove` are supplied from a Client Component — omit them from a Server
+ * Component to render a read-only summary instead.
+ */
+interface CartLineItemView {
+    productId: string;
+    variantId?: string | null;
+    name: string;
+    variantName?: string;
+    /** Integer cents. */
+    unitPrice: number;
+    quantity: number;
+    imageUrl?: string;
+    /** `null`/`undefined` = untracked stock — never clamps the stepper's max. */
+    maxStock?: number | null;
+}
+interface CartLineListLabels {
+    quantityLabel: string;
+    decrease: string;
+    increase: string;
+    remove: string;
+    unitPriceSuffix: string;
+    /** REB-837 — default copy for `notice={true}`. */
+    cancelledNotice: string;
+}
+interface CartLineListProps {
+    items: CartLineItemView[];
+    onQuantityChange?: (productId: string, variantId: string | null | undefined, quantity: number) => void;
+    onRemove?: (productId: string, variantId: string | null | undefined) => void;
+    /**
+     * A visually-hidden `aria-live="polite"` announcement (e.g. "Cantidad
+     * actualizada", "Producto eliminado del carrito") — the consuming SITE
+     * decides WHEN to set it (after a successful mutation), this component
+     * 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, notice, labels, currencyCode, locale, className, }: CartLineListProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * `CartSummary` — presentational price breakdown (REB-829): subtotal,
+ * optional discount, optional shipping (sourced from `ShopConfig` by the
+ * consuming SITE — this component only renders what it's given), and total.
+ * Pure data in, RSC-safe (no hooks, no callbacks).
+ */
+interface CartSummaryLabels {
+    subtotal: string;
+    discountPrefix: string;
+    shipping: string;
+    freeShipping: string;
+    /**
+     * Shown when `shipping` is `null`/`undefined` (unknown yet) — REB-829
+     * review finding: this is NOT the same state as `0` (confirmed free).
+     * Claiming "free shipping" for an amount the SITE simply hasn't computed
+     * yet understates the real total and is reversed at checkout.
+     */
+    shippingCalculated: string;
+    total: string;
+    /** REB-837 — default copy for `notice={true}`. */
+    cancelledNotice: string;
+}
+interface CartSummaryProps {
+    /** Integer cents. */
+    subtotal: number;
+    /** Integer cents, positive. Omit (or `0`) to hide the discount line. */
+    discount?: number;
+    /** The applied discount code, shown next to the discount amount. */
+    discountCode?: string;
+    /** Integer cents. Only rendered when `shippingEnabled` is true. */
+    shipping?: number | null;
+    /** Whether this tenant's shop even has shipping cost — hides the line entirely when false/omitted. */
+    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, 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
+ * (REB-829): a guest-checkout identification dialog offering "continue with
+ * this email" (so the SITE can check for an existing account via
+ * `client.shop.checkEmail`) or "continue as guest" outright. Fully
+ * controlled/presentational — it performs NO fetch itself (unlike
+ * demo-site's original `CheckoutLoginModal`, which called
+ * `/api/shop/check-email` internally); the consuming SITE owns `email`
+ * state and the `checkEmail` call, and drives `checking`/`error` from its
+ * own result.
+ */
+interface CheckoutLoginPromptLabels {
+    title: string;
+    description: string;
+    emailLabel: string;
+    emailPlaceholder: string;
+    continueWithEmail: string;
+    checking: string;
+    continueAsGuest: string;
+    close: string;
+}
+interface CheckoutLoginPromptProps {
+    open: boolean;
+    email: string;
+    onEmailChange: (value: string) => void;
+    onClose: () => void;
+    /** Called when the visitor confirms a (valid-looking) email. */
+    onSubmitEmail: () => void;
+    onContinueAsGuest: () => void;
+    checking?: boolean;
+    error?: string | null;
+    labels?: Partial<CheckoutLoginPromptLabels>;
+    className?: string;
+}
+declare function CheckoutLoginPrompt({ open, email, onEmailChange, onClose, onSubmitEmail, onContinueAsGuest, checking, error, labels, className, }: CheckoutLoginPromptProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * `CheckoutForm` — presentational guest-checkout form (REB-829): contact
+ * fields, a discount-code section, an optional `loginPrompt` slot, and the
+ * submit CTA. Fully controlled — `values`/callbacks only, no internal state,
+ * no fetch, no react-hook-form/zod dependency (keeping this package's
+ * dependency surface minimal); the consuming SITE owns validation and wires
+ * its own `onSubmit`.
+ *
+ * Scope note: shipping/billing address collection is intentionally OUT of
+ * this component — those field sets vary by tenant shop config (shipping
+ * enabled/disabled, invoicing requirements) far more than the guest-email +
+ * discount-code flow the issue named. A SITE that needs them renders its own
+ * fields via the `children` slot, rendered between the contact and discount
+ * sections.
+ */
+interface CheckoutContactValues {
+    name: string;
+    email: string;
+    phone?: string;
+}
+type CheckoutContactErrors = Partial<Record<keyof CheckoutContactValues, string>>;
+interface CheckoutAppliedDiscount {
+    code: string;
+    amount: number;
+}
+interface CheckoutFormLabels {
+    contactTitle: string;
+    nameLabel: string;
+    namePlaceholder: string;
+    emailLabel: string;
+    emailPlaceholder: string;
+    phoneLabel: string;
+    discountTitle: string;
+    discountPlaceholder: string;
+    applyDiscount: string;
+    applyingDiscount: string;
+    removeDiscount: string;
+    discountAppliedSuffix: (formattedAmount: string) => string;
+    submit: string;
+    submitting: string;
+}
+interface CheckoutFormProps {
+    contact: CheckoutContactValues;
+    onContactChange: (values: CheckoutContactValues) => void;
+    contactErrors?: CheckoutContactErrors;
+    discountCode: string;
+    onDiscountCodeChange: (value: string) => void;
+    onApplyDiscount: () => void;
+    onRemoveDiscount: () => void;
+    appliedDiscount?: CheckoutAppliedDiscount | null;
+    discountApplying?: boolean;
+    discountError?: string | null;
+    /**
+     * Rendered OUTSIDE the `<form>`, immediately before it — e.g. the
+     * `CheckoutLoginPrompt` dialog. It must never render inside the `<form>`:
+     * an Enter keypress in one of ITS inputs would otherwise submit checkout
+     * (REB-829 review finding — see `handleDiscountCodeKeyDown` below for the
+     * same defect class).
+     */
+    loginPrompt?: ReactNode;
+    /** Rendered between the contact and discount sections — e.g. shipping/billing fields. */
+    children?: ReactNode;
+    submitting?: boolean;
+    submitDisabled?: boolean;
+    onSubmit: (event: FormEvent<HTMLFormElement>) => void;
+    labels?: Partial<CheckoutFormLabels>;
+    currencyCode?: string;
+    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;
+
+/**
+ * `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' | 'loading' | 'paid' | 'pending_timeout' | 'failed' | 'refunded' | 'partially_refunded' | 'not_found' | 'error';
+interface OrderConfirmationLabels {
+    pollingTitle: string;
+    pollingDescription: string;
+    foundTitle: string;
+    foundDescription: string;
+    timeoutTitle: string;
+    timeoutDescription: string;
+    orderNumberLabel: string;
+    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 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, cartHref, onRecheck, labels, currencyCode, locale, className, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element;
+
+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 };