@reblu/site-blocks 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @reblu/site-blocks
 
+## 0.8.0
+
+### Minor Changes
+
+- c40434a: Add a distributable controlled phone input and E.164 normalization. Preserve and validate the additive checkout `details.field` in typed API errors so CheckoutForm can mark the rejected phone while retaining generic error fallback.
+
+### Patch Changes
+
+- Updated dependencies [c40434a]
+  - @reblu/site-ui@0.7.0
+
+## 0.7.0
+
+### Minor Changes
+
+- 21feec3: REB-836 — checkout hardening: Stripe redirect-origin check + stable checkout error codes.
+  - `@reblu/site-contracts`: re-exports the new `ShopErrorCode` type (type-only, `z.infer` from base-api's `shopErrorCodeSchema`, no Zod reaches the published `.d.ts`) — nine values: `STOCK_CHANGED`, `PRICE_CHANGED`, `PRODUCT_UNAVAILABLE`, `DISCOUNT_INVALID`, `SHIPPING_UNAVAILABLE`, `INVALID_INPUT`, `STORE_DISABLED`, `PAYMENT_PROVIDER_ERROR`, and `INTERNAL_ERROR` (added in a native-review follow-up to distinguish an unexpected, non-Stripe failure — reported as HTTP 500 — from a Stripe failure, reported as 400 or, for a transient/5xx Stripe error, 503). This is the shop write endpoints' (`checkout`/`validateCart`/`applyDiscount`) new optional error-body `code` field.
+  - `@reblu/site-client`: (1) `shop.checkout()` now validates the returned Stripe Checkout URL is `https:` on an allowed host (default `checkout.stripe.com`, injectable via the new `RebluClientConfig.checkoutRedirectHosts`) before ever returning it, throwing the new `UnsafeCheckoutRedirectError` otherwise — exported alongside `isSafeCheckoutRedirectUrl` and `DEFAULT_CHECKOUT_REDIRECT_HOSTS`. (2) `ApiError.body` (`ApiErrorBody`/`ApiErrorDetails`) gains the optional `code` and `details.productIds` fields.
+  - `@reblu/site-next`: (1) `createShopCheckoutRoute` re-checks the Checkout URL server-side before responding to the browser (502 `unsafe_redirect` when it fails the check) — new `ShopCheckoutRouteOptions.allowedRedirectHosts`/`unsafeRedirectMessage`. (2) Native-review follow-up: that same route now strips `content-encoding`/`content-length`/`transfer-encoding` from its re-serialized response instead of forwarding them from the upstream proxy response, fixing a "browser tries to gunzip already-decoded JSON" failure mode.
+  - `@reblu/site-blocks`: adds `DEFAULT_SHOP_ERROR_MESSAGES` (a default Spanish message per `ShopErrorCode`, including `INTERNAL_ERROR`'s "Ha ocurrido un error inesperado. Inténtalo de nuevo en unos minutos.") and `getShopErrorMessage(code, overrides?, fallback?)`, which a SITE can override per code without restating the others.
+
+  All new fields/exports are additive and optional (REB-788) — a SITE that ignores `code`/`checkoutRedirectHosts` keeps working unchanged. The base-api side of this change (the `ShopErrorCode` schema itself, `checkout.service.ts`'s Stripe-vs-internal error classification, and `apiError()`'s options-object signature) is unpublished — it ships with the next base-api deploy, not through these changesets.
+
+- b86a16b: Add-to-cart feedback (REB-837). `AddToCartButton` gets a built-in confirmed
+  state («Añadido ✓» for `successDurationMs`, default 1500ms, overridable
+  label), an `aria-live="polite"` announcement, a controlled `error` prop for
+  out-of-stock/max-quantity, `onAdded`/`onError` callbacks carrying the opaque
+  `item`, and a non-reentrancy guard (pointer AND keyboard) during the success
+  window. `CartIcon` gets an opt-in count "bump" (`bumpOnAdd`) that is
+  hydration-safe — pass `useCart().hydrated` through, or it bumps on every
+  page load with a non-empty persisted cart — and respects
+  `prefers-reduced-motion`. New `AddedToCartToast` organism (product name,
+  thumbnail, "Ver carrito" link, status copy) over `@reblu/site-ui`'s `Toast`
+  pattern — content only, no `aria-live` of its own (the host toaster owns
+  announcement).
+
+  **Breaking**: `AddToCartButton` and `CartIcon` now carry genuine internal
+  state and move from the RSC-safe root `.` entry to `./client` —
+  `import { AddToCartButton, CartIcon } from '@reblu/site-blocks/client'`.
+
+  README "Cart & checkout" documents the recommended pattern: a toast plus the
+  `CartIcon` badge, never an auto-opening cart drawer.
+
+- b86a16b: `CartSummary`/`CartLineList` accept a `notice` prop (REB-837): `true` renders
+  the default «Pago cancelado: tu carrito sigue aquí» banner (overridable via
+  `labels.cancelledNotice`), any other node renders custom content, omitted/
+  `false` renders nothing — pairs with `@reblu/site-next/shop`'s
+  `useCheckoutReturn()`.
+- b86a16b: `OrderConfirmation` renders `@reblu/site-next`'s `useShopOrderStatus` states
+  directly (REB-837): `loading`/`paid` are drop-in aliases for the pre-existing
+  `polling`/`found`, and `pending_timeout`/`failed`/`refunded`/
+  `partially_refunded`/`not_found`/`error` get their own default Spanish copy,
+  all overridable via `labels`. New optional `cartHref` (a "Volver al
+  carrito" link on `failed`) and `onRecheck` (a "Volver a comprobar" button on
+  `pending_timeout`/`error`) props. Backward compatible: the original
+  `'polling' | 'found' | 'timeout'` API and copy are unchanged.
+- b86a16b: Gentle AI review follow-up (REB-837):
+  - `AddToCartButton`'s `onAddToCart` may now return the add's outcome
+    (`AddToCartOutcome | void | Promise<...>`) — a `'refused'` result always
+    shows the error state and calls `onError`, instead of deciding purely from
+    the `error` prop captured at render time (which showed "Añadido ✓" for a
+    refused add whenever the caller never flipped `error` on). Non-reentrant
+    while an async `onAddToCart` is pending, not just during the success window.
+  - `CartIcon`'s bump could get stuck `true` forever (a remove shortly after an
+    add cancelled the pending timeout without resetting the flag) — fixed.
+    Omitting `hydrated` entirely now means "no hydration guard, bump on every
+    increase" instead of silently disabling every bump.
+  - `OrderConfirmation` no longer renders the full "paid" order summary
+    (items, total, confirmation-email line) for `failed`/`pending_timeout`/
+    `refunded`/`partially_refunded`/`not_found`/`error` — only `paid`/`found`
+    and the legacy `timeout` state keep it. `refunded`/`partially_refunded`/
+    `pending_timeout` get a neutral order-number-only reference instead.
+  - `CartSummary` without a `notice` keeps its root as a bare `<dl>` (no extra
+    wrapper `<div>`) — the wrapper only appears when a notice actually renders.
+
+### Patch Changes
+
+- Updated dependencies [21feec3]
+- Updated dependencies [b86a16b]
+  - @reblu/site-contracts@1.6.0
+  - @reblu/site-ui@0.6.0
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -10,17 +10,18 @@ a different-looking site for every tenant, with zero forks.
 
 ## What's inside
 
-| Export | Entry | Purpose |
-| ------ | ----- | ------- |
-| `readingTime`, `formatPrice`, `buildShareUrls`, `markdownToSafeHtml` | `.` | Pure, framework-agnostic helpers (RSC-safe). |
-| `sanitizeHtml` | `.` | Sanitises an HTML string before `dangerouslySetInnerHTML` — the **HTML boundary**. See "Security boundaries" below. |
-| `MarkdownRenderer` | `.` | Canonical Blog renderer: `marked` → **hast-util-sanitize** (XSS) → component map, with a YouTube-domain allowlist. RSC-safe. |
-| `Treatment`, `Specialty`, `ProfileCard`, `ProductCard` | `.` | Presentational organisms over the SITE API contracts. RSC-safe. |
-| `ShopFilters` | `.` | Plug-and-play shop filter chrome over `GET /api/site/shop/facets`. RSC-safe. See "Shop filters" below. |
-| `AddToCartButton`, `CartIcon`, `CartLineList`, `CartSummary`, `CheckoutLoginPrompt`, `CheckoutForm`, `OrderConfirmation` | `.` | Cart & checkout organisms. RSC-safe by construction. See "Cart & checkout" below. |
-| `useCollection` | `./client` | Headless filterable/sortable/paginated collection hook (facets, category, tag, search). Serves both page and blog indexes. |
-| `Collection` | `./client` | Token-driven presentational grid over `useCollection`. |
-| `ShareButtons` | `./client` | Social share (X / LinkedIn / WhatsApp / copy). |
+| Export                                                                                                        | Entry      | Purpose                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `readingTime`, `formatPrice`, `buildShareUrls`, `markdownToSafeHtml`                                          | `.`        | Pure, framework-agnostic helpers (RSC-safe).                                                                                 |
+| `sanitizeHtml`                                                                                                | `.`        | Sanitises an HTML string before `dangerouslySetInnerHTML` — the **HTML boundary**. See "Security boundaries" below.          |
+| `MarkdownRenderer`                                                                                            | `.`        | Canonical Blog renderer: `marked` → **hast-util-sanitize** (XSS) → component map, with a YouTube-domain allowlist. RSC-safe. |
+| `Treatment`, `Specialty`, `ProfileCard`, `ProductCard`                                                        | `.`        | Presentational organisms over the SITE API contracts. RSC-safe.                                                              |
+| `ShopFilters`                                                                                                 | `.`        | Plug-and-play shop filter chrome over `GET /api/site/shop/facets`. RSC-safe. See "Shop filters" below.                       |
+| `CartLineList`, `CartSummary`, `AddedToCartToast`, `CheckoutLoginPrompt`, `CheckoutForm`, `OrderConfirmation` | `.`        | Cart & checkout organisms. RSC-safe by construction. See "Cart & checkout" below.                                            |
+| `useCollection`                                                                                               | `./client` | Headless filterable/sortable/paginated collection hook (facets, category, tag, search). Serves both page and blog indexes.   |
+| `Collection`                                                                                                  | `./client` | Token-driven presentational grid over `useCollection`.                                                                       |
+| `ShareButtons`                                                                                                | `./client` | Social share (X / LinkedIn / WhatsApp / copy).                                                                               |
+| `AddToCartButton`, `CartIcon`                                                                                 | `./client` | Add-to-cart feedback (REB-837) — **moved here from `.`**, see below.                                                         |
 
 ## Boundary
 
@@ -43,7 +44,7 @@ Calle Mayor 1
 ```
 
 renders as one paragraph reading `Calle Mayor 1 28001 Madrid`. This is standard
-CommonMark — a lone newline is a *soft* break, i.e. whitespace — and it is what
+CommonMark — a lone newline is a _soft_ break, i.e. whitespace — and it is what
 this renderer has done since it replaced the interim, non-standard one that
 emitted a `<br>` for every newline. **Text written under the old behaviour reads
 differently now**, so addresses, signature blocks and enumerated clauses typed on
@@ -51,11 +52,11 @@ consecutive lines are worth re-reading.
 
 To force a visible break, use any of:
 
-| Want | Write |
-| ---- | ----- |
-| A new paragraph | A blank line between the two lines |
-| A hard break inside one paragraph | Two spaces at the end of the first line |
-| A hard break, visibly | A trailing `\` at the end of the first line |
+| Want                              | Write                                       |
+| --------------------------------- | ------------------------------------------- |
+| A new paragraph                   | A blank line between the two lines          |
+| A hard break inside one paragraph | Two spaces at the end of the first line     |
+| A hard break, visibly             | A trailing `\` at the end of the first line |
 
 ### `hidden` hides a block — it does not withhold it
 
@@ -184,39 +185,157 @@ never stranding the visitor with no way back).
 
 ## Cart & checkout
 
-Seven organisms over the cart/checkout flow (REB-829), all presentational —
-data + optional callbacks in, no fetching, no cart/zustand dependency of
-their own. Wire them to `@reblu/site-next/cart`'s `useCart()` and the
-`./shop-route-handlers` Route Handlers (see that package's README for the
-wiring steps and a full example app).
-
-| Component | Props it needs | RSC-safe without callbacks? |
-| --------- | --------------- | ---------------------------- |
-| `AddToCartButton` | `onAddToCart?`, `disabled?`, `outOfStock?`, `pending?` | Yes |
-| `CartIcon` | `itemCount`, `href` | Yes |
-| `CartLineList` | `items`, `onQuantityChange?`, `onRemove?`, `liveMessage?` | Yes |
-| `CartSummary` | `subtotal`, `discount?`, `shipping?`, `shippingEnabled?`, `total` | Yes |
-| `CheckoutLoginPrompt` | `open`, `email`, `onEmailChange`, `onClose`, `onSubmitEmail`, `onContinueAsGuest` | Yes (renders `null` when `open` is false) |
-| `CheckoutForm` | `contact`, `onContactChange`, `discountCode`, `onDiscountCodeChange`, `onApplyDiscount`, `onRemoveDiscount`, `onSubmit` | Yes |
-| `OrderConfirmation` | `status` (`'polling' \| 'found' \| 'timeout'`), `order` | Yes |
-
-Same RSC-safety contract as `ShopFilters`'s `OptionLink`: none of these
-components carry `'use client'` themselves — a Server Component may render
-any of them read-only (omit the callback props), and a Client Component
-wires the callbacks to real state/mutations. All labels default to
-Spanish-neutral copy and are overridable via each component's `labels` prop.
+Organisms over the cart/checkout flow (REB-829, extended REB-837), all
+presentational — data + optional callbacks in, no fetching, no cart/zustand
+dependency of their own. Wire them to `@reblu/site-next/cart`'s `useCart()`
+and the `./shop-route-handlers` Route Handlers (see that package's README
+for the wiring steps and a full example app).
+
+| Component             | Entry      | Props it needs                                                                                                          | RSC-safe without callbacks?                                                       |
+| --------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| `AddToCartButton`     | `./client` | `onAddToCart?`, `disabled?`, `outOfStock?`, `pending?`, `error?`, `item?`, `successDurationMs?`, `onAdded?`, `onError?` | No — carries a built-in confirmed/error timer (`useState`/`useEffect`), see below |
+| `CartIcon`            | `./client` | `itemCount`, `href`, `hydrated?`, `bumpOnAdd?`                                                                          | No — the bump animation needs state, see below                                    |
+| `AddedToCartToast`    | `.`        | `productName`, `cartHref`, `status?`, `quantity?`, `imageUrl?`                                                          | Yes                                                                               |
+| `CartLineList`        | `.`        | `items`, `onQuantityChange?`, `onRemove?`, `liveMessage?`, `notice?`                                                    | Yes                                                                               |
+| `CartSummary`         | `.`        | `subtotal`, `discount?`, `shipping?`, `shippingEnabled?`, `total`, `notice?`                                            | Yes                                                                               |
+| `CheckoutLoginPrompt` | `.`        | `open`, `email`, `onEmailChange`, `onClose`, `onSubmitEmail`, `onContinueAsGuest`                                       | Yes (renders `null` when `open` is false)                                         |
+| `CheckoutForm`        | `.`        | `contact`, `onContactChange`, `discountCode`, `onDiscountCodeChange`, `onApplyDiscount`, `onRemoveDiscount`, `onSubmit` | Yes                                                                               |
+| `OrderConfirmation`   | `.`        | `status`, `order`, `cartHref?`, `onRecheck?`                                                                            | Yes                                                                               |
+
+**REB-837 breaking move**: `AddToCartButton` and `CartIcon` now carry real
+internal state (the confirmed/error timer, the bump-on-add guard) and ship
+from `@reblu/site-blocks/client` instead of the root `.` entry. Update the
+import:
+
+```diff
+-import { AddToCartButton, CartIcon } from '@reblu/site-blocks'
++import { AddToCartButton, CartIcon } from '@reblu/site-blocks/client'
+```
+
+Every other organism above keeps the same RSC-safety contract as
+`ShopFilters`'s `OptionLink`: none of them carry `'use client'` themselves —
+a Server Component may render any of them read-only (omit the callback
+props), and a Client Component wires the callbacks to real state/mutations.
+All labels default to Spanish-neutral copy and are overridable via each
+component's `labels` prop.
+
+### Add-to-cart feedback (REB-837): the recommended pattern
+
+The recommended pattern is **a toast plus the `CartIcon` badge — never an
+auto-opening cart drawer**. An auto-opening drawer steals focus and
+interrupts a visitor who is still browsing; a toast + badge confirms the add
+without moving them anywhere.
+
+```tsx
+'use client'
+import { AddToCartButton, AddedToCartToast } from '@reblu/site-blocks/client'
+import { useCart } from '@reblu/site-next/cart'
+import { toast } from 'sonner' // or any toaster — see site-ui's Toast primitive
+
+function AddToCart({ product }: { product: Product }) {
+  const { addItem } = useCart()
+
+  return (
+    <AddToCartButton
+      item={product}
+      onAddToCart={(item) => {
+        const outcome = addItem({ productId: item.id, /* … */ quantity: 1 })
+        // Stable id per product: a repeat add on the SAME product UPDATES
+        // the existing toast (shows the new resulting quantity) instead of
+        // stacking a second one.
+        toast.custom(
+          () => (
+            <AddedToCartToast
+              productName={product.name}
+              imageUrl={product.imageUrl}
+              quantity={outcome.quantity}
+              status={outcome.status === 'refused' ? 'outOfStock' : 'success'}
+              cartHref='/shop/cart'
+            />
+          ),
+          { id: `cart-add-${product.id}` },
+        )
+      }}
+    />
+  )
+}
+```
+
+`AddToCartButton`'s own confirmed/error state (`«Añadido ✓»` for
+`successDurationMs` — default 1500ms, then reverts; `aria-live="polite"`
+so the label change is announced) is independent of whatever toast you
+show — the button never knows about the toast, and the toast never knows
+about the button. Both read `addItem`'s return value
+(`{ status: 'added' | 'clamped' | 'refused', quantity }`, REB-837) to decide
+their own copy.
+
+`AddedToCartToast` renders NO `aria-live` region of its own — your toaster
+(sonner or otherwise) already owns one; adding a second would double-announce.
+
+`CartIcon`'s bump only fires on a REAL increase, never on the rehydration
+jump (`itemCount` going `0 -> N` the instant `CartProvider` finishes
+rehydrating a non-empty persisted cart — see `@reblu/site-next`'s README "The
+hydration gotcha"). Always pass `hydrated` through when you set `bumpOnAdd`:
+
+```tsx
+const { itemCount, hydrated } = useCart()
+<CartIcon itemCount={itemCount} href='/shop/cart' hydrated={hydrated} bumpOnAdd />
+```
+
+`hydrated` is a guard you opt INTO by passing it, not a value `CartIcon`
+otherwise assumes `false`: omitting it entirely disables the rehydration
+guard and bumps on every `itemCount` increase — only reach for that when
+`itemCount` has no client-side rehydration step at all (e.g. computed
+server-side and never changing after mount). Passing `hydrated={false}`
+explicitly is different: it keeps the guard active and means "not hydrated
+yet", so no bump fires until a later render passes `hydrated={true}`.
+
+The animation itself is `motion-safe:`-gated (Tailwind), so it's inert under
+`prefers-reduced-motion: reduce`.
 
 `CartLineList`'s `liveMessage` prop renders inside a visually-hidden
 `aria-live="polite"` region — the consuming SITE sets it (e.g. "Cantidad
 actualizada", "Producto eliminado") after a successful mutation; the
 component only renders the live region, it never decides when to announce.
 
+`CartLineList`/`CartSummary`'s `notice` prop (REB-837) renders a
+`role="status"` banner above the content: `true` shows the default «Pago
+cancelado: tu carrito sigue aquí» copy (overridable via
+`labels.cancelledNotice`), any other `ReactNode` renders custom content,
+`false`/omitted renders nothing. Pair it with `@reblu/site-next/shop`'s
+`useCheckoutReturn()`:
+
+```tsx
+const { status } = useCheckoutReturn()
+<CartSummary {...summaryProps} notice={status === 'cancelled'} />
+```
+
 `CheckoutForm` intentionally does NOT collect shipping/billing addresses —
 those field sets vary by tenant shop config far more than the guest-email +
 discount-code flow. Render them via `CheckoutForm`'s `children` slot
 (rendered between the contact and discount sections) if your shop has
 shipping enabled.
 
+For phone normalization, pass `phoneRegion` from the tenant's configured country:
+the controlled `contact.phone` callback receives E.164 when valid and raw text
+when incomplete. On a checkout API rejection pass the parsed response body to
+`checkoutError` (not the transport error's prefixed `message`). Only an
+`INVALID_INPUT` body with `details.field === 'customerPhone'` and a nonblank
+`error` marks the phone field. Unknown/missing/malformed details show the
+existing generic code message instead; other code paths are unchanged. Clear
+the response on edit/retry in the consuming SITE to remove a stale server error.
+
+```tsx
+<CheckoutForm {...checkoutProps} phoneRegion='ES' checkoutError={checkoutErrorBody} />
+```
+
+Pass `error.body` after catching `error instanceof ApiError` from
+`@reblu/site-client`. Its `body` parser now types and validates the optional
+string `details.field`; never parse the transport-prefixed `error.message`.
+For malformed bodies (which parse as `undefined`), pass a generic body such as
+`error.body ?? { error: 'Checkout failed' }` to show the fallback banner.
+An external SITE (including Dermamedicin) must adopt this wiring separately.
+
 `validate-cart`'s rejection path (out-of-stock, price-changed, empty cart)
 surfaces through `CheckoutForm`'s own error-display conventions: pass the
 first `ShopCartValidationError.message` from `client.shop.validateCart(...)`
@@ -224,15 +343,50 @@ as a toast/banner in your page (the component itself has no cart-wide error
 slot — it only owns contact/discount field-level errors via `contactErrors`/
 `discountError`).
 
+### `OrderConfirmation` states (REB-837)
+
+`status` accepts `@reblu/site-next/shop`'s `useShopOrderStatus` hook result
+directly — `loading`/`paid` are drop-in aliases for the original
+`polling`/`found` states, so existing callers on the pre-REB-837 3-state API
+(`'polling' | 'found' | 'timeout'`) are completely unaffected.
+
+| `status`              | Default copy                                    | Order details shown                                  | Extra UI                                              |
+| --------------------- | ----------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| `loading` / `polling` | «Confirmando tu pedido…»                        | —                                                    | —                                                     |
+| `paid` / `found`      | «¡Pedido confirmado!»                           | Full summary (items, total, confirmation-email line) | —                                                     |
+| `failed`              | «El pago no se ha completado»                   | None                                                 | "Volver al carrito" link when `cartHref` is given     |
+| `refunded`            | «Este pedido ha sido reembolsado»               | Order number only (neutral reference)                | —                                                     |
+| `partially_refunded`  | «…reembolsado parcialmente»                     | Order number only                                    | —                                                     |
+| `pending_timeout`     | «Pedido recibido. Estamos confirmando el pago…» | Order number only                                    | "Volver a comprobar" button when `onRecheck` is given |
+| `not_found`           | «No encontramos ningún pedido»                  | None                                                 | —                                                     |
+| `error`               | «Ha ocurrido un error»                          | None                                                 | "Volver a comprobar" button when `onRecheck` is given |
+| `timeout` (legacy)    | «Pago recibido» — UNCHANGED                     | Full summary (unchanged pre-REB-837 behavior)        | —                                                     |
+
+**REB-837 review fix**: the full order summary (items, total, "te hemos
+enviado un email de confirmación a…") renders ONLY for `paid`/`found` and
+the legacy `timeout` state. `useShopOrderStatus` sets `order` from whatever
+the last response returned regardless of `paymentStatus` — without this
+gate, a `failed`/`refunded`/`pending_timeout` order would render the exact
+same "confirmed purchase" summary a successful one gets. `refunded`/
+`partially_refunded`/`pending_timeout` instead get a neutral, number-only
+reference (`labels.orderReferenceLabel`); `failed`/`not_found`/`error`
+render no order details at all, even if an `order` object happens to be
+present.
+
+Every title/description is overridable via `labels` (see
+`OrderConfirmationLabels`). See `@reblu/site-next`'s README
+"`useShopOrderStatus` — the order-confirmation flow" for the full wiring
+recipe.
+
 ## Security boundaries
 
 Two sinks, two different helpers, in two different packages — do not reach for
 one where the other belongs:
 
-| Sink | Helper | Package |
-| ---- | ------ | ------- |
-| HTML rendered via `dangerouslySetInnerHTML` | `sanitizeHtml` (strip/allowlist sanitiser) | `@reblu/site-blocks` (here) |
-| `<script type="application/ld+json">` body | `jsonLdScriptContent` / `<JsonLd>` (escaper) | [`@reblu/site-next/json-ld`](../site-next#structured-data-json-ld) |
+| Sink                                        | Helper                                       | Package                                                            |
+| ------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------ |
+| HTML rendered via `dangerouslySetInnerHTML` | `sanitizeHtml` (strip/allowlist sanitiser)   | `@reblu/site-blocks` (here)                                        |
+| `<script type="application/ld+json">` body  | `jsonLdScriptContent` / `<JsonLd>` (escaper) | [`@reblu/site-next/json-ld`](../site-next#structured-data-json-ld) |
 
 A `<script>` body is HTML's **raw-text** context: the parser ends it on the
 first `</script` byte sequence regardless of whether that sequence sits inside

package/dist/client.cjs

@@ -31,6 +31,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
+  AddToCartButton: () => AddToCartButton,
+  CartIcon: () => CartIcon,
   Collection: () => Collection,
   ShareButtons: () => ShareButtons,
   useCollection: () => useCollection
@@ -326,8 +328,204 @@ function ShareButtons({ url, title, className, labels }) {
     /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { role: "status", "aria-live": "polite", className: "sr-only", children: copied ? t.copyStatus : "" })
   ] });
 }
+
+// src/components/add-to-cart-button.tsx
+var import_react2 = require("react");
+var import_utils3 = require("@reblu/site-ui/utils");
+var import_jsx_runtime3 = require("react/jsx-runtime");
+var DEFAULT_LABELS3 = {
+  add: "A\xF1adir al carrito",
+  adding: "A\xF1adiendo\u2026",
+  outOfStock: "Agotado",
+  added: "A\xF1adido \u2713",
+  error: "No se pudo a\xF1adir"
+};
+function AddToCartButton({
+  onAddToCart,
+  disabled,
+  outOfStock,
+  pending,
+  error,
+  item,
+  successDurationMs = 1500,
+  onAdded,
+  onError,
+  labels,
+  className
+}) {
+  const t = { ...DEFAULT_LABELS3, ...labels };
+  const [status, setStatus] = (0, import_react2.useState)("idle");
+  const timeoutRef = (0, import_react2.useRef)(null);
+  const prevErrorRef = (0, import_react2.useRef)(error);
+  const inSuccessWindowRef = (0, import_react2.useRef)(false);
+  const resolvingRef = (0, import_react2.useRef)(false);
+  const mountedRef = (0, import_react2.useRef)(true);
+  const [resolving, setResolving] = (0, import_react2.useState)(false);
+  const clearTimer = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+  };
+  (0, import_react2.useEffect)(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+      clearTimer();
+    };
+  }, []);
+  const triggerSuccess = () => {
+    inSuccessWindowRef.current = true;
+    clearTimer();
+    setStatus("success");
+    onAdded?.(item);
+    timeoutRef.current = setTimeout(() => {
+      inSuccessWindowRef.current = false;
+      setStatus("idle");
+    }, successDurationMs);
+  };
+  const triggerError = (errorValue = true) => {
+    clearTimer();
+    inSuccessWindowRef.current = false;
+    setStatus("error");
+    onError?.(item, errorValue);
+    timeoutRef.current = setTimeout(() => setStatus("idle"), successDurationMs);
+  };
+  (0, import_react2.useEffect)(() => {
+    if (error && !prevErrorRef.current) {
+      triggerError(error);
+    }
+    prevErrorRef.current = error;
+  }, [error]);
+  const applyOutcome = (result) => {
+    if (!mountedRef.current || outOfStock) return;
+    if (result?.status === "refused") {
+      triggerError(true);
+      return;
+    }
+    if (error) return;
+    triggerSuccess();
+  };
+  const handleClick = () => {
+    if (inSuccessWindowRef.current || resolvingRef.current) return;
+    const result = onAddToCart?.(item);
+    if (result && typeof result.then === "function") {
+      resolvingRef.current = true;
+      setResolving(true);
+      result.then((resolved) => {
+        resolvingRef.current = false;
+        if (mountedRef.current) setResolving(false);
+        applyOutcome(resolved);
+      }).catch(() => {
+        resolvingRef.current = false;
+        if (mountedRef.current) setResolving(false);
+        applyOutcome({ status: "refused" });
+      });
+      return;
+    }
+    applyOutcome(result);
+  };
+  const isDisabled = Boolean(disabled || outOfStock || pending || status === "success" || resolving);
+  const label = outOfStock ? t.outOfStock : status === "success" ? t.added : status === "error" ? typeof error === "string" ? error : t.error : pending || resolving ? t.adding : t.add;
+  return /* @__PURE__ */ (0, import_jsx_runtime3.jsx)(
+    "button",
+    {
+      type: "button",
+      onClick: handleClick,
+      disabled: isDisabled,
+      "aria-disabled": isDisabled,
+      "aria-live": "polite",
+      "data-slot": "add-to-cart-button",
+      "data-status": status,
+      className: (0, import_utils3.cn)(
+        "inline-flex items-center justify-center gap-2 rounded-xl px-4 py-2.5 text-sm font-semibold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        isDisabled ? "cursor-not-allowed bg-muted text-muted-foreground" : "bg-primary text-primary-foreground hover:bg-primary/90",
+        status === "error" && "bg-destructive text-destructive-foreground",
+        className
+      ),
+      children: label
+    }
+  );
+}
+
+// src/components/cart-icon.tsx
+var import_react3 = require("react");
+var import_utils4 = require("@reblu/site-ui/utils");
+var import_jsx_runtime4 = require("react/jsx-runtime");
+var DEFAULT_LABELS4 = {
+  cart: "Carrito",
+  itemsSuffix: (count) => `${count} art\xEDculo${count === 1 ? "" : "s"}`
+};
+var BUMP_DURATION_MS = 400;
+function CartIcon({ itemCount, href, hydrated, bumpOnAdd, labels, className }) {
+  const t = { ...DEFAULT_LABELS4, ...labels };
+  const ariaLabel = itemCount > 0 ? `${t.cart} (${t.itemsSuffix(itemCount)})` : t.cart;
+  const displayCount = itemCount > 99 ? "99+" : String(itemCount);
+  const [bumping, setBumping] = (0, import_react3.useState)(false);
+  const prevCountRef = (0, import_react3.useRef)(itemCount);
+  const prevHydratedRef = (0, import_react3.useRef)(hydrated);
+  (0, import_react3.useEffect)(() => {
+    const hydrationGuardSatisfied = hydrated === void 0 || prevHydratedRef.current === true;
+    const shouldBump = Boolean(bumpOnAdd) && itemCount > prevCountRef.current && hydrationGuardSatisfied;
+    prevCountRef.current = itemCount;
+    prevHydratedRef.current = hydrated;
+    if (!shouldBump) {
+      setBumping(false);
+      return;
+    }
+    setBumping(true);
+    const id = setTimeout(() => setBumping(false), BUMP_DURATION_MS);
+    return () => clearTimeout(id);
+  }, [itemCount, hydrated, bumpOnAdd]);
+  return /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
+    "a",
+    {
+      href,
+      "aria-label": ariaLabel,
+      "data-slot": "cart-icon",
+      "data-bumping": bumping || void 0,
+      className: (0, import_utils4.cn)(
+        "relative inline-flex items-center justify-center rounded-lg p-2 text-foreground/80 transition-colors hover:bg-muted/60 hover:text-foreground",
+        className
+      ),
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime4.jsxs)(
+          "svg",
+          {
+            viewBox: "0 0 24 24",
+            fill: "none",
+            stroke: "currentColor",
+            strokeWidth: 2,
+            strokeLinecap: "round",
+            strokeLinejoin: "round",
+            className: (0, import_utils4.cn)("h-5 w-5", bumping && "motion-safe:scale-125 motion-safe:transition-transform motion-safe:duration-300"),
+            "aria-hidden": "true",
+            children: [
+              /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("circle", { cx: "9", cy: "21", r: "1" }),
+              /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("circle", { cx: "20", cy: "21", r: "1" }),
+              /* @__PURE__ */ (0, import_jsx_runtime4.jsx)("path", { d: "M1 1h4l2.68 13.39a2 2 0 0 0 2 1.61h9.72a2 2 0 0 0 2-1.61L23 6H6" })
+            ]
+          }
+        ),
+        itemCount > 0 && /* @__PURE__ */ (0, import_jsx_runtime4.jsx)(
+          "span",
+          {
+            "aria-hidden": "true",
+            className: (0, import_utils4.cn)(
+              "absolute -top-0.5 -right-0.5 flex h-[18px] min-w-[18px] items-center justify-center rounded-full bg-primary px-1 text-[10px] font-bold leading-none tabular-nums text-primary-foreground",
+              bumping && "motion-safe:scale-125 motion-safe:transition-transform motion-safe:duration-300"
+            ),
+            children: displayCount
+          }
+        )
+      ]
+    }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AddToCartButton,
+  CartIcon,
   Collection,
   ShareButtons,
   useCollection