@thorprovider/blocks 1.0.0 → 3.0.0

package/README.md

@@ -1,7 +1,7 @@
 ---
 title: "@thorprovider/blocks"
 purpose: "Reusable, framework-agnostic storefront blocks built from ShadcnStore UI, decoupled from data and backend"
-lastReviewed: "2026-10-17"
+lastReviewed: "2026-10-22"
 ---
 
 # @thorprovider/blocks
@@ -39,58 +39,163 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 
 | Export | Category | Description |
 | --- | --- | --- |
-| `Navbar1` | Marketing | Simple navbar with logo, links, sign-in, CTA and cart count |
-| `Navbar2` | Marketing | Mega-menu navbar with grouped flyouts and featured card |
-| `Navbar3` | Marketing | Floating navbar that condenses into a rounded pill on scroll |
-| `Navbar4` | Marketing | Storefront navbar: utility bar, category links, search, account menu, cart sheet |
+| `Navbar` | Marketing | Page-level navigation header: `bar`, `mega` (grouped flyouts plus optional featured promo) or `floating` (self-reserving pinned pill) |
+| `StorefrontNavbar` | E-commerce | Commerce navigation shell: utility strip, category mega menu, optional search, account menu, cart sheet |
 | `Banner1` | Marketing | Announcement banner (bar or pill) with dismiss |
 | `HeroSection1` | Marketing | Hero with badge, headline, CTA, reviewer avatars, rating and image |
 | `CtaSection1` | Marketing | Full-width call-to-action with badge, headline and two CTAs |
 | `Feature` | Marketing | Canonical benefits section: `cards` (icon feature grid) or `split` (editorial split with a required image) presentation |
-| `Testimonial1` | Marketing | Testimonial carousel with rating stars |
-| `Testimonial2` | Marketing | Bento testimonials grid |
+| `TestimonialSection` | Marketing | Canonical testimonial collection section with `carousel` and `bento` presentations |
 | `FaqBlock1` | Marketing | FAQ accordion (single or multiple open) |
 | `PricingSection1` | Marketing | Pricing tiers with popular badge |
 | `Statistic1` | Marketing | Metrics grid with progress bars |
 | `LogoCloud1` | Marketing | Logo cloud with skeleton fallback |
-| `FooterSection1` | Marketing | Footer with brand, link columns and newsletter |
-| `FooterSection3` | Marketing | Newsletter + six-column footer with social links |
+| `FooterSection` | Marketing | Canonical page-level footer with `brand-columns`, `newsletter-grid` or `contact` presentation |
 | `ProductCard` | E-commerce | Canonical product card (item cell of a listing); `presentation` `classic`/`minimal`/`rich`, canonical `ProductPresentation` items with `Money` prices, evidence-only merchandising |
 | `ProductShowcase1` | E-commerce | Combined grid-and-carousel of product cards with manual paging |
 | `ProductOverview` | E-commerce | Canonical product detail; bounded `presentation` `standard`/`gallery`/`rich` (rich adds optional specs/features/reviews tabs) |
 | `ProductQuickView` | E-commerce | Quick-view dialog with gallery, variants and quantity |
-| `ReviewRating1` | E-commerce | Review list with rating summary |
-| `ReviewRating2` | E-commerce | Rating summary with distribution and review carousel |
+| `ReviewSummary` | E-commerce | Canonical review aggregate unit; required `averageRating`, `totalReviews` and 1–5 `distribution`, bars ordered 5→1 with counts |
+| `ReviewList` | E-commerce | Canonical review collection section; bounded `presentation` `list`/`carousel`, host-authoritative engagement, host-owned pagination, empty state |
+| `ReviewCard` | E-commerce | Canonical review item cell (author, date, rating, content, optional helpful count and actions) used inside `ReviewList` |
+| `ReviewComposer` | E-commerce | Canonical controlled review form; `useId` field ids, native radio rating group, host `isSubmitting`/`error`, input preserved on failure |
 | `ProductCategory` | E-commerce | Canonical category block; bounded `presentation` `grid` (image cards) / `icons` (compact icon grid) / `list` (rows with subcategory chips and optional controlled search) |
