@reblu/site-blocks 0.28.0 → 0.30.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @reblu/site-blocks
 
+## 0.30.0
+
+### Minor Changes
+
+- 3b096d4: `CartLineList` gains an optional `lineIncludes` render prop (REB-1208): it adds a collapsed «Qué incluye» disclosure under a line (`labels.includesSummary`). New drop-in `CartLineIncludes` (term/description list plus optional `note`) and `bundleComponentsToIncludes`, which maps `ShopProductDetail.bundleComponents` to its entries. Omitting the prop renders the cart exactly as before.
+
+## 0.29.0
+
+### Minor Changes
+
+- cdab121: Single-step checkout drop-ins (REB-1197 / REB-1198), all rendering tenant configuration from the site API: `CheckoutDeliveryChoice` (home delivery with the address form, cost and estimate, or free pickup at the tenant's points), `CheckoutQuoteSummary` (lines, subtotal, discount, delivery, tax rows, total from `ShopQuote`, plus why a code was not applied or why the order cannot be paid), `CheckoutTermsAcceptance` (the required, unticked terms box with the link to the full document) and `CheckoutPayAction` («Continuar al pago» with the amount notice under it). Body helpers: `defaultCheckoutFulfillment`, `quoteRequiresDelivery`, `toCheckoutFulfillmentFields(value, address, requiresDelivery?)` (no address for a cart that ships nothing), `toCheckoutTermsFields`.
+
 ## 0.28.0
 
 ### Minor Changes

package/README.md

@@ -327,7 +327,8 @@ for the wiring steps and a full example app).
 | `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?`, `lineMessage?`                                    | Yes                                                                               |
+| `CartLineList`        | `.`        | `items`, `onQuantityChange?`, `onRemove?`, `liveMessage?`, `notice?`, `lineMessage?`, `lineIncludes?`                   | Yes                                                                               |
+| `CartLineIncludes`    | `.`        | `entries`, `note?`                                                                                                      | Yes                                                                               |
 | `CartAdjustmentsNotice` | `.`      | `removed?`, `quantityChanges?`, `priceChanges?`, `labels?`                                                              | Yes                                                                               |
 | `CartSummary`         | `.`        | `subtotal`, `discount?`, `autoDiscount?`, `shipping?`, `shippingEnabled?`, `total`, `notice?`                           | Yes                                                                               |
 | `CheckoutLoginPrompt` | `.`        | `open`, `email`, `onEmailChange`, `onClose`, `onSubmitEmail`, `onContinueAsGuest`                                       | Yes (renders `null` when `open` is false)                                         |
@@ -530,6 +531,36 @@ function). `currencyCode`/`locale` format the prices.
 `CartLineList`'s `lineMessage={(item) => …}` renders a message under a line,
 e.g. `validation.getLineError(item.productId, item.variantId)?.message`.
 
+### «Qué incluye» per line — `lineIncludes` + `CartLineIncludes` (REB-1208)
+
+`CartLineList`'s `lineIncludes={(item) => …}` adds a collapsed
+`<details>` under a line whose summary reads «Qué incluye»
+(`labels.includesSummary`). Return `null`/`undefined` for lines with nothing
+to show; omit the prop and the cart renders exactly as before.
+
+`CartLineIncludes` is the drop-in body: a term/description list plus an
+optional `note`. Build its entries from the product's own data — nothing is
+fixed per product type. For a bundle, `bundleComponentsToIncludes` maps
+`ShopProductDetail.bundleComponents` to name / `x{quantity}` rows:
+
+```tsx
+import { CartLineIncludes, CartLineList, bundleComponentsToIncludes } from '@reblu/site-blocks'
+
+// `detailsById`: the SITE's ShopProductDetail per productId (already fetched for the ficha).
+<CartLineList
+  items={items}
+  lineIncludes={(item) => {
+    const product = detailsById[item.productId]
+    if (!product) return null
+    const entries = [
+      ...bundleComponentsToIncludes(product.bundleComponents),
+      // …plus any other `{ label, value }` row built from the product's own data.
+    ]
+    return entries.length > 0 ? <CartLineIncludes entries={entries} /> : null
+  }}
+/>
+```
+
 ### `OrderConfirmation` states (REB-837)
 
 `status` accepts `@reblu/site-next/shop`'s `useShopOrderStatus` hook result
