@reblu/site-blocks 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # @reblu/site-blocks
 
+## 0.14.0
+
+### Minor Changes
+
+- fff0bf5: REB-981: `CartAdjustmentsNotice` — presentational notice for what cart validation changed (removed lines, clamped quantities, changed prices), fed by `@reblu/site-next/cart`'s `useCartValidation()`. `CartLineList` gains an optional `lineMessage` prop to render a message under a line (e.g. its validation error). README replaces the `errors[0].message` guidance.
+- b7667d4: Add `CourseDescription` — the drop-in for the rich-text course `description` from `client.academy.bySlug()` (REB-879). Server Component: sanitised Markdown (headings, GFM tables, images) through the `MarkdownRenderer` pipeline; renders nothing, not even its heading, when the description is null, blank or emptied by the sanitiser; an optional `heading` makes it a labelled `<section>` with the description's own headings demoted under it. README: snippet for the course page.
+- b7667d4: Add `markdownToPlainText(markdown, { maxLength })` (root and `./seo` entries): rich-text Markdown → the plain text a reader sees, for meta/OG descriptions and excerpts. It runs the same sanitised pipeline as `MarkdownRenderer`, drops images, and cuts at a word boundary with `…`. README: how to render a rich-text course description and build its meta description (REB-879).
+
+## 0.13.0
+
+### Minor Changes
+
+- 614e826: New drop-in `FullInvoiceFields` (REB-73): the shop checkout's «¿Quieres
+  factura completa?» opt-in with the buyer's identifier (Spanish NIF/NIE/CIF,
+  EU VAT id, passport or ID document, with its issuing country), name and
+  billing address — required, without a toggle, when the cart total is over
+  `ShopConfig.simplifiedInvoiceCapCents`. Controlled and hook-free; with
+  `isOverSimplifiedInvoiceCap` and `toCheckoutInvoiceFields`, which builds the
+  `wantsFullInvoice`/`billing` checkout body fields.
+- 614e826: Shop checkout: no full-invoice opt-in on a shop that issues no invoices (REB-73).
+  - `ShopErrorCode` gains `FULL_INVOICE_UNAVAILABLE` (HTTP 422,
+    `details.field: 'wantsFullInvoice'`): `wantsFullInvoice: true` sent to a shop
+    whose invoicing is off (`ShopConfig.simplifiedInvoiceCapCents` is `null`) is
+    refused before any payment instead of succeeding without an invoice. Clients
+    that never send the opt-in are unaffected. The union is additive: a SITE
+    with an exhaustive `switch` over `ShopErrorCode` (or a
+    `Record<ShopErrorCode, …>`) must add the new member when it upgrades.
+  - `@reblu/site-blocks`: new `shopIssuesInvoices(config)`; `FullInvoiceFields`
+    takes `issuesInvoices` (default `true`) and renders nothing when it is
+    `false`, and `toCheckoutInvoiceFields(value, overCap, issuesInvoices)`
+    returns no opt-in and no billing block then. Default Spanish copy for the
+    new code in `getShopErrorMessage`.
+
+- 614e826: Shop: the order's invoice and the simplified-invoice cap (REB-73).
+  - `ShopOrder` gains the optional `invoice: { number, url } | null`
+    (`ShopOrderInvoice`): once the sale invoice is issued, its number and the
+    shop's authenticated client-portal route that serves it — never a signed
+    URL, so the link does not expire; the buyer signs in to open it.
+  - `ShopConfig` gains `simplifiedInvoiceCapCents` (cents, never above the legal
+    300000; `null` while the shop issues no invoices): above it, checkout needs
+    the buyer's identifier, name and billing address.
+  - `@reblu/site-blocks`: new drop-in `OrderInvoiceLink`, which
+    `OrderConfirmation` now renders under a confirmed order (labels
+    `invoiceLinkLabel`/`invoiceSignInHint`), and default Spanish copy for the
+    `BILLING_DATA_REQUIRED`/`INVOICING_NOT_READY` checkout codes in
+    `getShopErrorMessage`.
+
+### Patch Changes
+
+- Updated dependencies [614e826]
+- Updated dependencies [614e826]
+- Updated dependencies [614e826]
+  - @reblu/site-contracts@1.15.0
+
 ## 0.12.1
 
 ### Patch Changes

package/README.md

@@ -8,16 +8,26 @@ their own. Every color, radius and font comes from CSS design tokens (OKLCH)
 that each tenant injects through its `site-theme.css`. The same package renders
 a different-looking site for every tenant, with zero forks.
 