-| `CategoryFilter1` | E-commerce | Category filter bar |
-| `CategoryFilter2` | E-commerce | Filter sidebar with mobile sheet |
+| `CategoryListing` | E-commerce | Canonical category listing (results + pagination) with a controlled query and bounded `presentation` `sidebar` (persistent desktop panel + mobile sheet) / `toolbar` (sticky mobile toolbar + drawers); generic facet groups render only from real metadata |
 | `ShoppingCart` | E-commerce | Canonical cart; backend-authoritative `Money` totals and item lines, optional promo entry and recently-viewed suggestions; `presentation` `compact` (collapsible card) or `page` (full-width review) |
-| `CheckoutForm1` | E-commerce | Essential checkout fields |
-| `CheckoutForm2` | E-commerce | Single-page checkout with order summary beside |
+| `Checkout` | E-commerce | Canonical page-level checkout; controlled values, backend-authoritative `Money` totals, `PaymentMethod[]` data with no raw card input; `presentation` `single-page` or `stepper`, optional `showReviewStep` |
 | `CheckoutConfirmation` | E-commerce | Order confirmation with fulfilment timeline |
-| `OrderHistory1` | E-commerce | Orders list |
-| `OrderHistory2` | E-commerce | Order cards with carousel items |
+| `OrderHistory` | E-commerce | Canonical order-history collection; `presentation` `cards` or `rows`, order-level `Money` totals rendered verbatim, status as data, host-owned pagination and actions |
+| `OrderLine` | E-commerce | Canonical order-line item cell (`name`, optional image/details, quantity, `Money` line total) used inside `OrderHistory` |
 | `StorefrontHero` | E-commerce | Canonical storefront hero; `presentation` `compact` (gradient headline, CTAs, product grid), `showcase` (search + rotating product carousel), `editorial` (departments, featured deals, store locator) or `promotional` (rotating deals bar, category cards) |
 | `AppShell1` | Application | Application shell with navigation slots |
-| `LoginPage1` | Application | Login card with remember-me and social buttons |
-| `LoginPage2` | Application | Login with prominent social options |
-| `SignUpPage1` | Application | Registration card with social options |
+| `LoginPage` | Application | Canonical sign-in form with explicit `card` or `social` presentation |
+| `SignUpPage1` | Application | Registration form with social options (same profile as `LoginPage`) |
 | `ForgotPasswordPage1` | Application | Four-step password recovery wizard |
 | `Verify1` | Application | Two-factor verification (OTP or backup code) |
 
