@reblu/site-blocks 0.27.0 → 0.29.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @reblu/site-blocks
 
+## 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
+
+- 275adaf: REB-1201: `ArbitrationBadge` drop-in renders the tenant's consumer-arbitration distinctive in the footer — logo at `h-16`, `alt` with the adhesion number («… N.º de adhesión CA00000»), the number as visible text, optional link in a new window. `TrustBadges` knows the new type (heading «Arbitraje de consumo») but leaves it out of its default groups, so a footer with both never shows it twice; opt in with `types`. Any badge with an adhesion number gets it in its `alt`.
+
+### Patch Changes
+
+- Updated dependencies [275adaf]
+  - @reblu/site-contracts@1.28.0
+
 ## 0.27.0
 
 ### Minor Changes

package/README.md

@@ -35,6 +35,7 @@ colour on the red background. See `docs/theming/theming.md`.
 | `PageBlocks`, `FaqAccordion`                                                                                  | `.`        | Registry-block renderer (`PageDetail.blocks`) and native `<details>` FAQ. Server Components. See "Page blocks" below.        |
 | `ProductTrustItems`, `DEFAULT_TRUST_ICONS`                                                                    | `.`        | Store-wide trust messages from `ShopConfig.productTrustItems`. Server Component. See "Product trust items" below.            |
 | `TrustBadges`, `DEFAULT_TRUST_BADGE_HEADINGS`                                                                 | `.`        | The tenant's trust badges from `client.trustBadges.list()`, grouped by type. Server Component. See "Trust badges" below.     |
+| `ArbitrationBadge`                                                                                            | `.`        | The consumer-arbitration distinctive with its adhesion number, for the footer. Server Component. See "Consumer arbitration badge" below. |
 | `buildFaqPageJsonLd`, `collectFaqItems`                                                                       | `./seo`    | schema.org `FAQPage` structured data. Directive-free (also on `.`). See "Page blocks" 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`.                                                                       |
@@ -584,6 +585,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
@@ -755,7 +898,11 @@ export async function Footer() {
 - `types` picks which groups render and in what order, e.g. only the funding
   logos: `<TrustBadges badges={badges} types={['SUBVENTION']} />`. To fetch
   only one type, `client.trustBadges.list({ type: 'SUBVENTION' })`.
-- A logo is an `<img>` with `alt` = badge name, rendered only when its URL is
+- `CONSUMER_ARBITRATION` is not in the default groups — render it with
+  `ArbitrationBadge` (below). Opt in with `types` to group it here; its heading
+  is «Arbitraje de consumo».
+- A logo is an `<img>` with `alt` = badge name (plus «N.º de adhesión …» when
+  the badge has an adhesion number), rendered only when its URL is
   http(s) or root-relative (`/logos/x.svg`); any other scheme (`javascript:`,
   `data:`, `//host`) is dropped and the badge shows its name as text, like a
   badge without a logo. A badge `url` (http/https only) opens in a new window
@@ -781,6 +928,46 @@ export async function Footer() {
   `listClassName` and `logoClassName` are layout/sizing slots and still merge
   with `cn`.
 
+## Consumer arbitration badge — `ArbitrationBadge` (REB-1201)
+
+A tenant adhered to the consumer arbitration system shows the official
+distinctive in the footer, visible and accessible, with its adhesion number. In
+nexus › Trust badges create a badge of type «Arbitraje de consumo» with the
+official logo, the «Número de adhesión» (required for that type) and an
+optional link. The API serves it like any other badge, with `adhesionNumber`.
+
+```tsx
+import { ArbitrationBadge, TrustBadges } from '@reblu/site-blocks'
+
+export async function Footer() {
+  const { data: badges } = await client.trustBadges.list().catch(() => ({ data: [] }))
+  return (
+    <footer>
+      {/* … */}
+      <TrustBadges badges={badges} headingLevel={2} />
+      <ArbitrationBadge badges={badges} />
+    </footer>
+  )
+}
+```
+
+- Feed it the whole list: only `CONSUMER_ARBITRATION` badges render, and
+  `TrustBadges` leaves that type out by default, so it never shows twice. To
+  fetch only it, `client.trustBadges.list({ type: 'CONSUMER_ARBITRATION' })`.
+- The logo is an `<img>` at `h-16` (not a tiny icon) with `alt` = «{name}.
+  N.º de adhesión {number}». The number is also shown as visible text under the
+  logo, `aria-hidden` there because the `alt` already says it. Without a usable
+  logo (same http(s)/root-relative rule as `TrustBadges`) the name and number
+  are plain text.
+- `numberLabel` changes «N.º de adhesión» (alt and caption); `showNumber={false}`
+  drops the visible caption, the `alt` keeps the number.
+- A http(s) `url` opens in a new window with `rel="noopener noreferrer"` and a
+  visually hidden `newWindowLabel`.
+- Nothing renders without a named consumer-arbitration badge.
+- Styling hooks: `className` (the `<ul>`), `logoClassName` (merged with
+  `h-16 w-auto object-contain`, e.g. `brightness-0 invert` on a dark footer),
+  `numberClassName`.
+
 ## `ParentPage` (formerly `Specialty`)
 
 `ParentPage` renders a page that groups other pages: the hero and content