@thorprovider/blocks 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @thorprovider/blocks
 
+## 2.0.0
+
+### Major Changes
+
+- dc82f71: Consolidate the category filter family into one canonical `CategoryListing` block.
+
+  - Adds `CategoryListing` (export + `CategoryListingProps` and the `CategoryListing*` option, facet, status, filter and active-filter types). It is the single controlled listing controller: products, pagination and the selected query are props; `on*Change` / `onClearFilters` / `onRepair` / `onRetry` report intent; the block never fetches, parses the URL, or keeps a private query.
+  - Two bounded presentations share one contract: `sidebar` (default; persistent desktop panel plus mobile sheet) and `toolbar` (sticky mobile toolbar, filter/sort drawers and chip rail). Presentation changes chrome only.
+  - Results render through the canonical `ProductCard` (`minimal`), so the listing owns no card markup. Facets are generic option-only groups supplied by the host; a group renders only from real metadata, a real `0` count is displayed, and an absent/invalid count is omitted. Price renders only from a real finite range, sort only from advertised options, and no result total is fabricated.
+  - `ProductCard` gains `hideAddToCart` for listing cells and renders `data-slot='product-image-placeholder'` instead of an image with an empty source.
+  - Runtime: `toFilterProduct` → `toListingProduct` (returns canonical `ProductPresentation` with `Money`), `CategoryFilterPresentation(Input)` → `CategoryListingPresentation(Input)`, `mapCatalogResultsToFilterProps` → `mapCatalogResultsToCategoryListing`, and `resolveFilterPresentationSupport` → `resolveCategoryListingSupport` plus a separate `resolveCategoryFacetSupport`. The old numbered presentation metadata is gone.
+
+  BREAKING: removes the `CategoryFilter1`, `CategoryFilter2` and `CategoryFilter4` exports, their types, and the `category-filter-4-*` helpers. Consumers must migrate to `CategoryListing`:
+
+  | Removed           | Migration                                                                                                                                                                                     |
+  | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `CategoryFilter1` | `CategoryListing` with `presentation='sidebar'`; replace counted categories/price bands with real `categories` / `priceRange` metadata.                                                       |
+  | `CategoryFilter2` | `CategoryListing` with `presentation='sidebar'` (the default). Products become canonical `ProductPresentation` items with `Money` prices; `filterPrice` string prices are no longer accepted. |
+  | `CategoryFilter4` | `CategoryListing` with `presentation='toolbar'`; replace bike-specific facets/frame/model fields with generic `facets` groups and remove its private grid/state.                              |
+
+- 28a3bd7: Consolidate the numbered checkout-form family into one canonical page-level `Checkout` block.
+
+  - Adds `Checkout` (export plus `CheckoutProps`, `CheckoutValues`, `CheckoutPresentation`, `CheckoutStepId`, `CheckoutLabels`, `CheckoutValuesFieldErrors`, `CheckoutFieldDescriptions`, `CheckoutChangeHandler`, `CheckoutOrderSummary`, `CheckoutOrderLine`, `CheckoutTotals`, `CheckoutTotalsState`, `CheckoutCountryOption`, `CheckoutShippingOption`) with a required bounded `presentation` (`single-page` | `stepper`) and an orthogonal `showReviewStep` flow option. `single-page` is the former `CheckoutForm2` structure; `stepper` is the former `CheckoutForm1` wizard; `stepper` plus the review option is the former `CheckoutForm3`. Field values are controlled (`values` + `onChange`), the step index is ephemeral block state, and `validateStep(step: CheckoutStepId)` is injected — the block contains no validation logic.
+  - Totals are canonical `Money` only and render verbatim from the host; the legacy numeric `price`/`shipping`/`tax`/`discount`/`promoDiscount` fields and their fallback summation are removed. A missing or malformed required total renders as unavailable with recovery, never as zero.
+  - Removes raw card capture: `cardNumber`, `expiryDate`, `cvv`, `cardName`, the `collectCardFields` escape hatch, the CVV visibility toggle, and `card-formatting.ts`. Payment methods remain data (`PaymentMethod[]`); card collection belongs to the host payment-provider surface.
+  - Removes the numbered exports `CheckoutForm1`, `CheckoutForm2`, `CheckoutForm3` and their `CheckoutForm1*`, `CheckoutForm2*`, `CheckoutForm3*` types.
+
+  BREAKING: consumers importing a numbered checkout must migrate to `Checkout` with the `presentation` prop (and `showReviewStep` for the review flow). Values lose the card fields and `sameAsBilling`; totals must be supplied as backend `Money`; `validateStep` now receives a `CheckoutStepId` instead of a step number.
+
+- 06333a8: Consolidate the navigation family into two canonical components and retire the numbered navbars.
+
+  - `Navbar` is the canonical page-level header with bounded `bar`, `mega`, and `floating` presentations. Content is serializable (`links`, `items`, `featured`, `signIn`, `cta`, `logoText`, `logoHref`, `currentPath`); icons resolve through a host-bound `iconMap`; `floating` uses `sticky` so it reserves its own space.
+  - `StorefrontNavbar` is the canonical commerce shell (formerly `Navbar4`) and keeps its full storefront contract: utility strip, category navigation, optional search, account states, and the controlled cart sheet with canonical `Money`.
+  - Removed identifiers: `Navbar1`, `Navbar2`, `Navbar3`, `Navbar4`, `navbar4PropsSchema`, `Navbar4SpecProps`, `Navbar4LikeButton`, `Navbar4ProductGrid`, and the `navbar-4-*` helper modules (now `storefront-navbar-cart-sheet`, `storefront-navbar-account-menu`, `storefront-navbar-search-bar`, `storefront-navbar-mobile-nav`).
+  - The page-level header no longer owns cart state: `cartCount` and `onOpenCart` are gone. Use the commerce shell for the cart affordance.
+
+- 65fac4b: Remove the numbered compatibility adapters `Testimonial1`, `Testimonial2`, `LoginPage1`, `LoginPage2`, `FooterSection1`, `FooterSection3`, and `FooterSection4`, including their deep module paths and legacy prop types. Migrate testimonials to `TestimonialSection` with `carousel` or `bento`, login pages to `LoginPage` with `card` or `social`, and footers to `FooterSection` with `brand-columns`, `newsletter-grid`, or `contact`. Select native footer link behavior explicitly where browser navigation is intended.
+
+### Minor Changes
+
+- 5d32763: The auth blocks render into the host page instead of owning it.
+
+  `LoginPage` (both `card` and `social`), `SignUpPage1`, `ForgotPasswordPage1` and `Verify1` no longer paint a full-viewport surface. They drop the `min-h-dvh` canvas, the page landmark (the `social` presentation no longer renders a root `<main>`), the `bg-linear-to-br` backdrop with `isolate`/`overflow-hidden`, the vertical centring and the page-level padding. Each block now renders a neutral, content-sized root that keeps its width cap (`max-w-md` for login and recovery, `max-w-lg` for registration) and its card styling, including the shadow.
+
+  Why: a generated storefront mounts these blocks inside the default chrome (notice + banner + navbar + footer). A viewport-height canvas inside that chrome centres the form roughly 100 px low and, for the `social` presentation, emits a second `<main>` landmark inside the page's own `<main>`.
+
+  No prop, type or export changed, so existing call sites keep compiling. What changes is visual ownership: a host that relied on the block's canvas must now supply one (a route shell, a modal, a split screen, or a template the host owns), using the same theme tokens. `@thorprovider/storefront` does exactly that for the generated `account` view, which keeps the shopper-visible result unchanged.
+
 ## 1.0.0
 
 ### Major Changes

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-21"
 ---
 
 # @thorprovider/blocks
