@reblu/site-blocks 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @reblu/site-blocks
 
+## 0.22.0
+
+### Minor Changes
+
+- 01d0e15: Academy catalogue filters by price and instructor (REB-547). `@reblu/site-contracts` exports `AcademyCourseListQuery`, the documented query of `GET /api/site/academy/courses`. `@reblu/site-client` adds `academy.instructors()` (instructors of published courses, for the filter), and `AcademyCourseListParams` is now that query type, so the SDK cannot drift from the API. `@reblu/site-blocks` adds `CourseCatalogFilters`, a drop-in instructor and price filter (bands in integer cents plus «Gratis»), RSC-safe like `ShopFilters`.
+- d1db04e: Tenant-configurable interest question on the contact form (REB-759).
+  - `Config.contactInterest`: `{ label, options }` or `null`, the tenant's own question and options from nexus. `null` means the field must not render; there is no default catalogue.
+  - `ContactFormInput.interests`: the chosen option labels (up to 20). The server keeps only labels the tenant offers.
+  - New drop-in `ContactInterestField` in `@reblu/site-blocks`: a controlled checkbox group that renders nothing when the tenant has no question. Slots: `contact-interest`, `contact-interest-option`.
+
+- 5ca48ee: Discount code usage limits are enforced before payment (REB-912).
+  - New `ShopErrorCode` `DISCOUNT_LIMIT_REACHED` (400): checkout refuses a discount code that has used up its total uses (slots held by open payment sessions count), before any payment session is created. The buyer can continue without the code.
+  - `DEFAULT_SHOP_ERROR_MESSAGES.DISCOUNT_LIMIT_REACHED`: «Este código ya ha alcanzado su límite de usos».
+  - A per-customer limit still answers `DISCOUNT_INVALID` with a neutral message.
+
+### Patch Changes
+
+- Updated dependencies [01d0e15]
+- Updated dependencies [d1db04e]
+- Updated dependencies [5ca48ee]
+  - @reblu/site-contracts@1.22.0
+
+## 0.21.0
+
+### Minor Changes
+
+- 76e64f3: Free-preview lessons for the public, and a redesigned course programme (REB-1135).
+  - New RSC-safe `LessonPreview`: the hosted video player in an `<iframe>` plus the lesson body through the sanitising Markdown pipeline, over `getLessonPreview()` from `@reblu/site-next/academy-server`. Spanish copy overridable via `DEFAULT_LESSON_PREVIEW_LABELS`. The SITE's CSP needs `frame-src https://player.mux.com`.
+  - `CourseSyllabus` redesign: rotating chevron icon, a video/reading icon per lesson, lesson durations as «m:ss» / «h:mm:ss» aligned right, the course total in the summary, «Expandir todo / Contraer todo», and «Vista previa gratuita» as a call to action through the new `getPreviewHref`, `previewHrefTemplate` or `onPreview` props. Every existing `data-slot` is kept; new slots: `course-syllabus-header`, `course-syllabus-toggle-all`, `course-syllabus-chevron`, `course-syllabus-lesson-icon`, `course-syllabus-lesson-duration`, `course-syllabus-preview`. New labels: `expandAll`, `collapseAll`, `videoLesson`, `textLesson`. Visible change: lesson durations read «10:00» instead of «10 min».
+
+### Patch Changes
+
+- Updated dependencies [76e64f3]
+  - @reblu/site-contracts@1.21.0
+
 ## 0.20.0
 
 ### Minor Changes

package/README.md

@@ -25,9 +25,11 @@ colour on the red background. See `docs/theming/theming.md`.
 | `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".  |
+| `LessonPreview`, `DEFAULT_LESSON_PREVIEW_LABELS`                                                              | `.`        | A public free-preview lesson: hosted video player + sanitised body (`getLessonPreview()`). Server Component. See "Free-preview lesson".  |
 | `Treatment`, `ParentPage`, `ProfileCard`, `ProductCard`                                                       | `.`        | Presentational organisms over the SITE API contracts. RSC-safe. `Specialty`: deprecated alias, see below.                    |
 | `ProfessionalFields`                                                                                          | `.`        | The tenant's own professional fields (`professional.fields`) on a team card or profile. RSC-safe. See below.                 |
 | `ShopFilters`                                                                                                 | `.`        | Plug-and-play shop filter chrome over `GET /api/site/shop/facets`. RSC-safe. See "Shop filters" below.                       |
+| `CourseCatalogFilters`, `DEFAULT_COURSE_PRICE_BANDS`                                                         | `.`        | Course catalogue filters by instructor and price (`client.academy.instructors()`). RSC-safe. See "Course catalogue filters". |
 | `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.            |