@@ -585,6 +616,148 @@ import { OrderInvoiceLink } from '@reblu/site-blocks'
 // «Descargar la factura FAC-2026-0010» + «Te pediremos que inicies sesión para abrirla.»
 ```
 
+### The single-step checkout (REB-1197 / REB-1198)
+
+One last web step before Stripe: what is being bought, how it is delivered,
+the contact data, the summary with shipping and taxes, the terms box and
+«Continuar al pago» with the amount under it. Every text and rule is tenant
+configuration edited in nexus (`ShopConfig.delivery`, `ShopConfig.checkout`,
+`ShopQuote`); the blocks render what the API returns and carry no tenant copy.
+
+| Block | Reads | Renders |
+| ----- | ----- | ------- |
+| `CheckoutDeliveryChoice` | `config.delivery`, `config.checkout` | Home delivery (cost, estimate, address form) or free pickup (points with address, hours, ready-in text). Only the methods the tenant offers; nothing for a cart that ships nothing. |
+| `CheckoutQuoteSummary` | `ShopQuote` | Lines (kind, `qty × unit`), subtotal, discount, delivery row, tax rows, total, «Impuestos incluidos», remaining for free shipping, delivery term; `role=status` for an unusable code, `role=alert` when the order cannot be paid. |
+| `CheckoutTermsAcceptance` | `config.checkout` | The required, unticked box with `{terms}` as the link to the full document and `{tenant}` filled. Nothing when no terms are published. |
+| `CheckoutPayAction` | `config.checkout.continueToPaymentLabel`, `quote.payNotice` | The submit button and the notice with the amount under it (`text-sm`, the button's description). |
+
+Mount `createShopQuoteRoute()` at `app/api/shop/quote/route.ts` and
+`createShopCheckoutRoute()` at `app/api/shop/checkout/route.ts`
+(`@reblu/site-next/shop-route-handlers`), then:
+
+```tsx
+'use client'
+import { useState } from 'react'
+import { useCart } from '@reblu/site-next/cart'
+import { useShopQuote } from '@reblu/site-next/shop'
+import type { ShopConfig } from '@reblu/site-contracts'
+import {
+  CheckoutDeliveryChoice,
+  CheckoutPayAction,
+  CheckoutQuoteSummary,
+  CheckoutTermsAcceptance,
+  EMPTY_CHECKOUT_ADDRESS,
+  defaultCheckoutFulfillment,
+  getShopErrorMessage,
+  quoteRequiresDelivery,
+  toCheckoutFulfillmentFields,
+  toCheckoutTermsFields,
+} from '@reblu/site-blocks'
+
+export function SingleStepCheckout({ config }: { config: ShopConfig }) {
+  const { items } = useCart()
+  const [fulfillment, setFulfillment] = useState(() => defaultCheckoutFulfillment(config.delivery))
+  const [address, setAddress] = useState(EMPTY_CHECKOUT_ADDRESS)
+  const [acceptsTerms, setAcceptsTerms] = useState(false)
+  const lines = items.map(({ productId, variantId, quantity }) => ({ productId, variantId, quantity }))
+  const { quote, status, error, refresh } = useShopQuote(
+    lines.length ? { items: lines, fulfillment: toCheckoutFulfillmentFields(fulfillment, address).fulfillment } : null,
+  )
+  // A cart that ships nothing hides the choice: send no address (blank = 400).
+  const delivery = toCheckoutFulfillmentFields(fulfillment, address, quoteRequiresDelivery(quote))
+
+  async function onSubmit(event: React.FormEvent) {
+    event.preventDefault()
+    // Pay only against a total the buyer saw, and a fresh one.
+    const fresh = await refresh()
+    if (!fresh?.canCheckout) return
+    const res = await fetch('/api/shop/checkout', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        items: lines,
+        customerName, customerEmail, // your contact fields (or CheckoutForm)
+        ...delivery,
+        ...toCheckoutTermsFields(config.checkout, acceptsTerms),
+      }),
+    })
+    const json = await res.json()
+    if (res.ok) window.location.assign(json.data.url)
+    else showError(getShopErrorMessage(json.code)) // TERMS_VERSION_CHANGED: reload the config
+  }
+
+  return (
+    <form onSubmit={onSubmit} className='grid gap-8 lg:grid-cols-3'>
+      <div className='space-y-8 lg:col-span-2'>
+        {/* contact fields, FullInvoiceFields, discount code… */}
+        {config.delivery && config.checkout ? (
+          <CheckoutDeliveryChoice
+            delivery={config.delivery}
+            copy={config.checkout}
+            value={fulfillment}
+            onChange={setFulfillment}
+            address={address}
+            onAddressChange={setAddress}
+            quote={quote}
+            requiresDelivery={quoteRequiresDelivery(quote)}
+          />
+        ) : null}
+      </div>
+      <aside className='space-y-5'>
+        {quote ? <CheckoutQuoteSummary quote={quote} heading='Resumen' /> : null}
+        {status === 'error' ? (
+          <p role='alert'>
+            {error?.message ?? 'No hemos podido calcular el total.'}{' '}
+            <button type='button' onClick={() => void refresh()}>Reintentar</button>
+          </p>
+        ) : null}
+        {config.checkout ? (
+          <>
+            <CheckoutTermsAcceptance
+              copy={config.checkout}
+              termsHref='/terms-and-conditions'
+              checked={acceptsTerms}
+              onCheckedChange={setAcceptsTerms}
+            />
+            <CheckoutPayAction
+              label={config.checkout.continueToPaymentLabel}
+              notice={quote?.payNotice}
+              // No quote (loading or error) = no total shown = no payment.
+              disabled={status !== 'ready' || !quote?.canCheckout}
+            />
+          </>
+        ) : null}
+      </aside>
+    </form>
+  )
+}
+```
+
+Notes:
+
+- `quote.total` is exactly what Stripe charges for the same body: base-api
+  prices the quote and the checkout with one function. Show it, never a sum
+  of your own.
+- Never let the buyer pay without a ready quote: while `useShopQuote` is
+  loading or failed, disable `CheckoutPayAction`, show the error with a retry
+  (`refresh()`), and `await refresh()` in `onSubmit` so the charged total is
+  the one on screen.
+- Send the discount code in the quote input too. A code that cannot be used
+  comes back in `quote.discountError` and is left out of the total; drop it
+  from your state when `discountError.code === 'DISCOUNT_LIMIT_REACHED'`.
+- `toCheckoutFulfillmentFields(value, address, quoteRequiresDelivery(quote))`:
+  for a cart with nothing to ship (third argument `false`, or no choice) it
+  sends only `fulfillment: { type: 'SHIPPING' }` and never the blank address
+  of the hidden block (the server refuses a blank address with 400): the server records no delivery
+  for such a cart, and the request stays on the current contract (REB-1227
+  removes the old shape).
+- The full-invoice texts are the tenant's too: pass
+  `labels={{ toggle: config.checkout.fullInvoiceCheckboxLabel, underCapNotice: config.checkout.fullInvoiceHelpText }}`
+  to `FullInvoiceFields`.
+- Ids default to `checkout-delivery`, `checkout-terms` and `checkout-pay`
+  (one checkout per page); pass `id` to change them. The three blocks hold no
+  state and use no hooks, so they ship from the RSC-safe root.
+
 ### The full-invoice request — `FullInvoiceFields` (REB-73)
 
 A full invoice needs the buyer's identifier — a Spanish NIF/NIE/CIF, or for a