-Interactions are exposed as callbacks (e.g. `onAddToCart`, `onBuyNow`, `onSelectColor`). `StorefrontHero` renders each affordance only when its handler is supplied (no dead controls); other blocks keep elements in the DOM with no-op behavior when a callback is absent.
+Interactions are exposed as callbacks (e.g. `onAddToCart`, `onBuyNow`, `onSelectColor`). `StorefrontHero` and `LoginPage` render optional affordances only when their handlers are supplied; other blocks may keep elements in the DOM with no-op behavior when a callback is absent.
+
+### Category listing
+
+`CategoryListing` is the single controlled listing controller. Products, pagination, the selected query values, active-filter chips and the status are props; the block emits `on*Change`/`onClearFilters`/`onRepair`/`onRetry` and never fetches, parses the URL, or keeps a private query. `presentation` changes only the chrome: `sidebar` keeps a persistent desktop panel plus a mobile sheet, `toolbar` adds a sticky mobile toolbar with filter/sort drawers. Results render through the canonical `ProductCard`, so the listing never owns card markup. Facets are option-only groups (`{ id, label, options: [{ value, label, count? }] }`) supplied by the host; a group renders only when real metadata provides it, a real `0` count is displayed, and an absent/invalid count is omitted rather than invented.
+
+### Footer sections
+
+`FooterSection` is the canonical page-level footer. Its required `presentation`
+is `brand-columns`, `newsletter-grid`, or `contact`; provide serializable text,
+links, and social records as props. Social records use `{ label, href?, icon }`
+with an optional `ariaLabel`; callbacks and visible fallback text keep using the
+raw `label`. Bind icon IDs to `LucideIcon` components through `socialIcons`, and
+keep that map, `logo` nodes, and callbacks outside JSON fixtures.
+
+Column/legal and social links have separate `linkBehavior` and
+`socialLinkBehavior` props, both defaulting to `host`. Host mode requires the
+matching callback and renders callback-less destinations as text; `native`
+preserves browser navigation. Contact address, phone, and email hrefs are native.
+Newsletter controls stay visible but disabled without `onNewsletterSubmit`;
+the callback receives the entered email and the block performs no network request.
+
+The numbered `FooterSection1`, `FooterSection3`, and `FooterSection4` exports,
+deep module paths, and legacy prop contracts have been removed. Migrate to
+`FooterSection` by supplying an explicit presentation and canonical serializable
+content props. Select `linkBehavior="native"` or
+`socialLinkBehavior="native"` when browser navigation is intended; both default
+to host-controlled behavior. Canonical link types are exported as
+`CanonicalFooterLink` and `CanonicalFooterLinkColumn` to avoid collisions with
+other package contracts.
+
+### Login page
+
+`LoginPage` is a sign-in composition with one shared credential form and a
+required `presentation` of `card` or `social`. Both presentations submit the
+same `{ email, password, remember }` payload. `remember` starts as `false` and
+is reported to the host; the block does not decide session persistence.
+
+The block renders into the host page and does not own it: no viewport height, no
+page landmark, no page backdrop, no vertical centring. `card` caps its width at
+`max-w-md` and `social` at the same cap, and the mounting page supplies the
+canvas — a route shell, a modal, a split screen, or a template the host owns.
+Before the shell was removed, each of these blocks painted a full-viewport
+surface; a host that relied on that canvas must now provide it.
+
+Provider data stays serializable. Pass provider IDs and labels separately from
+the icon components, and provide a selection callback so provider buttons are
+only rendered when they can act. IDs must be unique within the list; an
+unmapped icon falls back to the visible provider label:
+
+```tsx
+import { AtSign } from 'lucide-react'
+import { LoginPage } from '@thorprovider/blocks'
+
+<LoginPage
+  presentation='social'
+  providers={[{ id: 'email', label: 'Email' }]}
+  providerIcons={{ email: AtSign }}
+  onProviderSelect={providerId => startProviderLogin(providerId)}
+  onSubmit={({ email, password, remember }) => signIn({ email, password, remember })}
+/>
+```
+
+The numbered `LoginPage1` and `LoginPage2` exports, deep module paths, and legacy
+prop contracts have been removed. Migrate to `LoginPage` and select `card` or
+`social` explicitly; both presentations use the canonical
+`{ email, password, remember }` host callback contract.
+
+## Testimonials
+
+`TestimonialSection` renders a collection of testimonials in one of two explicit
+presentations: `carousel` or `bento`. Each item requires a stable, collection-unique
+`id`, `name`, and `content`. `role`, `avatar`, and `rating` are optional and are
+rendered only when supplied; the block never invents attribution or ratings and
+does not emit an empty image source.
+
+```tsx
+import { TestimonialSection } from '@thorprovider/blocks'
+
+const testimonials = [
+  { id: 't-1', name: 'Rosa Díaz', role: 'Propietaria', content: 'Excelente servicio.' },
+]
+
+<TestimonialSection
+  presentation="carousel"
+  items={testimonials}
+  title="Lo que dicen nuestros clientes"
+  carouselLabels={{
+    previous: 'Testimonio anterior',
+    next: 'Testimonio siguiente',
+    slide: 'Ir al testimonio {n}',
+  }}
+/>
+```
+
+For `carousel`, `carouselLabels` is required and supplies localized previous,
+next, and slide-button labels; `{n}` is replaced with the one-based page number.
+Arrows and dots appear only when the collection spans more than one page, so a
+collection that fits the viewport renders no navigation at all. The page count is
+re-measured on resize and on re-render, so the same collection can show controls
+on a narrow screen and hide them on a wide one. The native buttons support
+keyboard activation, and the selected page is exposed with `aria-current`. For
+`bento`, omit `carouselLabels`; one-to-three items render
+without empty cards, and collections larger than four repeat the four-tile visual
+rhythm without dropping entries. An empty `items` array renders no section or
+controls. `title`, `description`, and `className` are optional for either
+presentation.
+
+The numbered `Testimonial1` and `Testimonial2` exports, deep module paths, and
+legacy prop contracts have been removed. Migrate to `TestimonialSection` with
+shared testimonial items and select `carousel` or `bento` explicitly.
 
 ## Optional brand props
 
 Three existing blocks expose an optional brand seam. Omitting the prop renders
 the block's current output unchanged; no demo content is added.
 