@@ -39,22 +39,18 @@ 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) |
@@ -62,35 +58,138 @@ Blocks follow `src/blocks/<category>/<section>/<block>.tsx`. Each block co-locat
 | `ReviewRating1` | E-commerce | Review list with rating summary |
 | `ReviewRating2` | E-commerce | Rating summary with distribution and review carousel |
 | `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 |
 | `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 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
+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 +200,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 +215,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 +239,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 +274,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 +309,35 @@ 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)
+## 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`.
 
-`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.
+### Migrating from the numbered checkout blocks
 
-- `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.
+| 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 |
 
-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 +411,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/blocks",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Reusable, framework-agnostic React component blocks for Thor Commerce storefronts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/blocks/application/login-forms/login-page.test.tsx

@@ -0,0 +1,190 @@
+// @vitest-environment jsdom
+import { beforeAll, describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { AtSign } from 'lucide-react'
+import * as blockExports from '../../../index'
+import { LoginPage, type LoginPageProps } from './login-page'
+
+beforeAll(() => {
+  Object.assign(SVGElement.prototype, { getTotalLength: () => 15 })
+})
+
+describe('LoginPage', () => {
+  it('is the only exported login page API', () => {
+    expect(blockExports.LoginPage).toBe(LoginPage)
+    expect('LoginPage1' in blockExports).toBe(false)
+    expect('LoginPage2' in blockExports).toBe(false)
+  })
+
+  it.each(['card', 'social'] as const)('submits the same structured credentials for the %s presentation', async presentation => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn()
+
+    render(
+      <LoginPage
+        presentation={presentation}
+        emailLabel='Email'
+        passwordLabel='Password'
+        rememberMeLabel='Remember me'
+        signInLabel='Sign in'
+        onSubmit={onSubmit}
+      />,
+    )
+
+    await user.type(screen.getByLabelText('Email'), 'shopper@example.com')
+    await user.type(screen.getByLabelText('Password'), 'correct-horse')
+    await user.click(screen.getByRole('checkbox', { name: 'Remember me' }))
+    await user.click(screen.getByRole('button', { name: 'Sign in' }))
+
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'shopper@example.com',
+      password: 'correct-horse',
+      remember: true,
+    })
+  })
+
+  it('rejects a missing presentation instead of silently choosing a layout', () => {
+    expect(() => render(<LoginPage {...({} as LoginPageProps)} />)).toThrow(/presentation/i)
+  })
+
+  it('round-trips serializable provider data and reports the selected provider id', async () => {
+    const user = userEvent.setup()
+    const onProviderSelect = vi.fn()
+    const providers = JSON.parse(JSON.stringify([{ id: 'github', label: 'GitHub' }])) as LoginPageProps['providers']
+
+    render(
+      <LoginPage
+        presentation='social'
+        providers={providers}
+        providerIcons={{ github: AtSign }}
+        onProviderSelect={onProviderSelect}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: 'GitHub' }))
+
+    expect(onProviderSelect).toHaveBeenCalledWith('github')
+  })
+
+  it('renders provider labels when an icon is not mapped', () => {
+    render(
+      <LoginPage
+        presentation='card'
+        providers={[{ id: 'custom', label: 'Custom provider' }]}
+        onProviderSelect={vi.fn()}
+      />,
+    )
+
+    expect(screen.getByRole('button', { name: 'Custom provider' }).textContent).toBe('Custom provider')
+  })
+
+  it('omits the provider group when there are no providers', () => {
+    render(<LoginPage presentation='card' onProviderSelect={vi.fn()} />)
+
+    expect(screen.queryByRole('group', { name: 'O continúa con' })).toBeNull()
+  })
+
+  it('rejects duplicate provider IDs so provider React keys remain unique', () => {
+    expect(() =>
+      render(
+        <LoginPage
+          presentation='card'
+          providers={[
+            { id: 'duplicate', label: 'First' },
+            { id: 'duplicate', label: 'Second' },
+          ]}
+          onProviderSelect={vi.fn()}
+        />,
+      ),
+    ).toThrow(/provider ids must be unique/i)
+  })
+
+  it('omits optional actions and providers when their handlers are absent', () => {
+    render(
+      <LoginPage
+        presentation='card'
+        forgotPasswordLabel='Forgot password'
+        createAccountLabel='Create account'
+        providers={[{ id: 'github', label: 'GitHub' }]}
+      />,
+    )
+
+    expect(screen.queryByRole('button', { name: 'Forgot password' })).toBeNull()
+    expect(screen.queryByRole('button', { name: 'Create account' })).toBeNull()
+    expect(screen.queryByRole('group', { name: 'O continúa con' })).toBeNull()
+  })
+
+  it('invokes optional action handlers', async () => {
+    const user = userEvent.setup()
+    const onForgotPassword = vi.fn()
+    const onCreateAccount = vi.fn()
+
+    render(
+      <LoginPage
+        presentation='card'
+        forgotPasswordLabel='Forgot password'
+        createAccountLabel='Create account'
+        onForgotPassword={onForgotPassword}
+        onCreateAccount={onCreateAccount}
+      />,
+    )
+
+    await user.click(screen.getByRole('button', { name: 'Forgot password' }))
+    await user.click(screen.getByRole('button', { name: 'Create account' }))
+
+    expect(onForgotPassword).toHaveBeenCalledOnce()
+    expect(onCreateAccount).toHaveBeenCalledOnce()
+  })
+
+  it('updates the password toggle accessible name with its state', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <LoginPage
+        presentation='card'
+        passwordLabel='Password'
+        showPasswordAriaLabel='Show password'
+        hidePasswordAriaLabel='Hide password'
+      />,
+    )
+
+    expect(screen.getByRole('button', { name: 'Show password' })).toBeTruthy()
+    await user.click(screen.getByRole('button', { name: 'Show password' }))
+    expect(screen.getByRole('button', { name: 'Hide password' })).toBeTruthy()
+    expect(screen.getByLabelText('Password').getAttribute('type')).toBe('text')
+  })
+
+  it('keeps fields and secondary actions reachable in keyboard order', async () => {
+    const user = userEvent.setup()
+
+    render(
+      <LoginPage
+        presentation='card'
+        emailLabel='Email'
+        passwordLabel='Password'
+        rememberMeLabel='Remember me'
+        forgotPasswordLabel='Forgot password'
+        signInLabel='Sign in'
+        createAccountLabel='Create account'
+        onForgotPassword={vi.fn()}
+        onCreateAccount={vi.fn()}
+      />,
+    )
+
+    const expectedFocusOrder = [
+      screen.getByLabelText('Email'),
+      screen.getByLabelText('Password'),
+      screen.getByRole('button', { name: 'Mostrar contraseña' }),
+      screen.getByRole('checkbox', { name: 'Remember me' }),
+      screen.getByRole('button', { name: 'Forgot password' }),
+      screen.getByRole('button', { name: 'Sign in' }),
+      screen.getByRole('button', { name: 'Create account' }),
+    ]
+
+    for (const element of expectedFocusOrder) {
+      await user.tab()
+      expect(document.activeElement).toBe(element)
+    }
+  })
+})