@reblu/site-blocks 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @reblu/site-blocks
 
+## 0.34.0
+
+### Minor Changes
+
+- 46b855f: Page links drop-ins (REB-1100). Additive only: no existing component changes.
+  - `LinkedPagesGrid` (root entry): a linked card grid over a page's `links` (the pages it picked in nexus, e.g. a profile's areas) or `relatedPages` (derived: the pages of those areas, or the pages that belong to this one). Renders nothing for an empty or absent list.
+  - `TeamGrid` (root entry): `ProfileCard`s over a page's `team` (derived: the team profiles linked to this page or to the pages it belongs to). Renders nothing without members.
+  - `TeamDirectory` (client entry): the team listing with one filter chip per page the members link to, «Todos» first (labels overridable). `memberHrefBase` (a string) links the cards from a Server Component, where a `memberHref` function cannot be passed. Members without `links` render as a plain listing.
+  - Pure helpers `linkKey`, `linkFilterOptions` and `filterByLink` (root entry) for a SITE that builds its own chips.
+
+  The props are structural, so the drop-ins already accept today's `PageListItem` and `ResolvedEmbed`.
+
+- e43b01c: `ReviewsCarousel` (REB-1272), from `@reblu/site-blocks/client`. It shows the tenant's published reviews as an accessible carousel: the same cards and data rules as `Reviews`, on the package's scroll-snap track, with a labelled focusable region and labelled previous/next buttons. It never autoplays, and scrolling is instant under `prefers-reduced-motion`. `Reviews` renders exactly as before; its card moved into a shared internal module. `FeaturedReviews`, also from `/client`, renders the reviews a tenant featured for its home in the layout it chose in nexus: `grid` uses `Reviews`, `carousel` uses `ReviewsCarousel`, and an unknown layout falls back to the grid.
+- 83084d0: «Reseñas» page block (REB-1272). `@reblu/site-contracts` adds the `reviews` block type: `ReviewsBlockData` (`{ scope: 'all' | 'page', limit?, layout?: 'grid' | 'carousel', notice? }`) and an optional `reviews: Review[]` on `PageBlock`, which the site API fills with the published reviews the block selects. `@reblu/site-blocks` renders it in `PageBlocks` with the `Reviews` drop-in (the tenant's notice included) and skips the whole section when there is no review to show. Every existing block type renders exactly as before. The carousel layout renders as the grid in the server-safe `PageBlocks`; `ReviewsBlockRenderer` from `@reblu/site-blocks/client` renders the real carousel through `components.reviews`. `PageDetail` gains an `id` (optional on the wire, always emitted), so a SITE can call `client.reviews.list({ pageId: page.id })`.
+
+### Patch Changes
+
+- 1e2f438: REB-1227: docs only. `toCheckoutFulfillmentFields` documentation now says that the server reads a request without `fulfillment` on a cart that ships as home delivery, with the address required (422 `SHIPPING_ADDRESS_REQUIRED`). No code change.
+- Updated dependencies [49d31ea]
+- Updated dependencies [c8bf6c1]
+- Updated dependencies [83084d0]
+  - @reblu/site-contracts@1.32.0
+
+## 0.33.0
+
+### Minor Changes
+
+- 8c2e641: REB-1236: the order confirmation screen says what happens next for each purchase type.
+  - `@reblu/site-contracts`: `ShopOrder.purchaseTexts?: ShopOrderPurchaseText[]` (`{ kind: 'shipping' | 'pickup' | 'digital' | 'service', label, text }`), one entry per purchase type in the order, with the shop's texts from nexus or their Spanish defaults. Optional: older servers do not send it.
+  - `@reblu/site-blocks`: `OrderConfirmation` renders `order.purchaseTexts` under a confirmed order, with no extra wiring. New optional prop `showPurchaseTexts` (default `true`). An order without the field renders as before.
+
+- fb9bfcc: REB-1236 follow-up: the pickup block of the order confirmation names the pickup point.
+  - `@reblu/site-contracts`: `ShopOrderPurchaseText.place?: { name, address: string[] }`, sent on the `pickup` entry with the pickup point frozen on the order (the same name and address lines as the confirmation email). Optional: absent on other kinds and on older servers.
+  - `@reblu/site-blocks`: `OrderConfirmation` shows that name and address in the pickup block, with no extra wiring.
+
+### Patch Changes
+
+- Updated dependencies [8c2e641]
+- Updated dependencies [fb9bfcc]
+  - @reblu/site-contracts@1.31.0
+
 ## 0.32.0
 
 ### Minor Changes

package/README.md

@@ -334,7 +334,7 @@ for the wiring steps and a full example app).
 | `CartSummary`         | `.`        | `subtotal`, `discount?`, `autoDiscount?`, `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`, `autoDiscount?` | Yes                                                                               |