+**Required theme tokens.** Besides the usual shadcn tokens, the consuming
+theme must define `--destructive-foreground` (text colour on `--destructive`,
+≥ 4.5:1 contrast) and map it in `@theme inline` as
+`--color-destructive-foreground: var(--destructive-foreground);`. Tailwind v4
+emits no CSS for `text-destructive-foreground` without it, so error states
+(e.g. `AddToCartButton`'s `error` status) would render with inherited text
+colour on the red background. See `docs/theming/theming.md`.
+
 ## What's inside
 
 | Export                                                                                                        | Entry      | Purpose                                                                                                                      |
 | ------------------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `readingTime`, `formatPrice`, `buildShareUrls`, `markdownToSafeHtml`                                          | `.`        | Pure, framework-agnostic helpers (RSC-safe).                                                                                 |
+| `markdownToPlainText`                                                                                         | `.`        | Markdown → plain text for meta/OG descriptions (also on `./seo`). Same sanitiser as `MarkdownRenderer`.                      |
 | `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. |
+| `CourseDescription`                                                                                           | `.`        | Drop-in for the rich-text course `description` (`client.academy.bySlug()`). Server Component. See "Rich-text descriptions".  |
 | `Treatment`, `ParentPage`, `ProfileCard`, `ProductCard`                                                       | `.`        | Presentational organisms over the SITE API contracts. RSC-safe. `Specialty`: deprecated alias, see below.                    |
 | `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.                                            |
+| `CartLineList`, `CartSummary`, `CartAdjustmentsNotice`, `AddedToCartToast`, `CheckoutLoginPrompt`, `CheckoutForm`, `OrderConfirmation` | `.`        | Cart & checkout organisms. RSC-safe by construction. See "Cart & checkout" below.                                            |
 | `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.            |
 | `buildFaqPageJsonLd`, `collectFaqItems`                                                                       | `./seo`    | schema.org `FAQPage` structured data. Directive-free (also on `.`). See "Page blocks" below.                                 |
@@ -199,11 +209,14 @@ 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?`                                                    | Yes                                                                               |
+| `CartLineList`        | `.`        | `items`, `onQuantityChange?`, `onRemove?`, `liveMessage?`, `notice?`, `lineMessage?`                                    | Yes                                                                               |
+| `CartAdjustmentsNotice` | `.`      | `removed?`, `quantityChanges?`, `priceChanges?`, `labels?`                                                              | 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                                                                               |
+| `OrderInvoiceLink`    | `.`        | `invoice` (`order.invoice`), `labels?`                                                                                  | Yes (renders `null` without an invoice)                                           |
+| `FullInvoiceFields`   | `.`        | `value`, `onChange`, `overCap`, `errors?`, `countries?`, `labels?`                                                      | Yes (controlled, no hooks)                                                        |
 
 **REB-837 breaking move**: `AddToCartButton` and `CartIcon` now carry real
 internal state (the confirmed/error timer, the bump-on-add guard) and ship
@@ -350,12 +363,36 @@ 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(...)`
-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`).
+Do not surface validate-cart's rejection as the first
+`ShopCartValidationError.message`: it does not say which line failed, and a
+deleted product only comes back as «Producto desconocido». Use
+`@reblu/site-next/cart`'s `useCartValidation()` (REB-981) on the cart and
+checkout pages: it removes unavailable lines, clamps quantities and refreshes
+prices in the store, and its result feeds `CartAdjustmentsNotice` and
+`CartLineList`'s `lineMessage` — see "Cart adjustments" below and that
+package's README.
+
+### Cart adjustments — `CartAdjustmentsNotice` (REB-981)
+
+Presentational: tells the visitor what cart validation changed. Every prop is
+optional and renders nothing when empty, so it can stay mounted.
+
+```tsx
+<CartAdjustmentsNotice
+  removed={validation.removed}           // [{ name, variantName? }]
+  quantityChanges={validation.quantityChanges} // [{ name, variantName?, to }]
+  priceChanges={validation.priceChanges}       // [{ name, variantName?, from, to }] cents
+/>
+```
+
+Default copy: «Hemos quitado del carrito: X, ya no está disponible.» (plural
+«…ya no están disponibles.»), «Hemos ajustado la cantidad de X a N por el
+stock disponible.», «El precio de X ha cambiado: antes A, ahora B.». Override
+any of them with `labels={{ removed, quantityChanged, priceChanged }}` (each a
+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`.
 
 ### `OrderConfirmation` states (REB-837)
 
@@ -392,6 +429,78 @@ Every title/description is overridable via `labels` (see
 "`useShopOrderStatus` — the order-confirmation flow" for the full wiring
 recipe.
 
+### The order's invoice — `OrderInvoiceLink` (REB-73)
+
+Once the sale invoice is issued, the order lookup (`client.shop.order(sessionId)`,
+or `useShopOrderStatus`) carries `order.invoice: { number, url }` — `null`
+while there is none. `url` is the shop's **authenticated** client-portal route,
+never a signed URL: the buyer signs in to open the PDF, so the link never
+expires and is safe to show anywhere. `OrderConfirmation` already renders it
+under a confirmed order (`paid`/`found`/`timeout`), with its copy overridable
+through `labels.invoiceLinkLabel` (`{number}` is replaced) and
+`labels.invoiceSignInHint`. To place it elsewhere — an account page, a custom
+confirmation — drop it in:
+
+```tsx
+import { OrderInvoiceLink } from '@reblu/site-blocks'
+
+// order: ShopOrder from client.shop.order(sessionId) / useShopOrderStatus
+;<OrderInvoiceLink invoice={order.invoice} />
+// «Descargar la factura FAC-2026-0010» + «Te pediremos que inicies sesión para abrirla.»
+```
+
+### The full-invoice request — `FullInvoiceFields` (REB-73)
+
+A full invoice needs the buyer's identifier — a Spanish NIF/NIE/CIF, or for a
+foreign buyer an EU VAT id, a passport or an ID document of their country,
+with the country that issued it — plus their name and billing address;
+without it the invoice is simplified. Over `ShopConfig.simplifiedInvoiceCapCents`
+a full invoice is the only legal one, so checkout refuses the sale without
+them (`BILLING_DATA_REQUIRED`). Drop the fields into your checkout form and
+send what they produce:
+
+```tsx
+'use client'
+import { useState } from 'react'
+import {
+  EMPTY_FULL_INVOICE_VALUE,
+  FullInvoiceFields,
+  isOverSimplifiedInvoiceCap,
+  shopIssuesInvoices,
+  toCheckoutInvoiceFields,
+} from '@reblu/site-blocks'
+
+const [invoice, setInvoice] = useState(EMPTY_FULL_INVOICE_VALUE)
+const issuesInvoices = shopIssuesInvoices(shopConfig)
+const overCap = isOverSimplifiedInvoiceCap(cartTotalCents, shopConfig.simplifiedInvoiceCapCents)
+
+<FullInvoiceFields
+  value={invoice}
+  onChange={setInvoice}
+  overCap={overCap}
+  issuesInvoices={issuesInvoices}
+/>
+
+// in onSubmit:
+await client.shop.checkout({
+  ...checkoutBody,
+  ...toCheckoutInvoiceFields(invoice, overCap, issuesInvoices),
+})
+```
+
+A shop that issues no invoices (`ShopConfig.simplifiedInvoiceCapCents` is
+`null`) offers no full invoice: pass `issuesInvoices={shopIssuesInvoices(config)}`
+and the block renders nothing, and give the same flag to
+`toCheckoutInvoiceFields(invoice, overCap, issuesInvoices)` so the body never
+carries the opt-in.
+
+Checkout refusals tied to invoicing come with their own default copy in
+`getShopErrorMessage`: `BILLING_DATA_REQUIRED` (422 — a full invoice, or a
+total over `ShopConfig.simplifiedInvoiceCapCents`, needs the buyer's
+NIF/NIE or ID document, name and billing address), `INVOICING_NOT_READY`
+(503) and `FULL_INVOICE_UNAVAILABLE` (422 — `wantsFullInvoice: true` sent to a
+shop that issues no invoices).
+
 ## Product trust items
 
 `ProductTrustItems` renders the store-wide trust messages (shipping, returns,
@@ -625,6 +734,57 @@ called on the server (REB-846). `test/seo-entry.test.ts` guards this on the
 emitted `dist`. The caller serialises; `@reblu/site-next`'s `<JsonLd>` escapes
 the `</script>` boundary.
 
+### Rich-text descriptions on a page (`CourseDescription` + `markdownToPlainText`)
+
+Some API fields are rich-text Markdown written in nexus with the shared editor
+(headings, GFM tables, images) — for example a course `description` from
+`client.academy.bySlug()` (REB-879). Never print them as plain text and never
+pass them to `dangerouslySetInnerHTML`. On the course page, drop in
+`CourseDescription`; for the meta description use `markdownToPlainText`, never a
+slice of the raw Markdown (that leaks `##`, table pipes and `![…](…)` into search
+snippets):
+
+```tsx
+import { CourseDescription } from '@reblu/site-blocks'
+import { markdownToPlainText } from '@reblu/site-blocks/seo'
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const course = await client.academy.bySlug((await params).slug)
+  const description =
+    course.shortDescription || markdownToPlainText(course.description, { maxLength: 160 })
+  return { description: description || undefined }
+}
+
+export default async function CoursePage({ params }: Props) {
+  const course = await client.academy.bySlug((await params).slug)
+  return (
+    <article>
+      <h1>{course.title}</h1>
+      {/* The heading is your own copy, in your SITE's language. */}
+      <CourseDescription description={course.description} heading='Sobre el curso' />
+    </article>
+  )
+}
+```
+
+`CourseDescription` (Server Component, RSC-safe):
+
+- runs the Markdown through the same sanitised pipeline as `MarkdownRenderer`
+  (`<script>`, event handlers, `javascript:` links and non-YouTube iframes are
+  dropped);
+- renders **nothing**, not even the heading, for `null`, blank, or content the
+  sanitiser leaves empty, so a page never shows an empty "About the course";
+- with `heading`, renders a `<section aria-labelledby>` and demotes the
+  description's own headings under it (`headingLevel`, default `2`; override with
+  `headingOffset`; `headingId` when the page renders it twice);
+- styling hooks: `className`, `headingClassName`, `contentClassName`, and
+  `data-slot='course-description'` on the outer element.
+
+For any other rich-text Markdown field, `MarkdownRenderer` is the generic
+renderer (`headingOffset` demotes its headings under yours).
+`markdownToPlainText` drops images and anything the sanitiser strips, and cuts
+at a word boundary with `…` within `maxLength`.
+
 ## Security boundaries
 
 Two sinks, two different helpers, in two different packages — do not reach for