-- `Navbar4` — `logoAccent?: { text: string; className?: string }` accents a
+- `StorefrontNavbar` — `logoAccent?: { text: string; className?: string }` accents a
   trailing segment of `logoText`. With `logoText="ElectroCuba"` and
   `logoAccent={{ text: 'Cuba', className: 'text-brand-promo' }}`, the block
   renders `Electro` plus an accented `Cuba` span. If `text` is not a trailing
   segment of `logoText`, the wordmark renders unchanged.
-- `FooterSection1` — `brandAccent?: { text: string; className?: string }` applies
+- `FooterSection` — `brandAccent?: { text: string; className?: string }` applies
   the same trailing-segment accent to `brandName`.
 - `StorefrontHero` — `heroImage?: { src: string; alt: string }` renders a native
   `<img>` when `src` is a non-empty string, and nothing when the prop is absent
@@ -101,13 +206,13 @@ the library hardcodes no brand color.
 
 ## Custom surface `className`
 
-`Navbar4` (outer `<header>`) and `FooterSection1` (outer `<footer>`) accept an
+`Navbar4` (outer `<header>`) and `FooterSection` (outer `<footer>`) accept an
 optional `className`, merged with the existing `cn` helper. It is purely
 presentational: no layout, structure, or behavior prop, and no hardcoded color.
 
 - **Omitted `className`** — the block renders its default surface unchanged.
   `Navbar4` keeps `bg-background/95` **and** its
-  `supports-backdrop-filter:bg-background/80` variant; `FooterSection1` keeps
+  `supports-backdrop-filter:bg-background/80` variant; `FooterSection` keeps
   `bg-secondary`.
 - **Supplied `className`** — the consumer owns the surface. The default
   background **and its backdrop-filter variant** are not applied, so a semantic
@@ -116,13 +221,13 @@ presentational: no layout, structure, or behavior prop, and no hardcoded color.
   it). Layout, border, sticky, and `backdrop-blur-md` classes stay internal.
 
 The consumer is responsible for the text, transparency, and context tokens of a
-supplied surface. `Navbar4` adapts its primary nav links: they inherit the
+supplied surface. `StorefrontNavbar` adapts its primary nav links: they inherit the
 surface text color and add `hover:text-foreground` so `hover:bg-muted` never
 paints white-on-light. No magic colors are introduced by the block.
 
-## Navbar4 account affordance
+## StorefrontNavbar account affordance
 
-`Navbar4` renders a **session-driven** account affordance exclusively from
+`StorefrontNavbar` renders a **session-driven** account affordance exclusively from
 consumer-supplied props — it never resolves a session or authenticates itself.
 Given a `user` (`StoreUser`; `avatar` is optional) and `accountMenuItems`, it
 renders an authenticated account menu with the identity, the configured items,
@@ -140,10 +245,10 @@ authentication.
 
 ## Footer newsletter
 