-| `OrderConfirmation`   | `.`        | `status`, `order`, `cartHref?`, `onRecheck?`                                                                            | Yes                                                                               |
+| `OrderConfirmation`   | `.`        | `status`, `order`, `cartHref?`, `onRecheck?`, `showPurchaseTexts?`                                                      | Yes                                                                               |
 | `OrderInvoiceLink`    | `.`        | `invoice` (`order.invoice`), `labels?`                                                                                  | Yes (renders `null` without an invoice)                                           |
 | `FullInvoiceFields`   | `.`        | `value`, `onChange`, `overCap`, `errors?`, `countries?`, `labels?`                                                      | Yes (controlled, no hooks)                                                        |
 
@@ -604,6 +604,29 @@ shown instead of a raw placeholder. A SITE that passes its own
 `labels.foundDescription` is unaffected: a text without `{email}` keeps the
 confirmation-email line, exactly as before.
 
+**REB-1236 — what happens next, per purchase type.** The order lookup
+carries `order.purchaseTexts: Array<{ kind, label, text }>`: one entry per
+purchase type in the order (`shipping`, `pickup`, `digital`, `service`; a
+mixed order gets one each, delivery first). `label` is the shop's checkout
+label for that type and `text` the shop's own text from nexus › Tienda ›
+Configuración › Confirmación, or its Spanish default. `OrderConfirmation`
+renders them under a confirmed order (`paid`/`found`/`timeout`) with no extra
+wiring; the SITE writes no copy of its own:
+
+```tsx
+const { status, order, recheck } = useShopOrderStatus(sessionId)
+
+// The per-type texts appear on their own. Pass showPurchaseTexts={false} to hide them.
+<OrderConfirmation status={status} order={order} sessionId={sessionId} onRecheck={recheck} />
+```
+
+The `pickup` entry also carries `place: { name, address }`, the pickup point
+frozen on the order, and the block shows it above the text (the same lines as
+the confirmation email).
+
+A server older than REB-1236 sends no `purchaseTexts`, and the screen renders
+as before.
+
 Every title/description is overridable via `labels` (see
 `OrderConfirmationLabels`). See `@reblu/site-next`'s README
 "`useShopOrderStatus` — the order-confirmation flow" for the full wiring
@@ -771,8 +794,9 @@ Notes:
   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).
+  for such a cart. A request without `fulfillment` on a cart that ships is
+  read as home delivery and needs the address (422 `SHIPPING_ADDRESS_REQUIRED`,
+  REB-1227).
 - Pickup point (REB-1276): switching to pickup with exactly one point selects
   it (`pickupLocationId` is sent); with two or more, none is preselected.
   While pickup has no point, `isCheckoutDeliveryComplete(fulfillment)` is
@@ -978,6 +1002,62 @@ const { data: pageReviews } = await client.reviews.list({ pageId: page.id })
   slot rule and REPLACE their defaults (`text-xl font-semibold`,
   `sm:grid-cols-2 lg:grid-cols-3`, `text-sm text-muted-foreground`).
 