@@ -633,6 +635,27 @@ 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).
 
+A discount code that has used up its total uses is refused by checkout
+BEFORE any payment session exists, with `DISCOUNT_LIMIT_REACHED` (400, REB-912)
+and the default copy «Este código ya ha alcanzado su límite de usos». Let the
+buyer remove the code and continue; nothing was charged. Slots held by open
+payment sessions count, so the last use can never be sold twice. A
+per-customer limit keeps answering `DISCOUNT_INVALID` with a neutral message,
+so the response never reveals whether an email already bought.
+
+```tsx
+import { getShopErrorMessage } from '@reblu/site-blocks'
+import { ApiError } from '@reblu/site-client'
+
+try {
+  await client.shop.checkout(body)
+} catch (error) {
+  if (error instanceof ApiError && error.body?.code === 'DISCOUNT_LIMIT_REACHED') {
+    setDiscountError(getShopErrorMessage('DISCOUNT_LIMIT_REACHED')) // offer «continuar sin código»
+  }
+}
+```
+
 ## Product trust items
 
 `ProductTrustItems` renders the store-wide trust messages (shipping, returns,
@@ -906,40 +929,181 @@ It renders the package's `ProductCard` by default. To use your own card, pass
   `headingClassName` replaces the heading's typography (see the className rule
   above). It renders nothing for an empty list.
 
-## Course programme — `CourseSyllabus` (REB-1134)
+## Course programme — `CourseSyllabus` (REB-1134, redesigned in REB-1135)
 
 The programme of a public course page: every module, and inside each module the
 lessons that make it up. The header reads «Programa» and «3 módulos · 12
-lecciones». Each module row shows its lesson count and, when every lesson in it
-has a duration, the module's total («4 lecciones · 1 h 20 min»). Opening a
-module lists its lessons in order, with each lesson's duration and a «Vista
-previa gratuita» badge on free-preview lessons.
+lecciones · 2 h 40 min», with an «Expandir todo / Contraer todo» control. Each
+module row shows a number badge, its lesson count and, when every lesson in it
+has a duration, the module's total («4 lecciones · 1 h 20 min»), and a chevron
+that rotates when open. Opening a module lists its lessons in order: a video or
+reading icon, the title, the duration right-aligned as «m:ss» / «h:mm:ss», and on
+free-preview lessons «Vista previa gratuita» as a call to action.
 
 ```tsx
 import { CourseSyllabus } from '@reblu/site-blocks/client'
 
 // `course` is an `AcademyCourseDetail` from `client.academy.bySlug(slug)`.
-// It works from a Server Component page: every prop is serialisable.
-<CourseSyllabus modules={course.modules} />
+// From a Server Component page, use the serialisable template:
+<CourseSyllabus
+  modules={course.modules}
+  previewHrefTemplate={`/formacion/${course.slug}/preview/{lessonSlug}`}
+/>
+
+// From a Client Component you can pass functions instead:
+<CourseSyllabus
+  modules={course.modules}
+  getPreviewHref={(lesson) => `/formacion/${course.slug}/preview/${lesson.slug}`}
+  // or: onPreview={(lesson) => openPreviewModal(lesson.slug)}
+/>
 ```
 
+- **Free preview call to action.** `getPreviewHref(lesson)` (or the
+  serialisable `previewHrefTemplate`, with `{lessonSlug}` and `{lessonId}`)
+  renders a link; `onPreview(lesson)` renders a button (e.g. to open a modal).
+  Both apply only to lessons with `isFreePreview`. With neither, the flag is a
+  plain label. The link/button is named «Vista previa gratuita: {título}». Point
+  it at a page that renders `LessonPreview` (see "Free-preview lesson").
 - **Public data only.** It renders what the API serves. The API returns
   published lessons only, and never a video, playback or attachment id, a
   signed URL or the lesson content.
 - **Accessibility.** The block is a `region` named by its heading. A module
   with lessons is a `<button>` with `aria-expanded` and `aria-controls`