-`FooterSection1` renders the interactive newsletter form (input + submit button)
-**only** when `newsletter.onSubmit` is supplied. A `newsletter` object without
-`onSubmit` renders no form, input, or button — never a fake form. Omit
-`newsletter` entirely to hide the newsletter block.
+`FooterSection` renders the newsletter form disabled when
+`onNewsletterSubmit` is absent. When supplied, the callback receives the entered
+email; the block performs no network request. Omit `newsletter` to hide the
+newsletter block.
 
 ## Cart presentation (controlled)
 
@@ -175,10 +280,10 @@ either is visible in the other.
   suggestion list (name, optional image, optional `Money` price) rendered only
   when supplied.
 
-`Navbar4` owns the lateral. Pass `cartOpen` + `onCartOpenChange` to control the
+`StorefrontNavbar` owns the lateral. Pass `cartOpen` + `onCartOpenChange` to control the
 sheet's visibility from host state (omit both to keep the legacy uncontrolled
 sheet); the block keeps `aria-expanded`/`data-state` in sync. Its cart sheet
-(`Navbar4CartSheet`) takes an optional `canonical` mode where each line shows the
+(`StorefrontNavbarCartSheet`) takes an optional `canonical` mode where each line shows the
 canonical `lineTotal` (never the placeholder numeric price), plus
 `checkoutUnavailable`/`viewCartUnavailable` to hide actions the store cannot
 serve, and a `state` (`'idle' | 'pending' | 'error'`) with retry for read/mutation
@@ -210,18 +315,141 @@ affordance only when supplied. Prices render through the canonical
 `formatMoney` path (no hardcoded currency), and every label is overridable
 with Spanish defaults (`Agregar al carrito`, `Precio no disponible`, …).
 