+### `ReviewsCarousel` — the same reviews as a carousel
+
+The same cards and data rules as `Reviews`, on the package's scroll-snap
+carousel. A Client Component, from `@reblu/site-blocks/client`:
+
+```tsx
+import { ReviewsCarousel } from '@reblu/site-blocks/client'
+
+// In a Server Component: fetch, then hand the data to the carousel.
+const { data: reviews } = await client.reviews.list({ limit: 9 }).catch(() => ({ data: [] }))
+<ReviewsCarousel
+  reviews={reviews}
+  heading='Reseñas'
+  notice='Cada reseña enlaza a su original.'
+/>
+```
+
+- **Accessible.** The track is a labelled, focusable region
+  (`aria-roledescription="carrusel"`): swipe on touch, arrow keys once it has
+  focus. «Reseña anterior» / «Reseña siguiente» buttons (from `sm` up) scroll one
+  page and are disabled at the ends; they are not rendered when everything fits.
+- **Never moves by itself.** No autoplay, so there is nothing to pause.
+  Button scrolling is instant under `prefers-reduced-motion: reduce`.
+- `labels` renames the region and buttons; `itemClassName` changes the slide
+  width; `cardClassName`, `headingClassName` and `noticeClassName` style as in
+  `Reviews`.
+- `null`, `[]` or no checkable review render nothing.
+
+### `FeaturedReviews` — the home's featured reviews, in the tenant's layout
+
+The tenant chooses in nexus which reviews its home features, in what order,
+and whether they show as a grid or a carousel. `FeaturedReviews` renders
+exactly that: `grid` → the `Reviews` grid, `carousel` → `ReviewsCarousel`. An
+unknown layout falls back to the grid. Client Component, from
+`@reblu/site-blocks/client`:
+
+```tsx
+import { FeaturedReviews } from '@reblu/site-blocks/client'
+
+// In a Server Component (`client.reviews.featured()` returns both).
+const featured = await client.reviews
+  .featured()
+  .catch(() => ({ layout: 'grid' as const, reviews: [] }))
+<FeaturedReviews reviews={featured.reviews} layout={featured.layout} heading='Reseñas' />
+```
+
+Nothing to show (no featured review, module off) renders nothing.
+
+### Why the carousel lives in `./client`
+
+`ReviewsCarousel` needs browser state, and the root entry must stay loadable in
+React Server Components: re-exporting it from the root breaks every
+Server-Component render of the root entry (`test/rsc-safety.test.ts`, verified
+REB-1272). So the carousel, and everything that may render it, ships from
+`@reblu/site-blocks/client`.
+
 ## Trust badges
 
 `TrustBadges` renders the tenant's trust badges — partners, insurers, funding,
