@reblu/site-blocks 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @reblu/site-blocks
 
+## 0.10.0
+
+### Minor Changes
+
+- e78229a: REB-853 — rename the `Specialty` organism to the niche-agnostic `ParentPage` (a page with a linked grid of child pages), with props `childPages`, `childPageHref` and `childPagesLabel`.
+
+  `Specialty` / `SpecialtyProps` and the props `treatments`, `treatmentHref` and `treatmentsLabel` remain as `@deprecated` aliases — `Specialty` is the same reference as `ParentPage`, so rendering is unchanged. They will be removed in the next major, not before 2027-03-31.
+
+## 0.9.0
+
+### Minor Changes
+
+- 14814b0: Add a shared renderer for page registry blocks and FAQ structured data (REB-850).
+  - `PageBlocks` (root entry, Server Component): renders `PageDetail.blocks`,
+    applying each block's mirrored section `heading`, `backgroundColor` and `cta`.
+    Every block type's body is overridable through a `components` map keyed by
+    canonical type. Unknown block types and embeds with `resolved: null` render
+    nothing; the deprecated `doctor_embed`/`specialty_embed` aliases render
+    through the `profile_embed`/`page_embed` renderers. Blocks render in `order`;
+    a `cta` slot with no heading, no usable CTA and no override renders nothing.
+    Pass `idPrefix` when a page renders more than one `PageBlocks` instance, so
+    section heading ids stay unique.
+  - `FaqAccordion` (root entry, Server Component): native `<details>`/`<summary>`
+    FAQ list with configurable heading levels; no JavaScript required.
+  - `buildFaqPageJsonLd` and `collectFaqItems` on the new directive-free
+    `@reblu/site-blocks/seo` subpath (also on the root): build a schema.org
+    `FAQPage` object, callable from Server Components. Questions follow block
+    `order` and keep the author's plain text (whitespace collapsed only), so the
+    structured data matches what `FaqAccordion` shows.
+
+  Additive only — no existing export changes.
+
 ## 0.8.0
 
 ### Minor Changes

package/README.md

