@thorprovider/blocks 2.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-21"
+lastReviewed: "2026-10-22"
 ---
 
 # @thorprovider/blocks
@@ -55,15 +55,17 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 | `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) |
 | `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) |
 | `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 |
 | `LoginPage` | Application | Canonical sign-in form with explicit `card` or `social` presentation |
@@ -167,9 +169,13 @@ const testimonials = [
 ```
 
 For `carousel`, `carouselLabels` is required and supplies localized previous,
-next, and slide-button labels; `{n}` is replaced with the one-based item number.
-The native buttons support keyboard activation, and the selected item is exposed
-with `aria-current`. For `bento`, omit `carouselLabels`; one-to-three items render
+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
@@ -339,6 +345,112 @@ The order summary is an internal projection of `Checkout`, not a separate block.
 | `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 |
+
+
 ## Usage
 
 ```tsx