@@ -1140,6 +1220,65 @@ export async function ServicesTeaser() {
 }
 ```
 
+## Page links — `TeamDirectory`, `LinkedPagesGrid`, `TeamGrid` (REB-1100)
+
+In nexus a page can pick other pages, in order: a team profile picks its
+areas («Áreas»), and any other page picks the areas it belongs to («Páginas a
+las que pertenece»). Which category holds the «areas» is the tenant's choice;
+this package names none. The SITE API serves:
+
+- `links` on every item of `client.pages.list` and on `client.pages.bySlug`:
+  the published pages this page picked, in the tenant's order;
+- on `client.pages.bySlug` only, two DERIVED lists:
+  - `team`: the team profiles linked to this page or to any page it links to.
+    On an area page that is the area's team; on a page that belongs to areas,
+    the team of those areas;
+  - `relatedPages`: the other pages linked to this page or to its links. On a
+    profile that is the pages of its areas; on an area, the pages that belong
+    to it.
+
+All three are optional on the wire: every drop-in below renders nothing (or a
+plain listing) when they are absent, so it is safe to place before the server
+emits them.
+
+The team listing, with one filter chip per area (client entry):
+
+```tsx
+import { TeamDirectory } from '@reblu/site-blocks/client'
+
+const { data: team } = await client.pages.list({ type: ['team'] })
+
+<TeamDirectory
+  members={team}
+  memberHrefBase='/equipo' // → `/equipo/${slug}`; from a Client Component, `memberHref={(m) => …}` also works
+  showLinksOnCards // the member's areas as chips on each card
+  labels={{ all: 'Todos', filter: 'Filtrar el equipo' }} // the defaults
+/>
+```
+
+A profile's areas and the pages derived from them, and the team of an area or
+of a page (RSC):
+
+```tsx
+import { LinkedPagesGrid, TeamGrid } from '@reblu/site-blocks'
+
+const page = await client.pages.bySlug(slug)
+const href = (p: { slug: string; category?: { slug: string } | null }) =>
+  `/${p.category?.slug}/${p.slug}`
+
+// On a team profile
+<LinkedPagesGrid heading='Áreas' pages={page.links} pageHref={href} />
+<LinkedPagesGrid heading='Qué hace' pages={page.relatedPages} pageHref={href} />
+
+// On an area page, or on a page that belongs to areas
+<TeamGrid heading='Equipo' members={page.team} memberHref={(m) => `/equipo/${m.slug}`} />
+```
+
+Building your own chips? `linkFilterOptions(items)` gives each distinct link
+once (`{ key, label }`, first-seen order) and `filterByLink(items, key)` the
+items linked to it (`null` keeps all). Style the drop-ins with `className` or
+`[data-slot="team-directory" | "linked-pages" | "team-grid"]`.
+
 ## Professional fields — `ProfessionalFields` (REB-1099)
 
 Each tenant defines its own fields for team profiles in nexus › Equipo ›
@@ -1570,6 +1709,8 @@ that applies the parent section's mirrored fields (REB-849):
   render the slot.
 - **Deprecated aliases** `doctor_embed` and `specialty_embed` (REB-852) render
   through the `profile_embed` and `page_embed` renderers respectively.
+- A **`reviews` block** with no `reviews` (none match, or the tenant's reviews
+  module is off) renders nothing, not even its heading.
 
 ### Overriding a block type
 
@@ -1692,6 +1833,49 @@ import { ImageTextSplit } from '@reblu/site-blocks'
 
 The legacy `sections[]` layouts `TEXT_IMAGE` / `IMAGE_TEXT` are unchanged.
 
+### «Reseñas» page block (REB-1272)
+
+A tenant adds a «Reseñas» section in the nexus page editor and picks which
+reviews (all published ones, or only those linked to that page), a maximum, a
+layout and an optional notice. The site API resolves the reviews onto the
+block (`block.reviews`, same shape as `client.reviews.list()`), so a SITE that
+renders `PageBlocks` needs nothing else: no extra read, no wiring.
+
+```tsx
+import { PageBlocks } from '@reblu/site-blocks'
+
+// page = (await client.pages.get(slug)).data
+<PageBlocks blocks={page.blocks} />
+// A «Reseñas» block renders <Reviews reviews={block.reviews} notice={block.data.notice} />
+// inside the section.
+```
+
+**Carousel layout.** The tenant can choose `layout: 'carousel'`. The carousel
+needs the browser, and `PageBlocks` must stay a Server Component, so on its own
+it draws the grid (with `data-reviews-layout="carousel"`). To show the real
+carousel, pass the client renderer:
+
+```tsx
+import { PageBlocks } from '@reblu/site-blocks'
+import { ReviewsBlockRenderer } from '@reblu/site-blocks/client'
+
+<PageBlocks blocks={page.blocks} components={{ reviews: ReviewsBlockRenderer }} />
+```
+
+To style it, override the body with the same drop-in:
+
+```tsx
+import { PageBlocks, Reviews, type BlockRendererProps } from '@reblu/site-blocks'
+
+function BrandedReviews({ block }: BlockRendererProps<'reviews'>) {
+  return <Reviews reviews={block.reviews} notice={block.data.notice} cardClassName='bg-muted' />
+}
+
+<PageBlocks blocks={page.blocks} components={{ reviews: BrandedReviews }} />
+```
+
+An SDK older than this one renders nothing for the block (unknown type, fail-closed).
+
 ### `FaqAccordion`
 
 Native `<details>`/`<summary>` — opens and closes with no JavaScript, keyboard