-  pointing at its lesson list. Tab reaches it; Enter and Space open and close
-  it. Modules open independently and start closed.
+  pointing at its lesson list. Tab reaches «Expandir todo», then each module;
+  Enter and Space open and close it, and an open module's preview links follow
+  it in the tab order. Modules open independently and start closed. Icons are
+  `aria-hidden`; each lesson's type is announced as «Vídeo» / «Lectura».
+  Durations are `<time datetime="PT10M0S">`.
 - **Modules without lessons** render as a plain row with the title, not a
   button. A payload without `lessons` renders the same way.
 - **Copy.** The defaults are Spanish (`DEFAULT_COURSE_SYLLABUS_LABELS`).
   Override any of them with `labels={{ heading, moduleSingular, modulePlural,
-  lessonSingular, lessonPlural, freePreview, hours, minutes }}`.
-- **Styling.** `headingLevel` (default `2`), `headingClassName` (replaces the
+  lessonSingular, lessonPlural, freePreview, hours, minutes, expandAll,
+  collapseAll, videoLesson, textLesson }}`.
+- **Styling.** Uses only the SDK tokens (`border`, `card`, `muted`, `primary`,
+  `ring`). `headingLevel` (default `2`), `headingClassName` (replaces the
   heading's typography, see the className rule above) and `className`. Style
-  the parts with `[data-slot="course-syllabus"]`, `course-syllabus-module`,
-  `course-syllabus-lessons` and `course-syllabus-lesson`. It renders nothing
-  for a course without modules.
+  the parts with `[data-slot="course-syllabus"]`, `course-syllabus-header`,
+  `course-syllabus-summary`, `course-syllabus-toggle-all`,
+  `course-syllabus-module`, `course-syllabus-chevron`, `course-syllabus-lessons`,
+  `course-syllabus-lesson`, `course-syllabus-lesson-icon` (`data-type="video" |
+  "text"`), `course-syllabus-lesson-title`, `course-syllabus-lesson-duration`
+  and `course-syllabus-preview`. No slot was renamed in REB-1135. It renders
+  nothing for a course without modules.
+
+## Course catalogue filters — `CourseCatalogFilters` (REB-547)
+
+Drop-in filters for the academy catalogue: an instructor filter fed by
+`client.academy.instructors()` (instructors of published courses, sorted by
+name) and a price filter (bands in integer cents plus «Gratis»). Each option
+maps 1:1 onto a `client.academy.courses()` param: `instructor`, `priceMin`,
+`priceMax`, `free`. Same RSC-safe contract as `ShopFilters`: every option is a
+real `<a href>`; pass `onChange` only from a `'use client'` boundary.
+
+```tsx
+import { CourseCatalogFilters } from '@reblu/site-blocks'
+import type { AcademyCourseListQuery } from '@reblu/site-contracts'
+import { client } from '@/lib/reblu'
+
+export default async function CoursesPage({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | undefined>>
+}) {
+  const sp = await searchParams
+  const num = (v?: string) => (v ? Number(v) : undefined)
+  const active: AcademyCourseListQuery = {
+    instructor: sp.instructor,
+    priceMin: num(sp.priceMin),
+    priceMax: num(sp.priceMax),
+    free: sp.free === 'true',
+  }
+  const [courses, instructors] = await Promise.all([
+    client.academy.courses(active),
+    client.academy.instructors(),
+  ])
+
+  // Keep the other params; `free` and a price band exclude each other.
+  const href = (patch: Partial<AcademyCourseListQuery>) => {
+    const next = new URLSearchParams()
+    for (const [k, v] of Object.entries({ ...active, ...patch })) {
+      if (v !== undefined && v !== false) next.set(k, String(v))
+    }
+    const qs = next.toString()
+    return qs ? `/cursos?${qs}` : '/cursos'
+  }
+
+  return (
+    <>
+      <CourseCatalogFilters
+        instructors={instructors.data}
+        active={active}
+        hrefs={{
+          instructor: (id) => href({ instructor: id }),
+          price: (min, max) => href({ priceMin: min, priceMax: max, free: false }),
+          free: (next) => href({ free: next, priceMin: undefined, priceMax: undefined }),
+          clearAll: () => '/cursos',
+        }}
+      />
+      {/* render courses.data */}
+    </>
+  )
+}
+```
+
+- **Price is integer cents.** The default bands (`DEFAULT_COURSE_PRICE_BANDS`)
+  are EUR: up to 50, 50 to 150, 150 to 300, from 300. Pass `priceBands` for
+  another catalogue and `currencyCode` / `locale` for the labels.
+- **«Gratis» wins.** The API applies `free=true` over any price range, so no
+  band shows as active while it is on; the component's `onChange` patches turn
+  one off when the other is picked, and `hrefs` should do the same.
+- **Unnamed instructors** (no first or last name) are not offered. An active
+  instructor id that is no longer listed keeps the group visible, so it can be
+  cleared.
+- Spanish default labels (`DEFAULT_COURSE_CATALOG_FILTERS_LABELS`), all
+  overridable through `labels`.
+
+## Free-preview lesson — `LessonPreview` (REB-1135)
+
+A lesson the owner marked «Vista previa gratuita», for visitors who have not
+paid or enrolled: the video and the lesson body. Fetch it on the server with
+`getLessonPreview` (`@reblu/site-next/academy-server`), which returns `null`
+for any lesson the public may not see.
+
+```tsx
+// app/formacion/[slug]/preview/[lessonSlug]/page.tsx — a Server Component
+import { notFound } from 'next/navigation'
+import { LessonPreview } from '@reblu/site-blocks'
+import { getLessonPreview } from '@reblu/site-next/academy-server'
+import { client } from '@/lib/reblu' // your server-side RebluClient
+
+export const dynamic = 'force-dynamic' // the video token is short-lived: never ISR
+
+export default async function Page({ params }) {
+  const { slug, lessonSlug } = await params
+  const lesson = await getLessonPreview(client, slug, lessonSlug)
+  if (!lesson) notFound()
+  return <LessonPreview lesson={lesson} headingLevel={1} />
+}
+```
+
+- **Player.** `video.embedUrl` is the provider's hosted player, already carrying
+  its short-lived token, rendered in an `<iframe>` named «Vídeo: {título}» —
+  no video library in the SDK. Only `https:` URLs are embedded. Add
+  `frame-src https://player.mux.com` to the SITE's Content-Security-Policy.
+  `video` is `null` for a text-only lesson (no player is rendered).
+- **Body.** `content` is Markdown, rendered through the same sanitising
+  pipeline as `CourseDescription`: no raw HTML, no scripts, no `javascript:`
+  links. Its headings sit one level below the lesson title. An empty body
+  renders nothing.
+- **Semantics.** An `<article>` named by the title; the duration is a
+  `<time>`. Server Component (RSC-safe), from the root entry.
+- **Copy.** Spanish defaults (`DEFAULT_LESSON_PREVIEW_LABELS`), override with
+  `labels={{ badge, player, duration }}`.
+- **Styling.** `headingLevel` (default `2`), `headingId`, `headingClassName`,
+  `contentClassName`, `className`; slots `lesson-preview`,
+  `lesson-preview-badge`, `lesson-preview-duration`, `lesson-preview-player`,
+  `lesson-preview-content`.
 
 ## Page blocks
 
