@reblu/site-blocks 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -1,6 +1,8 @@
-import { ShopErrorCode, PageDetail, PageListItem, ShopProductListItem, ShopFacets, ShopOrder } from '@reblu/site-contracts';
+import { ShopErrorCode, PageDetail, PageListItem, ShopProductListItem, BlockType, PageBlock, ResolvedEmbed, ShopFacets, ShopOrder } from '@reblu/site-contracts';
+import { FaqItem } from './seo.cjs';
+export { FaqPageJsonLd, buildFaqPageJsonLd, collectFaqItems } from './seo.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, FormEvent } from 'react';
+import { ComponentType, ReactNode, FormEvent } from 'react';
 
 declare function readingTime(content: string | null | undefined): number | null;
 
@@ -302,6 +304,102 @@ interface ProductCardProps {
 }
 declare function ProductCard({ product, href, currencyCode, locale, className }: ProductCardProps): react_jsx_runtime.JSX.Element;
 
+/** A heading level a caller can configure — `h1`…`h6`. */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * REB-850 — accessible FAQ list on native `<details>`/`<summary>`.
+ *
+ * A Server Component: no hooks, no `'use client'`, no JavaScript needed to
+ * open or close an item — the browser owns the disclosure state, keyboard
+ * support and the expanded/collapsed semantics. Answers render as TEXT (React
+ * escapes them; line breaks are preserved), never as markup.
+ *
+ * Pair it with `buildFaqPageJsonLd` (`@reblu/site-blocks/seo`) for the
+ * matching schema.org `FAQPage` structured data.
+ */
+interface FaqAccordionProps {
+    items: readonly FaqItem[];
+    /** Optional heading above the list. */
+    heading?: string | null;
+    /** Level of `heading`. Default `2`. */
+    headingLevel?: HeadingLevel;
+    /**
+     * When set, each question is wrapped in `<h{level}>` inside its `<summary>`
+     * so it appears in the document outline. Default: plain summary text.
+     */
+    questionHeadingLevel?: HeadingLevel;
+    /** Indexes of the items rendered open initially. */
+    defaultOpen?: readonly number[];
+    className?: string;
+}
+declare function FaqAccordion({ items, heading, headingLevel, questionHeadingLevel, defaultOpen, className, }: FaqAccordionProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * REB-850 — `PageBlocks`: the shared renderer for a page's registry blocks
+ * (`PageDetail.blocks`, REB-75), so a SITE stops hand-writing its own.
+ *
+ * A SERVER COMPONENT by default: no hooks, no `'use client'`, reachable from the
+ * RSC-safe root entry (`test/rsc-safety.test.ts` renders it under
+ * `--conditions=react-server`).
+ *
+ * Each block is wrapped in a `<section>` carrying the parent section's
+ * mirrored fields (REB-849): `heading`, `backgroundColor` and `cta`. The body
+ * comes from a per-type renderer that the `components` map can replace.
+ *
+ * Fail-closed rules:
+ *  • an unknown `blockType` renders nothing (the whole section) and never throws;
+ *  • an embed whose `resolved` is `null`/absent renders nothing — no heading,
+ *    no dead link;
+ *  • deprecated alias types (`doctor_embed`, `specialty_embed` — REB-852)
+ *    render through their generic type's renderer (`profile_embed`, `page_embed`).
+ */
+type DeprecatedAlias = 'doctor_embed' | 'specialty_embed';
+/** Block types a renderer is registered under — deprecated aliases resolve to these. */
+type CanonicalBlockType = Exclude<BlockType, DeprecatedAlias>;
+type EmbedType = 'page_embed' | 'profile_embed';
+type WireTypesOf<T extends CanonicalBlockType> = T extends 'profile_embed' ? 'profile_embed' | 'doctor_embed' : T extends 'page_embed' ? 'page_embed' | 'specialty_embed' : T;
+/**
+ * The block a renderer for `T` receives — including its deprecated alias, and
+ * with `resolved` guaranteed non-null for embeds (unresolved ones never render).
+ */
+type RenderableBlock<T extends CanonicalBlockType> = T extends EmbedType ? Extract<PageBlock, {
+    blockType: WireTypesOf<T>;
+}> & {
+    resolved: ResolvedEmbed;
+} : Extract<PageBlock, {
+    blockType: WireTypesOf<T>;
+}>;
+interface BlockRendererProps<T extends CanonicalBlockType> {
+    block: RenderableBlock<T>;
+    /** Level for headings INSIDE the block — one below the section heading when there is one. */
+    headingLevel: HeadingLevel;
+    /** Builds an embed's href (the `embedHref` prop, or the default `/${slug}`). */
+    embedHref: (resolved: ResolvedEmbed) => string;
+}
+/** Per-block-type renderer overrides, keyed by canonical type. */
+type PageBlocksComponents = Partial<{
+    [T in CanonicalBlockType]: ComponentType<BlockRendererProps<T>>;
+}>;
+interface PageBlocksProps {
+    blocks: readonly PageBlock[] | null | undefined;
+    /** Replace the body renderer of any block type. */
+    components?: PageBlocksComponents;
+    /** Level of each section heading. Default `2` (the page title is the `h1`). */
+    headingLevel?: HeadingLevel;
+    /** Href for an embedded page. Default `/${resolved.slug}`. */
+    embedHref?: (resolved: ResolvedEmbed) => string;
+    /**
+     * Namespace for the section heading ids (`aria-labelledby` targets). Pass a
+     * distinct value when one document renders `PageBlocks` more than once with
+     * overlapping blocks. Sanitised to a valid IDREF. Default `'page-block'`.
+     */
+    idPrefix?: string;
+    className?: string;
+    sectionClassName?: string;
+}
+declare function PageBlocks({ blocks, components, headingLevel, embedHref, idPrefix, className, sectionClassName, }: PageBlocksProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * `ShopFilters` — plug-and-play SITE filter chrome over `GET /api/site/shop/facets`
  * (REB-809). Which axes appear, their order and labels come entirely from
@@ -645,6 +743,14 @@ interface CheckoutFormProps {
     contact: CheckoutContactValues;
     onContactChange: (values: CheckoutContactValues) => void;
     contactErrors?: CheckoutContactErrors;
+    /** Country asserted by the SITE for national phone input; omit rather than guessing. */
+    phoneRegion?: string;
+    /** Optional raw checkout API error body; only INVALID_INPUT/customerPhone marks the phone field. */
+    checkoutError?: {
+        code?: unknown;
+        error?: unknown;
+        details?: unknown;
+    } | null;
     discountCode: string;
     onDiscountCodeChange: (value: string) => void;
     onApplyDiscount: () => void;
@@ -670,7 +776,7 @@ interface CheckoutFormProps {
     locale?: string;
     className?: string;
 }
-declare function CheckoutForm({ contact, onContactChange, contactErrors, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
+declare function CheckoutForm({ contact, onContactChange, contactErrors, phoneRegion, checkoutError, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
 
 /**
  * `OrderConfirmation` — presentational order-confirmation view (REB-829,
@@ -732,4 +838,4 @@ interface OrderConfirmationProps {
 }
 declare function OrderConfirmation({ status, order, sessionId, cartHref, onRecheck, labels, currencyCode, locale, className, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element;
 
-export { ALLOWED_YOUTUBE_HOSTS, AddedToCartToast, type AddedToCartToastLabels, type AddedToCartToastProps, type AddedToCartToastStatus, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE, DEFAULT_SHOP_ERROR_MESSAGES, DEFAULT_SHOP_PRICE_BANDS, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, getShopErrorMessage, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };
+export { ALLOWED_YOUTUBE_HOSTS, AddedToCartToast, type AddedToCartToastLabels, type AddedToCartToastProps, type AddedToCartToastStatus, type BlockRendererProps, type CanonicalBlockType, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE, DEFAULT_SHOP_ERROR_MESSAGES, DEFAULT_SHOP_PRICE_BANDS, FaqAccordion, type FaqAccordionProps, FaqItem, type HeadingLevel, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, PageBlocks, type PageBlocksComponents, type PageBlocksProps, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, type RenderableBlock, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, getShopErrorMessage, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { ShopErrorCode, PageDetail, PageListItem, ShopProductListItem, ShopFacets, ShopOrder } from '@reblu/site-contracts';
+import { ShopErrorCode, PageDetail, PageListItem, ShopProductListItem, BlockType, PageBlock, ResolvedEmbed, ShopFacets, ShopOrder } from '@reblu/site-contracts';
+import { FaqItem } from './seo.js';
+export { FaqPageJsonLd, buildFaqPageJsonLd, collectFaqItems } from './seo.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode, FormEvent } from 'react';
+import { ComponentType, ReactNode, FormEvent } from 'react';
 
 declare function readingTime(content: string | null | undefined): number | null;
 
@@ -302,6 +304,102 @@ interface ProductCardProps {
 }
 declare function ProductCard({ product, href, currencyCode, locale, className }: ProductCardProps): react_jsx_runtime.JSX.Element;
 
+/** A heading level a caller can configure — `h1`…`h6`. */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+/**
+ * REB-850 — accessible FAQ list on native `<details>`/`<summary>`.
+ *
+ * A Server Component: no hooks, no `'use client'`, no JavaScript needed to
+ * open or close an item — the browser owns the disclosure state, keyboard
+ * support and the expanded/collapsed semantics. Answers render as TEXT (React
+ * escapes them; line breaks are preserved), never as markup.
+ *
+ * Pair it with `buildFaqPageJsonLd` (`@reblu/site-blocks/seo`) for the
+ * matching schema.org `FAQPage` structured data.
+ */
+interface FaqAccordionProps {
+    items: readonly FaqItem[];
+    /** Optional heading above the list. */
+    heading?: string | null;
+    /** Level of `heading`. Default `2`. */
+    headingLevel?: HeadingLevel;
+    /**
+     * When set, each question is wrapped in `<h{level}>` inside its `<summary>`
+     * so it appears in the document outline. Default: plain summary text.
+     */
+    questionHeadingLevel?: HeadingLevel;
+    /** Indexes of the items rendered open initially. */
+    defaultOpen?: readonly number[];
+    className?: string;
+}
+declare function FaqAccordion({ items, heading, headingLevel, questionHeadingLevel, defaultOpen, className, }: FaqAccordionProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * REB-850 — `PageBlocks`: the shared renderer for a page's registry blocks
+ * (`PageDetail.blocks`, REB-75), so a SITE stops hand-writing its own.
+ *
+ * A SERVER COMPONENT by default: no hooks, no `'use client'`, reachable from the
+ * RSC-safe root entry (`test/rsc-safety.test.ts` renders it under
+ * `--conditions=react-server`).
+ *
+ * Each block is wrapped in a `<section>` carrying the parent section's
+ * mirrored fields (REB-849): `heading`, `backgroundColor` and `cta`. The body
+ * comes from a per-type renderer that the `components` map can replace.
+ *
+ * Fail-closed rules:
+ *  • an unknown `blockType` renders nothing (the whole section) and never throws;
+ *  • an embed whose `resolved` is `null`/absent renders nothing — no heading,
+ *    no dead link;
+ *  • deprecated alias types (`doctor_embed`, `specialty_embed` — REB-852)
+ *    render through their generic type's renderer (`profile_embed`, `page_embed`).
+ */
+type DeprecatedAlias = 'doctor_embed' | 'specialty_embed';
+/** Block types a renderer is registered under — deprecated aliases resolve to these. */
+type CanonicalBlockType = Exclude<BlockType, DeprecatedAlias>;
+type EmbedType = 'page_embed' | 'profile_embed';
+type WireTypesOf<T extends CanonicalBlockType> = T extends 'profile_embed' ? 'profile_embed' | 'doctor_embed' : T extends 'page_embed' ? 'page_embed' | 'specialty_embed' : T;
+/**
+ * The block a renderer for `T` receives — including its deprecated alias, and
+ * with `resolved` guaranteed non-null for embeds (unresolved ones never render).
+ */
+type RenderableBlock<T extends CanonicalBlockType> = T extends EmbedType ? Extract<PageBlock, {
+    blockType: WireTypesOf<T>;
+}> & {
+    resolved: ResolvedEmbed;
+} : Extract<PageBlock, {
+    blockType: WireTypesOf<T>;
+}>;
+interface BlockRendererProps<T extends CanonicalBlockType> {
+    block: RenderableBlock<T>;
+    /** Level for headings INSIDE the block — one below the section heading when there is one. */
+    headingLevel: HeadingLevel;
+    /** Builds an embed's href (the `embedHref` prop, or the default `/${slug}`). */
+    embedHref: (resolved: ResolvedEmbed) => string;
+}
+/** Per-block-type renderer overrides, keyed by canonical type. */
+type PageBlocksComponents = Partial<{
+    [T in CanonicalBlockType]: ComponentType<BlockRendererProps<T>>;
+}>;
+interface PageBlocksProps {
+    blocks: readonly PageBlock[] | null | undefined;
+    /** Replace the body renderer of any block type. */
+    components?: PageBlocksComponents;
+    /** Level of each section heading. Default `2` (the page title is the `h1`). */
+    headingLevel?: HeadingLevel;
+    /** Href for an embedded page. Default `/${resolved.slug}`. */
+    embedHref?: (resolved: ResolvedEmbed) => string;
+    /**
+     * Namespace for the section heading ids (`aria-labelledby` targets). Pass a
+     * distinct value when one document renders `PageBlocks` more than once with
+     * overlapping blocks. Sanitised to a valid IDREF. Default `'page-block'`.
+     */
+    idPrefix?: string;
+    className?: string;
+    sectionClassName?: string;
+}
+declare function PageBlocks({ blocks, components, headingLevel, embedHref, idPrefix, className, sectionClassName, }: PageBlocksProps): react_jsx_runtime.JSX.Element | null;
+
 /**
  * `ShopFilters` — plug-and-play SITE filter chrome over `GET /api/site/shop/facets`
  * (REB-809). Which axes appear, their order and labels come entirely from
@@ -645,6 +743,14 @@ interface CheckoutFormProps {
     contact: CheckoutContactValues;
     onContactChange: (values: CheckoutContactValues) => void;
     contactErrors?: CheckoutContactErrors;
+    /** Country asserted by the SITE for national phone input; omit rather than guessing. */
+    phoneRegion?: string;
+    /** Optional raw checkout API error body; only INVALID_INPUT/customerPhone marks the phone field. */
+    checkoutError?: {
+        code?: unknown;
+        error?: unknown;
+        details?: unknown;
+    } | null;
     discountCode: string;
     onDiscountCodeChange: (value: string) => void;
     onApplyDiscount: () => void;
@@ -670,7 +776,7 @@ interface CheckoutFormProps {
     locale?: string;
     className?: string;
 }
-declare function CheckoutForm({ contact, onContactChange, contactErrors, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
+declare function CheckoutForm({ contact, onContactChange, contactErrors, phoneRegion, checkoutError, discountCode, onDiscountCodeChange, onApplyDiscount, onRemoveDiscount, appliedDiscount, discountApplying, discountError, loginPrompt, children, submitting, submitDisabled, onSubmit, labels, currencyCode, locale, className, }: CheckoutFormProps): react_jsx_runtime.JSX.Element;
 
 /**
  * `OrderConfirmation` — presentational order-confirmation view (REB-829,
@@ -732,4 +838,4 @@ interface OrderConfirmationProps {
 }
 declare function OrderConfirmation({ status, order, sessionId, cartHref, onRecheck, labels, currencyCode, locale, className, }: OrderConfirmationProps): react_jsx_runtime.JSX.Element;
 
-export { ALLOWED_YOUTUBE_HOSTS, AddedToCartToast, type AddedToCartToastLabels, type AddedToCartToastProps, type AddedToCartToastStatus, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE, DEFAULT_SHOP_ERROR_MESSAGES, DEFAULT_SHOP_PRICE_BANDS, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, getShopErrorMessage, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };
+export { ALLOWED_YOUTUBE_HOSTS, AddedToCartToast, type AddedToCartToastLabels, type AddedToCartToastProps, type AddedToCartToastStatus, type BlockRendererProps, type CanonicalBlockType, type CartLineItemView, CartLineList, type CartLineListLabels, type CartLineListProps, CartSummary, type CartSummaryLabels, type CartSummaryProps, type CheckoutAppliedDiscount, type CheckoutContactErrors, type CheckoutContactValues, CheckoutForm, type CheckoutFormLabels, type CheckoutFormProps, CheckoutLoginPrompt, type CheckoutLoginPromptLabels, type CheckoutLoginPromptProps, DEFAULT_SHOP_ERROR_FALLBACK_MESSAGE, DEFAULT_SHOP_ERROR_MESSAGES, DEFAULT_SHOP_PRICE_BANDS, FaqAccordion, type FaqAccordionProps, FaqItem, type HeadingLevel, MarkdownRenderer, type MarkdownRendererProps, OrderConfirmation, type OrderConfirmationLabels, type OrderConfirmationOrder, type OrderConfirmationProps, type OrderConfirmationStatus, PageBlocks, type PageBlocksComponents, type PageBlocksProps, ProductCard, type ProductCardProps, ProfileCard, type ProfileCardProps, type RenderableBlock, SafeHtml, type SafeHtmlProps, type ShareUrls, type ShopFilterPriceBand, ShopFilters, type ShopFiltersActive, type ShopFiltersHrefs, type ShopFiltersLabels, type ShopFiltersProps, Specialty, type SpecialtyProps, Treatment, type TreatmentProps, buildShareUrls, formatPrice, getShopErrorMessage, isAllowedYouTubeHost, markdownToSafeHtml, readingTime, sanitizeHtml, shouldRenderShopFilters };