@@ -15,9 +15,11 @@ a different-looking site for every tenant, with zero forks.
 | `readingTime`, `formatPrice`, `buildShareUrls`, `markdownToSafeHtml`                                          | `.`        | Pure, framework-agnostic helpers (RSC-safe).                                                                                 |
 | `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. |
-| `Treatment`, `Specialty`, `ProfileCard`, `ProductCard`                                                        | `.`        | Presentational organisms over the SITE API contracts. RSC-safe.                                                              |
+| `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.                                            |
+| `PageBlocks`, `FaqAccordion`                                                                                  | `.`        | Registry-block renderer (`PageDetail.blocks`) and native `<details>` FAQ. Server Components. See "Page blocks" 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`.                                                                       |
 | `ShareButtons`                                                                                                | `./client` | Social share (X / LinkedIn / WhatsApp / copy).                                                                               |
@@ -378,6 +380,150 @@ Every title/description is overridable via `labels` (see
 "`useShopOrderStatus` — the order-confirmation flow" for the full wiring
 recipe.
 
+## `ParentPage` (formerly `Specialty`)
+
+`ParentPage` renders a page that groups other pages: the hero and content
+sections of a `PageDetail`, then an optional linked grid of its child pages
+(`PageListItem[]` — cover image, title, excerpt).
+
+```tsx
+import { ParentPage } from '@reblu/site-blocks'
+
+export function ServicesHub({ page, services }) {
+  return (
+    <ParentPage
+      page={page}
+      childPages={services}
+      childPageHref={(slug) => `/services/${slug}`}
+      childPagesLabel='Services'
+    />
+  )
+}
+```
+
+**Deprecated (REB-853) — removed in the next major, not before 2027-03-31:**
+
+| Deprecated        | Use instead       |
+| ----------------- | ----------------- |
+| `Specialty`       | `ParentPage`      |
+| `SpecialtyProps`  | `ParentPageProps` |
+| `treatments`      | `childPages`      |
+| `treatmentHref`   | `childPageHref`   |
+| `treatmentsLabel` | `childPagesLabel` |
+
+`Specialty` is the same component reference as `ParentPage`, not a copy, so
+existing code renders exactly as before. When a new prop and its deprecated
+counterpart are both passed, the new one wins. The default grid heading stays
+`"Treatments"` and the root keeps `data-slot="specialty"` until that major, so
+the rename changes no markup — pass `childPagesLabel` to set your own heading.
+
+## Page blocks
+
+`PageBlocks` renders a page's registry blocks (`PageDetail.blocks` from
+`GET /api/site/pages/[slug]`) so a SITE does not hand-write its own block
+switch. It is a **Server Component** — no hooks, no `'use client'` — exported
+from the RSC-safe root entry.
+
+```tsx
+import { PageBlocks } from '@reblu/site-blocks'
+import { buildFaqPageJsonLd, collectFaqItems } from '@reblu/site-blocks/seo'
+import { JsonLd } from '@reblu/site-next/json-ld'
+
+export default async function Page({ params }) {
+  const page = await getPage((await params).slug)
+  const faq = buildFaqPageJsonLd(collectFaqItems(page.blocks))
+  return (
+    <main>
+      <h1>{page.title}</h1>
+      <PageBlocks blocks={page.blocks} embedHref={(r) => `/${r.slug}`} />
+      {faq && <JsonLd id='faq' data={faq} />}
+    </main>
+  )
+}
+```
+
+Each block is wrapped in a `<section data-slot="page-block" data-block-type="…">`
+that applies the parent section's mirrored fields (REB-849):
+
+- **`heading`** — rendered at `headingLevel` (default `2`) and used as the
+  section's accessible name. Headings inside the block go one level deeper.
+- **`backgroundColor`** — applied as the section background. Theme tokens
+  (`var(--primary)`, `var(--secondary)`, `var(--accent)`) get their paired
+  `-foreground` token; a custom hex gets white or near-black text by WCAG
+  luminance; any other value keeps the theme foreground.
+- **`cta`** — rendered after the body as a link styled with `buttonVariants`;
+  external CTAs open in a new tab with `rel="noopener noreferrer"`.
+
+| Prop                | Default              | Purpose                                                    |
+| ------------------- | -------------------- | ---------------------------------------------------------- |
+| `blocks`            | —                    | `PageDetail.blocks`. `null`/empty renders nothing.         |
+| `components`        | `{}`                 | Per-type body renderer overrides (see below).              |
+| `headingLevel`      | `2`                  | Level of each section heading.                             |
+| `embedHref`         | `` r => `/${r.slug}` `` | Href of an embedded page — route it per `r.pageType`.   |
+| `idPrefix`          | `'page-block'`       | Namespace for heading ids; pass distinct values when one document renders `PageBlocks` twice with the same blocks. |
+| `className`, `sectionClassName` | —        | Extra classes on the list / on each section.               |
+
+### Fail-closed rules
+
+- An **unknown `blockType`** (e.g. a type added to the API before this package
+  is upgraded) renders nothing — not even its heading — and never throws.
+- An **embed** (`page_embed`, `profile_embed`) whose `resolved` is `null` or
+  absent renders nothing: no heading, no dead link.
+- A **`cta` block** references a live CTA by `data.slot`, which only the SITE
+  can resolve; by default it renders just the section heading and mirrored
+  CTA, and nothing at all when it has neither. Supply `components.cta` to
+  render the slot.
+- **Deprecated aliases** `doctor_embed` and `specialty_embed` (REB-852) render
+  through the `profile_embed` and `page_embed` renderers respectively.
+
+### Overriding a block type
+
+`components` is a partial map keyed by **canonical** block type. An override
+replaces only the block body; the section wrapper (heading, background, CTA)
+still applies.
+
+```tsx
+import { PageBlocks, type BlockRendererProps } from '@reblu/site-blocks'
+
+function TeamCard({ block, headingLevel, embedHref }: BlockRendererProps<'profile_embed'>) {
+  // `block.resolved` is never null here; `block.blockType` may be the deprecated alias.
+  return <a href={embedHref(block.resolved)}>{block.resolved.title}</a>
+}
+
+<PageBlocks blocks={page.blocks} components={{ profile_embed: TeamCard }} />
+```
+
+Every renderer receives `{ block, headingLevel, embedHref }`. Overrides may be
+async Server Components, or Client Components when they need interactivity.
+
+### `FaqAccordion`
+
+Native `<details>`/`<summary>` — opens and closes with no JavaScript, keyboard
+and screen-reader semantics come from the browser. Answers render as text,
+never as markup; line breaks are kept.
+
+| Prop                   | Default | Purpose                                                       |
+| ---------------------- | ------- | ------------------------------------------------------------- |
+| `items`                | —       | `{ q, a }[]` — the `faq` block's `data.items`.                |
+| `heading`              | —       | Optional heading above the list.                              |
+| `headingLevel`         | `2`     | Level of `heading`.                                           |
+| `questionHeadingLevel` | —       | When set, wraps each question in `<h{n}>` inside its summary. |
+| `defaultOpen`          | `[]`    | Indexes of items open on first render.                        |
+
+### `buildFaqPageJsonLd(items)`
+
+Returns a schema.org `FAQPage` object (or `null` when no item has both a
+question and an answer — an empty `FAQPage` is invalid). Questions and answers
+are plain text and pass through verbatim — only whitespace is collapsed — so the
+structured data says exactly what `FaqAccordion` shows (`a < b` survives).
+`collectFaqItems` orders blocks by `order` with the same helper `PageBlocks`
+uses, so question order matches the page. It is a pure function exported from the directive-free
+`@reblu/site-blocks/seo` entry, so Server Components and `generateMetadata` can
+call it — a helper reachable only through a `'use client'` entry cannot be
+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.
+
 ## Security boundaries
 
 Two sinks, two different helpers, in two different packages — do not reach for