-## Checkout blocks (controlled)
-
-`CheckoutForm1` (3-step wizard) and `CheckoutForm2` (single page) are **controlled components**: they receive the current form values through a `values` prop and report every edit through `onChange`. They hold no internal form state, so a renderer's validation context can read field values from its own state model. `CheckoutForm3` (4-step wizard) keeps the same contract with internal step state.
-
-- `paymentMethods?: PaymentMethod[]` — available payment methods as data (canonical `@thorprovider/types` `PaymentMethod`). The blocks render a radio list from this prop, show the selected method's name + `description`, and only render the card fields (`cardNumber`, `expiryDate`, `cvv`, `cardName`) when the selected method's `type === 'card'`. No payment method is hardcoded; pass an empty list to trigger the empty state.
-- `values: CheckoutForm1FormData` / `CheckoutForm2Data` — current field values (including `cardNumber`, `expiryDate`, `cvv`, `cardName`, and `paymentMethod` for `CheckoutForm1`/`CheckoutForm3`).
-- `onChange: (field, value) => void` — reported per edit; card grouping and MM/YY masking are applied by the block before the value reaches `onChange` (presentation only, no validation logic in the block).
-- `fieldErrors?: Partial<Record<FieldKey, Array<{ message?: string }>>>` — per-field error messages rendered via `FieldError` (`role="alert"`, `aria-invalid`/`aria-describedby` wiring). The same channel carries async/server errors (e.g. payment decline, invalid promo).
-- `fieldDescriptions?: Partial<Record<FieldKey, string>>` — helper text rendered via `FieldDescription`.
-- `validateStep?: (step: number) => boolean` (wizard only) — the block calls it on "Next"; advance only happens when it returns `true`, and the final submit only fires when every step validates.
+## Checkout block (page-level, controlled)
+
+`Checkout` is the single public checkout surface; it replaces the numbered `CheckoutForm1`, `CheckoutForm2`, and `CheckoutForm3` blocks. It is a **controlled component**: field values arrive through `values` and every edit is reported through `onChange`, so the host owns all commercial state. The block owns only the ephemeral step index of the `stepper` presentation.
+
+- `presentation: 'single-page' | 'stepper'` (required) — `single-page` renders every section visible at once (summary first in DOM order on mobile); `stepper` shows one step at a time with an accessible progress indicator. Both accept the same props and emit the same callbacks.
+- `showReviewStep?: boolean` — appends a confirmation step (`stepper`) or section (`single-page`) before submission.
+- `values: CheckoutValues` — `email`, `firstName`, `lastName`, `phone`, `address`, `city`, `state`, `zipCode`, `country`, `paymentMethod`, `saveInfo`, `newsletter`, `promoCode`. There are no card fields.
+- `onChange: (field, value) => void` — reported per edit. The block holds no private copy of the form data and applies no masking.
+- `orderSummary?: { items, totals? }` — line identity, name, quantity, optional variant/image, optional canonical `Money` `lineTotal` and `unitPrice`, plus backend `totals` (`subtotal`, optional `discount`/`tax`/`shipping`, `total`). Amounts render verbatim; required totals that are absent or malformed render as unavailable with the retry action, never as zero. No local arithmetic, tax rate, shipping cost, threshold, or hardcoded currency.
+- `totalsState?: 'idle' | 'pending' | 'error'` and `onRetryTotals?` — controlled reads; pending and failed states render status/alert copy without inventing amounts.
+- `countries?: { value, label }[]`, `shippingOptions?`, `selectedShippingOptionId?`, `onSelectShippingOption?` — host-owned options and selection. With no country list the block renders a text input; with no shipping options it renders no method section; nothing is pre-selected.
+- `paymentMethods?: PaymentMethod[]` — payment methods as data (canonical `@thorprovider/types`). One option per method, the selected method's description, an empty state for an empty list, and a non-selectable rendering for `isEnabled === false`. The block renders **no raw card fields**: card collection belongs to the host payment-provider surface.
+- `labels?: Partial<CheckoutLabels>` and `formatMoney?: (money: Money) => string` — every user-facing string is overridable (neutral English defaults) and amounts format through canonical `Money` with no hardcoded symbol.
+- `fieldErrors?` / `fieldDescriptions?` — per-field messages and helper text, rendered with `role="alert"` and `aria-invalid`/`aria-describedby` wiring.
+- `validateStep?: (step: CheckoutStepId) => boolean` and `onStepChange?` — the block consults `validateStep` before advancing and for every applicable step before submitting; `onStepChange` is a notification only, never a controlled value. Without the callback the block advances and leaves submit protection to the host.
+- `onSubmit?`, `submitting?`, `submitError?`, `onRetrySubmit?` — submission is reported, with a pending guard and a recoverable error state; the block never creates an order, clears a cart, or claims success.
+
+Validation itself is **not** implemented in the block. Declare checks in your store spec's validation configuration (built-in `required`/`email`/`pattern`/`minLength`/`maxLength`/cross-field `requiredIf`/`equalTo`/`lessThan`/`greaterThan`, plus catalog-registered custom functions) and evaluate them with the renderer; the messages live in the spec so they are per-store and per-language.
+
+The order summary is an internal projection of `Checkout`, not a separate block. Order receipt and fulfilment progress remain `CheckoutConfirmation`.
+
+### Migrating from the numbered checkout blocks
+
+| Retired | Replacement |
+| --- | --- |
+| `CheckoutForm1` | `<Checkout presentation="stepper" />` — same controlled values minus `cardNumber`/`expiryDate`/`cvv`/`cardName`/`sameAsBilling`; `validateStep` now receives a `CheckoutStepId` (`'contact' \| 'shipping' \| 'payment' \| 'review'`) instead of a number |
+| `CheckoutForm2` | `<Checkout presentation="single-page" />` — the host supplies `Money` totals; the block no longer computes tax, shipping, or free-shipping thresholds |
+| `CheckoutForm3` | `<Checkout presentation="stepper" showReviewStep />` — values become controlled; `apartment`, card fields, per-step icons, and internal `isStepComplete` state are gone |
+
+
+## Order history (canonical)
+
+`OrderHistory` is the single public order-history surface; it replaces the
+numbered `OrderHistory1` and `OrderHistory2` blocks. It renders a collection of
+**orders**, and each order's lines render through `OrderLine`, the canonical
+item cell. Pagination, ordering, detail navigation, loading/error states, and
+the amount formatter all belong to the host.
+
+- `orders: OrderHistoryOrder[]` — each order carries `id` (backend identity: the
+  React key and the value reported to the actions), `number` (rendered through
+  `orderLabel`), `date` (already formatted by the host), `status`
+  (`{ label, tone? }`), `total: Money`, `items: OrderLineData[]`, and an optional
+  `trackable`. Two orders may share a display number; `id` keeps them distinct.
+- `presentation: 'cards' | 'rows'` (default `cards`) — a bounded structure
+  switch. `cards` renders one card per order (muted header strip, line grid,
+  total footer); `rows` renders one bordered row per order. Both accept the same
+  data and report the same actions. Responsiveness is grid/stack CSS only: no
+  viewport measurement, no item-visibility breakpoints, no carousel.
+- `total: Money` is the backend order total and renders **verbatim**. The
+  collection never sums its lines, never multiplies a unit price by a quantity,
+  and never formats with a hardcoded currency: every amount goes through
+  `formatMoney`/`isAvailableMoney` from `lib/money.ts`, and an absent or
+  malformed amount renders `amountUnavailableLabel` (never `0`).
+- `status` is data. `status.label` is rendered and `status.tone`
+  (`default | secondary | destructive | outline`) styles it, so the block never
+  compares a status string to a literal in any language.
+- `onViewOrder(id)` and `onTrackOrder(id)` receive the backend order id. A
+  missing handler removes its control (no inert button), and the tracking action
+  additionally requires `trackable === true`. Neither action navigates, tracks,
+  or requests on its own.
+- `labels?: Partial<OrderHistoryLabels>`, `locale?`, `formatMoney?(money)` —
+  every rendered string is overridable (Spanish defaults, like the rest of the
+  commerce family), placeholders (`Pedido {number}`, `Realizado el {date}`,
+  `Cantidad: {n}`) interpolate host data, and a host formatter wins over
+  `locale`, which wins over the canonical default. All paths still go through
+  `formatMoney`.
+- Empty state: an empty `orders` array renders `emptyLabel` inside the labelled
+  region instead of an empty shell.
+
+`OrderLine` is public so a host can render a single line outside the collection
+(order detail, receipt line). It takes `{ name, image?, details?, quantity,
+lineTotal }` plus optional copy and formatter props; an absent or empty `image`
+renders a neutral placeholder — never `<img src="">` — and absent `details` is
+omitted. It has no list semantics and owns no collection state.
+
+### Migrating from the numbered order-history blocks
+
+| Retired | Replacement |
+| --- | --- |
+| `OrderHistory1` | `<OrderHistory presentation="rows" />` — the numbered block's flat per-item table becomes the order-level row presentation; each former row is an `OrderLineData` under its order (`OrderHistory1Order` → `OrderHistoryOrder` + `OrderLineData`) |
+| `OrderHistory2` | `<OrderHistory presentation="cards" />` — the carousel, the numeric item-visibility breakpoints, and the internal `useWindowSize` measurement are gone; items render as a responsive grid |
+| numeric `price: number` (`OrderHistory1`) | `lineTotal: Money` — the backend decimal is rendered verbatim, never recomputed with `toFixed` |
+| string `price`/`total` (`OrderHistory2`) | `lineTotal: Money` / `total: Money` — the host stops pre-formatting; the block formats from the value's own currency code |
+| `status: string` (`OrderHistory2`) | `status: { label, tone? }` — copy and styling arrive as data instead of an English string compared inside the block |
+| flat `*Label` props (both) | `labels?: Partial<OrderHistoryLabels>` with `{number}`/`{date}`/`{n}` placeholders |
+
+
+## Reviews (canonical)
+
+`ReviewSummary`, `ReviewList`, `ReviewCard`, and `ReviewComposer` replace the
+numbered `ReviewRating1`, `ReviewRating2`, and `ReviewRating1ReviewForm`
+surfaces. The family splits by class: an aggregate unit, a collection, its item
+cell, and a form. A host composes only the pieces it has data for.
+
+- `ReviewSummary` requires `averageRating`, `totalReviews`, and a complete 1–5
+  `distribution`. It never derives an average, never accepts a partial
+  distribution, and never fills five stars regardless of the value: the stars
+  come from `averageRating` clamped and rounded, the rows always render 5→1 with
+  their counts, and each percentage is `count / totalReviews` (a zero total
+  renders `0%`, never `NaN`). A host that holds reviews may derive those numbers
+  itself; the block may not, because it does not own the data.
+- `ReviewList` renders exactly the reviews it receives — pagination, ordering,
+  loading, and error states belong to the host. `presentation: 'list' |
+  'carousel'` is the bounded structure switch; both accept the same data and
+  report the same actions, and responsiveness is CSS only (no viewport
+  measurement). An empty array renders `emptyLabel` instead of an empty shell.
+- `ReviewCard` takes one review: `{ id, author, avatar?, date, dateTime?,
+  rating, content, helpfulCount?, likedByViewer? }`. `date` is a display string
+  rendered verbatim; `dateTime` is emitted only when it parses, so an unparsable
+  date never throws. `helpfulCount` and `likedByViewer` are host-authoritative:
+  the cell renders them and reports intent, it never increments a count or
+  toggles its own state. The like control renders only with `onToggleLike` and
+  the comment control only with `onComment` — no handler, no control. An absent
+  or empty `avatar` renders initials, never `<img src="">`.
+- `ReviewComposer` owns the draft and reports one submission
+  (`{ name, email, content, rating }`). `isSubmitting` and `error` come from the
+  host; a pending state disables submit, an error keeps every entered value, and
+  the fields clear only when the host advances `resetSignal` (after a successful
+  submission). Field ids come from `useId`, so two composers on one page never
+  collide, and the rating is one native radio group selectable with arrow keys.
+- Every rendered string, including star and distribution accessible names, is
+  overridable through `labels`/`cardLabels` (Spanish defaults).
+
+### Migrating from the numbered review blocks
+
+| Retired | Replacement |
+| --- | --- |
+| `ReviewRating1` (page shell, `pageTitle`, client pagination) | `<ReviewList reviews={...} />` plus `<ReviewSummary />` and `<ReviewComposer />` when the host holds those inputs; the page heading and pagination belong to the host |
+| `ReviewRating2` (optional aggregate, carousel) | `<ReviewSummary averageRating totalReviews distribution />` + `<ReviewList presentation="carousel" />` |
+| `ReviewRating1ReviewForm` (`form` labels, `onSubmitReview`) | `<ReviewComposer isSubmitting error resetSignal onSubmit />` |
+| `ReviewRating1Review` (`id: number`, `userName`, `userAvatar`, `likes`) | `ReviewItemData` (`id: string`, `author`, `avatar`, `helpfulCount`, `likedByViewer`) |
+| `reviewsPerPage` (client slicing) | host-owned pagination: the host supplies the page's reviews |
+| local `isLiked` map and `likes + 1` | `likedByViewer` + `helpfulCount` from the host; `onToggleLike(id, liked)` reports intent |
+| five filled stars / `count / maxCount` bars | stars from `averageRating`, bars from `count / totalReviews`, rows 5→1 |
 
-Validation itself is **not** implemented in the blocks. Declare checks in your store spec's validation configuration (built-in `required`/`email`/`pattern`/`minLength`/`maxLength`/cross-field `requiredIf`/`equalTo`/`lessThan`/`greaterThan`, plus catalog-registered custom functions like `luhn`/`cvv`/`expiryDate`) and evaluate them with the renderer; the messages live in the spec so they are per-store and per-language. Without a validation provider the blocks render with no inline errors.
 
 ## Usage
 
@@ -295,4 +523,4 @@ callbacks (`useCallback`); a fresh object literal always notifies a reference-on
 store guard; and every registered action completes its round-trip (handler → set +
 emit → spec `on` → recompute → bind). See
 [`docs/standards/interaction-contracts.md`](docs/standards/interaction-contracts.md)
-for the rules and the review checklist.
+for the rules and the review checklist.