@reblu/site-blocks 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @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

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,7 +209,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?`                                                    | 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                                                                               |
@@ -352,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)
 
@@ -699,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