@@ -1101,6 +1265,37 @@ renderer (`headingOffset` demotes its headings under yours).
 `markdownToPlainText` drops images and anything the sanitiser strips, and cuts
 at a word boundary with `…` within `maxLength`.
 
+## Contact form interest question — `ContactInterestField` (REB-759)
+
+The tenant's own optional question on the contact form, e.g. «¿Qué tratamiento
+te interesa?», with the options it configured in nexus (Integraciones →
+Formulario de Contacto). Pass `config.contactInterest` from `/api/site/config`
+and send the chosen labels as `interests`. Unconfigured (`null`, or an older
+base-api) renders nothing. **Never supply your own fallback list**: there is no
+default catalogue, and the server keeps only labels the tenant offers.
+
+```tsx
+'use client'
+import { useState } from 'react'
+import { ContactInterestField } from '@reblu/site-blocks'
+import type { Config } from '@reblu/site-contracts'
+
+export function ContactFormInterest({ config }: { config: Config }) {
+  const [interests, setInterests] = useState<string[]>([])
+  // ...on submit: client.contactForm.submit({ ...fields, interests })
+  return (
+    <ContactInterestField
+      interest={config.contactInterest}
+      value={interests}
+      onChange={setInterests}
+    />
+  )
+}
+```
+
+Styling: `data-slot="contact-interest"` (the `<fieldset>`, its `<legend>` is the
+question) and `data-slot="contact-interest-option"` (each `<label>`).
+
 ## GDPR rights form — `DataRequestForm` (REB-980)
 
 Drop-in form for a SITE's public rights page (e.g. `/derechos-rgpd`): request